feat: flat design docs + decoupled reference sync

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 ---
 title: "Architecture"
-generator: "method sync ship"
+generator: "method sync refs"
 provenance_level: artifact_history
 ---
 
@@ -27,6 +27,7 @@ src/
   domain.ts
   drift.ts
   errors.ts
+  feedback-surface.ts
   frontmatter.ts
   generate.ts
   index.ts
@@ -45,6 +46,7 @@ The `Workspace` class is the core. It owns:
 - **Backlog operations**: `captureIdea`, `pullItem`, `moveBacklogItem`
 - **Cycle lifecycle**: `closeCycle`, `openCycles`, `captureWitness`
 - **Drift detection**: `detectDrift` (delegates to `drift.ts`)
+- **Reference sync**: `syncRefs` (refreshes generated reference docs without touching ship-only artifacts)
 - **Ship sync**: `shipSync` (updates CHANGELOG and BEARING)
 - **Status**: `status` (backlog lanes, active cycles, legend health)
 

README.md

@@ -8,8 +8,12 @@ A backlog, a loop, and honest bookkeeping.
 
 **The agent and the human sit at the same table.** They see different
 things. Both are named in every design as abstract roles (e.g.,
-"Repository Operator", "System Architect"). Both must agree before work
-ships.
+"Repository Operator", "System Architect"), not literal people or tool
+instances. Both must agree before work ships.
+
+When METHOD says `user`, it means the served perspective or beneficiary
+of the change, like in a user story. It does not mean a specific named
+person who must be present during authorship or playback.
 
 **The METHOD repo gets no special pleading.** The repository that
 defines METHOD should use METHOD on itself. If repo truth conflicts with
@@ -74,12 +78,11 @@ docs/
     backlog/
       inbox/                        raw ideas, anyone, anytime
       asap/                         do this now
-      up-next/                      do this soon
       cool-ideas/                   experiments, wild thoughts
       bad-code/                     tech debt
+      vX.Y.Z/                       release-scoped planning lane
+      <repo-lane>/                  other repo-defined planning lanes
       *.md                          everything else
-    feedback/                       raw feedback awaiting triage
-    feedback/archive/               processed feedback kept for provenance
     legends/                        named domains
     retro/<cycle>/<task>.md         retrospectives
     releases/vX.Y.Z/                internal release packets
@@ -143,14 +146,18 @@ The inbox is processed during maintenance.
 |------|---------|
 | `inbox/` | Unprocessed. |
 | `asap/` | Pull into a cycle soon. |
-| `up-next/` | Next in line. |
 | `cool-ideas/` | Not commitments. |
 | `bad-code/` | It works, but it bothers you. |
 
-Anything else sits in the backlog root.
+Repos may also create custom first-level backlog lanes when the default
+buckets stop being the right planning surface. A lane such as
+`v1.1.0/` is valid when the repo wants to group candidate work toward a
+named release target or another explicit planning bucket.
 
-`method init` scaffolds all lane directories. Lanes exist from
-initialization, not on first use.
+`method init` scaffolds the canonical lanes above. Custom lanes are
+created intentionally on demand. Backlog root remains a valid escape
+hatch, but items there should be short-lived because `method doctor`
+warns on unclassified root backlog files.
 
 ### Naming
 
@@ -164,10 +171,13 @@ debt-trailer-codec-dts.md
 
 ### Promoting
 
-When a backlog item is pulled into a cycle, it becomes a design doc:
+When a backlog item is pulled into a cycle, it becomes a design doc.
+Unreleased work without explicit release scope goes to `docs/design/`.
+Release-tagged work goes to `docs/releases/<version>/design/`.
 
 ```text
 backlog/asap/SYNTH_executive-summary-protocol.md -> design/<cycle>/executive-summary-protocol.md
+backlog/v2.4.5/PROCESS_release-scope.md -> releases/v2.4.5/design/<cycle>/release-scope.md
 ```
 
 The backlog file is removed. Work does not live in two places.
@@ -296,6 +306,10 @@ in one sentence, the cycle is too big. Split it.
 4. **Playback** - produce a witness. The agent answers agent
    questions. The human answers user questions. Write it down.
 
+   Those are perspective labels, not literal identities. `agent` names
+   the machine-operable seat in the workflow, and `user` names the
+   served perspective the hill claims to satisfy.
+
    The **witness** is the concrete artifact - test output, transcript,
    screenshot, recording - that shows both answers. No clear yes means
    no. If the witness cannot be reproduced from committed commands,
@@ -380,7 +394,7 @@ a standup:
 - Is this workspace structurally healthy? -> `method doctor`
 - What is under review? -> `method review-state`
 - What is committed? -> each design doc names its sponsors and hill
-- What is next? -> `ls docs/method/backlog/asap/`
+- What is next? -> `method status` and the current lane under `docs/method/backlog/`
 - What failed and why? -> `ls docs/method/retro/`
 - What did we decide not to do? -> `ls docs/method/graveyard/`
 
@@ -436,37 +450,32 @@ Rejected work moves to `docs/method/graveyard/` with a note explaining
 why. The graveyard prevents re-proposing without context. If you want
 to resurrect something, you must address the note.
 
-## Feedback
+Use `method retire` when a live backlog item should become a graveyard
+tombstone instead of silently disappearing.
 
-Feedback that is not yet shaped into backlog or design work belongs in
-`docs/method/feedback/`.
+## Intake
 
-Treat feedback docs as an inbox for critique, review notes, and
-outside-in observations. When processed, turn accepted feedback into
-explicit repo artifacts such as backlog items, design edits, signpost
-updates, or release notes. Then move the processed feedback document to
-`docs/method/feedback/archive/` with a short disposition note instead
-of deleting it.
+Anything not yet shaped into planned work belongs in `inbox/`,
+including critique, review notes, and outside-in observations.
 
-The archive preserves provenance, shows what feedback already landed,
-and prevents the same point from being rediscovered without context.
+Use `method inbox` to capture raw intake without prematurely deciding
+whether it belongs in `asap/`, a release lane such as `v2.4.5/`,
+`bad-code/`, `cool-ideas/`, or the graveyard. When provenance matters,
+record it explicitly with `--source` and `--captured-at`.
 
 ---
 
 ## Flow
 
 ```text
-idea -> inbox/ -> cool-ideas/ -> up-next/ -> asap/
-  -> design/<cycle>/  (committed)
+idea -> inbox/ -> chosen lane (cool-ideas/, asap/, v2.4.5/, bad-code/, ...)
+  -> design/<cycle>/ or releases/<version>/design/<cycle>/  (committed)
   -> RED -> GREEN -> playback (witness)
-  -> retro/<cycle>/   (cycle packet closed)
+  -> retro/<cycle>/ or releases/<version>/retros/<cycle>/   (cycle packet closed)
   -> PR/review -> main
   -> ship sync (BEARING / CHANGELOG / release when meaningful)
       - or ->
   -> graveyard/
-
-feedback -> feedback/ -> backlog/design/signpost/release/no-action
-  -> feedback/archive/
 ```
 
 ---
@@ -488,15 +497,22 @@ Run during development:
 npm run method -- status
 ```
 
-Core commands: `method init`, `method doctor`, `method inbox`,
-`method pull`, `method close`, `method drift`, `method status`,
-`method mcp`, `method sync github`, `method sync ship`.
+Core commands: `method init`, `method doctor`, `method migrate`, `method inbox`,
+`method backlog add`, `method backlog move`, `method backlog edit`, `method backlog list`, `method backlog deps`, `method retire`,
+`method signpost status`, `method signpost init`,
+`method repair`, `method next`, `method pull`,
+`method close`, `method drift`, `method status`, `method mcp`,
+`method sync github`, `method sync ship`, `method sync refs`.
 
 See `docs/CLI.md` for the full command reference with flags and
 examples. See `docs/MCP.md` for the MCP tool reference
-(`method_doctor`, `method_status`, `method_inbox`, `method_pull`,
-`method_drift`, `method_close`, `method_sync_ship`, `method_sync_github`,
-`method_capture_witness`).
+(`method_doctor`, `method_migrate`, `method_status`, `method_inbox`, `method_backlog_add`,
+`method_backlog_move`, `method_backlog_edit`, `method_backlog_query`, `method_backlog_dependencies`,
+`method_next_work`,
+`method_signpost_status`, `method_signpost_init`,
+`method_retire`, `method_pull`, `method_drift`,
+`method_repair`, `method_close`, `method_sync_ship`, `method_sync_refs`,
+`method_sync_github`, `method_capture_witness`).
 
 Repo-local CI currently uses GitHub Actions as a host adapter through
 `.github/workflows/ci.yml`. The first cut stays narrow and explicit:

docs/CLI.md

@@ -1,7 +1,7 @@
 ---
 title: CLI Reference
 generated_at: 2026-04-08T21:17:50.746Z
-generator: method sync ship
+generator: method sync refs
 generated_from_commit: ecde6ac00e798d68bf69b2c2bfb9044ad44d47e9
 provenance_level: artifact_history
 ---
@@ -23,17 +23,62 @@ Scaffold a METHOD workspace in the given directory.
 
 Inspect METHOD workspace health without mutating it.
 
-### `method inbox <idea> [--legend CODE] [--title TITLE]`
+### `method migrate [--json]`
 
-Capture a raw idea in docs/method/backlog/inbox/.
+Run doctor, apply the bounded repair set, then re-check the workspace.
+
+### `method inbox <idea> [--legend CODE] [--title TITLE] [--body-file PATH] [--source TEXT] [--captured-at YYYY-MM-DD] [--json]`
+
+Capture raw input in docs/method/backlog/inbox/.
+
+### `method backlog add --lane LANE --title TITLE [--legend CODE] [--body-file PATH] [--json]`
+
+Create a shaped backlog note directly in the requested backlog lane.
+
+### `method backlog move <item> --to LANE [--json]`
+
+Move a live backlog note into another backlog lane.
+
+### `method backlog edit <item> [--owner TEXT|--clear-owner] [--priority VALUE|--clear-priority] [--keyword VALUE ...|--clear-keywords] [--blocked-by REF ...|--clear-blocked-by] [--blocks REF ...|--clear-blocks] [--json]`
+
+Update explicit schema-backed backlog metadata on a live backlog note. Repeat `--keyword`, `--blocked-by`, or `--blocks` to replace list fields.
+
+### `method backlog list [--lane LANE] [--legend CODE] [--priority VALUE] [--keyword VALUE] [--owner VALUE] [--ready|--blocked] [--has-acceptance-criteria|--missing-acceptance-criteria] [--blocked-by REF] [--blocks REF] [--sort lane|priority|path] [--limit N] [--json]`
+
+Return structured backlog items and explicit frontmatter metadata such as owner, priority, keywords, blocks, blocked_by, readiness, and acceptance criteria presence.
+
+### `method backlog deps [item] [--ready] [--critical-path] [--json]`
+
+Inspect live backlog dependencies from `blocked_by` / `blocks` frontmatter.
+Use `--ready` to show unblocked work, or pass `<item> --critical-path` to show the longest blocker chain to one item.
+
+### `method retire <item> --reason TEXT [--replacement PATH] [--dry-run] [--yes] [--json]`
+
+Retire a live backlog note into the graveyard with an explicit disposition record.
+
+### `method signpost status [--json]`
+
+Report which expected repo signposts exist, which are missing, and which can be initialized by helper commands.
+
+### `method signpost init <name> [--json]`
+
+Initialize a narrowly supported missing canonical signpost such as BEARING or MCP.
+
+### `method repair (--plan | --apply) [--json]`
+
+Plan or apply bounded doctor-guided repairs for missing directories, scaffold files, and frontmatter stubs.
+
+### `method next [--lane LANE] [--legend CODE] [--priority VALUE] [--keyword VALUE] [--owner VALUE] [--include-blocked] [--limit N] [--json]`
+
+Return a bounded advisory menu of sensible next backlog items using lane order, declared frontmatter, dependency readiness, and literal BEARING mentions.
 
 ### `method pull <item>`
 
-Promote a backlog item into the next numbered design cycle.
+Promote a backlog item into the next numbered cycle packet. Release-tagged work scaffolds under docs/releases/<version>/.
 
 ### `method close [cycle] [--drift-check yes|no] --outcome hill-met|partial|not-met`
 
-Close an active cycle into docs/method/retro/. `--outcome` is required.
+Close an active cycle into its retro packet. `--outcome` is required.
 
 ### `method status`
 
@@ -53,12 +98,12 @@ Defaults to --current-branch when no selector flag is provided.
 
 Start an MCP (Model Context Protocol) server on stdio.
 
-### `method sync github|ship [options]`
+### `method sync github|ship|refs [options]`
 
 GitHub Options:
   --push                      Update GitHub issues with local changes (default).
   --pull                      Update local backlog with GitHub changes (labels, comments, status).
-Perform Ship Sync or synchronize the backlog with GitHub Issues.
+Perform Ship Sync, refresh generated reference docs, or synchronize the backlog with GitHub Issues.
 
 ### Exit Codes
 

docs/GUIDE.md

@@ -1,6 +1,6 @@
 ---
 title: "Guide"
-generator: "method sync ship"
+generator: "method sync refs"
 provenance_level: artifact_history
 ---
 
@@ -42,24 +42,25 @@ Why this is good practice:
   current feature work.
 - It avoids awkward cleanup and weird Git operations later.
 
-## Process feedback in batches
+## Keep one raw-intake path
 
 If review notes or operator feedback start piling up, capture them in
-`docs/method/feedback/` instead of scattering them across chat or
-deleting them after triage.
+`docs/method/backlog/inbox/` instead of inventing a second holding area
+for critique.
 
-Treat a feedback doc as raw input, not as a backlog item yet. During a
-maintenance pass, read it carefully, split accepted points into the
-right durable artifacts, and then move the source document into
-`docs/method/feedback/archive/` with a short note about what happened.
+Use `method inbox` for this too. Add `--source` and `--captured-at`
+when origin and timing matter.
+
+Treat the inbox item as raw input, not as already-prioritized work.
+During a maintenance pass, split accepted points into the right durable
+artifacts and then move or retire the inbox item intentionally.
 
 Why this is good practice:
 
-- It keeps the backlog from becoming a dumping ground for half-processed
-  critique.
+- It keeps raw intake legible in one place.
 - It preserves the original wording and context behind later backlog or
   docs changes.
-- It makes "no action" a visible decision instead of silent deletion.
+- It makes triage visible instead of hiding it in parallel inboxes.
 
 ## Advice is not doctrine