@warren-dean/code-kit 0.11.1 → 0.12.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.11.1",
+      "version": "0.12.1",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
 
+## 0.12.1 (2026-10-13)
+
+Ask about an approval before you give it.
+
+- **Ask about it, in the Approve pane.** When a request isn't clear, ask what it's for right there. The answer comes from a side call over the lead's conversation and what code-kit knows of the request (what was asked for and for whom, why it was refused, its story, the limits it missed), and it stays in the pane: nothing is added to the lead's session. Follow-ups carry on the conversation. Before the lead has replied, it answers from code-kit's facts alone. Nothing is approved until you press Approve.
+
+## 0.12.0 (2026-10-13)
+
+What only you can decide reaches you, and waits until you answer.
+
+- **Questions from the lead.** What the lead can't settle itself (a product choice, an account only you can create, wording only you can sign off) is asked with `code-kit ask`, and waits in the Decisions tab with the lead's options and what each does. Your answer, a press or your own words, is sent to the lead. A question can hold its story, which reads "waiting on you": nothing dispatches or reviews it, and the stories that depend on it wait, until you answer.
+- **Your brief's open questions** are decisions too, each with **Answer…** (the lead records it in the brief) and **Later**.
+- **What Claude Code itself refused.** A call Claude Code's own permission check refused, which code-kit can't approve past, waits in the band with **Put it in the prompt** (the command after `!`, for you to run), **Done it** and **Not now**.
+- **Approval requests wait until answered.** They no longer vanish after 60 minutes; one nobody needs is dropped with **Not needed**, or by the lead with `code-kit requests drop`.
+- **A card for each decision.** Two approvals waiting are two cards in the Decisions tab, each answered on its own.
+- **Bug reports for code-kit.** With `harness.report.on` (off unless you turn it on; init asks), an agent that code-kit got in the way of drafts a report with only code-kit's own facts, your project's folders and email addresses taken out. You read it and send it to code-kit's GitHub with your own `gh` (a comment, if it's filed already), or get the link to file it, or discard it.
+
 ## 0.11.1 (2026-10-12)
 
 The loop and the lead stop talking past each other, and approvals ask only what still needs you.

package/README.md

@@ -280,17 +280,21 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
 - **The band** sits above the prompt. While the build is moving (the lead mid-turn, an agent at work, the loop started) it opens with the mission: **goal**, the milestone being built and how many of its stories are done; **now**, what the lead is doing and the loop's state, with **Pause** or **Resume**; **next**, the step the loop takes next; and **agents**, a line per agent at work with its current tool and how long since. With Context Graph installed, a line says when a lane edited files without understanding them, and only then. Beneath, labelled **you**, what only you can decide, each with the story it's for ("for ST-4 Booking form (BOOK-1)"), and **d** ("Why, and what each choice does") opens it as a card in the Decisions tab; usage and the plan's pause are labelled **note**. In a team (`team` in the config), it also names what of the team needs you, and only that: your stale claim (Keep or Release), a claim of yours changing the same files as someone else's, an intent touching what you own or lease (every intent, with Agree and Drop, for the tech lead), and a pull request in a lane you own. While the loop runs, a lane's finished work is the lead's to review and merge, so it never waits here; with the loop off, Review and Merge are offered to you. With nothing happening and nothing waiting, the band is gone. It shows:
   - an agent's call held for you: installing a new package, writing or committing a protected file, or a lane changing the kit. Rather than stopping the agent, the call waits while the band asks ("web wants to install dayjs · 1:53"). **Approve** opens the confirmation and, once you confirm, the same call runs; **Refuse**, or no answer within `harness.hold.minutes` (2 unless set), refuses it as before. Under `autonomy: autonomous`, a call within `approvals.delegate` is approved as delegated without asking. Nothing is held under `claude -p` or the SDK, where nobody can answer;
   - the lead loop, under `harness.autonomy`. `/code-kit:init` asks you how hands-off you want it. Until you've chosen, the loop's first step waits in the band ("code-kit can keep the build moving between your prompts") with **Keep going**, **Ask each time** and **Off**, and your answer is recorded as your setting. Once the lead has finished a turn, the loop keeps the build moving: with the lead idle and nothing typed in the prompt, it asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own, never the same step twice while nothing has changed, and never a story an agent is still on: one its lane agent is building, or a reviewer is reviewing, waits until that agent finishes ("waiting: ST-10 is still with its agent"). A step the lead was prompted with twice in a row and that is still next goes to you instead, in the band: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Go**. **Pause** and **Resume** stop and start it. Under `propose`, each step waits in the band for **Go**; under `off`, the loop does nothing. A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged, unless its work is done (it handed back, or its branch is in review or the merge queue); at `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times, and then the band flags the lane. When every story is done, the band says so and the loop stops. With `harness.agents.reviewer.on`, a finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it. A branch the lead's review passes joins the merge queue (`code-kit queue`). Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. There's no first merge for you: setting up commits the rules you approved straight onto the base, and in a project set up before that, the lead puts them there itself (`code-kit queue rules`) before its first merge. A merged lane's worktree is removed when it holds nothing uncommitted. A head that conflicts or fails verify goes back to its lane. The pane lists the queue, and lanes whose branch waits in it read `queued`;
-  - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite;
+  - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite. When it isn't clear what it's for, **Ask about it** in that pane: the answer comes from a side call over the lead's conversation and code-kit's facts about the request, shown in the pane and never added to the lead's session; follow-ups carry on the aside. A request waits until it's answered, its file is committed by someone who could, or it's dropped (at most a week); on its card, **Not needed** drops it;
+  - questions from the lead ("The lead asks: which weather provider?"): what it can't settle and only you can, asked with `code-kit ask`. **Answer…** opens it as a card with each of the lead's options and what it does, and **Something else…** for your own words; your answer is recorded and sent to the lead. A question can hold its story, which then reads `waiting on you`: nothing dispatches or reviews it, and the stories that depend on it wait, until you answer;
+  - your brief's open questions: **Answer…** sends your answer to the lead, which records it in the brief's decisions; **Later** puts one off until the next session;
+  - a call Claude Code's own permission check refused (its auto mode, a deny rule), which code-kit can't approve past: "Claude Code refused the lead's `pnpm db:generate`". **Put it in the prompt** puts a command in your prompt after `!` for you to run, **Done it** tells the lead you ran or allowed it, and **Not now** tells it to carry on with other work;
+  - with `harness.report.on`, a bug report for code-kit an agent drafted when code-kit got in its way: only code-kit's own facts (its version, the rule, what it said, the command), with the project's folders and email addresses taken out. **Read it** shows the exact text; **Send** files it on code-kit's GitHub with your own `gh` (a comment, if it's filed already; without `gh`, you get the link to file it), and **Discard** drops it;
   - stories finished and waiting for review: **Review** asks the lead to run `/code-kit:review` on the branch, and **Merge** runs `verify`, checks included, then merges if it passes;
   - a finish check failing in this session: **Lanes** opens the pane;
   - a story using more than three times the median of the stories finished this session (once three have finished): **Lanes** opens the pane;
   - background agents paused, once the plan’s 5-hour use passes `harness.background.pauseAtPercent` (80% unless set).
 
-  Each button has a digit: type it in an empty prompt to press it.
+  Each button has a digit: type it in an empty prompt to press it. The band keeps one line per kind ("2 approvals waiting"); the Decisions tab has a card for each decision.
 
 - **`/lanes`** opens the Lanes pane. Its first line counts the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key. Tabs on **1** to **7**: **Lanes** opens on the loop as a card: its mode, the steps it took, the one running and the next. Then each lane on fixed columns: its name, state and story, its agent's current or last tool call with the time since beneath (amber once quiet, red when stalled), and its tokens; the lead reads orchestrating while its turn runs. A selected lane shows its stories as cards (state, requirements, what each waits on or its branch), then its agent and the paths it owns. **Decisions**, each decision that needs you as a card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does; **Journal**, the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell; **Code map**, the whole project's folders by layer when no story is at work, or a story's files in a column per layer with the imports between them: a file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet; **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph (box-drawing text in the terminal, an SVG on Desktop); **Trail**, every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it; beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red; **Queue**, the merge queue; and **Usage**. **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story. **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
 - **Refusals** a code-kit hook gives an agent are drawn as cards: what was refused, the rule, what to do, and Approve… where your approval would allow it. The full text is a press away.
-- **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, and the use at which background agents pause. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
+- **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, the use at which background agents pause, and whether agents draft bug reports for code-kit. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
 - **`/approvals`** lists the approvals waiting (one per approval and lane, with every file it covers), the approvals in force with minutes left, and every approval given, newest first: who gave it (you, or the lead within your delegated rules), its reason, and the files and branches it covered, merged or not. A request stops waiting once an approval is given for it, or its file is committed by someone who could; a read-only agent such as the reviewer never asks. **`/verify-branch`** runs `code-kit verify` on this branch. Neither calls the model.
 
 Approving from the band records `(approved in the code-kit pane)` with your reason, and a merge from it says it was merged by the person from the pane. A settings change is logged as made in the pane. These happen only on your press: the hooks refuse `approve --via pane`, `merge --person` and `settings set` from every agent. Outside a project with `.claude/code-kit.json`, the mod draws nothing. Mods don't draw in the VS Code extension's chat panel, the Agent SDK or `claude -p`.
@@ -359,6 +363,11 @@ code-kit next [--base ref] [--json]    # the step to take now, from the project'
 code-kit trace <path>... [--json]      # what a file is for: requirements, lane, layer rules
 code-kit merge <branch> --delegated|--person [--into branch]  # merge a branch that passes verify: the lead where approvals.delegate.merge is on, or the person
 code-kit requests [--json]                                   # approval requests still waiting, the approvals in force, and every approval given
+code-kit requests drop <n>[,<n>…]|all [--reason "…"]         # stop waiting on requests nobody needs answered (the lead, or Not needed in the pane)
+code-kit ask "<question>" [--story ST-n] [--blocks] [--why "…"] [--option "Label: what it does"]...   # the lead asks you what it can't settle; it waits in your Decisions tab
+code-kit ask [--json] | ask answer <id> "<answer>" | ask withdraw <id> --reason "…"   # the questions; your answer (given in chat, recorded by the lead); one settled another way
+code-kit report "<title>" --what "…" [--expected …] [--command …] [--refusal …] [--rule …]   # with harness.report.on, an agent drafts a bug report for code-kit
+code-kit report [--json] | report send|discard <id>          # the drafts; sending files it on code-kit's GitHub with your gh, which only you do
 code-kit stops [--session id] [--json]                       # finish checks that refused an agent's last stop and still fail
 code-kit sent-back <branch> [--reason "…"]                    # record a review's send-back: status shows the story as sent back until the branch moves on
 code-kit settings [--json]                                   # the harness settings in force, with their defaults
@@ -419,7 +428,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pan
 | `setup`                        | no                | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `team`                         | no                | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default) or `{ command, fallback? }` for another team provider, such as the code-kit teams hub; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached. See docs/specs/16-teams.md. |
 | `branches.protected`           | no                | Default `["main", "master"]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `harness`                      | no                | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (default the session's), and `background.pauseAtPercent` (default 80). Change them with `/harness` or `code-kit settings set`.                                                                                                                                                                                                                                      |
+| `harness`                      | no                | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (default the session's), `background.pauseAtPercent` (default 80) and `report.on` (agents draft bug reports for code-kit, which you send or discard; default `false`). Change them with `/harness` or `code-kit settings set`.                                                                                                                                      |
 
 Add `.claude/approvals/`, `.claude/state/` and `.claude/code-kit.draft.json` to `.gitignore`, and `.claude/approval-log.jsonl merge=union` to `.gitattributes`, so merging branches that both logged changes keeps every entry. Commit `.claude/code-kit.baseline.json` if the project has one.
 
@@ -454,7 +463,7 @@ code-kit approve dep-dayjs --lane web --reason "Yes, add dayjs for ST-12"
 
 ### Requests
 
-Every refusal that a person's approval would allow is recorded as a request in `.claude/state/requests.jsonl` in the main checkout: who was refused, the approvals that would allow it, the command or file, and why. A request stays open until approvals for all its names are in force, or for 60 minutes. `code-kit requests` lists the open ones and the approvals in force, with minutes left, and the code-kit mod shows them above the prompt.
+Every refusal that a person's approval would allow is recorded as a request in `.claude/state/requests.jsonl` in the main checkout: who was refused, the approvals that would allow it, the command or file, and why. A request stays open until approvals for all its names answer it, its file is committed by someone who could, or it's dropped (`code-kit requests drop`), and at most a week. `code-kit requests` lists the open ones, numbered, and the approvals in force, with minutes left, and the code-kit mod shows them above the prompt.
 
 `--via pane` and `merge --person` are the person's own acts, which the code-kit mod uses for a press in its pane. The hooks refuse both from every agent.
 

package/bin/code-kit.mjs

@@ -20,6 +20,13 @@
 //   merge <branch> --delegated|--person [--into branch]  merge a branch that passes verify: the lead
 //                                    (approvals.delegate.merge) or the person (the code-kit pane)
 //   requests [--json]                 open approval requests and approvals in force
+//   requests drop <n>|all [--reason …] [--via pane]   drop requests nobody needs answered any more
+//   ask "<question>" [--story ST-n] [--blocks] [--why …] [--option "Label: what it does"]...
+//                                    the lead asks the person what it can't settle; ask [--json] lists them
+//   ask answer <id> "<answer>" [--via pane] | ask withdraw <id> --reason …
+//   report "<title>" --what … [--expected …] [--command …] [--refusal …] [--rule …]
+//                                    with harness.report.on, an agent drafts a bug report for code-kit
+//   report [--json] | report send|discard <id>   the person sends a draft to code-kit's GitHub, or not
 //   stops [--session id] [--json]     finish checks that refused an agent's last stop, still failing
 //   sent-back <branch> [--reason …]   records that a review sent the branch back at its current commit
 //   settings [--json] | settings set <key> <value> --reason … [--via pane]
@@ -51,6 +58,13 @@ import { diffConfigs, ownershipMoves } from '../hooks/lib/diff.mjs';
 import { CODE, importsOf, layerOf, layerProblems, targetOf } from '../hooks/lib/layers.mjs';
 import { ADAPTERS, activeAdapters, adapterFacts } from '../hooks/lib/adapters/index.mjs';
 import { nextStep } from '../hooks/lib/next.mjs';
+import { discardReport, draftReport, readReports, sendReport } from '../hooks/lib/report.mjs';
+import {
+  answerQuestion,
+  askQuestion,
+  readQuestions,
+  withdrawQuestion,
+} from '../hooks/lib/questions.mjs';
 import { traceFile } from '../hooks/lib/trace.mjs';
 import { buildStatus, specCheckRows } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
@@ -84,6 +98,7 @@ import {
   approvalsInForce,
   delegatedMark,
   grantApprovals,
+  dropRequests,
   openRequests,
   ownerOf,
   reviewerOf,
@@ -126,6 +141,15 @@ const staleDaysGiven = option('--stale-days');
 const intentsGiven = option('--intents');
 const ownersGiven = [];
 for (let o = option('--owner'); o !== undefined; o = option('--owner')) ownersGiven.push(o);
+const storyGiven = option('--story');
+const whyGiven = option('--why');
+const whatGiven = option('--what');
+const expectedGiven = option('--expected');
+const commandGiven = option('--command');
+const refusalGiven = option('--refusal');
+const ruleGiven = option('--rule');
+const optionsGiven = [];
+for (let o = option('--option'); o !== undefined; o = option('--option')) optionsGiven.push(o);
 const FLAGS = [
   '--write',
   '--no-checks',
@@ -135,6 +159,7 @@ const FLAGS = [
   '--fresh',
   '--peek',
   '--off',
+  '--blocks',
 ];
 const flag = (name) => args.includes(name);
 const writeBaseline = flag('--write');
@@ -911,16 +936,30 @@ function story(id) {
 // Open approval requests and the approvals in force, for the person and the mod's band.
 function requests() {
   load();
+  // CARD-7: a request nobody needs answered any more is dropped: the person's Dismiss, or the lead.
+  if (rest[0] === 'drop') {
+    if (!rest[1])
+      die('code-kit requests drop <n>|all [--reason "…"]: n as `code-kit requests` numbers them.');
+    const r = dropRequests(resolve('.'), rest[1], {
+      by: via === 'pane' ? 'person' : 'lead',
+      reason: reason ?? null,
+    });
+    if (!r.ok) die(r.why);
+    return out(
+      `Dropped ${r.dropped.length} request${r.dropped.length === 1 ? '' : 's'}: ${r.dropped.map((d) => `${d.names.join(', ')} for ${d.lane ? `the ${d.lane} lane` : d.actor}`).join('; ')}.`,
+    );
+  }
   const open = openRequests(resolve('.'));
   const granted = approvalsInForce(resolve('.'));
   // CARD-6: every approval given, newest first.
   const history = approvalHistory(resolve('.')).slice(0, 100);
   if (flag('--json')) return out(JSON.stringify({ open, inForce: granted, history }, null, 2));
   out(open.length ? `${open.length} approval request(s) open:` : 'No approval requests open.');
-  for (const r of open)
+  open.forEach((r, i) =>
     out(
-      `  ${r.names.join(', ')} for ${r.lane ? `the ${r.lane} lane` : r.actor}: ${r.what}  (${r.why})`,
-    );
+      `  ${i + 1}. ${r.names.join(', ')} for ${r.lane ? `the ${r.lane} lane` : r.actor}: ${r.what}  (${r.why}; asked ${r.at.slice(0, 16).replace('T', ' ')})`,
+    ),
+  );
   out(granted.length ? `\n${granted.length} approval(s) in force:` : '\nNo approvals in force.');
   for (const a of granted)
     out(
@@ -1613,6 +1652,121 @@ function intendCommand() {
   );
 }
 
+/**
+ * ASK-1 to ASK-3: questions for the person. `ask "<question>"` records one (the lead's: the hooks refuse
+ * it from lanes), waiting in the Decisions tab; `--blocks` holds its story until it's answered. `ask`
+ * lists them; `ask answer` records the answer (the person's from the pane with --via pane, which the
+ * hooks refuse from agents; otherwise the lead recording what the person said in chat); `ask withdraw`
+ * takes one back once it no longer needs the person.
+ */
+function askCommand() {
+  const root = resolve('.');
+  const [sub, id, ...words] = rest;
+  if (sub === 'answer') {
+    const r = answerQuestion(root, id, {
+      answer: words.join(' '),
+      by: via === 'pane' ? 'person' : 'lead',
+      via: via === 'pane' ? 'pane' : 'chat',
+    });
+    if (!r.ok) die(r.why);
+    return out(
+      `Recorded the answer to ${id}${via === 'pane' ? '' : ' (given in chat, recorded by the lead)'}: ${r.question.answer.text}${r.question.blocks ? ` ${r.question.story} no longer waits on the person.` : ''}`,
+    );
+  }
+  if (sub === 'withdraw') {
+    if (!reason?.trim()) die('Say why it no longer needs the person, with --reason "…".');
+    const r = withdrawQuestion(root, id, reason);
+    if (!r.ok) die(r.why);
+    return out(`Withdrew ${id}: ${reason.trim()}`);
+  }
+  const all = readQuestions(root);
+  if (!rest.length) {
+    if (flag('--json')) return out(JSON.stringify(all, null, 2));
+    const open = all.filter((q) => q.state === 'open');
+    out(
+      open.length
+        ? `${open.length} question(s) wait for the person:`
+        : 'No questions wait for the person.',
+    );
+    for (const q of open)
+      out(
+        `  ${q.id}${q.story ? ` (${q.story}${q.blocks ? ', which waits on it' : ''})` : ''}: ${q.question}${q.options.length ? `  [${q.options.map((o) => o.label).join(' / ')}]` : ''}`,
+      );
+    const answered = all.filter((q) => q.state === 'answered').slice(-10);
+    if (answered.length) out('\nAnswered lately:');
+    for (const q of answered) out(`  ${q.id}: ${q.question} → ${q.answer.text}`);
+    return;
+  }
+  const question = rest.join(' ').trim();
+  if (flag('--blocks') && !storyGiven) die('--blocks holds a story: name it with --story ST-n.');
+  const r = askQuestion(root, {
+    by: 'lead',
+    question,
+    why: whyGiven ?? null,
+    story: storyGiven ?? null,
+    blocks: flag('--blocks'),
+    options: optionsGiven,
+  });
+  out(
+    r.existed
+      ? `${r.question.id} is already open: ${r.question.question}`
+      : `Asked ${r.question.id}. It waits in the person's Decisions tab${r.question.blocks ? `, and ${r.question.story} waits on it` : ''}; their answer is sent to you as a prompt. Carry on with other work meanwhile.`,
+  );
+}
+
+/**
+ * REPORT-1 to REPORT-3: bug reports for code-kit itself. An agent drafts one (with harness.report.on);
+ * the person reads it and sends or discards it, from the pane or their terminal: the hooks refuse
+ * `report send` and `report discard` from every agent.
+ */
+function reportCommand() {
+  const root = resolve('.');
+  const [sub, id] = rest;
+  if (sub === 'send') {
+    const r = sendReport(root, id);
+    if (!r.ok) die(`${r.why}${r.link ? `\nOpen this to file it yourself: ${r.link}` : ''}`);
+    return out(
+      r.comment ? `Someone had filed it already; added it there: ${r.url}` : `Filed ${r.url}`,
+    );
+  }
+  if (sub === 'discard') {
+    const r = discardReport(root, id);
+    if (!r.ok) die(r.why);
+    return out(`Discarded ${id}.`);
+  }
+  if (!rest.length) {
+    const all = readReports(root);
+    if (flag('--json')) return out(JSON.stringify(all, null, 2));
+    const drafts = all.filter((r) => r.state === 'draft');
+    out(
+      drafts.length
+        ? `${drafts.length} report(s) wait for the person to send or discard:`
+        : 'No reports waiting.',
+    );
+    for (const r of drafts) out(`  ${r.id}: ${r.title}`);
+    return;
+  }
+  const { config } = load();
+  if (!config.harness.report.on)
+    die(
+      "Reporting code-kit's bugs is off (harness.report.on). Tell the person what went wrong instead: what you ran, what code-kit said, and what you expected.",
+    );
+  const r = draftReport(root, {
+    title: rest.join(' '),
+    what: whatGiven,
+    expected: expectedGiven,
+    command: commandGiven,
+    refusal: refusalGiven,
+    rule: ruleGiven,
+  });
+  if (!r.ok) die(r.why);
+  out(
+    r.existed
+      ? `${r.report.id} already reports this; it waits for the person.`
+      : `Drafted ${r.report.id}. The person reads it in the Decisions tab and sends it to code-kit's GitHub, or discards it. Carry on: work around it if you can, and say so.`,
+  );
+}
+
 /**
  * The lead loop's pause (LOOP-6): `loop` says whether the person paused it; `loop pause|resume`, the
  * person's act from the code-kit band, records it, so other tools' background work pauses with it.
@@ -1647,6 +1801,8 @@ const commands = {
   queue,
   team: teamCommand,
   intend: intendCommand,
+  ask: askCommand,
+  report: reportCommand,
   story: () => (rest.length === 1 ? story(rest[0]) : usage()),
   map: () => (rest.length === 1 ? mapCommand(rest[0]) : usage()),
   trail: trailCommand,
@@ -1672,7 +1828,11 @@ function usage() {
       '              | security [--base ref] [--branch name] [--json]\n' +
       '              | next [--base ref] [--json] | adapters | trace <path>... [--json]\n' +
       '              | approve <name>... --reason "…" [--lane name]   [--config file]\n' +
-      '              | merge <branch> --delegated|--person [--into branch] | requests [--json]\n' +
+      '              | merge <branch> --delegated|--person [--into branch] | requests [--json] | requests drop <n>|all\n' +
+      '              | ask "<question>" [--story ST-n] [--blocks] [--why "…"] [--option "Label: effect"]... | ask [--json]\n' +
+      '              | ask answer <id> "<answer>" | ask withdraw <id> --reason "…"\n' +
+      '              | report "<title>" --what "…" [--expected …] [--command …] [--refusal …] [--rule …]\n' +
+      '              | report [--json] | report send|discard <id>\n' +
       '              | stops [--session id] [--json] | sent-back <branch> [--reason "…"]\n' +
       '              | settings [--json] | settings set <key> <value> --reason "…" [--via pane]\n' +
       '              | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +

package/hooks/guard-bash.mjs

@@ -77,6 +77,8 @@ const approves = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+approve\b`));
 const delegatedMerge = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+(?:queue\s+)?merge\b`));
 const queues = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+queue\s+(?:add|drop)\b`));
 const rulesOntoBase = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+queue\s+rules\b`));
+const asks = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+ask\b\s+(?!--json\b)\S`));
+const dropsRequests = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+requests\s+drop\b`));
 const commits = runs(cmd, new RegExp(String.raw`^${GIT}commit\b`));
 if (error) {
   if (commits) block(`Blocked: ${error}\nFix the config before committing.`);
@@ -163,6 +165,21 @@ if ((delegatedMerge && /\s--person\b/.test(cmd)) || (approves && /\s--via\b/.tes
   block(
     `Blocked: merging or approving as the person is the person's own act, from the code-kit pane or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
   );
+// ASK-2, CARD-7: answering as the person, or dismissing their request, is theirs, from the pane.
+if ((asks || dropsRequests) && /\s--via\b/.test(cmd))
+  block(
+    `Blocked: answering a question or dismissing a request in the person's name is their own act, from the code-kit pane or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
+  );
+// ASK-1: questions for the person, and taking back requests, go through the lead.
+if ((asks || dropsRequests) && actor.kind !== 'lead')
+  block(
+    `Blocked: only the lead asks the person a question or drops an approval request. Write the question for the lead (what you need decided, the options and what each does), and stop.\nCommand: ${cmd}`,
+  );
+// REPORT-3: sending a report to code-kit's GitHub, under the person's account, or discarding it, is theirs.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+report\s+(send|discard)\b`)))
+  block(
+    `Blocked: sending a bug report to code-kit's GitHub, or discarding it, is the person's own act, from the code-kit pane or their terminal. Tell them it's drafted, and carry on.\nCommand: ${cmd}`,
+  );
 // Pausing and resuming the lead loop is the person's, from the band or their terminal.
 if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+loop\s+(pause|resume)\b`)))
   block(

package/hooks/lib/harness.mjs

@@ -57,6 +57,12 @@ export const SETTINGS = {
       Number.isFinite(v) && v > 0 && v <= 100 ? null : 'must be a percentage from 1 to 100',
     about: "The plan's 5-hour use at which background agents pause",
   },
+  'report.on': {
+    default: false,
+    problem: (v) => (typeof v === 'boolean' ? null : 'must be true or false'),
+    about:
+      "Agents draft a bug report for code-kit's GitHub when code-kit itself gets in their way; you read each one and send it, or not",
+  },
 };
 
 const get = (obj, key) =>

package/hooks/lib/next.mjs

@@ -56,18 +56,21 @@ const hasMarkdown = (dir) => {
 };
 
 /**
- * { step, why, args, then, attention }. `step` is a skill (spec-design, init, check, dispatch,
+ * { step, why, args, then, attention, brief }. `brief`: the brief's open questions (ASK-4). `step` is a skill (spec-design, init, check, dispatch,
  * review), `merge` (the head of the merge queue, where the lead merges), `wait` (lanes are
  * building) or `done`. `base(config)` resolves the branch lanes merge into.
  */
 export function nextStep(root, base) {
   const attention = [];
+  // ASK-4: the brief's open questions, for the person's Decisions tab.
+  let briefQuestions = [];
   const result = (step, why, extra = {}) => ({
     step,
     why,
     args: '',
     then: [],
     attention,
+    brief: briefQuestions,
     ...extra,
   });
   const isRepo = git(root, 'rev-parse', '--is-inside-work-tree') === 'true';
@@ -82,8 +85,10 @@ export function nextStep(root, base) {
       `The config is invalid, so nothing but the config can be written: ${error.split('\n')[0]}`,
     );
   const brief = readBrief(root, config);
-  if (brief?.openQuestions.length)
+  if (brief?.openQuestions.length) {
     attention.push(`${brief.openQuestions.length} open question(s) in ${brief.path}.`);
+    briefQuestions = brief.openQuestions.map((question) => ({ question, path: brief.path }));
+  }
 
   if (!config) {
     if (existsSync(join(root, DRAFT_FILE)))
@@ -187,6 +192,12 @@ export function nextStep(root, base) {
   const [review, building, blocked, fixes] = ['review', 'in progress', 'blocked', 'sent back'].map(
     ids,
   );
+  // ASK-3: a story whose question is open waits on the person; nothing dispatches or reviews it.
+  const waitingOnPerson = status.stories.filter((s) => s.state === 'waiting on you');
+  for (const s of waitingOnPerson)
+    attention.push(
+      `${s.id} waits on the person: ${s.waitingFor.question} (${s.waitingFor.id}, in their Decisions tab).`,
+    );
   // A ready story with a gap (unknown lane, a requirement no spec defines) waits for the plan's fix.
   const defined = new Set(status.requirements.map((r) => r.id));
   const buildable = (s) =>
@@ -302,6 +313,12 @@ export function nextStep(root, base) {
       'spec-design',
       `${unbuildable.join(', ')} ${unbuildable.length === 1 ? 'is' : 'are'} next, but the plan has gaps to fix first.`,
     );
+  // ASK-3: what's left waits on the person's answers, directly or through a dependency.
+  if (waitingOnPerson.length)
+    return result(
+      'wait',
+      `${waitingOnPerson.map((s) => `${s.id} waits on the person (${s.waitingFor.id})`).join('; ')}${blocked.length ? `; ${blocked.join(', ')} ${blocked.length === 1 ? 'waits' : 'wait'} on ${waitingOnPerson.length === 1 ? 'it' : 'them'}` : ''}. Carry on with anything else; their answer is sent to you.`,
+    );
   if (blocked.length)
     return result(
       'spec-design',

package/hooks/lib/plan.mjs

@@ -7,6 +7,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { waitingStories } from './questions.mjs';
 import { sentBack } from './reviews.mjs';
 
 export const REQUIREMENT = /\b(?!ST-)([A-Z][A-Z0-9]*-\d+)\b/g;
@@ -138,7 +139,8 @@ function worktrees(root) {
  * `base` is in review; one level with it is in progress, or done once the plan had it in review.
  * A branch still at the commit a review sent back is `sent back`, waiting for its lane's fix.
  * Without a branch, the plan's status stands. A story is `blocked` while a story it depends on
- * isn't done, whatever its branch holds; a todo story whose dependencies are done is `ready`.
+ * isn't done, whatever its branch holds; a todo story whose dependencies are done is `ready`. A story
+ * with an open question for the person that holds it (`code-kit ask --blocks`) is `waiting on you`.
  */
 export function storyStates(root, stories, base) {
   const trees = worktrees(root);
@@ -165,10 +167,16 @@ export function storyStates(root, stories, base) {
     };
   });
   const done = new Set(states.filter((s) => s.state === 'done').map((s) => s.id));
+  // ASK-3: a story whose question for the person is open waits on them, whatever its branch holds.
+  const asked = waitingStories(root);
   for (const s of states) {
     if (s.state === 'done') continue;
     s.waitingOn = s.dependsOn.filter((d) => !done.has(d));
-    if (s.waitingOn.length) s.state = 'blocked';
+    s.waitingFor = asked.has(s.id)
+      ? { id: asked.get(s.id).id, question: asked.get(s.id).question }
+      : null;
+    if (s.waitingFor) s.state = 'waiting on you';
+    else if (s.waitingOn.length) s.state = 'blocked';
     else if (s.state === 'todo') s.state = 'ready';
   }
   return states;
@@ -216,7 +224,11 @@ export function buildStatus(root, config, base, files) {
     let state = 'no story';
     if (r.removed) state = 'removed';
     else if (covering.length && covering.every((s) => s.state === 'done')) state = 'done';
-    else if (covering.some((s) => ['in progress', 'review', 'sent back', 'done'].includes(s.state)))
+    else if (
+      covering.some((s) =>
+        ['in progress', 'review', 'sent back', 'waiting on you', 'done'].includes(s.state),
+      )
+    )
       state = 'in progress';
     else if (covering.length) state = 'todo';
     return { ...r, state, stories: covering.map((s) => s.id), tests: tested[r.id] ?? [] };
@@ -224,7 +236,7 @@ export function buildStatus(root, config, base, files) {
   const drift = stories
     .filter(
       (s) =>
-        !['ready', 'blocked'].includes(s.state) &&
+        !['ready', 'blocked', 'waiting on you'].includes(s.state) &&
         s.state !== s.status &&
         !(s.state === 'sent back' && s.status === 'in progress'),
     )