@sabaiway/agent-workflow-kit 7.0.0 → 7.2.0

package/CHANGELOG.md

@@ -4,6 +4,90 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 7.2.0 — `.mcp.json` joins the hidden-mode footprint, and a worktree never owns it (AD-111)
+
+7.0.0 taught the kit to register its MCP server. It did not teach hidden mode about the file that
+registration writes — so a hidden deployment that ran `/agent-workflow-kit mcp` left `.mcp.json`
+sitting in `git status`, one `git add -A` away from a commit. That is exactly the leak the footprint
+registry exists to prevent, and it shipped anyway.
+
+- **`/.mcp.json` is in `KIT_OWN_PATHS`.** It joins `/.claude/settings.json` as a SHARED container the
+  kit merges into rather than owns, on the same terms: the tracked→ASK arm means a project that
+  already commits its own registration is asked, never silently un-tracked. Candidacy is
+  unconditional on purpose — the path is CONSIDERED before a later `mcp --apply` writes the file
+  rather than only after it appears, and is then hidden, dropped as already covered by a tracked
+  `.gitignore`, or surfaced as an ASK. That is what removes the follow-up reconcile the bug depended
+  on. The `contracts.md` prose mirror names it.
+- **A worktree is never HANDED one, and never owns one.** The scope is the untracked lanes this tool
+  drives — the registry copy set and `--include`; a TRACKED `.mcp.json` still arrives with
+  `git worktree add`, because that is the checkout, not a copy. One frozen never-provisioned set,
+  read at three sites because each needs it for a different reason: the copy set would hand a
+  satellite a launcher pinned to a path consented for the MAIN checkout; the containment sweep would
+  STOP the whole provision on an escaping symlink at that path (a device-node mask realpaths inside
+  the repo and reaches the later special-file refusal instead); and `registryRoots` decides what
+  `cleanup` may REMOVE. That third one was measured — without the guard, `cleanup` on a landed
+  worktree carrying a satellite's own `.mcp.json` exited 0 and took the file with it. `--include` is
+  refused pre-mutation for the same paths: it is the one door that bypasses the copy set, and it
+  would have recorded the launcher as ours.
+- **A settings copy this tool wrote never enables a server the worktree cannot declare.** The
+  guarantee is exactly that narrow. `.claude/settings.json` rides `REBASE_TARGETS` into a worktree
+  carrying `enabledMcpjsonServers`, which `mcp.md` itself calls a client error on every startup. An
+  untracked copy still equal to MAIN loses our enable and our two derived allow rules — and ONLY
+  those; every foreign server, rule and key survives, as do the file's EOL and the order of its
+  non-index keys (`withoutRegistration`, the token-removal complement of `mergeSettings`, not its
+  exact inverse — a JSON round-trip still hoists integer-like keys, as JS object semantics require).
+  **Where a rewrite would LOSE something the kit does not own, it is refused whole and says why.**
+  Three ways, each detected before anything is written: a number past double precision comes back a
+  different value; a duplicate key at any depth collapses to the last one (both found on the source
+  TEXT, because after the parse the evidence is gone); and invalid UTF-8 would become U+FFFD, so both
+  rewriting lanes — the pin rebase and the token strip — decode with FATAL UTF-8 and refuse
+  separately. The MAIN-equality proof compares BYTES, with the BOM preserved through the decode, so
+  a BOM-carrying original and a BOM-less copy can never pass for the same file.
+  The rewrite is admitted by ONE positive conjunction — untracked, bytes still MAIN's or their
+  rebased form, and a launcher proven ABSENT — so a tracked or user-modified settings file keeps its
+  registration tokens on purpose, as does one standing beside a launcher that is present or that
+  cannot be read. Those states get a neutral line naming the tokens; orphanhood is only CLAIMED where
+  it is proven.
+- **All three output arms name the reconcile.** Applied, masked hand-off, and already-registered —
+  the last one matters most, because a deployment registered under 7.0.0 learns about the reconcile
+  on its next run. A settings write that fails after the entry landed carries the note too: that
+  path never reaches the report, and it strands a standing registration.
+
+**Known residual, stated:** a VISIBLE deployment still commits a launcher carrying an absolute
+machine path. The fix is not symmetric with hidden mode — a visible `.mcp.json` may legitimately hold
+a team's own committable servers — so it is its own queued decision, not a line in this release.
+
+## 7.1.0 — `fold-scope`: the fold channel gets a checker that refuses a claim whose reference does not resolve (AD-110)
+
+The engine canon now asks every finding to NAME the invariant its fix enforces before the edit
+(engine **3.1.0**). Prose cannot check that a named invariant is really where you say it is.
+
+- **`tools/fold-scope.mjs` + `tools/fold-scope-cli.mjs`** — the pure rule and its CLI half:
+  `--class in-scope|new-invariant|blocking`, `--claim "<the invariant>"`, `--plan <plan-file>`,
+  `--queue <queue-file>`. Exit 0 for every ACCEPT, non-zero for every REFUSE, one case per arm.
+- **`--plan` and `--queue` are REQUIRED and never defaulted.** A project can have two registers that
+  both look like "the queue" — the planning lifecycle's `docs/plans/queue.md` and a declared
+  `flow.debtQueue` — and a checker that guessed would attest a deferral against the wrong file.
+- **What it refuses**, each naming the lane out of it: an `in-scope` claim matching no acceptance
+  bullet; a `new-invariant` whose invariant IS an acceptance bullet (route to fold); a deferral with
+  no queue row, with several, whose row title carries `DONE`/`CLOSED`, that repeats a field label,
+  that is missing a field (named, including an `origin` that is not a `file:line`), whose claim is
+  not inside the row's `invariant` field, or whose residual exposure is declared live (route to
+  blocking) or declares neither.
+- **`/agent-workflow-kit procedures plan-execution` renders the populated command** — under solo,
+  reviewed AND council, because the rule routes every finding and a Solo project must see the checker
+  too — and NAMES which of the two registers it chose for `--queue`. Every PATH operand goes through
+  the family's shell quoter (bare when the value is already safe, single-quoted when it is not), and
+  the two placeholders are single-quoted literals so their angle brackets and pipe are inert — the
+  line is safe to paste as rendered. `--json` gains an additive `foldScope` array.
+- **Markdown is read through `references/scripts/markdown-blocks.mjs`**, the block model the
+  archivers already use, so fenced examples, heading levels and CRLF are solved once for the family;
+  a document that model refuses is a loud refusal, never a silent empty read.
+
+**Advisory by design:** nothing records that the checker ran, so a skipped or late call is
+indistinguishable from a pre-edit declaration. A fingerprint-bound receipt a gate reads is the next
+slice. Additive throughout — no existing command, flag, output field or exit code changed.
+
 ## 7.0.0 — `/agent-workflow-kit mcp` registers the typed channel in ONE project, and `uninstall` stops reporting an interrupted teardown as a success (AD-108)
 
 > ### ⚠ BREAKING — an `uninstall` run that silently passed can now refuse, and its plan reports more

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '7.0.0'
+  version: '7.2.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/contracts.md

@@ -42,7 +42,7 @@ diverge:
 | `/.aider.input.history` | Aider | file | no | input history |
 | `/.continue/` | Continue | dir | no | project config dir |
 
-The kit's OWN footprint (`KIT_OWN_PATHS`) — `AGENTS.md`, `CLAUDE.md`, `docs/ai/` (subsumes the stamp), the added `scripts/*.mjs`, `docs/plans/`, `.claude/settings.local.json`, and `.claude/settings.json` (hidden-only — visible mode commits it) — is always a candidate in hidden mode.
+The kit's OWN footprint (`KIT_OWN_PATHS`) — `AGENTS.md`, `CLAUDE.md`, `docs/ai/` (subsumes the stamp), the added `scripts/*.mjs`, `docs/plans/`, `.claude/settings.local.json`, `.claude/settings.json` (hidden-only — visible mode commits it), and `.mcp.json` (the `mcp` mode's registration; hidden-only for the same reason, and it carries an absolute machine path) — is always a candidate in hidden mode.
 
 Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
 Deferred to a later release + migration.

package/references/modes/mcp.md

@@ -17,6 +17,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/mcp.mjs [--dry-run | --apply] [--cwd <dir>]`
 2. **Ask consent** via **`AskUserQuestion` where supported**, the no-change option first: keep the shell lanes, or register the typed channel — presenting the trust posture above in plain language.
 3. **Only on an explicit yes**, re-run with `--apply`. It writes **`.mcp.json` FIRST, then `.claude/settings.json`** — settings that enable a server whose entry is not yet there is a client error on every startup. Both writes are merge-don't-clobber (foreign servers, foreign keys and existing allow rules preserved; a re-apply adds nothing twice) and keep each file's existing EOL. New MCP servers are picked up when the client next starts — unlike the `hook` mode, this is not a hot reload.
 
+4. **Hidden-mode deployments:** after apply, run the hide-footprint reconcile (`node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile`) so the registration stays invisible to `git status` — `/.mcp.json` is in the known-footprint registry; every output arm reminds you.
+
 **The two arms that are not a write:**
 
 - **DIFFERING** — `.mcp.json` already carries an `"agent-workflow"` entry that **structurally differs** from ours (another kit copy, a hand-edited path, an added `env`, a `null`). The comparison is deliberately key-order-independent, so a re-serialized identical entry is the SAME registration, while any real difference in what would be launched is a difference. The run **STOPs unwritten, on both lanes**: silently changing what an MCP server launches is exactly what consent must not slide past. The recovery is named — review that entry, then remove or rename it and re-run. The kit never resolves this for you.

package/references/modes/worktrees.md

@@ -14,10 +14,25 @@ The ONE stored-metadata exception is the PREPARED OID recorded in the handoff: l
 Git ≥ 2.36 is required for NUL-terminated worktree porcelain; an older Git fails closed with its
 own verbatim error through the existing Git-error surface.
 
+**The MCP registration is never HANDED to a worktree, and never owned by one.** The scope is the
+untracked lanes this tool drives — the registry copy set and `--include` (refused pre-mutation, and
+a recorded include from an older handoff is filtered out too); a TRACKED `.mcp.json` still arrives
+with `git worktree add`, because that is the checkout, not a copy. `/.mcp.json` names an absolute
+machine path and its consent is per checkout, so it is excluded from the copy set, from the provision
+containment sweep, and from what `cleanup` may remove — a satellite's own `.mcp.json` therefore stays
+classified as foreign work and blocks cleanup, rather than being deleted as ours. The settings half
+is rewritten only under ONE conjunction of proven facts: untracked, bytes still MAIN's (or their
+rebased form), and a launcher proven ABSENT — then the copy loses our `enabledMcpjsonServers`
+membership and our two derived allow rules and nothing else. Every other state keeps its registration
+TOKENS — not necessarily its bytes, since `rebasePins` may still rewrite absolute pins in that same
+file on its own lane — and, where the settings file is readable, well-formed and actually carries
+tokens, gets a neutral line naming them; orphanhood is claimed only where it is proven.
+
 - `provision <slug> --plan <path> [--as <name>.md] [--dir <path>] [--branch <name>] [--include <path>]... [--install] [--resume]`
   — create a feature worktree (default: the visible sibling `<repoParent>/<repoName>--<slug>`,
   branch `aw/<slug>`) and populate it: the registry-derived footprint copy-if-missing (a tracked
-  file is NEVER overwritten), EXACTLY ONE seeded feature plan, the `handoff-<slug>.md` stub
+  file is NEVER overwritten, and `/.mcp.json` is never copied or owned — see below), EXACTLY ONE seeded
+  feature plan, the `handoff-<slug>.md` stub
   (written at provision — the tool's own record; `list` and `cleanup` read it), a
   `node_modules` symlink when main has one and the link stays ignored — a SHARED MUTABLE cache:
   writes through it hit MAIN's node_modules; for isolation RUN the printed isolated-install

package/references/templates/agent_rules.md

@@ -76,10 +76,12 @@ Apply this as part of §2 before any user-facing summary:
 ### 2.6. Planning, review & process-fidelity invariants
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
 - **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **State table BEFORE the guard — enumerate by PROOF, never by exclusion.** The subtraction rule above fires on a repeat finding, which is a LATE signal: by then the review has paid for each miss. The EARLY signal is structural — a decision whose input has **several independent state dimensions** (is it tracked? do the bytes still match the source? does the neighbouring file exist?). Write the table first, admit the write with **ONE conjunction of proven facts**, and funnel every other cell into a single refusal; the table is then the table-driven test. An exclusion list (`if (bad1) return; if (bad2) return;`) fails **OPEN** on the first state nobody enumerated — and "unreadable" is a state, distinct from "absent". A reviewer cannot save you here: it judges the patch in front of it and can only name the NEXT missing state, one round at a time.
 - **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
 - **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
 - **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.

package/tools/fold-scope-cli.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// The CLI half of the finding-scope checker: argv and fs, no rule (the rule is fold-scope.mjs).
+//
+// `--plan` and `--queue` are REQUIRED and never defaulted. A project has two registers that can both
+// look like "the queue" - the planning lifecycle's docs/plans/queue.md and a declared
+// flow.debtQueue - and a checker that guessed would attest a deferral against the wrong file. The
+// procedures advisor renders this command already populated, and NAMES which register it chose.
+//
+// Read-only: reads the two files it is pointed at, writes nothing, records nothing (advisory).
+// Dependency-free, Node >= 22.
+//
+// Exit codes: 0 ACCEPT; 1 a matrix REFUSE; 2 usage - a missing/unknown flag, an unreadable path, or
+// a refusal about the arguments themselves (an unknown or absent --class, an absent --claim).
+
+import { readFileSync } from 'node:fs';
+import { isDirectRun } from './direct-run.mjs';
+import { CLASSES, ROW_FIELDS, decideFoldScope } from './fold-scope.mjs';
+
+const HELP = `fold-scope — declare a finding's SCOPE before the edit (agent-workflow family).
+
+Usage:
+  node fold-scope-cli.mjs --class <${CLASSES.join('|')}> --claim "<the invariant>" \\
+                          --plan <plan-file> --queue <queue-file>
+
+Every finding NAMES the invariant its fix enforces, BEFORE the edit. Where that invariant already
+lives decides the arm, and this checker refuses a claim whose reference does not resolve:
+
+  in-scope       the claim matches WITHIN ONE \`- \` bullet under the plan's ## Verification
+                 (those bullets ARE the acceptance criteria) -> fold here.
+  new-invariant  the claim matches NO acceptance bullet AND exactly one queue row carries all five
+                 fields (${ROW_FIELDS.join(', ')}), its residual exposure
+                 declared "not live" -> the narrow fix ships now, only the generalization defers.
+  blocking       no correct narrow fix exists -> the phase does not close. There is no queue arm.
+
+--plan and --queue are required and never defaulted: guessing the register would attest a deferral
+against the wrong file. The check is advisory — nothing records that it ran, so a skipped or late
+call is indistinguishable from a pre-edit declaration.
+
+Exit codes: 0 ACCEPT; 1 REFUSE; 2 usage (missing/unknown flag, unreadable path, bad --class/--claim).`;
+
+const FLAGS = ['class', 'claim', 'plan', 'queue'];
+
+const parseArgs = (argv) => {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const eq = arg.indexOf('=');
+    const name = arg.startsWith('--') ? arg.slice(2, eq === -1 ? undefined : eq) : null;
+    if (!name || !FLAGS.includes(name)) throw new Error(`unexpected argument "${arg}" (flags: ${FLAGS.map((f) => `--${f}`).join(', ')})`);
+    if (eq !== -1) {
+      opts[name] = arg.slice(eq + 1);
+      continue;
+    }
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`--${name} requires a value`);
+    opts[name] = value;
+    i += 1;
+  }
+  for (const name of ['plan', 'queue']) {
+    if (!opts[name]) throw new Error(`--${name} is required and is never defaulted — name the file this claim is checked against`);
+  }
+  return opts;
+};
+
+// main(argv, deps) -> { code, stdout, stderr }. Never calls process.exit itself (the direct-run
+// guard does), and never reads anything the caller did not point it at.
+export const main = (argv, deps = {}) => {
+  const read = deps.readFileSync ?? readFileSync;
+  if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    return { code: 2, stdout: '', stderr: `fold-scope: ${err.message}` };
+  }
+  const text = {};
+  for (const name of ['plan', 'queue']) {
+    try {
+      text[name] = read(opts[name], 'utf8');
+    } catch (err) {
+      return { code: 2, stdout: '', stderr: `fold-scope: --${name} "${opts[name]}" is unreadable — ${(err && err.message) || err}` };
+    }
+  }
+  const decided = decideFoldScope({ cls: opts.class, claim: opts.claim, planText: text.plan, queueText: text.queue });
+  return { code: decided.exit, stdout: decided.lines.join('\n'), stderr: '' };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exit(result.code);
+}

package/tools/fold-scope.mjs

@@ -0,0 +1,307 @@
+// The finding-scope rule as a checker — the half prose cannot do (the engine canon: procedures.md,
+// plan-execution step 5). A finding NAMES the invariant its fix enforces BEFORE the edit; WHERE that
+// invariant already lives decides the disposition, and this module REFUSES a claim whose reference
+// does not resolve:
+//
+//   in-scope       the claim matches WITHIN ONE acceptance bullet of the plan -> fold here.
+//   new-invariant  the claim matches NO acceptance bullet AND one OPEN queue row carries the claim in
+//                  its invariant field and all five fields (invariant, origin as file:line, narrow
+//                  fix, proof, residual exposure) with that exposure declared NOT live -> the narrow
+//                  fix ships now, only the generalization defers.
+//   blocking       no correct narrow fix exists -> the phase does not close; there is no queue arm.
+//
+// Markdown is read through the family's ONE block model (references/scripts/markdown-blocks.mjs, the
+// module the archivers already read through): fenced regions, ATX headings at 0-3 columns of indent,
+// CRLF and the backtick-info-string rule are ITS problem, not a second hand-rolled grammar here. A
+// document it refuses is a loud refusal, never a silent empty read.
+//
+// ADVISORY in this slice: nothing records that it ran, so a skipped or late call is
+// indistinguishable from a pre-edit declaration. A fingerprint-bound receipt a gate reads is next.
+//
+// Pure string functions - every input is text; the CLI half (fold-scope-cli.mjs) owns the fs.
+// Dependency-free, Node >= 22.
+
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+
+export const CLASSES = ['in-scope', 'new-invariant', 'blocking'];
+export const ROW_FIELDS = ['invariant', 'origin', 'narrow fix', 'proof', 'residual exposure'];
+export const ACCEPTANCE_HEADING = '## Verification';
+// The canon says a deferral row carries "the origin `file:line`". Anchored at the start of the value
+// and a POSITIVE line number, so "file.mjs:12junk" and "file.mjs:0" are not one; trailing context
+// after the token is fine, because the canon asks the row to CARRY a file:line, not to carry nothing
+// else.
+const ORIGIN_SHAPE = /^\S+:[1-9]\d*(\s|$)/;
+// A closed row is not a live deferral. Narrow on purpose: the row TITLE carrying one of these
+// literals refuses fail-closed; the general per-project status grammar is queued, not guessed here.
+const CLOSED_MARKERS = ['DONE', 'CLOSED'];
+const ORIGIN_MISSING = 'origin (the canon requires a file:line)';
+const BULLET = /^-\s+\S/;
+
+const normalize = (s) => String(s ?? '').replace(/\r/g, '').replace(/\s+/g, ' ').trim();
+const contains = (haystack, needle) => normalize(haystack).toLowerCase().includes(needle);
+
+// The ONE bullet scan both readers use, over the block model's lines. A fenced region is a quotation
+// AND a boundary: it closes the block it interrupts, so text past a fence can never join the bullet
+// before it (which would let a far-side literal satisfy a near-side claim). A `-` plus any whitespace
+// run opens a block; a blank or indented line continues it; any other unindented line closes it.
+// Blocks are returned RAW (their own lines) — the queue reader needs the field lines inside them.
+const bulletBlocks = (lines, fencedLines, from, to) => {
+  const blocks = [];
+  let current = null;
+  const close = () => {
+    if (current) blocks.push(current);
+    current = null;
+  };
+  for (let index = from; index < to; index += 1) {
+    if (fencedLines.has(index)) {
+      close();
+      continue;
+    }
+    const line = lines[index];
+    if (BULLET.test(line)) {
+      close();
+      current = [line];
+    } else if (current && (line.trim() === '' || /^\s+\S/.test(line))) {
+      current.push(line);
+    } else {
+      close();
+    }
+  }
+  close();
+  return blocks;
+};
+
+// extractAcceptance(planText) -> the top-level bullets under `## Verification`, each collapsed to one
+// line. Per the planning canon those bullets ARE the acceptance criteria and they are the WHOLE list.
+// ONE heading recognizer decides both ends: the section opens on the block model's `## Verification`
+// heading and closes at the next heading of level 1 or 2, so a level-3 subheading stays INSIDE (which
+// is what "in this section" means) and a 4-space line, being an indented code block rather than a
+// heading, neither opens nor closes it. A Verification with no bullets declares NO criteria.
+export const extractAcceptance = (planText) => {
+  const { lines, headings, fencedLines } = tokenizeMarkdown(String(planText ?? ''), 'the plan');
+  const open = headings.find((heading) => heading.text.trim() === ACCEPTANCE_HEADING);
+  if (!open) return [];
+  const next = headings.find((heading) => heading.index > open.index && heading.level <= 2);
+  return bulletBlocks(lines, fencedLines, open.index + 1, next ? next.index : lines.length)
+    .map((block) => normalize(block.join('\n').replace(/^-\s+/, '')))
+    .filter(Boolean);
+};
+
+// ONE question per pattern: this one asks whether the line CARRIES a label, never whether the value
+// behind it is any good. Requiring a non-empty value here made an empty repeat invisible, so a row
+// could repeat a label and still be admitted; the value is judged downstream, where "" is missing.
+const FIELD_LINE = new RegExp(`^\\s*(?:[-*]\\s+)?(${ROW_FIELDS.map((f) => f.replace(' ', '\\s+')).join('|')})\\s*:\\s*(.*)$`, 'i');
+
+// The labelled fields of one row, folding CONTINUATION lines into the value they belong to (a wrapped
+// invariant read to its first line only would refuse a legitimate deferral). A REPEATED label is
+// recorded and REFUSED, never resolved by keeping the first value: a row saying "not live" and then
+// "live" would otherwise be accepted as not-live, which is the contradiction this fails closed on.
+const parseFields = (block) => {
+  const values = {};
+  let open = null;
+  for (const line of block.split('\n')) {
+    const match = line.match(FIELD_LINE);
+    if (match) {
+      open = match[1].toLowerCase().replace(/\s+/g, ' ');
+      values[open] = [...(values[open] ?? []), match[2].trim()];
+    } else if (open && /^\s+\S/.test(line) && !BULLET.test(line.trim())) {
+      values[open][values[open].length - 1] += ` ${line.trim()}`;
+    } else {
+      open = null;
+    }
+  }
+  const fields = {};
+  for (const label of ROW_FIELDS) fields[label] = values[label]?.[0] ?? null;
+  return { fields, values, duplicates: ROW_FIELDS.filter((label) => (values[label] ?? []).length > 1) };
+};
+
+// The disposition a residual exposure declares. Exactly TWO forms declare the negative: "not live"
+// and "not-live", each a standalone token on both sides — so "not--live", "not - live",
+// "not-live-ish" and "maybe-not-live" declare nothing. EVERY not-live span is removed before the
+// positive is looked for, malformed ones included: the `live` inside a botched negative is not a
+// declaration of the positive, and reading it as one would route the author to blocking over a row
+// that only needs re-wording. A standalone bare `live` then decides, and a row carrying both a
+// declared negative and a real positive is a contradiction that fails closed as live.
+const NEGATIVE_SPAN = /(?<![-\w])not[\s-]*live(?![-\w])/g;
+const DECLARED_NEGATIVE = /(?<![-\w])not(?:\s+|-)live(?![-\w])/;
+const LIVE_TOKEN = /(?<![-\w])live(?![-\w])/;
+const exposureOf = (value) => {
+  const text = String(value ?? '').toLowerCase();
+  const declaredNegative = DECLARED_NEGATIVE.test(text);
+  if (LIVE_TOKEN.test(text.replace(NEGATIVE_SPAN, ' '))) return 'live';
+  return declaredNegative ? 'not-live' : null;
+};
+
+const topLevelRows = (queueText) => {
+  const { lines, fencedLines } = tokenizeMarkdown(String(queueText ?? ''), 'the queue');
+  return bulletBlocks(lines, fencedLines, 0, lines.length).map((block) => block.join('\n'));
+};
+
+const EMPTY_ROW = () => ({ found: false, matches: 0, fields: {}, missing: [...ROW_FIELDS], duplicates: [], exposure: null, closed: null, claimInInvariant: false });
+
+// findDebtRow(queueText, claim) -> the ONE queue row FOR this invariant, its fields and its
+// disposition. Discovery prefers the row whose INVARIANT field carries the claim; the whole-block
+// match is only the fallback, and it exists so a row that carries the claim but no invariant field is
+// still FOUND and its missing field can be named. Zero and several matches are both "not found" with
+// the count: a deferral names ONE row, and guessing which is the unresolved reference this refuses.
+export const findDebtRow = (queueText, claim) => {
+  const needle = normalize(claim).toLowerCase();
+  if (!needle) return EMPTY_ROW();
+  const rows = topLevelRows(queueText).map((block) => ({ block, ...parseFields(block) }));
+  // EVERY recorded value of `invariant` is a candidate key, not just the first: a claim sitting in a
+  // repeated label would otherwise be invisible here and resolve to some OTHER row.
+  const owns = (r) => (r.values.invariant ?? []).some((v) => contains(v, needle));
+  const byInvariant = rows.filter(owns);
+  const hits = byInvariant.length ? byInvariant : rows.filter((r) => contains(r.block, needle));
+  // A candidate that repeats a label cannot be reasoned about at all, so the refusal comes BEFORE the
+  // row is resolved — ahead of the ambiguity count and ahead of every field judgement.
+  const broken = [...new Set(hits.flatMap((r) => r.duplicates))];
+  if (broken.length) return { ...EMPTY_ROW(), matches: hits.length, duplicates: broken };
+  if (hits.length !== 1) return { ...EMPTY_ROW(), matches: hits.length };
+  const { block, fields, duplicates } = hits[0];
+  const missing = ROW_FIELDS.filter((label) => !fields[label]);
+  if (fields.origin && !ORIGIN_SHAPE.test(fields.origin)) missing.push(ORIGIN_MISSING);
+  return {
+    found: true,
+    matches: 1,
+    block,
+    fields,
+    missing,
+    duplicates,
+    exposure: exposureOf(fields['residual exposure']),
+    closed: CLOSED_MARKERS.find((marker) => block.split('\n')[0].includes(marker)) ?? null,
+    claimInInvariant: owns(hits[0]),
+  };
+};
+
+const verdict = (kind, code, exit, claim, lines) => ({
+  verdict: kind,
+  code,
+  exit,
+  lines: [`fold-scope: ${kind} ${code}${claim ? ` — "${claim}"` : ''}`, ...lines],
+});
+const accept = (code, claim, lines) => verdict('ACCEPT', code, 0, claim, lines);
+const refuse = (code, claim, lines, exit = 1) => verdict('REFUSE', code, exit, claim, lines);
+
+const FIVE_FIELDS = ROW_FIELDS.join(', ');
+
+// A document read is the ONE place a throw is expected: the block model REFUSES an unclosed fence and
+// an ambiguous leading `---` rather than guessing, and its message names the file and line.
+const read = (fn) => {
+  try {
+    return { value: fn() };
+  } catch (err) {
+    return { error: (err && err.message) || String(err) };
+  }
+};
+const unreadable = (claim, message) => refuse('document-unreadable', claim, [
+  `  ${message}`,
+  '  a document that cannot be read as markdown is never guessed around — fix it, then re-run.',
+], 2);
+
+// decideFoldScope({ cls, claim, planText, queueText }) -> { verdict, code, exit, lines }.
+// Exit 0 for every ACCEPT, 1 for every matrix REFUSE, 2 for a refusal about the ARGUMENTS themselves
+// (an unknown or absent class, an absent claim, an unreadable document) - the CLI prints the lines
+// and returns the code.
+export const decideFoldScope = ({ cls, claim, planText, queueText } = {}) => {
+  const claimText = normalize(claim);
+  if (!CLASSES.includes(cls)) {
+    return refuse('class-unknown', typeof cls === 'string' ? cls : '', [
+      `  --class must be one of: ${CLASSES.join(', ')} — there is no default arm.`,
+      '  name the invariant the fix would enforce, then say where it already lives.',
+    ], 2);
+  }
+  if (!claimText) {
+    return refuse('claim-absent', '', [
+      '  --claim carries the invariant the fix would enforce, as a literal.',
+      '  a finding with no named invariant has no scope to decide.',
+    ], 2);
+  }
+  if (cls === 'blocking') {
+    return accept('blocking', claimText, [
+      '  no correct narrow fix exists, so the phase does not close.',
+      '  there is no deferral arm here: fix it in this phase, or the phase stays open.',
+    ]);
+  }
+  const criteria = read(() => extractAcceptance(planText));
+  if (criteria.error) return unreadable(claimText, criteria.error);
+  const acceptance = criteria.value;
+  const needle = claimText.toLowerCase();
+  const matched = acceptance.find((bullet) => contains(bullet, needle)) ?? null;
+  if (cls === 'in-scope') {
+    return matched
+      ? accept('in-scope', claimText, [
+          `  matched acceptance bullet: ${matched}`,
+          '  fold here: the invariant is already required by this plan. Fold the finding as a red->green test and re-review.',
+        ])
+      : refuse('in-scope-unmatched', claimText, [
+          `  no acceptance bullet of the plan carries this literal (${acceptance.length} bullet(s) read).`,
+          '  the lane: ship the NARROW fix for the found site (red first, then green); the generalization defers only as',
+          `  --class new-invariant, once a queue row carries ${FIVE_FIELDS}. With no correct narrow fix, --class blocking.`,
+        ]);
+  }
+  if (matched) {
+    return refuse('new-invariant-already-accepted', claimText, [
+      `  the invariant IS an acceptance bullet: ${matched}`,
+      '  route to the fold arm: --class in-scope. Already-required work is never a deferral.',
+    ]);
+  }
+  const found = read(() => findDebtRow(queueText, claimText));
+  if (found.error) return unreadable(claimText, found.error);
+  const row = found.value;
+  if (row.duplicates.length) {
+    return refuse('new-invariant-row-duplicate-field', claimText, [
+      `  a candidate queue row declares more than once: ${row.duplicates.join(', ')}.`,
+      '  a repeated label is not resolved by keeping the first value — a row that says both "not live"',
+      '  and "live" declares a contradiction, and a claim hidden in a repeat would resolve to another row.',
+      '  Delete the duplicate so the row states ONE value per field.',
+    ]);
+  }
+  if (row.matches > 1) {
+    return refuse('new-invariant-row-ambiguous', claimText, [
+      `  ${row.matches} queue rows carry this literal — a deferral names ONE row.`,
+      '  narrow the claim to the invariant statement of the row you mean.',
+    ]);
+  }
+  if (!row.found) {
+    return refuse('new-invariant-row-absent', claimText, [
+      '  no queue row carries this literal.',
+      `  a deferral owes a row carrying all five fields: ${FIVE_FIELDS}, that exposure declared NOT live.`,
+      '  if the exposure IS live, this is not a deferral at all — it is --class blocking.',
+    ]);
+  }
+  if (row.closed) {
+    return refuse('new-invariant-row-closed', claimText, [
+      `  the queue row title carries "${row.closed}" — a closed row is not a live deferral.`,
+      '  re-open that row, or write a new one for the invariant this finding names.',
+    ]);
+  }
+  if (row.missing.length) {
+    return refuse('new-invariant-row-incomplete', claimText, [
+      `  the queue row is missing: ${row.missing.join(', ')}.`,
+      '  a row short of a field is a note, not a deferral — write the field, then re-run.',
+    ]);
+  }
+  if (!row.claimInInvariant) {
+    return refuse('new-invariant-claim-not-invariant', claimText, [
+      `  the row carries this literal, but NOT in its invariant field: ${row.fields.invariant}`,
+      '  a deferral is keyed on the invariant the row states — quote that, or write the row this finding needs.',
+    ]);
+  }
+  if (row.exposure === 'live') {
+    return refuse('new-invariant-exposure-live', claimText, [
+      `  the residual exposure is declared LIVE: ${row.fields['residual exposure']}`,
+      '  a live defect in shipped behaviour is never deferred — route to --class blocking.',
+    ]);
+  }
+  if (row.exposure === null) {
+    return refuse('new-invariant-exposure-undeclared', claimText, [
+      `  the residual exposure declares neither "live" nor "not live": ${row.fields['residual exposure']}`,
+      '  silence is not a declaration — state the disposition in the row.',
+    ]);
+  }
+  return accept('new-invariant', claimText, [
+    `  the queue row carries all five fields and declares its residual exposure NOT live: ${row.fields.origin}`,
+    '  the narrow fix ships in this phase; ONLY the generalization defers.',
+  ]);
+};

package/tools/known-footprint.mjs

@@ -33,7 +33,12 @@ export const stop = (message, fields = {}) =>
 // may have unrelated scripts). `/.claude/settings.json` is carried HIDDEN-ONLY: in hidden mode the
 // kit's own attribution file is a footprint; in visible mode the kit commits it and never runs this
 // tool. It passes the same tracked→ASK classifier, so a project that already commits it gets an ASK,
-// never a silent un-track. `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
+// never a silent un-track. `/.mcp.json` (the `mcp` mode's registration) is the second shared
+// container carried on those terms — the kit merges into it and preserves foreign servers, so the
+// same tracked→ASK arm is what protects a team that commits its own. It is seated here rather than
+// in KNOWN_FOOTPRINT deliberately: KIT_OWN candidacy is unconditional, so the path is in the block
+// BEFORE a later `mcp --apply` writes the file — present-only candidacy would re-open the very
+// follow-up-reconcile gap this entry closes. Never provisioned into a worktree (worktrees.mjs). `/docs/plans/` + both `.claude/settings*.json` are listed because a pure
 // hidden deploy has no tracked `.gitignore`; the classifier drops any candidate a tracked `.gitignore`
 // already covers, so in a repo that DOES track those ignores they are never re-written.
 // The enumeration must cover EVERY file the deploy copies into `scripts/` (bootstrap step 8 copies
@@ -67,6 +72,7 @@ export const KIT_OWN_PATHS = [
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',
+  '/.mcp.json',
 ];
 
 // Every OTHER tool's footprint. `falsePositiveRisk` flags a name generic/ambiguous enough that a

package/tools/mcp-registration.mjs

@@ -183,6 +183,76 @@ export const decideSettingsText = (text, allowRules) => {
   };
 };
 
+// The token-removal COMPLEMENT of mergeSettings (not its exact inverse — merging into an empty file
+// and removing again leaves the managed containers behind), for a settings copy moved away from its `.mcp.json`
+// (a provisioned worktree: it gets no launcher, so a copied enable would be a client error on every
+// client start). Removes ONLY our own tokens — our `SERVER_NAME` membership and our derived allow
+// rules — and preserves every foreign server, foreign rule, foreign key and the file's EOL. Returns
+// `{ text, changed, hasTokens, reason }` (the four outcomes are tabulated at the function); `text`
+// is the input byte-for-byte whenever `changed` is false — this never repairs, and never edits what
+// it did not understand.
+// A JSON round-trip is not content-preserving for everything a file may legally carry, and this
+// function rewrites a file it does NOT own — so each way the trip can lose data is detected and
+// REFUSES the rewrite whole. Two are known and both are checked on the SOURCE TEXT, because after
+// `JSON.parse` the evidence is already gone:
+//   • a number past double precision (9007199254740993 → …992) comes back a different value;
+//   • a duplicate key ({"a":1,"a":2}) collapses to the last one, dropping foreign data silently.
+// String bodies are blanked to `""` first, so a digit run or a colon inside a string is never read
+// as a number or a key. Deliberately strict on numbers: `1.0` and `1e2` are re-spellings rather
+// than losses and are refused too — fail-closed is the correct direction here.
+const blankStrings = (text) => text.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+const JSON_NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][-+]?\d+)?/g;
+
+const countKeys = (value) => (Array.isArray(value)
+  ? value.reduce((n, v) => n + countKeys(v), 0)
+  : isPlainObject(value)
+    ? Object.entries(value).reduce((n, [, v]) => n + 1 + countKeys(v), 0)
+    : 0);
+
+// Why a COUNT: a duplicate at any depth makes the source carry more key tokens than the parsed
+// value has keys. No second JSON parser, and nothing depends on where the duplicate sits.
+const roundTripLoss = (text, parsed) => {
+  const blanked = blankStrings(text);
+  const numbers = blanked.match(JSON_NUMBER) ?? [];
+  if (!numbers.every((lit) => String(JSON.parse(lit)) === lit)) return 'a number would not survive the rewrite';
+  const keyTokens = (blanked.match(/""\s*:/g) ?? []).length;
+  if (keyTokens !== countKeys(parsed)) return 'a duplicate key would be collapsed by the rewrite';
+  return null;
+};
+
+// Four outcomes over `{ text, changed, hasTokens, reason }`, and a caller must be able to tell them
+// apart — `changed:false` alone conflates
+// "nothing of ours is here" with "ours is here and the rewrite was REFUSED", and the second one owes
+// the operator a word:
+//   unreadable          → {changed:false, hasTokens:false, reason:'…'}   not JSON of the shape we write
+//   nothing of ours     → {changed:false, hasTokens:false, reason:null}
+//   refused (lossy)     → {changed:false, hasTokens:true,  reason:'…'}   tokens stay, say why
+//   rewritten           → {changed:true,  hasTokens:true,  reason:null}
+export const withoutRegistration = (text, allowRules = allowRulesFor()) => {
+  const keep = (hasTokens, reason) => ({ text, changed: false, hasTokens, reason });
+  const decided = decideSettingsText(text, allowRules);
+  if (decided.state !== STATE.PRESENT) return keep(false, 'not readable as settings JSON');
+  if (!decided.enabled && decided.allowPresent.length === 0) return keep(false, null);
+  const loss = roundTripLoss(text, decided.data);
+  if (loss !== null) return keep(true, loss);
+  const { [ENABLED_KEY]: enabledList, permissions } = decided.data;
+  const keptEnabled = (Array.isArray(enabledList) ? enabledList : []).filter((n) => n !== SERVER_NAME);
+  const keptAllow = (isPlainObject(permissions) && Array.isArray(permissions.allow) ? permissions.allow : [])
+    .filter((rule) => !allowRules.includes(rule));
+  // Only an allow array that ALREADY existed is rewritten — synthesising `allow: []` where the file
+  // had no such key would be adding foreign content under the name of removing ours.
+  const nextPermissions = isPlainObject(permissions) && Array.isArray(permissions.allow)
+    ? { ...permissions, allow: keptAllow }
+    : permissions;
+  // Rebuilt through the original order of the NON-INDEX keys — a settings file the user reads should
+  // not be reordered by a removal it did not ask for. Integer-like keys are the stated exception:
+  // any JSON round-trip hoists them to the front, because JS object semantics say so.
+  const next = Object.fromEntries(Object.entries(decided.data).map(([key, value]) => (
+    key === ENABLED_KEY ? [key, keptEnabled] : key === 'permissions' ? [key, nextPermissions] : [key, value]
+  )));
+  return { text: formatJson(next, decided.eol), changed: true, hasTokens: true, reason: null };
+};
+
 // readRegistration(root, io?) → the full registration picture of ONE project. `io.serverPath`
 // overrides the running kit's server path (tests); every fs primitive in `io` is the fs-read-nofollow
 // injection contract. NEVER throws.

package/tools/mcp.mjs

@@ -185,16 +185,35 @@ export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
     writeContainedFileAtomic(root, registration.mcpJson.abs, plan.mcpBody, deps, { stop, label: MCP_JSON_REL });
   }
   if (plan.writeSettings) {
-    // The ONE write the preflight deliberately does not do: creating `.claude/` is a mutation, so it
-    // belongs on the apply lane only — a preview that made a directory would not be a preview.
-    assertCreatableDirSafe(join(root, CLAUDE_DIR_REL), deps, { stop, noun: SETTINGS_REL });
-    writeContainedFileAtomic(root, registration.settings.abs, plan.settingsBody, deps, { stop, label: SETTINGS_REL });
+    // A settings failure AFTER the entry landed leaves a STANDING registration on disk that never
+    // reaches formatResult — so the reconcile note has to ride the failure too, or a hidden
+    // deployment is left with a visible `.mcp.json` and no mention of it anywhere.
+    // The catch is around the WRITE, not inside it: a raw fs error (a failing rename) never passes
+    // through the injected stop, and it is exactly the case that strands a standing registration.
+    try {
+      // The ONE write the preflight deliberately does not do: creating `.claude/` is a mutation, so
+      // it belongs on the apply lane only — a preview that made a directory would not be a preview.
+      assertCreatableDirSafe(join(root, CLAUDE_DIR_REL), deps, { stop, noun: SETTINGS_REL });
+      writeContainedFileAtomic(root, registration.settings.abs, plan.settingsBody, deps, { stop, label: SETTINGS_REL });
+    } catch (err) {
+      // Reaching here always leaves a STANDING registration on disk — either this run wrote the
+      // entry (`writeMcpJson`) or the preflight found it already current (`matches`), and those two
+      // are exhaustive, so the note is unconditional rather than guarded by a branch nothing can
+      // take. A differing entry never reaches the writer at all; it STOPs in the preflight.
+      throw Object.assign(err, { message: `${err.message}\n${HIDDEN_MODE_LINE}` });
+    }
   }
   return { ...base, wrote: plan.writeMcpJson || plan.writeSettings };
 };
 
 // ── the report ─────────────────────────────────────────────────────────────────────────
 
+// A registration is an AI-tool footprint: `/.mcp.json` is in the known-footprint registry, so a
+// HIDDEN deployment needs the reconcile before `git status` is clean again. Stated conditionally —
+// this mode never detects visibility, and detecting it would widen what it reads.
+const HIDDEN_MODE_LINE =
+  'hidden-mode note: if this deployment is hidden, run the hide-footprint reconcile so the registration stays out of `git status` (the registry carries /.mcp.json).';
+
 const POSTURE_LINE =
   'trust posture: the registered server is a READ-ONLY child of your MCP client (path/type/size/line facts and literal search over this project root) — it runs OUTSIDE the Bash sandbox, as the client itself does, and exposes no write or exec API. The two allow rules make its tool calls promptless; nothing else in this project changes.';
 
@@ -229,6 +248,7 @@ const maskedReport = (result) => {
     `  merge into ${SETTINGS_REL} (that file was observable — and read where present — so this body already carries what is in it):`,
     indented(result.fragments.settings),
     POSTURE_LINE,
+    HIDDEN_MODE_LINE,
   ].join(LF);
 };
 
@@ -236,7 +256,7 @@ export const formatResult = (result) => {
   if (result.masked) return maskedReport(result);
   const nothingToDo = !result.plan.writeMcpJson && !result.plan.writeSettings;
   if (nothingToDo) {
-    return [`agent-workflow MCP registration — already registered ("${SERVER_NAME}"); nothing to do.`, POSTURE_LINE].join(LF);
+    return [`agent-workflow MCP registration — already registered ("${SERVER_NAME}"); nothing to do.`, POSTURE_LINE, HIDDEN_MODE_LINE].join(LF);
   }
   const lines = [
     result.dryRun
@@ -247,6 +267,7 @@ export const formatResult = (result) => {
     '  the entry this registration declares (re-serialized here; the same structured value goes into the file):',
     indented(JSON.stringify(result.registration.entry, null, JSON_INDENT)),
     POSTURE_LINE,
+    HIDDEN_MODE_LINE,
   ];
   if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root)}`);
   return lines.join(LF);

package/tools/procedures.mjs

@@ -31,6 +31,9 @@ import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from '.
 // The plan-in-flight detector (AD-038) — imported from the plan-files.mjs LEAF (read-only fs by
 // construction); the WRITER-capable grounding.mjs is only NAMED in rendered text, never imported.
 import { plansInFlight, PLANS_REL } from './plan-files.mjs';
+// The family's ONE shell quoter for a RENDERED command operand (bare when the value is already safe,
+// single-quoted otherwise) — the same leaf eight other command renderers here read through.
+import { shellQuoteArg } from './repo-lex.mjs';
 // The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
 // is READ-ONLY: it imports the reader + the SHARED slot/recipe validity, never the fs-writer
 // (orchestration-write.mjs) DIRECTLY — the import-split test pins the direct-import rule.
@@ -298,6 +301,24 @@ const autonomyAdvice = (activity, facts) => {
   ];
 };
 
+// The finding-scope block (procedures.md plan-execution step 5) — plan-execution ONLY and
+// UNCONDITIONAL: the rule routes EVERY finding, review-backed or not, so gating it on REVIEW_RECIPES
+// (which gates only the loop economics above) would hide it from every Solo project. The canon
+// section is printed VERBATIM above, so this block never re-states the rule — it carries only what
+// the canon cannot: the POPULATED checker command, and which of the two registers `--queue` names.
+export const FOLD_SCOPE_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'fold-scope-cli.mjs');
+const foldScopeAdvice = (activity, config, plans) => {
+  if (activity !== 'plan-execution') return [];
+  const declared = config?.flow?.debtQueue ?? null;
+  const queue = declared ?? `${PLANS_REL}/queue.md`;
+  const plan = plans.length === 1 ? `${PLANS_REL}/${plans[0]}` : '<plan-file>';
+  return [
+    'Finding scope (procedures.md plan-execution step 5) — the rule is the section above; this is the checker it names:',
+    `  • node ${shellQuoteArg(FOLD_SCOPE_TOOL)} --class '<in-scope|new-invariant|blocking>' --claim '<the invariant>' --plan ${shellQuoteArg(plan)} --queue ${shellQuoteArg(queue)}`,
+    `  • --queue is ${declared ? `${declared}, the declared flow.debtQueue` : `${queue}, the planning lifecycle queue (no flow.debtQueue is declared)`}. Advisory: nothing records that it ran, so a skipped or late call is indistinguishable from a pre-edit declaration.`,
+  ];
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
@@ -445,7 +466,7 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => {
   const lines = [
     section,
     '',
@@ -464,6 +485,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   if (grounding.length) lines.push('', ...grounding);
   const advice = reviewLoopAdvice(slots, activity);
   if (advice.length) lines.push('', ...advice);
+  if (foldScope.length) lines.push('', ...foldScope);
   lines.push('', ...costLanesAdvice());
   if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
@@ -473,7 +495,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -486,6 +508,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   groundingPreStep: groundingPreStepAdvice(activity, slots, plans),
   // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.
   costLanes: costLanesAdvice(),
+  // ADDITIVE (the fold channel): the finding-scope block, structured (empty outside plan-execution).
+  foldScope,
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
   // ADDITIVE (D-17 U1): the SAME composed lines the human render prints — one array, two renders, so
@@ -574,9 +598,10 @@ export const main = (argv, ctx = {}) => {
     const flowProbe = ctx.flowProbe ?? defaultFlowProbe;
     const flowHalves = config?.flow == null ? null : flowHalvesAdvice(config.flow, flowProbe(cwd));
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
+    const foldScope = foldScopeAdvice(activity, config, plans);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }

package/tools/worktrees.mjs

@@ -16,6 +16,7 @@ import { join, dirname, basename, resolve, relative, isAbsolute, sep } from 'nod
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { MCP_JSON_REL, SERVER_NAME, SETTINGS_REL, withoutRegistration } from './mcp-registration.mjs';
 import {
   KIT_OWN_PATHS, KNOWN_FOOTPRINT, expandGlob, normalizeSlashes, isDirPattern, isGlobPattern,
   patternToProbe,
@@ -65,6 +66,9 @@ const EXCLUDED_BASENAMES = new Set([
 ]);
 // Registry entries provision seeds by its own rules instead of copying wholesale.
 const SEEDED_SEPARATELY = new Set([`/${PLANS_REL}/`]);
+// Never copied AND never owned — unlike SEEDED_SEPARATELY, whose members cleanup may still remove.
+// A satellite's own `.mcp.json` must stay FOREIGN or an ordinary cleanup deletes what we never placed.
+const NEVER_PROVISIONED = new Set(['/.mcp.json']);
 // Copied files whose absolute main-root pins are rebased onto the worktree root.
 const REBASE_TARGETS = Object.freeze(['docs/ai/gates.json', '.claude/settings.json', '.claude/settings.local.json']);
 const TRACKED_PIN_DECLARATION =
@@ -192,6 +196,12 @@ const readFileNoFollow = (fs, abs) => {
   }
 };
 
+// Fatal UTF-8: a lossy decode would let invalid bytes become U+FFFD and pass for text we may rewrite.
+// `ignoreBOM: true` KEEPS a leading BOM in the string — the default STRIPS it, which would make a
+// BOM-carrying file and a BOM-less one decode identically and defeat a byte-faithful comparison.
+const UTF8_STRICT = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const decodeUtf8Strict = (buf) => { try { return UTF8_STRICT.decode(buf); } catch { return null; } };
+
 const NOFOLLOW_WRITE = fsC.O_WRONLY | fsC.O_CREAT | fsC.O_EXCL | (fsC.O_NOFOLLOW ?? 0);
 const COPY_BUFFER_BYTES = 64 * 1024;
 
@@ -650,7 +660,7 @@ export const provisionCopySet = (root, deps = {}) => {
   const fs = fsOf(deps);
   const out = [];
   for (const pattern of KIT_OWN_PATHS) {
-    if (SEEDED_SEPARATELY.has(pattern)) continue;
+    if (SEEDED_SEPARATELY.has(pattern) || NEVER_PROVISIONED.has(pattern)) continue;
     if (isPresent(root, pattern, fs)) out.push(pattern);
   }
   for (const entry of KNOWN_FOOTPRINT) {
@@ -902,7 +912,7 @@ export const rebaseAbsolutePins = (text, mainRoot, wtRoot) => {
 const assertProvisionSourcesContained = ({ root, rootReal, fs, statFollow }) => {
   const rels = [];
   for (const pattern of [...KIT_OWN_PATHS, ...KNOWN_FOOTPRINT.map((e) => e.pattern)]) {
-    if (SEEDED_SEPARATELY.has(pattern)) continue;
+    if (SEEDED_SEPARATELY.has(pattern) || NEVER_PROVISIONED.has(pattern)) continue;
     if (isGlobPattern(pattern)) {
       rels.push(...expandGlob(pattern, { dir: root, readdir: fs.readdir, stat: statFollow }).map((p) => patternToProbe(p)));
       continue;
@@ -2057,7 +2067,13 @@ const rebasePins = ({ root, wtRoot, git, fs, report, journal = NO_JOURNAL }) =>
     }
     const tracked = git(['ls-files', '--', target], wtRoot);
     if (tracked.status !== 0) throw stop(`git ls-files failed for ${target}: ${(tracked.stderr || tracked.stdout).trim()}`);
-    const text = String(cur.bytes);
+    // Fatal decode BEFORE any rewrite: `String(buffer)` turns invalid bytes into U+FFFD, so a
+    // rebase would silently destroy them in a file this lane only means to re-point.
+    const text = decodeUtf8Strict(cur.bytes);
+    if (text === null) {
+      report.push(`  ${target}: not valid UTF-8 — left untouched, pins not rebased`);
+      continue;
+    }
     const { text: rebased, changes } = rebaseAbsolutePins(text, root, wtRoot);
     if (tracked.stdout.trim() !== '') {
       if (changes.length > 0) report.push(`  ${target}: ${TRACKED_PIN_DECLARATION}`);
@@ -2065,7 +2081,7 @@ const rebasePins = ({ root, wtRoot, git, fs, report, journal = NO_JOURNAL }) =>
     }
     if (changes.length === 0) continue;
     const main = readFileNoFollow(fs, join(root, target));
-    const mainText = main.bytes ? String(main.bytes) : null;
+    const mainText = main.bytes ? decodeUtf8Strict(main.bytes) : null;
     const rebasedMain = mainText === null ? null : rebaseAbsolutePins(mainText, root, wtRoot).text;
     if (mainText !== null && (text === mainText || text === rebasedMain)) {
       writeContainedFileAtomic(wtRoot, wtAbs, rebasedMain, fs, { stop: (m) => stop(m) });
@@ -2163,6 +2179,13 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
     // Overlap refusal (pre-mutation): an include rel that another provision lane also populates
     // (the frozen registry footprint, the seeded plan, the handoff) — or another include root —
     // would meet the copy-if-missing kept-exit and skip the identity door entirely.
+    // A NEVER_PROVISIONED path is absent from reservedRels precisely because provision skips it, so
+    // the overlap arm below cannot see it — and an --include would copy it AND record it as owned,
+    // which is the never-owned half of the rule defeated through the one door that bypasses the set.
+    const neverProvisioned = [...NEVER_PROVISIONED].find((p) => includeRelsOverlap(rel, patternToProbe(p).replace(/\/$/, '')));
+    if (neverProvisioned !== undefined) {
+      throw stop(`--include names a path a worktree never gets and never owns (${neverProvisioned}): ${inc} — an MCP registration is machine-local and its consent is per checkout; register the satellite itself instead`);
+    }
     const reserved = reservedRels.find((r) => includeRelsOverlap(rel, r));
     if (reserved !== undefined) {
       throw stop(`--include overlaps a path provision itself populates (${reserved}): ${inc} — the footprint, the seeded plan, and the handoff are copied by provision; drop the --include`);
@@ -2239,6 +2262,69 @@ export const runProvision = ({ argvSlug, flags, cwd, git, deps, log }) => {
   }
 };
 
+// The worktree gets no `.mcp.json`, so a settings enable carried over would name a server it does
+// not declare. Eligibility is decided LIVE by the same two questions rebasePins asks — is the file
+// tracked, and is it still MAIN's bytes (before or after the pin rebase)? — never by a run-local
+// copy log, which a --resume turns into `kept` and silently skips. Anything else is user work: the
+// registration TOKENS stay — the bytes may still move, since rebasePins rewrites absolute pins on
+// its own lane — and the tokens are REPORTED rather than quietly left. Scope note: this is the
+// untracked provision lane; a TRACKED `.mcp.json` arrives with `git worktree add`, not with us.
+//
+// SCOPE, stated: this speaks only about a settings file that is readable, well-formed and actually
+// carries tokens of ours. An absent, unreadable or non-JSON one is not this lane's business and
+// returns silently — `rebasePins` above already reports the unreadable case in its own words.
+const dropMcpRegistration = ({ root, wtRoot, git, fs, report }) => {
+  const wtAbs = join(wtRoot, SETTINGS_REL);
+  const cur = readFileNoFollow(fs, wtAbs);
+  if (!cur.bytes) return;
+  // STRICT decode, and the MAIN comparison below is on BYTES: `String(buffer)` replaces invalid
+  // UTF-8 with U+FFFD, so two DIFFERENT byte sequences can decode to the same string — which would
+  // let a file that is not MAIN's satisfy the "matches MAIN" proof and be rewritten.
+  const text = decodeUtf8Strict(cur.bytes);
+  if (text === null) {
+    report.push(`  ${SETTINGS_REL}: not valid UTF-8 — left untouched, and no registration claim is made about it`);
+    return;
+  }
+  const removal = withoutRegistration(text);
+  if (!removal.hasTokens) return; // nothing of ours in it, or not readable as ours
+  if (removal.reason !== null) {
+    // Tokens ARE here and the rewrite was refused to protect foreign data — never a silent skip.
+    report.push(`  ${SETTINGS_REL}: carries registration tokens for "${SERVER_NAME}" but ${removal.reason}; left untouched`);
+    return;
+  }
+  // ONE conjunction of PROVEN facts admits the write; every other state — including every state a
+  // read cannot settle — takes the single report branch below. Stated as a positive proof rather
+  // than a list of exclusions on purpose: three review rounds each found one more launcher/copy
+  // sub-state an exclusion list had not enumerated, and an unenumerated state failed OPEN.
+  const tracked = git(['ls-files', '--', SETTINGS_REL], wtRoot);
+  if (tracked.status !== 0) throw stop(`git ls-files failed for ${SETTINGS_REL}: ${(tracked.stderr || tracked.stdout).trim()}`);
+  const main = readFileNoFollow(fs, join(root, SETTINGS_REL));
+  const mainText = main.bytes ? decodeUtf8Strict(main.bytes) : null;
+  // Byte equality, and it is NOT interchangeable with string equality: a decoder that strips the BOM
+  // maps a BOM-carrying file and a BOM-less one to the same string. Only the DIRECT branch is
+  // independent of that policy — the rebased branch rebuilds the expected bytes FROM `mainText`, so
+  // it holds only because `ignoreBOM: true` kept the BOM in the decode.
+  const isMainCopy = mainText !== null
+    && (cur.bytes.equals(main.bytes)
+      || cur.bytes.equals(Buffer.from(rebaseAbsolutePins(mainText, root, wtRoot).text, 'utf8')));
+  // ABSENT is the only launcher state that proves the tokens are orphaned. Unreadable, symlinked,
+  // device-masked and present-with-an-entry all mean "a declaration may be live" — never strip.
+  const launcherAbsent = readFileNoFollow(fs, join(wtRoot, MCP_JSON_REL)).absent === true;
+  // The admission is ONE positive conjunction; the chain below only NAMES which proof was missing.
+  const canStrip = tracked.stdout.trim() === '' && isMainCopy && launcherAbsent;
+  const why = canStrip ? null
+    : tracked.stdout.trim() !== '' ? 'tracked'
+      // NOT "user-modified": the same arm covers a MAIN settings file that is absent or unreadable.
+      : !isMainCopy ? 'not proven to match MAIN'
+        : `a ${MCP_JSON_REL} is present or unreadable`;
+  if (!canStrip) {
+    report.push(`  ${SETTINGS_REL}: ${why} — carries registration tokens for "${SERVER_NAME}"; left untouched, remove them by hand if this worktree declares no server`);
+    return;
+  }
+  writeContainedFileAtomic(wtRoot, wtAbs, removal.text, fs, { stop: (m) => stop(m) });
+  report.push(`  ${SETTINGS_REL}: dropped our registration tokens (this worktree declares no ${MCP_JSON_REL})`);
+};
+
 const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed, includeSources, provisionSet, git, deps, fs, report, log }) => {
   // THIS run's proof set: every lane journals the leaf it placed or kept, and nothing else is ever
   // examined by the resume verify — the session's own work is out of scope by construction.
@@ -2261,6 +2347,9 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
   const vscodeMode = provisionVscode({ root, wtRoot: targetPath, slug, git, fs, report, journal });
 
   rebasePins({ root, wtRoot: targetPath, git, fs, report, journal });
+  // AFTER the rebase: stripping first makes the copy differ from MAIN, and rebasePins would then
+  // read it as user work and skip the pins it exists to fix.
+  dropMcpRegistration({ root, wtRoot: targetPath, git, fs, report });
 
   const inFlight = plansInFlight(targetPath, fs.readdir);
   if (inFlight.length !== 1 || inFlight[0] !== seed.name) {
@@ -2877,6 +2966,7 @@ const headEntry = (git, cwd, head, path) => {
 const registryRoots = () => {
   const roots = [];
   for (const pattern of [...KIT_OWN_PATHS, ...KNOWN_FOOTPRINT.map((entry) => entry.pattern)]) {
+    if (NEVER_PROVISIONED.has(pattern)) continue; // on the RAW pattern — normalizing first never matches
     const normalized = normalizeSlashes(pattern).replace(/^\//, '').replace(/\/$/, '');
     if (normalized) roots.push(normalized);
   }
@@ -2891,10 +2981,20 @@ const safeRecordedPath = (path) => {
   return normalized;
 };
 
+// Ownership has TWO sources — the registry and the record's own includes — and BOTH must honour
+// NEVER_PROVISIONED. A record written before the --include refusal existed still names the path, and
+// without this filter that legacy record hands cleanup a registration it may delete. The comparison
+// is includeRelsOverlap, the SAME predicate the refusal uses. Stated honestly: on POSIX that is
+// indistinguishable from an exact match here (a recorded DESCENDANT covers nothing at this path, and
+// case is significant); what it buys is the backslash-platform case fold, already pinned on the
+// predicate itself (worktrees-include-identity.test.mjs) rather than claimed by a test run here.
+const NEVER_PROVISIONED_RELS = [...NEVER_PROVISIONED].map((p) => patternToProbe(p).replace(/\/$/, ''));
+const isNeverProvisionedRel = (rel) => NEVER_PROVISIONED_RELS.some((p) => includeRelsOverlap(rel, p));
+
 const provisionKnownRoots = (identity) => {
   const roots = [
     ...registryRoots(),
-    ...identity.record.includes.map(safeRecordedPath),
+    ...identity.record.includes.map(safeRecordedPath).filter((rel) => !isNeverProvisionedRel(rel)),
     PLANS_REL,
   ];
   if (identity.record.vscode === 'written') roots.push('.vscode/settings.json');