@warren-dean/code-kit 0.6.0 → 0.8.0

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})` : ''}`;
+}

package/hooks/mod/loop.mjs

@@ -0,0 +1,68 @@
+// The lead loop (spec 05), the pure parts: what to prompt the lead with for a step `code-kit next`
+// reports, and what a quiet lane agent is due. The mod watches and prompts; the lead acts, with the
+// existing skills, and the hooks judge every call as before.
+
+/** The steps the loop hands the lead; the rest (spec-design, init, check) wait for the person. */
+const LEAD_STEPS = new Set(['dispatch', 'review', 'lead', 'merge']);
+
+/**
+ * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
+ * take. Every ready story is named: the dispatch skill decides how many lanes go (LOOP-2). A prompt
+ * names the skill rather than starting with it: Claude Code refuses a mod's prompt that begins with
+ * `/`, which would run a command as the person.
+ */
+export function leadPrompt(step, { cli = 'code-kit' } = {}) {
+  if (!step || !LEAD_STEPS.has(step.step)) return null;
+  const ids = (step.args ?? '').split(/\s+/).filter(Boolean);
+  // MQ-2: the head of the merge queue, where the lead merges within the delegated rules.
+  if (step.step === 'merge')
+    return ids.length
+      ? `Merge ${ids[0]}, next in the merge queue: run node "${cli}" queue merge --delegated. It verifies the branch against the base as it is now, and sends it back to its lane if it conflicts or fails.`
+      : null;
+  if (step.step === 'dispatch')
+    return ids.length
+      ? `Dispatch ${ids.join(', ')}: run /code-kit:dispatch ${ids.join(' ')}.`
+      : null;
+  // The review skill takes one story, or none for every story in review.
+  if (step.step === 'review')
+    return ids.length === 1
+      ? `Review ${ids[0]}: run /code-kit:review ${ids[0]}.`
+      : `Review ${ids.join(', ')}: run /code-kit:review.`;
+  if (!ids.length) return null;
+  const branches = ids.map((id) => `lead/${id.toLowerCase()}`).join(', ');
+  return `Build ${ids.join(', ')} yourself: ${ids.length === 1 ? "it is the lead's own story" : "they are the lead's own stories"}. Work on ${branches}, then review ${ids.length === 1 ? 'it' : 'them'} like any branch.`;
+}
+
+/** A step's identity: the loop never submits the same step twice while the project stands still. */
+export const stepKey = (step) => `${step.step}:${step.args ?? ''}`;
+
+/** The band's words for a step (LOOP-5): "Dispatch ST-7, ST-9". */
+export function stepLabel(step) {
+  const ids = (step.args ?? '').split(/\s+/).filter(Boolean).join(', ');
+  const verb =
+    { dispatch: 'Dispatch', review: 'Review', lead: 'Build', merge: 'Merge' }[step.step] ??
+    step.step;
+  return ids ? `${verb} ${ids}` : verb;
+}
+
+/**
+ * What a lane agent with no tool call for `quietMs` is due (LOOP-3): 'nudge' at stall.nudgeMinutes,
+ * 'restart' at stall.restartMinutes, 'flag' once its story has been restarted stall.maxRestarts
+ * times, or null. `agent` holds what was done already: { nudged, stopped }.
+ */
+export function stallDue(quietMs, agent, restarts, stall) {
+  const minutes = quietMs / 60000;
+  if (minutes >= stall.restartMinutes && !agent.stopped)
+    return restarts >= stall.maxRestarts ? 'flag' : 'restart';
+  if (minutes >= stall.nudgeMinutes && !agent.nudged) return 'nudge';
+  return null;
+}
+
+/** The lead's prompt to stop a stalled agent and dispatch its story again (LOOP-3). */
+export function restartPrompt({ type, id, story, minutes }) {
+  return `${type} (agent ${id}) on ${story} has made no tool call for ${minutes} minutes. Stop it with TaskStop, then dispatch ${story} again with the same brief on the same branch: /code-kit:dispatch ${story}`;
+}
+
+/** The message a quiet agent gets (LOOP-3). */
+export const nudgeText = (minutes) =>
+  `No tool call for ${minutes} minutes: report where you are, or carry on.`;

package/hooks/mod/mission.mjs

@@ -0,0 +1,116 @@
+// The mission band (docs/specs/14-mission-and-maps.md, MISSION-1 to MISSION-3), the pure parts: the
+// goal, what the lead is doing now, the loop's next step, each agent at work with its tool, and a line
+// from another tool only when it has something to say. The band draws these above what needs the person.
+import { stepLabel } from './loop.mjs';
+
+/**
+ * MISSION-1: the milestone being built: the plan's first milestone with a story not done (else its
+ * last), with how many of its stories are done: { name, done, total }, or null when the plan has none.
+ */
+export function goalOf(stories = []) {
+  const named = stories.filter((s) => s.milestone);
+  if (!named.length) return null;
+  const open = named.find((s) => s.state !== 'done') ?? named.at(-1);
+  const mine = named.filter((s) => s.milestone === open.milestone);
+  return {
+    name: open.milestone,
+    done: mine.filter((s) => s.state === 'done').length,
+    total: mine.length,
+  };
+}
+
+/** The words for the loop's next step, from `code-kit next --json`. */
+export function nextText(step) {
+  if (!step) return null;
+  if (step.step === 'done') return 'nothing: every story is done';
+  if (step.step === 'wait') return `waiting: ${step.why}`;
+  const then = (step.then ?? []).map((t) => stepLabel(t));
+  const label = ['spec-design', 'init', 'check'].includes(step.step)
+    ? `${step.step} (yours to run)`
+    : stepLabel(step);
+  return `${label}${then.length ? `, then ${then.join(', ')}` : ''}`;
+}
+
+/** At most this many agents get a line of their own; the rest are counted. */
+const AGENT_LINES = 5;
+
+/**
+ * MISSION-1 to MISSION-3: the band's mission rows, or none while nothing is happening (no lead turn,
+ * no agent at work, the loop not started). Each row is { kind, mission: true, label, text, ... }:
+ * goal; now (with Pause or Resume while the loop runs); next; agents, with one entry per lane at work
+ * ({ lane, tool, ago, level }); and a line per adapter fact worth the person's attention.
+ */
+export function missionLines({
+  state,
+  loop = null,
+  leadBusy = false,
+  live = {},
+  nextStep = null,
+  combined = null,
+}) {
+  if (state?.kind !== 'ok') return [];
+  const working = state.lanes.filter((l) => l.name !== 'lead' && l.active && live[l.name]);
+  const loopOn = Boolean(loop?.started) && !['off', 'stopped'].includes(loop?.state);
+  if (!leadBusy && !working.length && !loopOn) return [];
+  const rows = [];
+  const goal = goalOf(state.stories);
+  if (goal)
+    rows.push({
+      kind: 'goal',
+      label: 'goal',
+      text: `${goal.name} · ${goal.done} of ${goal.total} ${goal.total === 1 ? 'story' : 'stories'} done`,
+    });
+  const lead = leadBusy
+    ? `lead ${live.lead?.tool ? `at work: ${live.lead.tool}` : 'at work'}`
+    : 'lead idle';
+  const loopWord =
+    loop?.state === 'paused'
+      ? 'loop paused'
+      : loop?.state === 'off'
+        ? 'loop off'
+        : loop?.state === 'done'
+          ? 'milestone done'
+          : loopOn
+            ? `loop ${loop.autonomy === 'propose' ? 'proposing' : 'on'}${loop.last ? ` · last: ${loop.last}` : ''}`
+            : null;
+  rows.push({
+    kind: 'now',
+    label: 'now',
+    text: [lead, loopWord].filter(Boolean).join(' · '),
+    actions:
+      loop?.state === 'paused'
+        ? [{ id: 'resume', label: 'Resume' }]
+        : loopOn && loop?.state === 'running'
+          ? [{ id: 'pause', label: 'Pause' }]
+          : [],
+  });
+  const next = nextText(nextStep);
+  if (next && loop?.state !== 'done') rows.push({ kind: 'next', label: 'next', text: next });
+  if (working.length)
+    rows.push({
+      kind: 'agents',
+      label: 'agents',
+      text: `${working.length} at work`,
+      agents: working.slice(0, AGENT_LINES).map((l) => ({
+        lane: l.name,
+        tool: live[l.name].tool,
+        ago: live[l.name].ago,
+        level: live[l.name].level ?? null,
+      })),
+      more: Math.max(0, working.length - AGENT_LINES),
+    });
+  // MISSION-3: another tool's line only when it isn't zero: edits made before the file was understood.
+  const unread = Object.entries(combined ?? {}).filter(([, f]) => f.without > 0);
+  if (unread.length)
+    rows.push({
+      kind: 'facts',
+      label: 'context',
+      text: unread
+        .map(
+          ([lane, f]) =>
+            `${lane} edited ${f.without} file${f.without === 1 ? '' : 's'} without understanding ${f.without === 1 ? 'it' : 'them'}`,
+        )
+        .join(' · '),
+    });
+  return rows.map((r) => ({ actions: [], ...r, mission: true }));
+}