@warren-dean/code-kit 0.12.2 → 0.14.0

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;
 }
 
@@ -786,6 +788,7 @@ export function bandLines({
     lines.push({
       kind: 'proposal',
       text: `code-kit can keep the build moving between your prompts. Next: ${loop.proposal.label}.`,
+      proposal: loop.proposal,
       actions: [
         { id: 'keepGoing', label: 'Keep going' },
         { id: 'askEach', label: 'Ask each time' },
@@ -799,8 +802,12 @@ export function bandLines({
       text: loop.proposal.repeated
         ? `${loop.proposal.label}: still next after ${loop.proposal.repeated} prompts. Ask the lead again?`
         : `${loop.proposal.label}?`,
-      actions: [{ id: 'go', label: 'Go' }],
+      proposal: loop.proposal,
+      actions: [{ id: 'go', label: loop.proposal.repeated ? 'Ask again' : 'Go' }],
     });
+  // LOOP-11, LOOP-12: what the loop read in the lead's reply holds it until the person says.
+  const waitingLine = waitingOf(loop?.waiting);
+  if (waitingLine) lines.push(waitingLine);
   // A held call's request is asked on its own line above, not again here.
   // CARD-2: counted as decisions, not files: one approval for a lane covers every file it was asked for.
   const asks = approvalAsks((requests?.open ?? []).filter((r) => !held.some((h) => sameAsk(h, r))));
@@ -913,7 +920,14 @@ export function bandLines({
   // With the mission rows drawn, the loop's state and its Pause or Resume are on the `now` row.
   else if (mission.length) {
     // nothing more
-  } else if (loop?.state === 'paused')
+  } else if (loop?.state === 'elsewhere')
+    // LOOP-10: another session in this project runs the loop; this one never prompts its lead.
+    lines.push({
+      kind: 'loop',
+      text: 'the loop runs in another session',
+      actions: [{ id: 'leadHere', label: 'Lead from here' }],
+    });
+  else if (loop?.state === 'paused')
     lines.push({ kind: 'loop', text: 'loop paused', actions: [{ id: 'resume', label: 'Resume' }] });
   else if (loop?.state === 'running' && loop.started)
     lines.push({
@@ -928,6 +942,48 @@ export function bandLines({
   return lines;
 }
 
+/**
+ * LOOP-11, LOOP-12: the band's line for what the loop waits on, or null: the lead waiting on the
+ * person (its question, when the reply asked one), a turn the person stopped, a step the lead didn't
+ * take, or design stories left to the person and the lead.
+ */
+export function waitingOf(waiting) {
+  if (!waiting) return null;
+  if (waiting.kind === 'person')
+    return {
+      kind: 'waiting',
+      text: waiting.question
+        ? `The lead waits on you: ${waiting.question}`
+        : `The lead waits on you${waiting.reason ? `: ${waiting.reason}` : ''}`,
+      waiting,
+      actions: waiting.question
+        ? [{ id: 'openDecision', label: 'Answer…' }]
+        : [{ id: 'carryOn', label: 'Carry on' }],
+    };
+  if (waiting.kind === 'stopped')
+    return {
+      kind: 'waiting',
+      text: "You stopped the lead's turn: the loop waits for you",
+      waiting,
+      actions: [{ id: 'carryOn', label: 'Carry on' }],
+    };
+  if (waiting.kind === 'blocked')
+    return {
+      kind: 'waiting',
+      text: `${waiting.label}: the lead didn't take it${waiting.reason ? `: ${waiting.reason}` : ''}`,
+      waiting,
+      actions: [{ id: 'askAgain', label: 'Ask again' }],
+    };
+  if (waiting.kind === 'design')
+    return {
+      kind: 'designing',
+      text: `${waiting.label}: with you and the lead, so the loop doesn't prompt it again`,
+      waiting,
+      actions: [{ id: 'askAgain', label: 'Ask the lead' }],
+    };
+  return null;
+}
+
 /** The band, drawn with the elements `$.ui.resolve(e)` returned; `onAction(id, line)` acts. */
 export function band(lines, { Box, Text, Button }, onAction) {
   const COLOR = {
@@ -936,6 +992,8 @@ export function band(lines, { Box, Text, Button }, onAction) {
     queue: 'blue',
     stalled: 'red',
     proposal: 'cyan',
+    waiting: 'cyan',
+    designing: 'blue',
     loop: 'green',
     done: 'green',
     approvals: 'yellow',
@@ -1073,29 +1131,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 +1159,73 @@ 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}:`
+      : q.kind === 'lead'
+        ? 'What the lead asked in its last reply, and waits on:'
+        : `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 +1269,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,
@@ -1175,9 +1284,33 @@ export function answerPane(
         children: [
           kind === 'brief'
             ? `An open question in ${answering.path}. The lead records your answer in the brief's decisions and builds on it.`
-            : `${answering.id}, from the lead${answering.story ? `, for ${answering.story}` : ''}. Your answer is recorded and sent to the lead.`,
+            : kind === 'lead'
+              ? 'From the lead, which waits on it. Your answer is sent to the lead.'
+              : `${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.14.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