@sabaiway/agent-workflow-kit 5.5.0 → 5.7.0

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/shared/deploy-tail.md

@@ -12,7 +12,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
 - **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](${CLAUDE_SKILL_DIR}/references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
-- **Never leak kit internals to the user.** No ADR ids, tool / function / operation names (`reconcile`, `inject`, `ensureSlot`), marker / slot / fragment / anchor terminology, or verbatim tool stderr in anything the user reads. Translate every tool outcome into plain language a third-party user — who has never read this `SKILL.md` — can understand and act on (e.g. the cap-refusal report in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3).
+- **Never leak kit internals to the user — and a tool-COMPOSED user-facing line holds the same bar at the source.** No ADR ids, tool / function / operation names (`reconcile`, `inject`, `ensureSlot`), marker / slot / fragment / anchor terminology, or verbatim tool stderr **inside the human sentence** of anything the user reads. Translate every tool outcome into plain language a third-party user — who has never read this `SKILL.md` — can understand and act on (e.g. the cap-refusal report in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3). The composed lines themselves are **user-grade** language: machine tokens and tool self-labels belong to the **machine-line channel** — the `[run-gates] status=…` grammar (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`), a line's leading self-label/prefix, or a runnable command/path the user can act on — never mid-sentence; alarm words (`PARTIALLY`, `incomplete`, `failed`, `broken`, `persists`) render only in outcomes gated on a **detected abnormal condition**. ONE designed exception, stated not implied: the configuration ensures' LEADING outcome token — one closed-vocabulary token, a failure's closed cause word opening its detail line — is that contract's own machine slot, not a leak. The **verbatim**-paste contract stays: the agent pastes tool-composed outcome lines as written and never re-composes their facts — the lines are user-grade at the source, so pasting them verbatim IS the plain language.
 - **Uninstall never deletes user-authored content, and dry-runs first.** `/agent-workflow-kit uninstall` removes only what is **provably ours** (a managed skill dir / wrapper symlink / fenced block / marker hook) and **prints — never runs** the `rm` / `git rm --cached` for `docs/ai` and the entry-point docs, and an **edit** instruction (not an `rm`) for `.claude/settings.json`. Always run `--dry-run` first, show the plan, get consent, then `--yes`. A skill dir or symlink that is not provably ours is a STOP, never a clobber (the `setup` posture, inverted). Removing a shared global (memory/engine/a bridge) may affect another project — say so.
 
 ---

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": []
 }

package/tools/ack-write.mjs

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
 // ack-write.mjs — the consent-gated writer for the family-owned neutral ack store
-// (docs/ai/acks.json, AD-055 Part I). The upgrade Recommendations `sandbox-lane` item renders THIS
-// tool's PREVIEW one-liner; the preview prints the exact `--apply` command; the agent runs `--apply`
-// only after the mode doc's §3 informed-consent confirmation. It records a NEUTRAL recipe fingerprint
-// acknowledgement — never a security key; the kit never writes sandbox network/filesystem allowances.
+// (docs/ai/acks.json, AD-055 Part I). An upgrade Recommendations item whose state can only be
+// ANSWERED renders THIS tool's PREVIEW one-liner; the preview prints the exact `--apply` command;
+// the agent runs `--apply` only after the mode doc's §3 informed-consent confirmation. It records a
+// NEUTRAL fingerprint acknowledgement — never a security key; the kit never writes sandbox
+// network/filesystem allowances.
+//
+// The wording is per-LANE or genuinely neutral, never "recipe": the sandbox lane acknowledges a
+// session-sandbox recipe, but the coverage-domain lane acknowledges a census FACT and the
+// source-size-copy lane a set of declared tool claims. One lane's noun stated over all of them was
+// simply false about the others.
 //
 // Family writer discipline (velocity / orchestration-write / gate-hook), verbatim:
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
@@ -34,8 +40,9 @@ const EXIT_OK = 0;
 const EXIT_PRECONDITION = 1;
 const EXIT_USAGE = 2;
 const JSON_INDENT = 2;
-// The recipeFingerprint shape (recommendations.mjs: sha256 hex sliced to 16) — a fail-closed guard so
-// the store never records a malformed or injected value.
+// The shape every advisor fingerprint carries (recommendations.mjs: sha256 hex sliced to 16, whether
+// minted over a recipe or over a canonical fact string) — a fail-closed guard so the store never
+// records a malformed or injected value.
 export const FINGERPRINT_PATTERN = /^[0-9a-f]{16}$/u;
 // The lane this writer records when none is named — the original single-lane contract, so every
 // pre-existing sandbox-lane invocation and its rendered one-liner stay byte-identical.
@@ -126,13 +133,13 @@ export const formatResult = (result) => {
   if (result.dryRun) {
     if (result.alreadyAcked) {
       return [
-        `agent-workflow ack — DRY RUN: ${ACKS_FILE} already records this recipe fingerprint (${result.fingerprint}) — nothing to do.`,
+        `agent-workflow ack — DRY RUN: ${ACKS_FILE} already records this ${result.lane} fingerprint (${result.fingerprint}) — nothing to do.`,
       ].join('\n');
     }
     return [
       `agent-workflow ack — DRY RUN (no changes; re-run with --apply)`,
       `  - would ${result.existed ? 'set' : 'create'} ${ACKS_FILE} "${result.ackKey}" = "${result.fingerprint}"${merge}`,
-      `  - this is a NEUTRAL recipe acknowledgement, never a security key.`,
+      `  - this is a NEUTRAL ${result.lane} acknowledgement, never a security key.`,
       `  to apply: ${applyCommand(result.root, result.fingerprint, result.lane)}`,
     ].join('\n');
   }
@@ -145,9 +152,11 @@ export const formatResult = (result) => {
 // ── CLI ─────────────────────────────────────────────────────────────────────────────────
 const USAGE = `usage: ack-write --fingerprint <16-hex> [--lane <${Object.keys(ACK_LANES).join('|')}>] [--dry-run | --apply] [--cwd <dir>] [--help]
 
-Records a NEUTRAL recipe acknowledgement into ${ACKS_FILE} (the family-owned ack store — no host
-settings validator guards it). --lane names which advisor item is being acknowledged (default
-"${DEFAULT_ACK_LANE}"); each lane owns one top-level key. Default is --dry-run (a preview; writes
+Records a NEUTRAL acknowledgement into ${ACKS_FILE} (the family-owned ack store — no host settings
+validator guards it). --lane names which advisor item is being acknowledged (default
+"${DEFAULT_ACK_LANE}") and what the fingerprint stands for — a session-sandbox recipe, a worktrees
+probe dir, a tracked-tree census fact, a set of declared tool claims; each lane owns one top-level
+key. Default is --dry-run (a preview; writes
 nothing) and prints the exact --apply command. --apply merges that ONE key into ${ACKS_FILE},
 preserving every existing key. Refuses an absent docs/ai deployment; never a security key; never
 commits.`;

package/tools/atomic-write.mjs

@@ -8,6 +8,8 @@
 //       (bridges 2.3.0, D6): ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf. The
 //       host dir is CREATED if absent (a host config SHOULD materialize), unlike the docs/ai gate
 //       which REFUSES an absent deployment.
+//   • writeProjectFileCreateOnly — a SEED under a project subdirectory (the ensure CLI's enforcement
+//       scripts): the parent dir is created + verified, and the write is create-only.
 //
 // The discipline (verbatim from the source implementation) — writeContainedFileAtomic(root, dst, …):
 //   - a per-consumer GATE runs first (deployment gate for docs/ai; create+verify for the host dir).
@@ -19,12 +21,19 @@
 //   - tmp cleaned up on any failure after its creation.
 //   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
 //
+// `opts.createOnly` swaps the LAST step only: `link(tmp, dst)` instead of `rename(tmp, dst)`. A rename
+// replaces whatever is there — correct for a refresh, wrong for a SEED, where a file that appeared
+// between the probe and the write must survive. link() is the primitive that both keeps the content
+// atomic and fails EEXIST instead of clobbering; the caller learns which happened from `created`,
+// never from a second probe (which would be the same race again). A filesystem that cannot hard-link
+// surfaces its own error — there is no silent fallback to a clobbering write.
+//
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*) so the guards are
 // unit-testable. NEVER imported by a read-only module (procedures.mjs — pinned by an import guard).
 
-import { lstatSync, writeFileSync, renameSync, rmSync, mkdirSync } from 'node:fs';
+import { lstatSync, writeFileSync, renameSync, linkSync, rmSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { assertContainedRealPath } from './fs-safe.mjs';
 
 export const ATOMIC_WRITE_STOP = 'ATOMIC_WRITE_STOP';
@@ -78,11 +87,12 @@ export const assertDocsAiDeployment = (cwd, deps = {}, opts = {}) => {
   }
 };
 
-// Host config dir gate — CREATE the dir if absent (a host config SHOULD materialize on first write,
-// the opposite of the docs/ai deployment gate), then refuse a symlinked / non-directory dir we would
-// write THROUGH (a rename into a symlinked dir would land outside where the user thinks). `noun` names
-// what the caller writes so each consumer's STOP message stays exactly as its own tests pinned it.
-export const assertHostConfigDirSafe = (dir, deps = {}, opts = {}) => {
+// Creatable-dir gate — CREATE the dir if absent (a host config / a project's scripts dir SHOULD
+// materialize on first write, the opposite of the docs/ai deployment gate), then refuse a symlinked /
+// non-directory dir we would write THROUGH (a rename into a symlinked dir would land outside where the
+// user thinks). `noun` names what the caller writes so each consumer's STOP message stays exactly as
+// its own tests pinned it.
+export const assertCreatableDirSafe = (dir, deps = {}, opts = {}) => {
   const lstat = deps.lstat ?? lstatSync;
   const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
   const stop = opts.stop ?? defaultStop;
@@ -95,12 +105,17 @@ export const assertHostConfigDirSafe = (dir, deps = {}, opts = {}) => {
 };
 
 // The hardened atomic flow, parameterized by containment ROOT + an already-passed gate. `dst` is the
-// ABSOLUTE target under `root`; `opts.label` names it in a symlink-refusal message. Returns
-// { writtenPath: dst }. THROWS the caller's typed STOP (opts.stop) or a native fs error.
+// ABSOLUTE target under `root`; `opts.label` names it in a symlink-refusal message; `opts.createOnly`
+// makes the last step a no-clobber link (above). Returns { writtenPath: dst, created, tmpLeftBehind }
+// — `created` is false ONLY under createOnly, when a regular file already stood there, and
+// `tmpLeftBehind` names the temp file when the post-publication cleanup failed (the write STANDS;
+// the leftover is reported, never swallowed). THROWS the caller's typed STOP (opts.stop) or a native
+// fs error.
 export const writeContainedFileAtomic = (root, dst, body, deps = {}, opts = {}) => {
   const lstat = deps.lstat ?? lstatSync;
   const writeFile = deps.writeFile ?? writeFileSync;
   const rename = deps.rename ?? renameSync;
+  const link = deps.link ?? linkSync;
   const rm = deps.rm ?? ((p) => rmSync(p, { force: true }));
   const rand = deps.rand ?? (() => randomBytes(6).toString('hex'));
   const stop = opts.stop ?? defaultStop;
@@ -121,6 +136,8 @@ export const writeContainedFileAtomic = (root, dst, body, deps = {}, opts = {})
   // Exclusive-create (wx): never clobber a leftover tmp (a stray collision is surfaced, not silently
   // overwritten). The random suffix makes a collision effectively impossible; wx makes it impossible-loud.
   writeFile(tmp, body, { encoding: 'utf8', flag: 'wx' });
+  let created = true;
+  let tmpLeftBehind = null;
   try {
     // TOCTOU re-check: the parent chain + the leaf may have changed since the pre-checks above.
     guard(dst);
@@ -128,30 +145,66 @@ export const writeContainedFileAtomic = (root, dst, body, deps = {}, opts = {})
     if (leafAgain && leafAgain.isSymbolicLink()) {
       throw stop(`${label} became a symlink — refusing to replace it`);
     }
-    rename(tmp, dst);
+    if (opts.createOnly) {
+      try {
+        link(tmp, dst);
+      } catch (err) {
+        if (!err || err.code !== 'EEXIST') throw err;
+        // EEXIST is not proof that a REGULAR FILE stands there. Re-check no-follow: a symlink that
+        // appeared inside the race window meets the same refusal as one that was there all along, a
+        // non-file is refused rather than reported as a preserved seed, and a dst that is already
+        // gone again is a loud conflict — never a silent "it was already there".
+        const raced = lstatNoFollow(dst, lstat);
+        if (raced === null) throw stop(`${label} could not be created, and nothing is there now — something is creating and removing it underneath this write; re-run when the tree is settled`);
+        if (raced.isSymbolicLink()) throw stop(`${label} became a symlink — refusing to seed through it`);
+        if (!raced.isFile()) throw stop(`${label} exists but is not a regular file — refusing to seed through it`);
+        created = false; // it appeared under us — the existing file stands, byte-for-byte
+      }
+      // The publication is DONE (or the dst already stood): dropping our tmp name may not turn a
+      // completed write into a failure. A cleanup that fails is reported instead — never swallowed.
+      try {
+        rm(tmp);
+      } catch {
+        tmpLeftBehind = tmp;
+      }
+    } else {
+      rename(tmp, dst);
+    }
   } catch (err) {
     rm(tmp); // never leave a temp file behind on failure
     throw err;
   }
-  return { writtenPath: dst };
+  return { writtenPath: dst, created, tmpLeftBehind };
 };
 
-// writeDocsAiFileAtomic(cwd, rel, body, deps, opts) → { writtenPath: rel } on success; THROWS the
-// caller's typed STOP (via opts.stop) or a native fs error otherwise. `body` arrives pre-serialized
-// (each consumer owns its canonical serialization). Thin wrapper over the core: gate = deployment
-// gate, root = cwd, target = cwd/rel; the label + return stay `rel` so its public API is unchanged.
+// writeDocsAiFileAtomic(cwd, rel, body, deps, opts) → { writtenPath: rel, created } on success;
+// THROWS the caller's typed STOP (via opts.stop) or a native fs error otherwise. `body` arrives
+// pre-serialized (each consumer owns its canonical serialization). Thin wrapper over the core: gate =
+// deployment gate, root = cwd, target = cwd/rel; the label + return stay `rel` so its public API is
+// unchanged (`created` is additive — always true unless the caller asked for createOnly).
 export const writeDocsAiFileAtomic = (cwd, rel, body, deps = {}, opts = {}) => {
   assertDocsAiDeployment(cwd, deps, { ...opts, rel });
   const dst = join(cwd, rel);
-  writeContainedFileAtomic(cwd, dst, body, deps, { ...opts, label: rel });
-  return { writtenPath: rel };
+  const { created, tmpLeftBehind } = writeContainedFileAtomic(cwd, dst, body, deps, { ...opts, label: rel });
+  return { writtenPath: rel, created, tmpLeftBehind };
 };
 
 // writeHostConfigFileAtomic(dir, filename, body, deps, opts) → { writtenPath: dir/filename }. Gate =
 // create+verify the host dir; root = that dir; target = dir/filename. For the out-of-tree host config
 // surface (bridge-settings.conf) that no project deployment owns.
 export const writeHostConfigFileAtomic = (dir, filename, body, deps = {}, opts = {}) => {
-  assertHostConfigDirSafe(dir, deps, opts);
+  assertCreatableDirSafe(dir, deps, opts);
   const dst = join(dir, filename);
   return writeContainedFileAtomic(dir, dst, body, deps, { ...opts, label: opts.label ?? dst });
 };
+
+// writeProjectFileCreateOnly(root, rel, body, deps, opts) → { writtenPath: rel, created }. Gate =
+// create+verify the target's PARENT dir inside the project (a symlinked `scripts/` is a STOP, not a
+// write through it); root = the project dir; the write is create-only, so an existing file is left
+// exactly as it is and `created` says so.
+export const writeProjectFileCreateOnly = (root, rel, body, deps = {}, opts = {}) => {
+  const dst = join(root, rel);
+  assertCreatableDirSafe(dirname(dst), deps, opts);
+  const { created, tmpLeftBehind } = writeContainedFileAtomic(root, dst, body, deps, { ...opts, createOnly: true, label: rel });
+  return { writtenPath: rel, created, tmpLeftBehind };
+};