@warren-dean/code-kit 0.12.2 → 0.14.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/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

@@ -22,6 +22,7 @@ export const DECISION_KINDS = new Set([
   'brief',
   'denied',
   'report',
+  'waiting',
 ]);
 
 /** What each answer does, in the person's words. */
@@ -54,6 +55,10 @@ const EFFECT = {
     'Puts it in your prompt after !, so you run it yourself; press Enter to run it, then Done it.',
   deniedDone: 'The lead is told you ran it, or allowed it, and carries on.',
   deniedNo: "The lead is told you won't run it now, and carries on with other work.",
+  answerLead: 'The lead is told your answer and carries on.',
+  answerLeadText: 'Type your answer; the lead is told it and carries on.',
+  askAgain: 'The lead is asked to take this step again now.',
+  carryOn: 'The loop goes on with whatever is next.',
   sendReport:
     "Files it on code-kit's GitHub under your account (a comment instead, if it's filed already).",
   discardReport: "It's not sent, and goes.",
@@ -133,6 +138,18 @@ function optionsOf(line) {
       { id: 'sendReport', label: 'Send' },
       { id: 'discardReport', label: 'Discard' },
     ];
+  // LOOP-11: what the lead waits on, read from its reply: its answers, or the person's own words.
+  if (line.kind === 'waiting' && line.waiting.kind === 'person' && line.waiting.question)
+    return [
+      ...line.waiting.options.map((o, i) => ({
+        id: `answerLead-${i}`,
+        act: 'answerLead',
+        label: o.label,
+        effect: o.effect,
+        line: { ...line, choice: o.label },
+      })),
+      { id: 'answerLeadText', label: line.waiting.options.length ? 'Something else…' : 'Answer…' },
+    ];
   return line.actions;
 }
 
@@ -149,6 +166,7 @@ const TAG = {
   brief: 'your brief',
   denied: 'refused',
   report: 'bug report',
+  waiting: 'the lead',
 };
 
 /** At most `n` characters on one line, cut with an ellipsis. */
@@ -189,7 +207,10 @@ function headlineOf(line, story) {
       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}` };
+    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`,
@@ -197,6 +218,8 @@ function headlineOf(line, story) {
     };
   if (line.kind === 'report')
     return { headline: line.report.title, sub: "drafted by an agent, for code-kit's GitHub" };
+  if (line.kind === 'waiting' && line.waiting.question)
+    return { headline: line.waiting.question, sub: 'from the lead, which waits on it' };
   return { headline: line.text, sub: story ? `${story.id} ${story.title ?? ''}` : '' };
 }
 
@@ -239,9 +262,15 @@ 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 === 'waiting' && line.waiting.kind === 'person')
+    return "The lead's last reply waits on you, so the loop doesn't prompt it again until you answer, here or in the chat.";
+  if (line.kind === 'waiting' && line.waiting.kind === 'stopped')
+    return 'You stopped the lead mid-turn, so the loop leaves the lead to you until you say.';
+  if (line.kind === 'waiting' && line.waiting.kind === 'blocked')
+    return "The lead was asked to take this step and didn't, so the loop won't ask again until you say.";
   if (line.kind === 'report')
     return "code-kit got in an agent's way. It's sent under your GitHub account to a public repository, so read what it says first.";
   return null;
@@ -297,9 +326,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(
@@ -318,7 +349,22 @@ export function decisionCards(lines, context = {}) {
         // 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,
@@ -343,6 +389,7 @@ export function decisionCards(lines, context = {}) {
             : 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.waiting?.label ? `The loop's last step: ${line.waiting.label}` : null) ??
           (line.denial ? clip(line.denial.command ?? line.denial.what, 400) : null) ??
           (line.report ? line.report.body : null),
         settled,
@@ -361,3 +408,51 @@ export function contextOf(card) {
   const reqs = card.requirements.map((r) => r.id).join(', ');
   return `for ${card.story.id} ${card.story.title}${reqs ? ` (${reqs})` : ''}`;
 }
+
+/** DECIDE-4: the kinds of decision settled with a choice, asked in Claude Code's own question dialog. */
+export const NATIVE_KINDS = new Set(['proposal', 'stalled', 'teamStale', 'question', 'waiting']);
+
+/** One sentence ended as a question asks. */
+const asked = (text, question) => `${String(text).replace(/[.\s]+$/, '')}. ${question}`;
+
+/**
+ * DECIDE-4: a decision card as Claude Code's question dialog asks it: { key, question, header, options:
+ * [{ label, act, line }], typed }, or null for one that needs the pane (a reason to give, an answer to
+ * type with no choices offered). An option without `act` leaves the decision where it is; `typed` names
+ * the act that takes the person's own words, typed under the dialog's Other.
+ */
+export function nativeChoice(card) {
+  if (!NATIVE_KINDS.has(card.kind)) return null;
+  const line = card.line;
+  const w = line.waiting;
+  // What the person stopped, or a reply waiting on them with no question in it, is theirs to pick up
+  // in the chat: no dialog over what they're about to type.
+  if (card.kind === 'waiting' && !(w?.kind === 'person' && w.question) && w?.kind !== 'blocked')
+    return null;
+  const options = card.options
+    .filter((o) => !o.label.endsWith('…'))
+    .slice(0, 4)
+    .map((o) => ({ label: o.label, act: o.act ?? o.id, line: o.line ?? line }));
+  if (!options.length) return null;
+  if (options.length === 1) options.push({ label: 'Not now', act: null, line });
+  const question =
+    card.kind === 'proposal' && line.proposal?.first
+      ? asked(line.text, 'How much should it do on its own?')
+      : card.kind === 'proposal' && line.proposal?.repeated
+        ? `${card.why} ${line.text}`
+        : card.kind === 'stalled'
+          ? asked(`${line.text}. ${card.why}`, 'Restart it?')
+          : card.kind === 'teamStale'
+            ? asked(line.text, 'Keep your claim?')
+            : card.kind === 'waiting' && w.kind === 'blocked'
+              ? asked(line.text, 'Ask the lead again?')
+              : card.headline;
+  return {
+    key: `${card.kind}:${card.headline}:${options.map((o) => o.label).join('|')}`,
+    question: /\?$/.test(question) ? question : `${question}?`,
+    header: card.tag.slice(0, 12),
+    options,
+    typed:
+      card.kind === 'question' ? 'answerTyped' : card.kind === 'waiting' ? 'answerLeadTyped' : null,
+  };
+}