@sabaiway/agent-workflow-kit 13.1.0 → 13.3.0

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/ensure-configs.mjs

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-// ensure-configs.mjs — ONE runnable command for the six stamp-independent upgrade ensures:
+// ensure-configs.mjs — ONE runnable command for the seven stamp-independent upgrade ensures:
 //
 //   orchestration  docs/ai/orchestration.json  seed, or refresh a still-canonical onboarding note
 //   gates          docs/ai/gates.json          seed-if-missing (an existing declaration is authored content)
 //   autonomy       docs/ai/autonomy.json       seed-if-missing (same)
+//   vehicles       docs/ai/vehicles.json       seed-if-missing (same)
 //   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
 //   specs          scripts/<spec layer>        reader + checker pairs seeded when absent, refreshed only on
 //                  + docs/ai/specs/index.md    a shipped prior body, store root seeded behind a current checker
 //   index          docs/ai/index.md            regenerate-if-missing-or-stale (a GENERATED artifact)
 //
 // Each was prose in references/modes/upgrade.md that an agent performed by hand. One command instead
-// of six is deliberate: six independent runs would be six chances to skip one, and the mode doc now
-// has a single invocation point whose six outcome lines it relays.
+// of seven is deliberate: seven independent runs would be seven chances to skip one, and the mode doc now
+// has a single invocation point whose seven outcome lines it relays.
 //
 // The contract (pinned by this module's tests):
 //   • --reconcile is REQUIRED. A bare run is a usage error, so nothing writes by accident.
@@ -19,7 +20,7 @@
 //   • The ops run in a FIXED order and one op's failure NEVER skips the rest: every op reports its own
 //     token, and the exit is non-zero when any of them failed.
 //   • The deployment gate runs ONCE, before any op: an absent/symlinked docs/ai stops the whole run
-//     with the gate's own message rather than six copies of it.
+//     with the gate's own message rather than seven copies of it.
 //
 // Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
 // Exit codes: 0 every op fine · 1 an op failed, or the deployment gate stopped the run · 2 usage.
@@ -51,12 +52,12 @@ const EMPTY_ONLY = `--only needs one operation name (${ENSURE_OPS.join(' | ')})
 const REPEATED_ONLY = '--only was passed more than once — this selector names exactly ONE operation';
 const unknownOp = (value) => `--only ${value}: no such operation (${ENSURE_OPS.join(' | ')}) — nothing was run`;
 
-const HELP = `ensure-configs — the six stamp-independent upgrade ensures, as ONE command.
+const HELP = `ensure-configs — the seven stamp-independent upgrade ensures, as ONE command.
 
 Usage:
   node ensure-configs.mjs --reconcile [--dry-run] [--only <op>] [--cwd <project>]
 
-  --reconcile   required — run the six ensures (${ENSURE_OPS.join(', ')})
+  --reconcile   required — run the seven ensures (${ENSURE_OPS.join(', ')})
   --dry-run     report what each ensure WOULD do; write nothing
   --only <op>   run EXACTLY ONE of them (an unknown, missing or repeated value is a usage error)
   --cwd <dir>   the target project (default: the current directory)
@@ -148,7 +149,7 @@ export const main = (argv = [], ctx = {}) => {
     const cwd = resolve(args.cwd ?? ctx.cwd ?? process.cwd());
     const deps = ctx.deps ?? {};
     // ONE deployment gate for the whole run (see the header): with no docs/ai there is nothing to
-    // reconcile, and six identical STOPs would read as six separate problems.
+    // reconcile, and seven identical STOPs would read as seven separate problems.
     assertDocsAiDeployment(cwd, deps, { noun: 'the project configuration', rel: 'under docs/ai' });
     const outcomes = runEnsures({ cwd, kitRoot: ctx.kitRoot ?? KIT_ROOT, dryRun: args.dryRun, deps, only: args.only });
     return {

package/tools/ensure-ops.mjs

@@ -1,5 +1,5 @@
-// ensure-ops.mjs — FIVE of the upgrade ensure operations, one function each, behind one shared
-// outcome shape; the sixth (the spec-layer ensure, ensure-specs.mjs) composes its outcomes through
+// ensure-ops.mjs — the upgrade ensure operations this module owns, one function each, behind one shared
+// outcome shape; the spec-layer ensure (ensure-specs.mjs) composes its outcomes through
 // the same door and probes exported below. The CLI that orders and runs them is ensure-configs.mjs —
 // it owns the op table, so the import graph stays acyclic; this module owns what each ensure DOES
 // and, more importantly, what it is allowed to CLAIM.
@@ -32,6 +32,7 @@ import { seedConfig, writeConfig } from './orchestration-write.mjs';
 import { lstatNoFollow, writeDocsAiFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
 import { GATES_REL } from './gates-declaration.mjs';
 import { AUTONOMY_REL } from './autonomy-config.mjs';
+import { VEHICLES_REL } from './vehicle-settings.mjs';
 import { surveyAdrLayoutStrict } from './family-registry.mjs';
 import { ENSURE_TOKENS, FAILURE_CAUSES, SEED_SCRIPTS } from './ensure-vocabulary.mjs';
 import { NODE_EVIDENCE, describeNodeProbes, probeNodeEvidence } from './node-evidence.mjs';
@@ -51,6 +52,9 @@ export {
 } from './ensure-vocabulary.mjs';
 
 const SCRIPTS_DIR = 'scripts';
+const VEHICLES_OP = 'vehicles';
+const VEHICLES_TEMPLATE = 'vehicles.json';
+const VEHICLES_NOUN = 'a vehicle settings declaration';
 
 const outcome = (op, token, lines, failed = false) => {
   if (!ENSURE_TOKENS.includes(token)) {
@@ -98,7 +102,7 @@ export const probeSeedTarget = (abs, lstat) => {
 export const tmpNote = (rel, tmpLeftBehind) =>
   (tmpLeftBehind ? [`${rel}: the write stands, but its temp file could not be removed — delete it by hand: ${tmpLeftBehind}`] : []);
 
-// ── 1. orchestration.json — seed, or refresh ONLY a still-canonical onboarding note ────────────────
+// ── orchestration.json — seed, or refresh ONLY a still-canonical onboarding note ────────────────
 
 // Which no-change outcome is it? refreshReadme returns `changed: false` for two very different trees:
 // a note that already IS the current canonical, and a note the user rewrote. Reporting both as
@@ -173,7 +177,7 @@ export const ensureOrchestration = ({ cwd, dryRun = false, deps = {} }) => {
   return { ...refreshed, lines: [...refreshed.lines, ...seedNote] };
 };
 
-// ── 2/3. gates.json + autonomy.json — seed-if-missing, existing file preserved byte-for-byte ───────
+// ── gates.json + autonomy.json + vehicles.json — seed-if-missing, existing file preserved byte-for-byte ───────
 
 const seedFromTemplate = ({ op, rel, template, noun, cwd, kitRoot, dryRun, deps }) => {
   const lstat = deps.lstat ?? lstatSync;
@@ -202,7 +206,10 @@ export const ensureGates = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
 export const ensureAutonomy = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
   seedFromTemplate({ op: 'autonomy', rel: AUTONOMY_REL, template: 'autonomy.json', noun: 'an autonomy policy', cwd, kitRoot, dryRun, deps });
 
-// ── 4. scripts/ — the ADR-cascade enforcement pairs, detect-first ──────────────────────────────────
+export const ensureVehicles = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
+  seedFromTemplate({ op: VEHICLES_OP, rel: VEHICLES_REL, template: VEHICLES_TEMPLATE, noun: VEHICLES_NOUN, cwd, kitRoot, dryRun, deps });
+
+// ── scripts/ — the ADR-cascade enforcement pairs, detect-first ──────────────────────────────────
 
 // The Node-evidence refusal every ensure that places Node scripts shares (contract: kit/node-evidence):
 // null when Node provably runs here, else the ONE outcome the caller returns — a stated skip naming the
@@ -288,7 +295,7 @@ export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   return outcome('scripts', anyCreated ? 'seeded' : 'already-present', lines, false);
 };
 
-// ── 5. docs/ai/index.md — the GENERATED navigator, regenerated when missing or stale ───────────────
+// ── docs/ai/index.md — the GENERATED navigator, regenerated when missing or stale ───────────────
 
 // The only ensure whose target is generated rather than authored: there is nothing to preserve, and
 // nothing to seed from either — the bundled generator IS the writer, driven through its idempotent
@@ -363,12 +370,13 @@ export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   return loud('index', 'index-probe-failed', `${INDEX_REL}: the generator reported a regeneration, but the verifying probe answered neither fresh nor stale — ${MAY_HAVE_WRITTEN}. ${verify.error ? causeOf(verify.error) : verdict}`);
 };
 
-// The five ops this module owns, by name. The CLI composes the full ENSURE_OPS table from these plus
+// The ops this module owns, by name. The CLI composes the full ENSURE_OPS table from these plus
 // the spec-layer ensure (ensure-specs.mjs imports THIS module, so the table cannot live here).
 export const OWN_IMPLEMENTATIONS = Object.freeze({
   orchestration: ensureOrchestration,
   gates: ensureGates,
   autonomy: ensureAutonomy,
+  vehicles: ensureVehicles,
   scripts: ensureScripts,
   index: ensureIndex,
 });

package/tools/ensure-vocabulary.mjs

@@ -10,7 +10,7 @@
 // The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
 // `specs` sits after `scripts` (its reader pair is a scripts/ seed too) and BEFORE `index`: the store
 // root it seeds is a docs/ai file the navigator must count.
-export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts', 'specs', 'index']);
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'vehicles', 'scripts', 'specs', 'index']);
 
 // Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
 // walks this set), and each has exactly one `would-` counterpart below. `refreshed` is the spec-layer

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;
+}