@sabaiway/agent-workflow-kit 5.5.0 → 5.7.0

package/tools/checker-claim.mjs

@@ -0,0 +1,100 @@
+// checker-claim.mjs — what a declared gate cmd CLAIMS about one of the kit's own `--check` tools,
+// as three named outcomes instead of a boolean. A LEAF: node built-ins only, so every surface that
+// must recognize a tool invocation (the source-size matcher, the advisor's probes, the standalone
+// migration's twin) decides through ONE screen.
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+// 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

package/tools/coverage-producer.mjs

@@ -13,13 +13,29 @@
 //
 // 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
@@ -52,8 +68,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,
@@ -65,4 +82,24 @@ 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

package/tools/direct-run.mjs

@@ -0,0 +1,76 @@
+// direct-run.mjs — the ONE direct-invocation predicate for kit modules, plus the EXPLICIT registry of
+// library-only modules and the refusal they print when someone runs one as a command.
+//
+// Two facts this leaf owns:
+//
+//   1. WAS this module the process entry point? Compared by REAL path, not lexically. ESM resolves a
+//      symlinked entry point to its target, so `import.meta.url === pathToFileURL(process.argv[1]).href`
+//      is FALSE whenever a tool is invoked through a link — a CLI whose gate reads that way exits 0
+//      having run nothing, which reads as PASS. The realpath compare was fixed once inside the
+//      source-size writer; this module is that fix extracted, so every consumer shares it (the
+//      THE-LEXICAL-DIRECT-RUN-GUARD class stays closed in one place instead of per file).
+//
+//   2. WHICH modules have no CLI at all. A library-only module invoked directly today runs its
+//      top-level code, prints nothing, and exits 0 — indistinguishable from a tool that worked. The
+//      registry below turns that silence into a one-line pointer at the command that DOES the thing,
+//      and a non-zero exit.
+//
+// The registry is EXPLICIT, never a repo-wide heuristic (D6). Its membership rule — the one the
+// completeness test enforces — is REACHABILITY BY NAME: a module a mode doc names is a module an
+// agent or a user can try to run, and it is exactly those that need a pointer. A library module no
+// document names is unreachable by name and stays out.
+//
+// A pure leaf: it imports NOTHING from tools/ (the read-graph purity walk depends on that) and has no
+// side effect on import.
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { basename } from 'node:path';
+
+// The usage exit code of the family's CLIs — invoking a library module is a usage error, not a
+// precondition failure.
+export const DIRECT_RUN_USAGE_EXIT = 2;
+
+// Compared by REAL path (see (1) above). Exported as a test seam: the unresolvable arm cannot be
+// reached through a real invocation, where an existing entry point is a precondition.
+export const sameFile = (a, b) => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
+
+// isDirectRun(import.meta.url) → was THIS module the entry point of the current process?
+export const isDirectRun = (moduleUrl, argv1 = process.argv[1]) =>
+  Boolean(argv1) && sameFile(fileURLToPath(moduleUrl), argv1);
+
+// The registry: library-only module → the command that does what someone reaching for it wants. The
+// value is a user-facing command token of the kit's own catalog (commands.mjs), pinned by the test —
+// never a raw node invocation, which would just move the confusion one file over.
+export const LIBRARY_ONLY_MODULES = Object.freeze({
+  // Named by references/modes/upgrade.md as the source of truth for the _README refresh decision; the
+  // command that APPLIES that decision is the ensure CLI, and the one that edits the config by intent
+  // is set-recipe.
+  'orchestration-config.mjs': '/agent-workflow-kit set-recipe',
+});
+
+// The frozen refusal line. One line, names the module, names the command.
+export const libraryOnlyLine = (name) => {
+  const command = LIBRARY_ONLY_MODULES[name];
+  if (command === undefined) {
+    throw new Error(`[agent-workflow-kit] ${name} is not in LIBRARY_ONLY_MODULES — register it before guarding it`);
+  }
+  return `${name}: library module — no CLI; use ${command}`;
+};
+
+// refuseDirectRun(import.meta.url) — the guard a library-only module ends with. A no-op when imported
+// (the overwhelmingly common case); on a DIRECT run it prints the pointer and sets a non-zero exit
+// code. `process.exitCode` rather than `process.exit`: nothing else is pending on a direct run, and a
+// hard exit inside module evaluation would be a side effect of import if the predicate ever misfired.
+export const refuseDirectRun = (moduleUrl, deps = {}) => {
+  if (!isDirectRun(moduleUrl, deps.argv1 ?? process.argv[1])) return 0;
+  (deps.errlog ?? console.error)(libraryOnlyLine(basename(fileURLToPath(moduleUrl))));
+  (deps.setExitCode ?? ((code) => { process.exitCode = code; }))(DIRECT_RUN_USAGE_EXIT);
+  return DIRECT_RUN_USAGE_EXIT;
+};

package/tools/doc-parity.mjs

@@ -33,6 +33,8 @@ import {
   ACKS_FILE,
 } from './recommendations.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
+// The parity verdicts that read-only skip may report — a CLOSED set the same two mode docs enumerate.
+import { PARITY } from './refresh-parity.mjs';
 // The host-conditional qualifier every settings-derived runtime claim carries (Decision 11).
 import { HOST_HONORS_QUALIFIER } from './velocity-profile.mjs';
 import { LATENT_ARM_NOTICE } from './review-state.mjs';
@@ -47,6 +49,14 @@ import { RECEIPT_DEADLINE_CONTRACT } from './receipt-deadline.mjs';
 import { DISPATCH_CONTRACT } from './dispatch.mjs';
 // The coverage vocabulary leaf: a CLOSED value set the gates contract doc must enumerate.
 import { COVERAGE } from './coverage-state.mjs';
+// The canonical producer body: gates.md prints the whole command byte for byte, so the doc is a
+// hand copy of a moving constant unless it is bound here.
+import { COVERAGE_PRODUCER_BODY } from './coverage-producer.mjs';
+// The ensure outcomes upgrade.md relays: the doc enumerates them for the agent, so an outcome the
+// tool renames or drops must fail here rather than leave the doc teaching a vocabulary nobody emits.
+// Imported from the VOCABULARY leaf, never from the ops: a read-only lint must not pull the ensure
+// implementation — and through it the orchestration writer — into its import graph.
+import { RELAYED_ENSURE_TOKENS } from './ensure-vocabulary.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -116,6 +126,18 @@ export const BINDINGS = Object.freeze([
   // (setup.md owns --refresh-placed; upgrade.md pastes its lines) — a reworded doc dropping the
   // outcome fails this pin plus the gate. The token tracks the exported SETUP constant.
   valueBinding('refresh-skipped-readonly', SKIPPED_READONLY, SKIPPED_READONLY, [SETUP_DOC, UPGRADE_DOC]),
+  // And the parity verdict that outcome now carries (feedback-hardening Plan 1 F3 / D3): the skip
+  // line used to assert "PARTIALLY updated" and "drift persists" unconditionally, so the docs
+  // described a post-state nothing had checked. The verdict set is CLOSED — one binding per value,
+  // backticked so a bare word in prose cannot pass for the pinned token — and both docs that
+  // enumerate the refresh outcomes must carry all three, or a reworded doc goes back to promising a
+  // claim the tool no longer makes.
+  ...Object.values(PARITY).map((token) => valueBinding(`refresh-parity:${token}`, token, `\`${token}\``, [SETUP_DOC, UPGRADE_DOC])),
+  // The project-configuration ensures (feedback-hardening Plan 1 F4): upgrade.md used to PRESCRIBE
+  // each of the four as prose, so the doc was the only place the outcome set existed and drifted for
+  // free. Now one command performs them and the doc enumerates its tokens — backticked, so a bare
+  // word in a sentence cannot pass for the pinned outcome.
+  ...RELAYED_ENSURE_TOKENS.map((token) => valueBinding(`ensure-outcome:${token}`, token, `\`${token}\``, [UPGRADE_DOC])),
   // The "the tool knows and does not say" contract: a clean-tree PASS must still name a latent arm.
   // It was a prose-only bar a doc could silently drop, so it is pinned to the live string the tool
   // actually emits — a reworded doc dropping the notice fails this pin plus the gate.
@@ -163,6 +185,13 @@ export const BINDINGS = Object.freeze([
   // CLOSED value set, so a renamed or added value fails here instead of leaving the doc describing
   // a vocabulary the runner no longer speaks. One binding per value — the set is small and closed.
   ...Object.values(COVERAGE).map((value) => valueBinding(`coverage-state:${value}`, value, `\`coverage=${value}\``, [GATES_DOC])),
+  // The canonical producer body: gates.md prints the whole command byte for byte, so the doc is a
+  // HAND COPY of a constant that moves (it moved once already, when the destination became a
+  // required-parameter expansion). Nothing else pinned it — the drift guard holds the two authored
+  // copies of the code region equal, and the producer test pins the shipped template, but neither
+  // sees the doc. Bound here, a future move fails a declared gate instead of leaving the contract
+  // doc quietly describing a command the kit no longer emits.
+  valueBinding('coverage-producer-body', COVERAGE_PRODUCER_BODY, COVERAGE_PRODUCER_BODY, [GATES_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -209,13 +238,15 @@ Usage:
 A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
 table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
 contract (section header, empty line, verdict templates), the acks-store path, the host-conditional
-qualifier every settings-derived runtime claim carries, the setup refresh degrade token, the review-state clean-tree latent-arm notice, the worktrees provision-record
+qualifier every settings-derived runtime claim carries, the setup refresh degrade token and the three
+parity verdicts it reports, the review-state clean-tree latent-arm notice, the worktrees provision-record
 orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture), the
 worktrees cleanup-ownership rule, the worktrees include-identity rule, the worktrees
 resume-verify rule, the flow tolerate contract (the accepted flow schema version + the
 lagging-kit sentence, procedures.md), the receipt-deadline arrival contract, the dispatch engine's
-FORM-only + aggregate-refusal contract (dispatch.md), and the runner's closed coverage= summary
-vocabulary (gates.md) — to
+FORM-only + aggregate-refusal contract (dispatch.md), the runner's closed coverage= summary
+vocabulary (gates.md), and the canonical coverage-producer-body command the same doc prints in full
+(gates.md) — to
 the exact token its references/modes/*.md contract must carry, and
 asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
 or an absent token FAILS CLOSED.

package/tools/engine-source.mjs

@@ -111,7 +111,7 @@ export const detectEngine = (engineDir, { source, rel } = {}, deps = {}) => {
           ? `engine manifest name "${report.name}" is not "${EXPECTED_ENGINE_NAME}"`
           : report.available === false
             ? 'engine manifest is a declared stub (available:false)'
-            : `engine fragment missing (${fragmentRel})`;
+            : `a required engine file is missing (${fragmentRel})`;
   return { ok, reason, dir: engineDir };
 };
 
@@ -124,15 +124,19 @@ export const detectEngine = (engineDir, { source, rel } = {}, deps = {}) => {
 export const readEngineFragment = (engineDir, deps = {}) => {
   const detection = detectEngine(engineDir, { source: deps.source, rel: deps.rel }, deps);
   const installHint = `npx @sabaiway/agent-workflow-engine@latest init  (or set ${ENGINE_ENV})`;
-  if (!detection.ok) {
-    throw new Error(`methodology engine not found/invalid at ${engineDir} (${detection.reason}) — install it: ${installHint}`);
-  }
+  // The typed {stable, reason} pair lets a consumer split the classified human line from the raw
+  // diagnostic (its machine-line channel) without parsing the message; .message stays whole for
+  // consumers that print one line.
+  const installMe = (reason) => Object.assign(
+    new Error(`methodology engine not found/invalid at ${engineDir} (${reason}) — install it: ${installHint}`),
+    { stable: `methodology engine not found/invalid at ${engineDir} — install it: ${installHint}`, reason },
+  );
+  if (!detection.ok) throw installMe(detection.reason);
   const read = deps.readFileSync ?? readFileSync;
+  const fragmentRel = deps.rel ?? ENGINE_FRAGMENT_REL;
   try {
-    return read(join(engineDir, deps.rel ?? ENGINE_FRAGMENT_REL), 'utf8');
+    return read(join(engineDir, fragmentRel), 'utf8');
   } catch (err) {
-    throw new Error(
-      `methodology engine not found/invalid at ${engineDir} (fragment unreadable: ${err.message}) — install it: ${installHint}`,
-    );
+    throw installMe(`a required engine file is unreadable (${fragmentRel}): ${err.message}`);
   }
 };

package/tools/ensure-configs.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// ensure-configs.mjs — ONE runnable command for the four stamp-independent upgrade ensures:
+//
+//   orchestration  docs/ai/orchestration.json  seed, or refresh a still-canonical onboarding note
+//   gates          docs/ai/gates.json          seed-if-missing (an existing declaration is authored content)
+//   autonomy       docs/ai/autonomy.json       seed-if-missing (same)
+//   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
+//
+// Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
+// of four is deliberate: four independent runs would be four chances to skip one, and the mode doc now
+// has a single invocation point whose four outcome lines it relays.
+//
+// The contract (pinned by this module's tests):
+//   • --reconcile is REQUIRED. A bare run is a usage error, so nothing writes by accident.
+//   • --dry-run reports `would-*` tokens and writes nothing — never a write token.
+//   • The ops run in a FIXED order and one op's failure NEVER skips the rest: every op reports its own
+//     token, and the exit is non-zero when any of them failed.
+//   • The deployment gate runs ONCE, before any op: an absent/symlinked docs/ai stops the whole run
+//     with the gate's own message rather than four copies of it.
+//
+// Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
+// Exit codes: 0 every op fine · 1 an op failed, or the deployment gate stopped the run · 2 usage.
+// main(argv, ctx) → { code, stdout, stderr }; cwd + fs are injectable for host-independent tests.
+//
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertDocsAiDeployment } from './atomic-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { ENSURE_IMPLEMENTATIONS, ENSURE_OPS, failedOutcome } from './ensure-ops.mjs';
+
+const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const EXIT_OK = 0;
+const EXIT_FAILED = 1;
+const EXIT_USAGE = 2;
+
+const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+const EMPTY_CWD = '--cwd needs a path argument (an empty value would silently mean the current directory)';
+
+const HELP = `ensure-configs — the four stamp-independent upgrade ensures, as ONE command.
+
+Usage:
+  node ensure-configs.mjs --reconcile [--dry-run] [--cwd <project>]
+
+  --reconcile   required — run the four ensures (orchestration, gates, autonomy, scripts)
+  --dry-run     report what each ensure WOULD do; write nothing
+  --cwd <dir>   the target project (default: the current directory)
+  --help, -h    this help
+
+Every seed is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
+refreshed in place. The one refresh is the orchestration onboarding note, and only while it still
+matches a canonical the kit shipped — your own wording is preserved verbatim. The enforcement-script
+ensure detects an older ADR-store layout FIRST and instructs the opt-in migration instead of seeding.
+
+Exit codes: 0 every op fine; 1 an op failed (its line says so) or there is no deployment here; 2 usage.`;
+
+// argv → { reconcile, dryRun, cwd, help }. Order-independent; an unknown flag or a missing --cwd
+// value is a usage error, never a silently-ignored argument.
+export const parseArgs = (argv) => {
+  const out = { reconcile: false, dryRun: false, cwd: undefined, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--reconcile') out.reconcile = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--cwd') {
+      // An EMPTY value resolves to the ambient cwd — a writing CLI would then act on a different
+      // project than the caller named, silently. Both spellings refuse it.
+      const next = argv[i + 1];
+      if (next === undefined || next === '' || next.startsWith('-')) throw fail(EXIT_USAGE, EMPTY_CWD);
+      out.cwd = next;
+      i += 1;
+    } else if (a.startsWith('--cwd=')) {
+      const value = a.slice('--cwd='.length);
+      if (value === '') throw fail(EXIT_USAGE, EMPTY_CWD);
+      out.cwd = value;
+    } else throw fail(EXIT_USAGE, `unknown argument: ${a}`);
+  }
+  if (!out.help && !out.reconcile) {
+    throw fail(EXIT_USAGE, 'nothing to do — pass --reconcile (see --help). This tool never writes without it.');
+  }
+  return out;
+};
+
+// Run every op in ENSURE_OPS order. A throw from one op becomes THAT op's failed outcome — the
+// remaining ops still run, because a project missing its gate declaration should not also be left
+// without its autonomy seed just because the first ensure hit an unreadable file.
+export const runEnsures = ({ cwd, kitRoot, dryRun, deps }) =>
+  ENSURE_OPS.map((op) => {
+    try {
+      return ENSURE_IMPLEMENTATIONS[op]({ cwd, kitRoot, dryRun, deps });
+    } catch (err) {
+      return failedOutcome(op, err);
+    }
+  });
+
+const render = (outcomes, dryRun) => {
+  // The banner names the tool + the flag it ran under (both machine tokens the L2 rule exempts);
+  // the failure footer is a user-grade sentence — the composed-lines guard scans both.
+  const lines = [dryRun ? 'ensure-configs (--reconcile, dry run — nothing written)' : 'ensure-configs (--reconcile)'];
+  for (const o of outcomes) {
+    lines.push(`  ${o.op}: ${o.token}`);
+    for (const detail of o.lines) lines.push(`      ${detail}`);
+  }
+  if (outcomes.some((o) => o.failed)) {
+    // No blanket claim about what was written: an op that copies file by file can stop PARTWAY, and
+    // its own lines are the only accurate account of what landed.
+    lines.push('', '  part of this configuration run did NOT complete — the lines above name the cause, and what was and was not written.');
+  }
+  return lines.join('\n');
+};
+
+export const main = (argv = [], ctx = {}) => {
+  try {
+    const args = parseArgs(argv);
+    if (args.help) return { code: EXIT_OK, stdout: HELP, stderr: '' };
+    const cwd = resolve(args.cwd ?? ctx.cwd ?? process.cwd());
+    const deps = ctx.deps ?? {};
+    // ONE deployment gate for the whole run (see the header): with no docs/ai there is nothing to
+    // reconcile, and four identical STOPs would read as four separate problems.
+    assertDocsAiDeployment(cwd, deps, { noun: 'the project configuration', rel: 'under docs/ai' });
+    const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps });
+    return {
+      code: outcomes.some((o) => o.failed) ? EXIT_FAILED : EXIT_OK,
+      stdout: render(outcomes, args.dryRun),
+      stderr: '',
+    };
+  } catch (err) {
+    return { code: err.exitCode ?? EXIT_FAILED, stdout: '', stderr: `ensure-configs: ${err.message}` };
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) console.log(r.stdout);
+  if (r.stderr) console.error(r.stderr);
+  process.exitCode = r.code;
+}