@warren-dean/code-kit 0.29.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,11 +8,13 @@ import { loadConfig, mergeDelegation } from './config.mjs';
8
8
  import { buildStatus, readStories, DESIGN, LEAD } from './plan.mjs';
9
9
  import { pendingSetup } from './adapters/index.mjs';
10
10
  import { CONFIG_FILE, SETUP_VERSION } from './config.mjs';
11
- import { mergingNow, nextToMerge, readQueue, waiting } from './queue.mjs';
12
- import { handedOver, readRegister, toolOf } from './designs.mjs';
11
+ import { mergingNow, nextToMerge, queuePause, readQueue, waiting } from './queue.mjs';
12
+ import { activeDeferrals, deferralWords } from './deferrals.mjs';
13
+ import { designsFor, handedOver, readRegister, toolOf } from './designs.mjs';
13
14
  import { decidedBy, laneOf, openRequests } from './rules.mjs';
14
15
  import { instructionsState } from './instructions.mjs';
15
16
  import { SECURITY_AGENT_FILE } from './security.mjs';
17
+ import { isTestFile } from './testfiles.mjs';
16
18
  import { laneClaims } from './laneclaims.mjs';
17
19
  import { keptBecause, worktrees } from './worktrees.mjs';
18
20
  import { ciFindings } from './ci.mjs';
@@ -20,7 +22,7 @@ import { storyModels } from './dispatches.mjs';
20
22
  import { pickPerLane } from './schedule.mjs';
21
23
  import { reconcileAll } from './events.mjs';
22
24
  import { readCache, teamOf } from './team.mjs';
23
- import { driftHoldWords, driftHolds, driftUnchecked } from './teamfacts.mjs';
25
+ import { driftHoldWords, driftHolds, driftUnchecked, storyOfBranch } from './teamfacts.mjs';
24
26
 
25
27
  export const DRAFT_FILE = '.claude/code-kit.draft.json';
26
28
  export const BRIEF_STATES = ['framed', 'explored', 'scoped', 'specified', 'planned', 'ready'];
@@ -84,7 +86,9 @@ const hasMarkdown = (dir) => {
84
86
  };
85
87
 
86
88
  /**
87
- * { step, why, args, then, attention, brief, worktrees }. `brief`: the brief's open questions (ASK-4);
89
+ * { step, why, args, then, attention, brief, worktrees, deferred, queuePaused }. `brief`: the brief's open
90
+ * questions (ASK-4); `deferred`: the stories the lead holds, { story, reason, until, at, branch } (LOOP-15);
91
+ * `queuePaused`: the lead's pause of the merge queue, { reason, at }, or null (MQ-8);
88
92
  * `worktrees`: the merged ones still holding changes, { branch, story, changes, files }, for the person (LEAN-8);
89
93
  * `models`: each story offered to a lane, with the model it runs on and why, { story, model, why } (SCHED-3). `step` is a skill (spec-design, init, check, dispatch,
90
94
  * review), `merge` (the head of the merge queue, where the lead merges), `wait` (lanes are
@@ -98,6 +102,9 @@ export function nextStep(root, base) {
98
102
  let holdingTrees = [];
99
103
  // SCHED-3: the model each story offered to a lane runs on, and why.
100
104
  let models = [];
105
+ // LOOP-15, MQ-8: what the lead holds on purpose: stories, and the whole merge queue.
106
+ let deferred = [];
107
+ let queuePaused = null;
101
108
  const result = (step, why, extra = {}) => ({
102
109
  step,
103
110
  why,
@@ -107,6 +114,8 @@ export function nextStep(root, base) {
107
114
  brief: briefQuestions,
108
115
  worktrees: holdingTrees,
109
116
  models,
117
+ deferred,
118
+ queuePaused,
110
119
  ...extra,
111
120
  });
112
121
  const isRepo = git(root, 'rev-parse', '--is-inside-work-tree') === 'true';
@@ -275,6 +284,20 @@ export function nextStep(root, base) {
275
284
  `${stopped.join(', ')} ${stopped.length === 1 ? 'has its branch but no commits, and no agent on it' : 'have their branches but no commits, and no agent on them'}: ${stopped.length === 1 ? 'it goes' : 'they go'} to a fresh agent, on the same branch.`,
276
285
  );
277
286
 
287
+ // LOOP-15: a story the lead holds isn't dispatched, reviewed or merged until the hold ends.
288
+ const holds = activeDeferrals(root);
289
+ const heldIds = new Set(holds.map((h) => h.story));
290
+ deferred = holds.map((h) => ({
291
+ ...h,
292
+ branch: status.stories.find((s) => s.id === h.story)?.branch ?? null,
293
+ words: deferralWords(h),
294
+ }));
295
+ for (const h of holds)
296
+ attention.push(
297
+ `${deferralWords(h)}. Nothing dispatches, reviews or merges it until ${h.until ? 'then, or ' : ''}code-kit defer release ${h.story}.`,
298
+ );
299
+ // MQ-8: the lead's pause of the merge queue: nothing merges, and no merge is offered.
300
+ queuePaused = queuePause(root);
278
301
  // A branch already in the merge queue has passed its review: it isn't reviewed again.
279
302
  const entries = readQueue(root);
280
303
  const inQueue = waiting(entries);
@@ -288,7 +311,14 @@ export function nextStep(root, base) {
288
311
  )
289
312
  : new Map();
290
313
  // MQ-7: what can merge next; a branch queued with partners waits until they're queued too.
291
- const { head: mergeHead, held: heldGroups, drifting } = nextToMerge(entries, drift);
314
+ const deferredBy = new Map(
315
+ inQueue.flatMap((e) => {
316
+ const story = storyOfBranch(e.branch);
317
+ const hold = story && holds.find((h) => h.story === story);
318
+ return hold ? [[e.branch, hold]] : [];
319
+ }),
320
+ );
321
+ const { head: mergeHead, held: heldGroups, drifting } = nextToMerge(entries, drift, deferredBy);
292
322
  const queued = inQueue.map((e) => e.branch);
293
323
  const driftWords = drifting.map((d) =>
294
324
  driftHoldWords(d.branch, d.findings, {
@@ -303,6 +333,7 @@ export function nextStep(root, base) {
303
333
  const ids = (state) =>
304
334
  status.stories
305
335
  .filter((s) => s.state === state && !(state === 'review' && queued.includes(s.branch)))
336
+ .filter((s) => state === 'in progress' || !heldIds.has(s.id))
306
337
  .map((s) => s.id);
307
338
  const [review, building, blocked, fixes] = ['review', 'in progress', 'blocked', 'sent back'].map(
308
339
  ids,
@@ -319,7 +350,7 @@ export function nextStep(root, base) {
319
350
  (Boolean(config.lanes[s.lane]) || s.lane === LEAD || s.lane === DESIGN) &&
320
351
  (s.requirements.length > 0 || s.noRequirements) &&
321
352
  s.requirements.every((r) => defined.has(r));
322
- const readyStories = status.stories.filter((s) => s.state === 'ready');
353
+ const readyStories = status.stories.filter((s) => s.state === 'ready' && !heldIds.has(s.id));
323
354
  // The lead's own stories are built by the lead, not dispatched to a lane agent.
324
355
  const forLead = readyStories.filter((s) => buildable(s) && s.lane === LEAD).map((s) => s.id);
325
356
  const ready = readyStories
@@ -387,14 +418,18 @@ export function nextStep(root, base) {
387
418
  const leadMerges = delegation.delegated && config.harness.autonomy === 'autonomous';
388
419
  // SETUP-2: a base with no rules committed (a project set up before setup committed them there): the
389
420
  // lead puts the approved rules onto it, and the queue merges under them from then on.
390
- if (queued.length && delegation.first)
421
+ if (queued.length && delegation.first && !queuePaused)
391
422
  return result(
392
423
  'rules',
393
424
  `${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.`,
394
425
  { args: delegation.into },
395
426
  );
396
- const mergeable = queued.filter((b) => !heldByDrift.has(b));
397
- if (mergeable.length && !leadMerges)
427
+ const mergeable = queued.filter((b) => !heldByDrift.has(b) && !deferredBy.has(b));
428
+ if (queuePaused)
429
+ attention.push(
430
+ `The merge queue is paused: ${queuePaused.reason}. Nothing merges until code-kit queue resume${queued.length ? `; ${queued.join(', ')} ${queued.length === 1 ? 'waits' : 'wait'} in it` : ''}.`,
431
+ );
432
+ else if (mergeable.length && !leadMerges)
398
433
  attention.push(
399
434
  `${mergeable.join(', ')} passed review and ${mergeable.length === 1 ? 'waits' : 'wait'} for the person to merge (code-kit queue merge --person, or Merge in the code-kit band).`,
400
435
  );
@@ -408,12 +443,35 @@ export function nextStep(root, base) {
408
443
  attention.push(
409
444
  `${h.branch} passed review and merges together with ${h.missing.join(', ')}: it waits until ${h.missing.length === 1 ? 'that is' : 'they are'} reviewed and queued.`,
410
445
  );
411
- if (mergeHead && leadMerges && !merging)
446
+ if (mergeHead && leadMerges && !merging && !queuePaused)
412
447
  return result(
413
448
  'merge',
414
449
  `${mergeHead.branch} passed review and is next in the merge queue${queued.length > 1 ? ` (then ${queued.filter((b) => b !== mergeHead.branch).join(', ')})` : ''}.`,
415
450
  { args: mergeHead.branch },
416
451
  );
452
+ // HAND-6: a screen story whose screens' approved designs are only in a design tool can't be built:
453
+ // the gate refuses each screen until the lead hands its design over. It waits, and the hand-over is
454
+ // the step, rather than a lane dispatched to be refused.
455
+ const { entries: registered } = readRegister(root, config);
456
+ const toHandOver = new Map();
457
+ for (const list of [fixes, ready]) {
458
+ const kept = list.filter((id) => {
459
+ const s = status.stories.find((x) => x.id === id);
460
+ const toolOnly = designsFor(registered, id, status.stories).filter(
461
+ (e) => !handedOver(e) && laneOf(e.file, config) === s?.lane,
462
+ );
463
+ if (toolOnly.length) toHandOver.set(id, toolOnly);
464
+ return !toolOnly.length;
465
+ });
466
+ list.splice(0, list.length, ...kept);
467
+ }
468
+ const onlyInTool = [...toHandOver.values()].flat();
469
+ const distinct = (pick) => [...new Set(onlyInTool.map(pick))];
470
+ const handOver = distinct((e) => e.story).sort((a, b) => a.slice(3) - b.slice(3));
471
+ const one = toHandOver.size === 1;
472
+ const handOverWhy = toHandOver.size
473
+ ? `${[...toHandOver.keys()].join(', ')} ${one ? 'builds' : 'build'} screens whose approved designs (${distinct((e) => e.screen ?? e.file).join(', ')}) are only in ${distinct((e) => toolOf(e)).join(', ')}, not as files a lane can build from: hand ${handOver.join(', ')} over with /code-kit:design --hand-over ${handOver.join(' ')} before ${one ? 'it is' : 'they are'} dispatched.`
474
+ : '';
417
475
  // SCHED-1, SCHED-2: one story for each free lane, across every session; the open slice's first.
418
476
  const busy = new Set([
419
477
  ...laneClaims(root)
@@ -438,7 +496,7 @@ export function nextStep(root, base) {
438
496
  `${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.`,
439
497
  );
440
498
  // HAND-5: approved designs still only in a design tool, which no lane can read, are handed over once.
441
- const toolOnly = readRegister(root, config).entries.filter((e) => !handedOver(e));
499
+ const toolOnly = registered.filter((e) => !handedOver(e));
442
500
  if (toolOnly.length)
443
501
  attention.push(
444
502
  `${toolOnly.length} approved screen${toolOnly.length === 1 ? ' is' : 's are'} only in ${[...new Set(toolOnly.map(toolOf))].join(', ')}, not as files a lane can build from: hand ${toolOnly.length === 1 ? 'it' : 'them'} over with /code-kit:design --hand-over.`,
@@ -453,6 +511,8 @@ export function nextStep(root, base) {
453
511
  );
454
512
  models = toDispatch.filter((id) => chosen[id]).map((id) => ({ story: id, ...chosen[id] }));
455
513
  if (review.length && forDesign.length) then.push({ step: 'design', args: forDesign.join(' ') });
514
+ const handOverStep = { step: 'design', args: handOver.join(' '), handOver: true };
515
+ if (review.length && handOver.length) then.push(handOverStep);
456
516
  if (review.length && toDispatch.length)
457
517
  then.push({ step: 'dispatch', args: toDispatch.join(' ') });
458
518
  if (forLead.length) then.push({ step: 'lead', args: forLead.join(' ') });
@@ -468,11 +528,21 @@ export function nextStep(root, base) {
468
528
  {
469
529
  args: forDesign.join(' '),
470
530
  then: [
531
+ ...(handOver.length ? [handOverStep] : []),
471
532
  ...(toDispatch.length ? [{ step: 'dispatch', args: toDispatch.join(' ') }] : []),
472
533
  ...(forLead.length ? [{ step: 'lead', args: forLead.join(' ') }] : []),
473
534
  ],
474
535
  },
475
536
  );
537
+ if (handOver.length)
538
+ return result('design', handOverWhy, {
539
+ args: handOver.join(' '),
540
+ handOver: true,
541
+ then: [
542
+ ...(toDispatch.length ? [{ step: 'dispatch', args: toDispatch.join(' ') }] : []),
543
+ ...(forLead.length ? [{ step: 'lead', args: forLead.join(' ') }] : []),
544
+ ],
545
+ });
476
546
  if (fixes.length)
477
547
  return result(
478
548
  'dispatch',
@@ -509,7 +579,11 @@ export function nextStep(root, base) {
509
579
  );
510
580
  // Stories waiting on branches in the merge queue wait for the merge, not on a broken plan. HUBR-9: a
511
581
  // queue that only drift findings hold says which, and how each clears.
512
- const heldOnly = !mergeHead && driftWords.length ? driftWords.join(' ') : null;
582
+ const heldOnly = queuePaused
583
+ ? `The merge queue is paused: ${queuePaused.reason}.`
584
+ : !mergeHead && driftWords.length
585
+ ? driftWords.join(' ')
586
+ : null;
513
587
  if (queued.length)
514
588
  return result(
515
589
  'wait',
@@ -528,6 +602,12 @@ export function nextStep(root, base) {
528
602
  'wait',
529
603
  `${waitingOnPerson.map((s) => `${s.id} waits on the person (${s.waitingFor.id})`).join('; ')}${blocked.length ? `; ${blocked.join(', ')} ${blocked.length === 1 ? 'waits' : 'wait'} on ${waitingOnPerson.length === 1 ? 'it' : 'them'}` : ''}. Carry on with anything else; their answer is sent to you.`,
530
604
  );
605
+ // LOOP-15: what's left waits on stories the lead holds, or is one of them.
606
+ if (holds.length && status.stories.some((s) => heldIds.has(s.id) && s.state !== 'done'))
607
+ return result(
608
+ 'wait',
609
+ `${holds.map(deferralWords).join('; ')}. Nothing else can start; the loop goes on when a hold ends or is released.`,
610
+ );
531
611
  if (blocked.length)
532
612
  return result(
533
613
  'spec-design',
@@ -546,7 +626,8 @@ export function nextStep(root, base) {
546
626
 
547
627
  const SCREEN_LANE = /(^|-)(web|mobile|frontend|front-end|ui|desktop|ios|android|admin|portal)(-|$)/;
548
628
  const SCREEN_FILE = /\.(tsx|jsx|vue|svelte|swift|dart)$/;
549
- const TEST_FILE = /(^|\/)(__tests__|e2e|tests?)\/|\.(test|spec|stories)\.\w+$/;
629
+ // A story file shows a screen in isolation; like a test, it isn't one.
630
+ const STORIES_FILE = /\.stories\.\w+$/;
550
631
  const QA_LANE = /(^|-)(qa|e2e|tests?)(-|$)/;
551
632
 
552
633
  /**
@@ -569,7 +650,9 @@ export function setupGaps(config, stories, files = []) {
569
650
  function screenGaps(config, stories, files) {
570
651
  const lanes = Object.entries(config.lanes);
571
652
  const holdsScreens = new Set(
572
- files.filter((f) => SCREEN_FILE.test(f) && !TEST_FILE.test(f)).map((f) => laneOf(f, config)),
653
+ files
654
+ .filter((f) => SCREEN_FILE.test(f) && !isTestFile(f, config) && !STORIES_FILE.test(f))
655
+ .map((f) => laneOf(f, config)),
573
656
  );
574
657
  const screens = lanes
575
658
  .filter(
@@ -11,6 +11,7 @@ import { readEvents } from './events.mjs';
11
11
  import { laneClaims } from './laneclaims.mjs';
12
12
  import { waitingStories } from './questions.mjs';
13
13
  import { sentBack } from './reviews.mjs';
14
+ import { isTestFile } from './testfiles.mjs';
14
15
  import { WORKTREES_DIR } from './worktrees.mjs';
15
16
 
16
17
  export const REQUIREMENT = /\b(?!ST-)([A-Z][A-Z0-9]*-\d+)\b/g;
@@ -22,9 +23,6 @@ export const DROPPED = 'dropped';
22
23
  export const LEAD = 'lead';
23
24
  /** ONB-2: the pseudo-lane for design stories, which the lead designs with the person before any screen is built. */
24
25
  export const DESIGN = 'design';
25
- // Test files, by the usual conventions. Tests name the requirement IDs they prove.
26
- const TEST =
27
- /(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
28
26
 
29
27
  /** The markdown files at `path`: the file itself, or every one under the folder, sorted. */
30
28
  export const markdownFiles = (root, path) => {
@@ -85,6 +83,134 @@ export function readSpecs(root, specsPath, plan = null) {
85
83
  return found;
86
84
  }
87
85
 
86
+ /** A screen's name as the specs and the register give it, compared: no markdown, one case, one space. */
87
+ export const screenKey = (name) =>
88
+ String(name ?? '')
89
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
90
+ .replace(/[*_`]/g, '')
91
+ .replace(/\s+/g, ' ')
92
+ .trim()
93
+ .toLowerCase();
94
+
95
+ /** The states a `**States:**` line or a States cell lists, in lower case. */
96
+ const statesOf = (text) =>
97
+ String(text)
98
+ .replace(/<br\s*\/?>/gi, ',')
99
+ .split(/[,;/]/)
100
+ .map((s) => screenKey(s).replace(/\.$/, ''))
101
+ .filter(Boolean);
102
+
103
+ /** A `- **Name** …` bullet that lists a screen: { indent, title }, or null (a field such as `**States:**`). */
104
+ function screenBullet(line) {
105
+ const m = line.match(/^(\s*)[-*]\s+\*\*([^*]+?)\*\*/);
106
+ return m && !/:\s*$/.test(m[2]) ? { indent: m[1].length, title: m[2] } : null;
107
+ }
108
+
109
+ const cellsOf = (line) =>
110
+ line
111
+ .trim()
112
+ .replace(/^\||\|$/g, '')
113
+ .split('|')
114
+ .map((c) => c.trim());
115
+
116
+ /**
117
+ * The screens one `## Screens` section lists, from its lines: `### Name` and `#### Name` headings (a
118
+ * trailing `(…)` left out of the name), `- **Name** …` bullets (by the bold title; a bold title ending in
119
+ * a colon, such as `**States:**`, is a field, not a screen), and a table's rows (by its Screen or Name
120
+ * column, else its first; a States column gives the states).
121
+ */
122
+ function screensIn(lines, file) {
123
+ const found = [];
124
+ const fieldStates = (body) => body.match(/\*\*States:\*\*\s*(.+)/i)?.[1] ?? null;
125
+ lines.forEach((line, i) => {
126
+ const heading = line.match(/^#{3,4}\s+(.+?)\s*$/);
127
+ if (heading) {
128
+ const end = lines.findIndex((l, j) => j > i && /^#{1,4}\s/.test(l));
129
+ const block = lines.slice(i, end < 0 ? undefined : end);
130
+ // Its own States line comes before any screen listed under it.
131
+ const own = block.findIndex((l, j) => j > 0 && screenBullet(l));
132
+ const listed = fieldStates(block.slice(0, own < 0 ? undefined : own).join('\n'));
133
+ const name = heading[1].replace(/\s*\([^)]*\)\s*$/, '');
134
+ found.push({
135
+ name: screenKey(name),
136
+ title: name.replace(/[*_`]/g, '').trim(),
137
+ file,
138
+ states: listed ? statesOf(listed) : null,
139
+ body: block.join('\n'),
140
+ });
141
+ return;
142
+ }
143
+ const bullet = screenBullet(line);
144
+ if (bullet) {
145
+ const { indent } = bullet;
146
+ const end = lines.findIndex(
147
+ (l, j) =>
148
+ j > i &&
149
+ (/^#{1,4}\s/.test(l) ||
150
+ /^\s*\|/.test(l) ||
151
+ (/^\s*[-*]\s/.test(l) && l.match(/^\s*/)[0].length <= indent)),
152
+ );
153
+ const body = lines.slice(i, end < 0 ? undefined : end).join('\n');
154
+ const listed = fieldStates(body);
155
+ found.push({
156
+ name: screenKey(bullet.title),
157
+ title: bullet.title.trim(),
158
+ file,
159
+ states: listed ? statesOf(listed) : null,
160
+ body,
161
+ });
162
+ }
163
+ });
164
+ // Tables: a header row, its separator, then a row per screen.
165
+ for (let i = 0; i + 1 < lines.length; i++) {
166
+ if (!/^\s*\|/.test(lines[i]) || !/^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1])) continue;
167
+ if (i > 0 && /^\s*\|/.test(lines[i - 1])) continue;
168
+ const header = cellsOf(lines[i]).map((c) => screenKey(c));
169
+ const nameAt = Math.max(
170
+ header.findIndex((c) => /^(screen|name)\b/.test(c)),
171
+ 0,
172
+ );
173
+ const statesAt = header.findIndex((c) => /^states?\b/.test(c));
174
+ for (let j = i + 2; j < lines.length && /^\s*\|/.test(lines[j]); j++) {
175
+ const cells = cellsOf(lines[j]);
176
+ const title = (cells[nameAt] ?? '').replace(/\s*\([^)]*\)\s*$/, '');
177
+ if (!screenKey(title)) continue;
178
+ found.push({
179
+ name: screenKey(title),
180
+ title: title.replace(/[*_`]/g, '').trim(),
181
+ file,
182
+ states: statesAt >= 0 && cells[statesAt] ? statesOf(cells[statesAt]) : null,
183
+ body: lines[j],
184
+ });
185
+ }
186
+ }
187
+ return found;
188
+ }
189
+
190
+ /**
191
+ * HAND-9: every screen the specs' `## Screens` sections list: [{ name, title, file, states, body }].
192
+ * `name` is the screen's name compared (screenKey), `title` as written; `states` what a `**States:**`
193
+ * line or a States column lists, or null when neither does; `body` its text, for the states it mentions.
194
+ */
195
+ export function readScreens(root, specsPath) {
196
+ if (!specsPath) return [];
197
+ const found = [];
198
+ for (const file of markdownFiles(root, specsPath)) {
199
+ let lines;
200
+ try {
201
+ lines = readFileSync(join(root, file), 'utf8').split('\n');
202
+ } catch {
203
+ continue;
204
+ }
205
+ lines.forEach((line, i) => {
206
+ if (!/^##\s+Screens\b/i.test(line)) return;
207
+ const end = lines.findIndex((l, j) => j > i && /^#{1,2}\s/.test(l));
208
+ found.push(...screensIn(lines.slice(i + 1, end < 0 ? undefined : end), file));
209
+ });
210
+ }
211
+ return found;
212
+ }
213
+
88
214
  /** The first paragraph under a story's `**Field:**` lines, on one line, or null. */
89
215
  function summaryOf(body) {
90
216
  const start = body.findIndex((l) => l.trim() && !/^\*\*[^*]+:\*\*/.test(l.trim()));
@@ -99,7 +225,7 @@ function summaryOf(body) {
99
225
  }
100
226
 
101
227
  /**
102
- * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, fixes, milestone, slice, size, summary }].
228
+ * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, fixes, milestone, slice, size, screens, summary }].
103
229
  * A story's milestone is the `## ` heading above it ("Milestone 5: Your own key"), or null; its summary the
104
230
  * paragraph under its fields, on one line, or null.
105
231
  */
@@ -135,6 +261,13 @@ export function readStories(root, planPath) {
135
261
  field(body, 'Size')
136
262
  .toLowerCase()
137
263
  .match(/^(small|medium|large)\b/)?.[1] ?? null,
264
+ // HAND-10: the screens a design story designs, where the plan names them, or null.
265
+ screens: field(body, 'Screens')
266
+ ? field(body, 'Screens')
267
+ .split(/[,;]/)
268
+ .map((n) => n.trim())
269
+ .filter(Boolean)
270
+ : null,
138
271
  summary: summaryOf(body),
139
272
  });
140
273
  });
@@ -168,11 +301,11 @@ export function readMilestones(root, planPath) {
168
301
 
169
302
  export const storyBranch = (story) => `${story.lane}/${story.id.toLowerCase()}`;
170
303
 
171
- /** Requirement IDs each tracked test file names: { id: [file, ...] }. */
172
- export function testedRequirements(root, files, specsPath) {
304
+ /** Requirement IDs each tracked test file names (tests name the IDs they prove): { id: [file, ...] }. */
305
+ export function testedRequirements(root, files, specsPath, config) {
173
306
  const tested = {};
174
307
  for (const file of files) {
175
- if (!TEST.test(file) || file.endsWith('.md') || file.startsWith(`${specsPath}/`)) continue;
308
+ if (!isTestFile(file, config) || file.startsWith(`${specsPath}/`)) continue;
176
309
  let body;
177
310
  try {
178
311
  body = readFileSync(join(root, file), 'utf8');
@@ -279,8 +412,12 @@ function worktrees(root) {
279
412
  * whatever the plan says yet. A lane's branch that never moved is `stopped`: its agent stopped before its
280
413
  * first commit, and the story is ready again (or blocked) for a fresh agent, so its lane isn't held by
281
414
  * nothing. A branch only on origin may be a teammate's, and stays in progress unless the base holds it.
415
+ *
416
+ * HAND-10: a design story's branch is committed to as each screen is approved, so with commits ahead it
417
+ * stays in progress while `designing(story, ref)` says screens it designs aren't in its register yet,
418
+ * until the plan's status says `review`.
282
419
  */
283
- export function storyStates(root, stories, base) {
420
+ export function storyStates(root, stories, base, { designing = null } = {}) {
284
421
  const trees = worktrees(root);
285
422
  const backs = sentBack(root);
286
423
  const refs = branchRefs(root, base);
@@ -322,7 +459,11 @@ export function storyStates(root, stories, base) {
322
459
  if (ref && !['done', DROPPED].includes(story.status)) {
323
460
  const head = backs[branch] ? refs[ref].sha : null;
324
461
  if (head && head === backs[branch].sha) state = 'sent back';
325
- else if (ahead > 0) state = building(story) ? 'in progress' : 'review';
462
+ else if (ahead > 0)
463
+ state =
464
+ building(story) || (story.lane === DESIGN && designing?.(story, ref))
465
+ ? 'in progress'
466
+ : 'review';
326
467
  else if (story.status === 'review') state = 'done';
327
468
  else if (builtBy(story, branch)) state = 'in progress';
328
469
  else {
@@ -398,12 +539,46 @@ export function traceProblems(requirements, stories, lanes) {
398
539
  return problems;
399
540
  }
400
541
 
542
+ /**
543
+ * HAND-10: (story, ref) => whether a design story still has screens to design on its branch: a screen
544
+ * its plan entry names (`**Screens:**`), or else one the `## Screens` sections of its requirements'
545
+ * specs list, with no entry in the register as `ref` has it. The plan's `**Status:** review` says the
546
+ * lead is done with it, whatever is left. Null without a design gate.
547
+ */
548
+ function stillDesigning(root, config, requirements) {
549
+ const register = config.designGate?.register;
550
+ if (!register) return null;
551
+ let screens = null;
552
+ return (story, ref) => {
553
+ if (story.status === 'review') return false;
554
+ let wanted = story.screens?.map(screenKey);
555
+ if (!wanted) {
556
+ screens ??= readScreens(root, config.docs?.specs);
557
+ const files = new Set(
558
+ requirements.filter((r) => story.requirements.includes(r.id)).map((r) => r.file),
559
+ );
560
+ wanted = screens.filter((s) => files.has(s.file)).map((s) => s.name);
561
+ }
562
+ if (!wanted.length) return false;
563
+ let entries = [];
564
+ try {
565
+ entries = JSON.parse(git(root, 'show', `${ref}:${register}`) ?? '{}').screens ?? [];
566
+ } catch {
567
+ // an unreadable register on the branch holds no screen yet
568
+ }
569
+ const named = new Set((Array.isArray(entries) ? entries : []).map((e) => screenKey(e?.screen)));
570
+ return wanted.some((w) => !named.has(w));
571
+ };
572
+ }
573
+
401
574
  /** The whole picture for `code-kit status` and `code-kit next`: stories, requirements, gaps, drift. */
402
575
  export function buildStatus(root, config, base, files) {
403
576
  const { specs, plan } = config.docs;
404
577
  const requirements = readRequirements(root, specs).filter((r) => r.file !== plan);
405
- const stories = storyStates(root, readStories(root, plan), base);
406
- const tested = testedRequirements(root, files, specs);
578
+ const stories = storyStates(root, readStories(root, plan), base, {
579
+ designing: stillDesigning(root, config, requirements),
580
+ });
581
+ const tested = testedRequirements(root, files, specs, config);
407
582
  const problems = traceProblems(requirements, stories, Object.keys(config.lanes));
408
583
  const byRequirement = requirements.map((r) => {
409
584
  const covering = stories.filter((s) => s.state !== DROPPED && s.requirements.includes(r.id));
@@ -1,7 +1,7 @@
1
1
  // The merge queue (docs/specs/09-merge-queue.md): branches that passed the lead's review, merged one at
2
2
  // a time in the order they passed, each verified against the base as it is then. Kept in the main
3
3
  // checkout, beside the requests and reviews, so every worktree and a restarted session see the same.
4
- import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4
+ import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
5
5
  import { dirname, join } from 'node:path';
6
6
  import { projectWorktrees } from './rules.mjs';
7
7
  import { GIT, commandsOf } from './shell.mjs';
@@ -80,11 +80,12 @@ export function dequeue(root, branch) {
80
80
  * review, so it's reviewed again), or waiting again.
81
81
  */
82
82
  export function settle(root, branch, state, reason = null, now = Date.now()) {
83
- const entries = readQueue(root).map((e) =>
84
- e.branch === branch && ['waiting', 'merging'].includes(e.state)
85
- ? { ...e, state, at: new Date(now).toISOString(), ...(reason ? { reason } : {}) }
86
- : e,
87
- );
83
+ const entries = readQueue(root).map((e) => {
84
+ if (e.branch !== branch || !['waiting', 'merging'].includes(e.state)) return e;
85
+ // The merge that settled it is over: its process no longer marks the entry.
86
+ const { pid: _pid, ...rest } = e;
87
+ return { ...rest, state, at: new Date(now).toISOString(), ...(reason ? { reason } : {}) };
88
+ });
88
89
  // Merged and sent-back entries move behind the waiting ones' history, in the order they settled.
89
90
  const settled = entries.filter((e) => e.branch === branch && e.state === state);
90
91
  writeQueue(root, [...entries.filter((e) => !settled.includes(e)), ...settled]);
@@ -122,11 +123,13 @@ export function mergingNow(entry) {
122
123
  * MQ-7: what the queue merges next. A branch queued `with` others merges only together with them, once
123
124
  * each is queued too: verified as one tree, merged one after another. Until then it waits, and the
124
125
  * queue goes on with the next. HUBR-9: a branch the team provider's drift findings hold (`drift`,
125
- * Map(branch → findings), from `driftHolds`) waits too, with its group, until they clear. `{ head,
126
- * partners, held, drifting }`: `head` null when nothing can merge yet; `held` lists each waiting branch
127
- * with the partners it still needs queued; `drifting` each one waiting on findings, with them.
126
+ * Map(branch → findings), from `driftHolds`) waits too, with its group, until they clear. MQ-8: so does
127
+ * a branch whose story the lead holds (`deferred`, Map(branch → hold), from `activeDeferrals`). `{ head,
128
+ * partners, held, drifting, deferred }`: `head` null when nothing can merge yet; `held` lists each
129
+ * waiting branch with the partners it still needs queued; `drifting` each one waiting on findings,
130
+ * with them; `deferred` each one whose group holds a held story, with that hold.
128
131
  */
129
- export function nextToMerge(entries, drift = new Map()) {
132
+ export function nextToMerge(entries, drift = new Map(), deferredBy = new Map()) {
130
133
  const queue = waiting(entries);
131
134
  const queued = new Set(queue.map((e) => e.branch));
132
135
  // A partner already merged on its own is no longer waited for.
@@ -151,6 +154,7 @@ export function nextToMerge(entries, drift = new Map()) {
151
154
  };
152
155
  const held = [];
153
156
  const drifting = [];
157
+ const deferred = [];
154
158
  let head = null;
155
159
  let partners = [];
156
160
  for (const e of queue) {
@@ -158,7 +162,9 @@ export function nextToMerge(entries, drift = new Map()) {
158
162
  // A group lands as one, so a finding on any of its branches holds them all.
159
163
  const findings = [...group].flatMap((b) => drift.get(b) ?? []);
160
164
  if (findings.length) drifting.push({ branch: e.branch, findings });
161
- if (head) continue;
165
+ const hold = [...group].map((b) => deferredBy.get(b)).find(Boolean);
166
+ if (hold) deferred.push({ branch: e.branch, hold });
167
+ if (head || hold) continue;
162
168
  const missing = [...group]
163
169
  .flatMap((b) => queue.find((y) => y.branch === b)?.with ?? [])
164
170
  .filter((b) => !queued.has(b) && !merged.has(b));
@@ -170,7 +176,40 @@ export function nextToMerge(entries, drift = new Map()) {
170
176
  head = e;
171
177
  partners = queue.filter((x) => x.branch !== e.branch && group.has(x.branch));
172
178
  }
173
- return { head, partners, held, drifting };
179
+ return { head, partners, held, drifting, deferred };
180
+ }
181
+
182
+ export const PAUSE_FILE = '.claude/state/merge-queue-paused.json';
183
+
184
+ const pauseFile = (root) => join(projectWorktrees(root)[0] ?? root, PAUSE_FILE);
185
+
186
+ /**
187
+ * MQ-8: the lead's deliberate pause of the whole queue, { reason, at, session } or null: while it's
188
+ * paused, the queue merges nothing and nothing offers a merge; branches are still queued.
189
+ */
190
+ export function queuePause(root) {
191
+ try {
192
+ const p = JSON.parse(readFileSync(pauseFile(root), 'utf8'));
193
+ return p && typeof p.reason === 'string' ? p : null;
194
+ } catch {
195
+ return null;
196
+ }
197
+ }
198
+
199
+ /** MQ-8: pauses the queue with why; a pause already in force takes the new reason. */
200
+ export function pauseQueue(root, reason, session = null, now = Date.now()) {
201
+ const file = pauseFile(root);
202
+ mkdirSync(dirname(file), { recursive: true });
203
+ const pause = { reason, at: new Date(now).toISOString(), ...(session ? { session } : {}) };
204
+ writeFileSync(file, `${JSON.stringify(pause, null, 2)}\n`);
205
+ return pause;
206
+ }
207
+
208
+ /** MQ-8: lets the queue merge again; the pause it ended, or null when it wasn't paused. */
209
+ export function resumeQueue(root) {
210
+ const was = queuePause(root);
211
+ if (was) rmSync(pauseFile(root), { force: true });
212
+ return was;
174
213
  }
175
214
 
176
215
  /** MQ-7: a queued branch's partners, which it merges together with. */