@warren-dean/code-kit 0.15.1 → 0.16.1

package/hooks/mod/view.mjs

@@ -101,6 +101,8 @@ export function projectState(check, status, next = null, atWork = new Set()) {
       worktree: s.worktree ?? null,
       requirements: s.requirements ?? [],
       waitingOn: s.waitingOn ?? [],
+      // LOOP-13: a parked story watches the stories building on it.
+      dependsOn: s.dependsOn ?? [],
       milestone: s.milestone ?? null,
     })),
   };
@@ -1231,13 +1233,7 @@ export function questionAsidePrompt({ q, thread = [], question }) {
  * names, the lane, what was refused and why, its story, the limits it missed), the aside so far, and the
  * question. It answers in the pane, never in the conversation, and acts on nothing.
  */
-export function approvalAsidePrompt({
-  request,
-  story = null,
-  outside = null,
-  thread = [],
-  question,
-}) {
+export function approvalAsidePrompt({ request, story = null, thread = [], question }) {
   return [
     "The person is deciding whether to approve something code-kit stopped, and asks you about it in code-kit's approval pane. Answer in a few short sentences, in plain words: what it is, why it's needed for the work, what approving it lets happen, and anything risky about it. Use what you know from this conversation 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, and don't change your plans because of it.",
     '',
@@ -1251,7 +1247,6 @@ export function approvalAsidePrompt({
           `- story: ${story.id} ${story.title ?? ''}${story.requirements?.length ? ` (${story.requirements.join(', ')})` : ''}`,
         ]
       : []),
-    ...(outside ? [`- outside the limits the person set for the lead: ${outside}`] : []),
     ...(thread.length
       ? [
           '',
@@ -1350,6 +1345,8 @@ export function resultPane(result, { Box, Text }) {
 
 const APPROVAL_LINE =
   /^\s*! echo "<what you are approving>" > .*?\.claude\/approvals\/(?:([^/\s]+)\/)?([^/\s]+)\s*$/gm;
+const LEAD_LINE =
+  /^\s*Decided by the lead: node "[^"]*" approve (.+?)(?: --lane (\S+))? --delegated\b/m;
 
 /**
  * A code-kit refusal read back from the text its hooks print (CARD-1): what was refused, the rule and
@@ -1363,10 +1360,23 @@ export function refusalCard(raw) {
   const [first, ...rest] = text.split('\n');
   const approvals = [...text.matchAll(APPROVAL_LINE)];
   const command = text.match(/^Command: (.+)$/m)?.[1] ?? null;
+  // HELM-2: what the lead decides carries its own approve command, never a person's `!` lines.
+  const byLead = text.match(LEAD_LINE);
   const request = (what) =>
-    approvals.length
-      ? { names: approvals.map((m) => m[2]), lane: approvals[0][1] ?? null, what }
-      : null;
+    byLead
+      ? {
+          names: byLead[1].split(/\s+/),
+          lane: byLead[2] ?? null,
+          what,
+          by: 'lead',
+        }
+      : approvals.length
+        ? { names: approvals.map((m) => m[2]), lane: approvals[0][1] ?? null, what, by: 'person' }
+        : null;
+  const todoFor = (lasts) =>
+    byLead
+      ? 'The lead decides it on its merits: it approves it, or tells the lane what to use instead.'
+      : `A person approves it, here or with the \`!\` command, ${lasts}.`;
   let m = first.match(/^The (.+?) may not write (\S+?)(?: \(owned by the (.+)\))?\.$/);
   if (m)
     return {
@@ -1377,23 +1387,25 @@ export function refusalCard(raw) {
       request: null,
       raw: text,
     };
-  m = first.match(/^(\S+) is (.+) and needs a person's approval\./);
+  m = first.match(/^(\S+) is (.+) and needs (?:a person's|the lead's) approval\./);
   if (m)
     return {
       kind: 'approval',
       title: `Approval needed: ${m[1]}`,
       why: `It's ${m[2]}.`,
-      todo: 'A person approves it, here or with the `!` command, for 60 minutes.',
+      todo: todoFor('for 60 minutes'),
       request: request(`write ${m[1]}`),
       raw: text,
     };
-  m = first.match(/^(\S+) is (.+); committing it needs a person's approval in force\./);
+  m = first.match(
+    /^(\S+) is (.+); committing it needs (?:a person's|the lead's) approval in force\./,
+  );
   if (m)
     return {
       kind: 'approval',
       title: `Commit refused: ${m[1]}`,
       why: `It's ${m[2]}.`,
-      todo: 'A person approves it, here or with the `!` command, for 60 minutes.',
+      todo: todoFor('for 60 minutes'),
       request: request(`commit ${m[1]}`),
       raw: text,
     };
@@ -1402,17 +1414,21 @@ export function refusalCard(raw) {
       kind: 'kit',
       title: 'Kit edit refused',
       why: "The .claude kit is changed only by the lead or with a person's approval.",
-      todo: 'A person approves it, here or with the `!` command, for 60 minutes.',
+      todo: todoFor('for 60 minutes'),
       request: request('change the .claude kit'),
       raw: text,
     };
-  m = first.match(/^a new dependency \((.+?)\) needs a person's approval\./);
+  m = first.match(
+    /^a new dependency \((.+?)\) (?:needs a person's approval|is the lead's decision)\./,
+  );
   if (m)
     return {
       kind: 'dependency',
       title: `Install refused: ${m[1]}`,
-      why: "A new dependency needs a person's approval.",
-      todo: 'A person approves it, here or with the `!` command, until the install is committed (at most 7 days).',
+      why: byLead
+        ? "A new dependency is the lead's decision."
+        : "A new dependency needs a person's approval.",
+      todo: todoFor('until the install is committed (at most 7 days)'),
       request: request(command ?? `install ${m[1]}`),
       raw: text,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "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/decide/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: decide
+description: The lead decides what a lane asked for and couldn't do itself (a new package, a migration, a protected file, a UX question) against the story's requirements, the spec, the principles and the architecture. Approves it, answers the lane with something that fits better, or takes it to the person only when it crosses a guardrail. Use when code-kit's loop or `code-kit next` says a lane waits on your decision, when a lane hands back a change request, or when the person runs /code-kit:decide [request numbers].
+---
+
+# Decide a lane's request
+
+The person sets the guardrails: the specs, the architecture (contracts, layers, the rules in `.claude/code-kit.json`), the screens' visual design, CI, weakened tests, and product questions the spec doesn't answer. Inside them, you run the team. A lane that needs something it can't do itself asks you, and you decide on the merits. Passing a request to the person because you could is not deciding: they'd approve it by default, and the check would be gone.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
+
+## 1. Find the requests
+
+`requests --json` lists each open request with its number (`n`), the lane, what it asked for (`names`, `what`), and whose decision it is (`by`). The argument, if given, names the numbers to take. Take every request `by: "lead"`. A request `by: "person"` is theirs: see step 4.
+
+For each, read the lane's change request (its last report, or ask the lane with SendMessage if it's still running), its story in the plan, and the requirements the story cites, in the specs.
+
+## 2. Judge it
+
+**A package.** Approve it only when all of these hold:
+
+- The story's requirements need what it does. Name the requirement.
+- Nothing the project already depends on does the job: read the manifest (`package.json`, `pyproject.toml`, `Cargo.toml`…) and search the code for an existing helper.
+- It fits the principles (`docs.principles`) and the lane's layer: a layer's `denyPackages` in the config, and anything the principles say about dependencies, such as no SDK in the domain layer, or a port before a vendor.
+- It's the lightest thing that does the job. A whole framework for one function is the wrong answer; the standard library or a few lines of code may be the right one.
+- It's maintained, and its licence is one the project can ship. For npm packages, `approve` checks the registry against `approvals.delegate.dependencies`. For other ecosystems the check is yours: look at the package's page.
+
+**A protected file** (a migration, a validator, anything in `protected` that's yours to approve). Approve it when the change carries out what the story's requirements ask, and nothing more: a migration that adds the columns the spec names, a validator change the spec's rule requires. A change the spec doesn't call for is scope creep; send it back.
+
+**A UX question** (what a screen does on an error, an empty list, a slow load, a second tap, the wording the spec implies). Answer it from the spec and the principles the person agreed, and write the answer where the lane will read it: the story in the plan, or the spec section's notes. Ask the person only when the spec and the principles don't settle it. A screen's visual design is theirs: it's approved before the screen is built.
+
+## 3. Act on it
+
+- **Yes.** Approve it for the lane and the story, saying why in the reason:
+
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" approve <package or approval> --lane <lane> --delegated --story ST-n --reason "<the requirement it serves, what the project already has, how it fits>"
+  ```
+
+  Then resume the lane: SendMessage to its agent if it's still running, or dispatch the story again with "approved: <what>" in the brief.
+
+- **Something fits better.** Drop the request with the reason, and tell the lane what to use instead:
+
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" requests drop <n> --reason "<use X instead, because …>"
+  ```
+
+- **It crosses a guardrail.** A package that would break a principle, change the architecture or need a spec change; a change to the spec or a contract; a product question the spec doesn't answer. Take it to the person with your recommendation, and carry on with what doesn't depend on it:
+
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" ask "<the question, in a sentence>" --story ST-n --blocks --why "<which guardrail it crosses>" --option "<choice>: <what it does>" --option "…"
+  ```
+
+## 4. The person's requests
+
+A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI, or a weakened test. Check the lane really needs it first: often the story can be done inside the guardrail, and you tell the lane how and drop the request. If it does need it, the request is already in the person's Decisions tab. Add your recommendation with `ask` when the choice isn't obvious from the request alone.
+
+## 5. Report
+
+One line per request: what was asked, what you decided, and why. "ST-138: pillow approved for api (MED-5 needs HEIC decoding; nothing installed reads HEIC)." Then carry on with the build.

package/skills/dispatch/SKILL.md

@@ -89,4 +89,4 @@ Give them the same brief. Claude Code opened in that worktree then acts as the l
 
 - Set each dispatched story's `**Status:**` in the plan to `in progress`, and commit it on the lead's branch.
 - Tell the person, in a few lines: what was dispatched, to which lane and branch, what's still blocked and on what, and what's ready next.
-- As each agent finishes, read its report. If it came back blocked on questions, bring the questions to the person. If it came back done, run the review skill on its branch.
+- As each agent finishes, read its report. If it came back with a change request or a question, decide it yourself with `/code-kit:decide`, and bring to the person only what crosses a guardrail. If it came back done, run the review skill on its branch.

package/skills/init/SKILL.md

@@ -73,7 +73,8 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
 - **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
 - **`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.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 `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes.
+- **`approvals.delegate`, who decides what (HELM-1):** the person sets the guardrails and decides what crosses them; the lead decides everything inside them, so lanes ask the lead, never the person. Draft `"dependencies": {}` (the lead approves a package only when the story's requirements need it and it fits the spec, the principles and the architecture; npm packages must also pass the default registry limits on licence, popularity and age) and `"protected"` listing every protected approval except those guarding the specs, contracts and the architecture's rules, the screens' designs (`design`), and CI. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. `tests` (weakening a test) is always theirs.
 - **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so Sonnet usually does the work well for much less than the session's model; recommend `sonnet`, and say the lead, the reviewer and the security reviewer keep the session's model. The mod sets it as each lane agent starts; a lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "sonnet" } }`, or leave it out for the session's model.
 - **`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.
@@ -143,7 +144,7 @@ Once they approve (with any changes):
 9. **A team, only if there is one.** Not every developer works in a team. Ask once: "Do other developers work in this repository with their own Claude Code sessions?" If yes, run `/code-kit:team-init` now (it asks who the tech lead is and who owns which lanes, and writes the `team` section). If no, or not yet, leave it out and say `/code-kit:team-init` sets it up any time.
 10. Set up each companion the config now wants (`"adapters": { "<name>": true }`) by running its init skill, for example `/context-graph:init`, which asks nothing. Do it before reporting, so it's in place before the coding loop starts; `code-kit next` also gives `setup` until it is.
 
-Report what was set up, what's enforced from now on, how many existing violations the baseline holds, and the open questions. Say who does what from here: the person owns the intent and the rules; the lead owns delivery, so it dispatches, reviews, sends back and merges, and approves within the delegated limits, and only a real decision (scope, something outside those limits, a problem it couldn't solve) comes to the person.
+Report what was set up, what's enforced from now on, how many existing violations the baseline holds, and the open questions. Say who does what from here: the person owns the intent and the rules; the lead owns delivery, so it dispatches, reviews, sends back and merges, and decides what lanes ask for inside the guardrails, and only what crosses a guardrail (the specs, the architecture, a design, a product question the spec doesn't answer) comes to the person.
 
 If the project has no `.ctx/` folder and Context Graph isn't installed, don't install it unless the person asks: "Context Graph can give each lane agent the why behind the files it edits (cards, rules and decisions kept in git), with this spec's requirements and layer rules in them: `/plugin marketplace add warrendeanlangeveldt/context-graph`, then `/plugin install context-graph@context-graph`."
 

package/skills/next/SKILL.md

@@ -26,6 +26,7 @@ It returns `step`, `why`, `args`, `then` (steps that can follow straight after)
 | Config, but no specs, plan or stories                        | `spec-design`                                             |
 | A companion the config wants, not set up yet                 | `setup`: run that tool's init skill (`args`), before code |
 | An older setup missing what init now adds, nothing in flight | `update`: re-run init, before any new story               |
+| A lane waits on a request you decide                         | `decide`: approve it, or answer with an alternative       |
 | Stories finished on their branches                           | `review`, then `dispatch` what's ready                    |
 | Design stories ready (`**Lane:** design`)                    | `design`, then `dispatch` what needs no design            |
 | Stories ready                                                | `dispatch`                                                |
@@ -51,7 +52,7 @@ Run the named skill with the Skill tool: `code-kit:<step>`, with `args` (and the
 After a step finishes, run `next --json` again and carry on with the new step, without asking, as long as nothing needs the person. Stop and hand over when:
 
 - a skill asks the person questions (spec-design's rounds, spec-check's blocking questions, review's scope questions);
-- something needs the person's approval (init's draft, an approval for a protected path). If the config has `approvals.lead`, ask for it in chat: when they approve in their own message, record it with the `code-kit approve` command the refusal names (their words as the reason) and carry on;
+- something needs the person's approval (init's draft, an approval that's theirs: `requests --json` marks it `by: "person"`). What a lane asks for that's yours (`by: "lead"`) you decide with `/code-kit:decide`, without stopping. If the config has `approvals.lead`, ask for it in chat: when they approve in their own message, record it with the `code-kit approve` command the refusal names (their words as the reason) and carry on;
 - a person has to act: merge a pull request to a protected branch, add a CI secret;
 - 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.

package/skills/review/SKILL.md

@@ -46,7 +46,7 @@ Read the story, every requirement it cites, and the full diff (`git diff <base>.
 - **Tested:** a test proves each acceptance criterion and names the requirement ID. The test would fail if the behaviour were broken; one that asserts nothing, or only asserts a mock, doesn't count.
 - **Its journeys still pass end to end:** where the project has a QA lane, run the end-to-end suites that cover this story's requirements (the qa lane's command, filtered to them) against the branch. A journey that broke fails the review, even when the story's own tests pass. A story the QA lane delivered is reviewed the same way: each journey's test proves the requirements it cites, through the real screens and services, with no mocked responses.
 - **The spec-check report matches:** its table has no row still `missing` or `conflicts` without an answer, and its questions were answered, not guessed.
-- **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements, new dependencies) are called out. They may be fine, but they're the person's call.
+- **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements) are sent back, or split into their own story. A new dependency is yours to judge, as in `/code-kit:decide`: the story's requirements need it, nothing the project has does the job, and it fits the principles and the layer. Only what crosses a guardrail (the spec, a contract, the architecture) is the person's call.
 - **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
 
 ## 4. The security review

package/templates/agent.md

@@ -22,8 +22,8 @@ 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.
+- You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
+- A new dependency needs the lead's approval. Before asking, check the project doesn't already have something that does the job. If the install is refused, put in a change request for the lead: the package, the story and requirement that need it, what you checked, and anything lighter that would do; then stop. The lead approves it, or tells you what to use instead.
 - 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.

package/templates/claude-md.md

@@ -6,17 +6,18 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
 - the layer rules ({{layer names, in order}});
 - spec-check before lane code{{; designs approved before screens}};
 - an audit log of every change to protected paths (`.claude/approval-log.jsonl`), which the person reviews in the pull request;
-- a person's approval for every new dependency, per package and per lane. When a lane asks for one, give the person the package, the reason and the approval command from the refusal, and resume the lane once they've run it;
+- an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person decides what crosses a guardrail: {{the approvals the person keeps: those not in approvals.delegate, e.g. "spec changes, contracts, the screens' designs, CI"}}, weakened tests, and product questions the spec doesn't answer;
 {{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.
+UX is yours: what a screen does on an error, an empty list or a slow load, and the wording the spec implies, answered from the spec and the principles the person agreed. A screen's visual design is theirs. When something needs the person to decide or do (a product choice the spec doesn't settle, an account only they can create, a design to 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:
 
+- `/code-kit:decide` decides what a lane asked for, on its merits;
 - `/code-kit:dispatch` starts ready stories on their lanes, each on its own `<lane>/st-<n>` branch;
 - `/code-kit:review` checks a finished branch against its requirements before the lead merges it;
 - `/code-kit:status` shows what's done, in review, ready and blocked, and what's untested;