@warren-dean/code-kit 0.28.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.
Files changed (41) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHANGELOG.md +31 -0
  4. package/README.md +17 -9
  5. package/bin/code-kit.mjs +498 -60
  6. package/hooks/act.mjs +30 -2
  7. package/hooks/guard-bash.mjs +59 -25
  8. package/hooks/lib/adapters/hub/client.mjs +7 -1
  9. package/hooks/lib/checkout.mjs +78 -1
  10. package/hooks/lib/checks.mjs +13 -3
  11. package/hooks/lib/deferrals.mjs +107 -0
  12. package/hooks/lib/designs.mjs +100 -42
  13. package/hooks/lib/events.mjs +49 -0
  14. package/hooks/lib/instructions.mjs +1 -1
  15. package/hooks/lib/next.mjs +124 -15
  16. package/hooks/lib/plan.mjs +186 -11
  17. package/hooks/lib/queue.mjs +61 -12
  18. package/hooks/lib/regression.mjs +18 -11
  19. package/hooks/lib/reviews.mjs +43 -2
  20. package/hooks/lib/rules.mjs +11 -2
  21. package/hooks/lib/security.mjs +50 -7
  22. package/hooks/lib/shell.mjs +97 -0
  23. package/hooks/lib/snapshot.mjs +125 -8
  24. package/hooks/lib/storymap.mjs +13 -7
  25. package/hooks/lib/team.mjs +35 -13
  26. package/hooks/lib/teamfacts.mjs +80 -2
  27. package/hooks/lib/testfiles.mjs +22 -0
  28. package/hooks/lib/verify.mjs +55 -11
  29. package/hooks/lib/worktrees.mjs +25 -3
  30. package/hooks/mod/board.mjs +12 -1
  31. package/hooks/mod/loop.mjs +9 -2
  32. package/hooks/mod/register.mjs +4 -3
  33. package/hooks/mod/view.mjs +51 -11
  34. package/package.json +1 -1
  35. package/skills/design/SKILL.md +4 -4
  36. package/skills/dispatch/SKILL.md +1 -1
  37. package/skills/init/SKILL.md +5 -0
  38. package/skills/next/SKILL.md +1 -0
  39. package/skills/review/SKILL.md +12 -4
  40. package/templates/agent.md +2 -1
  41. package/templates/claude-md.md +2 -0
package/bin/code-kit.mjs CHANGED
@@ -16,6 +16,8 @@
16
16
  // trace <path> [--json] what a file is for: the requirements it delivers, its lane, its layer rules
17
17
  // designs [<story>] [--json] the approved designs from the register: a story's screens' design files,
18
18
  // every state, for the lane's brief; or every entry and what's wrong with it
19
+ // designs evidence <story> <screen file or name> <state> <screenshot.png>
20
+ // the review records its screenshot of a built state beside its design (HAND-7)
19
21
  // next [--base ref] [--json]
20
22
  // the step to take now (spec-design, init, dispatch, review…), from the project's state
21
23
  // approve <name>... --reason "…" [--lane name]
@@ -51,6 +53,10 @@
51
53
  // ci check [--json] | ci usage [--days N] [--json]
52
54
  // what the project's CI spends and what multiplies it (spec 25)
53
55
  // release <version> cut release/<version> from the base and push it: the full CI runs there
56
+ // queue pause --reason "…" | queue resume
57
+ // the lead holds the whole merge queue on purpose, and lets it go (MQ-8)
58
+ // defer <story>... --reason "…" [--until <date|ISO time>] | defer release <story>... | defer [--json]
59
+ // stories the lead holds on purpose: not dispatched, reviewed or merged (LOOP-15)
54
60
  // --config <file> reads a draft (.claude/code-kit.draft.json) instead of .claude/code-kit.json.
55
61
  import { execFileSync, spawnSync } from 'node:child_process';
56
62
  import {
@@ -103,13 +109,16 @@ import {
103
109
  import { traceFile } from '../hooks/lib/trace.mjs';
104
110
  import { buildStatus, readStories, specCheckRows } from '../hooks/lib/plan.mjs';
105
111
  import {
112
+ atViewport,
106
113
  designsFor,
107
114
  entryProblems,
108
115
  handedOver,
116
+ pngSize,
109
117
  readRegister,
118
+ sha256Of,
110
119
  toolOf,
111
120
  } from '../hooks/lib/designs.mjs';
112
- import { recordSentBack } from '../hooks/lib/reviews.mjs';
121
+ import { evidenceDir, recordEvidence, recordSentBack } from '../hooks/lib/reviews.mjs';
113
122
  import {
114
123
  SECURITY_AGENT,
115
124
  SECURITY_AGENT_FILE,
@@ -134,7 +143,10 @@ import {
134
143
  mergingNow,
135
144
  nextToMerge,
136
145
  setPartners,
146
+ pauseQueue,
147
+ queuePause,
137
148
  readQueue,
149
+ resumeQueue,
138
150
  settle,
139
151
  waiting,
140
152
  } from '../hooks/lib/queue.mjs';
@@ -150,6 +162,7 @@ import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/har
150
162
  import { claimLead, readLoop, releaseLead, writeLoop } from '../hooks/lib/loop-state.mjs';
151
163
  import {
152
164
  claimChanges,
165
+ isIntentId,
153
166
  storyOfBranch,
154
167
  syncBoard,
155
168
  readCache,
@@ -158,7 +171,14 @@ import {
158
171
  teamProvider,
159
172
  whoami,
160
173
  } from '../hooks/lib/team.mjs';
161
- import { codeowners, decisionRecord, slugOf } from '../hooks/lib/teamfacts.mjs';
174
+ import {
175
+ codeowners,
176
+ decisionRecord,
177
+ driftHoldWords,
178
+ driftHolds,
179
+ driftUnchecked,
180
+ slugOf,
181
+ } from '../hooks/lib/teamfacts.mjs';
162
182
  import {
163
183
  APPROVAL_MINUTES,
164
184
  approvalLifetime,
@@ -185,7 +205,14 @@ import {
185
205
  import { heldTo, laneOfBranch, verifyBranch } from '../hooks/lib/verify.mjs';
186
206
  import { skippedLine } from '../hooks/lib/checks.mjs';
187
207
  import { TESTS_APPROVAL } from '../hooks/lib/regression.mjs';
188
- import { freshCheckout } from '../hooks/lib/checkout.mjs';
208
+ import { freshCheckout, matchInstalls } from '../hooks/lib/checkout.mjs';
209
+ import {
210
+ activeDeferrals,
211
+ deferStories,
212
+ deferralWords,
213
+ parseUntil,
214
+ releaseStories,
215
+ } from '../hooks/lib/deferrals.mjs';
189
216
  import { laneClaim, laneClaims, releaseLane, shortSession } from '../hooks/lib/laneclaims.mjs';
190
217
  import { slicesOf } from '../hooks/lib/schedule.mjs';
191
218
  import {
@@ -255,6 +282,7 @@ const actGiven = option('--act');
255
282
  const foundGiven = option('--found');
256
283
  const howGiven = option('--how');
257
284
  const leaseGiven = option('--lease');
285
+ const intentGiven = option('--intent');
258
286
  const touchesGiven = option('--touches');
259
287
  const techLeadGiven = option('--tech-lead');
260
288
  const staleDaysGiven = option('--stale-days');
@@ -265,6 +293,7 @@ const storyGiven = option('--story');
265
293
  const whyGiven = option('--why');
266
294
  const whatGiven = option('--what');
267
295
  const withGiven = option('--with');
296
+ const untilGiven = option('--until');
268
297
  const expectedGiven = option('--expected');
269
298
  const commandGiven = option('--command');
270
299
  const refusalGiven = option('--refusal');
@@ -540,6 +569,7 @@ const VERIFY_GROUPS = {
540
569
  layers: 'Layer rules',
541
570
  baseline: 'Baseline',
542
571
  design: 'Designs before screens',
572
+ evidence: 'Builds compared with their designs',
543
573
  tests: 'Weakened tests',
544
574
  regression: 'Fixes and their tests',
545
575
  standards: 'Standards',
@@ -683,7 +713,7 @@ function publishAfter(config, byPerson) {
683
713
  const mode = target.branches.publish;
684
714
  if (!mode) return '';
685
715
  const mayMove = byPerson || target.approvals.delegate?.push === true;
686
- return ` ${publishBase(resolve('.'), into, { mode, mayMove }).message}`;
716
+ return ` ${publishBase(mainCheckout(resolve('.')), into, { mode, mayMove }).message}`;
687
717
  }
688
718
 
689
719
  /** `publish --delegated|--person`: publishes what's merged and not yet on the remote, as a merge does. */
@@ -698,17 +728,47 @@ function publish() {
698
728
  out(publishAfter(config, byPerson).trim());
699
729
  }
700
730
 
731
+ /**
732
+ * HUBR-9: the team provider's word on drift for `branches`: which its open findings hold (`holds`,
733
+ * Map(branch → findings)), why in words (`words(branch, findings)`), and `note`, that nothing was
734
+ * checked, when it didn't answer. `fresh` asks it now, as a merge does; otherwise its state as last read,
735
+ * as the queue's list and `next` do. GitHub's provider checks no drift, so it's never asked.
736
+ */
737
+ function driftNow(config, branches, { fresh = false } = {}) {
738
+ const none = { holds: new Map(), note: null, words: () => '' };
739
+ const team = teamOf(config);
740
+ if (!team || team.provider === 'github' || !branches.length) return none;
741
+ const root = resolve('.');
742
+ const state = fresh ? teamProvider(root, team).state({ fresh: true }) : readCache(root);
743
+ if (!state && !fresh) return none;
744
+ return {
745
+ holds: driftHolds(state, branches),
746
+ note: driftUnchecked(state),
747
+ words: (branch, findings) =>
748
+ driftHoldWords(branch, findings, {
749
+ techLead: team.techLead,
750
+ provider: state?.provider?.name ?? team.provider.name ?? null,
751
+ }),
752
+ };
753
+ }
754
+
701
755
  function merge(branch) {
702
756
  const { config } = load();
703
757
  const byPerson = mergeMode();
758
+ const drift = driftNow(config, [branch], { fresh: true });
759
+ const findings = drift.holds.get(branch);
760
+ if (findings) die(`Nothing was merged. ${drift.words(branch, findings)}`);
761
+ const root = mainCheckout(resolve('.'));
704
762
  try {
705
763
  const { message } = mergeOne(branch, config, byPerson);
706
764
  // A branch merged outside the queue leaves it too, as one the queue merged would.
707
- settle(resolve('.'), branch, 'merged');
708
- out(`${message}${publishAfter(config, byPerson)}`);
765
+ settle(root, branch, 'merged');
766
+ out(`${message}${publishAfter(config, byPerson)}${drift.note ? ` ${drift.note}` : ''}`);
709
767
  } catch (e) {
710
- if (e instanceof MergeStop) die(e.message);
711
- throw e;
768
+ if (!(e instanceof MergeStop)) throw e;
769
+ if (e.kind !== 'already') die(e.message);
770
+ settle(root, branch, 'merged', 'already in the base');
771
+ out(e.message);
712
772
  }
713
773
  }
714
774
 
@@ -733,9 +793,15 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
733
793
  if (!target.branches.protected.includes(into))
734
794
  refuse(`${into} isn't a protected branch; merge into it with git.`);
735
795
  if (target.branches.protected.includes(branch)) refuse(`${branch} is itself a protected branch.`);
736
- const root = resolve('.');
796
+ // The main checkout, found once, before anything is removed: a merge run from inside the lane's own
797
+ // worktree must still reach the project's state when that worktree is done with.
798
+ const root = mainCheckout(resolve('.'));
737
799
  const g = (cwd, ...a) =>
738
- execFileSync('git', ['-C', cwd, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
800
+ execFileSync('git', ['-C', cwd, ...a], {
801
+ encoding: 'utf8',
802
+ stdio: ['ignore', 'pipe', 'pipe'],
803
+ maxBuffer: 64 * 1024 * 1024,
804
+ });
739
805
  try {
740
806
  g(root, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`);
741
807
  } catch {
@@ -746,10 +812,31 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
746
812
  .split('\n\n')
747
813
  .map((w) => ({ path: w.match(/^worktree (.+)$/m)?.[1], ref: w.match(/^branch (.+)$/m)?.[1] }))
748
814
  .find((w) => w.ref === `refs/heads/${b}`)?.path;
749
- const clean = (dir, b) => {
750
- if (g(dir, 'status', '--porcelain', '--untracked-files=no').trim())
751
- fail(`${b} has uncommitted changes in ${dir}; commit or stash them first.`);
815
+ const contains = (ref, commit) =>
816
+ spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', commit, ref]).status === 0;
817
+ // What a checkout holds uncommitted, tracked or not: each path, a rename's both.
818
+ const uncommitted = (dir) => {
819
+ const parts = g(dir, 'status', '--porcelain=v1', '-z', '--untracked-files=all').split('\0');
820
+ const paths = [];
821
+ for (let i = 0; i < parts.length; i++) {
822
+ if (!parts[i]) continue;
823
+ paths.push(parts[i].slice(3));
824
+ if (/^[RC]/.test(parts[i])) paths.push(parts[++i]);
825
+ }
826
+ return paths;
827
+ };
828
+ // MQ-1: only what the merge changes has to be committed in the base's checkout: git carries every other
829
+ // change, which tools sharing the checkout (a log a tool appends to each turn) make at any time.
830
+ const inTheWay = (dir, tips) => {
831
+ const lands = new Set(
832
+ tips.flatMap((t) =>
833
+ g(dir, 'diff', '--name-only', '--no-renames', `HEAD...${t}`).split('\n').filter(Boolean),
834
+ ),
835
+ );
836
+ return uncommitted(dir).filter((f) => lands.has(f));
752
837
  };
838
+ const dirtyWords = (dir, files) =>
839
+ `Nothing was merged: ${into}'s checkout (${dir}) has uncommitted changes to ${files.length === 1 ? 'a file' : 'files'} this merge changes (${files.slice(0, 5).join(', ')}${files.length > 5 ? `, and ${files.length - 5} more` : ''}). Commit or stash ${files.length === 1 ? 'it' : 'them'} there, then merge again; changes to other files are carried as they are.`;
753
840
  const temporary = [];
754
841
  // A stop is thrown at once, so every way out of here removes the temporary worktrees first.
755
842
  const cleanup = () => {
@@ -783,14 +870,31 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
783
870
  `Nothing was merged: ${branch} has moved on since its review passed (${commit.slice(0, 7)} → ${tip.slice(0, 7)}). Review it again, then queue it.`,
784
871
  'moved',
785
872
  );
873
+ // A branch whose commit the base already holds has nothing left to merge: it isn't verified again
874
+ // (against the base it's an empty change, which says nothing) and never sent back.
875
+ if (contains(into, tip))
876
+ fail(
877
+ `${branch} is already merged into ${into}: ${into} holds its commit ${tip.slice(0, 7)}, so there's nothing of it left to merge.`,
878
+ 'already',
879
+ );
786
880
  // MQ-1: verified as it will land: the branch merged with the base as it is now, in a fresh checkout
787
- // with its own copy of the installs (the branch's worktree's, else the main checkout's), so neither
788
- // a stale branch head nor a checkout without dependencies decides it.
881
+ // with its own copy of the installs. They're the base's checkout's (the main checkout's), which match
882
+ // the base; where the merged tree's manifests or lockfiles differ from them, the install runs there.
883
+ // A branch's worktree can be far behind the base, or have no installs at all.
884
+ const baseCheckout = checkedOut(into);
885
+ const installsFrom = baseCheckout ?? root;
886
+ if (baseCheckout) {
887
+ const blocking = inTheWay(baseCheckout, [
888
+ tip,
889
+ ...partners.map((p) => `refs/heads/${p.branch}`),
890
+ ]);
891
+ if (blocking.length) fail(dirtyWords(baseCheckout, blocking));
892
+ }
789
893
  let fresh;
790
894
  try {
791
895
  fresh = freshCheckout(root, into, {
792
896
  merge: tip,
793
- installsFrom: checkedOut(branch) ?? root,
897
+ installsFrom,
794
898
  prefix: 'code-kit-merge-',
795
899
  });
796
900
  } catch (e) {
@@ -802,29 +906,47 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
802
906
  }
803
907
  temporary.push(fresh);
804
908
  const verifyIn = fresh.dir;
805
- // MQ-7: a group lands as one: its partners merged into the same tree, which the checks run on.
806
- const members = partners.map((p) => ({
807
- ...p,
808
- tip: g(root, 'rev-parse', `refs/heads/${p.branch}`).trim(),
809
- }));
810
- for (const m of members) {
811
- const merged = spawnSync(
909
+ // MQ-7: a group lands as one: its partners merged into the same tree, which the checks run on. A
910
+ // partner the base already holds has nothing left to merge.
911
+ const members = partners
912
+ .map((p) => ({ ...p, tip: g(root, 'rev-parse', `refs/heads/${p.branch}`).trim() }))
913
+ .filter((m) => !contains(into, m.tip));
914
+ const mergeInto = (dir, ref) =>
915
+ spawnSync(
812
916
  'git',
813
- ['-C', verifyIn, '-c', 'user.name=code-kit', '-c', 'user.email=code-kit@localhost'].concat([
917
+ ['-C', dir, '-c', 'user.name=code-kit', '-c', 'user.email=code-kit@localhost'].concat([
814
918
  'merge',
815
919
  '--no-ff',
816
920
  '--no-edit',
817
921
  '--quiet',
818
- m.tip,
922
+ ref,
819
923
  ]),
820
924
  { encoding: 'utf8' },
821
925
  );
926
+ for (const m of members) {
927
+ const merged = mergeInto(verifyIn, m.tip);
822
928
  if (merged.status !== 0)
823
929
  fail(
824
- `Nothing was merged: ${m.branch} doesn't merge cleanly with ${branch} on ${into}. Merge one into the other and resolve it there, then merge again.\n${`${merged.stdout}${merged.stderr}`.trim()}`,
930
+ `Nothing was merged: ${m.branch} doesn't merge cleanly with ${branch} on ${into}. Merge one into the other and resolve it there, then merge again.\n${`${merged.stdout ?? ''}${merged.stderr ?? ''}`.trim()}`,
825
931
  'conflict',
826
932
  );
827
933
  }
934
+ // MQ-1: the checks run with installs that match the merged tree, and say whose they were.
935
+ const installs = matchInstalls(verifyIn, installsFrom, { prepare: config.regression?.prepare });
936
+ const installedWith = installs.command
937
+ ? `installed with \`${installs.command}\` in the merged tree, since ${installs.differ.length ? `its ${installs.differ.join(', ')} differ${installs.differ.length === 1 ? 's' : ''} from ${installsFrom}'s` : `${installsFrom} had nothing installed`}`
938
+ : installs.differ.length
939
+ ? `with the installs of ${installsFrom}, which may not match: the merged tree's ${installs.differ.join(', ')} differ${installs.differ.length === 1 ? 's' : ''} from its, and code-kit knows no install for them (set regression.prepare to the command that installs, and the queue runs it there)`
940
+ : installs.copied
941
+ ? `with the installs of ${installsFrom}`
942
+ : installs.lockfile
943
+ ? `with no installs, since ${installsFrom} has none: install there, and the queue copies them`
944
+ : null;
945
+ if (installs.failed)
946
+ fail(
947
+ `Nothing was merged: the merged tree's checks need its own installs (${installs.differ.length ? `its ${installs.differ.join(', ')} differ from ${installsFrom}'s` : `${installsFrom} has nothing installed`}), and \`${installs.command}\` ${installs.failed.missing ? "isn't installed here" : 'failed'} in ${verifyIn}${installs.failed.output ? `:\n${installs.failed.output}` : '.'}\nThat says nothing against ${branch}, so it keeps its place in the queue. Make the install work (or set regression.prepare to the command that installs), then merge again.`,
948
+ 'installs',
949
+ );
828
950
  const lane = members.length ? null : laneOfBranch(branch, config);
829
951
  const { changed, found, skipped, unfinished } = verifyBranch({
830
952
  root: verifyIn,
@@ -834,13 +956,29 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
834
956
  checks: true,
835
957
  branch,
836
958
  });
837
- // Each member is still held to its own lane's paths, on its own tree.
959
+ // MQ-7: each member is still held to its own lane's paths, for its own changes alone: measured against
960
+ // the base merged with its partners, so a lane's branch built on its lead partner's (as dispatch has
961
+ // it) isn't held to the partner's files. A partner built on this member already holds the member's
962
+ // commits, so it's left out of the member's base, which would otherwise show no change at all.
838
963
  for (const b of members.length ? [{ branch, tip }, ...members] : []) {
839
- const own = freshCheckout(root, into, { merge: b.tip, prefix: 'code-kit-merge-' });
964
+ const own = freshCheckout(root, into, { prefix: 'code-kit-merge-' });
840
965
  temporary.push(own);
966
+ const others = [{ branch, tip }, ...members].filter(
967
+ (x) => x.branch !== b.branch && !contains(x.tip, b.tip),
968
+ );
969
+ for (const o of others) {
970
+ const merged = mergeInto(own.dir, o.tip);
971
+ if (merged.status !== 0)
972
+ fail(
973
+ `Nothing was merged: ${o.branch} doesn't merge cleanly with ${b.branch}'s partners on ${into}. Merge one into the other and resolve it there, then merge again.\n${`${merged.stdout ?? ''}${merged.stderr ?? ''}`.trim()}`,
974
+ 'conflict',
975
+ );
976
+ }
977
+ const withPartners = g(own.dir, 'rev-parse', 'HEAD').trim();
978
+ g(own.dir, 'checkout', '--quiet', '--detach', b.tip);
841
979
  const held = verifyBranch({
842
980
  root: own.dir,
843
- base: into,
981
+ base: withPartners,
844
982
  config,
845
983
  lane: laneOfBranch(b.branch, config),
846
984
  checks: false,
@@ -860,17 +998,19 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
860
998
  // #62: a check that only ran out of time says nothing against the branch: it's tried again.
861
999
  if (problems.length === 1 && unfinished)
862
1000
  fail(
863
- `Nothing was merged: a check on ${branch} didn't finish, which says nothing against the branch (checked in ${verifyIn}):\n ${problems[0]}\nIt stays at the head of the queue; merge again once fewer suites are running.`,
1001
+ `Nothing was merged: a check on ${branch} didn't finish, which says nothing against the branch (checked in ${verifyIn}${installedWith ? `, ${installedWith}` : ''}):\n ${problems[0]}\nIt stays at the head of the queue; merge again once fewer suites are running.`,
864
1002
  'unfinished',
865
1003
  );
866
1004
  if (problems.length)
867
1005
  fail(
868
- `Nothing was merged. code-kit verify found ${problems.length} problem(s) on ${branch} (checked in ${verifyIn}):\n ${problems.join('\n ')}\nSend it back to its lane, or fix it, then merge again.`,
1006
+ `Nothing was merged. code-kit verify found ${problems.length} problem(s) on ${branch} (checked in ${verifyIn}${installedWith ? `, ${installedWith}` : ''}):\n ${problems.join('\n ')}\nSend it back to its lane, or fix it, then merge again.`,
869
1007
  'verify',
870
1008
  problems[0].split('\n')[0],
871
1009
  );
872
1010
  const mergeIn = checkedOut(into) ?? worktree(into, false);
873
- clean(mergeIn, into);
1011
+ // Checked again now the verify is done: only changes to what the merge changes stop it.
1012
+ const blocking = inTheWay(mergeIn, [tip, ...members.map((m) => m.tip)]);
1013
+ if (blocking.length) fail(dirtyWords(mergeIn, blocking));
874
1014
  const before = g(mergeIn, 'rev-parse', 'HEAD').trim();
875
1015
  const together = members.length
876
1016
  ? ` together with ${members.map((m) => m.branch).join(', ')} (MQ-7)`
@@ -906,7 +1046,7 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
906
1046
  const stories = [branch, ...members.map((m) => m.branch)].map(storyOfBranch).filter(Boolean);
907
1047
  let unreleased = '';
908
1048
  if (team) {
909
- const provider = teamProvider(resolve('.'), team);
1049
+ const provider = teamProvider(root, team);
910
1050
  for (const story of stories) {
911
1051
  const left = provider.release(story, { merged: true });
912
1052
  if (!left?.ok)
@@ -915,20 +1055,50 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
915
1055
  for (const s of mergedClaims(root, provider.state()?.claims ?? [], into))
916
1056
  if (!stories.includes(s)) provider.release(s, { merged: true });
917
1057
  }
918
- // LEAN-8: the merged branch's worktree, and any other that's done with, go now.
919
- const pruned = pruneWorktrees(root, config).removed;
920
- const removed = pruned.length
921
- ? ` Removed ${pruned.length} worktree${pruned.length === 1 ? '' : 's'} that ${pruned.length === 1 ? 'was' : 'were'} done with.`
922
- : '';
1058
+ // LEAN-8: the merged branch's worktree, and any other that's done with, go now; not the one this
1059
+ // command runs in, which would leave its shell in a folder that's gone.
1060
+ const { removed: pruned, kept } = pruneWorktrees(root, config);
1061
+ const here = kept.find((k) => k.here);
1062
+ const removed = `${
1063
+ pruned.length
1064
+ ? ` Removed ${pruned.length} worktree${pruned.length === 1 ? '' : 's'} that ${pruned.length === 1 ? 'was' : 'were'} done with.`
1065
+ : ''
1066
+ }${here?.merged ? ` Kept ${here.label}'s worktree, since this command runs in it: it goes at the next merge.` : ''}`;
923
1067
  return {
924
1068
  into,
925
- message: `Merged ${branch}${together} into ${into}: verify passed on ${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}, at ${tip.slice(0, 7)}.${skipped.length ? ` ${notRun(skipped)}` : ''}${removed}${unreleased}`,
1069
+ message: `Merged ${branch}${together} into ${into}: verify passed on ${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}, at ${tip.slice(0, 7)}${installs.command ? `, ${installedWith}` : ''}.${skipped.length ? ` ${notRun(skipped)}` : ''}${removed}${unreleased}`,
926
1070
  };
927
1071
  } finally {
928
1072
  cleanup();
929
1073
  }
930
1074
  }
931
1075
 
1076
+ /** A local branch's commit, or null when there's no such branch. */
1077
+ function branchTip(branch) {
1078
+ try {
1079
+ return execFileSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], {
1080
+ encoding: 'utf8',
1081
+ stdio: ['ignore', 'pipe', 'ignore'],
1082
+ }).trim();
1083
+ } catch {
1084
+ return null;
1085
+ }
1086
+ }
1087
+
1088
+ /** LOOP-15: the branches of the stories the lead holds now, Map(branch → hold), by the plan's branch names. */
1089
+ function heldBranches(root, config) {
1090
+ const holds = activeDeferrals(root);
1091
+ if (!holds.length) return new Map();
1092
+ const byBranch = new Map();
1093
+ const branches = waiting(readQueue(root)).map((e) => e.branch);
1094
+ for (const b of branches) {
1095
+ const story = storyOfBranch(b);
1096
+ const hold = story && holds.find((h) => h.story === story.toUpperCase());
1097
+ if (hold) byBranch.set(b, hold);
1098
+ }
1099
+ return byBranch;
1100
+ }
1101
+
932
1102
  /**
933
1103
  * The merge queue (spec 09): `queue` lists it; `queue add <branch>` puts a branch the lead's review
934
1104
  * passed at the back; `queue drop <branch>` takes one out; `queue merge --delegated|--person` merges
@@ -937,8 +1107,31 @@ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
937
1107
  */
938
1108
  function queue() {
939
1109
  const { config } = load();
940
- const root = resolve('.');
1110
+ // The main checkout, where the queue is kept, found once: a merge run from inside a lane's worktree
1111
+ // must still reach the queue once that worktree is done with.
1112
+ const root = mainCheckout(resolve('.'));
1113
+ const into = intoName ?? config.branches.protected[0];
941
1114
  const [sub, branch] = rest;
1115
+ // MQ-8: the lead pauses the whole queue on purpose, with why; branches are still queued meanwhile.
1116
+ if (sub === 'pause') {
1117
+ if (!reason?.trim())
1118
+ die(
1119
+ 'code-kit queue pause --reason "…": say why the queue waits, so the person and the band can see it.',
1120
+ );
1121
+ const was = queuePause(root);
1122
+ pauseQueue(root, reason.trim(), callerSession);
1123
+ return out(
1124
+ `${was ? 'The merge queue stays paused, now' : 'Paused the merge queue'}: ${reason.trim()}. Nothing merges, and nothing offers a merge, until code-kit queue resume.`,
1125
+ );
1126
+ }
1127
+ if (sub === 'resume') {
1128
+ const was = resumeQueue(root);
1129
+ return out(
1130
+ was
1131
+ ? `The merge queue merges again (it was paused: ${was.reason}).`
1132
+ : "The merge queue wasn't paused.",
1133
+ );
1134
+ }
942
1135
  if (sub === 'add' || sub === 'drop') {
943
1136
  if (!branch) die(`code-kit queue ${sub} <branch>`);
944
1137
  if (sub === 'drop')
@@ -981,14 +1174,56 @@ function queue() {
981
1174
  if (sub === 'rules') return rulesOntoBase(root, config);
982
1175
  if (sub === 'merge') {
983
1176
  const byPerson = mergeMode();
1177
+ const paused = queuePause(root);
1178
+ if (paused)
1179
+ return out(
1180
+ `The merge queue is paused (${paused.reason}, since ${paused.at.slice(0, 16).replace('T', ' ')}): nothing was merged. code-kit queue resume lets it merge again.`,
1181
+ );
1182
+ // A queued branch whose commit the base already holds (merged outside the queue, or by a run that
1183
+ // couldn't record it) is settled as merged: never verified again, never sent back.
1184
+ const already = waiting(readQueue(root)).filter((e) => {
1185
+ const at = e.commit ?? branchTip(e.branch);
1186
+ return (
1187
+ at && spawnSync('git', ['-C', root, 'merge-base', '--is-ancestor', at, into]).status === 0
1188
+ );
1189
+ });
1190
+ for (const e of already) settle(root, e.branch, 'merged', `already in ${into}`);
1191
+ const settledWords = already.length
1192
+ ? `${already.map((e) => e.branch).join(', ')} ${already.length === 1 ? 'was' : 'were'} already merged into ${into}, so ${already.length === 1 ? 'it leaves' : 'they leave'} the queue as merged. `
1193
+ : '';
984
1194
  const entries = readQueue(root);
985
- if (!waiting(entries).length) return out('The merge queue is empty.');
1195
+ if (!waiting(entries).length) return out(`${settledWords}The merge queue is empty.`);
986
1196
  // MQ-7: the first branch that can merge: one queued with partners waits until they're queued too.
987
- const { head, partners, held } = nextToMerge(entries);
988
- if (!head)
1197
+ // HUBR-9: and one the team provider's drift findings hold waits until they clear.
1198
+ const drift = driftNow(
1199
+ config,
1200
+ waiting(entries).map((e) => e.branch),
1201
+ { fresh: true },
1202
+ );
1203
+ // LOOP-15: a branch whose story the lead holds waits, with its group, until the hold ends.
1204
+ const deferredBy = heldBranches(root, config);
1205
+ const { head, partners, held, drifting, deferred } = nextToMerge(
1206
+ entries,
1207
+ drift.holds,
1208
+ deferredBy,
1209
+ );
1210
+ const holding = [
1211
+ ...drifting.map((d) => drift.words(d.branch, d.findings)),
1212
+ ...deferred.map(
1213
+ (d) =>
1214
+ `${d.branch} waits: ${deferralWords(d.hold)} (code-kit defer release ${d.hold.story}).`,
1215
+ ),
1216
+ ];
1217
+ const unchecked = drift.note ? ` ${drift.note}` : '';
1218
+ if (!head) {
1219
+ const waits = held.map(
1220
+ (h) =>
1221
+ `${h.branch} merges together with ${h.missing.join(', ')}, which ${h.missing.length === 1 ? "isn't" : "aren't"} queued yet`,
1222
+ );
989
1223
  return out(
990
- `Nothing can merge yet: ${held.map((h) => `${h.branch} merges together with ${h.missing.join(', ')}, which ${h.missing.length === 1 ? "isn't" : "aren't"} queued yet`).join('; ')}.`,
1224
+ `${settledWords}Nothing can merge yet${waits.length ? `: ${waits.join('; ')}.` : '.'}${holding.length ? ` ${holding.join(' ')}` : ''}`,
991
1225
  );
1226
+ }
992
1227
  const group = [head, ...partners];
993
1228
  // One merge at a time: a second run while the first verifies would merge the same head twice.
994
1229
  if (mergingNow(head))
@@ -1024,20 +1259,26 @@ function queue() {
1024
1259
  const published = publishAfter(config, byPerson);
1025
1260
  const left = waiting(readQueue(root));
1026
1261
  return out(
1027
- `${message}${published}${left.length ? ` Next in the queue: ${left[0].branch}.` : ' The queue is empty.'}`,
1262
+ `${settledWords}${message}${published}${left.length ? ` Next in the queue: ${left[0].branch}.` : ' The queue is empty.'}${holding.length ? ` ${holding.join(' ')}` : ''}${unchecked}`,
1028
1263
  );
1029
1264
  } catch (e) {
1030
1265
  if (!(e instanceof MergeStop)) throw e;
1031
- // MQ-3: a conflict or a failed verify goes back to the lane; a refusal leaves the queue as it is.
1032
- if (e.kind === 'refused') die(e.message);
1266
+ // MQ-3: a conflict or a failed verify goes back to the lane; a refusal leaves the queue as it is,
1267
+ // and so does an install or a check that couldn't run, which says nothing against the branch.
1268
+ if (['refused', 'unfinished', 'installs'].includes(e.kind)) die(e.message);
1269
+ if (e.kind === 'already') {
1270
+ for (const m of group) settle(root, m.branch, 'merged', `already in ${into}`);
1271
+ const left = waiting(readQueue(root));
1272
+ return out(
1273
+ `${e.message} It leaves the queue as merged.${left.length ? ` Next in the queue: ${left[0].branch}.` : ' The queue is empty.'}`,
1274
+ );
1275
+ }
1033
1276
  // A branch that moved after its review leaves the queue for the lead to review it again; it
1034
1277
  // isn't sent back, since nothing is wrong with it yet.
1035
- if (e.kind === 'unfinished') die(e.message);
1036
1278
  if (e.kind === 'moved') {
1037
1279
  settle(root, head.branch, 'moved', 'changed after its review');
1038
1280
  die(`${e.message}\n${head.branch} leaves the queue until then.`);
1039
1281
  }
1040
- const into = intoName ?? config.branches.protected[0];
1041
1282
  const after = lastMerged(entries);
1042
1283
  const why =
1043
1284
  e.kind === 'conflict'
@@ -1059,18 +1300,47 @@ function queue() {
1059
1300
  }
1060
1301
  if (sub !== undefined)
1061
1302
  die(
1062
- 'code-kit queue [--json] | queue add <branch> [--with <branch>,…] | queue drop <branch> | queue rules | queue merge --delegated|--person',
1303
+ 'code-kit queue [--json] | queue add <branch> [--with <branch>,…] | queue drop <branch> | queue rules | queue merge --delegated|--person | queue pause --reason "…" | queue resume',
1063
1304
  );
1064
1305
  const entries = readQueue(root);
1065
- if (flag('--json')) return out(JSON.stringify(entries, null, 2));
1066
1306
  const left = waiting(entries);
1307
+ const paused = queuePause(root);
1308
+ const deferredBy = heldBranches(root, config);
1309
+ // HUBR-9: what the team provider's findings hold, as last read (a merge asks it again).
1310
+ const drift = driftNow(
1311
+ config,
1312
+ left.map((e) => e.branch),
1313
+ );
1314
+ if (flag('--json'))
1315
+ return out(
1316
+ JSON.stringify(
1317
+ entries.map((e) => ({
1318
+ ...e,
1319
+ ...(left.includes(e) && drift.holds.has(e.branch)
1320
+ ? { drift: drift.holds.get(e.branch) }
1321
+ : {}),
1322
+ ...(left.includes(e) && deferredBy.has(e.branch)
1323
+ ? { deferred: deferredBy.get(e.branch) }
1324
+ : {}),
1325
+ ...(left.includes(e) && paused ? { paused } : {}),
1326
+ })),
1327
+ null,
1328
+ 2,
1329
+ ),
1330
+ );
1331
+ if (paused)
1332
+ out(
1333
+ `The merge queue is paused: ${paused.reason} (since ${paused.at.slice(0, 16).replace('T', ' ')}). code-kit queue resume lets it merge again.`,
1334
+ );
1067
1335
  if (!left.length) out('The merge queue is empty.');
1068
1336
  else out(`${left.length} waiting to merge, in order:`);
1069
1337
  left.forEach((e, i) =>
1070
1338
  out(
1071
- ` ${i + 1}. ${e.branch} (passed review ${e.passed}${e.commit ? ` at ${e.commit.slice(0, 7)}` : ''})`,
1339
+ ` ${i + 1}. ${e.branch} (passed review ${e.passed}${e.commit ? ` at ${e.commit.slice(0, 7)}` : ''})${drift.holds.has(e.branch) ? ' · held by the drift check' : ''}${deferredBy.has(e.branch) ? ` · ${deferralWords(deferredBy.get(e.branch))}` : ''}`,
1072
1340
  ),
1073
1341
  );
1342
+ for (const [branch, findings] of drift.holds) out(drift.words(branch, findings));
1343
+ if (left.length && drift.note) out(drift.note);
1074
1344
  }
1075
1345
 
1076
1346
  /**
@@ -1140,7 +1410,7 @@ function trailCommand() {
1140
1410
  die('trail needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
1141
1411
  const from = base(config, false);
1142
1412
  const status = buildStatus('.', config, from, tracked());
1143
- const rows = trail(resolve('.'), status, from);
1413
+ const rows = trail(resolve('.'), status, from, config);
1144
1414
  if (flag('--json')) return out(JSON.stringify({ base: from, requirements: rows }, null, 2));
1145
1415
  for (const r of rows)
1146
1416
  out(
@@ -1604,6 +1874,69 @@ function releaseCommand(version) {
1604
1874
  );
1605
1875
  }
1606
1876
 
1877
+ /**
1878
+ * LOOP-15: stories the lead holds on purpose. `defer <story>… --reason "…" [--until <date|ISO time>]`
1879
+ * holds them: `next`, the loop and the merge queue don't dispatch, review or merge them until the time
1880
+ * comes or `defer release <story>…`. `defer [--json]` lists the holds in force.
1881
+ */
1882
+ function deferCommand() {
1883
+ const { config } = load();
1884
+ const root = mainCheckout(resolve('.'));
1885
+ const [sub, ...ids] = rest;
1886
+ const usageLine =
1887
+ 'code-kit defer <story>… --reason "…" [--until <date|ISO time>] | defer release <story>… | defer [--json]';
1888
+ if (sub === undefined) {
1889
+ const holds = activeDeferrals(root);
1890
+ if (flag('--json')) return out(JSON.stringify(holds, null, 2));
1891
+ if (!holds.length) return out('No story is held.');
1892
+ out(`${holds.length} ${holds.length === 1 ? 'story is' : 'stories are'} held:`);
1893
+ for (const h of holds) out(` ${deferralWords(h)}`);
1894
+ return;
1895
+ }
1896
+ const isStory = (id) => /^[a-z][a-z0-9]*-\d+$/i.test(id);
1897
+ if (sub === 'release') {
1898
+ if (!ids.length || !ids.every(isStory)) die(usageLine);
1899
+ const ended = releaseStories(root, ids);
1900
+ const was = new Set(ended.map((h) => h.story));
1901
+ const notHeld = ids.map((id) => id.toUpperCase()).filter((id) => !was.has(id));
1902
+ return out(
1903
+ [
1904
+ ended.length
1905
+ ? `Released ${ended.map((h) => h.story).join(', ')}: ${ended.length === 1 ? 'it goes' : 'they go'} on as the plan has ${ended.length === 1 ? 'it' : 'them'}.`
1906
+ : null,
1907
+ notHeld.length
1908
+ ? `${notHeld.join(', ')} ${notHeld.length === 1 ? "wasn't" : "weren't"} held.`
1909
+ : null,
1910
+ ]
1911
+ .filter(Boolean)
1912
+ .join(' '),
1913
+ );
1914
+ }
1915
+ const stories = [sub, ...ids];
1916
+ if (!stories.every(isStory)) die(usageLine);
1917
+ if (!reason?.trim())
1918
+ die(
1919
+ 'code-kit defer needs --reason "…": what the story waits on, so the person and the band can see why it isn\'t moving.',
1920
+ );
1921
+ const { until, error } = parseUntil(untilGiven);
1922
+ if (error) die(error);
1923
+ const plan = config.docs?.plan;
1924
+ if (plan) {
1925
+ const known = new Set(readStories(root, plan).map((s) => s.id));
1926
+ const unknown = stories.map((s) => s.toUpperCase()).filter((s) => !known.has(s));
1927
+ if (unknown.length)
1928
+ die(`There is no story ${unknown.join(', ')} in ${plan}; nothing was held.`);
1929
+ }
1930
+ const made = deferStories(root, stories, {
1931
+ reason: reason.trim(),
1932
+ until,
1933
+ session: callerSession,
1934
+ });
1935
+ out(
1936
+ `${made.map(deferralWords).join('. ')}. Nothing dispatches, reviews or merges ${made.length === 1 ? 'it' : 'them'} until ${until ? 'then, or ' : ''}code-kit defer release ${made.map((h) => h.story).join(' ')}.`,
1937
+ );
1938
+ }
1939
+
1607
1940
  /** Records the review's send-back of `branch` at its current commit (lib/reviews.mjs). */
1608
1941
  function sentBackCommand(branch) {
1609
1942
  load();
@@ -1690,7 +2023,7 @@ function verify() {
1690
2023
  }
1691
2024
  }
1692
2025
  const lane = laneOfBranch(branch, config);
1693
- const { changed, found, skipped } = verifyBranch({
2026
+ const { changed, found, skipped, evidenceUnchecked } = verifyBranch({
1694
2027
  root: resolve('.'),
1695
2028
  base: from,
1696
2029
  config,
@@ -1704,7 +2037,16 @@ function verify() {
1704
2037
  const count = Object.values(found).reduce((n, list) => n + list.length, 0);
1705
2038
  out(
1706
2039
  JSON.stringify(
1707
- { base: from, branch, lane, changed: changed.length, found, problems: count, skipped },
2040
+ {
2041
+ base: from,
2042
+ branch,
2043
+ lane,
2044
+ changed: changed.length,
2045
+ found,
2046
+ problems: count,
2047
+ skipped,
2048
+ evidenceUnchecked: Boolean(evidenceUnchecked),
2049
+ },
1708
2050
  null,
1709
2051
  2,
1710
2052
  ),
@@ -1723,6 +2065,10 @@ function verify() {
1723
2065
  for (const p of found[key]) out(` ${p.split('\n').join('\n ')}`);
1724
2066
  }
1725
2067
  if (skipped.length) out(`\n${notRun(skipped)}`);
2068
+ if (evidenceUnchecked)
2069
+ out(
2070
+ `\nNot checked: whether the review compared each built screen with its design (HAND-7). The review's records are kept with the lead (.claude/state/), not here; the merge queue checks them.`,
2071
+ );
1726
2072
  if (count) die(`\n${count} problem(s). Fix them on this branch.`);
1727
2073
  out(skipped.length ? 'No problems in what ran.' : 'No problems.');
1728
2074
  }
@@ -2104,16 +2450,22 @@ function teamCommand() {
2104
2450
  const holderWords = (h) =>
2105
2451
  `${h.story} is claimed by ${h.by} (${ago(h.at)}). Ask them, or the tech lead (${team.techLead}), to release it.`;
2106
2452
  if (sub === 'claim') {
2107
- if (!story) die('code-kit team claim <story> [--lease "<glob>,<glob>"]');
2453
+ if (!story) die('code-kit team claim <story> [--lease "<glob>,<glob>"] [--intent <number>]');
2108
2454
  const lease = (leaseGiven ?? '')
2109
2455
  .split(',')
2110
2456
  .map((g) => g.trim())
2111
2457
  .filter(Boolean);
2112
- const r = provider.claim(story, lease);
2458
+ // HUBR-2: the intent this story carries out, so its pull request is the intent's.
2459
+ const intent = intentGiven === undefined ? null : Number(intentGiven.replace(/^#/, ''));
2460
+ if (intentGiven !== undefined && !isIntentId(intent))
2461
+ die(
2462
+ `"${intentGiven}" isn't an intent's number: give it as code-kit intend printed it (#12).`,
2463
+ );
2464
+ const r = provider.claim(story, lease, intent);
2113
2465
  if (r.holder) die(holderWords(r.holder));
2114
2466
  if (!r.ok) die(r.why);
2115
2467
  return out(
2116
- `Claimed ${story} as ${r.claim.by}${lease.length ? `, leasing ${lease.join(', ')}` : ''}.`,
2468
+ `Claimed ${story} as ${r.claim.by}${lease.length ? `, leasing ${lease.join(', ')}` : ''}${intent ? `, carrying out intent #${intent}` : ''}.`,
2117
2469
  );
2118
2470
  }
2119
2471
  // TEAM-12: the plan mirrored onto the team's GitHub Project.
@@ -2234,7 +2586,7 @@ function teamCommand() {
2234
2586
  out(state.claims.length ? 'Claims:' : 'Nothing is claimed.');
2235
2587
  for (const c of state.claims)
2236
2588
  out(
2237
- ` ${c.story} by ${c.by}, ${ago(c.at)}${c.stale ? ` · stale, nothing since ${ago(c.active)}` : ''}${c.lease.length ? ` · leases ${c.lease.join(', ')}` : ''}`,
2589
+ ` ${c.story} by ${c.by}, ${ago(c.at)}${c.stale ? ` · stale, nothing since ${ago(c.active)}` : ''}${c.lease.length ? ` · leases ${c.lease.join(', ')}` : ''}${c.intent ? ` · carries out intent #${c.intent}` : ''}`,
2238
2590
  );
2239
2591
  if (state.intents.length) out('Intents:');
2240
2592
  for (const i of state.intents)
@@ -2257,13 +2609,14 @@ function snapshotNow(team) {
2257
2609
  if (!config.docs?.specs || !config.docs?.plan) return null;
2258
2610
  const from = base(config, false);
2259
2611
  const status = buildStatus('.', config, from, tracked());
2260
- const claims = (readCache(resolve('.')) ?? {}).claims ?? [];
2612
+ const { claims = [], pulls = [] } = readCache(resolve('.')) ?? {};
2261
2613
  return buildSnapshot({
2262
2614
  root: resolve('.'),
2263
2615
  config,
2264
2616
  status,
2265
2617
  base: from,
2266
2618
  claims,
2619
+ pulls,
2267
2620
  version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
2268
2621
  });
2269
2622
  }
@@ -2873,6 +3226,7 @@ function designsCommand() {
2873
3226
  if (!config.designGate) die('The project has no design gate (designGate in the config).');
2874
3227
  const { entries, error } = readRegister(root, config);
2875
3228
  if (error) die(error);
3229
+ if (rest[0] === 'evidence') return designEvidence(root, config, entries);
2876
3230
  const story = rest[0];
2877
3231
  const stories = config.docs?.plan ? readStories(root, config.docs.plan) : [];
2878
3232
  const shown = (story ? designsFor(entries, story, stories) : entries).map((e) => ({
@@ -2900,6 +3254,86 @@ function designsCommand() {
2900
3254
  }
2901
3255
  }
2902
3256
 
3257
+ /**
3258
+ * HAND-7: `designs evidence <story> <screen> <state> <screenshot.png>`: the review's screenshot of a
3259
+ * built state, taken at its design's viewport and set beside the design's PNG, recorded for the story's
3260
+ * branch at its current commit. verify, and so the merge queue, report each approved state of the
3261
+ * screens a branch builds that has none.
3262
+ */
3263
+ function designEvidence(root, config, entries) {
3264
+ const [, storyArg, screenArg, stateArg, png] = rest;
3265
+ if (!storyArg || !screenArg || !stateArg || !png)
3266
+ die(
3267
+ 'Usage: code-kit designs evidence <story> <screen file or name> <state> <screenshot.png>, after setting the screenshot of the built state beside its design.',
3268
+ );
3269
+ const stories = config.docs?.plan ? readStories(root, config.docs.plan) : [];
3270
+ const story = stories.find((s) => s.id.toLowerCase() === storyArg.toLowerCase());
3271
+ const branch = story ? `${story.lane}/${story.id.toLowerCase()}` : storyArg;
3272
+ const sha =
3273
+ spawnSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${branch}^{commit}`], {
3274
+ encoding: 'utf8',
3275
+ }).stdout?.trim() ?? '';
3276
+ if (!sha)
3277
+ die(
3278
+ `${storyArg} has no branch here (${branch}): name the story whose branch you reviewed, or its branch.`,
3279
+ );
3280
+ const designs = (story ? designsFor(entries, story.id, stories) : entries).filter(handedOver);
3281
+ const key = (v) =>
3282
+ String(v ?? '')
3283
+ .trim()
3284
+ .toLowerCase();
3285
+ const byFile = designs.filter((e) => e.file === screenArg);
3286
+ const matching = byFile.length ? byFile : designs.filter((e) => key(e.screen) === key(screenArg));
3287
+ if (!matching.length)
3288
+ die(
3289
+ `${screenArg} isn't a screen with an approved design ${story ? `for ${story.id}` : 'in the register'}. \`code-kit designs${story ? ` ${story.id}` : ''}\` lists them; name its file or its screen.`,
3290
+ );
3291
+ if (matching.length > 1)
3292
+ die(
3293
+ `${screenArg} names more than one screen file (${matching.map((e) => e.file).join(', ')}): name the file the screenshot is of.`,
3294
+ );
3295
+ const [entry] = matching;
3296
+ const state = entry.states.find((st) => key(st?.name) === key(stateArg));
3297
+ if (!state)
3298
+ die(
3299
+ `${entry.screen ?? entry.file} has no approved ${stateArg} state; its states are ${entry.states.map((st) => st.name).join(', ')}.`,
3300
+ );
3301
+ let bytes;
3302
+ try {
3303
+ bytes = readFileSync(resolve(png));
3304
+ } catch {
3305
+ die(`${png} isn't there: take the screenshot of the built state first.`);
3306
+ }
3307
+ const size = pngSize(bytes);
3308
+ if (!size) die(`${png} isn't a PNG: save the screenshot as a PNG.`);
3309
+ if (!atViewport(size, state.viewport))
3310
+ die(
3311
+ `${png} is ${size.width}x${size.height}, not taken at the design's viewport (${state.viewport}, at 1x to 4x): take it again at ${state.viewport}, so it can be set beside ${state.image}.`,
3312
+ );
3313
+ const slug = (v) => String(v).replace(/[^\w.-]+/g, '_');
3314
+ const kept = posix.join(slug(branch), slug(entry.file), `${slug(state.name)}.png`);
3315
+ const dir = evidenceDir(root);
3316
+ mkdirSync(join(dir, posix.dirname(kept)), { recursive: true });
3317
+ writeFileSync(join(dir, kept), bytes);
3318
+ const image = posix.join('.claude/state/reviews', kept);
3319
+ recordEvidence(root, {
3320
+ branch,
3321
+ sha,
3322
+ story: story?.id ?? null,
3323
+ file: entry.file,
3324
+ screen: entry.screen ?? null,
3325
+ state: state.name,
3326
+ design: state.image,
3327
+ image,
3328
+ sha256: sha256Of(dir, kept),
3329
+ viewport: state.viewport ?? null,
3330
+ size: `${size.width}x${size.height}`,
3331
+ });
3332
+ out(
3333
+ `Recorded: ${entry.screen ?? entry.file}'s ${state.name} state on ${branch} at ${sha.slice(0, 7)}, beside ${state.image} (kept as ${image}).`,
3334
+ );
3335
+ }
3336
+
2903
3337
  const commands = {
2904
3338
  check,
2905
3339
  designs: designsCommand,
@@ -2918,6 +3352,7 @@ const commands = {
2918
3352
  decisions: decisionsCommand,
2919
3353
  task: taskCommand,
2920
3354
  hold: () => (rest.length === 1 ? hold(rest[0]) : usage()),
3355
+ defer: deferCommand,
2921
3356
  queue,
2922
3357
  team: teamCommand,
2923
3358
  intend: intendCommand,
@@ -2953,6 +3388,7 @@ function usage() {
2953
3388
  ' | next [--base ref] [--json] | adapters | trace <path>... [--json]\n' +
2954
3389
  ' | instructions [--write] [--json] | instructions show lead|lane [<lane>]\n' +
2955
3390
  ' | standards [--json] [--for <path>...] | designs [<story>] [--json]\n' +
3391
+ ' | designs evidence <story> <screen file or name> <state> <screenshot.png>\n' +
2956
3392
  ' | worktrees [--json] | worktrees release|discard <branch> | worktrees prune [--quiet]\n' +
2957
3393
  ' | approve <name>... --reason "…" [--lane name] [--config file]\n' +
2958
3394
  ' | merge <branch> --delegated|--person [--into branch] | publish --delegated|--person\n' +
@@ -2970,6 +3406,8 @@ function usage() {
2970
3406
  ' | ci check [--json] | ci usage [--days N] [--json] | release <version>\n' +
2971
3407
  ' | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +
2972
3408
  ' | queue [--json] | queue add|drop <branch> | queue rules | queue merge --delegated|--person\n' +
3409
+ ' | queue pause --reason "…" | queue resume\n' +
3410
+ ' | defer <story>... --reason "…" [--until <date|ISO time>] | defer release <story>... | defer [--json]\n' +
2973
3411
  ' | loop [--json] | loop pause|resume | loop lead|release --session id [--take]\n' +
2974
3412
  ' | map <story>|project [--json] | trail [--json] | journal [--json]\n' +
2975
3413
  ' | story <id> [--json] | timeline [--json]\n' +