Wire ROADMAP.md through the standards docs

ROADMAP.md was named as a destination in two places but never created,
indexed, or read back. Add the convention to how-i-work.md, note it after
the README decision tree and in the loads-when table, give it a row in the
portability layer table, make the retrofit prompt create it, and have
handoff seed it and pull from it when Current state's next steps run thin.

README.md

@@ -24,12 +24,15 @@ The governing question: **would a different agent need this to work on the repo?
 6. **Must happen deterministically, every time, no matter what the model decides?** → a hook (`.claude/settings.json`), not markdown. Markdown is guidance a model can interpret; a hook is a shell command the harness always runs. Advanced and Claude-specific — an execution-layer tool to reach for only when guidance-that-can-be-ignored isn't enough. Not needed to start.
 7. **Discovered mid-work?** → auto memory holds it for now; promote durable facts into AGENTS.md, since auto memory is never committed or backed up.
 
+*The tree above routes durable **guidance**. Project **state** is tracked separately: near-term status and next steps in AGENTS.md's `## Current state` section; longer-term backlog in `ROADMAP.md` at the repo root.*
+
 ## What loads when
 
 | Layer | Loads | After `/compact` |
 |---|---|---|
 | `how-i-work.md` (via `~/.claude/CLAUDE.md`) | In full, every session | Re-read |
 | `AGENTS.md` (via `CLAUDE.md` symlink) | In full, every session | **Re-read from disk** |
+| `ROADMAP.md` | Only when you open it deliberately | n/a — never auto-loaded |
 | `docs/guides/*` (via `.claude/rules/` symlinks) | Only when files matching `paths:` are opened | **Not re-injected** — promote anything chat-only into AGENTS.md before compacting |
 | Skills | On invocation / relevance | n/a |
 | Subagents | Isolated context window; returns a summary | n/a |

guides/handoff.md

@@ -35,8 +35,12 @@ and why. The user may provide optional focus notes; weave them in where relevant
   - Next steps in priority order
   - Open questions, risks, or anything the user flagged that wasn't resolved
   - Test/build status if worth knowing
-- Anything longer-term goes in ROADMAP.md, not here. If Current state is accumulating
+- Anything longer-term than the next steps goes in `ROADMAP.md` at the repo root, not here
-  history, prune it — history lives in the git log.
+  — create it if it doesn't exist yet and there's backlog to record. If Current state is
+  accumulating history, prune it: finished narrative to the git log, still-real longer-term
+  items to ROADMAP.md.
+- Keep the two in sync: when the next steps here run thin, pull the next item(s) up from
+  ROADMAP.md so a fresh session always finds concrete next steps in Current state.
 
 ## 4. Final report
 

guides/retrofit.md

@@ -51,7 +51,8 @@ file. Instead, help the user mine the right chat, then stop:
      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).
+     symlink; B — the `## Current state` section, plus seeding ROADMAP.md with any longer-term
+     backlog; 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.

how-i-work.md

@@ -50,3 +50,4 @@ Instruction files are the durable, visible record of how I want you to work —
 - **Add and remove.** If a new rule supersedes an old one, rewrite or delete the old one. Stale rules are worse than no rule.
 - **Reconcile conflicts.** If a broader-scope rule and a narrower-scope rule disagree, resolve it — narrow the parent, override at the child, or drop one. Don't leave future-me to guess which wins.
 - **Right scope:** universal → this file; whole-repo → that repo's AGENTS.md; subsystem → a scoped guide. Keep each file to what's true at its scope.
+- **Where project state goes:** a repo's near-term status and next steps live in the `## Current state` section of its AGENTS.md (a snapshot, overwritten each session); longer-term backlog lives in a separate `ROADMAP.md` at the repo root. The split is by time horizon, not scope: would a session starting now act on it? Yes → Current state; not yet → ROADMAP.

portability.md

@@ -33,7 +33,8 @@ Corollaries:
 | Layer | Neutral source of truth | Claude adapter | Portability status |
 |---|---|---|---|
 | Project knowledge | `<repo>/AGENTS.md` | symlink `CLAUDE.md` → `AGENTS.md` | Open standard — Cursor, Copilot, Codex, Gemini CLI, opencode read it |
-| Project status | `## Current state` section in AGENTS.md | (same symlink) | Fully portable; maintained by the close-out ritual |
+| Project status (now) | `## Current state` section in AGENTS.md | (same symlink) | Fully portable; maintained by the close-out ritual |
+| Project backlog (later) | `ROADMAP.md` at repo root | — (plain committed file, no symlink) | Fully portable; committed and pushed like any file, read only on demand |
 | Scoped guides | `<repo>/docs/guides/<topic>.md` with `paths:` frontmatter, plus one index line each in AGENTS.md | symlinks from `.claude/rules/` (auto lazy-load) | Content fully portable; lazy-loading is per-tool. Other tools find guides via the index lines |
 | User preferences | `~/Projects/standards/how-i-work.md` | symlink `~/.claude/CLAUDE.md` → it | No cross-tool standard above repo level; each tool's global file symlinks here at adoption |
 | Skills (procedures) | folders of `SKILL.md` + plain bash/python scripts | `.claude/skills/` | Format is open markdown; a cross-tool home (`.agents/skills/`) is emerging. Worst case: a pointer line in AGENTS.md |

retrofit-playbook.md

@@ -80,7 +80,7 @@ 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
 
-> **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. Longer-term backlog goes in a separate ROADMAP.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.
 
 > **C — secrets sweep:** Scan AGENTS.md and anything else you just wrote for secrets — API keys, tokens, passwords, account numbers, private URLs. Replace each with its env-var name and a note about where the real value lives.
 
@@ -167,7 +167,7 @@ continues the most recent conversation in that folder. Nothing lost.
 **Other rules:**
 - `/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. Prune it; history lives in the git log.
+- 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.
 - **AGENTS.md is the real file; CLAUDE.md is a symlink to it.** AGENTS.md is the cross-vendor standard (Cursor, Copilot, Codex, Gemini CLI, and the open-source harnesses read it); Claude Code reads only CLAUDE.md, so the symlink serves it the same file under its preferred name. Either name edits the same file — every "update CLAUDE.md" in this runbook lands in AGENTS.md. If you ever switch providers or run self-hosted agents, the repo is already in their native format.
 - **The portability principle, generalized:** knowledge lives in vendor-neutral files; vendor-named paths are symlinks into it. Root: AGENTS.md ← CLAUDE.md. Scoped guidance: docs/guides/*.md ← .claude/rules/*.md, indexed by one line each in AGENTS.md. To try a different provider, swap at a session boundary: run the close-out ritual, open the other tool, and it reads AGENTS.md + Current state and continues. The repo is brain-agnostic; sessions are visits. Full protocol: portability.md in the standards repo.