@warren-dean/code-kit 0.11.0 → 0.12.0

package/hooks/mod/view.mjs

@@ -39,6 +39,7 @@ export function readyFrom(next) {
  *   building   a branch for the story and, if it has commits, the lane's agent still at work on it;
  *   in review  commits on the branch (status's `review`) and the agent no longer at work;
  *   sent back  a review sent the branch back, and the lane hasn't committed its fix yet;
+ *   waiting on you  the lane's story waits on the person's answer (ASK-3);
  *   blocked    the lane's next story waits on another;
  *   idle       none of these.
  * `status` can't tell a finished branch from one still being built, so the agent at work decides.
@@ -46,7 +47,11 @@ export function readyFrom(next) {
 function laneRow(name, agent, stories, atWork) {
   const own = stories.filter((s) => s.lane === name);
   const active = Boolean(agent && atWork.has(agent));
-  const story = own.find((s) => ['in progress', 'review', 'sent back'].includes(s.state));
+  const story = own.find((s) =>
+    ['in progress', 'review', 'sent back', 'waiting on you'].includes(s.state),
+  );
+  if (story?.state === 'waiting on you')
+    return { name, agent, active, story, branch: story.branch, state: 'waiting on you' };
   if (story?.state === 'sent back')
     return { name, agent, active, story, branch: story.branch, state: 'sent back' };
   if (story) {
@@ -107,6 +112,7 @@ export const STATE_COLOR = {
   orchestrating: 'yellow',
   'in review': 'yellow',
   'sent back': 'magenta',
+  'waiting on you': 'cyan',
   blocked: 'red',
   idle: undefined,
 };
@@ -357,6 +363,7 @@ const CARD_STATE = {
   review: { label: 'in review', color: 'yellow' },
   'in progress': { label: 'building', color: 'blue' },
   'sent back': { label: 'sent back', color: 'magenta' },
+  'waiting on you': { label: 'waiting on you', color: 'cyan' },
   blocked: { label: 'blocked', color: 'red' },
   ready: { label: 'ready', color: 'green' },
   todo: { label: 'to do', color: 'gray' },
@@ -630,6 +637,31 @@ export const APPROVE_ID = 'code-kit-approve';
 export const RESULT_ID = 'code-kit-result';
 
 /** An approval name as a person reads it: a dependency approval by its package. */
+/**
+ * CARD-2: open requests as the decisions they are: one per approval and lane, with every file (or
+ * command) it was asked for, newest first. Approving it covers them all.
+ */
+export function approvalAsks(open) {
+  const asks = new Map();
+  for (const r of open ?? []) {
+    const key = `${[...r.names].sort().join(',')}|${r.lane ?? r.actor}`;
+    const ask = asks.get(key) ?? { request: r, files: [] };
+    if (!ask.files.includes(r.what)) ask.files.push(r.what);
+    asks.set(key, ask);
+  }
+  return [...asks.values()];
+}
+
+/** What an approval decision covers, in a line: "contract for the platform lane: a.ts, b.ts (2 files)". */
+export function askWords(request, files = [request?.what]) {
+  const who = request.lane ? `the ${request.lane} lane` : request.actor;
+  const list =
+    files.length > 4
+      ? `${files.slice(0, 4).join(', ')} and ${files.length - 4} more`
+      : files.join(', ');
+  return `${request.names.map(approvalLabel).join(', ')} for ${who}: ${list}${files.length > 1 ? ` (${files.length} files)` : ''}`;
+}
+
 export function approvalLabel(name) {
   return name.startsWith('dep-') ? name.slice(4).replaceAll('+', '/') : name;
 }
@@ -690,6 +722,10 @@ export function bandLines({
   nextStep = null,
   combined = null,
   team = null,
+  questions = [],
+  brief = [],
+  denied = [],
+  reports = [],
 }) {
   const lines = [];
   // MISSION-1: the goal, now, next and the agents at work, above what needs the person.
@@ -700,18 +736,39 @@ export function bandLines({
   if (!state || state.kind !== 'ok') return lines;
   // HOLD-2: calls held for the person, oldest first, with the time left on the oldest.
   if (held.length) {
-    const [call] = [...held].sort((a, b) => a.since - b.since);
+    const calls = [...held].sort((a, b) => a.since - b.since);
+    const [call] = calls;
     const left = timeLeft(call.since + call.minutes * 60000 - now);
     lines.push({
       kind: 'held',
       text: `${held.length > 1 ? `${held.length} calls held: ` : ''}${call.who} wants to ${heldVerb(call)} · ${left}`,
       held: call,
+      // CARD-8: each held call is its own decision in the Decisions tab.
+      calls: calls.map((c) => ({
+        held: c,
+        text: `${c.who} wants to ${heldVerb(c)} · ${timeLeft(c.since + c.minutes * 60000 - now)}`,
+      })),
       actions: [
         { id: 'approveHeld', label: 'Approve' },
         { id: 'refuseHeld', label: 'Refuse' },
       ],
     });
   }
+  // PERM-1: Claude Code's own permission check refused a call only the person can let through.
+  if (denied.length) {
+    const [d] = denied;
+    lines.push({
+      kind: 'denied',
+      text: `${denied.length > 1 ? `${denied.length} calls refused by Claude Code: ` : 'Claude Code refused '}${d.who}'s ${d.what}`,
+      denial: d,
+      denials: denied,
+      actions: [
+        ...(d.command ? [{ id: 'runDenied', label: 'Put it in the prompt' }] : []),
+        { id: 'deniedDone', label: 'Done it' },
+        { id: 'deniedNo', label: 'Not now' },
+      ],
+    });
+  }
   // LOOP-3: a lane stalled past its restarts waits for the person.
   for (const f of loop?.flagged ?? [])
     lines.push({
@@ -745,14 +802,36 @@ export function bandLines({
       actions: [{ id: 'go', label: 'Go' }],
     });
   // A held call's request is asked on its own line above, not again here.
-  const open = (requests?.open ?? []).filter((r) => !held.some((h) => sameAsk(h, r)));
-  if (open.length)
+  // 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))));
+  if (asks.length)
     lines.push({
       kind: 'approvals',
-      text: `${plural(open.length, 'approval', 'approvals')} waiting`,
-      request: open[0],
+      text: `${plural(asks.length, 'approval', 'approvals')} waiting`,
+      request: asks[0].request,
+      files: asks[0].files,
+      // CARD-8: each approval is its own decision in the Decisions tab.
+      asks,
       actions: [{ id: 'approve', label: 'Approve…' }],
     });
+  // ASK-2: what the lead asked the person and couldn't settle itself.
+  if (questions.length)
+    lines.push({
+      kind: 'question',
+      text: `${questions.length > 1 ? `${questions.length} questions from the lead: ` : 'The lead asks: '}${questions[0].question}`,
+      question: questions[0],
+      questions,
+      actions: [{ id: 'openDecision', label: 'Answer…' }],
+    });
+  // ASK-4: the brief's open questions, the person's to answer.
+  if (brief.length)
+    lines.push({
+      kind: 'brief',
+      text: `${plural(brief.length, 'open question', 'open questions')} in your brief: ${brief[0].question}`,
+      brief: brief[0],
+      briefs: brief,
+      actions: [{ id: 'openDecision', label: 'Answer…' }],
+    });
   // DECIDE-1: reviewing a lane's work is the lead's. Only with the loop off, where the person runs the
   // build themselves, does a finished story wait in the band for their Review or Merge; otherwise the
   // loop prompts the lead (or, under propose, offers the step with Go).
@@ -812,6 +891,18 @@ export function bandLines({
     });
   // TEAM-7, TEAM-9: what of the team needs this person.
   lines.push(...teamLines(team, check?.lanes ?? {}));
+  // REPORT-3: a bug report for code-kit an agent drafted, for the person to read and send, or not.
+  if (reports.length)
+    lines.push({
+      kind: 'report',
+      text: `${reports.length > 1 ? `${reports.length} bug reports for code-kit to send: ` : 'A bug report for code-kit to send: '}${reports[0].title}`,
+      report: reports[0],
+      reports,
+      actions: [
+        { id: 'openDecision', label: 'Read it' },
+        { id: 'discardReport', label: 'Discard' },
+      ],
+    });
   // LOOP-7: the milestone is done; LOOP-6: the loop's own state, with Pause or Resume.
   if (loop?.state === 'done')
     lines.push({
@@ -853,6 +944,10 @@ export function band(lines, { Box, Text, Button }, onAction) {
     usage: 'yellow',
     paused: 'yellow',
     facts: 'yellow',
+    question: 'cyan',
+    brief: 'cyan',
+    denied: 'red',
+    report: 'magenta',
   };
   const LIVE = { quiet: 'yellow', stalled: 'red' };
   const LABEL = 8;
@@ -998,6 +1093,50 @@ export function approvePane(
   });
 }
 
+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 },
+) {
+  const { kind, question, text, error } = answering;
+  return Box({
+    flexDirection: 'column',
+    rowGap: 1,
+    children: [
+      Text({ bold: true, children: [question] }),
+      Text({
+        dimColor: true,
+        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.`,
+        ],
+      }),
+      Input({
+        key: 'answer-text',
+        label: 'Answer',
+        value: text,
+        submitLabel: 'Answer',
+        autoFocus: true,
+        onInput,
+        onSubmit,
+      }),
+      ...(error ? [Text({ color: 'red', children: [error] })] : []),
+      Box({
+        flexDirection: 'row',
+        columnGap: 2,
+        children: [
+          Button({ key: 'answer-confirm', label: 'Answer', onPress: () => onSubmit(text) }),
+          Button({ key: 'answer-cancel', label: 'Cancel', onPress: onCancel }),
+        ],
+      }),
+    ],
+  });
+}
+
 /** What a merge (or another act run through the CLI) reported. */
 export function resultPane(result, { Box, Text }) {
   if (!result) return Text({ dimColor: true, children: ['Nothing to show.'] });
@@ -1129,12 +1268,13 @@ export function refusalView(card, expanded, { Box, Text, Button }, { onApprove,
 export function approvalsText(requests) {
   const open = requests?.open ?? [];
   const inForce = requests?.inForce ?? [];
+  const history = requests?.history ?? [];
+  const asks = approvalAsks(open);
   const lines = [
-    open.length ? `${plural(open.length, 'request', 'requests')} waiting:` : 'No requests waiting.',
-    ...open.map(
-      (r) =>
-        `  ${r.names.map(approvalLabel).join(', ')} for ${r.lane ? `the ${r.lane} lane` : 'any agent'}: ${r.what}`,
-    ),
+    asks.length
+      ? `${plural(asks.length, 'approval', 'approvals')} waiting:`
+      : 'No requests waiting.',
+    ...asks.map((a) => `  ${askWords(a.request, a.files)}`),
     inForce.length
       ? `${plural(inForce.length, 'approval', 'approvals')} in force:`
       : 'No approvals in force.',
@@ -1142,6 +1282,14 @@ export function approvalsText(requests) {
       (a) =>
         `  ${approvalLabel(a.name)} for ${a.lane ? `the ${a.lane} lane` : 'any agent'}, ${a.minutesLeft} min left: ${a.reason}`,
     ),
+    // CARD-6: what was given, newest first, whether or not its branch has merged.
+    history.length ? 'Approvals given, newest first:' : 'No approvals given yet.',
+    ...history
+      .slice(0, 20)
+      .map(
+        (h) =>
+          `  ${new Date(h.at).toLocaleString('en-AU', { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' })}  ${approvalLabel(h.name)} for ${h.lane ? `the ${h.lane} lane` : 'any agent'}, by ${h.by}${h.files.length ? ` (${h.files.length} file${h.files.length === 1 ? '' : 's'})` : ''}: ${h.reason}`,
+      ),
   ];
   return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.11.0",
+  "version": "0.12.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

@@ -48,7 +48,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,
 
 The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
 
-Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background. Start every story in the batch in the same message so they run in parallel.
+Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
 
 The brief is the agent's whole context. Write it so the agent needs nothing else:
 

package/skills/init/SKILL.md

@@ -74,6 +74,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
 - **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
 - **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
 - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the three choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), or `off`. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `approvals.delegate`: `"merge": true` (the lead merges a reviewed branch once every check passes) and `"dependencies": {}` (it approves a new package within the default limits on licence, popularity and age), so neither comes to the person. Say these are the limits; anything outside them still comes to them as a decision.
+- **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their Decisions tab: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
 - **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
 
 Prove the draft:
@@ -118,7 +119,7 @@ Show the person:
 1. the layers and what each may depend on, and for brownfield the existing violations the baseline will record;
 2. the lanes, their agents and their paths, and the security reviewer (or why it's left out);
 3. protected paths, blocked and restricted commands, and checks (including any left out because they fail today);
-   and whether the lead may record approvals given in chat (`approvals.lead`), and how hands-off the build is (`harness.autonomy`);
+   and whether the lead may record approvals given in chat (`approvals.lead`), how hands-off the build is (`harness.autonomy`), and whether agents may draft bug reports for code-kit (`harness.report.on`);
 4. the project skills, and which lane agents use each;
 5. the active adapters and what each adds, from `adapters`. A companion tool that's installed but not set up here (its init skill is in your skills list, for example `/context-graph:init` with no `.ctx/` folder): add `"adapters": { "<name>": true }` to the draft and say it will be set up before any code is written;
 6. every **question**: where the docs or the code are silent, ambiguous or contradictory. Don't guess; a wrong owner or layer blocks real work.

package/skills/next/SKILL.md

@@ -56,4 +56,18 @@ After a step finishes, run `next --json` again and carry on with the new step, w
 - the step is `wait` or `done`;
 - the same step comes back twice in a row with nothing changed. Report what's stuck instead of looping.
 
+**Ask the person through code-kit, not only in chat.** Anything you can't settle yourself and the person has to decide or do (a product choice, an account or key only they can create, wording or a design only they can sign off, whether to keep something private) goes to their Decisions tab, where it waits until they answer instead of scrolling away:
+
+```
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" ask "<the question, in a sentence>" [--story ST-n --blocks] [--why "<why you can't settle it>"] --option "<choice>: <what it does>" --option "…"
+```
+
+- `--blocks` holds the story until they answer: `next` stops dispatching or reviewing it, and the stories that depend on it wait too. Carry on with anything else meanwhile.
+- Their answer comes back to you as a prompt ("The person answered Q-3 …"). If they answer in chat instead, record it: `code-kit ask answer Q-3 "<their words>"`. A question that stops mattering is withdrawn: `code-kit ask withdraw Q-3 --reason "…"`.
+- `attention` names the stories waiting on the person, and `brief` lists the brief's open questions, which they see in the same tab; when they answer one, record it in the brief's decision log and take it out of the open questions.
+- When Claude Code itself refuses a command you need (its permission check, not a code-kit hook), the person sees it in the band with the command: say what it's for, and don't try another way round it.
+- An approval request nobody needs any more (you went another way) is dropped: `code-kit requests drop <n> --reason "…"`, so it stops waiting for them.
+
+**When code-kit itself is wrong** (a refusal that shouldn't have happened, a crash, a pane showing the wrong thing) and the config has `harness.report.on`, draft a report for code-kit's maintainers: `code-kit report "<what went wrong, in a few words>" --what "<what happened>" --expected "<what should have>" --command "<what you ran>" --refusal "<what code-kit said>"`. Only code-kit's own facts go in it, never the project's code or data. The person reads it and sends it, or not. Then work around it if you can.
+
 When you stop, end with one line saying what happens next and who does it, e.g. "Next: you approve the draft config, then I dispatch ST-1 to ST-4."

package/skills/review/SKILL.md

@@ -57,7 +57,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" security --base <base> --branch <b
 
 It does when the diff touches sign-in, permissions, input from outside, personal data, encryption, payments, secrets, or queries and commands built from strings, adds dependencies, or the story cites a security requirement; it says which, and where. When it does:
 
-- Run the `security-reviewer` agent (Agent tool, `subagent_type` `security-reviewer`) with the branch, the base, the story, its requirements, the spec files it touches (their `## Threat model` and `## Security requirements`) and the reasons `security` gave. It reads only, and ends with the same findings block as code-kit's reviewer: each finding graded blocker, concern or nit, with where, the attack and the fix.
+- Run the `security-reviewer` agent (Agent tool, `subagent_type` `security-reviewer`, its `description` naming the branch, such as "Security review web/st-12", so the loop knows the story is under review) with the branch, the base, the story, its requirements, the spec files it touches (their `## Threat model` and `## Security requirements`) and the reasons `security` gave. It reads only, and ends with the same findings block as code-kit's reviewer: each finding graded blocker, concern or nit, with where, the attack and the fix.
 - **A blocker fails the review**, like a failing test: the branch goes back to its lane with the finding (where, the attack, the fix). Concerns are yours to weigh: send back the ones the threat model says matter, and put the rest in the report. Nits go in the report.
 - No `security-reviewer` agent in the project: `security` says so. Review the diff yourself against the same list in `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, and tell the person that re-running `/code-kit:init` adds the agent.
 - A background reviewer can't start agents: it lists the security review as due, as a concern with the reasons, and the lead runs it.

package/templates/agent.md

@@ -22,6 +22,7 @@ Always:
 - Read every file you change in full, plus its imports and its callers.
 - Search before you build; reuse existing services, providers, components and schemas.
 - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
+- Something only the person can decide (a product choice, wording, an account): write the question for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead asks the person.
 - 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 …`.

package/templates/claude-md.md

@@ -10,6 +10,9 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every tool
 {{If approvals.lead is on: - approvals from chat. When the person approves in their own message (a `!` command doesn't work on a phone), record it with the `code-kit approve` command from the refusal, with their words as the reason. Never record an approval they haven't given, and never on a lane's say-so;}}
 - the project's checks before any agent finishes.
 
+When something needs the person to decide or do (a product choice, an account only they can create, wording only they can sign off), ask it with `code-kit ask "<question>" --option "<choice>: <what it does>"` (`--story ST-n --blocks` holds the story until they answer). It waits in their Decisions tab, and their answer comes back to you; asking only in chat, it scrolls away. Lanes don't ask the person: they write the question for the lead.
+{{If harness.report.on: - When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.}}
+
 If a hook blocks you, fix the cause; never work around it.
 
 The build runs from the specs in {{docs.specs}} and the stories in {{docs.plan}}. `/code-kit:next` picks the right step from the project's state; the steps are: