Thread inbox-check line and canonical .gitignore into the retrofit flow; scope relative-symlink rule to in-repo links

Retrofit playbook Step 0/Step 1 and the /retrofit guide now seed every new repo
with the canonical .gitignore block and the inbox-check line, and Part 5 documents
/capture, /triage, /roundup. portability.md and the portability-checker guide now
scope the relative-symlink mandate to in-repo (committed) symlinks, so global
~/.claude/* links are no longer flagged. ROADMAP adds a high-priority cross-repo
git-hygiene audit.

ROADMAP.md

@@ -118,3 +118,24 @@ the CLAUDE.md symlink, ROADMAP.md, the canonical `.gitignore`, and the inbox-che
 **Open questions:** Gitea repo creation — API token vs. manual UI step; how much scaffolding
 is generic vs. stack-specific (does it call a `/harden` step from item 1 to install the
 stack's linter+hook?); whether the workshop output also seeds the first `## Current state`.
+
+## 6. Cross-repo git-hygiene audit + remediation — HIGH PRIORITY
+
+**Why:** a shallow scan of `~/Projects` (2026-06-14) shows the `.claude`/git setup is *not*
+consistent across repos. Git repos with the full AGENTS.md + `.claude` + `.gitignore` setup:
+`CRM`, `premier-gunner`, `recap-relay`, `recap`, `spark-control`, `standards`, `Workout-log`.
+Outliers: `ten31-transcripts` has a `CLAUDE.md` but **no `.claude/` dir** (possible real file
+instead of an AGENTS.md symlink — the stale-retrofit failure); `start-os` has neither (likely
+an external/upstream repo). Plus many non-git folders (unprotected work). We don't yet know,
+per repo, what inside `.claude/` is committed vs gitignored, or whether in-repo symlinks are
+relative.
+
+**Do:** fan out one read-only `portability-checker` (or `Explore`) per git repo under
+`~/Projects`, each reporting: is `CLAUDE.md` a relative symlink to `AGENTS.md` or a real
+file; what's in `.claude/` and which of it is tracked vs gitignored (esp. `settings.local.json`
+committed by mistake, or shared `settings.json`/rules symlinks missing); whether `.gitignore`
+carries the canonical block; any absolute in-repo symlinks. Synthesize one compliance matrix +
+a prioritized remediation list, then a follow-up pass fixes each repo (its own commit).
+
+**Open questions:** treat non-git folders (flag for retrofit) vs. external upstreams
+(`start-os`?) differently; report-only first vs. auto-fix.

guides/portability-checker.md

@@ -26,6 +26,9 @@ A path to the repo to audit (default: the current working directory).
 3. **Resolve every symlink concretely.** Use `ls -l` / `readlink` (not assumptions): confirm
    it exists, points the correct *direction*, its target exists (not dangling), and the link
    is **relative**, never absolute — an absolute link breaks if the repo is cloned or moved.
+   Scope this to symlinks *inside the repo* (the ones git commits). Symlinks outside the repo
+   — notably the global `~/.claude/*` links — are never committed and are recreated per
+   machine, so they may be absolute without harm; do not flag them in a repo audit.
 4. **Check each layer against the checklist below**, citing file paths and `readlink` output.
 5. **Reconcile with the live spec.** If `portability.md` states a rule the checklist doesn't
    cover, check it too and flag the gap.
@@ -60,7 +63,8 @@ A path to the repo to audit (default: the current working directory).
 **Self-containment and swap-readiness**
 - Everything required to work on the repo lives in the repo. A hard dependency on a global
   or user-level file for a *requirement* (not a preference) is a blocker.
-- All vendor symlinks are relative, so the repo stays portable.
+- All vendor symlinks **inside the repo** are relative, so the repo stays portable. (The
+  global `~/.claude/*` links are out of scope — not part of the repo and never committed.)
 - `.gitignore` covers `.env`; no secrets, large binaries, or generated artifacts committed.
 
 ## Hard rules
@@ -68,8 +72,9 @@ A path to the repo to audit (default: the current working directory).
   user can run (the `git mv` / `ln -s` to run), never apply them.
 - Every PASS/FAIL cites concrete evidence: a file path, a `readlink` result, a line number.
   Anything you did not actually inspect is UNVERIFIED, never assumed.
-- Verify both **direction** and **relativeness** of every symlink — a link that resolves but
-  points the wrong way, or is absolute, fails.
+- Verify both **direction** and **relativeness** of every **in-repo** symlink — a link that
+  resolves but points the wrong way, or is absolute, fails. (Global `~/.claude/*` links are
+  out of scope.)
 - Distinguish **blockers** (break vendor-neutrality or hot-swap) from **warnings** (friction
   or style). The absence of an optional layer (no subagents, no scoped guides) is neither —
   list it as Not applicable. Only present-but-wrong is a finding.

guides/retrofit.md

@@ -22,8 +22,9 @@ 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 this is not a git repo: propose `git init`, a `.gitignore` (the canonical block from
+  `portability.md`'s "What git tracks" — `.env`, `.claude/settings.local.json` and
+  `*.local.*`, OS cruft), 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).
@@ -88,6 +89,8 @@ AGENTS.md now exists but is a strong draft, not yet checked against reality.
 - **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.
+- Ensure AGENTS.md carries the **inbox-check line** (the portable surfacing mechanism; see
+  `retrofit-playbook.md` Step 1 / `portability.md`). If it's missing, propose adding it.
 
 ## Phase 5 — Independent checks (delegate)
 

portability.md

@@ -57,7 +57,11 @@ secrets** — but it lands in three places.
 Because every vendor path in this standard is a *relative* symlink (`CLAUDE.md → AGENTS.md`,
 `.claude/rules/x.md → ../../docs/guides/x.md`), it commits and clones correctly on any
 machine. This is the concrete payoff of the relative-symlink mandate: an absolute symlink
-would commit too, but break on every other clone. Never commit an absolute symlink.
+would commit too, but break on every other clone. Never commit an absolute symlink. This
+mandate binds **in-repo** symlinks specifically — the ones git commits and clones. The
+global `~/.claude/*` symlinks (point 3) are never committed, so the rule doesn't reach them:
+they're per-machine glue, recreated on each machine by the adoption step, and may be absolute
+without harm. A repo audit checks only the symlinks inside the repo.
 
 **2. Inside a project repo — commit shared, ignore local.**
 

retrofit-playbook.md

@@ -62,7 +62,7 @@ claude
 
 Paste:
 
-> Is this a git repo? If not: git init, write a sensible .gitignore (including .env), and make an initial commit. If it is: tell me whether there are uncommitted changes and when the last commit was, then commit anything outstanding.
+> Is this a git repo? If not: git init, write a .gitignore covering .env, .claude/settings.local.json (and any *.local.*), and OS cruft — the canonical block in portability.md's "What git tracks" — and make an initial commit. If it is: tell me whether there are uncommitted changes and when the last commit was, then commit anything outstanding.
 
 Approve the git commands it proposes. Then `/exit`. (A repo existing isn't the same as work being saved in it — uncommitted changes are exactly as unprotected as no repo at all.)
 
@@ -78,7 +78,7 @@ Pick your long-running chat from the list. Desktop-app sessions live on this sam
 
 Paste, one after another:
 
-> **A — knowledge:** Based on everything we've done in this project, write an AGENTS.md at the repo root that a fresh coding-agent session could read and be immediately productive with. Include: a one-line description; the stack/versions that matter; the exact build, test (including how to run a single test), lint, and run commands; the directory layout worth knowing on day one; the conventions you've learned I follow here; and an Always/Never list of the gotchas and decisions we hit — especially anything you got wrong earlier that I corrected. Under 200 lines, markdown headers and short bullets, concrete and verifiable, no history. Don't invent commands or paths — mark anything you're unsure of as TODO. No API keys, tokens, or secrets — reference env-var names instead. Write the file now, then create a symlink so Claude Code loads it: ln -s AGENTS.md CLAUDE.md
+> **A — knowledge:** Based on everything we've done in this project, write an AGENTS.md at the repo root that a fresh coding-agent session could read and be immediately productive with. Include: a one-line description; the stack/versions that matter; the exact build, test (including how to run a single test), lint, and run commands; the directory layout worth knowing on day one; the conventions you've learned I follow here; and an Always/Never list of the gotchas and decisions we hit — especially anything you got wrong earlier that I corrected. Under 200 lines, markdown headers and short bullets, concrete and verifiable, no history. Don't invent commands or paths — mark anything you're unsure of as TODO. No API keys, tokens, or secrets — reference env-var names instead. Also add this line near the top so captured items surface in future sessions: "Inbox check: at session start, if ~/Projects/standards/INBOX.md exists, scan it for items tagged (this-repo) and surface them before proposing next steps; triage with /triage." Write the file now, then create a symlink so Claude Code loads it: ln -s AGENTS.md CLAUDE.md
 
 > **B — state:** Now append a "## Current state" section to the bottom of AGENTS.md: what's built and working, what's in progress and exactly where it stands, decisions we made that aren't implemented yet, known bugs, and the next 3–5 concrete steps. 15 lines max, present tense, no history. Anything longer-term than those next steps — backlog, someday ideas, deferred decisions — goes in a separate ROADMAP.md at the repo root; create it now if there's any such backlog to capture.
 
@@ -171,6 +171,7 @@ claude -c
 continues the most recent conversation in that folder. Nothing lost.
 
 **Other rules:**
+- **Stray ideas, any project:** `/capture` logs an idea or bug to the standards inbox without derailing the session; `/triage` inside a repo pulls its captured items into AGENTS.md/ROADMAP; `/roundup` from `~/Projects` gives one priority-grouped to-do list across all projects.
 - `/compact` is for mid-task context overflow only. Task finished = close-out ritual + `/exit`. Never compact to extend a finished chat — that's the old habit sneaking back.
 - `/memory` shows every CLAUDE.md and rules file loaded right now, and lets you browse what auto memory has saved. Auto memory lives in `~/.claude`, outside the repo — Gitea never backs it up — so promote anything important into CLAUDE.md.
 - When **Current state** stops fitting in ~15 lines, it's accumulating history or backlog. Prune it: finished narrative lives in the git log, still-real longer-term items move to ROADMAP.md. Current state holds only what a session starting now would act on.