@sabaiway/agent-workflow-kit 7.5.0 → 8.0.0

package/CHANGELOG.md

@@ -4,6 +4,78 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 8.0.0 — the bundled reader gets the scenario floor, and the refresh lane carries it out (AD-117)
+
+Memory **5.0.0** gives the spec reader one new refusal — a `## Scenarios` section carrying no
+scenario line — and this kit ships those bytes. Nothing in the kit's own logic changed shape; what
+changed is what the deployed reader says about a document, and therefore what a project's spec gate
+says about its store.
+
+> ### ⚠ BREAKING — inherited from memory 5.0.0
+>
+> `spec-check` (both lanes) and the `spec-check` gate row relay the reader's verdict, so a spec that
+> pins NOTHING now turns a deployment red with no edit of its own. The remedy is one line per
+> scenario — `- S<N> <name> :: unbound` while no test pins it. The refusal is the migration signal:
+> a contract that pins nothing is the one shape the layer exists to refuse.
+
+- **`references/scripts/spec-schema{,.test}.mjs`** — refreshed to the 5.0.0 bodies; the four mirrored
+  copies stay byte-identical, `sync-mirrors --check` green.
+- **`tools/script-priors.mjs`** — the catalog gains the two OUTGOING `4.7.0..4.7.0` reader rows
+  (`spec-schema.mjs`, `spec-schema.test.mjs`), read from the released bytes, so an unmodified 4.7.0
+  deployment is recognised as unmodified and converges on the next kit touch instead of stranding as
+  `custom`. The independent `FROZEN_PRIORS` pin in the test moves with it — 8 catalog rows, none
+  equal to the bundled body.
+- **Obligation discharged: KIT-SUBTREE-CHANGED-WITHOUT-A-BUMP.** Slice 4 wrote 19 spec-binding
+  markers into this package's subtree and shipped no bump. This release carries them.
+
+
+## 7.6.0 — `spec-check`: the spec store judged against what the session SAYS it changed (AD-115)
+
+The feature-spec layer gets its structural checker. The change source is EXPLICIT and never git — a
+session states what it did, and the checker decides whether the store on disk says the same thing.
+"Well-formed" keeps its ONE definition: every per-document verdict is RELAYED from the shipped
+reader's 7.5.0 `structure` extraction, and this release adds no second parser.
+
+- **`tools/spec-check-ops.mjs` — one accepted spelling per document.** Four verbs
+  (`add` | `modify` | `remove` | `rename=<old>:<new>`) over POSIX repo-relative `.md` paths inside
+  `docs/ai/specs/` whose every segment is D-schema shaped. Nothing is normalized away: `./x.md`,
+  `a//b.md`, `a/../b.md`, a backslash, a drive letter, an absolute path and a trailing-slash
+  directory all REFUSE rather than resolving to some other path — so a dedup can be an equality, and
+  because no accepted target can carry a `:` the rename separator is unambiguous. A path holds at
+  most ONE role (self-rename, fan-out, fan-in, chain and any two-role clash refuse); the store root
+  is never a target; any error empties the whole op list.
+- **`tools/spec-check.mjs` — the judge, with no filesystem of its own.** `{read, probe, realpath,
+  list}` are injected and an uninjected one throws. The SESSION lane judges the closure of the
+  declared ops (targets plus each one's listing parent) on the post-state, the reader verdict, the
+  per-kind line cap, the scenario bindings (the marker must occur EXACTLY once in the file the
+  scenario names) and the containment of every path each document names. A `## Module` path must
+  also EXIST with the kind it declares — a `dir/` root resolving to a directory, a file-list entry
+  to a regular file — so a contract can no longer name code that is not there. `--all` judges the
+  whole store instead and adds the four questions no document can answer about itself: an unlisted
+  child (DISTINCT from an orphan), acyclicity, store-wide slug uniqueness and module overlap.
+- **Fail-closed means PROVEN contained.** A path whose realpath does not resolve is never read.
+  Containment asks the platform's own path model, because a textual prefix test reads
+  `/repo\outside` as a child of `/repo` on POSIX and mis-reads a filesystem root in both directions.
+  Every listed edge is resolved, contained and probed before it may enter the reachability graph — a
+  phantom target would otherwise be marked reached and launder an orphan into a reached document.
+  The census admits a CLOSED set — plain directories and regular `.md` files — and states everything
+  else: an unlistable directory, one that resolves outside the root, any non-regular entry, and a
+  regular file that is not a spec document. A census that observed nothing keeps its own refusal
+  instead of collapsing into a usage error. The leaf read is descriptor-bound and no-follow.
+- **`tools/spec-check-cli.mjs` — the IO shell.** `--op` (repeatable) unions `--ops-file`, `--all` is
+  exclusive of both, `--root` defaults to the cwd. The register is never defaulted: guessing which
+  file states the change set would attest a post-state nobody declared. Blank and `#` lines parse
+  away, CRLF reads like LF, and every other line is passed on UNTRIMMED so both op sources accept
+  exactly the same strings. Exit 0 clean, 1 findings, 2 usage.
+- **`tools/procedures.mjs` — the advisor names it.** A `plan-execution` render now carries the
+  populated `spec-check` commands for both lanes and the session register they read, plus the
+  additive `specCheck` `--json` key. Advisory, like the finding-scope block beside it: nothing
+  records that it ran.
+- **Proof.** Every suite authored RED first and observed failing before its module existed; the
+  D-scale gate measures the checker's OWN median (573 ms) beside the unchanged hook median against
+  the 1500 ms budget, so a slower checker can never pass by sitting inside the hook's headroom.
+  Tarball count 247 -> 250.
+
 ## 7.5.0 — the reader pair joins the known-prior refresh lane; the mirrored reader gains the structure verdict (AD-114)
 
 Slice 2b's `spec-check` will need a structural read of a spec document, and the reader is the ONE

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '7.5.0'
+  version: '8.0.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "7.5.0",
+  "version": "8.0.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.5.0",
+  "version": "8.0.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/procedures.md

@@ -19,6 +19,8 @@ Run **`node ${CLAUDE_SKILL_DIR}/tools/procedures.mjs <activity> [--override <slo
 
 **Declared source-size practice block (upfront knowledge, D-17 U1).** When the project declares a source-size practice in `docs/ai/source-size.json`, the advisor also renders `Declared source-size practice (docs/ai/source-size.json) — known BEFORE the code is written:` — the caps, what is recorded and the canonical WHY sentence (the plan-time layout itself is the planning canon's Module ledger). `--json` carries the SAME lines under **`declaredPractice`** (an empty array when nothing is declared), so the human and structured renders never diverge. The four config states each read as themselves: **ABSENT** renders nothing at all (a project declaring no practice is handed no invented limits), **AUTHORED** and **INCOMPLETE** are pre-mint (the second names the half-written machine key), **MINTED** carries the recorded counts. A declaration that cannot be read (malformed, unknown-keyed, a dangling symlink) renders ONE loud `UNREADABLE` line and the advisor **still exits 0** — the practice's own checker owns the exit code for its config (exit 2 there) and its declared gate reds the gate matrix. Read through the practice's pure read core, so this advisor never reaches its writer half.
 
+**Spec-store block (the feature-spec layer, `plan-execution` only).** After a `plan-execution` render the advisor also prints `Spec store (the feature-spec layer) — …`: the two POPULATED `spec-check` commands and the session register they read. **Session lane** — `--ops-file docs/plans/spec-ops.list` (or repeated `--op <add|modify|remove>=<path>` / `rename=<old>:<new>`) judges the closure of the declared change: the targets plus each one's listing parent, on their post-state, their reader verdict, their per-kind line cap, their scenario bindings and the containment of every path they name. **Store lane** — `--all` judges the whole store instead and adds the four cross-document invariants (an unlisted child, DISTINCT from an orphan · acyclicity · store-wide slug uniqueness · module overlap); an absent store root refuses the run rather than reporting an empty clean store. The two lanes are exclusive. **Register lifecycle:** `docs/plans/spec-ops.list` is *session scratch* — the session writes it, the plan's Phase Cleanup deletes it — and it is **never defaulted** by the tool, because an unnamed register would attest a post-state nobody declared (the `fold-scope --queue` precedent). `--json` carries the same lines under **`specCheck`** (an empty array outside `plan-execution`). Advisory like the finding-scope block: nothing records that it ran. Exit `0` clean · `1` findings · `2` usage.
+
 **Cap-soft-skip degradation (the feature's only AUTO route).** The activity procedures are auto-discoverable only through the one-line **`workflow:methodology`** pointer (this kit + the engine carry `disable-model-invocation:true`, so NL like "write a plan" does **not** auto-load this skill). On a deployment whose methodology pointer was cap-soft-skipped — or whose pre-existing customized pointer lacks the procedures clause — the procedures are still reachable by **explicitly** invoking `/agent-workflow-kit procedures`; surface that plainly rather than treating it as a gap.
 
 **Invariants:** read-only · never writes · never commits · never runs a subscription CLI · the deterministic resolution is the kit's, the recipe execution is the orchestrator's.

package/references/scripts/spec-schema.mjs

@@ -38,7 +38,7 @@ export const SPEC_SCHEMA = Object.freeze({
     'frontmatter', 'frontmatter-key', 'substrate-key', 'type', 'kind', 'maxlines', 'status', 'revision',
     'root-owns', 'slug', 'kind-path', 'root-uplink', 'title', 'section-missing', 'section-order',
     'section-forbidden', 'fence', 'children-link', 'children-duplicate', 'fan-out', 'scenario-line',
-    'scenario-number', 'scenario-marker', 'scenario-path', 'out-of-scope', 'module-line', 'module-empty',
+    'scenario-number', 'scenario-marker', 'scenario-path', 'scenarios-empty', 'out-of-scope', 'module-line', 'module-empty',
     'module-traversal', 'module-absolute', 'module-backslash', 'module-glob', 'module-mix', 'parts',
   ]),
 });
@@ -238,6 +238,10 @@ const checkScenarios = (parsed, slug, status, errors, warnings) => {
     }
     scenarios.push(scenario);
   }
+  if (scenarios.length === 0) {
+    errors.push({ rule: 'scenarios-empty', message: `at least one scenario line (\`${SPEC_SCHEMA.unboundMarker}\` while no test pins it)` });
+    return;
+  }
   const gap = scenarios.findIndex((scenario, i) => scenario.n !== i + 1);
   if (gap !== -1) errors.push({ rule: 'scenario-number', message: `scenario ${gap + 1} is numbered S${scenarios[gap].n} — N runs contiguously from 1` });
   for (const scenario of scenarios) {

package/references/scripts/spec-schema.test.mjs

@@ -131,6 +131,14 @@ describe('readSpecDocument — refuse, exactly one rule per defect', () => {
     refuses(specDoc({ scenarios: ['- S1 a :: /abs/login.test.mjs :: spec:login/S1'] }), 'login.md', 'scenario-path');
   });
 
+  it('scenarios-empty / no empty-marker escape', () => {
+    refuses(specDoc({ scenarios: [] }), 'login.md', 'scenarios-empty');
+    refuses(specDoc({ scenarios: ['*(empty)*'] }), 'login.md', 'scenario-line');
+    for (const status of SPEC_SCHEMA.statuses) {
+      expect(readSpecDocument(specDoc({ scenarios: ['- S1 x :: unbound'], fields: { status } }), 'login.md').errors).toEqual([]);
+    }
+  });
+
   it('out-of-scope / module-empty / module-* path refusals / module-mix / parts', () => {
     refuses(specDoc({ outOfScope: '' }), 'login.md', 'out-of-scope');
     refuses(specDoc({ outOfScope: 'nothing excluded' }), 'login.md', 'out-of-scope');

package/tools/procedures.mjs

@@ -319,6 +319,22 @@ const foldScopeAdvice = (activity, config, plans) => {
   ];
 };
 
+// The spec-store block (the feature-spec layer) — plan-execution ONLY and unconditional, like the
+// finding-scope block above: a change to docs/ai/specs/ is judged whoever reviews it. It carries
+// only what no canon can: the POPULATED checker commands, and the session register they read. The
+// register is NEVER defaulted by the tool — naming it here is the whole point of the block.
+export const SPEC_CHECK_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'spec-check-cli.mjs');
+const SPEC_OPS_REGISTER = `${PLANS_REL}/spec-ops.list`;
+const specCheckAdvice = (activity) => {
+  if (activity !== 'plan-execution') return [];
+  return [
+    'Spec store (the feature-spec layer) — state what this session changed, then let the checker judge the store against it:',
+    `  • node ${shellQuoteArg(SPEC_CHECK_TOOL)} --ops-file ${shellQuoteArg(SPEC_OPS_REGISTER)}   (or --op '<add|modify|remove>=docs/ai/specs/<slug>.md', repeatable; rename=<old>:<new>)`,
+    `  • node ${shellQuoteArg(SPEC_CHECK_TOOL)} --all — the whole store instead: unlisted child vs orphan, acyclicity, store-wide slug uniqueness, module overlap.`,
+    `  • ${SPEC_OPS_REGISTER} is SESSION SCRATCH: this session writes it, the plan's Cleanup deletes it. It is never defaulted — an unnamed register would attest a post-state nobody declared. Advisory: nothing records that it ran.`,
+  ];
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
@@ -466,7 +482,7 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck }) => {
   const lines = [
     section,
     '',
@@ -486,6 +502,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   const advice = reviewLoopAdvice(slots, activity);
   if (advice.length) lines.push('', ...advice);
   if (foldScope.length) lines.push('', ...foldScope);
+  if (specCheck.length) lines.push('', ...specCheck);
   lines.push('', ...costLanesAdvice());
   if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
@@ -495,7 +512,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -510,6 +527,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   costLanes: costLanesAdvice(),
   // ADDITIVE (the fold channel): the finding-scope block, structured (empty outside plan-execution).
   foldScope,
+  // ADDITIVE (spec layer 2b): the spec-store block, structured (empty outside plan-execution).
+  specCheck,
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
   // ADDITIVE (D-17 U1): the SAME composed lines the human render prints — one array, two renders, so
@@ -599,9 +618,10 @@ export const main = (argv, ctx = {}) => {
     const flowHalves = config?.flow == null ? null : flowHalvesAdvice(config.flow, flowProbe(cwd));
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
     const foldScope = foldScopeAdvice(activity, config, plans);
+    const specCheck = specCheckAdvice(activity);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }

package/tools/script-priors.mjs

@@ -31,6 +31,8 @@ export const SCRIPT_PRIORS = Object.freeze([
   prior('check-docs-size.test.mjs', '4.0.0', '4.5.4', '88fbb3d7f097d74771b7c5d9ad99fcd58b274ae33f391e1ff01f4b138b9236cd'),
   prior('spec-schema.mjs', '4.6.0', '4.6.1', 'f8ee23d81e90fd4225ca4ece288cba41982c4430290bc6d033f5ca18d2d283f4'),
   prior('spec-schema.test.mjs', '4.6.0', '4.6.1', 'a12d6d3f5d32c6dabdee7e15af7d2ab15a0ced37515d1844fe0951f60cddbc99'),
+  prior('spec-schema.mjs', '4.7.0', '4.7.0', '40b5b038d5ec5ed53c327c6d269d22fe5fa2bed99ae711fbf84306ad047be452'),
+  prior('spec-schema.test.mjs', '4.7.0', '4.7.0', 'fde896419924223e54cfcabfdb1ef5807df5386fac700ed7c1463b6e7f81501b'),
 ]);
 
 export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');

package/tools/spec-check-cli.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// The CLI half of the structural checker: argv and fs, no rule (the rules are spec-check.mjs and
+// spec-check-ops.mjs). The change source is EXPLICIT and never git — a session states what it did.
+//
+//   node spec-check-cli.mjs --op modify=docs/ai/specs/login.md [--op ...] [--root <dir>]
+//   node spec-check-cli.mjs --ops-file docs/plans/spec-ops.list
+//   node spec-check-cli.mjs --all
+//
+// `--op` and `--ops-file` UNION and dedup by identity; `--all` is exclusive of both. The register
+// `--ops-file` names is session scratch, and it is never defaulted: guessing which file states the
+// change set would attest a post-state nobody declared (the fold-scope --queue precedent). A named
+// register that does not exist is usage, not an empty change set.
+//
+// The leaf read is the family's descriptor-bound no-follow door (fs-read-nofollow.mjs) — a pathname
+// swapped after the probe cannot change the bytes judged. Read-only, records nothing: ADVISORY, so
+// a skipped or late call is indistinguishable from one that ran.
+//
+// Exit codes: 0 ACCEPT; 1 one or more findings; 2 usage — a missing/unknown flag, a bad op, an
+// unreadable register, a --root that is not a directory, or an --all run with no store root.
+// Dependency-free, Node >= 22.
+
+import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { isDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { SPEC_OPS_GRAMMAR, parseSpecOps } from './spec-check-ops.mjs';
+import { checkSpecs } from './spec-check.mjs';
+
+const { verbs, separator, storePrefix } = SPEC_OPS_GRAMMAR;
+
+const HELP = `spec-check — judge the feature-spec store against what this session says it changed.
+
+Usage:
+  node spec-check-cli.mjs [--root <dir>] --op <op> [--op <op> ...]
+  node spec-check-cli.mjs [--root <dir>] --ops-file <file>
+  node spec-check-cli.mjs [--root <dir>] --all
+
+An op is one of ${verbs.slice(0, -1).map((v) => `${v}=<path>`).join(' | ')} | rename=<old>${separator}<new>, and every
+path is a POSIX repo-relative .md document inside ${storePrefix} whose segments are kebab slugs.
+Nothing is normalized away and the store root is never an op target, so one document has exactly
+one accepted spelling.
+
+  --op        repeatable; unions --ops-file and dedups by identity.
+  --ops-file  one op per line; blank lines and # comments parse away. Never defaulted — name the
+              register this session wrote (e.g. docs/plans/spec-ops.list).
+  --all       judge the WHOLE store instead: reachability (unlisted child vs orphan), acyclicity,
+              store-wide slug uniqueness and module overlap. Exclusive of both op sources.
+  --root      the repo root the paths are relative to (default: the process cwd).
+
+The check is advisory — nothing records that it ran, so a skipped or late call is indistinguishable
+from one made before the edit.
+
+Exit codes: 0 ACCEPT; 1 findings; 2 usage (bad flag or op, unreadable register, bad --root).`;
+
+const FLAGS = ['op', 'ops-file', 'all', 'root'];
+const REPEATABLE = ['op'];
+const BOOLEAN = ['all'];
+
+const parseArgs = (argv) => {
+  const opts = { op: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const eq = arg.indexOf('=');
+    const name = arg.startsWith('--') ? arg.slice(2, eq === -1 ? undefined : eq) : null;
+    if (!name || !FLAGS.includes(name)) throw new Error(`unexpected argument "${arg}" (flags: ${FLAGS.map((f) => `--${f}`).join(', ')})`);
+    if (BOOLEAN.includes(name)) {
+      if (eq !== -1) throw new Error(`--${name} takes no value`);
+      opts[name] = true;
+      continue;
+    }
+    let value = eq === -1 ? argv[i + 1] : arg.slice(eq + 1);
+    if (eq === -1) i += 1;
+    if (value === undefined || (eq === -1 && value.startsWith('--'))) throw new Error(`--${name} requires a value`);
+    if (REPEATABLE.includes(name)) opts[name].push(value);
+    else opts[name] = value;
+  }
+  return opts;
+};
+
+// The probe: a fail-closed lstat CLASSIFICATION, never a boolean. A symlink is its own state (it is
+// never followed to decide what sits at a path), and anything that cannot be stat-ed at all is
+// "unreadable" rather than "absent" — the two lead to different verdicts and must not collapse.
+export const probe = (path) => {
+  try {
+    const st = lstatSync(path);
+    return st.isSymbolicLink() ? 'symlink' : st.isDirectory() ? 'dir' : st.isFile() ? 'file' : 'unreadable';
+  } catch (err) {
+    return err && err.code === 'ENOENT' ? 'absent' : 'unreadable';
+  }
+};
+
+export const realpath = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+};
+
+export const list = (path) => {
+  try {
+    return readdirSync(path);
+  } catch {
+    return null;
+  }
+};
+
+// A LINE ENDING is not content: the split takes CRLF as well as LF, so a register saved on Windows
+// reads like one saved anywhere else. Blank and `#` lines parse away; every OTHER line is handed on
+// UNTRIMMED, because trimming here would let the file lane accept a spelling the --op lane refuses —
+// exactly the alias the frozen grammar denies. The ops parser refuses that whitespace out loud.
+const opsFileLines = (text) => text.split(/\r?\n/).filter((line) => line.trim() !== '' && !line.trim().startsWith('#'));
+
+// main(argv, deps) -> { code, stdout, stderr }. Never calls process.exit itself (the direct-run
+// guard does), and never reads anything the caller did not point it at.
+export const main = (argv, deps = {}) => {
+  if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+  const read = deps.readFileSync ?? readFileSync;
+  const cwd = deps.cwd ?? (() => process.cwd());
+  const usage = (message) => ({ code: 2, stdout: '', stderr: `spec-check: ${message}` });
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    return usage(err.message);
+  }
+  if (opts.all && (opts.op.length > 0 || opts['ops-file'])) {
+    return usage('--all judges the whole store and is exclusive of --op and --ops-file — run one lane or the other');
+  }
+  const root = resolve(cwd(), opts.root ?? '.');
+  if (probe(root) !== 'dir') return usage(`--root "${opts.root ?? cwd()}" is not a directory`);
+  let specs = [...opts.op];
+  if (opts['ops-file']) {
+    const register = resolve(cwd(), opts['ops-file']);
+    try {
+      specs = [...specs, ...opsFileLines(read(register, 'utf8'))];
+    } catch (err) {
+      return usage(`--ops-file "${opts['ops-file']}" is unreadable — ${(err && err.message) || err}`);
+    }
+  }
+  let ops = [];
+  if (!opts.all) {
+    const parsed = parseSpecOps(specs);
+    if (parsed.errors.length > 0) {
+      return usage(parsed.errors.map((e) => `${e.code} — ${e.message}`).join('\nspec-check: '));
+    }
+    ops = parsed.ops;
+  }
+  const decided = checkSpecs({ root, ops, all: Boolean(opts.all) }, { read: readRegularFileNoFollow, probe, realpath, list });
+  return { code: decided.exit, stdout: decided.lines.join('\n'), stderr: '' };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exit(result.code);
+}

package/tools/spec-check-ops.mjs

@@ -0,0 +1,181 @@
+// spec-check-ops.mjs — the frozen CHANGE-OP grammar of the structural checker (spec layer 2b).
+//
+// The change source is EXPLICIT and never git: a session states what it did to the spec store, and
+// this module decides whether that statement is even sayable. Four verbs, one separator, one
+// spelling per path:
+//
+//   add=<p> | modify=<p> | remove=<p> | rename=<old>:<new>
+//
+// A target is a POSIX repo-relative `.md` path inside docs/ai/specs/ whose every segment is
+// D-schema-shaped (kebab dirs; a `<slug>.md` or `index.md` leaf). Because no accepted target can
+// carry a `:`, the rename separator is unambiguous — which is why the grammar can stay one line.
+//
+// NOTHING is normalized away: `./x.md`, `a//b.md` and `a/../b.md` REFUSE rather than resolving to
+// some other path, so one document has exactly ONE accepted spelling and a dedup can be an equality.
+// The store root is never an op target — it is the navigator, not a contract.
+//
+// The D-schema values come from the ONE reader (references/scripts/spec-schema.mjs): no second
+// source of the prefix, the navigator filename or the slug pattern. Pure strings in, ops out — the
+// filesystem belongs to spec-check.mjs. Dependency-free, Node >= 22.
+
+import { SPEC_SCHEMA } from '../references/scripts/spec-schema.mjs';
+
+const STORE = SPEC_SCHEMA.storePrefix;
+const NAV = SPEC_SCHEMA.navigatorFile;
+const SUFFIX = '.md';
+const SEPARATOR = ':';
+
+export const SPEC_OPS_GRAMMAR = Object.freeze({
+  verbs: Object.freeze(['add', 'modify', 'remove', 'rename']),
+  separator: SEPARATOR,
+  storePrefix: STORE,
+  navigator: NAV,
+  suffix: SUFFIX,
+  slugPattern: SPEC_SCHEMA.slugPattern,
+  storeRoot: `${STORE}${NAV}`,
+  roles: Object.freeze(['add', 'modify', 'remove', 'rename-from', 'rename-to', 'listing-parent']),
+});
+
+const SLUG_RE = new RegExp(SPEC_SCHEMA.slugPattern);
+const DRIVE_RE = /^[A-Za-z]:/;
+const VERBS = SPEC_OPS_GRAMMAR.verbs;
+
+// The ONE target judgement, ordered from the most literal defect to the most structural. The store
+// PREFIX is asked before the dot segments on purpose: `./docs/ai/specs/x.md` is not a store path
+// that needs normalizing, it is a path outside the store, and saying so is the honest refusal.
+const targetDefect = (target) => {
+  if (target.includes('\\')) return { code: 'op-target', reason: 'a backslash is not a path separator here' };
+  if (DRIVE_RE.test(target)) return { code: 'op-target', reason: 'a drive letter is not a repo-relative path' };
+  if (target.startsWith('/')) return { code: 'op-target', reason: 'an absolute path is not repo-relative' };
+  if (target.includes('//')) return { code: 'op-target', reason: 'a doubled slash is not a path segment' };
+  if (target.endsWith('/')) return { code: 'op-target', reason: 'a directory is never an op target — name the document' };
+  if (!target.startsWith(STORE)) return { code: 'op-target', reason: `the target is outside the store ${STORE}` };
+  if (target.split('/').some((segment) => segment === '.' || segment === '..')) {
+    return { code: 'op-target', reason: 'a dot segment is never resolved away — write the path as it is' };
+  }
+  if (!target.endsWith(SUFFIX)) return { code: 'op-target', reason: `a spec document is a ${SUFFIX} file` };
+  if (target === SPEC_OPS_GRAMMAR.storeRoot) {
+    return { code: 'op-root', reason: 'the store root is the navigator, never an op target' };
+  }
+  const segments = target.slice(STORE.length).split('/');
+  const leaf = segments[segments.length - 1];
+  const badDir = segments.slice(0, -1).find((segment) => !SLUG_RE.test(segment));
+  if (badDir !== undefined) return { code: 'op-segment', reason: `"${badDir}" is not a slug (${SPEC_SCHEMA.slugPattern})` };
+  const stem = leaf.slice(0, -SUFFIX.length);
+  if (leaf !== NAV && !SLUG_RE.test(stem)) return { code: 'op-segment', reason: `"${stem}" is not a slug (${SPEC_SCHEMA.slugPattern})` };
+  return null;
+};
+
+// The slug a document owns — the folder name for an index.md, the file stem otherwise. The same
+// rule the reader applies to `rel`, kept here because the checker asks it of WHOLE PATHS.
+export const slugOf = (path) => {
+  const segments = path.slice(STORE.length).split('/');
+  const leaf = segments[segments.length - 1];
+  return leaf === NAV ? segments[segments.length - 2] ?? null : leaf.slice(0, -SUFFIX.length);
+};
+
+// The document that LISTS this one: `<dir>/index.md` for a leaf, ONE level up for an index.md
+// (a promoted root is listed by its parent, never by itself). The store root is listed by nothing.
+export const listingParentOf = (path) => {
+  const segments = path.slice(STORE.length).split('/');
+  const dirs = segments.slice(0, -1);
+  if (segments[segments.length - 1] === NAV) {
+    return dirs.length === 0 ? null : `${STORE}${[...dirs.slice(0, -1), NAV].join('/')}`;
+  }
+  return `${STORE}${[...dirs, NAV].join('/')}`;
+};
+
+// The shape a path plays. A path in TWO roles is refused rather than reconciled: "added and then
+// removed" states two different post-states for one probe, and guessing which one the session meant
+// is exactly the unresolved reference this module exists to refuse.
+const SHAPES = Object.freeze({ 'rename-from,rename-from': 'fan-out', 'rename-to,rename-to': 'fan-in', 'rename-from,rename-to': 'chain' });
+const roleConflict = (roles) => SHAPES[[...roles].sort().join(',')] ?? 'two roles';
+
+// parseSpecOps(specs) -> { ops, errors }. Every op is judged, so one call names EVERY defect; any
+// error at all empties `ops` — a partially-understood change set would attest a post-state nobody
+// declared.
+export const parseSpecOps = (specs) => {
+  const errors = [];
+  const ops = [];
+  const seen = new Set();
+  const roles = new Map();
+  const claim = (path, role, spec) => {
+    const held = roles.get(path);
+    if (held === undefined) roles.set(path, { role, spec });
+    else errors.push({ code: 'op-role', message: `"${spec}" and "${held.spec}" put ${path} in two roles (${roleConflict([held.role, role])})` });
+  };
+  for (const raw of specs ?? []) {
+    const spec = String(raw);
+    // Surrounding whitespace is REFUSED rather than trimmed: trimming would give one document a
+    // second accepted spelling, and the whole grammar rests on there being exactly one.
+    if (spec !== spec.trim()) {
+      errors.push({ code: 'op-grammar', message: `"${spec}" — leading or trailing whitespace is never trimmed away; write the op without it` });
+      continue;
+    }
+    const eq = spec.indexOf('=');
+    const verb = eq === -1 ? spec : spec.slice(0, eq);
+    const payload = eq === -1 ? '' : spec.slice(eq + 1);
+    if (!VERBS.includes(verb)) {
+      errors.push({ code: 'op-grammar', message: `"${spec}" — an op is verb=<target>, the verb one of ${VERBS.join('|')}` });
+      continue;
+    }
+    if (payload === '') {
+      errors.push({ code: 'op-grammar', message: `"${spec}" — an op is verb=<target>, and the target is never empty` });
+      continue;
+    }
+    if (seen.has(spec)) continue;
+    seen.add(spec);
+    const sides = verb === 'rename' ? payload.split(SEPARATOR) : [payload];
+    if (verb === 'rename' && sides.length !== 2) {
+      errors.push({ code: 'op-grammar', message: `"${spec}" — rename takes <old>${SEPARATOR}<new>: exactly one separator "${SEPARATOR}"` });
+      continue;
+    }
+    const defect = sides.map(targetDefect).find(Boolean);
+    if (defect) {
+      errors.push({ code: defect.code, message: `"${spec}" — ${defect.reason}` });
+      continue;
+    }
+    if (verb === 'rename' && sides[0] === sides[1]) {
+      errors.push({ code: 'op-role', message: `"${spec}" — a rename to itself (self) declares no change` });
+      continue;
+    }
+    if (verb === 'rename') {
+      claim(sides[0], 'rename-from', spec);
+      claim(sides[1], 'rename-to', spec);
+      ops.push({ verb, from: sides[0], to: sides[1] });
+    } else {
+      claim(payload, verb, spec);
+      ops.push({ verb, target: payload });
+    }
+  }
+  if (errors.length === 0 && ops.length === 0) {
+    errors.push({ code: 'op-empty', message: 'no op to judge — name at least one --op or --ops-file entry, or run --all' });
+  }
+  return { ops: errors.length > 0 ? [] : ops, errors };
+};
+
+// buildClosure(ops) -> [{ path, roles }] sorted: every op path PLUS the document that lists it.
+// A listing parent that is itself an op target keeps its op role; two ops under one parent name it
+// once; ops under different parents name both.
+export const buildClosure = (ops) => {
+  const entries = new Map();
+  const put = (path, role) => entries.set(path, [...new Set([...(entries.get(path) ?? []), role])]);
+  const targets = [];
+  for (const op of ops) {
+    if (op.verb === 'rename') {
+      put(op.from, 'rename-from');
+      put(op.to, 'rename-to');
+      targets.push(op.from, op.to);
+    } else {
+      put(op.target, op.verb);
+      targets.push(op.target);
+    }
+  }
+  for (const target of targets) {
+    const parent = listingParentOf(target);
+    if (parent !== null && !entries.has(parent)) put(parent, 'listing-parent');
+  }
+  return [...entries]
+    .map(([path, roles]) => ({ path, roles }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+};

package/tools/spec-check.mjs

@@ -0,0 +1,381 @@
+// spec-check.mjs — the structural checker of the feature-spec layer (spec layer 2b), ADVISORY.
+//
+// It answers ONE question per document: given what the session says it changed, does the store on
+// disk say the same thing? The change source is EXPLICIT (parsed ops, never git), and "well-formed"
+// has no second definition here — every per-document verdict is RELAYED from the ONE reader
+// (references/scripts/spec-schema.mjs) and its 2a `structure` extraction. This module adds only what
+// text alone cannot decide: does the post-state on disk match the declared op, is the document
+// listed by its parent, does its scenario marker really occur once in the file it names, and — under
+// --all — the five invariants that span documents.
+//
+// Two lanes:
+//   session   the closure of the declared ops (targets + their listing parents), judged per document.
+//   --all     every document under the store, plus: unlisted child (DISTINCT from orphan),
+//             acyclicity, store-wide slug uniqueness, module overlap. An ABSENT store root refuses.
+//
+// FAIL-CLOSED before every read. Containment is judged lexically AND by realpath over each
+// path-bearing field, and the parents of a leaf are judged BEFORE the leaf is opened. The LEAF read
+// itself is descriptor-bound and no-follow (the CLI half passes fs-read-nofollow.mjs in), so a
+// pathname swapped after the probe cannot change the bytes judged. A mid-run PARENT swap is a
+// STATED non-goal: this is an advisory checker, not a custody mechanism.
+//
+// No IO of its own: { read, probe, realpath, list } are injected. Dependency-free, Node >= 22.
+
+import { dirname as pathDirname, isAbsolute, relative, sep } from 'node:path';
+import { SPEC_SCHEMA, readSpecDocument, classifyPath } from '../references/scripts/spec-schema.mjs';
+import { SPEC_OPS_GRAMMAR, buildClosure, listingParentOf, slugOf } from './spec-check-ops.mjs';
+
+const STORE = SPEC_OPS_GRAMMAR.storePrefix;
+const NAV = SPEC_OPS_GRAMMAR.navigator;
+const STORE_ROOT = SPEC_OPS_GRAMMAR.storeRoot;
+const STORE_DIR = STORE.slice(0, -1);
+
+// The post-state each role declares. A listing parent declares NONE — it was not changed, it is read
+// because something else was. `present` DOES declare one: the census already OBSERVED that document
+// as a regular file, so a state that has changed underneath since is a fact to state, never a
+// document to drop quietly from a store the run would otherwise call clean.
+const DECLARED_STATE = Object.freeze({ add: 'file', modify: 'file', 'rename-to': 'file', remove: 'absent', 'rename-from': 'absent', present: 'file' });
+const missing = () => {
+  throw new Error('spec-check: an IO dependency was not injected — this module owns no filesystem of its own');
+};
+
+const dirOf = (rel) => rel.slice(0, rel.lastIndexOf('/'));
+const leafOf = (rel) => rel.slice(rel.lastIndexOf('/') + 1);
+const bare = (rel) => (rel.endsWith('/') ? rel.slice(0, -1) : rel);
+const lineCount = (text) => text.replace(/\n$/, '').split('\n').length;
+const occurrences = (text, needle) => text.split(needle).length - 1;
+// Containment is a question about path COMPONENTS, and only the platform's own path model answers
+// it. A textual prefix test reads "/repo\outside" as a child of "/repo" on a POSIX host — where the
+// backslash is an ordinary filename character — and it mis-reads a filesystem root ("/" or "C:\")
+// in both directions. `..` is compared as a whole SEGMENT, so a child named "..keep" stays inside.
+const contained = (rootReal, real) => {
+  const rel = relative(rootReal, real);
+  return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+};
+
+// The link string a parent must carry for this child — verbatim, so `./x.md` and `./x/index.md`
+// stay the distinct targets the 2a extraction froze them as.
+const expectedLink = (rel, parent) => `./${rel.slice(parent.length - NAV.length)}`;
+
+const verdictOf = (findings, documents, lane) => {
+  if (findings.length === 0) {
+    return { verdict: 'ACCEPT', exit: 0, findings, documents, lines: [`spec-check: ACCEPT — ${documents} document(s) clean (${lane})`] };
+  }
+  return {
+    verdict: 'REFUSE',
+    exit: 1,
+    findings,
+    documents,
+    lines: [
+      `spec-check: REFUSE — ${findings.length} finding(s) over ${documents} document(s) (${lane})`,
+      ...findings.map((f) => `  ${f.path}: ${f.rule} — ${f.message}`),
+    ],
+  };
+};
+const refusal = (message) => ({ verdict: 'REFUSE', exit: 2, findings: [], documents: 0, lines: [`spec-check: REFUSE — ${message}`] });
+
+// Every document of the closure, read ONCE: probe, then (only for a regular file) the descriptor-
+// bound read and the reader verdict. Containment of the containing directory is decided BEFORE the
+// read, so a directory that resolves outside the root is never opened through.
+const readClosure = (closure, ctx) => {
+  const { io, at, rootReal, add } = ctx;
+  const docs = new Map();
+  for (const { path, roles } of closure) {
+    if (classifyPath(path) !== 'file' || !path.startsWith(STORE)) {
+      add('contained', path, 'the path is not a repo-relative file inside the store');
+      continue;
+    }
+    const dirReal = io.realpath(at(dirOf(path)));
+    const dirContained = dirReal !== null && contained(rootReal, dirReal);
+    if (dirReal !== null && !dirContained) {
+      add('contained', path, `its directory ${dirOf(path)} resolves outside the root (${dirReal})`);
+      continue;
+    }
+    const state = io.probe(at(path));
+    const doc = { path, roles, state, verdict: null, lines: 0, ground: [], edges: [] };
+    docs.set(path, doc);
+    const declared = roles.map((role) => DECLARED_STATE[role]).find(Boolean);
+    if (declared && state !== declared) {
+      const source = roles.includes('present')
+        ? 'the census observed this document as a regular file'
+        : `the op declares this document ${declared === 'absent' ? 'gone' : 'present as a regular file'}`;
+      add('post-state', path, `${source}, the store now says "${state}"`);
+    }
+    if (state !== 'file') continue;
+    // Fail-closed is PROVEN contained, not "not proven to escape": a directory whose realpath does
+    // not resolve was never observed, so the leaf inside it is never opened.
+    if (!dirContained) {
+      add('contained', path, `its directory ${dirOf(path)} does not resolve, so the read is refused (fail closed)`);
+      continue;
+    }
+    const read = io.read(at(path));
+    if (read.outcome !== 'ok') {
+      add('unreadable', path, `the descriptor-bound read says ${read.outcome}${read.className ? ` (${read.className})` : ''}${read.code ? ` (${read.code})` : ''} — the probe is not what is judged`);
+      continue;
+    }
+    doc.lines = lineCount(read.content);
+    doc.verdict = readSpecDocument(read.content, path.slice(STORE.length));
+  }
+  return docs;
+};
+
+const linkTargetsOf = (doc) => [...(doc?.verdict?.structure?.children ?? []), ...(doc?.verdict?.structure?.parts ?? [])].map((link) => link.target);
+
+// Every LISTED edge is a claim about another document, and an unchecked claim is what lets a broken
+// or escaping target ride into the reachability graph as if it were reached. Each edge is resolved,
+// contained (lexically AND by realpath) and PROBED; only an observed regular file becomes an edge.
+const judgeEdges = (doc, ctx) => {
+  const { io, at, rootReal, add } = ctx;
+  for (const target of linkTargetsOf(doc)) {
+    const child = `${dirOf(doc.path)}/${target.slice(2)}`;
+    if (classifyPath(child) !== 'file' || !child.startsWith(STORE)) {
+      add('link', doc.path, `it lists ${target}, which is not a document inside the store`);
+      continue;
+    }
+    const real = io.realpath(at(child));
+    if (real === null || !contained(rootReal, real)) {
+      add('link', doc.path, `it lists ${target}, which ${real === null ? 'does not resolve' : `resolves outside the root (${real})`}`);
+      continue;
+    }
+    const state = io.probe(at(child));
+    if (state !== 'file') {
+      add('link', doc.path, `it lists ${target}, which the store reports as "${state}" — a listed child is a regular file`);
+      continue;
+    }
+    doc.edges.push(child);
+  }
+};
+
+// The per-document judgement, identical in both lanes: the relayed reader rules, the kind's own
+// line cap, the listed edges, the D4 scenario bindings and the containment of every path it names.
+const judgeDocument = (doc, ctx) => {
+  const { io, at, rootReal, add } = ctx;
+  const { path, verdict } = doc;
+  if (verdict === null) return;
+  for (const error of verdict.errors) add('reader', path, `${error.rule}: ${error.message}`, { readerRule: error.rule });
+  const cap = SPEC_SCHEMA.maxLines[verdict.kind];
+  if (cap !== undefined && doc.lines > cap) {
+    add('threshold', path, `${doc.lines} lines over the ${verdict.kind} cap of ${cap} — promote it to <slug>/index.md + parts`);
+  }
+  const structure = verdict.structure;
+  if (structure === null) return;
+  // A module names the code the contract governs. Ground that is absent, unreadable or of the OTHER
+  // kind is a claim about code that is not there — and only a PROVEN canonical path is kept, so the
+  // store-wide overlap comparison never mixes observed ground with a lexical guess.
+  for (const claimed of structure.module?.paths ?? []) {
+    const wantDir = claimed.endsWith('/');
+    const target = bare(claimed);
+    const real = io.realpath(at(target));
+    if (real === null) {
+      add('module', path, `the module path ${claimed} names ground that is not there`);
+      continue;
+    }
+    if (!contained(rootReal, real)) {
+      add('contained', path, `the module path ${claimed} resolves outside the root (${real})`);
+      continue;
+    }
+    const state = io.probe(at(target));
+    if (state !== (wantDir ? 'dir' : 'file')) {
+      add('module', path, `the module path ${claimed} is "${state}", not the ${wantDir ? 'directory' : 'file'} it declares`);
+      continue;
+    }
+    doc.ground.push(real);
+  }
+  judgeEdges(doc, ctx);
+  for (const scenario of structure.scenarios) {
+    if (scenario.binding === null) continue;
+    const { file, marker } = scenario.binding;
+    if (classifyPath(file) !== 'file') {
+      add('binding', path, `S${scenario.ordinal} names "${file}", which is not a repo-relative file`);
+      continue;
+    }
+    const real = io.realpath(at(file));
+    if (real === null) {
+      add('binding', path, `S${scenario.ordinal} binds ${file}, which does not resolve — an unobserved path is never opened`);
+      continue;
+    }
+    if (!contained(rootReal, real)) {
+      add('contained', path, `the S${scenario.ordinal} binding ${file} resolves outside the root (${real})`);
+      continue;
+    }
+    const state = io.probe(at(file));
+    if (state !== 'file') {
+      add('binding', path, `S${scenario.ordinal} binds ${file}, which the store reports as "${state}"`);
+      continue;
+    }
+    const read = io.read(at(file));
+    if (read.outcome !== 'ok') {
+      add('binding', path, `S${scenario.ordinal} binds ${file}, which cannot be read (${read.outcome})`);
+      continue;
+    }
+    const found = occurrences(read.content, marker);
+    if (found !== 1) add('binding', path, `the marker ${marker} occurs ${found} time(s) in ${file} — exactly once binds a scenario`);
+  }
+};
+
+// The listing judgement — a SESSION-lane rule: the document the ops touched must be listed by its
+// parent exactly once after an add/modify/rename-to, and not at all after a remove/rename-from.
+// Under --all the reachability invariants below own this ground instead, so it never doubles up.
+const judgeListing = (doc, docs, add) => {
+  const declared = doc.roles.map((role) => DECLARED_STATE[role]).find(Boolean);
+  if (!declared) return;
+  const parent = listingParentOf(doc.path);
+  if (parent === null) return;
+  const holder = docs.get(parent);
+  const link = expectedLink(doc.path, parent);
+  if (!holder || holder.state !== 'file' || holder.verdict === null) {
+    add('listed', doc.path, `its listing parent ${parent} cannot be read, so nothing states whether ${link} is listed`);
+    return;
+  }
+  const found = linkTargetsOf(holder).filter((target) => target === link).length;
+  if (declared === 'file' && found !== 1) add('listed', doc.path, `${parent} lists ${link} ${found} time(s) — a present document is listed exactly once`);
+  if (declared === 'absent' && found !== 0) add('listed', doc.path, `${parent} still lists ${link} — a removed document is listed by nobody`);
+};
+
+// Every `.md` document under the store, found by LISTING rather than by trusting any index. The walk
+// is what makes "unlisted" and "orphan" observable at all — so a branch it could not observe is a
+// FINDING, never an empty directory quietly walked past: an incomplete census that reported a clean
+// store would be the one answer this lane must never give. A directory is contained BEFORE it is
+// listed, and a non-regular `.md` sitting in the store is stated rather than skipped.
+const walkStore = (ctx) => {
+  const { io, at, rootReal, add } = ctx;
+  const found = [];
+  const stack = [STORE_DIR];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    const dirReal = io.realpath(at(dir));
+    if (dirReal === null || !contained(rootReal, dirReal)) {
+      add('census', dir, `the store directory ${dirReal === null ? 'does not resolve' : `resolves outside the root (${dirReal})`}, so what it holds was never observed`);
+      continue;
+    }
+    const names = io.list(at(dir));
+    if (names === null) {
+      add('census', dir, 'the store directory cannot be listed, so this branch of the census is unobserved');
+      continue;
+    }
+    for (const name of names) {
+      const rel = `${dir}/${name}`;
+      const state = io.probe(at(rel));
+      if (state === 'dir') stack.push(rel);
+      else if (state === 'file' && name.endsWith(SPEC_OPS_GRAMMAR.suffix)) found.push(rel);
+      // Every OTHER entry is stated, `.md` or not. A symlinked DIRECTORY is the hole a `.md`-only
+      // census leaves: an edge can be resolved THROUGH it while the documents behind it were never
+      // observed, read or judged — and --all would then accept a store it never fully saw.
+      else add('census', rel, `a ${state} sits inside the store — it holds regular ${SPEC_OPS_GRAMMAR.suffix} documents and plain directories only`);
+    }
+  }
+  return found.sort();
+};
+
+// Reachability from the store root over the extracted child/part links. Identity is the realpath of
+// the containing DIRECTORY plus the leaf name — that is what makes a symlinked folder pointing at an
+// ancestor a cycle rather than an infinite walk, and it is judged on the trail, not on the visited
+// set, so a diamond (two indexes listing one document) is not mistaken for a loop.
+const reachStore = (docs, ctx) => {
+  const { io, at } = ctx;
+  const reached = new Set();
+  const cycles = [];
+  const identity = (rel) => `${io.realpath(at(dirOf(rel))) ?? dirOf(rel)}/${leafOf(rel)}`;
+  const visit = (rel, trail) => {
+    const id = identity(rel);
+    if (trail.has(id)) {
+      cycles.push(rel);
+      return;
+    }
+    if (reached.has(rel)) return;
+    reached.add(rel);
+    const next = new Set([...trail, id]);
+    // PROVEN edges only (judgeEdges): a phantom target would launder an orphan into a reached
+    // document and hide exactly what this lane exists to find.
+    for (const child of docs.get(rel)?.edges ?? []) visit(child, next);
+  };
+  visit(STORE_ROOT, new Set());
+  return { reached, cycles };
+};
+
+// The four cross-document invariants (the fifth — an absent store root — refuses the run before any
+// of them can be asked). Each is a question no single document can answer about itself.
+const judgeStore = (docs, ctx) => {
+  const { add } = ctx;
+  const { reached, cycles } = reachStore(docs, ctx);
+  for (const rel of cycles) add('acyclic', rel, 'the child graph reaches this document from inside itself — a cycle, not a tree');
+  for (const [rel, doc] of docs) {
+    if (reached.has(rel) || doc.state !== 'file') continue;
+    const parent = listingParentOf(rel);
+    if (parent !== null && reached.has(parent)) {
+      add('unlisted-child', rel, `${parent} is reached from the store root but does not list ${expectedLink(rel, parent)}`);
+    } else {
+      add('orphan', rel, 'no index reaches this document — it is not an unlisted child, it is outside the tree entirely');
+    }
+  }
+  const bySlug = new Map();
+  for (const [rel, doc] of docs) {
+    const slug = doc.state === 'file' ? slugOf(rel) : null;
+    if (slug === null || rel === STORE_ROOT) continue;
+    bySlug.set(slug, [...(bySlug.get(slug) ?? []), rel]);
+  }
+  for (const [slug, paths] of bySlug) {
+    if (paths.length > 1) for (const rel of paths) add('slug-unique', rel, `the slug "${slug}" is claimed by ${paths.length} documents (${paths.join(', ')}) — a slug is store-wide`);
+  }
+  // PROVEN canonical ground only (judgeDocument) — a path that never resolved is not compared as if
+  // it had. Nesting is asked with the platform's own path model — `dirname` walked upward, never a
+  // hand-rolled separator rule — and it is asked ONCE PER PATH rather than once per pair: the store
+  // this lane exists for holds a thousand specs, and a pairwise sweep would spend the whole D-scale
+  // budget re-deciding the same question a million times.
+  const owners = new Map();
+  for (const doc of docs.values()) {
+    for (const claimed of doc.ground) owners.set(claimed, new Set([...(owners.get(claimed) ?? []), doc.path]));
+  }
+  // The index accumulates unique conflicting PAIRS, which is the granularity a pairwise sweep
+  // reported: one finding per document per pair. Counting per ground path instead would repeat a
+  // pair once per descendant it shares, and a three-level chain would fuse unrelated pairs into one
+  // lumped message.
+  const pairs = new Map();
+  // The key is JSON, not a joined string: the census lists what is ON DISK, so a document path can
+  // carry any byte a filesystem allows — a space included — long before the reader refuses its slug.
+  // Any separator those paths might themselves contain makes the key non-injective, and the pair
+  // that collides would be dropped in silence.
+  const note = (one, other, claimed) => {
+    if (one === other) return;
+    const [a, b] = [one, other].sort();
+    const key = JSON.stringify([a, b]);
+    if (!pairs.has(key)) pairs.set(key, { a, b, claimed });
+  };
+  for (const [claimed, held] of owners) {
+    const owned = [...held];
+    for (const [i, one] of owned.entries()) for (const other of owned.slice(i + 1)) note(one, other, claimed);
+    for (let up = pathDirname(claimed), below = claimed; up !== below; below = up, up = pathDirname(up)) {
+      for (const above of owners.get(up) ?? []) for (const one of owned) note(one, above, claimed);
+    }
+  }
+  for (const { a, b, claimed } of pairs.values()) {
+    add('overlap', a, `its module ground overlaps ${claimed}, also claimed by ${b} — two contracts, one piece of code`);
+    add('overlap', b, `its module ground overlaps ${claimed}, also claimed by ${a} — two contracts, one piece of code`);
+  }
+};
+
+// checkSpecs({ root, ops, all }, deps) -> { verdict, exit, findings, documents, lines }.
+// Exit 0 ACCEPT · 1 one or more findings · 2 a refusal about the RUN itself (an unresolvable root,
+// an absent store root under --all) — the CLI prints the lines and returns the code.
+export const checkSpecs = ({ root, ops = [], all = false } = {}, deps = {}) => {
+  const io = { read: missing, probe: missing, realpath: missing, list: missing, ...deps };
+  const at = (rel) => (rel === '' ? root : `${root}/${rel}`);
+  const rootReal = io.realpath(root);
+  if (rootReal === null) return refusal(`--root "${root}" does not resolve to a directory — nothing can be judged against it`);
+  const findings = [];
+  const add = (rule, path, message, extra = {}) => findings.push({ rule, path, message, ...extra });
+  const ctx = { io, at, rootReal, add };
+  if (all && io.probe(at(STORE_ROOT)) !== 'file') {
+    return refusal(`the store root ${STORE_ROOT} is not a regular file — an --all run over no store would report an empty clean store, so it refuses instead`);
+  }
+  const closure = all ? walkStore(ctx).map((path) => ({ path, roles: ['present'] })) : buildClosure(ops);
+  // A census that observed nothing still established one fact: its own refusal. Collapsing that into
+  // the empty-closure usage error would throw away the only thing the run learned, so the usage
+  // refusal is the SESSION lane's alone.
+  if (closure.length === 0 && findings.length === 0) return refusal('no document to judge — the op closure is empty');
+  const docs = readClosure(closure, ctx);
+  for (const doc of docs.values()) judgeDocument(doc, ctx);
+  if (all) judgeStore(docs, ctx);
+  else for (const doc of docs.values()) judgeListing(doc, docs, add);
+  return verdictOf(findings, closure.length, all ? 'the whole store' : `${ops.length} op(s)`);
+};