@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
@@ -93,6 +93,18 @@ export function leadDecides(name, config, actor) {
93
93
  return (rules.protected ?? []).includes(name);
94
94
  }
95
95
 
96
+ /**
97
+ * WHO-1: whether the lead needs an approval in force to change a file protected by `name` itself. Where
98
+ * the person merges, they review the lead's change in the pull request, so it needs none. Where merges
99
+ * are delegated to the lead nobody else sees it, so what the person keeps (not delegated to the lead)
100
+ * needs the person's approval, as it would from a lane. The kit is the lead's to change either way: the
101
+ * person approved the setup, and code-kit writes most of it.
102
+ */
103
+ export const leadNeedsApproval = (name, config) =>
104
+ name !== 'kit' &&
105
+ Boolean(config?.approvals?.delegate?.merge) &&
106
+ !leadDecides(name, config, { kind: 'lead' });
107
+
96
108
  /** HELM-2: whose decision approvals `names` are: the lead's when it may grant every one, else the person's. */
97
109
  export const decidedBy = (names, config, actor) =>
98
110
  [names].flat().every((n) => leadDecides(n, config, actor)) ? 'lead' : 'person';
@@ -186,6 +198,25 @@ function noteGiven(root, entries) {
186
198
  }
187
199
  }
188
200
 
201
+ /**
202
+ * Why an approval for `name` given to `actor` lately isn't in force any more: used up by an earlier
203
+ * commit, or out of time. A sentence for a refusal, or '' when none was given lately.
204
+ */
205
+ export function approvalEnded(root, name, actor, now = Date.now()) {
206
+ const lane = actor?.kind === 'lane' ? actor.lane : null;
207
+ const last = approvalsGiven(root)
208
+ .filter((e) => e.name === name && (!e.lane || e.lane === lane))
209
+ .at(-1);
210
+ if (!last?.at) return '';
211
+ const at = (t) => new Date(t).toTimeString().slice(0, 5);
212
+ const given = Date.parse(last.at);
213
+ if (now - given > 24 * 3600_000) return '';
214
+ if (last.usedAt)
215
+ return ` The ${name} approval given at ${at(given)} was used up at ${at(last.usedAt)} by an earlier commit${last.usedBy ? ` (${last.usedBy})` : ''}, so another is needed.`;
216
+ const ends = given + approvalMinutes(name) * 60_000;
217
+ return now >= ends ? ` The ${name} approval given at ${at(given)} ran out at ${at(ends)}.` : '';
218
+ }
219
+
189
220
  /** The approvals given through code-kit (and those used up), oldest first. */
190
221
  export function approvalsGiven(root) {
191
222
  try {
@@ -353,6 +384,7 @@ export function useApproval(root, name, actor) {
353
384
  ...(file !== join(dir, name) ? { lane: actor.lane } : {}),
354
385
  reason: a.reason,
355
386
  usedAt: new Date().toISOString(),
387
+ ...(actor?.label ? { usedBy: actor.label } : {}),
356
388
  },
357
389
  ]);
358
390
  return rmSync(file, { force: true });
@@ -438,6 +470,9 @@ export function recordRequest(root, actor, names, what, why, now = Date.now(), e
438
470
  why: String(why).slice(0, 300),
439
471
  ...extra,
440
472
  };
473
+ // The file's commits already made in the second it's asked, which don't answer it.
474
+ const before = commitsFrom(root, request.what, request.at);
475
+ if (before?.length) request.before = before;
441
476
  if (openRequests(root, now).some((r) => sameRequest(r, request))) return;
442
477
  const file = requestsFile(root);
443
478
  mkdirSync(dirname(file), { recursive: true });
@@ -528,32 +563,38 @@ function installedSince(root, r) {
528
563
  });
529
564
  }
530
565
 
531
- /** Whether the file a request named has been committed, on any branch, since it was asked. */
532
- function committedSince(root, r) {
533
- const path = String(r.what);
534
- if (/\s/.test(path) || (!path.includes('/') && !path.includes('.'))) return false;
566
+ /** The commits of `path`, on any branch, in or after the second `at` falls in; null when it isn't a path. */
567
+ function commitsFrom(root, path, at) {
568
+ if (/\s/.test(path) || (!path.includes('/') && !path.includes('.'))) return null;
535
569
  try {
536
- const out = execFileSync(
570
+ return execFileSync(
537
571
  'git',
538
572
  [
539
- '-C',
540
- root,
541
- 'log',
542
- '--all',
543
- '-1',
544
- '--format=%ct',
545
- `--since=@${Math.floor(Date.parse(r.at) / 1000)}`,
546
- '--',
547
- path,
573
+ ...['-C', root, 'log', '--all', '--format=%H'],
574
+ `--since=@${Math.floor(Date.parse(at) / 1000)}`,
575
+ ...['--', path],
548
576
  ],
549
577
  { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
550
- );
551
- return Boolean(out.trim());
578
+ )
579
+ .split('\n')
580
+ .filter(Boolean);
552
581
  } catch {
553
- return false;
582
+ return [];
554
583
  }
555
584
  }
556
585
 
586
+ /**
587
+ * Whether the file a request named has been committed, on any branch, since it was asked. Git dates are
588
+ * whole seconds, so the commits already there in the second it was asked (the one before the refused
589
+ * commit) are the request's `before`, and don't answer it.
590
+ */
591
+ function committedSince(root, r) {
592
+ const commits = commitsFrom(root, String(r.what), r.at);
593
+ if (!commits) return false;
594
+ const before = new Set(r.before ?? []);
595
+ return commits.some((c) => !before.has(c));
596
+ }
597
+
557
598
  /**
558
599
  * CARD-6: every approval given, newest first: { at, name, lane, reason, by, files, branches, used,
559
600
  * expired }. From the approvals given through code-kit, the approvals on disk (a person's own `!` echo
@@ -766,9 +807,11 @@ export function writeProblem(actor, rel, root, config) {
766
807
  const guarded = protectedEntry(rel, config);
767
808
  if (actor.kind === 'readonly' && (guarded || !matchesAny(rel, config.anyActor)))
768
809
  return readonlyProblem(actor, rel);
769
- // The lead writes protected files without an approval: the person reviews them in the pull request,
770
- // and every committed change is in the audit log. Anyone else needs a person's approval as well.
771
- if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
810
+ // The lead writes protected files without an approval where the person merges: they review them in
811
+ // the pull request, and every committed change is in the audit log. Where the lead merges, what the
812
+ // person keeps needs their approval (WHO-1). Anyone else needs an approval as well.
813
+ const leadFree = actor.kind === 'lead' && !leadNeedsApproval(guarded?.approval, config);
814
+ if (guarded && !leadFree && !approval(root, guarded.approval, actor)) {
772
815
  recordRequest(root, actor, guarded.approval, rel, guarded.why);
773
816
  const who =
774
817
  decidedBy(guarded.approval, config, actor) === 'lead'
@@ -142,6 +142,26 @@ export function securityReasons({ files = [], added = [], cites = [], security =
142
142
  return reasons;
143
143
  }
144
144
 
145
+ /** Every kind of reason a change gets the security review for: the sensitive kinds, then the rest. */
146
+ export const SECURITY_KINDS = [...SENSITIVE.map((s) => s.kind), 'dependencies', 'requirements'];
147
+
148
+ /**
149
+ * The security review's rules for a project: whether it has the reviewer agent, the kinds of change
150
+ * that get the review, and the ids of its specs' security requirements, a story citing any of which
151
+ * gets it too. { reviewer, kinds, requirements }.
152
+ */
153
+ export function securityRules(root, config) {
154
+ const specs = config.docs?.specs;
155
+ const texts = specs
156
+ ? markdownFiles(root, specs).map((f) => readFileSync(join(root, f), 'utf8'))
157
+ : [];
158
+ return {
159
+ reviewer: existsSync(join(root, SECURITY_AGENT_FILE)),
160
+ kinds: SECURITY_KINDS,
161
+ requirements: [...securityRequirementIds(texts)],
162
+ };
163
+ }
164
+
145
165
  /** The reasons as one sentence: "sign-in or sessions (src/auth/login.ts), dependencies (package.json)". */
146
166
  export const reasonsInWords = (reasons) =>
147
167
  reasons.map((r) => `${r.why} (${examples(r.where)})`).join('; ');
@@ -11,6 +11,7 @@ import { join } from 'node:path';
11
11
  import { matchesAny } from './glob.mjs';
12
12
  import { CLI, projectWorktrees } from './rules.mjs';
13
13
  import { shortSession } from './laneclaims.mjs';
14
+ import { isHandle } from './teamfacts.mjs';
14
15
 
15
16
  export { shortSession };
16
17
  export const SESSIONS_DIR = '.claude/state/sessions';
@@ -20,20 +21,37 @@ export const SESSION_LIVE_MS = 15 * 60_000;
20
21
  const SEEN_EVERY_MS = 60_000;
21
22
  /** The uncommitted files a session wrote, kept for SESS-5: at most this many. */
22
23
  const WROTE_KEPT = 500;
24
+ /** The file a session edits is noted again at most this often, unless it's another file. */
25
+ const EDITING_EVERY_MS = 30_000;
26
+ /** The code-kit a session runs, as it starts: the plugin can be updated while other sessions run. */
27
+ const KIT_VERSION = (() => {
28
+ try {
29
+ return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
30
+ } catch {
31
+ return null;
32
+ }
33
+ })();
23
34
 
24
35
  const main = (root) => projectWorktrees(root)[0] ?? root;
25
36
  const dirOf = (root) => join(main(root), SESSIONS_DIR);
26
37
  const safe = (id) => String(id).replace(/[^\w.-]/g, '_');
27
38
  const fileOf = (root, id) => join(dirOf(root), `${safe(id)}.json`);
28
39
 
29
- /** The person at this machine: their GitHub login if code-kit has it cached, or the OS user. */
30
- export function personHere(root) {
40
+ /** The person at this machine by their GitHub login, when code-kit has it cached, or null. */
41
+ export function loginHere(root) {
31
42
  try {
32
43
  const cached = JSON.parse(readFileSync(join(main(root), '.claude/state/whoami.json'), 'utf8'));
33
- if (cached?.login) return cached.login;
44
+ if (isHandle(cached?.login)) return cached.login;
34
45
  } catch {
35
- // not cached: the OS user
46
+ // not cached
36
47
  }
48
+ return null;
49
+ }
50
+
51
+ /** The person at this machine: their GitHub login if code-kit has it cached, or the OS user. */
52
+ export function personHere(root) {
53
+ const login = loginHere(root);
54
+ if (login) return login;
37
55
  try {
38
56
  return userInfo().username || null;
39
57
  } catch {
@@ -89,40 +107,62 @@ export const leadSession = (root, now = Date.now()) =>
89
107
  /**
90
108
  * SESS-2: a session starting (or resumed). It's the lead when no other live session is; otherwise a
91
109
  * working session. A resumed session keeps the role it had, unless it was the lead and another session
92
- * has led since.
110
+ * has led since. `model` is the model it runs on, when Claude Code says (SessionStart's `model`); the
111
+ * session also keeps its person's GitHub login, when code-kit knows it, and the code-kit it runs.
93
112
  */
94
- export function startSession(root, id, now = Date.now()) {
113
+ export function startSession(root, id, now = Date.now(), { model = null } = {}) {
95
114
  const at = new Date(now).toISOString();
96
115
  const had = readSession(root, id);
97
116
  const lead = leadSession(root, now);
98
117
  return write(root, {
99
118
  id,
100
119
  person: had?.person ?? personHere(root),
120
+ login: loginHere(root) ?? had?.login ?? null,
101
121
  role: lead && lead.id !== id ? 'working' : 'lead',
102
122
  started: had?.started ?? at,
103
123
  seen: at,
104
124
  ended: null,
105
125
  task: had?.task ?? null,
106
126
  wrote: had?.wrote ?? [],
127
+ model: model ?? had?.model ?? null,
128
+ codeKit: KIT_VERSION,
129
+ editing: had?.editing ?? null,
107
130
  });
108
131
  }
109
132
 
110
- /** A hook saw the session act: it's still there. A session code-kit hadn't seen starts here. */
111
- export function seeSession(root, id, now = Date.now()) {
133
+ /**
134
+ * A hook saw the session act: it's still there. A session code-kit hadn't seen starts here. `facts()`
135
+ * gives what's read only when the record is written (the model it runs on now), at most once a minute.
136
+ */
137
+ export function seeSession(root, id, now = Date.now(), facts = () => ({})) {
112
138
  if (!id) return null;
113
139
  const had = readSession(root, id);
114
- if (!had || had.ended) return startSession(root, id, now);
140
+ if (!had || had.ended) return startSession(root, id, now, facts());
115
141
  // A lead that went quiet past SESSION_LIVE_MS, while another session took the lead, works now.
116
142
  const lead = had.role === 'lead' ? leadSession(root, now) : null;
117
143
  const demoted = lead && lead.id !== id;
118
144
  if (!demoted && now - Date.parse(had.seen) < SEEN_EVERY_MS) return had;
145
+ const { model } = facts();
119
146
  return write(root, {
120
147
  ...had,
121
148
  seen: new Date(now).toISOString(),
122
149
  ...(demoted ? { role: 'working' } : {}),
150
+ ...(model ? { model } : {}),
123
151
  });
124
152
  }
125
153
 
154
+ /**
155
+ * The file the session last edited, in any of the project's checkouts: { path, at }, for the team
156
+ * provider's presence and the report. `rel` is relative to the checkout it's in.
157
+ */
158
+ export function noteEditing(root, id, rel, now = Date.now()) {
159
+ if (!id || !rel) return;
160
+ const had = readSession(root, id) ?? startSession(root, id, now);
161
+ const was = had.editing;
162
+ if (was?.path === rel && now - Date.parse(was.at) < EDITING_EVERY_MS) return;
163
+ write(root, { ...had, editing: { path: rel, at: new Date(now).toISOString() } });
164
+ }
165
+
126
166
  /** The session ended: it's no longer live, and leads nothing. Its task stays, stale, for SESS-4. */
127
167
  export function endSession(root, id, now = Date.now()) {
128
168
  const had = readSession(root, id);
@@ -9,9 +9,13 @@ import { execFileSync } from 'node:child_process';
9
9
  import { dirname, join } from 'node:path';
10
10
  import { APPROVAL_LOG } from './rules.mjs';
11
11
  import { approverOf } from './journal.mjs';
12
- import { readQueue } from './queue.mjs';
12
+ import { readQueue, waiting } from './queue.mjs';
13
13
  import { sendBacks } from './reviews.mjs';
14
- import { readMilestones, specCheckRows } from './plan.mjs';
14
+ import { readMilestones, readSpecs, specCheckRows } from './plan.mjs';
15
+ import { handedOver, entryProblems, readRegister, toolOf } from './designs.mjs';
16
+ import { SECURITY_KINDS, securityRules } from './security.mjs';
17
+ import { sessions } from './sessions.mjs';
18
+ import { storyOfBranch } from './teamfacts.mjs';
15
19
  import { storyTimes } from './timeline.mjs';
16
20
  import { trail } from './storymap.mjs';
17
21
  import {
@@ -20,6 +24,7 @@ import {
20
24
  LEVELS,
21
25
  ORIGINS,
22
26
  SOURCES,
27
+ laneLayers,
23
28
  projectStandards,
24
29
  sourceOf,
25
30
  } from './standards.mjs';
@@ -28,9 +33,12 @@ import { slicesOf } from './schedule.mjs';
28
33
 
29
34
  /**
30
35
  * 2 adds the project's standards (code-kit spec 22); 3 the plan's slices (spec 23, SCHED-2); 4 each
31
- * story's summary and each requirement's title.
36
+ * story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
37
+ * each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
38
+ * approver and story, the security review's rules, each story's spec-check result and place in the
39
+ * merge queue, the design register's entries, and the sessions at work.
32
40
  */
33
- export const SNAPSHOT_VERSION = 4;
41
+ export const SNAPSHOT_VERSION = 5;
34
42
 
35
43
  /** A story's stage, as a report names it. */
36
44
  export const STAGES = [
@@ -44,6 +52,10 @@ export const STAGES = [
44
52
  'done',
45
53
  ];
46
54
  export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
55
+ /** A spec-check report's status for a requirement, and for a story, its worst requirement's. */
56
+ export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
57
+ /** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
58
+ export const DESIGN_STATES = ['handed-over', 'in-tool', 'problems'];
47
59
 
48
60
  /**
49
61
  * The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
@@ -79,6 +91,10 @@ export const SNAPSHOT_SCHEMA = {
79
91
  claimedBy: 'handle?',
80
92
  // Added in version 4.
81
93
  summary: 'summary?',
94
+ // Added in version 5: the spec-check report's worst status on its branch (`none` with no report),
95
+ // and its place in the merge queue (1 merges next) while its branch waits there.
96
+ check: `enum:${[...CHECKS, 'none'].join('|')}?`,
97
+ queuePosition: 'count?',
82
98
  },
83
99
  ],
84
100
  sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
@@ -90,10 +106,24 @@ export const SNAPSHOT_SCHEMA = {
90
106
  stories: ['id'],
91
107
  built: ['path'],
92
108
  tested: ['path'],
93
- check: 'enum:done|partial|missing|conflicts|none',
109
+ check: `enum:${[...CHECKS, 'none'].join('|')}`,
110
+ },
111
+ ],
112
+ // Version 5: each spec, by the id the project gives it, its title, its outcome line and its
113
+ // requirements' ids. Nothing else of its text.
114
+ specs: [{ id: 'name', file: 'path', title: 'title?', outcome: 'summary?', requirements: ['id'] }],
115
+ approvals: [
116
+ {
117
+ what: 'name',
118
+ path: 'path?',
119
+ who: 'enum:person|lead',
120
+ at: 'ms',
121
+ branch: 'name?',
122
+ // Added in version 5: the person's GitHub login, when code-kit knew it; the story of its branch.
123
+ approver: 'handle?',
124
+ story: 'id?',
94
125
  },
95
126
  ],
96
- approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
97
127
  usage: [
98
128
  {
99
129
  story: 'id?',
@@ -104,11 +134,48 @@ export const SNAPSHOT_SCHEMA = {
104
134
  },
105
135
  ],
106
136
  rules: {
107
- layers: [{ name: 'name', mayImport: ['name'] }],
137
+ // `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
138
+ layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
108
139
  protected: [{ glob: 'path', approval: 'name' }],
109
140
  delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
110
141
  designGate: 'bool',
142
+ // Version 5: each lane, its deliverable kind, the layers its paths fall in, and what it owns.
143
+ lanes: [{ name: 'name', label: 'name', layers: ['name'], paths: ['path'], exclude: ['path'] }],
144
+ // Version 5: whether the project has the security reviewer, the kinds of change it reviews, and
145
+ // the security requirements a story citing gets it for.
146
+ security: {
147
+ reviewer: 'bool',
148
+ kinds: [`enum:${SECURITY_KINDS.join('|')}`],
149
+ requirements: ['id'],
150
+ },
111
151
  },
152
+ // Version 5: the design register's entries, by screen, the code file, the design story, when it was
153
+ // approved, the tool it was drawn in, its state and its states' names.
154
+ designs: [
155
+ {
156
+ screen: 'name',
157
+ file: 'path',
158
+ story: 'id?',
159
+ approved: 'date?',
160
+ tool: 'name?',
161
+ state: `enum:${DESIGN_STATES.join('|')}`,
162
+ states: ['name'],
163
+ },
164
+ ],
165
+ // Version 5: the sessions at work on this machine: the lead or a working one, its person's GitHub
166
+ // login, the code-kit and model it runs, when it started, and the file it last edited, and when.
167
+ sessions: [
168
+ {
169
+ id: 'name',
170
+ role: 'enum:lead|working',
171
+ person: 'handle?',
172
+ codeKit: 'name?',
173
+ model: 'name?',
174
+ started: 'ms',
175
+ editing: 'path?',
176
+ editedAt: 'ms?',
177
+ },
178
+ ],
112
179
  // Spec 22: each standard that applies, by id and title, how it's applied and where it came from;
113
180
  // its why in one line at most, and its evidence only as counts.
114
181
  standards: [
@@ -128,8 +195,19 @@ export const SNAPSHOT_SCHEMA = {
128
195
  ],
129
196
  };
130
197
 
131
- /** Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. */
132
- export const LATER_PARTS = ['standards', 'slices'];
198
+ /**
199
+ * Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. Each
200
+ * is a dotted path into the allow-list, `[]` for a list's items; a leaf that may be missing ends in `?`.
201
+ */
202
+ export const LATER_PARTS = [
203
+ 'standards',
204
+ 'slices',
205
+ 'specs',
206
+ 'designs',
207
+ 'sessions',
208
+ 'rules.lanes',
209
+ 'rules.security',
210
+ ];
133
211
 
134
212
  export const SUMMARY_MAX = 600;
135
213
 
@@ -167,6 +245,8 @@ const KINDS = {
167
245
 
168
246
  /** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
169
247
  export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
248
+ const later = (k) =>
249
+ LATER_PARTS.includes(`${at}.${k}`.replace(/^snapshot\./, '').replace(/\[\d+\]/g, '[]'));
170
250
  if (typeof shape === 'string') {
171
251
  const optional = shape.endsWith('?');
172
252
  const kind = optional ? shape.slice(0, -1) : shape;
@@ -185,7 +265,7 @@ export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot'
185
265
  return [
186
266
  ...extra.map((k) => `${at}.${k}: not a field a report may hold`),
187
267
  ...Object.entries(shape)
188
- .filter(([k]) => !(shape === SNAPSHOT_SCHEMA && LATER_PARTS.includes(k) && !(k in value)))
268
+ .filter(([k]) => !(later(k) && !(k in value)))
189
269
  .flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
190
270
  ];
191
271
  }
@@ -206,11 +286,40 @@ export const EVENT_PARTS = [
206
286
  'stories',
207
287
  'sendBacks',
208
288
  'requirements',
289
+ 'specs',
209
290
  'approvals',
210
291
  'rules',
211
292
  'standards',
293
+ 'designs',
212
294
  ];
213
295
 
296
+ /** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
297
+ const KINDS_BY_NAME = [
298
+ [/^(schemas?|contracts?|api|types|openapi|graphql|protos?)$/, 'API contract'],
299
+ [/^(web|mobile|ui|app|apps|screens?|frontend|client|pages|views?)$/, 'Screens'],
300
+ [/^(data|db|database|migrations?|storage|sql)$/, 'Data'],
301
+ [/^(domain|core|services?|backend|server|workers?|functions|logic|ai|jobs)$/, 'Service'],
302
+ [/^(tests?|qa|e2e|quality)$/, 'Tests'],
303
+ [/^(design|designs|ux)$/, 'Design'],
304
+ [/^(infra|infrastructure|platform|ops|devops|deploy|ci)$/, 'Infrastructure'],
305
+ [/^(docs?|documentation|runbooks?)$/, 'Docs'],
306
+ ];
307
+
308
+ /**
309
+ * A layer's or lane's deliverable kind: its `label`, or else what its name gives ("schemas" →
310
+ * "API contract", "web" → "Screens"), or else its name, capitalised, its hyphens as spaces.
311
+ */
312
+ export function deliverableKind(name, label = null) {
313
+ if (typeof label === 'string' && label.trim()) return label.trim().slice(0, 120);
314
+ const n = String(name ?? '').toLowerCase();
315
+ const found = KINDS_BY_NAME.find(([re]) => re.test(n))?.[1];
316
+ if (found) return found;
317
+ const words = String(name ?? '')
318
+ .replace(/[-_]+/g, ' ')
319
+ .trim();
320
+ return (words.charAt(0).toUpperCase() + words.slice(1)).slice(0, 120) || 'Code';
321
+ }
322
+
214
323
  const git = (root, ...args) => {
215
324
  try {
216
325
  return execFileSync('git', ['-C', root, ...args], {
@@ -277,8 +386,6 @@ function checkedRows(root, story) {
277
386
  return [];
278
387
  }
279
388
 
280
- const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
281
-
282
389
  /**
283
390
  * The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
284
391
  * branch stories merge into, `claims` the team's claims as last read, `version` code-kit's.
@@ -293,10 +400,14 @@ export function buildSnapshot({
293
400
  now = Date.now(),
294
401
  }) {
295
402
  const times = new Map(storyTimes(root, status.stories, base).map((t) => [t.id, t]));
296
- const queued = new Map(
297
- readQueue(root)
298
- .filter((e) => e.state === 'waiting' || e.state === 'merging')
299
- .map((e) => [e.branch, Date.parse(e.passed)]),
403
+ const inQueue = waiting(readQueue(root));
404
+ const queued = new Map(inQueue.map((e) => [e.branch, Date.parse(e.passed)]));
405
+ const place = new Map(inQueue.map((e, i) => [e.branch, i + 1]));
406
+ // Each story's spec-check report, on its branch: the requirements' statuses, and the story's worst.
407
+ const rowsOf = new Map(
408
+ status.stories
409
+ .filter((s) => s.branchExists)
410
+ .map((s) => [s.id, checkedRows(root, s).filter((r) => CHECKS.includes(r.status))]),
300
411
  );
301
412
  const backs = sendBacks(root);
302
413
  const claimed = new Map(claims.map((c) => [c.story, c.by]));
@@ -332,6 +443,8 @@ export function buildSnapshot({
332
443
  },
333
444
  claimedBy: claimed.get(s.id) ?? null,
334
445
  summary: reportedSummary(s.summary),
446
+ check: worstCheck(rowsOf.get(s.id) ?? []),
447
+ queuePosition: place.get(s.branch) ?? null,
335
448
  };
336
449
  });
337
450
 
@@ -352,10 +465,8 @@ export function buildSnapshot({
352
465
  .map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
353
466
 
354
467
  const checks = new Map();
355
- for (const s of status.stories)
356
- if (s.branchExists)
357
- for (const row of checkedRows(root, s))
358
- if (CHECKS.includes(row.status)) checks.set(row.requirement, row.status);
468
+ for (const rows of rowsOf.values())
469
+ for (const row of rows) checks.set(row.requirement, row.status);
359
470
  const requirements = trail(root, status, base).map((r) => ({
360
471
  id: r.id,
361
472
  title: line(r.title),
@@ -379,12 +490,16 @@ export function buildSnapshot({
379
490
  const key = `${e.approval}|${e.file ?? ''}|${at}`;
380
491
  if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
381
492
  seen.add(key);
493
+ const who = approverOf(e);
494
+ const story = KINDS.name(e.branch) ? storyOfBranch(e.branch) : null;
382
495
  approvals.push({
383
496
  what: e.approval,
384
497
  path: KINDS.path(e.file) ? e.file : null,
385
- who: approverOf(e),
498
+ who,
386
499
  at,
387
500
  branch: KINDS.name(e.branch) ? e.branch : null,
501
+ approver: who === 'person' && KINDS.handle(e.approver) ? e.approver : null,
502
+ story: KINDS.id(story) ? story : null,
388
503
  });
389
504
  }
390
505
 
@@ -402,10 +517,15 @@ export function buildSnapshot({
402
517
  stories,
403
518
  sendBacks: sendBackList,
404
519
  requirements,
520
+ specs: reportedSpecs(root, config, line),
405
521
  approvals,
406
522
  usage: recordedUsage(root),
407
523
  rules: {
408
- layers: (config.layers ?? []).map((l) => ({ name: l.name, mayImport: l.mayImport ?? [] })),
524
+ layers: (config.layers ?? []).map((l) => ({
525
+ name: l.name,
526
+ mayImport: l.mayImport ?? [],
527
+ label: deliverableKind(l.name, l.label),
528
+ })),
409
529
  protected: (config.protected ?? [])
410
530
  .filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
411
531
  .map((p) => ({ glob: p.glob, approval: p.approval })),
@@ -415,12 +535,97 @@ export function buildSnapshot({
415
535
  merge: Boolean(delegate?.merge),
416
536
  },
417
537
  designGate: Boolean(config.designGate),
538
+ lanes: Object.entries(config.lanes ?? {}).map(([name, lane]) => ({
539
+ name,
540
+ label: deliverableKind(name, lane.label),
541
+ layers: laneLayers(lane, config),
542
+ paths: (lane.paths ?? []).filter((p) => KINDS.path(p)),
543
+ exclude: (lane.exclude ?? []).filter((p) => KINDS.path(p)),
544
+ })),
545
+ security: securityRules(root, config),
418
546
  },
419
547
  standards: reportedStandards(root, config, line),
548
+ designs: reportedDesigns(root, config),
549
+ sessions: reportedSessions(root, now),
420
550
  };
421
551
  return snapshot;
422
552
  }
423
553
 
554
+ /** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
555
+ function worstCheck(rows) {
556
+ if (!rows.length) return 'none';
557
+ return [...CHECKS].reverse().find((c) => rows.some((r) => r.status === c));
558
+ }
559
+
560
+ /** Each spec as a report holds it: its id, file, title, outcome line and requirements' ids. */
561
+ function reportedSpecs(root, config, line) {
562
+ const { specs, plan } = config.docs ?? {};
563
+ if (!specs) return [];
564
+ return readSpecs(root, specs, plan)
565
+ .filter((sp) => KINDS.name(sp.id) && KINDS.path(sp.file))
566
+ .map((sp) => ({
567
+ id: sp.id,
568
+ file: sp.file,
569
+ title: line(sp.title),
570
+ outcome: reportedSummary(sp.outcome),
571
+ requirements: sp.requirements,
572
+ }));
573
+ }
574
+
575
+ /**
576
+ * The design register's entries (spec 24): handed over (its files there, as approved), only in a design
577
+ * tool, or with problems (a file missing or changed, a state the spec lists without a design).
578
+ */
579
+ function reportedDesigns(root, config) {
580
+ const { entries } = readRegister(root, config);
581
+ const one = (v, max = 120) =>
582
+ typeof v === 'string' && v.trim() ? v.replace(/\s+/g, ' ').trim().slice(0, max) : null;
583
+ return entries
584
+ .filter((e) => e && KINDS.path(e.file))
585
+ .map((e) => {
586
+ const approved = String(e.approved ?? '').slice(0, 10);
587
+ return {
588
+ screen: one(e.screen) ?? e.file.slice(0, 120),
589
+ file: e.file,
590
+ story: KINDS.id(e.story) ? e.story : null,
591
+ approved: KINDS.date(approved) ? approved : null,
592
+ tool: one(toolOf(e, null)),
593
+ state: !handedOver(e)
594
+ ? 'in-tool'
595
+ : entryProblems(root, e, config.docs?.specs).length
596
+ ? 'problems'
597
+ : 'handed-over',
598
+ states: (handedOver(e) ? e.states : []).map((st) => one(st?.name)).filter(Boolean),
599
+ };
600
+ });
601
+ }
602
+
603
+ /**
604
+ * The sessions at work on this machine's checkout (SESS-1): what code-kit recorded as each started and
605
+ * acted. A session that has ended, or gone quiet past SESSION_LIVE_MS, isn't at work.
606
+ */
607
+ function reportedSessions(root, now) {
608
+ const ms = (iso) => {
609
+ const t = Date.parse(iso ?? '');
610
+ return Number.isInteger(t) && t > 0 ? t : null;
611
+ };
612
+ return sessions(root, now)
613
+ .filter((s) => s.live && KINDS.name(s.id) && ms(s.started))
614
+ .map((s) => {
615
+ const editing = s.editing && KINDS.path(s.editing.path) ? s.editing : null;
616
+ return {
617
+ id: s.id,
618
+ role: s.role === 'lead' ? 'lead' : 'working',
619
+ person: KINDS.handle(s.login) ? s.login : null,
620
+ codeKit: KINDS.name(s.codeKit) ? s.codeKit : null,
621
+ model: KINDS.name(s.model) ? s.model : null,
622
+ started: ms(s.started),
623
+ editing: editing?.path ?? null,
624
+ editedAt: editing ? ms(editing.at) : null,
625
+ };
626
+ });
627
+ }
628
+
424
629
  /**
425
630
  * Spec 22: the standards that apply, as a report holds them. One that the file can't make sense of (an
426
631
  * unknown category, no level) is left out: `code-kit standards` tells the project what's wrong with it.