@warren-dean/code-kit 0.11.1 → 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' },
@@ -715,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.
@@ -725,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({
@@ -778,8 +810,28 @@ export function bandLines({
       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).
@@ -839,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({
@@ -880,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;
@@ -1025,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.'] });

package/package.json

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