@warren-dean/code-kit 0.16.0 → 0.16.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.16.0",
+      "version": "0.16.1",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,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.16.1 (2026-10-16)
+
+The lead loop stops asking for stories that are waiting on other work.
+
+- When the lead says a story isn't due yet because it waits on work still going, such as a paired story a lane is building, a rebuild or a check running, the loop parks that story. A parked story is left out of every step, so a step that names it with others prompts the lead only for the others. Before, the loop held a declined step only while the step stayed exactly the same, so when one more story became ready, or any lane committed, it prompted the same reviews again.
+- A parked story wakes when what it waits on moves: its own branch or state, the stories the lead named, or the unfinished stories in the plan that depend on it. Other lanes' commits don't wake it. After 30 minutes with nothing moving, the lead is asked once more.
+- The band's next row says what each parked story waits on. A step the lead declined for another reason no longer holds up every other step.
+
 ## 0.16.0 (2026-10-16)
 
 The lead runs the team inside your guardrails, and lanes ask the lead, never you.

package/README.md

@@ -332,6 +332,7 @@ The loop keeps the build moving between your prompts, under `harness.autonomy`.
 
 - **Each step.** Once the lead has finished a turn, with the lead idle and nothing typed in the prompt, the loop asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own. It never prompts the same step twice while nothing has changed, and never a story an agent is still on: one its lane agent is building, or a reviewer is reviewing, waits until that agent finishes ("waiting: ST-10 is still with its agent").
 - **It reads the lead's reply first.** Before prompting again, the loop reads the lead's last reply with a side call over the lead's own conversation. A reply that waits on you (a question, a design to look at, an approval), or a turn you stopped, holds the loop until you answer or speak to the lead: the band says what the lead waits on, and its question is asked in Claude Code's own question dialog. A step the lead didn't take waits in the band with its reason and **Ask again**.
+- **Stories waiting on other work.** When the lead says a story isn't due yet because it waits on work still going (a paired story a lane is building, a rebuild, a check running), the loop parks that story and leaves it out of every step, so a step naming it with others prompts only the others. It wakes when what it waits on moves: its own branch, the stories the lead named, or the unfinished stories that depend on it. Other lanes' commits don't wake it, and after 30 minutes with nothing moving the lead is asked once more.
 - **A step that doesn't move.** One the lead was prompted with twice in a row that is still next goes to you instead: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Ask again**.
 - **Designs.** A design story is handed to the lead once a session; while you and the lead design it, the loop leaves it to you.
 - **One session runs it.** The first session whose loop acts runs it for the project. Another session you open there, for any reason, never prompts its lead: its band reads "the loop runs in another session", with **Lead from here** to move the loop to it.

package/hooks/mod/loop.mjs

@@ -40,8 +40,8 @@ export function storiesInFlight(agents) {
  * gives way to the next one `next` listed; with nothing left, the loop waits, saying for what, until an
  * agent finishes (which moves the project on).
  */
-export function withoutInFlight(step, inFlight) {
-  if (!step || !inFlight?.size) return step;
+export function withoutInFlight(step, inFlight, parked = new Map()) {
+  if (!step || (!inFlight?.size && !parked?.size)) return step;
   const chain = [step, ...(step.then ?? [])].map(({ then: _then, ...s }) => s);
   const kept = [];
   const busy = [];
@@ -51,19 +51,72 @@ export function withoutInFlight(step, inFlight) {
       continue;
     }
     const ids = (s.args ?? '').split(/\s+/).filter(Boolean);
-    const free = ids.filter((id) => !inFlight.has(id.toUpperCase()));
-    busy.push(...ids.filter((id) => inFlight.has(id.toUpperCase())));
+    const held = (id) => inFlight?.has(id.toUpperCase()) || parked?.has(id.toUpperCase());
+    const free = ids.filter((id) => !held(id));
+    busy.push(...ids.filter(held));
     if (free.length) kept.push({ ...s, args: free.join(' ') });
   }
   if (kept.length) return { ...kept[0], ...(kept.length > 1 ? { then: kept.slice(1) } : {}) };
-  const names = [...new Set(busy)];
+  const names = [...new Set(busy.map((id) => id.toUpperCase()))];
+  const working = names.filter((id) => inFlight?.has(id));
+  // LOOP-13: what each parked story waits on, as the lead said.
+  const waits = names
+    .filter((id) => !inFlight?.has(id))
+    .map(
+      (id) =>
+        `${id} waits${parked.get(id)?.on?.length ? ` on ${parked.get(id).on.join(', ')}` : ''}`,
+    );
   return {
     step: 'wait',
-    why: `${names.join(', ')} ${names.length === 1 ? 'is' : 'are'} still with ${names.length === 1 ? 'its agent' : 'their agents'}; the loop goes on when one finishes`,
+    why: [
+      working.length
+        ? `${working.join(', ')} ${working.length === 1 ? 'is' : 'are'} still with ${working.length === 1 ? 'its agent' : 'their agents'}`
+        : null,
+      ...waits,
+    ]
+      .filter(Boolean)
+      .join('; ')
+      .concat('; the loop goes on when one moves'),
     inFlight: names,
   };
 }
 
+/** LOOP-13: how long a parked story waits with nothing it waits on moving, before the lead is asked again. */
+export const PARK_MS = 30 * 60_000;
+
+/**
+ * LOOP-13: the stories to watch while `id` is parked: itself, the stories the lead said it waits on,
+ * and the stories that depend on it and aren't done (a pair the lead merges together).
+ */
+export function parkWatch(id, on = [], stories = []) {
+  const dependents = stories
+    .filter((s) => (s.dependsOn ?? []).includes(id) && s.state !== 'done')
+    .map((s) => s.id);
+  return [...new Set([id, ...on, ...dependents])];
+}
+
+/**
+ * LOOP-13: where the watched stories stand, as one string: each one's state, its branch's commit and
+ * whether an agent is at work on it. A parked story wakes when this changes.
+ */
+export function storiesSignature(ids, stories = [], heads = new Map(), inFlight = new Set()) {
+  return ids
+    .map((id) => {
+      const s = stories.find((x) => x.id === id);
+      return `${id}:${s?.state ?? '?'}:${s?.branch ? (heads.get(s.branch) ?? '') : ''}:${inFlight.has(id) ? 'busy' : ''}`;
+    })
+    .join('|');
+}
+
+/** The story ids a step names, upper-cased: `review ST-158 ST-172` gives ST-158 and ST-172. */
+export const stepStories = (step) =>
+  STORY_STEPS.has(step?.stepKind ?? step?.kind ?? step?.step)
+    ? String(step?.target ?? step?.args ?? '')
+        .split(/\s+/)
+        .filter((id) => /^ST-\d+$/i.test(id))
+        .map((id) => id.toUpperCase())
+    : [];
+
 /**
  * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
  * take. Every ready story is named: the dispatch skill decides how many lanes go (LOOP-2). A prompt
@@ -157,7 +210,7 @@ export const nudgeText = (minutes) =>
   `No tool call for ${minutes} minutes: report where you are, or carry on.`;
 
 /** LOOP-11: what a lead turn left the build at, as the loop reads the lead's reply. */
-export const OUTCOMES = new Set(['done', 'started', 'needs-person', 'blocked']);
+export const OUTCOMES = new Set(['done', 'started', 'needs-person', 'blocked', 'waiting']);
 const ANSWER_SHOWN = 4000;
 
 /**
@@ -175,11 +228,12 @@ export function outcomePrompt({ prompt = null, answer = '' }) {
       : "The person prompted you, and code-kit's lead loop is about to prompt you with the build's next step.",
     `Your reply ended your turn. It read:\n"""\n${shown}\n"""`,
     'Say where that reply left things, so the loop knows whether to prompt you again. Answer with one JSON object and nothing else:',
-    '{"outcome": "done" | "started" | "needs-person" | "blocked", "question": "…", "options": [{"label": "…", "effect": "…"}], "reason": "…"}',
+    '{"outcome": "done" | "started" | "needs-person" | "blocked" | "waiting", "question": "…", "options": [{"label": "…", "effect": "…"}], "reason": "…", "waits": [{"story": "ST-n", "on": ["ST-n"], "why": "…"}]}',
     '- done: you finished what was asked, or there was nothing to do.',
     '- started: you started work that carries on without you, such as lane agents.',
     "- needs-person: you asked the person something, or wait on their answer, approval or feedback before you go on. question: what you wait on, as one question; options: 2 to 4 answers they could give (a label of at most five words, and what it does), or [] when it's theirs to put in words.",
-    "- blocked: you didn't take the step, for a reason no answer from the person settles now. reason: why, in a sentence.",
+    "- waiting: the step isn't due yet for some or all of its stories: they wait on other work still going (a lane building a story they merge with, a rebuild, a check running). waits: one entry per story that waits, with the stories it waits on (their ST ids, [] when it's other work) and why, in a few words. Use this, not done, when you said a story can't be taken yet.",
+    "- blocked: you didn't take the step, for a reason no answer from the person settles now and no work in flight will change. reason: why, in a sentence.",
   ].join('\n');
 }
 
@@ -203,11 +257,21 @@ export function readOutcome(text) {
     .map((o) => ({ label: words(o?.label, 40), effect: words(o?.effect, 200) }))
     .filter((o) => o.label)
     .slice(0, 4);
+  const story = (v) =>
+    typeof v === 'string' && /^ST-\d+$/i.test(v.trim()) ? v.trim().toUpperCase() : null;
+  const waits = (Array.isArray(parsed.waits) ? parsed.waits : [])
+    .map((w) => ({
+      story: story(w?.story),
+      on: (Array.isArray(w?.on) ? w.on : []).map(story).filter(Boolean),
+      why: words(w?.why, 200),
+    }))
+    .filter((w) => w.story);
   return {
     outcome: parsed.outcome,
     question: words(parsed.question, 400),
     options: options.length >= 2 ? options : [],
     reason: words(parsed.reason, 300),
+    waits,
   };
 }
 

package/hooks/mod/register.mjs

@@ -58,12 +58,16 @@ import {
   leadPrompt,
   nudgeText,
   outcomePrompt,
+  PARK_MS,
+  parkWatch,
   readOutcome,
   restartPrompt,
   stallDue,
   stepKey,
   stepLabel,
+  stepStories,
   storiesInFlight,
+  storiesSignature,
   withoutInFlight,
 } from './loop.mjs';
 import { goalOf, nextText } from './mission.mjs';
@@ -122,6 +126,8 @@ const loop = {
   // LOOP-11, LOOP-12: what holds the loop: { kind: 'person' | 'stopped' | 'blocked' | 'design', key, label, prompt, question, options, reason }
   waiting: null,
   handedDesign: new Set(), // LOOP-12: design stories handed to the lead this session
+  // LOOP-13: stories the lead said wait on other work: id → { on, why, watch, sig, at }
+  parked: new Map(),
 };
 // LOOP-10: whether this session runs the loop, the session that does when another does, and when this
 // one last renewed its lease.
@@ -1099,6 +1105,45 @@ export function register(on) {
         $.ui.invalidate('ui.render');
         await act.step('resume');
       },
+      // LOOP-13: where the watched stories stand now: their states, branch commits, and agents at work.
+      storiesNow: async () => {
+        const refs = await $.process
+          .run(['git', 'for-each-ref', '--format=%(objectname) %(refname)', 'refs/heads'], { cwd })
+          .catch(() => ({ stdout: '' }));
+        const heads = new Map(
+          String(refs.stdout ?? '')
+            .split('\n')
+            .map((l) => /^\s*(\S+)\s+(?:refs\/heads\/)?(\S+)/.exec(l))
+            .filter(Boolean)
+            .map((m) => [m[2], m[1]]),
+        );
+        const inFlight = storiesInFlight(await $.agent.list().catch(() => []));
+        const stories = model.state?.stories ?? [];
+        return {
+          heads,
+          inFlight,
+          stories,
+          sig: (ids) => storiesSignature(ids, stories, heads, inFlight),
+        };
+      },
+      park: async (waits) => {
+        if (!waits.length) return;
+        const now = await $.clock.now();
+        const seen = await act.storiesNow();
+        for (const w of waits) {
+          const watch = parkWatch(w.id, w.on, seen.stories);
+          loop.parked.set(w.id, { on: w.on, why: w.why, watch, sig: seen.sig(watch), at: now });
+        }
+        $.ui.invalidate('ui.render');
+      },
+      // LOOP-13: a parked story wakes when anything it watches moves, or after PARK_MS with nothing moving.
+      unpark: async () => {
+        if (!loop.parked.size) return;
+        const now = await $.clock.now();
+        const seen = await act.storiesNow();
+        for (const [id, p] of loop.parked)
+          if (now - p.at >= PARK_MS || seen.sig(p.watch) !== p.sig) loop.parked.delete(id);
+      },
       // LOOP-11: the lead's last reply, read once before the loop prompts it again. A reply that waits on
       // the person, or a turn they stopped, holds the loop until they speak; a step the lead didn't take
       // holds that step while it's still next.
@@ -1145,6 +1190,21 @@ export function register(on) {
         // Spec 05's data: what came of the step, once known.
         const record = sent ? loop.steps.findLast((x) => x.prompt === sent.prompt) : null;
         if (record) record.outcome = heard?.outcome ?? 'unread';
+        // LOOP-13: stories the lead said wait on other work are parked, each until what it waits on moves.
+        const ids = stepStories(sent);
+        if (['waiting', 'blocked'].includes(heard?.outcome) && ids.length) {
+          const named = new Map((heard.waits ?? []).map((w) => [w.story, w]));
+          // A blocked step, or a reply that names none, parks all its stories; otherwise those it names.
+          const waiting =
+            heard.outcome === 'blocked' || !named.size ? ids : ids.filter((id) => named.has(id));
+          await act.park(
+            waiting.map((id) => ({
+              id,
+              on: named.get(id)?.on ?? [],
+              why: named.get(id)?.why ?? heard.reason ?? null,
+            })),
+          );
+        }
         if (heard?.outcome === 'needs-person')
           loop.waiting = {
             kind: 'person',
@@ -1154,7 +1214,7 @@ export function register(on) {
             reason: heard.reason,
           };
         else if (heard?.outcome === 'blocked' && sent)
-          loop.waiting = { kind: 'blocked', ...step, reason: heard.reason };
+          loop.waiting = { kind: 'blocked', ...step, reason: heard.reason, stories: ids };
         if (loop.waiting) $.ui.invalidate('ui.render');
       },
       // LOOP-11: the person's choice from the lead's options, or their own words, told to the lead.
@@ -1181,11 +1241,13 @@ export function register(on) {
         const w = loop.waiting;
         if (!w?.prompt || leadTurn) return;
         loop.waiting = null;
+        for (const id of w.stories ?? []) loop.parked.delete(id);
         loop.asked = { key: w.key, times: 0 };
         await act.submit(w.prompt, w.stepKind, w.target, { key: w.key, label: w.label });
       },
       // LOOP-11: the person lets the loop go on.
       carryOn: async () => {
+        for (const id of loop.waiting?.stories ?? []) loop.parked.delete(id);
         loop.waiting = null;
         loop.lastKey = null;
         $.ui.invalidate('ui.render');
@@ -1253,12 +1315,15 @@ export function register(on) {
           return act.submit(prompt, 'restart', story);
         }
         const ran = await $.process.run(['node', cli, 'next', '--json'], { cwd });
+        // LOOP-13: a parked story stays out of the step until what it waits on moves.
+        await act.unpark();
         // LOOP-9: never a story an agent is already at work on, building or reviewing it.
         const step =
           ran.exitCode === 0
             ? withoutInFlight(
                 parseJson(ran.stdout),
                 storiesInFlight(await $.agent.list().catch(() => [])),
+                loop.parked,
               )
             : null;
         // MISSION-1: the band shows what the loop takes next.
@@ -1294,9 +1359,17 @@ export function register(on) {
         // LOOP-11, LOOP-12: a step the lead didn't take, or designs left to the person and the lead, hold
         // that step while it's still next; any other step goes on.
         if (loop.waiting) {
-          if (loop.waiting.key === key) return;
-          loop.waiting = null;
-          $.ui.invalidate('ui.render');
+          // LOOP-13: a blocked step's stories are parked, so the line stays while any of them is, and
+          // other steps go on; a step without stories holds while it's still next.
+          const stories = loop.waiting.stories ?? [];
+          const held = stories.length
+            ? stories.some((id) => loop.parked.has(id))
+            : loop.waiting.key === key;
+          if (held && !stories.length) return;
+          if (!held) {
+            loop.waiting = null;
+            $.ui.invalidate('ui.render');
+          }
         }
         if (!prompt) return;
         if (designHandedOver(step, loop.handedDesign)) {

package/hooks/mod/register.test.ts

@@ -2510,6 +2510,83 @@ test('LOOP-11 dismissed, what the lead waits on stays in the band, and the loop
   expect(w.prompts.at(-1)).toBe('Review ST-4: run /code-kit:review ST-4.');
 });
 
+test('LOOP-13 stories the lead says wait on other work are parked, each until what it waits on moves', async ($, on) => {
+  const w = project();
+  w.stories.push(
+    {
+      id: 'ST-158',
+      title: 'Storage',
+      lane: 'web',
+      state: 'in review',
+      branch: 'web/st-158',
+      waitingOn: [],
+    },
+    {
+      id: 'ST-164',
+      title: 'Callers use the storage',
+      lane: 'api',
+      state: 'in progress',
+      branch: 'api/st-164',
+      dependsOn: ['ST-158'],
+      waitingOn: [],
+    },
+    {
+      id: 'ST-172',
+      title: 'Silent tests',
+      lane: 'core',
+      state: 'in review',
+      branch: 'core/st-172',
+      waitingOn: [],
+    },
+    {
+      id: 'ST-173',
+      title: 'Verdicts',
+      lane: 'lead',
+      state: 'in review',
+      branch: 'lead/st-173',
+      waitingOn: [],
+    },
+  );
+  w.refs += ' s1 refs/heads/web/st-158\n s2 refs/heads/api/st-164\n s3 refs/heads/core/st-172\n';
+  w.next = { step: 'review', args: 'ST-158 ST-172', then: [] };
+  w.sideReply = unread;
+  const clock = await start($, on, w);
+  await leadTurn($);
+  await settle(clock);
+  expect(w.prompts.at(-1)).toBe('Review ST-158, ST-172: run /code-kit:review.');
+  // The lead says neither is due yet; next then names a third story as well.
+  w.sideReply = outcome({
+    outcome: 'waiting',
+    waits: [
+      { story: 'ST-158', on: [], why: 'it merges with its paired branch' },
+      { story: 'ST-172', on: [], why: 'its merge checks are re-running' },
+    ],
+  });
+  w.next = { step: 'review', args: 'ST-158 ST-172 ST-173', then: [] };
+  await leadSays(
+    $,
+    't-2',
+    'None of these is due: ST-158 merges with ST-164; ST-172 re-runs its checks.',
+  );
+  await settle(clock);
+  // Only the story that isn't waiting is asked for.
+  expect(w.prompts.at(-1)).toBe('Review ST-173: run /code-kit:review ST-173.');
+  const asked = w.prompts.length;
+  // Lanes committing elsewhere don't wake them, and nothing is prompted while both still wait.
+  w.sideReply = unread;
+  w.next = { step: 'review', args: 'ST-158 ST-172', then: [] };
+  w.refs += ' x1 refs/heads/core/st-9\n';
+  await leadTurn($, 't-3');
+  await settle(clock);
+  expect(w.prompts).toHaveLength(asked);
+  // The story building on ST-158 commits: ST-158 wakes, and ST-172 still waits.
+  w.refs = w.refs.replace(' s2 refs/heads/api/st-164', ' s9 refs/heads/api/st-164');
+  await leadTurn($, 't-4');
+  await settle(clock);
+  expect(w.prompts.at(-1)).toBe('Review ST-158: run /code-kit:review ST-158.');
+  expect(w.prompts).toHaveLength(asked + 1);
+});
+
 test('LOOP-11 a turn the person stopped holds the loop, with no dialog, until they speak or press Carry on', async ($, on) => {
   const w = project();
   w.sideReply = unread;

package/hooks/mod/view.mjs

@@ -101,6 +101,8 @@ export function projectState(check, status, next = null, atWork = new Set()) {
       worktree: s.worktree ?? null,
       requirements: s.requirements ?? [],
       waitingOn: s.waitingOn ?? [],
+      // LOOP-13: a parked story watches the stories building on it.
+      dependsOn: s.dependsOn ?? [],
       milestone: s.milestone ?? null,
     })),
   };

package/package.json

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