@sabaiway/agent-workflow-kit 13.1.0 → 13.2.0

package/CHANGELOG.md

@@ -4,6 +4,93 @@ 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.2.0 — the task tier lands: `checkpoint.mjs` mints, orders, verifies and prunes tree snapshots of a plan's sequence, `checkpoint-restore.mjs` restores one in three proven steps, `task-brief.mjs` stamps and checks a brief against the newest checkpoint, and `TASK-` is a scratch name (AD-141)
+
+**MINOR: three new tools and one added arm of the scratch-name predicate; no existing verb, record, transition or
+metric moves.** Since 13.1.0 the delegation ledger could measure a thread against a `checkpoint` base — a tree the
+orchestrator had to compute by hand. Now the kit mints it, keeps it in a sequence, restores to it and binds the
+task's brief to it. The contract is `docs/ai/specs/kit/checkpoint/index.md` with its parts `restore.md` and
+`task-brief.md` (live, revision 2, S1–S10 bound).
+
+- **`tools/checkpoint.mjs` (146 lines).** `mint --plan docs/plans/<stem>.md` writes ONE tree over the snapshot
+  scope of 13.1.0 (`snapshotScope`, the newest checkpoint as the base tree) through its own temporary index — a
+  forced add of every present regular file or symlink, one `write-tree`, the index removed before every return —
+  so `docs/ai/` deliverables are in the snapshot and the brief under `docs/plans/` never is; an absent leaf and a
+  directory at a former file leaf are deletions; a present non-regular path refuses by name and writes nothing;
+  the real index, the work tree and every other ref are untouched. The plan must be a readable regular file that is
+  a DIRECT child of `docs/plans/`, not a scratch name, with a stem `git check-ref-format` admits, else `stem`. The
+  ref of checkpoint `n` is `refs/agent-workflow/checkpoints/<stem>/<n>` and points at the TREE (reachable across
+  `gc`, never a branch, a fetch or a push); numbers run contiguously from 0; a mint whose tree equals the newest
+  ref's writes nothing and prints the newest's line; the line is `checkpoint <stem>/<n> <oid>`. `newest --plan`
+  prints the greatest or refuses `no-checkpoint`; `verify <oid>` recomputes with the target as base and prints
+  CLEAN (exit 0) or DIRTY (exit 1) with both oids, a lost snapshot path counted as dirt; `prune --plan` deletes the
+  plan's refs (an empty sequence exits 0) and refuses `open-thread`, deleting nothing, while any delegation-ledger
+  thread whose dispatch base is one of those trees is OPEN — judged by base oid alone, so another sequence's thread
+  holds the ref exactly when the two share the tree, and an unfolded success return still holds it; a malformed
+  ledger refuses. A non-tree id refuses through 13.1.0's `resolveTreeObject` wording. Exactly three exit codes:
+  0 accept or CLEAN, 1 refuse or DIRTY, 2 usage; `main(argv, deps)` returns and never exits; git runs through the
+  same guarded runner discipline as the 13.1.0 leaf (a thrown runner is a failed spawn).
+- **`tools/checkpoint-core.mjs` (118 lines).** The git seam the two halves share — the guarded runner, the
+  repository resolution, the sequence-ref reader (a listing line that is not `<ref> <oid>` refuses `sequence`),
+  the temporary-index discipline, the scope lstat and the snapshot write — so `checkpoint.mjs` and
+  `checkpoint-restore.mjs` both import the leaf; `checkpoint.mjs` still imports the restore module, which no longer
+  imports `checkpoint.mjs`. The pair had imported each other;
+  the tools graph's acyclic pin (`read-graph-purity`) caught it at the release gate, after the council.
+- **`tools/checkpoint-restore.mjs` (126 lines) and the `restore <oid>` verb.** Whole-tree over the snapshot scope,
+  ORDERED, idempotent and proven. Refused BEFORE the first write on exactly five states: a non-tree target;
+  `target-scope` — a target leaf outside the domain (an excluded path such as `docs/plans/x`), under a `.git`
+  segment, with a gitlink mode, or a tree no sequence ref carries; `ledger` — an unreadable or malformed ledger
+  (an absent one holds no thread); `open-thread` — an OPEN thread whose base oid is in the HELD SET, the target
+  plus every tree of every sequence carrying it (a disjoint sequence and a head base proceed); `type-conflict` — a
+  directory (empty or not) where the target holds a blob or a symlink, or a file or symlink at a parent segment
+  where the target needs a directory. Then MATERIALIZE (`read-tree` + `checkout-index -a -f` under a temporary
+  index: a blob lands as a file, a symlink entry as a symlink), EXTRAS (every domain path the target does not hold
+  is unlinked at its own lstat-ed leaf, never through a link; a parent emptied by that deletion is removed, never
+  the repository top, never a directory that still holds anything), PROOF (the scope tree recomputed as `verify`
+  computes it; equal → `checkpoint restore <oid> proof <oid>`, exit 0; unequal → exit 1 naming both oids, never a
+  restore claimed). Each step is a pure function of the target and the tree, so a re-run after an interruption at
+  any step converges; a restored ignore file that UNCOVERS a path the first domain did not hold surfaces as a
+  proof mismatch; re-running the restore converges. The real index is never a domain nor written (a staged change survives; the work tree under it is the
+  snapshot's); `docs/plans/`, the three settings files, the footprint and `node_modules` are never read, written or
+  deleted; earlier checkpoints stay; a restore to an older checkpoint is legal and undoes every task after it.
+- **`tools/task-brief.mjs` (270 lines).** A brief is `docs/plans/TASK-<stem>-T<n>.md`, its execute attempt's
+  dispatch file `TASK-<stem>-T<n>-a<attempt>.md` beside it — both scratch, both outside the scope. The grammar is
+  closed: `# Task: <name>`, the story line byte-equal to the plan's, `## Slice` (`Plan:`, `Row:`, `Grouping:`,
+  `Files:` of `- <path> :: <tag>`), `## Reads`, `## Acceptance` (`- <command> :: <expected>`), `## Negative cases`,
+  `## Budget` (`- <path> :: <max lines>`, one per file), at most one `aw-task-binding` block. Exactly seven states
+  refuse `shape`; a tag outside test/impl/pin, a `Grouping:` not equal to the present tags in that order, or the
+  pin rule broken (exactly one pin line naming the package-content path on that row, none elsewhere) refuse
+  `grouping`; a `Row:` naming no row, an impl path that is not the row's path or a sweep expansion (the anchor is
+  never a ground), or a test path not co-located refuse `row`; the story line absent or unequal refuses `story`.
+  `stamp <brief>` judges the grammar, then writes the ONE block `{ schema: 1, plan: { path, sha256 }, reads: [{
+  path, sha256 }], checkpoint: <newest tree oid>, head: <commit oid> }` over zero or one existing block and prints
+  `task-brief digest sha256:<hex>` of the whole stamped file; a plan or read that is not a readable regular file
+  inside the repository refuses `reads` (the descriptor-bound no-follow door), an empty sequence `no-checkpoint`,
+  an unresolvable HEAD `head`. `check <brief> [--dispatch <file>]` recomputes everything and refuses each stale
+  state by one name: `binding`, `no-checkpoint`, `reads`, `binding-plan`, `binding-read`, `binding-checkpoint`,
+  `checkpoint-stale` (the tree DIRTY against the bound checkpoint — mint again, stamp again), `binding-head`, and
+  with `--dispatch` `dispatch-inputs` when the attempt's `aw-dispatch-contract` header does not carry the brief
+  path and the current digest literal. Checkpoint facts are read through `checkpoint.mjs`'s own exports.
+- **`tools/plan-files.mjs`.** `TASK-` joins `isScratchPlanName`, so a brief or a dispatch file is never an
+  in-flight plan and neither `plan-shape --in-flight` nor `review-state` judges it; the review-state mode document
+  and header name the prefix.
+- **Tarball 305 → 309.** The four modules are pinned by name. Suites: `tools/checkpoint.test/mint.test.mjs`
+  (50), `tools/checkpoint.test/restore.test.mjs` (42), `tools/task-brief.test.mjs` (69), `tools/plan-files.test.mjs`
+  (2): every case of the first session written before the code existed and red, the three cases of the diff
+  review's fold red on the pre-fold code, then green; the release gate's coverage checker named the uncovered
+  sites and five cases closed them (each CLI run as a process, the malformed listing for both verbs, the
+  non-numeric suffix) — 311 of 311 across the seven files the story touches.
+- **Stated limits.** A present non-regular scope path refuses the restore at the proof step, after the writes; the
+  extras of a restore are judged under the ignore rules the tree carries BEFORE step (1), so a restored ignore file
+  that RE-COVERS a path (the task had un-ignored a build directory the snapshot never held) deletes that path as an
+  extra with a matching proof — a task that edits an ignore file is restored under the rules it left behind; a
+  retry of a terminal failure opens on the same base BEFORE Cleanup's prune, because after the prune no sequence
+  ref carries the base and the restore the retry needs refuses `target-scope` (the tree object itself is not
+  deleted, only unreachable by name); the precondition of a restore is no concurrent in-scope writer — a parallel session's `docs/ai/` write
+  during the task is restored away with a matching proof, so holding it is the orchestrator's; the process-group
+  stop of a running wrapper stays the bridge's contract, the kit's door is the OPEN-thread refusal; no parallel
+  tasks over one plan and no satellite worktrees; the `task` and `epic` rows of the activity table are story S7's.
+
 ## 13.1.0 — the delegation ledger learns a base: a dispatch records `head` or `checkpoint`, every measurement of a checkpoint thread is base-relative over the snapshot scope, and a checkpoint thread holds the delegate's session (AD-140)
 
 **MINOR: one optional key on the dispatch record, one new flag on `open`, one new IO leaf; every record minted

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: '13.1.0'
+  version: '13.2.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

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

package/references/modes/review-state.md

@@ -7,7 +7,7 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
 1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, the `held session: <id> — <n> fold(s) rode it` / `none` / substitution line when configured delegated execution arms it, and per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. Before the review-recipe early return, a configured `plan-execution.execute = delegated` with a plan in flight and a dirty, fingerprintable tree audits the delegation ledger and refuses a substituted held session; an absent ledger is inert, while an unreadable, malformed, foreign, audit-refused ledger or failed HEAD read fails closed with its own reason. For a head-base thread, the accepted-replacement escape is a `codex-exec` degrade at the substituted return's tree, standing after every later fold, never the review receipt id `codex`. A checkpoint-based thread's substitution closes only by its own ledger `degrade` (which also withdraws the expectation, so the next fold establishes HELD) — no core-evidence degrade lifts it, and the report's recovery hint says so. The remaining **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (after the held-session arm above) (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a cwd where git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree location that passes — `error`, `redirected`, `no-work-tree` and `env-only` refuse by their state name once a receipt could be required), or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a not-a-repository cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY review-backend escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (every edit the payload can see moves the fingerprint, and no more), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
+2. **`--check`** → the gate exit code. Before the review-recipe early return, a configured `plan-execution.execute = delegated` with a plan in flight and a dirty, fingerprintable tree audits the delegation ledger and refuses a substituted held session; an absent ledger is inert, while an unreadable, malformed, foreign, audit-refused ledger or failed HEAD read fails closed with its own reason. For a head-base thread, the accepted-replacement escape is a `codex-exec` degrade at the substituted return's tree, standing after every later fold, never the review receipt id `codex`. A checkpoint-based thread's substitution closes only by its own ledger `degrade` (which also withdraws the expectation, so the next fold establishes HELD) — no core-evidence degrade lifts it, and the report's recovery hint says so. The remaining **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (after the held-session arm above) (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`/`TASK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a cwd where git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree location that passes — `error`, `redirected`, `no-work-tree` and `env-only` refuse by their state name once a receipt could be required), or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a not-a-repository cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY review-backend escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (every edit the payload can see moves the fingerprint, and no more), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent init preview — never without consent (AD-021/D9).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated gates-init preview — `node ${CLAUDE_SKILL_DIR}/tools/gates-init.mjs --cwd <project>` (dry-run: it prints the derived entries and writes NOTHING; `--apply --only review-state` writes exactly this one on your explicit yes) — offers exactly this entry, path resolved and quoted, ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces). The full consent-fill contract is in `${CLAUDE_SKILL_DIR}/references/modes/gates.md`. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate — and `run-gates --final` requires this check among its canonical core gates.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It inherits the `--check` decision whole — a backend with a current-tree degrade RECORD stops being waited on (the shared decideCheck), so you never hand-`--await` around a known degrade. A held-session refusal and an **AUTHORITATIVE veto terminate the wait loudly BEFORE the deadline**: neither can be moved by waiting; only the held-session retry/degrade lane or a fresh review can move its corresponding refusal. Still read-only (it re-reads the receipts + the evidence store); solo / no-plan / clean-tree resolve instantly. For waiting on **one dispatch's arrival** (never obligation satisfaction) use the receipt-arrival deadline runner, `${CLAUDE_SKILL_DIR}/references/modes/receipt-deadline.md`.
 

package/tools/checkpoint-core.mjs

@@ -0,0 +1,118 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/index.md
+import { lstatSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { snapshotScope } from './dispatch-baseline.mjs';
+import { isNeverCommittableStat } from './core-evidence.mjs';
+import { isThreadTerminalRecord } from './dispatch-record.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, withGitPath } from './git-env.mjs';
+
+export const CHECKPOINT_REF_PREFIX = 'refs/agent-workflow/checkpoints/';
+const ACCEPT = 0;
+const REFUSE = 1;
+const INCREMENT = 1;
+const EMPTY = '';
+const SPACE = ' ';
+const NEWLINE = '\n';
+const UTF8 = 'utf8';
+const TEMP_PREFIX = 'aw-checkpoint-';
+const INDEX_NAME = 'index';
+const LITERAL_PATHSPECS = '1';
+const WORK_TREE = 'work-tree';
+const MISSING_PATH_CODES = ['ENOENT', 'ENOTDIR'];
+const OID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const NAMES = { scope: 'scope', sequence: 'sequence' };
+const DISPATCH_KIND = 'dispatch';
+const CHECKPOINT_KIND = 'checkpoint';
+const LOCATION_ERROR = 'checkpoint requires a git work tree';
+const SEQUENCE_ERROR = 'expected contiguous numbered refs on trees';
+const STAT_ERROR = 'cannot classify path';
+const TYPE_ERROR = 'present path is not a regular file, symlink or directory';
+const OID_ERROR = 'git did not return a tree oid';
+const GIT = 'git';
+const GIT_ARGS = {
+  refs: ['for-each-ref', '--format=%(refname) %(objectname)'],
+  empty: ['read-tree', '--empty'],
+  add: ['add', '-f', '--'],
+  tree: ['write-tree'],
+};
+
+export const refuse = (reason, code = REFUSE) => ({ ok: false, code, reason });
+const defaultRunGit = (args, cwd, input, env) => spawnSync(GIT, args, {
+  cwd, input, env: withGitPath(env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true,
+});
+export const makeRunner = ({ runGit = defaultRunGit, env = process.env } = {}) => (args, cwd, input, override = env) => {
+  try { return runGit(args, cwd, input, override); }
+  catch (error) { return { error, status: null, stdout: Buffer.alloc(ACCEPT) }; }
+};
+export const readGitBytes = ({ run, top, env }, args, override = env) => {
+  const result = run(args, top, undefined, override);
+  if (result == null || result.error || result.signal || result.status !== ACCEPT || result.stdout == null) {
+    throw new Error(`${GIT} ${args.join(SPACE)} failed: ${result?.error?.message ?? String(result?.stderr ?? EMPTY).trim()}`);
+  }
+  return Buffer.from(result.stdout);
+};
+export const readGit = (context, args, override = context.env) => readGitBytes(context, args, override).toString(UTF8).trimEnd();
+export const withRepository = (cwd, io, action) => {
+  try {
+    const env = io.env ?? process.env;
+    const run = makeRunner({ ...io, env });
+    const location = resolveGitLocation(cwd, { env,
+      spawn: (command, args, options) => run(args, options.cwd, undefined, options.env) });
+    if (location.state !== WORK_TREE) return refuse(location.cause ?? LOCATION_ERROR);
+    return action({ cwd, top: location.top, env, run, io: { ...io, env, runGit: run } });
+  } catch (error) {
+    return refuse(error.message);
+  }
+};
+export const readCheckpointRefs = (context, prefix = CHECKPOINT_REF_PREFIX) => {
+  const lines = readGit(context, [...GIT_ARGS.refs, prefix]).split(NEWLINE).filter(Boolean);
+  return lines.map((line) => {
+    const [ref, oid, extra] = line.split(SPACE);
+    if (!ref.startsWith(prefix) || !OID_PATTERN.test(oid) || extra !== undefined) {
+      throw new Error(`${NAMES.sequence}: ${SEQUENCE_ERROR}`);
+    }
+    return { ref, oid };
+  });
+};
+export const withTemporaryIndex = (env, action) => {
+  const directory = mkdtempSync(join(tmpdir(), TEMP_PREFIX));
+  try {
+    return action({ ...env, GIT_INDEX_FILE: join(directory, INDEX_NAME), GIT_LITERAL_PATHSPECS: LITERAL_PATHSPECS });
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+};
+export const readScopeStat = (context, path) => {
+  try {
+    const stat = (context.io.lstat ?? lstatSync)(join(context.top, path));
+    if (stat == null) throw new Error(STAT_ERROR);
+    return stat;
+  } catch (error) {
+    if (MISSING_PATH_CODES.includes(error.code)) return null;
+    throw new Error(`${NAMES.scope}: ${path}: ${error.message}`);
+  }
+};
+export const writeSnapshot = (context, baseTreeOid) => {
+  const scope = snapshotScope(context.top, { baseTreeOid }, context.io);
+  if (!scope.ok) return refuse(scope.reason);
+  const paths = scope.paths.filter((path) => {
+    const stat = readScopeStat(context, path);
+    if (stat === null) return false;
+    if (isNeverCommittableStat(stat) || !(stat.isFile() || stat.isSymbolicLink() || stat.isDirectory())) {
+      throw new Error(`${NAMES.scope}: ${path}: ${TYPE_ERROR}`);
+    }
+    return stat.isFile() || stat.isSymbolicLink();
+  });
+  return withTemporaryIndex(context.env, (env) => {
+    readGit(context, GIT_ARGS.empty, env);
+    for (const path of paths) readGit(context, [...GIT_ARGS.add, path], env);
+    const oid = readGit(context, GIT_ARGS.tree, env);
+    if (!OID_PATTERN.test(oid)) return refuse(`${NAMES.scope}: ${OID_ERROR}`);
+    return { ok: true, oid };
+  });
+};
+export const findOpenCheckpointThread = (records, held) => records.find((record, index) =>
+  record.kind === DISPATCH_KIND && record.baseline?.kind === CHECKPOINT_KIND && held.has(record.baseline.treeOid)
+  && !records.slice(index + INCREMENT).some((successor) => successor.nonce === record.nonce && isThreadTerminalRecord(successor)));

package/tools/checkpoint-restore.mjs

@@ -0,0 +1,126 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/restore.md
+import { unlinkSync, rmdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { resolveTreeObject, snapshotScope } from './dispatch-baseline.mjs';
+import { readDelegationLedger } from './dispatch-store-read.mjs';
+import { CHECKPOINT_REF_PREFIX, withRepository, readGit, readGitBytes, readCheckpointRefs,
+  withTemporaryIndex, readScopeStat, writeSnapshot, findOpenCheckpointThread } from './checkpoint-core.mjs';
+
+const REFUSE = 1;
+const START = 0;
+const NEXT = 1;
+const LAST = -1;
+const SLASH = '/';
+const NUL = '\0';
+const UTF8 = 'utf8';
+const ROOT = '.';
+const FORBIDDEN_SEGMENTS = ['', '.', '..', '.git'];
+const ENTRY_PATTERN = /^([0-9]{6}) [^ ]+ [0-9a-f]+\t([\s\S]+)$/;
+const SEQUENCE_REF_PATTERN = /^[^/]+\/(?:0|[1-9][0-9]*)$/;
+const ALLOWED_MODES = ['100644', '100755', '120000'];
+const LEDGER_ABSENT = 'absent';
+const LEDGER_OK = 'ok';
+const NONEMPTY_CODES = ['ENOTEMPTY', 'EEXIST'];
+const NAMES = { scope: 'target-scope', ledger: 'ledger', open: 'open-thread', conflict: 'type-conflict' };
+const ENCODING_ERROR = 'target tree paths are not lossless UTF-8';
+const ENTRY_ERROR = 'unreadable target tree entry';
+const UNREFERENCED_ERROR = 'no checkpoint sequence carries target';
+const MISMATCH = 'checkpoint restore mismatch';
+const GIT_ARGS = {
+  resolve: ['rev-parse', '--verify'],
+  entries: ['ls-tree', '-r', '-z'],
+  read: ['read-tree'],
+  checkout: ['checkout-index', '-a', '-f'],
+};
+
+const refuse = (reason) => ({ ok: false, code: REFUSE, reason });
+const readTargetEntries = (context, target) => {
+  const bytes = readGitBytes(context, [...GIT_ARGS.entries, target]);
+  const text = bytes.toString(UTF8);
+  if (!Buffer.from(text, UTF8).equals(bytes)) throw new Error(`${NAMES.scope}: ${ENCODING_ERROR}`);
+  return text.split(NUL).filter(Boolean).map((entry) => {
+    const parsed = ENTRY_PATTERN.exec(entry);
+    if (parsed === null) throw new Error(`${NAMES.scope}: ${ENTRY_ERROR}`);
+    const [, mode, path] = parsed;
+    if (!ALLOWED_MODES.includes(mode) || path.split(SLASH).some((segment) => FORBIDDEN_SEGMENTS.includes(segment))) {
+      throw new Error(`${NAMES.scope}: ${path}`);
+    }
+    return path;
+  });
+};
+const readHeldSet = (context, target) => {
+  const refs = readCheckpointRefs(context).filter(({ ref }) => SEQUENCE_REF_PATTERN.test(ref.slice(CHECKPOINT_REF_PREFIX.length)));
+  const sequences = new Set(refs.filter(({ oid }) => oid === target).map(({ ref }) => dirname(ref)));
+  if (sequences.size === START) throw new Error(`${NAMES.scope}: ${UNREFERENCED_ERROR}: ${target}`);
+  return new Set([target, ...refs.filter(({ ref }) => sequences.has(dirname(ref))).map(({ oid }) => oid)]);
+};
+const checkLedger = (context, held) => {
+  const ledger = readDelegationLedger(context.cwd, context.env);
+  if (ledger.state !== LEDGER_ABSENT && ledger.state !== LEDGER_OK) return refuse(`${NAMES.ledger}: ${ledger.reason}`);
+  const open = findOpenCheckpointThread(ledger.records ?? [], held);
+  return open === undefined ? { ok: true } : refuse(`${NAMES.open}: ${open.nonce}`);
+};
+const listParents = (path) => {
+  const parts = path.split(SLASH).slice(START, LAST);
+  return parts.map((part, index) => parts.slice(START, index + NEXT).join(SLASH));
+};
+const checkTypes = (context, paths) => {
+  for (const path of paths) {
+    for (const parent of listParents(path)) {
+      const stat = readScopeStat(context, parent);
+      if (stat === null) break;
+      if (!stat.isDirectory()) return refuse(`${NAMES.conflict}: ${parent}: ${path}`);
+    }
+    if (readScopeStat(context, path)?.isDirectory()) return refuse(`${NAMES.conflict}: ${path}`);
+  }
+  return { ok: true };
+};
+const removeEmptyParents = (context, path) => {
+  const parent = dirname(path);
+  if (parent === ROOT) return;
+  const stat = readScopeStat(context, parent);
+  if (stat === null || !stat.isDirectory()) return;
+  try {
+    rmdirSync(join(context.top, parent));
+  } catch (error) {
+    if (!NONEMPTY_CODES.includes(error.code)) throw error;
+    return;
+  }
+  removeEmptyParents(context, parent);
+};
+const removeExtras = (context, domain, targets) => {
+  for (const path of domain) {
+    if (targets.has(path) || path.split(SLASH).some((segment) => FORBIDDEN_SEGMENTS.includes(segment))) continue;
+    if (!listParents(path).every((parent) => readScopeStat(context, parent)?.isDirectory())) continue;
+    const stat = readScopeStat(context, path);
+    if (stat === null || !(stat.isFile() || stat.isSymbolicLink())) continue;
+    unlinkSync(join(context.top, path));
+    removeEmptyParents(context, path);
+  }
+};
+
+export const restoreCheckpoint = (cwd, oid, io = {}) => withRepository(cwd, io, (context) => {
+  const tree = resolveTreeObject(context.top, oid, context.io);
+  if (!tree.ok) return refuse(tree.reason);
+  const target = readGit(context, [...GIT_ARGS.resolve, oid]);
+  const entries = readTargetEntries(context, target);
+  const scope = snapshotScope(context.top, { baseTreeOid: target }, context.io);
+  if (!scope.ok) return refuse(scope.reason);
+  const domain = new Set(scope.paths);
+  const outside = entries.find((path) => !domain.has(path));
+  if (outside !== undefined) return refuse(`${NAMES.scope}: ${outside}`);
+  const held = readHeldSet(context, target);
+  const ledger = checkLedger(context, held);
+  if (!ledger.ok) return ledger;
+  const types = checkTypes(context, entries);
+  if (!types.ok) return types;
+  withTemporaryIndex(context.env, (env) => {
+    readGit(context, [...GIT_ARGS.read, target], env);
+    readGit(context, GIT_ARGS.checkout, env);
+  });
+  removeExtras(context, scope.paths, new Set(entries));
+  const snapshot = writeSnapshot(context, target);
+  if (!snapshot.ok) return snapshot;
+  return snapshot.oid === target ? { ok: true, target, proof: snapshot.oid }
+    : refuse(`${MISMATCH}: ${target} ${snapshot.oid}`);
+});

package/tools/checkpoint.mjs

@@ -0,0 +1,146 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/index.md
+import { lstatSync, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { resolveTreeObject } from './dispatch-baseline.mjs';
+import { readDelegationLedger } from './dispatch-store-read.mjs';
+import { PLANS_REL, isScratchPlanName } from './plan-files.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { CHECKPOINT_REF_PREFIX, refuse, withRepository, readGit, readCheckpointRefs, writeSnapshot,
+  findOpenCheckpointThread } from './checkpoint-core.mjs';
+import { restoreCheckpoint } from './checkpoint-restore.mjs';
+
+export { CHECKPOINT_REF_PREFIX } from './checkpoint-core.mjs';
+const ACCEPT = 0;
+const REFUSE = 1;
+const USAGE = 2;
+const FIRST_NUMBER = 0;
+const INCREMENT = 1;
+const LAST = -1;
+const EMPTY = '';
+const NEWLINE = '\n';
+const SLASH = '/';
+const STRING = 'string';
+const MARKDOWN = '.md';
+const NUMBER_PATTERN = /^(0|[1-9][0-9]*)$/;
+const VERBS = { mint: 'mint', newest: 'newest', verify: 'verify', prune: 'prune', restore: 'restore' };
+const NAMES = { stem: 'stem', sequence: 'sequence', ledger: 'ledger', open: 'open-thread', empty: 'no-checkpoint' };
+const CHECKPOINT_KIND = 'checkpoint';
+const LEDGER_ABSENT = 'absent';
+const LEDGER_OK = 'ok';
+const CLEAN = 'CLEAN';
+const DIRTY = 'DIRTY';
+const PROOF = 'proof';
+const PLAN_FLAG = '--plan';
+const PLAN_ARG_COUNT = 3;
+const OID_ARG_COUNT = 2;
+const ARGV_OFFSET = 2;
+const USAGE_TEXT = 'usage: checkpoint mint|newest|prune --plan <plan> | verify|restore <oid>';
+const PLAN_ERROR = 'expected a readable regular plan directly under docs/plans';
+const SEQUENCE_ERROR = 'expected contiguous numbered refs on trees';
+const GIT_ARGS = {
+  checkRef: ['check-ref-format'],
+  resolve: ['rev-parse', '--verify'],
+  update: ['update-ref', '--no-deref'],
+  remove: ['update-ref', '--no-deref', '-d'],
+};
+
+const readPlan = (context, planPath) => {
+  try {
+    if (typeof planPath !== STRING || isAbsolute(planPath)) return refuse(`${NAMES.stem}: ${PLAN_ERROR}`);
+    const path = resolve(context.cwd, planPath);
+    const parent = relative(context.top, dirname(path)).split(sep).join(SLASH);
+    const name = basename(path);
+    if (parent !== PLANS_REL || !name.endsWith(MARKDOWN) || isScratchPlanName(name)
+      || !(context.io.lstat ?? lstatSync)(path).isFile()) return refuse(`${NAMES.stem}: ${PLAN_ERROR}`);
+    readFileSync(path);
+    const stem = name.slice(FIRST_NUMBER, -MARKDOWN.length);
+    readGit(context, [...GIT_ARGS.checkRef, `${CHECKPOINT_REF_PREFIX}${stem}/${FIRST_NUMBER}`]);
+    return { ok: true, stem };
+  } catch (error) {
+    return refuse(`${NAMES.stem}: ${error.message}`);
+  }
+};
+const readSequence = (context, stem) => {
+  const prefix = `${CHECKPOINT_REF_PREFIX}${stem}${SLASH}`;
+  const refs = readCheckpointRefs(context, prefix).map(({ ref, oid }) => {
+    const suffix = ref.slice(prefix.length);
+    if (!NUMBER_PATTERN.test(suffix)) {
+      throw new Error(`${NAMES.sequence}: ${SEQUENCE_ERROR}`);
+    }
+    return { ref, oid, n: Number(suffix), stem };
+  }).sort((left, right) => left.n - right.n);
+  for (const [index, checkpoint] of refs.entries()) {
+    if (!Number.isSafeInteger(checkpoint.n) || checkpoint.n !== index) throw new Error(`${NAMES.sequence}: ${SEQUENCE_ERROR}`);
+    const tree = resolveTreeObject(context.top, checkpoint.oid, context.io);
+    if (!tree.ok) throw new Error(tree.reason);
+  }
+  return refs;
+};
+const withSequence = (cwd, planPath, io, action) => withRepository(cwd, io, (context) => {
+  const plan = readPlan(context, planPath);
+  if (!plan.ok) return plan;
+  return action(context, plan.stem, readSequence(context, plan.stem));
+});
+
+export const mintCheckpoint = (cwd, planPath, io = {}) => withSequence(cwd, planPath, io, (context, stem, refs) => {
+  const newest = refs.at(LAST);
+  const snapshot = writeSnapshot(context, newest?.oid ?? null);
+  if (!snapshot.ok) return snapshot;
+  if (snapshot.oid === newest?.oid) return { ok: true, ...newest };
+  const n = newest === undefined ? FIRST_NUMBER : newest.n + INCREMENT;
+  const ref = `${CHECKPOINT_REF_PREFIX}${stem}/${n}`;
+  readGit(context, [...GIT_ARGS.update, ref, snapshot.oid]);
+  return { ok: true, stem, n, ref, oid: snapshot.oid };
+});
+
+export const newestCheckpoint = (cwd, planPath, io = {}) => withSequence(cwd, planPath, io, (context, stem, refs) => {
+  const newest = refs.at(LAST);
+  return newest === undefined ? refuse(`${NAMES.empty}: ${stem}`) : { ok: true, ...newest };
+});
+
+export const verifyCheckpoint = (cwd, oid, io = {}) => withRepository(cwd, io, (context) => {
+  const tree = resolveTreeObject(context.top, oid, context.io);
+  if (!tree.ok) return refuse(tree.reason);
+  const target = readGit(context, [...GIT_ARGS.resolve, oid]);
+  const snapshot = writeSnapshot(context, target);
+  if (!snapshot.ok) return snapshot;
+  return { ok: true, clean: target === snapshot.oid, target, oid: snapshot.oid };
+});
+
+export const pruneCheckpoints = (cwd, planPath, io = {}) => withSequence(cwd, planPath, io, (context, stem, refs) => {
+  const ledger = readDelegationLedger(context.cwd, context.env);
+  if (ledger.state !== LEDGER_ABSENT && ledger.state !== LEDGER_OK) return refuse(`${NAMES.ledger}: ${ledger.reason}`);
+  const records = ledger.records ?? [];
+  const held = new Set(refs.map(({ oid }) => oid));
+  const open = findOpenCheckpointThread(records, held);
+  if (open !== undefined) return refuse(`${NAMES.open}: ${open.nonce}`);
+  for (const { ref } of [...refs].reverse()) readGit(context, [...GIT_ARGS.remove, ref]);
+  return { ok: true };
+});
+
+const PLAN_OPERATIONS = { [VERBS.mint]: mintCheckpoint, [VERBS.newest]: newestCheckpoint, [VERBS.prune]: pruneCheckpoints };
+const formatRef = ({ stem, n, oid }) => `${CHECKPOINT_KIND} ${stem}/${n} ${oid}${NEWLINE}`;
+const formatRefusal = ({ code, reason }) => ({ code, stdout: EMPTY, stderr: `${reason}${NEWLINE}` });
+export const main = (argv = process.argv.slice(ARGV_OFFSET), deps = {}) => {
+  const [verb, operand, planPath] = argv;
+  const planVerb = Object.hasOwn(PLAN_OPERATIONS, verb);
+  const oidVerb = verb === VERBS.verify || verb === VERBS.restore;
+  if (!(planVerb && argv.length === PLAN_ARG_COUNT && operand === PLAN_FLAG && planPath)
+    && !(oidVerb && argv.length === OID_ARG_COUNT && operand)) return formatRefusal(refuse(USAGE_TEXT, USAGE));
+  const cwd = deps.cwd ?? process.cwd();
+  const operation = verb === VERBS.restore ? restoreCheckpoint : verifyCheckpoint;
+  const result = planVerb ? PLAN_OPERATIONS[verb](cwd, planPath, deps) : operation(cwd, operand, deps);
+  if (!result.ok) return formatRefusal(result);
+  if (verb === VERBS.restore) return { code: ACCEPT,
+    stdout: `${CHECKPOINT_KIND} ${VERBS.restore} ${result.target} ${PROOF} ${result.proof}${NEWLINE}`, stderr: EMPTY };
+  if (verb === VERBS.verify) return { code: result.clean ? ACCEPT : REFUSE,
+    stdout: `${result.clean ? CLEAN : DIRTY} ${result.target} ${result.oid}${NEWLINE}`, stderr: EMPTY };
+  return { code: ACCEPT, stdout: verb === VERBS.prune ? EMPTY : formatRef(result), stderr: EMPTY };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main();
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  process.exitCode = result.code;
+}

package/tools/plan-files.mjs

@@ -9,12 +9,13 @@ import { join } from 'node:path';
 
 export const PLANS_REL = 'docs/plans';
 
-// Scratch by the naming convention: EXECUTE-/FEEDBACK- prefixes, or a name carrying PROMPT/prompt/
+// Scratch by the naming convention: EXECUTE-/FEEDBACK-/TASK- prefixes, or a name carrying PROMPT/prompt/
 // handoff. queue.md is the series index, never a plan.
 export const isScratchPlanName = (name) =>
   name === 'queue.md' ||
   name.startsWith('EXECUTE-') ||
   name.startsWith('FEEDBACK-') ||
+  name.startsWith('TASK-') ||
   name.includes('PROMPT') ||
   name.includes('prompt') ||
   name.includes('handoff');

package/tools/review-state.mjs

@@ -18,7 +18,7 @@
 //   exit 0  when the CONFIGURED plan-execution.review recipe is solo (or the computed default is —
 //           absent config with no reviewer backend ready); when no plan is in flight (docs/plans/
 //           holds no top-level .md that is not queue.md and not scratch by the naming convention:
-//           prefixes EXECUTE- / FEEDBACK-, or a name containing PROMPT / prompt / handoff); when
+//           prefixes EXECUTE- / FEEDBACK- / TASK-, or a name containing PROMPT / prompt / handoff); when
 //           the tree is clean (nothing to review — under a non-solo review obligation the PASS
 //           still NAMES every plan in flight and states that the gate arms as soon as the tree
 //           turns dirty, so a latent arm is discoverable before it blocks a pending commit); when

package/tools/task-brief.mjs

@@ -0,0 +1,270 @@
+// spec:checkpoint — docs/ai/specs/kit/checkpoint/task-brief.md
+import { writeFileSync, realpathSync, constants as fsConstants } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep, posix } from 'node:path';
+import { createHash } from 'node:crypto';
+import { readFileBytesNoFollow } from './fs-read-nofollow.mjs';
+import { parseLedger, isSweep, PLAN_HEADINGS } from './plan-shape.mjs';
+import { expandSweepPaths } from './plan-shape-facts.mjs';
+import { readStoryLine, PIN_FILE } from './plan-shape-ownership.mjs';
+import { parseDispatchContract } from './dispatch-record.mjs';
+import { newestCheckpoint, verifyCheckpoint } from './checkpoint.mjs';
+import { withRepository, readGit } from './checkpoint-core.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+export const BRIEF_BINDING_INFO_STRING = 'aw-task-binding';
+const ACCEPT = 0;
+const REFUSE = 1;
+const USAGE = 2;
+const START = 0;
+const ONE = 1;
+const EMPTY = '';
+const NL = '\n';
+const CR_END = /\r$/;
+const UTF8 = 'utf8';
+const STRING = 'string';
+const OBJECT = 'object';
+const HASH = 'sha256';
+const HEX = 'hex';
+const SHA_PREFIX = 'sha256:';
+const DIGEST_LINE = 'task-brief digest';
+const FENCE = '```';
+const FENCE_RE = /^(`{3,})(.*)$/;
+const TITLE_RE = /^# Task: (\S.*)$/;
+const HEADING_RE = /^#{1,2} /;
+const STORY_PREFIX = 'Story:';
+const HEADINGS = ['## Slice', '## Reads', '## Acceptance', '## Negative cases', '## Budget'];
+const SLICE_FIELDS = [/^Plan: (docs\/plans\/[^/]+\.md)$/, /^Row: (\S+)$/, /^Grouping: (.*)$/, /^Files:$/];
+const PAIR_RE = /^- (\S(?:.*\S)?) :: (\S(?:.*\S)?)$/;
+const BULLET_RE = /^- (\S.*)$/;
+const INTEGER_RE = /^[1-9]\d*$/;
+const TEST_RE = /(?:^|\/)[^/]+\.test(?:\.mjs$|\/[^/].*$)/;
+const EXTENSION_RE = /\.[^/.]+$/;
+const TEST_SUFFIX = '.test.mjs';
+const TEST_DIRECTORY = '.test/';
+const TEST = 'test';
+const IMPL = 'impl';
+const PIN = 'pin';
+const TAGS = [TEST, IMPL, PIN];
+const GROUP_SEPARATOR = ', ';
+const PARENT = '..';
+const CURRENT = '.';
+const READ_OK = 'ok';
+const SCHEMA = 1;
+const BINDING_KEYS = ['schema', 'plan', 'reads', 'checkpoint', 'head'];
+const FILE_KEYS = ['path', 'sha256'];
+const SHA_RE = /^[0-9a-f]{64}$/;
+const OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const HEAD_ARGS = ['rev-parse', '--verify', 'HEAD^{commit}'];
+const STAMP = 'stamp';
+const CHECK = 'check';
+const DISPATCH_FLAG = '--dispatch';
+const BASIC_ARGS = 2;
+const DISPATCH_ARGS = 4;
+const ARGV_OFFSET = 2;
+const NAMES = { shape: 'shape', grouping: 'grouping', row: 'row', story: 'story', reads: 'reads', binding: 'binding',
+  plan: 'binding-plan', read: 'binding-read', checkpoint: 'binding-checkpoint', stale: 'checkpoint-stale',
+  head: 'head', boundHead: 'binding-head', dispatch: 'dispatch-inputs' };
+const USAGE_TEXT = 'usage: task-brief stamp <brief> | check <brief> [--dispatch <file>]';
+const WRITE_FLAGS = fsConstants.O_WRONLY | fsConstants.O_TRUNC | fsConstants.O_NOFOLLOW;
+
+const refuse = (reason, code = REFUSE) => ({ ok: false, code, reason });
+const reject = (name, detail = EMPTY) => { throw new Error(`${name}: ${detail}`); };
+const computeDigest = (bytes) => createHash(HASH).update(bytes).digest(HEX);
+const matchLine = (pattern, line) => {
+  const match = pattern.exec(line ?? EMPTY);
+  if (match === null) reject(NAMES.shape, line);
+  return match.slice(ONE);
+};
+const splitBindingBlocks = (text) => {
+  const raw = text.split(NL);
+  const lines = raw.map((line) => line.replace(CR_END, EMPTY));
+  const state = lines.reduce((state, line, index) => {
+    const fence = FENCE_RE.exec(line);
+    if (fence === null) return state;
+    const ticks = fence[ONE].length;
+    const info = fence[BASIC_ARGS].trim();
+    if (state.open === null) return { ...state, open: { ticks, info, start: index } };
+    if (info !== EMPTY || ticks < state.open.ticks) return state;
+    const blocks = state.open.info === BRIEF_BINDING_INFO_STRING
+      ? [...state.blocks, { start: state.open.start, end: index, source: lines.slice(state.open.start + ONE, index).join(NL) }]
+      : state.blocks;
+    return { open: null, blocks };
+  }, { open: null, blocks: [] });
+  const unclosed = state.open?.info === BRIEF_BINDING_INFO_STRING;
+  const blocks = unclosed ? [...state.blocks, { start: state.open.start, end: lines.length, source: null }] : state.blocks;
+  const outside = (index) => !blocks.some(({ start, end }) => index >= start && index <= end);
+  return { blocks, unclosed, body: raw.filter((line, index) => outside(index)).join(NL),
+    lines: lines.filter((line, index) => outside(index) && line.trim() !== EMPTY) };
+};
+export const parseBrief = (text) => {
+  try {
+    if (typeof text !== STRING) return refuse(NAMES.shape);
+    const document = splitBindingBlocks(text);
+    const lines = document.lines;
+    const [title] = matchLine(TITLE_RE, lines[START]);
+    const headings = lines.flatMap((line, index) => HEADING_RE.test(line) ? [{ text: line, index }] : []);
+    if (headings.length !== HEADINGS.length + ONE || HEADINGS.some((text, index) => headings[index + ONE]?.text !== text)) reject(NAMES.shape);
+    const sections = HEADINGS.map((heading, index) => lines.slice(headings[index + ONE].index + ONE, headings[index + BASIC_ARGS]?.index ?? lines.length));
+    const storyLines = lines.slice(ONE, headings[ONE].index);
+    if (storyLines.some((line) => !line.startsWith(STORY_PREFIX))) reject(NAMES.shape);
+    const [slice, reads, acceptance, negative, budget] = sections;
+    const [[planPath], [rowId], [grouping]] = SLICE_FIELDS.map((pattern, index) => matchLine(pattern, slice[index]));
+    const files = slice.slice(SLICE_FIELDS.length).map((line) => {
+      const [path, tag] = matchLine(PAIR_RE, line);
+      return { path, tag };
+    });
+    const budgets = budget.map((line) => {
+      const [path, count] = matchLine(PAIR_RE, line);
+      if (!INTEGER_RE.test(count) || !Number.isSafeInteger(Number(count))) reject(NAMES.shape, line);
+      return { path, maxLines: Number(count) };
+    });
+    const filePaths = new Set(files.map(({ path }) => path));
+    if (files.length === START || budgets.length !== filePaths.size || new Set(budgets.map(({ path }) => path)).size !== filePaths.size
+      || budgets.some(({ path }) => !filePaths.has(path)) || acceptance.length === START || negative.length === START) reject(NAMES.shape);
+    return { ok: true, title, storyLines, planPath, rowId, grouping, files, budgets,
+      reads: reads.map((line) => matchLine(BULLET_RE, line)[START]),
+      acceptance: acceptance.map((line) => matchLine(PAIR_RE, line)), negative: negative.map((line) => matchLine(BULLET_RE, line)[START]),
+      blocks: document.blocks, unclosed: document.unclosed, body: document.body };
+  } catch (error) { return refuse(error.message); }
+};
+const isInside = (top, path) => {
+  const rel = relative(top, path);
+  return !isAbsolute(rel) && rel !== PARENT && !rel.startsWith(`${PARENT}${sep}`);
+};
+const readInside = (context, path, name = NAMES.reads) => {
+  try {
+    if (typeof path !== STRING || path === EMPTY || isAbsolute(path)) reject(name, path);
+    const absolute = resolve(context.cwd, path);
+    if (!isInside(context.top, absolute) || !isInside(realpathSync(context.top), realpathSync(dirname(absolute)))) reject(name, path);
+    const result = readFileBytesNoFollow(absolute, context.io);
+    if (result.outcome !== READ_OK) reject(name, `${path}: ${result.code ?? result.className ?? result.outcome}`);
+    return { path, absolute, bytes: result.bytes, sha256: computeDigest(result.bytes) };
+  } catch (error) { reject(name, `${path}: ${error.message}`); }
+};
+const checkGrouping = (brief, row) => {
+  if (brief.files.some(({ tag }) => !TAGS.includes(tag))
+    || brief.grouping !== TAGS.filter((tag) => brief.files.some((file) => file.tag === tag)).join(GROUP_SEPARATOR)) reject(NAMES.grouping);
+  const pins = brief.files.filter(({ tag }) => tag === PIN);
+  if (row && posix.basename(row.path) === PIN_FILE) {
+    if (pins.length !== ONE || pins[START].path !== row.path) reject(NAMES.grouping);
+  } else if (pins.length !== START) reject(NAMES.grouping);
+};
+const checkRow = (context, brief, row) => {
+  if (!row?.valid) reject(NAMES.row, brief.rowId);
+  const files = brief.files.map((file) => {
+    const path = posix.normalize(file.path);
+    if (path !== file.path || path === CURRENT || path.startsWith(PARENT) || posix.isAbsolute(path)) reject(NAMES.row, file.path);
+    return { ...file, path };
+  });
+  const implementations = files.filter(({ tag }) => tag === IMPL).map(({ path }) => path);
+  const allowed = isSweep(row.path) ? expandSweepPaths(context.top, [row.path])[row.path] : [row.path];
+  if (implementations.some((path) => !allowed.includes(path))) reject(NAMES.row, row.id);
+  const tests = files.filter(({ tag }) => tag === TEST);
+  if (tests.some(({ path }) => TEST_RE.test(row.path) ? path !== row.path : !implementations.some((impl) => {
+    const stem = impl.replace(EXTENSION_RE, EMPTY);
+    return path === `${stem}${TEST_SUFFIX}` || path.startsWith(`${stem}${TEST_DIRECTORY}`);
+  }))) reject(NAMES.row, row.id);
+};
+const selectStory = (lines) => {
+  const entries = lines.map((text, index) => ({ text, line: index + ONE }));
+  const result = readStoryLine(entries);
+  return result.story && result.findings.length === START ? lines[result.story.line - ONE] : null;
+};
+const readGrammar = (context, briefPath) => {
+  const file = readInside(context, briefPath);
+  const brief = parseBrief(file.bytes.toString(UTF8));
+  if (!brief.ok) return brief;
+  const plan = readInside(context, brief.planPath);
+  const ledger = parseLedger(plan.bytes.toString(UTF8));
+  const row = ledger.rows.find(({ id }) => id === brief.rowId);
+  checkGrouping(brief, row);
+  checkRow(context, brief, row);
+  const goal = ledger.document.headings.find(({ text }) => text === PLAN_HEADINGS[START]);
+  const end = ledger.document.headings.find(({ index }) => index > goal?.index);
+  const story = goal ? selectStory(ledger.document.lines.slice(goal.index + ONE, end?.index)) : null;
+  if (story === null || selectStory(brief.storyLines) !== story) reject(NAMES.story);
+  return { ok: true, file, brief, plan };
+};
+const checkBlockCount = (brief, required) => {
+  if (brief.unclosed || brief.blocks.length > ONE || (required && brief.blocks.length !== ONE)) reject(NAMES.binding);
+};
+const hasClosedKeys = (value, keys) => value !== null && typeof value === OBJECT && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+const isFileBinding = (value) => hasClosedKeys(value, FILE_KEYS) && typeof value.path === STRING && typeof value.sha256 === STRING && SHA_RE.test(value.sha256);
+const readBinding = (brief) => {
+  checkBlockCount(brief, true);
+  try {
+    const value = JSON.parse(brief.blocks[START].source);
+    if (!hasClosedKeys(value, BINDING_KEYS) || value.schema !== SCHEMA || !isFileBinding(value.plan)
+      || !Array.isArray(value.reads) || !value.reads.every(isFileBinding) || typeof value.checkpoint !== STRING
+      || !OID_RE.test(value.checkpoint) || typeof value.head !== STRING || !OID_RE.test(value.head)) reject(NAMES.binding);
+    return value;
+  } catch (error) { reject(NAMES.binding, error.message); }
+};
+const readHead = (context, name) => {
+  try {
+    const oid = readGit(context, HEAD_ARGS);
+    if (!OID_RE.test(oid)) reject(name);
+    return oid;
+  } catch (error) { reject(name, error.message); }
+};
+const bindFile = ({ path, sha256 }) => ({ path, sha256 });
+const checkDispatch = (context, dispatchPath, briefPath, digest) => {
+  const file = readInside(context, dispatchPath, NAMES.dispatch);
+  const parsed = parseDispatchContract(file.bytes.toString(UTF8));
+  if (!parsed.ok || typeof parsed.contract.inputs !== STRING || !parsed.contract.inputs.includes(briefPath)
+    || !parsed.contract.inputs.includes(`${SHA_PREFIX}${digest}`)) reject(NAMES.dispatch);
+};
+
+export const stampBrief = (cwd, briefPath, io = {}) => withRepository(cwd, io, (context) => {
+  const grammar = readGrammar(context, briefPath);
+  if (!grammar.ok) return grammar;
+  const { file, brief, plan } = grammar;
+  checkBlockCount(brief, false);
+  const reads = brief.reads.map((path) => bindFile(readInside(context, path)));
+  const newest = newestCheckpoint(cwd, brief.planPath, context.io);
+  if (!newest.ok) return newest;
+  const binding = { schema: SCHEMA, plan: bindFile(plan), reads, checkpoint: newest.oid, head: readHead(context, NAMES.head) };
+  const bytes = Buffer.from(`${brief.body.trimEnd()}${NL}${NL}${FENCE}${BRIEF_BINDING_INFO_STRING}${NL}${JSON.stringify(binding)}${NL}${FENCE}${NL}`, UTF8);
+  writeFileSync(file.absolute, bytes, { flag: WRITE_FLAGS });
+  return { ok: true, digest: computeDigest(bytes) };
+});
+
+export const checkBrief = (cwd, briefPath, { dispatchPath } = {}, io = {}) => withRepository(cwd, io, (context) => {
+  const grammar = readGrammar(context, briefPath);
+  if (!grammar.ok) return grammar;
+  const { file, brief, plan } = grammar;
+  const binding = readBinding(brief);
+  const newest = newestCheckpoint(cwd, brief.planPath, context.io);
+  if (!newest.ok) return newest;
+  const reads = brief.reads.map((path) => bindFile(readInside(context, path)));
+  if (binding.plan.path !== brief.planPath || binding.plan.sha256 !== plan.sha256) reject(NAMES.plan);
+  if (binding.reads.length !== reads.length || reads.some((entry, index) =>
+    entry.path !== binding.reads[index].path || entry.sha256 !== binding.reads[index].sha256)) reject(NAMES.read);
+  if (binding.checkpoint !== newest.oid) reject(NAMES.checkpoint);
+  const verified = verifyCheckpoint(cwd, binding.checkpoint, context.io);
+  if (!verified.ok || !verified.clean) reject(NAMES.stale, verified.reason);
+  if (binding.head !== readHead(context, NAMES.boundHead)) reject(NAMES.boundHead);
+  if (dispatchPath !== undefined) checkDispatch(context, dispatchPath, briefPath, file.sha256);
+  return { ok: true, digest: file.sha256 };
+});
+
+const formatResult = (result) => result.ok
+  ? { code: ACCEPT, stdout: `${DIGEST_LINE} ${SHA_PREFIX}${result.digest}${NL}`, stderr: EMPTY }
+  : { code: result.code, stdout: EMPTY, stderr: `${result.reason}${NL}` };
+export const main = (argv = process.argv.slice(ARGV_OFFSET), deps = {}) => {
+  try {
+    const [verb, path, flag, dispatchPath] = argv;
+    if (!path || !(verb === STAMP || verb === CHECK) || !(argv.length === BASIC_ARGS
+      || (verb === CHECK && argv.length === DISPATCH_ARGS && flag === DISPATCH_FLAG && dispatchPath))) return formatResult(refuse(USAGE_TEXT, USAGE));
+    const cwd = deps.cwd ?? process.cwd();
+    return formatResult(verb === STAMP ? stampBrief(cwd, path, deps) : checkBrief(cwd, path, { dispatchPath }, deps));
+  } catch (error) { return formatResult(refuse(error.message)); }
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main();
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  process.exitCode = result.code;
+}