@warren-dean/code-kit 0.12.1 → 0.13.0

package/hooks/lib/regression.mjs

@@ -0,0 +1,321 @@
+// Regression (docs/specs/18-regression.md). REG-1: a fix comes with a test that fails without it, as the
+// bug, and passes with it. REG-2: a test isn't weakened (deleted, skipped, cut down, its snapshot
+// rewritten) without the person's `tests` approval, which the lead can't delegate. The commit hook
+// refuses a weakening commit; verify finds what a branch weakened, from git.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { runChecks } from './checks.mjs';
+import { matchesAny } from './glob.mjs';
+import { readStories } from './plan.mjs';
+
+/** The approval that lets a test be weakened: the person's only. */
+export const TESTS_APPROVAL = 'tests';
+
+// Test files by the usual conventions, when the config names none (`tests`).
+const TEST =
+  /(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
+export const SNAPSHOT = /(^|\/)__snapshots__\/|\.snap$/;
+
+/** Whether `rel` is a test: the config's `tests` globs, or the usual conventions. */
+export const isTestFile = (rel, config) =>
+  !rel.endsWith('.md') && (config?.tests?.length ? matchesAny(rel, config.tests) : TEST.test(rel));
+
+// A case's name: it('…') / test('…') in JavaScript, def test_… in Python, func Test… in Go, @Test in JVM.
+const JS_CASE =
+  /\b(?:it|test)(?:\.(?:each\s*\([^)]*\)|concurrent|serial|skip|only|todo|fixme|fails))*\s*\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/g;
+const PY_CASE = /^\s*(?:async\s+)?def\s+(test_\w+)/gm;
+const GO_CASE = /^func\s+(Test\w+)\s*\(/gm;
+const JVM_CASE = /@Test\b[^{;]*?\b(?:void|fun)\s+(\w+)\s*\(/g;
+// Markers that skip or focus a test, so the rest stop running.
+const SKIPS = [
+  /\b(?:it|test|describe|suite|context)\.(?:skip|only|todo|fixme)\s*\(/,
+  /\b(?:xit|xtest|xdescribe|fit|fdescribe)\s*\(/,
+  /@pytest\.mark\.(?:skip|skipif|xfail)\b/,
+  /\bpytest\.skip\s*\(/,
+  /\bunittest\.skip/,
+  /\bt\.Skip(?:f|Now)?\s*\(/,
+  /@(?:Disabled|Ignore)\b/,
+];
+const ASSERTION =
+  /\bexpect\s*\(|\bassert\w*\s*[.(]|\bt\.(?:Error|Errorf|Fatal|Fatalf|Fail)\b|\bshould\.\w/g;
+
+const skipLines = (text) =>
+  String(text ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => SKIPS.some((r) => r.test(l)));
+
+/** What a test file holds: its cases' names, its skip and focus markers, and how many assertions. */
+export function testShape(text) {
+  const t = String(text ?? '');
+  const cases = [
+    ...[...t.matchAll(JS_CASE)].map((m) => m[2]),
+    ...[...t.matchAll(PY_CASE)].map((m) => m[1]),
+    ...[...t.matchAll(GO_CASE)].map((m) => m[1]),
+    ...[...t.matchAll(JVM_CASE)].map((m) => m[1]),
+  ];
+  return { cases, skips: skipLines(t), assertions: (t.match(ASSERTION) ?? []).length };
+}
+
+const clip = (s, n = 70) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+const quoteList = (names) =>
+  names
+    .slice(0, 3)
+    .map((n) => `"${clip(n, 50)}"`)
+    .join(', ') + (names.length > 3 ? ` and ${names.length - 3} more` : '');
+
+/** How `after` weakens `before`, in words; empty when it doesn't. */
+export function weakenings(before, after) {
+  const was = testShape(before);
+  const now = testShape(after);
+  const reasons = [];
+  const old = new Set(was.skips);
+  const added = now.skips.filter((l) => !old.has(l));
+  if (added.length || now.skips.length > was.skips.length)
+    reasons.push(
+      `adds a skip or focus marker${
+        added.length
+          ? ` (${added
+              .slice(0, 2)
+              .map((l) => `\`${clip(l, 60)}\``)
+              .join(', ')})`
+          : ''
+      }`,
+    );
+  if (now.cases.length < was.cases.length) {
+    const left = new Set(now.cases);
+    const gone = was.cases.filter((c) => !left.has(c));
+    reasons.push(
+      `has ${was.cases.length - now.cases.length} fewer test case${was.cases.length - now.cases.length === 1 ? '' : 's'}${gone.length ? ` (${quoteList(gone)} gone)` : ''}`,
+    );
+  } else if (now.assertions < was.assertions)
+    reasons.push(
+      `has ${was.assertions - now.assertions} fewer assertion${was.assertions - now.assertions === 1 ? '' : 's'} (${was.assertions} → ${now.assertions})`,
+    );
+  return reasons;
+}
+
+/**
+ * REG-2: the tests a set of changes weakens: [{ file, reasons }]. `changes` is [{ status: 'A'|'M'|'D',
+ * file, from? }] (from: a rename's old path); `before(path)` and `after(path)` read the two sides, null
+ * when the file isn't there. A deleted test whose cases all reappear in an added one was moved, not cut.
+ */
+export function weakenedTests(changes, before, after, config) {
+  const found = [];
+  const added = changes.filter((c) => c.status === 'A' && isTestFile(c.file, config));
+  for (const c of changes) {
+    const was = c.from ?? c.file;
+    if (SNAPSHOT.test(was) && c.status !== 'A') {
+      if (c.status === 'D' || before(was) !== after(c.file))
+        found.push({
+          file: c.file,
+          reasons: [c.status === 'D' ? 'deletes a snapshot' : 'rewrites a snapshot'],
+        });
+      continue;
+    }
+    if (!isTestFile(was, config) || c.status === 'A') continue;
+    const old = before(was);
+    if (old === null) continue;
+    if (c.status === 'D') {
+      const cases = testShape(old).cases;
+      const moved =
+        cases.length > 0 &&
+        added.some((a) => {
+          const there = new Set(testShape(after(a.file)).cases);
+          return cases.every((n) => there.has(n));
+        });
+      if (!moved)
+        found.push({
+          file: c.file,
+          reasons: [
+            `deletes the test file${cases.length ? ` (${cases.length} case${cases.length === 1 ? '' : 's'})` : ''}`,
+          ],
+        });
+      continue;
+    }
+    const reasons = weakenings(old, after(c.file));
+    if (reasons.length) found.push({ file: c.file, reasons });
+  }
+  return found;
+}
+
+const git = (root, ...args) =>
+  execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+const showAt = (root, ref, rel) => {
+  try {
+    return git(root, 'show', `${ref}:${rel}`);
+  } catch {
+    return null;
+  }
+};
+
+/** REG-2 for a branch: what it weakened since `from` (where it left the base), judged from git. */
+export function branchWeakenings(root, from, config) {
+  const changes = git(root, 'diff', '--name-status', '-M', from, 'HEAD')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      const [status, a, b] = l.split('\t');
+      return status.startsWith('R')
+        ? { status: 'M', from: a, file: b }
+        : { status: status[0] === 'D' ? 'D' : status[0] === 'A' ? 'A' : 'M', file: a };
+    });
+  return weakenedTests(
+    changes,
+    (rel) => showAt(root, from, rel),
+    (rel) => showAt(root, 'HEAD', rel),
+    config,
+  );
+}
+
+/**
+ * REG-2 for a commit about to be made: `files` as the commit hook lists them, HEAD against the
+ * working tree.
+ */
+export function commitWeakenings(root, files, config) {
+  const read = (rel) => {
+    try {
+      return readFileSync(join(root, rel), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+  const changes = files.map((file) => {
+    const was = showAt(root, 'HEAD', file) !== null;
+    const is = existsSync(join(root, file));
+    return { status: !was ? 'A' : is ? 'M' : 'D', file };
+  });
+  return weakenedTests(changes, (rel) => showAt(root, 'HEAD', rel), read, config);
+}
+
+/**
+ * REG-1: what a branch fixes, or null when it isn't a fix: its plan story's `**Fixes:**` line (branch
+ * `<lane>/st-<n>`), or a branch named `<lane>/fix-…`.
+ */
+export function fixOf(root, branch, config) {
+  if (!branch) return null;
+  const story = branch.match(/^[^/]+\/(st-\d+)$/i)?.[1]?.toUpperCase();
+  if (story && config.docs?.plan) {
+    const s = readStories(root, config.docs.plan).find((x) => x.id === story);
+    if (s?.fixes) return { story: s.id, what: s.fixes };
+  }
+  if (/^[^/]+\/fix-/.test(branch))
+    return { story: null, what: branch.split('/').slice(1).join('/').slice(4).replace(/-/g, ' ') };
+  return null;
+}
+
+// A failure that only says the test can't reach what it calls: the fix added it, so it proves nothing.
+const UNREACHABLE =
+  /Cannot find module|is not a function|does not provide an export named|is not exported|has no exported member|error TS2305|error TS2339|error TS2724|error TS2614|ImportError|ModuleNotFoundError|cannot import name|undefined: \w|\[build failed\]|ReferenceError: \w+ is not defined/;
+// Signs a test ran and an assertion failed.
+const ASSERTED =
+  /AssertionError|AssertionFailedError|Expected:|Received:|expected .+ to |toBe|toEqual|assert\w* failed|^\s*--- FAIL|Error: expect\(/m;
+
+/** Whether a failure's output only shows the tests couldn't reach what the fix adds. */
+export const onlyUnreachable = (output) =>
+  UNREACHABLE.test(output) && !ASSERTED.test(output.replace(UNREACHABLE, ''));
+
+// The folders an install puts beside the code, which a fresh checkout lacks.
+const INSTALLS = new Set(['node_modules', '.venv', 'venv']);
+
+/** Links the checkout's installs (node_modules and the like, wherever git ignores them) into `dir`. */
+function linkInstalls(root, dir) {
+  let ignored = [];
+  try {
+    ignored = git(root, 'ls-files', '--others', '--ignored', '--exclude-standard', '--directory')
+      .split('\n')
+      .map((l) => l.replace(/\/$/, ''))
+      .filter((l) => l && INSTALLS.has(basename(l)));
+  } catch {
+    return;
+  }
+  for (const rel of ignored) {
+    const to = join(dir, rel);
+    if (!existsSync(dirname(to)) || existsSync(to)) continue;
+    try {
+      symlinkSync(join(root, rel), to, 'dir');
+    } catch {
+      // the check then says what it couldn't run
+    }
+  }
+}
+
+/**
+ * REG-1: whether a fix's tests prove its bug. In a temporary worktree of the branch (with the
+ * checkout's installs linked in, after `regression.prepare`), the checks covering the tests it added
+ * or changed must pass, and fail, as the bug, once every change outside the tests goes back to `from`.
+ * Problems in words; empty when the tests prove it.
+ */
+export function proveFix({ root, from, base, changed, config, fix }) {
+  const what = `This branch fixes ${fix.what}${fix.story ? ` (${fix.story})` : ''}`;
+  const tests = changed.filter(
+    (f) => isTestFile(f, config) && !SNAPSHOT.test(f) && showAt(root, 'HEAD', f) !== null,
+  );
+  if (!tests.length)
+    return [
+      `${what}, but it adds or changes no test. Add a test that fails without the fix: it's what stops the bug coming back.`,
+    ];
+  const covering = config.checks.filter((c) =>
+    tests.some((f) => matchesAny(f, c.files) && !matchesAny(f, c.exclude)),
+  );
+  if (!covering.length)
+    return [
+      `${what}, but no check runs its tests (${tests.join(', ')}), so code-kit can't show they fail without it. Add a check whose files match them.`,
+    ];
+  const strict = { ...config, checks: covering.map((c) => ({ ...c, ifMissing: 'fail' })) };
+  const actor = { kind: 'lead', label: 'lead' };
+  const dir = mkdtempSync(join(tmpdir(), 'code-kit-fix-'));
+  rmSync(dir, { recursive: true });
+  try {
+    git(root, 'worktree', 'add', '--quiet', '--detach', dir, 'HEAD');
+    linkInstalls(root, dir);
+    const prepare = config.regression?.prepare;
+    if (prepare) {
+      const res = spawnSync(prepare, { cwd: dir, shell: true, encoding: 'utf8', timeout: 900000 });
+      if (res.status !== 0)
+        return [
+          `regression.prepare (\`${prepare}\`) failed in a fresh checkout, so the fix's tests couldn't run:\n${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-20).join('\n')}`,
+        ];
+    }
+    const { failure: withFix } = runChecks(strict, tests, dir, actor);
+    if (withFix)
+      return [
+        `${what}, but its tests don't pass in a fresh checkout of the branch (${withFix.title.replace(/ Fix it:$/, '')}), so code-kit can't tell whether they fail without it. If they need an install or a build first, set regression.prepare.${withFix.output ? `\n${String(withFix.output).trim().split('\n').slice(-20).join('\n')}` : ''}`,
+      ];
+    for (const f of changed) {
+      if (isTestFile(f, config) || SNAPSHOT.test(f)) continue;
+      if (showAt(root, from, f) !== null) git(dir, 'checkout', from, '--', f);
+      else rmSync(join(dir, f), { force: true });
+    }
+    const { failure: without } = runChecks(strict, tests, dir, actor);
+    if (!without)
+      return [
+        `${what}, but its tests (${tests.join(', ')}) also pass without the fix, so they don't prove the bug and it can come back. Write a test that fails on ${base} and passes here.`,
+      ];
+    const output = `${without.title}\n${without.output ?? ''}`;
+    if (onlyUnreachable(output)) {
+      const line =
+        output
+          .split('\n')
+          .find((l) => UNREACHABLE.test(l))
+          ?.trim() ?? '';
+      return [
+        `${what}, but its tests fail without the fix only because they call what the fix adds (${clip(line, 120)}). A test that goes through the existing code fails on an assertion when the bug is there: write that one.`,
+      ];
+    }
+    return [];
+  } finally {
+    try {
+      git(root, 'worktree', 'remove', '--force', dir);
+    } catch {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+}

package/hooks/lib/rules.mjs

@@ -415,6 +415,7 @@ export function openRequests(root, now = Date.now()) {
     // allowed), or the file it named was committed since by someone who could.
     if (r.names.every((n) => grantedSince(root, given, n, r))) continue;
     if (committedSince(root, r)) continue;
+    if (installedSince(root, r)) continue;
     open.push(r);
   }
   return open;
@@ -439,6 +440,39 @@ function grantedSince(root, given, name, r) {
   });
 }
 
+/**
+ * CARD-7: whether every package a dependency request named has since been added to a committed
+ * manifest, on any branch: the install happened (approved, or run by the person themselves), so it no
+ * longer waits.
+ */
+function installedSince(root, r) {
+  if (!r.names.length || !r.names.every((n) => n.startsWith(DEPENDENCY_APPROVAL))) return false;
+  return r.names.every((name) => {
+    const pkg = name.slice(DEPENDENCY_APPROVAL.length).replaceAll('+', '/');
+    try {
+      const out = execFileSync(
+        'git',
+        [
+          '-C',
+          root,
+          'log',
+          '--all',
+          '-1',
+          '--format=%ct',
+          `--since=@${Math.floor(Date.parse(r.at) / 1000)}`,
+          `-S"${pkg}"`,
+          '--',
+          ':(glob)**/package.json',
+        ],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      );
+      return Boolean(out.trim());
+    } catch {
+      return false;
+    }
+  });
+}
+
 /** Whether the file a request named has been committed, on any branch, since it was asked. */
 function committedSince(root, r) {
   const path = String(r.what);

package/hooks/lib/verify.mjs

@@ -10,6 +10,7 @@ import { CONFIG_FILE } from './config.mjs';
 import { isDependencyFile } from './dependencies.mjs';
 import { matchesAny } from './glob.mjs';
 import { layerProblems } from './layers.mjs';
+import { TESTS_APPROVAL, branchWeakenings, fixOf, proveFix } from './regression.mjs';
 import {
   APPROVAL_LOG,
   SECRETS,
@@ -152,17 +153,46 @@ function historySecrets(root, from, changed) {
   return problems;
 }
 
+/** The branch checked out at `root`, or null when HEAD is detached. */
+function currentBranchOf(root) {
+  try {
+    const name = git(root, 'rev-parse', '--abbrev-ref', 'HEAD').trim();
+    return name === 'HEAD' ? null : name;
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Every problem with the branch, grouped: { ownership, protected, layers, baseline, design, checks }.
- * `lane` holds the branch to that lane's paths; `checks: false` leaves the project's checks to CI's
- * own steps.
+ * The files changed, every problem with the branch, grouped as { ownership, protected, layers,
+ * baseline, design, tests, regression, checks }, and the checks `skipped` because a tool isn't
+ * installed. `lane` holds the branch to that lane's paths; `checks: false` leaves the project's
+ * checks to CI's own steps. `fixes` runs a fix's tests without the fix (REG-1; with the
+ * checks unless said); `branch` names the branch when the checkout is detached.
  */
-export function verifyBranch({ root, base, config, lane = null, checks = true }) {
+export function verifyBranch({
+  root,
+  base,
+  config,
+  lane = null,
+  checks = true,
+  fixes = checks,
+  branch = null,
+}) {
   // Where the branch left the base: the base may have moved on since (new log entries, a smaller baseline).
   const from = git(root, 'merge-base', base, 'HEAD').trim();
   const changed = branchChanges(root, base);
   const present = changed.filter((f) => existsSync(join(root, f)));
-  const found = { ownership: [], protected: [], layers: [], baseline: [], design: [], checks: [] };
+  const found = {
+    ownership: [],
+    protected: [],
+    layers: [],
+    baseline: [],
+    design: [],
+    tests: [],
+    regression: [],
+    checks: [],
+  };
   const { entries, problems: logProblems } = logEntries(root, from);
   found.protected.push(...logProblems);
   const logged = new Map(entries.map((e) => [e.file, e]));
@@ -235,11 +265,27 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
           found.baseline.push(`${BASELINE_FILE} gained ${p}; it only shrinks.`);
   }
 
+  // REG-2: a test weakened on the branch needs the person's `tests` approval, logged by the commit.
+  for (const w of branchWeakenings(root, from, config)) {
+    const approved = entries.some((e) => e.file === w.file && e.approval === TESTS_APPROVAL);
+    if (!approved)
+      found.tests.push(
+        `${w.file} ${w.reasons.join(', and ')}. A weakened test can hide a regression, so it needs the person's tests approval, which the commit records in ${APPROVAL_LOG}. Restore the test and fix the code, or ask the person.`,
+      );
+  }
+
+  // REG-1: a fix's tests fail without it, as the bug.
+  const fix = fixes ? fixOf(root, branch ?? currentBranchOf(root), config) : null;
+  if (fix) found.regression.push(...proveFix({ root, from, base, changed, config, fix }));
+
+  let skipped = [];
   if (checks) {
     const actor = lane
       ? { kind: 'lane', lane, label: `${lane} lane branch` }
       : { kind: 'lead', label: 'lead' };
-    const failure = runChecks(config, changed, root, actor);
+    const ran = runChecks(config, changed, root, actor);
+    skipped = ran.skipped;
+    const { failure } = ran;
     if (failure)
       found.checks.push(
         `${failure.title}\n${String(failure.output ?? '')
@@ -248,5 +294,5 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
           .join('\n')}`.trim(),
       );
   }
-  return { changed, found };
+  return { changed, found, skipped };
 }

package/hooks/mod/decisions.mjs

@@ -2,7 +2,7 @@
 // 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.
-import { askWords } from './view.mjs';
+import { approvalLabel, askWords, commandItself } from './view.mjs';
 
 /** The kinds of band line that are the person's to decide; the rest are notes. */
 export const DECISION_KINDS = new Set([
@@ -136,6 +136,73 @@ function optionsOf(line) {
   return line.actions;
 }
 
+/** A kind of decision as its card's tag says it. */
+const TAG = {
+  held: 'held call',
+  approvals: 'approval',
+  stalled: 'stalled',
+  proposal: 'next step',
+  queue: 'merge',
+  review: 'review',
+  notice: 'notice',
+  question: 'question',
+  brief: 'your brief',
+  denied: 'refused',
+  report: 'bug report',
+};
+
+/** At most `n` characters on one line, cut with an ellipsis. */
+const clip = (text, n) => {
+  const one = String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+};
+
+/** Names as a person reads them, at most three, then how many more. */
+const someNames = (names) => {
+  const shown = names.slice(0, 3).map(approvalLabel).join(', ');
+  return names.length > 3 ? `${shown} and ${names.length - 3} more` : shown;
+};
+
+/**
+ * CARD-9: a decision's headline and the line under it, short enough for a card in a list:
+ * { tag, headline, sub }.
+ */
+function headlineOf(line, story) {
+  const forStory = story ? ` · ${story.id}` : '';
+  if (line.kind === 'approvals') {
+    const who = line.request.lane ? `the ${line.request.lane} lane` : line.request.actor;
+    return {
+      headline: `Approve ${someNames(line.request.names)}`,
+      sub: `for ${who}${forStory} · ${clip(commandItself(line.files?.[0] ?? line.request.what), 70)}`,
+    };
+  }
+  if (line.kind === 'held')
+    return {
+      headline: `${line.held.who} wants to ${line.text.replace(/^.*? wants to /, '').replace(/ · \d+:\d+$/, '')}`,
+      sub: `held${forStory} · ${line.text.match(/\d+:\d+$/)?.[0] ?? ''} left`,
+    };
+  if (line.kind === 'question')
+    return {
+      headline: line.question.question,
+      sub: `from the lead${forStory}${line.question.blocks ? ', which waits on it' : ''}`,
+    };
+  if (line.kind === 'brief')
+    return {
+      headline: line.brief.question,
+      sub: `open in ${line.brief.path}${line.brief.blocks ? ` · holds up ${line.brief.blocks}` : ''}`,
+    };
+  if (line.kind === 'denied')
+    return {
+      headline: `Claude Code refused ${line.denial.who}'s call`,
+      sub: clip(line.denial.command ?? line.denial.what, 80),
+    };
+  if (line.kind === 'report')
+    return { headline: line.report.title, sub: "drafted by an agent, for code-kit's GitHub" };
+  return { headline: line.text, sub: story ? `${story.id} ${story.title ?? ''}` : '' };
+}
+
 /** Why a line needs the person, when the line itself doesn't say. */
 function whyOf(line, check) {
   if (line.kind === 'held') {
@@ -175,7 +242,7 @@ function whyOf(line, check) {
       "The lead can't settle this itself: it's yours to decide, and the lead builds on your answer."
     );
   if (line.kind === 'brief')
-    return `It's an open question in ${line.brief.path}: what gets built depends on your answer.`;
+    return `It's an open question in ${line.brief.path}, left for you: what gets built depends on your answer. Not sure what it means? Ask about it when you answer.`;
   if (line.kind === 'denied')
     return `Claude Code's own permission check refused it${line.denial.reason ? ` (${line.denial.reason})` : ''}, which code-kit can't approve past: only you can run it or allow it.`;
   if (line.kind === 'report')
@@ -233,9 +300,11 @@ export function decisionCards(lines, context = {}) {
     .map(({ source, line }, i) => {
       const story = storyOf(line, state);
       const lane = line.held?.lane ?? line.request?.lane ?? line.stall?.lane ?? story?.lane ?? null;
+      // Approvals in force bear on an approval or a held call, not on a question about the product.
+      const aboutApprovals = ['held', 'approvals', 'stalled'].includes(line.kind);
       const settled = [
         ...journal.filter((e) => story && e.story === story.id).map((e) => e.text),
-        ...inForce
+        ...(aboutApprovals ? inForce : [])
           .filter((a) => !lane || !a.lane || a.lane === lane)
           .slice(0, 3)
           .map(
@@ -243,14 +312,33 @@ export function decisionCards(lines, context = {}) {
               `${a.name} is approved${a.lane ? ` for the ${a.lane} lane` : ''}${a.reason ? `: ${a.reason}` : ''}`,
           ),
       ].slice(-5);
+      const { headline, sub } = headlineOf(line, story);
       return {
         id: `${line.kind}-${i}`,
         kind: line.kind,
+        tag: TAG[line.kind] ?? 'decision',
+        headline: clip(headline, 100),
+        sub,
         line,
         // The band line it came from: one line can stand for several decisions (CARD-8).
         source,
         title: line.text,
-        asked: [request, goal].filter(Boolean).join(' · ') || null,
+        // CARD-9: what they asked for in a line (the brief's title, not its whole problem).
+        asked:
+          [request && clip(firstSentence(request), 140), goal].filter(Boolean).join(' · ') || null,
+        // The question itself, and the brief's own columns for it (who decides, what it holds up).
+        details: [
+          ...(line.kind === 'brief'
+            ? [
+                { label: 'Question', value: line.brief.question },
+                ...(line.brief.owner ? [{ label: 'Who decides', value: line.brief.owner }] : []),
+                ...(line.brief.blocks ? [{ label: 'Holds up', value: line.brief.blocks }] : []),
+              ]
+            : []),
+          ...(line.kind === 'question'
+            ? [{ label: 'Question', value: line.question.question }]
+            : []),
+        ],
         story: story
           ? { id: story.id, title: story.title ?? '', branch: story.branch ?? null }
           : null,
@@ -260,14 +348,22 @@ export function decisionCards(lines, context = {}) {
         })),
         doing:
           line.held?.command ??
-          (line.request ? askWords(line.request, line.files ?? [line.request.what]) : null) ??
+          (line.request
+            ? clip(
+                askWords(
+                  line.request,
+                  (line.files ?? [line.request.what]).map((f) => commandItself(f)),
+                ),
+                300,
+              )
+            : null) ??
           (line.proposal?.label ? `Next step: ${line.proposal.label}` : null) ??
           (line.intent
             ? `Intent #${line.intent.id}: ${line.intent.about}${line.intent.touches.length ? ` (touches ${line.intent.touches.join(', ')})` : ''}`
             : null) ??
           (line.pull ? `Pull request #${line.pull.number} on ${line.pull.branch}` : null) ??
           (line.question?.blocks ? `${line.question.story} waits on your answer.` : null) ??
-          (line.denial ? (line.denial.command ?? line.denial.what) : null) ??
+          (line.denial ? clip(line.denial.command ?? line.denial.what, 400) : null) ??
           (line.report ? line.report.body : null),
         settled,
         why: whyOf(line, check),

package/hooks/mod/loop.mjs

@@ -75,7 +75,7 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
   // 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.`
+      ? `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; a branch that moved after its review leaves the queue for you to review again.`
       : null;
   // SETUP-2: the base has no rules yet; the lead puts the approved ones there, then merges as usual.
   if (step.step === 'rules')