@sabaiway/agent-workflow-kit 7.1.0 → 7.3.0

package/references/templates/agent_rules.md

@@ -23,12 +23,12 @@ Read in order, then confirm before starting:
 4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
-**Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.
+**Before any feature:** name its governing spec(s) — the feature spec under `docs/ai/specs/` for every touched spec-covered slice (zero is legal during adoption; each cited spec's Out of scope bounds that slice's work). Where only a page spec (`docs/ai/pages/<page>.md`) exists it governs as an ADOPTION SHIM: state Out of scope + Revision inline in the plan. If the contract changes, the spec revision is authored WITH the plan (visible at review) and lands with the code, so docs and code never diverge.
 
 **For every code change:**
 1. Grep for similar implementations — reuse existing patterns.
 2. Check the design-system layer for an existing component; if missing, add it there FIRST, then use it.
-3. Verify changes align with `docs/ai/pages/<page>.md`; for a new page, create a full spec.
+3. Verify changes align with the governing spec(s) and `docs/ai/pages/<page>.md`; a new feature gets a `draft` spec (the skill's `SPEC_TEMPLATE.md`), a new page a full page spec.
 4. Follow §2 (Self-Review): functional style, named exports, full variable names, no magic literals.
 5. Write/update tests FIRST (TDD): unit for pure functions, E2E for user flows.
 6. Run quality checks: lint, type-check, tests.
@@ -36,7 +36,7 @@ Read in order, then confirm before starting:
 ### 1.3. Task Completion
 Before claiming "done":
 1. Run all quality gates (lint + type-check + tests) — all green.
-2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation). Only bump "Last Updated" when content actually changed.
+2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation), the governing spec (its revision lands with the code: `draft` -> `live` on the landing row). Only bump "Last Updated" when content actually changed.
 3. Run the docs cap-validator + index-freshness gate (pre-commit also enforces). On failure: trim the offending file, or run the changelog rotation if the offender is `changelog.md`.
 4. If the work executed a plan file — run that plan's final **Phase: Cleanup** (see the planning skill / §5). Without it the plan is not done.
 5. **Ask before committing** (§4): report lint / type-check / test counts + docs status, then wait for explicit approval. DO NOT auto-commit.
@@ -78,9 +78,11 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **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.
+- **Spec-first.** A plan names its GOVERNING spec(s) — zero, one or many, one per touched spec-covered slice (the feature spec under `docs/ai/specs/`; page-only coverage governs as an ADOPTION SHIM, with Out of scope + Revision stated inline in the plan). Each cited spec's Out of scope bounds that slice's work and the plan's non-goals restate it per slice — no global union; a cross-spec conflict is resolved by a spec revision BEFORE approval, never by silent precedence. A NEW feature's draft spec exists AT plan review (a `create` row); a change to a governed contract rides the plan as its proposed revision (a `modify` row); approval confirms plan and contract atomically, and the revision lands with the code. Scenario bindings are per scenario: a new scenario is `unbound` until its test lands in the same plan, and a status never regresses for an extension.
 - **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/references/templates/specs/index.md

@@ -0,0 +1,21 @@
+---
+type: spec
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 80
+kind: index
+---
+
+# Specs
+
+> Up: [technical_specification.md](../technical_specification.md)
+
+The top spec is the system root; this store holds the per-feature contracts under it. Every folder's
+`index.md` lists ONLY its immediate children (at most 30); a spec over 150 lines is promoted to
+`<slug>/index.md` + parts. Author a new spec from the skill's `SPEC_TEMPLATE.md`; the canon is the
+engine's `references/specs.md`.
+
+## Children
+

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
@@ -64,9 +69,12 @@ export const KIT_OWN_PATHS = [
   '/scripts/migrate-gates-branches.test.mjs',
   '/scripts/migrate-gates.mjs',
   '/scripts/migrate-gates.test.mjs',
+  '/scripts/spec-schema.mjs',
+  '/scripts/spec-schema.test.mjs',
   '/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/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');