@sabaiway/agent-workflow-kit 7.4.0 → 7.6.0

package/CHANGELOG.md

@@ -4,6 +4,85 @@ 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.
 
+## 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
+definition of well-formed — so the memory canon's reader (mirrored here byte-identically) now
+returns an additive `structure` field. Because the bundled reader bytes move, the reader pair joins
+the AD-113 known-prior refresh lane in the SAME release: without catalog rows for the outgoing
+bodies, every 4.6.x deployment would classify `custom` against the new bundle and be stranded out of
+the store seed forever.
+
+- **`tools/script-priors.mjs` — the catalog spans both pairs.** `PRIOR_FILES` is now the FULL
+  refreshable catalog (checker pair + reader pair); `SCRIPT_PRIORS` appends the outgoing
+  4.6.0..4.6.1 reader-pair bodies (rows 4 -> 6, fixtures under `4.6.0/`, the literal frozen prefix
+  extended with its first four rows byte-identical). The maintenance rule generalizes with it: a
+  release that changes ANY catalog member appends the outgoing body's row.
+- **`tools/ensure-specs.mjs` — the pairs decoupled, the reader refreshes.** `CHECKER_PAIR` was an
+  alias of `PRIOR_FILES`, so the widened catalog would have double-surveyed the readers: the op now
+  owns exported `READER_PAIR`/`CHECKER_PAIR` (the suite pins pairs-union === catalog domain), and
+  `decideWrites` admits a reader REFRESH — reader seeds stay unconditional create-only (a custom
+  neighbour never blocks them); a refresh runs only inside a pair whose every file is
+  current | prior | absent; one custom file withholds its pair's REFRESHES and every downstream
+  write, DIRECTIONALLY (a prior reader still refreshes beside a custom checker, which holds back
+  only its own pair and the store). Order reader -> checker -> store unchanged; lines and tokens
+  unchanged (`refreshed` now covers either pair).
+- **Prose caught up at every live surface** — `references/modes/upgrade.md` (the configs summary
+  and the spec-layer paragraph), the `ensure-configs` header + help, the vocabulary comment, the
+  package-content ledger, and the memory twin's refresh-lane sentence all name BOTH pairs.
+- **Proof.** The state table gains the reader-prior rows, the directional-withhold pin and dry-run
+  rows; the E2E upgrades a real 4.6.x deployment (reader on the 4.6.0 bodies, checker current)
+  whole under the real installed pre-commit hook, and the whole-chain prior+prior cell stays
+  table-covered. Red-first throughout — three red-proofs minted on frozen test bytes against the
+  pre-fix modules. Tarball count unchanged at 247.
+
 ## 7.4.0 — the spec layer reaches existing deployments: known-prior refresh, seed-behind-checker, the `specs` ensure (AD-113)
 
 7.3.0 made a FRESH bootstrap deliver the feature-spec layer whole; this release gives every EXISTING

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.4.0'
+  version: '7.6.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.4.0",
+  "version": "7.6.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/modes/upgrade.md

@@ -30,7 +30,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    **`footprint` — hidden-mode footprint reconcile (D9 / AD-014).** A deployment does not record whether it chose `hidden`, so first **infer visibility** — the dry-run writes **zero bytes** and reports one of — **visible** (the entry point is tracked) → nothing to do; **ambiguous** (untracked but not ignored — could be a fresh uncommitted repo, or a hide that broke) → **ASK** the user which it is, never guess; **hidden** → re-run without `--dry-run` to migrate any older **machine-global** hide to the **project-local** `.git/info/exclude` (one managed block; folds in the legacy `.claude/skills/` line), idempotently (a clean re-run is zero-diff). Handle its surfaced paths exactly as bootstrap step 9 (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) (already-committed → show `git rm --cached`, ask before `--include`; generic-name present file → ask; **leftover machine-wide ignore block → ASK before `--remove-global`**, default keep + report). No Node on the agent host / Windows → as bootstrap step 9 (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`). This runs on **every** hidden upgrade, like the methodology slot — no lineage-head bump, no migration file.
 
-   **`configs` — the project-configuration ensures, ONE run.** The ONE command performs **all six** ensures described below — orchestration config · gate declaration · autonomy declaration · enforcement scripts · spec layer · navigator index — in a fixed order, and prints **one outcome line per ensure**: paste those lines into the step 4 / step 8 success report. Every SEED is **create-only** (an existing file is preserved byte-for-byte); the three refresh-class ops are named apart — the orchestration onboarding note (refreshed only while it still matches a canonical this kit shipped), the spec-layer checker pair (below) and the **navigator index**, a GENERATED artifact regenerated whenever it is missing or stale (never authored content, so there is nothing to preserve). One ensure failing **never** skips the others: each reports its own outcome and the run exits non-zero when any of them `failed`. The outcome tokens, by ensure: orchestration → `seeded` / `note-refreshed` / `already-current` / `customized-preserved` / `malformed-preserved`; gates and autonomy → `seeded` / `already-present`; scripts → `seeded` / `already-present` / `old-adr-layout-migration-instructed` / `skipped-no-node`; specs → `seeded` / `refreshed` / `already-present` / `customized-preserved` / `skipped-no-node`; index → `regenerated` / `already-current`; and any ensure may report `failed`, whose line OPENS with the cause (relay it with that cause — never soften it into a skip; an op that copies file by file also states when it stopped partway). The cause vocabulary is CLOSED — one of `race-unresolved`, `template-unreadable`, `bundle-unreadable`, `adr-layout-unverifiable`, `wrong-node-kind`, `write-refused`, `unexpected-error`, `generator-unlaunchable`, `generator-failed`, `index-probe-failed`, `index-stale-after-write` — and every cause that can only arise AFTER the generator ran (`generator-failed`, and `index-probe-failed` / `index-stale-after-write` when they follow a reported regeneration) DISCLOSES in its own line that a write may already have landed. **A non-zero exit STOPs this upgrade** — report the failed line and stop there, before the equal-head exit, the migrations and the re-stamp. Add `--dry-run` to preview without writing a byte. Like the pointer slots + the footprint reconcile, all six reach an equal-head deployment **without a lineage-head bump or a migration file** (they are `.json` / `scripts/` / a generated artifact / a seeded store root, inherently outside the docs cap-validator).
+   **`configs` — the project-configuration ensures, ONE run.** The ONE command performs **all six** ensures described below — orchestration config · gate declaration · autonomy declaration · enforcement scripts · spec layer · navigator index — in a fixed order, and prints **one outcome line per ensure**: paste those lines into the step 4 / step 8 success report. Every SEED is **create-only** (an existing file is preserved byte-for-byte); the three refresh-class ops are named apart — the orchestration onboarding note (refreshed only while it still matches a canonical this kit shipped), the spec-layer reader and checker pairs (below) and the **navigator index**, a GENERATED artifact regenerated whenever it is missing or stale (never authored content, so there is nothing to preserve). One ensure failing **never** skips the others: each reports its own outcome and the run exits non-zero when any of them `failed`. The outcome tokens, by ensure: orchestration → `seeded` / `note-refreshed` / `already-current` / `customized-preserved` / `malformed-preserved`; gates and autonomy → `seeded` / `already-present`; scripts → `seeded` / `already-present` / `old-adr-layout-migration-instructed` / `skipped-no-node`; specs → `seeded` / `refreshed` / `already-present` / `customized-preserved` / `skipped-no-node`; index → `regenerated` / `already-current`; and any ensure may report `failed`, whose line OPENS with the cause (relay it with that cause — never soften it into a skip; an op that copies file by file also states when it stopped partway). The cause vocabulary is CLOSED — one of `race-unresolved`, `template-unreadable`, `bundle-unreadable`, `adr-layout-unverifiable`, `wrong-node-kind`, `write-refused`, `unexpected-error`, `generator-unlaunchable`, `generator-failed`, `index-probe-failed`, `index-stale-after-write` — and every cause that can only arise AFTER the generator ran (`generator-failed`, and `index-probe-failed` / `index-stale-after-write` when they follow a reported regeneration) DISCLOSES in its own line that a write may already have landed. **A non-zero exit STOPs this upgrade** — report the failed line and stop there, before the equal-head exit, the migrations and the re-stamp. Add `--dry-run` to preview without writing a byte. Like the pointer slots + the footprint reconcile, all six reach an equal-head deployment **without a lineage-head bump or a migration file** (they are `.json` / `scripts/` / a generated artifact / a seeded store root, inherently outside the docs cap-validator).
 
    **What the orchestration-config ensure does.** `docs/ai/orchestration.json` must exist **and its onboarding note must be current**: created from the canonical seed if missing; if it already exists, **every activity/slot the user set is preserved** and ONLY the `_README` note is refreshed, and only when the existing one still matches a known prior canonical — the tested `refreshIfCanonical` / `refreshReadme` in `tools/orchestration-config.mjs` is the source of truth for that decision (it normalizes CRLF/whitespace before comparing; a *customized* `_README` is preserved verbatim → `customized-preserved`; a *malformed* existing config is **preserved untouched + LOUD** → `malformed-preserved`, never clobbered and never silently skipped). The current note points at `/agent-workflow-kit set-recipe`. **Kit-owned:** in the **delegated** path memory only seeds/preserves the file (memory upgrade step 2) and this ensure applies the `_README` refresh; in the **fallback** path it does both. (Memory stays standalone.)
 
@@ -42,7 +42,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    **What the navigator ensure does.** `docs/ai/index.md` is the always-loaded navigator the entry point declares, and it is GENERATED — no template ships it, so a deployment that never ran the generator boots from a broken entry point (and, on a Node project, carries a pre-commit hook that fails its own index check). The ensure runs the bundled generator's finalizer and reports `regenerated` (it was missing or stale — it was written) or `already-current` (nothing written). It never skips a No-Node project: the generator runs from `${CLAUDE_SKILL_DIR}/references/scripts/` on the agent host, not from the project's `scripts/`. **Its position in the run-list is EARLY and therefore NOT authoritative** — `lens` (and, on the migrated path, steps 6–7) still change `docs/ai` afterwards — so the authoritative run is the LATE `--only index` rung documented at both exits; the early one is idempotent and costs at most an `already-current` line.
 
-   **What the spec-layer ensure does.** A deployment older than the feature-spec layer lacks `scripts/spec-schema.mjs` and `docs/ai/specs/index.md`, and its deployed `check-docs-size.mjs` predates the store collapse. In ONE order: the reader pair is seeded (create-only); the checker pair is REFRESHED only while its bytes are a body a release shipped (an append-only digest catalog → `refreshed`; an edited body is preserved verbatim and withholds the writes that depend on it); the store root is seeded from the bundled template, date rendered, ONLY behind a checker pair current after the run — an older or edited checker renders the store row by row and reds the hook's `--check-index`, so behind a custom checker the store root is NOT seeded and the line names the remedy (copy the pair from `${CLAUDE_SKILL_DIR}/references/scripts/` by hand, re-run). One token by precedence: `seeded` > `refreshed` > `customized-preserved` (an edited pair, and this run wrote nothing) > `already-present`; `skipped-no-node` without a `package.json`; every line states what this run did, and a write that stops partway names what landed. The legacy-ADR instruct never withholds it.
+   **What the spec-layer ensure does.** A deployment older than the feature-spec layer lacks `scripts/spec-schema.mjs` and `docs/ai/specs/index.md`, and its deployed `check-docs-size.mjs` predates the store collapse. In ONE order: the reader pair, then the checker pair — each seeded when absent and REFRESHED only while a file's bytes are a body a release shipped (an append-only digest catalog → `refreshed`; an edited body is preserved verbatim and withholds the writes that depend on it, the checker lane waiting on a byte-current reader pair); the store root is seeded from the bundled template, date rendered, ONLY behind a checker pair current after the run — an older or edited checker renders the store row by row and reds the hook's `--check-index`, so behind a custom checker the store root is NOT seeded and the line names the remedy (copy the pair from `${CLAUDE_SKILL_DIR}/references/scripts/` by hand, re-run). One token by precedence: `seeded` > `refreshed` > `customized-preserved` (an edited pair, and this run wrote nothing) > `already-present`; `skipped-no-node` without a `package.json`; every line states what this run did, and a write that stops partway names what landed. The legacy-ADR instruct never withholds it.
 
    **`gates-migration` — legacy gates.json migration (consented preview — D8).** An EXISTING declaration may still carry the retired review-ledger / fold-completeness checks. Run the preview (dry-run — writes NOTHING), show the user the exact plan, and only on an explicit yes re-run it with `--apply`: canonical legacy entries (matched by their documented single-invocation cmd forms) are REMOVED, the canonical `unit-tests` cmd gains the built-in lcov reporters, and the coverage-check gate is ADDED last — atomic and COMPLETE, so the migrated declaration satisfies `run-gates --final`. **The checker rides a PRODUCER or is not declared at all** (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`): with no gate producing the lcov it reads, the migration does NOT add it, an already-declared one is reported INERT, the result is not called final-run-capable, and the preview prints the paste-ready suite cmd to declare by hand — nothing is ever removed for you. CUSTOMIZED entries are NEVER auto-touched: the preview names each with a paste-ready recovery, and the commit guard must NOT be installed until they are resolved. This is the ONLY gates.json writer at upgrade (the consented FILL preview runs at init).
 

package/references/scripts/spec-schema.mjs

@@ -310,13 +310,45 @@ const checkParts = (parsed, at, errors) => {
   if (duplicate !== undefined) errors.push({ rule: 'parts', message: `part "${duplicate}" is listed twice` });
 };
 
-// The verdict: { kind, status, revision, errors: [{ rule, message }], warnings: [{ rule, message }] }.
-// Errors are collected past the first defect wherever later checks stay meaningful; a missing or
-// defective frontmatter and an unknown kind each end the read, because no shape can be judged without them.
+// The structure verdict (additive, slice 2a): the DETERMINISTIC extraction of what parsed, per
+// section, targets VERBATIM as written (`./x.md` and `./x/index.md` stay distinct strings). The
+// grammar is per line for scenarios/children/parts — a malformed line is simply absent — while the
+// module is a conjunction (ONE `dir/` root or an all-file list): prose, a refused path, a mix or
+// `*(empty)*` extracts null. `## Links` is free prose and is never extracted.
+const scenarioEntry = (line) => {
+  const scenario = parseScenario(line);
+  if (scenario === null) return null;
+  return { ordinal: scenario.n, binding: scenario.bound ? { file: scenario.path, marker: scenario.marker } : null };
+};
+const linkEntry = (re) => (line) => {
+  const m = line.match(re);
+  return m && SLUG_RE.test(m[2]) ? { name: m[1], target: `./${m[2]}${m[3] ?? ''}.md` } : null;
+};
+const entriesOf = (parsed, heading, entryOf) =>
+  contentOf(sectionLines(parsed, heading) ?? []).map(entryOf).filter((entry) => entry !== null);
+const extractModule = (parsed) => {
+  const content = contentOf(sectionLines(parsed, '## Module') ?? []);
+  const paths = bulletsOf(content);
+  if (paths.length === 0 || content.some((line) => !isBullet(line))) return null;
+  const kinds = paths.map(classifyPath);
+  if (paths.length === 1 && kinds[0] === 'dir') return { form: 'root', paths };
+  return kinds.every((kind) => kind === 'file') ? { form: 'fileSet', paths } : null;
+};
+const extractStructure = (parsed) => ({
+  scenarios: entriesOf(parsed, '## Scenarios', scenarioEntry),
+  children: entriesOf(parsed, '## Children', linkEntry(CHILD_LINK_RE)),
+  parts: entriesOf(parsed, '## Parts', linkEntry(PART_LINK_RE)),
+  module: extractModule(parsed),
+});
+
+// The verdict: { kind, status, revision, structure, errors: [{ rule, message }], warnings: [{ rule,
+// message }] }. Errors are collected past the first defect wherever later checks stay meaningful; a
+// missing or defective frontmatter and an unknown kind each end the read (structure stays null),
+// because no shape can be judged without them.
 export const readSpecDocument = (text, rel) => {
   const errors = [];
   const warnings = [];
-  const verdict = (kind, status, revision) => ({ kind, status, revision, errors, warnings });
+  const verdict = (kind, status, revision, structure = null) => ({ kind, status, revision, structure, errors, warnings });
   const front = parseFrontmatter(text.replace(/\r\n/g, '\n'));
   if (front === null) {
     errors.push({ rule: 'frontmatter', message: 'missing YAML frontmatter' });
@@ -351,5 +383,5 @@ export const readSpecDocument = (text, rel) => {
   }
   const status = kind === 'spec' ? fields.status ?? null : null;
   const revision = kind === 'spec' && REVISION_RE.test(fields.revision ?? '') ? Number(fields.revision) : null;
-  return verdict(kind, status, revision);
+  return verdict(kind, status, revision, extractStructure(parsed));
 };

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

@@ -194,6 +194,73 @@ describe('readSpecDocument — refuse, exactly one rule per defect', () => {
   });
 });
 
+describe('readSpecDocument — the structure verdict (additive, slice 2a)', () => {
+  const structureOf = (text, rel) => readSpecDocument(text, rel).structure;
+  const BOTH_SCENARIOS = [
+    { ordinal: 1, binding: { file: 'test/login.test.mjs', marker: 'spec:login/S1' } },
+    { ordinal: 2, binding: null },
+  ];
+
+  it('a flat spec extracts scenarios (bound + unbound) and its one dir/ module root', () => {
+    expect(structureOf(specDoc(), 'login.md')).toEqual({
+      scenarios: BOTH_SCENARIOS,
+      children: [],
+      parts: [],
+      module: { form: 'root', paths: ['src/login/'] },
+    });
+  });
+
+  it('a promoted root extracts parts and a fileSet module; ## Links stays free prose, never extracted', () => {
+    const text = specDoc({ module: '- src/a.mjs\n- src/b.mjs', extra: '\n## Parts\n\n- [sessions](./sessions.md)\n\n## Links\n\n- [[AD-112]]\n' });
+    expect(structureOf(text, 'auth/login/index.md')).toEqual({
+      scenarios: BOTH_SCENARIOS,
+      children: [],
+      parts: [{ name: 'sessions', target: './sessions.md' }],
+      module: { form: 'fileSet', paths: ['src/a.mjs', 'src/b.mjs'] },
+    });
+  });
+
+  it('an index extracts children with VERBATIM targets — ./x.md and ./x/index.md stay distinct strings', () => {
+    expect(structureOf(indexDoc(), 'auth/index.md')).toEqual({
+      scenarios: [],
+      children: [{ name: 'login', target: './login.md' }, { name: 'billing', target: './billing/index.md' }],
+      parts: [],
+      module: null,
+    });
+  });
+
+  it('a part extracts the empty structure; a retired *(empty)* module extracts null on a CLEAN document', () => {
+    expect(structureOf(partDoc(), 'auth/login/sessions.md')).toEqual({ scenarios: [], children: [], parts: [], module: null });
+    const retired = specDoc({ fields: { status: 'retired' }, module: '*(empty)*', scenarios: ['- S1 gone :: unbound'] });
+    expect(structureOf(retired, 'login.md').module).toBeNull();
+  });
+
+  it('EVERY early refusal reads structure null: missing frontmatter, a frontmatter defect, an unknown or absent kind', () => {
+    expect(structureOf('# Spec: Login\n', 'login.md')).toBeNull();
+    expect(structureOf(specDoc({ fields: { priority: 'high' } }), 'login.md')).toBeNull();
+    expect(structureOf(specDoc({ fields: { kind: 'feature' } }), 'login.md')).toBeNull();
+    expect(structureOf(specDoc({ drop: ['kind'] }), 'login.md')).toBeNull();
+  });
+
+  it('a grammar-malformed scenario/child/part line is simply ABSENT — valid lines before and after it extract', () => {
+    const s = structureOf(specDoc({ scenarios: ['- S1 a :: unbound', '- S2 broken', '- S3 c :: unbound'] }), 'login.md');
+    expect(s.scenarios).toEqual([{ ordinal: 1, binding: null }, { ordinal: 3, binding: null }]);
+    const c = structureOf(indexDoc({ children: ['- [a](./a.md)', '- broken', '- [b](./b/index.md)'] }), 'auth/index.md');
+    expect(c.children).toEqual([{ name: 'a', target: './a.md' }, { name: 'b', target: './b/index.md' }]);
+    const p = structureOf(specDoc({ extra: '\n## Parts\n\n- [a](./a.md)\n- broken\n- [b](./b.md)\n' }), 'auth/login/index.md');
+    expect(p.parts).toEqual([{ name: 'a', target: './a.md' }, { name: 'b', target: './b.md' }]);
+  });
+
+  it('the module is a CONJUNCTION — prose, a refused path, a dir/file mix each extract null; a rule-refused scenario line still extracts verbatim', () => {
+    for (const module of ['the root is\n- src/login/', '- ../src/', '- src/login/\n- src/login/a.mjs']) {
+      expect(structureOf(specDoc({ module }), 'login.md').module).toBeNull();
+    }
+    const v = readSpecDocument(specDoc({ scenarios: ['- S1 a :: test/a.mjs :: spec:login/S2'] }), 'login.md');
+    expect(v.errors.map((e) => e.rule)).toEqual(['scenario-marker']);
+    expect(v.structure.scenarios).toEqual([{ ordinal: 1, binding: { file: 'test/a.mjs', marker: 'spec:login/S2' } }]);
+  });
+});
+
 describe('classifyPath + the frozen constants', () => {
   it('classifies the lexical path forms', () => {
     expect(['src/', 'src/a.mjs', '../x', '/x', 'C:/x', 'a\\b', 'src/*.mjs'].map(classifyPath)).toEqual([

package/tools/ensure-configs.mjs

@@ -5,7 +5,7 @@
 //   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
+//   specs          scripts/<spec layer>        reader + checker pairs seeded when absent, 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)
 //
@@ -64,9 +64,10 @@ Usage:
 
 Every SEED is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
 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
+matches a canonical the kit shipped (your own wording is preserved verbatim); the spec-layer reader
+and checker pairs, only while a file's bytes are a body a release shipped (an edited file is
+preserved, and the writes that depend on it — the spec store root included — are withheld 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.
 

package/tools/ensure-specs.mjs

@@ -1,11 +1,12 @@
 // 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;
+//   1. the reader pair   scripts/spec-schema.mjs + .test.mjs      — created when absent; since 2a
+//      also REFRESHED when the deployed bytes are a body a release shipped (script-priors.mjs), a
+//      custom body preserved verbatim (brief D1 shipped it create-only; the 4.6.x bodies joining the
+//      catalog is what keeps those deployments out of the stranded-custom cell);
+//   2. the checker pair  scripts/check-docs-size.mjs + .test.mjs  — the same prior-refresh lane, and
+//      only behind a reader pair this run leaves 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
@@ -24,7 +25,7 @@
 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 { classifyDeployedScript } from './script-priors.mjs';
 import { composeFailure, composeOutcome, isNodeProject, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
 
 const OP = 'specs';
@@ -33,8 +34,10 @@ 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;
+// Explicit pairs, deliberately NOT aliased to the catalog's PRIOR_FILES (which spans both): each
+// file is surveyed exactly once. Exported so the suite pins pairs-union === catalog domain.
+export const READER_PAIR = Object.freeze(['spec-schema.mjs', 'spec-schema.test.mjs']);
+export const CHECKER_PAIR = Object.freeze(['check-docs-size.mjs', 'check-docs-size.test.mjs']);
 
 const ok = (token, lines) => composeOutcome(OP, token, lines, false);
 const loud = (cause, ...lines) => composeFailure(OP, cause, ...lines);
@@ -67,14 +70,20 @@ const surveyStoreRoot = (cwd, lstat) => {
 
 // ── 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']);
+// Reader seeds are create-only and always admitted. A REFRESH overwrites bytes, so it runs only
+// inside a pair whose every file is proven refreshable (current | prior | absent) — one custom file
+// withholds its whole pair; the checker lane (its seeds included) and the store additionally wait
+// for a reader pair this run leaves byte-current (seeded + refreshed = current).
+const PAIR_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 readerEligible = reader.every((f) => PAIR_ELIGIBLE.has(f.state));
+  const checkerEligible = readerEligible && checker.every((f) => PAIR_ELIGIBLE.has(f.state));
   const writes = [];
-  for (const f of reader) if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
+  for (const f of reader) {
+    if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
+    if (readerEligible && f.state === 'prior') writes.push({ kind: 'refresh', file: f });
+  }
   if (checkerEligible) {
     for (const f of checker) {
       if (f.state === 'absent') writes.push({ kind: 'seed', file: f });

package/tools/ensure-vocabulary.mjs

@@ -14,8 +14,8 @@ export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', '
 
 // 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. `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).
+// ensure's pair refresh (reader or checker) — 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']);
 

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

@@ -13,9 +13,12 @@
 
 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']);
+// The deployed scripts the spec-layer ensure may REFRESH — the FULL refreshable catalog: the checker
+// pair that imports the reader, and (since 2a) the reader pair itself. 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', 'spec-schema.mjs', 'spec-schema.test.mjs',
+]);
 
 const prior = (file, firstShipped, lastShipped, digest) => Object.freeze({ file, firstShipped, lastShipped, digest });
 
@@ -26,6 +29,8 @@ export const SCRIPT_PRIORS = Object.freeze([
   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'),
+  prior('spec-schema.mjs', '4.6.0', '4.6.1', 'f8ee23d81e90fd4225ca4ece288cba41982c4430290bc6d033f5ca18d2d283f4'),
+  prior('spec-schema.test.mjs', '4.6.0', '4.6.1', 'a12d6d3f5d32c6dabdee7e15af7d2ab15a0ced37515d1844fe0951f60cddbc99'),
 ]);
 
 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)`);
+};