@sabaiway/agent-workflow-kit 7.2.0 → 7.4.0

package/references/templates/agent_rules.md

@@ -23,12 +23,12 @@ Read in order, then confirm before starting:
 4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
-**Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.
+**Before any feature:** name its governing spec(s) — the feature spec under `docs/ai/specs/` for every touched spec-covered slice (zero is legal during adoption; each cited spec's Out of scope bounds that slice's work). Where only a page spec (`docs/ai/pages/<page>.md`) exists it governs as an ADOPTION SHIM: state Out of scope + Revision inline in the plan. If the contract changes, the spec revision is authored WITH the plan (visible at review) and lands with the code, so docs and code never diverge.
 
 **For every code change:**
 1. Grep for similar implementations — reuse existing patterns.
 2. Check the design-system layer for an existing component; if missing, add it there FIRST, then use it.
-3. Verify changes align with `docs/ai/pages/<page>.md`; for a new page, create a full spec.
+3. Verify changes align with the governing spec(s) and `docs/ai/pages/<page>.md`; a new feature gets a `draft` spec (the skill's `SPEC_TEMPLATE.md`), a new page a full page spec.
 4. Follow §2 (Self-Review): functional style, named exports, full variable names, no magic literals.
 5. Write/update tests FIRST (TDD): unit for pure functions, E2E for user flows.
 6. Run quality checks: lint, type-check, tests.
@@ -36,7 +36,7 @@ Read in order, then confirm before starting:
 ### 1.3. Task Completion
 Before claiming "done":
 1. Run all quality gates (lint + type-check + tests) — all green.
-2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation). Only bump "Last Updated" when content actually changed.
+2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation), the governing spec (its revision lands with the code: `draft` -> `live` on the landing row). Only bump "Last Updated" when content actually changed.
 3. Run the docs cap-validator + index-freshness gate (pre-commit also enforces). On failure: trim the offending file, or run the changelog rotation if the offender is `changelog.md`.
 4. If the work executed a plan file — run that plan's final **Phase: Cleanup** (see the planning skill / §5). Without it the plan is not done.
 5. **Ask before committing** (§4): report lint / type-check / test counts + docs status, then wait for explicit approval. DO NOT auto-commit.
@@ -78,6 +78,7 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **Spec-first.** A plan names its GOVERNING spec(s) — zero, one or many, one per touched spec-covered slice (the feature spec under `docs/ai/specs/`; page-only coverage governs as an ADOPTION SHIM, with Out of scope + Revision stated inline in the plan). Each cited spec's Out of scope bounds that slice's work and the plan's non-goals restate it per slice — no global union; a cross-spec conflict is resolved by a spec revision BEFORE approval, never by silent precedence. A NEW feature's draft spec exists AT plan review (a `create` row); a change to a governed contract rides the plan as its proposed revision (a `modify` row); approval confirms plan and contract atomically, and the revision lands with the code. Scenario bindings are per scenario: a new scenario is `unbound` until its test lands in the same plan, and a status never regresses for an extension.
 - **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.

package/references/templates/specs/index.md

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

package/tools/ensure-configs.mjs

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
-// ensure-configs.mjs — ONE runnable command for the five stamp-independent upgrade ensures:
+// ensure-configs.mjs — ONE runnable command for the six 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
+//   specs          scripts/<spec layer>        reader pair seed-if-missing, checker pair refreshed only on
+//                  + docs/ai/specs/index.md    a shipped prior body, store root seeded behind a current checker
 //   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact)
 //
 // Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
-// of five is deliberate: five independent runs would be five chances to skip one, and the mode doc now
-// has a single invocation point whose five outcome lines it relays.
+// of six is deliberate: six independent runs would be six chances to skip one, and the mode doc now
+// has a single invocation point whose six 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.
@@ -17,7 +19,7 @@
 //   • 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 five copies of it.
+//     with the gate's own message rather than six 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.
@@ -29,10 +31,15 @@ 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';
+import { ENSURE_OPS, OWN_IMPLEMENTATIONS, failedOutcome } from './ensure-ops.mjs';
+import { ensureSpecs } from './ensure-specs.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
+// The op table this CLI walks — name → implementation, in ENSURE_OPS order. Composed HERE (the one
+// consumer) because the spec-layer ensure imports ensure-ops.mjs for its outcome door and probes.
+export const ENSURE_IMPLEMENTATIONS = Object.freeze({ ...OWN_IMPLEMENTATIONS, specs: ensureSpecs });
+
 const EXIT_OK = 0;
 const EXIT_FAILED = 1;
 const EXIT_USAGE = 2;
@@ -44,22 +51,24 @@ const EMPTY_ONLY = `--only needs one operation name (${ENSURE_OPS.join(' | ')})
 const REPEATED_ONLY = '--only was passed more than once — this selector names exactly ONE operation';
 const unknownOp = (value) => `--only ${value}: no such operation (${ENSURE_OPS.join(' | ')}) — nothing was run`;
 
-const HELP = `ensure-configs — the five stamp-independent upgrade ensures, as ONE command.
+const HELP = `ensure-configs — the six stamp-independent upgrade ensures, as ONE command.
 
 Usage:
   node ensure-configs.mjs --reconcile [--dry-run] [--only <op>] [--cwd <project>]
 
-  --reconcile   required — run the five ensures (${ENSURE_OPS.join(', ')})
+  --reconcile   required — run the six ensures (${ENSURE_OPS.join(', ')})
   --dry-run     report what each ensure WOULD do; write nothing
   --only <op>   run EXACTLY ONE of them (an unknown, missing or repeated value is a usage error)
   --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. Two ops refresh instead: the orchestration onboarding note, only while it still
-matches a canonical the kit shipped (your own wording is preserved verbatim), and the navigator
-index — a GENERATED artifact, regenerated whenever it is missing or stale. The enforcement-script
-ensure detects an older ADR-store layout FIRST and instructs the opt-in migration instead of seeding.
+refreshed in place. Three ops refresh instead: the orchestration onboarding note, only while it still
+matches a canonical the kit shipped (your own wording is preserved verbatim); the spec-layer checker
+pair, only while its bytes are a body a release shipped (an edited checker is preserved, and the spec
+store root is then NOT seeded behind it); and the navigator index — a GENERATED artifact, regenerated
+whenever it is missing or stale. 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.`;
 
@@ -138,7 +147,7 @@ export const main = (argv = [], ctx = {}) => {
     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 five identical STOPs would read as five separate problems.
+    // reconcile, and six identical STOPs would read as six 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, only: args.only });
     return {

package/tools/ensure-ops.mjs

@@ -1,6 +1,8 @@
-// ensure-ops.mjs — the FIVE upgrade ensure operations, one function each, behind one shared outcome
-// shape. The CLI that orders and runs them is ensure-configs.mjs; this module owns what each ensure
-// DOES and, more importantly, what it is allowed to CLAIM.
+// ensure-ops.mjs — FIVE of the upgrade ensure operations, one function each, behind one shared
+// outcome shape; the sixth (the spec-layer ensure, ensure-specs.mjs) composes its outcomes through
+// the same door and probes exported below. The CLI that orders and runs them is ensure-configs.mjs —
+// it owns the op table, so the import graph stays acyclic; this module owns what each ensure DOES
+// and, more importantly, what it is allowed to CLAIM.
 //
 // Why they became code at all: `references/modes/upgrade.md` prescribed each of them as prose an agent
 // was expected to carry out by hand ("create it from the template if missing", "copy the pair from
@@ -86,14 +88,14 @@ export const failedOutcome = (op, err) => loud(op, 'unexpected-error', `${op}: $
 // directory or a symlink named gates.json report a green ensure while the declaration the project
 // needs does not exist — an exit 0 proving nothing (both review backends found this).
 const NODE_KIND = (st) => (st.isSymbolicLink() ? 'a symlink' : st.isDirectory() ? 'a directory' : 'not a regular file');
-const probeSeedTarget = (abs, lstat) => {
+export const probeSeedTarget = (abs, lstat) => {
   const st = lstatNoFollow(abs, lstat);
   if (st === null) return { present: false };
   return st.isFile() ? { present: true } : { present: true, wrongKind: NODE_KIND(st) };
 };
 
 // A leftover temp file never fails a completed write, and is never silent either.
-const tmpNote = (rel, tmpLeftBehind) =>
+export const tmpNote = (rel, tmpLeftBehind) =>
   (tmpLeftBehind ? [`${rel}: the write stands, but its temp file could not be removed — delete it by hand: ${tmpLeftBehind}`] : []);
 
 // ── 1. orchestration.json — seed, or refresh ONLY a still-canonical onboarding note ────────────────
@@ -204,7 +206,7 @@ export const ensureAutonomy = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
 
 // A project with no package.json at its root is not where Node enforcement scripts belong. Stated,
 // never silent: the token names the evidence, and the three config ensures still run.
-const isNodeProject = (cwd, lstat) => lstatNoFollow(join(cwd, PACKAGE_JSON), lstat) !== null;
+export const isNodeProject = (cwd, lstat) => lstatNoFollow(join(cwd, PACKAGE_JSON), lstat) !== null;
 
 const OLD_ADR_LAYOUTS = new Set(['old', 'old-unrotated']);
 
@@ -352,8 +354,9 @@ export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   return loud('index', 'index-probe-failed', `${INDEX_REL}: the generator reported a regeneration, but the verifying probe answered neither fresh nor stale — ${MAY_HAVE_WRITTEN}. ${verify.error ? causeOf(verify.error) : verdict}`);
 };
 
-// The op table the CLI walks — name → implementation, in ENSURE_OPS order.
-export const ENSURE_IMPLEMENTATIONS = Object.freeze({
+// The five ops this module owns, by name. The CLI composes the full ENSURE_OPS table from these plus
+// the spec-layer ensure (ensure-specs.mjs imports THIS module, so the table cannot live here).
+export const OWN_IMPLEMENTATIONS = Object.freeze({
   orchestration: ensureOrchestration,
   gates: ensureGates,
   autonomy: ensureAutonomy,

package/tools/ensure-specs.mjs

@@ -0,0 +1,214 @@
+// ensure-specs.mjs — the SIXTH upgrade ensure: the spec layer (memory 4.6.0, AD-112) delivered to an
+// EXISTING deployment on an equal-head upgrade. Four deployed scripts and one store root, written in
+// a FIXED order the measured coupling dictates:
+//   1. the reader pair   scripts/spec-schema.mjs + .test.mjs      — CREATE-ONLY (brief D1: a new
+//      deployed script ships create-only before any refresh of a file that imports it);
+//   2. the checker pair  scripts/check-docs-size.mjs + .test.mjs  — REFRESHED only when the deployed
+//      bytes are a body a release shipped (script-priors.mjs), created when absent, a custom body
+//      preserved verbatim — and only behind a reader pair that is byte-current;
+//   3. the store root    docs/ai/specs/index.md                   — seeded (placeholders rendered)
+//      only once both pairs are current.
+// Why the order: the kit's bundled navigator generator collapses `specs/` into one row, while the
+// project's pre-commit hook runs ITS deployed checker — an older one renders the store row by row and
+// reds `--check-index`. A store root seeded behind a stale checker breaks the hook, so the store is
+// the LAST write and admits only behind a checker this run has proven current.
+//
+// The state table (enumerate by PROOF, never by exclusion): every file is classified into exactly one
+// of current | prior | custom | absent | wrong-kind before anything is written, each write admits
+// through ONE conjunction of those facts (decideWrites), and every other cell is a stated refusal —
+// a custom file of either pair preserves itself AND withholds every write that depends on it. Writes
+// run in order and each is idempotent, so a run that stopped partway converges on the next run.
+//
+// Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeContainedFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
+import { PRIOR_FILES, classifyDeployedScript } from './script-priors.mjs';
+import { composeFailure, composeOutcome, isNodeProject, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
+
+const OP = 'specs';
+const SCRIPTS_DIR = 'scripts';
+const BUNDLED_SCRIPTS = ['references', 'scripts'];
+const STORE_ROOT_REL = 'docs/ai/specs/index.md';
+const STORE_ROOT_TEMPLATE = ['references', 'templates', 'specs', 'index.md'];
+const DATE_PLACEHOLDER = '{{DATE}}';
+const READER_PAIR = Object.freeze(['spec-schema.mjs', 'spec-schema.test.mjs']);
+const CHECKER_PAIR = PRIOR_FILES;
+
+const ok = (token, lines) => composeOutcome(OP, token, lines, false);
+const loud = (cause, ...lines) => composeFailure(OP, cause, ...lines);
+const causeOf = (err) => String((err && err.message) || err);
+const todayIso = () => new Date().toISOString().slice(0, 10);
+
+// ── the survey: five paths classified, nothing written ────────────────────────────────────────────
+
+// One deployed script → { rel, name, state, bundle }; `wrongKind` carries the node kind for the
+// refusal, `prior`/`custom` come from the catalog classifier against the bundled body.
+const surveyScript = ({ cwd, kitRoot, name, read, lstat }) => {
+  const rel = `${SCRIPTS_DIR}/${name}`;
+  let bundle;
+  try {
+    bundle = read(join(kitRoot, ...BUNDLED_SCRIPTS, name));
+  } catch (err) {
+    return { rel, name, state: 'bundle-unreadable', error: causeOf(err) };
+  }
+  const probe = probeSeedTarget(join(cwd, SCRIPTS_DIR, name), lstat);
+  if (probe.wrongKind) return { rel, name, state: 'wrong-kind', wrongKind: probe.wrongKind, bundle };
+  if (!probe.present) return { rel, name, state: 'absent', bundle };
+  return { rel, name, state: classifyDeployedScript(read(join(cwd, SCRIPTS_DIR, name)), name, bundle), bundle };
+};
+
+const surveyStoreRoot = (cwd, lstat) => {
+  const probe = probeSeedTarget(join(cwd, STORE_ROOT_REL), lstat);
+  if (probe.wrongKind) return { rel: STORE_ROOT_REL, state: 'wrong-kind', wrongKind: probe.wrongKind };
+  return { rel: STORE_ROOT_REL, state: probe.present ? 'present' : 'absent' };
+};
+
+// ── the decision: which writes the survey admits (pure over the survey) ───────────────────────────
+
+const CURRENT_AFTER_SEED = new Set(['current', 'absent']);
+const CHECKER_ELIGIBLE = new Set(['current', 'prior', 'absent']);
+
+export const decideWrites = ({ reader, checker, store }) => {
+  const readerCurrentAfter = reader.every((f) => CURRENT_AFTER_SEED.has(f.state));
+  const checkerEligible = readerCurrentAfter && checker.every((f) => CHECKER_ELIGIBLE.has(f.state));
+  const writes = [];
+  for (const f of reader) if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
+  if (checkerEligible) {
+    for (const f of checker) {
+      if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
+      if (f.state === 'prior') writes.push({ kind: 'refresh', file: f });
+    }
+  }
+  if (checkerEligible && store.state === 'absent') writes.push({ kind: 'store' });
+  return { writes, withheld: !checkerEligible };
+};
+
+// ── the lines (composed from what HAPPENED, never from what was planned) ──────────────────────────
+
+// Every file's line is a function of its surveyed state and the FATE of its write this run:
+// `written` · `stood` (lost the create-only race to the bundled body) · `would` (dry run) ·
+// `withheld` (a custom file in the pair) · `stopped` (the run failed before reaching it) · `none`
+// (no write was admitted or needed). A line never claims a write that did not happen.
+const LEFT_FOR = { withheld: 'it waits on the pair named above', stopped: 'the run stopped before it' };
+const SCRIPT_LINES = {
+  current: () => 'already the bundled body — nothing written',
+  custom: () => "carries a body this kit did not ship as current — preserved verbatim; the writes that depend on it wait until the pair matches the bundled scripts (copy them by hand from the kit's references/scripts/ when convenient, then re-run the upgrade)",
+  absent: (fate) => ({
+    written: 'copied from the bundled scripts',
+    stood: 'appeared while this run was seeding it — the bundled body stands',
+    would: 'absent — would be copied from the bundled scripts',
+  })[fate] ?? `absent — not copied${fate === 'withheld' ? ' this run' : ''}; ${LEFT_FOR[fate]}`,
+  prior: (fate) => `matches a body an earlier release shipped — ${({
+    written: 'refreshed to the bundled one',
+    would: 'would be refreshed to the bundled one',
+  })[fate] ?? `left as is; ${LEFT_FOR[fate]}`}`,
+};
+const scriptLine = (f, fate) => `${f.rel}: ${SCRIPT_LINES[f.state](fate)}`;
+const STORE_LINES = {
+  present: 'already present — preserved byte-for-byte, nothing written',
+  written: "created from the bundled template (today's date rendered)",
+  stood: 'appeared while this run was seeding it — the existing file stands',
+  would: 'absent — would be created from the bundled template',
+  withheld: "not seeded — an older or edited checker renders the spec store row by row and reds the hook's index check, so the store root waits for a current checker pair",
+  stopped: 'absent — not created; the run stopped before it',
+};
+const storeLine = (store, fate) => `${STORE_ROOT_REL}: ${STORE_LINES[store.state === 'present' ? 'present' : fate]}`;
+const relOf = (write) => (write.kind === 'store' ? STORE_ROOT_REL : write.file.rel);
+
+// The fate of every path for the lines: a write that ran carries its result, an admitted write the
+// run never reached is `stopped`, and a path with no admitted write is `withheld` behind a custom
+// file or `none` when nothing was needed.
+const fateOf = (rel, { writes, fates, withheld, stopped }) => {
+  if (fates.has(rel)) return fates.get(rel);
+  if (writes.some((w) => relOf(w) === rel)) return stopped ? 'stopped' : 'would';
+  return withheld ? 'withheld' : 'none';
+};
+const composeLines = ({ reader, checker, store, writes, fates, withheld, stopped }) => {
+  const fate = (rel) => fateOf(rel, { writes, fates, withheld, stopped });
+  const lines = [...reader, ...checker].map((f) => scriptLine(f, fate(f.rel)));
+  const storeFate = fate(STORE_ROOT_REL);
+  if (store.state === 'present' || storeFate !== 'none') lines.push(storeLine(store, storeFate));
+  return lines;
+};
+
+// A per-file loop can stop partway; the run says which files already landed — never "nothing happened".
+const partialNote = (count) =>
+  (count > 0 ? [`the writes stopped PARTWAY — the ${count} file(s) named above were already written and are NOT rolled back`] : []);
+
+// ── the ensure ────────────────────────────────────────────────────────────────────────────────────
+
+// The store body is read and rendered BEFORE the first write, so a missing or unrenderable template
+// refuses with nothing written.
+const renderStoreRoot = (kitRoot, read, today) => {
+  const body = String(read(join(kitRoot, ...STORE_ROOT_TEMPLATE), 'utf8')).replaceAll(DATE_PLACEHOLDER, today);
+  if (body.includes('{{')) throw new Error('the bundled template carries a placeholder this kit cannot render — reinstall the kit');
+  return body;
+};
+
+export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
+  if (!isNodeProject(cwd, lstat)) {
+    return ok('skipped-no-node', [`${SCRIPTS_DIR}/: no package.json at the project root — the spec reader and checker are Node scripts; nothing written`]);
+  }
+  const survey = (name) => surveyScript({ cwd, kitRoot, name, read, lstat });
+  const reader = READER_PAIR.map(survey);
+  const checker = CHECKER_PAIR.map(survey);
+  const store = surveyStoreRoot(cwd, lstat);
+  for (const f of [...reader, ...checker]) {
+    if (f.state === 'bundle-unreadable') return loud('bundle-unreadable', `${f.rel}: the bundled script could not be read, so nothing was written — reinstall the kit. ${f.error}`);
+  }
+  for (const f of [...reader, ...checker, store]) {
+    if (f.state === 'wrong-kind') return loud('wrong-node-kind', `${f.rel}: exists but is ${f.wrongKind} — nothing was read or written; resolve it by hand, then re-run`);
+  }
+
+  const { writes, withheld } = decideWrites({ reader, checker, store });
+  const kinds = new Set(writes.map((w) => w.kind));
+  // ONE token by precedence — a write that happened (or, dry, would happen) always outranks the
+  // preserved-custom report, which names a run that wrote nothing behind an edited pair.
+  const tokenFor = (seeded, refreshed) => {
+    if (seeded) return dryRun ? 'would-seed' : 'seeded';
+    if (refreshed) return dryRun ? 'would-refresh' : 'refreshed';
+    return withheld ? 'customized-preserved' : 'already-present';
+  };
+  const fates = new Map();
+  const linesNow = (stopped) => composeLines({ reader, checker, store, writes, fates, withheld, stopped });
+  const writtenCount = () => [...fates.values()].filter((fate) => fate === 'written').length;
+  if (dryRun) return ok(tokenFor(kinds.has('seed') || kinds.has('store'), kinds.has('refresh')), linesNow(false));
+
+  let storeBody = null;
+  if (kinds.has('store')) {
+    try {
+      storeBody = renderStoreRoot(kitRoot, read, deps.today ?? todayIso());
+    } catch (err) {
+      return loud('template-unreadable', `${STORE_ROOT_REL}: ${causeOf(err)}`, ...linesNow(true));
+    }
+  }
+  const writeOne = ({ kind, file }) => {
+    if (kind === 'store') return writeProjectFileCreateOnly(cwd, STORE_ROOT_REL, storeBody, deps, { noun: 'the spec store root' });
+    if (kind === 'seed') return writeProjectFileCreateOnly(cwd, file.rel, String(file.bundle), deps, { noun: 'a seeded spec-layer script' });
+    return writeContainedFileAtomic(cwd, join(cwd, file.rel), String(file.bundle), deps, { label: file.rel });
+  };
+  // A seed that lost the create-only race is re-PROVEN before anything that depends on it runs: the
+  // file that appeared must carry the bundled body, or the tree is changing underneath this run.
+  const stoodCurrent = ({ kind, file }) => kind === 'store' || classifyDeployedScript(read(join(cwd, file.rel)), file.name, file.bundle) === 'current';
+  const notes = [];
+  for (const write of writes) {
+    const rel = relOf(write);
+    let result;
+    try {
+      result = writeOne(write);
+    } catch (err) {
+      return loud('write-refused', `${rel}: ${causeOf(err)}`, ...linesNow(true), ...notes, ...partialNote(writtenCount()));
+    }
+    if (write.kind !== 'refresh' && !result.created && !stoodCurrent(write)) {
+      return loud('race-unresolved', `${rel}: appeared while this run was seeding it and does not carry the bundled body — something is writing there underneath this run; nothing further written, re-run when the tree is settled`, ...linesNow(true), ...notes, ...partialNote(writtenCount()));
+    }
+    fates.set(rel, write.kind !== 'refresh' && !result.created ? 'stood' : 'written');
+    notes.push(...tmpNote(rel, result.tmpLeftBehind));
+  }
+  const landed = (kind) => writes.some((w) => w.kind === kind && fates.get(relOf(w)) === 'written');
+  return ok(tokenFor(landed('seed') || landed('store'), landed('refresh')), [...linesNow(false), ...notes]);
+};

package/tools/ensure-vocabulary.mjs

@@ -8,12 +8,16 @@
 // read-only tool's import graph. Vocabulary here, behaviour in ensure-ops.mjs.
 
 // The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
-export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts', 'index']);
+// `specs` sits after `scripts` (its reader pair is a scripts/ seed too) and BEFORE `index`: the store
+// root it seeds is a docs/ai file the navigator must count.
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts', 'specs', 'index']);
 
 // Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
-// walks this set), and each has exactly one `would-` counterpart below.
-export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'regenerated']);
-export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-regenerate']);
+// walks this set), and each has exactly one `would-` counterpart below. `refreshed` is the spec-layer
+// ensure's checker-pair refresh — a deployed script on a body a release shipped, rewritten to the
+// bundled one (a custom body is never refreshed).
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate']);
 
 // The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
 // token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
@@ -65,6 +69,7 @@ export const RELAYED_FAILURE_CAUSES = FAILURE_CAUSES;
 export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'seeded',
   'note-refreshed',
+  'refreshed',
   'regenerated',
   'already-current',
   'customized-preserved',

package/tools/known-footprint.mjs

@@ -69,6 +69,8 @@ export const KIT_OWN_PATHS = [
   '/scripts/migrate-gates-branches.test.mjs',
   '/scripts/migrate-gates.mjs',
   '/scripts/migrate-gates.test.mjs',
+  '/scripts/spec-schema.mjs',
+  '/scripts/spec-schema.test.mjs',
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',

package/tools/script-priors.mjs

@@ -0,0 +1,41 @@
+// script-priors.mjs — the APPEND-ONLY catalog of every enforcement-script body this family has shipped
+// into a project's `scripts/`, as sha256 digests, and the ONE classifier the spec-layer ensure asks
+// before it refreshes a deployed script: `current` (byte-equal to the bundled copy) · `prior` (a body
+// a release shipped, never edited since) · `custom` (anything else — preserved verbatim, never
+// overwritten). The lens-region idiom (AD-041) over whole script bodies.
+//
+// Append discipline: when a release changes one of PRIOR_FILES, append the OUTGOING body's row here
+// in the same release and copy its bytes to test/fixtures/script-priors/<firstShipped>/<file>.txt —
+// script-priors.test.mjs holds the two sides equal both ways and pins the row count. Rows are never
+// edited or removed: a deployment on any shipped body must keep classifying `prior`.
+//
+// Pure leaf: node:crypto only. No side effects on import.
+
+import { createHash } from 'node:crypto';
+
+// The deployed scripts the spec-layer ensure may REFRESH (the checker pair that imports the reader).
+// Every other deployed script is outside the refresh lane by design.
+export const PRIOR_FILES = Object.freeze(['check-docs-size.mjs', 'check-docs-size.test.mjs']);
+
+const prior = (file, firstShipped, lastShipped, digest) => Object.freeze({ file, firstShipped, lastShipped, digest });
+
+// One row per DISTINCT shipped body (memory package versions; the body is the memory canon the kit
+// mirrors). `firstShipped`..`lastShipped` is the inclusive release range that carried the body.
+export const SCRIPT_PRIORS = Object.freeze([
+  prior('check-docs-size.mjs', '4.0.0', '4.3.0', '84fb3673b034d4b2ba5bedf4a3e47899f98da3971c17902d1f2a548d07dc53bf'),
+  prior('check-docs-size.mjs', '4.4.0', '4.5.0', '7a5cd7f98571c3248d0378623172e9c60073b8d8761bce7a95c263f99bfb3a42'),
+  prior('check-docs-size.mjs', '4.5.1', '4.5.4', 'fef3555b14a5ade46071bac18bd6dfc87daec39dd63ce1f7965864c3e51558d9'),
+  prior('check-docs-size.test.mjs', '4.0.0', '4.5.4', '88fbb3d7f097d74771b7c5d9ad99fcd58b274ae33f391e1ff01f4b138b9236cd'),
+]);
+
+export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+// classifyDeployedScript(deployedBytes, file, bundleBytes, priors?) → 'current' | 'prior' | 'custom'.
+// The bundled body is compared FIRST, so a bundle that happens to equal a catalogued body still
+// reads as current; the catalog is consulted by file name, so a body shipped under another name is
+// never a prior for this one.
+export const classifyDeployedScript = (deployedBytes, file, bundleBytes, priors = SCRIPT_PRIORS) => {
+  const digest = digestOf(deployedBytes);
+  if (digest === digestOf(bundleBytes)) return 'current';
+  return priors.some((row) => row.file === file && row.digest === digest) ? 'prior' : 'custom';
+};

package/tools/upgrade-runlist.mjs

@@ -38,6 +38,7 @@ export const UPGRADE_RUNLIST = Object.freeze([
     [
       'seeded',
       'note-refreshed',
+      'refreshed',
       'regenerated',
       'already-current',
       'customized-preserved',