@sabaiway/agent-workflow-kit 14.6.0 → 14.8.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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.
 
+## 14.8.0 — the kit ships an epic template and a task-brief template, each accepted by its checker once filled in (AD-154)
+
+**A first epic and a first task brief can start from a file instead of from a checker's refusal.** Until 14.8.0 the
+two shapes lived only in the planning reference and in what `epic-shape-cli` and `task-brief` refuse. The kit now
+ships `references/authoring/EPIC_TEMPLATE.md` and `references/authoring/TASK_TEMPLATE.md` in its skill home. Copy one
+from there into your project, replace every `{{KEY}}` placeholder with a value its checker admits and change no
+other byte: the epic, placed at `docs/ai/epics/<EPIC_ID>.md`, passes `epic-shape-cli --check`; the brief, placed at
+`docs/plans/TASK-<stem>-T<n>.md` beside a plan that carries the same Story line and the named row, with a checkpoint
+minted, is stamped by `task-brief stamp` and passes `task-brief check`. A template copied and left unedited is
+refused: the epic by the check, the brief by the stamp.
+Story S2 of the epic `KIT-USERS-LEARN-THE-TIER-AND-WALK-IT`; contract `docs/ai/specs/kit/tier/tier-templates.md`
+(new), with `docs/ai/specs/kit/tier/tier-walk.md` at revision 2.
+
+- **Two templates, one placeholder form, a closed key list each.** The epic template carries eleven keys (`DATE`,
+  `EPIC_TITLE`, `INTENT`, `VALUE`, `NON_GOALS`, `ACCEPTANCE`, `SPECS`, `STORY_NAME`, `OWNED_PATHS`, `EPIC_ID`,
+  `QUEUE_BUCKET`) and one story row; the brief template carries thirteen keys and one task with one test file and one
+  module. Neither carries guidance prose: a template is the shape and its placeholders only. Where a grammar leaves a
+  choice, the template makes it: the epic opens `state: open` with `S1` planned, `depends-on: none` and
+  `shared: none`; the brief groups `test, impl` and reads the plan alone. For more stories, files or cases, repeat
+  the line in the form its checker takes: the next story id, and a `## Budget` line for each added file.
+- **Not deployed into a project.** The directory sits outside `references/templates/`, so neither `bootstrap` nor
+  `upgrade` copies anything from it into `docs/ai/`; `init` places it in the kit's skill home only. Nothing in the
+  kit points at the templates yet; the guide that explains each key comes with a later story of the same epic.
+- **Internals.** The repository walk fixture `test/tier-walk-e2e.test.mjs` now renders its epic and brief from the
+  installed templates, pins each template's bytes to a literal text, and checks that an unedited copy is refused; its
+  ground helpers move to `test/tier-walk-harness.test.mjs`. The package-content pin names both files, and the tarball
+  holds 333 files. Neither test file ships.
+
+## 14.7.0 — an epic closes in a project with no queue file, every task-brief refusal says what failed, and the missing-section offer is a command you can run (AD-153)
+
+**A project outside this repo can now walk one epic, one story and one task to the end, solo.** A walk through the
+three tiers on a fresh project, with no backend, stopped twice before 14.7.0: the epic close demanded a queue file the
+project never had, and a malformed task brief was refused with `shape: ` and nothing after it. The offer to insert a
+missing rules section printed `<kit>` and `<project>` placeholders, so it could not run as printed. Story S1 of the epic
+`KIT-USERS-LEARN-THE-TIER-AND-WALK-IT`; contracts `docs/ai/specs/kit/tier-walk.md` (new),
+`docs/ai/specs/kit/epic-shape/` (revision 2), `docs/ai/specs/kit/checkpoint/` (revision 5),
+`docs/ai/specs/kit/rules-regions/` (revision 3).
+
+- **`epic-shape-cli.mjs --close` accepts a project with no queue file.** When `docs/plans/queue.md` is proven absent,
+  no queue row can stand, so the close goes ahead once the other three conditions hold. Only a proven absence counts:
+  a symlink or a directory at that path, a failed read, or any other answer the read did not name refuses
+  `queue-read`, and the refusal names what the read returned, never "absent".
+- **Every `task-brief` refusal is one line, `<name>: <detail>`, and the detail is never empty.** A `shape` refusal
+  names the grammar rule that failed and where: the offending line, or the heading, section, field or path that is
+  absent, foreign or repeated. `checkpoint-stale` names the cause and the remedy: mint a fresh checkpoint, then stamp
+  the brief again. A refusal from outside the tool's own names and the three the checkpoint hands up (`stem`,
+  `sequence`, `no-checkpoint`), such as git's `fatal: not a git repository` sentence, a thrown error or a failed
+  write, prints as `environment: <the whole reason>`. `environment` is the one new name; the other names, the exit
+  codes and the digest line are unchanged. A line break inside a detail is printed escaped, so the refusal stays on
+  one line.
+- **The missing-section offer runs as printed.** When the upgrade reconcile (`tools/lens-region.mjs reconcile`) finds
+  no Communication or Story sessions section in `docs/ai/agent_rules.md`, its note now carries the real command:
+  `node`, the running kit's own `rules-insert.mjs` path, `--cwd` and your project root. A path with a space or a
+  shell-active byte is single-quoted, so the command pasted into a POSIX shell gets exactly those arguments; a plain
+  path prints unquoted. For a target that is not `docs/ai/agent_rules.md`, or a path holding a control byte or a
+  backtick, the reconcile prints the absent-section line alone, with no command. The gap entry
+  `story-sessions-section` builds its preview line with the same builder, so the two offers cannot drift apart.
+- **Internals.** `tools/rules-regions.mjs` exports `buildInsertPreview`, the one builder of the insert preview line;
+  `tools/task-brief.mjs` exports its `NAMES` map. A new repository fixture, `test/tier-walk-e2e.test.mjs`, installs
+  the kit into a throwaway home and walks one epic, one story and one task solo, from a bare project and from a
+  seeded one, every tool spawned from the installed copy. It ships in no package.
+
 ## 14.6.0 — your rules file gains a Story sessions section, and the kit can now put a missing template section there for you (AD-152)
 
 **A section you were told to add by hand is now one command.** Up to 14.5.0 a project's

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.6.0",
+  "version": "14.8.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/authoring/EPIC_TEMPLATE.md

@@ -0,0 +1,32 @@
+---
+type: epic
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 60
+state: open
+---
+
+# Epic: {{EPIC_TITLE}}
+
+## Intent
+{{INTENT}}
+
+## Value
+{{VALUE}}
+
+## Non-goals
+{{NON_GOALS}}
+
+## Acceptance
+{{ACCEPTANCE}}
+
+## Specs
+{{SPECS}}
+
+## Stories ledger
+- S1 | {{STORY_NAME}} | depends-on: none | owns: {{OWNED_PATHS}} | shared: none | state: planned
+
+## Queue
+Row {{EPIC_ID}} in {{QUEUE_BUCKET}}

package/references/authoring/TASK_TEMPLATE.md

@@ -0,0 +1,23 @@
+# Task: {{TASK_NAME}}
+Story: {{STORY_ID}} of {{EPIC_ID}}
+
+## Slice
+Plan: {{PLAN_PATH}}
+Row: {{ROW_ID}}
+Grouping: test, impl
+Files:
+- {{TEST_PATH}} :: test
+- {{MODULE_PATH}} :: impl
+
+## Reads
+- {{PLAN_PATH}}
+
+## Acceptance
+- {{ACCEPTANCE_COMMAND}} :: {{EXPECTED_OUTCOME}}
+
+## Negative cases
+- {{NEGATIVE_CASE}} :: {{NEGATIVE_OUTCOME}}
+
+## Budget
+- {{TEST_PATH}} :: {{TEST_MAX_LINES}}
+- {{MODULE_PATH}} :: {{MODULE_MAX_LINES}}

package/tools/epic-shape-ledger.mjs

@@ -9,6 +9,7 @@ const ERROR = 'error';
 const INFO = 'info';
 const OPEN = 'open';
 const LANDED = 'landed';
+const ABSENT = 'absent';
 const EPIC = 'epic';
 const OWN = 'owns';
 const FRONT_DELIMITER = '---';
@@ -122,9 +123,12 @@ const carriesToken = (title, id) => {
   const escaped = id.replace(REGEX_BYTES, '\\$&');
   return new RegExp(`(?<!${TOKEN_EDGE})${escaped}(?!${TOKEN_EDGE})`, 'u').test(title);
 };
+const describeQueue = (queue) => [queue?.outcome, queue?.reason].filter((part) => part !== undefined).join(': ')
+  || (queue === null ? 'null' : typeof queue);
 const checkQueueAbsence = (queue, path, id) => {
   if (typeof queue !== 'string') {
-    return [makeFinding(path, FIRST_LINE, 'queue-read', `${queue?.outcome ?? 'absent'}: ${queue?.reason ?? 'no readable queue text'}`)];
+    if (queue?.outcome === ABSENT) return [];
+    return [makeFinding(path, FIRST_LINE, 'queue-read', describeQueue(queue))];
   }
   try {
     const { rows } = auditQueue(queue, { label: path });

package/tools/lens-region.mjs

@@ -2,7 +2,7 @@
 // The only mutation of a deployed rules file the composition root runs WITHOUT a consent ask.
 import { isDirectRun } from './direct-run.mjs';
 import { normalizeCanonical } from './orchestration-config.mjs';
-import { RULES_REGIONS, extractRegionBy, readTemplateSpan, frontmatterMaxLines, exceedsCap } from './rules-regions.mjs';
+import { RULES_REGIONS, extractRegionBy, readTemplateSpan, frontmatterMaxLines, exceedsCap, buildInsertPreview } from './rules-regions.mjs';
 
 export { frontmatterMaxLines } from './rules-regions.mjs';
 const [COMMUNICATION, STORY, LENS] = RULES_REGIONS;
@@ -13,6 +13,7 @@ const LF = String.fromCharCode(10);
 const CR = String.fromCharCode(13);
 const CRLF = CR + LF;
 const BACKSLASH = String.fromCharCode(92);
+const BACKTICK = String.fromCharCode(96);
 const EM_DASH = String.fromCharCode(8212);
 const EXIT_OK = 0;
 const EXIT_STOP = 1;
@@ -34,12 +35,14 @@ const NEUTRAL_COMMS_RE = /^### 2[.]x[.] Communication [(]user-facing messages[)]
 const NEUTRAL_STORY_RE = /^### 2[.]x[.] Story sessions/;
 const LINE_UNSAFE = new RegExp(`[${BACKSLASH}u007f-${BACKSLASH}u009f${BACKSLASH}u2028${BACKSLASH}u2029]`, 'g');
 const HUMAN_UNSAFE = new RegExp(`[${BACKSLASH}u0000-${BACKSLASH}u001f${BACKSLASH}u007f-${BACKSLASH}u009f${BACKSLASH}u2028${BACKSLASH}u2029]+`, 'g');
-const INSERT_NOTE = '[lens-region] note: preview the absent section with `node <kit>/tools/rules-insert.mjs --cwd <project>`; use `--apply` only after an explicit yes.';
+const SERVED_TARGET = ['docs', 'ai', 'agent_rules.md'];
+const insertNote = (command) => command ? [`[lens-region] note: preview the absent section with \`${command}\`; use \`--apply\` only after an explicit yes.`] : [];
 const OUTCOME_PREFIXES = Object.freeze({ communication: 'comms', 'story-sessions': 'story', lens: 'lens' });
 const stripCr = (line) => (line.endsWith(CR) ? line.slice(0, -1) : line);
 const escUnsafe = (character) => `${BACKSLASH}u${character.codePointAt(0).toString(HEX_RADIX).padStart(UNICODE_WIDTH, '0')}`;
 const errorDetail = (raw) => `[lens-region] error=${JSON.stringify(String(raw)).replace(LINE_UNSAFE, escUnsafe)}`;
 const oneLine = (value) => String(value).replace(HUMAN_UNSAFE, ' ');
+const spanFree = (value) => oneLine(value).replaceAll(BACKTICK, escUnsafe(BACKTICK));
 
 export const parseLensPriors = (text) => {
   const entries = [];
@@ -104,9 +107,9 @@ const RECONCILERS = Object.freeze({ communication: reconcileCommsText, 'story-se
 export const OUTCOME_LINES = Object.freeze({
   errorDetail,
   targetAbsent: (target) => `[lens-region] ${oneLine(target)} is absent ${EM_DASH} skipped (nothing to update; the file is seeded at bootstrap).`,
-  commsNoRegion: (target) => [
-    `[lens-region] no "${COMMUNICATION.label}" section in ${oneLine(target)} ${EM_DASH} left untouched.`,
-    INSERT_NOTE,
+  commsNoRegion: (target, command) => [
+    `[lens-region] no "${COMMUNICATION.label}" section in ${spanFree(target)} ${EM_DASH} left untouched.`,
+    ...insertNote(command),
   ],
   commsCurrent: () => `[lens-region] Communication section already current ${EM_DASH} nothing to do (zero-diff).`,
   commsCustom: () => [
@@ -117,9 +120,9 @@ export const OUTCOME_LINES = Object.freeze({
   commsCapRefused: (target, count, cap) => `[lens-region] refused ${EM_DASH} refreshing the Communication section would push ${oneLine(target)} to ${count} lines (cap ${cap}); trim the file and re-run. The Communication section was not changed.`,
   commsRefreshed: () => '[lens-region] refreshed the Communication section to the current canon.',
   templateCanonStop: () => `[lens-region] STOP ${EM_DASH} the kit's bundled agent_rules.md template canon is unreadable; reinstall the kit: npx @sabaiway/agent-workflow-kit@latest init`,
-  storyNoRegion: (target) => [
-    `[lens-region] no "${STORY.label}" section in ${oneLine(target)} ${EM_DASH} left untouched.`,
-    INSERT_NOTE,
+  storyNoRegion: (target, command) => [
+    `[lens-region] no "${STORY.label}" section in ${spanFree(target)} ${EM_DASH} left untouched.`,
+    ...insertNote(command),
   ],
   storyCurrent: () => `[lens-region] Story sessions section already current ${EM_DASH} nothing to do (zero-diff).`,
   storyCustom: () => [
@@ -187,9 +190,11 @@ export const runCli = async (argv, deps = {}) => {
     return EXIT_USAGE;
   }
   const fs = deps.fs ?? (await import('node:fs/promises'));
-  const { dirname, basename, join, resolve } = await import('node:path');
+  const { dirname, basename, join, resolve, sep } = await import('node:path');
   const { fileURLToPath } = await import('node:url');
   const targetPath = resolve(argv[1]);
+  const served = targetPath.endsWith(sep + SERVED_TARGET.join(sep));
+  const command = served ? buildInsertPreview(resolve(targetPath, '..', '..', '..')) : '';
   const text = await (async () => {
     try {
       return await fs.readFile(targetPath, UTF8);
@@ -238,7 +243,7 @@ export const runCli = async (argv, deps = {}) => {
       return state;
     }
     if (!region.found) {
-      for (const line of OUTCOME_LINES[`${prefix}NoRegion`](argv[1])) log(line);
+      for (const line of OUTCOME_LINES[`${prefix}NoRegion`](argv[1], command)) log(line);
       return state;
     }
     const canon = descriptor.canon === 'template'

package/tools/profile-gaps.mjs

@@ -7,6 +7,7 @@ import {
   planInsert,
   frontmatterMaxLines,
   decodeUtf8Strict,
+  buildInsertPreview,
 } from './rules-regions.mjs';
 
 const GAP_ID = 'story-sessions-section';
@@ -17,9 +18,6 @@ const MISSING_FILE_CODE = 'ENOENT';
 const SINGLE_HEADING = 1;
 const TARGET_PATH = 'docs/ai/agent_rules.md';
 const TEMPLATE_PATH = fileURLToPath(new URL('../references/templates/agent_rules.md', import.meta.url));
-const INSERT_PATH = fileURLToPath(new URL('./rules-insert.mjs', import.meta.url));
-const COMMAND_PREFIX = 'node ';
-const CWD_FLAG = ' --cwd ';
 const VERDICTS = Object.freeze({
   present: 'present',
   absent: 'absent',
@@ -83,8 +81,6 @@ const detectStorySessions = ({ root, deps }) => {
   return { verdict: VERDICTS.absent };
 };
 
-const buildInsertPreview = (root) => COMMAND_PREFIX + INSERT_PATH + CWD_FLAG + root;
-
 export const PROFILE_GAPS = Object.freeze([
-  Object.freeze({ id: GAP_ID, detect: detectStorySessions, apply: buildInsertPreview }),
+  Object.freeze({ id: GAP_ID, detect: detectStorySessions, apply: (root) => buildInsertPreview(root) }),
 ]);

package/tools/rules-regions.mjs

@@ -1,3 +1,5 @@
+import { fileURLToPath } from 'node:url';
+
 const LF = String.fromCharCode(10);
 const CR = String.fromCharCode(13);
 const CRLF = CR + LF;
@@ -18,6 +20,11 @@ const UTF8_LABEL = 'utf-8';
 const UTF8_ENCODING = 'utf8';
 const ROUND_TRIP_MESSAGE = 'the bytes read do not survive a UTF-8 round trip';
 const BOM_CHAR = String.fromCharCode(65279);
+const INSERT_PATH = fileURLToPath(new URL('./rules-insert.mjs', import.meta.url));
+const COMMAND_UNSAFE_RE = /[\u0000-\u001f\u007f`]/;
+const SHELL_PLAIN_RE = /^[A-Za-z0-9_./-]+$/;
+const SINGLE_QUOTE = "'";
+const QUOTE_ESCAPE = "'\\''";
 
 // Append the OUTGOING canon here in the same release that changes the template
 // §2.5 region — the fragment-or-prior reconcile depends on it.
@@ -165,3 +172,12 @@ export const planInsert = ({ text, spans, cap }) => {
   if (decision.over) return { refusal: CAP_REFUSAL, count: decision.count, cap };
   return { planned, text: resultText };
 };
+
+const shellWord = (path) => SHELL_PLAIN_RE.test(path)
+  ? path
+  : SINGLE_QUOTE + path.split(SINGLE_QUOTE).join(QUOTE_ESCAPE) + SINGLE_QUOTE;
+
+export const buildInsertPreview = (root, insertPath = INSERT_PATH) => {
+  if ([root, insertPath].some((path) => COMMAND_UNSAFE_RE.test(path))) return '';
+  return 'node ' + shellWord(insertPath) + ' --cwd ' + shellWord(root);
+};

package/tools/task-brief.mjs

@@ -68,20 +68,38 @@ 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',
+export 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' };
+  head: 'head', boundHead: 'binding-head', dispatch: 'dispatch-inputs', environment: 'environment' };
+const HANDED_UP = ['stem', 'sequence', 'no-checkpoint'];
+const MEMBERS = new Set([...Object.values(NAMES), ...HANDED_UP]);
+const NAME_SEPARATOR = ': ';
+const LINE_BREAKS = /[\r\n]/g;
+const ESCAPED_BREAKS = { '\r': '\\r', '\n': '\\n' };
+const SLICE_NAMES = ['Plan', 'Row', 'Grouping', 'Files:'];
+const STALE_REMEDY = 'mint a fresh checkpoint, then stamp the brief again';
 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 reject = (name, detail) => { throw new Error(`${name}${NAME_SEPARATOR}${detail}`); };
 const computeDigest = (bytes) => createHash(HASH).update(bytes).digest(HEX);
-const matchLine = (pattern, line) => {
+const matchLine = (pattern, line, rule) => {
   const match = pattern.exec(line ?? EMPTY);
-  if (match === null) reject(NAMES.shape, line);
+  if (match === null) reject(NAMES.shape, line === undefined ? `${rule} is absent` : `${rule}: ${line}`);
   return match.slice(ONE);
 };
+const checkMembers = (found, expected, label) => {
+  const faults = [[found.find((item) => !expected.includes(item)), 'is foreign'],
+    [found.find((item, index) => found.indexOf(item) !== index), 'is repeated'], [expected.find((item) => !found.includes(item)), 'is absent']];
+  const [item, fault] = faults.find(([candidate]) => candidate !== undefined) ?? [];
+  if (item !== undefined) reject(NAMES.shape, `${label} ${item} ${fault}`);
+};
+const checkSliceField = (pattern, line, index) => {
+  const name = SLICE_NAMES[index];
+  if (line === undefined || !line.startsWith(name)) reject(NAMES.shape, `## Slice field ${name} is absent before: ${line ?? 'the section end'}`);
+  return matchLine(pattern, line, `## Slice field ${name} is malformed`);
+};
 const splitBindingBlocks = (text) => {
   const raw = text.split(NL);
   const lines = raw.map((line) => line.replace(CR_END, EMPTY));
@@ -105,32 +123,37 @@ const splitBindingBlocks = (text) => {
 };
 export const parseBrief = (text) => {
   try {
-    if (typeof text !== STRING) return refuse(NAMES.shape);
+    if (typeof text !== STRING) return refuse(`${NAMES.shape}${NAME_SEPARATOR}the brief is not text`);
     const document = splitBindingBlocks(text);
     const lines = document.lines;
-    const [title] = matchLine(TITLE_RE, lines[START]);
+    const [title] = matchLine(TITLE_RE, lines[START], 'the title is not "# Task: <name>"');
     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 storyLines = lines.slice(ONE, headings[ONE]?.index ?? lines.length);
+    const stray = storyLines.find((line) => !line.startsWith(STORY_PREFIX));
+    if (stray !== undefined) reject(NAMES.shape, `a line before ## Slice is not a Story line: ${stray}`);
+    const found = headings.slice(ONE).map(({ text }) => text);
+    checkMembers(found, HEADINGS, 'heading');
+    if (HEADINGS.some((text, index) => found[index] !== text)) reject(NAMES.shape, `headings out of order: ${found.join(', ')}`);
     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 [[planPath], [rowId], [grouping]] = SLICE_FIELDS.map((pattern, index) => checkSliceField(pattern, slice[index], index));
     const files = slice.slice(SLICE_FIELDS.length).map((line) => {
-      const [path, tag] = matchLine(PAIR_RE, line);
+      const [path, tag] = matchLine(PAIR_RE, line, 'a Files: line is not "- <path> :: <tag>"');
       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);
+      const [path, count] = matchLine(PAIR_RE, line, 'a ## Budget line is not "- <path> :: <lines>"');
+      if (!INTEGER_RE.test(count) || !Number.isSafeInteger(Number(count))) reject(NAMES.shape, `a ## Budget count is not a positive integer: ${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);
+    if (files.length === START) reject(NAMES.shape, 'Files: lists no path');
+    checkMembers(budgets.map(({ path }) => path), [...new Set(files.map(({ path }) => path))], '## Budget path');
+    if (acceptance.length === START) reject(NAMES.shape, '## Acceptance lists no line');
+    if (negative.length === START) reject(NAMES.shape, '## Negative cases lists no line');
     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]),
+      reads: reads.map((line) => matchLine(BULLET_RE, line, 'a ## Reads line is not a bullet')[START]),
+      acceptance: acceptance.map((line) => matchLine(PAIR_RE, line, 'an ## Acceptance line is not "- <command> :: <outcome>"')),
+      negative: negative.map((line) => matchLine(BULLET_RE, line, 'a ## Negative cases line is not a bullet')[START]),
       blocks: document.blocks, unclosed: document.unclosed, body: document.body };
   } catch (error) { return refuse(error.message); }
 };
@@ -149,12 +172,14 @@ const readInside = (context, path, name = NAMES.reads) => {
   } 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 foreign = brief.files.find(({ tag }) => !TAGS.includes(tag));
+  if (foreign !== undefined) reject(NAMES.grouping, `${foreign.path} carries the tag ${foreign.tag}, not test, impl or pin`);
+  const expected = TAGS.filter((tag) => brief.files.some((file) => file.tag === tag)).join(GROUP_SEPARATOR);
+  if (brief.grouping !== expected) reject(NAMES.grouping, `Grouping: ${brief.grouping} differs from the Files tags ${expected}`);
   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);
+    if (pins.length !== ONE || pins[START].path !== row.path) reject(NAMES.grouping, `a pin row tags only its own path ${row.path} pin`);
+  } else if (pins.length !== START) reject(NAMES.grouping, `the pin tag belongs to a ${PIN_FILE} row only`);
 };
 const checkRow = (context, brief, row) => {
   if (!row?.valid) reject(NAMES.row, brief.rowId);
@@ -190,38 +215,45 @@ const readGrammar = (context, briefPath) => {
   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);
+  if (story === null) reject(NAMES.story, `${brief.planPath} carries no single Story line`);
+  if (selectStory(brief.storyLines) !== story) reject(NAMES.story, `the brief's Story line differs from the plan's ${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);
+  if (brief.unclosed) reject(NAMES.binding, `the ${BRIEF_BINDING_INFO_STRING} block never closes`);
+  if (brief.blocks.length > ONE) reject(NAMES.binding, `more than one ${BRIEF_BINDING_INFO_STRING} block`);
+  if (required && brief.blocks.length !== ONE) reject(NAMES.binding, `no ${BRIEF_BINDING_INFO_STRING} block: stamp the brief first`);
 };
 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);
+  let value;
   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;
+    value = JSON.parse(brief.blocks[START].source);
   } catch (error) { reject(NAMES.binding, error.message); }
+  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, `the block is not a schema ${SCHEMA} binding`);
+  return value;
 };
 const readHead = (context, name) => {
+  let oid;
   try {
-    const oid = readGit(context, HEAD_ARGS);
-    if (!OID_RE.test(oid)) reject(name);
-    return oid;
+    oid = readGit(context, HEAD_ARGS);
   } catch (error) { reject(name, error.message); }
+  if (!OID_RE.test(oid)) reject(name, `HEAD resolves to ${oid}, not an object id`);
+  return oid;
 };
+const stale = (cause) => reject(NAMES.stale, `${cause}; ${STALE_REMEDY}`);
 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);
+  if (!parsed.ok) reject(NAMES.dispatch, `${dispatchPath}: ${parsed.reason}`);
+  const inputs = parsed.contract.inputs;
+  if (typeof inputs !== STRING || !inputs.includes(briefPath) || !inputs.includes(`${SHA_PREFIX}${digest}`)) reject(NAMES.dispatch, `${dispatchPath} inputs do not name ${briefPath} at ${SHA_PREFIX}${digest}`);
 };
 
 export const stampBrief = (cwd, briefPath, io = {}) => withRepository(cwd, io, (context) => {
@@ -246,31 +278,40 @@ export const checkBrief = (cwd, briefPath, { dispatchPath } = {}, io = {}) => wi
   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);
+  if (binding.plan.path !== brief.planPath || binding.plan.sha256 !== plan.sha256) reject(NAMES.plan, `${brief.planPath} changed since the stamp`);
+  if (binding.reads.length !== reads.length) reject(NAMES.read, `## Reads lists ${reads.length} files, the stamp bound ${binding.reads.length}`);
+  const moved = reads.find((entry, index) => entry.path !== binding.reads[index].path || entry.sha256 !== binding.reads[index].sha256);
+  if (moved !== undefined) reject(NAMES.read, `${moved.path} changed since the stamp`);
+  if (binding.checkpoint !== newest.oid) reject(NAMES.checkpoint, `the stamp bound checkpoint ${binding.checkpoint}, the newest is ${newest.oid}`);
   const verified = verifyCheckpoint(cwd, binding.checkpoint, context.io);
-  if (!verified.ok) reject(NAMES.stale, verified.reason);
+  if (!verified.ok) return verified;
   if (!verified.clean) {
     const changed = runBaseDiff(context.top, { kind: CHECKPOINT_KIND, treeOid: binding.checkpoint }, CHANGED_PATH_ARGS, context.io);
-    if (changed === null) reject(NAMES.stale, verified.reason);
+    if (changed === null) stale(`the tree differs from checkpoint ${binding.checkpoint}`);
     const paths = changed.toString(UTF8).split(NUL).filter(Boolean);
     const ledger = readDelegationLedger(context.cwd, context.env);
-    if (ledger.state === READ_ERROR) reject(NAMES.stale, ledger.reason);
+    if (ledger.state === READ_ERROR) stale(ledger.reason);
     const claimed = new Set(ledger.state === READ_OK
       ? claimedPaths(ledger.records, binding.checkpoint, ledger.head, isThreadTerminalRecord) : []);
     const ownFiles = new Set(brief.files.map(({ path }) => path));
-    if (!paths.every((path) => claimed.has(path) && !ownFiles.has(path))) reject(NAMES.stale, verified.reason);
+    const unclaimed = paths.filter((path) => !claimed.has(path) || ownFiles.has(path));
+    if (unclaimed.length > START) stale(`${unclaimed.join(', ')} changed since checkpoint ${binding.checkpoint}`);
   }
-  if (binding.head !== readHead(context, NAMES.boundHead)) reject(NAMES.boundHead);
+  const head = readHead(context, NAMES.boundHead);
+  if (binding.head !== head) reject(NAMES.boundHead, `the stamp bound HEAD ${binding.head}, HEAD is now ${head}`);
   if (dispatchPath !== undefined) checkDispatch(context, dispatchPath, briefPath, file.sha256);
   return { ok: true, digest: file.sha256 };
 });
 
+const nameReason = (reason) => {
+  const text = String(reason).replace(LINE_BREAKS, (byte) => ESCAPED_BREAKS[byte]);
+  const cut = text.indexOf(NAME_SEPARATOR);
+  const named = cut > START && MEMBERS.has(text.slice(START, cut)) && text.slice(cut + NAME_SEPARATOR.length).trim() !== EMPTY;
+  return named ? text : `${NAMES.environment}${NAME_SEPARATOR}${text}`;
+};
 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}` };
+  : { code: result.code, stdout: EMPTY, stderr: `${result.code === REFUSE ? nameReason(result.reason) : result.reason}${NL}` };
 export const main = (argv = process.argv.slice(ARGV_OFFSET), deps = {}) => {
   try {
     const [verb, path, flag, dispatchPath] = argv;