@warren-dean/code-kit 0.21.0 → 0.22.1

package/hooks/lib/laneclaims.mjs

@@ -0,0 +1,89 @@
+// One agent per lane, across every session in the project (docs/specs/23-the-team.md, SCHED-1). Two
+// agents in one lane build on overlapping files in their worktrees and conflict at merge; the plan's
+// graph is for running different lanes at once. Starting a lane's agent claims the lane, and the claim
+// ends when the agent finishes, its session ends, or the lead releases a lane whose agent has stopped.
+// Kept in the main checkout, one file per lane, so every session and worktree on the machine sees them,
+// and two agents started in the same moment can't both take a lane: the file is created exclusively.
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { projectWorktrees } from './rules.mjs';
+
+export const LANE_CLAIMS_DIR = '.claude/state/lanes';
+/** A claim this old is taken to be left over from an agent nobody saw stop. */
+export const LANE_CLAIM_STALE_MS = 12 * 3600_000;
+
+const dirOf = (root) => join(projectWorktrees(root)[0] ?? root, LANE_CLAIMS_DIR);
+const fileOf = (root, lane) => join(dirOf(root), `${lane.replace(/[^\w.-]/g, '_')}.json`);
+
+/** A session's id as people read it: its first 8 characters. */
+export const shortSession = (session) => (session ? String(session).slice(0, 8) : null);
+
+function read(root, lane) {
+  try {
+    return JSON.parse(readFileSync(fileOf(root, lane), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const withAge = (claim, now) =>
+  claim && { ...claim, stale: now - Date.parse(claim.since) >= LANE_CLAIM_STALE_MS };
+
+/** Every lane claimed now: [{ lane, story, session, since, stale }], by lane. */
+export function laneClaims(root, now = Date.now()) {
+  let files = [];
+  try {
+    files = readdirSync(dirOf(root)).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  return files
+    .map((f) => {
+      try {
+        return withAge(JSON.parse(readFileSync(join(dirOf(root), f), 'utf8')), now);
+      } catch {
+        return null;
+      }
+    })
+    .filter((c) => c?.lane)
+    .sort((a, b) => a.lane.localeCompare(b.lane));
+}
+
+/** The lane's claim, or null. */
+export const laneClaim = (root, lane, now = Date.now()) => withAge(read(root, lane), now);
+
+/**
+ * SCHED-1: claims `lane` for `story` in `session`: { ok: true } or { ok: false, claim } naming who has it.
+ * The session already holding it for the same story (a restart, a send-back) takes it again; so does
+ * anyone, from a stale claim.
+ */
+export function claimLane(root, { lane, story = null, session = null }, now = Date.now()) {
+  const record = { lane, story, session, since: new Date(now).toISOString() };
+  mkdirSync(dirOf(root), { recursive: true });
+  try {
+    writeFileSync(fileOf(root, lane), `${JSON.stringify(record)}\n`, { flag: 'wx' });
+    return { ok: true };
+  } catch {
+    // held already: by whom, and whether it may be taken over
+  }
+  const held = laneClaim(root, lane, now);
+  const same = held && held.session === session && (held.story === story || !held.story);
+  if (held && !same && !held.stale) return { ok: false, claim: held };
+  writeFileSync(fileOf(root, lane), `${JSON.stringify(record)}\n`);
+  return { ok: true };
+}
+
+/** Ends the lane's claim; with `session`, only that session's. True when one ended. */
+export function releaseLane(root, lane, { session = null } = {}) {
+  const held = read(root, lane);
+  if (!held || (session && held.session !== session)) return false;
+  rmSync(fileOf(root, lane), { force: true });
+  return true;
+}
+
+/** Ends every claim a session holds, as it ends: the lanes it named. */
+export function releaseSession(root, session, now = Date.now()) {
+  const ended = laneClaims(root, now).filter((c) => c.session === session);
+  for (const c of ended) releaseLane(root, c.lane, { session });
+  return ended.map((c) => c.lane);
+}

package/hooks/lib/loop-state.mjs

@@ -5,6 +5,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { projectWorktrees } from './rules.mjs';
+import { leadSession, makeLead, readSession } from './sessions.mjs';
 
 export const LOOP_FILE = '.claude/state/loop.json';
 /** LOOP-10: a lead session renews its lease well within this; one not renewed for this long has ended. */
@@ -34,10 +35,19 @@ const liveLead = (state, now) => {
   return now - Date.parse(lead.at) < LEAD_LEASE_MS ? { session: lead.session, at: lead.at } : null;
 };
 
-/** { paused, at, lead }: not paused when nothing was recorded; `lead` is the live lead session or null. */
+/**
+ * { paused, at, lead }: not paused when nothing was recorded; `lead` is the live lead session or null.
+ * SESS-2: where sessions are recorded, the lead session is the lead; the lease is for a session code-kit's
+ * session hook never saw.
+ */
 export function readLoop(root, now = Date.now()) {
   const state = readRaw(root);
-  return { paused: state.paused === true, at: state.at ?? null, lead: liveLead(state, now) };
+  const lead = leadSession(root, now);
+  return {
+    paused: state.paused === true,
+    at: state.at ?? null,
+    lead: lead ? { session: lead.id, at: lead.seen } : liveLead(state, now),
+  };
 }
 
 export function writeLoop(root, paused, now = Date.now()) {
@@ -49,6 +59,14 @@ export function writeLoop(root, paused, now = Date.now()) {
  * person moved the loop here): { ok: true } or { ok: false, lead } naming the session that has it.
  */
 export function claimLead(root, session, { take = false } = {}, now = Date.now()) {
+  // SESS-2: the loop runs in the lead session; Lead from here (`take`) makes this session the lead.
+  if (readSession(root, session)) {
+    if (take) makeLead(root, session, now);
+    const lead = leadSession(root, now);
+    return lead?.id === session
+      ? { ok: true, lead: null }
+      : { ok: false, lead: lead ? { session: lead.id, at: lead.seen } : null };
+  }
   const state = readRaw(root);
   const lead = liveLead(state, now);
   if (lead && lead.session !== session && !take) return { ok: false, lead };

package/hooks/lib/next.mjs

@@ -12,6 +12,8 @@ import { readQueue, waiting } from './queue.mjs';
 import { decidedBy, laneOf, openRequests } from './rules.mjs';
 import { instructionsState } from './instructions.mjs';
 import { SECURITY_AGENT_FILE } from './security.mjs';
+import { laneClaims } from './laneclaims.mjs';
+import { pickPerLane } from './schedule.mjs';
 
 export const DRAFT_FILE = '.claude/code-kit.draft.json';
 export const BRIEF_STATES = ['framed', 'explored', 'scoped', 'specified', 'planned', 'ready'];
@@ -280,7 +282,9 @@ export function nextStep(root, base) {
   }
   // HELM-4: a lane waiting on something the lead decides goes first: the lane can't go on without it.
   const forLeadToDecide = openRequests(root).flatMap((r, i) =>
-    r.lane && decidedBy(r.names, config) === 'lead' ? [{ ...r, n: i + 1 }] : [],
+    r.lane && decidedBy(r.names, config, { kind: 'lane', lane: r.lane }) === 'lead'
+      ? [{ ...r, n: i + 1 }]
+      : [],
   );
   if (forLeadToDecide.length)
     return result(
@@ -311,6 +315,29 @@ export function nextStep(root, base) {
       `${queued[0]} passed review and is next in the merge queue${queued.length > 1 ? ` (then ${queued.slice(1).join(', ')})` : ''}.`,
       { args: queued[0] },
     );
+  // SCHED-1, SCHED-2: one story for each free lane, across every session; the open slice's first.
+  const busy = new Set([
+    ...laneClaims(root)
+      .filter((c) => !c.stale)
+      .map((c) => c.lane),
+    ...status.stories.filter((s) => s.state === 'in progress' && s.lane).map((s) => s.lane),
+  ]);
+  const sched = pickPerLane(status.stories, {
+    fixes,
+    ready,
+    busy,
+    open: config.harness.slices.open,
+  });
+  for (const list of [fixes, ready])
+    list.splice(0, list.length, ...list.filter((id) => sched.pick.includes(id)));
+  for (const a of sched.ahead)
+    attention.push(
+      `${a.id} is ahead of its slice (${a.slice}): its lane has nothing ready in the open slice.`,
+    );
+  if (sched.waiting.length)
+    attention.push(
+      `${sched.waiting.join(', ')} ${sched.waiting.length === 1 ? 'waits' : 'wait'} for ${sched.waiting.length === 1 ? 'its lane' : 'their lanes'}: a lane runs one story at a time.`,
+    );
   const then = [];
   // A sent-back story goes back to its lane with the review's findings, before new work starts.
   const toDispatch = [...fixes, ...ready];
@@ -358,6 +385,12 @@ export function nextStep(root, base) {
       'update',
       `${missingWords} Re-run /code-kit:init before the next story: it shows the person the difference before anything changes.`,
     );
+  // SCHED-1: ready stories whose lanes are all running one.
+  if (!building.length && sched.waiting.length)
+    return result(
+      'wait',
+      `${sched.waiting.join(', ')} ${sched.waiting.length === 1 ? 'waits' : 'wait'} for ${sched.waiting.length === 1 ? 'its lane' : 'their lanes'}, running another story; a lane runs one story at a time.`,
+    );
   if (building.length)
     return result(
       'wait',

package/hooks/lib/plan.mjs

@@ -52,7 +52,7 @@ const field = (lines, name) =>
     .trim() ?? '';
 
 /**
- * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, fixes, milestone }]. A story's
+ * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, fixes, milestone, slice }]. A story's
  * milestone is the `## ` heading above it ("Milestone 5: Your own key"), or null.
  */
 export function readStories(root, planPath) {
@@ -80,6 +80,8 @@ export function readStories(root, planPath) {
         dependsOn: [...field(body, 'Depends on').matchAll(/\bST-\d+\b/g)].map((r) => r[0]),
         status: STATES.includes(status) ? status : 'todo',
         milestone,
+        // SCHED-2: the slice it belongs to, a feature built across lanes, or null.
+        slice: field(body, 'Slice') || null,
       });
     });
   }

package/hooks/lib/questions.mjs

@@ -35,16 +35,25 @@ function append(root, record) {
 }
 
 /**
- * Every question, oldest first: { id, at, by, question, why, story, blocks, options: [{ label, effect }],
+ * Every question, oldest first: { id, at, by, session, count, question, why, story, blocks, options: [{ label, effect }],
  * state: 'open' | 'answered' | 'withdrawn', answer: { text, at, by, via } | null, withdrawn: { at, reason } | null }.
  */
 export function readQuestions(root) {
   const byId = new Map();
   for (const r of records(root)) {
     if (r.kind === 'ask')
-      byId.set(r.id, { ...r, kind: undefined, state: 'open', answer: null, withdrawn: null });
+      byId.set(r.id, {
+        ...r,
+        kind: undefined,
+        session: r.session ?? null,
+        count: 1,
+        state: 'open',
+        answer: null,
+        withdrawn: null,
+      });
     const q = byId.get(r.id);
     if (!q || q.state !== 'open') continue;
+    if (r.kind === 'again') q.count += 1;
     if (r.kind === 'answer') {
       q.state = 'answered';
       q.answer = { text: r.answer, at: r.at, by: r.by, via: r.via };
@@ -73,20 +82,29 @@ export function parseOption(text) {
  */
 export function askQuestion(
   root,
-  { by, question, why = null, story = null, blocks = false, options = [] },
+  { by, question, why = null, story = null, blocks = false, options = [], session = null },
   now = Date.now(),
 ) {
   const text = String(question).trim();
+  // OWN-3: the same question still open in the same session is one decision, asked again.
   const open = openQuestions(root).find(
-    (q) => q.question === text && (q.story ?? null) === (story ?? null),
+    (q) =>
+      q.question === text &&
+      (q.story ?? null) === (story ?? null) &&
+      (q.session ?? null) === (session ?? null),
   );
-  if (open) return { question: open, existed: true };
+  if (open) {
+    append(root, { kind: 'again', id: open.id, at: new Date(now).toISOString() });
+    return { question: readQuestions(root).find((q) => q.id === open.id), existed: true };
+  }
   const n = readQuestions(root).length + 1;
   const record = {
     kind: 'ask',
     id: `Q-${n}`,
     at: new Date(now).toISOString(),
     by,
+    // OWN-1: the session that asked it: it's asked, answered and heard there only.
+    session: session ?? null,
     question: text,
     why: why?.trim() || null,
     story: story ?? null,

package/hooks/lib/regression.mjs

@@ -1,6 +1,7 @@
 // Regression (docs/specs/18-regression.md). REG-1: a fix comes with a test that fails without it, as the
 // bug, and passes with it. REG-2: a test isn't weakened (deleted, skipped, cut down, its snapshot
-// rewritten) without the person's `tests` approval, which the lead can't delegate. The commit hook
+// rewritten) without a `tests` approval: the lead's on a lane's branch where tests are delegated (spec 23,
+// WHO-2), the person's otherwise and always on the lead's own. The commit hook
 // refuses a weakening commit; verify finds what a branch weakened, from git.
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs';

package/hooks/lib/rules.mjs

@@ -81,19 +81,21 @@ export const delegateCommand = (names, lane) =>
   }>"`;
 
 /**
- * HELM-1: whether the lead grants approval `name` itself, by the project's delegated rules. Weakening a
- * test is always the person's; a package is the lead's where dependencies are delegated.
+ * HELM-1, WHO-1: whether the lead grants approval `name` itself, by the project's delegated rules. A
+ * package is the lead's where dependencies are delegated. WHO-2: a weakened test is the lead's on a lane's
+ * branch, where tests are delegated, and the person's on the lead's own: nobody else reviews those.
  */
-export function leadDecides(name, config) {
+export function leadDecides(name, config, actor) {
   const rules = config?.approvals?.delegate;
-  if (!rules || name === 'tests') return false;
+  if (!rules) return false;
+  if (name === 'tests') return rules.tests === true && actor?.kind === 'lane';
   if (String(name).startsWith(DEPENDENCY_APPROVAL)) return Boolean(rules.dependencies);
   return (rules.protected ?? []).includes(name);
 }
 
 /** HELM-2: whose decision approvals `names` are: the lead's when it may grant every one, else the person's. */
-export const decidedBy = (names, config) =>
-  [names].flat().every((n) => leadDecides(n, config)) ? 'lead' : 'person';
+export const decidedBy = (names, config, actor) =>
+  [names].flat().every((n) => leadDecides(n, config, actor)) ? 'lead' : 'person';
 
 /**
  * HELM-2: what an actor refused for `names` does next, after the refusal's first line. A lane asks the
@@ -108,7 +110,7 @@ export function askHowTo(names, actor, root, config, { allows, need } = {}) {
     (pkg
       ? 'the package, the story and requirement that need it, what the project already has that you checked, and anything lighter that would do'
       : 'the file, the story and requirement that need the change, and what you checked first');
-  if (decidedBy(names, config) === 'lead') {
+  if (decidedBy(names, config, actor) === 'lead') {
     if (actor?.kind === 'lead')
       return `You decide this as the lead. Approve it only if the story's requirements need it${pkg ? ', nothing the project already depends on does the job, and it fits the principles and the layer it goes in' : ' and it keeps to the spec and the architecture'}:\n  Decided by the lead: ${delegateCommand(names)}`;
     return `The lead decides this, not the person. Hand the lead a change request and stop: ${brief}. The lead approves it, or tells you what to use instead.\n  Decided by the lead: ${delegateCommand(names, lane)}`;
@@ -278,19 +280,21 @@ export function currentBranch(root) {
 
 /** Who is acting: { kind: 'lead' | 'lane' | 'readonly', lane?, label }. */
 export function actorFor(input, root, config) {
+  // OWN-1: the session it acts in, whose decisions what it's refused become.
+  const session = input.session_id ?? null;
   const agent = input.agent_type;
   if (agent) {
     const lane = Object.keys(config.lanes).find((l) => config.lanes[l].agent === agent);
     return lane
-      ? { kind: 'lane', lane, label: `${agent} (${lane} lane)` }
-      : { kind: 'readonly', label: agent };
+      ? { kind: 'lane', lane, label: `${agent} (${lane} lane)`, session }
+      : { kind: 'readonly', label: agent, session };
   }
   const laneFile = join(root, LANE_FILE);
   if (existsSync(laneFile)) {
     const lane = readFileSync(laneFile, 'utf8').trim();
-    return { kind: 'lane', lane, label: `${lane} lane worktree` };
+    return { kind: 'lane', lane, label: `${lane} lane worktree`, session };
   }
-  return { kind: 'lead', label: 'lead session' };
+  return { kind: 'lead', label: 'lead session', session };
 }
 
 /** Where approvals live: the main checkout's approvals folder, shared by all of its worktrees. */
@@ -358,6 +362,7 @@ export function useApproval(root, name, actor) {
 const requestsFile = (root) => join(projectWorktrees(root)[0] ?? root, REQUESTS_FILE);
 const sameRequest = (a, b) =>
   a.actor === b.actor &&
+  (a.session ?? null) === (b.session ?? null) &&
   a.what === b.what &&
   [...a.names].sort().join() === [...b.names].sort().join();
 
@@ -423,6 +428,7 @@ export function recordRequest(root, actor, names, what, why, now = Date.now(), e
       at: new Date(now).toISOString(),
       actor: actor?.label ?? 'unknown',
       ...(actor?.kind === 'lane' ? { lane: actor.lane } : {}),
+      ...(actor?.session ? { session: actor.session } : {}),
       names: [names].flat(),
       what: String(what).slice(0, 200),
       why: String(why).slice(0, 300),
@@ -761,7 +767,7 @@ export function writeProblem(actor, rel, root, config) {
   if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
     recordRequest(root, actor, guarded.approval, rel, guarded.why);
     const who =
-      decidedBy(guarded.approval, config) === 'lead'
+      decidedBy(guarded.approval, config, actor) === 'lead'
         ? "the lead's approval"
         : "a person's approval";
     return `${rel} is ${guarded.why} and needs ${who}.${noteFor(root, config, { kind: 'protected', name: guarded.approval, glob: guarded.glob })} ${askHowTo(guarded.approval, actor, root, config)}`;

package/hooks/lib/schedule.mjs

@@ -0,0 +1,86 @@
+// What starts next, lane by lane (docs/specs/23-the-team.md, SCHED-1 and SCHED-2), the pure parts. A lane
+// runs one story at a time; the plan's graph is for running different lanes at once. Slices (a story's
+// `**Slice:** <name>`, a feature that can be shown working across lanes) set the order, not a gate: a free
+// lane takes a ready story in an open slice first, then one in the next slice while fewer than
+// `harness.slices.open` are open, then any story outside a slice, and only then one ahead of its slice.
+
+/** States a story is in once its work has started: its slice is open from then until all of it is done. */
+const STARTED = new Set(['in progress', 'review', 'sent back', 'waiting on you', 'done']);
+
+/** Each slice in plan order: [{ name, stories, open, done }]. */
+export function slicesOf(stories) {
+  const byName = new Map();
+  for (const s of stories) {
+    if (!s.slice) continue;
+    if (!byName.has(s.slice)) byName.set(s.slice, []);
+    byName.get(s.slice).push(s);
+  }
+  return [...byName].map(([name, own]) => {
+    const done = own.every((s) => s.state === 'done');
+    return {
+      name,
+      stories: own.map((s) => s.id),
+      done,
+      open: !done && own.some((s) => STARTED.has(s.state)),
+    };
+  });
+}
+
+/**
+ * SCHED-1, SCHED-2: at most one story for each free lane. `fixes` (sent back, which go first in their
+ * lane) and `ready` are story ids; `busy` the lanes running a story now. Returns { pick, ahead, waiting,
+ * opened }: the ids to dispatch, those of them ahead of their slice ([{ id, slice }]), the ready or sent-back
+ * ids left for a lane's next turn, and the slices a pick opens.
+ */
+export function pickPerLane(stories, { fixes = [], ready = [], busy = new Set(), open = 1 } = {}) {
+  const order = new Map(stories.map((s, i) => [s.id, i]));
+  const byId = new Map(stories.map((s) => [s.id, s]));
+  const slices = slicesOf(stories);
+  const opened = new Set(slices.filter((s) => s.open).map((s) => s.name));
+  const startOrder = [];
+  let room = Math.max(0, open - opened.size);
+  // The next slice in plan order that isn't open or done: the one a free lane may open.
+  const nextSlice = () => slices.find((s) => !s.done && !opened.has(s.name))?.name ?? null;
+  const rank = (id) => {
+    const slice = byId.get(id)?.slice ?? null;
+    if (slice && opened.has(slice)) return 0;
+    if (slice && room > 0 && slice === nextSlice()) return 1;
+    return slice ? 3 : 2;
+  };
+  const candidates = [...new Set([...fixes, ...ready])].filter((id) => byId.get(id)?.lane);
+  const lanes = [...new Set(candidates.map((id) => byId.get(id).lane))].sort(
+    (a, b) =>
+      Math.min(...candidates.filter((id) => byId.get(id).lane === a).map((id) => order.get(id))) -
+      Math.min(...candidates.filter((id) => byId.get(id).lane === b).map((id) => order.get(id))),
+  );
+  const pick = [];
+  const ahead = [];
+  // Lanes with something in an open slice choose first, so the feature in progress is never passed over.
+  const firstRank = (lane) =>
+    Math.min(...candidates.filter((id) => byId.get(id).lane === lane).map(rank));
+  for (const lane of [...lanes].sort((a, b) => firstRank(a) - firstRank(b))) {
+    if (busy.has(lane)) continue;
+    const own = candidates.filter((id) => byId.get(id).lane === lane);
+    const fix = own.find((id) => fixes.includes(id));
+    const chosen =
+      fix ??
+      [...own].sort((a, b) => rank(a) - rank(b) || order.get(a) - order.get(b)).find(Boolean);
+    if (!chosen) continue;
+    const r = fix ? null : rank(chosen);
+    const slice = byId.get(chosen).slice ?? null;
+    if (r === 1) {
+      opened.add(slice);
+      startOrder.push(slice);
+      room -= 1;
+    }
+    if (r === 3) ahead.push({ id: chosen, slice });
+    pick.push(chosen);
+  }
+  pick.sort((a, b) => order.get(a) - order.get(b));
+  return {
+    pick,
+    ahead,
+    waiting: candidates.filter((id) => !pick.includes(id)),
+    opened: startOrder,
+  };
+}