@warren-dean/code-kit 0.7.0 → 0.8.0

package/hooks/lib/plan.mjs

@@ -47,12 +47,18 @@ const field = (lines, name) =>
     .find(Boolean)?.[1]
     .trim() ?? '';
 
-/** Every story in the plan: [{ id, title, lane, requirements, dependsOn, status }]. */
+/**
+ * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, milestone }]. A story's
+ * milestone is the `## ` heading above it ("Milestone 5: Your own key"), or null.
+ */
 export function readStories(root, planPath) {
   const stories = [];
   for (const file of markdownFiles(root, planPath)) {
     const lines = readFileSync(join(root, file), 'utf8').split('\n');
+    let milestone = null;
     lines.forEach((line, i) => {
+      const heading = line.match(/^##\s+(.+?)\s*$/);
+      if (heading) milestone = heading[1];
       const m = line.match(STORY_HEADING);
       if (!m) return;
       const end = lines.findIndex((l, j) => j > i && /^#{1,3}\s/.test(l));
@@ -67,6 +73,7 @@ export function readStories(root, planPath) {
         noRequirements: /^none\b/i.test(field(body, 'Requirements')),
         dependsOn: [...field(body, 'Depends on').matchAll(/\bST-\d+\b/g)].map((r) => r[0]),
         status: STATES.includes(status) ? status : 'todo',
+        milestone,
       });
     });
   }

package/hooks/lib/storymap.mjs

@@ -0,0 +1,155 @@
+// A story's code as the pane draws it (docs/specs/14-mission-and-maps.md): the files it changed, by the
+// layer each sits in, with the imports between them (MAP-1); and each requirement's trail to its
+// stories, their files and the tests that name it (TRAIL-1). Read from git, the config and the plan.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { matchesAny } from './glob.mjs';
+import { CODE, importsOf, layerOf, targetOf } from './layers.mjs';
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return '';
+  }
+};
+
+/** Files that are the build's own code: not the plan, the specs, or the tools' state. */
+const KIT = /^(\.claude|\.ctx|\.github)\//;
+const isCode = (rel) => CODE.test(rel) && !KIT.test(rel);
+
+/**
+ * The code files a story changed: those in commits whose message names it (on any branch, so a merged
+ * story still has its files) and, while its branch is open, its diff against the base. Only files that
+ * still exist, in path order.
+ */
+export function storyFiles(root, story, from) {
+  const found = new Set();
+  const id = story.id;
+  const log = git(
+    root,
+    'log',
+    '--all',
+    '--no-merges',
+    '-E',
+    // POSIX ERE has no \b: "ST-1" mustn't match "ST-12".
+    `--grep=(^|[^A-Za-z0-9-])${id}([^0-9]|$)`,
+    '--format=',
+    '--name-only',
+  );
+  for (const f of log.split('\n')) if (f) found.add(f);
+  if (story.branchExists && story.branch)
+    for (const f of git(root, 'diff', '--name-only', `${from}...${story.branch}`).split('\n'))
+      if (f) found.add(f);
+  return [...found].filter((f) => isCode(f) && existsSync(join(root, f))).sort();
+}
+
+const EXTENSIONS = [
+  '',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '/index.ts',
+  '/index.tsx',
+  '/index.js',
+];
+
+/** The file in `files` an import specifier in `rel` points at, or null. */
+function resolveIn(spec, rel, aliases, files) {
+  const target = targetOf(spec, rel, aliases);
+  if (!target) return null;
+  // `./x.js` in TypeScript source names `./x.ts`.
+  const bare = target.replace(/\.(js|mjs|cjs)$/, '');
+  for (const ext of EXTENSIONS) {
+    for (const candidate of [`${target}${ext}`, `${bare}${ext}`])
+      if (files.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The lane that owns `rel`, or `lead`, or null. */
+export function laneOfFile(rel, config) {
+  const lane = Object.keys(config.lanes).find((name) => {
+    const { paths, exclude = [] } = config.lanes[name];
+    return matchesAny(rel, paths) && !matchesAny(rel, exclude);
+  });
+  if (lane) return lane;
+  return matchesAny(
+    rel,
+    config.lead.paths.filter((p) => p !== '*'),
+  )
+    ? 'lead'
+    : null;
+}
+
+const TEST = /(^|\/)(tests?|e2e|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * MAP-1: a story's code: { story, layers, files: [{ path, layer, lane, imports }] }. `layers` are the
+ * config's layers in their order, then `tests` and `other` where any file falls there; each file's
+ * imports are the story's other files it imports.
+ */
+export function storyMap(root, story, config, from) {
+  const paths = storyFiles(root, story, from);
+  const set = new Set(paths);
+  const aliases = config.importAliases ?? {};
+  const files = paths.map((rel) => {
+    let source = '';
+    try {
+      source = readFileSync(join(root, rel), 'utf8');
+    } catch {
+      // unreadable: no imports
+    }
+    const imports = [
+      ...new Set(
+        importsOf(source)
+          .map((spec) => resolveIn(spec, rel, aliases, set))
+          .filter((t) => t && t !== rel),
+      ),
+    ];
+    const layer = TEST.test(rel) ? 'tests' : (layerOf(rel, config.layers)?.name ?? 'other');
+    return { path: rel, layer, lane: laneOfFile(rel, config), imports };
+  });
+  const used = new Set(files.map((f) => f.layer));
+  const layers = [...config.layers.map((l) => l.name), 'tests', 'other'].filter((l) => used.has(l));
+  return {
+    story: { id: story.id, title: story.title, lane: story.lane, state: story.state },
+    layers,
+    files,
+  };
+}
+
+/**
+ * TRAIL-1: each requirement's trail: { id, title, spec, state, stories: [{ id, state, lane }],
+ * files, tests }. Files are the code its stories changed, tests aside; tests are the files that name it.
+ */
+export function trail(root, status, from) {
+  const byStory = new Map();
+  const filesOf = (s) => {
+    if (!byStory.has(s.id)) byStory.set(s.id, storyFiles(root, s, from));
+    return byStory.get(s.id);
+  };
+  return status.requirements
+    .filter((r) => !r.removed)
+    .map((r) => {
+      const stories = status.stories.filter((s) => s.requirements.includes(r.id));
+      const files = [...new Set(stories.flatMap((s) => filesOf(s)).filter((f) => !TEST.test(f)))];
+      return {
+        id: r.id,
+        title: r.title,
+        spec: r.file ? posix.basename(r.file) : null,
+        state: r.state,
+        stories: stories.map((s) => ({ id: s.id, state: s.state, lane: s.lane })),
+        files,
+        tests: [...(r.tests ?? [])],
+      };
+    });
+}

package/hooks/mod/codemap.mjs

@@ -0,0 +1,328 @@
+// The code map (docs/specs/14-mission-and-maps.md, MAP-1 to MAP-4), the pure parts: what an agent's
+// tool call touches, which files glow and for whom, the map laid out by layer, and the drawing of it:
+// box-drawing text for the terminal, an SVG elsewhere. Its data is `code-kit map <story> --json`.
+
+/** Calls that read a file, and calls that change one. */
+const READS = new Set(['Read', 'NotebookRead']);
+const EDITS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+
+/**
+ * MAP-2: the repository path a tool call reads or edits, and which: { path, verb } or null. Paths in
+ * an agent's worktree (`.claude/worktrees/<id>/…`) are the same repository path.
+ */
+export function touchOf(call, cwd = '') {
+  const verb = READS.has(call?.tool) ? 'read' : EDITS.has(call?.tool) ? 'edit' : null;
+  const raw = call?.file_path ?? call?.notebook_path ?? call?.path;
+  if (!verb || typeof raw !== 'string') return null;
+  let path = raw;
+  const tree = path.match(/\/\.claude\/worktrees\/[^/]+\/(.+)$/);
+  if (tree) path = tree[1];
+  else if (cwd && path.startsWith(`${cwd}/`)) path = path.slice(cwd.length + 1);
+  return path.startsWith('/') ? null : { path, verb };
+}
+
+/** How long a touched file glows after the call. */
+export const GLOW_MS = 20000;
+
+/** MAP-2: the files glowing now: { [path]: { lane, verb } }, the latest touch of each winning. */
+export function glowOf(touches, now, windowMs = GLOW_MS) {
+  const out = {};
+  for (const t of [...touches].sort((a, b) => a.at - b.at))
+    if (now - t.at <= windowMs) out[t.path] = { lane: t.lane, verb: t.verb };
+  return out;
+}
+
+/** A file's card as another tool knows it: current, stale or missing, or null when none says. */
+export function cardOf(file) {
+  for (const facts of Object.values(file.adapters ?? {})) if (facts?.card) return facts.card;
+  return null;
+}
+
+/** The name a node shows: the file's name, and its folder when another file shares the name. */
+const nameOf = (path, all) => {
+  const base = path.split('/').pop();
+  const twins = all.filter((p) => p.split('/').pop() === base);
+  if (twins.length < 2) return base;
+  const parts = path.split('/');
+  return parts.slice(-2).join('/');
+};
+
+const NODE_H = 4;
+const ROW_GAP = 1;
+const COL_GAP = 6;
+const GUTTER = 3;
+
+/**
+ * MAP-1: the map laid out in character cells: a column per layer (in the map's order), its files
+ * stacked; { columns: [{ layer, x, width }], nodes: { [path]: { x, y, w, h, name, layer } }, width,
+ * height }. `width` is the room there is; columns share it, each between 16 and 30 cells.
+ */
+export function layout(map, width = 100) {
+  const layers = map.layers.filter((l) => map.files.some((f) => f.layer === l));
+  const n = Math.max(1, layers.length);
+  const colW = Math.max(16, Math.min(30, Math.floor((width - COL_GAP * (n - 1)) / n)));
+  const all = map.files.map((f) => f.path);
+  // A gutter of GUTTER cells left of each column carries the imports between files of one layer.
+  const columns = layers.map((layer, i) => ({
+    layer,
+    x: GUTTER + i * (colW + COL_GAP),
+    width: colW,
+  }));
+  const nodes = {};
+  let height = 2;
+  for (const c of columns) {
+    const files = map.files.filter((f) => f.layer === c.layer);
+    files.forEach((f, j) => {
+      const y = 2 + j * (NODE_H + ROW_GAP);
+      nodes[f.path] = { x: c.x, y, w: colW, h: NODE_H, name: nameOf(f.path, all), layer: c.layer };
+      height = Math.max(height, y + NODE_H);
+    });
+  }
+  return { columns, nodes, width: columns.length ? columns.at(-1).x + colW : 0, height };
+}
+
+/** The words under a node's name: what's happening to it, or its card. */
+function statusOf(path, file, glow) {
+  const g = glow[path];
+  if (g)
+    return {
+      text: `${g.lane} ${g.verb === 'edit' ? 'editing' : 'reading'}`,
+      style: g.verb === 'edit' ? 'editing' : 'reading',
+      lane: g.lane,
+    };
+  const card = cardOf(file);
+  if (!card) return { text: '', style: 'dim' };
+  // A card is the file's why: what it's for, what it relies on, what it must keep true.
+  if (card.state === 'current') return { text: '✓ why written', style: 'ok', card: 'current' };
+  if (card.state === 'stale') return { text: 'why out of date', style: 'warn', card: 'stale' };
+  return { text: 'no why yet', style: 'warn', card: 'missing' };
+}
+
+const fit = (s, n) => (s.length > n ? `${s.slice(0, Math.max(0, n - 1))}…` : s);
+
+/**
+ * MAP-1 to MAP-3 in the terminal: the map as rows of styled runs, [[{ text, style, lane? }]]. Styles:
+ * dim (layer names, edges), node, selected, reading and editing (a glowing box's border, with the
+ * lane), fill-read and fill-edit (its inside, filled with the lane's colour), ok, warn. Edges are
+ * drawn between neighbouring columns; the others are named in the selected file's detail.
+ */
+export function mapRows(map, { glow = {}, selected = null, width = 100 } = {}) {
+  const L = layout(map, width);
+  if (!L.columns.length) return [];
+  const W = L.width;
+  const grid = Array.from({ length: L.height }, () =>
+    Array.from({ length: W }, () => ({ ch: ' ', style: 'dim' })),
+  );
+  const put = (x, y, ch, style, lane) => {
+    if (y < 0 || y >= L.height || x < 0 || x >= W) return;
+    grid[y][x] = { ch, style, ...(lane ? { lane } : {}) };
+  };
+  for (const c of L.columns) {
+    const label = fit(c.layer, c.width);
+    [...label].forEach((ch, i) => put(c.x + i, 0, ch, 'dim'));
+  }
+  // Edges first, so the boxes draw over their ends: from the importer's side to the imported's.
+  const byPath = Object.fromEntries(map.files.map((f) => [f.path, f]));
+  const colOf = (p) => L.columns.findIndex((c) => c.layer === L.nodes[p].layer);
+  const joints = new Map();
+  const line = (x, y, dir) => {
+    const key = `${x},${y}`;
+    const had = joints.get(key) ?? new Set();
+    for (const d of dir) had.add(d);
+    joints.set(key, had);
+  };
+  for (const f of map.files)
+    for (const target of f.imports) {
+      if (!L.nodes[target]) continue;
+      const a = L.nodes[f.path];
+      const b = L.nodes[target];
+      const ca = colOf(f.path);
+      const cb = colOf(target);
+      // MAP-1: within one layer, a bracket in the column's gutter joins the two files.
+      if (ca === cb) {
+        const x = a.x - 2;
+        const ya = a.y + 1;
+        const yb = b.y + 1;
+        line(a.x - 1, ya, 'we');
+        line(x, ya, yb > ya ? 'es' : 'ne');
+        for (let y = Math.min(ya, yb) + 1; y < Math.max(ya, yb); y++) line(x, y, 'ns');
+        line(x, yb, yb > ya ? 'ne' : 'es');
+        line(b.x - 1, yb, 'we');
+        continue;
+      }
+      if (Math.abs(ca - cb) !== 1) continue;
+      const left = ca < cb ? a : b;
+      const right = ca < cb ? b : a;
+      const ya = left.y + 1;
+      const yb = right.y + 1;
+      const x0 = left.x + left.w;
+      const x1 = right.x - 1;
+      const mid = x0 + Math.floor((x1 - x0) / 2);
+      for (let x = x0; x <= mid; x++)
+        line(x, ya, x === mid ? (yb === ya ? 'we' : yb > ya ? 'ws' : 'wn') : 'we');
+      for (let y = Math.min(ya, yb) + 1; y < Math.max(ya, yb); y++) line(mid, y, 'ns');
+      if (yb !== ya) line(mid, yb, yb > ya ? 'ne' : 'se');
+      for (let x = mid + 1; x <= x1; x++) line(x, yb, 'we');
+    }
+  const JOINT = {
+    we: '─',
+    ns: '│',
+    ne: '└',
+    es: '┌',
+    sw: '┐',
+    nw: '┘',
+    nes: '├',
+    nsw: '┤',
+    esw: '┬',
+    new: '┴',
+    nesw: '┼',
+  };
+  for (const [key, dirs] of joints) {
+    const [x, y] = key.split(',').map(Number);
+    const k = ['n', 'e', 's', 'w'].filter((d) => dirs.has(d)).join('');
+    put(x, y, JOINT[k] ?? '─', 'dim');
+  }
+  for (const [path, node] of Object.entries(L.nodes)) {
+    const file = byPath[path];
+    const status = statusOf(path, file, glow);
+    const box = path === selected ? 'selected' : glow[path] ? status.style : 'node';
+    const lane = glow[path]?.lane;
+    const { x, y, w } = node;
+    const edge =
+      glow[path]?.verb === 'edit' ? ['┏', '┓', '┗', '┛', '━', '┃'] : ['╭', '╮', '╰', '╯', '─', '│'];
+    put(x, y, edge[0], box, lane);
+    put(x + w - 1, y, edge[1], box, lane);
+    put(x, y + 3, edge[2], box, lane);
+    put(x + w - 1, y + 3, edge[3], box, lane);
+    for (let i = 1; i < w - 1; i++) {
+      put(x + i, y, edge[4], box, lane);
+      put(x + i, y + 3, edge[4], box, lane);
+    }
+    // MAP-2: a glowing file fills with its lane's colour, its name and status written over it.
+    const fill = lane ? `fill-${glow[path].verb}` : null;
+    for (const row of [1, 2]) {
+      put(x, y + row, edge[5], box, lane);
+      put(x + w - 1, y + row, edge[5], box, lane);
+      for (let i = 1; i < w - 1; i++) put(x + i, y + row, ' ', fill ?? 'node', lane);
+    }
+    [...fit(node.name, w - 4)].forEach((ch, i) =>
+      put(x + 2 + i, y + 1, ch, fill ?? (path === selected ? 'selected' : 'node'), lane),
+    );
+    [...fit(status.text, w - 4)].forEach((ch, i) =>
+      put(x + 2 + i, y + 2, ch, fill ?? status.style, status.lane ?? lane),
+    );
+  }
+  // Runs: neighbouring cells of one style (and lane) as one piece of text.
+  return grid.map((row) => {
+    const runs = [];
+    for (const cell of row) {
+      const last = runs.at(-1);
+      if (last && last.style === cell.style && last.lane === cell.lane) last.text += cell.ch;
+      else
+        runs.push({ text: cell.ch, style: cell.style, ...(cell.lane ? { lane: cell.lane } : {}) });
+    }
+    return runs;
+  });
+}
+
+const esc = (s) =>
+  String(s).replace(
+    /[&<>"]/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c],
+  );
+
+/**
+ * MAP-1 to MAP-3 on the remote surfaces: the map as an SVG, every import drawn, glowing files pulsing
+ * in their lane's colour. `tints` gives each lane's colour; `selected` is outlined.
+ */
+export function mapSvg(map, { glow = {}, selected = null, tints = {}, width = 100 } = {}) {
+  const L = layout(map, width);
+  const CW = 7.2;
+  const RH = 16;
+  const W = Math.max(200, Math.round(L.width * CW) + 20);
+  const H = Math.round(L.height * RH) + 20;
+  const box = (p) => {
+    const n = L.nodes[p];
+    return { x: 10 + n.x * CW, y: 10 + n.y * RH, w: n.w * CW, h: 3 * RH };
+  };
+  const parts = [];
+  for (const c of L.columns)
+    parts.push(
+      `<text x="${10 + c.x * CW}" y="${10 + RH * 0.8}" fill="#7f8c8d" font-size="11">${esc(c.layer)}</text>`,
+    );
+  for (const f of map.files)
+    for (const target of f.imports) {
+      if (!L.nodes[target]) continue;
+      const a = box(f.path);
+      const b = box(target);
+      const fromRight = a.x > b.x;
+      const x1 = fromRight ? a.x : a.x + a.w;
+      const x2 = fromRight ? b.x + b.w : b.x;
+      const y1 = a.y + a.h / 2;
+      const y2 = b.y + b.h / 2;
+      const mx = (x1 + x2) / 2;
+      const live = glow[f.path] || glow[target];
+      const color = live ? (tints[(glow[f.path] ?? glow[target]).lane] ?? '#5fb3b3') : '#3b4c50';
+      parts.push(
+        `<path d="M${x1},${y1} C${mx},${y1} ${mx},${y2} ${x2},${y2}" fill="none" stroke="${color}" stroke-width="${live ? 1.6 : 1}"/>`,
+      );
+    }
+  const byPath = Object.fromEntries(map.files.map((f) => [f.path, f]));
+  for (const [path, node] of Object.entries(L.nodes)) {
+    const b = box(path);
+    const status = statusOf(path, byPath[path], glow);
+    const g = glow[path];
+    const tint = g ? (tints[g.lane] ?? '#5fb3b3') : null;
+    if (tint)
+      parts.push(
+        `<rect x="${b.x - 4}" y="${b.y - 4}" width="${b.w + 8}" height="${b.h + 8}" rx="6" fill="${tint}" opacity="${g.verb === 'edit' ? 0.4 : 0.22}"><animate attributeName="opacity" values="${g.verb === 'edit' ? '0.4;0.15;0.4' : '0.22;0.08;0.22'}" dur="1.2s" repeatCount="indefinite"/></rect>`,
+      );
+    const stroke =
+      path === selected
+        ? '#8fb8ff'
+        : status.style === 'ok'
+          ? '#78c98a'
+          : status.style === 'warn'
+            ? '#e3b450'
+            : '#3b4c50';
+    parts.push(
+      `<rect x="${b.x}" y="${b.y}" width="${b.w}" height="${b.h}" rx="4" fill="${path === selected ? '#1d3a52' : '#0f1618'}" stroke="${stroke}"${status.card === 'missing' ? ' stroke-dasharray="4 3"' : ''}/>`,
+    );
+    parts.push(
+      `<text x="${b.x + 8}" y="${b.y + 18}" fill="#cfd9da" font-size="12">${esc(fit(node.name, node.w - 2))}</text>`,
+    );
+    const color =
+      tint ?? (status.style === 'ok' ? '#78c98a' : status.style === 'warn' ? '#e3b450' : '#6e8286');
+    parts.push(
+      `<text x="${b.x + 8}" y="${b.y + 36}" fill="${color}" font-size="11">${esc(status.text)}</text>`,
+    );
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" font-family="ui-monospace, Menlo, monospace">${parts.join('')}</svg>`;
+}
+
+/** MAP-3: the selected file's neighbours in the story: what it imports and what imports it. */
+export function neighboursOf(map, path) {
+  const file = map.files.find((f) => f.path === path);
+  return {
+    imports: file?.imports ?? [],
+    importers: map.files.filter((f) => f.imports.includes(path)).map((f) => f.path),
+  };
+}
+
+/** The story the code map opens on: the one asked for, else the selected lane's, else one at work. */
+export function mapStoryOf(state, selectedLane, asked = null) {
+  if (asked) return asked;
+  const lane = state?.lanes?.find((l) => l.name === selectedLane);
+  if (lane?.story) return lane.story.id;
+  const busy = state?.lanes?.find((l) => l.story && ['building', 'in review'].includes(l.state));
+  return busy?.story.id ?? state?.stories?.find((s) => s.state !== 'done')?.id ?? null;
+}
+
+/** MAP-2, MAP-3: the map's legend: what the colours and words mean, a card being the file's why. */
+export const MAP_LEGEND = [
+  { text: '■ a lane at work', style: 'glow' },
+  { text: '✓ why written', style: 'ok' },
+  { text: 'why out of date', style: 'warn' },
+  { text: 'no why yet', style: 'warn' },
+  { text: "a file's why is its card, kept in git by Context Graph", style: 'dim' },
+];

package/hooks/mod/decisions.mjs

@@ -0,0 +1,146 @@
+// Decisions (docs/specs/15-decisions-and-journal.md, DECIDE-2 and DECIDE-3), the pure parts: what reaches
+// the person, each with its lineage. The band's "you" lines say what needs them; a decision card says why:
+// what they asked for, the story and requirements it belongs to, what the agent was doing, what was already
+// settled, why the lead couldn't settle this itself, and each option with what happens next.
+
+/** The kinds of band line that are the person's to decide; the rest are notes. */
+export const DECISION_KINDS = new Set([
+  'held',
+  'approvals',
+  'stalled',
+  'proposal',
+  'queue',
+  'review',
+  'notice',
+]);
+
+/** What each answer does, in the person's words. */
+const EFFECT = {
+  approveHeld: 'The held call runs now, and the agent carries on.',
+  refuseHeld: 'The agent is told no and has to find another way; the lead hears why.',
+  approve: "You confirm it with your reason; it's logged, and the agent can go ahead.",
+  resumeStall: 'The lead dispatches the story again, with the same brief, on the same branch.',
+  lanes: 'Opens the Lanes pane, to look before deciding.',
+  go: 'The lead is asked to take this step now.',
+  keepGoing: 'The build keeps moving between your prompts. You can pause it any time.',
+  askEach: 'Each step waits here for your Go.',
+  loopOff: 'Nothing happens between your prompts; you drive the build.',
+  mergeQueue: "It's verified against main as it is now and merged; after that the lead merges.",
+  review: 'The lead reviews it against its requirements now.',
+  merge: "It's verified and merged now, by you.",
+  dismiss: 'Clears this message.',
+};
+
+/** Why a line needs the person, when the line itself doesn't say. */
+function whyOf(line, check) {
+  if (line.kind === 'held') {
+    const c = line.held;
+    const rule = c.refusal ? firstSentence(c.refusal) : 'It needs an approval only you can give.';
+    const limits = limitsWhy(c.outside);
+    return limits ? `${rule} ${limits}` : rule;
+  }
+  if (line.kind === 'approvals')
+    return line.request?.why ?? 'It needs an approval only you can give.';
+  if (line.kind === 'stalled')
+    return `The lead restarted it ${line.stall.count - 1} time${line.stall.count === 2 ? '' : 's'} and it stalled again, so it stopped trying.`;
+  if (line.kind === 'proposal' && line.proposal?.first)
+    return "You haven't chosen yet how much the lead does between your prompts.";
+  if (line.kind === 'proposal' && line.proposal?.repeated)
+    return `The lead was asked to do this ${line.proposal.repeated} times and it's still the next step, so something stopped it.`;
+  if (line.kind === 'proposal') return 'You asked to approve each step before the lead takes it.';
+  if (line.kind === 'queue')
+    return check?.firstMerge
+      ? 'main has no rules committed yet, so this first merge is yours; after it, the lead merges.'
+      : "Your rules don't let the lead merge into main, so merges are yours.";
+  if (line.kind === 'review') return 'The loop is off, so reviewing finished work is yours.';
+  return null;
+}
+
+/** A refusal's first sentence: what the rule is, without the instructions meant for the agent. */
+const firstSentence = (text) => text.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? text;
+
+/**
+ * Why the lead couldn't approve it itself, from `code-kit approve --delegated`'s refusal: nothing
+ * delegated, or the delegated rules each name it missed ("dep-x: fewer than 1000 weekly downloads").
+ */
+export function limitsWhy(outside) {
+  if (!outside) return null;
+  if (/delegates no approvals/.test(outside))
+    return "You haven't let the lead approve these itself.";
+  const misses = outside
+    .split('\n')
+    .filter((l) => /^\s{2}\S/.test(l))
+    .map((l) => l.trim());
+  return misses.length
+    ? `It's outside the limits you set for the lead: ${misses.join('; ')}.`
+    : null;
+}
+
+/** The story a line belongs to: the held call's or request's lane's story, the stalled story, the queued branch's. */
+function storyOf(line, state) {
+  const stories = state?.stories ?? [];
+  const lane = line.held?.lane ?? line.request?.lane ?? line.stall?.lane ?? null;
+  if (line.story) return stories.find((s) => s.id === line.story.id) ?? line.story;
+  if (line.stall?.story) return stories.find((s) => s.id === line.stall.story) ?? null;
+  if (line.branch) return stories.find((s) => s.branch === line.branch) ?? null;
+  if (lane) {
+    const row = state?.lanes?.find((l) => l.name === lane);
+    if (row?.story) return stories.find((s) => s.id === row.story.id) ?? row.story;
+  }
+  return null;
+}
+
+/**
+ * DECIDE-2: a card for each line that needs the person, in the band's order: { id, kind, title, asked,
+ * story, requirements, doing, settled, why, options }. `context`: { state, status (for requirement
+ * titles), check, goal (the milestone), request (what the person asked for), journal (events),
+ * inForce (approvals in force) }.
+ */
+export function decisionCards(lines, context = {}) {
+  const { state, status, check, goal = null, request = null, journal = [], inForce = [] } = context;
+  const titles = new Map((status?.requirements ?? []).map((r) => [r.id, r.title]));
+  return lines
+    .filter((l) => DECISION_KINDS.has(l.kind) && !l.mission)
+    .map((line, i) => {
+      const story = storyOf(line, state);
+      const lane = line.held?.lane ?? line.request?.lane ?? line.stall?.lane ?? story?.lane ?? null;
+      const settled = [
+        ...journal.filter((e) => story && e.story === story.id).map((e) => e.text),
+        ...inForce
+          .filter((a) => !lane || !a.lane || a.lane === lane)
+          .slice(0, 3)
+          .map(
+            (a) =>
+              `${a.name} is approved${a.lane ? ` for the ${a.lane} lane` : ''}${a.reason ? `: ${a.reason}` : ''}`,
+          ),
+      ].slice(-5);
+      return {
+        id: `${line.kind}-${i}`,
+        kind: line.kind,
+        line,
+        title: line.text,
+        asked: [request, goal].filter(Boolean).join(' · ') || null,
+        story: story
+          ? { id: story.id, title: story.title ?? '', branch: story.branch ?? null }
+          : null,
+        requirements: (story?.requirements ?? []).map((id) => ({
+          id,
+          title: titles.get(id) ?? '',
+        })),
+        doing:
+          line.held?.command ??
+          line.request?.what ??
+          (line.proposal?.label ? `Next step: ${line.proposal.label}` : null),
+        settled,
+        why: whyOf(line, check),
+        options: line.actions.map((a) => ({ ...a, effect: EFFECT[a.id] ?? null })),
+      };
+    });
+}
+
+/** The band's short context for a decision line: "for ST-23 The original panel (ORIG-3)". */
+export function contextOf(card) {
+  if (!card.story) return null;
+  const reqs = card.requirements.map((r) => r.id).join(', ');
+  return `for ${card.story.id} ${card.story.title}${reqs ? ` (${reqs})` : ''}`;
+}