@warren-dean/code-kit 0.26.2 → 0.28.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 +24 -0
  4. package/README.md +8 -6
  5. package/bin/code-kit.mjs +269 -52
  6. package/hooks/act.mjs +14 -5
  7. package/hooks/guard-bash.mjs +82 -17
  8. package/hooks/lib/adapters/hub/client.mjs +22 -0
  9. package/hooks/lib/checkout.mjs +105 -0
  10. package/hooks/lib/checks.mjs +34 -8
  11. package/hooks/lib/config.mjs +16 -2
  12. package/hooks/lib/dependencies.mjs +4 -0
  13. package/hooks/lib/designs.mjs +138 -0
  14. package/hooks/lib/events.mjs +9 -4
  15. package/hooks/lib/hook.mjs +61 -2
  16. package/hooks/lib/next.mjs +26 -5
  17. package/hooks/lib/plan.mjs +55 -13
  18. package/hooks/lib/queue.mjs +86 -1
  19. package/hooks/lib/regression.mjs +54 -44
  20. package/hooks/lib/rules.mjs +63 -20
  21. package/hooks/lib/security.mjs +20 -0
  22. package/hooks/lib/sessions.mjs +49 -9
  23. package/hooks/lib/snapshot.mjs +227 -22
  24. package/hooks/lib/team.mjs +27 -1
  25. package/hooks/lib/verify.mjs +37 -4
  26. package/hooks/lib/worktrees.mjs +18 -1
  27. package/hooks/mod/board.mjs +10 -1
  28. package/hooks/mod/loop.mjs +44 -1
  29. package/hooks/mod/register.mjs +96 -8
  30. package/hooks/mod/view.mjs +8 -0
  31. package/hooks/post-edit-check.mjs +3 -1
  32. package/hooks/session.mjs +3 -1
  33. package/hooks/stop-check.mjs +6 -1
  34. package/package.json +1 -1
  35. package/skills/design/SKILL.md +36 -7
  36. package/skills/dispatch/SKILL.md +1 -0
  37. package/skills/init/SKILL.md +2 -0
  38. package/skills/review/SKILL.md +2 -1
  39. package/skills/spec-design/SKILL.md +1 -1
  40. package/skills/status/SKILL.md +1 -1
  41. package/templates/agent.md +2 -1
package/bin/code-kit.mjs CHANGED
@@ -14,6 +14,8 @@
14
14
  // each story and requirement in the plan: built, in review, ready, blocked, tested
15
15
  // adapters other tools detected in the project, what each adds to the rules, and its setup
16
16
  // trace <path> [--json] what a file is for: the requirements it delivers, its lane, its layer rules
17
+ // designs [<story>] [--json] the approved designs from the register: a story's screens' design files,
18
+ // every state, for the lane's brief; or every entry and what's wrong with it
17
19
  // next [--base ref] [--json]
18
20
  // the step to take now (spec-design, init, dispatch, review…), from the project's state
19
21
  // approve <name>... --reason "…" [--lane name]
@@ -100,6 +102,13 @@ import {
100
102
  } from '../hooks/lib/questions.mjs';
101
103
  import { traceFile } from '../hooks/lib/trace.mjs';
102
104
  import { buildStatus, readStories, specCheckRows } from '../hooks/lib/plan.mjs';
105
+ import {
106
+ designsFor,
107
+ entryProblems,
108
+ handedOver,
109
+ readRegister,
110
+ toolOf,
111
+ } from '../hooks/lib/designs.mjs';
103
112
  import { recordSentBack } from '../hooks/lib/reviews.mjs';
104
113
  import {
105
114
  SECURITY_AGENT,
@@ -117,7 +126,18 @@ import {
117
126
  leadSection,
118
127
  writeInstructions,
119
128
  } from '../hooks/lib/instructions.mjs';
120
- import { dequeue, enqueue, lastMerged, readQueue, settle, waiting } from '../hooks/lib/queue.mjs';
129
+ import {
130
+ dequeue,
131
+ enqueue,
132
+ lastMerged,
133
+ markMerging,
134
+ mergingNow,
135
+ nextToMerge,
136
+ setPartners,
137
+ readQueue,
138
+ settle,
139
+ waiting,
140
+ } from '../hooks/lib/queue.mjs';
121
141
  import { publishBase } from '../hooks/lib/publish.mjs';
122
142
  import {
123
143
  briefOf,
@@ -133,6 +153,7 @@ import {
133
153
  storyOfBranch,
134
154
  syncBoard,
135
155
  readCache,
156
+ mergedClaims,
136
157
  teamOf,
137
158
  teamProvider,
138
159
  whoami,
@@ -164,6 +185,7 @@ import {
164
185
  import { heldTo, laneOfBranch, verifyBranch } from '../hooks/lib/verify.mjs';
165
186
  import { skippedLine } from '../hooks/lib/checks.mjs';
166
187
  import { TESTS_APPROVAL } from '../hooks/lib/regression.mjs';
188
+ import { freshCheckout } from '../hooks/lib/checkout.mjs';
167
189
  import { laneClaim, laneClaims, releaseLane, shortSession } from '../hooks/lib/laneclaims.mjs';
168
190
  import { slicesOf } from '../hooks/lib/schedule.mjs';
169
191
  import {
@@ -178,6 +200,8 @@ import {
178
200
  } from '../hooks/lib/sessions.mjs';
179
201
  import { globsOverlap } from '../hooks/lib/teamfacts.mjs';
180
202
  import {
203
+ BUSY_MS,
204
+ agentBusy,
181
205
  cleanOf,
182
206
  discardWorktree,
183
207
  keptBecause,
@@ -240,6 +264,7 @@ for (let o = option('--owner'); o !== undefined; o = option('--owner')) ownersGi
240
264
  const storyGiven = option('--story');
241
265
  const whyGiven = option('--why');
242
266
  const whatGiven = option('--what');
267
+ const withGiven = option('--with');
243
268
  const expectedGiven = option('--expected');
244
269
  const commandGiven = option('--command');
245
270
  const refusalGiven = option('--refusal');
@@ -677,7 +702,10 @@ function merge(branch) {
677
702
  const { config } = load();
678
703
  const byPerson = mergeMode();
679
704
  try {
680
- out(`${mergeOne(branch, config, byPerson).message}${publishAfter(config, byPerson)}`);
705
+ const { message } = mergeOne(branch, config, byPerson);
706
+ // 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)}`);
681
709
  } catch (e) {
682
710
  if (e instanceof MergeStop) die(e.message);
683
711
  throw e;
@@ -690,7 +718,7 @@ function merge(branch) {
690
718
  * commit, and refuses if the branch has moved on from it. Returns { into, message }; throws a
691
719
  * MergeStop when nothing was merged.
692
720
  */
693
- function mergeOne(branch, config, byPerson, commit = null) {
721
+ function mergeOne(branch, config, byPerson, commit = null, partners = []) {
694
722
  const refuse = (message) => {
695
723
  throw new MergeStop('refused', message);
696
724
  };
@@ -725,9 +753,13 @@ function mergeOne(branch, config, byPerson, commit = null) {
725
753
  const temporary = [];
726
754
  // A stop is thrown at once, so every way out of here removes the temporary worktrees first.
727
755
  const cleanup = () => {
728
- for (const dir of temporary.splice(0)) {
756
+ for (const t of temporary.splice(0)) {
757
+ if (t.remove) {
758
+ t.remove();
759
+ continue;
760
+ }
729
761
  try {
730
- g(root, 'worktree', 'remove', '--force', dir);
762
+ g(root, 'worktree', 'remove', '--force', t);
731
763
  } catch {
732
764
  // already gone
733
765
  }
@@ -745,17 +777,55 @@ function mergeOne(branch, config, byPerson, commit = null) {
745
777
  return dir;
746
778
  };
747
779
  try {
748
- // Verify where the branch is checked out (its dependencies are installed there), else in a
749
- // temporary worktree, where checks that need an install fail rather than being skipped.
750
- const verifyIn = checkedOut(branch) ?? worktree(branch, true);
751
- clean(verifyIn, branch);
752
- const tip = g(verifyIn, 'rev-parse', 'HEAD').trim();
780
+ const tip = g(root, 'rev-parse', `refs/heads/${branch}`).trim();
753
781
  if (commit && tip !== commit)
754
782
  fail(
755
783
  `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.`,
756
784
  'moved',
757
785
  );
758
- const lane = laneOfBranch(branch, config);
786
+ // 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.
789
+ let fresh;
790
+ try {
791
+ fresh = freshCheckout(root, into, {
792
+ merge: tip,
793
+ installsFrom: checkedOut(branch) ?? root,
794
+ prefix: 'code-kit-merge-',
795
+ });
796
+ } catch (e) {
797
+ if (!e.conflict) throw e;
798
+ fail(
799
+ `Nothing was merged: ${branch} doesn't merge cleanly into ${into}. Merge ${into} into ${branch} and resolve it there, then merge again.\n${e.message}`,
800
+ 'conflict',
801
+ );
802
+ }
803
+ temporary.push(fresh);
804
+ 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(
812
+ 'git',
813
+ ['-C', verifyIn, '-c', 'user.name=code-kit', '-c', 'user.email=code-kit@localhost'].concat([
814
+ 'merge',
815
+ '--no-ff',
816
+ '--no-edit',
817
+ '--quiet',
818
+ m.tip,
819
+ ]),
820
+ { encoding: 'utf8' },
821
+ );
822
+ if (merged.status !== 0)
823
+ 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()}`,
825
+ 'conflict',
826
+ );
827
+ }
828
+ const lane = members.length ? null : laneOfBranch(branch, config);
759
829
  const { changed, found, skipped, unfinished } = verifyBranch({
760
830
  root: verifyIn,
761
831
  base: into,
@@ -764,9 +834,29 @@ function mergeOne(branch, config, byPerson, commit = null) {
764
834
  checks: true,
765
835
  branch,
766
836
  });
767
- const problems = Object.entries(VERIFY_GROUPS).flatMap(([key, title]) =>
768
- found[key].map((p) => `${title}: ${p.split('\n').join('\n ')}`),
769
- );
837
+ // Each member is still held to its own lane's paths, on its own tree.
838
+ for (const b of members.length ? [{ branch, tip }, ...members] : []) {
839
+ const own = freshCheckout(root, into, { merge: b.tip, prefix: 'code-kit-merge-' });
840
+ temporary.push(own);
841
+ const held = verifyBranch({
842
+ root: own.dir,
843
+ base: into,
844
+ config,
845
+ lane: laneOfBranch(b.branch, config),
846
+ checks: false,
847
+ fixes: false,
848
+ branch: b.branch,
849
+ });
850
+ for (const key of Object.keys(found))
851
+ found[key].push(...held.found[key].map((p) => `${b.branch}: ${p}`));
852
+ }
853
+ const problems = [
854
+ ...new Set(
855
+ Object.entries(VERIFY_GROUPS).flatMap(([key, title]) =>
856
+ found[key].map((p) => `${title}: ${p.split('\n').join('\n ')}`),
857
+ ),
858
+ ),
859
+ ];
770
860
  // #62: a check that only ran out of time says nothing against the branch: it's tried again.
771
861
  if (problems.length === 1 && unfinished)
772
862
  fail(
@@ -781,32 +871,50 @@ function mergeOne(branch, config, byPerson, commit = null) {
781
871
  );
782
872
  const mergeIn = checkedOut(into) ?? worktree(into, false);
783
873
  clean(mergeIn, into);
784
- try {
785
- g(
786
- mergeIn,
787
- 'merge',
788
- '--no-ff',
789
- '-m',
790
- `Merge ${branch} into ${into}`,
791
- '-m',
792
- `Verified with code-kit verify (${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}) at ${tip.slice(0, 7)}${commit ? ', the commit the review passed,' : ''} and merged ${byPerson ? 'by the person, from the code-kit pane' : 'by the lead within the delegated rules'}.${skipped.length ? ` ${notRun(skipped)}` : ''}`,
793
- tip,
794
- );
795
- } catch (e) {
874
+ const before = g(mergeIn, 'rev-parse', 'HEAD').trim();
875
+ const together = members.length
876
+ ? ` together with ${members.map((m) => m.branch).join(', ')} (MQ-7)`
877
+ : '';
878
+ for (const b of [{ branch, tip, commit }, ...members]) {
796
879
  try {
797
- g(mergeIn, 'merge', '--abort');
798
- } catch {
799
- // nothing to abort
880
+ g(
881
+ mergeIn,
882
+ 'merge',
883
+ '--no-ff',
884
+ '-m',
885
+ `Merge ${b.branch} into ${into}`,
886
+ '-m',
887
+ `Verified with code-kit verify (${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}) at ${b.tip.slice(0, 7)}${b.commit ? ', the commit the review passed,' : ''}${together && b.branch === branch ? together : ''} and merged ${byPerson ? 'by the person, from the code-kit pane' : 'by the lead within the delegated rules'}.${skipped.length ? ` ${notRun(skipped)}` : ''}`,
888
+ b.tip,
889
+ );
890
+ } catch (e) {
891
+ try {
892
+ g(mergeIn, 'merge', '--abort');
893
+ } catch {
894
+ // nothing to abort
895
+ }
896
+ // A group's earlier members stay merged only if the whole group lands: undo them.
897
+ if (b.branch !== branch) g(mergeIn, 'reset', '--hard', before);
898
+ fail(
899
+ `Nothing was merged: ${b.branch} doesn't merge cleanly into ${into}. Merge ${into} into ${b.branch} and resolve it there, then merge again.\n${String(e.stderr ?? e.message).trim()}`,
900
+ 'conflict',
901
+ );
800
902
  }
801
- fail(
802
- `Nothing was merged: ${branch} doesn't merge cleanly into ${into}. Merge ${into} into ${branch} and resolve it there, then merge again.\n${String(e.stderr ?? e.message).trim()}`,
803
- 'conflict',
804
- );
805
903
  }
806
- // TEAM-1: a merged story's claim ends, whoever merged it.
904
+ // TEAM-1: a merged story's claim ends, whoever merged it, and so does any an earlier merge left.
807
905
  const team = teamOf(config);
808
- const story = storyOfBranch(branch);
809
- if (team && story) teamProvider(resolve('.'), team).release(story, { merged: true });
906
+ const stories = [branch, ...members.map((m) => m.branch)].map(storyOfBranch).filter(Boolean);
907
+ let unreleased = '';
908
+ if (team) {
909
+ const provider = teamProvider(resolve('.'), team);
910
+ for (const story of stories) {
911
+ const left = provider.release(story, { merged: true });
912
+ if (!left?.ok)
913
+ unreleased += ` Its claim on ${story} wasn't released (${left?.why ?? "the team provider didn't answer"}): run code-kit team release ${story}.`;
914
+ }
915
+ for (const s of mergedClaims(root, provider.state()?.claims ?? [], into))
916
+ if (!stories.includes(s)) provider.release(s, { merged: true });
917
+ }
810
918
  // LEAN-8: the merged branch's worktree, and any other that's done with, go now.
811
919
  const pruned = pruneWorktrees(root, config).removed;
812
920
  const removed = pruned.length
@@ -814,7 +922,7 @@ function mergeOne(branch, config, byPerson, commit = null) {
814
922
  : '';
815
923
  return {
816
924
  into,
817
- message: `Merged ${branch} into ${into}: verify passed on ${changed.length} file(s)${lane ? `, held to ${heldTo(lane)}` : ''}, at ${tip.slice(0, 7)}.${skipped.length ? ` ${notRun(skipped)}` : ''}${removed}`,
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}`,
818
926
  };
819
927
  } finally {
820
928
  cleanup();
@@ -850,23 +958,69 @@ function queue() {
850
958
  }
851
959
  // The commit the review passed: the queue merges exactly it, and a branch that moves is reviewed again.
852
960
  const added = enqueue(root, branch, commit);
853
- if (!added) return out(`${branch} is already in the merge queue, at ${commit.slice(0, 7)}.`);
961
+ // MQ-7: branches that only land together.
962
+ const partnersGiven = (withGiven ?? '')
963
+ .split(/[\s,]+/)
964
+ .filter(Boolean)
965
+ .filter((b) => b !== branch);
966
+ if (partnersGiven.length) setPartners(root, branch, partnersGiven);
967
+ const joined = partnersGiven.length
968
+ ? ` It merges together with ${partnersGiven.join(', ')}, once ${partnersGiven.length === 1 ? "it's" : "they're"} queued too.`
969
+ : '';
970
+ if (!added)
971
+ return out(`${branch} is already in the merge queue, at ${commit.slice(0, 7)}.${joined}`);
854
972
  if (added === 'updated')
855
- return out(`${branch} keeps its place in the merge queue, now at ${commit.slice(0, 7)}.`);
973
+ return out(
974
+ `${branch} keeps its place in the merge queue, now at ${commit.slice(0, 7)}.${joined}`,
975
+ );
856
976
  const place = waiting(readQueue(root)).length;
857
977
  return out(
858
- `Queued ${branch} at ${commit.slice(0, 7)} to merge${place > 1 ? `, ${place - 1} ahead of it` : ', next'}.`,
978
+ `Queued ${branch} at ${commit.slice(0, 7)} to merge${place > 1 ? `, ${place - 1} ahead of it` : ', next'}.${joined}`,
859
979
  );
860
980
  }
861
981
  if (sub === 'rules') return rulesOntoBase(root, config);
862
982
  if (sub === 'merge') {
863
983
  const byPerson = mergeMode();
864
984
  const entries = readQueue(root);
865
- const head = waiting(entries)[0];
866
- if (!head) return out('The merge queue is empty.');
985
+ if (!waiting(entries).length) return out('The merge queue is empty.');
986
+ // 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)
989
+ 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('; ')}.`,
991
+ );
992
+ const group = [head, ...partners];
993
+ // One merge at a time: a second run while the first verifies would merge the same head twice.
994
+ if (mergingNow(head))
995
+ die(
996
+ `${head.branch} is being merged now (queue merge, process ${head.pid}); nothing more was started. It says when it's done.`,
997
+ );
998
+ markMerging(root, head.branch, process.pid);
999
+ // However this run ends without settling the head, it goes back to waiting in its place.
1000
+ process.on('exit', () => {
1001
+ if (readQueue(root).some((e) => e.branch === head.branch && e.state === 'merging'))
1002
+ markMerging(root, head.branch, null);
1003
+ });
867
1004
  try {
868
- const { message } = mergeOne(head.branch, config, byPerson, head.commit ?? null);
869
- settle(root, head.branch, 'merged');
1005
+ for (const p of partners) {
1006
+ const at = execFileSync('git', ['rev-parse', '--verify', `${p.branch}^{commit}`], {
1007
+ encoding: 'utf8',
1008
+ }).trim();
1009
+ if (p.commit && at !== p.commit) {
1010
+ settle(root, p.branch, 'moved', 'changed after its review');
1011
+ die(
1012
+ `Nothing was merged: ${p.branch}, which ${head.branch} merges together with, has moved on since its review passed (${p.commit.slice(0, 7)} → ${at.slice(0, 7)}). It leaves the queue until it's reviewed again; ${head.branch} waits for it.`,
1013
+ );
1014
+ }
1015
+ }
1016
+ const { message } = mergeOne(
1017
+ head.branch,
1018
+ config,
1019
+ byPerson,
1020
+ head.commit ?? null,
1021
+ partners.map((p) => ({ branch: p.branch, commit: p.commit ?? null })),
1022
+ );
1023
+ for (const m of group) settle(root, m.branch, 'merged');
870
1024
  const published = publishAfter(config, byPerson);
871
1025
  const left = waiting(readQueue(root));
872
1026
  return out(
@@ -889,19 +1043,23 @@ function queue() {
889
1043
  e.kind === 'conflict'
890
1044
  ? `conflicts with ${into}${after ? ` after ${after}` : ''}`
891
1045
  : `fails verify against ${into}${after ? ` after ${after}` : ''}${e.first ? `: ${e.first}` : ''}`;
892
- const sha = execFileSync('git', ['rev-parse', '--verify', `${head.branch}^{commit}`], {
893
- encoding: 'utf8',
894
- }).trim();
895
- recordSentBack(root, head.branch, sha, why);
896
- settle(root, head.branch, 'sent back', why);
1046
+ // A group goes back together: it only lands as one.
1047
+ for (const m of group) {
1048
+ const sha = execFileSync('git', ['rev-parse', '--verify', `${m.branch}^{commit}`], {
1049
+ encoding: 'utf8',
1050
+ }).trim();
1051
+ recordSentBack(root, m.branch, sha, why);
1052
+ settle(root, m.branch, 'sent back', why);
1053
+ }
1054
+ const names = group.map((m) => m.branch).join(', ');
897
1055
  die(
898
- `${e.message}\n${head.branch} is sent back to its lane (${why}) and leaves the queue; its fix rejoins after the next review.`,
1056
+ `${e.message}\n${names} ${group.length === 1 ? 'is sent back to its lane' : 'are sent back to their lanes'} (${why}) and ${group.length === 1 ? 'leaves' : 'leave'} the queue; ${group.length === 1 ? 'its fix rejoins' : 'their fixes rejoin'} after the next review.`,
899
1057
  );
900
1058
  }
901
1059
  }
902
1060
  if (sub !== undefined)
903
1061
  die(
904
- 'code-kit queue [--json] | queue add <branch> | queue drop <branch> | queue rules | queue merge --delegated|--person',
1062
+ 'code-kit queue [--json] | queue add <branch> [--with <branch>,…] | queue drop <branch> | queue rules | queue merge --delegated|--person',
905
1063
  );
906
1064
  const entries = readQueue(root);
907
1065
  if (flag('--json')) return out(JSON.stringify(entries, null, 2));
@@ -2351,8 +2509,17 @@ function intendCommand() {
2351
2509
  * hooks refuse from agents; otherwise the lead recording what the person said in chat); `ask withdraw`
2352
2510
  * takes one back once it no longer needs the person.
2353
2511
  */
2512
+ const ASK_USAGE = `code-kit ask "<question>" [--story ST-n] [--blocks] [--why …] [--option "Label: what it does"]...
2513
+ asks the person what the lead can't settle; it waits in their Decisions tab
2514
+ code-kit ask [list] [--json] the questions waiting, and those answered lately
2515
+ code-kit ask answer <id> "<answer>"
2516
+ code-kit ask withdraw <id> --reason "…"`;
2517
+
2354
2518
  function askCommand() {
2355
2519
  const root = resolve('.');
2520
+ if (['--help', '-h', 'help'].includes(rest[0])) return out(ASK_USAGE);
2521
+ // `ask list` lists, as `ask` does.
2522
+ if (rest[0] === 'list' && rest.length === 1) rest.length = 0;
2356
2523
  const [sub, id, ...words] = rest;
2357
2524
  if (sub === 'answer') {
2358
2525
  const r = answerQuestion(root, id, {
@@ -2390,6 +2557,13 @@ function askCommand() {
2390
2557
  return;
2391
2558
  }
2392
2559
  const question = rest.join(' ').trim();
2560
+ // A question reaches the person, so a flag or a stray word never becomes one.
2561
+ if (rest[0].startsWith('-'))
2562
+ die(`${rest[0]} isn't an option of ask; nothing was asked.\n${ASK_USAGE}`);
2563
+ if (!/\s/.test(question) && !question.endsWith('?'))
2564
+ die(
2565
+ `"${question}" isn't a question for the person; nothing was asked. Ask it as a sentence they can answer.\n${ASK_USAGE}`,
2566
+ );
2393
2567
  if (flag('--blocks') && !storyGiven) die('--blocks holds a story: name it with --story ST-n.');
2394
2568
  const r = askQuestion(root, {
2395
2569
  by: 'lead',
@@ -2571,6 +2745,10 @@ function worktreesCommand() {
2571
2745
  if (rest[0] === 'release') {
2572
2746
  const w = list.find((x) => x.branch === rest[1] || x.path === rest[1]);
2573
2747
  if (!w) die(`No worktree has ${rest[1] ?? '<branch>'} checked out.`);
2748
+ if (agentBusy(root, w))
2749
+ die(
2750
+ `The ${w.branch.split('/')[0]} lane's agent is still at work on ${w.branch} (its last act was under ${BUSY_MS / 60_000} minutes ago, with no hand-back); nothing was removed. Wait for it to hand back, or stop it with TaskStop, then release it.`,
2751
+ );
2574
2752
  return out(`Released ${releaseWorktree(w)}. The branch and its commits stay.`);
2575
2753
  }
2576
2754
  if (rest[0] === 'discard') {
@@ -2684,8 +2862,47 @@ function standardsCommand() {
2684
2862
  process.exit(1);
2685
2863
  }
2686
2864
 
2865
+ /**
2866
+ * HAND-3, HAND-5: the approved designs, from the design register. `designs <story>` gives the designs a
2867
+ * story's screens are built from (its own entries and its design stories'), each state's files and
2868
+ * viewport, for the lane's brief; `designs` lists every entry and what's wrong with it.
2869
+ */
2870
+ function designsCommand() {
2871
+ const { config } = load();
2872
+ const root = resolve('.');
2873
+ if (!config.designGate) die('The project has no design gate (designGate in the config).');
2874
+ const { entries, error } = readRegister(root, config);
2875
+ if (error) die(error);
2876
+ const story = rest[0];
2877
+ const stories = config.docs?.plan ? readStories(root, config.docs.plan) : [];
2878
+ const shown = (story ? designsFor(entries, story, stories) : entries).map((e) => ({
2879
+ ...e,
2880
+ handedOver: handedOver(e),
2881
+ problems: entryProblems(root, e, config.docs?.specs),
2882
+ }));
2883
+ if (flag('--json')) return out(JSON.stringify(shown, null, 2));
2884
+ if (!shown.length)
2885
+ return out(
2886
+ story ? `No approved design is for ${story}'s screens.` : 'No approved designs yet.',
2887
+ );
2888
+ for (const e of shown) {
2889
+ out(
2890
+ `${e.file}: ${e.screen ?? '(no screen name)'}, approved ${e.approved ?? '?'} in ${e.story}`,
2891
+ );
2892
+ if (!e.handedOver)
2893
+ out(` only in ${toolOf(e)}: hand it over with /code-kit:design --hand-over`);
2894
+ for (const st of e.states ?? [])
2895
+ out(
2896
+ ` ${st.name} (${st.viewport ?? 'no viewport'}): ${[st.image, st.code].filter(Boolean).join(', ')}${st.why ? ` (no code: ${st.why})` : ''}`,
2897
+ );
2898
+ if (e.tokens) out(` tokens: ${e.tokens}`);
2899
+ for (const p of e.handedOver ? e.problems : []) out(` ✗ ${p}`);
2900
+ }
2901
+ }
2902
+
2687
2903
  const commands = {
2688
2904
  check,
2905
+ designs: designsCommand,
2689
2906
  standards: standardsCommand,
2690
2907
  worktrees: worktreesCommand,
2691
2908
  instructions: instructionsCommand,
@@ -2735,7 +2952,7 @@ function usage() {
2735
2952
  ' | security [--base ref] [--branch name] [--json]\n' +
2736
2953
  ' | next [--base ref] [--json] | adapters | trace <path>... [--json]\n' +
2737
2954
  ' | instructions [--write] [--json] | instructions show lead|lane [<lane>]\n' +
2738
- ' | standards [--json] [--for <path>...]\n' +
2955
+ ' | standards [--json] [--for <path>...] | designs [<story>] [--json]\n' +
2739
2956
  ' | worktrees [--json] | worktrees release|discard <branch> | worktrees prune [--quiet]\n' +
2740
2957
  ' | approve <name>... --reason "…" [--lane name] [--config file]\n' +
2741
2958
  ' | merge <branch> --delegated|--person [--into branch] | publish --delegated|--person\n' +
package/hooks/act.mjs CHANGED
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  // Durable lanes (spec 26): the event log's writer. PreToolUse records each act's start, PostToolUse
3
- // its end and PostToolUseFailure its failure, and SubagentStop a lane agent handing back. It never
4
- // blocks a call (DUR-2): it runs in the background (`async` in hooks.json), so no call waits for it,
5
- // and a write that fails is said once in the session while the work goes on.
3
+ // its end and PostToolUseFailure its failure, and SubagentStop a lane agent handing back, or stopped by
4
+ // an API error. It never blocks a call (DUR-2): it runs in the background (`async` in hooks.json), so
5
+ // no call waits for it, and a write that fails is said once in the session while the work goes on.
6
6
  import { existsSync, realpathSync, writeFileSync } from 'node:fs';
7
7
  import { tmpdir } from 'node:os';
8
8
  import { basename, dirname, isAbsolute, join, relative } from 'node:path';
9
- import { start } from './lib/hook.mjs';
9
+ import { apiStopOf, start } from './lib/hook.mjs';
10
10
  import { actorFor, currentBranch, sessionRoot } from './lib/rules.mjs';
11
11
  import {
12
12
  classify,
@@ -55,8 +55,17 @@ try {
55
55
  const ctx = { session: input.session_id ?? null, agent: input.agent_id ?? null, actor: who };
56
56
  if (mode === 'handback') {
57
57
  const story = storyOf({ kind: 'handback', target: '', branch }).story;
58
+ // An agent Claude's API stopped (its usage limit) didn't hand back: it stopped, mid-story.
59
+ const error = apiStopOf(input);
58
60
  if (actor.kind === 'lane' && story)
59
- recordNote(root, { ...ctx, story, branch, kind: 'handback', head: headOf(root) });
61
+ recordNote(root, {
62
+ ...ctx,
63
+ story,
64
+ branch,
65
+ kind: error ? 'stopped' : 'handback',
66
+ head: headOf(root),
67
+ ...(error ? { result: { error } } : {}),
68
+ });
60
69
  process.exit(0);
61
70
  }
62
71
  const { kind, target } = classify(input.tool_name, input.tool_input, config);