@sabaiway/agent-workflow-memory 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.3.0 — the migration emits a destination that refuses by name, accepts the producer marker, and preserves a vendored core check (AD-092 + AD-093 + AD-094; ships with kit 5.7.0)
+
+The `migrate-gates.mjs` canon moves in lockstep with the kit it is byte-twinned to. Three changes,
+all in the drift-guarded shared block or the branches around it:
+
+- **The emitted coverage destination becomes `"${AW_GIT_DIR:?exported by run-gates}/…lcov.info"`.**
+  Where the runner injects the variable, behaviour is byte-identical; where a human pastes the cmd
+  into a bare shell, bash refuses loudly by name — the old form expanded to empty and wrote the
+  lcov to the filesystem root. Recognition stays APPEND-ONLY: every previously emitted form is
+  still recognised, so an old-form declaration migrates as `keep` with zero diff.
+- **The migration recognises the `lcovProducer` marker.** An optional gate-level boolean; only the
+  literal `true` is a producer claim, and producer-ness stays POSITIONAL — a marker on the coverage
+  checker itself never self-pairs. Strict schema validation of the key lives in the kit
+  (`gates-declaration.mjs`), which accepts it in lockstep with this release; the published 5.6.0
+  kit rejects a marker-carrying `gates.json` at exit 5 by design (forward-only; the kit's
+  Issue-016 note owns the cross-version statement).
+- **A vendored copy of a core check is PRESERVED instead of stopping the upgrade.** The
+  three-outcome claim classifier (`canonical` / `tool-elsewhere` / `not-the-tool`) routes a
+  shape-matching copy at a non-canonical realpath into a `keep` row plus separately rendered
+  verify metadata — exit 0, nothing auto-added, a zero-diff apply, with the preview stating the
+  verification instead of
+  claiming final-run-capability the runner would refuse. A genuine id-squatter still hard-stops.
+
+This package stays standalone — it imports nothing from the kit; the shared block is held equal by
+the text drift guard, never by an import.
+
 ## 4.2.0 — the gates migration stops handing you a coverage checker with nothing to read (AD-089)
 
 `migrate-gates.mjs` added the canonical `coverage-check` gate to any legacy declaration that lacked

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '4.2.0'
+  version: '4.3.0'
 ---
 
 # agent-workflow-memory

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/scripts/migrate-gates-branches.test.mjs

@@ -10,10 +10,13 @@ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, lstat
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { UNIT_TESTS_COVERAGE_FLAGS, RETIRED_STORE_BASENAMES, main } from './migrate-gates.mjs';
+import { CHECKER_CLAIM, UNIT_TESTS_COVERAGE_FLAGS, RETIRED_STORE_BASENAMES, checkerClaimTool, classifyCheckerClaim, main } from './migrate-gates.mjs';
 
+// Both core checks exist as real files — canonicity is a realpath anchor, so a check whose file is
+// absent resolves to nothing and is no claim at all (the fail-closed answer run-gates gives too).
 const KIT_TOOLS = mkdtempSync(join(tmpdir(), 'migrate-branches-kit-'));
 writeFileSync(join(KIT_TOOLS, 'coverage-check.mjs'), '// the installed checker the migration points at\n');
+writeFileSync(join(KIT_TOOLS, 'review-state.mjs'), '// the installed review-state check\n');
 
 const mkProject = (gates) => {
   const root = mkdtempSync(join(tmpdir(), 'migrate-branches-'));
@@ -34,6 +37,8 @@ const CHECKER = { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOL
 const REVIEW_STATE = { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` };
 const LEGACY = { id: 'review-ledger', title: 'L', cmd: 'node "/kit/tools/review-ledger.mjs" --check' };
 const UNIT = { id: 'unit-tests', title: 'U', cmd: 'node --test tools/*.test.mjs' };
+// A suite the closed producer world cannot express, declaring itself with the optional marker.
+const MARKED_SUITE = { id: 'suite', title: 'S', cmd: 'pnpm vitest run --coverage', lcovProducer: true };
 
 describe('migrate-gates — refusal and no-op branches', () => {
   it('--help prints the contract and exits 0', () => {
@@ -141,6 +146,146 @@ describe('migrate-gates — refusal and no-op branches', () => {
     rmSync(root, { recursive: true, force: true });
   });
 
+  it('a marker-carrying entry survives an apply UNCHANGED — the loader is lenient, the writer opaque', () => {
+    // The declaration this tool rewrites may carry keys it knows nothing about. The loader accepts
+    // any `{ gates: [...] }` shape and the writer re-serializes the ENTRY, not a reconstruction of
+    // it, so an upgrade over a marker-carrying deployment never silently drops the claim.
+    const root = mkProject([LEGACY, MARKED_SUITE, REVIEW_STATE]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io), 0, io.err.join('\n'));
+    const raw = readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8');
+    const written = JSON.parse(raw).gates;
+    assert.deepEqual(written.map((g) => g.id), ['suite', 'review-state', 'coverage-check'], 'the checker is ADDED over a marker-claimed producer');
+    assert.deepEqual(written[0], MARKED_SUITE, 'the marked entry round-trips key for key');
+    assert.match(raw, /"lcovProducer": true/, 'and the marker is really in the written bytes');
+    assert.doesNotMatch(io.out.join('\n'), /WARNING/, 'nothing is withheld over a declared producer');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a marker on the CHECKER ITSELF never self-pairs — the declared pair stays INERT', () => {
+    // The producer question is POSITIONAL: the checker always ends up last, so it can never be its
+    // own producer. Asking it over the whole kept set would let this declaration certify itself
+    // into final-run-capability with nothing writing the lcov.
+    const root = mkProject([{ id: 'lint', title: 'L', cmd: 'eslint .' }, REVIEW_STATE, { ...CHECKER, lcovProducer: true }]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+    const text = io.out.join('\n');
+    assert.match(text, /INERT/, 'the dead pair is named');
+    assert.doesNotMatch(text, /already final-run-capable/, 'and never claimed capable');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a MARKED unit-tests entry is a zero-diff keep — never extended, never reported customized', () => {
+    // Both arms the marker settles at once: `npm test` is a cmd this tool cannot verify (customized
+    // without the marker), and rewriting a cmd whose owner declared it the producer would change
+    // bytes the byte-exact hook approval binds.
+    const marked = { id: 'unit-tests', title: 'U', cmd: 'npm test', lcovProducer: true };
+    const root = mkProject([marked, REVIEW_STATE]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+    const text = io.out.join('\n');
+    assert.match(text, /ADD coverage-check/, 'the claimed producer unlocks the checker');
+    assert.doesNotMatch(text, /EXTEND unit-tests/, 'a claimed producer cmd is never rewritten');
+    assert.doesNotMatch(text, /CUSTOMIZED/, 'nor reported as a cmd the tool cannot verify');
+    rmSync(root, { recursive: true, force: true });
+
+    // The SAME entry unmarked is the customized/withheld path — the marker is what settles it.
+    const bare = mkProject([{ id: 'unit-tests', title: 'U', cmd: 'npm test' }, REVIEW_STATE]);
+    const io2 = quiet();
+    assert.equal(main(['--cwd', bare, '--kit-tools', KIT_TOOLS], io2), 0, io2.err.join('\n'));
+    const text2 = io2.out.join('\n');
+    assert.match(text2, /CUSTOMIZED/);
+    assert.doesNotMatch(text2, /ADD coverage-check/, 'the checker stays withheld with no producer');
+    rmSync(bare, { recursive: true, force: true });
+  });
+
+  it('a marker over an UNRUNNABLE cmd never unlocks the checker — the lenient loader has no validator', () => {
+    // This tool accepts any `{ gates: [...] }` shape, so an entry the strict validator would refuse
+    // reaches the plan builder intact. A marker on such an entry must not make the migration ADD the
+    // canonical checker: the result would be the dead pair the withhold exists to prevent, and the
+    // written declaration would then fail run-gates outright.
+    for (const cmd of ['   ', 'echo a\nrm -rf b']) {
+      const root = mkProject([{ id: 'suite', title: 'S', cmd, lcovProducer: true }, REVIEW_STATE]);
+      const io = quiet();
+      assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+      const text = io.out.join('\n');
+      assert.doesNotMatch(text, /ADD coverage-check/, `an unrunnable cmd must not unlock the checker: ${JSON.stringify(cmd)}`);
+      assert.match(text, /WARNING: the canonical coverage-check gate was NOT added/, 'and the withhold is stated');
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('a marker on a DUPLICATE canonical checker never produces for the other — nor claims capability', () => {
+    // `--final` accepts exactly ONE canonical checker, and a checker cannot write the lcov it reads.
+    // Excluding only the LAST checker row from the producer search let a marker on the first one pair
+    // with the second, and the preview then called the result final-run-capable over a declaration
+    // --final rejects outright, with nothing writing the file.
+    const root = mkProject([{ ...CHECKER, id: 'coverage-check', lcovProducer: true }, REVIEW_STATE, { ...CHECKER, id: 'coverage-check-2' }]);
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+    const text = io.out.join('\n');
+    assert.doesNotMatch(text, /already final-run-capable/, 'two checkers are never a final-run-capable result');
+    assert.match(text, /2 declared gates are the canonical coverage checker/, 'the duplication is NAMED');
+    assert.match(text, /INERT/, 'and the pair is still reported inert — nothing writes the lcov');
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('the tool-claim twin RUNS in this module — three outcomes, fail-closed on the unresolvable', () => {
+    // The text drift guard (beside the kit's own copy) proves the two owners are byte-equal; it
+    // cannot prove this copy WORKS, because the region is byte-equal inside a DIFFERENT host with
+    // different imports. Executing it here is what proves the twin resolves everything it uses.
+    const canonical = join(KIT_TOOLS, 'coverage-check.mjs');
+    const root = mkProject([]);
+    try {
+      const elsewhere = join(root, 'vendor-coverage-check.mjs');
+      writeFileSync(elsewhere, '// a vendored copy\n');
+      const tool = checkerClaimTool('coverage-check.mjs', canonical);
+      assert.equal(classifyCheckerClaim(tool, `node "${canonical}" --check`, KIT_TOOLS), CHECKER_CLAIM.CANONICAL);
+      const vendored = checkerClaimTool('vendor-coverage-check.mjs', canonical);
+      assert.equal(classifyCheckerClaim(vendored, `node "${elsewhere}" --check`, KIT_TOOLS), CHECKER_CLAIM.ELSEWHERE);
+      assert.equal(classifyCheckerClaim(tool, `node "${canonical}" --check || true`, KIT_TOOLS), CHECKER_CLAIM.NOT_THE_TOOL, 'a masked form is no claim');
+      assert.equal(classifyCheckerClaim(tool, `node "${join(KIT_TOOLS, 'nowhere', 'coverage-check.mjs')}" --check`, KIT_TOOLS), CHECKER_CLAIM.NOT_THE_TOOL, 'unresolvable fails closed');
+      assert.equal(classifyCheckerClaim(tool, 'node $(pwd)/coverage-check.mjs --check', KIT_TOOLS), CHECKER_CLAIM.NOT_THE_TOOL, 'a shell-active bare token is no claim');
+    } finally {
+      rmSync(root, { recursive: true, force: true }); // every other case here cleans up; this one held its root only for a path
+    }
+  });
+
+  it('a VENDORED deployment previews at exit 0 and its --apply writes ZERO bytes', () => {
+    // The upgrade path this fixes: every preview AND every apply over a deployment that declared the
+    // checker through its own vendored copy used to exit 1 on an id collision, so such a deployment
+    // could not be upgraded at all.
+    const vendoredTools = mkdtempSync(join(tmpdir(), 'migrate-branches-vendored-'));
+    writeFileSync(join(vendoredTools, 'coverage-check.mjs'), '// a vendored copy of the checker\n');
+    const vendored = { id: 'coverage-check', title: 'CC', cmd: `node "${join(vendoredTools, 'coverage-check.mjs')}" --check` };
+    const root = mkProject([UNIT_DONE, REVIEW_STATE, vendored]);
+    const before = readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8');
+
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+    const preview = io.out.join('\n');
+    assert.match(preview, /VERIFY \(preserved exactly as declared\): coverage-check/);
+    assert.doesNotMatch(preview, /ADD coverage-check/, 'nothing is added over a checker that is already declared');
+    assert.doesNotMatch(io.err.join('\n'), /id collision/, 'a vendored copy is not a squatter');
+
+    const io2 = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS, '--apply'], io2), 0, io2.err.join('\n'));
+    assert.equal(readFileSync(join(root, 'docs', 'ai', 'gates.json'), 'utf8'), before, 'the apply is a ZERO-DIFF write');
+    assert.match(io2.out.join('\n'), /NOT final-run-capable/, 'and the withheld claim survives the no-op apply');
+    rmSync(vendoredTools, { recursive: true, force: true });
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a vendored copy named by a RELATIVE path resolves against the PROJECT root, as the runner resolves it', () => {
+    const root = mkProject([UNIT_DONE, REVIEW_STATE, { id: 'coverage-check', title: 'CC', cmd: 'node "vendor/coverage-check.mjs" --check' }]);
+    mkdirSync(join(root, 'vendor'), { recursive: true });
+    writeFileSync(join(root, 'vendor', 'coverage-check.mjs'), '// a vendored copy inside the project\n');
+    const io = quiet();
+    assert.equal(main(['--cwd', root, '--kit-tools', KIT_TOOLS], io), 0, io.err.join('\n'));
+    assert.match(io.out.join('\n'), /VERIFY \(preserved exactly as declared\): coverage-check/, 'a relative token is resolved, not dismissed');
+    rmSync(root, { recursive: true, force: true });
+  });
+
   it('an un-unlinkable retired store is reported LOUDLY and never fails the migration', () => {
     const root = mkProject([LEGACY, UNIT]);
     spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' });

package/references/scripts/migrate-gates.mjs

@@ -56,13 +56,29 @@ export const LEGACY_FORMS = Object.freeze([
 //
 // The destination is written against AW_GIT_DIR, which run-gates exports to every gate child on a
 // plain run AND on --final (AW_LCOV_FILE is --final only), so one cmd survives the unmet
-// producer-variable preflight in both modes. The explicit stdout reporter is not decoration:
-// without it the lcov reporter swallows the human TAP/spec stream.
+// producer-variable preflight in both modes. The `:?` is not decoration either: this cmd is also
+// PASTE-READY, and the required-parameter form makes bash refuse BY NAME when AW_GIT_DIR is unset
+// or EMPTY, where a bare `$AW_GIT_DIR` expanded to empty and wrote the lcov to the filesystem ROOT.
+// Residual, stated: `:?` says nothing about the value's ORIGIN — a STALE exported AW_GIT_DIR
+// expands fine and the lcov lands under it; only the runner's own injection makes it the right dir.
+// The explicit stdout reporter keeps the human stream: without it the lcov reporter swallows the
+// TAP/spec output.
 export const UNIT_TESTS_COVERAGE_FLAGS =
-  '--experimental-test-coverage --test-reporter=lcov --test-reporter-destination="$AW_GIT_DIR/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout';
+  '--experimental-test-coverage --test-reporter=lcov --test-reporter-destination="${AW_GIT_DIR:?exported by run-gates}/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout';
 
-// The ONE suite body that produces that lcov with no extra dependency.
+// Every flag set the kit has EVER emitted — APPEND-ONLY, newest first. Emission uses the head; the
+// tail exists so a declaration written by an EARLIER kit and living on disk in a deployed project
+// keeps reading as the producer it is. De-recognizing a prior form would silently reclassify a
+// working suite gate as customized and withhold the checker over it.
+export const KNOWN_COVERAGE_FLAG_SETS = Object.freeze([
+  UNIT_TESTS_COVERAGE_FLAGS,
+  '--experimental-test-coverage --test-reporter=lcov --test-reporter-destination="$AW_GIT_DIR/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout',
+]);
+
+// The ONE suite body that produces that lcov with no extra dependency (the EMITTED form), beside
+// the closed set of bodies recognition accepts.
 export const COVERAGE_PRODUCER_BODY = `node --test ${UNIT_TESTS_COVERAGE_FLAGS}`;
+const KNOWN_PRODUCER_BODIES = Object.freeze(KNOWN_COVERAGE_FLAG_SETS.map((flags) => `node --test ${flags}`));
 
 // The per-PM exec wrappers a fill offer puts that body behind. Recognition must cover every form
 // the kit has EMITTED, so the prefixes are matched literally; gates-init's execCmdFor stays the one
@@ -95,8 +111,9 @@ const PRODUCER_EXEC_PREFIXES = Object.freeze([
 const PRODUCER_PATH_TOKEN = /^(?!-)[A-Za-z0-9_./*{},:@+=~?[\]!'"-]+$/;
 const pathShapedTail = (tail) => tail === '' || tail.split(/[ \t]+/).every((token) => PRODUCER_PATH_TOKEN.test(token));
 const carriesProducerBody = (text) =>
-  text === COVERAGE_PRODUCER_BODY ||
-  (text.startsWith(`${COVERAGE_PRODUCER_BODY} `) && pathShapedTail(text.slice(COVERAGE_PRODUCER_BODY.length).trim()));
+  KNOWN_PRODUCER_BODIES.some(
+    (body) => text === body || (text.startsWith(`${body} `) && pathShapedTail(text.slice(body.length).trim())),
+  );
 
 // matchesCoverageProducer(cmd) → CLOSED-WORLD over the full command forms the kit emits, never a
 // substring probe: `echo "$AW_GIT_DIR/agent-workflow-lcov.info"`, a half-written reporter flag set,
@@ -108,8 +125,120 @@ export const matchesCoverageProducer = (cmd) => {
   if (carriesProducerBody(trimmed)) return true;
   return PRODUCER_EXEC_PREFIXES.some((prefix) => trimmed.startsWith(prefix) && carriesProducerBody(trimmed.slice(prefix.length)));
 };
+
+// isCoverageProducerGate(gate) → the GATE-level producer question, and the ONE predicate every
+// consumer asks it through: does THIS declared entry write the lcov the canonical checker reads?
+// Exactly two ways to be one — the cmd passes the closed world above, or the declaration CLAIMS
+// production through the optional `lcovProducer` marker. The marker exists because the closed world
+// is a `node --test` world: a project whose primary suite is another runner has NO cmd form
+// recognition can accept, so without it the checker over such a suite reads as a dead pair forever.
+// Recognition itself never widens (anti-squatter) — the marker is a declared claim, not a new
+// grammar. Only the literal `true` claims: any truthy value would let the string "false" certify.
+// And the claim is about the DECLARATION, never the run — a marked gate that produces no lcov still
+// ends `skipped-no-lcov` / `attested=no` at run time.
+// An entry with no RUNNABLE cmd claims nothing (fail closed): no string cmd, an empty or
+// whitespace-only one, or one carrying an embedded newline. The strict validator already refuses all
+// three, but this predicate has a SECOND host — the standalone migration's loader is deliberately
+// lenient — and a marker must never make a checker pair with an entry that runs nothing there.
+export const isCoverageProducerGate = (gate) => {
+  if (gate === null || typeof gate !== 'object' || Array.isArray(gate) || typeof gate.cmd !== 'string') return false;
+  if (gate.cmd.trim() === '' || /[\r\n]/.test(gate.cmd)) return false;
+  return matchesCoverageProducer(gate.cmd) || gate.lcovProducer === true;
+};
 // coverage-producer canon <<< END drift-guarded region
 
+// checker-claim canon >>> BEGIN drift-guarded region
+// Authored TWICE, byte-identically: in the composition root's tools/checker-claim.mjs and in the
+// memory substrate's references/scripts/migrate-gates.mjs. Neither side imports the other — the
+// substrate is standalone and must not depend on the root, and the root must not import mirrored
+// bytes — so a TEXT drift guard beside the root's copy holds them equal. Edit BOTH, then re-run the
+// mirror sync.
+//
+// A cmd makes exactly ONE of three claims about a given tool, and collapsing them into a boolean is
+// what makes a VENDORED copy of the tool read as "the tool is not declared at all" — a false
+// absence, with a remedy (adopt it) that then collides with the entry already there:
+//   • canonical      — this tool's `--check` invocation, resolving to THIS copy of it
+//   • tool-elsewhere — the same invocation shape, resolving to a DIFFERENT real copy
+//   • not-the-tool   — anything else: another command, a masked form, an inadmissible token, or a
+//                      path nothing can resolve
+// The realpath anchor never widens: a lookalike file that merely carries the basename is not this
+// tool, whatever it prints. What widens is the VOCABULARY. Stated residual, unchanged by the split:
+// nothing here reads the file's CONTENT, so a byte-swapped file at the canonical path is invisible.
+export const CHECKER_CLAIM = Object.freeze({
+  CANONICAL: 'canonical',
+  ELSEWHERE: 'tool-elsewhere',
+  NOT_THE_TOOL: 'not-the-tool',
+});
+
+// The token is screened by the rules of the quoting it actually carries, because the two halves are
+// interpreted differently and a single screen would be wrong for one of them:
+//   • QUOTED — double quotes survive most bytes, so only what breaks OUT of them is refused.
+//   • BARE   — anything the shell may split, expand or glob makes the executed command different
+//              from the string, so a bare token is admitted only from a known-safe alphabet.
+// Either way the point is the same: a path that resolves literally here while the shell would read
+// it differently must never be called a claim about this tool, or the screen certifies a command
+// that never runs.
+export const dqUnsafePath = (text) => [...text].some((ch) => {
+  const code = ch.codePointAt(0);
+  return ch === '"' || ch === '$' || code === 96 || code === 92 || code === 13 || code === 10;
+});
+
+// Stated as the bytes the shell ACTS on, not as an alphabet of blessed ones: an allow-list refuses
+// perfectly ordinary paths (`@`, `+`, `,`, `%`, `=`, anything non-ASCII) that the shell passes
+// through verbatim, and refusing a command that really is canonical is its own defect. Whitespace
+// and ASCII control bytes are refused too — a bare token cannot contain them and still be one token.
+const SHELL_ACTIVE_BARE = new Set([...'"\'\\$|&;<>(){}[]*?!#~^`']);
+const bareTokenSafe = (text) => text.length > 0 && ![...text].some((ch) => {
+  const code = ch.codePointAt(0);
+  return code <= 0x20 || code === 0x7f || SHELL_ACTIVE_BARE.has(ch);
+});
+
+const RE_META = /[.*+?^${}()|[\]\\]/g;
+
+// checkerClaimTool(basename, canonicalPath) → the screen for ONE tool. The shape is the STRICT full
+// command — `node` + ONE (quoted or bare) path token + the exact basename + ` --check` + END — so a
+// masked form (`--check --help`, `--check || true`, a prefix command) is never any claim at all.
+// Separators are PLAIN SPACES, not \s: a newline between the tokens is not a command a runner would
+// execute as written. The basename is regex-escaped here, never by the caller — a caller-escaped
+// literal is one forgotten backslash away from a dot matching any byte.
+export const checkerClaimTool = (basename, canonicalPath) => {
+  const safe = basename.replace(RE_META, '\\$&');
+  return Object.freeze({
+    re: new RegExp(`^node +(?:"((?:[^"]*[/\\\\])?${safe})"|((?:[^\\s"]*[/\\\\])?${safe})) +--check$`),
+    canonical: canonicalPath,
+  });
+};
+
+// classifyCheckerClaim(tool, cmd, projectDir) → one CHECKER_CLAIM value. Every unresolvable side
+// fails CLOSED to `not-the-tool`: an unresolvable path is not evidence the tool lives elsewhere, it
+// is evidence nothing can be told about it — and `tool-elsewhere` is a claim a consumer ACTS on.
+//
+// Two screens beyond the shape, for the same reason the quoting screens exist — a claim must never
+// be minted for a command that cannot run the tool as written:
+//   • a token starting with `-` is an OPTION to node, whatever it resolves to on disk. (First-order,
+//     like the producer canon's own leading-`-` rule: `{x,-y}` still defeats it, and the cost of a
+//     miss is only a withheld claim.)
+//   • the RESOLVED target must be a REGULAR FILE. A directory or a FIFO carrying the basename
+//     resolves perfectly well and is not a copy of anything; `realpathSync` succeeding proves a path
+//     exists, never that it is a tool. lstat runs AFTER realpath, so there is no link left to follow.
+export const classifyCheckerClaim = (tool, cmd, projectDir) => {
+  if (typeof cmd !== 'string' || typeof projectDir !== 'string') return CHECKER_CLAIM.NOT_THE_TOOL;
+  const match = tool.re.exec(cmd.trim());
+  if (!match) return CHECKER_CLAIM.NOT_THE_TOOL;
+  const token = match[1] ?? match[2];
+  const admissible = match[1] !== undefined ? !dqUnsafePath(token) : bareTokenSafe(token);
+  if (!admissible || token.startsWith('-')) return CHECKER_CLAIM.NOT_THE_TOOL;
+  const declared = isAbsolute(token) ? token : join(projectDir, token);
+  try {
+    const resolved = realpathSync(declared);
+    if (!lstatSync(resolved).isFile()) return CHECKER_CLAIM.NOT_THE_TOOL;
+    return resolved === realpathSync(tool.canonical) ? CHECKER_CLAIM.CANONICAL : CHECKER_CLAIM.ELSEWHERE;
+  } catch {
+    return CHECKER_CLAIM.NOT_THE_TOOL;
+  }
+};
+// checker-claim canon <<< END drift-guarded region
+
 // The RETIRED kit-owned git-dir stores the deleted machinery wrote — dead data a consumer's
 // upgrade would otherwise strand forever. The migration cleans them (consented via the preview;
 // ENOENT is a silent no-op; any other unlink error is reported loudly but never fails the
@@ -134,36 +263,35 @@ export const findRetiredStores = (cwd) => {
 
 const UNIT_TESTS_PREFIX = 'node --test ';
 
-// The core-check forms the stripped core anchors on (same strict single-invocation shape as the
-// legacy matcher). Canonicity is PURE path equality against the caller-named kit tools dir —
-// an ABSOLUTE token resolving to the installed tool; run-gates --final does the live realpath
-// check. A cmd that MATCHES the shape but resolves elsewhere (or relatively) is a LOOKALIKE —
-// reported customized, never counted as the core check.
-const CORE_CHECK_RE = { 'coverage-check': legacyRe('coverage-check\\.mjs'), 'review-state': legacyRe('review-state\\.mjs') };
-const coreCheckToken = (cmd) => /^node\s+(?:"([^"]+)"|([^\s"]+))\s+--check$/.exec(cmd.trim())?.slice(1).find(Boolean) ?? null;
-const samePath = (a, b) => {
-  try {
-    return realpathSync(a) === realpathSync(b);
-  } catch {
-    return resolve(a) === resolve(b); // an unresolvable side falls back to the lexical compare
-  }
-};
-const isCanonicalCoreCheck = (name, cmd, kitToolsDir) => {
-  if (!CORE_CHECK_RE[name].test(cmd.trim())) return false;
-  const token = coreCheckToken(cmd);
-  return token !== null && isAbsolute(token) && samePath(token, join(kitToolsDir, `${name}.mjs`));
-};
+// The core checks the stripped core anchors on, asked through the checker-claim canon above — the
+// SAME three outcomes, so a declared cmd is read as what it is: this copy of the tool, a DIFFERENT
+// copy of it, or not the tool at all. Resolution is anchored on the PROJECT root, exactly as
+// run-gates resolves a declared token (gates-declaration.mjs matchesCanonicalCheck), so the
+// migration and the runner never disagree about which copy a cmd names.
+const CORE_CHECK_NAMES = Object.freeze(['coverage-check', 'review-state']);
+const coreCheckTools = (kitToolsDir) =>
+  Object.fromEntries(CORE_CHECK_NAMES.map((name) => [name, checkerClaimTool(`${name}.mjs`, join(kitToolsDir, `${name}.mjs`))]));
 
-// buildMigrationPlan(gates, kitToolsDir) → the PURE migration plan.
+// buildMigrationPlan(gates, kitToolsDir, projectDir) → the PURE migration plan.
 // plan rows: { action: 'keep' | 'remove' | 'extend' | 'move' | 'add', entry, reason }.
 // finalCapable mirrors the run-gates --final acceptance shape: the canonical review-state check
 // must be PRESENT (the checker itself is guaranteed last by the plan) — missing means the result
-// is NOT final-run-capable and the preview says so loudly with the paste-ready candidate.
-export const buildMigrationPlan = (gates, kitToolsDir) => {
+// is NOT final-run-capable and the preview says so loudly with the paste-ready candidate. An
+// EXTERNAL-COPY core check withholds that claim too: the runner anchors on the installed copy.
+export const buildMigrationPlan = (gates, kitToolsDir, projectDir) => {
+  if (typeof projectDir !== 'string') {
+    throw stop('buildMigrationPlan needs the project root — a declared cmd may name a core check by a RELATIVE path, and only the project root resolves it the way the runner does');
+  }
+  const tools = coreCheckTools(kitToolsDir);
+  const claimOf = (name, cmd) => classifyCheckerClaim(tools[name], cmd, projectDir);
   const plan = [];
   const customized = [];
+  // EVERY canonical checker row, not just the last one seen: a duplicate is a real declaration
+  // state, and both the producer question and the final-capability claim have to see all of them.
+  const checkerRows = [];
+  // A core check declared through a DIFFERENT copy of the tool — the vendored deployment.
+  const externalCoreChecks = [];
   let unitTestsExtended = false;
-  let checkerRow = null;
   let hasReviewState = false;
   const coverageCmd = `node "${join(kitToolsDir, 'coverage-check.mjs')}" --check`;
   for (const gate of gates) {
@@ -172,19 +300,44 @@ export const buildMigrationPlan = (gates, kitToolsDir) => {
       plan.push({ action: 'remove', entry: gate, reason: `the ${legacy.name} check died with its tool (strip-the-kit)` });
       continue;
     }
-    if (isCanonicalCoreCheck('coverage-check', gate.cmd, kitToolsDir)) {
-      checkerRow = { action: 'keep', entry: gate, reason: null };
-      plan.push(checkerRow);
+    const coverageClaim = claimOf('coverage-check', gate.cmd);
+    if (coverageClaim === CHECKER_CLAIM.CANONICAL) {
+      const row = { action: 'keep', entry: gate, reason: null };
+      checkerRows.push(row);
+      plan.push(row);
       continue;
     }
-    if (isCanonicalCoreCheck('review-state', gate.cmd, kitToolsDir)) {
+    const reviewClaim = claimOf('review-state', gate.cmd);
+    if (reviewClaim === CHECKER_CLAIM.CANONICAL) {
       hasReviewState = true;
       plan.push({ action: 'keep', entry: gate, reason: null });
       continue;
     }
+    // The third outcome: this IS the tool, from a copy the caller did not name. A vendored
+    // deployment declared it deliberately, so it is PRESERVED as written — a plain keep row, never
+    // a new action kind (resultingGates carries only keep|extend|move|add and would silently drop
+    // one) — and it counts as DECLARED, which is what stops the checker being added on top of it
+    // and stops its id reading as a squatter. What it does not buy is the final-capability claim:
+    // run-gates --final anchors on the installed copy by realpath and would refuse this cmd.
+    const elsewhereName = coverageClaim === CHECKER_CLAIM.ELSEWHERE
+      ? 'coverage-check'
+      : reviewClaim === CHECKER_CLAIM.ELSEWHERE ? 'review-state' : null;
+    if (elsewhereName !== null) {
+      const row = { action: 'keep', entry: gate, reason: null };
+      externalCoreChecks.push({ name: elsewhereName, entry: gate, installed: join(kitToolsDir, `${elsewhereName}.mjs`), row });
+      plan.push(row);
+      continue;
+    }
     if (gate.id === 'unit-tests') {
-      if (gate.cmd.includes(UNIT_TESTS_COVERAGE_FLAGS)) {
-        plan.push({ action: 'keep', entry: gate, reason: null }); // already fully configured
+      // Already fully configured — decided by the CLOSED predicate, never a substring probe, and
+      // over ANY flag set the kit has emitted: a declaration written by an earlier kit stays a
+      // zero-diff keep (the constant moving must not re-read a working gate as customized), while a
+      // cmd that merely CONTAINS the bytes — `echo <flags>`, a `&& rm -f <lcov>` tail — is not a
+      // producer and must reach the CUSTOMIZED report with its recovery instead of a silent keep.
+      // A declared `lcovProducer` marker settles it the same way: the entry claims production, so
+      // there is nothing to extend and nothing to report as unverifiable.
+      if (isCoverageProducerGate(gate)) {
+        plan.push({ action: 'keep', entry: gate, reason: null });
         continue;
       }
       if (gate.cmd.startsWith(UNIT_TESTS_PREFIX) && !/--experimental-test-coverage|--test-reporter/.test(gate.cmd)) {
@@ -206,45 +359,94 @@ export const buildMigrationPlan = (gates, kitToolsDir) => {
     plan.push({ action: 'keep', entry: gate, reason: null });
   }
   const kept = plan.filter((r) => r.action === 'keep' || r.action === 'extend');
-  // The checker READS an lcov; something has to WRITE it. Adding the checker over a declaration
-  // with no producer creates the dead pair — the gate PASSES (`skipped-no-lcov`) and certifies
-  // nothing, so the migration withholds it and says why instead.
-  const hasProducer = kept.some((r) => matchesCoverageProducer(r.entry.cmd));
+  const checkerRow = checkerRows[checkerRows.length - 1] ?? null;
+  const externalCoverageChecks = externalCoreChecks.filter((c) => c.name === 'coverage-check');
+  // The checker READS an lcov; something has to WRITE it FIRST. Adding the checker over a
+  // declaration with no producer creates the dead pair — the gate PASSES (`skipped-no-lcov`) and
+  // certifies nothing, so the migration withholds it and says why instead.
+  // POSITIONAL, like every other producer question in the family: the checker always ends up LAST
+  // here (added last, or moved last), so the producers are exactly the rows that are not a checker.
+  // EVERY checker row is excluded, not merely the one that ends up last — a checker cannot produce
+  // the lcov it reads, so a marker on a DUPLICATE checker must not read as the producer for the
+  // other one; that pair would claim final-capability while nothing wrote the file. A VENDORED
+  // checker is excluded for the identical reason: which copy runs changes nothing about the fact
+  // that a checker consumes the lcov rather than writing it.
+  const consumerRows = new Set([...checkerRows, ...externalCoverageChecks.map((c) => c.row)]);
+  const isProducerRow = (row) => !consumerRows.has(row) && isCoverageProducerGate(row.entry);
+  const hasProducer = kept.some(isProducerRow);
   let collision = null;
   let checkerWithheld = false;
-  if (checkerRow === null) {
+  if (checkerRow !== null) {
+    if (kept[kept.length - 1] !== checkerRow) {
+      checkerRow.action = 'move';
+      checkerRow.reason = 'the canonical checker must be the LAST declared gate (nothing may run after it consumed the lcov)';
+    }
+  } else if (externalCoverageChecks.length > 0) {
+    // The checker IS declared, from another copy. Adding the canonical one beside it would create
+    // the very duplicate the collision STOP exists to prevent — and rewriting the row the
+    // deployment chose is not this tool's call. Nothing is added, nothing is moved, nothing
+    // collides; the verify warning below carries what the maintainer has to decide.
+  } else if (kept.some((r) => r.entry.id === 'coverage-check')) {
     // A surviving NON-canonical entry already holding the checker's id blocks the add — two
     // `coverage-check` rows would be ambiguous; the customized entry must be resolved by hand
     // FIRST (the caller turns this into a loud STOP on preview and apply alike).
-    if (kept.some((r) => r.entry.id === 'coverage-check')) {
-      collision = 'coverage-check';
-    } else if (!hasProducer) {
-      checkerWithheld = true;
-    } else {
-      plan.push({
-        action: 'add',
-        entry: { id: 'coverage-check', title: 'Changed-line coverage + red-proof verification (the final-run checker)', cmd: coverageCmd },
-        reason: 'run-gates --final requires the canonical checker as the LAST declared gate',
-      });
-    }
-  } else if (kept[kept.length - 1] !== checkerRow) {
-    checkerRow.action = 'move';
-    checkerRow.reason = 'the canonical checker must be the LAST declared gate (nothing may run after it consumed the lcov)';
+    collision = 'coverage-check';
+  } else if (!hasProducer) {
+    checkerWithheld = true;
+  } else {
+    plan.push({
+      action: 'add',
+      entry: { id: 'coverage-check', title: 'Changed-line coverage + red-proof verification (the final-run checker)', cmd: coverageCmd },
+      reason: 'run-gates --final requires the canonical checker as the LAST declared gate',
+    });
   }
   // An ALREADY-declared checker over no producer is the same dead pair the withhold prevents — an
   // earlier deployment could have created it. The migration removes no declared gate, so it reports
   // the inertness and refuses to call the result final-run-capable.
-  const checkerInert = checkerRow !== null && !hasProducer;
+  //
+  // The two checker kinds need DIFFERENT questions, and asking one question would be wrong for one
+  // of them. A canonical checker always ENDS UP LAST here — added last, or moved last — so "a
+  // producer exists at all" and "a producer runs before it" are the same fact. A VENDORED checker is
+  // deliberately left where the deployment put it, so for that row the question is POSITIONAL: a
+  // producer declared AFTER it writes the lcov the checker has already read past, and counting it
+  // would report a live pair over one that certifies nothing.
+  // Tracked PER ROW, not as one flag: the renderer has to name the edit for the row it is talking
+  // about, and a single boolean is what let one preview demand a removal and a reorder at once.
+  const inertExternalRows = new Set(
+    externalCoverageChecks.filter(({ row }) => !kept.slice(0, kept.indexOf(row)).some(isProducerRow)).map(({ row }) => row),
+  );
+  // The canonical checker's ONLY inert cause is that nothing produces at all — it always ends up
+  // last — so its sentence never has to speak about order.
+  const canonicalCheckerInert = checkerRow !== null && !hasProducer;
+  const checkerInert = canonicalCheckerInert || inertExternalRows.size > 0;
+  // `--final` accepts EXACTLY ONE canonical checker, so a declaration carrying two is not
+  // final-run-capable however healthy the rest of it looks. The migration removes no declared gate,
+  // so it names the duplication and withholds the claim instead of over-promising a green.
+  const duplicateCheckers = checkerRows.length;
   const reviewStateCandidate = `{ "id": "review-state", "title": "Review receipts converged (D3(b))", "cmd": "node \\"${join(kitToolsDir, 'review-state.mjs')}\\" --check" }`;
   return {
     plan,
     customized,
     unitTestsExtended,
-    finalCapable: hasReviewState && !checkerWithheld && !checkerInert,
+    finalCapable:
+      hasReviewState && !checkerWithheld && !checkerInert && duplicateCheckers <= 1 && externalCoreChecks.length === 0,
     hasProducer,
     hasReviewState,
     checkerWithheld,
     checkerInert,
+    duplicateCheckers,
+    // The plan ROW is an internal handle (the move arm mutates it) — consumers get the facts only.
+    // `canonicalTwin` decides the RECOVERY: with the installed copy already declared, "repoint this
+    // cmd" would leave two canonical checkers, which --final refuses — a recovery that cannot
+    // converge is worse than none.
+    externalCoreChecks: externalCoreChecks.map(({ name, entry, installed, row }) => ({
+      name,
+      entry,
+      installed,
+      canonicalTwin: name === 'coverage-check' ? checkerRows.length > 0 : hasReviewState,
+      inert: inertExternalRows.has(row),
+    })),
+    canonicalCheckerInert,
     reviewStateCandidate,
     collision,
   };
@@ -265,7 +467,7 @@ const customizedRecovery = (gate) =>
     ? `declare the canonical suite gate by hand so the coverage contract is verifiable: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`
     : 'remove the entry, or repoint it at a living check — the review-ledger / fold-completeness tools no longer exist.';
 
-const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable, checkerWithheld = false, checkerInert = false, reviewStateCandidate }) => {
+const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable, hasProducer = false, checkerWithheld = false, canonicalCheckerInert = false, duplicateCheckers = 0, externalCoreChecks = [], reviewStateCandidate }) => {
   const lines = [];
   for (const gate of customized) {
     lines.push(`  CUSTOMIZED (untouched): ${gate.id}: ${gate.cmd}`);
@@ -274,15 +476,48 @@ const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable,
   if (customized.length) {
     lines.push('  IMPORTANT: do NOT install the commit guard until every customized entry above is resolved — a declaration that cannot pass run-gates --final would block every commit.');
   }
+  for (const { name, entry, installed, canonicalTwin = false, inert = false } of externalCoreChecks) {
+    lines.push(`  VERIFY (preserved exactly as declared): ${entry.id}: ${entry.cmd}`);
+    lines.push(
+      `    this IS the ${name} check by invocation shape, but it resolves to a DIFFERENT copy of the tool than --kit-tools names (${installed}) — a vendored deployment. Nothing was added over it and nothing was rewritten.`,
+    );
+    lines.push(
+      canonicalTwin
+        ? `    the INSTALLED ${name} check is declared here too, so repointing this cmd would leave TWO — run-gates --final accepts exactly ONE canonical check. Remove THIS entry by hand and keep the canonical one.`
+        : `    run-gates --final anchors on the installed copy by realpath, so the result is NOT final-run-capable while this entry stands: either repoint the cmd at ${installed}, or upgrade through the kit that owns the copy it names.`,
+    );
+    // The inertness of THIS row, said on THIS row, with exactly one edit attached — and when the
+    // entry is already destined for removal, no second edit at all.
+    if (inert && canonicalTwin) {
+      lines.push('    it is also INERT as declared — nothing produces the lcov before it — and removing it, as above, is the ONE edit that resolves both.');
+    } else if (inert && hasProducer) {
+      lines.push('    it is also INERT as declared: a gate DOES produce the lcov, but it runs AFTER this entry, so this checker reads nothing (or stale bytes) and passes while verifying nothing — a checker belongs LAST, after its producer.');
+    } else if (inert) {
+      lines.push(`    it is also INERT as declared: no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing — declare the suite gate: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+    }
+  }
+  if (externalCoreChecks.length) {
+    // The same consequence the customized block carries, for the same reason: a declaration --final
+    // refuses mints no receipt, and the commit guard then refuses every commit.
+    lines.push('  IMPORTANT: do NOT install the commit guard while the entr(ies) above stand — a declaration that cannot pass run-gates --final would block every commit.');
+  }
   if (checkerWithheld) {
     lines.push('  WARNING: the canonical coverage-check gate was NOT added — no declared gate would PRODUCE the lcov it reads, and a checker with no producer passes while verifying nothing. Declare the suite gate first, then re-run this migration:');
     lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
   }
-  if (checkerInert) {
+  // The CANONICAL checker's inertness only. An external row's is said on the row itself above, with
+  // the edit that fits that row — this block would otherwise add a second, contradictory one.
+  if (canonicalCheckerInert) {
     lines.push('  WARNING: the DECLARED coverage-check gate is INERT — no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing. Nothing is removed for you; declare the suite gate:');
     lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
   }
-  if (!hasReviewState) {
+  if (duplicateCheckers > 1) {
+    lines.push(`  WARNING: ${duplicateCheckers} declared gates are the canonical coverage checker — run-gates --final accepts EXACTLY ONE, so the result is NOT final-run-capable. Nothing is removed for you; keep a single checker and delete the rest by hand.`);
+  }
+  // A review-state declared through an external copy already has its VERIFY row above, naming the
+  // same missing capability with the RIGHT remedy — telling the maintainer to "add it" on top of an
+  // entry that is already there would advise a duplicate.
+  if (!hasReviewState && !externalCoreChecks.some((c) => c.name === 'review-state')) {
     lines.push('  WARNING: the result is NOT final-run-capable — no canonical review-state check is declared. Add it (paste-ready), then run-gates --final can mint the receipt:');
     lines.push(`    ${reviewStateCandidate}`);
   }
@@ -441,7 +676,7 @@ export const main = (argv = process.argv.slice(2), io = {}) => {
       return 0;
     }
     const parsed = declaration.outcome === 'loaded' ? declaration.parsed : { gates: [] };
-    const analysis = { ...buildMigrationPlan(parsed.gates, kitTools), retiredStores };
+    const analysis = { ...buildMigrationPlan(parsed.gates, kitTools, resolve(args.cwd)), retiredStores };
     if (analysis.collision) {
       throw stop(
         `id collision — a NON-canonical entry already uses id "${analysis.collision}"; resolve it by hand first ` +

package/references/scripts/migrate-gates.test.mjs

@@ -12,6 +12,7 @@ import { spawnSync } from 'node:child_process';
 import {
   LEGACY_FORMS,
   UNIT_TESTS_COVERAGE_FLAGS,
+  KNOWN_COVERAGE_FLAG_SETS,
   COVERAGE_PRODUCER_BODY,
   RETIRED_STORE_BASENAMES,
   findRetiredStores,
@@ -21,8 +22,17 @@ import {
   main,
 } from './migrate-gates.mjs';
 
+// An INSTALLED kit tools dir carries both core checks as real files. That is a fixture
+// requirement, not decoration: canonicity is a realpath anchor, so a core check whose file is not
+// there resolves to nothing and is no claim at all — the same fail-closed answer run-gates gives.
 const KIT_TOOLS = mkdtempSync(join(tmpdir(), 'migrate-gates-kit-'));
 writeFileSync(join(KIT_TOOLS, 'coverage-check.mjs'), '// the installed checker the migration points at\n');
+writeFileSync(join(KIT_TOOLS, 'review-state.mjs'), '// the installed review-state check\n');
+// The project root the plan builder resolves declared RELATIVE tokens against — the same anchor
+// run-gates uses. Empty on purpose for the pure-plan cases: a relative lookalike resolves to
+// nothing there, which is exactly the "no claim can be made" outcome those rows assert. The
+// vendored rows below build their own project and pass it explicitly.
+const PROJECT = mkdtempSync(join(tmpdir(), 'migrate-gates-project-'));
 
 const mkProject = (gates) => {
   const root = mkdtempSync(join(tmpdir(), 'migrate-gates-'));
@@ -37,6 +47,21 @@ const quiet = () => {
   return { log: (l) => out.push(String(l)), error: (l) => err.push(String(l)), out, err };
 };
 
+// The FIRST flag set the kit ever emitted, frozen here as literal bytes — never read back out of
+// KNOWN_COVERAGE_FLAG_SETS. Deployed declarations on disk carry exactly these bytes, so the
+// append-only promise needs a checker that goes red if they are edited or dropped; deriving the
+// "prior" from the set under test would keep this green while real deployments broke.
+const PRIOR_FLAG_SET_V1 =
+  '--experimental-test-coverage --test-reporter=lcov --test-reporter-destination="$AW_GIT_DIR/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout';
+
+// A VENDORED deployment: the SAME tools, from a copy `--kit-tools` does not name. Recognition is a
+// realpath anchor, so these are real files — a fake path would be the unresolvable case instead.
+const VENDORED_TOOLS = mkdtempSync(join(tmpdir(), 'migrate-gates-vendored-'));
+writeFileSync(join(VENDORED_TOOLS, 'coverage-check.mjs'), '// a vendored copy of the checker\n');
+writeFileSync(join(VENDORED_TOOLS, 'review-state.mjs'), '// a vendored copy of the review-state check\n');
+const vendoredCmd = (name) => `node "${join(VENDORED_TOOLS, `${name}.mjs`)}" --check`;
+const installedCmd = (name) => `node "${join(KIT_TOOLS, `${name}.mjs`)}" --check`;
+
 const LEGACY_LEDGER = { id: 'review-ledger', title: 'L', cmd: 'node "/kit/tools/review-ledger.mjs" --check' };
 const LEGACY_FOLD = { id: 'fold-completeness', title: 'F', cmd: 'node /kit/tools/fold-completeness.mjs --check' };
 const UNIT = { id: 'unit-tests', title: 'U', cmd: 'node --test tools/*.test.mjs' };
@@ -45,12 +70,12 @@ const CUSTOM = { id: 'my-ledger-wrap', title: 'C', cmd: 'node scripts/wrap.mjs &
 describe('migrate-gates — the pure migration plan', () => {
   it('matches BOTH documented legacy forms (quoted and bare paths) and removes them', () => {
     for (const form of LEGACY_FORMS) assert.ok(form.re instanceof RegExp);
-    const { plan } = buildMigrationPlan([LEGACY_LEDGER, LEGACY_FOLD], KIT_TOOLS);
+    const { plan } = buildMigrationPlan([LEGACY_LEDGER, LEGACY_FOLD], KIT_TOOLS, PROJECT);
     assert.deepEqual(plan.filter((r) => r.action === 'remove').map((r) => r.entry.id), ['review-ledger', 'fold-completeness']);
   });
 
   it('extends the canonical unit-tests cmd with the lcov reporters (flags inserted after `node --test`)', () => {
-    const { plan, unitTestsExtended } = buildMigrationPlan([UNIT], KIT_TOOLS);
+    const { plan, unitTestsExtended } = buildMigrationPlan([UNIT], KIT_TOOLS, PROJECT);
     assert.ok(unitTestsExtended);
     const extended = plan.find((r) => r.action === 'extend').entry;
     assert.equal(extended.cmd, `node --test ${UNIT_TESTS_COVERAGE_FLAGS} tools/*.test.mjs`);
@@ -58,23 +83,60 @@ describe('migrate-gates — the pure migration plan', () => {
 
   it('an already-extended unit-tests cmd is left alone (idempotent)', () => {
     const done = { id: 'unit-tests', title: 'U', cmd: `node --test ${UNIT_TESTS_COVERAGE_FLAGS} tools/*.test.mjs` };
-    const { plan } = buildMigrationPlan([done], KIT_TOOLS);
+    const { plan } = buildMigrationPlan([done], KIT_TOOLS, PROJECT);
     assert.equal(plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
   });
 
+  it('a declaration carrying a PRIOR emitted flag set reads as already-configured — keep, zero diff, no warning', () => {
+    // The canonical flag set moved (the destination became a required-parameter expansion). A
+    // deployment written by the earlier kit must not suddenly read as customized: that would send
+    // the maintainer to hand-fix a gate which already produces the lcov the checker reads.
+    assert.notEqual(PRIOR_FLAG_SET_V1, UNIT_TESTS_COVERAGE_FLAGS, 'the v1 bytes are a form the kit no longer emits');
+    assert.ok(KNOWN_COVERAGE_FLAG_SETS.includes(PRIOR_FLAG_SET_V1), 'and the append-only set still carries them');
+    const deployed = [
+      { id: 'unit-tests', title: 'U', cmd: `node --test ${PRIOR_FLAG_SET_V1} tools/*.test.mjs` },
+      { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` },
+      { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check` },
+    ];
+    const analysis = buildMigrationPlan(deployed, KIT_TOOLS, PROJECT);
+    assert.equal(analysis.plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
+    assert.deepEqual(analysis.customized, [], 'a prior emitted form is never reported customized');
+    assert.equal(analysis.hasProducer, true, 'it still counts as the producer the checker reads');
+    assert.equal(analysis.checkerInert, false);
+    assert.equal(analysis.finalCapable, true);
+    assert.deepEqual(resultingGates(analysis.plan), deployed, 'zero diff — nothing is rewritten');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /nothing to migrate/, 'the preview says there is nothing to do');
+    assert.doesNotMatch(preview, /CUSTOMIZED|INERT|WARNING/, 'and warns about nothing');
+  });
+
+  it('a unit-tests entry that merely CONTAINS the prior bytes is CUSTOMIZED, never a silent keep', () => {
+    // The already-configured decision runs through the closed producer predicate. A substring probe
+    // would call `echo <prior flags>` already configured and say nothing, leaving the maintainer
+    // with an entry the tool cannot verify and no recovery line.
+    const nearMiss = { id: 'unit-tests', title: 'U', cmd: `echo ${PRIOR_FLAG_SET_V1}` };
+    const analysis = buildMigrationPlan([nearMiss], KIT_TOOLS, PROJECT);
+    assert.equal(analysis.plan.find((r) => r.entry.id === 'unit-tests').action, 'keep', 'nothing is rewritten');
+    assert.deepEqual(analysis.customized.map((g) => g.id), ['unit-tests'], 'but it IS reported customized');
+    assert.equal(analysis.hasProducer, false, 'and it never counts as the producer the checker would read');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /CUSTOMIZED \(untouched\): unit-tests/);
+    assert.match(preview, /declare the canonical suite gate by hand/, 'the paste-ready recovery rides along');
+  });
+
   it('adds the coverage-check gate LAST with the RESOLVED quoted path; never a second one', () => {
-    const { plan } = buildMigrationPlan([UNIT], KIT_TOOLS);
+    const { plan } = buildMigrationPlan([UNIT], KIT_TOOLS, PROJECT);
     const result = resultingGates(plan);
     const last = result[result.length - 1];
     assert.equal(last.id, 'coverage-check');
     assert.equal(last.cmd, `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check`);
-    const again = buildMigrationPlan(result, KIT_TOOLS);
+    const again = buildMigrationPlan(result, KIT_TOOLS, PROJECT);
     assert.ok(!again.plan.some((r) => r.action === 'add'), 'a declaration already carrying the checker gains no duplicate');
   });
 
   it('a declaration with NO producer never GAINS the checker — the pair is declared together or not at all', () => {
     const npmSuite = { id: 'suite', title: 'S', cmd: 'npm test' };
-    const analysis = buildMigrationPlan([LEGACY_LEDGER, npmSuite], KIT_TOOLS);
+    const analysis = buildMigrationPlan([LEGACY_LEDGER, npmSuite], KIT_TOOLS, PROJECT);
     assert.ok(!analysis.plan.some((r) => r.action === 'add'), 'no checker is added over a declaration that produces no lcov');
     assert.deepEqual(resultingGates(analysis.plan).map((g) => g.id), ['suite'], 'the legacy entry still goes, nothing dead arrives');
     assert.equal(analysis.finalCapable, false, 'a declaration with no checker is not final-run-capable');
@@ -86,7 +148,7 @@ describe('migrate-gates — the pure migration plan', () => {
   it('an ALREADY-declared checker over no producer is reported INERT, is never removed, and is not final-run-capable', () => {
     const checker = { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check` };
     const reviewState = { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` };
-    const analysis = buildMigrationPlan([{ id: 'suite', title: 'S', cmd: 'npm test' }, reviewState, checker], KIT_TOOLS);
+    const analysis = buildMigrationPlan([{ id: 'suite', title: 'S', cmd: 'npm test' }, reviewState, checker], KIT_TOOLS, PROJECT);
     assert.equal(analysis.finalCapable, false, 'a review-state present must NOT make an inert pair read as final-run-capable');
     assert.ok(resultingGates(analysis.plan).some((g) => g.id === 'coverage-check'), 'the declared checker is never removed');
     const preview = formatPreview(analysis, 'APPLY');
@@ -101,7 +163,7 @@ describe('migrate-gates — the pure migration plan', () => {
       title: 'T',
       cmd: `COREPACK_ENABLE_NETWORK=0 npm exec --offline --script-shell /bin/sh -- ${COVERAGE_PRODUCER_BODY}`,
     };
-    const analysis = buildMigrationPlan([offered], KIT_TOOLS);
+    const analysis = buildMigrationPlan([offered], KIT_TOOLS, PROJECT);
     assert.deepEqual(resultingGates(analysis.plan).map((g) => g.id), ['test', 'coverage-check']);
     // The `no canonical unit-tests entry` advice is keyed on the ID, but a producer is recognized
     // under ANY id — repeating the advice over a working producer sends the user to fix nothing.
@@ -109,7 +171,7 @@ describe('migrate-gates — the pure migration plan', () => {
   });
 
   it('a CUSTOMIZED dead-tool reference (compound form) is kept untouched and reported', () => {
-    const analysis = buildMigrationPlan([CUSTOM], KIT_TOOLS);
+    const analysis = buildMigrationPlan([CUSTOM], KIT_TOOLS, PROJECT);
     assert.equal(analysis.plan.find((r) => r.entry.id === 'my-ledger-wrap').action, 'keep');
     assert.deepEqual(analysis.customized.map((g) => g.id), ['my-ledger-wrap']);
     const preview = formatPreview(analysis, 'APPLY');
@@ -121,7 +183,7 @@ describe('migrate-gates — the pure migration plan', () => {
 describe('migrate-gates — the canonical anchor + final-capability validation (round-1 folds)', () => {
   it('a canonical checker NOT in the last position is MOVED last (never left mid-list)', () => {
     const canonical = { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check` };
-    const { plan } = buildMigrationPlan([canonical, UNIT], KIT_TOOLS);
+    const { plan } = buildMigrationPlan([canonical, UNIT], KIT_TOOLS, PROJECT);
     const result = resultingGates(plan);
     assert.equal(result[result.length - 1].id, 'coverage-check', 'the canonical checker ends up LAST');
     assert.ok(plan.some((r) => r.action === 'move' && r.entry.id === 'coverage-check'), 'the reorder is an explicit move action');
@@ -130,14 +192,14 @@ describe('migrate-gates — the canonical anchor + final-capability validation (
 
   it('a LOOKALIKE checker cmd is CUSTOMIZED (never counted canonical) and the canonical one is still added', () => {
     const lookalike = { id: 'cov', title: 'C', cmd: 'node scripts/coverage-check.mjs --check' };
-    const analysis = buildMigrationPlan([lookalike, UNIT], KIT_TOOLS);
+    const analysis = buildMigrationPlan([lookalike, UNIT], KIT_TOOLS, PROJECT);
     assert.ok(analysis.customized.some((g) => g.id === 'cov'), 'the lookalike is reported customized');
     const result = resultingGates(analysis.plan);
     assert.equal(result[result.length - 1].id, 'coverage-check', 'the REAL canonical checker is added last');
   });
 
   it('the result is judged final-capable ONLY with a canonical review-state present; missing → a LOUD warning with the candidate line, never "final-run-capable"', () => {
-    const analysis = buildMigrationPlan([UNIT], KIT_TOOLS);
+    const analysis = buildMigrationPlan([UNIT], KIT_TOOLS, PROJECT);
     assert.equal(analysis.finalCapable, false, 'no review-state → not final-capable');
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /review-state/, 'the warning names the missing core check');
@@ -146,13 +208,14 @@ describe('migrate-gates — the canonical anchor + final-capability validation (
     const withRs = buildMigrationPlan(
       [UNIT, { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` }],
       KIT_TOOLS,
+      PROJECT,
     );
     assert.equal(withRs.finalCapable, true);
   });
 
   it('a NON-canonical unit-tests cmd (npm test / wrapper) is CUSTOMIZED with the full flag set as the recovery', () => {
     const npmTest = { id: 'unit-tests', title: 'U', cmd: 'npm test' };
-    const analysis = buildMigrationPlan([npmTest], KIT_TOOLS);
+    const analysis = buildMigrationPlan([npmTest], KIT_TOOLS, PROJECT);
     assert.equal(analysis.plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
     assert.ok(analysis.customized.some((g) => g.id === 'unit-tests'), 'a non-canonical suite cmd is customized');
     const preview = formatPreview(analysis, 'APPLY');
@@ -161,7 +224,7 @@ describe('migrate-gates — the canonical anchor + final-capability validation (
 
   it('a PARTIALLY-flagged unit-tests cmd is CUSTOMIZED (a lone coverage flag never reads as configured)', () => {
     const partial = { id: 'unit-tests', title: 'U', cmd: 'node --test --experimental-test-coverage tools/*.test.mjs' };
-    const analysis = buildMigrationPlan([partial], KIT_TOOLS);
+    const analysis = buildMigrationPlan([partial], KIT_TOOLS, PROJECT);
     assert.equal(analysis.plan.find((r) => r.entry.id === 'unit-tests').action, 'keep');
     assert.ok(analysis.customized.some((g) => g.id === 'unit-tests'), 'the half-wired cmd is customized, never silently left');
   });
@@ -203,6 +266,135 @@ describe('migrate-gates — the canonical anchor + final-capability validation (
   });
 });
 
+describe('migrate-gates — a VENDORED core check is the tool, from a copy --kit-tools does not name (D6)', () => {
+  const UNIT_DONE = { id: 'unit-tests', title: 'U', cmd: `${COVERAGE_PRODUCER_BODY} tools/*.test.mjs` };
+  const INSTALLED_REVIEW_STATE = { id: 'review-state', title: 'RS', cmd: installedCmd('review-state') };
+
+  it('a vendored coverage-check is PRESERVED exactly as declared — declared, never added over, never a collision', () => {
+    // Before the split this entry was a LOOKALIKE holding the checker's id, which made the whole
+    // upgrade a hard STOP: every preview and every apply over a vendored deployment failed.
+    const vendored = { id: 'coverage-check', title: 'CC', cmd: vendoredCmd('coverage-check') };
+    const declaration = [UNIT_DONE, INSTALLED_REVIEW_STATE, vendored];
+    const analysis = buildMigrationPlan(declaration, KIT_TOOLS, PROJECT);
+    assert.equal(analysis.collision, null, 'a vendored copy carries the tool\'s own id legitimately — it is no squatter');
+    assert.ok(!analysis.plan.some((r) => r.action === 'add'), 'the checker IS declared, so a second one is never added');
+    assert.deepEqual(analysis.plan.map((r) => r.action), ['keep', 'keep', 'keep'], 'nothing is rewritten or reordered');
+    assert.deepEqual(resultingGates(analysis.plan), declaration, 'the declaration comes out byte-for-byte as it went in');
+    assert.deepEqual(analysis.externalCoreChecks.map((c) => c.name), ['coverage-check']);
+    assert.deepEqual(analysis.customized, [], 'a real copy of the tool is not an entry the tool cannot verify');
+    assert.equal(analysis.finalCapable, false, '--final anchors on the INSTALLED copy, so the capability claim is withheld');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /VERIFY \(preserved exactly as declared\): coverage-check/, 'the outcome is NAMED');
+    assert.match(preview, /DIFFERENT copy of the tool/, 'and says what it actually found');
+    assert.match(preview, /NOT final-run-capable/);
+    assert.doesNotMatch(preview, /already final-run-capable/);
+  });
+
+  it('a vendored review-state is preserved too — and is never advised to "add it" on top of itself', () => {
+    const vendored = { id: 'review-state', title: 'RS', cmd: vendoredCmd('review-state') };
+    const analysis = buildMigrationPlan([UNIT_DONE, vendored], KIT_TOOLS, PROJECT);
+    assert.deepEqual(analysis.externalCoreChecks.map((c) => c.name), ['review-state']);
+    assert.equal(analysis.hasReviewState, false, 'the INSTALLED review-state is still not declared');
+    assert.equal(analysis.finalCapable, false);
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /VERIFY \(preserved exactly as declared\): review-state/);
+    assert.doesNotMatch(preview, /Add it \(paste-ready\)/, 'a second review-state entry is the ambiguity, not the remedy');
+  });
+
+  it('a core check naming a path nothing resolves is NO claim — fail-closed exactly where --final is', () => {
+    // A lexical path compare called this canonical: the file need not exist to compare equal after
+    // resolve(). The migration then promised final-run-capability over a cmd --final cannot run.
+    const ghost = { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'nowhere', 'review-state.mjs')}" --check` };
+    const analysis = buildMigrationPlan([UNIT_DONE, ghost], KIT_TOOLS, PROJECT);
+    assert.equal(analysis.hasReviewState, false, 'an unresolvable path is never the installed tool');
+    assert.deepEqual(analysis.externalCoreChecks, [], 'nor evidence that the tool lives somewhere else');
+    assert.ok(analysis.customized.some((g) => g.id === 'review-state'), 'it is reported as an entry the tool cannot verify');
+    assert.equal(analysis.finalCapable, false);
+  });
+
+  it('a vendored checker never produces the lcov it reads — the declared pair stays INERT', () => {
+    const vendored = { id: 'coverage-check', title: 'CC', cmd: vendoredCmd('coverage-check'), lcovProducer: true };
+    const analysis = buildMigrationPlan(
+      [{ id: 'lint', title: 'L', cmd: 'eslint .' }, INSTALLED_REVIEW_STATE, vendored],
+      KIT_TOOLS,
+      PROJECT,
+    );
+    assert.equal(analysis.hasProducer, false, 'a marker on the checker itself never self-pairs, whichever copy it is');
+    assert.equal(analysis.checkerInert, true, 'a checker over nothing that writes the lcov passes verifying nothing');
+    assert.match(formatPreview(analysis, 'APPLY'), /INERT/);
+  });
+
+  it('producer-after-vendored-checker: a producer declared AFTER a vendored checker never covers it', () => {
+    // A canonical checker is always MOVED last, so "a producer exists" answers "a producer runs
+    // first" for it. A vendored checker is left where the deployment put it, so the position-blind
+    // answer reported a live pair over a checker that reads the lcov before anything writes one.
+    const vendored = { id: 'coverage-check', title: 'CC', cmd: vendoredCmd('coverage-check') };
+    const after = buildMigrationPlan([INSTALLED_REVIEW_STATE, vendored, UNIT_DONE], KIT_TOOLS, PROJECT);
+    assert.equal(after.hasProducer, true, 'a producer IS declared somewhere');
+    assert.equal(after.checkerInert, true, 'but not before the checker that reads what it writes');
+    assert.equal(after.finalCapable, false);
+    assert.match(formatPreview(after, 'APPLY'), /INERT/);
+
+    const before = buildMigrationPlan([UNIT_DONE, INSTALLED_REVIEW_STATE, vendored], KIT_TOOLS, PROJECT);
+    assert.equal(before.checkerInert, false, 'the same entries in producer-first order are a live pair');
+    assert.doesNotMatch(formatPreview(before, 'APPLY'), /INERT/);
+  });
+
+  it('the INERT warning names the edit the reader must actually make — order, not a missing gate', () => {
+    // The two ways to be inert need two sentences. Telling someone whose suite gate is already
+    // declared to declare it again sends them to fix nothing while the real defect stays.
+    const vendored = { id: 'coverage-check', title: 'CC', cmd: vendoredCmd('coverage-check') };
+    const misordered = formatPreview(buildMigrationPlan([INSTALLED_REVIEW_STATE, vendored, UNIT_DONE], KIT_TOOLS, PROJECT), 'APPLY');
+    assert.match(misordered, /runs AFTER this entry/, 'the ORDER is named as the defect, on the row it belongs to');
+    assert.match(misordered, /a checker belongs LAST, after its producer/, 'and the remedy is the reorder');
+    assert.doesNotMatch(misordered, /declare the suite gate/, 'never advise declaring a gate that is already there');
+
+    const absent = formatPreview(buildMigrationPlan([INSTALLED_REVIEW_STATE, vendored], KIT_TOOLS, PROJECT), 'APPLY');
+    assert.match(absent, /no declared gate PRODUCES the lcov/, 'with nothing producing, the old sentence still holds');
+    assert.match(absent, /declare the suite gate/);
+  });
+
+  it('a mixed declaration renders ONE edit, never a removal and a reorder at once', () => {
+    // The two folds met here: canonicalTwin asks for a removal, the inert arm asked for a reorder,
+    // and a preview carrying both leaves the reader with no unambiguous next step.
+    const canonical = { id: 'coverage-check', title: 'CC', cmd: installedCmd('coverage-check') };
+    const vendored = { id: 'coverage-check-vendor', title: 'CCV', cmd: vendoredCmd('coverage-check') };
+    const analysis = buildMigrationPlan([INSTALLED_REVIEW_STATE, vendored, UNIT_DONE, canonical], KIT_TOOLS, PROJECT);
+    assert.deepEqual(analysis.externalCoreChecks.map((c) => [c.canonicalTwin, c.inert]), [[true, true]]);
+    assert.equal(analysis.canonicalCheckerInert, false, 'the canonical checker ends up last, after the producer');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /Remove THIS entry by hand/);
+    assert.match(preview, /the ONE edit that resolves both/);
+    assert.doesNotMatch(preview, /belongs LAST, after its producer/, 'no second, contradictory edit');
+    assert.doesNotMatch(preview, /declare the suite gate/);
+  });
+
+  it('a canonical checker declared BESIDE the vendored one changes the recovery — remove, never repoint', () => {
+    // Repointing the vendored cmd at the installed copy would leave TWO canonical checkers, and
+    // --final accepts exactly one; a recovery that cannot converge is worse than none.
+    const canonical = { id: 'coverage-check', title: 'CC', cmd: installedCmd('coverage-check') };
+    const vendored = { id: 'coverage-check-vendor', title: 'CCV', cmd: vendoredCmd('coverage-check') };
+    const analysis = buildMigrationPlan([UNIT_DONE, INSTALLED_REVIEW_STATE, vendored, canonical], KIT_TOOLS, PROJECT);
+    assert.deepEqual(analysis.externalCoreChecks.map((c) => c.canonicalTwin), [true]);
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /accepts exactly ONE canonical check/);
+    assert.match(preview, /Remove THIS entry by hand/);
+    assert.doesNotMatch(preview, /either repoint the cmd/, 'the non-convergent recovery is not offered here');
+  });
+
+  it('a vendored deployment carries the SAME commit-guard consequence a customized one does', () => {
+    // Both end in a declaration --final refuses, which mints no receipt, which makes the guard
+    // refuse every commit. Naming the consequence for one and not the other is a false asymmetry.
+    const vendored = { id: 'coverage-check', title: 'CC', cmd: vendoredCmd('coverage-check') };
+    const preview = formatPreview(buildMigrationPlan([UNIT_DONE, INSTALLED_REVIEW_STATE, vendored], KIT_TOOLS, PROJECT), 'APPLY');
+    assert.match(preview, /do NOT install the commit guard/);
+  });
+
+  it('the plan builder REFUSES without the project root — a relative cmd cannot be resolved without it', () => {
+    assert.throws(() => buildMigrationPlan([UNIT_DONE], KIT_TOOLS), /project root/);
+  });
+});
+
 describe('migrate-gates — preview writes NOTHING; apply is atomic and complete', () => {
   it('the dry-run default leaves gates.json byte-identical and prints the plan + the apply hint', () => {
     const root = mkProject([LEGACY_LEDGER, UNIT]);

package/references/templates/gates.json

@@ -1,4 +1,4 @@
 {
-  "_README": "Per-project gate declaration: the ordered list of verification commands (tests, validators, scanners, docs checks) that must be green before a commit. Run them all in one batch with the family gate runner (the composition root's `gates` command); re-run one with `--only <id>`. Each entry is { id, title, cmd }: `id` = a unique kebab-case handle, `title` = a short human label, `cmd` = ONE bash command line — gates are spawned via bash (brace/glob expansion works; a host without bash gets a loud preflight error, never a silent reinterpretation under another shell). This file declares WHAT to check, never who executes it — the schema has no lane/model/routing fields and rejects unknown keys loudly. Trust posture: the runner executes this project's OWN declared commands with the caller's privileges — a batching convenience over commands the project already runs by hand, not a sandbox. Strict JSON — no comments.",
+  "_README": "Per-project gate declaration: the ordered list of verification commands (tests, validators, scanners, docs checks) that must be green before a commit. Run them all in one batch with the family gate runner (the composition root's `gates` command); re-run one with `--only <id>`. Each entry is { id, title, cmd } plus ONE optional key: `id` = a unique kebab-case handle, `title` = a short human label, `cmd` = ONE bash command line — gates are spawned via bash (brace/glob expansion works; a host without bash gets a loud preflight error, never a silent reinterpretation under another shell) — and `lcovProducer` (boolean, optional) DECLARES that this gate writes the lcov the coverage checker reads, for a suite the kit's closed `node --test` recognition cannot read on its own. Only the literal true claims it, and it widens what the declaration may CLAIM, never what a run CERTIFIES: a marked gate that produces no lcov still ends `skipped-no-lcov` at run time. This file declares WHAT to check, never who executes it — the schema has no lane/model/routing fields and rejects unknown keys loudly. Trust posture: the runner executes this project's OWN declared commands with the caller's privileges — a batching convenience over commands the project already runs by hand, not a sandbox. Strict JSON — no comments.",
   "gates": []
 }