Backfill memory files for all existing scripts and skills

Creates MEMORY.md index and 10 memory files documenting:
- Scripts: context-load, start-claude, install-hooks, setup-formatters, git-status-report
- Skills: /log, /reflect-logs, /reflect, /distill-best-practices, /linter

Each file covers purpose, usage, how it works, and gotchas.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

MEMORY.md

@@ -0,0 +1,17 @@
+# claude-foundations — Memory Index
+
+## Scripts
+
+- [context-load](memory/script-context-load.md) — Walks cwd upward collecting CLAUDE.md, CONTEXT.md, MEMORY.md, BESTPRACTICES.md, trees, and git status for system prompt injection
+- [start-claude](memory/script-start-claude.md) — Wrapper that runs context-load and launches claude with --append-system-prompt
+- [install-hooks](memory/script-install-hooks.md) — Symlinks hooks into ~/.claude/hooks/ and prints settings.json config
+- [setup-formatters](memory/script-setup-formatters.md) — Opts a project into auto-formatting by symlinking formatter scripts
+- [git-status-report](memory/script-git-status-report.md) — Scans directories for git repos, reports uncommitted changes and remote sync (lives in small-scripts)
+
+## Skills
+
+- [/log](memory/skill-log.md) — End-of-session logging to memory/log/ for later reflection
+- [/reflect-logs](memory/skill-reflect-logs.md) — Processes session logs into topic memory files (gotchas, decisions, process lessons)
+- [/reflect](memory/skill-reflect.md) — Milestone reflection: reviews conversation + git log, produces structured artifacts
+- [/distill-best-practices](memory/skill-distill-best-practices.md) — Cross-project distillation of memory files into best-practices/ topic files
+- [/linter](memory/skill-linter.md) — Audit and manage project formatters/linters (scan, run, cleanup modes)

memory/script-context-load.md

@@ -0,0 +1,30 @@
+# script: context-load
+
+**Location:** `scripts/context-load`
+**Symlinked to:** `~/sbin/context-load`
+
+## Purpose
+
+Gathers project context for a Claude Code session by walking from cwd upward, collecting key index files, and outputting structured text suitable for `--append-system-prompt`.
+
+## What it loads (in order)
+
+1. Every `CLAUDE.md` found walking up from cwd (top-down order) + directory tree (depth 3) from each
+2. Every `CONTEXT.md` found walking up (top-down)
+3. Every `MEMORY.md` found walking up (top-down)
+4. Every `BESTPRACTICES.md` found walking up (top-down)
+5. All `*.md` files in cwd (deduped against already-emitted files)
+6. `git-status-report` output from the highest-level CLAUDE.md directory
+
+## How it works
+
+- Uses `discover_upward()` to walk from `$PWD` to `/`, collecting directories
+- Resolves symlinks via `readlink -f` to deduplicate (e.g., `~/dev/claude/CLAUDE.md` symlink to `claude-foundations/CLAUDE.md`)
+- Emits each file with a structured header (`=== FILE: ... ===`) for easy parsing
+- Tree output uses `tree` with fallback to `find`
+- ANSI codes are stripped from git-status-report output
+
+## Gotchas
+
+- Only walks **upward** from cwd — does not descend into subdirectories. Launch from within a project directory to get that project's context.
+- Index files (MEMORY.md, CONTEXT.md, BESTPRACTICES.md) should be thin indexes, not large documents, since they're injected into the system prompt.

memory/script-git-status-report.md

@@ -0,0 +1,31 @@
+# script: git-status-report
+
+**Location:** `~/dev/claude/small-scripts/scripts/git-status-report`
+**Symlinked to:** `~/sbin/git-status-report`
+**Source project:** small-scripts (not claude-foundations)
+
+## Purpose
+
+Recursively scans a directory for git repos and reports uncommitted changes and remote sync status. Used by `context-load` to include git status in the system prompt.
+
+## Usage
+
+```bash
+git-status-report [OPTIONS] [DIRECTORY]
+```
+
+- `-n, --dryrun` — List discovered repos without running status checks
+- Default directory: cwd
+
+## How it works
+
+1. **Discovery:** Finds all `.git` directories, filters out nested repos
+2. **Status:** For each repo, runs `git status --porcelain` and checks remote tracking branches
+3. **Character diff:** Reports approximate character-level additions/removals per file (not just line counts)
+4. **Report:** Prints dirty repos with colour-coded status, clean repo count at the end
+
+## Gotchas
+
+- Does not `git fetch` — reports against local tracking refs only (speed over accuracy)
+- Exit code 1 if any repo is dirty (useful for CI/scripting)
+- ANSI colour output — `context-load` strips it via `strip_ansi` when embedding in system prompts

memory/script-install-hooks.md

@@ -0,0 +1,27 @@
+# script: install-hooks
+
+**Location:** `scripts/install-hooks.sh`
+
+## Purpose
+
+Symlinks all hook scripts from `claude-foundations/hooks/` into `~/.claude/hooks/` and prints the `settings.json` configuration to add.
+
+## Usage
+
+```bash
+cd ~/dev/claude/projects/claude-foundations
+scripts/install-hooks.sh
+```
+
+One-time setup. Re-run after adding new hooks.
+
+## How it works
+
+1. Iterates over `hooks/*.sh`
+2. Creates symlinks in `~/.claude/hooks/` (force-overwrites existing)
+3. Prints the JSON config for `~/.claude/settings.json` covering PreCompact and PostToolUse matchers
+
+## Gotchas
+
+- The printed JSON must be manually added to `settings.json` — the script doesn't edit it automatically.
+- Symlinks mean the hook code stays in the repo; updates take effect immediately without re-running the script.

memory/script-setup-formatters.md

@@ -0,0 +1,28 @@
+# script: setup-formatters
+
+**Location:** `scripts/setup-formatters.sh`
+
+## Purpose
+
+Opts a project into the auto-formatting system by creating a `formatters/` directory with symlinks back to the canonical formatter scripts in claude-foundations.
+
+## Usage
+
+```bash
+scripts/setup-formatters.sh <project-dir> <ext> [<ext> ...]
+```
+
+Run with no arguments to see available formatters: `py`, `sh`, `ts`, `js`, `sql`, `json`, `yaml`, `md`.
+
+## How it works
+
+1. Creates `<project-dir>/formatters/` if needed
+2. Computes a relative path from the project's `formatters/` to `claude-foundations/formatters/`
+3. Creates symlinks for each requested extension
+4. If the project is a git repo and has no pre-commit hook, installs `pre-commit-lint.sh` as the git pre-commit hook
+
+## Gotchas
+
+- Uses `python3` for relative path computation — requires Python 3 available.
+- Won't overwrite an existing pre-commit hook.
+- The `formatters/` directory can be committed (symlinks) or gitignored — project's choice.

memory/script-start-claude.md

@@ -0,0 +1,23 @@
+# script: start-claude
+
+**Location:** `scripts/start-claude`
+**Symlinked to:** `~/sbin/start-claude`
+
+## Purpose
+
+Wrapper that runs `context-load` and passes the result to the `claude` CLI via `--append-system-prompt`. This is the standard way to launch a Claude Code session with full project context.
+
+## Usage
+
+```bash
+start-claude [claude args...]
+```
+
+All arguments are forwarded to `claude`. If `context-load` produces no output, `claude` is launched without the extra system prompt.
+
+## How it works
+
+1. Locates `context-load` in the same directory as itself
+2. Runs it and captures stdout
+3. If non-empty, passes it as `--append-system-prompt` to `claude`
+4. Uses `exec` so the wrapper doesn't linger as a parent process

memory/skill-distill-best-practices.md

@@ -0,0 +1,35 @@
+# skill: /distill-best-practices
+
+**Location:** `custom-claude-skills/skills/distill-best-practices/SKILL.md`
+
+## Purpose
+
+Cross-project best practices distillation. Reads changed memory files from all tracked projects and proposes additions, updates, or removals to `claude-foundations/best-practices/`. Always targets claude-foundations as output regardless of which project it's run from.
+
+## Usage
+
+```
+/distill-best-practices
+```
+
+No arguments. Interactive — presents proposals for approval before applying.
+
+## How it works
+
+1. Reads `settings.yaml` for tracked projects and `best-practices/.distill-state.json` for last-processed SHAs
+2. For each project with changes since last SHA: finds changed `memory/*.md` files via `git diff`
+3. Maps memory files to best-practices topics (e.g., `gotchas-k8s.md` → `kubernetes.md`)
+4. Classifies each potential change as ADD, UPDATE, or REMOVE
+5. Presents numbered proposals — waits for user approval
+6. Applies approved changes, updates `BESTPRACTICES.md` index if new files created
+7. Updates `.distill-state.json` with current HEADs
+
+## Part of the knowledge pipeline
+
+`/log` → `/reflect-logs` → `/distill-best-practices`
+
+## Gotchas
+
+- Generalises project-specific details: strips IPs, namespace names, hostnames — keeps principles and reasoning
+- Only promotes lessons that would apply to at least one other project type
+- Never auto-applies — always interactive

memory/skill-linter.md

@@ -0,0 +1,41 @@
+# skill: /linter
+
+**Location:** `custom-claude-skills/skills/linter/SKILL.md`
+
+## Purpose
+
+Audits and manages project formatters/linters. Three modes: scan (audit setup), run (format all files), cleanup (remove orphaned `.pre-lint` files).
+
+## Usage
+
+```
+/linter          # Scan mode (default) — audit setup
+/linter scan     # Same as above
+/linter run      # Format and lint all files
+/linter cleanup  # Remove orphaned .pre-lint files
+```
+
+## How it works
+
+### Scan mode
+1. Finds all file extensions in the project
+2. Checks `formatters/` directory for symlinks
+3. Verifies tool availability (ruff, shfmt, shellcheck, biome, sqlfluff, prettier)
+4. Checks for config files (pyproject.toml, .editorconfig, biome.json, .sqlfluff, .prettierrc)
+5. Checks pre-commit hook installation
+6. Presents results as a table with status per extension
+
+### Run mode
+1. Creates a git stash checkpoint
+2. Runs each formatter on all matching files
+3. Reports errors and `git diff --stat` summary
+
+### Cleanup mode
+1. Finds `*.pre-lint` files (orphaned checkpoint files from interrupted lint runs)
+2. Lists and removes them
+
+## Gotchas
+
+- Scan mode is non-destructive — safe to run anytime
+- Run mode creates a stash checkpoint for safety
+- `.pre-lint` files are git blob SHA references used by the PostToolUse hook for rollback

memory/skill-log.md

@@ -0,0 +1,33 @@
+# skill: /log
+
+**Location:** `custom-claude-skills/skills/log/SKILL.md`
+
+## Purpose
+
+End-of-session logging. Captures key decisions, gotchas, open questions, and process notes into `memory/log/YYYY-MM-DD.<HHMMSS>.md` for later reflection. Run before ending a session.
+
+## Usage
+
+```
+/log
+```
+
+No arguments. Reviews the full conversation history automatically.
+
+## How it works
+
+1. Creates `memory/log/` if needed
+2. Reviews the conversation and extracts: Summary, Decisions, Gotchas (tagged with `[topic]`), Open Questions, Key Context, Process Notes
+3. Writes a structured log file — empty sections are omitted
+4. Prunes old logs: deletes reflected logs older than `retention_days` (default 7), warns about unreflected logs older than `warn_unreflected_days` (default 14)
+
+## Part of the knowledge pipeline
+
+`/log` → `/reflect-logs` → `/distill-best-practices`
+
+Raw session logs are input for `/reflect-logs`, which routes entries into topic memory files.
+
+## Gotchas
+
+- Trivial sessions can be skipped — the skill says so if nothing worth logging happened
+- `[topic]` tags on gotchas should match existing memory file topics for routing by `/reflect-logs`

memory/skill-reflect-logs.md

@@ -0,0 +1,36 @@
+# skill: /reflect-logs
+
+**Location:** `custom-claude-skills/skills/reflect-logs/SKILL.md`
+
+## Purpose
+
+Processes unprocessed session logs from `memory/log/` into structured, topic-based memory files. Routes gotchas, decisions, and process lessons to the appropriate `memory/*.md` files. Run periodically or after several sessions.
+
+## Usage
+
+```
+/reflect-logs
+```
+
+No arguments. Automatically identifies unprocessed logs via `.reflection-state.json`.
+
+## How it works
+
+1. Compares `memory/log/` against `.reflection-state.json` to find new/changed logs (by md5 hash)
+2. Reads each unprocessed log and categorises entries by destination:
+   - `[topic]` gotchas → `memory/gotchas-<topic>.md`
+   - Decisions → `memory/decisions.md`
+   - Process Notes → `memory/process-lessons.md`
+3. Deduplicates by substance (semantic, not string match) against existing entries
+4. Runs staleness detection: flags version-specific bugs that have been fixed, manual processes that have been automated
+5. Updates `MEMORY.md` index if new topic files were created
+6. Updates `.reflection-state.json` with processed hashes
+
+## Part of the knowledge pipeline
+
+`/log` → `/reflect-logs` → `/distill-best-practices`
+
+## Gotchas
+
+- Respects `max_logs_per_run` from settings (default 10), processes oldest first
+- Creates new `gotchas-<topic>.md` files automatically if a `[topic]` tag doesn't match existing files

memory/skill-reflect.md

@@ -0,0 +1,32 @@
+# skill: /reflect
+
+**Location:** `custom-claude-skills/skills/reflect/SKILL.md`
+
+## Purpose
+
+Runs a milestone reflection after completing a milestone. Reviews the full conversation history, git log, and current project docs to produce structured reflection artifacts.
+
+## Usage
+
+```
+/reflect M8
+```
+
+Takes the milestone identifier as an argument (e.g., `M8`, `M3`).
+
+## How it works
+
+1. Reviews the entire conversation history for the milestone
+2. Analyses git log to quantify: total commits, fix vs. forward progress ratio, longest debugging detour
+3. Drafts reflection covering: process improvements, key knowledge for reproduction, scripts/automation opportunities, future improvement ideas
+4. Updates files in order:
+   - `MEMORY.md` — Adds milestone reflection section and updates gotchas/process lessons
+   - `FUTURE.md` — Adds new improvement ideas
+   - `README.md` — Updates milestone table and scripts section
+   - `CLAUDE.md` — Updates repo structure and conventions
+
+## Gotchas
+
+- Must be run while the conversation still has the full milestone context (before compaction)
+- Quality checks enforce: actionable bullets, symptom+fix for gotchas, rule format for process lessons, all four fields for FUTURE items
+- The verify script for the milestone (`scripts/verify-m<N>.sh`) should be read manually as part of the reflection