docs: add lessons learned from YOLO vs human-guided refactoring

Templates:
- CONVENTIONS.md: Add naming prefixes, path construction, testing patterns
- CONSTITUTION.md: Add stdlib path construction rule (security)
- AGENT_PLAYBOOK.md: Add consolidation vs feature guidance

Project context:
- LEARNINGS.md: Document YOLO mode debt patterns, hook regex overfitting
- DECISIONS.md: Record constants consolidation and minimal constitution decisions

Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>

Author: josealekhine

.context/DECISIONS.md

@@ -242,3 +242,62 @@ agent to check its own mind.
 - `IMPLEMENTATION_PLAN.md` becomes a thin directive layer
 - Historical milestones are archived, not active tasks
 - North Star goals live in IMPLEMENTATION_PLAN.md (meta-level, not tasks)
+
+---
+
+## [2026-01-25] Centralize Constants with Semantic Prefixes
+
+**Status**: Accepted (implemented)
+
+**Context**: YOLO-mode feature development scattered magic strings across the codebase. Same literals (`"TASKS.md"`, `"task"`, `".context"`) appeared in 10+ files. Human-guided refactoring session consolidated them.
+
+**Decision**: All repeated literals go in `internal/config/config.go` with semantic prefixes:
+- `Dir*` for directories (`DirContext`, `DirArchive`, `DirSessions`)
+- `File*` for file paths (`FileSettings`, `FileClaudeMd`)
+- `Filename*` for file names only (`FilenameTask`, `FilenameDecision`)
+- `UpdateType*` for entry types (`UpdateTypeTask`, `UpdateTypeDecision`)
+
+Maps must use constants as keys:
+```go
+var FileType = map[string]string{
+    UpdateTypeTask: FilenameTask,  // not "task": "TASKS.md"
+}
+```
+
+**Rationale**:
+- Single source of truth for all identifiers
+- Refactoring is find-replace on constant name
+- IDE navigation works (go-to-definition)
+- Typos caught at compile time, not runtime
+- Self-documenting code (constants have godoc)
+
+**Consequences**:
+- All new literals must go through config package
+- Existing code migrated to use constants
+- Slightly more verbose but much more maintainable
+
+---
+
+## [2026-01-25] Keep CONSTITUTION Minimal
+
+**Status**: Accepted
+
+**Context**: When codifying lessons learned, temptation was to add all conventions to CONSTITUTION.md as "invariants."
+
+**Decision**: CONSTITUTION.md contains only truly inviolable rules:
+- Security invariants (secrets, path traversal)
+- Correctness invariants (tests pass)
+- Process invariants (decision records)
+
+Style preferences and best practices go in CONVENTIONS.md instead.
+
+**Rationale**:
+- Overly strict constitution creates friction and gets ignored
+- "Crying wolf" effect — developers stop reading it
+- Conventions can be bent; constitution cannot
+- Security vs style are fundamentally different categories
+
+**Consequences**:
+- CONVENTIONS.md becomes the living style guide
+- CONSTITUTION.md stays short and scary
+- New rules must pass "is this truly inviolable?" test

.context/LEARNINGS.md

@@ -279,3 +279,41 @@ Manual file reading is better for exploratory/memory questions:
 - "What should I work on?" → `ctx agent` (need tasks)
 
 - **[2026-01-23]** Claude Code skills are markdown files in .claude/commands/ with YAML frontmatter (description, argument-hint, allowed-tools). Body is the prompt. Use code blocks with ! prefix for shell execution. $ARGUMENTS passes command args.
+
+---
+
+## YOLO Mode vs Human-Guided Refactoring
+
+### Autonomous Mode Creates Technical Debt
+**Discovered**: 2026-01-25
+
+**Context**: Compared commits from autonomous "YOLO mode" (auto-accept, agent-driven) vs human-guided refactoring sessions.
+
+**Lesson**: YOLO mode is effective for feature velocity but accumulates technical debt:
+
+| YOLO Pattern                           | Human-Guided Fix                      |
+|----------------------------------------|---------------------------------------|
+| `"TASKS.md"` scattered in 10 files     | `config.FilenameTask` constant        |
+| `dir + "/" + file`                     | `filepath.Join(dir, file)`            |
+| `{"task": "TASKS.md"}`                 | `{UpdateTypeTask: FilenameTask}`      |
+| Monolithic `cli_test.go` (1500+ lines) | Colocated `package/package_test.go`   |
+| `package initcmd` in `init/` folder    | `package initialize` in `initialize/` |
+
+**Application**:
+1. Schedule periodic consolidation sessions (not just feature sprints)
+2. When same literal appears 3+ times, extract to constant
+3. Constants should reference constants (self-referential maps)
+4. Tests belong next to implementations, not in monoliths
+
+### Hook Regex Can Overfit
+**Discovered**: 2026-01-25
+
+**Context**: `.claude/hooks/block-non-path-ctx.sh` was blocking legitimate sed commands because the regex `ctx[^ ]*` matched paths containing "ctx" as a directory component (e.g., `/home/user/ctx/internal/...`).
+
+**Lesson**: When writing shell hook regexes:
+- Test against paths that contain the target string as a substring
+- `ctx` as binary vs `ctx` as directory name are different
+- Original: `(/home/|/tmp/|/var/)[^ ]*ctx[^ ]* ` — overfits
+- Fixed: `(/home/|/tmp/|/var/)[^ ]*/ctx( |$)` — matches binary only
+
+**Application**: Always test hooks with edge cases before deploying.

internal/templates/AGENT_PLAYBOOK.md

@@ -162,3 +162,21 @@ Never assume. If you don't see it in files, you don't know it.
 - Don't invent history - check sessions/ for actual discussions
 - If uncertain, say "I don't see this documented"
 - Trust files over intuition
+
+## When to Consolidate vs Add Features
+
+**Signs you should consolidate first:**
+- Same string literal appears in 3+ files
+- Hardcoded paths use string concatenation
+- Test file is growing into a monolith (>500 lines)
+- Package name doesn't match folder name
+
+**YOLO mode creates debt** — rapid feature additions scatter patterns across the codebase. Periodic consolidation prevents this from compounding.
+
+**Human-guided refactoring catches:**
+- Magic strings that should be constants
+- Path construction that should use `filepath.Join()`
+- Tests that should be colocated with implementations
+- Naming inconsistencies
+
+When in doubt, ask: "Would a new contributor understand where this belongs?"

internal/templates/CONSTITUTION.md

@@ -11,6 +11,7 @@ These rules are INVIOLABLE. If a task requires violating these, the task is wron
 
 - [ ] All code must pass tests before commit
 - [ ] No TODO comments in main branch (move to TASKS.md)
+- [ ] Path construction uses stdlib — no string concatenation (security: prevents path traversal)
 
 ## Process Invariants
 

internal/templates/CONVENTIONS.md

@@ -2,6 +2,56 @@
 
 ## Naming
 
+- **Constants use semantic prefixes**: Group related constants with prefixes
+  - `Dir*` for directories (`DirContext`, `DirArchive`)
+  - `File*` for file paths (`FileSettings`, `FileClaudeMd`)
+  - `Filename*` for file names only (`FilenameTask`, `FilenameDecision`)
+  - `*Type*` for enum-like values (`UpdateTypeTask`, `UpdateTypeDecision`)
+- **Package name = folder name**: Go canonical pattern
+  - `package initialize` in `initialize/` folder
+  - Never `package initcmd` in `init/` folder
+- **Maps reference constants**: Use constants as keys, not literals
+  - `map[string]X{ConstKey: value}` not `map[string]X{"literal": value}`
+
 ## Patterns
 
+- **Centralize magic strings**: All repeated literals belong in a `config` or `constants` package
+  - If a string appears in 3+ files, it needs a constant
+  - If a string is used for comparison, it needs a constant
+- **Path construction**: Always use stdlib path joining
+  - Go: `filepath.Join(dir, file)`
+  - Python: `os.path.join(dir, file)`
+  - Node: `path.join(dir, file)`
+  - Never: `dir + "/" + file`
+- **Constants reference constants**: Self-referential definitions
+  - `FileType[UpdateTypeTask] = FilenameTask` not `FileType["task"] = "TASKS.md"`
+- **Colocate related code**: Group by feature, not by type
+  - `session/run.go`, `session/types.go`, `session/parse.go`
+  - Not: `runners/session.go`, `types/session.go`, `parsers/session.go`
+
 ## Testing
+
+- **Colocate tests**: Test files live next to source files
+  - `foo.go` → `foo_test.go` in same package
+  - Not a separate `tests/` folder
+- **Test the unit, not the file**: One test file can test multiple related functions
+- **Integration tests are separate**: `cli_test.go` for end-to-end binary tests
+
+## Documentation
+
+- **Godoc format**: Use canonical sections
+  ```go
+  // FunctionName does X.
+  //
+  // Longer description if needed.
+  //
+  // Parameters:
+  //   - param1: Description
+  //   - param2: Description
+  //
+  // Returns:
+  //   - Type: Description of return value
+  func FunctionName(param1, param2 string) error
+  ```
+- **Package doc in doc.go**: Each package gets a `doc.go` with package-level documentation
+- **Copyright headers**: All source files get the project copyright header