@warren-dean/code-kit 0.5.0 → 0.7.0

package/hooks/lane-audit.mjs

@@ -2,8 +2,9 @@
 // PostToolUse (Bash) and part of Stop: shell commands can write files without going through the
 // path guard, so after each one every uncommitted change in the worktree is checked against the
 // same rules (lib/rules.mjs). Anything the actor may not write is reported for revert.
-import { readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
   APPROVAL_LOG,
@@ -39,12 +40,54 @@ export function changedFiles(root) {
     .filter((f) => f !== LANE_FILE);
 }
 
+// A read-only agent (a reviewer, a card writer) works in a checkout it shares, usually the lead's,
+// whose uncommitted work isn't the agent's. So its shell commands are judged by what each one changed:
+// the uncommitted files are noted before the command runs (guard-bash) and compared after it.
+const snapshotFile = (id) => join(tmpdir(), 'code-kit-shell', `${id}.json`);
+const signature = (root, rel) => {
+  try {
+    const s = statSync(join(root, rel));
+    return `${s.size}:${s.mtimeMs}`;
+  } catch {
+    return 'gone';
+  }
+};
+
+/** Notes the uncommitted files and their state before a read-only agent's command runs. */
+export function noteBefore(input) {
+  const root = actorRoot(input);
+  if (!root || !input.tool_use_id) return;
+  const before = Object.fromEntries(changedFiles(root).map((rel) => [rel, signature(root, rel)]));
+  try {
+    mkdirSync(join(tmpdir(), 'code-kit-shell'), { recursive: true });
+    writeFileSync(snapshotFile(input.tool_use_id), JSON.stringify(before));
+  } catch {
+    // without a note, every uncommitted change is judged, as for any actor
+  }
+}
+
+/** What was noted before the command, taken once; null when nothing was. */
+function takeNote(input) {
+  if (!input.tool_use_id) return null;
+  const file = snapshotFile(input.tool_use_id);
+  try {
+    const before = JSON.parse(readFileSync(file, 'utf8'));
+    rmSync(file, { force: true });
+    return before;
+  } catch {
+    return null;
+  }
+}
+
 export function auditProblems(input, config) {
   const root = actorRoot(input);
   if (!root) return [];
   const actor = actorFor(input, root, config);
+  const before = actor.kind === 'readonly' ? takeNote(input) : null;
   return (
     changedFiles(root)
+      // A read-only agent answers for what its command changed, not for the checkout it shares.
+      .filter((rel) => !before || before[rel] !== signature(root, rel))
       .filter((rel) => !(rel === APPROVAL_LOG && appendedOnly(root, rel)))
       // Mid-merge, the incoming branch's changes are its own, not this actor's writes.
       .filter((rel) => !arrivesWithMerge(root, rel))

package/hooks/lib/adapters/context-graph.mjs

@@ -7,13 +7,34 @@
 // lead act on what the person says in chat (`approvals.lead`). A delegated ratification, signed
 // `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's own act under the repository's [delegate]
 // rules: only the lead may write that trailer, and Context Graph's gate checks the kinds it covers.
-// Ratifying with `--commit`, and dropping a proposal, are the person's acts in ctx too, so no actor runs
-// them; only a command in command position counts, so text that mentions one isn't refused.
+// Ratifying with `--commit`, dropping a proposal and changing the harness settings are the person's acts
+// in ctx too, so no actor runs
+// them; only a command the line runs counts, so a heredoc or quoted text that mentions one isn't refused.
+import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
+/** ctx's JSON for `args`, run in `root`, or null where ctx isn't installed or fails. */
+function ctx(root, args) {
+  try {
+    return JSON.parse(
+      execFileSync('ctx', [...args, '--json'], {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 30000,
+      }),
+    );
+  } catch {
+    return null;
+  }
+}
+
 const CTX = String.raw`(?:ctx|node\s+["']?[^\s"']*ctx\.mjs["']?|npx\s+(?:--yes\s+)?@warren-dean/context-graph(?:@\S+)?)`;
-const PERSONS_ACT = String.raw`(?:^|[;&|\n])\s*${CTX}\s+(?:ratify\b[^;&|\n]*\s--commit\b|drop\b)`;
+const PERSONS_ACT = String.raw`^${CTX}\s+(?:ratify\b[^;&|\n]*\s--commit\b|drop\b|settings\s+set\b)`;
+
+/** A commit the person signed with their ratification trailer; agents may not write it. */
+const PERSON_SIGNED = '^Ctx-Ratified-By:(?![^\\n]*\\(delegated\\))\\s*\\S';
 
 export default {
   name: 'context-graph',
@@ -27,9 +48,15 @@ export default {
         approval: 'ctx',
         why: "Context Graph's rules and concepts",
         // A person's ratification (`ctx ratify --commit`, `ctx drop --commit`) is signed, not logged.
-        signedBy: '^Ctx-Ratified-By:(?![^\\n]*\\(delegated\\))\\s*\\S',
+        signedBy: PERSON_SIGNED,
+      },
+      // Setting Context Graph up is ratified the same way: the person commits it from their terminal.
+      {
+        glob: '.ctx/config.toml',
+        approval: 'ctx',
+        why: "Context Graph's settings",
+        signedBy: PERSON_SIGNED,
       },
-      { glob: '.ctx/config.toml', approval: 'ctx', why: "Context Graph's settings" },
     ],
   },
   shell: {
@@ -41,7 +68,8 @@ export default {
       },
       {
         pattern: PERSONS_ACT,
-        why: "Ratifying a Context Graph proposal with --commit, and dropping one, are the person's own acts: they run them themselves, with a `!` command, or from the Context Graph pane.",
+        command: true,
+        why: "Ratifying a Context Graph proposal with --commit, dropping one, and changing Context Graph's harness settings are the person's own acts: they run them themselves, with a `!` command, or from the Context Graph pane.",
       },
     ],
     restricted: [
@@ -52,6 +80,47 @@ export default {
       },
     ],
   },
+  // What Context Graph knows of the lanes' work (the combined lane view, docs/specs/13-combined.md).
+  facts: {
+    /** Whether ctx's command line runs here. */
+    available: (root) => ctx(root, ['agents', '--session', 'none']) !== null,
+    /**
+     * Per agent type in a session (null for the main session): the edits made without understanding,
+     * each with the files still unread, and the cards owed.
+     */
+    lanes: (root, { session }) => {
+      const agents = session ? (ctx(root, ['agents', '--session', session]) ?? []) : [];
+      const byType = {};
+      for (const a of Array.isArray(agents) ? agents : []) {
+        const key = a.agentType ?? 'lead';
+        const f = (byType[key] ??= { withoutUnderstanding: [], cardsOwed: [] });
+        for (const e of a.edited ?? [])
+          if (!e.understood) f.withoutUnderstanding.push({ path: e.path, unread: e.missing ?? [] });
+        for (const c of a.cardsOwed ?? []) if (!f.cardsOwed.includes(c)) f.cardsOwed.push(c);
+      }
+      return byType;
+    },
+    /** Per file: the rules that apply to it, agreed and proposed. */
+    files: (root, paths) =>
+      Object.fromEntries(
+        paths.map((path) => {
+          const f = ctx(root, ['file', path]);
+          return [
+            path,
+            {
+              rules: (f?.rules ?? []).map((r) => ({
+                id: r.id,
+                text: r.text,
+                mode: r.mode,
+                proposed: r.mode === 'G?',
+              })),
+            },
+          ];
+        }),
+      ),
+    /** The command that opens Context Graph's pane on a file, given its path. */
+    open: { command: 'graph' },
+  },
   setup: [
     '.gitignore: .ctx/archive/, .ctx/bench/, .ctx/models/ and .ctx/serve.json (ctx working files, never committed)',
     '.gitattributes: .ctx/decisions.ctx merge=union and .ctx/cards.ctx merge=union (lanes record decisions and cards on parallel branches; merging keeps them all)',

package/hooks/lib/adapters/index.mjs

@@ -11,6 +11,9 @@
 //             shell.block (`person: true` marks a person's act the lead may do for them under
 //             approvals.lead); restricted: commands only the lead and the listed lanes may run
 //   setup     lines for init to apply or tell the person: ignore files, merge drivers, instructions
+//   facts     what the tool knows of the lanes' work, for the mod's combined view: { available(root),
+//             lanes(root, { session }) → { [agent type or 'lead']: { withoutUnderstanding, cardsOwed } },
+//             files(root, paths) → { [path]: { rules } }, open: { command } (its view of a file) }
 //
 // The core only ever calls applyAdapters() and activeAdapters(); it never names a tool.
 import contextGraph from './context-graph.mjs';
@@ -22,6 +25,21 @@ export function activeAdapters(raw, root) {
   return ADAPTERS.filter((a) => raw.adapters?.[a.name] !== false && a.detect(root));
 }
 
+/**
+ * What the active adapters that know of the lanes' work report (JOIN-1): [{ name, lanes?, files?, open }],
+ * only those whose tool is available here. `paths` asks for those files' facts too.
+ */
+export function adapterFacts(raw, root, { session = null, paths = null } = {}) {
+  return activeAdapters(raw, root)
+    .filter((a) => a.facts && a.facts.available(root))
+    .map((a) => ({
+      name: a.name,
+      ...(a.facts.lanes ? { lanes: a.facts.lanes(root, { session }) } : {}),
+      ...(paths && a.facts.files ? { files: a.facts.files(root, paths) } : {}),
+      open: a.facts.open ?? null,
+    }));
+}
+
 /** The effective config with every active adapter's contributions merged in. */
 export function applyAdapters(config, raw, root) {
   const active = activeAdapters(raw, root);

package/hooks/lib/config.mjs

@@ -1,6 +1,8 @@
 // The project's rules live in .claude/code-kit.json. The hooks read it from the project the session
 // was opened in; a project without one is not governed by the kit, and an invalid one fails closed.
+import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
+import { harnessProblems, harnessSettings } from './harness.mjs';
 import { join } from 'node:path';
 import { ADAPTERS, applyAdapters } from './adapters/index.mjs';
 
@@ -28,6 +30,43 @@ export function loadConfig(projectDir) {
   return { config: effectiveConfig(raw, projectDir) };
 }
 
+/**
+ * The config as committed on `ref`: what governs merging into it, so a branch's own config can't grant
+ * itself a merge its target doesn't allow. `{ config }`, `{ error }` when it's invalid, or `{}` when
+ * `ref` has none committed yet (the first merge, which brings code-kit's rules onto it).
+ */
+export function committedConfig(root, ref, file = CONFIG_FILE) {
+  let text;
+  try {
+    text = execFileSync('git', ['-C', root, 'show', `${ref}:${file}`], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return {};
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    return { error: `${file} on ${ref} is not valid JSON: ${e.message}` };
+  }
+  const problems = validate(raw);
+  if (problems.length)
+    return { error: `${file} on ${ref} is invalid:\n  ${problems.join('\n  ')}` };
+  return { config: effectiveConfig(raw, root) };
+}
+
+/**
+ * Whether the lead may merge into the base (the first protected branch), by the rules committed there:
+ * `{ into, delegated, first }`, `first` when the base has no config committed yet.
+ */
+export function mergeDelegation(root, config, file = CONFIG_FILE) {
+  const into = config.branches.protected[0];
+  const { config: target, error } = committedConfig(root, into, file);
+  return { into, delegated: Boolean(target?.approvals.delegate?.merge), first: !target && !error };
+}
+
 /** The rules the hooks enforce: the project's config, the kit's defaults, and any active adapters. */
 export const effectiveConfig = (raw, root) => applyAdapters(withDefaults(raw), raw, root);
 
@@ -55,6 +94,7 @@ export function withDefaults(c) {
     checks: c.checks ?? [],
     branches: { protected: c.branches?.protected ?? ['main', 'master'] },
     approvals: { lead: c.approvals?.lead === true, delegate: delegateRules(c.approvals?.delegate) },
+    harness: harnessSettings(c.harness),
   };
 }
 
@@ -191,6 +231,7 @@ export function validate(c) {
     c.branches === undefined || isList(c.branches?.protected),
     '"branches.protected" must be a list of branch names',
   );
+  p.push(...harnessProblems(c.harness));
   return p;
 }
 
@@ -249,10 +290,13 @@ function validateLayers(c, need, each) {
 function validateShell(s, lanes, need) {
   if (!need(isObj(s), '"shell" must be an object')) return;
   const rule = (r) => isObj(r) && isRegExp(r.pattern) && isStr(r.why);
-  const blockRule = (r) => rule(r) && [undefined, true, false].includes(r.person);
+  const blockRule = (r) =>
+    rule(r) &&
+    [undefined, true, false].includes(r.person) &&
+    [undefined, true, false].includes(r.command);
   need(
     s.block === undefined || (Array.isArray(s.block) && s.block.every(blockRule)),
-    '"shell.block" must be a list of { pattern, why, person? }',
+    '"shell.block" must be a list of { pattern, why, person?, command? }',
   );
   const restricted =
     s.restricted === undefined ||

package/hooks/lib/dependencies.mjs

@@ -1,6 +1,7 @@
 // New dependencies: which packages a shell command adds, and which files installing them changes.
 // Each package needs a person's approval (`dep-<package>`), which also covers those files.
 import { basename } from 'node:path';
+import { commandsOf } from './shell.mjs';
 
 // What installing a package rewrites: manifests and lockfiles, wherever they sit.
 const DEPENDENCY_FILES = new Set([
@@ -86,22 +87,38 @@ const MANAGERS = {
 };
 MANAGERS.pip3 = MANAGERS.pip;
 
-/** The packages `cmd` adds as dependencies, in order: none for a bare install or a requirements file. */
+/**
+ * The packages `cmd` adds as dependencies, in order: none for a bare install or a requirements file.
+ * Only the commands it runs count: quoted text and heredoc bodies are data (an echo, a commit message),
+ * except a shell's `-c` script, which runs.
+ */
 export function addedPackages(cmd) {
   const found = [];
-  for (const segment of cmd.split(/&&|\|\||[;|\n]/)) {
-    const tokens = segment
-      .trim()
-      .split(/\s+/)
-      .map((t) => t.replace(/^["']|["']$/g, ''));
-    tokens.forEach((token, i) => {
-      const manager = MANAGERS[basename(token)];
-      if (manager) found.push(...packagesAfter(tokens.slice(i + 1), manager));
+  for (const { text, code } of commandsOf(cmd)) {
+    // Words split where the quote-masked code has spaces, so a quoted word stays one word.
+    const words = [...code.matchAll(/\S+/g)].map((m) => ({
+      quoted: /^["']/.test(m[0]),
+      word: text.slice(m.index, m.index + m[0].length).replace(/^["']|["']$/g, ''),
+    }));
+    words.forEach(({ word, quoted }, i) => {
+      if (quoted) return;
+      if (SHELLS.has(basename(word)) && words[i + 1]?.word === '-c' && words[i + 2])
+        found.push(...addedPackages(words[i + 2].word));
+      const manager = MANAGERS[basename(word)];
+      if (manager)
+        found.push(
+          ...packagesAfter(
+            words.slice(i + 1).map((w) => w.word),
+            manager,
+          ),
+        );
     });
   }
   return [...new Set(found)];
 }
 
+const SHELLS = new Set(['sh', 'bash', 'zsh']);
+
 // The words after a package manager's name: its subcommand must be one that adds packages, and the
 // words after that, other than flags and their values, are the packages.
 function packagesAfter(words, manager) {

package/hooks/lib/harness.mjs

@@ -0,0 +1,131 @@
+// The harness's settings (docs/specs/12-settings.md): the `harness` section of .claude/code-kit.json,
+// what the mod's loop, hold, reviewer and usage read. Defaults fill what the section leaves out; a value
+// out of range is a config problem like any other.
+
+export const AUTONOMY = ['autonomous', 'propose', 'off'];
+export const MODELS = ['haiku', 'sonnet', 'opus'];
+
+/** Each setting by its dotted key: its default, and why a value is wrong (or null when it's right). */
+export const SETTINGS = {
+  autonomy: {
+    default: 'autonomous',
+    problem: (v) => (AUTONOMY.includes(v) ? null : `must be one of ${AUTONOMY.join(', ')}`),
+    about: 'How the lead loop acts: on its own, by proposing each step, or not at all',
+  },
+  'hold.minutes': {
+    default: 2,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 0 && v <= 10
+        ? null
+        : 'must be a number of minutes from 0 (off) to 10',
+    about: 'How long a call waiting on your approval is held before it is refused',
+  },
+  'stall.nudgeMinutes': {
+    default: 5,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 1 ? null : 'must be a number of minutes, at least 1',
+    about: 'Minutes without a tool call before a lane agent is nudged',
+  },
+  'stall.restartMinutes': {
+    default: 10,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 1 ? null : 'must be a number of minutes, at least 1',
+    about: 'Minutes without a tool call before a lane agent is restarted',
+  },
+  'stall.maxRestarts': {
+    default: 2,
+    problem: (v) =>
+      Number.isInteger(v) && v >= 0 && v <= 10 ? null : 'must be a whole number from 0 to 10',
+    about: 'Restarts on one story before the lane is flagged for you',
+  },
+  'agents.reviewer.on': {
+    default: false,
+    problem: (v) => (typeof v === 'boolean' ? null : 'must be true or false'),
+    about: 'A background reviewer for each finished branch',
+  },
+  'agents.reviewer.model': {
+    default: null,
+    problem: (v) =>
+      v === null || (typeof v === 'string' && v.length > 0)
+        ? null
+        : `must be a model (${MODELS.join(', ')}, or an id), or null for the session's`,
+    about: "The reviewer's model; none means the session's",
+  },
+  'background.pauseAtPercent': {
+    default: 80,
+    problem: (v) =>
+      Number.isFinite(v) && v > 0 && v <= 100 ? null : 'must be a percentage from 1 to 100',
+    about: "The plan's 5-hour use at which background agents pause",
+  },
+};
+
+const get = (obj, key) =>
+  key.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), obj);
+const set = (obj, key, value) => {
+  const parts = key.split('.');
+  let o = obj;
+  for (const k of parts.slice(0, -1)) o = o[k] && typeof o[k] === 'object' ? o[k] : (o[k] = {});
+  o[parts.at(-1)] = value;
+  return obj;
+};
+
+/** Every key the section holds, as dotted keys: `stall.nudgeMinutes`, `agents.reviewer.on`… */
+function keysOf(obj, prefix = '') {
+  return Object.entries(obj ?? {}).flatMap(([k, v]) =>
+    v && typeof v === 'object' && !Array.isArray(v) && !(`${prefix}${k}` in SETTINGS)
+      ? keysOf(v, `${prefix}${k}.`)
+      : [`${prefix}${k}`],
+  );
+}
+
+/** The settings in force: the section's values over the defaults, as a nested object. A value that's
+ * wrong (reported by `harnessProblems`) gives way to the default. */
+export function harnessSettings(section) {
+  const out = {};
+  for (const [key, s] of Object.entries(SETTINGS)) {
+    const v = section && typeof section === 'object' ? get(section, key) : undefined;
+    set(out, key, v === undefined || s.problem(v) ? s.default : v);
+  }
+  return out;
+}
+
+/** The section's problems, in the config's words. */
+export function harnessProblems(section) {
+  if (section === undefined) return [];
+  if (!section || typeof section !== 'object' || Array.isArray(section))
+    return ['"harness" must be an object'];
+  const p = [];
+  for (const key of keysOf(section)) {
+    if (!(key in SETTINGS)) {
+      p.push(
+        `"harness.${key}" isn't a harness setting (they are ${Object.keys(SETTINGS).join(', ')})`,
+      );
+      continue;
+    }
+    const why = SETTINGS[key].problem(get(section, key));
+    if (why) p.push(`"harness.${key}" ${why}`);
+  }
+  const h = harnessSettings(section);
+  if (h.stall.restartMinutes <= h.stall.nudgeMinutes)
+    p.push('"harness.stall.restartMinutes" must be more than "harness.stall.nudgeMinutes"');
+  return p;
+}
+
+/** A value typed on the command line, as the setting's type: numbers, true and false, null, or text. */
+export function parseSetting(key, text) {
+  const d = SETTINGS[key]?.default;
+  if (text === 'null') return null;
+  if (typeof d === 'boolean' || text === 'true' || text === 'false')
+    return text === 'true' ? true : text === 'false' ? false : text;
+  if (typeof d === 'number' && /^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  return text;
+}
+
+/** The raw config with one harness setting changed (a copy). */
+export function withSetting(raw, key, value) {
+  const copy = structuredClone(raw);
+  copy.harness = set(copy.harness ?? {}, key, value);
+  return copy;
+}
+
+export { get as settingOf };

package/hooks/lib/next.mjs

@@ -4,8 +4,9 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, posix } from 'node:path';
-import { loadConfig } from './config.mjs';
+import { loadConfig, mergeDelegation } from './config.mjs';
 import { buildStatus, readStories, LEAD } from './plan.mjs';
+import { readQueue, waiting } from './queue.mjs';
 
 export const DRAFT_FILE = '.claude/code-kit.draft.json';
 export const BRIEF_STATES = ['framed', 'explored', 'scoped', 'specified', 'planned', 'ready'];
@@ -52,7 +53,8 @@ const hasMarkdown = (dir) => {
 
 /**
  * { step, why, args, then, attention }. `step` is a skill (spec-design, init, check, dispatch,
- * review), `wait` (lanes are building) or `done`. `base(config)` resolves the branch lanes merge into.
+ * review), `merge` (the head of the merge queue, where the lead merges), `wait` (lanes are
+ * building) or `done`. `base(config)` resolves the branch lanes merge into.
  */
 export function nextStep(root, base) {
   const attention = [];
@@ -149,7 +151,12 @@ export function nextStep(root, base) {
       `The plan's status lines are out of date for ${status.drift.map((d) => d.story).join(', ')}.`,
     );
 
-  const ids = (state) => status.stories.filter((s) => s.state === state).map((s) => s.id);
+  // A branch already in the merge queue has passed its review: it isn't reviewed again.
+  const queued = waiting(readQueue(root)).map((e) => e.branch);
+  const ids = (state) =>
+    status.stories
+      .filter((s) => s.state === state && !(state === 'review' && queued.includes(s.branch)))
+      .map((s) => s.id);
   const [review, building, blocked, fixes] = ['review', 'in progress', 'blocked', 'sent back'].map(
     ids,
   );
@@ -168,6 +175,25 @@ export function nextStep(root, base) {
     attention.push(
       `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
     );
+  // The merge queue (spec 09): branches the lead's review passed. Under autonomy, where the base's
+  // committed rules delegate merges, the lead merges the head first, so dependents see it; otherwise
+  // the person does, and always the first merge, which brings code-kit's rules onto the base.
+  const delegation = queued.length ? mergeDelegation(root, config) : { delegated: false };
+  const leadMerges = delegation.delegated && config.harness.autonomy === 'autonomous';
+  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.`,
+    );
+  else 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).`,
+    );
+  if (queued.length && leadMerges)
+    return result(
+      'merge',
+      `${queued[0]} passed review and is next in the merge queue${queued.length > 1 ? ` (then ${queued.slice(1).join(', ')})` : ''}.`,
+      { args: queued[0] },
+    );
   const then = [];
   // A sent-back story goes back to its lane with the review's findings, before new work starts.
   const toDispatch = [...fixes, ...ready];
@@ -211,6 +237,11 @@ export function nextStep(root, base) {
       'spec-design',
       `${blocked.join(', ')} wait on stories that can't finish: the plan has a dependency cycle or a missing story.`,
     );
+  if (queued.length)
+    return result(
+      'wait',
+      `${queued.join(', ')} ${queued.length === 1 ? 'waits' : 'wait'} to be merged.`,
+    );
   return result(
     'done',
     `All ${status.stories.length} stories are done; spec-design plans the next milestone or feature.`,

package/hooks/lib/plan.mjs

@@ -221,3 +221,32 @@ export function buildStatus(root, config, base, files) {
     .map((s) => ({ story: s.id, plan: s.status, actual: s.state }));
   return { stories, requirements: byRequirement, problems, drift };
 }
+
+/**
+ * The rows of a spec-check report's table (skills/spec-check): [{ requirement, status, where, note }],
+ * the first column's requirement id, the status as written (done, partial, missing or conflicts).
+ */
+export function specCheckRows(text) {
+  const lines = String(text).split('\n');
+  const head = lines.findIndex((l) => /^\s*\|\s*Requirement\s*\|/i.test(l));
+  if (head < 0) return [];
+  const rows = [];
+  for (const line of lines.slice(head + 1)) {
+    if (!/^\s*\|/.test(line)) break;
+    const cells = line
+      .trim()
+      .replace(/^\||\|$/g, '')
+      .split('|')
+      .map((c) => c.trim());
+    if (cells.every((c) => /^:?-+:?$/.test(c) || c === '')) continue;
+    const [requirement = '', status = '', where = '', note = ''] = cells;
+    rows.push({
+      requirement: requirement.match(REQUIREMENT_ID)?.[0] ?? requirement,
+      status: status.toLowerCase(),
+      where,
+      note,
+    });
+  }
+  return rows;
+}
+const REQUIREMENT_ID = /\b[A-Z][A-Z0-9]*-\d+\b/;

package/hooks/lib/queue.mjs

@@ -0,0 +1,75 @@
+// The merge queue (docs/specs/09-merge-queue.md): branches that passed the lead's review, merged one at
+// a time in the order they passed, each verified against the base as it is then. Kept in the main
+// checkout, beside the requests and reviews, so every worktree and a restarted session see the same.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { projectWorktrees } from './rules.mjs';
+
+export const QUEUE_FILE = '.claude/state/merge-queue.json';
+/** Merged and sent-back entries kept for the pane, newest last. */
+const DONE_KEPT = 20;
+
+const queueFile = (root) => join(projectWorktrees(root)[0] ?? root, QUEUE_FILE);
+
+/** The queue's entries: [{ branch, passed, state, at?, reason? }], waiting ones in merge order. */
+export function readQueue(root) {
+  try {
+    const entries = JSON.parse(readFileSync(queueFile(root), 'utf8'));
+    return Array.isArray(entries) ? entries.filter((e) => e && typeof e.branch === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(root, entries) {
+  const done = entries.filter((e) => !['waiting', 'merging'].includes(e.state));
+  const kept = [
+    ...done.slice(-DONE_KEPT),
+    ...entries.filter((e) => ['waiting', 'merging'].includes(e.state)),
+  ];
+  const file = queueFile(root);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(kept, null, 2)}\n`);
+}
+
+/** The branches still to merge, in order (MQ-1). */
+export const waiting = (entries) => entries.filter((e) => ['waiting', 'merging'].includes(e.state));
+
+/** Adds a branch the lead's review passed, at the back; a branch already waiting keeps its place. */
+export function enqueue(root, branch, now = Date.now()) {
+  const entries = readQueue(root);
+  if (waiting(entries).some((e) => e.branch === branch)) return false;
+  writeQueue(root, [
+    ...entries.filter((e) => e.branch !== branch),
+    { branch, passed: new Date(now).toISOString(), state: 'waiting' },
+  ]);
+  return true;
+}
+
+/** Takes a waiting branch out of the queue. */
+export function dequeue(root, branch) {
+  const entries = readQueue(root);
+  if (!waiting(entries).some((e) => e.branch === branch)) return false;
+  writeQueue(
+    root,
+    entries.filter((e) => !(e.branch === branch && ['waiting', 'merging'].includes(e.state))),
+  );
+  return true;
+}
+
+/** Sets a waiting branch's state: merging, merged, sent back (with why), or waiting again. */
+export function settle(root, branch, state, reason = null, now = Date.now()) {
+  const entries = readQueue(root).map((e) =>
+    e.branch === branch && ['waiting', 'merging'].includes(e.state)
+      ? { ...e, state, at: new Date(now).toISOString(), ...(reason ? { reason } : {}) }
+      : e,
+  );
+  // Merged and sent-back entries move behind the waiting ones' history, in the order they settled.
+  const settled = entries.filter((e) => e.branch === branch && e.state === state);
+  writeQueue(root, [...entries.filter((e) => !settled.includes(e)), ...settled]);
+}
+
+/** The branch merged last, for a send-back's reason ("conflicts with main after web/st-4"). */
+export function lastMerged(entries) {
+  return [...entries].reverse().find((e) => e.state === 'merged')?.branch ?? null;
+}