@sabaiway/agent-workflow-kit 12.3.0 → 13.0.0

package/CHANGELOG.md

@@ -4,6 +4,121 @@ 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.
 
+## 13.0.0 — a plan proves its own ground: `plan-shape` judges a plan's rows against its epic story's claims in both arms and `--in-flight`, the claim relation lives in one leaf, and the containment rule is one positive predicate (AD-139)
+
+**MAJOR: the containment rule refuses a row or anchor path spelling 12.4.0 accepted — a trailing or doubled slash, a
+`.` segment — so a consumer's declared `--in-flight` gate can turn red with no edit of theirs (the refusal names the
+row and the rule; no migration note, as for every kit MAJOR since 4.0.0 — the class AD-117 and AD-133 called MAJOR),
+and the story relation joins the structural set, so a consumer already on the 12.4.0 epic tier can go red the same
+way with no edit of theirs (each code's reach is stated in the bullets below); three new shipped leaves, one new
+structural rule set, no deployed gate line's TEXT changes.** The epic
+tier (12.4.0) gave a story a ledger of claims; the bar "a plan stays inside its story's claims" lived in prose, and
+the last bar this epic wrote down drifted inside a day. The rung is now a tool, enforced where a dispatch is spent: `--in-flight` is already the gate
+this family runs before every dispatch. The contract is `docs/ai/specs/kit/plan-shape-ownership.md` (live, revision 1,
+S1–S11 bound) beside `plan-review-loop` revision 9.
+
+- **The story line.** A plan carrying an epic story names it with exactly one line `Story: S<N> of <ID>` inside
+  `## Goal and boundary`, `<ID>` the epic's file stem under `docs/ai/epics/`. Two lines refuse `story-line`; an
+  unknown epic or story id refuses `story-unknown` by name; a landed epic refuses `story-epic-landed`. Zero lines is
+  a storyless plan and stays legal — judged as today plus the collision half. The plan's own story is looked up in
+  the full record list, landed rows included; its `state:` is never read.
+- **ONE relation, in the STRUCTURAL set.** Over every concrete row path after glob expansion, against every
+  not-landed story of every open epic minus the plan's own: an `owns` overlap refuses `story-owns`; a `shared`
+  overlap inside the plan's own epic refuses `story-shared` unless a transitive `depends-on` edge orders the two
+  in either direction; a storyless plan against a `shared` claim refuses the same way (name the story); a
+  cross-epic `shared` overlap is not judged (the epic tier prints it). For a storied plan, an in-scope row path —
+  the declared source-size practice's roots, extensions and exclusions — that no own claim covers refuses
+  `story-scope`; the package-content pin path is covered by the shipped `create` or `delete` row it pins and is
+  never claimed by a story. `checkPlan`, `verifyPlan` and `checkPlanStructure` all carry it, so `--check`,
+  `--verify` and `--check --in-flight` agree.
+- **Facts.** `openRepo` reads `docs/ai/epics/` once per run through the epic sweep's own no-follow door, and
+  `buildFacts` hands the judge `stories` (one record per valid story row of every open epic: `{ path, id, line, state, claims,
+  reachable }`), `landedEpics` (the file stems the sweep read as landed) and `storeRefusal`. Only ENOENT reads as
+  an absent store; a symlinked root, a regular file, ENOTDIR, any other error, a failed read, an unreadable `.md`
+  entry, a frontmatter the header reader refuses, an open epic the shape check refuses or a state outside the
+  closed set refuse EVERY judged plan `story-store`. A facts object with no `stories` field (the bare callers)
+  leaves the relation unjudged.
+- **The pin exemption (`plan-review-loop` revision 9, S34).** Several `modify` rows whose OWN path is one
+  package-content pin path may own it — the ONE exemption to `duplicate-path`: a single pin row owes nothing; with
+  two or more, every one binds in ledger order the nearest untaken shipped `create` or `delete` row above it whose
+  package pin is that path, and a row that finds none refuses `pin-unbound`. A sweep expansion never rides it; the
+  `before`/`after` totals count each concrete path once; a judge with no `pathFacts` admits repeated `modify` pin
+  rows unjudged; a duplicate involving a `create` or `delete` still refuses.
+- **Containment enumerated by proof.** A row or anchor path is admitted only when it has no backslash and every
+  `/`-separated segment is non-empty and neither `.` nor `..` — one predicate instead of an exclusion list, after
+  `./x` (plan review) and `x/` (diff review, confirmed live) each walked around a claim; a leading slash was
+  already refused by 12.4.0's own predicate.
+- **Three leaves, no cycle, no claim primitive written twice.** `tools/claim-relation.mjs` (`expandClaim`,
+  `hasPathOverlap`, `findReachable`, `listStories`, `unique` — `plan-shape.mjs` re-exports `unique` so every import
+  site stands), `tools/epic-store.mjs` (`EPICS_REL`, `readEpicEntries` — the epic CLI's door, unchanged — and
+  `readEpicStore`, the facts half's no-follow probe), `tools/plan-shape-ownership.mjs` (`readStoryLine`,
+  `checkStoryOwnership`, `PIN_FILE`, `PIN_VERBS`). `epic-shape-ledger.mjs` and `epic-shape-cli.mjs` keep their
+  findings and counts byte for byte under their unchanged suites; the sweep result gains `landedEpics` beside
+  `counts`. Tarball pin 301 → 304. Every touched shipped module stays under the 400-line cap (`plan-shape.mjs` 384);
+  the kit's recorded aggregate rises by the three leaves and their suites, the reason recorded in the ratchet.
+- **Recorded debt (queue).** `openRepo` walks the repository before the store probe, so an EACCES directory
+  anywhere exits 2 before `story-store` can be named (refuse-direction, pre-existing); the robustness coverage
+  table reads a filesystem errno as a process-launch outcome; a delegate read its own sandbox's spawn limit as a
+  reason to stop a slice; a near-miss story line (`- Story: …`, the bullet marker the canon's own sentence sits
+  under) reads as a storyless plan instead of refusing; the one-line read describer is written twice by the store
+  extraction (`describeRead` in the epic CLI and in the store leaf); a storied plan whose only pin-path row ships
+  no `create` or `delete` above it refuses `story-scope` with no repair inside the rule.
+
+## 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: '13.0.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": "13.0.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "12.3.0",
+  "version": "13.0.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/claim-relation.mjs

@@ -0,0 +1,33 @@
+const OPEN = 'open';
+const CLAIM_FIELDS = Object.freeze(['owns', 'shared']);
+const TRAILING_SLASH = /\/$/;
+const SOURCE_EXTENSION = /^(.*[^/])(\.[^./]+)$/;
+const TEST_FILE = /\.test\.[^/]+$/;
+const TEST_SUFFIX = '.test';
+
+export const unique = (items) => [...new Set(items)];
+
+export 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];
+};
+export 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}/`);
+};
+export 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 getClaims = (row) => CLAIM_FIELDS.flatMap((field) => row[field].map((path) => ({ field, path, ground: expandClaim(path) })));
+
+export const listStories = (epics) => epics.filter((epic) => epic.state === OPEN).flatMap((epic) => {
+  const graph = new Map(epic.rows.map((row) => [row.id, row.dependsOn]));
+  return epic.rows.filter((row) => row.valid).map((row) => ({
+    path: epic.path, id: row.id, line: row.line, state: row.state,
+    claims: getClaims(row), reachable: findReachable(graph, row.dependsOn),
+  }));
+});

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,144 @@
+#!/usr/bin/env node
+import { constants, openSync, closeSync, fstatSync, writeSync, ftruncateSync } from 'node:fs';
+import { basename, dirname, 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 { readEpicEntries } from './epic-store.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 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 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 = readEpicEntries(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,160 @@
+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 { hasPathOverlap, findReachable, listStories, unique } from './claim-relation.mjs';
+
+const FIRST_LINE = 1;
+const ERROR = 'error';
+const INFO = 'info';
+const OPEN = 'open';
+const LANDED = 'landed';
+const EPIC = 'epic';
+const OWN = 'owns';
+const FRONT_DELIMITER = '---';
+const CR_END = /\r$/;
+const MARKDOWN_SUFFIX = '.md';
+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 readGraph = (epic, rows, stories) => {
+  const graph = new Map(rows.map((row) => [row.id, row.dependsOn]));
+  const byLine = new Map(stories.map((story) => [story.line, story.reachable]));
+  const reachable = new Map(rows.map((row) => [row.id, byLine.get(row.line) ?? 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 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 stories = listStories([epic]);
+    const graph = readGraph(epic, rows, stories);
+    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`));
+    return { stories: stories.filter((story) => story.state !== LANDED),
+      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: [], landedEpics: [entry.name.slice(0, -MARKDOWN_SUFFIX.length)] };
+  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 }, landedEpics: [] });
+  }
+  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) },
+    landedEpics: results.flatMap((result) => result.landedEpics ?? []),
+  });
+};
+
+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 };
+};

package/tools/epic-store.mjs

@@ -0,0 +1,33 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { describeNonRegular, readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+
+export const EPICS_REL = 'docs/ai/epics';
+const MARKDOWN_SUFFIX = '.md';
+const ABSENT_CODE = 'ENOENT';
+const REGULAR_FILE = 'regular file';
+const describeRead = (result) => result.code ?? result.className ?? result.outcome;
+const refuseStore = (error) => ({ outcome: 'refused', reason: error?.code ?? error?.message ?? String(error) });
+
+export const readEpicEntries = (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) };
+});
+
+export const readEpicStore = (projectRoot, read = readRegularFileNoFollow) => {
+  const root = join(projectRoot, EPICS_REL);
+  const probe = (() => {
+    try { return { stats: lstatSync(root) }; }
+    catch (error) { return { result: error?.code === ABSENT_CODE ? { outcome: 'absent', entries: [] } : refuseStore(error) }; }
+  })();
+  if (probe.stats?.isDirectory()) {
+    try { return { outcome: 'ok', entries: readEpicEntries(root, read) }; }
+    catch (error) { return refuseStore(error); }
+  }
+  return probe.result ?? { outcome: 'refused', reason: probe.stats.isFile() ? REGULAR_FILE : describeNonRegular(probe.stats) };
+};

package/tools/plan-shape-facts.mjs

@@ -4,13 +4,18 @@ import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { classIds, readShippedRobustnessLiterals } from './robustness-literals.mjs';
 import { segmentPrefixOf, validateSourceSizeConfig } from './source-size-config.mjs';
 import { getLineCount, isSweep, resolveAnchorCandidates, unique } from './plan-shape.mjs';
+import { listStories } from './claim-relation.mjs';
+import { EPICS_REL, readEpicStore } from './epic-store.mjs';
+import { sweepSiblings } from './epic-shape-ledger.mjs';
+import { PIN_FILE } from './plan-shape-ownership.mjs';
 
 const SOURCE_SIZE_REL = 'docs/ai/source-size.json';
 const PACKAGE_FILE = 'package.json';
-const PIN_FILE = 'package-content.test.mjs';
 const EXCLUDED_DIRECTORIES = new Set(['.git', 'node_modules']);
 const NEGATED_CLASS = /\[[!^]/;
 const UNSUPPORTED_GLOB = /[()\\\u0000-\u001f]/;
+const STORE_REFUSED = 'refused';
+const FINDING_SEPARATOR = '; ';
 
 const usageError = (message, scope = 'repository') => Object.assign(new Error(message), { exitCode: 2, scope });
 const planError = (message) => usageError(message, 'plan');
@@ -200,18 +205,31 @@ const describePath = (root, path, practice, repoFiles, packageCache) => {
   };
 };
 
+const readStoryFacts = (root) => {
+  const store = readEpicStore(root);
+  if (store.outcome === STORE_REFUSED) return { stories: [], landedEpics: [], storeRefusal: `${EPICS_REL}: ${store.reason}` };
+  const sweep = sweepSiblings(store.entries, EPICS_REL);
+  return {
+    stories: sweep.ok ? listStories(sweep.epics) : [],
+    landedEpics: sweep.ok ? sweep.landedEpics : [],
+    storeRefusal: sweep.ok ? null : sweep.findings.map((finding) => finding.message).join(FINDING_SEPARATOR),
+  };
+};
+
 export const openRepo = (root, { robustnessDeps } = {}) => {
   const repoRoot = realpathSync(root);
-  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), robustClasses: loadRobustClasses(robustnessDeps), packageCache: new Map() };
+  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), robustClasses: loadRobustClasses(robustnessDeps),
+    packageCache: new Map(), ...readStoryFacts(repoRoot) };
 };
 
 export const expandSweepPaths = (root, patterns) => expandPatterns(walkRegularFiles(realpathSync(root)), patterns);
 
 export const buildFacts = (root, { paths = [], robustnessDeps, repo = openRepo(root, { robustnessDeps }) } = {}) => {
-  const { repoRoot, repoFiles, practice, robustClasses, packageCache } = repo;
+  const { repoRoot, repoFiles, practice, robustClasses, packageCache, stories, landedEpics, storeRefusal } = repo;
   const expansions = expandPatterns(repoFiles, paths.filter(isSweep));
   const allPaths = unique([...paths, ...Object.values(expansions).flat()]);
   const pathFacts = Object.fromEntries(allPaths.map((path) => [path, describePath(repoRoot, path, practice, repoFiles, packageCache)]));
   const candidates = (suffix, precedingPaths = []) => resolveAnchorCandidates(repoFiles, suffix, precedingPaths);
-  return { capDeclared: practice.capDeclared, cap: practice.cap, robustClasses, pathFacts, expansions, repoFiles, candidates };
+  return { capDeclared: practice.capDeclared, cap: practice.cap, robustClasses, pathFacts, expansions, repoFiles, candidates,
+    stories, landedEpics, storeRefusal };
 };

package/tools/plan-shape-ownership.mjs

@@ -0,0 +1,83 @@
+import { posix } from 'node:path';
+import { hasPathOverlap } from './claim-relation.mjs';
+
+const STORY_LINE = /^Story: (S[1-9]\d*) of ([^\s/]+)$/;
+const STORY_FIELDS = 'stories';
+export const PIN_FILE = 'package-content.test.mjs';
+const MARKDOWN_SUFFIX = '.md';
+const FIRST_LINE = 1;
+const LANDED = 'landed';
+const OWNS = 'owns';
+const SHARED = 'shared';
+const STRING_TYPE = 'string';
+export const PIN_VERBS = new Set(['create', 'delete']);
+const CODES = Object.freeze({ line: 'story-line', store: 'story-store', landed: 'story-epic-landed',
+  unknown: 'story-unknown', owns: 'story-owns', shared: 'story-shared', scope: 'story-scope' });
+const ONE_STORY = 'the plan names its story with one line';
+const NAME_STORY = 'name the story that carries the file';
+const ORDER_STORIES = 'declare a transitive depends-on order between the stories';
+const makeFinding = (line, code, message, rowId = null) => ({ line, code, message, rowId });
+const sortFindings = (findings) => ({ findings: findings.sort((left, right) => left.line - right.line) });
+const hasIdentity = (left, right) => left.path === right.path && left.id === right.id;
+const hasClaimCover = (claim, path) => claim.ground.some((ground) => hasPathOverlap(path, ground));
+const hasOwnCover = (own, path) => own.claims.some((claim) => hasClaimCover(claim, posix.normalize(path)));
+
+export const readStoryLine = (lines) => {
+  const [story = null, second] = lines.flatMap(({ text, line }) => {
+    const match = STORY_LINE.exec(text.trim());
+    if (!match) return [];
+    const [, id, epic] = match;
+    return [{ id, epic, line }];
+  });
+  return { story, findings: second ? [makeFinding(second.line, CODES.line, ONE_STORY)] : [] };
+};
+
+const findOwnStory = (story, facts) => {
+  if (!story) return { own: null, findings: [] };
+  const epics = facts.stories.filter((record) => posix.basename(record.path, MARKDOWN_SUFFIX) === story.epic);
+  const own = epics.find((record) => record.id === story.id) ?? null;
+  if (facts.landedEpics?.includes(story.epic)) {
+    return { own: null, findings: [makeFinding(story.line, CODES.landed, `${story.epic} is landed; name a story of an open epic`)] };
+  }
+  if (!own) {
+    const name = epics.length ? `${story.epic} ${story.id}` : story.epic;
+    return { own: null, findings: [makeFinding(story.line, CODES.unknown, `${name} is unknown; name a story present in an open epic`)] };
+  }
+  return { own, findings: [] };
+};
+
+const checkCollision = (row, path, record, claim, own) => {
+  if (!hasClaimCover(claim, posix.normalize(path))) return [];
+  const message = `${row.id} path ${path} overlaps ${record.path} ${record.id} ${claim.field} ${claim.path}`;
+  if (claim.field === OWNS) return [makeFinding(row.line, CODES.owns, message, row.id)];
+  if (claim.field !== SHARED) return [];
+  if (own && (record.path !== own.path || own.reachable.has(record.id) || record.reachable.has(own.id))) return [];
+  return [makeFinding(row.line, CODES.shared, `${message}; ${own ? ORDER_STORIES : NAME_STORY}`, row.id)];
+};
+
+const hasPinCover = (path, rows, facts, own) => posix.basename(path) === PIN_FILE && rows.some((row) => {
+  const fact = facts.pathFacts?.[row.path];
+  return PIN_VERBS.has(row.verb) && fact?.shipped === true && fact.pinTest === path && hasOwnCover(own, row.path);
+});
+const checkScope = (row, path, rows, facts, own) => {
+  if (!own || facts.pathFacts?.[path]?.inScope !== true || hasOwnCover(own, path) || hasPinCover(path, rows, facts, own)) return [];
+  return [makeFinding(row.line, CODES.scope,
+    `${row.id} path ${path} is in the declared practice and no claim of ${own.id} covers it`, row.id)];
+};
+
+export const checkStoryOwnership = ({ rows, goalLines, facts, getConcretePaths }) => {
+  const { story, findings } = readStoryLine(goalLines);
+  if (!Object.hasOwn(facts, STORY_FIELDS)) return { findings };
+  if (typeof facts.storeRefusal === STRING_TYPE) {
+    return sortFindings([...findings, makeFinding(FIRST_LINE, CODES.store, facts.storeRefusal)]);
+  }
+  const resolved = findOwnStory(story, facts);
+  const own = resolved.own;
+  const others = facts.stories.filter((record) => record.state !== LANDED && (!own || !hasIdentity(record, own)));
+  const validRows = rows.filter((row) => row.valid);
+  const relation = validRows.flatMap((row) => getConcretePaths(row, facts).flatMap((path) => [
+    ...others.flatMap((record) => record.claims.flatMap((claim) => checkCollision(row, path, record, claim, own))),
+    ...checkScope(row, path, validRows, facts, own),
+  ]));
+  return sortFindings([...findings, ...resolved.findings, ...relation]);
+};

package/tools/plan-shape.mjs

@@ -1,5 +1,8 @@
+import { posix } from 'node:path';
 import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
 import { parseRobustTag } from './robustness-literals.mjs';
+import { unique } from './claim-relation.mjs';
+import { checkStoryOwnership, PIN_FILE, PIN_VERBS } from './plan-shape-ownership.mjs';
 
 export const PLAN_TITLE_PREFIX = '# Plan: ';
 export const PLAN_HEADINGS = Object.freeze([
@@ -31,7 +34,7 @@ const BULLET = /^-\s+\S/;
 export const getLineCount = (text) => text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
 export const isSweep = (path) => GLOB_BYTE.test(path);
 const endsWithPath = (path, suffix) => path === suffix || path.endsWith(`/${suffix}`);
-export const unique = (items) => [...new Set(items)];
+export { unique } from './claim-relation.mjs';
 const getFindingLine = (document, index) => document.frontLines + index + 1;
 const makeFinding = (line, code, message, rowId = null) => ({ line, code, message, rowId });
 const getHeading = (document, text) => document.headings.find((heading) => heading.text === text);
@@ -54,7 +57,8 @@ const getFigure = (value) => Number(String(value).replace(/^~/, ''));
 const getConcretePaths = (row, facts) => isSweep(row.path) ? facts.expansions?.[row.path] ?? [] : [row.path];
 const getPathFact = (facts, path) => facts.pathFacts?.[path] ?? null;
 const getAnchorPath = (anchor) => anchor.replace(/:[1-9]\d*$/, '');
-const hasPathDefect = (path) => path.startsWith('/') || path.includes('\\') || path.split('/').includes('..');
+const hasPathDefect = (path) => !(!path.includes('\\') &&
+  path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'));
 const hasRaiseBullet = (verificationBullets, path) => verificationBullets.some((bullet) =>
   bullet.includes('--write-baseline') && bullet.includes('--reason') && bullet.includes(path));
 
@@ -174,6 +178,22 @@ const checkHeadings = (text, document) => {
   return findings;
 };
 
+const isPinRow = (row, path) => row.verb === 'modify' && row.path === path && posix.basename(row.path) === PIN_FILE;
+const checkPinBindings = (rows, owners, facts) => {
+  if (!Object.hasOwn(facts, 'pathFacts')) return [];
+  return [...owners].flatMap(([path, group]) => {
+    const pins = group.filter((row) => isPinRow(row, path));
+    if (pins.length < 2) return [];
+    const taken = new Set();
+    return pins.flatMap((pin) => {
+      const above = rows.slice(0, rows.indexOf(pin)).findLast((row) => row.valid && PIN_VERBS.has(row.verb) && !taken.has(row) &&
+        getPathFact(facts, row.path)?.shipped === true && getPathFact(facts, row.path)?.pinTest === path);
+      if (above) { taken.add(above); return []; }
+      return [makeFinding(pin.line, 'pin-unbound', `${pin.id} is a repeated pin row with no untaken shipped create or delete above it`, pin.id)];
+    });
+  });
+};
+
 const checkLedgerStructure = (parsed, facts) => {
   const findings = [];
   const nonBlank = parsed.entries.filter((entry) => entry.raw.trim() !== '');
@@ -206,11 +226,15 @@ const checkLedgerStructure = (parsed, facts) => {
   const owners = new Map();
   for (const row of parsed.rows.filter((item) => item.valid)) {
     for (const path of getConcretePaths(row, facts)) {
-      const prior = owners.get(path);
-      if (prior) findings.push(makeFinding(row.line, 'duplicate-path', `${path} is owned by both ${prior} and ${row.id}`, row.id));
-      else owners.set(path, row.id);
+      const prior = owners.get(path) ?? [];
+      const conflicting = prior.find((owner) => !isPinRow(owner, path) || !isPinRow(row, path));
+      if (conflicting) {
+        findings.push(makeFinding(row.line, 'duplicate-path', `${path} is owned by both ${conflicting.id} and ${row.id}`, row.id));
+      }
+      owners.set(path, [...prior, row]);
     }
   }
+  findings.push(...checkPinBindings(parsed.rows, owners, facts));
   const last = nonBlank.at(-1);
   if (!parsed.total || (parsed.totals ?? []).length !== 1 || last?.line !== parsed.total?.line) {
     findings.push(makeFinding(last?.line ?? 1, 'total', 'the exact total line must be the last non-blank ledger line'));
@@ -236,9 +260,9 @@ const getAnchorCandidates = (row, preceding, facts) => {
   return facts.candidates(suffix, precedingPaths);
 };
 
-const getCurrentLines = (rows, facts, verbs) => rows
+const getCurrentLines = (rows, facts, verbs) => unique(rows
   .filter((row) => row.valid && verbs.has(row.verb) && row.budget !== 'n/a')
-  .flatMap((row) => getConcretePaths(row, facts))
+  .flatMap((row) => getConcretePaths(row, facts)))
   .reduce((sum, path) => sum + (getPathFact(facts, path)?.lines ?? 0), 0);
 
 const checkAuthoring = (parsed, facts) => {
@@ -335,7 +359,11 @@ const judge = (text, facts, stateRules) => {
     return { findings: [makeFinding(line, 'block-model', parsedResult.error.message)], skips: [], parsed: null };
   }
   const parsed = parsedResult.parsed;
-  const structural = [...checkHeadings(String(text ?? ''), parsed.document), ...checkLedgerStructure(parsed, facts)];
+  const goal = getHeading(parsed.document, PLAN_HEADINGS[0]);
+  const goalLines = goal ? getSectionLines(parsed.document, PLAN_HEADINGS[0])
+    .map((text, offset) => ({ text, line: getFindingLine(parsed.document, goal.index + 1 + offset) })) : [];
+  const structural = [...checkHeadings(String(text ?? ''), parsed.document), ...checkLedgerStructure(parsed, facts),
+    ...checkStoryOwnership({ rows: parsed.rows, goalLines, facts, getConcretePaths }).findings];
   const state = stateRules ? stateRules(parsed, facts) : { findings: [], skips: [] };
   const findings = [...structural, ...state.findings].map((finding, index) => ({ ...finding, order: index }))
     .sort((left, right) => left.line - right.line || left.order - right.order)