@sabaiway/agent-workflow-memory 4.5.4 → 4.6.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.6.0 — the feature-spec layer: a store under `docs/ai/specs/`, one text-only reader, a counted navigator row (AD-112)
+
+A deployed project gains a middle altitude of durable knowledge between the whole-project
+`technical_specification.md` and the ephemeral plan: one contract per feature — what it accepts and
+returns, which scenarios pin it, and, the part the family actually suffers from, what is OUT of its
+scope. This is an adapted layer in the substrate's own vocabulary, not a methodology import: the
+existing plan-approval checkpoint confirms a contract, the existing `maxLines` caps bound every file,
+the existing `[[AD-NNN]]` convention links the why, and hidden mode covers the store with no new
+machinery (`/docs/ai/` already subsumes it).
+
+- **`references/scripts/spec-schema.mjs`** (+ its deploy-payload test) — the ONE reader that DEFINES
+  a well-formed spec. Pure text in (`readSpecDocument(text, rel)`), a verdict out; it imports nothing
+  and opens no file, so it seeds layout-free into any deployment. It carries the frozen schema
+  (`SPEC_SCHEMA`: kinds `index|spec|part`, statuses `draft|live|retired`, fan-out 30, promotion at
+  `maxLines: 150`, the kebab slug, the scenario-binding grammar, the module-root grammar) and names
+  exactly ONE rule id per defect — 33 rules, each pinned by a repo-only fixture. It models no markdown
+  code: a fence line refuses, a spec carries no code sample.
+- **`references/scripts/check-docs-size.mjs`** — the ADR-only collapse became a GROUPS loop the spec
+  store joins: every file the reader accepts folds into ONE `specs/` navigator row with live counts
+  (specs / parts / indexes), so adding or removing a valid spec changes the generated index and
+  `--check-index` sees it; a file the reader refuses keeps its own visible row and its schema
+  refusal surfaces as `spec <rule>:` WARNINGS — advisory (the structural checker is a later slice);
+  the substrate's own frontmatter and `maxLines` errors stay blocking, as for every `docs/ai` file.
+  The 591-line ratchet held by trimming prose, not by raising a record.
+- **`references/templates/specs/index.md`** — the seed store root (`kind: index`, the exact up-link
+  line to `technical_specification.md`, an empty `## Children`); deployed by the bootstrap like the
+  `adr/` seed. **`references/templates/SPEC_TEMPLATE.md`** — the `kind: spec` authoring reference
+  with one bound and one unbound scenario; skill-home only, excluded by NAME like `adr-record.md` —
+  in the SKILL prose AND in the bootstrap E2E copy loop, which also runs the real installed
+  pre-commit hook over a seeded spec and asserts the one counted row.
+- **`references/templates/agent_rules.md`** §1.2/§1.3 — name the governing spec(s) before a
+  feature (zero, one or many; page-only coverage governs as an adoption shim), the revision lands
+  with the code; the `### 2.6` lens region carries the engine's new `Spec-first` bullet.
+  **`references/templates/AGENTS.md`** — the `technical_specification.md` Memory-Map row now points
+  at the contracts under `docs/ai/specs/` (96 lines; the cap is 100).
+- **Scale is a release gate.** 1000 valid specs in a 30-per-folder tree: both hook runs sum to a
+  median of 843 ms against a 1500 ms budget (pre-slice 0.75 s for 1161 docs); over budget blocks the
+  release.
+
+**Reaches a FRESH bootstrap only.** An existing deployment keeps its old checker (which never imports
+the reader) and has no `docs/ai/specs/` to collapse; delivery to existing deployments — the `specs`
+ensure op, the layout-free reader seed, the prior-matching checker refresh, an upgrade E2E — is slice
+1b of the same series.
+
 ## 4.5.4 — the deployed `agent_rules.md` carries the state-table clause (AD-111)
 
 Template-only follow-up to engine 3.2.0: the rendered lens block in

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '4.5.4'
+  version: '4.6.0'
 ---
 
 # agent-workflow-memory
@@ -102,11 +102,13 @@ bootstrapping over a live system, but the user makes the final call.
    (`ln -s AGENTS.md CLAUDE.md`). **Leave ALL THREE pointer slots (`workflow:methodology` +
    `workflow:orchestration` + `workflow:autonomy`) exactly as shipped — empty.** Filling them is the
    composition root's job.
-6. **Deploy `docs/ai/`.** Create the files + `pages/` + the seed `adr/` store from
-   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md`, non-`adr-record.md` template —
-   the latter is a skill-home 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), plus the three seeded, **user-editable** strict-JSON configs:
+6. **Deploy `docs/ai/`.** Create the files + `pages/` + the seed `adr/` store + the seed `specs/`
+   store from `${CLAUDE_SKILL_DIR}/references/templates/` (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; feature contracts are authored
+   under it from `SPEC_TEMPLATE.md`), plus the three seeded, **user-editable** strict-JSON configs:
    `docs/ai/orchestration.json` — the per-project recipe defaults the composition root's `procedures`
    advisor reads — `docs/ai/gates.json` — the project's gate declaration, an empty list to fill with
    its own verification commands, consumed by the composition root's gate runner — and
@@ -333,9 +335,12 @@ The three setup choices each have a full contract in
 - [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md` (with the three empty
   pointer slots — methodology + orchestration + autonomy), `agent_rules.md`, the seeded user-editable
   `orchestration.json` + `autonomy.json` configs, the `adr-record.md` ADR authoring reference + the
-  seed `adr/log.md` navigator, and all `docs/ai/` files to deploy.
+  seed `adr/log.md` navigator, the `SPEC_TEMPLATE.md` spec authoring reference + the seed
+  `specs/index.md` store root, and all `docs/ai/` files to deploy.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness +
-  index-freshness gate, one-file-per-ADR archive, hook installer) and their unit tests.
+  index-freshness gate with the counted `specs/` collapse, the import-free spec reader
+  `spec-schema.mjs` that defines a well-formed spec, one-file-per-ADR archive, hook installer) and
+  their unit tests.
 - [`scripts/stamp-takeover.mjs`](scripts/stamp-takeover.mjs) — the upgrade-time lineage state
   machine (`LINEAGE_HEAD`, atomic stamp writes) + tests.
 - [`migrations/`](migrations/) — per-version upgrade steps, incl. `legacy-stamp-takeover.md`;

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "4.5.4",
+  "version": "4.6.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.5.4",
+  "version": "4.6.0",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",

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.
@@ -38,7 +38,7 @@ Read in order, then confirm before starting:
 
 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 — complete it per the project's **planning skill / methodology** (the `workflow:methodology` slot in `AGENTS.md` points to it; see §5). Without completing that step the plan is not done. (The methodology, including any mandatory final cleanup, is defined there — not in this substrate.)
 5. **Ask before committing** (§4): report lint / type-check / test counts + docs status, then wait for explicit approval. DO NOT auto-commit.
@@ -80,6 +80,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
+