@warren-dean/code-kit 0.15.1 → 0.16.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.15.1",
+      "version": "0.16.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.15.1",
+  "version": "0.16.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,25 @@
 
 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.16.1 (2026-10-16)
+
+The lead loop stops asking for stories that are waiting on other work.
+
+- When the lead says a story isn't due yet because it waits on work still going, such as a paired story a lane is building, a rebuild or a check running, the loop parks that story. A parked story is left out of every step, so a step that names it with others prompts the lead only for the others. Before, the loop held a declined step only while the step stayed exactly the same, so when one more story became ready, or any lane committed, it prompted the same reviews again.
+- A parked story wakes when what it waits on moves: its own branch or state, the stories the lead named, or the unfinished stories in the plan that depend on it. Other lanes' commits don't wake it. After 30 minutes with nothing moving, the lead is asked once more.
+- The band's next row says what each parked story waits on. A step the lead declined for another reason no longer holds up every other step.
+
+## 0.16.0 (2026-10-16)
+
+The lead runs the team inside your guardrails, and lanes ask the lead, never you.
+
+- You decide what crosses a guardrail: changes to the specs, the contracts and the architecture's rules, the screens' visual design, CI, weakened tests, and product questions the spec doesn't answer. The lead decides the rest, as `approvals.delegate` names it. `/code-kit:init` proposes that split and asks what else you want to keep; re-run it on an existing project to get the split, and the new wording in CLAUDE.md and the lane agent files.
+- A lane refused something the lead decides is told so, with no `!` command and no mention of you. It hands the lead a change request with what it needs, the story and requirement, and what it checked first. The call isn't held, and nothing reaches your band. `code-kit requests` numbers each request and says whose it is to decide.
+- The new `/code-kit:decide` skill judges each request on its merits. A package is approved only when the story's requirements need it, nothing the project already depends on does the job, and it fits the principles and the lane's layer; otherwise the lead tells the lane what to use instead. Only what crosses a guardrail comes to you, with the lead's recommendation. `code-kit next` returns `decide` while a lane waits on the lead, so the loop prompts it before reviews and dispatches.
+- `code-kit approve --delegated` takes a package for a story: `--story ST-n`, checked against the plan, and recorded in the audit log. The npm registry rules apply only to npm's packages. A Python, Rust, Go or Ruby package used to be looked up on npm and sent to you; it's now the lead's judgement.
+- The mod no longer approves calls within the delegated rules by itself. Every approval the lead gives now comes with its reasons.
+- UX is the lead's to decide from the spec and the principles you agreed, such as what a screen does on an error or an empty list. A screen's visual design is still yours to approve.
+
 ## 0.15.1 (2026-10-16)
 
 Lanes stop less often to wait for you.

package/README.md

@@ -52,12 +52,12 @@ code-kit catches each of these, most at the moment it would happen: the hook ref
 
 - **Lanes:** each lane agent writes only its own paths. The main session (the lead) writes contracts, specs and config, and delegates the rest. Any other subagent is read-only. An edit outside those paths is refused before it happens; a file a shell command writes outside them is reported straight after, for the agent to revert, and the finish check refuses to finish until it's gone.
 - **Layers:** each layer depends only on the layers it lists, and never on packages it's denied, for JavaScript and TypeScript imports. An edit that would add a violation is refused before it's written; the rules are checked again after each edit and before finishing, which is what catches a file a shell command wrote. In brownfield code, existing violations can be recorded in a baseline so only new ones block. Imports are found by pattern, not by parsing: see [the limits](#what-verify-proves-and-its-limits).
-- **Protected paths and the approval log:** every committed change to the kit, registers or contracts is appended to `.claude/approval-log.jsonl`, in the same commit. Only the lead writes these paths without a person's approval, and the person reviews them in the pull request.
+- **Protected paths and the approval log:** every committed change to the kit, registers or contracts is appended to `.claude/approval-log.jsonl`, in the same commit. Only the lead writes these paths without an approval, and the person reviews them in the pull request. A lane needs an approval: the lead's for what `approvals.delegate` gives it, otherwise the person's.
 - **Spec-check before code:** when the project has specs, a lane can't write code on a branch until it has saved a spec-check report for that branch. The hook checks that the report exists; review checks what it says.
 - **Designs before screens** (optional): a screen file can't be written until the design register lists it.
 - **Shell rules**, matched against the command's text before it runs:
   - no force-push, pushing to or committing on protected branches, `--no-verify`, destructive deletes, or piping downloads into a shell;
-  - no new dependency without a person's approval, for that package and that lane; the approval also covers the manifest and lockfile changes the install makes;
+  - no new dependency without an approval, for that package and that lane: the lead's, for a story it judged needs it, where dependencies are delegated, otherwise a person's; the approval also covers the manifest and lockfile changes the install makes;
   - no forged approvals;
   - no commit that weakens a test (deletes it, skips or focuses it, removes cases or assertions, or rewrites a snapshot) without the person's `tests` approval, which the lead can't delegate;
   - the project's own blocked commands (deploys, releases) and lane-restricted commands (shared local services).
@@ -315,7 +315,7 @@ The band sits above the prompt. With nothing happening and nothing waiting, it's
 
 What waits for you there:
 
-- **A held call.** An agent 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.
+- **A held call.** An agent installing a new package, writing or committing a protected file, or a lane changing the kit, where the approval is yours. 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. What the lead decides (`approvals.delegate`) is never held for you: the lane asks the lead, which approves it on its merits. Nothing is held under `claude -p` or the SDK, where nobody can answer.
 - **Approvals agents 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**: 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, and 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?"), asked with `code-kit ask`: what it can't settle and only you can. **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**, each with who decides and what it holds up (from the table's Owner and Blocks columns; one owned by the lead alone isn't yours, and doesn't show). **Answer…** sends your answer to the lead, which records it in the brief's decisions, and **Ask about it** in the answer box explains it first, beside the conversation; **Later** puts one off until the next session.
@@ -332,6 +332,7 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
 
 - **Each step.** Once the lead has finished a turn, with the lead idle and nothing typed in the prompt, the loop asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own. It never prompts 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").
 - **It reads the lead's reply first.** Before prompting again, the loop reads the lead's last reply with a side call over the lead's own conversation. A reply that waits on you (a question, a design to look at, an approval), or a turn you stopped, holds the loop until you answer or speak to the lead: the band says what the lead waits on, and its question is asked in Claude Code's own question dialog. A step the lead didn't take waits in the band with its reason and **Ask again**.
+- **Stories waiting on other work.** When the lead says a story isn't due yet because it waits on work still going (a paired story a lane is building, a rebuild, a check running), the loop parks that story and leaves it out of every step, so a step naming it with others prompts only the others. It wakes when what it waits on moves: its own branch, the stories the lead named, or the unfinished stories that depend on it. Other lanes' commits don't wake it, and after 30 minutes with nothing moving the lead is asked once more.
 - **A step that doesn't move.** One the lead was prompted with twice in a row that is still next goes to you instead: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Ask again**.
 - **Designs.** A design story is handed to the lead once a session; while you and the lead design it, the loop leaves it to you.
 - **One session runs it.** The first session whose loop acts runs it for the project. Another session you open there, for any reason, never prompts its lead: its band reads "the loop runs in another session", with **Lead from here** to move the loop to it.
@@ -373,11 +374,13 @@ Once init has switched the rules on, the lead runs the build in a loop:
 
 ```text
 /code-kit:dispatch next      # start every ready story on its lane
+/code-kit:decide             # decide what lanes asked for: approve, offer something better, or bring it to you
 /code-kit:review ST-12       # check a finished branch, then merge or send it back
 /code-kit:status             # where the build stands against the spec
 ```
 
 - **Dispatch** picks the stories whose dependencies are done. It checks that no open question blocks them and that their contracts exist, then starts each lane agent in its own worktree on the branch `<lane>/st-<n>`, in parallel. Each brief names the story's requirements and acceptance criteria. Lanes spec-check first, build end to end, name requirement IDs in their test titles, and commit.
+- **Decide** takes what a lane asked for and couldn't do itself: a package, a migration, a protected file, a UX question. The lead judges it against the story's requirements, the spec, the principles and the architecture, and approves it, tells the lane what to use instead, or brings it to you when it crosses a guardrail. See [Who decides what](#who-decides-what).
 - **Review** runs `verify` on the branch, then checks each requirement: built end to end, proved by a test, matching the spec-check report, and nothing beyond the story. It ends with merge, send back with the list of problems, or a question for you.
 - **Status** traces every requirement to its story, branch and tests. It shows what's done, in review, ready and blocked, which requirements no test names, and where the plan's status lines are out of date.
 
@@ -430,7 +433,7 @@ code-kit status [--base ref] [--json]  # stories and requirements against the sp
 code-kit next [--base ref] [--json]    # the step to take now, from the project's state
 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 [--json]                                   # approval requests still waiting, numbered, each the lead's or the person's to decide, 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
@@ -464,7 +467,7 @@ code-kit map <story>|project [--json]                                 # a story'
 code-kit trail [--json]                                       # each requirement to its stories, the code they changed and the tests that name it
 code-kit adapters [--json --session id]                       # the adapters in use; with --json, what they know of each lane's work in a session
 code-kit hold <id> [--minutes N]                              # used by the mod: a held call waits here for the band's answer (--answer approved|refused)
-code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pane|<tool>]  # record a person's approval from chat, or (--delegated) grant one within the delegated rules; a package name stands for its dep- approval
+code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST-n] | --via pane|<tool>]  # record a person's approval from chat, or (--delegated) the lead's own, for a story (a package needs --story); a package name stands for its dep- approval
 ```
 
 `verify` compares the branch with where it left `--base` (default `origin/main`, then `main`). A branch named `<lane>/…`, or given as `--branch`, is held to that lane. `--no-checks` leaves the project's checks to CI's own steps. `status` reads `docs.specs` and `docs.plan`.
@@ -483,7 +486,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pan
 | `lead.outside`                 | no                | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `anyActor`                     | no                | Paths every writer may change (e.g. the lockfile), read-only agents included. `.claude/state/**` is always included. An entry may be `{ "glob", "reviewer" }` to name the lane (or `"lead"`) that reviews changes to it; otherwise the lead reviews them, and `who` and `trace` say so.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `lanes.<name>`                 | yes (may be `{}`) | `{ agent, paths, exclude?, owners? }`: the agent name maps a subagent to its lane; `owners` (GitHub handles) are the people whose sessions work it, in a team (needs `team`). A worktree with a `.lane` file holding the lane name makes the main session that lane.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `protected[]`                  | no                | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs a person's approval (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `protected[]`                  | no                | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs an approval: the lead's where `approvals.delegate.protected` names it, otherwise a person's (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `designGate`                   | no                | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) lists them. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `layers[]`                     | no                | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `importAliases`                | no                | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -495,7 +498,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pan
 | `checks[]`                     | no                | `{ name, files, exclude?, run[], each?, owners?, ifMissing?, timeoutSeconds? }`: before finishing, when matching files changed. `each` runs the commands in every changed folder matching that glob. `owners` limits who may change the files (the lead always may). `ifMissing: "fail"` makes a missing tool an error (the default is to skip the check, which `verify` and a merge list as not run).                                                                                                                                                                                                                                                                                                                                                       |
 | `adapters`                     | no                | `{ "<adapter>": false }` switches off an adapter that would otherwise be detected; `true` says the project wants that tool, so until it's set up here `next` gives its setup before any code. See [Adapters](#adapters).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `approvals.lead`               | no                | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `approvals.delegate`           | no                | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: approvals the lead may grant on its own, with `code-kit approve --delegated`, and with `merge`, merges into a protected branch with `code-kit merge --delegated`. Dependencies are checked against the npm registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals).                                                                                                                                                                                                   |
+| `approvals.delegate`           | no                | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`. Lanes ask the lead for these, never you. npm packages are also checked against the registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals).                                                                      |
 | `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"]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -536,27 +539,29 @@ 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 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.
+Every refusal that an 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. The code-kit mod shows the person's own above the prompt; the lead decides the rest (`code-kit next` hands them to it as `decide`).
 
 `--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.
 
-### Delegated
+### Who decides what
 
-For a lead that runs without a person watching, such as an autonomous team, `approvals.delegate` lets the lead approve some things on its own authority, within rules the person sets in the config:
+You set the guardrails and decide what crosses them: the specs, the contracts and the architecture's rules, the screens' visual design, CI, weakened tests, and product questions the spec doesn't answer. The lead decides everything inside them. `approvals.delegate` draws the line: what it names is the lead's, the rest is yours. `/code-kit:init` proposes the split and asks what you want to keep.
 
 ```json
-"approvals": { "delegate": { "protected": ["design"], "dependencies": { "minWeeklyDownloads": 10000 } } }
+"approvals": { "delegate": { "protected": ["schema", "truth"], "dependencies": {} } }
 ```
 
+A lane asks the lead, never you. When a lane is refused something the lead decides, the refusal says so, with no `!` command, and the lane hands the lead a change request and stops: what it needs, the story and requirement, and what it checked first. The call isn't held and nothing reaches your band. `code-kit next` hands the waiting requests to the lead (`decide`), and `/code-kit:decide` judges each on its merits: approve it for the story, tell the lane what to use instead, or bring it to you when it crosses a guardrail, with a recommendation.
+
 ```bash
-code-kit approve date-fns --lane web --delegated --reason "Date formatting for ST-12"
+code-kit approve pillow --lane api --delegated --story ST-138 --reason "MED-5 needs HEIC decoding; nothing installed reads HEIC"
 ```
 
 - **Protected approvals:** the lead may grant those named in `protected`, and no others.
-- **Dependencies:** each package is checked against the npm registry. Its licence must be in `licences`; it must have at least `minWeeklyDownloads` downloads last week and a release within `maxMonthsSinceRelease` months; and installing it must run no scripts, unless `allowInstallScripts` allows them: `true` for any, or a list of the kinds allowed, such as `["binary"]` for packages that only download a prebuilt binary for the platform (esbuild, sharp). The kinds are `binary`, `build` (compiles native code with node-gyp) and `other` (runs the package's own code). Packages from other ecosystems, and anything the registry can't confirm, go to the person.
-- **All or nothing:** if any name is outside the rules, nothing is approved, and the command says which rule each one broke, so the lead asks the person.
+- **Dependencies:** approved for a story, with `--story`: the lead approves a package only when the story's requirements need it, nothing the project already depends on does the job, and it fits the principles and the lane's layer. An npm package must also pass the registry rules: its licence must be in `licences`; it must have at least `minWeeklyDownloads` downloads last week and a release within `maxMonthsSinceRelease` months; and installing it must run no scripts, unless `allowInstallScripts` allows them: `true` for any, or a list of the kinds allowed, such as `["binary"]` for packages that only download a prebuilt binary for the platform (esbuild, sharp). The kinds are `binary`, `build` (compiles native code with node-gyp) and `other` (runs the package's own code). A package from another ecosystem (pip, uv, Poetry, cargo, go, bundler) is the lead's judgement alone.
+- **All or nothing:** if any name is outside the rules, nothing is approved, and the command says which rule each one broke.
 - **The record:** the approval reads `(approved by the lead within the delegated rules: <rule>)` after the reason. The approval log keeps it when the change is committed.
-- **Who:** only the lead. A lane asks the lead with a change request, and its refusals say the lead may approve within the rules. Without `approvals.delegate`, `--delegated` is refused.
+- **Who:** only the lead. Without `approvals.delegate`, `--delegated` is refused, and every approval is yours.
 - **Merges:** with `"merge": true`, the lead merges a reviewed branch into a protected branch with `code-kit merge <branch> --delegated`.
   - It runs `code-kit verify` on the branch first, checks included, and merges only if it passes. The checks run where the branch is checked out; in a temporary worktree without the project's install, checks that need one fail rather than being skipped.
   - The merge commit says it was verified and delegated.

package/bin/code-kit.mjs

@@ -66,7 +66,7 @@ import {
   withdrawQuestion,
 } from '../hooks/lib/questions.mjs';
 import { traceFile } from '../hooks/lib/trace.mjs';
-import { buildStatus, specCheckRows } from '../hooks/lib/plan.mjs';
+import { buildStatus, readStories, specCheckRows } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
 import {
   SECURITY_AGENT,
@@ -96,6 +96,7 @@ import {
   PANE,
   approvalHistory,
   approvalsInForce,
+  decidedBy,
   delegatedMark,
   grantApprovals,
   dropRequests,
@@ -968,7 +969,7 @@ function story(id) {
 
 // Open approval requests and the approvals in force, for the person and the mod's band.
 function requests() {
-  load();
+  const { config } = 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])
@@ -982,15 +983,20 @@ function requests() {
       `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('.'));
+  // HELM-2: each request's number for `requests drop`, and whose decision it is.
+  const open = openRequests(resolve('.')).map((r, i) => ({
+    ...r,
+    n: i + 1,
+    by: decidedBy(r.names, config),
+  }));
   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.');
-  open.forEach((r, i) =>
+  open.forEach((r) =>
     out(
-      `  ${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', ' ')})`,
+      `  ${r.n}. ${r.names.join(', ')} for ${r.lane ? `the ${r.lane} lane` : r.actor}, ${r.by === 'lead' ? "the lead's to decide" : "the person's to decide"}: ${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.');
@@ -1366,6 +1372,19 @@ async function approve(given) {
       die(
         'This project delegates no approvals to the lead ("approvals.delegate" isn\'t set). Ask the person.',
       );
+    // HELM-3: the lead approves a package for a story it has read, not by default.
+    const packages = names.filter((n) => n.startsWith(DEPENDENCY_APPROVAL));
+    if (packages.length && !storyGiven)
+      die(
+        `Nothing was approved. Name the story the package is for, with --story ST-n: approve a dependency only when that story's requirements need it, nothing the project already depends on does the job, and it fits the principles and the layer it goes in.`,
+      );
+    const stories = storyGiven && config.docs?.plan ? readStories('.', config.docs.plan) : [];
+    const story = storyGiven
+      ? (stories.find((st) => st.id.toUpperCase() === storyGiven.toUpperCase()) ??
+        (config.docs?.plan
+          ? die(`Nothing was approved: ${config.docs.plan} has no story ${storyGiven}.`)
+          : { id: storyGiven }))
+      : null;
     const outside = [];
     for (const name of names) {
       if (name === TESTS_APPROVAL) {
@@ -1378,10 +1397,22 @@ async function approve(given) {
           continue;
         }
         const pkg = packageOf(name);
-        const problems = dependencyRuleProblems(await npmFacts(pkg), rules.dependencies);
+        // HELM-3: the registry rules are npm's; a package from another ecosystem is the lead's judgement.
+        const registries = new Set(
+          openRequests(resolve('.'))
+            .filter((r) => r.names.includes(name) && (r.lane ?? undefined) === laneName)
+            .map((r) => r.registries?.[pkg])
+            .filter(Boolean),
+        );
+        const npm = !registries.size || registries.has('npm');
+        const problems = npm ? dependencyRuleProblems(await npmFacts(pkg), rules.dependencies) : [];
         if (problems.length) outside.push(`${name}: ${problems.join('; ')}`);
-        else marks[name] = delegatedMark(`dependencies (${pkg})`);
-      } else if (rules.protected.includes(name)) marks[name] = delegatedMark(`protected: ${name}`);
+        else
+          marks[name] = delegatedMark(
+            `dependencies (${pkg}${npm ? '' : `, from ${[...registries].join(', ')}, judged by the lead`}) for ${story.id}`,
+          );
+      } else if (rules.protected.includes(name))
+        marks[name] = delegatedMark(`protected: ${name}${story ? ` for ${story.id}` : ''}`);
       else
         outside.push(
           `${name}: not among the delegated approvals (${rules.protected.join(', ') || 'none'})`,

package/hooks/guard-bash.mjs

@@ -8,7 +8,12 @@
 import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, resolve } from 'node:path';
-import { addedPackages, dependencyApproval, isDependencyFile } from './lib/dependencies.mjs';
+import {
+  addedPackages,
+  dependencyApproval,
+  ecosystemOf,
+  isDependencyFile,
+} from './lib/dependencies.mjs';
 import { CODE_KIT, GIT, codeOf, commandsOf, runs } from './lib/shell.mjs';
 import { block, start } from './lib/hook.mjs';
 import { CONFIG_FILE } from './lib/config.mjs';
@@ -22,7 +27,9 @@ import {
   arrivesWithMerge,
   approval,
   approvalHowTo,
+  askHowTo,
   currentBranch,
+  decidedBy,
   dependencyChange,
   dependencyGrants,
   useApproval,
@@ -242,8 +249,8 @@ if (approves && !delegating && !forPerson)
     `Blocked: this project doesn't let the lead record approvals ("approvals.lead" is off).${config.approvals.delegate ? ' Within the delegated rules, approve it yourself with --delegated;' : ''} Ask the person to run the \`!\` command from the refusal, or to turn "approvals": { "lead": true } on in the config.\nCommand: ${cmd}`,
   );
 
-// Each new package needs a person's approval, for this actor; it also covers the manifest and lockfile
-// changes the install makes (lib/rules.mjs › dependencyChange).
+// Each new package needs an approval for this actor (the lead's where dependencies are delegated, HELM-3,
+// otherwise a person's); it also covers the manifest and lockfile changes the install makes (lib/rules.mjs › dependencyChange).
 if (packages.length) {
   if (actor.kind === 'readonly')
     block(`Blocked: ${actor.label} is read-only; it may not add dependencies.\nCommand: ${cmd}`);
@@ -256,22 +263,17 @@ if (packages.length) {
       actor,
       unapproved.map(dependencyApproval),
       cmd,
-      "A new dependency needs a person's approval.",
+      'A new dependency needs an approval.',
+      Date.now(),
+      // HELM-3: where each package comes from, for the registry rules (npm's only).
+      { registries: Object.fromEntries(unapproved.map((p) => [p, ecosystemOf(cmd, p)])) },
     );
-    const ask =
-      actor.kind === 'lead'
-        ? 'Ask the person to approve it by running'
-        : config.approvals.delegate
-          ? "Write a short change request for the lead (the package, why, and the lane's story), and stop. The lead approves it within the project's delegated rules, or asks the person to run"
-          : "Write a short change request for the lead (the package, why, and the lane's story), and stop. The lead asks the person to run";
+    // HELM-2, HELM-3: a lane asks the lead, which judges the package on its merits where it decides.
+    const names = unapproved.map(dependencyApproval);
+    const whose =
+      decidedBy(names, config) === 'lead' ? "is the lead's decision" : "needs a person's approval";
     block(
-      `Blocked: a new dependency (${unapproved.join(', ')}) needs a person's approval. ${ask}\n${approvalHowTo(
-        unapproved.map(dependencyApproval),
-        actor,
-        sessionIn ?? project,
-        'installing it, and the manifest and lockfile changes that makes,',
-        config,
-      )}\nCommand: ${cmd}`,
+      `Blocked: a new dependency (${unapproved.join(', ')}) ${whose}. ${askHowTo(names, actor, sessionIn ?? project, config, { allows: 'installing it, and the manifest and lockfile changes that makes,' })}\nCommand: ${cmd}`,
     );
   }
 }
@@ -392,7 +394,7 @@ if (kitWrite && actor.kind !== 'lead' && !approval(root, 'kit', actor)) {
     "The .claude kit is changed only by the lead or with a person's approval.",
   );
   block(
-    `Blocked: the .claude kit is changed only by the lead or with a person's approval. Ask the lead to run\n${approvalHowTo('kit', actor, root, undefined, config)}`,
+    `Blocked: the .claude kit is changed only by the lead or with a person's approval. ${askHowTo('kit', actor, root, config, { need: 'the change to the kit, and what the story needs it for' })}`,
   );
 }
 
@@ -447,7 +449,7 @@ function recordApprovals() {
     if (entry && !granted && actor.kind !== 'lead' && !byDependency) {
       recordRequest(root, actor, entry.approval, file, entry.why);
       block(
-        `Blocked: ${file} is ${entry.why}; committing it needs a person's approval in force. Ask the lead to run\n${approvalHowTo(entry.approval, actor, root, undefined, config)}`,
+        `Blocked: ${file} is ${entry.why}; committing it needs ${decidedBy(entry.approval, config) === 'lead' ? "the lead's" : "a person's"} approval in force. ${askHowTo(entry.approval, actor, root, config)}`,
       );
     }
     if (granted)

package/hooks/lib/dependencies.mjs

@@ -93,6 +93,24 @@ MANAGERS.pip3 = MANAGERS.pip;
  * except a shell's `-c` script, which runs.
  */
 export function addedPackages(cmd) {
+  return [...new Set(packagesWithManagers(cmd).map((p) => p.name))];
+}
+
+/** The package managers that read the npm registry: their packages are npm's. */
+const NPM_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+
+/**
+ * HELM-3: the registry `pkg` comes from, by the command that adds it: `npm` for npm, pnpm, yarn and
+ * bun, otherwise the manager's name (`pip`, `uv`, `cargo`…), or null when the command doesn't add it.
+ */
+export function ecosystemOf(cmd, pkg) {
+  const found = packagesWithManagers(cmd).find((p) => p.name === pkg);
+  if (!found) return null;
+  return NPM_MANAGERS.has(found.manager) ? 'npm' : found.manager;
+}
+
+/** Each package `cmd` adds, with the manager that adds it: `{ name, manager }`. */
+function packagesWithManagers(cmd) {
   const found = [];
   for (const { text, code } of commandsOf(cmd)) {
     // Words split where the quote-masked code has spaces, so a quoted word stays one word.
@@ -103,18 +121,18 @@ export function addedPackages(cmd) {
     words.forEach(({ word, quoted }, i) => {
       if (quoted) return;
       if (SHELLS.has(basename(word)) && words[i + 1]?.word === '-c' && words[i + 2])
-        found.push(...addedPackages(words[i + 2].word));
+        found.push(...packagesWithManagers(words[i + 2].word));
       const manager = MANAGERS[basename(word)];
       if (manager)
         found.push(
           ...packagesAfter(
             words.slice(i + 1).map((w) => w.word),
             manager,
-          ),
+          ).map((name) => ({ name, manager: basename(word).replace(/3$/, '') })),
         );
     });
   }
-  return [...new Set(found)];
+  return found;
 }
 
 const SHELLS = new Set(['sh', 'bash', 'zsh']);

package/hooks/lib/next.mjs

@@ -9,7 +9,7 @@ import { buildStatus, readStories, DESIGN, LEAD } from './plan.mjs';
 import { pendingSetup } from './adapters/index.mjs';
 import { CONFIG_FILE, SETUP_VERSION } from './config.mjs';
 import { readQueue, waiting } from './queue.mjs';
-import { laneOf } from './rules.mjs';
+import { decidedBy, laneOf, openRequests } from './rules.mjs';
 import { SECURITY_AGENT_FILE } from './security.mjs';
 
 export const DRAFT_FILE = '.claude/code-kit.draft.json';
@@ -253,6 +253,16 @@ export function nextStep(root, base) {
     attention.push(
       `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
     );
+  // HELM-4: a lane waiting on something the lead decides goes first: the lane can't go on without it.
+  const forLeadToDecide = openRequests(root).flatMap((r, i) =>
+    r.lane && decidedBy(r.names, config) === 'lead' ? [{ ...r, n: i + 1 }] : [],
+  );
+  if (forLeadToDecide.length)
+    return result(
+      'decide',
+      `${forLeadToDecide.map((r, i) => `${i ? 'the' : 'The'} ${r.lane} lane asks for ${r.names.map((n) => n.replace(/^dep-/, '').replaceAll('+', '/')).join(', ')}`).join('; ')}: yours to decide, against the story's requirements, the spec and the principles.`,
+      { args: forLeadToDecide.map((r) => r.n).join(' ') },
+    );
   // The merge queue (spec 09): branches the lead's review passed. Under autonomy, where the base's
   // committed rules delegate merges, the lead merges the head first, so dependents see it; otherwise
   // the person does, and always the first merge, which brings code-kit's rules onto the base.

package/hooks/lib/rules.mjs

@@ -71,9 +71,51 @@ export const GIVEN_FILE = '.claude/state/approvals-given.jsonl';
 /** Marks an approval the lead granted on its own, within `approvals.delegate`; `rule` names the rule. */
 export const delegatedMark = (rule) => `(approved by the lead within the delegated rules: ${rule})`;
 
-/** The command the lead runs to approve `names` itself, within the delegated rules. */
+/** The command the lead runs to approve `names` itself, within the delegated rules (HELM-3: for a story). */
 export const delegateCommand = (names, lane) =>
-  `node "${CLI}" approve ${[names].flat().join(' ')}${lane ? ` --lane ${lane}` : ''} --delegated --reason "<why, for this story>"`;
+  `node "${CLI}" approve ${[names].flat().join(' ')}${lane ? ` --lane ${lane}` : ''} --delegated --story <ST-n> --reason "<${
+    [names].flat().some((n) => String(n).startsWith(DEPENDENCY_APPROVAL))
+      ? 'what the story needs it for, what the project already has, how it fits'
+      : 'what the story needs the change for'
+  }>"`;
+
+/**
+ * HELM-1: whether the lead grants approval `name` itself, by the project's delegated rules. Weakening a
+ * test is always the person's; a package is the lead's where dependencies are delegated.
+ */
+export function leadDecides(name, config) {
+  const rules = config?.approvals?.delegate;
+  if (!rules || name === 'tests') return false;
+  if (String(name).startsWith(DEPENDENCY_APPROVAL)) return Boolean(rules.dependencies);
+  return (rules.protected ?? []).includes(name);
+}
+
+/** HELM-2: whose decision approvals `names` are: the lead's when it may grant every one, else the person's. */
+export const decidedBy = (names, config) =>
+  [names].flat().every((n) => leadDecides(n, config)) ? 'lead' : 'person';
+
+/**
+ * HELM-2: what an actor refused for `names` does next, after the refusal's first line. A lane asks the
+ * lead, never the person: with no `!` command where the lead decides. The lead approves its own call
+ * on its merits. What the person decides is brought to them by the lead.
+ */
+export function askHowTo(names, actor, root, config, { allows, need } = {}) {
+  const lane = actor?.kind === 'lane' ? actor.lane : undefined;
+  const pkg = [names].flat().some((n) => String(n).startsWith(DEPENDENCY_APPROVAL));
+  const brief =
+    need ??
+    (pkg
+      ? 'the package, the story and requirement that need it, what the project already has that you checked, and anything lighter that would do'
+      : 'the file, the story and requirement that need the change, and what you checked first');
+  if (decidedBy(names, config) === 'lead') {
+    if (actor?.kind === 'lead')
+      return `You decide this as the lead. Approve it only if the story's requirements need it${pkg ? ', nothing the project already depends on does the job, and it fits the principles and the layer it goes in' : ' and it keeps to the spec and the architecture'}:\n  Decided by the lead: ${delegateCommand(names)}`;
+    return `The lead decides this, not the person. Hand the lead a change request and stop: ${brief}. The lead approves it, or tells you what to use instead.\n  Decided by the lead: ${delegateCommand(names, lane)}`;
+  }
+  if (actor?.kind === 'lead')
+    return `This is the person's decision: ask them, with what it's for and your recommendation. They approve it with\n${approvalHowTo(names, actor, root, allows, config)}`;
+  return `The person decides this, and the lead brings it to them. Hand the lead a change request and stop: ${brief}. Their approval is\n${approvalHowTo(names, actor, root, allows, config)}`;
+}
 
 export const relayCommand = (names, lane) =>
   `node "${CLI}" approve ${[names].flat().join(' ')}${lane ? ` --lane ${lane}` : ''} --reason "<the person's words>"`;
@@ -370,7 +412,7 @@ export function dropRequests(root, which, { by, reason = null }, now = Date.now(
  * actor, names and command or file while one is still open count as one request. Recording never
  * changes the refusal, so any failure here is ignored.
  */
-export function recordRequest(root, actor, names, what, why, now = Date.now()) {
+export function recordRequest(root, actor, names, what, why, now = Date.now(), extra = {}) {
   // A read-only agent (a reviewer) is never approved to write: what it changed goes back, not to the
   // person as a request.
   if (actor?.kind === 'readonly') return;
@@ -382,6 +424,7 @@ export function recordRequest(root, actor, names, what, why, now = Date.now()) {
       names: [names].flat(),
       what: String(what).slice(0, 200),
       why: String(why).slice(0, 300),
+      ...extra,
     };
     if (openRequests(root, now).some((r) => sameRequest(r, request))) return;
     const file = requestsFile(root);
@@ -715,7 +758,11 @@ export function writeProblem(actor, rel, root, config) {
   // and every committed change is in the audit log. Anyone else needs a person's approval as well.
   if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
     recordRequest(root, actor, guarded.approval, rel, guarded.why);
-    return `${rel} is ${guarded.why} and needs a person's approval. Ask the lead (a person) to run\n${approvalHowTo(guarded.approval, actor, root, undefined, config)}`;
+    const who =
+      decidedBy(guarded.approval, config) === 'lead'
+        ? "the lead's approval"
+        : "a person's approval";
+    return `${rel} is ${guarded.why} and needs ${who}. ${askHowTo(guarded.approval, actor, root, config)}`;
   }
   if (matchesAny(rel, config.anyActor)) return null;
   if (actor.kind === 'readonly') return readonlyProblem(actor, rel);

package/hooks/mod/decisions.mjs

@@ -227,9 +227,7 @@ function headlineOf(line, story) {
 function whyOf(line, check) {
   if (line.kind === 'held') {
     const c = line.held;
-    const rule = c.refusal ? firstSentence(c.refusal) : 'It needs an approval only you can give.';
-    const limits = limitsWhy(c.outside);
-    return limits ? `${rule} ${limits}` : rule;
+    return c.refusal ? firstSentence(c.refusal) : 'It needs an approval only you can give.';
   }
   if (line.kind === 'approvals')
     return line.request?.why ?? 'It needs an approval only you can give.';
@@ -279,23 +277,6 @@ function whyOf(line, check) {
 /** A refusal's first sentence: what the rule is, without the instructions meant for the agent. */
 const firstSentence = (text) => text.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? text;
 
-/**
- * Why the lead couldn't approve it itself, from `code-kit approve --delegated`'s refusal: nothing
- * delegated, or the delegated rules each name it missed ("dep-x: fewer than 1000 weekly downloads").
- */
-export function limitsWhy(outside) {
-  if (!outside) return null;
-  if (/delegates no approvals/.test(outside))
-    return "You haven't let the lead approve these itself.";
-  const misses = outside
-    .split('\n')
-    .filter((l) => /^\s{2}\S/.test(l))
-    .map((l) => l.trim());
-  return misses.length
-    ? `It's outside the limits you set for the lead: ${misses.join('; ')}.`
-    : null;
-}
-
 /** The story a line belongs to: the held call's or request's lane's story, the stalled story, the queued branch's. */
 function storyOf(line, state) {
   const stories = state?.stories ?? [];

package/hooks/mod/hold.mjs

@@ -13,6 +13,8 @@ const HOLDABLE = new Set(['dependency', 'approval', 'kit']);
 export function holdable(resultText) {
   const card = refusalCard(resultText);
   if (!card || !HOLDABLE.has(card.kind) || !card.request?.names.length) return null;
+  // HELM-6: what the lead decides is never held for the person; the lane asks the lead.
+  if (card.request.by === 'lead') return null;
   return { kind: card.kind, title: card.title, ...card.request };
 }