@warren-dean/code-kit 0.32.0 → 0.34.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.
@@ -1414,8 +1431,13 @@ export function register(on) {
1414
1431
  if (!loop.parked.size) return;
1415
1432
  const now = await $.clock.now();
1416
1433
  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);
1434
+ for (const [id, p] of loop.parked) {
1435
+ const moved = seen.sig(p.watch) !== p.sig;
1436
+ if (!moved && now - p.at < PARK_MS) continue;
1437
+ loop.parked.delete(id);
1438
+ if (moved) loop.idled.delete(id);
1439
+ else loop.idled.set(id, { watch: p.watch, sig: p.sig });
1440
+ }
1419
1441
  },
1420
1442
  // LEAN-3: a milestone finished in this session: the lead's context is compacted before the next,
1421
1443
  // asked in Claude Code's dialog or done at once, as compact.milestone says. True when it took over
@@ -1486,6 +1508,94 @@ export function register(on) {
1486
1508
  });
1487
1509
  return true;
1488
1510
  },
1511
+ // LOOP-17: a step checked against the project before the lead is prompted with it: the prompt, with
1512
+ // what shows it's due, or null when it isn't (held by its key). A check that can't be read lets
1513
+ // the step go, as before.
1514
+ check: async ({ prompt, step, key, label, print }) => {
1515
+ const facts = await act
1516
+ .stepFacts(step)
1517
+ .catch((err) => `(not read: ${err?.message ?? err})`);
1518
+ const said = await $.model
1519
+ .complete({ model: 'sonnet', prompt: checkPrompt({ prompt, facts }), maxTokens: 400 })
1520
+ .catch(() => ({ isAnswered: false }));
1521
+ const heard = said.isAnswered ? readCheck(said.text) : null;
1522
+ if (!heard) return prompt;
1523
+ if (heard.due)
1524
+ return heard.why
1525
+ ? `${prompt} (Checked against the project just now: ${heard.why.replace(/[.\s]+$/, '')}.)`
1526
+ : prompt;
1527
+ const why = heard.why ?? 'the project shows it is not due';
1528
+ loop.held.set(key, { why, at: await $.clock.now(), print, label });
1529
+ await act.record('held', `${label}: ${why}`);
1530
+ $.ui.invalidate('ui.render');
1531
+ return null;
1532
+ },
1533
+ // LOOP-17: what the check reads, as the project is now: the step's stories and branches against
1534
+ // the base, the merge queue, the agents at work, the latest commits and the lead's last replies.
1535
+ stepFacts: async (step) => {
1536
+ const git = async (...args) => {
1537
+ const r = await $.process.run(['git', ...args], { cwd }).catch(() => null);
1538
+ return r?.exitCode === 0 ? String(r.stdout ?? '').trim() : null;
1539
+ };
1540
+ const base = model.base ?? 'main';
1541
+ const now = await $.clock.now();
1542
+ const lines = [`Step: ${stepLabel(step)}`];
1543
+ const stories = model.state?.stories ?? [];
1544
+ const named = [step, ...(step.then ?? [])].flatMap((s) => stepStories(s));
1545
+ const branches = new Set(
1546
+ (step.step === 'merge' ? String(step.args ?? '').split(/\s+/) : []).filter(Boolean),
1547
+ );
1548
+ for (const id of new Set(named)) {
1549
+ const s = stories.find((x) => x.id === id);
1550
+ lines.push(
1551
+ s
1552
+ ? `${id} ${s.title ?? ''}: ${s.state}${s.branch ? `, branch ${s.branch}` : ''}`
1553
+ : `${id}: not in the plan`,
1554
+ );
1555
+ if (s?.branch) branches.add(s.branch);
1556
+ }
1557
+ for (const b of branches) {
1558
+ const head = await git('log', '-1', '--format=%h %cr: %s', b);
1559
+ if (head === null) {
1560
+ lines.push(`${b}: no such branch here`);
1561
+ continue;
1562
+ }
1563
+ const ahead = await git('rev-list', '--count', `${base}..${b}`);
1564
+ const merged = await $.process
1565
+ .run(['git', 'merge-base', '--is-ancestor', b, base], { cwd })
1566
+ .then((r) => r.exitCode === 0)
1567
+ .catch(() => false);
1568
+ lines.push(
1569
+ `${b}: last commit ${head}; ${merged ? `merged into ${base}` : `${ahead ?? '?'} commits ahead of ${base}`}`,
1570
+ );
1571
+ }
1572
+ const queue = (model.queue ?? []).filter(
1573
+ (q) => q.state !== 'merged' || branches.has(q.branch),
1574
+ );
1575
+ if (queue.length)
1576
+ lines.push(`Merge queue: ${queue.map((q) => `${q.branch} ${q.state}`).join('; ')}`);
1577
+ const atWork = ((await $.agent.list().catch(() => [])) ?? []).filter((a) =>
1578
+ ['pending', 'running', 'waiting'].includes(a.status),
1579
+ );
1580
+ lines.push(
1581
+ atWork.length
1582
+ ? `Agents at work: ${atWork.map((a) => `${a.type} (${a.status}): ${a.description}`).join('; ')}`
1583
+ : 'Agents at work: none',
1584
+ );
1585
+ lines.push(
1586
+ `Latest commits on ${base}:\n${(await git('log', '--oneline', '-8', base)) ?? '(none)'}`,
1587
+ );
1588
+ const here = await git('rev-parse', '--abbrev-ref', 'HEAD');
1589
+ if (here && here !== base)
1590
+ lines.push(
1591
+ `This checkout is on ${here}:\n${(await git('log', '--oneline', '-5', 'HEAD')) ?? ''}`,
1592
+ );
1593
+ for (const r of loop.replies)
1594
+ lines.push(
1595
+ `The lead's reply ${Math.round((now - r.at) / 60_000)} minutes ago, to ${r.label ? `"${r.label}"` : 'the person'}:\n${r.text}`,
1596
+ );
1597
+ return lines.join('\n');
1598
+ },
1489
1599
  // LOOP-11: the lead's last reply, read once before the loop prompts it again. A reply that waits on
1490
1600
  // the person, or a turn they stopped, holds the loop until they speak; a step the lead didn't take
1491
1601
  // holds that step while it's still next.
@@ -1530,11 +1640,25 @@ export function register(on) {
1530
1640
  const said = await $.model
1531
1641
  .complete({
1532
1642
  model: 'sonnet',
1533
- prompt: outcomePrompt({ prompt: sent?.prompt ?? null, answer: reply.text }),
1643
+ prompt: outcomePrompt({
1644
+ prompt: sent?.prompt ?? null,
1645
+ answer: reply.text,
1646
+ said: reply.said,
1647
+ }),
1534
1648
  maxTokens: 600,
1535
1649
  })
1536
1650
  .catch(() => ({ isAnswered: false }));
1537
1651
  const heard = said.isAnswered ? readOutcome(said.text) : null;
1652
+ // LOOP-16: the person talking with the lead about something other than the build holds the loop
1653
+ // until they've been quiet a while; asking it to carry on, or a reply that can't be read, doesn't.
1654
+ if (!sent && reply.said) {
1655
+ const quiet = harness().loop.quietMinutes;
1656
+ loop.talking =
1657
+ heard?.talk === 'conversation' && quiet > 0 && loop.talk
1658
+ ? { until: loop.talk.at + quiet * 60_000 }
1659
+ : null;
1660
+ if (loop.talking) await act.record('talking', `the loop waits ${quiet} minutes`);
1661
+ }
1538
1662
  // Spec 05's data: what came of the step, once known.
1539
1663
  const record = sent ? loop.steps.findLast((x) => x.prompt === sent.prompt) : null;
1540
1664
  if (record) record.outcome = heard?.outcome ?? 'unread';
@@ -1553,6 +1677,15 @@ export function register(on) {
1553
1677
  })),
1554
1678
  );
1555
1679
  }
1680
+ // LOOP-17: a step without stories (a merge, the instructions) the lead said isn't due, or didn't
1681
+ // take, is held by its key, so the person speaking doesn't bring it back while nothing changed.
1682
+ if (['waiting', 'blocked'].includes(heard?.outcome) && sent && !ids.length)
1683
+ loop.held.set(sent.key, {
1684
+ why: heard.reason ?? heard.waits?.[0]?.why ?? "the lead didn't take it",
1685
+ at: await $.clock.now(),
1686
+ print: await act.fingerprint(),
1687
+ label: sent.label,
1688
+ });
1556
1689
  // LOOP-13: a story the lead's turn left exactly where it stood wasn't taken, whatever the reply
1557
1690
  // reads as; it's parked like one the lead said waits, so the loop doesn't prompt it again until
1558
1691
  // it moves.
@@ -1580,6 +1713,7 @@ export function register(on) {
1580
1713
  const w = loop.waiting;
1581
1714
  if (!w?.prompt || leadTurn) return;
1582
1715
  loop.waiting = null;
1716
+ loop.held.delete(w.key);
1583
1717
  for (const id of w.stories ?? []) loop.parked.delete(id);
1584
1718
  loop.asked = { key: w.key, times: 0 };
1585
1719
  await act.submit(w.prompt, w.stepKind, w.target, { key: w.key, label: w.label });
@@ -1588,6 +1722,9 @@ export function register(on) {
1588
1722
  carryOn: async () => {
1589
1723
  for (const id of loop.waiting?.stories ?? []) loop.parked.delete(id);
1590
1724
  loop.waiting = null;
1725
+ // LOOP-16, LOOP-17: the person lets it go on: no wait for their quiet, and no step held.
1726
+ loop.talking = null;
1727
+ loop.held.clear();
1591
1728
  loop.lastKey = null;
1592
1729
  loop.askedAt = { print: null, keys: new Set() };
1593
1730
  $.ui.invalidate('ui.render');
@@ -1630,7 +1767,7 @@ export function register(on) {
1630
1767
  const stale = () => leadTurn || leadTurns !== turns;
1631
1768
  // LOOP-14: a prompt now would fail as the last turn did.
1632
1769
  if (loop.limited && (await $.clock.now()) < loop.limited.until) return;
1633
- if (trigger === 'tick' && !loop.started && !loop.pending.length) return;
1770
+ if (trigger === 'tick' && !loop.started && !loop.pending.length && !loop.talking) return;
1634
1771
  const box = await $.prompt.read().catch(() => null);
1635
1772
  if (box?.text?.trim()) return;
1636
1773
  // LOOP-10: one session in the project runs the loop; in any other, the lead is the person's alone.
@@ -1638,6 +1775,12 @@ export function register(on) {
1638
1775
  // LOOP-11: the lead's last reply first: one that waits on the person holds every step.
1639
1776
  await act.hear();
1640
1777
  if (loop.waiting && ['person', 'stopped'].includes(loop.waiting.kind)) return;
1778
+ // LOOP-16: while the person talks with the lead about something else, nothing is prompted.
1779
+ if (loop.talking) {
1780
+ if ((await $.clock.now()) < loop.talking.until) return;
1781
+ loop.talking = null;
1782
+ $.ui.invalidate('ui.render');
1783
+ }
1641
1784
  // #59: a restart or hand-back for a story that has since merged is stale, and goes unasked; LEAN-5:
1642
1785
  // so is carrying on a story that has since been sent back or queued to merge.
1643
1786
  const stories = model.state?.stories ?? [];
@@ -1693,6 +1836,14 @@ export function register(on) {
1693
1836
  return;
1694
1837
  }
1695
1838
  let prompt = leadPrompt(step, { cli });
1839
+ // LOOP-13, LOOP-15: a story asked about again with nothing it watches moving may wait on a date or
1840
+ // something outside the build; the lead holds it, rather than being asked every half hour.
1841
+ const seen = loop.idled.size ? await act.storiesNow() : null;
1842
+ const idle = stepStories(step).filter(
1843
+ (id) =>
1844
+ loop.idled.has(id) && seen.sig(loop.idled.get(id).watch) === loop.idled.get(id).sig,
1845
+ );
1846
+ if (prompt && idle.length) prompt = `${prompt} ${holdHint(idle, { cli })}`;
1696
1847
  let kind = step.step;
1697
1848
  let target = step.args ?? '';
1698
1849
  let key = stepKey(step);
@@ -1733,6 +1884,14 @@ export function register(on) {
1733
1884
  const print = await act.fingerprint();
1734
1885
  if (stale()) return;
1735
1886
  if (key === loop.lastKey && print === loop.lastPrint) return;
1887
+ // LOOP-17: a step not due yet waits until the project has moved and a while has passed, or for
1888
+ // half an hour with nothing moving; then it's checked again.
1889
+ const hold = loop.held.get(key);
1890
+ if (hold) {
1891
+ const since = (await $.clock.now()) - hold.at;
1892
+ if (since < PARK_MS && (print === hold.print || since < RECHECK_MS)) return;
1893
+ loop.held.delete(key);
1894
+ }
1736
1895
  // LOOP-14: nor any step already prompted while it stood so, as steps taken in turn would be.
1737
1896
  if (loop.askedAt.print !== print) loop.askedAt = { print, keys: new Set() };
1738
1897
  if (loop.askedAt.keys.has(key)) return;
@@ -1756,6 +1915,13 @@ export function register(on) {
1756
1915
  $.ui.invalidate('ui.render');
1757
1916
  return;
1758
1917
  }
1918
+ // LOOP-17: checked against the project as it is now, which code-kit's records can lag.
1919
+ if (h.loop.check && CHECKED_STEPS.has(kind) && loop.unchecked !== key) {
1920
+ const checked = await act.check({ prompt, step, key, label, print });
1921
+ if (stale() || !checked) return;
1922
+ prompt = checked;
1923
+ }
1924
+ loop.unchecked = null;
1759
1925
  loop.asked.times += 1;
1760
1926
  await act.submit(prompt, kind, target, { key, label });
1761
1927
  },
@@ -1823,6 +1989,17 @@ export function register(on) {
1823
1989
  $.ui.invalidate('ui.render');
1824
1990
  await act.step('resume');
1825
1991
  },
1992
+ // LOOP-17: the person asks for a step held as not due: the lead is prompted with it, unchecked.
1993
+ askHeld: async (line) => {
1994
+ const key = line?.step?.key;
1995
+ if (!key || leadTurn) return;
1996
+ loop.held.delete(key);
1997
+ loop.unchecked = key;
1998
+ loop.lastKey = null;
1999
+ loop.askedAt = { print: null, keys: new Set() };
2000
+ $.ui.invalidate('ui.render');
2001
+ await act.step('resume');
2002
+ },
1826
2003
  // LOOP-14: the person asks the loop not to wait out the limit; a turn that fails again holds it again.
1827
2004
  tryNow: async () => {
1828
2005
  loop.limited = null;
@@ -2487,7 +2664,18 @@ export function register(on) {
2487
2664
  sent: loop.sent,
2488
2665
  asked: turnQuestions,
2489
2666
  read: false,
2667
+ // LOOP-16: what the person said, when the turn was theirs.
2668
+ said: loop.sent ? null : (loop.talk?.text ?? null),
2490
2669
  };
2670
+ // LOOP-17: the lead's last replies, which the check reads.
2671
+ if (e.answer?.trim()) {
2672
+ loop.replies.push({
2673
+ at: await $.clock.now(),
2674
+ text: e.answer.trim().slice(0, 800),
2675
+ label: loop.sent?.label ?? null,
2676
+ });
2677
+ if (loop.replies.length > 3) loop.replies.shift();
2678
+ }
2491
2679
  loop.sent = null;
2492
2680
  $.ui.invalidate('ui.render');
2493
2681
  // LOOP-14: a turn the API failed did nothing; the loop holds until the limit resets.
@@ -2530,6 +2718,8 @@ export function register(on) {
2530
2718
  // LOOP-14: the person tries again themselves; the turn's end says whether the limit still holds.
2531
2719
  loop.limited = null;
2532
2720
  loop.askedAt = { print: null, keys: new Set() };
2721
+ // LOOP-16: what they said, and when, for the reading of the lead's reply to it.
2722
+ loop.talk = { at: await $.clock.now(), text: String(e.text ?? '') };
2533
2723
  }
2534
2724
  return next(e);
2535
2725
  });
@@ -2592,6 +2782,14 @@ export function register(on) {
2592
2782
  laneNotes,
2593
2783
  // LOOP-14: the hold on Claude's usage limit, while it lasts.
2594
2784
  limited: loop.limited && now < loop.limited.until ? loop.limited : null,
2785
+ // LOOP-16: the wait while the person talks with the lead; LOOP-17: the steps not due yet.
2786
+ talking:
2787
+ loop.talking && now < loop.talking.until
2788
+ ? { minutes: harness().loop.quietMinutes, until: loop.talking.until }
2789
+ : null,
2790
+ held: [...loop.held]
2791
+ .filter(([key]) => key !== loop.waiting?.key)
2792
+ .map(([key, x]) => ({ key, label: x.label, why: x.why })),
2595
2793
  now,
2596
2794
  reviews: [...reviews.values()].map((r) => ({
2597
2795
  ...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.32.0",
3
+ "version": "0.34.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",
@@ -55,7 +55,7 @@ For each, read the lane's change request (its report, in `.claude/state/reports/
55
55
 
56
56
  ## 4. The person's requests
57
57
 
58
- A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI, or a weakened test. Check the lane really needs it first: often the story can be done inside the guardrail, and you tell the lane how and drop the request. If it does need it, the request is already waiting for the person, in their band and the pane's Needs you. Add your recommendation with `ask` when the choice isn't obvious from the request alone.
58
+ A request `by: "person"` is a guardrail the lane hit: a spec, a contract, a design, CI, a weakened test, or the running budget. A `cost` request (a commit over the budget, spec 29) is the person's under vibe too, and never goes to them bare: first look for what fits the budget (a smaller size, a cheaper tier or provider, one environment instead of two, a service the story can do without at launch), and send the lane back with it if one does. If none fits, ask them with each option that comes closest, what it gives up and what it saves a month, and the over-budget one with its cost (`code-kit ask … --option …`; under vibe, `--needs payment`). Check the lane really needs it first: often the story can be done inside the guardrail, and you tell the lane how and drop the request. If it does need it, the request is already waiting for the person, in their band and the pane's Needs you. Add your recommendation with `ask` when the choice isn't obvious from the request alone.
59
59
 
60
60
  ## 5. Report
61
61
 
@@ -80,6 +80,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
80
80
  - **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so most stories don't need the session's model. Recommend `story`: each story runs on the model its `**Size:**` in the plan gives (Haiku for small, Sonnet for medium, Opus for large), raised to Opus for a security requirement, to Sonnet at least for a fix, and one step for each time its branch is sent back. Offer one model for every lane (`sonnet`) as the simpler choice, and say the lead, the reviewer and the security reviewer keep their own models either way. A lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "story" } }`, or leave it out for the session's model. A project set up before sizes existed has stories with none, which run on Sonnet until the lead sizes them.
81
81
  - **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their band and the pane's Needs you: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
82
82
  - **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
83
+ - **`cost`, the running budget (spec 29):** from the brief's running budget, or ask the person if it has none: how much a month each environment may cost, in their currency, and the load to plan for. Write `"cost": { "currency": "AUD", "monthly": { "prod": 100, "dev": 20 }, "load": "500 users at launch", "paths": [...] }`. `paths` lists the project's infrastructure files, whatever defines them (Terraform, CDK, Pulumi, Serverless, SST, Docker Compose, Kubernetes or Helm, `fly.toml`, `vercel.json`, `netlify.toml`, `render.yaml`, `wrangler.toml`, `supabase/config.toml`, an `infra/` folder); a branch that changes one has to say in the register what that costs. Set `docs.costs` only if the register isn't `docs/costs.md`. The register is written by any agent (a lane costs the infrastructure its story adds), and a commit that takes an environment past its budget waits for the person's `cost` approval, whatever the config delegates. Show the budget with the rest of the setup.
83
84
  - **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
84
85
 
85
86
  ### Standards (spec 22)
@@ -184,6 +185,7 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
184
185
  - the security reviewer (`.claude/agents/security-reviewer.md`), unless the product handles no sign-in, personal data, payments, outside input or secrets; and, as a proposal for the person, a threat model and security requirements for each spec that lacks them (spec-design's section 4);
185
186
  - `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
186
187
  - project standards, when the project has no `docs/standards.md`: suggest them as section 2's Standards describes, moving the engineering rules out of `docs/principles.md`, and protect the file.
188
+ - a running budget, when the config has no `cost` (whatever its `setup`): ask the person for it as section 2 describes. Then cost what's already defined in the infrastructure files, or deployed, into `docs/costs.md`, a row per paid thing at its real size, and run `code-kit cost`. When it's over the budget, bring the person options that fit (spec-design's architecture step lists the kinds), each with what it gives up and what it saves a month, and record their choice in the brief's decision log; the stories that bring it within budget go in the plan.
187
189
  3. **Show the difference:**
188
190
 
189
191
  ```bash
@@ -58,6 +58,7 @@ Read the story and every requirement it cites. Then start from what's already be
58
58
  It's refused when the screenshot isn't a PNG at the design's viewport (1x to 4x); take it again at that size. `verify`, and the merge queue, report every approved state of the branch's screens with no screenshot recorded since the screen last changed, so a branch that moves after your review is compared again. A state the build can't serve yet (the contract has no field for what the design shows) goes in the report with what's missing, and you add the story that provides it, rather than leaving a gap nobody sees.
59
59
 
60
60
  - **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
61
+ - **Running cost (spec 29):** where the config has a budget, a branch that changes the infrastructure files (`cost.paths`) changes `docs/costs.md` too (verify fails it otherwise). Read the two together: the size, tier and count in the code are the ones in the register's rows, every new paid thing has a row, and the estimate is for the load the spec gives, not a provider's production default. A mismatch sends the branch back, naming the file and the row. `code-kit cost` shows the totals against the budget and the prices to recheck.
61
62
  - **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
62
63
 
63
64
  ## 4. The security review
@@ -51,6 +51,7 @@ Get the problem straight before any solution:
51
51
  - **Users:** each kind of user or actor, including admins, other systems and scheduled jobs, and what each is trying to get done.
52
52
  - **Outcome:** what's different when this works, and how anyone will know. Prefer something observable ("a new customer books without calling us") over a feature list.
53
53
  - **Why now, and constraints:** deadline, budget, team, required platforms and technology, regulation and data residency, existing systems it must fit.
54
+ - **Running budget (spec 29):** how much a month the person will spend running it (hosting, databases, queues, outside services), for each environment they'll have (production at least; dev or staging only if they'll run), in their currency, and the load to plan for at launch (users, requests, data). 0 is a real answer: free tiers only. It shapes the architecture as much as any requirement, so ask it in the first round, and record it in the brief.
54
55
  - **Non-goals:** what this deliberately won't do. Ask for them; they are as useful as the goals.
55
56
 
56
57
  Write `docs/brief.md` as soon as the frame is agreed, with `Status: framed`, and keep it current from then on.
@@ -107,7 +108,9 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
107
108
  - how the quality targets from phase 3 are met;
108
109
  - **recipes**: under `## Recipes`, a `### <recipe-name>` for each layer's common addition (a new screen, endpoint, migration, domain service, job): the steps in order, the files each step creates or changes, and how it's tested. Each becomes a project skill when init sets up the lanes, so every lane agent builds the same thing the same way;
109
110
  - the **design tool** for screens, when there are any: the one the person uses (Paper, Figma, Pencil), or design files under `design/` when they have none.
111
+ - the **running cost** of each shape you propose (spec 29): every paid thing (a database, a container, a function's invocations, a queue, a domain, an outside API), its provider, the size or tier, and its monthly estimate at the expected load, per environment, from the provider's published pricing, with the page and the date you read it. Size for the load the brief gives, not for a provider's production default: one small instance before a cluster, a free or starter tier before a dedicated one, managed services that scale to zero before ones that run all the time, no standby, NAT gateway or second region unless a quality target needs it. At least one shape fits the budget. When the one the person prefers doesn't, say by how much, and offer options that fit (a smaller size, a cheaper tier or provider, one environment instead of two, a service the product can do without at launch, less scope), each with what it gives up; the person picks.
110
112
  Propose the architecture from the specs and constraints, explain the choices, and ask about the ones that matter. Record each in the decision log.
113
+ - **`docs/costs.md`:** the chosen shape's costs, one table whose header is `| Item | Provider | Environment | Size | Monthly | Basis |`: a row per paid thing; Environment one the budget names, or `all`; Monthly a plain number in the budget's currency; Basis the pricing page and the date (YYYY-MM-DD). `code-kit cost` adds it up once init has written the budget. Write it before the plan: a design over the budget isn't planned.
111
114
  - **`docs/standards.md`:** the engineering rules, each a `### <id> <title>` heading with `level` (required or recommended), `applied` (enforced, checked or advice), `layers`, `why` and `source` lines, the id's prefix its category: `PRI-` principles, `PAT-` patterns, `ARC-` architecture, `CON-` conventions, `POL-` policies. Draw them from the architecture (an `ARC-` standard for each layer rule, `enforced by: layers (<layer> may not import <layer>)`), the threat models (a `POL-` standard for what must never happen to sensitive data), and the decisions; cite each one's source. Propose them and ask about each: a standard is a guardrail, so the person decides it. Init checks the file and protects it.
112
115
  - **`docs/principles.md`:** the privacy and data residency targets from the brief (where data may be stored and processed, what is never logged), which the security reviewer checks against; what counts as a contract; the definition of done (tests, checks, reviews, end-to-end working features); the test, lint, typecheck and database commands once they're known; and which commands only CI or a person may run, such as deploys.
113
116
  - **`docs/plan.md`**, from `${CLAUDE_PLUGIN_ROOT}/templates/plan.md`:
@@ -26,6 +26,7 @@ Always:
26
26
  - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
27
27
  - 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
28
  - 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.
29
+ - {{if cost}}The project has a running budget. When you add, remove or resize anything that costs money to run (a database, a container, a function, a queue, an outside service, a plan tier), change its row in `{{docs.costs}}` in the same branch: the item, provider, environment, size, its monthly estimate as a number, and the pricing page and date you read it. Size it for the load the spec gives, not the provider's production default. A branch that changes the infrastructure files without the register fails verify. If your commit is refused for going over the budget, don't look for a way round it: hand the lead a change request with what you need, what it costs a month, and the options that fit, each with what it gives up.{{end}}
29
30
  - Build every feature end to end. No mocks, stubs, placeholder screens or "coming soon".
30
31
  - A screen is built to its approved design: the brief names every state's image and code under `design/`. Read each before you write the screen, match its layout, copy, spacing and states, and build it from the project's components rather than pasting the export. Your report lists each state with what you built for it.
31
32
  - Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.
@@ -15,6 +15,8 @@ The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file
15
15
 
16
16
  {{if vibe}}Product and UX are yours: what the spec leaves open, a screen's visual design, the wording, what to build next. Answer from the brief, the specs and the principles, and record each product decision in the brief's decision log with why. Build everything that doesn't need the person, and stop only for what nobody else can give: an account with a service provider, an API key or secret from one, a payment, or an act outside the repository (DNS, an app store). Ask for it with `code-kit ask "<what you need, and what it's for>" --needs account|key|payment|outside` (`--story ST-n --blocks` holds the story until they answer), and carry on with everything else meanwhile, against a local or test stand-in where there is one. Lanes don't ask the person: they write the question for the lead.{{end}}
17
17
 
18
+ {{if cost}}The project has a running budget the person set, per environment, and `{{docs.costs}}` estimates what each paid thing costs a month; `code-kit cost` adds it up against the budget. Design and review to it: size each service for the load the spec gives, not a provider's production default. In review, check a branch that changes the infrastructure against its register rows: the size in the code is the size in the row, and every new paid thing has one; send it back otherwise. Going past the budget is always the person's call, under vibe too: a commit that does is refused until they approve `cost`. Before asking, find options that fit (a smaller size, a cheaper tier or provider, fewer environments, less at launch), and ask with `code-kit ask "<what's over, and by how much>" --option "<option>: <what it gives up, what it saves a month>"`, the over-budget choice among them (under vibe, with `--needs payment`).{{end}}
19
+
18
20
  {{if standards.all}}The project's standards, in `{{docs.standards}}`: {{standards.all}}. Each lane is given the ones for its layers. In review, check each changed file against the checked standards for its layer (`code-kit standards --for <file>`): a broken required one sends the branch back, naming the standard; a broken recommended one is a concern, and advice at most a nit. Adding a recommended standard may be yours where the config delegates the `standards` approval; removing one, or weakening a required one, is always the person's.{{end}}
19
21
 
20
22
  - {{if harness.report.on}}When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.{{end}}