@sabaiway/agent-workflow-kit 7.1.0 → 7.3.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)