@sabaiway/agent-workflow-kit 12.3.0 → 12.4.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 12.4.0 — the epic tier gets its checker: `epic-shape` judges a capped concept file by one altitude predicate and one claim relation, renders its review brief, folds the findings by the same predicate, and closes it by rewriting one byte range (AD-138)
+
+**MINOR: one new tool, four verbs, four shipped modules; no deployed gate line changes its verdict.** The epic this
+family works under was settled after a six-round design consult whose brief had no altitude bar, and the file drifted
+within a day — a backticked hash in a state field, ground named in prose, an id paragraph above the first section. A
+prose bar has been measured failing under load here, so the rung is a tool. The contract is
+`docs/ai/specs/kit/epic-shape/` (index + `ledger.md` + `brief.md`, live, revision 1, S1–S16 bound).
+
+- **`tools/epic-shape-cli.mjs --check <epic>`** reads `docs/ai/epics/<ID>.md` through the no-follow door — the id is
+  the file stem — and refuses on: a frontmatter key set other than the substrate six plus `state: open | landed`,
+  `maxLines` other than 60, a file over 60 lines, a title other than `# Epic: <title>`, any heading outside the seven
+  sections in their order (Intent, Value, Non-goals, Acceptance, Specs, Stories ledger, Queue), a non-blank line
+  above Intent, a `## Queue` line outside `Row <ID> in <bucket>`, a second or non-date `Result line:`, a
+  `docs/plans/<name>.md` token other than the queue, and — the ALTITUDE BAR, one predicate over every body line
+  outside the two claim fields — a code fence line, a backtick span or a path-with-line citation (`something.ext:123`,
+  `dir/file:123`, backticked or bare); a mechanism written as plain prose passes, a stated residual, no word list.
+  The story ledger is six ` | ` fields per row (`S<N>`, name, `depends-on:`, `owns:`, `shared:`, `state:`), ids
+  contiguous from S1, at most 200 bytes counted OUTSIDE `owns:` and `shared:`; a claim is a repo-relative path in one
+  canonical spelling (a closed byte set — no whitespace, backtick, parenthesis, wildcard, pipe, colon or hash — no
+  `.`/`..` segment, no leading slash, an optional trailing slash as a directory prefix), never a file the checker
+  opens; a co-located test path (`foo.test.mjs`, `foo.test/`) is covered by `foo.mjs`. ONE claim relation between
+  distinct not-landed stories identified by (epic path, id): overlap is equality or a slash-boundary prefix;
+  owns × owns refuses inside and across epics; a pair with a shared side needs a transitive `depends-on` edge inside
+  one epic and is REPORTED (exit 0) across epics; the graph is closed and acyclic, a cycle named by its stories. The
+  sibling sweep reads the DIRECT entries of the store into an entry list — a symlinked or unreadable `.md` refuses
+  naming it, a `type: epic` file with a state outside `open | landed` refuses, an OPEN sibling is judged whole by
+  the same shape check and a refusal names the file (unknown never reads as "owns nothing"), a LANDED sibling is
+  its header only and contributes no story and no finding whatever its body holds, another type or a subdirectory
+  is skipped and counted — and prints `epic-shape: sweep <root>: epics read <n>; entries skipped <n>`, the handed
+  epic counted among the read.
+- **`--review-brief <epic>`** prints, for an epic `--check` accepts and for no other file, a deterministic brief: the
+  id and state, the guard verbatim ("Judge intent, value, boundaries, ownership and story order. A finding that names
+  a mechanism, a file line or an implementation choice is below this tier's altitude and is NOT counted."), the
+  seven sections, five questions one per line. The same render serves a design consult over a draft.
+- **`--fold <findings-file>`** reads entries by its own reader (column-0 `-`, `*`, `<n>.` with indented and blank
+  continuation), excises each entry's first citation (with its backticks only when the span is exactly the token),
+  judges the remainder by the same predicate and prints three named lists with counts — kept, discarded with a
+  reason each, lines outside entries; a zero-entry file refuses.
+- **`--close <epic>`** runs the check, then four conditions — every story `landed <date>`, a result-line date, the
+  header not already landed, the queue row not standing by parsed id or whole-token display title over
+  `queue-audit`'s parser of `<root>/docs/plans/queue.md` read whole (absent or unparseable refuses) — and on accept
+  rewrites ONLY the header `state` bytes through the one descriptor it read; a second hard link refuses without a
+  write; an epic outside a `docs/ai/epics/` store refuses.
+- **Grammar and exits.** `--help` alone, or exactly one verb and exactly one positional; a positional opening with
+  `-`, a second verb, a repeated positional and an empty invocation are usage. Exit 0 accept · 1 refuse · 2 usage.
+  Findings render as `epic-shape: <path>:<line>: <code>: <message>`. Nothing reads git.
+- **Modules and suites.** `tools/epic-shape.mjs` (232 lines — `EPIC_SECTIONS`, `parseEpic`, `parseStoryRow`,
+  `judgeAltitude`, `checkEpic`), `tools/epic-shape-ledger.mjs` (180 — `checkClaims`, `sweepSiblings`, `judgeClose`),
+  `tools/epic-shape-brief.mjs` (75 — `BRIEF_GUARD`, `renderBrief`, `readEntries`, `foldFindings`),
+  `tools/epic-shape-cli.mjs` (153 — argv and fs only, `main(argv, io)`); four suites under `tools/epic-shape.test/`
+  bind S1–S16 with every changed line covered. The tarball gains the four modules by name (301 files, from 297).
+
+Repo-only: this repo's own epic is rewritten to the contract inside its 60 lines (58) and its `--check` line is a
+declared gate before `coverage-check`; the engine canon gains `## The epic` (engine 5.3.0).
+
 ## 12.3.0 — the purge archive is a tool: `queue-purge` snapshots a section's bytes and vouches for what leaves, and `queue-audit` exports the two surfaces it reads (AD-137)
 
 **MINOR: one new tool, two verbs, and the sibling's revision 6; no deployed gate line changes its verdict.** The canon has

package/SKILL.md

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

package/capability.json

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

package/package.json

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

package/tools/epic-shape-brief.mjs

@@ -0,0 +1,75 @@
+import { checkEpic, judgeAltitude, EPIC_SECTIONS, findCitation } from './epic-shape.mjs';
+import { getLineCount } from './plan-shape.mjs';
+
+export const BRIEF_GUARD = 'Judge intent, value, boundaries, ownership and story order. A finding that names a mechanism, a file line or an implementation choice is below this tier\'s altitude and is NOT counted.';
+const QUESTIONS = Object.freeze([
+  'Intent: Is the intended change clear?',
+  'Value: Is the value worth the work?',
+  'Boundaries: Are the non-goals and acceptance boundaries clear?',
+  'Ownership: Does each story have distinct, declared ownership?',
+  'Story order: Do the dependencies express the required order?',
+]);
+const BRIEF_PREFIX = '# Epic review: ';
+const FIRST_LINE = 1;
+const ENTRY_START = /^(?:[-*]|\d+\.)(?:[ \t]|$)/;
+const INDENTED_LINE = /^[ \t]+\S/;
+const CR_END = /\r$/;
+const CITATION_SPAN = /(?<!`)(`+)(?!`)([\s\S]*?)(?<!`)\1(?!`)/g;
+const SPAN_CONTENT = 2;
+const CITATION_GAP = ' ';
+const ERROR = 'error';
+const makeEntry = (entry) => ({ ...entry, text: entry.lines.join('\n') });
+
+export const renderBrief = (text, path) => {
+  const { findings, epic } = checkEpic(text, path);
+  if (findings.length) return { findings, brief: null };
+  const sections = EPIC_SECTIONS.map((heading) => epic.sections.find((section) => section.heading === heading).text).join('');
+  const separator = sections.endsWith('\n') ? '\n' : '\n\n';
+  return `${BRIEF_PREFIX}${epic.id} (${epic.state})\n\n${BRIEF_GUARD}\n\n${sections}${separator}${QUESTIONS.join('\n')}\n`;
+};
+
+export const readEntries = (text) => {
+  const source = String(text ?? '');
+  const lines = source.split('\n').slice(0, getLineCount(source));
+  const read = lines.reduce((state, raw, index) => {
+    const line = index + FIRST_LINE;
+    if (ENTRY_START.test(raw.replace(CR_END, ''))) {
+      return { ...state, entries: state.current ? [...state.entries, makeEntry(state.current)] : state.entries,
+        current: { line, lines: [raw] } };
+    }
+    if (state.current && (raw.trim() === '' || INDENTED_LINE.test(raw))) {
+      return { ...state, current: { ...state.current, lines: [...state.current.lines, raw] } };
+    }
+    return { current: null, entries: state.current ? [...state.entries, makeEntry(state.current)] : state.entries,
+      outside: raw.trim() === '' ? state.outside : [...state.outside, { line, text: raw }] };
+  }, { entries: [], outside: [], current: null });
+  return { entries: read.current ? [...read.entries, makeEntry(read.current)] : read.entries, outside: read.outside };
+};
+
+const findCitationRange = (text) => {
+  const citation = findCitation(text);
+  if (!citation) return null;
+  const span = [...text.matchAll(CITATION_SPAN)].find((match) => match.index < citation.index && match.index + match[0].length > citation.end);
+  if (!span) return citation;
+  return span[SPAN_CONTENT] === citation.text ? { index: span.index, end: span.index + span[0].length } : null;
+};
+const judgeEntry = (entry) => {
+  const citation = findCitationRange(entry.text);
+  const remainder = citation ? entry.text.slice(0, citation.index) + CITATION_GAP + entry.text.slice(citation.end) : entry.text;
+  const lines = remainder.split('\n').map((line, index) => ({
+    ...judgeAltitude(index === 0 ? line.replace(ENTRY_START, '') : line), reasonLine: entry.line + index,
+  }));
+  const violation = lines.find((line) => line.below) ?? { ...judgeAltitude(remainder), reasonLine: entry.line };
+  return violation.below ? { ...entry, form: violation.form, reasonLine: violation.reasonLine,
+    reason: `${violation.form} is below concept altitude` } : null;
+};
+
+export const foldFindings = (text) => {
+  const { entries, outside } = readEntries(text);
+  const judged = entries.map((entry) => ({ entry, discarded: judgeEntry(entry) }));
+  const kept = judged.filter((item) => !item.discarded).map((item) => item.entry);
+  const discarded = judged.filter((item) => item.discarded).map((item) => item.discarded);
+  const findings = entries.length ? [] : [{ line: FIRST_LINE, code: 'empty-findings', severity: ERROR, message: 'the findings file contains no entries' }];
+  return { ok: findings.length === 0, findings, kept, discarded, outside,
+    counts: { kept: kept.length, discarded: discarded.length, outside: outside.length } };
+};

package/tools/epic-shape-cli.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { constants, openSync, closeSync, fstatSync, readdirSync, writeSync, ftruncateSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { checkEpic } from './epic-shape.mjs';
+import { checkClaims, sweepSiblings, judgeClose, STORE_PATH, QUEUE_PATH } from './epic-shape-ledger.mjs';
+import { renderBrief, foldFindings } from './epic-shape-brief.mjs';
+
+const EXIT = Object.freeze({ accept: 0, refuse: 1, usage: 2 });
+const CHECK = '--check';
+const BRIEF = '--review-brief';
+const FOLD = '--fold';
+const CLOSE = '--close';
+const VERBS = Object.freeze([CHECK, BRIEF, FOLD, CLOSE]);
+const HELP_FLAG = '--help';
+const HELP_ARITY = 1;
+const VERB_ARITY = 2;
+const FIRST_LINE = 1;
+const MARKDOWN_SUFFIX = '.md';
+const PREFIX = 'epic-shape:';
+const INFO = 'info';
+const STORE_TO_PROJECT = '../../..';
+const LANDED_BYTES = Buffer.from('landed');
+const HELP = `Usage:
+  node epic-shape-cli.mjs --check <epic>
+  node epic-shape-cli.mjs --review-brief <epic>
+  node epic-shape-cli.mjs --fold <findings-file>
+  node epic-shape-cli.mjs --close <epic>
+  node epic-shape-cli.mjs --help
+
+Only --close writes: the epic header state becomes landed.
+Exit codes: 0 accept, 1 refuse, 2 usage.`;
+
+const parseArgv = (argv) => {
+  if (argv.length === HELP_ARITY && argv[0] === HELP_FLAG) return { help: true };
+  const [verb, path] = argv;
+  if (argv.length !== VERB_ARITY || !VERBS.includes(verb) || !path || path.startsWith('-')) {
+    throw fail(EXIT.usage, 'use --help alone, or exactly one verb followed by exactly one path that does not open with a dash');
+  }
+  return { verb, path: resolve(path) };
+};
+const makeFailure = (path, code, message) => Object.assign(fail(EXIT.refuse, message), { path, code });
+const formatFinding = (finding, fallbackPath) => {
+  const path = finding.path ?? fallbackPath;
+  const prefix = `${path}: `;
+  const message = finding.message.startsWith(prefix) ? finding.message.slice(prefix.length) : finding.message;
+  return `${PREFIX} ${path}:${finding.line ?? FIRST_LINE}: ${finding.code}: ${message}`;
+};
+const printFindings = (findings, path, io) => {
+  for (const finding of findings) (finding.severity === INFO ? io.log : io.error)(formatFinding(finding, path));
+};
+const printAccept = (verb, path, log) => log(`${PREFIX} accept ${verb} ${path}`);
+const printSweep = (sweep, log) => log(`${PREFIX} sweep ${sweep.root}: epics read ${sweep.counts.epicsRead + FIRST_LINE}; entries skipped ${sweep.counts.skipped}`);
+const describeRead = (result) => result.code ?? result.className ?? result.outcome;
+const openWritable = (path, flags) => openSync(path, flags | constants.O_RDWR);
+const readInput = (path, read, writable) => {
+  const result = read(path, writable ? { keepFd: true, open: openWritable } : {});
+  if (result.outcome !== 'ok') throw makeFailure(path, 'read', describeRead(result));
+  return result;
+};
+const readDirectory = (root, read) => readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).map((entry) => {
+  const name = entry.name;
+  if (entry.isDirectory()) return { name, outcome: 'directory' };
+  if (!name.endsWith(MARKDOWN_SUFFIX)) return { name, text: '' };
+  const result = read(join(root, name));
+  if (result.outcome === 'ok') return { name, text: result.content };
+  if (result.outcome === 'foreign') return { name, outcome: 'non-regular', kind: result.className };
+  return { name, outcome: 'unreadable', reason: describeRead(result) };
+});
+const readQueue = (path, read) => {
+  if (!STORE_PATH.test(path)) return { outcome: 'unreadable', reason: 'epic is outside a project store' };
+  const queuePath = resolve(dirname(path), STORE_TO_PROJECT, QUEUE_PATH);
+  const result = read(queuePath);
+  return result.outcome === 'ok' ? result.content : { outcome: result.outcome, reason: describeRead(result) };
+};
+
+const writeAll = (fd, bytes, position, path, offset = 0) => {
+  if (offset === bytes.length) return;
+  const written = writeSync(fd, bytes, offset, bytes.length - offset, position + offset);
+  if (written <= 0) throw makeFailure(path, 'write', 'the descriptor write made no progress');
+  writeAll(fd, bytes, position, path, offset + written);
+};
+const writeState = (input, range, path) => {
+  const stats = fstatSync(input.fd);
+  if (stats.nlink !== FIRST_LINE) throw makeFailure(path, 'hardlink', 'close refuses a file with a second hard link');
+  if (!stats.isFile() || stats.dev !== input.dev || stats.ino !== input.ino || stats.size !== input.bytes.length) throw makeFailure(path, 'changed-file', 'the held file changed after the check');
+  const suffix = Buffer.concat([LANDED_BYTES, input.bytes.subarray(range.end)]);
+  writeAll(input.fd, suffix, range.start, path);
+  ftruncateSync(input.fd, range.start + suffix.length);
+};
+const runFold = (input, path, io) => {
+  const result = foldFindings(input.content);
+  io.log(`${PREFIX} kept (${result.counts.kept})`);
+  for (const entry of result.kept) io.log(`${entry.line}: ${entry.text}`);
+  io.log(`${PREFIX} discarded (${result.counts.discarded})`);
+  for (const entry of result.discarded) io.log(`${entry.line}: ${entry.reason} (line ${entry.reasonLine})\n${entry.text}`);
+  io.log(`${PREFIX} outside (${result.counts.outside})`);
+  for (const line of result.outside) io.log(`${line.line}: ${line.text}`);
+  printFindings(result.findings, path, io);
+  if (!result.ok) return EXIT.refuse;
+  printAccept(FOLD, path, io.log);
+  return EXIT.accept;
+};
+const runEpic = (verb, input, path, io) => {
+  const entries = readDirectory(dirname(path), io.read).filter((entry) => entry.name !== basename(path));
+  const shape = checkEpic(input.content, path);
+  const sweep = sweepSiblings(entries, dirname(path));
+  const claims = shape.findings.length === 0 && sweep.ok
+    ? checkClaims([shape.epic, ...sweep.epics]) : { findings: [] };
+  const findings = [...shape.findings, ...sweep.findings, ...claims.findings];
+  const output = verb === BRIEF ? { ...io, log: io.error } : io;
+  printSweep(sweep, output.log);
+  if (findings.some((finding) => finding.severity !== INFO)) {
+    printFindings(findings, path, output);
+    return EXIT.refuse;
+  }
+  if (verb === CLOSE) {
+    const closed = judgeClose({ epic: input.content, path, queue: readQueue(path, io.read), entries });
+    printFindings(closed.findings, path, io);
+    if (!closed.ok) return EXIT.refuse;
+    writeState(input, closed.stateRange, path);
+  } else {
+    printFindings(findings, path, output);
+    if (verb === BRIEF) {
+      const brief = renderBrief(input.content, path);
+      if (typeof brief !== 'string') { printFindings(brief.findings, path, output); return EXIT.refuse; }
+      io.log(brief.slice(0, -FIRST_LINE));
+    }
+  }
+  printAccept(verb, path, output.log);
+  return EXIT.accept;
+};
+
+export const main = (argv, { log = console.log, error = console.error, read = readRegularFileNoFollow } = {}) => {
+  try {
+    const options = parseArgv(argv);
+    if (options.help) { log(HELP); return EXIT.accept; }
+    const input = readInput(options.path, read, options.verb === CLOSE);
+    try {
+      const io = { log, error, read };
+      return options.verb === FOLD ? runFold(input, options.path, io) : runEpic(options.verb, input, options.path, io);
+    } finally {
+      if (input.fd !== undefined) closeSync(input.fd);
+    }
+  } catch (failure) {
+    error(formatFinding({ path: failure.path, line: FIRST_LINE, code: failure.code ?? 'usage', message: failure.message }, argv[1] ?? 'invocation'));
+    return failure.exitCode === EXIT.usage ? EXIT.usage : EXIT.refuse;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(VERB_ARITY));

package/tools/epic-shape-ledger.mjs

@@ -0,0 +1,180 @@
+import { posix } from 'node:path';
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { parseHeader, checkEpic } from './epic-shape.mjs';
+import { auditQueue } from './queue-audit.mjs';
+import { unique } from './plan-shape.mjs';
+
+const FIRST_LINE = 1;
+const ERROR = 'error';
+const INFO = 'info';
+const OPEN = 'open';
+const LANDED = 'landed';
+const EPIC = 'epic';
+const OWN = 'owns';
+const CLAIM_FIELDS = Object.freeze([OWN, 'shared']);
+const FRONT_DELIMITER = '---';
+const CR_END = /\r$/;
+const MARKDOWN_SUFFIX = '.md';
+const TRAILING_SLASH = /\/$/;
+const SOURCE_EXTENSION = /^(.*[^/])(\.[^./]+)$/;
+const TEST_FILE = /\.test\.[^/]+$/;
+const TEST_SUFFIX = '.test';
+export const STORE_PATH = /^(?:(.*)\/)?docs\/ai\/epics\/([^/]+)\.md$/;
+export const QUEUE_PATH = 'docs/plans/queue.md';
+const TOKEN_EDGE = '[\\p{L}\\p{N}_-]';
+const REGEX_BYTES = /[.*+?^${}()|[\]\\]/g;
+const PARSE_REFUSALS = Object.freeze([1, 2]);
+const makeFinding = (path, line, code, message, severity = ERROR) => ({ path, line, code, message: `${path}: ${message}`, severity });
+const finishJudgement = (findings, data = {}) => ({ ...data, ok: !findings.some((finding) => finding.severity === ERROR), findings });
+const nameFindings = (findings, path) => findings.map((finding) => makeFinding(path, finding.line, finding.code, finding.message));
+const getIdentity = (story) => JSON.stringify([story.path, story.id]);
+
+const findReachable = (graph, pending, visited = new Set()) => {
+  const unseen = unique(pending.filter((id) => !visited.has(id)));
+  if (unseen.length === 0) return visited;
+  return findReachable(graph, unseen.flatMap((id) => graph.get(id) ?? []), new Set([...visited, ...unseen]));
+};
+const readGraph = (epic, rows) => {
+  const graph = new Map(rows.map((row) => [row.id, row.dependsOn]));
+  const reachable = new Map(rows.map((row) => [row.id, findReachable(graph, row.dependsOn)]));
+  const unknowns = rows.flatMap((row) => row.dependsOn.filter((id) => !graph.has(id))
+    .map((id) => makeFinding(epic.path, row.line, 'dependency-id', `${row.id} depends on absent story ${id}`)));
+  const cyclic = rows.filter((row) => reachable.get(row.id).has(row.id));
+  const groups = unique(cyclic.map((row) => JSON.stringify(cyclic.filter((other) =>
+    reachable.get(row.id).has(other.id) && reachable.get(other.id).has(row.id)).map((other) => other.id))));
+  const cycles = groups.map((group) => {
+    const ids = JSON.parse(group);
+    return makeFinding(epic.path, rows.find((row) => row.id === ids[0]).line, 'dependency-cycle', `dependency cycle includes ${ids.join(', ')}`);
+  });
+  return { reachable, findings: [...unknowns, ...cycles] };
+};
+
+const expandClaim = (path) => {
+  const source = SOURCE_EXTENSION.exec(path);
+  return source && !TEST_FILE.test(path)
+    ? [path, `${source[1]}${TEST_SUFFIX}${source[2]}`, `${source[1]}${TEST_SUFFIX}/`] : [path];
+};
+const hasPathOverlap = (left, right) => {
+  const a = left.replace(TRAILING_SLASH, '');
+  const b = right.replace(TRAILING_SLASH, '');
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+};
+const getClaims = (row) => CLAIM_FIELDS.flatMap((field) => row[field].map((path) => ({ field, path, ground: expandClaim(path) })));
+const hasClaimOverlap = (left, right) => left.ground.some((a) => right.ground.some((b) => hasPathOverlap(a, b)));
+const checkPair = (left, right) => {
+  if (getIdentity(left) === getIdentity(right)) return [];
+  const sameEpic = left.path === right.path;
+  const ordered = sameEpic && (left.reachable.has(right.id) || right.reachable.has(left.id));
+  return left.claims.flatMap((a) => right.claims.flatMap((b) => {
+    if (!hasClaimOverlap(a, b)) return [];
+    const owners = a.field === OWN && b.field === OWN;
+    if (!owners && ordered) return [];
+    const code = owners ? 'owns-overlap' : sameEpic ? 'shared-order' : 'shared-cross-epic';
+    const severity = owners || sameEpic ? ERROR : INFO;
+    const message = `${left.id} ${a.field} ${a.path} overlaps ${right.path} ${right.id} ${b.field} ${b.path}`;
+    return [makeFinding(left.path, left.line, code, message, severity)];
+  }));
+};
+
+export const checkClaims = (epics) => {
+  const parsed = epics.map((epic) => {
+    const rows = epic.rows;
+    const graph = readGraph(epic, rows);
+    const findings = rows.filter((row) => !row.valid)
+      .map((row) => makeFinding(epic.path, row.line, 'row-grammar', `${row.id} has invalid story fields or claim tokens`));
+    const stories = epic.state === OPEN ? rows.filter((row) => row.valid && row.state !== LANDED).map((row) => ({
+      path: epic.path, id: row.id, line: row.line, claims: getClaims(row), reachable: graph.reachable.get(row.id),
+    })) : [];
+    return { stories, findings: [...nameFindings(epic.findings, epic.path), ...findings, ...graph.findings] };
+  });
+  const stories = parsed.flatMap((epic) => epic.stories);
+  const collisions = stories.flatMap((left, index) => stories.slice(index + FIRST_LINE).flatMap((right) => checkPair(left, right)));
+  return finishJudgement([...parsed.flatMap((epic) => epic.findings), ...collisions]);
+};
+
+const readSiblingHeader = (text, path) => {
+  const lines = text.split('\n');
+  if (lines[0].replace(CR_END, '') !== FRONT_DELIMITER) return { fields: null, findings: [] };
+  const end = lines.findIndex((line, index) => index > 0 && line.replace(CR_END, '') === FRONT_DELIMITER);
+  if (end < 0) return { fields: null, findings: [makeFinding(path, FIRST_LINE, 'sibling-header', 'frontmatter opens but never closes')] };
+  try {
+    const frontmatter = tokenizeMarkdown(`${lines.slice(0, end + FIRST_LINE).join('\n')}\n`, path).frontmatter;
+    const { fields } = parseHeader(frontmatter);
+    const valid = Object.keys(fields).length === end - FIRST_LINE;
+    return valid ? { fields, findings: [] }
+      : { fields: null, findings: [makeFinding(path, FIRST_LINE, 'sibling-header', 'frontmatter contains an unreadable or repeated field')] };
+  } catch (error) {
+    if (!PARSE_REFUSALS.includes(error.exitCode)) throw error;
+    return { fields: null, findings: [makeFinding(path, FIRST_LINE, 'sibling-header', error.message)] };
+  }
+};
+const readSibling = (entry, root) => {
+  const skipped = { read: 0, skipped: FIRST_LINE, epics: [], findings: [] };
+  if (entry.outcome === 'directory' || entry.kind === 'directory') return skipped;
+  if (!entry.name.endsWith(MARKDOWN_SUFFIX)) return skipped;
+  const path = posix.join(root, entry.name);
+  if (typeof entry.text !== 'string' || entry.outcome) {
+    return { read: 0, skipped: 0, epics: [], findings: [makeFinding(path, FIRST_LINE, 'sibling-read', `${entry.outcome ?? 'unreadable'}: ${entry.reason ?? entry.kind ?? 'no readable text'}`)] };
+  }
+  const header = readSiblingHeader(entry.text, path);
+  if (header.findings.length) return { read: 0, skipped: 0, epics: [], findings: header.findings };
+  if (header.fields?.type !== EPIC) return skipped;
+  if (![OPEN, LANDED].includes(header.fields.state)) {
+    return { read: 0, skipped: 0, epics: [], findings: [makeFinding(path, FIRST_LINE, 'sibling-state', 'epic state is missing or outside open and landed')] };
+  }
+  if (header.fields.state === LANDED) return { read: FIRST_LINE, skipped: 0, epics: [], findings: [] };
+  const { epic, findings } = checkEpic(entry.text, path);
+  return { read: FIRST_LINE, skipped: 0, epics: findings.length ? [] : [epic], findings: nameFindings(findings, path) };
+};
+
+export const sweepSiblings = (entries, root) => {
+  if (!Array.isArray(entries)) {
+    return finishJudgement([makeFinding(root, FIRST_LINE, 'sibling-read', 'the direct entry list is unreadable')], { root, epics: [], counts: { epicsRead: 0, skipped: 0 } });
+  }
+  const results = entries.map((entry) => readSibling(entry, root));
+  const epics = results.flatMap((result) => result.epics);
+  return finishJudgement(results.flatMap((result) => result.findings), {
+    root, epics, counts: { epicsRead: results.reduce((sum, result) => sum + result.read, 0), skipped: results.reduce((sum, result) => sum + result.skipped, 0) },
+  });
+};
+
+const carriesToken = (title, id) => {
+  const escaped = id.replace(REGEX_BYTES, '\\$&');
+  return new RegExp(`(?<!${TOKEN_EDGE})${escaped}(?!${TOKEN_EDGE})`, 'u').test(title);
+};
+const checkQueueAbsence = (queue, path, id) => {
+  if (typeof queue !== 'string') {
+    return [makeFinding(path, FIRST_LINE, 'queue-read', `${queue?.outcome ?? 'absent'}: ${queue?.reason ?? 'no readable queue text'}`)];
+  }
+  try {
+    const { rows } = auditQueue(queue, { label: path });
+    return rows.filter((row) => row.id === id || carriesToken(row.title, id))
+      .map((row) => makeFinding(path, row.line, 'close-queue', `queue row still stands for ${id}: ${row.title}`));
+  } catch (error) {
+    if (!PARSE_REFUSALS.includes(error.exitCode)) throw error;
+    return [makeFinding(path, FIRST_LINE, 'queue-read', error.message)];
+  }
+};
+
+export const judgeClose = ({ epic: text, path, queue, entries }) => {
+  const checked = checkEpic(text, path);
+  const epic = checked.epic;
+  const base = { epic, stateRange: null };
+  if (checked.findings.length) return finishJudgement(nameFindings(checked.findings, path), base);
+  const store = STORE_PATH.exec(path);
+  if (!store) return finishJudgement([makeFinding(path, FIRST_LINE, 'close-path', 'close requires docs/ai/epics/<ID>.md in a project store')], base);
+  const root = store[1] === undefined ? '.' : store[1] || '/';
+  const queuePath = posix.join(root, QUEUE_PATH);
+  const sweep = sweepSiblings(entries, posix.dirname(path));
+  const claims = checkClaims([epic, ...sweep.epics.filter((sibling) => sibling.path !== posix.normalize(path))]);
+  const checks = [...sweep.findings, ...claims.findings];
+  const data = { ...base, root, queuePath, sweep };
+  if (!sweep.ok || !claims.ok) return finishJudgement(checks, data);
+  const stories = epic.rows.filter((row) => row.state !== LANDED)
+    .map((row) => makeFinding(path, row.line, 'close-stories', `${row.id} has not landed with a date`));
+  const result = epic.result ? [] : [makeFinding(path, FIRST_LINE, 'close-result', 'Acceptance has no Result line with a bare date')];
+  const state = epic.state === LANDED ? [makeFinding(path, FIRST_LINE, 'close-state', 'header state is already landed')] : [];
+  const findings = [...checks, ...stories, ...result, ...state, ...checkQueueAbsence(queue, queuePath, epic.id)];
+  const judged = finishJudgement(findings, data);
+  return { ...judged, stateRange: judged.ok ? epic.stateRange : null };
+};

package/tools/epic-shape.mjs

@@ -0,0 +1,232 @@
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { bulletBlocks, getLineCount, unique } from './plan-shape.mjs';
+
+export const EPIC_SECTIONS = Object.freeze([
+  '## Intent', '## Value', '## Non-goals', '## Acceptance', '## Specs', '## Stories ledger', '## Queue',
+]);
+const [INTENT, , , ACCEPTANCE, , LEDGER, QUEUE] = EPIC_SECTIONS;
+const HEADER_KEYS = Object.freeze(['type', 'lastUpdated', 'scope', 'staleAfter', 'owner', 'maxLines', 'state']);
+const HEADER_STATES = Object.freeze(['open', 'landed']);
+const STORY_STATES = Object.freeze(['planned', 'in-flight']);
+const MAX_LINES = 60;
+const MAX_ROW_BYTES = 200;
+const FIELD_COUNT = 6;
+const FIRST_LINE = 1;
+const HEADER_TAIL_LINES = 2;
+const MARKDOWN_REFUSAL = 1;
+const FIELD_SEPARATOR = ' | ';
+const NONE = 'none';
+const EPIC_TYPE = 'epic';
+const TITLE_PREFIX = '# Epic: ';
+const RESULT_PREFIX = 'Result line:';
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME_SUFFIX = 'T00:00:00.000Z';
+const STORY_ID = /^S[1-9]\d*$/;
+const DEPENDENCIES = /^depends-on: (none|S[1-9]\d*(?:, S[1-9]\d*)*)$/;
+const CLAIM_FIELD = /^(owns|shared): (.+)$/;
+const CLAIM_FORBIDDEN = /[\s`()\*?\[\]{}|:#]/;
+const STATE_FIELD = /^state: (planned|in-flight|landed (\d{4}-\d{2}-\d{2}))$/;
+const HEADER_FIELD = /^([A-Za-z][A-Za-z0-9]*):([ \t]*)(.*?)[ \t]*\r?$/;
+const QUEUE_LINE = /^Row (\S+) in (\S(?:.*\S)?)$/;
+const RESULT_LINE = /^Result line: (\d{4}-\d{2}-\d{2})$/;
+const PLAN_PATH = /docs\/plans\/([^\s`()[\]{}<>|,:;"']+\.md)(?=$|[\s`()[\]{}<>|,:;"'.!?])/g;
+const QUEUE_NAME = 'queue.md';
+const FENCE_LINE = /^\s*(?:`{3,}[^`]*|~{3,}.*)$/;
+const BACKTICK_RUN = /`+/g;
+const CITATION = /[^\s`()[\]{}<>|:;,"'!?]+[./][^\s`()[\]{}<>|:;,"'!?]+:\d+(?![\dA-Za-z_])/;
+const TOP_BULLET = /^-\s+\S/;
+const BULLET_PREFIX = /^-\s+/;
+const INDENTED_LINE = /^\s+\S/;
+const MARKDOWN_ERROR_LINE = /:(\d+):/;
+const makeFinding = (line, code, message) => ({ line, code, message });
+const getFileLine = (document, index) => document.frontLines + index + FIRST_LINE;
+const getSection = (epic, heading) => epic.sections.find((section) => section.heading === heading);
+const getNonBlank = (entries) => entries.filter((entry) => entry.raw.trim() !== '');
+const getEntries = (document, start, end) => document.lines.slice(start, end).map((raw, offset) => ({
+  raw, index: start + offset, line: getFileLine(document, start + offset),
+}));
+export const isEpicDate = (value) => {
+  if (!DATE_PATTERN.test(value)) return false;
+  const date = new Date(`${value}${DATE_TIME_SUFFIX}`);
+  return Number.isFinite(date.getTime()) && date.toISOString() === `${value}${DATE_TIME_SUFFIX}`;
+};
+
+export const findCitation = (line) => {
+  const match = CITATION.exec(line);
+  return match ? { text: match[0], index: match.index, end: match.index + match[0].length } : null;
+};
+
+const hasBacktickSpan = (line) => {
+  const runs = [...line.matchAll(BACKTICK_RUN)];
+  return runs.some((opening, index) => runs.slice(index + FIRST_LINE).some((closing) => closing[0].length === opening[0].length));
+};
+
+export const judgeAltitude = (line) => {
+  const form = FENCE_LINE.test(line) ? 'fence' : hasBacktickSpan(line) ? 'backtick' : findCitation(line) ? 'citation' : null;
+  return { below: form !== null, form };
+};
+
+const isClaim = (token) => {
+  if (!token || token === NONE || token.startsWith('/') || CLAIM_FORBIDDEN.test(token)) return false;
+  const segments = token.replace(/\/$/, '').split('/');
+  return segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+};
+const parseClaims = (field, name) => {
+  const match = CLAIM_FIELD.exec(field ?? '');
+  if (!match || match[1] !== name) return null;
+  if (match[2] === NONE) return [];
+  const claims = match[2].split(',').map((claim) => claim.trim());
+  return claims.every(isClaim) ? claims : null;
+};
+
+export const parseStoryRow = (blockLines) => {
+  const lines = blockLines.map((line) => line.replace(/\r$/, ''));
+  const raw = lines[0] ?? '';
+  const parts = raw.replace(BULLET_PREFIX, '').split(FIELD_SEPARATOR).map((part) => part.trim());
+  const [id, name, dependencyField, ownsField, sharedField, stateField] = parts;
+  const dependencies = DEPENDENCIES.exec(dependencyField ?? '');
+  const owns = parseClaims(ownsField, 'owns');
+  const shared = parseClaims(sharedField, 'shared');
+  const stateMatch = STATE_FIELD.exec(stateField ?? '');
+  const date = stateMatch?.[2] ?? null;
+  const state = date ? 'landed' : stateMatch?.[1] ?? null;
+  const bodyLines = lines.slice(FIRST_LINE);
+  const body = bodyLines.join('\n').trimEnd();
+  const outsideClaims = [id, name, dependencyField, stateField].join(FIELD_SEPARATOR);
+  const countedBytes = Buffer.byteLength(outsideClaims + (body ? `\n${body}` : ''), 'utf8');
+  const valid = TOP_BULLET.test(raw) && parts.length === FIELD_COUNT && STORY_ID.test(id ?? '') && Boolean(name)
+    && Boolean(dependencies) && owns !== null && shared !== null
+    && (STORY_STATES.includes(state) || (state === 'landed' && isEpicDate(date)))
+    && bodyLines.every((line) => line.trim() === '' || INDENTED_LINE.test(line));
+  return {
+    raw, id: id ?? null, name: name ?? null, valid, countedBytes, body, bodyLines,
+    dependsOn: dependencies ? (dependencies[1] === NONE ? [] : unique(dependencies[1].split(', '))) : [],
+    owns: owns ?? [], shared: shared ?? [], state, date,
+    altitudeLine: parts.length === FIELD_COUNT ? outsideClaims : raw,
+  };
+};
+
+export const parseHeader = (frontmatter) => {
+  const lines = frontmatter.split('\n');
+  const entries = lines.slice(FIRST_LINE, -HEADER_TAIL_LINES).map((raw, index) => {
+    const match = HEADER_FIELD.exec(raw);
+    const prefix = lines.slice(0, index + FIRST_LINE).join('\n') + '\n';
+    const start = match ? Buffer.byteLength(prefix + `${match[1]}:${match[2]}`, 'utf8') : null;
+    return { key: match?.[1], value: match?.[3], line: index + FIRST_LINE + FIRST_LINE,
+      range: match ? { start, end: start + Buffer.byteLength(match[3], 'utf8') } : null };
+  });
+  const fields = Object.fromEntries(entries.filter((entry) => entry.key).map((entry) => [entry.key, entry.value]));
+  const findings = entries.flatMap((entry) => !entry.key || !HEADER_KEYS.includes(entry.key) || entry.value === ''
+    ? [makeFinding(entry.line, 'frontmatter', 'frontmatter must contain only the seven non-empty epic fields')] : []);
+  for (const key of HEADER_KEYS) {
+    if (entries.filter((entry) => entry.key === key).length !== FIRST_LINE) {
+      findings.push(makeFinding(FIRST_LINE, 'frontmatter', `frontmatter must carry ${key} exactly once`));
+    }
+  }
+  if (fields.type !== EPIC_TYPE) findings.push(makeFinding(FIRST_LINE, 'frontmatter', 'type must be epic'));
+  if (fields.maxLines !== String(MAX_LINES)) findings.push(makeFinding(FIRST_LINE, 'max-lines', `maxLines is frozen at ${MAX_LINES}`));
+  if (!HEADER_STATES.includes(fields.state)) findings.push(makeFinding(FIRST_LINE, 'header-state', 'header state must be open or landed'));
+  const states = entries.filter((entry) => entry.key === 'state');
+  return { fields, stateRange: states.length === FIRST_LINE ? states[0].range : null, findings };
+};
+
+const parseSections = (document, titleHeading) => document.headings.filter((heading) => heading !== titleHeading).map((heading, index, headings) => {
+  const end = headings[index + FIRST_LINE]?.index ?? document.lines.length;
+  const lines = document.lines.slice(heading.index + FIRST_LINE, end);
+  const raw = document.lines.slice(heading.index, end).join('\n');
+  return { heading: heading.text, index: heading.index, line: getFileLine(document, heading.index), end, lines,
+    text: raw + (end < document.lines.length ? '\n' : ''), entries: getEntries(document, heading.index + FIRST_LINE, end) };
+});
+
+export const parseEpic = (text, path) => {
+  const source = String(text ?? '');
+  const epicPath = String(path ?? '');
+  const id = epicPath.split('/').at(-1).replace(/\.md$/, '');
+  const base = { text: source, path: epicPath, id, title: null, fields: {}, state: null, stateRange: null,
+    sections: [], rows: [], queue: null, result: null, resultLines: [], ledgerEntries: [], document: null, findings: [] };
+  try {
+    const document = tokenizeMarkdown(source, epicPath);
+    const header = parseHeader(document.frontmatter);
+    const titleHeading = document.headings.find((heading) => heading.level === FIRST_LINE && heading.text.startsWith(TITLE_PREFIX));
+    const sections = parseSections(document, titleHeading);
+    const ledger = sections.find((section) => section.heading === LEDGER);
+    const blocks = ledger ? bulletBlocks(document.lines, document.fencedLines, ledger.index + FIRST_LINE, ledger.end) : [];
+    const rows = blocks.map((block) => ({ ...parseStoryRow(block.lines), index: block.start,
+      line: getFileLine(document, block.start), span: block.span }));
+    const queueEntries = getNonBlank(sections.find((section) => section.heading === QUEUE)?.entries ?? []);
+    const queueMatch = queueEntries.length === FIRST_LINE ? QUEUE_LINE.exec(queueEntries[0].raw.trim()) : null;
+    const resultLines = (sections.find((section) => section.heading === ACCEPTANCE)?.entries ?? [])
+      .filter((entry) => entry.raw.trim().startsWith(RESULT_PREFIX));
+    const resultMatch = resultLines.length === FIRST_LINE ? RESULT_LINE.exec(resultLines[0].raw.trim()) : null;
+    return {
+      ...base, ...header, document, titleHeading, title: titleHeading?.text.slice(TITLE_PREFIX.length).trim() ?? null,
+      state: header.fields.state ?? null, sections, rows, ledgerEntries: ledger?.entries ?? [], resultLines,
+      queue: queueMatch ? { id: queueMatch[1], bucket: queueMatch[2], line: queueEntries[0].line } : null,
+      result: resultMatch && isEpicDate(resultMatch[1]) ? { date: resultMatch[1], line: resultLines[0].line } : null,
+    };
+  } catch (error) {
+    if (error.exitCode !== MARKDOWN_REFUSAL) throw error;
+    return { ...base, findings: [makeFinding(Number(MARKDOWN_ERROR_LINE.exec(error.message)?.[1] ?? FIRST_LINE), 'markdown', error.message)] };
+  }
+};
+
+const checkSections = (epic) => {
+  const { document, titleHeading, sections } = epic;
+  const findings = [];
+  if (!epic.title || document.headings[0] !== titleHeading) {
+    findings.push(makeFinding(titleHeading ? getFileLine(document, titleHeading.index) : FIRST_LINE, 'title', `the first heading must be ${TITLE_PREFIX}<title>`));
+  }
+  if (sections.length !== EPIC_SECTIONS.length || sections.some((section, index) => section.heading !== EPIC_SECTIONS[index])) {
+    findings.push(makeFinding(sections[0]?.line ?? FIRST_LINE, 'headings', 'the seven epic sections must appear exactly once in their literal order, with no other headings'));
+  }
+  const intent = getSection(epic, INTENT);
+  const outside = getEntries(document, 0, intent?.index ?? document.lines.length)
+    .filter((entry) => entry.index !== titleHeading?.index && entry.raw.trim() !== '');
+  for (const entry of outside) findings.push(makeFinding(entry.line, 'outside-section', 'every non-blank body line after the title must lie inside a section'));
+  return findings;
+};
+
+const checkClosedLines = (epic) => {
+  const findings = [];
+  if (!epic.queue || epic.queue.id !== epic.id) {
+    findings.push(makeFinding(getSection(epic, QUEUE)?.line ?? FIRST_LINE, 'queue', `Queue must hold exactly one line: Row ${epic.id} in <bucket>`));
+  }
+  if (epic.resultLines.length > FIRST_LINE || (epic.resultLines.length === FIRST_LINE && !epic.result)) {
+    findings.push(makeFinding(epic.resultLines[0].line, 'result-line', 'Acceptance admits at most one Result line: YYYY-MM-DD with a date and nothing else'));
+  }
+  return findings;
+};
+
+const checkRows = (epic) => {
+  const findings = [];
+  if (epic.rows.length === 0) findings.push(makeFinding(getSection(epic, LEDGER)?.line ?? FIRST_LINE, 'empty-ledger', 'the ledger must carry at least S1'));
+  const covered = new Set(epic.rows.flatMap((row) => Array.from({ length: row.span }, (_, offset) => row.index + offset)));
+  for (const entry of getNonBlank(epic.ledgerEntries)) {
+    if (!covered.has(entry.index)) findings.push(makeFinding(entry.line, 'ledger-line', 'ledger content must belong to a top-level story bullet'));
+  }
+  for (const [index, row] of epic.rows.entries()) {
+    if (!row.valid) findings.push(makeFinding(row.line, 'row-grammar', 'a story must carry the six ordered fields, canonical claims and a valid state'));
+    if (row.id !== `S${index + FIRST_LINE}`) findings.push(makeFinding(row.line, 'story-ids', 'story ids must run contiguously from S1'));
+    if (row.countedBytes > MAX_ROW_BYTES) findings.push(makeFinding(row.line, 'row-bytes', `${row.id} has ${row.countedBytes} bytes outside owns and shared; the cap is ${MAX_ROW_BYTES}`));
+  }
+  return findings;
+};
+
+const checkAltitude = (epic) => {
+  const rowLines = new Map(epic.rows.map((row) => [row.index, row.altitudeLine]));
+  return epic.document.lines.flatMap((line, index) => {
+    const judgement = judgeAltitude(rowLines.get(index) ?? line);
+    return judgement.below ? [makeFinding(getFileLine(epic.document, index), 'altitude', `${judgement.form} is below concept altitude`)] : [];
+  });
+};
+const checkPlanPaths = (text) => text.split('\n').flatMap((line, index) => [...line.matchAll(PLAN_PATH)]
+  .filter((match) => match[1] !== QUEUE_NAME)
+  .map((match) => makeFinding(index + FIRST_LINE, 'plan-path', `${match[0]} is ephemeral; only docs/plans/queue.md may be stored`)));
+
+export const checkEpic = (text, path) => {
+  const epic = parseEpic(text, path);
+  const capFindings = getLineCount(epic.text) > MAX_LINES
+    ? [makeFinding(FIRST_LINE, 'line-cap', `the epic has ${getLineCount(epic.text)} lines; the cap is ${MAX_LINES}`)] : [];
+  const shapeFindings = epic.document ? [...checkSections(epic), ...checkClosedLines(epic), ...checkRows(epic), ...checkAltitude(epic)] : [];
+  return { findings: [...epic.findings, ...capFindings, ...checkPlanPaths(epic.text), ...shapeFindings], epic };
+};