@warren-dean/code-kit 0.33.0 → 0.35.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.
@@ -77,7 +77,12 @@ import {
77
77
  leadPrompt,
78
78
  nudgeText,
79
79
  outcomePrompt,
80
+ CHECKED_STEPS,
80
81
  COMPACT_FLOOR,
82
+ RECHECK_MS,
83
+ checkPrompt,
84
+ readCheck,
85
+ talkingText,
81
86
  PARK_MS,
82
87
  compactInstructions,
83
88
  continuePrompt,
@@ -95,6 +100,7 @@ import {
95
100
  stepKey,
96
101
  stepLabel,
97
102
  stepStories,
103
+ holdHint,
98
104
  storiesInFlight,
99
105
  storiesSignature,
100
106
  withoutInFlight,
@@ -168,8 +174,19 @@ const loop = {
168
174
  handedDesign: new Set(), // LOOP-12: design stories handed to the lead this session
169
175
  // LOOP-13: stories the lead said wait on other work: id → { on, why, watch, sig, at }
170
176
  parked: new Map(),
177
+ // LOOP-13: parked stories that woke with nothing they watch moving, until it moves: id → { watch, sig }
178
+ idled: new Map(),
171
179
  // LEAN-3: the milestones already done when this session first looked, and those finished since.
172
180
  milestones: null,
181
+ // LOOP-16: the person's last prompt to the lead ({ at, text }), and, while they talk with the lead
182
+ // about something other than the build, until when the loop waits ({ until }).
183
+ talk: null,
184
+ talking: null,
185
+ // LOOP-17: steps not due yet, by key, whether the lead said so or the check found it: { why, at, print, label }
186
+ held: new Map(),
187
+ // LOOP-17: the lead's last replies, for the check: { at, text, label }
188
+ replies: [],
189
+ unchecked: null, // LOOP-17: the step the person asked for from the band, prompted without a check
173
190
  };
174
191
  // LOOP-10: whether this session runs the loop, the session that does when another does, and when this
175
192
  // one last renewed its lease.
@@ -404,13 +421,19 @@ export function register(on) {
404
421
  boardSynced = at;
405
422
  $.process.run(['node', cli, 'team', 'board'], { cwd, timeoutMs: 120000 }).catch(() => {});
406
423
  }
424
+ const recorded = await json('loop', '--session', session).catch(() => null);
407
425
  // LOOP-10: while another session runs the loop, whether it still does (its lease lapses as it ends).
408
426
  if (!lease.mine) {
409
- const recorded = await json('loop', '--session', session).catch(() => null);
410
427
  const lead = recorded?.lead ?? null;
411
428
  lease.other = lead && lead.session !== session ? lead : null;
412
429
  role = recorded?.role ?? role;
413
430
  }
431
+ // LOOP-6: a pause another tool recorded in the project (`code-kit loop pause`) pauses this loop too.
432
+ if (recorded?.paused && !loop.paused) {
433
+ loop.paused = true;
434
+ loop.proposal = null;
435
+ $.ui.invalidate('ui.render');
436
+ }
414
437
  // SESS-4: a working session's own task, for its band.
415
438
  const task =
416
439
  valid && role === 'working'
@@ -669,6 +692,8 @@ export function register(on) {
669
692
  // TEAM-7: a live provider (the hub's helper) rewrites the team's state as events arrive.
670
693
  await stamp('.claude/state/team.json'),
671
694
  await stamp('.claude/state/merge-queue.json'),
695
+ // LOOP-6: a pause recorded by another tool.
696
+ await stamp('.claude/state/loop.json'),
672
697
  await listing('.claude/approvals'),
673
698
  await listing('.claude/state/stop-blocks'),
674
699
  [...agentsAtWork(await $.agent.list().catch(() => []))].sort().join(','),
@@ -1414,8 +1439,13 @@ export function register(on) {
1414
1439
  if (!loop.parked.size) return;
1415
1440
  const now = await $.clock.now();
1416
1441
  const seen = await act.storiesNow();
1417
- for (const [id, p] of loop.parked)
1418
- if (now - p.at >= PARK_MS || seen.sig(p.watch) !== p.sig) loop.parked.delete(id);
1442
+ for (const [id, p] of loop.parked) {
1443
+ const moved = seen.sig(p.watch) !== p.sig;
1444
+ if (!moved && now - p.at < PARK_MS) continue;
1445
+ loop.parked.delete(id);
1446
+ if (moved) loop.idled.delete(id);
1447
+ else loop.idled.set(id, { watch: p.watch, sig: p.sig });
1448
+ }
1419
1449
  },
1420
1450
  // LEAN-3: a milestone finished in this session: the lead's context is compacted before the next,
1421
1451
  // asked in Claude Code's dialog or done at once, as compact.milestone says. True when it took over
@@ -1486,6 +1516,94 @@ export function register(on) {
1486
1516
  });
1487
1517
  return true;
1488
1518
  },
1519
+ // LOOP-17: a step checked against the project before the lead is prompted with it: the prompt, with
1520
+ // what shows it's due, or null when it isn't (held by its key). A check that can't be read lets
1521
+ // the step go, as before.
1522
+ check: async ({ prompt, step, key, label, print }) => {
1523
+ const facts = await act
1524
+ .stepFacts(step)
1525
+ .catch((err) => `(not read: ${err?.message ?? err})`);
1526
+ const said = await $.model
1527
+ .complete({ model: 'sonnet', prompt: checkPrompt({ prompt, facts }), maxTokens: 400 })
1528
+ .catch(() => ({ isAnswered: false }));
1529
+ const heard = said.isAnswered ? readCheck(said.text) : null;
1530
+ if (!heard) return prompt;
1531
+ if (heard.due)
1532
+ return heard.why
1533
+ ? `${prompt} (Checked against the project just now: ${heard.why.replace(/[.\s]+$/, '')}.)`
1534
+ : prompt;
1535
+ const why = heard.why ?? 'the project shows it is not due';
1536
+ loop.held.set(key, { why, at: await $.clock.now(), print, label });
1537
+ await act.record('held', `${label}: ${why}`);
1538
+ $.ui.invalidate('ui.render');
1539
+ return null;
1540
+ },
1541
+ // LOOP-17: what the check reads, as the project is now: the step's stories and branches against
1542
+ // the base, the merge queue, the agents at work, the latest commits and the lead's last replies.
1543
+ stepFacts: async (step) => {
1544
+ const git = async (...args) => {
1545
+ const r = await $.process.run(['git', ...args], { cwd }).catch(() => null);
1546
+ return r?.exitCode === 0 ? String(r.stdout ?? '').trim() : null;
1547
+ };
1548
+ const base = model.base ?? 'main';
1549
+ const now = await $.clock.now();
1550
+ const lines = [`Step: ${stepLabel(step)}`];
1551
+ const stories = model.state?.stories ?? [];
1552
+ const named = [step, ...(step.then ?? [])].flatMap((s) => stepStories(s));
1553
+ const branches = new Set(
1554
+ (step.step === 'merge' ? String(step.args ?? '').split(/\s+/) : []).filter(Boolean),
1555
+ );
1556
+ for (const id of new Set(named)) {
1557
+ const s = stories.find((x) => x.id === id);
1558
+ lines.push(
1559
+ s
1560
+ ? `${id} ${s.title ?? ''}: ${s.state}${s.branch ? `, branch ${s.branch}` : ''}`
1561
+ : `${id}: not in the plan`,
1562
+ );
1563
+ if (s?.branch) branches.add(s.branch);
1564
+ }
1565
+ for (const b of branches) {
1566
+ const head = await git('log', '-1', '--format=%h %cr: %s', b);
1567
+ if (head === null) {
1568
+ lines.push(`${b}: no such branch here`);
1569
+ continue;
1570
+ }
1571
+ const ahead = await git('rev-list', '--count', `${base}..${b}`);
1572
+ const merged = await $.process
1573
+ .run(['git', 'merge-base', '--is-ancestor', b, base], { cwd })
1574
+ .then((r) => r.exitCode === 0)
1575
+ .catch(() => false);
1576
+ lines.push(
1577
+ `${b}: last commit ${head}; ${merged ? `merged into ${base}` : `${ahead ?? '?'} commits ahead of ${base}`}`,
1578
+ );
1579
+ }
1580
+ const queue = (model.queue ?? []).filter(
1581
+ (q) => q.state !== 'merged' || branches.has(q.branch),
1582
+ );
1583
+ if (queue.length)
1584
+ lines.push(`Merge queue: ${queue.map((q) => `${q.branch} ${q.state}`).join('; ')}`);
1585
+ const atWork = ((await $.agent.list().catch(() => [])) ?? []).filter((a) =>
1586
+ ['pending', 'running', 'waiting'].includes(a.status),
1587
+ );
1588
+ lines.push(
1589
+ atWork.length
1590
+ ? `Agents at work: ${atWork.map((a) => `${a.type} (${a.status}): ${a.description}`).join('; ')}`
1591
+ : 'Agents at work: none',
1592
+ );
1593
+ lines.push(
1594
+ `Latest commits on ${base}:\n${(await git('log', '--oneline', '-8', base)) ?? '(none)'}`,
1595
+ );
1596
+ const here = await git('rev-parse', '--abbrev-ref', 'HEAD');
1597
+ if (here && here !== base)
1598
+ lines.push(
1599
+ `This checkout is on ${here}:\n${(await git('log', '--oneline', '-5', 'HEAD')) ?? ''}`,
1600
+ );
1601
+ for (const r of loop.replies)
1602
+ lines.push(
1603
+ `The lead's reply ${Math.round((now - r.at) / 60_000)} minutes ago, to ${r.label ? `"${r.label}"` : 'the person'}:\n${r.text}`,
1604
+ );
1605
+ return lines.join('\n');
1606
+ },
1489
1607
  // LOOP-11: the lead's last reply, read once before the loop prompts it again. A reply that waits on
1490
1608
  // the person, or a turn they stopped, holds the loop until they speak; a step the lead didn't take
1491
1609
  // holds that step while it's still next.
@@ -1530,11 +1648,25 @@ export function register(on) {
1530
1648
  const said = await $.model
1531
1649
  .complete({
1532
1650
  model: 'sonnet',
1533
- prompt: outcomePrompt({ prompt: sent?.prompt ?? null, answer: reply.text }),
1651
+ prompt: outcomePrompt({
1652
+ prompt: sent?.prompt ?? null,
1653
+ answer: reply.text,
1654
+ said: reply.said,
1655
+ }),
1534
1656
  maxTokens: 600,
1535
1657
  })
1536
1658
  .catch(() => ({ isAnswered: false }));
1537
1659
  const heard = said.isAnswered ? readOutcome(said.text) : null;
1660
+ // LOOP-16: the person talking with the lead about something other than the build holds the loop
1661
+ // until they've been quiet a while; asking it to carry on, or a reply that can't be read, doesn't.
1662
+ if (!sent && reply.said) {
1663
+ const quiet = harness().loop.quietMinutes;
1664
+ loop.talking =
1665
+ heard?.talk === 'conversation' && quiet > 0 && loop.talk
1666
+ ? { until: loop.talk.at + quiet * 60_000 }
1667
+ : null;
1668
+ if (loop.talking) await act.record('talking', `the loop waits ${quiet} minutes`);
1669
+ }
1538
1670
  // Spec 05's data: what came of the step, once known.
1539
1671
  const record = sent ? loop.steps.findLast((x) => x.prompt === sent.prompt) : null;
1540
1672
  if (record) record.outcome = heard?.outcome ?? 'unread';
@@ -1553,6 +1685,15 @@ export function register(on) {
1553
1685
  })),
1554
1686
  );
1555
1687
  }
1688
+ // LOOP-17: a step without stories (a merge, the instructions) the lead said isn't due, or didn't
1689
+ // take, is held by its key, so the person speaking doesn't bring it back while nothing changed.
1690
+ if (['waiting', 'blocked'].includes(heard?.outcome) && sent && !ids.length)
1691
+ loop.held.set(sent.key, {
1692
+ why: heard.reason ?? heard.waits?.[0]?.why ?? "the lead didn't take it",
1693
+ at: await $.clock.now(),
1694
+ print: await act.fingerprint(),
1695
+ label: sent.label,
1696
+ });
1556
1697
  // LOOP-13: a story the lead's turn left exactly where it stood wasn't taken, whatever the reply
1557
1698
  // reads as; it's parked like one the lead said waits, so the loop doesn't prompt it again until
1558
1699
  // it moves.
@@ -1580,6 +1721,7 @@ export function register(on) {
1580
1721
  const w = loop.waiting;
1581
1722
  if (!w?.prompt || leadTurn) return;
1582
1723
  loop.waiting = null;
1724
+ loop.held.delete(w.key);
1583
1725
  for (const id of w.stories ?? []) loop.parked.delete(id);
1584
1726
  loop.asked = { key: w.key, times: 0 };
1585
1727
  await act.submit(w.prompt, w.stepKind, w.target, { key: w.key, label: w.label });
@@ -1588,6 +1730,9 @@ export function register(on) {
1588
1730
  carryOn: async () => {
1589
1731
  for (const id of loop.waiting?.stories ?? []) loop.parked.delete(id);
1590
1732
  loop.waiting = null;
1733
+ // LOOP-16, LOOP-17: the person lets it go on: no wait for their quiet, and no step held.
1734
+ loop.talking = null;
1735
+ loop.held.clear();
1591
1736
  loop.lastKey = null;
1592
1737
  loop.askedAt = { print: null, keys: new Set() };
1593
1738
  $.ui.invalidate('ui.render');
@@ -1630,7 +1775,7 @@ export function register(on) {
1630
1775
  const stale = () => leadTurn || leadTurns !== turns;
1631
1776
  // LOOP-14: a prompt now would fail as the last turn did.
1632
1777
  if (loop.limited && (await $.clock.now()) < loop.limited.until) return;
1633
- if (trigger === 'tick' && !loop.started && !loop.pending.length) return;
1778
+ if (trigger === 'tick' && !loop.started && !loop.pending.length && !loop.talking) return;
1634
1779
  const box = await $.prompt.read().catch(() => null);
1635
1780
  if (box?.text?.trim()) return;
1636
1781
  // LOOP-10: one session in the project runs the loop; in any other, the lead is the person's alone.
@@ -1638,6 +1783,12 @@ export function register(on) {
1638
1783
  // LOOP-11: the lead's last reply first: one that waits on the person holds every step.
1639
1784
  await act.hear();
1640
1785
  if (loop.waiting && ['person', 'stopped'].includes(loop.waiting.kind)) return;
1786
+ // LOOP-16: while the person talks with the lead about something else, nothing is prompted.
1787
+ if (loop.talking) {
1788
+ if ((await $.clock.now()) < loop.talking.until) return;
1789
+ loop.talking = null;
1790
+ $.ui.invalidate('ui.render');
1791
+ }
1641
1792
  // #59: a restart or hand-back for a story that has since merged is stale, and goes unasked; LEAN-5:
1642
1793
  // so is carrying on a story that has since been sent back or queued to merge.
1643
1794
  const stories = model.state?.stories ?? [];
@@ -1693,6 +1844,14 @@ export function register(on) {
1693
1844
  return;
1694
1845
  }
1695
1846
  let prompt = leadPrompt(step, { cli });
1847
+ // LOOP-13, LOOP-15: a story asked about again with nothing it watches moving may wait on a date or
1848
+ // something outside the build; the lead holds it, rather than being asked every half hour.
1849
+ const seen = loop.idled.size ? await act.storiesNow() : null;
1850
+ const idle = stepStories(step).filter(
1851
+ (id) =>
1852
+ loop.idled.has(id) && seen.sig(loop.idled.get(id).watch) === loop.idled.get(id).sig,
1853
+ );
1854
+ if (prompt && idle.length) prompt = `${prompt} ${holdHint(idle, { cli })}`;
1696
1855
  let kind = step.step;
1697
1856
  let target = step.args ?? '';
1698
1857
  let key = stepKey(step);
@@ -1733,6 +1892,14 @@ export function register(on) {
1733
1892
  const print = await act.fingerprint();
1734
1893
  if (stale()) return;
1735
1894
  if (key === loop.lastKey && print === loop.lastPrint) return;
1895
+ // LOOP-17: a step not due yet waits until the project has moved and a while has passed, or for
1896
+ // half an hour with nothing moving; then it's checked again.
1897
+ const hold = loop.held.get(key);
1898
+ if (hold) {
1899
+ const since = (await $.clock.now()) - hold.at;
1900
+ if (since < PARK_MS && (print === hold.print || since < RECHECK_MS)) return;
1901
+ loop.held.delete(key);
1902
+ }
1736
1903
  // LOOP-14: nor any step already prompted while it stood so, as steps taken in turn would be.
1737
1904
  if (loop.askedAt.print !== print) loop.askedAt = { print, keys: new Set() };
1738
1905
  if (loop.askedAt.keys.has(key)) return;
@@ -1756,6 +1923,13 @@ export function register(on) {
1756
1923
  $.ui.invalidate('ui.render');
1757
1924
  return;
1758
1925
  }
1926
+ // LOOP-17: checked against the project as it is now, which code-kit's records can lag.
1927
+ if (h.loop.check && CHECKED_STEPS.has(kind) && loop.unchecked !== key) {
1928
+ const checked = await act.check({ prompt, step, key, label, print });
1929
+ if (stale() || !checked) return;
1930
+ prompt = checked;
1931
+ }
1932
+ loop.unchecked = null;
1759
1933
  loop.asked.times += 1;
1760
1934
  await act.submit(prompt, kind, target, { key, label });
1761
1935
  },
@@ -1823,6 +1997,17 @@ export function register(on) {
1823
1997
  $.ui.invalidate('ui.render');
1824
1998
  await act.step('resume');
1825
1999
  },
2000
+ // LOOP-17: the person asks for a step held as not due: the lead is prompted with it, unchecked.
2001
+ askHeld: async (line) => {
2002
+ const key = line?.step?.key;
2003
+ if (!key || leadTurn) return;
2004
+ loop.held.delete(key);
2005
+ loop.unchecked = key;
2006
+ loop.lastKey = null;
2007
+ loop.askedAt = { print: null, keys: new Set() };
2008
+ $.ui.invalidate('ui.render');
2009
+ await act.step('resume');
2010
+ },
1826
2011
  // LOOP-14: the person asks the loop not to wait out the limit; a turn that fails again holds it again.
1827
2012
  tryNow: async () => {
1828
2013
  loop.limited = null;
@@ -2487,7 +2672,18 @@ export function register(on) {
2487
2672
  sent: loop.sent,
2488
2673
  asked: turnQuestions,
2489
2674
  read: false,
2675
+ // LOOP-16: what the person said, when the turn was theirs.
2676
+ said: loop.sent ? null : (loop.talk?.text ?? null),
2490
2677
  };
2678
+ // LOOP-17: the lead's last replies, which the check reads.
2679
+ if (e.answer?.trim()) {
2680
+ loop.replies.push({
2681
+ at: await $.clock.now(),
2682
+ text: e.answer.trim().slice(0, 800),
2683
+ label: loop.sent?.label ?? null,
2684
+ });
2685
+ if (loop.replies.length > 3) loop.replies.shift();
2686
+ }
2491
2687
  loop.sent = null;
2492
2688
  $.ui.invalidate('ui.render');
2493
2689
  // LOOP-14: a turn the API failed did nothing; the loop holds until the limit resets.
@@ -2530,6 +2726,8 @@ export function register(on) {
2530
2726
  // LOOP-14: the person tries again themselves; the turn's end says whether the limit still holds.
2531
2727
  loop.limited = null;
2532
2728
  loop.askedAt = { print: null, keys: new Set() };
2729
+ // LOOP-16: what they said, and when, for the reading of the lead's reply to it.
2730
+ loop.talk = { at: await $.clock.now(), text: String(e.text ?? '') };
2533
2731
  }
2534
2732
  return next(e);
2535
2733
  });
@@ -2592,6 +2790,14 @@ export function register(on) {
2592
2790
  laneNotes,
2593
2791
  // LOOP-14: the hold on Claude's usage limit, while it lasts.
2594
2792
  limited: loop.limited && now < loop.limited.until ? loop.limited : null,
2793
+ // LOOP-16: the wait while the person talks with the lead; LOOP-17: the steps not due yet.
2794
+ talking:
2795
+ loop.talking && now < loop.talking.until
2796
+ ? { minutes: harness().loop.quietMinutes, until: loop.talking.until }
2797
+ : null,
2798
+ held: [...loop.held]
2799
+ .filter(([key]) => key !== loop.waiting?.key)
2800
+ .map(([key, x]) => ({ key, label: x.label, why: x.why })),
2595
2801
  now,
2596
2802
  reviews: [...reviews.values()].map((r) => ({
2597
2803
  ...r,
@@ -7,7 +7,7 @@ export const NOT_CODE_KIT = "This project doesn't use code-kit.";
7
7
  const LEAD = 'lead';
8
8
 
9
9
  /** A CLI run's stdout as JSON, or null when it printed none. */
10
- import { limitText } from './loop.mjs';
10
+ import { limitText, talkingText } from './loop.mjs';
11
11
  import { teamLines } from './teamview.mjs';
12
12
 
13
13
  export function parseJson(stdout) {
@@ -379,6 +379,22 @@ export function bandLines({
379
379
  // LOOP-11, LOOP-12: what the loop read in the lead's reply holds it until the person says.
380
380
  const waitingLine = waitingOf(loop?.waiting);
381
381
  if (waitingLine) lines.push(waitingLine);
382
+ // LOOP-16: the person talks with the lead about something else; Carry on lets the loop go on now.
383
+ if (loop?.talking)
384
+ lines.push({
385
+ kind: 'talking',
386
+ text: talkingText(loop.talking.minutes),
387
+ actions: [{ id: 'carryOn', label: 'Carry on' }],
388
+ });
389
+ // LOOP-17: a step not due yet, and what shows it; Ask now prompts the lead with it anyway.
390
+ const notDue = loop?.held ?? [];
391
+ if (notDue.length)
392
+ lines.push({
393
+ kind: 'holding',
394
+ text: `${notDue[0].label}: not due yet: ${notDue[0].why}${notDue.length > 1 ? ` (and ${notDue.length - 1} more)` : ''}`,
395
+ step: notDue[0],
396
+ actions: [{ id: 'askHeld', label: 'Ask now' }],
397
+ });
382
398
  // A held call's request is asked on its own line above, not again here.
383
399
  // CARD-2: counted as decisions, not files: one approval for a lane covers every file it was asked for.
384
400
  const asks = approvalAsks((requests?.open ?? []).filter((r) => !held.some((h) => sameAsk(h, r))));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.33.0",
3
+ "version": "0.35.0",
4
4
  "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",
5
5
  "license": "MIT",
6
6
  "author": "Warren Langeveldt",
@@ -23,6 +23,7 @@ Always:
23
23
  - {{if standards}}Build to the project's standards for your layers, from `{{docs.standards}}` (read a standard's why and evidence there when you need it). A required one that review checks sends your branch back if it's broken; advice is yours to weigh:{{standards}}{{end}}
24
24
  - Read every file you change in full. Of what it imports and what calls it, read what your change needs: the definitions it uses and the call sites it changes. A context tool's fresh card for a file stands for reading it whole; read the source where the card is missing, stale or not enough.
25
25
  - Search before you build; reuse existing services, providers, components and schemas.
26
+ - Change files with the Edit and Write tools, not the shell: no `cat > file <<EOF`, `python3 - <<EOF`, `sed -i` or `>>`. In your own worktree, Claude Code refuses a shell command it can't prove stays inside it, and each refusal is a step lost. Keep shell commands to running things, one plain command at a time, from your worktree's root.
26
27
  - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
27
28
  - You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
28
29
  - A new dependency needs the lead's approval. Before asking, check the project doesn't already have something that does the job. If the install is refused, put in a change request for the lead: the package, the story and requirement that need it, what you checked, and anything lighter that would do; then stop. The lead approves it, or tells you what to use instead.