Land 0030-0033 repo-truth and MCP debt fixes

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+### Breaking Changes
+
+- `Workspace.closeCycle(cycleName, completedDriftCheck, outcome)` now
+  requires the `outcome` argument. Downstream `Workspace` consumers must
+  update any direct calls to pass one of `hill-met`, `partial`, or
+  `not-met`. Treat the first published release containing this API
+  change as semver-major, or ship an explicit migration note if the
+  release plan changes before publication. Migration example:
+  `await workspace.closeCycle('0033-bearing-truthfulness', true, 'hill-met')`.
+
+### Fixed
+
+- Tightened MCP runtime behavior around GitHub sync flag parsing,
+  explicit legend normalization, and design-doc frontmatter escaping.
+- Hardened the review-facing docs backlog items so their acceptance
+  criteria and historical notes match the live contract.
+
 ## v0.3.0
 
 First public release. 29 cycles closed, 127 tests passing.
@@ -37,5 +56,3 @@ First public release. 29 cycles closed, 127 tests passing.
 - docs/GUIDE.md: operator advice with generated signpost inventory.
 - docs/BEARING.md: generated direction signpost.
 - docs/VISION.md: generated executive synthesis.
-
-## Unreleased

README.md

@@ -71,6 +71,8 @@ docs/
       cool-ideas/                   experiments, wild thoughts
       bad-code/                     tech debt
       *.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
@@ -418,6 +420,21 @@ 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
+
+Feedback that is not yet shaped into backlog or design work belongs in
+`docs/method/feedback/`.
+
+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.
+
+The archive preserves provenance, shows what feedback already landed,
+and prevents the same point from being rediscovered without context.
+
 ---
 
 ## Flow
@@ -431,6 +448,9 @@ idea -> inbox/ -> cool-ideas/ -> up-next/ -> asap/
   -> ship sync (BEARING / CHANGELOG / release when meaningful)
       - or ->
   -> graveyard/
+
+feedback -> feedback/ -> backlog/design/signpost/release/no-action
+  -> feedback/archive/
 ```
 
 ---

docs/CLI.md

@@ -1,8 +1,8 @@
 ---
-title: "CLI Reference"
-generated_at: 2026-04-07T05:30:14.481Z
-generator: "method sync ship"
-generated_from_commit: "03d889ddbe57ecb6b336ba2a62815f863f85bfd1"
+title: CLI Reference
+generated_at: 2026-04-08T21:17:50.746Z
+generator: method sync ship
+generated_from_commit: ecde6ac00e798d68bf69b2c2bfb9044ad44d47e9
 provenance_level: artifact_history
 ---
 
@@ -27,9 +27,9 @@ Capture a raw idea in docs/method/backlog/inbox/.
 
 Promote a backlog item into the next numbered design cycle.
 
-### `method close [cycle] [--drift-check yes|no] [--outcome hill-met|partial|not-met]`
+### `method close [cycle] [--drift-check yes|no] --outcome hill-met|partial|not-met`
 
-Close an active cycle into docs/method/retro/.
+Close an active cycle into docs/method/retro/. `--outcome` is required.
 
 ### `method status`
 

docs/GUIDE.md

@@ -36,6 +36,25 @@ Why this is good practice:
   current feature work.
 - It avoids awkward cleanup and weird Git operations later.
 
+## Process feedback in batches
+
+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.
+
+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.
+
+Why this is good practice:
+
+- It keeps the backlog from becoming a dumping ground for half-processed
+  critique.
+- It preserves the original wording and context behind later backlog or
+  docs changes.
+- It makes "no action" a visible decision instead of silent deletion.
+
 ## Advice is not doctrine
 
 Some things are worth saying before they are worth standardizing.

docs/MCP.md

@@ -1,8 +1,8 @@
 ---
-title: "MCP Reference"
-generated_at: 2026-04-07T05:30:14.482Z
-generator: "method sync ship"
-generated_from_commit: "03d889ddbe57ecb6b336ba2a62815f863f85bfd1"
+title: MCP Reference
+generated_at: 2026-04-08T21:17:50.754Z
+generator: method sync ship
+generated_from_commit: ecde6ac00e798d68bf69b2c2bfb9044ad44d47e9
 provenance_level: artifact_history
 ---
 
@@ -25,6 +25,10 @@ workspace-agnostic — a single instance can serve multiple projects.
 
 Get the current status of the METHOD workspace (backlog lanes, active cycles, legend health)
 
+**Parameters:**
+
+- `summary` (optional) `boolean` — Return a compact structured summary instead of the fully expanded workspace status (default: false)
+
 ### `method_inbox`
 
 Capture a new raw idea into the inbox
@@ -85,6 +89,20 @@ Automate terminal evidence capture for a cycle
 
 ## Error Handling
 
-All tools return `isError: true` with a text message on failure.
+All tools return a human-readable text message in `content`.
+Machine-readable callers should consume `structuredContent`.
+
+On success, `structuredContent` includes:
+
+- `tool`
+- `ok: true`
+- `result`
+
+On failure, tools set `isError: true` and `structuredContent` includes:
+
+- `tool`
+- `ok: false`
+- `error.message`
+
 Common errors: `workspace is required`, `not a METHOD workspace`,
 `No active cycles found`.

docs/design/0030-backlog-metadata-single-source-of-truth/backlog-metadata-single-source-of-truth.md

@@ -0,0 +1,96 @@
+---
+title: "Backlog Metadata Single Source Of Truth"
+legend: PROCESS
+cycle: "0030-backlog-metadata-single-source-of-truth"
+source_backlog: "docs/method/backlog/asap/PROCESS_backlog-metadata-single-source-of-truth.md"
+---
+
+# Backlog Metadata Single Source Of Truth
+
+Source backlog item: `docs/method/backlog/asap/PROCESS_backlog-metadata-single-source-of-truth.md`
+Legend: PROCESS
+
+## Sponsors
+
+- Human: Backlog operator who needs lane and legend moves to stay honest
+  without manually repairing YAML after every triage action.
+- Agent: Automation and MCP clients that need one cheap, stable source of
+  backlog truth instead of inferring metadata from filenames and
+  directory shape.
+
+## Hill
+
+Backlog metadata becomes frontmatter-first. `status`, `pull`, lane
+moves, and legend health all resolve `legend` and `lane` from YAML when
+present, while compatibility fallbacks keep older cards readable until
+they are backfilled. Managed moves should repair missing lane metadata
+instead of preserving drift.
+
+## Playback Questions
+
+### Human
+
+- [ ] If a backlog card's filename or directory disagrees with its YAML,
+      does `method status` report the YAML lane and legend rather than
+      the path-derived guess?
+- [ ] If I move a legacy backlog card between lanes, does METHOD
+      backfill lane metadata so the card no longer depends on path
+      inference?
+
+### Agent
+
+- [ ] Can I consume backlog lane and legend from `Workspace.status()`
+      without reverse-engineering filename prefixes or folder names?
+- [ ] If a backlog card has stale filename legend text, does `method pull`
+      still carry the YAML legend into the design packet?
+
+## Accessibility and Assistive Reading
+
+- Linear truth / reduced-complexity posture: backlog metadata should be
+  explicit in one place so humans and agents do not need to cross-check
+  path, filename, and YAML to learn the current state.
+- Non-visual or alternate-reading expectations: metadata must stay
+  machine-readable and linearly inspectable from the document header.
+
+## Localization and Directionality
+
+- Locale / wording / formatting assumptions: legend codes remain stable,
+  uppercase repo-local identifiers independent of prose wording.
+- Logical direction / layout assumptions: no layout dependence; the
+  solution lives in YAML keys and deterministic CLI/API output.
+
+## Agent Inspectability and Explainability
+
+- What must be explicit and deterministic for agents: lane and legend
+  resolution order, compatibility fallback behavior, and move-time
+  metadata repair.
+- What must be attributable, evidenced, or governed: tests should prove
+  that frontmatter wins over filenames and directories, and that active
+  legend health can read design doc frontmatter.
+
+## Non-goals
+
+- [ ] Redesign backlog filenames or cycle slug generation in this cycle.
+- [ ] Eliminate every legacy fallback path before the repo backlog docs
+      have been backfilled.
+- [ ] Replace the generated design or retro scaffolds; that remains
+      separate debt under `PROCESS_generated-doc-scaffold-contract`.
+
+## Backlog Context
+
+Backlog metadata is still split across filename prefixes and YAML
+frontmatter. `captureIdea` writes `legend` and `lane` into frontmatter,
+but `collectBacklogItems`, `calculateLegendHealth`, and `pullItem` still
+derive legend from the filename stem, while `moveBacklogItem` renames the
+file without updating frontmatter metadata. That creates silent drift:
+the path can say one thing, the YAML can say another, and status/MCP
+surfaces may report whichever source they happen to trust.
+
+This is bad code because the repo now has multiple authorities for the
+same facts. It is especially hostile to agents, which need one cheap,
+stable, machine-readable source instead of filename heuristics plus
+special-case inference.
+
+The fix should make frontmatter canonical for backlog metadata, keep
+filenames as convenience or display structure, and ensure move/pull/
+status/audit flows preserve and validate the YAML fields.

docs/design/0031-generated-doc-scaffold-contract/generated-doc-scaffold-contract.md

@@ -0,0 +1,86 @@
+---
+title: "Generated Doc Scaffold Contract"
+legend: PROCESS
+cycle: "0031-generated-doc-scaffold-contract"
+source_backlog: "docs/method/backlog/asap/PROCESS_generated-doc-scaffold-contract.md"
+---
+
+# Generated Doc Scaffold Contract
+
+Source backlog item: `docs/method/backlog/asap/PROCESS_generated-doc-scaffold-contract.md`
+Legend: PROCESS
+
+## Sponsors
+
+- Human: Cycle operator
+- Agent: Scaffold repair agent
+
+## Hill
+
+`method pull` and `method close` generate design and retro docs that
+already satisfy the repo's committed document contract. A fresh cycle
+packet should not require manual frontmatter surgery just to survive the
+docs suite or honest review.
+
+## Playback Questions
+
+### Human
+
+- [ ] Does `method pull` create a design doc that already includes
+      required frontmatter fields like `title`, `legend`, `cycle`, and
+      `source_backlog`?
+- [ ] Does `method close` create a retro doc that already includes
+      required frontmatter fields like `title`, `outcome`,
+      `drift_check`, and `design_doc`?
+
+### Agent
+
+- [ ] Can I rely on scaffolded design docs to satisfy the repo docs
+      contract without manual patching?
+- [ ] Can I rely on scaffolded retro docs to satisfy the repo docs
+      contract without post-close repairs?
+
+## Accessibility and Assistive Reading
+
+- Linear truth / reduced-complexity posture: generated docs should place
+  critical metadata in YAML so readers do not need to infer validity
+  from body prose or repair steps.
+- Non-visual or alternate-reading expectations: the scaffold contract
+  must stay explicit and machine-readable from the first lines of the
+  document.
+
+## Localization and Directionality
+
+- Locale / wording / formatting assumptions: scaffold metadata keys stay
+  stable and deterministic regardless of the prose in the body.
+- Logical direction / layout assumptions: no layout-specific behavior;
+  validity depends on frontmatter and predictable section structure.
+
+## Agent Inspectability and Explainability
+
+- What must be explicit and deterministic for agents: which frontmatter
+  keys are emitted for design and retro docs, and that close-time output
+  does not require manual cleanup before commit.
+- What must be attributable, evidenced, or governed: CLI tests should
+  prove scaffolded docs meet the repo contract, and the existing cycle
+  docs produced before the fix should be repaired on-branch.
+
+## Non-goals
+
+- [ ] Redesign the substantive content of every historical design or
+      retro doc.
+- [ ] Solve broader signpost truth drift such as `BEARING.md` claims.
+- [ ] Redesign witness capture output beyond keeping the generated docs
+      commit-safe.
+
+## Backlog Context
+
+`method pull` and `method close` still generate design and retro
+documents with older scaffold shapes that do not match the repo's
+current frontmatter contract. The committed docs suite enforces YAML
+frontmatter and required fields on real docs, but the command-generated
+templates do not yet guarantee those same invariants.
+
+That means METHOD can generate docs that its own repo doctrine would
+reject if they were committed. The scaffolders and the tests need to be
+brought back into parity so generated docs are valid by construction.