@warren-dean/code-kit 0.8.0 → 0.8.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.8.0",
+      "version": "0.8.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.8.0",
+  "version": "0.8.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,14 @@
 
 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.8.1 (2026-10-11)
+
+Fixes for projects set up before 0.8.0.
+
+- **No first merge for you here either.** A project set up before 0.8.0 has no code-kit rules on `main`, so its first merge still waited on you. Now the lead puts the rules you approved onto `main` itself (`code-kit queue rules`, a step the loop takes), without switching branches, and then merges the queue under them.
+- **Waiting on the merge queue isn't a broken plan.** Stories that depend on branches waiting to merge were reported as a dependency cycle, sending the build back to spec design. `next` now says they wait for the merge.
+- The band's key for decisions reads "d: Why, and what each choice does", not "d: d Why".
+
 ## 0.8.0 (2026-10-11)
 
 You decide what's built and the rules; the lead delivers it. Only real decisions reach you, each with the story behind it, and the whole build reads as one story from your request to now.

package/README.md

@@ -274,7 +274,7 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
 
 - **The band** sits above the prompt. While the build is moving (the lead mid-turn, an agent at work, the loop started) it opens with the mission: **goal**, the milestone being built and how many of its stories are done; **now**, what the lead is doing and the loop's state, with **Pause** or **Resume**; **next**, the step the loop takes next; and **agents**, a line per agent at work with its current tool and how long since. With Context Graph installed, a line says when a lane edited files without understanding them, and only then. Beneath, labelled **you**, what only you can decide, each with the story it's for ("for ST-4 Booking form (BOOK-1)"), and **d** ("Why, and what each choice does") opens it as a card in the Decisions tab; usage and the plan's pause are labelled **note**. While the loop runs, a lane's finished work is the lead's to review and merge, so it never waits here; with the loop off, Review and Merge are offered to you. With nothing happening and nothing waiting, the band is gone. It shows:
   - an agent's call held for you: installing a new package, writing or committing a protected file, or a lane changing the kit. Rather than stopping the agent, the call waits while the band asks ("web wants to install dayjs · 1:53"). **Approve** opens the confirmation and, once you confirm, the same call runs; **Refuse**, or no answer within `harness.hold.minutes` (2 unless set), refuses it as before. Under `autonomy: autonomous`, a call within `approvals.delegate` is approved as delegated without asking. Nothing is held under `claude -p` or the SDK, where nobody can answer;
-  - the lead loop, under `harness.autonomy`. `/code-kit:init` asks you how hands-off you want it. Until you've chosen, the loop's first step waits in the band ("code-kit can keep the build moving between your prompts") with **Keep going**, **Ask each time** and **Off**, and your answer is recorded as your setting. Once the lead has finished a turn, the loop keeps the build moving: with the lead idle and nothing typed in the prompt, it asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own, never the same step twice while nothing has changed. A step the lead was prompted with twice in a row and that is still next goes to you instead, in the band: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Go**. **Pause** and **Resume** stop and start it. Under `propose`, each step waits in the band for **Go**; under `off`, the loop does nothing. A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged, unless its work is done (it handed back, or its branch is in review or the merge queue); at `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times, and then the band flags the lane. When every story is done, the band says so and the loop stops. With `harness.agents.reviewer.on`, a finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it. A branch the lead's review passes joins the merge queue (`code-kit queue`). Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. There's no first merge for you: setting up commits the rules you approved straight onto the base. A merged lane's worktree is removed when it holds nothing uncommitted. A head that conflicts or fails verify goes back to its lane. The pane lists the queue, and lanes whose branch waits in it read `queued`;
+  - the lead loop, under `harness.autonomy`. `/code-kit:init` asks you how hands-off you want it. Until you've chosen, the loop's first step waits in the band ("code-kit can keep the build moving between your prompts") with **Keep going**, **Ask each time** and **Off**, and your answer is recorded as your setting. Once the lead has finished a turn, the loop keeps the build moving: with the lead idle and nothing typed in the prompt, it asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own, never the same step twice while nothing has changed. A step the lead was prompted with twice in a row and that is still next goes to you instead, in the band: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Go**. **Pause** and **Resume** stop and start it. Under `propose`, each step waits in the band for **Go**; under `off`, the loop does nothing. A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged, unless its work is done (it handed back, or its branch is in review or the merge queue); at `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times, and then the band flags the lane. When every story is done, the band says so and the loop stops. With `harness.agents.reviewer.on`, a finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it. A branch the lead's review passes joins the merge queue (`code-kit queue`). Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. There's no first merge for you: setting up commits the rules you approved straight onto the base, and in a project set up before that, the lead puts them there itself (`code-kit queue rules`) before its first merge. A merged lane's worktree is removed when it holds nothing uncommitted. A head that conflicts or fails verify goes back to its lane. The pane lists the queue, and lanes whose branch waits in it read `queued`;
   - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite;
   - stories finished and waiting for review: **Review** asks the lead to run `/code-kit:review` on the branch, and **Merge** runs `verify`, checks included, then merges if it passes;
   - a finish check failing in this session: **Lanes** opens the pane;
@@ -346,6 +346,7 @@ code-kit settings [--json]                                   # the harness setti
 code-kit settings set <key> <value> --reason "…"               # change one, as the person: written to the config and logged as a kit approval
 code-kit queue [--json]                                      # the merge queue: branches whose review passed, in order
 code-kit queue add|drop <branch>                              # the lead queues a branch its review passed, or takes it out
+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)
 code-kit queue merge --delegated|--person                     # merge the head, verified against the base as it is now; a conflict or failed verify sends it back to its lane
 code-kit loop [--json]                                        # whether the person paused the lead loop; other tools' background work pauses with it
 code-kit loop pause|resume                                    # the person's act, as Pause and Resume in the band

package/bin/code-kit.mjs

@@ -336,9 +336,82 @@ function configAt(ref) {
   return config ?? null;
 }
 
+/**
+ * SETUP-2: a project set up before setup committed its rules onto the base has none there, so nothing
+ * could be merged by the lead. `queue rules` commits the rules as committed on this branch (the ones the
+ * person approved) onto the base, as setup now does, without checking the base out: a commit of the base
+ * with those files changed, the base moved to it. Only while the base has no rules, and only the lead.
+ */
+function rulesOntoBase(root, config) {
+  const into = intoName ?? config.branches.protected[0];
+  const git = (args, opts = {}) =>
+    execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', ...opts }).trim();
+  const head = git(['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head === into)
+    die(
+      `You're on ${into}: commit ${file} here as setup does (\`git add ${file} && git commit\`), which the hooks allow while ${into} has no rules.`,
+    );
+  if (configAt(into))
+    return out(
+      `${into} already has code-kit's rules committed; the merge queue merges under them.`,
+    );
+  if (!configAt('HEAD'))
+    die(
+      `${head} has no ${file} committed. Commit the rules the person approved first, then run this again.`,
+    );
+  const used = git(['worktree', 'list', '--porcelain'])
+    .split('\n')
+    .some((l) => l === `branch refs/heads/${into}`);
+  if (used)
+    die(
+      `${into} is checked out in a worktree, so moving it here would leave that checkout behind. Commit ${file} in that checkout instead (the hooks allow it while ${into} has no rules).`,
+    );
+  // The rules, and the baseline of existing violations they were approved with.
+  const files = [file, BASELINE_FILE].filter((f) => {
+    try {
+      execFileSync('git', ['-C', root, 'cat-file', '-e', `HEAD:${f}`], { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const index = join(tmpdir(), `code-kit-rules-${process.pid}`);
+  const env = { ...process.env, GIT_INDEX_FILE: index };
+  try {
+    git(['read-tree', into], { env });
+    for (const f of files)
+      git(
+        ['update-index', '--add', '--cacheinfo', `100644,${git(['rev-parse', `HEAD:${f}`])},${f}`],
+        {
+          env,
+        },
+      );
+    const tree = git(['write-tree'], { env });
+    const before = git(['rev-parse', into]);
+    const commit = git(
+      [
+        'commit-tree',
+        tree,
+        '-p',
+        before,
+        '-m',
+        `code-kit's rules onto ${into}, as the person approved them on ${head}\n\nFrom now on ${into}'s committed rules decide who merges into it.`,
+      ],
+      { env },
+    );
+    git(['update-ref', `refs/heads/${into}`, commit, before]);
+  } finally {
+    rmSync(index, { force: true });
+  }
+  const now = configAt(into);
+  out(
+    `Committed ${files.join(' and ')} onto ${into}, from ${head}. ${now?.approvals.delegate?.merge ? 'The lead merges the queue from now on (code-kit queue merge --delegated).' : `${into}'s rules don't delegate merges, so the person merges the queue.`}`,
+  );
+}
+
 /** Why the first merge into `into`, which has no config committed yet, is the person's. */
 const firstMerge = (into, branch) =>
-  `${into} has no ${file} committed yet, so it delegates nothing: the first merge, which brings code-kit's rules onto ${into}, is the person's. Ask them to merge ${branch} from the code-kit band (Merge), or to run \`! node "${process.argv[1]}" queue merge --person\`. From then on, ${into}'s committed rules decide who merges.`;
+  `${into} has no ${file} committed yet, so it delegates nothing. Put the approved rules onto it first: \`node "${process.argv[1]}" queue rules\`. Then merge ${branch} again; from then on ${into}'s committed rules decide who merges.`;
 
 /** Why a merge didn't happen: `refused` (the rules), `verify` (problems) or `conflict`. */
 class MergeStop extends Error {
@@ -527,6 +600,7 @@ function queue() {
     const place = waiting(readQueue(root)).length;
     return out(`Queued ${branch} to merge${place > 1 ? `, ${place - 1} ahead of it` : ', next'}.`);
   }
+  if (sub === 'rules') return rulesOntoBase(root, config);
   if (sub === 'merge') {
     const byPerson = mergeMode();
     const entries = readQueue(root);
@@ -561,7 +635,7 @@ function queue() {
   }
   if (sub !== undefined)
     die(
-      'code-kit queue [--json] | queue add <branch> | queue drop <branch> | queue merge --delegated|--person',
+      'code-kit queue [--json] | queue add <branch> | queue drop <branch> | queue rules | queue merge --delegated|--person',
     );
   const entries = readQueue(root);
   if (flag('--json')) return out(JSON.stringify(entries, null, 2));
@@ -1194,7 +1268,7 @@ function usage() {
       '              | stops [--session id] [--json] | sent-back <branch> [--reason "…"]\n' +
       '              | settings [--json] | settings set <key> <value> --reason "…" [--via pane]\n' +
       '              | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +
-      '              | queue [--json] | queue add|drop <branch> | queue merge --delegated|--person\n' +
+      '              | queue [--json] | queue add|drop <branch> | queue rules | queue merge --delegated|--person\n' +
       '              | loop [--json] | loop pause|resume\n' +
       '              | map <story> [--json] | trail [--json] | journal [--json]\n' +
       '              | story <id> [--json] | timeline [--json]',

package/hooks/guard-bash.mjs

@@ -74,6 +74,7 @@ const packages = addedPackages(cmd);
 const approves = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+approve\b`));
 const delegatedMerge = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+(?:queue\s+)?merge\b`));
 const queues = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+queue\s+(?:add|drop)\b`));
+const rulesOntoBase = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+queue\s+rules\b`));
 const commits = runs(cmd, new RegExp(String.raw`^${GIT}commit\b`));
 if (error) {
   if (commits) block(`Blocked: ${error}\nFix the config before committing.`);
@@ -174,6 +175,10 @@ if (queues && actor.kind !== 'lead')
   block(
     `Blocked: only the lead puts branches in the merge queue, after its review passes them. Finish your story and commit it on your branch; the lead reviews it.\nCommand: ${cmd}`,
   );
+if (rulesOntoBase && actor.kind !== 'lead')
+  block(
+    `Blocked: only the lead puts code-kit's rules onto the protected branch. Finish your story and commit it on your branch; the lead takes it from there.\nCommand: ${cmd}`,
+  );
 if (delegatedMerge && actor.kind !== 'lead')
   block(
     `Blocked: only the lead merges into a protected branch. Finish your story and commit it on your branch; the lead reviews and merges it.\nCommand: ${cmd}`,

package/hooks/lib/next.mjs

@@ -180,11 +180,15 @@ export function nextStep(root, base) {
   // the person does, and always the first merge, which brings code-kit's rules onto the base.
   const delegation = queued.length ? mergeDelegation(root, config) : { delegated: false };
   const leadMerges = delegation.delegated && config.harness.autonomy === 'autonomous';
+  // SETUP-2: a base with no rules committed (a project set up before setup committed them there): the
+  // lead puts the approved rules onto it, and the queue merges under them from then on.
   if (queued.length && delegation.first)
-    attention.push(
-      `${queued[0]} passed review and is next to merge. ${delegation.into} has no code-kit config committed yet, so this first merge, which brings the rules onto it, is the person's (code-kit queue merge --person, or Merge in the code-kit band); after it, the lead merges.`,
+    return result(
+      'rules',
+      `${queued[0]} passed review and is next to merge, but ${delegation.into} has no code-kit rules committed yet. Put the rules the person approved onto it (code-kit queue rules); then the queue merges under them.`,
+      { args: delegation.into },
     );
-  else if (queued.length && !leadMerges)
+  if (queued.length && !leadMerges)
     attention.push(
       `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} for the person to merge (code-kit queue merge --person, or Merge in the code-kit band).`,
     );
@@ -227,6 +231,12 @@ export function nextStep(root, base) {
       'wait',
       `${building.join(', ')} ${building.length === 1 ? 'is' : 'are'} being built; nothing else can start until one finishes. A lane that stopped without finishing is dispatched again.`,
     );
+  // Stories waiting on branches in the merge queue wait for the merge, not on a broken plan.
+  if (queued.length)
+    return result(
+      'wait',
+      `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} to be merged; the stories that depend on ${queued.length === 1 ? 'it' : 'them'} start after.`,
+    );
   if (unbuildable.length)
     return result(
       'spec-design',

package/hooks/mod/decisions.mjs

@@ -50,7 +50,7 @@ function whyOf(line, check) {
   if (line.kind === 'proposal') return 'You asked to approve each step before the lead takes it.';
   if (line.kind === 'queue')
     return check?.firstMerge
-      ? 'main has no rules committed yet, so this first merge is yours; after it, the lead merges.'
+      ? 'The loop is off, so merging is yours. main has no rules committed yet: code-kit queue rules puts them there.'
       : "Your rules don't let the lead merge into main, so merges are yours.";
   if (line.kind === 'review') return 'The loop is off, so reviewing finished work is yours.';
   return null;

package/hooks/mod/loop.mjs

@@ -3,7 +3,7 @@
 // existing skills, and the hooks judge every call as before.
 
 /** The steps the loop hands the lead; the rest (spec-design, init, check) wait for the person. */
-const LEAD_STEPS = new Set(['dispatch', 'review', 'lead', 'merge']);
+const LEAD_STEPS = new Set(['dispatch', 'review', 'lead', 'merge', 'rules']);
 
 /**
  * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
@@ -19,6 +19,9 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
     return ids.length
       ? `Merge ${ids[0]}, next in the merge queue: run node "${cli}" queue merge --delegated. It verifies the branch against the base as it is now, and sends it back to its lane if it conflicts or fails.`
       : null;
+  // SETUP-2: the base has no rules yet; the lead puts the approved ones there, then merges as usual.
+  if (step.step === 'rules')
+    return `Put code-kit's approved rules onto ${ids[0] ?? 'the base'}: run node "${cli}" queue rules. It commits the rules as committed on this branch, without switching branches; after it, merge the queue as usual.`;
   if (step.step === 'dispatch')
     return ids.length
       ? `Dispatch ${ids.join(', ')}: run /code-kit:dispatch ${ids.join(' ')}.`
@@ -40,8 +43,9 @@ export const stepKey = (step) => `${step.step}:${step.args ?? ''}`;
 export function stepLabel(step) {
   const ids = (step.args ?? '').split(/\s+/).filter(Boolean).join(', ');
   const verb =
-    { dispatch: 'Dispatch', review: 'Review', lead: 'Build', merge: 'Merge' }[step.step] ??
-    step.step;
+    { dispatch: 'Dispatch', review: 'Review', lead: 'Build', merge: 'Merge', rules: 'Rules onto' }[
+      step.step
+    ] ?? step.step;
   return ids ? `${verb} ${ids}` : verb;
 }
 

package/hooks/mod/register.test.ts

@@ -2066,18 +2066,31 @@ test('MQ-2 where the person merges, the head of the queue waits in the band for
   expect(w.opened).toContain(RESULT);
 });
 
-test('MQ-2 the first merge, before the base has code-kit rules committed, is offered to the person', async ($, on) => {
+test("SETUP-2 with no rules on the base yet, the lead puts them there under autonomy: the band doesn't ask the person to merge", async ($, on) => {
   const w = project();
   (w.check as any).firstMerge = true;
   w.queue = [{ branch: 'lead/st-1', passed: '2026-10-10T00:00:00Z', state: 'waiting' }];
+  w.next = { step: 'rules', args: 'main', then: [] };
   await start($, on, w);
   const ui = await bandUi($);
-  expect(
-    await ui.find({
-      type: 'Text',
-      text: 'lead/st-1 is next to merge: the first merge is yours, then the lead merges',
-    }),
-  ).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: /next to merge/ })).toBeUndefined();
+  await ui.unmount();
+});
+
+test("SETUP-2 with the loop off, the merge is the person's, and its card says how the rules get onto main", async ($, on) => {
+  const w = project();
+  (w.check as any).firstMerge = true;
+  (w.check as any).harness = { autonomy: 'off' };
+  w.queue = [{ branch: 'lead/st-1', passed: '2026-10-10T00:00:00Z', state: 'waiting' }];
+  await start($, on, w);
+  const band = await bandUi($);
+  expect(await band.find({ type: 'Text', text: 'lead/st-1 is next to merge' })).toBeDefined();
+  await press($, 'band-decide');
+  await band.unmount();
+  const ui = await pane($, PANE);
+  expect((await ui.find({ key: 'decision-card' }))?.text).toMatch(
+    /code-kit queue rules puts them there/,
+  );
   await ui.unmount();
 });
 

package/hooks/mod/view.mjs

@@ -798,15 +798,13 @@ export function bandLines({
     });
   // MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge.
   const next = queue.find((e) => ['waiting', 'merging'].includes(e.state));
-  const leadMerges =
-    check?.delegatesMerge && (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
+  const autonomous = (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
+  // SETUP-2: with no rules on the base yet, the lead puts them there first and then merges.
+  const leadMerges = autonomous && (check?.delegatesMerge || check?.firstMerge);
   if (next && !leadMerges)
     lines.push({
       kind: 'queue',
-      // The first merge brings code-kit's rules onto the base, so it's the person's even under autonomy.
-      text: check?.firstMerge
-        ? `${next.branch} is next to merge: the first merge is yours, then the lead merges`
-        : `${next.branch} is next to merge`,
+      text: `${next.branch} is next to merge`,
       branch: next.branch,
       actions: [{ id: 'mergeQueue', label: 'Merge' }],
     });
@@ -931,7 +929,7 @@ export function band(lines, { Box, Text, Button }, onAction) {
           Text({ children: [''.padEnd(LABEL)] }),
           Button({
             key: 'band-decide',
-            label: 'd Why, and what each choice does',
+            label: 'Why, and what each choice does',
             hotkey: 'd',
             plain: true,
             onPress: () => onAction('decide', first),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",