@warren-dean/code-kit 0.12.2 → 0.13.0

package/hooks/mod/register.test.ts

@@ -160,6 +160,7 @@ function project() {
     questions: [] as any[], // `code-kit ask --json`
     reports: [] as any[], // `code-kit report --json`
     fills: [] as string[], // what the mod put in the prompt
+    leadBusy: false, // prompts are queued behind the lead's turn, and never resolve in the test
     sideAsks: [] as any[], // side calls: { fork } or { model }, with their prompt
     sideReply: { isAnswered: true, text: 'dayjs formats the booking dates.', usage: null } as any,
     holdWaits: false, // false: the hold ends at once, as if timed out (tests about cards, not hold)
@@ -392,6 +393,8 @@ function stub(on: any, w: World) {
   );
   on('prompt.submit', ($: any, e: any) => {
     w.prompts.push(e.text);
+    // A busy lead: the prompt is queued, and its turn doesn't end while the test looks.
+    if (w.leadBusy) return new Promise(() => {});
     return { text: e.text };
   });
   // $.ui.ask is the AskUserQuestion dialog: the person picks a label.
@@ -663,7 +666,7 @@ test("ACT-5 the person asks about an approval in its pane; the answer stays ther
   const confirm = await pane($, APPROVE);
   await $.ui.input({
     plugin: 'code-kit',
-    key: 'approve-ask',
+    key: 'ask-about',
     text: 'Why does the booking form need this?',
   });
   expect(w.sideAsks).toHaveLength(1);
@@ -679,7 +682,7 @@ test("ACT-5 the person asks about an approval in its pane; the answer stays ther
     /dayjs formats the booking dates/,
   );
   // A follow-up carries the aside so far; nothing went to the lead, and nothing was approved.
-  await $.ui.input({ plugin: 'code-kit', key: 'approve-ask', text: 'Is it maintained?' });
+  await $.ui.input({ plugin: 'code-kit', key: 'ask-about', text: 'Is it maintained?' });
   expect(w.sideAsks[1].prompt).toMatch(
     /Q: Why does the booking form need this\?\nA: dayjs formats the booking dates\./,
   );
@@ -697,7 +700,7 @@ test('ACT-5 before the lead has replied there is nothing to fork: it answers fro
   const ui = await bandUi($);
   await press($, 'band-approve');
   const confirm = await pane($, APPROVE);
-  await $.ui.input({ plugin: 'code-kit', key: 'approve-ask', text: 'What is it?' });
+  await $.ui.input({ plugin: 'code-kit', key: 'ask-about', text: 'What is it?' });
   expect(w.sideAsks.map((a) => a.model ?? 'fork')).toEqual(['fork', 'sonnet']);
   expect(JSON.stringify(await confirm.find({ key: 'aside-a-0' }))).toMatch(/From the facts alone/);
   await confirm.unmount();
@@ -1319,7 +1322,7 @@ test('HOLD-1 and HOLD-2 a lane installing a new package is held, and the band as
   const w = project();
   w.refusal = webInstall;
   const clock = await start($, on, w);
-  await heldCall($, w, clock);
+  const { call } = await heldCall($, w, clock);
   let ui = await bandUi($);
   expect(
     await ui.find({ type: 'Text', text: /^web wants to install dayjs · 2:00$/ }),
@@ -1332,6 +1335,8 @@ test('HOLD-1 and HOLD-2 a lane installing a new package is held, and the band as
   expect(await ui.find({ type: 'Text', text: /· 1:53$/ })).toBeDefined();
   await ui.unmount();
   w.waiting.get('tu-h1')?.('timed out');
+  // A timed-out hold refuses the call, as the hooks did; awaited, so the test doesn't end mid-call.
+  expect(refused(await call)).toBe(true);
 });
 
 test('DECIDE-2 a decision in the band says which story it is for, and d opens it as a card with its lineage', async ($, on) => {
@@ -1353,7 +1358,7 @@ test('DECIDE-2 a decision in the band says which story it is for, and d opens it
   w.agents = [{ id: 'a1', type: 'web-engineer', description: 'ST-4', status: 'running' }];
   const clock = await start($, on, w);
   await lanes($);
-  await heldCall($, w, clock);
+  const { call } = await heldCall($, w, clock);
   const band = await bandUi($);
   expect(await band.find({ type: 'Text', text: 'for ST-4 Booking form (BOOK-1)' })).toBeDefined();
   expect((await band.find({ key: 'band-decide' }))?.props.hotkey).toBe('d');
@@ -1373,6 +1378,8 @@ test('DECIDE-2 a decision in the band says which story it is for, and d opens it
   );
   await ui.unmount();
   w.waiting.get('tu-h1')?.('timed out');
+  // A timed-out hold refuses the call, as the hooks did; awaited, so the test doesn't end mid-call.
+  expect(refused(await call)).toBe(true);
 });
 
 test('DECIDE-3 an option on the card answers the decision, as the band would', async ($, on) => {
@@ -1538,6 +1545,92 @@ test("ASK-4 the brief's open questions are the person's decisions: answered to t
   await after.unmount();
 });
 
+test("ASK-5 a brief's question shows as a question, with who decides and what it holds up, and can be asked about before answering", async ($, on) => {
+  const w = project();
+  w.next = {
+    ...w.next,
+    brief: [
+      {
+        question: 'Product domain (for the inbound email address and the privacy policy URL).',
+        owner: 'Product owner',
+        blocks: 'CAP-1 (M2)',
+        path: 'docs/brief.md',
+      },
+    ],
+  };
+  w.requests = [];
+  w.inForce = [{ name: 'dep-rrule', lane: 'domain', reason: 'rrule', minutesLeft: 50 }];
+  w.journal = {
+    events: [
+      {
+        at: 1,
+        kind: 'request',
+        text: 'You asked for “My Aila”: a household’s default parent carries the mental load. Things get missed.',
+      },
+    ],
+  };
+  await start($, on, w);
+  const band = await bandUi($);
+  await press($, 'band-openDecision');
+  await band.unmount();
+  const ui = await pane($, PANE);
+  expect(await ui.find({ type: 'Text', text: 'An open question in your brief' })).toBeDefined();
+  expect(
+    await ui.find({
+      type: 'Text',
+      text: 'Product domain (for the inbound email address and the privacy policy URL).',
+    }),
+  ).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: 'Product owner' })).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: 'CAP-1 (M2)' })).toBeDefined();
+  // What they asked for in a line, and no approvals that have nothing to do with it.
+  expect(
+    await ui.find({
+      type: 'Text',
+      text: '“My Aila”: a household’s default parent carries the mental load.',
+    }),
+  ).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: /dep-rrule/ })).toBeUndefined();
+  await press($, 'decide-answerBrief', PANE);
+  const box = await pane($, 'code-kit-answer');
+  await $.ui.input({ plugin: 'code-kit', key: 'ask-about', text: 'What is this for?' });
+  expect(w.sideAsks[0].prompt).toMatch(/An open question in docs\/brief\.md:\n- Product domain/);
+  expect(w.sideAsks[0].prompt).toMatch(/what it holds up: CAP-1 \(M2\)/);
+  expect(JSON.stringify(await box.find({ key: 'aside-a-0' }))).toMatch(
+    /dayjs formats the booking dates/,
+  );
+  expect(w.prompts).toEqual([]);
+  await box.unmount();
+  await ui.unmount();
+});
+
+test('ASK-2 and ASK-4 an answer closes its decision at once, though the lead hears it only when its turn ends', async ($, on) => {
+  const w = project();
+  w.leadBusy = true;
+  w.questions = [question({ options: [] })];
+  w.next = { ...w.next, brief: [{ question: 'The product domain', path: 'docs/brief.md' }] };
+  await start($, on, w);
+  const band = await bandUi($);
+  await press($, 'band-openDecision');
+  await band.unmount();
+  const ui = await pane($, PANE);
+  await press($, 'decide-answer', PANE);
+  let box = await pane($, 'code-kit-answer');
+  await $.ui.input({ plugin: 'code-kit', key: 'answer-text', text: 'The Bureau' });
+  await box.unmount();
+  expect(w.closed).toContain('code-kit-answer');
+  expect(await ui.find({ type: 'Text', text: /Which weather provider/ })).toBeUndefined();
+  await press($, 'decide-answerBrief', PANE);
+  box = await pane($, 'code-kit-answer');
+  await $.ui.input({ plugin: 'code-kit', key: 'answer-text', text: 'myaila.com.au' });
+  await box.unmount();
+  expect(w.prompts).toHaveLength(2);
+  expect(
+    await ui.find({ type: 'Text', text: 'Nothing needs you. The lead is handling the build.' }),
+  ).toBeDefined();
+  await ui.unmount();
+});
+
 test("PERM-1 a call Claude Code's own permission check refused waits for the person, who runs it or says not now", async ($, on) => {
   const w = project();
   await start($, on, w);
@@ -1829,9 +1922,11 @@ test('HOLD-5 with autonomy propose the delegated rules are not tried; the call i
   w.delegateExit = 0;
   (w.check as any).harness = { autonomy: 'propose', hold: { minutes: 2 } };
   const clock = await start($, on, w);
-  await heldCall($, w, clock);
+  const { call } = await heldCall($, w, clock);
   expect(w.delegated).toEqual([]);
   w.waiting.get('tu-h1')?.('timed out');
+  // A timed-out hold refuses the call, as the hooks did; awaited, so the test doesn't end mid-call.
+  expect(refused(await call)).toBe(true);
 });
 
 test('HOLD-6 with nobody to ask, or hold off, the call is refused at once', async ($, on) => {
@@ -2067,43 +2162,51 @@ test('LOOP-6 the pause is recorded for other tools, and a new session starts wit
   ]);
 });
 
-test('LOOP-3 a quiet lane agent is nudged at 5 minutes, restarted through the lead at 10, and flagged after 2 restarts', async ($, on) => {
-  const w = project();
-  w.next = { step: 'wait', args: '', then: [] };
-  w.agents = [
-    { id: 'a1', type: 'web-engineer', description: 'ST-4 booking form', status: 'running' },
-  ];
-  const clock = await start($, on, w);
-  // First seen at the next look (2 s), so quiet for 5 minutes a look later.
-  await clock.advance(5 * 60000 + 2000);
-  expect(w.sent).toEqual([
-    {
-      to: 'a1',
-      text: 'No tool call for 5 minutes: report where you are, or carry on.',
-    },
-  ]);
-  await lanes($);
-  let ui = await pane($, PANE);
-  expect((await ui.find({ key: 'lane-web' }))?.text).toMatch(/nudged/);
-  await ui.unmount();
-  await clock.advance(5 * 60000);
-  expect(w.prompts[0]).toMatch(
-    /^web-engineer \(agent a1\) on ST-4 has made no tool call for 10 minutes\. Stop it with TaskStop.*\/code-kit:dispatch ST-4$/,
-  );
-  ui = await pane($, PANE);
-  expect((await ui.find({ key: 'lane-web' }))?.text).toMatch(/restarted 1\/2/);
-  await ui.unmount();
-  // The lane's agent is started again, and stalls again, twice more.
-  for (const id of ['a2', 'a3']) {
-    w.agents = [{ id, type: 'web-engineer', description: 'ST-4 booking form', status: 'running' }];
-    await clock.advance(10 * 60000 + 2000);
-  }
-  expect(w.prompts).toHaveLength(2);
-  const band = await bandUi($);
-  expect(await band.find({ type: 'Text', text: 'web stalled 3 times on ST-4' })).toBeDefined();
-  expect(await band.find({ key: 'band-resumeStall' })).toBeDefined();
-  await band.unmount();
-});
+// It steps the clock through tens of minutes of the mod's 2-second refresh, each tick a real round of
+// stubbed CLI runs: about 1.5 to 3 seconds locally, and more on a shared CI runner.
+test(
+  'LOOP-3 a quiet lane agent is nudged at 5 minutes, restarted through the lead at 10, and flagged after 2 restarts',
+  { timeoutMs: 30000 },
+  async ($, on) => {
+    const w = project();
+    w.next = { step: 'wait', args: '', then: [] };
+    w.agents = [
+      { id: 'a1', type: 'web-engineer', description: 'ST-4 booking form', status: 'running' },
+    ];
+    const clock = await start($, on, w);
+    // First seen at the next look (2 s), so quiet for 5 minutes a look later.
+    await clock.advance(5 * 60000 + 2000);
+    expect(w.sent).toEqual([
+      {
+        to: 'a1',
+        text: 'No tool call for 5 minutes: report where you are, or carry on.',
+      },
+    ]);
+    await lanes($);
+    let ui = await pane($, PANE);
+    expect((await ui.find({ key: 'lane-web' }))?.text).toMatch(/nudged/);
+    await ui.unmount();
+    await clock.advance(5 * 60000);
+    expect(w.prompts[0]).toMatch(
+      /^web-engineer \(agent a1\) on ST-4 has made no tool call for 10 minutes\. Stop it with TaskStop.*\/code-kit:dispatch ST-4$/,
+    );
+    ui = await pane($, PANE);
+    expect((await ui.find({ key: 'lane-web' }))?.text).toMatch(/restarted 1\/2/);
+    await ui.unmount();
+    // The lane's agent is started again, and stalls again, twice more.
+    for (const id of ['a2', 'a3']) {
+      w.agents = [
+        { id, type: 'web-engineer', description: 'ST-4 booking form', status: 'running' },
+      ];
+      await clock.advance(10 * 60000 + 2000);
+    }
+    expect(w.prompts).toHaveLength(2);
+    const band = await bandUi($);
+    expect(await band.find({ type: 'Text', text: 'web stalled 3 times on ST-4' })).toBeDefined();
+    expect(await band.find({ key: 'band-resumeStall' })).toBeDefined();
+    await band.unmount();
+  },
+);
 
 test('LOOP-3 an agent whose work is done is never nudged or restarted: it handed back, or its branch waits in the merge queue', async ($, on) => {
   const w = project();
@@ -2150,24 +2253,30 @@ test('LOOP-3 until the person has chosen how hands-off the loop is, a restart is
   await band.unmount();
 });
 
-test('LOOP-3 an agent waiting on a held call (or running a long command) is never quiet', async ($, on) => {
-  const w = project();
-  w.next = { step: 'wait', args: '', then: [] };
-  w.refusal = webInstall;
-  (w.check as any).harness = { hold: { minutes: 10 } };
-  w.agents = [{ id: 'a1', type: 'web-engineer', description: 'ST-4', status: 'running' }];
-  const clock = await start($, on, w);
-  const { call } = await heldCall($, w, clock);
-  await clock.advance(6 * 60000);
-  expect(w.sent).toEqual([]);
-  w.waiting.get('tu-h1')?.('timed out');
-  await call;
-  // Its quiet time starts again when the call ends: nudged 5 minutes after, not at once.
-  await clock.advance(2000);
-  expect(w.sent).toEqual([]);
-  await clock.advance(5 * 60000);
-  expect(w.sent.map((m) => m.to)).toEqual(['a1']);
-});
+// It steps the clock through tens of minutes of the mod's 2-second refresh, each tick a real round of
+// stubbed CLI runs: about 1.5 to 3 seconds locally, and more on a shared CI runner.
+test(
+  'LOOP-3 an agent waiting on a held call (or running a long command) is never quiet',
+  { timeoutMs: 30000 },
+  async ($, on) => {
+    const w = project();
+    w.next = { step: 'wait', args: '', then: [] };
+    w.refusal = webInstall;
+    (w.check as any).harness = { hold: { minutes: 10 } };
+    w.agents = [{ id: 'a1', type: 'web-engineer', description: 'ST-4', status: 'running' }];
+    const clock = await start($, on, w);
+    const { call } = await heldCall($, w, clock);
+    await clock.advance(6 * 60000);
+    expect(w.sent).toEqual([]);
+    w.waiting.get('tu-h1')?.('timed out');
+    await call;
+    // Its quiet time starts again when the call ends: nudged 5 minutes after, not at once.
+    await clock.advance(2000);
+    expect(w.sent).toEqual([]);
+    await clock.advance(5 * 60000);
+    expect(w.sent.map((m) => m.to)).toEqual(['a1']);
+  },
+);
 
 test('LOOP-7 when every story is done the loop stops, and the band says so until dismissed', async ($, on) => {
   const w = project();
@@ -2657,7 +2766,7 @@ test('VIEW-5 what needs the person is pinned at the top with its letter: a held
   const w = project();
   w.refusal = webInstall;
   const clock = await start($, on, w);
-  await heldCall($, w, clock);
+  const { call } = await heldCall($, w, clock);
   await lanes($);
   const ui = await pane($, PANE);
   expect((await ui.find({ key: 'need-held' }))?.text).toMatch(
@@ -2668,6 +2777,8 @@ test('VIEW-5 what needs the person is pinned at the top with its letter: a held
   expect(w.opened).toContain(APPROVE);
   await ui.unmount();
   w.waiting.get('tu-h1')?.('timed out');
+  // A timed-out hold refuses the call, as the hooks did; awaited, so the test doesn't end mid-call.
+  expect(refused(await call)).toBe(true);
 });
 
 test('VIEW-6 tabs on 1 to 7, j and k move between lanes, and the selected lane has its keys', async ($, on) => {

package/hooks/mod/view.mjs

@@ -663,6 +663,8 @@ export function askWords(request, files = [request?.what]) {
 }
 
 export function approvalLabel(name) {
+  // REG-2: the person's approval to weaken a test.
+  if (name === 'tests') return 'a weakened test';
   return name.startsWith('dep-') ? name.slice(4).replaceAll('+', '/') : name;
 }
 
@@ -1073,29 +1075,12 @@ export function approvePane(
         ],
       }),
       // ACT-5: an aside about this approval, answered here and never in the lead's conversation.
-      ...aside.thread.flatMap((turn, i) => [
-        Text({ key: `aside-q-${i}`, color: 'cyan', children: [`You: ${turn.question}`] }),
-        turn.pending
-          ? Text({ key: `aside-a-${i}`, dimColor: true, children: ['Asking…'] })
-          : turn.error
-            ? Text({ key: `aside-a-${i}`, color: 'red', children: [turn.error] })
-            : Markdown
-              ? Markdown({ key: `aside-a-${i}`, text: turn.answer })
-              : Text({ key: `aside-a-${i}`, children: [turn.answer] }),
-      ]),
-      ...(onAsk
-        ? [
-            Input({
-              key: 'approve-ask',
-              label: 'Ask about it',
-              value: aside.draft,
-              placeholder: 'What is it for, and what does approving it let happen?',
-              submitLabel: 'Ask',
-              onInput: onAskInput,
-              onSubmit: onAsk,
-            }),
-          ]
-        : []),
+      ...asideNodes(
+        aside,
+        { Text, Input, Markdown },
+        { onAskInput, onAsk },
+        'What is it for, and what does approving it let happen?',
+      ),
       Input({
         key: 'approve-reason',
         label: 'Reason',
@@ -1118,6 +1103,69 @@ export function approvePane(
   });
 }
 
+/**
+ * ACT-5: an aside in a pane: each question asked and its answer (or that it's being asked, or why there
+ * is none), then the box to ask the next.
+ */
+function asideNodes(aside, { Text, Input, Markdown }, { onAskInput, onAsk }, placeholder) {
+  return [
+    ...aside.thread.flatMap((turn, i) => [
+      Text({ key: `aside-q-${i}`, color: 'cyan', children: [`You: ${turn.question}`] }),
+      turn.pending
+        ? Text({ key: `aside-a-${i}`, dimColor: true, children: ['Asking…'] })
+        : turn.error
+          ? Text({ key: `aside-a-${i}`, color: 'red', children: [turn.error] })
+          : Markdown
+            ? Markdown({ key: `aside-a-${i}`, text: turn.answer })
+            : Text({ key: `aside-a-${i}`, children: [turn.answer] }),
+    ]),
+    ...(onAsk
+      ? [
+          Input({
+            key: 'ask-about',
+            label: 'Ask about it',
+            value: aside.draft,
+            placeholder,
+            submitLabel: 'Ask',
+            onInput: onAskInput,
+            onSubmit: onAsk,
+          }),
+        ]
+      : []),
+  ];
+}
+
+/**
+ * ASK-5: the side call's prompt for a question about one of the person's decisions (a question from the
+ * lead, or one open in their brief): what code-kit knows of it, the aside so far, and their question.
+ */
+export function questionAsidePrompt({ q, thread = [], question }) {
+  return [
+    "The person is deciding how to answer a question in code-kit's Decisions pane, and asks you about it first. Answer in a few short sentences, in plain words: what the question means, why it matters for the build, what the choices are and what each leads to, and what you'd recommend if you know enough to. Use what you know from this conversation, the project's docs you've read, and the facts below. If you don't know, say so; don't guess. This answer goes to that pane, not into the conversation: don't act on it.",
+    '',
+    q.kind === 'brief' ? `An open question in ${q.path}:` : `A question the lead asked (${q.id}):`,
+    `- ${q.question}`,
+    ...(q.owner ? [`- who decides: ${q.owner}`] : []),
+    ...(q.kind === 'brief' && q.blocks ? [`- what it holds up: ${q.blocks}`] : []),
+    ...(q.story ? [`- story: ${q.story}`] : []),
+    ...(q.why ? [`- why the lead can't settle it: ${q.why}`] : []),
+    ...(q.options?.length
+      ? [
+          `- the lead's options: ${q.options.map((o) => `${o.label}${o.effect ? ` (${o.effect})` : ''}`).join('; ')}`,
+        ]
+      : []),
+    ...(thread.length
+      ? [
+          '',
+          'Asked so far:',
+          ...thread.flatMap((t) => [`Q: ${t.question}`, `A: ${t.answer ?? t.error ?? ''}`]),
+        ]
+      : []),
+    '',
+    `Question: ${question}`,
+  ].join('\n');
+}
+
 /**
  * ACT-5: the side call's prompt for a question about an approval: what code-kit knows of the request (the
  * names, the lane, what was refused and why, its story, the limits it missed), the aside so far, and the
@@ -1161,10 +1209,11 @@ export const ANSWER_ID = 'code-kit-answer';
 /** ASK-2, ASK-4: the person's answer to the lead's question, or to one in their brief, typed. */
 export function answerPane(
   answering,
-  { Box, Text, Input, Button },
-  { onInput, onSubmit, onCancel },
+  { Box, Text, Input, Button, Markdown },
+  { onInput, onSubmit, onCancel, onAskInput, onAsk },
 ) {
   const { kind, question, text, error } = answering;
+  const aside = answering.aside ?? { thread: [], draft: '' };
   return Box({
     flexDirection: 'column',
     rowGap: 1,
@@ -1178,6 +1227,28 @@ export function answerPane(
             : `${answering.id}, from the lead${answering.story ? `, for ${answering.story}` : ''}. Your answer is recorded and sent to the lead.`,
         ],
       }),
+      ...(kind === 'brief' && (answering.owner || answering.blocks)
+        ? [
+            Text({
+              dimColor: true,
+              children: [
+                [
+                  answering.owner && `Who decides: ${answering.owner}`,
+                  answering.blocks && `Holds up: ${answering.blocks}`,
+                ]
+                  .filter(Boolean)
+                  .join(' · '),
+              ],
+            }),
+          ]
+        : []),
+      // ASK-5: not sure what it means? Ask, here, before answering.
+      ...asideNodes(
+        aside,
+        { Text, Input, Markdown },
+        { onAskInput, onAsk },
+        'What does it mean, and what would you suggest?',
+      ),
       Input({
         key: 'answer-text',
         label: 'Answer',

package/hooks/stop-check.mjs

@@ -82,7 +82,7 @@ const layers = changed
 if (layers.length)
   fail('Imports break the layer rules (.claude/code-kit.json › layers):', layers.join('\n'));
 
-const failure = runChecks(config, changed, root, actor);
+const { failure } = runChecks(config, changed, root, actor);
 if (failure) fail(failure.title, failure.output);
 
 // A lane hands back committed work on its own branch; the lead reviews and merges it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",

package/skills/dispatch/SKILL.md

@@ -61,6 +61,7 @@ Requirements (read each one in full, with its acceptance criteria):
 - …
 
 What to build: <the story's description, and anything the lead decided that the spec doesn't say>
+Fixes: <for a fix story, what was broken and where it was seen; write the test that fails because of it first>
 Contracts to use: <paths of the schemas, events or tables this story relies on>
 Out of scope: <what neighbouring stories or other lanes will do>
 

package/skills/review/SKILL.md

@@ -29,6 +29,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" verify --base <base>
 - new layer violations, and a baseline that grew;
 - screens without an approved design;
 - committed secrets;
+- tests weakened (deleted, skipped or focused, cut down, or a snapshot rewritten) without the person's `tests` approval in the log;
+- for a fix (its story has `**Fixes:**`, or the branch is `<lane>/fix-…`), that its tests fail without the fix, as the bug, and pass with it;
 - the project's checks for the changed files.
 
 Any problem it reports means the branch goes back. Don't fix a lane's code yourself; the lead doesn't write lane paths.
@@ -73,7 +75,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>
   ```
 
-  Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree.
+  Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree.
 
 - **Send back.** List each problem, where it is, and what "fixed" looks like. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
 

package/skills/spec-design/SKILL.md

@@ -111,7 +111,7 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
   - a **QA lane** (`qa`, agent `test-engineer`) whenever the product has screens or journeys that cross lanes: it owns the end-to-end suites (for example `e2e/**` or `apps/*/e2e/**`), in the runner that suits each surface (Playwright for web, Maestro or Detox for mobile), and its command runs them. Nobody else owns these tests, so without it nothing proves a journey works across the lanes;
   - no lane for security: it owns no paths. init adds a read-only security reviewer that checks every story touching the threat models' sensitive parts, so security requirements are delivered by the lanes whose code they constrain;
   - milestones, each a usable increment;
-  - stories, each small enough for one lane to finish on one branch. Each story is a `### ST-<n> Title` heading with `**Lane:**`, `**Requirements:**` (the IDs it delivers, or `none` for a spike or a foundation that delivers none), `**Depends on:**` and `**Status:** todo` lines. `code-kit status` and the dispatch skill read them. A story that needs two lanes is two stories, with a dependency between them;
+  - stories, each small enough for one lane to finish on one branch. Each story is a `### ST-<n> Title` heading with `**Lane:**`, `**Requirements:**` (the IDs it delivers, or `none` for a spike or a foundation that delivers none), `**Depends on:**` and `**Status:** todo` lines, and for a story that fixes a bug, `**Fixes:**` with what was broken. `code-kit status` and the dispatch skill read them. A story that needs two lanes is two stories, with a dependency between them;
   - sequencing: contracts and shared foundations first, as the lead's own stories (`**Lane:** lead`, built by the lead rather than dispatched), then work that can run in parallel;
   - **a test story per journey**: for each main user journey, a story in the `qa` lane citing the journey's requirements and depending on the screen and service stories it goes through, so the journey is proven end to end as soon as its parts are built;
   - **design before code**: when there are screens, a design story for each area's screens (`**Lane:** design`, citing the requirements its screens serve), early in the plan, and every story that builds those screens depends on it. The lead designs them with the person (`/code-kit:design`), and no screen is built until its design is approved.

package/templates/agent.md

@@ -26,5 +26,7 @@ Always:
 - A new dependency needs a person's approval for your lane. If the install is refused, put the package, why it's needed and the approval command from the refusal in a change request for the lead, and stop.
 - Build every feature end to end. No mocks, stubs, placeholder screens or "coming soon".
 - Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.
+- Fixing a bug: first write a test that fails because of the bug, through the code that's already there, then fix it. `verify` runs your test without the fix, and it must fail on an assertion, not because it calls something the fix adds.
+- Never weaken a test to get to green: no deleting, skipping or focusing tests, cutting cases or assertions, or rewriting snapshots. The commit is refused without the person's approval. Fix the code; if the test itself is wrong, say why in a change request for the lead.
 - Commit your work on your branch before finishing; the stop hook runs the checks and requires it.
 - Finish with: what you did, the spec section, the commands you ran with their output, open questions.

package/templates/claude-md.md

@@ -1,6 +1,6 @@
 ## Enforced, not advised
 
-The code-kit plugin enforces the rules in `.claude/code-kit.json` on every tool call:
+The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file edit, shell command and finish:
 
 - who writes where (the lead delegates lane work to the lane agents in `.claude/agents/`);
 - the layer rules ({{layer names, in order}});

package/templates/plan.md

@@ -1,6 +1,6 @@
 # Plan
 
-`code-kit status` reads this file. Keep each story's heading and its four `**…:**` lines in this form. Use `**Lane:** lead` for the lead's own stories (contracts, foundations, spikes), `**Lane:** qa` for a journey's end-to-end test story (it depends on the screen and service stories the journey goes through), `**Lane:** design` for a design story (an area's screens, designed with the person before any of them is built; the stories building them depend on it), and `**Requirements:** none` for a story that delivers no requirement.
+`code-kit status` reads this file. Keep each story's heading and its four `**…:**` lines in this form. Use `**Lane:** lead` for the lead's own stories (contracts, foundations, spikes), `**Lane:** qa` for a journey's end-to-end test story (it depends on the screen and service stories the journey goes through), `**Lane:** design` for a design story (an area's screens, designed with the person before any of them is built; the stories building them depend on it), and `**Requirements:** none` for a story that delivers no requirement. A story that fixes a bug adds a fifth line, `**Fixes:** <what was broken, and where it was seen>`: `code-kit verify` then requires a test that fails without the fix and passes with it.
 
 ## Lanes