@sabaiway/agent-workflow-kit 7.2.0 → 7.3.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.3.0 — the spec layer's delivery half: hidden from day one, mirrored, bootstrapped (AD-112)
+
+The memory substrate ships the feature-spec layer in 4.6.0 and the engine its canon in 3.3.0; this
+release is what makes a FRESH kit bootstrap deliver it whole and hidden.
+
+- **Hidden mode, no new machinery.** `KIT_OWN_PATHS` gains `/scripts/spec-schema.mjs` and
+  `/scripts/spec-schema.test.mjs` (sentinel 28 -> 30) — the reader the navigator checker now imports
+  and its deployed test; `/docs/ai/` already subsumes the store. The integration suite proves it on a
+  bootstrapped layout with real `git check-ignore` on both files and on `docs/ai/specs/x.md`: nothing
+  of the layer is visible to git.
+- **Mirrors.** `references/scripts/` carries the reader pair and the GROUPS-collapse checker
+  byte-identical to the memory canon; `references/templates/` carries `specs/index.md` and
+  `SPEC_TEMPLATE.md` (the mirror manifest names both; template-parity reverse-pins them). The kit's
+  own fallback bootstrap excludes `SPEC_TEMPLATE.md` by NAME in its prose AND its E2E copy loop, and
+  the finalized navigator carries ONE counted `specs/` row.
+- **Templates.** `agent_rules.md` §1.2/§1.3 reworded (governing specs, adoption shim, the revision
+  lands with the code) and its lens region re-rendered with the engine's `Spec-first` bullet;
+  `AGENTS.md` routes `technical_specification.md` readers to the contracts under `docs/ai/specs/`.
+- Package-content pins: 241 -> 245 (the reader pair + the two templates), each by NAME.
+
 ## 7.2.0 — `.mcp.json` joins the hidden-mode footprint, and a worktree never owns it (AD-111)
 
 7.0.0 taught the kit to register its MCP server. It did not teach hidden mode about the file that

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.2.0",
+  "version": "7.3.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/bootstrap.md

@@ -21,7 +21,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 3. **Choose conversational language — answered in the step-2 batch.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](${CLAUDE_SKILL_DIR}/references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
 4. **Choose agent attribution — answered in the step-2 batch.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](${CLAUDE_SKILL_DIR}/references/contracts.md#attribution-contract).
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
-6. **Deploy `docs/ai/`.** Create every `docs/ai/` file + `pages/` + the seed `adr/` store from `${CLAUDE_SKILL_DIR}/references/templates/` (the template loop deploys each non-`AGENTS.md`, non-`adr-record.md` template — `adr-record.md` is a skill-home ADR authoring reference, never deployed). This deploys the HOT ADR window **`docs/ai/decisions.md`** and the seed navigator **`docs/ai/adr/log.md`** (its `adr/` subdir copies in wholesale), the `.md` docs, **and** the three seeded, user-editable strict-JSON configs: **`docs/ai/orchestration.json`** (the per-project recipe defaults the `procedures` advisor reads), **`docs/ai/gates.json`** (the project's gate declaration — seeded as the no-consent EMPTY list; FILLING it is the consented `gates-init` preview, `${CLAUDE_SKILL_DIR}/references/modes/gates.md`), and **`docs/ai/autonomy.json`** (the per-project autonomy policy — seeded SPARSE with the onboarding note only, so it is exactly the computed defaults until the user declares levels via `/agent-workflow-kit set-autonomy` or by hand). Keep each `.md` file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`); the `.json` seeds carry no frontmatter (the docs cap-validator globs `*.md` only, so they are inherently skipped).
+6. **Deploy `docs/ai/`.** Create every `docs/ai/` file + `pages/` + the seed `adr/` store + the seed `specs/` store from `${CLAUDE_SKILL_DIR}/references/templates/` (the template loop deploys every template except `AGENTS.md`, `adr-record.md` and `SPEC_TEMPLATE.md` — the latter two are skill-home authoring references, never deployed). This deploys the HOT ADR window **`docs/ai/decisions.md`** and the seed navigator **`docs/ai/adr/log.md`** (its `adr/` subdir copies in wholesale), the spec store root **`docs/ai/specs/index.md`** (its `specs/` subdir copies in wholesale), the `.md` docs, **and** the three seeded, user-editable strict-JSON configs: **`docs/ai/orchestration.json`** (the per-project recipe defaults the `procedures` advisor reads), **`docs/ai/gates.json`** (the project's gate declaration — seeded as the no-consent EMPTY list; FILLING it is the consented `gates-init` preview, `${CLAUDE_SKILL_DIR}/references/modes/gates.md`), and **`docs/ai/autonomy.json`** (the per-project autonomy policy — seeded SPARSE with the onboarding note only, so it is exactly the computed defaults until the user declares levels via `/agent-workflow-kit set-autonomy` or by hand). Keep each `.md` file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`); the `.json` seeds carry no frontmatter (the docs cap-validator globs `*.md` only, so they are inherently skipped).
 7. **Fill templates** per the table below. **Then materialize the navigator, as the last `docs/ai` step:** the entry point declares `docs/ai/index.md` always-loaded and it is a GENERATED artifact with no template, so run `node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<project>` and relay its one outcome line (`ensure-index: regenerated` / `already-current`, or a `write-refused` / `probe-failed` line naming the offending path — either is a STOP: resolve it before reporting the deploy, since the navigator the entry point declares does not exist yet). The generator runs from **this skill's own directory**, so a project with **no Node runtime** is covered too: the agent host runs it, and step 8's copy is not a precondition.
 8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 9 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
 9. **Wire / hide** per visibility (see [Visibility contract](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting. Once the gate declaration is final-run-capable, the installer's optional consented `--commit-guard <kit commit-guard.mjs path>` arm binds commits to the green `run-gates --final` receipt (the Recommendations advisor surfaces the exact one-liner).

package/references/scripts/check-docs-size.mjs

@@ -29,6 +29,7 @@ import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve, relative, join, basename, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
+import { readSpecDocument, SPECS_COLLAPSE } from './spec-schema.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -36,10 +37,8 @@ const ROOT = resolve(__dirname, '..');
 const DOCS_DIR = resolve(ROOT, 'docs/ai');
 const INDEX_PATH = resolve(DOCS_DIR, 'index.md');
 
-// Root-parameterized (BUGFREE-3 / AD-049, item (h)): the module ROOT constants are the CLI DEFAULT
-// (this deployment's own root); `--root=<dir>` and the exported `regenerateIndex(root, today)`
-// override them so the ADR-rotation hook (archive-decisions.mjs) and hermetic tests can regenerate
-// an arbitrary root's index without ever touching the real repo tree.
+// The module ROOT constants are the CLI DEFAULT (this deployment's own root); `--root=<dir>` and the
+// exported `regenerateIndex(root, today)` target an arbitrary root (the ADR-rotation hook, hermetic tests).
 const pathsFor = (root) => {
   const base = resolve(root);
   return { root: base, docsDir: resolve(base, 'docs/ai'), indexPath: resolve(base, 'docs/ai/index.md') };
@@ -58,12 +57,9 @@ const ENSURE_INDEX_PREFIX = 'ensure-index:';
 const DEFAULT_PROJECT_NAME = 'this project';
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'dist-ssr', 'coverage', 'build', '.next']);
 
-// `strict` is the finalizer's lens on the SAME walk: for a report, an unreadable subtree is fairly
-// skipped, but a run that WRITES the navigator may not silently treat "could not read" as "nothing
-// there" — it would publish an index missing whatever it could not see and call that success. Only
-// a genuine ENOENT stays an absence; every other fs error propagates.
-// Only a genuine ENOENT is an absence. A code-LESS throw (an injected reader, a wrapped client) is
-// not evidence of absence either, so it propagates too — "unknown" must never read as "empty".
+// `strict` is the finalizer's lens on the SAME walk: a run that WRITES the navigator may not treat
+// "could not read" as "nothing there". Only a genuine ENOENT is an absence — a code-LESS throw (an
+// injected reader, a wrapped client) propagates too: "unknown" must never read as "empty".
 const rethrowUnlessAbsent = (err, strict) => {
   if (strict && err?.code !== 'ENOENT') throw err;
 };
@@ -204,24 +200,25 @@ export const computeToday = (todayStr) =>
     ? new Date(`${todayStr}T00:00:00Z`)
     : new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00Z');
 
+// A file under the spec store is ALSO read through the shared reader (already-read text, no second
+// read): its verdict rides the row as `spec` and decides collapse eligibility; a refusal is ADVISORY
+// here — surfaced as warnings, never a cap error — the structural checker owns the refusal.
+const readSpecVerdict = (rel, text) =>
+  rel.startsWith(SPECS_COLLAPSE.prefix) ? readSpecDocument(text, rel.slice(SPECS_COLLAPSE.prefix.length)) : null;
+
 export const inspectFile = async (filePath, today, root = ROOT) => {
   const text = await readFile(filePath, 'utf8');
   const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
   const fm = parseFrontmatter(text);
   const rel = relative(root, filePath);
+  const spec = readSpecVerdict(rel, text);
 
   if (!fm) {
-    return {
-      path: rel,
-      lineCount,
-      frontmatter: null,
-      errors: [`missing YAML frontmatter`],
-      warnings: [],
-    };
+    return { path: rel, lineCount, frontmatter: null, spec, errors: [`missing YAML frontmatter`], warnings: [] };
   }
 
   const errors = [];
-  const warnings = [];
+  const warnings = (spec === null ? [] : [...spec.errors, ...spec.warnings]).map((finding) => `spec ${finding.rule}: ${finding.message}`);
 
   const maxLines = fm.maxLines ? Number(fm.maxLines) : null;
   if (maxLines === null || Number.isNaN(maxLines)) {
@@ -241,7 +238,7 @@ export const inspectFile = async (filePath, today, root = ROOT) => {
     }
   }
 
-  return { path: rel, lineCount, frontmatter: fm, errors, warnings };
+  return { path: rel, lineCount, frontmatter: fm, spec, errors, warnings };
 };
 
 const formatRow = (row) => {
@@ -304,19 +301,16 @@ const formatIndexRow = (row) => {
   return `| ${link} | ${fm.type ?? '—'} | ${row.lineCount}/${fm.maxLines ?? '—'} | ${fm.lastUpdated ?? '—'} | ${fm.staleAfter ?? '—'} |`;
 };
 
-// The one-file-per-ADR store (docs/ai/adr/) grows O(n) forever, so its rows would blow the index's
-// own 80-line cap. It COLLAPSES to a single aggregate row (link → the navigator adr/log.md, record
-// count + numeric id range) — while walkMarkdownFiles still finds + cap-checks every individual body
-// (a body over its own cap still fails in the main flow; only the index RENDERING is collapsed).
+// Two stores grow O(n) forever and would blow the index's own 80-line cap: the one-file-per-ADR store
+// (docs/ai/adr/) and the spec store (docs/ai/specs/). Each is a GROUP that COLLAPSES to a single
+// counted row — while walkMarkdownFiles still finds + cap-checks every individual body (only the
+// index RENDERING is collapsed). Membership is by PROOF: a genuine ADR record / the adr navigator,
+// or a spec-store file the shared reader accepts. Anything else under either dir (a stray README.md,
+// a malformed spec) renders as its OWN visible row — never silently hidden by the collapse.
 const ADR_DIR_PREFIX = 'docs/ai/adr/';
 const ADR_RECORD_RE = /\/AD-(\d{3,})-[^/]*\.md$/;
 const ADR_NAV_PATH = 'docs/ai/adr/log.md';
 
-// Only genuine records + the navigator collapse into the aggregate row; an UNEXPECTED file under
-// adr/ (a stray README.md, AD-foo.md) renders as its OWN visible index row — never silently hidden
-// by the collapse (it also fails archive-decisions' own store-integrity check).
-const isCollapsibleAdr = (path) => path.startsWith(ADR_DIR_PREFIX) && (ADR_RECORD_RE.test(path) || path === ADR_NAV_PATH);
-
 const formatAdrCollapseRow = (adrRows) => {
   const recs = adrRows
     .map((r) => {
@@ -329,23 +323,37 @@ const formatAdrCollapseRow = (adrRows) => {
   return `| [\`adr/\`](./adr/log.md) | adr | ${recs.length} records | ${range} | — |`;
 };
 
-// Pure index renderer — given inspected rows + the date to stamp in the header,
-// returns the exact bytes `docs/ai/index.md` should contain. Shared by
-// `--write-index` (writes it) and `--check-index` (diffs against on-disk).
+// The live counts make the row change when a spec is added or removed, so --check-index sees it.
+const formatSpecsCollapseRow = (specRows) => {
+  const count = (kind) => specRows.filter((r) => r.spec.kind === kind).length;
+  const link = `[\`${SPECS_COLLAPSE.label}\`](./${SPECS_COLLAPSE.navPath.replace(/^docs\/ai\//, '')})`;
+  return `| ${link} | ${SPECS_COLLAPSE.type} | ${count('spec')} specs | ${count('part')} parts · ${count('index')} indexes | — |`;
+};
+
+const COLLAPSE_GROUPS = [
+  { sortPath: ADR_DIR_PREFIX, isMember: (r) => r.path.startsWith(ADR_DIR_PREFIX) && (ADR_RECORD_RE.test(r.path) || r.path === ADR_NAV_PATH), format: formatAdrCollapseRow },
+  { sortPath: SPECS_COLLAPSE.prefix, isMember: (r) => Boolean(r.spec) && r.spec.errors.length === 0, format: formatSpecsCollapseRow },
+];
+
+// Pure index renderer — inspected rows + the header date → the exact bytes `docs/ai/index.md` should
+// contain. Shared by `--write-index` (writes it) and `--check-index` (diffs against on-disk).
 export const buildIndex = (rows, todayStr, meta = {}) => {
   const projectName = meta.projectName ?? DEFAULT_PROJECT_NAME;
   const onDemandLinks = meta.onDemandLinks ?? [];
   const hierarchicalLinks = meta.hierarchicalLinks ?? [];
   const header = INDEX_HEADER.replace('__TODAY__', todayStr).replace('__PROJECT__', projectName);
   const tableHeader = `| File | Type | Lines/Max | Updated | Stale after |\n|------|------|-----------|---------|-------------|`;
-  const nonAdr = [];
-  const adrRows = [];
+  const singles = [];
+  const grouped = COLLAPSE_GROUPS.map(() => []);
   for (const r of rows) {
     if (r.path === 'docs/ai/index.md') continue;
-    (isCollapsibleAdr(r.path) ? adrRows : nonAdr).push(r);
+    const group = COLLAPSE_GROUPS.findIndex((g) => g.isMember(r));
+    (group === -1 ? singles : grouped[group]).push(r);
   }
-  const tableEntries = nonAdr.map((r) => ({ sortPath: r.path, md: formatIndexRow(r) }));
-  if (adrRows.length > 0) tableEntries.push({ sortPath: ADR_DIR_PREFIX, md: formatAdrCollapseRow(adrRows) });
+  const tableEntries = singles.map((r) => ({ sortPath: r.path, md: formatIndexRow(r) }));
+  COLLAPSE_GROUPS.forEach((g, i) => {
+    if (grouped[i].length > 0) tableEntries.push({ sortPath: g.sortPath, md: g.format(grouped[i]) });
+  });
   tableEntries.sort((a, b) => a.sortPath.localeCompare(b.sortPath));
   const tableRows = tableEntries.map((e) => e.md).join('\n');
   const onDemandSection =
@@ -359,11 +367,8 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
   return `${header}${tableHeader}\n${tableRows}${onDemandSection}${hierarchicalSection}\n`;
 };
 
-// Decides whether an on-disk index is in sync with the source frontmatter.
-// The index is regenerated in memory using the on-disk index's OWN `lastUpdated`
-// for the header, so a mere day-rollover (no content change) is NOT flagged —
-// only genuine drift in the file table (added/removed files, changed
-// type/cap/lastUpdated/staleAfter, or a changed line count) makes it stale.
+// Freshness regenerates the index with the on-disk header's OWN `lastUpdated`, so a mere day-rollover
+// is NOT flagged — only genuine drift in the file table makes it stale.
 export const checkIndexFreshness = (rows, onDiskText, meta = {}) => {
   if (onDiskText === null || onDiskText === undefined || onDiskText === '') {
     return { fresh: false, expected: buildIndex(rows, 'unknown', meta) };
@@ -374,13 +379,11 @@ export const checkIndexFreshness = (rows, onDiskText, meta = {}) => {
   return { fresh: expected === onDiskText, expected };
 };
 
-// The navigator is a GENERATED artifact, so its write must land on the deployment's own file and
-// nowhere else: every component of <root>/docs/ai/index.md is lstat'ed no-follow (a symlinked root,
-// `docs`, `docs/ai` or leaf REFUSES — publishing through one would clobber whatever it points at),
-// the body goes out through a unique exclusive-create temp renamed into place with the chain
-// re-checked immediately before the rename, and the temp never survives a failure. The kit runs the
-// same discipline in atomic-write.mjs; this deployment script ships dependency-free, so the
-// semantics are REIMPLEMENTED here rather than imported.
+// The navigator write lands on the deployment's own file and nowhere else: every component of
+// <root>/docs/ai/index.md is lstat'ed no-follow (a symlink anywhere REFUSES — publishing through one
+// would clobber its target), the body goes out through an exclusive-create temp renamed into place
+// with the chain re-checked before the rename, and the temp never survives a failure. The kit's
+// atomic-write.mjs runs the same discipline; this script ships dependency-free, so it is REIMPLEMENTED.
 export const INDEX_WRITE_REFUSED = 'INDEX_WRITE_REFUSED';
 const refuse = (message) => Object.assign(new Error(message), { code: INDEX_WRITE_REFUSED });
 
@@ -444,11 +447,8 @@ const writeIndex = async (rows, today, meta, { root = ROOT, indexPath = INDEX_PA
   }
 };
 
-// regenerateIndex(root, todayStr) — the ONE reused generator, root-parameterized (item (h)). It runs
-// the SAME walk → inspect → discoverMeta → writeIndex pipeline as `--write-index`, against `root`
-// (default this deployment). The ADR-rotation hook reaches it via the CLI (`--write-index --root=…`);
-// hermetic tests call it directly. `todayStr` is 'YYYY-MM-DD' (null → today). Returns the written
-// index path + row count. No second index implementation exists.
+// regenerateIndex(root, todayStr) — the ONE reused generator: the SAME walk → inspect → discoverMeta →
+// writeIndex pipeline as `--write-index`, against `root`. `todayStr` is 'YYYY-MM-DD' (null → today).
 export const regenerateIndex = async (root, todayStr = null, deps = {}) => {
   const paths = pathsFor(root);
   const today = computeToday(todayStr);
@@ -460,12 +460,10 @@ export const regenerateIndex = async (root, todayStr = null, deps = {}) => {
   return { indexPath: paths.indexPath, files: rows.length };
 };
 
-// The finalizer promises its caller EXACTLY ONE outcome line, so every step it owns — the walk, the
-// metadata discovery, the freshness read and the write — runs inside one classified error path: an
-// unreadable docs/ai is a NAMED refusal, never a stack trace. The containment guard runs BEFORE the
-// freshness read for the same reason `already-present` needs a kind probe: a symlinked navigator
-// whose target happens to hold current bytes would otherwise report `already-current` over a file
-// this mode refuses to write through — an exit 0 proving nothing about the deployment's own file.
+// The finalizer promises EXACTLY ONE outcome line, so every step it owns runs inside one classified
+// error path: an unreadable docs/ai is a NAMED refusal, never a stack trace. The containment guard
+// runs BEFORE the freshness read: a symlinked navigator whose target holds current bytes would
+// otherwise report `already-current` over a file this mode refuses to write through.
 const runEnsureIndex = async ({ root, docsDir, indexPath, today, deps }) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.readFile ?? readFile;
@@ -571,9 +569,8 @@ export const runCli = async (argv, deps = {}) => {
   return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
-// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
-// reached through a symlink resolves to its target, so a raw string compare reads the two as
-// different and the CLI never runs. realpathSync collapses the link so both sides match.
+// Run main() only when executed directly, never on import — compared by REAL path, so an entry point
+// reached through a symlink still runs.
 const isDirectRun = (() => {
   const invoked = process.argv[1];
   if (!invoked) return false;

package/references/scripts/check-docs-size.test.mjs

@@ -178,11 +178,7 @@ describe('buildIndex — docs/ai/adr/ directory collapse (Decision 11)', () => {
   });
 
   it('a stray adr/ markdown file renders as its OWN visible row (never collapsed/hidden)', () => {
-    const rows = [
-      makeRow('docs/ai/adr/AD-001-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
-      makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }),
-      makeRow('docs/ai/adr/notes.md', { frontmatter: { type: 'reference', maxLines: '100' } }),
-    ];
+    const rows = [makeRow('docs/ai/adr/AD-001-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }), makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }), makeRow('docs/ai/adr/notes.md', { frontmatter: { type: 'reference', maxLines: '100' } })];
     const out = buildIndex(rows, '2026-07-09');
     expect(out).toMatch(/adr\/notes\.md/); // the stray is a visible row, not swallowed by the collapse
     const aggregateRows = out.split('\n').filter((l) => l.includes('](./adr/log.md)'));
@@ -190,11 +186,7 @@ describe('buildIndex — docs/ai/adr/ directory collapse (Decision 11)', () => {
   });
 
   it('the aggregate row shows the record count and a NUMERIC id range (AD-200 … AD-1000)', () => {
-    const rows = [
-      makeRow('docs/ai/adr/AD-200-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
-      makeRow('docs/ai/adr/AD-1000-b.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
-      makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }),
-    ];
+    const rows = [makeRow('docs/ai/adr/AD-200-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }), makeRow('docs/ai/adr/AD-1000-b.md', { frontmatter: { type: 'adr', maxLines: '400' } }), makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } })];
     const out = buildIndex(rows, '2026-07-09');
     expect(out).toMatch(/\[`adr\/`\]\(\.\/adr\/log\.md\) \| adr \| 2 records \| AD-200 … AD-1000/);
   });
@@ -219,13 +211,70 @@ describe('buildIndex — docs/ai/adr/ directory collapse (Decision 11)', () => {
   });
 });
 
+// The spec store (docs/ai/specs/**) joins the collapse as a second GROUP: every file whose reader
+// verdict is clean folds into ONE counted `specs/` row; a file the reader refuses keeps its own row.
+const SPEC_FRONT = (kind, maxLines, extra = '') =>
+  `---\ntype: spec\nlastUpdated: 2026-08-23\nscope: permanent\nstaleAfter: 90d\nowner: none\nmaxLines: ${maxLines}\nkind: ${kind}\n${extra}---\n`;
+const specBody = (slug) =>
+  `\n# Spec: ${slug}\n\n## Contract\n\nc\n\n## Scenarios\n\n- S1 a :: test/${slug}.test.mjs :: spec:${slug}/S1\n\n## Out of scope\n\n- b\n\n## Module\n\n- src/${slug}/\n`;
+const specRow = (path, kind, errors = []) => makeRow(path, { frontmatter: { type: 'spec', maxLines: '150' }, spec: { kind, status: 'draft', revision: 1, errors, warnings: [] } });
+const SPECS_ROW_RE = /\| \[`specs\/`\]\(\.\/specs\/index\.md\) \| spec \| (\d+) specs \| (\d+) parts · (\d+) indexes \| — \|/;
+
+describe('buildIndex — docs/ai/specs/ store collapse (spec layer 1a)', () => {
+  it('1000 valid specs + their indexes render ONE counted specs/ row; the index stays <= 80 lines', () => {
+    const specs = Array.from({ length: 1000 }, (_, i) => specRow(`docs/ai/specs/d${Math.floor(i / 30)}/s${i}.md`, 'spec'));
+    const indexes = Array.from({ length: 34 }, (_, i) => specRow(`docs/ai/specs/d${i}/index.md`, 'index'));
+    const rows = [makeRow('docs/ai/handover.md'), specRow('docs/ai/specs/index.md', 'index'), ...indexes, ...specs];
+    const out = buildIndex(rows, '2026-08-23');
+    const lines = out.split('\n');
+    expect(lines.filter((l) => l.includes('](./specs/index.md)')).length).toBe(1);
+    expect(out).not.toMatch(/s999\.md/);
+    expect(lines.length <= 80).toBe(true);
+    expect(out.match(SPECS_ROW_RE).slice(1)).toEqual(['1000', '0', '35']);
+  });
+
+  it('the counted row carries live counts per kind; a malformed file under specs/ keeps its OWN visible row beside it', () => {
+    const rows = [specRow('docs/ai/specs/index.md', 'index'), specRow('docs/ai/specs/a/index.md', 'spec'), specRow('docs/ai/specs/a/p.md', 'part'), specRow('docs/ai/specs/b.md', 'spec'), specRow('docs/ai/specs/broken.md', null, [{ rule: 'kind', message: 'x' }])];
+    const out = buildIndex(rows, '2026-08-23');
+    expect(out).toMatch(/specs\/broken\.md/);
+    expect(out.match(SPECS_ROW_RE).slice(1)).toEqual(['2', '1', '1']);
+  });
+
+  it('adding or removing one valid spec drifts the counted row -> the on-disk index is stale', () => {
+    const base = [specRow('docs/ai/specs/index.md', 'index'), specRow('docs/ai/specs/a.md', 'spec')];
+    const onDisk = buildIndex(base, '2026-08-23');
+    expect(checkIndexFreshness([...base, specRow('docs/ai/specs/b.md', 'spec')], onDisk).fresh).toBe(false);
+    expect(checkIndexFreshness(base.slice(0, 1), onDisk).fresh).toBe(false);
+    expect(checkIndexFreshness(base, onDisk).fresh).toBe(true);
+  });
+
+  it('inspectFile reads a file under docs/ai/specs/ through the reader: clean -> spec verdict, malformed -> advisory warnings only', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'specs-inspect-'));
+    try {
+      await mkdir(join(root, 'docs', 'ai', 'specs'), { recursive: true });
+      const clean = join(root, 'docs', 'ai', 'specs', 'login.md');
+      await writeFile(clean, `${SPEC_FRONT('spec', 150, 'status: draft\nrevision: 1\n')}${specBody('login')}`);
+      const ok = await inspectFile(clean, computeToday('2026-08-23'), root);
+      expect(ok.errors).toEqual([]);
+      expect(ok.spec.kind).toBe('spec');
+      expect(ok.spec.errors).toEqual([]);
+      const malformed = join(root, 'docs', 'ai', 'specs', 'broken.md');
+      await writeFile(malformed, `${SPEC_FRONT('spec', 150, 'status: draft\nrevision: 1\n')}${specBody('login')}`);
+      const bad = await inspectFile(malformed, computeToday('2026-08-23'), root);
+      expect(bad.errors).toEqual([]);
+      expect(bad.spec.errors.map((e) => e.rule)).toEqual(['scenario-marker']);
+      expect(bad.warnings.some((w) => /spec scenario-marker/.test(w))).toBe(true);
+      await writeFile(join(root, 'docs', 'ai', 'handover.md'), `${SPEC_FRONT('spec', 150)}\n# outside the store\n`);
+      expect((await inspectFile(join(root, 'docs', 'ai', 'handover.md'), computeToday('2026-08-23'), root)).spec).toBe(null);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('buildIndex', () => {
   it('is deterministic, sorts rows by path, and excludes index.md itself', () => {
-    const rows = [
-      makeRow('docs/ai/index.md'),
-      makeRow('docs/ai/b.md'),
-      makeRow('docs/ai/a.md'),
-    ];
+    const rows = [makeRow('docs/ai/index.md'), makeRow('docs/ai/b.md'), makeRow('docs/ai/a.md')];
     const out = buildIndex(rows, '2026-05-29');
     expect(out).toBe(buildIndex(rows, '2026-05-29')); // deterministic
     expect(out).not.toMatch(/\[`index\.md`\]/); // index.md row excluded
@@ -328,4 +377,19 @@ describe('root parameterization (item (h))', () => {
     expect(stale.status).toBe(1);
     expect(stale.stderr).toMatch(/stale/);
   });
+
+  it('the hook path over a real specs/ store: ONE counted row in the written index, a new spec makes --check-index exit 1', async () => {
+    const store = join(root, 'docs', 'ai', 'specs');
+    await mkdir(store, { recursive: true });
+    await writeFile(join(store, 'index.md'), `${SPEC_FRONT('index', 80)}\n# Specs\n\n> Up: [technical_specification.md](../technical_specification.md)\n\n## Children\n\n- [login](./login.md)\n`);
+    await writeFile(join(store, 'login.md'), `${SPEC_FRONT('spec', 150, 'status: draft\nrevision: 1\n')}${specBody('login')}`);
+    expect(runCli(['--write-index', `--root=${root}`]).status).toBe(0);
+    const index = await readFile(join(root, 'docs', 'ai', 'index.md'), 'utf8');
+    expect(index.match(SPECS_ROW_RE).slice(1)).toEqual(['1', '0', '1']);
+    expect(index).not.toMatch(/specs\/login\.md/);
+    expect(runCli(['--check-index', `--root=${root}`]).status).toBe(0);
+    await writeFile(join(store, 'signup.md'), `${SPEC_FRONT('spec', 150, 'status: draft\nrevision: 1\n')}${specBody('signup')}`);
+    expect(runCli(['--check-index', `--root=${root}`]).status).toBe(1);
+    expect(runCli([`--root=${root}`]).status).toBe(0);
+  });
 });

package/references/scripts/spec-schema.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+// spec-schema.mjs — the ONE reader that DEFINES a well-formed spec document under docs/ai/specs/.
+//
+// Pure text in, verdict out: readSpecDocument(text, rel) never touches the filesystem and imports
+// nothing, so it seeds layout-free into any deployment. The navigator's collapse (check-docs-size.mjs)
+// and the future spec-check read through THIS module — "malformed" has one definition, never two.
+// `rel` is the path INSIDE docs/ai/specs/ (the store root navigator is `index.md`).
+//
+// SPEC_SCHEMA carries the frozen values; the engine canon (references/specs.md) is pinned against it.
+// A refusal names exactly one rule id per defect, so a fixture corpus can be read rule by rule.
+
+export const SPEC_SCHEMA = Object.freeze({
+  storePrefix: 'docs/ai/specs/',
+  navigatorFile: 'index.md',
+  upLink: 'technical_specification.md',
+  upLinkLine: '> Up: [technical_specification.md](../technical_specification.md)',
+  type: 'spec',
+  substrateKeys: Object.freeze(['type', 'lastUpdated', 'scope', 'staleAfter', 'owner', 'maxLines']),
+  kinds: Object.freeze(['index', 'spec', 'part']),
+  statuses: Object.freeze(['draft', 'live', 'retired']),
+  transitions: Object.freeze([Object.freeze(['draft', 'live']), Object.freeze(['live', 'retired'])]),
+  maxLines: Object.freeze({ index: 80, spec: 150, part: 150 }),
+  fanOutMax: 30,
+  slugPattern: '^[a-z0-9]+(-[a-z0-9]+)*$',
+  emptyMarker: '*(empty)*',
+  unboundMarker: 'unbound',
+  titlePrefix: Object.freeze({ index: '# ', spec: '# Spec: ', part: '# Part: ' }),
+  requiredSections: Object.freeze({
+    index: Object.freeze(['## Children']),
+    spec: Object.freeze(['## Contract', '## Scenarios', '## Out of scope', '## Module']),
+    part: Object.freeze([]),
+  }),
+  optionalSections: Object.freeze({ spec: Object.freeze(['## Parts', '## Links']) }),
+  rootOwnedKeys: Object.freeze(['status', 'revision']),
+  rootOwnedSections: Object.freeze(['## Scenarios', '## Out of scope', '## Module', '## Parts']),
+  scenarioGrammar: '- S<N> <name> :: <repo-relative test path> :: spec:<slug>/S<N>  |  - S<N> <name> :: unbound',
+  rules: 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',
+    'module-traversal', 'module-absolute', 'module-backslash', 'module-glob', 'module-mix', 'parts',
+  ]),
+});
+
+// The descriptor check-docs-size.mjs joins to its ADR group: rows under `prefix` whose reader verdict
+// is clean collapse into ONE navigator row linking `navPath`; a row with reader errors stays visible.
+export const SPECS_COLLAPSE = Object.freeze({
+  prefix: SPEC_SCHEMA.storePrefix,
+  navPath: `${SPEC_SCHEMA.storePrefix}${SPEC_SCHEMA.navigatorFile}`,
+  label: 'specs/',
+  type: SPEC_SCHEMA.type,
+});
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+const FIELD_RE = /^([a-zA-Z][a-zA-Z0-9_]*):\s*(.*)$/;
+const SLUG_RE = new RegExp(SPEC_SCHEMA.slugPattern);
+const REVISION_RE = /^[1-9][0-9]*$/;
+const CHILD_LINK_RE = /^- \[([^\]]+)\]\(\.\/([^/)]+)(\/index)?\.md\)$/;
+const PART_LINK_RE = /^- \[([^\]]+)\]\(\.\/([^/)]+)\.md\)$/;
+const SCENARIO_HEAD_RE = /^S([0-9]+) (.+)$/;
+const GLOB_RE = /[*?[\]{}]/;
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:/;
+const SEPARATOR = ' :: ';
+const MD_SUFFIX = '.md';
+
+const FORBIDDEN_SECTIONS = Object.freeze({
+  index: SPEC_SCHEMA.rootOwnedSections,
+  spec: Object.freeze(['## Children']),
+  part: Object.freeze([...SPEC_SCHEMA.rootOwnedSections, '## Children']),
+});
+
+const KNOWN_KEYS = Object.freeze([...SPEC_SCHEMA.substrateKeys, 'kind', ...SPEC_SCHEMA.rootOwnedKeys]);
+
+// The frontmatter is a closed key set: an unknown key, a repeated key or a line that is not
+// `key: value` is a defect (`frontmatter-key`), never silently dropped or last-one-wins.
+const parseFrontmatter = (text) => {
+  const match = text.match(FRONTMATTER_RE);
+  if (!match) return null;
+  const fields = {};
+  const defects = [];
+  for (const line of match[1].split('\n')) {
+    const m = line.match(FIELD_RE);
+    if (!m) defects.push(`"${line}" is not \`key: value\``);
+    else if (!KNOWN_KEYS.includes(m[1])) defects.push(`unknown key ${m[1]}`);
+    else if (m[1] in fields) defects.push(`duplicate key ${m[1]}`);
+    else fields[m[1]] = m[2].trim();
+  }
+  return { fields, defects, body: text.slice(match[0].length) };
+};
+
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+
+// The body as { title, sections: [{ heading, lines }], preamble, fenced } — the title is the FIRST
+// `# ` line, every `## ` line opens a section, the lines before the first section are the preamble.
+// The reader parses NO markdown code: a fence line is recorded (the `fence` refusal) rather than
+// modelled, so a spec carries no code sample and no line is ever ambiguous between code and structure.
+const parseBody = (body) => {
+  const sections = [];
+  const preamble = [];
+  const fenced = [];
+  const state = { title: null, current: null, sectionBeforeTitle: false };
+  for (const raw of body.split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (FENCE_RE.test(line)) fenced.push(line);
+    if (line.startsWith('## ')) {
+      if (state.title === null) state.sectionBeforeTitle = true;
+      state.current = { heading: line, lines: [] };
+      sections.push(state.current);
+    } else if (state.title === null && line.startsWith('# ')) {
+      state.title = line;
+    } else {
+      (state.current ? state.current.lines : preamble).push(line);
+    }
+  }
+  return { title: state.title, sections, preamble, fenced, sectionBeforeTitle: state.sectionBeforeTitle };
+};
+
+// Lexical classification of a repo-relative path field — the same vocabulary for module roots and
+// scenario bindings. Realpath/symlink containment needs the filesystem and is the checker's duty.
+export const classifyPath = (path) => {
+  if (path.trim() === '') return 'empty';
+  if (path.includes('\\')) return 'backslash';
+  if (path.startsWith('/') || WINDOWS_DRIVE_RE.test(path)) return 'absolute';
+  if (path.split('/').includes('..')) return 'traversal';
+  if (GLOB_RE.test(path)) return 'glob';
+  return path.endsWith('/') ? 'dir' : 'file';
+};
+
+const MODULE_PATH_RULES = Object.freeze({
+  empty: 'module-empty',
+  backslash: 'module-backslash',
+  absolute: 'module-absolute',
+  traversal: 'module-traversal',
+  glob: 'module-glob',
+});
+
+// A bare `-` is a bullet with a blank payload (trailing whitespace is stripped before parsing).
+const isBullet = (line) => line === '-' || line.startsWith('- ');
+const bulletsOf = (lines) => lines.filter(isBullet).map((line) => line.slice(2));
+const contentOf = (lines) => lines.filter((line) => line.trim() !== '');
+
+// The slug a document owns: the file stem for a flat file, the folder name for an index.md.
+const describeRel = (rel) => {
+  const segments = rel.split('/');
+  const file = segments[segments.length - 1];
+  const dirs = segments.slice(0, -1);
+  const stem = file.endsWith(MD_SUFFIX) ? file.slice(0, -MD_SUFFIX.length) : file;
+  const isIndexFile = file === SPEC_SCHEMA.navigatorFile;
+  const slug = isIndexFile ? dirs[dirs.length - 1] ?? null : stem;
+  const slugSegments = [...dirs, ...(isIndexFile ? [] : [stem])];
+  return { dirs, stem, isIndexFile, slug, slugSegments, isStoreRoot: rel === SPEC_SCHEMA.navigatorFile };
+};
+
+const checkFrontmatter = (fields, kind, errors) => {
+  const missing = SPEC_SCHEMA.substrateKeys.filter((key) => !(key in fields));
+  if (missing.length > 0) errors.push({ rule: 'substrate-key', message: `frontmatter is missing ${missing.join(', ')}` });
+  if ('type' in fields && fields.type !== SPEC_SCHEMA.type) errors.push({ rule: 'type', message: `type must be ${SPEC_SCHEMA.type}` });
+  if ('maxLines' in fields && fields.maxLines !== String(SPEC_SCHEMA.maxLines[kind])) {
+    errors.push({ rule: 'maxlines', message: `a ${kind} carries maxLines: ${SPEC_SCHEMA.maxLines[kind]}` });
+  }
+  if (kind === 'spec') {
+    if (!SPEC_SCHEMA.statuses.includes(fields.status)) errors.push({ rule: 'status', message: `status must be one of ${SPEC_SCHEMA.statuses.join('|')}` });
+    if (!REVISION_RE.test(fields.revision ?? '')) errors.push({ rule: 'revision', message: 'revision must be an integer >= 1' });
+  } else {
+    const carried = SPEC_SCHEMA.rootOwnedKeys.filter((key) => key in fields);
+    if (carried.length > 0) errors.push({ rule: 'root-owns', message: `a ${kind} never carries ${carried.join(', ')} — the contract root owns them` });
+  }
+};
+
+const checkPath = (rel, kind, errors) => {
+  const at = describeRel(rel);
+  const badSegment = at.slugSegments.find((segment) => !SLUG_RE.test(segment));
+  if (badSegment !== undefined) errors.push({ rule: 'slug', message: `"${badSegment}" is not a slug (${SPEC_SCHEMA.slugPattern})` });
+  if (kind === 'index' && !at.isIndexFile) errors.push({ rule: 'kind-path', message: 'a kind: index document is an index.md' });
+  if (kind === 'part' && (at.isIndexFile || at.dirs.length === 0)) errors.push({ rule: 'kind-path', message: 'a kind: part document is a <name>.md beside a promoted root, never an index.md or a store-root file' });
+  if (kind === 'spec' && at.isIndexFile && at.slug === null) errors.push({ rule: 'kind-path', message: 'the store root is the navigator, never a contract root' });
+  return at;
+};
+
+const checkSections = (parsed, kind, errors) => {
+  const headings = parsed.sections.map((section) => section.heading);
+  const prefix = SPEC_SCHEMA.titlePrefix[kind];
+  if (parsed.title === null || parsed.sectionBeforeTitle || !parsed.title.startsWith(prefix) || parsed.title.slice(prefix.length).trim() === '') {
+    errors.push({ rule: 'title', message: `the FIRST heading is \`${prefix}<title>\`, before every section` });
+  }
+  const required = SPEC_SCHEMA.requiredSections[kind];
+  const missing = required.filter((heading) => !headings.includes(heading));
+  if (missing.length > 0) errors.push({ rule: 'section-missing', message: `missing ${missing.join(', ')}` });
+  const ordered = [...required, ...(SPEC_SCHEMA.optionalSections[kind] ?? [])];
+  const positions = ordered.filter((heading) => headings.includes(heading)).map((heading) => headings.indexOf(heading));
+  if (missing.length === 0 && positions.some((position, i) => i > 0 && position < positions[i - 1])) {
+    errors.push({ rule: 'section-order', message: `sections run ${ordered.join(', ')}` });
+  }
+  const forbidden = FORBIDDEN_SECTIONS[kind].filter((heading) => headings.includes(heading));
+  if (forbidden.length > 0) errors.push({ rule: 'section-forbidden', message: `a ${kind} never carries ${forbidden.join(', ')}` });
+};
+
+const sectionLines = (parsed, heading) => parsed.sections.find((section) => section.heading === heading)?.lines ?? null;
+
+const checkChildren = (parsed, errors) => {
+  const lines = sectionLines(parsed, '## Children');
+  if (lines === null) return;
+  const targets = [];
+  for (const line of contentOf(lines)) {
+    const m = line.match(CHILD_LINK_RE);
+    if (!m || !SLUG_RE.test(m[2])) {
+      errors.push({ rule: 'children-link', message: `"${line}" is not \`- [name](./<child>.md)\` or \`- [name](./<child>/index.md)\`` });
+      return;
+    }
+    targets.push(m[2]);
+  }
+  const duplicate = targets.find((target, i) => targets.indexOf(target) !== i);
+  if (duplicate !== undefined) errors.push({ rule: 'children-duplicate', message: `child "${duplicate}" is listed twice` });
+  if (targets.length > SPEC_SCHEMA.fanOutMax) errors.push({ rule: 'fan-out', message: `${targets.length} children > ${SPEC_SCHEMA.fanOutMax} — subdivide along slice boundaries` });
+};
+
+const parseScenario = (line) => {
+  if (!line.startsWith('- ')) return null;
+  const fields = line.slice(2).split(SEPARATOR);
+  const head = fields[0].match(SCENARIO_HEAD_RE);
+  if (!head) return null;
+  const base = { n: Number(head[1]), name: head[2] };
+  if (fields.length === 2 && fields[1] === SPEC_SCHEMA.unboundMarker) return { ...base, bound: false };
+  if (fields.length === 3) return { ...base, bound: true, path: fields[1], marker: fields[2] };
+  return null;
+};
+
+const checkScenarios = (parsed, slug, status, errors, warnings) => {
+  const lines = sectionLines(parsed, '## Scenarios');
+  if (lines === null) return;
+  const scenarios = [];
+  for (const line of contentOf(lines)) {
+    const scenario = parseScenario(line);
+    if (scenario === null) {
+      errors.push({ rule: 'scenario-line', message: `"${line}" does not match \`${SPEC_SCHEMA.scenarioGrammar}\`` });
+      return;
+    }
+    scenarios.push(scenario);
+  }
+  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) {
+    if (!scenario.bound) {
+      if (status === 'live') warnings.push({ rule: 'unbound', message: `S${scenario.n} is unbound on a live spec` });
+      continue;
+    }
+    const expected = `spec:${slug}/S${scenario.n}`;
+    if (scenario.marker !== expected) errors.push({ rule: 'scenario-marker', message: `S${scenario.n} marker "${scenario.marker}" must be "${expected}"` });
+    if (classifyPath(scenario.path) !== 'file') errors.push({ rule: 'scenario-path', message: `S${scenario.n} test path "${scenario.path}" is not a repo-relative file` });
+  }
+};
+
+const checkOutOfScope = (parsed, errors) => {
+  const lines = sectionLines(parsed, '## Out of scope');
+  if (lines === null) return;
+  const content = contentOf(lines);
+  const exclusions = bulletsOf(content).filter((text) => text.trim() !== '');
+  if (exclusions.length === 0 && !(content.length === 1 && content[0] === SPEC_SCHEMA.emptyMarker)) {
+    errors.push({ rule: 'out-of-scope', message: `at least one non-blank \`- \` bullet, or exactly \`${SPEC_SCHEMA.emptyMarker}\`` });
+  }
+};
+
+const checkModule = (parsed, status, errors) => {
+  const lines = sectionLines(parsed, '## Module');
+  if (lines === null) return;
+  const content = contentOf(lines);
+  const isEmptyMarker = content.length === 1 && content[0] === SPEC_SCHEMA.emptyMarker;
+  const prose = isEmptyMarker ? undefined : content.find((line) => !isBullet(line));
+  if (prose !== undefined) {
+    errors.push({ rule: 'module-line', message: `"${prose}" — every ## Module line is a \`- <path>\` bullet` });
+    return;
+  }
+  const paths = bulletsOf(content);
+  if (paths.length === 0) {
+    if (!(status === 'retired' && isEmptyMarker)) {
+      errors.push({ rule: 'module-empty', message: `a module root is required (\`${SPEC_SCHEMA.emptyMarker}\` only on a retired spec)` });
+    }
+    return;
+  }
+  const kinds = paths.map(classifyPath);
+  const offending = kinds.map((kind, i) => (kind in MODULE_PATH_RULES ? { rule: MODULE_PATH_RULES[kind], path: paths[i] } : null)).filter(Boolean);
+  if (offending.length > 0) {
+    for (const { rule, path } of offending) errors.push({ rule, message: `module path "${path}" refused` });
+    return;
+  }
+  const dirs = kinds.filter((kind) => kind === 'dir').length;
+  if (!(dirs === 1 && paths.length === 1) && dirs !== 0) {
+    errors.push({ rule: 'module-mix', message: 'the module is ONE `dir/` root OR a literal file list' });
+  }
+};
+
+const checkParts = (parsed, at, errors) => {
+  const lines = sectionLines(parsed, '## Parts');
+  if (lines === null) return;
+  if (!at.isIndexFile) {
+    errors.push({ rule: 'parts', message: 'only a promoted root (<slug>/index.md) carries ## Parts' });
+    return;
+  }
+  const names = [];
+  for (const line of contentOf(lines)) {
+    const m = line.match(PART_LINK_RE);
+    if (!m || !SLUG_RE.test(m[2])) {
+      errors.push({ rule: 'parts', message: `"${line}" is not \`- [name](./<part>.md)\`` });
+      return;
+    }
+    names.push(m[2]);
+  }
+  const duplicate = names.find((name, i) => names.indexOf(name) !== i);
+  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.
+export const readSpecDocument = (text, rel) => {
+  const errors = [];
+  const warnings = [];
+  const verdict = (kind, status, revision) => ({ kind, status, revision, errors, warnings });
+  const front = parseFrontmatter(text.replace(/\r\n/g, '\n'));
+  if (front === null) {
+    errors.push({ rule: 'frontmatter', message: 'missing YAML frontmatter' });
+    return verdict(null, null, null);
+  }
+  const { fields, defects, body } = front;
+  if (defects.length > 0) {
+    errors.push({ rule: 'frontmatter-key', message: defects.join('; ') });
+    return verdict(null, null, null);
+  }
+  const kind = fields.kind;
+  if (!SPEC_SCHEMA.kinds.includes(kind)) {
+    errors.push({ rule: 'kind', message: `kind must be one of ${SPEC_SCHEMA.kinds.join('|')}` });
+    return verdict(null, null, null);
+  }
+  checkFrontmatter(fields, kind, errors);
+  const at = checkPath(rel, kind, errors);
+  const parsed = parseBody(body);
+  if (parsed.fenced.length > 0) errors.push({ rule: 'fence', message: `"${parsed.fenced[0]}" — a spec document carries no code fence` });
+  checkSections(parsed, kind, errors);
+  if (kind === 'index') {
+    checkChildren(parsed, errors);
+    if (at.isStoreRoot && !parsed.preamble.includes(SPEC_SCHEMA.upLinkLine)) {
+      errors.push({ rule: 'root-uplink', message: `the store root carries the line \`${SPEC_SCHEMA.upLinkLine}\` before its first section` });
+    }
+  }
+  if (kind === 'spec') {
+    checkScenarios(parsed, at.slug, fields.status, errors, warnings);
+    checkOutOfScope(parsed, errors);
+    checkModule(parsed, fields.status, errors);
+    checkParts(parsed, at, errors);
+  }
+  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);
+};

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

@@ -0,0 +1,212 @@
+import { describe, it } from 'node:test';
+import { expect } from './_expect-shim.mjs';
+
+// Dynamic import: the suite LOADS without the module (red-proof observes it failing pre-fix).
+const reader = await import('./spec-schema.mjs').catch(() => ({}));
+const { readSpecDocument, classifyPath, SPEC_SCHEMA, SPECS_COLLAPSE } = reader;
+
+// Inline fixtures ONLY — this suite runs inside a deployed project's scripts/ where no corpus exists.
+// The repo-only corpus (engine test/fixtures/specs) is the durable record; this is the unit pin.
+
+const frontmatter = (fields) =>
+  `---\n${Object.entries(fields).map(([key, value]) => `${key}: ${value}`).join('\n')}\n---\n`;
+
+const SUBSTRATE = { type: 'spec', lastUpdated: '2026-08-23', scope: 'permanent', staleAfter: '90d', owner: 'none' };
+const UPLINK_LINE = '> Up: [technical_specification.md](../technical_specification.md)';
+
+const specDoc = ({ fields = {}, drop = [], title = '# Spec: Login', scenarios, outOfScope = '- Password reset', module = '- src/login/', extra = '' } = {}) => {
+  const all = { ...SUBSTRATE, maxLines: '150', kind: 'spec', status: 'draft', revision: '1', ...fields };
+  for (const key of drop) delete all[key];
+  const lines = scenarios ?? ['- S1 happy path :: test/login.test.mjs :: spec:login/S1', '- S2 lockout :: unbound'];
+  return `${frontmatter(all)}\n${title}\n\n## Contract\n\nAccepts a credential pair.\n\n## Scenarios\n\n${lines.join('\n')}\n\n## Out of scope\n\n${outOfScope}\n\n## Module\n\n${module}\n${extra}`;
+};
+
+const indexDoc = ({ fields = {}, children = ['- [login](./login.md)', '- [billing](./billing/index.md)'], preamble = '', title = '# Auth' } = {}) =>
+  `${frontmatter({ ...SUBSTRATE, maxLines: '80', kind: 'index', ...fields })}\n${title}\n${preamble}\n## Children\n\n${children.join('\n')}\n`;
+
+const partDoc = ({ fields = {}, title = '# Part: Sessions', extra = '' } = {}) =>
+  `${frontmatter({ ...SUBSTRATE, maxLines: '150', kind: 'part', ...fields })}\n${title}\n\nSession details.\n${extra}`;
+
+const rulesOf = (verdict) => verdict.errors.map((e) => e.rule);
+const refuses = (text, rel, rule) => {
+  const verdict = readSpecDocument(text, rel);
+  expect(rulesOf(verdict)).toEqual([rule]);
+};
+
+describe('readSpecDocument — accept', () => {
+  it('a flat draft spec reads clean with kind/status/revision', () => {
+    const verdict = readSpecDocument(specDoc(), 'login.md');
+    expect(verdict.errors).toEqual([]);
+    expect(verdict.warnings).toEqual([]);
+    expect({ kind: verdict.kind, status: verdict.status, revision: verdict.revision }).toEqual({ kind: 'spec', status: 'draft', revision: 1 });
+  });
+
+  it('a promoted root under <slug>/index.md with ## Parts and ## Links reads clean', () => {
+    const text = specDoc({ extra: '\n## Parts\n\n- [sessions](./sessions.md)\n\n## Links\n\n- [[AD-112]]\n' });
+    expect(readSpecDocument(text, 'auth/login/index.md').errors).toEqual([]);
+  });
+
+  it('a domain index, the store root (with the up-link) and a part read clean', () => {
+    expect(readSpecDocument(indexDoc(), 'auth/index.md').errors).toEqual([]);
+    const root = indexDoc({ preamble: `\n${UPLINK_LINE}\n`, children: [] });
+    const rootVerdict = readSpecDocument(root, 'index.md');
+    expect(rootVerdict.errors).toEqual([]);
+    expect(rootVerdict.kind).toBe('index');
+    expect(readSpecDocument(partDoc(), 'auth/login/sessions.md').errors).toEqual([]);
+  });
+
+  it('a retired spec may carry *(empty)* as its module; a live spec with an unbound scenario WARNS, never refuses', () => {
+    const retired = specDoc({ fields: { status: 'retired' }, module: '*(empty)*', scenarios: ['- S1 gone :: unbound'] });
+    expect(readSpecDocument(retired, 'login.md').errors).toEqual([]);
+    const live = readSpecDocument(specDoc({ fields: { status: 'live', revision: '3' } }), 'login.md');
+    expect(live.errors).toEqual([]);
+    expect(live.warnings.map((w) => w.rule)).toEqual(['unbound']);
+  });
+
+  it('CRLF line endings read identically', () => {
+    expect(readSpecDocument(specDoc().replace(/\n/g, '\r\n'), 'login.md').errors).toEqual([]);
+  });
+
+  it('*(empty)* is a legal Out of scope; a file-list module is legal', () => {
+    const text = specDoc({ outOfScope: '*(empty)*', module: '- src/a.mjs\n- src/b.mjs' });
+    expect(readSpecDocument(text, 'login.md').errors).toEqual([]);
+  });
+});
+
+describe('readSpecDocument — refuse, exactly one rule per defect', () => {
+  it('frontmatter / substrate-key / type / kind / maxlines', () => {
+    refuses('# Spec: Login\n', 'login.md', 'frontmatter');
+    refuses(specDoc({ drop: ['owner'] }), 'login.md', 'substrate-key');
+    refuses(specDoc({ fields: { type: 'reference' } }), 'login.md', 'type');
+    refuses(specDoc({ fields: { kind: 'feature' } }), 'login.md', 'kind');
+    refuses(specDoc({ drop: ['kind'] }), 'login.md', 'kind');
+    refuses(specDoc({ fields: { maxLines: '400' } }), 'login.md', 'maxlines');
+  });
+
+  it('status / revision / root-owns', () => {
+    refuses(specDoc({ fields: { status: 'approved' } }), 'login.md', 'status');
+    refuses(specDoc({ drop: ['status'] }), 'login.md', 'status');
+    refuses(specDoc({ fields: { revision: '0' } }), 'login.md', 'revision');
+    refuses(specDoc({ fields: { revision: '1.5' } }), 'login.md', 'revision');
+    refuses(indexDoc({ fields: { status: 'draft' } }), 'auth/index.md', 'root-owns');
+    refuses(partDoc({ fields: { revision: '2' } }), 'auth/login/sessions.md', 'root-owns');
+  });
+
+  it('slug / kind-path / root-uplink', () => {
+    refuses(specDoc({ scenarios: ['- S1 x :: unbound'] }), 'Login_Page.md', 'slug');
+    refuses(indexDoc(), 'auth/Auth Stuff/index.md', 'slug');
+    refuses(indexDoc(), 'auth/overview.md', 'kind-path');
+    refuses(partDoc(), 'auth/login/index.md', 'kind-path');
+    refuses(specDoc({ scenarios: ['- S1 x :: unbound'] }), 'index.md', 'kind-path');
+    refuses(indexDoc({ children: [] }), 'index.md', 'root-uplink');
+  });
+
+  it('title / section-missing / section-order / section-forbidden', () => {
+    refuses(specDoc({ title: '# Login' }), 'login.md', 'title');
+    refuses(specDoc({ title: '# Spec:   ' }), 'login.md', 'title');
+    refuses(partDoc({ title: '# Sessions' }), 'auth/login/sessions.md', 'title');
+    refuses(specDoc().replace('## Out of scope', '## Out-of-scope'), 'login.md', 'section-missing');
+    refuses(specDoc().replace('## Contract\n\nAccepts a credential pair.\n\n', '').concat('\n## Contract\n\nlate\n'), 'login.md', 'section-order');
+    refuses(indexDoc().concat('\n## Module\n\n- src/\n'), 'auth/index.md', 'section-forbidden');
+    refuses(partDoc({ extra: '\n## Scenarios\n\n- S1 x :: unbound\n' }), 'auth/login/sessions.md', 'section-forbidden');
+  });
+
+  it('children-link / children-duplicate / fan-out', () => {
+    refuses(indexDoc({ children: ['- login'] }), 'auth/index.md', 'children-link');
+    refuses(indexDoc({ children: ['- [login](../login.md)'] }), 'auth/index.md', 'children-link');
+    refuses(indexDoc({ children: ['- [login](./login.md)', '- [login again](./login.md)'] }), 'auth/index.md', 'children-duplicate');
+    const many = Array.from({ length: SPEC_SCHEMA.fanOutMax + 1 }, (_, i) => `- [c${i}](./c${i}.md)`);
+    refuses(indexDoc({ children: many }), 'auth/index.md', 'fan-out');
+    expect(readSpecDocument(indexDoc({ children: many.slice(0, SPEC_SCHEMA.fanOutMax) }), 'auth/index.md').errors).toEqual([]);
+  });
+
+  it('scenario-line / scenario-number / scenario-marker / scenario-path', () => {
+    refuses(specDoc({ scenarios: ['- S1 no binding'] }), 'login.md', 'scenario-line');
+    refuses(specDoc({ scenarios: ['S1 happy :: unbound'] }), 'login.md', 'scenario-line');
+    refuses(specDoc({ scenarios: ['- S1 a :: unbound', '- S3 b :: unbound'] }), 'login.md', 'scenario-number');
+    refuses(specDoc({ scenarios: ['- S2 a :: unbound'] }), 'login.md', 'scenario-number');
+    refuses(specDoc({ scenarios: ['- S1 a :: test/login.test.mjs :: spec:login/S2'] }), 'login.md', 'scenario-marker');
+    refuses(specDoc({ scenarios: ['- S1 a :: test/login.test.mjs :: spec:signup/S1'] }), 'login.md', 'scenario-marker');
+    refuses(specDoc({ scenarios: ['- S1 a :: ../test/login.test.mjs :: spec:login/S1'] }), 'login.md', 'scenario-path');
+    refuses(specDoc({ scenarios: ['- S1 a :: /abs/login.test.mjs :: spec:login/S1'] }), 'login.md', 'scenario-path');
+  });
+
+  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');
+    refuses(specDoc({ outOfScope: '- ' }), 'login.md', 'out-of-scope');
+    refuses(specDoc({ module: '' }), 'login.md', 'module-empty');
+    refuses(specDoc({ module: '*(empty)*' }), 'login.md', 'module-empty');
+    refuses(specDoc({ module: '- ../src/' }), 'login.md', 'module-traversal');
+    refuses(specDoc({ module: '- /src/login/' }), 'login.md', 'module-absolute');
+    refuses(specDoc({ module: '- C:/src/login/' }), 'login.md', 'module-absolute');
+    refuses(specDoc({ module: '- src\\login\\' }), 'login.md', 'module-backslash');
+    refuses(specDoc({ module: '- src/**/*.mjs' }), 'login.md', 'module-glob');
+    refuses(specDoc({ module: '- src/login/\n- src/login/a.mjs' }), 'login.md', 'module-mix');
+    refuses(specDoc({ module: '- src/login/\n- src/signup/' }), 'login.md', 'module-mix');
+    refuses(specDoc({ extra: '\n## Parts\n\n- [sessions](./sessions.md)\n' }), 'login.md', 'parts');
+    refuses(specDoc({ extra: '\n## Parts\n\n- sessions\n' }), 'auth/login/index.md', 'parts');
+    refuses(specDoc({ extra: '\n## Parts\n\n- [a](./a.md)\n- [b](./a.md)\n' }), 'auth/login/index.md', 'parts');
+  });
+
+  it('frontmatter-key: an unknown key, a duplicate key and a malformed line each refuse; an absent type is substrate-key ALONE', () => {
+    refuses(specDoc({ fields: { priority: 'high' } }), 'login.md', 'frontmatter-key');
+    refuses(specDoc().replace('owner: none\n', 'owner: none\nowner: none\n'), 'login.md', 'frontmatter-key');
+    refuses(specDoc().replace('owner: none\n', 'owner: none\n- a list item\n'), 'login.md', 'frontmatter-key');
+    refuses(specDoc({ drop: ['type'] }), 'login.md', 'substrate-key');
+  });
+
+  it('a part at the store root (no folder) is kind-path; a blank binding path is scenario-path; a blank module bullet is module-empty', () => {
+    refuses(partDoc(), 'orphan.md', 'kind-path');
+    refuses(specDoc({ scenarios: ['- S1 a ::  :: spec:login/S1'] }), 'login.md', 'scenario-path');
+    refuses(specDoc({ module: '- ' }), 'login.md', 'module-empty');
+  });
+
+  it('module-line: prose beside a module bullet refuses; root-uplink needs the exact markdown link, not a mention', () => {
+    refuses(specDoc({ module: 'the root is\n- src/login/' }), 'login.md', 'module-line');
+    refuses(indexDoc({ preamble: '\nSee technical_specification.md for the top spec.\n', children: [] }), 'index.md', 'root-uplink');
+    expect(readSpecDocument(indexDoc({ preamble: `\n${UPLINK_LINE}\n`, children: [] }), 'index.md').errors).toEqual([]);
+  });
+
+  it('the reader parses no markdown code: a fence line refuses `fence`; the up-link is a whole exact line, so an inline span or a trailing note is root-uplink', () => {
+    refuses(indexDoc({ preamble: `\n${UPLINK_LINE}\n\n\`\`\`\n${UPLINK_LINE}\n\`\`\`\n`, children: [] }), 'index.md', 'fence');
+    refuses(partDoc({ extra: '\n~~~js\nconst sample = 1;\n~~~\n' }), 'auth/login/sessions.md', 'fence');
+    refuses(indexDoc({ preamble: `\nWrite \`\`${UPLINK_LINE}\`\` here.\n`, children: [] }), 'index.md', 'root-uplink');
+    refuses(indexDoc({ preamble: `\n${UPLINK_LINE} — the top spec\n`, children: [] }), 'index.md', 'root-uplink');
+  });
+
+  it('a frontmatter defect ENDS the read with frontmatter-key alone (a malformed kind line is not a missing kind)', () => {
+    refuses(specDoc().replace('kind: spec\n', 'kind spec\n'), 'login.md', 'frontmatter-key');
+    refuses(specDoc({ fields: { priority: 'high', kind: 'feature' } }), 'login.md', 'frontmatter-key');
+  });
+
+  it('the title precedes every section; prose-only Module is module-line; a blank Module on a retired spec is module-empty', () => {
+    refuses(specDoc().replace('# Spec: Login\n', '## Surprise\n\nx\n\n# Spec: Login\n'), 'login.md', 'title');
+    refuses(specDoc({ module: 'the root is src' }), 'login.md', 'module-line');
+    refuses(specDoc({ fields: { status: 'retired' }, module: '' }), 'login.md', 'module-empty');
+  });
+
+  it('every rule id a refusal names is declared in SPEC_SCHEMA.rules', () => {
+    for (const rule of ['frontmatter', 'frontmatter-key', 'fence', 'kind', 'module-mix', 'module-line', 'scenario-path', 'parts', 'root-uplink']) {
+      expect(SPEC_SCHEMA.rules.includes(rule)).toBe(true);
+    }
+    expect(new Set(SPEC_SCHEMA.rules).size).toBe(SPEC_SCHEMA.rules.length);
+  });
+});
+
+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([
+      'dir', 'file', 'traversal', 'absolute', 'absolute', 'backslash', 'glob',
+    ]);
+  });
+
+  it('SPEC_SCHEMA carries the frozen numbers and SPECS_COLLAPSE joins the store root', () => {
+    expect(SPEC_SCHEMA.fanOutMax).toBe(30);
+    expect(SPEC_SCHEMA.maxLines).toEqual({ index: 80, spec: 150, part: 150 });
+    expect(SPEC_SCHEMA.statuses).toEqual(['draft', 'live', 'retired']);
+    expect(SPEC_SCHEMA.kinds).toEqual(['index', 'spec', 'part']);
+    expect(Object.isFrozen(SPEC_SCHEMA)).toBe(true);
+    expect(SPECS_COLLAPSE).toEqual({ prefix: 'docs/ai/specs/', navPath: 'docs/ai/specs/index.md', label: 'specs/', type: 'spec' });
+  });
+});

package/references/templates/AGENTS.md

@@ -37,7 +37,7 @@ All project knowledge lives in `docs/ai/`. Layered, lazy-loaded context:
 | [`docs/ai/handover.md`](./docs/ai/handover.md) | **Start of every session** | End of session if context changed |
 | [`docs/ai/active_plan.md`](./docs/ai/active_plan.md) | Picking next task | Completing a task |
 | [`docs/ai/current_state.md`](./docs/ai/current_state.md) | Need system overview | After feature completion |
-| [`docs/ai/technical_specification.md`](./docs/ai/technical_specification.md) | App overview & data models | Data-model changes |
+| [`docs/ai/technical_specification.md`](./docs/ai/technical_specification.md) | App overview & data models; feature contracts live under `docs/ai/specs/` | Data-model or contract changes |
 | [`docs/ai/pages/index.md`](./docs/ai/pages/index.md) | Understanding a page | Page behaviour changes |
 | [`docs/ai/architecture.md`](./docs/ai/architecture.md) | Understanding structure | Architecture changes |
 | [`docs/ai/known_issues.md`](./docs/ai/known_issues.md) | Debugging | New issue discovered |
@@ -72,7 +72,7 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 | Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
 | No business logic in components → hooks/services | Architecture review |
 | No changes without tests (TDD) | Required |
-| Check page docs before changes; update them after | Process |
+| Check the governing spec(s) + page docs before changes; update them after | Process |
 | Ask user before committing | Process |
 | Every page has an HTML-validity / a11y E2E test | Required |
 | **No silent failures** — structured logging on every rejected action | Required |

package/references/templates/SPEC_TEMPLATE.md

@@ -0,0 +1,45 @@
+---
+type: spec
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 150
+kind: spec
+status: draft
+revision: 1
+---
+
+# Spec: example-feature
+
+> Authoring reference for a `kind: spec` contract root — copy it to `docs/ai/specs/<slug>.md`
+> (the slug mirrors the feature-slice or module name, `^[a-z0-9]+(-[a-z0-9]+)*$`) and replace every
+> section. NOT deployed on bootstrap — it stays in the skill home like `adr-record.md`. The full
+> schema (kinds, statuses, transitions, promotion, precedence) is the engine canon `references/specs.md`;
+> the deployed reader `scripts/spec-schema.mjs` is what decides well-formed.
+
+## Contract
+
+What the feature accepts and returns, stated as invariants a test can pin. A `draft` spec is authored
+WITH the plan that lands the feature and exists at plan review; approval of that plan confirms the
+contract (no separate stop). It becomes `live` on the plan's landing row; `revision` increments by one
+per live contract change; `retired` on the removal row — never backwards.
+
+## Scenarios
+
+- S1 accepts a well-formed request :: test/example-feature.test.mjs :: spec:example-feature/S1
+- S2 refuses a malformed request with a typed error :: unbound
+
+## Out of scope
+
+- The neighbouring feature this one is often confused with (name it — exclusions are the core value)
+- Retry, caching and observability concerns owned by their own slices
+
+## Module
+
+- src/example-feature/
+
+## Links
+
+- [[AD-NNN]] — the decision that shaped this contract
+- `pages/<page>.md` — the page spec this feature's view layer is described in (a subordinate view)

package/references/templates/agent_rules.md

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

package/references/templates/specs/index.md

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

package/tools/known-footprint.mjs

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