@sabaiway/agent-workflow-kit 14.21.0 → 14.22.0

package/tools/tier-guide-facts.mjs

@@ -7,12 +7,10 @@ import { EPICS_REL, readEpicStore } from './epic-store.mjs';
 import { checkEpic } from './epic-shape.mjs';
 import { QUEUE_PATH, checkClaims, judgeClose, sweepSiblings } from './epic-shape-ledger.mjs';
 import { PLANS_REL, isScratchPlanName, plansInFlight, readPlanEntries } from './plan-files.mjs';
-import { PIN_FILE, readStoryLine } from './plan-shape-ownership.mjs';
-import { PLAN_HEADINGS, checkPlan, isSweep, parseLedger } from './plan-shape.mjs';
-import { buildFacts, openRepo } from './plan-shape-facts.mjs';
-import { newestCheckpoint } from './checkpoint.mjs';
+import { readStoryLine } from './plan-shape-ownership.mjs';
+import { PLAN_HEADINGS, isSweep, parseLedger } from './plan-shape.mjs';
+import { expandSweepPaths } from './plan-shape-facts.mjs';
 import { withRepository } from './checkpoint-core.mjs';
-import { parseBrief } from './task-brief.mjs';
 import { escapeForDisplay, isRenderableLine, shellQuoteArg } from './repo-lex.mjs';
 
 const WORK_TREE = 'work-tree';
@@ -25,21 +23,22 @@ const FRONT = '---';
 const CR_END = /\r$/;
 const SPAN = /\{\{([\s\S]*?)\}\}/g;
 const PLAN_STEM = /^[A-Za-z0-9_-]+$/;
-// The brief grammar's Plan field, matched one line at a time as task-brief matches it.
-const PLAN_FIELD = /^Plan: (docs\/plans\/[^/]+\.md)$/;
-const TASK_PREFIX = 'TASK-';
-const TASK_NUMBER = /-T([1-9][0-9]*)\.md$/;
+const PLAN_TITLE = /^# Plan: (.+)$/;
+const DOCS_AI = 'docs/ai/';
+const PROMPT_PREFIX = `${PLANS_REL}/EXECUTE-PROMPT-`;
 const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
-const NO_CHECKPOINT = 'no-checkpoint';
 const HEADER_CODES = new Set(['sibling-header', 'sibling-read']);
 const HEAD_ARGS = ['rev-parse', '-q', '--verify', 'HEAD^{commit}'];
+const INDEX_ARGS = ['diff-index', '--cached', '--quiet', 'HEAD', '--'];
+const INDEX_EQUAL = 0;
+const INDEX_DIFFERS = 1;
 const STAND_IN_EPIC = 'NEW-EPIC';
 const E1_CAUSE = `no epic file in ${EPICS_REL}`;
 const EPIC_TEMPLATE = '../references/authoring/EPIC_TEMPLATE.md';
 const TASK_TEMPLATE = '../references/authoring/TASK_TEMPLATE.md';
-const TEMPLATE_VERBS = new Set(['create', 'modify']);
 const READERS = Object.freeze({ store: 'readEpicStore', sweep: 'sweepSiblings', entries: 'readPlanEntries',
-  plans: 'plansInFlight', plan: 'checkPlan', brief: 'parseBrief', sequence: 'newestCheckpoint', head: 'readGit' });
+  plans: 'plansInFlight', ledger: 'parseLedger', story: 'readStoryLine', prompt: 'readRegularFileNoFollow',
+  head: 'readGit', index: 'diff-index' });
 
 const q = shellQuoteArg;
 const action = (kind, text, command = null) => ({ kind, text: escapeForDisplay(text), command });
@@ -53,13 +52,14 @@ const makeTools = (toolsDir) => {
     epicCheck: (path, kind = 'run') => node(kind, `check the epic ${path}`, 'epic-shape-cli.mjs', '--check', q(path)),
     review: (path) => node('run', `read the review brief of the epic ${path}; the solo review is the reading of it`, 'epic-shape-cli.mjs', '--review-brief', q(path)),
     close: (path) => node('run', `close the epic ${path}`, 'epic-shape-cli.mjs', '--close', q(path)),
-    planCheck: (plan) => node('run', `check the plan ${plan}`, 'plan-shape-cli.mjs', '--check', q(plan)),
+    planCheck: (plan, text = `check the plan ${plan}`) => node('run', text, 'plan-shape-cli.mjs', '--check', q(plan)),
     planVerify: (plan) => node('run', `verify the plan ${plan} against the tree`, 'plan-shape-cli.mjs', '--verify', q(plan)),
-    mint: (plan) => node('run', `mint a checkpoint of the plan ${plan}`, 'checkpoint.mjs', 'mint', '--plan', q(plan)),
-    prune: (plan) => node('run', `prune the checkpoints of the plan ${plan}`, 'checkpoint.mjs', 'prune', '--plan', q(plan)),
-    stamp: (brief) => node('run', `stamp the brief ${brief}`, 'task-brief.mjs', 'stamp', q(brief)),
-    check: (brief) => node('run', `check the brief ${brief}`, 'task-brief.mjs', 'check', q(brief)),
-    reviewState: () => node('run', 'check the review state of the tree', 'review-state.mjs', '--check'),
+    reviewState: () => node('run', 'check the review state of the tree: the commit gate', 'review-state.mjs', '--check'),
+    diff: () => lineOf('run', 'read the staged diff: the diff review reads it, in the solo walk you read it yourself', ['git', 'diff', '--cached']),
+    commit: (plan) => lineOf('run', `commit every staged change once, titled as the plan ${plan.path}`, ['git', 'commit', '-m', q(plan.title)]),
+    stage: (row, expansion) => (isSweep(row.path)
+      ? action('write', `stage every path the sweep row ${row.id} (${row.path}) expands to: ${expansion()}`)
+      : lineOf('run', `stage the path of the row ${row.id}`, ['git', '--literal-pathspecs', 'add', '--', q(row.path)])),
     copy: (template, target, text) => lineOf('write', text, ['cp', q(resolve(toolsDir, template)), q(target)]),
   };
 };
@@ -67,7 +67,8 @@ const state = (reader, file, cause, next = null) => ({ reader, file, cause: esca
 const findSpans = (file, text) => [...text.matchAll(SPAN)].map(([, span]) => ({ file, span: escapeForDisplay(span) }));
 const readText = (cwd, path) => {
   const result = readRegularFileNoFollow(resolve(cwd, path));
-  return result.outcome === 'ok' ? { text: result.content } : { cause: `${result.outcome}: ${result.code ?? result.className ?? 'unreadable'}` };
+  return result.outcome === 'ok' ? { text: result.content }
+    : { absent: result.outcome === 'absent', cause: `${result.outcome}: ${result.code ?? result.className ?? 'unreadable'}` };
 };
 const isPresent = (cwd, path) => lstatSync(resolve(cwd, path), { throwIfNoEntry: false }) !== undefined;
 // The lines of a file as the kit's readers see them: a CRLF file reads as its LF twin.
@@ -80,13 +81,17 @@ const declaresEpic = (text) => {
 };
 const stripPath = (finding) => (finding.message.startsWith(`${finding.path}: `) ? finding.message.slice(finding.path.length + 2) : finding.message);
 
-const readHead = (cwd, env) => withRepository(cwd, { env }, (context) => {
-  const result = context.run(HEAD_ARGS, context.top, undefined, context.env);
-  const stdout = String(result.stdout ?? '').trim();
-  if (result.status === 0 && OID.test(stdout)) return { ok: true, oid: stdout };
-  if (result.status === 1 && stdout === '' && !result.error) return { ok: true, oid: null };
-  return { ok: false, reason: String(result.stderr ?? result.error?.message ?? 'HEAD could not be read').trim() };
+const askGit = (cwd, env, args) => withRepository(cwd, { env }, (context) => {
+  const result = context.run(args, context.top, undefined, context.env);
+  return { status: result.error ? null : result.status, stdout: String(result.stdout ?? '').trim(),
+    reason: String(result.stderr ?? '').trim() || (result.error?.message ?? `git ${args[0]} exited ${result.status}`) };
 });
+const readHead = (cwd, env) => {
+  const answer = askGit(cwd, env, HEAD_ARGS);
+  if (answer.status === 0 && OID.test(answer.stdout)) return { ok: true, oid: answer.stdout };
+  if (answer.status === 1 && answer.stdout === '') return { ok: true, oid: null };
+  return { ok: false, reason: answer.reason };
+};
 
 const readStore = (cwd) => {
   const store = readEpicStore(cwd);
@@ -104,73 +109,55 @@ const readStore = (cwd) => {
     states: [...states, ...siblingStates.map((finding) => ({ finding }))] };
 };
 
-const judgeEpic = (entries, entry) => {
-  const path = `${EPICS_REL}/${entry.name}`;
-  const others = entries.filter((other) => other.name !== entry.name);
-  const shape = checkEpic(entry.text, path);
-  const sweep = sweepSiblings(others, EPICS_REL);
-  const claims = shape.findings.length === 0 && sweep.ok ? checkClaims([shape.epic, ...sweep.epics]) : { findings: [] };
-  const findings = [...shape.findings, ...sweep.findings, ...claims.findings];
-  return { path, others, epic: shape.epic, accepted: !findings.some((finding) => finding.severity !== INFO) };
-};
-
-const planOf = (text) => linesOf(text).map((line) => PLAN_FIELD.exec(line)?.[1]).find(Boolean) ?? null;
 const planShape = (row, epicId) => `The shape: the title # Plan: and a name; the five headings; under Goal and boundary the line Story: ${row.id} of ${epicId} and a governing spec path under docs/ai/specs or the words not adopted; one ledger row per file in six fields (id, verb, path, responsibility, budget, anchor) — a create or modify row an anchor that resolves to one place and, with no declared source-size cap, the budget n/a, a delete row a dash (—) in budget and anchor; the total line last, its before figure the current lines of every deleted file and of every modify row with a numeric budget, so total: 0 → 0 lines when every row is a create or modify with the budget n/a; at least one - bullet under Verification.`;
 
 // The Story line is read under Goal and boundary alone, as plan-shape reads it.
-const storyOf = (text) => {
-  const { document } = parseLedger(text);
+const storyOf = ({ document }) => {
   const goal = document.headings.find((heading) => heading.text === PLAN_HEADINGS[0]);
   const end = goal && document.headings.find((heading) => heading.index > goal.index && heading.level <= 2);
   const lines = goal ? document.lines.slice(goal.index + 1, end?.index).map((line, offset) => ({ text: line, line: goal.index + 2 + offset })) : [];
   return readStoryLine(lines);
 };
+// A plan's LEDGER ROWS are its valid rows outside docs/ai/, each with its prompt's canonical name.
 const readPlan = (cwd, tools, path) => {
   const read = readText(cwd, path);
-  if (read.text === undefined) return { path, text: null, story: null, failure: state(READERS.plans, path, read.cause) };
+  if (read.text === undefined) return { path, story: null, failure: state(READERS.plans, path, read.cause) };
+  const refused = (reader, cause) => ({ path, story: null, failure: state(reader, path, cause, tools.planCheck(path)) });
   try {
-    const { story, findings } = storyOf(read.text);
-    if (findings.length) return { path, text: read.text, story: null, failure: state(READERS.plan, path, findings[0].message, tools.planCheck(path)) };
-    return { path, text: read.text, story, failure: null };
+    const parsed = parseLedger(read.text);
+    const { story, findings } = storyOf(parsed);
+    if (findings.length) return refused(READERS.story, findings[0].message);
+    const stem = posix.basename(path, MARKDOWN);
+    const rows = parsed.rows.filter((row) => row.valid);
+    const ledger = rows.filter((row) => !row.path.startsWith(DOCS_AI)).map((row) => ({ ...row, prompt: `${PROMPT_PREFIX}${stem}-${row.id}${MARKDOWN}` }));
+    const title = linesOf(read.text).map((line) => PLAN_TITLE.exec(line)?.[1]).find(Boolean) ?? null;
+    return { path, story, hasRow: rows.length > 0, ledger, title, failure: null };
   } catch (error) {
-    return { path, text: read.text, story: null, failure: state(READERS.plan, path, error.message, tools.planCheck(path)) };
+    return refused(READERS.ledger, error.message);
   }
 };
 
 const readPlans = (cwd, tools) => {
   try {
     const listing = readPlanEntries(cwd);
-    const names = plansInFlight(cwd, () => listing);
-    const plans = names.map((name) => readPlan(cwd, tools, `${PLANS_REL}/${name}`));
-    const briefs = listing.filter((entry) => entry.isFile() && entry.name.startsWith(TASK_PREFIX) && entry.name.endsWith(MARKDOWN))
-      .map((entry) => {
-        const path = `${PLANS_REL}/${entry.name}`;
-        const read = readText(cwd, path);
-        return { path, name: entry.name, text: read.text ?? '', cause: read.cause ?? null, plan: planOf(read.text ?? ''),
-          number: Number(TASK_NUMBER.exec(entry.name)?.[1] ?? 1) };
-      });
-    return { ok: true, plans, briefs, states: plans.filter((plan) => plan.failure).map((plan) => plan.failure) };
+    const plans = plansInFlight(cwd, () => listing).map((name) => readPlan(cwd, tools, `${PLANS_REL}/${name}`));
+    const owners = plans.flatMap((plan) => (plan.ledger ?? []).map((row) => ({ prompt: row.prompt, path: plan.path })));
+    const shared = [...new Set(owners.map(({ prompt }) => prompt))]
+      .map((prompt) => ({ prompt, paths: [...new Set(owners.filter((owner) => owner.prompt === prompt).map(({ path }) => path))] }))
+      .filter(({ paths }) => paths.length > 1);
+    const sharing = new Set(shared.flatMap(({ paths }) => paths));
+    return { ok: true, plans: plans.map((plan) => ({ ...plan, shared: sharing.has(plan.path) })),
+      states: plans.filter((plan) => plan.failure).map((plan) => plan.failure),
+      shared: shared.map(({ prompt, paths }) => state(READERS.ledger, prompt, `the prompt name is derived by ${paths.join(', ')}: rename a row or a plan so every prompt has one name`)) };
   } catch (error) {
     return { ok: false, state: state(READERS.entries, PLANS_REL, error.message) };
   }
 };
 
-const readBinding = (brief) => {
-  if (brief.cause) return { refused: brief.cause };
-  const parsed = parseBrief(brief.text);
-  if (!parsed.ok) return { refused: parsed.reason };
-  if (parsed.unclosed || parsed.blocks.length > 1) return { refused: 'binding: the block count is not one closed block', binding: true };
-  if (parsed.blocks.length === 0) return { parsed, bound: false };
-  const value = (() => { try { return JSON.parse(parsed.blocks[0].source); } catch { return null; } })();
-  const isOid = (field) => typeof field === 'string' && OID.test(field);
-  if (!isOid(value?.checkpoint) || !isOid(value?.head)) return { refused: 'binding: the block carries no checkpoint and head', binding: true };
-  return { parsed, bound: true, checkpoint: value.checkpoint, head: value.head };
-};
-
 const judgeStory = (context, epicPath, epicId, row) => {
-  const { cwd, tools, plans } = context;
+  const { cwd, tools, plans, today } = context;
   const own = plans.plans.filter((plan) => plan.story?.id === row.id && plan.story?.epic === epicId);
-  const stateOf = (stage, actions, extra = {}) => ({ story: { id: row.id, plan: extra.plan ?? null, stage, residual: extra.residual ?? [], actions } });
+  const stateOf = (stage, actions, plan = null, residual = []) => ({ story: { id: row.id, plan, stage, residual, actions } });
   if (own.length > 1) return { state: state(READERS.plans, own[0].path, `story ${row.id} of ${epicId} has ${own.length} plans: ${own.map((plan) => plan.path).join(', ')}`) };
   if (own.length === 0) {
     if (plans.states.length) return {};
@@ -182,106 +169,100 @@ const judgeStory = (context, epicPath, epicId, row) => {
     if (isPresent(cwd, standIn)) return { state: state(READERS.plans, standIn, `the plan stand-in path is taken by a file carrying no Story line ${row.id} of ${epicId} under Goal and boundary: move the line there, or rename or remove the file`) };
     return stateOf('S1', [tools.review(epicPath), action('write', `author the plan by hand at ${standIn}. ${planShape(row, epicId)}`)]);
   }
-  const plan = own[0];
-  try {
-    return judgePlan(context, epicPath, row, plan, stateOf);
-  } catch (error) {
-    return { state: state(READERS.plan, plan.path, error.message, tools.planCheck(plan.path)) };
+  const [plan] = own;
+  if (plan.shared) return {};
+  if (!plan.hasRow) return { state: state(READERS.ledger, plan.path, 'the plan has no valid row in its Module ledger', tools.planCheck(plan.path, `add a ledger row to ${plan.path}, then check the plan`)) };
+  const prompts = plan.ledger.map((ledgerRow) => ({ row: ledgerRow, ...readText(cwd, ledgerRow.prompt) }));
+  const refused = prompts.find((prompt) => prompt.text === undefined && !prompt.absent);
+  if (refused) return { state: state(READERS.prompt, refused.row.prompt, refused.cause) };
+  const handed = ((gap) => (gap < 0 ? prompts.length : gap))(prompts.findIndex((prompt) => prompt.absent));
+  const stray = prompts.slice(handed).filter((prompt) => !prompt.absent).map((prompt) => prompt.row);
+  const next = plan.ledger[handed];
+  if (stray.length) {
+    return { state: state(READERS.prompt, stray[0].prompt, `row ${stray[0].id} has a prompt after row ${next.id}, which has none`,
+      action('write', `remove the prompts after the first gap (${stray.map((ledgerRow) => ledgerRow.prompt).join(', ')}), then copy and fill the prompt of row ${next.id}`)) };
   }
+  const residual = prompts.slice(0, handed).flatMap((prompt) => findSpans(prompt.row.prompt, prompt.text));
+  const copyFill = (ledgerRow) => [tools.copy(TASK_TEMPLATE, ledgerRow.prompt, `copy the task template to ${ledgerRow.prompt}, the prompt of row ${ledgerRow.id}`),
+    action('write', `fill every key of the task template's closed list in ${ledgerRow.prompt}; ROW_LINE is the row ${ledgerRow.id}, copied verbatim`)];
+  const carry = (ledgerRow) => [
+    action('write', `carry the row ${ledgerRow.id}: write its Files yourself in the solo walk, else hand ${ledgerRow.prompt} to the carrier task.execute resolves to, a bridge only for new tests or code and with the contract block the engine's The task names; a file you already wrote you lay down yourself`),
+    action('run', `run every command under ## Run in ${ledgerRow.prompt}; the guide prints no line of a prompt`), tools.stage(ledgerRow, () => {
+      try { return expandSweepPaths(cwd, [ledgerRow.path])[ledgerRow.path].join(', ') || 'no path on disk'; } catch (error) { return `not expanded (${error.message})`; }
+    })];
+  if (handed === 0 && next) return stateOf('S2', [tools.planCheck(plan.path), ...copyFill(next)], plan.path, residual);
+  const last = handed > 0 ? carry(plan.ledger[handed - 1]) : [];
+  if (next) return stateOf('S3', [...last, ...copyFill(next)], plan.path, residual);
+  return stateOf('S4', [...last, tools.planVerify(plan.path), action('write', `edit the story row ${row.id} of ${epicPath} to read state: landed ${today} before the diff review, and stage it with the story's changes where git tracks ${EPICS_REL}`)], plan.path, residual);
 };
 
-const judgePlan = (context, epicPath, row, plan, stateOf) => {
-  const { cwd, env, tools, plans, head, today } = context;
-  const stem = posix.basename(plan.path, MARKDOWN);
-  const standIn = (number) => `${PLANS_REL}/${TASK_PREFIX}${stem}-T${number}${MARKDOWN}`;
-  const taken = plans.briefs.find((brief) => brief.plan !== null && brief.plan !== plan.path && brief.path === standIn(brief.number));
-  if (taken) return { state: state(READERS.brief, taken.path, `the brief stand-in path is taken by a brief of ${taken.plan}: rename or remove it`) };
-  const briefs = plans.briefs.filter((brief) => brief.plan === plan.path || (brief.plan === null && brief.path === standIn(brief.number)));
-  const judged = briefs.map((brief) => ({ ...brief, ...readBinding(brief) }));
-  const refusedBrief = judged.find((brief) => brief.refused);
-  if (refusedBrief) return { state: state(READERS.brief, refusedBrief.path, refusedBrief.refused,
-    refusedBrief.binding ? tools.check(refusedBrief.path) : tools.stamp(refusedBrief.path)) };
-  const top = Math.max(0, ...judged.map((brief) => brief.number));
-  const inHandAll = judged.filter((brief) => brief.number === top);
-  if (inHandAll.length > 1) return { state: state(READERS.brief, inHandAll[0].path, `briefs ${inHandAll.map((brief) => brief.path).join(', ')} carry one task number`) };
-  const inHand = inHandAll[0];
-  const rows = parseLedger(plan.text).rows.filter((ledgerRow) => ledgerRow.valid);
-  const briefed = new Set(judged.map((brief) => brief.parsed.rowId));
-  const unbriefed = rows.find((ledgerRow) => !briefed.has(ledgerRow.id));
-  const residual = judged.filter((brief) => brief.bound).flatMap((brief) => findSpans(brief.path, brief.text));
-  const extra = { plan: plan.path, residual };
-  const newest = newestCheckpoint(cwd, plan.path, { env });
-  const noHead = () => ({ state: state(READERS.head, null, 'HEAD is unborn: no commit to compare the brief with') });
-  const copyAction = (ledgerRow, number) => (ledgerRow && TEMPLATE_VERBS.has(ledgerRow.verb) && !isSweep(ledgerRow.path) && posix.basename(ledgerRow.path) !== PIN_FILE
-    ? [tools.copy(TASK_TEMPLATE, standIn(number), `copy the task template to ${standIn(number)}`),
-      action('write', `fill every key of the brief template's closed list in ${standIn(number)}, Row: ${ledgerRow.id}`), tools.stamp(standIn(number))]
-    : [action('write', `write the brief of row ${ledgerRow?.id ?? 'none'} by hand at ${standIn(number)} per the brief grammar (checkpoint, task-brief); the task template does not fit it`), tools.stamp(standIn(number))]);
-  if (!newest.ok && !String(newest.reason).startsWith(NO_CHECKPOINT)) return { state: state(READERS.sequence, plan.path, newest.reason) };
-  if (!newest.ok) {
-    if (!judged.some((brief) => brief.bound)) {
-      const paths = rows.flatMap((ledgerRow) => [ledgerRow.path, ledgerRow.anchorPath].filter(Boolean));
-      const result = checkPlan(plan.text, buildFacts(cwd, { paths, repo: openRepo(cwd) }));
-      if (result.findings.length) return { state: state(READERS.plan, plan.path, result.findings[0].message, tools.planCheck(plan.path)) };
-      return stateOf('S2', [tools.planCheck(plan.path), tools.mint(plan.path)], extra);
-    }
-    if (head.oid === null) return noHead();
-    if (!unbriefed && inHand.bound && inHand.head !== head.oid) {
-      return stateOf('S8', [action('write', `edit the story row ${row.id} of ${epicPath} to read state: landed ${today}`)], extra);
-    }
-    return { state: state(READERS.sequence, plan.path, 'the sequence was pruned before the story was done', tools.mint(plan.path)) };
-  }
-  if (!inHand) return stateOf('S3', copyAction(rows[0], 1), extra);
-  if (!inHand.bound) return stateOf('S4', [tools.stamp(inHand.path)], extra);
-  if (head.oid === null) return noHead();
-  if (inHand.head !== head.oid) {
-    return stateOf('S7', unbriefed ? [tools.mint(plan.path), ...copyAction(unbriefed, top + 1)]
-      : [tools.planVerify(plan.path), tools.prune(plan.path)], extra);
+const judgeEpic = (context, entries, entry) => {
+  const path = `${EPICS_REL}/${entry.name}`;
+  const id = posix.basename(path, MARKDOWN);
+  const others = entries.filter((other) => other.name !== entry.name);
+  const shape = checkEpic(entry.text, path);
+  const sweep = sweepSiblings(others, EPICS_REL);
+  const claims = shape.findings.length === 0 && sweep.ok ? checkClaims([shape.epic, ...sweep.epics]) : { findings: [] };
+  const accepted = ![...shape.findings, ...sweep.findings, ...claims.findings].some((finding) => finding.severity !== INFO);
+  // The leftover: the plans in flight naming a landed row, in ledger order.
+  const leftover = accepted ? shape.epic.rows.filter((row) => row.state === LANDED)
+    .flatMap((row) => context.plans.plans.filter((plan) => plan.story?.epic === id && plan.story.id === row.id)) : [];
+  return { entry, path, id, others, epic: shape.epic, accepted, leftover };
+};
+
+const readIndex = (context, held) => {
+  const paths = held.flatMap((judged) => judged.leftover.map((plan) => plan.path));
+  if (context.head.oid === null) return { ok: false, state: state(READERS.head, paths[0], `HEAD is unborn: the index of the leftover of ${paths.join(', ')} has no commit to be read against`) };
+  const answer = askGit(context.cwd, context.env, INDEX_ARGS);
+  if (answer.status !== INDEX_EQUAL && answer.status !== INDEX_DIFFERS) return { ok: false, state: state(READERS.index, paths[0], answer.reason) };
+  if (answer.status === INDEX_DIFFERS && held.length > 1) {
+    return { ok: false, state: state(READERS.index, paths[0], `the index differs from HEAD while ${held.length} epics have a landed plan in flight (${paths.join(', ')}): one commit cannot keep their stories apart`) };
   }
-  if (inHand.checkpoint !== newest.oid) return stateOf('S5', [tools.stamp(inHand.path)], extra);
-  const files = inHand.parsed.files.map((file) => file.path);
-  return stateOf('S6', [tools.check(inHand.path),
-    action('write', `bring the Files of ${inHand.path} to the row's post-state, the test first, until every Acceptance line is green`),
-    ...inHand.parsed.acceptance.map(([command]) => lineOf('run', 'run the Acceptance command of the brief', [command])),
-    tools.reviewState(),
-    lineOf('run', 'stage the Files of the brief', ['git', '--literal-pathspecs', 'add', '--', ...files.map(q)]),
-    lineOf('run', 'commit the Files of the brief', ['git', 'commit', '-m', q(inHand.parsed.title)])], extra);
+  return { ok: true, differs: answer.status === INDEX_DIFFERS };
 };
 
-const cleanupOf = (context, epicId, rows) => context.plans.plans
-  .filter((plan) => plan.story?.epic === epicId && rows.some((row) => row.id === plan.story.id && row.state === LANDED))
-  .flatMap((plan) => {
-    const newest = newestCheckpoint(context.cwd, plan.path, { env: context.env });
-    const prune = !newest.ok && String(newest.reason).startsWith(NO_CHECKPOINT) ? [] : [context.tools.prune(plan.path)];
-    return [...prune, action('write', `remove the plan ${plan.path} and its briefs: the Cleanup of a landed story`)];
+const leftoverActions = (context, plans) => {
+  if (!context.index.ok || plans.some((plan) => plan.shared)) return [];
+  const removals = plans.map((plan) => {
+    const prompts = plan.ledger.map((row) => row.prompt).filter((prompt) => isPresent(context.cwd, prompt));
+    return action('write', `remove the plan ${plan.path} and its prompts (${prompts.length ? prompts.join(', ') : 'none on disk'}): the Cleanup of a landed story`);
   });
+  if (!context.index.differs) return removals;
+  const { tools } = context;
+  const commit = plans[0].title === null ? action('write', `commit every staged change once: the plan ${plans[0].path} carries no # Plan: title to name it`) : tools.commit(plans[0]);
+  return [tools.diff(), tools.reviewState(), commit, ...removals];
+};
 
-const judgeEntry = (context, store, entry) => {
-  const judged = judgeEpic(store.entries, entry);
+const closeActions = (context, judged) => {
+  const queueRead = readRegularFileNoFollow(resolve(context.cwd, QUEUE_PATH));
+  const queue = queueRead.outcome === 'ok' ? queueRead.content : { outcome: queueRead.outcome, reason: queueRead.code ?? queueRead.className };
+  const closed = judgeClose({ epic: judged.entry.text, path: judged.path, queue, entries: judged.others });
+  const edits = closed.findings.filter((finding) => finding.severity !== INFO).map((finding) => (finding.code === 'close-result'
+    ? action('write', `add the line Result line: ${context.today} under ## Acceptance of ${judged.path}`)
+    : action('write', finding.code === 'close-queue' ? `delete the queue row: ${stripPath(finding)}` : stripPath(finding))));
+  return [...edits, context.tools.close(judged.path),
+    action('write', `commit the close's edits (the header, the Result line, the queue row) where git tracks them: the epic's own change after its last story's commit`)];
+};
+
+const judgeEntry = (context, judged) => {
   const { tools } = context;
-  const id = posix.basename(judged.path, MARKDOWN);
-  const base = { stage: 'E2', id, path: judged.path, cause: null, fact: null, residual: [], actions: [tools.epicCheck(judged.path)], stories: [] };
+  const { path, id, epic } = judged;
+  const base = { stage: 'E2', id, path, cause: null, fact: null, residual: [], actions: [tools.epicCheck(path)], stories: [] };
   if (!judged.accepted) return { entry: base, states: [] };
-  const { epic } = judged;
-  const residual = findSpans(judged.path, entry.text);
-  const accepted = { ...base, residual };
-  if (epic.fields.state === LANDED) return { entry: { ...accepted, stage: 'E5', actions: cleanupOf(context, id, epic.rows) }, states: [] };
+  const accepted = { ...base, residual: findSpans(path, judged.entry.text) };
+  const leftover = judged.leftover.length ? leftoverActions(context, judged.leftover) : null;
+  if (epic.fields.state === LANDED) return { entry: { ...accepted, stage: 'E5', actions: leftover ?? [] }, states: [] };
   const landed = new Set(epic.rows.filter((row) => row.state === LANDED).map((row) => row.id));
   const inHand = epic.rows.filter((row) => row.state !== LANDED && row.dependsOn.every((dependency) => landed.has(dependency)));
-  if (inHand.length === 0) {
-    const queueRead = readRegularFileNoFollow(resolve(context.cwd, QUEUE_PATH));
-    const queue = queueRead.outcome === 'ok' ? queueRead.content : { outcome: queueRead.outcome, reason: queueRead.code ?? queueRead.className };
-    const closed = judgeClose({ epic: entry.text, path: judged.path, queue, entries: judged.others });
-    const edits = closed.findings.filter((finding) => finding.severity !== INFO).map((finding) => (finding.code === 'close-result'
-      ? action('write', `add the line Result line: ${context.today} under ## Acceptance of ${judged.path}`)
-      : action('write', finding.code === 'close-queue' ? `delete the queue row: ${stripPath(finding)}` : stripPath(finding))));
-    return { entry: { ...accepted, stage: 'E4', actions: [...edits, tools.close(judged.path), ...cleanupOf(context, id, epic.rows)] }, states: [] };
-  }
-  const stories = inHand.map((row) => judgeStory(context, judged.path, id, row));
-  return { entry: { ...accepted, stage: 'E3', fact: tools.epicCheck(judged.path, 'fact'), actions: cleanupOf(context, id, epic.rows),
-    stories: stories.filter((story) => story.story).map((story) => story.story) }, states: stories.filter((story) => story.state).map((story) => story.state) };
+  if (inHand.length === 0) return { entry: { ...accepted, stage: 'E4', actions: leftover ?? (context.index === null ? closeActions(context, judged) : []) }, states: [] };
+  const held = { ...accepted, stage: 'E3', fact: tools.epicCheck(path, 'fact'), actions: leftover ?? [] };
+  if (context.index !== null) return { entry: held, states: [] };
+  const stories = inHand.map((row) => judgeStory(context, path, id, row));
+  return { entry: { ...held, stories: stories.filter((story) => story.story).map((story) => story.story) },
+    states: stories.filter((story) => story.state).map((story) => story.state) };
 };
 
-const judgeFirstEpic = (context, store) => {
+const judgeFirstEpic = (context) => {
   const standIn = `${EPICS_REL}/${STAND_IN_EPIC}${MARKDOWN}`;
   if (isPresent(context.cwd, standIn)) return { states: [state(READERS.store, standIn, 'the epic stand-in path is taken by a file that is not an epic: rename or remove it')], entries: [] };
   return { states: [], entries: [{ stage: 'E1', id: null, path: null, cause: E1_CAUSE, fact: null, residual: [], actions: [
@@ -304,12 +285,17 @@ export const readTierFacts = ({ cwd, env, toolsDir, today }) => {
   const head = readHead(cwd, env);
   const headStates = head.ok ? [] : [state(READERS.head, null, head.reason)];
   if (!plans.ok) return { location, states: [...storeStates, plans.state, ...headStates], entries: [], skipped: store.skipped };
-  const context = { cwd, env, tools, plans, head: head.ok ? head : { oid: null }, today };
+  const planStates = [...storeStates, ...plans.states, ...plans.shared, ...headStates];
+  if (!head.ok) return { location, states: planStates, entries: [], skipped: store.skipped };
+  const context = { cwd, env, tools, plans, head, today, index: null };
   if (store.epics.length === 0) {
-    const first = store.headerFindings.length ? { states: [], entries: [] } : judgeFirstEpic(context, store);
-    return { location, states: [...storeStates, ...plans.states, ...headStates, ...first.states], entries: first.entries, skipped: store.skipped };
+    const first = store.headerFindings.length ? { states: [], entries: [] } : judgeFirstEpic(context);
+    return { location, states: [...planStates, ...first.states], entries: first.entries, skipped: store.skipped };
   }
-  const judged = store.epics.map((entry) => judgeEntry(context, store, entry));
-  return { location, states: [...storeStates, ...plans.states, ...headStates, ...judged.flatMap((item) => item.states)],
-    entries: judged.map((item) => item.entry), skipped: store.skipped };
+  const judged = store.epics.map((entry) => judgeEpic(context, store.entries, entry));
+  const held = judged.filter((item) => item.leftover.length);
+  const index = held.length ? readIndex(context, held) : null;
+  const rendered = judged.map((item) => judgeEntry({ ...context, index }, item));
+  return { location, states: [...planStates, ...(index?.state ? [index.state] : []), ...rendered.flatMap((item) => item.states)],
+    entries: rendered.map((item) => item.entry), skipped: store.skipped };
 };

package/tools/tier-guide.mjs

@@ -38,25 +38,19 @@ const EPIC_KEYS = [
   ['QUEUE_BUCKET', 'the queue section the epic\'s row stands in.'],
 ];
 const TASK_KEYS = [
-  ['TASK_NAME', 'the task in a few plain words; the commit title.'],
-  ['STORY_ID', 'the story the task serves: S1, S2 and so on.'],
-  ['EPIC_ID', 'the epic the story belongs to, its file stem.'],
+  ['TASK_NAME', 'the task in a few plain words.'],
   ['PLAN_PATH', 'the plan under docs/plans that carries the row.'],
-  ['ROW_ID', 'the ledger row the task carries.'],
-  ['TEST_PATH', 'the test file of the row, written first.'],
-  ['MODULE_PATH', 'the module file of the row.'],
-  ['ACCEPTANCE_COMMAND', 'a command line that proves the task done.'],
-  ['EXPECTED_OUTCOME', 'what that command answers when the task is done.'],
-  ['NEGATIVE_CASE', 'a case the task must not break.'],
-  ['NEGATIVE_OUTCOME', 'what stays true in that case.'],
-  ['TEST_MAX_LINES', 'the line budget of the test file.'],
-  ['MODULE_MAX_LINES', 'the line budget of the module file.'],
+  ['ROW_LINE', 'the ledger row, copied verbatim.'],
+  ['FILE_PATH', 'a path the carrier may write, one line per path, none ignored by git.'],
+  ['SCENARIO_LINE', 'a scenario line of the governing spec, verbatim, or the acceptance bullet of a plan that governs none.'],
+  ['RUN_COMMAND', 'a command line the carrier runs, the row\'s tests.'],
+  ['FORBIDDEN_COMMAND', 'a command the carrier must not run, such as git commit before the diff review.'],
 ];
 const renderTier = (toolsDir, cwd) => [
   'An epic is one outcome too large for one plan, split into stories in its ledger under docs/ai/epics.',
   'A story is one row of an epic\'s ledger, carried by one plan under docs/plans.',
-  'A task is one row of a story\'s plan, carried by one brief bound to a checkpoint.',
-  'A story runs as five sessions: spec, plan, tests, code, diff review + release + record.',
+  'A task is one row of a story\'s plan, handed out in one prompt from the task template; the story commits once, after its diff review.',
+  'A story runs as four sessions: spec and plan, tests, code, diff review + release + record.',
   `The epic template: ${resolve(toolsDir, '../references/authoring/EPIC_TEMPLATE.md')}`,
   `The task template: ${resolve(toolsDir, '../references/authoring/TASK_TEMPLATE.md')}`,
   'Epic template keys:',