Add best practices, hooks, memory files, and scripts from recent sessions

Includes: spec-driven and test-driven development best practices,
reproduce-before-fixing debugging workflow, require-plan-file hook,
find-project-root script, session logs, memory files for decisions/
gotchas/process-lessons, and updates to existing best practice topics.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

memory/decisions.md

@@ -0,0 +1,53 @@
+# Architecture & Design Decisions
+
+## Knowledge Pipeline: Separate /reflect-logs from /reflect
+
+`/reflect-logs` handles continuous log processing; `/reflect` handles milestone reflections. Different purpose, different cadence — combining them would overcomplicate the milestone skill.
+
+## Knowledge Pipeline: MD5 for reflection state, git SHAs for distill state
+
+Log files may not be committed when reflected on, so MD5 of file content is the right identity. `/distill-best-practices` works across committed repos, so git SHAs are appropriate there.
+
+## Knowledge Pipeline: Pruning happens in /log, not /reflect-logs
+
+`/log` runs most frequently (every session end), so it naturally keeps the log directory clean as a side effect.
+
+## Knowledge Pipeline: /distill-best-practices is interactive
+
+Cross-project convention changes need human judgment. The skill proposes updates and waits for approval before writing.
+
+## Session Logs: Timestamp-based IDs (HHMMSS)
+
+Human-readable, naturally sorted, no external dependencies. Format: `YYYY-MM-DD.HHMMSS.md`.
+
+## Linting: Formatter exit codes vs hook exit codes
+
+Formatter scripts exit 1 on lint errors. The dispatcher hook decides the final exit code (exit 2 for PostToolUse feedback). This separates formatter logic from hook semantics — same scripts work for both PostToolUse and pre-commit.
+
+## Linting: Checkpoint via git hash-object with .pre-lint sidecar
+
+Fast (~1ms), no commits or stash needed, orphan blobs auto-GC'd. Falls back to `cp` outside git repos.
+
+## Linting: Project opt-in via formatter symlinks
+
+Projects opt in by having a `formatters/` directory with symlinks back to canonical scripts. Zero-config, visible in `ls`, no parsing needed. The hook walks up the directory tree to find `formatters/`.
+
+## CLAUDE.md: Remove technology-specific sections from root
+
+Ansible and Helm sections removed from root CLAUDE.md — already covered with more detail in `best-practices/ansible.md` and `best-practices/helm.md`. Technology-specific practices belong in best-practices, not root guidelines.
+
+## context-load: Walk upward collecting context files
+
+Walks from cwd upward collecting CLAUDE.md, CONTEXT.md, MEMORY.md, BESTPRACTICES.md at each level. Gives hierarchical context inheritance — highest ancestor provides global guidelines, project dir provides specifics.
+
+## context-load: Dedup via readlink -f
+
+Root CLAUDE.md is a symlink to claude-foundations. Without dedup it would load twice. `readlink -f` resolves all symlinks before comparison.
+
+## context-load: Tree depth 3
+
+Deep enough to show project structure without overwhelming output. Applied at every CLAUDE.md location.
+
+## CONTEXT.md follows MEMORY.md pattern
+
+Thin index + `context/` folder. Consistency with MEMORY.md. CONTEXT.md focuses on active work for agent orientation; MEMORY.md on accumulated learnings.