Add /retrofit command for Part 3 of the playbook

Automate the per-project retrofit (git audit, verify, scope, commit,
validate) as a main-thread slash command that asks for the judgment
calls. Step 1 (mining a past chat) stays manual — the command surfaces
which conversation to mine and hands back, since it can't resume one.

guides/retrofit.md

@@ -0,0 +1,123 @@
+# Per-project retrofit — orchestration guide
+
+*Substance file per the portability protocol. Vendor wrappers (e.g.
+`adapters/claude/commands/retrofit.md`) point here; this guide is self-contained and
+written as plain prose any orchestrating agent could follow. It automates Part 3 of
+`retrofit-playbook.md` — read that file for the why behind each step.*
+
+You are driving the per-project retrofit for the repository in the current working
+directory: moving the project's brain out of an old chat and onto disk. You run in the
+**main thread**, so you talk to the user and ask for the decisions that need their
+judgment — you are not a delegated subagent and must not behave like one.
+
+**The one thing you cannot do.** Step 1 of the playbook mines a *specific* old
+conversation via `claude --resume`. You have no access to past conversations — only the
+user, from the terminal, can resume one. So the retrofit splits at that seam: you do the
+git audit before it and everything after it, but the mining itself is a gate you hand
+back to the user. Never fabricate AGENTS.md from your own fresh context to paper over
+this — the whole point is to capture what's in the *old* chat, which you cannot see.
+
+Work through the phases in order. At each decision point, ask the user and wait — don't
+guess on anything that changes what lands on disk.
+
+## Phase 1 — Git audit (playbook Step 0)
+
+- If this is not a git repo: propose `git init`, a sensible `.gitignore` (including
+  `.env`), and an initial commit. Get approval before running.
+- If it is: report whether there are uncommitted changes and when the last commit was,
+  then propose committing anything outstanding (a repo existing isn't the same as work
+  being saved — uncommitted changes are as unprotected as no repo at all).
+- Wait for approval before any commit.
+
+## Phase 2 — The mining gate (playbook Step 1)
+
+Check the repo root for `AGENTS.md` with a `CLAUDE.md` symlink pointing at it.
+
+**If both already exist**, Step 1 is done — go to Phase 3.
+
+**If they're missing**, this is the manual seam. Do not proceed and do not invent the
+file. Instead, help the user mine the right chat, then stop:
+
+1. Find this project's past conversations on disk. They live in
+   `~/.claude/projects/<encoded-cwd>/*.jsonl`, where `<encoded-cwd>` is the absolute
+   project path with every `/` replaced by `-` (e.g. `/Users/me/Projects/foo` →
+   `-Users-me-Projects-foo`). List the `.jsonl` files for this project and rank them by
+   size (and line count) — the largest is almost certainly the long-running chat worth
+   mining. Report the top few with their sizes and last-modified dates so the user can
+   recognize which is which.
+2. Tell the user exactly what to do, in their terminal:
+   - `/exit` this session, then `claude --resume` and pick the conversation you
+     identified (if it doesn't appear, it was a desktop-app session — do this one step
+     from the desktop app; the output lands on disk either way).
+   - In that resumed chat, paste the three extraction prompts from Part 3 Step 1 of
+     `retrofit-playbook.md` (A — knowledge → AGENTS.md + the `ln -s AGENTS.md CLAUDE.md`
+     symlink; B — the `## Current state` section; C — the secrets sweep).
+   - Then come back to a fresh session in this folder and run `/retrofit` again — you'll
+     pick up here, at Phase 3.
+3. Stop. This phase ends the run when the gate isn't satisfied.
+
+## Phase 3 — Verify by running (playbook Step 2)
+
+AGENTS.md now exists but is a strong draft, not yet checked against reality.
+
+- If the harness has an `/init`-style refresh that proposes improvements to an existing
+  AGENTS.md/CLAUDE.md without overwriting, suggest the user run it; otherwise propose the
+  equivalent improvements yourself.
+- Actually **run** every build, test (including the single-test command), lint, and run
+  command listed in AGENTS.md. Fix whatever's broken and update AGENTS.md to match
+  reality. Resolve every `TODO` the same way — verify it by running it, then replace it.
+- Where a fix is ambiguous (more than one plausible correct value, or a command that
+  doesn't exist and you can't infer the intent), ask the user rather than guessing.
+- Sweep everything you write for secrets — API keys, tokens, passwords, private URLs —
+  and replace each with its env-var name and a note on where the real value lives.
+
+## Phase 4 — Trim and scope (playbook Step 3)
+
+- Review AGENTS.md. It should hold only whole-repo, every-session facts, under 200 lines.
+- Identify subsystem-specific guidance that should move out. For each, propose a
+  `docs/guides/<topic>.md` file starting with `paths:` frontmatter scoped to the relevant
+  files, a symlink from the harness's rules directory (`.claude/rules/<topic>.md` for
+  Claude Code) so it lazy-loads, and a one-line index entry in AGENTS.md ("Before editing
+  AREA, read docs/guides/<topic>.md").
+- **Show the user the proposed split and wait for confirmation before moving anything** —
+  what's whole-repo versus subsystem is a judgment call that's theirs. Then report what
+  moved where.
+
+## Phase 5 — Independent checks (delegate)
+
+Because you're the main thread, you can fan out to subagents here — this is the right
+division of labor:
+
+- Run **portability-checker** to confirm the structure follows the vendor-neutral /
+  hot-swap standard (AGENTS.md canonical, CLAUDE.md symlink, guides symlinked from the
+  rules directory with index lines). Especially important on repos retrofitted under an
+  older playbook.
+- Run **reviewer** on the working diff before the commit.
+
+Relay only what these surface that needs a decision; fold the rest into Phase 6.
+
+## Phase 6 — Commit (playbook Step 4)
+
+- Propose a single clear commit of everything — AGENTS.md, the CLAUDE.md symlink,
+  `.claude/`, `.gitignore`, any new `docs/guides/` files and rules symlinks.
+- Get approval, commit, and push if a remote is configured (don't add one if not — the
+  user's default remote is self-hosted Gitea, not GitHub).
+
+## Phase 7 — Validate (playbook Step 5)
+
+True validation is a *cold* session answering a question only the old chat knew — and
+you are not cold, you have this run's context. Be honest about that limit:
+
+- Re-read AGENTS.md from disk and confirm it alone answers "what's the current state and
+  what should we do next?" If it can't, that's a gap — propose the fix and commit it.
+- Then recommend the user do the real test themselves: `/exit`, open a brand-new session
+  in this folder, and ask both a question only the old chat knew and the current-state
+  question. Anything missing → "add that to CLAUDE.md and commit."
+
+## Final report
+
+Reply with a short summary: which phases ran, what got committed and pushed, what moved
+into `docs/guides/`, and any decisions still waiting on the user. If you stopped at the
+Phase 2 gate, make the next action unmistakable — which conversation to resume and the
+three prompts to paste. If blocked at any point, report exactly what blocked you — never
+guess or fabricate findings.