@warren-dean/code-kit 0.27.0 → 0.29.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.
@@ -9,9 +9,14 @@ 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, securityReview, securityRules } from './security.mjs';
17
+ import { securityReviews } from './events.mjs';
18
+ import { sessions } from './sessions.mjs';
19
+ import { isHandle, storyOfBranch } from './teamfacts.mjs';
15
20
  import { storyTimes } from './timeline.mjs';
16
21
  import { trail } from './storymap.mjs';
17
22
  import {
@@ -20,6 +25,7 @@ import {
20
25
  LEVELS,
21
26
  ORIGINS,
22
27
  SOURCES,
28
+ laneLayers,
23
29
  projectStandards,
24
30
  sourceOf,
25
31
  } from './standards.mjs';
@@ -28,9 +34,14 @@ import { slicesOf } from './schedule.mjs';
28
34
 
29
35
  /**
30
36
  * 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.
37
+ * story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
38
+ * each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
39
+ * approver and story, the security review's rules, each story's spec-check result and place in the
40
+ * merge queue, the design register's entries, and the sessions at work; 6 each usage row's model, the
41
+ * security reviews each story needed and whether they ran, the pull request of each intent a claim
42
+ * carries out, and the team's claims with when each was last renewed.
32
43
  */
33
- export const SNAPSHOT_VERSION = 4;
44
+ export const SNAPSHOT_VERSION = 6;
34
45
 
35
46
  /** A story's stage, as a report names it. */
36
47
  export const STAGES = [
@@ -44,6 +55,12 @@ export const STAGES = [
44
55
  'done',
45
56
  ];
46
57
  export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
58
+ /** A spec-check report's status for a requirement, and for a story, its worst requirement's. */
59
+ export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
60
+ /** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
61
+ export const DESIGN_STATES = ['handed-over', 'in-tool', 'problems'];
62
+ /** What a security review that ran found: nothing, findings, or a report without a findings block that reads. */
63
+ export const SECURITY_RESULTS = ['pass', 'findings', 'unread'];
47
64
 
48
65
  /**
49
66
  * The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
@@ -79,6 +96,10 @@ export const SNAPSHOT_SCHEMA = {
79
96
  claimedBy: 'handle?',
80
97
  // Added in version 4.
81
98
  summary: 'summary?',
99
+ // Added in version 5: the spec-check report's worst status on its branch (`none` with no report),
100
+ // and its place in the merge queue (1 merges next) while its branch waits there.
101
+ check: `enum:${[...CHECKS, 'none'].join('|')}?`,
102
+ queuePosition: 'count?',
82
103
  },
83
104
  ],
84
105
  sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
@@ -90,25 +111,99 @@ export const SNAPSHOT_SCHEMA = {
90
111
  stories: ['id'],
91
112
  built: ['path'],
92
113
  tested: ['path'],
93
- check: 'enum:done|partial|missing|conflicts|none',
114
+ check: `enum:${[...CHECKS, 'none'].join('|')}`,
115
+ },
116
+ ],
117
+ // Version 5: each spec, by the id the project gives it, its title, its outcome line and its
118
+ // requirements' ids. Nothing else of its text.
119
+ specs: [{ id: 'name', file: 'path', title: 'title?', outcome: 'summary?', requirements: ['id'] }],
120
+ approvals: [
121
+ {
122
+ what: 'name',
123
+ path: 'path?',
124
+ who: 'enum:person|lead',
125
+ at: 'ms',
126
+ branch: 'name?',
127
+ // Added in version 5: the person's GitHub login, when code-kit knew it; the story of its branch.
128
+ approver: 'handle?',
129
+ story: 'id?',
94
130
  },
95
131
  ],
96
- approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
97
132
  usage: [
98
133
  {
99
134
  story: 'id?',
100
135
  kind: `enum:${AGENT_KINDS.join('|')}`,
136
+ // Added in version 6: the model the requests ran on, as Claude Code names it.
137
+ model: 'name?',
101
138
  input: 'count',
102
139
  output: 'count',
103
140
  cache: 'count',
104
141
  },
105
142
  ],
143
+ // Version 6: each story that needs the security review on its branch, or whose security reviewer ran:
144
+ // why it needs it (the kinds of change), whether the reviewer ran, when it reported, and what it found.
145
+ securityReviews: [
146
+ {
147
+ story: 'id',
148
+ branch: 'name?',
149
+ needed: 'bool?',
150
+ reasons: [`enum:${SECURITY_KINDS.join('|')}`],
151
+ ran: 'bool',
152
+ at: 'ms?',
153
+ result: `enum:${SECURITY_RESULTS.join('|')}?`,
154
+ findings: 'count?',
155
+ blockers: 'count?',
156
+ },
157
+ ],
158
+ // Version 6: each intent a claim says its story carries out, and that story's open pull request.
159
+ intents: [{ id: 'count', story: 'id', pull: 'count?', draft: 'bool?' }],
160
+ // Version 6: the team's claims: who holds each story, since when, what it leases, when it was last
161
+ // renewed (claimed again, its lease grown, its branch pushed) and whether it's stale. No lease renews
162
+ // on a schedule.
163
+ claims: [{ story: 'id', by: 'handle', at: 'ms', active: 'ms?', stale: 'bool', lease: ['path'] }],
106
164
  rules: {
107
- layers: [{ name: 'name', mayImport: ['name'] }],
165
+ // `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
166
+ layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
108
167
  protected: [{ glob: 'path', approval: 'name' }],
109
168
  delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
110
169
  designGate: 'bool',
170
+ // Version 5: each lane, its deliverable kind, the layers its paths fall in, and what it owns.
171
+ lanes: [{ name: 'name', label: 'name', layers: ['name'], paths: ['path'], exclude: ['path'] }],
172
+ // Version 5: whether the project has the security reviewer, the kinds of change it reviews, and
173
+ // the security requirements a story citing gets it for.
174
+ security: {
175
+ reviewer: 'bool',
176
+ kinds: [`enum:${SECURITY_KINDS.join('|')}`],
177
+ requirements: ['id'],
178
+ },
111
179
  },
180
+ // Version 5: the design register's entries, by screen, the code file, the design story, when it was
181
+ // approved, the tool it was drawn in, its state and its states' names.
182
+ designs: [
183
+ {
184
+ screen: 'name',
185
+ file: 'path',
186
+ story: 'id?',
187
+ approved: 'date?',
188
+ tool: 'name?',
189
+ state: `enum:${DESIGN_STATES.join('|')}`,
190
+ states: ['name'],
191
+ },
192
+ ],
193
+ // Version 5: the sessions at work on this machine: the lead or a working one, its person's GitHub
194
+ // login, the code-kit and model it runs, when it started, and the file it last edited, and when.
195
+ sessions: [
196
+ {
197
+ id: 'name',
198
+ role: 'enum:lead|working',
199
+ person: 'handle?',
200
+ codeKit: 'name?',
201
+ model: 'name?',
202
+ started: 'ms',
203
+ editing: 'path?',
204
+ editedAt: 'ms?',
205
+ },
206
+ ],
112
207
  // Spec 22: each standard that applies, by id and title, how it's applied and where it came from;
113
208
  // its why in one line at most, and its evidence only as counts.
114
209
  standards: [
@@ -128,8 +223,22 @@ export const SNAPSHOT_SCHEMA = {
128
223
  ],
129
224
  };
130
225
 
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'];
226
+ /**
227
+ * Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. Each
228
+ * is a dotted path into the allow-list, `[]` for a list's items; a leaf that may be missing ends in `?`.
229
+ */
230
+ export const LATER_PARTS = [
231
+ 'standards',
232
+ 'slices',
233
+ 'specs',
234
+ 'designs',
235
+ 'sessions',
236
+ 'rules.lanes',
237
+ 'rules.security',
238
+ 'securityReviews',
239
+ 'intents',
240
+ 'claims',
241
+ ];
133
242
 
134
243
  export const SUMMARY_MAX = 600;
135
244
 
@@ -167,6 +276,8 @@ const KINDS = {
167
276
 
168
277
  /** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
169
278
  export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
279
+ const later = (k) =>
280
+ LATER_PARTS.includes(`${at}.${k}`.replace(/^snapshot\./, '').replace(/\[\d+\]/g, '[]'));
170
281
  if (typeof shape === 'string') {
171
282
  const optional = shape.endsWith('?');
172
283
  const kind = optional ? shape.slice(0, -1) : shape;
@@ -185,7 +296,7 @@ export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot'
185
296
  return [
186
297
  ...extra.map((k) => `${at}.${k}: not a field a report may hold`),
187
298
  ...Object.entries(shape)
188
- .filter(([k]) => !(shape === SNAPSHOT_SCHEMA && LATER_PARTS.includes(k) && !(k in value)))
299
+ .filter(([k]) => !(later(k) && !(k in value)))
189
300
  .flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
190
301
  ];
191
302
  }
@@ -206,11 +317,42 @@ export const EVENT_PARTS = [
206
317
  'stories',
207
318
  'sendBacks',
208
319
  'requirements',
320
+ 'specs',
209
321
  'approvals',
210
322
  'rules',
211
323
  'standards',
324
+ 'designs',
325
+ 'securityReviews',
326
+ 'intents',
327
+ ];
328
+
329
+ /** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
330
+ const KINDS_BY_NAME = [
331
+ [/^(schemas?|contracts?|api|types|openapi|graphql|protos?)$/, 'API contract'],
332
+ [/^(web|mobile|ui|app|apps|screens?|frontend|client|pages|views?)$/, 'Screens'],
333
+ [/^(data|db|database|migrations?|storage|sql)$/, 'Data'],
334
+ [/^(domain|core|services?|backend|server|workers?|functions|logic|ai|jobs)$/, 'Service'],
335
+ [/^(tests?|qa|e2e|quality)$/, 'Tests'],
336
+ [/^(design|designs|ux)$/, 'Design'],
337
+ [/^(infra|infrastructure|platform|ops|devops|deploy|ci)$/, 'Infrastructure'],
338
+ [/^(docs?|documentation|runbooks?)$/, 'Docs'],
212
339
  ];
213
340
 
341
+ /**
342
+ * A layer's or lane's deliverable kind: its `label`, or else what its name gives ("schemas" →
343
+ * "API contract", "web" → "Screens"), or else its name, capitalised, its hyphens as spaces.
344
+ */
345
+ export function deliverableKind(name, label = null) {
346
+ if (typeof label === 'string' && label.trim()) return label.trim().slice(0, 120);
347
+ const n = String(name ?? '').toLowerCase();
348
+ const found = KINDS_BY_NAME.find(([re]) => re.test(n))?.[1];
349
+ if (found) return found;
350
+ const words = String(name ?? '')
351
+ .replace(/[-_]+/g, ' ')
352
+ .trim();
353
+ return (words.charAt(0).toUpperCase() + words.slice(1)).slice(0, 120) || 'Code';
354
+ }
355
+
214
356
  const git = (root, ...args) => {
215
357
  try {
216
358
  return execFileSync('git', ['-C', root, ...args], {
@@ -257,8 +399,9 @@ export function recordedUsage(root) {
257
399
  for (const e of entries) {
258
400
  if (!AGENT_KINDS.includes(e.kind)) continue;
259
401
  const story = KINDS.id(e.story) ? e.story : null;
260
- const key = `${story}|${e.kind}`;
261
- const was = sums.get(key) ?? { story, kind: e.kind, input: 0, output: 0, cache: 0 };
402
+ const model = KINDS.name(e.model) && e.model ? e.model : null;
403
+ const key = `${story}|${e.kind}|${model}`;
404
+ const was = sums.get(key) ?? { story, kind: e.kind, model, input: 0, output: 0, cache: 0 };
262
405
  for (const k of ['input', 'output', 'cache'])
263
406
  was[k] += Number.isInteger(e[k]) && e[k] > 0 ? e[k] : 0;
264
407
  sums.set(key, was);
@@ -277,11 +420,10 @@ function checkedRows(root, story) {
277
420
  return [];
278
421
  }
279
422
 
280
- const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
281
-
282
423
  /**
283
424
  * The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
284
- * branch stories merge into, `claims` the team's claims as last read, `version` code-kit's.
425
+ * branch stories merge into, `claims` and `pulls` the team's claims and open pull requests as last
426
+ * read, `version` code-kit's.
285
427
  */
286
428
  export function buildSnapshot({
287
429
  root,
@@ -289,14 +431,19 @@ export function buildSnapshot({
289
431
  status,
290
432
  base,
291
433
  claims = [],
434
+ pulls = [],
292
435
  version,
293
436
  now = Date.now(),
294
437
  }) {
295
438
  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)]),
439
+ const inQueue = waiting(readQueue(root));
440
+ const queued = new Map(inQueue.map((e) => [e.branch, Date.parse(e.passed)]));
441
+ const place = new Map(inQueue.map((e, i) => [e.branch, i + 1]));
442
+ // Each story's spec-check report, on its branch: the requirements' statuses, and the story's worst.
443
+ const rowsOf = new Map(
444
+ status.stories
445
+ .filter((s) => s.branchExists)
446
+ .map((s) => [s.id, checkedRows(root, s).filter((r) => CHECKS.includes(r.status))]),
300
447
  );
301
448
  const backs = sendBacks(root);
302
449
  const claimed = new Map(claims.map((c) => [c.story, c.by]));
@@ -332,6 +479,8 @@ export function buildSnapshot({
332
479
  },
333
480
  claimedBy: claimed.get(s.id) ?? null,
334
481
  summary: reportedSummary(s.summary),
482
+ check: worstCheck(rowsOf.get(s.id) ?? []),
483
+ queuePosition: place.get(s.branch) ?? null,
335
484
  };
336
485
  });
337
486
 
@@ -352,10 +501,8 @@ export function buildSnapshot({
352
501
  .map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
353
502
 
354
503
  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);
504
+ for (const rows of rowsOf.values())
505
+ for (const row of rows) checks.set(row.requirement, row.status);
359
506
  const requirements = trail(root, status, base).map((r) => ({
360
507
  id: r.id,
361
508
  title: line(r.title),
@@ -379,12 +526,16 @@ export function buildSnapshot({
379
526
  const key = `${e.approval}|${e.file ?? ''}|${at}`;
380
527
  if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
381
528
  seen.add(key);
529
+ const who = approverOf(e);
530
+ const story = KINDS.name(e.branch) ? storyOfBranch(e.branch) : null;
382
531
  approvals.push({
383
532
  what: e.approval,
384
533
  path: KINDS.path(e.file) ? e.file : null,
385
- who: approverOf(e),
534
+ who,
386
535
  at,
387
536
  branch: KINDS.name(e.branch) ? e.branch : null,
537
+ approver: who === 'person' && KINDS.handle(e.approver) ? e.approver : null,
538
+ story: KINDS.id(story) ? story : null,
388
539
  });
389
540
  }
390
541
 
@@ -402,10 +553,15 @@ export function buildSnapshot({
402
553
  stories,
403
554
  sendBacks: sendBackList,
404
555
  requirements,
556
+ specs: reportedSpecs(root, config, line),
405
557
  approvals,
406
558
  usage: recordedUsage(root),
407
559
  rules: {
408
- layers: (config.layers ?? []).map((l) => ({ name: l.name, mayImport: l.mayImport ?? [] })),
560
+ layers: (config.layers ?? []).map((l) => ({
561
+ name: l.name,
562
+ mayImport: l.mayImport ?? [],
563
+ label: deliverableKind(l.name, l.label),
564
+ })),
409
565
  protected: (config.protected ?? [])
410
566
  .filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
411
567
  .map((p) => ({ glob: p.glob, approval: p.approval })),
@@ -415,12 +571,178 @@ export function buildSnapshot({
415
571
  merge: Boolean(delegate?.merge),
416
572
  },
417
573
  designGate: Boolean(config.designGate),
574
+ lanes: Object.entries(config.lanes ?? {}).map(([name, lane]) => ({
575
+ name,
576
+ label: deliverableKind(name, lane.label),
577
+ layers: laneLayers(lane, config),
578
+ paths: (lane.paths ?? []).filter((p) => KINDS.path(p)),
579
+ exclude: (lane.exclude ?? []).filter((p) => KINDS.path(p)),
580
+ })),
581
+ security: securityRules(root, config),
418
582
  },
419
583
  standards: reportedStandards(root, config, line),
584
+ designs: reportedDesigns(root, config),
585
+ sessions: reportedSessions(root, now),
586
+ securityReviews: reportedSecurityReviews(root, config, status, base),
587
+ intents: reportedIntents(claims, pulls),
588
+ claims: reportedClaims(claims),
420
589
  };
421
590
  return snapshot;
422
591
  }
423
592
 
593
+ /**
594
+ * Version 6: each story that needs the security review on its branch now (security.mjs, for a branch
595
+ * still at work), or whose security reviewer ran (the event log's record of its findings).
596
+ */
597
+ function reportedSecurityReviews(root, config, status, base) {
598
+ const ran = securityReviews(root);
599
+ const out = [];
600
+ for (const s of status.stories) {
601
+ if (!KINDS.id(s.id)) continue;
602
+ const review = ran.get(s.id) ?? null;
603
+ let need = null;
604
+ if (s.branchExists && s.state !== 'done')
605
+ try {
606
+ need = securityReview(root, { base, branch: s.branch, config });
607
+ } catch {
608
+ // the branch can't be compared with the base: whether it needs the review isn't known
609
+ }
610
+ if (!review && !need?.needed) continue;
611
+ const counted = review && !review.unread;
612
+ const count = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
613
+ out.push({
614
+ story: s.id,
615
+ branch: KINDS.name(s.branch) ? s.branch : null,
616
+ needed: need ? need.needed : null,
617
+ reasons: need
618
+ ? [...new Set(need.reasons.map((r) => r.kind))].filter((k) => SECURITY_KINDS.includes(k))
619
+ : [],
620
+ ran: Boolean(review),
621
+ at: review ? msOf(review.at) : null,
622
+ result: !review ? null : review.unread ? 'unread' : review.findings ? 'findings' : 'pass',
623
+ findings: counted ? count(review.findings) : null,
624
+ blockers: counted ? count(review.blockers) : null,
625
+ });
626
+ }
627
+ return out;
628
+ }
629
+
630
+ const msOf = (iso) => {
631
+ const t = Date.parse(iso ?? '');
632
+ return Number.isInteger(t) && t > 0 ? t : null;
633
+ };
634
+
635
+ /**
636
+ * Version 6: each intent a claim names (`code-kit team claim <story> --intent <n>`), with its story and
637
+ * that story's open pull request, by its branch, draft or not; none while it has no pull request open.
638
+ */
639
+ function reportedIntents(claims, pulls) {
640
+ return claims
641
+ .filter((c) => Number.isInteger(c?.intent) && c.intent > 0 && KINDS.id(c.story))
642
+ .map((c) => {
643
+ const pr = pulls.find((p) => storyOfBranch(p?.branch) === c.story);
644
+ return {
645
+ id: c.intent,
646
+ story: c.story,
647
+ pull: Number.isInteger(pr?.number) && pr.number > 0 ? pr.number : null,
648
+ draft: pr ? Boolean(pr.draft) : null,
649
+ };
650
+ });
651
+ }
652
+
653
+ /**
654
+ * Version 6: the team's claims as the provider last gave them: when each was taken, when it was last
655
+ * renewed by work (`active`: claimed again, its lease grown or its branch pushed) and whether that's
656
+ * longer ago than the team's stale days. A claim never renews on a schedule.
657
+ */
658
+ function reportedClaims(claims) {
659
+ return claims
660
+ .filter((c) => KINDS.id(c?.story) && isHandle(c.by) && msOf(c.at))
661
+ .map((c) => ({
662
+ story: c.story,
663
+ by: c.by,
664
+ at: msOf(c.at),
665
+ active: msOf(c.active),
666
+ stale: c.stale === true,
667
+ lease: (Array.isArray(c.lease) ? c.lease : []).filter((p) => KINDS.path(p)),
668
+ }));
669
+ }
670
+
671
+ /** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
672
+ function worstCheck(rows) {
673
+ if (!rows.length) return 'none';
674
+ return [...CHECKS].reverse().find((c) => rows.some((r) => r.status === c));
675
+ }
676
+
677
+ /** Each spec as a report holds it: its id, file, title, outcome line and requirements' ids. */
678
+ function reportedSpecs(root, config, line) {
679
+ const { specs, plan } = config.docs ?? {};
680
+ if (!specs) return [];
681
+ return readSpecs(root, specs, plan)
682
+ .filter((sp) => KINDS.name(sp.id) && KINDS.path(sp.file))
683
+ .map((sp) => ({
684
+ id: sp.id,
685
+ file: sp.file,
686
+ title: line(sp.title),
687
+ outcome: reportedSummary(sp.outcome),
688
+ requirements: sp.requirements,
689
+ }));
690
+ }
691
+
692
+ /**
693
+ * The design register's entries (spec 24): handed over (its files there, as approved), only in a design
694
+ * tool, or with problems (a file missing or changed, a state the spec lists without a design).
695
+ */
696
+ function reportedDesigns(root, config) {
697
+ const { entries } = readRegister(root, config);
698
+ const one = (v, max = 120) =>
699
+ typeof v === 'string' && v.trim() ? v.replace(/\s+/g, ' ').trim().slice(0, max) : null;
700
+ return entries
701
+ .filter((e) => e && KINDS.path(e.file))
702
+ .map((e) => {
703
+ const approved = String(e.approved ?? '').slice(0, 10);
704
+ return {
705
+ screen: one(e.screen) ?? e.file.slice(0, 120),
706
+ file: e.file,
707
+ story: KINDS.id(e.story) ? e.story : null,
708
+ approved: KINDS.date(approved) ? approved : null,
709
+ tool: one(toolOf(e, null)),
710
+ state: !handedOver(e)
711
+ ? 'in-tool'
712
+ : entryProblems(root, e, config.docs?.specs).length
713
+ ? 'problems'
714
+ : 'handed-over',
715
+ states: (handedOver(e) ? e.states : []).map((st) => one(st?.name)).filter(Boolean),
716
+ };
717
+ });
718
+ }
719
+
720
+ /**
721
+ * The sessions at work on this machine's checkout (SESS-1): what code-kit recorded as each started and
722
+ * acted. A session that has ended, or gone quiet past SESSION_LIVE_MS, isn't at work.
723
+ */
724
+ function reportedSessions(root, now) {
725
+ const ms = (iso) => {
726
+ const t = Date.parse(iso ?? '');
727
+ return Number.isInteger(t) && t > 0 ? t : null;
728
+ };
729
+ return sessions(root, now)
730
+ .filter((s) => s.live && KINDS.name(s.id) && ms(s.started))
731
+ .map((s) => {
732
+ const editing = s.editing && KINDS.path(s.editing.path) ? s.editing : null;
733
+ return {
734
+ id: s.id,
735
+ role: s.role === 'lead' ? 'lead' : 'working',
736
+ person: KINDS.handle(s.login) ? s.login : null,
737
+ codeKit: KINDS.name(s.codeKit) ? s.codeKit : null,
738
+ model: KINDS.name(s.model) ? s.model : null,
739
+ started: ms(s.started),
740
+ editing: editing?.path ?? null,
741
+ editedAt: editing ? ms(editing.at) : null,
742
+ };
743
+ });
744
+ }
745
+
424
746
  /**
425
747
  * Spec 22: the standards that apply, as a report holds them. One that the file can't make sense of (an
426
748
  * unknown category, no level) is left out: `code-kit standards` tells the project what's wrong with it.
@@ -33,6 +33,8 @@ export {
33
33
  };
34
34
 
35
35
  const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
36
+ /** An intent's number, as the provider keeps it. */
37
+ export const isIntentId = (n) => Number.isInteger(n) && n > 0;
36
38
 
37
39
  /** What's wrong with `team` and the lanes' `owners`, as the config's other problems are worded. */
38
40
  export function teamProblems(c) {
@@ -154,9 +156,11 @@ export function whoami(root, now = Date.now()) {
154
156
 
155
157
  // --- the provider (TEAM-2) ----------------------------------------------------------------------------
156
158
  //
157
- // The core talks to the team through one interface: whoami, claim(story, lease), release(story),
159
+ // The core talks to the team through one interface: whoami, claim(story, lease, intent), release(story),
158
160
  // state() and intend(about, touches), report(snapshot) (HUBR-1) and standards() (STD-6: an
159
- // organisation's standards and this project's waivers, `{ standards, waivers, version }`). The GitHub
161
+ // organisation's standards and this project's waivers, `{ standards, waivers, version }`). A provider
162
+ // that checks drift says in its state what holds a merge (`mergeHolds`) and lists its open `findings`
163
+ // (HUBR-9); GitHub's checks none, so it holds nothing. The GitHub
160
164
  // provider is built in; any other is a command named in the config, called with the operation's name
161
165
  // and its input as JSON on stdin, answering JSON.
162
166
 
@@ -173,7 +177,14 @@ function claimOf(message) {
173
177
  try {
174
178
  const c = JSON.parse(message);
175
179
  return isStoryId(c.story) && isHandle(c.by)
176
- ? { story: c.story, by: c.by, at: c.at, lease: Array.isArray(c.lease) ? c.lease : [] }
180
+ ? {
181
+ story: c.story,
182
+ by: c.by,
183
+ at: c.at,
184
+ lease: Array.isArray(c.lease) ? c.lease : [],
185
+ // HUBR-2: the intent the story carries out, when its claim names one.
186
+ ...(isIntentId(c.intent) ? { intent: c.intent } : {}),
187
+ }
177
188
  : null;
178
189
  } catch {
179
190
  return null;
@@ -197,10 +208,12 @@ export function teamProvider(root, team) {
197
208
  const r = command[op](...args);
198
209
  if (!down(r) && r !== null) return r;
199
210
  const g = github[op](...args);
200
- // The state says it came through GitHub, and why, for the band.
201
- return op === 'state' && g
202
- ? { ...g, fallback: r?.why ?? "The team provider can't be reached." }
203
- : g;
211
+ if (op !== 'state' || !g) return g;
212
+ // The state says it came through GitHub, and why, for the band; kept so, so the hooks, `next` and
213
+ // the queue reading it later know the provider didn't answer (HUBR-9: no drift was checked).
214
+ const fell = { ...g, fallback: r?.why ?? "The team provider can't be reached." };
215
+ writeCache(root, fell);
216
+ return fell;
204
217
  };
205
218
  // A claim taken while the provider was down lives only on GitHub; one the provider doesn't know is
206
219
  // released there too, so it can't outlive its story (a merged story's claim, stuck and going stale).
@@ -403,7 +416,8 @@ function githubProvider(root, team) {
403
416
 
404
417
  const provider = {
405
418
  whoami: () => ({ login: me() }),
406
- claim(story, lease = []) {
419
+ /** `intent`: the intent the story carries out (HUBR-2); a claim again keeps the one it has. */
420
+ claim(story, lease = [], intent = null) {
407
421
  if (!isStoryId(story)) return { ok: false, why: `"${story}" isn't a story id.` };
408
422
  const by = me();
409
423
  if (!by) return { ok: false, why: 'Sign in to GitHub first (gh auth login).' };
@@ -423,8 +437,9 @@ function githubProvider(root, team) {
423
437
  const tree = git(['mktree'], { input: '' }).stdout.trim();
424
438
  // A lease only grows while the story is open: a claim again adds to it.
425
439
  lease = [...new Set([...(held?.lease ?? []), ...lease])];
426
- const message = JSON.stringify({ story, by, at, lease });
427
- const sha = git(['commit-tree', tree, '-m', message], { env }).stdout.trim();
440
+ const named = isIntentId(intent) ? intent : (held?.intent ?? null);
441
+ const claim = { story, by, at, lease, ...(named ? { intent: named } : {}) };
442
+ const sha = git(['commit-tree', tree, '-m', JSON.stringify(claim)], { env }).stdout.trim();
428
443
  const pushed = pushClaim(story, sha, held?.sha ?? '');
429
444
  if (!ok(pushed)) {
430
445
  // Someone claimed it between our fetch and push: say who.
@@ -433,7 +448,7 @@ function githubProvider(root, team) {
433
448
  return holder && holder.by !== by ? { ok: false, holder } : notReached();
434
449
  }
435
450
  provider.forget();
436
- return { ok: true, claim: { story, by, at, lease } };
451
+ return { ok: true, claim };
437
452
  },
438
453
  /** `merged`: the story merged, so its claim ends whoever releases it. */
439
454
  release(story, { merged = false } = {}) {
@@ -575,7 +590,13 @@ function githubProvider(root, team) {
575
590
  GIT_COMMITTER_EMAIL: email,
576
591
  };
577
592
  const tree = git(['mktree'], { input: '' }).stdout.trim();
578
- const message = JSON.stringify({ story, by: to, at, lease: held.lease });
593
+ const message = JSON.stringify({
594
+ story,
595
+ by: to,
596
+ at,
597
+ lease: held.lease,
598
+ ...(held.intent ? { intent: held.intent } : {}),
599
+ });
579
600
  const sha = git(['commit-tree', tree, '-m', message], { env }).stdout.trim();
580
601
  if (!ok(pushClaim(story, sha, held.sha))) return notReached();
581
602
  provider.forget();
@@ -770,7 +791,8 @@ function commandProvider(root, team, command) {
770
791
  };
771
792
  return {
772
793
  whoami: () => call('whoami'),
773
- claim: (story, lease = []) => call('claim', { story, lease }),
794
+ claim: (story, lease = [], intent = null) =>
795
+ call('claim', { story, lease, ...(isIntentId(intent) ? { intent } : {}) }),
774
796
  release: (story, { merged = false } = {}) => call('release', { story, merged }),
775
797
  state: ({ fresh = false } = {}) => {
776
798
  const s = call('state', { fresh });