@warren-dean/code-kit 0.30.2 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,7 +9,7 @@
9
9
  "name": "code-kit",
10
10
  "source": "./",
11
11
  "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",
12
- "version": "0.30.2",
12
+ "version": "0.31.0",
13
13
  "category": "development",
14
14
  "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
15
15
  "license": "MIT"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "code-kit",
3
- "version": "0.30.2",
3
+ "version": "0.31.0",
4
4
  "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",
5
5
  "author": {
6
6
  "name": "Warren Langeveldt"
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  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).
4
4
 
5
+ ## 0.31.0 (2026-11-05)
6
+
7
+ - **The project's own workspace packages are no new dependency.** `pnpm add @scope/pkg@workspace:*` (and `link:`, `file:` and `portal:` specs) adds one of the project's own packages, from no registry, but was refused as a new dependency that needs an approval. A registry package in the same command still needs its own.
8
+ - **`queue add` takes every `--with`.** `code-kit queue add <branch> --with a --with b` kept only `a`, so the group could be offered for merge before `b` was queued. Each `--with` now joins the group, as `--with a,b` does.
9
+ - **Harmless steps before a commit.** Making folders (`mkdir -p`), taking away a worktree (`git worktree remove`, `git worktree prune`) and unstaging (`git reset [HEAD] [--] <paths>`) in the same command as a commit were refused as commands that may write files. None changes a file the commit could take, so they're allowed. A reset to another commit, `git reset --hard` and a redirect are still refused.
10
+ - **The spec-check refusal says when only the table is missing.** A lane whose report was there but whose table header wasn't `| Requirement |` (an abbreviation such as `| Req |`) was told to run spec-check again, and kept retrying. The refusal now says the report has no requirement table and which header the gate looks for.
11
+ - **The review's screenshot for a screen another story designed.** verify and the merge queue ask for the review's screenshot of every registered screen a branch changes, but `code-kit designs evidence <story> …` and `code-kit designs <story>` only knew the screens whose design story was that story or one it depends on, so the command they named was refused. Both now include every registered screen the story's branch changes.
12
+ - **Vibe: hand the whole build to the lead.** A fourth answer to init's question of how hands-off the build is, `"harness": { "autonomy": "vibe" }`, chosen once the spec is done and code-kit is set up. The loop runs on its own, and every decision is the lead's: the specs for later milestones, the designs, CI, the kit, the standards, weakened tests on its own branches too, packages beyond the registry's rules (recorded with the rules they break), merges and pushes. The lead answers the open questions itself and records each in the brief's decision log. You're asked only for what nobody else can give, an account, a key, a payment or an act outside the repository: under vibe, `code-kit ask` needs `--needs account|key|payment|outside`. See the README's Vibe section.
13
+ - **The queue records a merge as soon as it lands.** `code-kit queue merge` now marks the branches merged the moment they're in the base, before it releases the stories' claims with the team provider and takes away the worktrees that are done with. Both can take minutes (a provider that's slow to answer, worktrees with big installs), and until now the queue showed the merged branches as still waiting all that time, or for good if the run was stopped meanwhile.
14
+ - **Reading the approval log beside other commands.** A shell read of `.claude/approval-log.jsonl` (`tail`, `grep`, `git log` and the rest) is no longer refused because something else runs in the same line, such as `git status` or a code-kit command after a `;` or `&&`. Each command that names the log must still only read it, and a line that defines a function or alias, sets a variable or has a heredoc is still judged whole.
15
+ - **A fork has the rights of the session it was forked from.** Claude Code's `fork` agent is a copy of the session's own conversation working in the background, but code-kit treated it as a read-only subagent, so the lead couldn't hand it work such as exporting approved designs into `design/`. A fork is now the lead (or the lane, in a lane's worktree), refused exactly what that session would be.
16
+ - **A throwaway merge to try a story isn't a merge into a branch.** Merging a story's branch where it lands on no branch (a detached worktree the command adds, a detached HEAD, or another repository it moves to with `cd`, also through a variable) is no longer refused as making a second main. A merge after a `cd` into another of the project's checkouts is judged against that checkout's branch, and the refusal names it. `git checkout -- <paths>` no longer reads as switching to a branch.
17
+ - **A commit is judged on the branch it lands on.** The protected branch's rules followed only where a command started and whether it switched to the protected branch anywhere, so a commit on a branch the command made first (`git switch -c x && git commit`), a commit followed by switching back to main, and a rebase in a worktree the command adds (after `cd` or with `git -C`) were all refused as commits on main. Each commit, merge or rebase is now judged on the branch it lands on, in the command's order; one that lands on the protected branch is still refused. Making a branch where the checkout stands (`git switch -c x`, `git checkout -b x`, with no start point) no longer counts as a command that may write files before a commit.
18
+ - **A file the design gate takes for a screen by mistake.** A file-based router keeps files that draw no screen beside its screens (an API route, middleware, a hook for links the phone hands the app), and a screens glob for the whole folder took them for screens, so a lane was told to design one first. The refusal now says what to do when the file draws no screen: ask the lead to leave it out with the screen's `not`. Init leaves out a router's layouts, API routes, middleware and special files from the start.
19
+ - **`code-kit designs` names an unnamed state.** A register entry whose state has no name or files is listed as `(unnamed) (no viewport): no files` instead of `undefined`.
20
+
5
21
  ## 0.30.2 (2026-11-04)
6
22
 
7
23
  Fixes from how code-kit is used: fewer commits refused after commands that write nothing, the setup commit takes the person's approval of the setup, and the fix check and the merge queue see more of a project.
package/README.md CHANGED
@@ -473,7 +473,7 @@ code-kit replay <story> [--json|--brief] # a story's state r
473
473
  code-kit reconcile [--json] # check what a stopped agent left open against git; the lead records what git can't settle with --act
474
474
  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
475
475
  code-kit requests drop <n>[,<n>…]|all [--reason "…"] # stop waiting on requests nobody needs answered (the lead, or Not needed in the pane)
476
- 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 band and the pane's Needs you
476
+ code-kit ask "<question>" [--story ST-n] [--blocks] [--why "…"] [--option "Label: what it does"]... [--needs account|key|payment|outside] # the lead asks you what it can't settle; it waits in your band and the pane's Needs you (under vibe, only with --needs)
477
477
  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
478
478
  code-kit report "<title>" --what "…" [--expected …] [--command …] [--refusal …] [--rule …] # with harness.report.on, an agent drafts a bug report for code-kit
479
479
  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
@@ -493,7 +493,7 @@ code-kit settings [--json] # the harness setti
493
493
  code-kit settings set <key> <value> --reason "…" # change one, as the person (approvals.<name> lead|person among them): written to the config and logged as a kit approval
494
494
  code-kit queue [--json] # the merge queue: branches whose review passed, in order, and any a team provider's open drift finding holds
495
495
  code-kit queue add|drop <branch> # the lead queues a branch at the commit its review passed, or takes it out
496
- code-kit queue add <branch> --with <branch>[,<branch>] # a branch that only lands together with others: merged as a group once all are queued
496
+ code-kit queue add <branch> --with <branch> [--with <branch>] # a branch that only lands together with others: merged as a group once all are queued
497
497
  code-kit queue rules # the lead puts the approved rules onto a base that has none yet (a project set up before 0.8.0)
498
498
  code-kit queue merge --delegated|--person # merge the head at the commit its review passed, verified against the base as it is now; a conflict or failed verify sends it back to its lane, a branch that moved since its review leaves the queue to be reviewed again, one the base already holds leaves it as merged, and one a team provider's open drift finding holds waits in its place until the finding clears
499
499
  code-kit queue pause --reason "…" | queue resume # the lead holds the whole queue on purpose: nothing merges and nothing offers a merge until it resumes; branches are still queued
@@ -531,36 +531,36 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
531
531
 
532
532
  `.claude/code-kit.json`. Globs use `*` (one segment), `**` (any depth), `**/` (zero or more folders), `?` and `{a,b}`. Patterns under `shell` are regular expressions.
533
533
 
534
- | Field | Required | What it is |
535
- | ------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
536
- | `version` | yes | `1` |
537
- | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
538
- | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
539
- | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
540
- | `docs.standards` | no | The project's standards (spec 22), default `docs/standards.md`: each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why`, `source` and, when enforced, `enforced by` naming the layer rule, protected path, check or shell rule that refuses a breach. The id's prefix is its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Each lane agent is given the ones for its layers; a refusal from an enforcing rule names the standard; reviews check the checked ones. Protect the file with the `standards` approval: removing a standard, or weakening a required one, always needs the person's, whatever is delegated |
541
- | `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
542
- | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory is always included, and the session's own folder in Claude Code's temporary folder (`/tmp/claude-<uid>/<project>/<session id>/`: its scratchpad and tool output), which the lanes may write too; another session's isn't. |
543
- | `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. |
544
- | `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners?, label? }`: the agent name maps a subagent to its lane; `label` names what the lane delivers ("Screens", "API contract"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the lane's name; `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. |
545
- | `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`. |
546
- | `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) holds their exported designs; an entry naming only a design tool's artboard doesn't open the gate. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
547
- | `layers[]` | no | `{ name, paths, mayImport, denyPackages?, label? }`: the first layer whose paths match a file owns it. A layer may always import itself. `label` names what the layer delivers ("Data", "Service"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the layer's name. |
548
- | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
549
- | `shell.block[]` | no | `{ pattern, why, person?, command? }`: never run. `person: true` marks a person's act, which the lead may do for them with `approvals.lead` on. `command: true` matches the pattern from the start of each command the line runs (after a package runner such as `npx` or `pnpm exec`, and inside `sh -c` or `eval`), with quoted text masked unless the pattern has quotes, so a grep, a heredoc or a message that mentions it isn't refused. Without it the pattern reads the whole line, except a read's quoted arguments: `grep "<command>" docs` doesn't run it |
550
- | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes. A read's quoted arguments don't count, as for `shell.block` |
551
- | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
552
- | `tests[]` | no | Globs naming the test files, in place of the conventions, for every rule that asks what a test is: weakened tests, a fix's tests, the tests that name a requirement, the code map and the security review. Default: a file named as a test (`*.test.*`, `*.spec.*`, `*.smoke.*`, `test_*.py`, `*_test.go`, `*_test.py`) or in a test folder (`test/`, `tests/`, `__tests__/`, `e2e/`, `smoke/`). Proving a fix keeps the files named as tests and takes the rest back, test-folder helpers included; with `tests` set, the files it names are the ones kept. |
553
- | `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. The checkout's `node_modules` and virtualenvs are copied in first (a copy-on-write clone where the disk has one), so it can't change the checkout's own. The merge queue runs it too, in the merged tree's checkout, when its manifests or lockfiles differ from the installs copied in; without it, the queue runs the install the lockfile calls for. |
554
- | `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). `timeoutSeconds` (240 unless set) is how long each command may run; one that runs out of time leaves its branch at the head of the merge queue rather than sending it back. |
555
- | `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). |
556
- | `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). |
557
- | `approvals.delegate` | no | `false`, or `{ protected?: [approval names], merge?: true, push?: true, tests?: 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`; with `push`, pushes the protected branch, never by force (yours unless you set it, since a push can deploy; read from the config committed on that branch); with `tests`, weakened tests on a lane's branch. Left out, the lead decides everything technical: every protected approval but `spec`, `design`, `ci` and `kit`, packages, merges and weakened tests (WHO-1); `false` keeps everything for you. Lanes ask the lead for these, never you. npm packages are also checked against the npm registry, and a Python lane's against PyPI; 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). |
558
- | `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 |
559
- | `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `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), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, the specs' titles and outcome lines, approvals, token use, the rules, the design register and the sessions at work; never code) to a provider that isn't GitHub. A provider may also supply an organisation's standards (`standards`, answering `{ standards, waivers, version }`, each standard in `docs.standards`' fields, each waiver `{ standard, paths?, expires?, reason?, approvedBy? }`): they apply as if in the project's file, which may extend or tighten one but weaken a required one only under a waiver. See docs/specs/16-teams.md, docs/specs/21-hub-adapter-and-reports.md and docs/specs/22-standards.md. |
560
- | `branches.protected` | no | Default `["main", "master"]` |
561
- | `branches.publish` | no | How a merge reaches the remote's base: `push` (the base is pushed, fast-forward only) or `pull-request` (for a base the remote only lets change through pull requests: code-kit opens one from `code-kit/publish-<base>` after each merge, and merges it where `approvals.delegate.push` is on, otherwise it waits for you). Left out, code-kit leaves pushing the base to you |
562
- | `execution.unrepeatable` | no | Patterns (regular expressions) for commands that can't safely run twice, such as a seed or a deploy. With migrations, the commands `shell.block` and `shell.restricted` name, and `git push`, an interrupted one is never run again on its own after a crash: the lead finds out what happened first (spec 26) |
563
- | `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` (code-kit's reviewer and the security reviewer; default `sonnet`), `agents.lanes.model` (the model each lane agent starts on, unless the lead's call or the lane's agent file names one: a model, or `story` for each story's `**Size:**` in the plan, raised for security requirements, fixes and send-backs; default the session's), `slices.open` (how many of the plan's slices are in focus: a free lane builds an open slice's stories first; default 1), `background.pauseAtPercent` (default 80), `compact.at` (compact the lead's context between turns once it's past this share of its window; default 40, 0 for never), `compact.milestone` (when a milestone finishes, compact the lead's context: `ask`, `auto` or `off`; default `ask`), `agents.lanes.contextLimit` (the context a lane agent may reach before it hands its story to a fresh agent; default 250,000 tokens), `notify.on` (a system notification when something new needs you; default `true`), `motion` (whether the pane's characters, clocks and the lead's rail move while work flows: `while-active` or `off`; default `while-active`) 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`. |
534
+ | Field | Required | What it is |
535
+ | ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
536
+ | `version` | yes | `1` |
537
+ | `docs.specs` | no | Folder of specs. With it, a lane needs a spec-check report before writing code on a branch |
538
+ | `docs.principles`, `docs.plan` | no | The engineering principles and the implementation plan |
539
+ | `docs.decisions` | no | Where agreed intents are recorded as numbered decision records (`code-kit intend record`); default `docs/decisions` |
540
+ | `docs.standards` | no | The project's standards (spec 22), default `docs/standards.md`: each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why`, `source` and, when enforced, `enforced by` naming the layer rule, protected path, check or shell rule that refuses a breach. The id's prefix is its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Each lane agent is given the ones for its layers; a refusal from an enforcing rule names the standard; reviews check the checked ones. Protect the file with the `standards` approval: removing a standard, or weakening a required one, always needs the person's, whatever is delegated |
541
+ | `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
542
+ | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory is always included, and the session's own folder in Claude Code's temporary folder (`/tmp/claude-<uid>/<project>/<session id>/`: its scratchpad and tool output), which the lanes may write too; another session's isn't. |
543
+ | `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. |
544
+ | `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners?, label? }`: the agent name maps a subagent to its lane; `label` names what the lane delivers ("Screens", "API contract"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the lane's name; `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. |
545
+ | `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`. |
546
+ | `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) holds their exported designs; an entry naming only a design tool's artboard doesn't open the gate. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
547
+ | `layers[]` | no | `{ name, paths, mayImport, denyPackages?, label? }`: the first layer whose paths match a file owns it. A layer may always import itself. `label` names what the layer delivers ("Data", "Service"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the layer's name. |
548
+ | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
549
+ | `shell.block[]` | no | `{ pattern, why, person?, command? }`: never run. `person: true` marks a person's act, which the lead may do for them with `approvals.lead` on. `command: true` matches the pattern from the start of each command the line runs (after a package runner such as `npx` or `pnpm exec`, and inside `sh -c` or `eval`), with quoted text masked unless the pattern has quotes, so a grep, a heredoc or a message that mentions it isn't refused. Without it the pattern reads the whole line, except a read's quoted arguments: `grep "<command>" docs` doesn't run it |
550
+ | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes. A read's quoted arguments don't count, as for `shell.block` |
551
+ | `postEdit[]` | no | `{ files, exclude?, run }`: after each edit of a matching file. `{file}` is the file. Exit 127 (tool not installed) is skipped. |
552
+ | `tests[]` | no | Globs naming the test files, in place of the conventions, for every rule that asks what a test is: weakened tests, a fix's tests, the tests that name a requirement, the code map and the security review. Default: a file named as a test (`*.test.*`, `*.spec.*`, `*.smoke.*`, `test_*.py`, `*_test.go`, `*_test.py`) or in a test folder (`test/`, `tests/`, `__tests__/`, `e2e/`, `smoke/`). Proving a fix keeps the files named as tests and takes the rest back, test-folder helpers included; with `tests` set, the files it names are the ones kept. |
553
+ | `regression.prepare` | no | A command run in a fresh checkout before a fix's tests run there without the fix, such as `npm ci`. The checkout's `node_modules` and virtualenvs are copied in first (a copy-on-write clone where the disk has one), so it can't change the checkout's own. The merge queue runs it too, in the merged tree's checkout, when its manifests or lockfiles differ from the installs copied in; without it, the queue runs the install the lockfile calls for. |
554
+ | `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). `timeoutSeconds` (240 unless set) is how long each command may run; one that runs out of time leaves its branch at the head of the merge queue rather than sending it back. |
555
+ | `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). |
556
+ | `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). |
557
+ | `approvals.delegate` | no | `false`, or `{ protected?: [approval names], merge?: true, push?: true, tests?: 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`; with `push`, pushes the protected branch, never by force (yours unless you set it, since a push can deploy; read from the config committed on that branch); with `tests`, weakened tests on a lane's branch. Left out, the lead decides everything technical: every protected approval but `spec`, `design`, `ci` and `kit`, packages, merges and weakened tests (WHO-1); `false` keeps everything for you. Lanes ask the lead for these, never you. npm packages are also checked against the npm registry, and a Python lane's against PyPI; 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). |
558
+ | `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 |
559
+ | `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `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), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, the specs' titles and outcome lines, approvals, token use, the rules, the design register and the sessions at work; never code) to a provider that isn't GitHub. A provider may also supply an organisation's standards (`standards`, answering `{ standards, waivers, version }`, each standard in `docs.standards`' fields, each waiver `{ standard, paths?, expires?, reason?, approvedBy? }`): they apply as if in the project's file, which may extend or tighten one but weaken a required one only under a waiver. See docs/specs/16-teams.md, docs/specs/21-hub-adapter-and-reports.md and docs/specs/22-standards.md. |
560
+ | `branches.protected` | no | Default `["main", "master"]` |
561
+ | `branches.publish` | no | How a merge reaches the remote's base: `push` (the base is pushed, fast-forward only) or `pull-request` (for a base the remote only lets change through pull requests: code-kit opens one from `code-kit/publish-<base>` after each merge, and merges it where `approvals.delegate.push` is on, otherwise it waits for you). Left out, code-kit leaves pushing the base to you |
562
+ | `execution.unrepeatable` | no | Patterns (regular expressions) for commands that can't safely run twice, such as a seed or a deploy. With migrations, the commands `shell.block` and `shell.restricted` name, and `git push`, an interrupted one is never run again on its own after a crash: the lead finds out what happened first (spec 26) |
563
+ | `harness` | no | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose`, `off` or `vibe`; default `autonomous`; `vibe` is autonomous with every decision the lead's, see [Vibe](#vibe)), `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` (code-kit's reviewer and the security reviewer; default `sonnet`), `agents.lanes.model` (the model each lane agent starts on, unless the lead's call or the lane's agent file names one: a model, or `story` for each story's `**Size:**` in the plan, raised for security requirements, fixes and send-backs; default the session's), `slices.open` (how many of the plan's slices are in focus: a free lane builds an open slice's stories first; default 1), `background.pauseAtPercent` (default 80), `compact.at` (compact the lead's context between turns once it's past this share of its window; default 40, 0 for never), `compact.milestone` (when a milestone finishes, compact the lead's context: `ask`, `auto` or `off`; default `ask`), `agents.lanes.contextLimit` (the context a lane agent may reach before it hands its story to a fresh agent; default 250,000 tokens), `notify.on` (a system notification when something new needs you; default `true`), `motion` (whether the pane's characters, clocks and the lead's rail move while work flows: `while-active` or `off`; default `while-active`) 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`. |
564
564
 
565
565
  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.
566
566
 
@@ -628,6 +628,12 @@ code-kit approve pillow --lane api --delegated --story ST-138 --reason "MED-5 ne
628
628
  - The merge commit says it was verified and delegated.
629
629
  - Committing or merging on a protected branch with git stays blocked for every actor, the lead included, as does switching to one and committing in the same command.
630
630
 
631
+ ## Vibe
632
+
633
+ Once the spec is done and code-kit is set up, `"harness": { "autonomy": "vibe" }` hands the whole build to the lead. The loop runs as under `autonomous`, and every decision the person would make is the lead's: the specs for later milestones, the screens' designs, CI, the kit, the standards, weakened tests (its own branches included), packages (beyond the registry's rules too, recorded with the rules each breaks), merges and pushes to the base (never by force). Whatever `approvals.delegate` says is set aside. The lead answers the brief's open questions and spec-design's, spec-check's and review's itself, recording each in the brief's decision log.
634
+
635
+ The person is asked only for what nobody else can give: `code-kit ask "…" --needs account|key|payment|outside` (an account with a service provider, an API key or secret, a payment, an act outside the repository such as DNS). Under vibe, `code-kit ask` refuses a question without `--needs`, and the lead builds everything else meanwhile. The project's `shell.block` rules, and the person's own acts (pausing the loop, choosing the lead session, changing the harness settings), stay as they are. What vibe gives up: nobody but the lead looks at a decision before it's built on, and a push to the base can deploy.
636
+
631
637
  ## Adapters
632
638
 
633
639
  Other tools share a project with code-kit and keep files of their own. An adapter tells code-kit about one such tool, without the core knowing its name. Each adapter lives in `hooks/lib/adapters/`, and declares:
package/bin/code-kit.mjs CHANGED
@@ -78,6 +78,7 @@ import {
78
78
  approvalSettings,
79
79
  committedConfig,
80
80
  effectiveConfig,
81
+ loadConfig,
81
82
  mergeDelegation,
82
83
  validate,
83
84
  withApprovalSetting,
@@ -158,7 +159,14 @@ import {
158
159
  recordFinding,
159
160
  replay as replayEvents,
160
161
  } from '../hooks/lib/events.mjs';
161
- import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/harness.mjs';
162
+ import {
163
+ SETTINGS,
164
+ VIBE,
165
+ VIBE_ASKS,
166
+ parseSetting,
167
+ settingOf,
168
+ withSetting,
169
+ } from '../hooks/lib/harness.mjs';
162
170
  import { claimLead, readLoop, releaseLead, writeLoop } from '../hooks/lib/loop-state.mjs';
163
171
  import {
164
172
  claimChanges,
@@ -291,8 +299,11 @@ const ownersGiven = [];
291
299
  for (let o = option('--owner'); o !== undefined; o = option('--owner')) ownersGiven.push(o);
292
300
  const storyGiven = option('--story');
293
301
  const whyGiven = option('--why');
302
+ const needsGiven = option('--needs');
294
303
  const whatGiven = option('--what');
295
- const withGiven = option('--with');
304
+ // `--with a --with b` and `--with a,b` alike.
305
+ const withsGiven = [];
306
+ for (let o = option('--with'); o !== undefined; o = option('--with')) withsGiven.push(o);
296
307
  const untilGiven = option('--until');
297
308
  const expectedGiven = option('--expected');
298
309
  const commandGiven = option('--command');
@@ -1041,6 +1052,10 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
1041
1052
  );
1042
1053
  }
1043
1054
  }
1055
+ // The branches are in the base now, so the queue says so at once: releasing the claims and taking
1056
+ // away the worktrees below can take minutes (a team provider that's slow to answer, big installs),
1057
+ // and a run stopped meanwhile would leave merged branches waiting.
1058
+ for (const b of [{ branch }, ...members]) settle(root, b.branch, 'merged');
1044
1059
  // TEAM-1: a merged story's claim ends, whoever merged it, and so does any an earlier merge left.
1045
1060
  const team = teamOf(config);
1046
1061
  const stories = [branch, ...members.map((m) => m.branch)].map(storyOfBranch).filter(Boolean);
@@ -1152,8 +1167,8 @@ function queue() {
1152
1167
  // The commit the review passed: the queue merges exactly it, and a branch that moves is reviewed again.
1153
1168
  const added = enqueue(root, branch, commit);
1154
1169
  // MQ-7: branches that only land together.
1155
- const partnersGiven = (withGiven ?? '')
1156
- .split(/[\s,]+/)
1170
+ const partnersGiven = withsGiven
1171
+ .flatMap((w) => w.split(/[\s,]+/))
1157
1172
  .filter(Boolean)
1158
1173
  .filter((b) => b !== branch);
1159
1174
  if (partnersGiven.length) setPartners(root, branch, partnersGiven);
@@ -1831,7 +1846,7 @@ function ciCommand() {
1831
1846
  out(` ${f.kind}: ${f.what}.\n Fix: ${f.fix}.`);
1832
1847
  }
1833
1848
  out(
1834
- "\nChanging CI is the person's to approve (approval ci). A release then runs the full suite once: code-kit release <version>.",
1849
+ `\nChanging CI is ${config.approvals.delegate?.protected?.includes('ci') ? "the lead's" : "the person's"} to approve (approval ci). A release then runs the full suite once: code-kit release <version>.`,
1835
1850
  );
1836
1851
  return;
1837
1852
  }
@@ -2366,7 +2381,12 @@ async function approve(given) {
2366
2381
  // WHO-2: a weakened test on a lane's branch, after the lead's review; on its own, the person's.
2367
2382
  if (name === TESTS_APPROVAL) {
2368
2383
  if (!rules.tests) outside.push(`${name}: weakened tests aren't delegated`);
2369
- else if (!laneName)
2384
+ else if (!laneName && rules.own) {
2385
+ // VIBE-2: under vibe the lead approves a weakened test on its own branch too.
2386
+ if (!storyGiven)
2387
+ outside.push(`${name}: name the story the weakened test is for, with --story ST-n`);
2388
+ else marks[name] = delegatedMark(`tests, the lead's own, for ${story.id} (vibe)`);
2389
+ } else if (!laneName)
2370
2390
  outside.push(
2371
2391
  `${name}: on your own branch a weakened test is the person's; you approve one only for a lane, with --lane`,
2372
2392
  );
@@ -2394,7 +2414,12 @@ async function approve(given) {
2394
2414
  const pypi = !npm && [...registries].some((r) => PYPI_MANAGERS.has(r));
2395
2415
  const facts = npm ? await npmFacts(pkg) : pypi ? await pypiFacts(pkg) : null;
2396
2416
  const problems = facts ? dependencyRuleProblems(facts, rules.dependencies) : [];
2397
- if (problems.length) outside.push(`${name}: ${problems.join('; ')}`);
2417
+ // VIBE-2: under vibe, beyond the registry rules is the lead's judgement, recorded with them.
2418
+ if (problems.length && rules.overRules)
2419
+ marks[name] = delegatedMark(
2420
+ `dependencies (${pkg}, judged by the lead over the registry rules: ${problems.join('; ')}) for ${story.id} (vibe)`,
2421
+ );
2422
+ else if (problems.length) outside.push(`${name}: ${problems.join('; ')}`);
2398
2423
  else
2399
2424
  marks[name] = delegatedMark(
2400
2425
  `dependencies (${pkg}${npm ? '' : pypi ? ', from PyPI' : `, from ${[...registries].join(', ')}, judged by the lead`}) for ${story.id}`,
@@ -2862,8 +2887,15 @@ function intendCommand() {
2862
2887
  * hooks refuse from agents; otherwise the lead recording what the person said in chat); `ask withdraw`
2863
2888
  * takes one back once it no longer needs the person.
2864
2889
  */
2865
- const ASK_USAGE = `code-kit ask "<question>" [--story ST-n] [--blocks] [--why …] [--option "Label: what it does"]...
2890
+ const VIBE_ASK_WORDS = {
2891
+ account: 'an account with a service provider, which only they can open',
2892
+ key: 'an API key, token or secret from their account',
2893
+ payment: 'a paid plan or anything that costs money',
2894
+ outside: 'an act outside the repository that only they can do, such as DNS or an app store',
2895
+ };
2896
+ const ASK_USAGE = `code-kit ask "<question>" [--story ST-n] [--blocks] [--why …] [--option "Label: what it does"]... [--needs account|key|payment|outside]
2866
2897
  asks the person what the lead can't settle; it waits in their Decisions tab
2898
+ (under vibe, only for what the lead can't give itself, named with --needs)
2867
2899
  code-kit ask [list] [--json] the questions waiting, and those answered lately
2868
2900
  code-kit ask answer <id> "<answer>"
2869
2901
  code-kit ask withdraw <id> --reason "…"`;
@@ -2918,6 +2950,15 @@ function askCommand() {
2918
2950
  `"${question}" isn't a question for the person; nothing was asked. Ask it as a sentence they can answer.\n${ASK_USAGE}`,
2919
2951
  );
2920
2952
  if (flag('--blocks') && !storyGiven) die('--blocks holds a story: name it with --story ST-n.');
2953
+ // VIBE-4: under vibe every decision is the lead's; the person is asked only for what nobody else can
2954
+ // give: an account, a key or secret, a payment, or an act outside the repository.
2955
+ const vibe = existsSync(resolve(file)) && loadConfig(root).config?.harness.autonomy === VIBE;
2956
+ if (needsGiven !== undefined && !VIBE_ASKS.includes(needsGiven))
2957
+ die(`--needs takes ${VIBE_ASKS.join(', ')}; nothing was asked.\n${ASK_USAGE}`);
2958
+ if (vibe && needsGiven === undefined)
2959
+ die(
2960
+ `Nothing was asked. Under vibe this is yours to decide, as the lead: choose what the spec, the principles and the architecture point to, record it in the brief's decision log with why, and carry on. Ask the person only for what you can't give yourself, naming it with --needs: ${VIBE_ASKS.map((k) => `${k} (${VIBE_ASK_WORDS[k]})`).join('; ')}.`,
2961
+ );
2921
2962
  const r = askQuestion(root, {
2922
2963
  by: 'lead',
2923
2964
  session: callerSession,
@@ -3215,6 +3256,23 @@ function standardsCommand() {
3215
3256
  process.exit(1);
3216
3257
  }
3217
3258
 
3259
+ /**
3260
+ * HAND-12: the approved designs a story's screens are built from: its own entries and its design
3261
+ * stories' (designsFor), and every registered screen its branch changes, which verify and the merge
3262
+ * queue ask the review's evidence for whichever design story the entry names.
3263
+ */
3264
+ function storyDesigns(root, config, entries, storyId, stories) {
3265
+ const own = designsFor(entries, storyId, stories);
3266
+ const story = stories.find((s) => s.id.toLowerCase() === String(storyId).toLowerCase());
3267
+ const branch = story ? `${story.lane}/${story.id.toLowerCase()}` : storyId;
3268
+ const base = config.branches.protected[0];
3269
+ const diff = spawnSync('git', ['-C', root, 'diff', '--name-only', `${base}...${branch}`], {
3270
+ encoding: 'utf8',
3271
+ });
3272
+ const changed = new Set(diff.status === 0 ? diff.stdout.split('\n').filter(Boolean) : []);
3273
+ return [...own, ...entries.filter((e) => changed.has(e.file) && !own.includes(e))];
3274
+ }
3275
+
3218
3276
  /**
3219
3277
  * HAND-3, HAND-5: the approved designs, from the design register. `designs <story>` gives the designs a
3220
3278
  * story's screens are built from (its own entries and its design stories'), each state's files and
@@ -3229,11 +3287,13 @@ function designsCommand() {
3229
3287
  if (rest[0] === 'evidence') return designEvidence(root, config, entries);
3230
3288
  const story = rest[0];
3231
3289
  const stories = config.docs?.plan ? readStories(root, config.docs.plan) : [];
3232
- const shown = (story ? designsFor(entries, story, stories) : entries).map((e) => ({
3233
- ...e,
3234
- handedOver: handedOver(e),
3235
- problems: entryProblems(root, e, config.docs?.specs),
3236
- }));
3290
+ const shown = (story ? storyDesigns(root, config, entries, story, stories) : entries).map(
3291
+ (e) => ({
3292
+ ...e,
3293
+ handedOver: handedOver(e),
3294
+ problems: entryProblems(root, e, config.docs?.specs),
3295
+ }),
3296
+ );
3237
3297
  if (flag('--json')) return out(JSON.stringify(shown, null, 2));
3238
3298
  if (!shown.length)
3239
3299
  return out(
@@ -3247,7 +3307,7 @@ function designsCommand() {
3247
3307
  out(` only in ${toolOf(e)}: hand it over with /code-kit:design --hand-over`);
3248
3308
  for (const st of e.states ?? [])
3249
3309
  out(
3250
- ` ${st.name} (${st.viewport ?? 'no viewport'}): ${[st.image, st.code].filter(Boolean).join(', ')}${st.why ? ` (no code: ${st.why})` : ''}`,
3310
+ ` ${st.name ?? '(unnamed)'} (${st.viewport ?? 'no viewport'}): ${[st.image, st.code].filter(Boolean).join(', ') || 'no files'}${st.why ? ` (no code: ${st.why})` : ''}`,
3251
3311
  );
3252
3312
  if (e.tokens) out(` tokens: ${e.tokens}`);
3253
3313
  for (const p of e.handedOver ? e.problems : []) out(` ✗ ${p}`);
@@ -3277,7 +3337,9 @@ function designEvidence(root, config, entries) {
3277
3337
  die(
3278
3338
  `${storyArg} has no branch here (${branch}): name the story whose branch you reviewed, or its branch.`,
3279
3339
  );
3280
- const designs = (story ? designsFor(entries, story.id, stories) : entries).filter(handedOver);
3340
+ const designs = (story ? storyDesigns(root, config, entries, story.id, stories) : entries).filter(
3341
+ handedOver,
3342
+ );
3281
3343
  const key = (v) =>
3282
3344
  String(v ?? '')
3283
3345
  .trim()