@warren-dean/code-kit 0.29.0 → 0.30.1

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.
@@ -414,8 +414,12 @@ export function bandLines({
414
414
  // build themselves, does a finished story wait in the band for their Review or Merge; otherwise the
415
415
  // loop prompts the lead (or, under propose, offers the step with Go).
416
416
  const loopOff = (check?.harness?.autonomy ?? 'autonomous') === 'off';
417
+ // LOOP-15: a story the lead holds isn't offered for review.
418
+ const heldStories = new Set((nextStep?.deferred ?? []).map((d) => d.story));
417
419
  const inReview = loopOff
418
- ? state.lanes.filter((l) => l.state === 'in review').map((l) => l.story)
420
+ ? state.lanes
421
+ .filter((l) => l.state === 'in review' && !heldStories.has(l.story?.id))
422
+ .map((l) => l.story)
419
423
  : [];
420
424
  if (inReview.length && !working) {
421
425
  const [story] = inReview;
@@ -458,13 +462,30 @@ export function bandLines({
458
462
  // MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge. HUBR-9: a
459
463
  // branch the team provider's drift findings hold (`drift`, from `queue --json`) isn't offered; it's said.
460
464
  const inQueue = queue.filter((e) => ['waiting', 'merging'].includes(e.state));
461
- const next = inQueue.find((e) => !e.drift?.length);
465
+ // MQ-8: the lead's pause of the queue (from `next`, or carried on each entry by `queue --json`);
466
+ // LOOP-15: a branch whose story the lead holds isn't offered either.
467
+ const queuePaused = nextStep?.queuePaused ?? inQueue.find((e) => e.paused)?.paused ?? null;
468
+ const next = queuePaused ? null : inQueue.find((e) => !e.drift?.length && !e.deferred);
462
469
  for (const e of inQueue.filter((x) => x.drift?.length && !working))
463
470
  lines.push({
464
471
  kind: 'drift',
465
472
  text: `${e.branch} is held by the drift check: ${e.drift[0].title || e.drift[0].conflictsWith}`,
466
473
  actions: [],
467
474
  });
475
+ if (queuePaused && !working)
476
+ lines.push({
477
+ kind: 'queuePaused',
478
+ text: `merge queue paused: ${queuePaused.reason}`,
479
+ actions: [],
480
+ });
481
+ const deferred = nextStep?.deferred ?? [];
482
+ if (deferred.length && !working)
483
+ lines.push({
484
+ kind: 'deferred',
485
+ text: `${deferred.length > 1 ? `${deferred.length} stories held: ` : ''}${deferred[0].words ?? `${deferred[0].story} is held: ${deferred[0].reason}`}`,
486
+ deferred,
487
+ actions: [],
488
+ });
468
489
  const autonomous = (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
469
490
  // SETUP-2: with no rules on the base yet, the lead puts them there first and then merges.
470
491
  const leadMerges = autonomous && (check?.delegatesMerge || check?.firstMerge);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.29.0",
3
+ "version": "0.30.1",
4
4
  "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
5
5
  "license": "MIT",
6
6
  "author": "Warren Langeveldt",
@@ -5,7 +5,7 @@ description: Design a design story's screens with the person before any of them
5
5
 
6
6
  # Design before code
7
7
 
8
- A screen is designed and approved before anyone builds it. The design gate refuses a lane writing a screen file until the design register lists it, and the plan's screen stories depend on their design story, so nothing is dispatched early. Designing is the lead's work with the person: you propose, they decide.
8
+ A screen is designed and approved before anyone builds it. The design gate refuses a lane writing a screen file until the design register holds its exported design (an entry naming only an artboard in the tool doesn't count), and the plan's screen stories depend on their design story, so nothing is dispatched early. Designing is the lead's work with the person: you propose, they decide.
9
9
 
10
10
  The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
11
11
 
@@ -13,7 +13,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
13
13
 
14
14
  For each story given (`**Lane:** design` in the plan):
15
15
 
16
- - read the requirements it cites and the `## Screens` section of their specs: each screen, what it shows, what the person can do there, and its empty, loading and error states;
16
+ - read the requirements it cites and the `## Screens` section of their specs: each screen, what it shows, what the person can do there, and its empty, loading and error states. A screen is a `###` or `####` heading, a `- **Name** (…)` bullet or a table row, by its exact name, with a `**States:**` line or a States column. If the story designs only some of a spec's screens, name them in the plan with a `**Screens:**` line under the story;
17
17
  - read the architecture for the design tool and the folders screens live in, and the principles for the brand, theme and accessibility targets;
18
18
  - look at the designs already approved (`design/register.json` and what it links to), so the new screens match them.
19
19
 
@@ -74,11 +74,11 @@ For each approved screen, add an entry to the register, naming the code file the
74
74
 
75
75
  `story` is this design story. One design can serve several code files, such as the web and the mobile screen: each has its own entry, naming the same states. Committing the register is refused while an entry names a file that isn't there, a hash that isn't the file's, a state with no image, or leaves out a state the spec lists for the screen; `code-kit designs` lists every entry and what's wrong with it.
76
76
 
77
- The register is protected by the `design` approval, which is the person's: writing it is refused until they approve, and in a session with the code-kit mod the write waits in the band for their Approve. Give the approval a reason in their words ("bookings list and detail, as shown"). Then commit the designs and the register on `design/st-<n>`, and review and merge it like the lead's own story. Once it's merged, `code-kit next` dispatches the screen stories that waited on it.
77
+ The register is protected by the `design` approval, which is the person's: writing it is refused until they approve, and in a session with the code-kit mod the write waits in the band for their Approve. Give the approval a reason in their words ("bookings list and detail, as shown"). Then commit the designs and the register on `design/st-<n>`. Commit each screen as the person approves it: the story reads as in progress until every screen it designs is in the branch's register (or you set its `**Status:**` to `review` in the plan), and then `code-kit next` sends it to review. Review and merge it like the lead's own story. Once it's merged, `code-kit next` dispatches the screen stories that waited on it.
78
78
 
79
79
  ## Handing over designs approved before (`--hand-over`)
80
80
 
81
- `code-kit next` names register entries whose design is only in a design tool ("6 approved screens are only in paper"). For each, find the artboard the entry names, and ask the person whether it's still the design they approved: the tool's copy may have changed since. Once they confirm, export it as in step 4 and rewrite its entry as in step 5. Then, for each of those screens that's already built, compare the build with the export as the review does (each state's screenshot beside its PNG), and add a fix story to the plan for each difference, citing the screen's requirements.
81
+ `code-kit next` names register entries whose design is only in a design tool ("6 approved screens are only in paper"), and holds every story that builds one of those screens, giving the `design` step with `handOver: true` and the design stories to hand over; a lane's write to such a screen is refused until it's handed over. For each, find the artboard the entry names, and ask the person whether it's still the design they approved: the tool's copy may have changed since. Once they confirm, export it as in step 4 and rewrite its entry as in step 5. Then, for each of those screens that's already built, compare the build with the export as the review does (each state's screenshot beside its PNG), and add a fix story to the plan for each difference, citing the screen's requirements.
82
82
 
83
83
  ## 6. Report
84
84
 
@@ -71,7 +71,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
71
71
  - `screens`: a glob for each such lane's screen files (routes, pages, views), from the architecture's folders, with `not` for tests and stories;
72
72
  - `howTo`: "Design it first: run /code-kit:design for this area's design story, and a person approves it.";
73
73
  - a `protected` entry for the register (approval `design`, why "only approved designs are built"). Never put `design` in `approvals.delegate`: approving a design is the person's.
74
- - **`shell.block`:** deploy, release and production commands reserved for CI or a person.
74
+ - **`shell.block`:** deploy, release and production commands reserved for CI or a person. Each rule that names a command (`cdk deploy`, `supabase db push`, `terraform apply`) gets `"command": true`, with a pattern for the command and its arguments (`"cdk\\s+deploy\\b"`), so a grep, a heredoc or a commit message that mentions the command isn't refused, while running it, after `cd …`, through `npx` or `pnpm exec`, or in `sh -c`, still is. Leave `command` out only for a rule about the whole line, such as a download piped into a shell.
75
75
  - **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
76
76
  - **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
77
77
  - **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
@@ -120,6 +120,11 @@ Draft, alongside the config:
120
120
  - Leave out the template's `Always:` list: it's code-kit's part, which `code-kit instructions --write` adds once the config is written, between its markers.
121
121
  - If an agent already exists, keep its content and add only what's missing.
122
122
  - Drop the spec-check lines if the config has no `docs.specs`.
123
+ - **The design tool, for reference (HAND-8):** where the architecture or the config names a design tool with an MCP server (Paper, Figma, Pencil), add that server's read-only tools to the `tools:` line of every lane agent that builds screens and of the QA lane's agent, and fill the template's **Design tool** line. Name the tools as this session lists them (`mcp__<server>__<tool>`, the server as it's installed here or in `.mcp.json`), and only the ones that read; never one that writes, exports, opens or switches a file:
124
+ - **Paper:** `get_basic_info`, `get_selection`, `get_children`, `get_tree_summary`, `find_nodes`, `get_node_info`, `get_jsx`, `get_computed_styles`, `get_fill_image`, `get_font_family_info`, `get_tokens`, `get_screenshot`, `get_guide`, `list_resources`, `list_comment_threads`, `get_comment_thread`. Not `write_html`, `create_*`, `update_*`, `set_*`, `delete_*`, `duplicate_nodes`, `move_nodes`, `rename_*`, `arrange_pages`, `finish_working_on_nodes`, `export`, `export_combined_pdf` or `open_file`.
125
+ - **Figma:** its read tools (`get_design_context`, `get_metadata`, `get_screenshot`, `get_variable_defs`, `get_code_connect_map`, and `get_code` or `get_image` where the server has them). Nothing that writes to the file.
126
+ - **Pencil, or another tool:** the tools whose names and descriptions say they only read (`get_…`, `list_…`, `find_…`, screenshots, snapshots); leave out any that edits, creates or saves. When it isn't clear, leave it out and say so.
127
+ The lanes still build from the register's exported files: they're the approved record, which the gate and the review hold the build to; the tool's live copy may have changed since, so it's for what the export can't carry (how parts relate, other artboards, interactions).
123
128
  - **A security reviewer:** write `.claude/agents/security-reviewer.md` from `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, in the same approval as the lane agents, whenever the product handles sign-in, personal data, payments, input from outside (forms, APIs, webhooks, uploads) or secrets. That's almost every product; leave it out only for one with none of these, such as a static site or a local tool with no accounts, and say why. It is a reviewer, not a lane: no entry in `lanes`, no paths, and only read-only tools (Read, Grep, Glob, and Bash for commands that change nothing), so the hooks treat it as read-only too. Fill it in from the docs (or the code, for brownfield):
124
129
  - what's sensitive, who might attack it and the trust boundaries, from the specs' `## Threat model` sections (brownfield, or specs without one: from the data the code stores and the routes it exposes, as a question to the person);
125
130
  - the spec files it reads;
@@ -30,6 +30,7 @@ It returns `step`, `why`, `args`, `then` (steps that can follow straight after)
30
30
  | A lane waits on a request you decide | `decide`: approve it, or answer with an alternative |
31
31
  | Stories finished on their branches | `review`, then `dispatch` what's ready |
32
32
  | Design stories ready (`**Lane:** design`) | `design`, then `dispatch` what needs no design |
33
+ | Ready stories whose screens' designs are only in the tool | `design` with `handOver: true`: `--hand-over` first |
33
34
  | Stories ready | `dispatch` |
34
35
  | The lead's own stories ready (`**Lane:** lead`) | `lead`: the lead builds them itself |
35
36
  | Stories being built, nothing else can start | wait |
@@ -28,13 +28,14 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" verify --base <base>
28
28
 
29
29
  - that every protected change is in the approval log, which is append-only;
30
30
  - new layer violations, and a baseline that grew;
31
- - screens without an approved design;
31
+ - screens without an approved design, or with one only in the design tool;
32
+ - for a lane's branch that builds screens, each approved state the review hasn't yet compared and recorded ("Builds compared with their designs"): it lists the comparisons step 3 still owes, and clears as you record each screenshot, so it isn't a reason on its own to send the branch back;
32
33
  - committed secrets;
33
34
  - tests weakened (deleted, skipped or focused, cut down, or a snapshot rewritten) without the person's `tests` approval in the log;
34
35
  - for a fix (its story has `**Fixes:**`, or the branch is `<lane>/fix-…`), that its tests fail without the fix, as the bug, and pass with it;
35
36
  - the project's checks for the changed files.
36
37
 
37
- Any problem it reports means the branch goes back. Don't fix a lane's code yourself; the lead doesn't write lane paths.
38
+ Any other problem it reports means the branch goes back. Don't fix a lane's code yourself; the lead doesn't write lane paths.
38
39
 
39
40
  ## 3. Check the work against the story
40
41
 
@@ -48,7 +49,14 @@ Read the story and every requirement it cites. Then start from what's already be
48
49
  - **Its journeys still pass end to end:** where the project has a QA lane, run the end-to-end suites that cover this story's requirements (the qa lane's command, filtered to them) against the branch. A journey that broke fails the review, even when the story's own tests pass. A story the QA lane delivered is reviewed the same way: each journey's test proves the requirements it cites, through the real screens and services, with no mocked responses.
49
50
  - **The spec-check report matches:** its table has no row still `missing` or `conflicts` without an answer, and its questions were answered, not guessed.
50
51
  - **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements) are sent back, or split into their own story. A new dependency is yours to judge, as in `/code-kit:decide`: the story's requirements need it, nothing the project has does the job, and it fits the principles and the layer. Only what crosses a guardrail (the spec, a contract, the architecture) is the person's call.
51
- - **Built to its design:** for a story that builds screens, `code-kit designs ST-<n>` lists each screen's approved states. Take a screenshot of each built state at the design's viewport (the project's end-to-end runner, or a headless browser) and set it beside the state's PNG. A missing state or a different layout is a blocker, naming the state and its design file; different copy or components fail it too; spacing within the design system's scale is a nit. A state the build can't serve yet (the contract has no field for what the design shows) goes in the report with what's missing, and you add the story that provides it, rather than leaving a gap nobody sees.
52
+ - **Built to its design:** for a story that builds screens, `code-kit designs ST-<n>` lists each screen's approved states. Take a screenshot of each built state at the design's viewport (the project's end-to-end runner, or a headless browser) as a PNG, and set it beside the state's PNG. A missing state or a different layout is a blocker, naming the state and its design file; different copy or components fail it too; spacing within the design system's scale is a nit. Record each screenshot you compared, whatever the verdict:
53
+
54
+ ```bash
55
+ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" designs evidence ST-<n> <screen file> <state> <screenshot.png>
56
+ ```
57
+
58
+ It's refused when the screenshot isn't a PNG at the design's viewport (1x to 4x); take it again at that size. `verify`, and the merge queue, report every approved state of the branch's screens with no screenshot recorded since the screen last changed, so a branch that moves after your review is compared again. A state the build can't serve yet (the contract has no field for what the design shows) goes in the report with what's missing, and you add the story that provides it, rather than leaving a gap nobody sees.
59
+
52
60
  - **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
53
61
  - **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
54
62
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: {{agent}}
3
3
  description: {{what this lane builds, in one sentence}} Use for {{the paths or kinds of work it owns}}.
4
- tools: Read, Grep, Glob, Edit, Write, Bash
4
+ tools: Read, Grep, Glob, Edit, Write, Bash{{, the design tool's read-only MCP tools, for a lane that builds screens and the QA lane (init, HAND-8)}}
5
5
  ---
6
6
 
7
7
  You are the {{lane}} engineer for this repository.
@@ -11,6 +11,7 @@ You are the {{lane}} engineer for this repository.
11
11
  **Specs:** {{the spec files this lane reads}}
12
12
  **Skills to use:** spec-check{{, every project skill whose recipe touches this lane's paths}}
13
13
  **Prove your work with:** `{{the command that proves this lane's work}}`
14
+ {{if the lane builds screens or tests them, and the architecture names a design tool with an MCP server}}**Design tool (reference only):** you can read {{the tool}} through its read-only tools. Build to the exported files the design register names: they're the approved design, which the gate and the review hold your screen to. The tool's copy may have changed since it was approved; use it only for what the export can't show.{{end}}
14
15
 
15
16
  Lane rules:
16
17
  {{- one line per rule the docs set for this lane}}
@@ -30,6 +30,8 @@ The build runs from the specs in `{{docs.specs}}` and the stories in `{{docs.pla
30
30
 
31
31
  {{if ci}}Pull requests run `code-kit verify`, and it must pass before a person merges to a protected branch.{{end}}
32
32
 
33
+ When you mean to leave a story alone for a while (it waits on something outside the build, or on a date), hold it rather than letting the loop ask about it again: `code-kit defer <story> --reason "…" [--until <date>]`, and `code-kit defer release <story>` when it can go on. `code-kit queue pause --reason "…"` holds the whole merge queue the same way, until `code-kit queue resume`.
34
+
33
35
  A story reaches the base only through the merge queue: never merge a story's branch into another branch with git. Where the remote's base only moves through pull requests, `"branches.publish": "pull-request"` has code-kit open them after each merge. The merge queue checks each story before it merges, so the project's full CI runs on its release branches, not on every merge. Releasing is the person's decision: when they ask for a release, cut it with `code-kit release <version>`, which branches `release/<version>` from the base and pushes it, and the full CI runs there once. Never cut one unasked. `code-kit ci check` says what in the project's workflows still runs per story, and `code-kit ci usage` what the project spent on GitHub Actions.
34
36
 
35
37
  Changing the rules means editing `.claude/code-kit.json` (the lead only), then running the `code-kit:check` skill.