@warren-dean/code-kit 0.28.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,7 +9,7 @@
9
9
  "name": "code-kit",
10
10
  "source": "./",
11
11
  "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
12
- "version": "0.28.0",
12
+ "version": "0.29.0",
13
13
  "category": "development",
14
14
  "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
15
15
  "license": "MIT"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "code-kit",
3
- "version": "0.28.0",
3
+ "version": "0.29.0",
4
4
  "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
5
5
  "author": {
6
6
  "name": "Warren Langeveldt"
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
4
4
 
5
+ ## 0.29.0 (2026-10-31)
6
+
7
+ A team provider's drift findings can hold a merge, and what a project reports covers models, security reviews, intents' pull requests and claims (report version 6).
8
+
9
+ - **Drift holds a merge (spec 21, HUBR-9).** Where a team's hosted provider checks each push for drift and its setting says what blocks a merge (a finding against a spec or decision, any finding, or nothing), the merge queue holds a branch while the provider has an open finding on it at that level, and goes on with the next. `code-kit queue`, `queue merge`, `merge` and `next` name the finding, say the tech lead decides, and how it clears: resolved on the provider, or a push the drift check no longer finds conflicting. The band offers no Merge for a held branch and says why. GitHub alone checks no drift, so it never holds; a provider that can't be reached holds nothing, and code-kit says drift wasn't checked.
10
+ - **What a project reports (report version 6, spec 21).** Each usage row now names the model its requests ran on. Each story whose branch needs the security review says why (the kinds of change), whether the security reviewer ran, when, and what it found, as counts of findings and blockers only. Each intent a story's claim carries out has that story's open pull request, and whether it's a draft. The team's claims are reported with when each was taken and last renewed (claimed again, its lease grown or its branch pushed), and whether it's stale; no claim renews on a schedule. A report from an older code-kit is still valid.
11
+ - **Intents and claims.** `code-kit team claim <story> --intent <number>` records the intent a story carries out on its claim; a claim again keeps it. The dispatch skill does this when it starts an intent's work.
12
+ - **The security reviewer's findings** are recorded in the story's event log as it stops, whether the lead waited on it or it ran in the background, so the review shows as run, with what it found.
13
+
5
14
  ## 0.28.0 (2026-10-31)
6
15
 
7
16
  What a project reports to a team provider now covers its outcomes, who approved what, its designs and the sessions at work (report version 5).
package/README.md CHANGED
@@ -413,7 +413,8 @@ Spec: `docs/specs/23-the-team.md`.
413
413
 
414
414
  For several people in one repository, each with their own agents. Not every developer works in a team, so it's off until you set it up: `/code-kit:init` asks whether others work in the repository, and `/code-kit:team-init` sets the team up (or changes it, or takes it out) at any time, asking for the tech lead and each lane's owners and showing what it writes first. Everything goes through GitHub; there's no server:
415
415
 
416
- - **Owners and claims.** A lane's owners are the only ones whose agents work it. Making a story's branch claims the story, through a ref in the shared repository, so two people can't both take it. The lead says what files the story will change (`team claim --lease`), and each commit adds what it changed; another person's agent editing a leased file is refused with who holds it.
416
+ - **Owners and claims.** A lane's owners are the only ones whose agents work it. Making a story's branch claims the story, through a ref in the shared repository, so two people can't both take it. The lead says what files the story will change (`team claim --lease`), and each commit adds what it changed; another person's agent editing a leased file is refused with who holds it. A story that carries out an intent says so on its claim (`team claim --intent`).
417
+ - **Drift holds a merge.** With a hosted provider that checks each push for drift, and whose setting says what blocks a merge (a finding against a spec or decision, any finding, or nothing), the merge queue holds a branch while it has an open finding at that level. `queue`, `queue merge` and `next` say which finding, that the tech lead decides, and how it clears: resolved on the provider, or a push the drift check no longer finds conflicting. GitHub alone checks no drift, so it never holds; a provider that can't be reached holds nothing, and code-kit says so.
417
418
  - **The tech lead's paths.** Only the tech lead's sessions change the plan, specs and contracts. Anyone else raises an **intent** (`code-kit intend`), a discussion in the repository's Intents category, before any code. The tech lead agrees, drops or marks it a duplicate; an agreed one becomes a numbered decision record (`code-kit intend record`) through a pull request, where every agent reads it.
418
419
  - **Since you last looked.** `code-kit team since` says, by person, what was pushed, opened, merged, reviewed, claimed and intended. The Team pane shows it.
419
420
  - **`/team`** opens the Team pane: the tech lead, who you are, and what coordinates the team (GitHub, or a hosted provider, and whether it's live). Its tabs: **People**, each person with their lanes, where they're at work (with a live provider), claims, pull requests and intents; **Since you looked**; **Claims**, with Keep and Release on yours, and Release and Reassign for the tech lead; **Intents**, with Agree and Drop for the tech lead; **Drift**, when the provider checks for it; and **Setup**, the team's config and what GitHub still needs.
@@ -488,11 +489,11 @@ code-kit lanes [--json] # what each lane is
488
489
  code-kit lanes release <lane> # free a lane whose agent stopped without finishing
489
490
  code-kit settings [--json] # the harness settings in force, with their defaults, and who decides each approval
490
491
  code-kit settings set <key> <value> --reason "…" # change one, as the person (approvals.<name> lead|person among them): written to the config and logged as a kit approval
491
- code-kit queue [--json] # the merge queue: branches whose review passed, in order
492
+ code-kit queue [--json] # the merge queue: branches whose review passed, in order, and any a team provider's open drift finding holds
492
493
  code-kit queue add|drop <branch> # the lead queues a branch at the commit its review passed, or takes it out
493
494
  code-kit queue add <branch> --with <branch>[,<branch>] # a branch that only lands together with others: merged as a group once all are queued
494
495
  code-kit queue rules # the lead puts the approved rules onto a base that has none yet (a project set up before 0.8.0)
495
- code-kit queue merge --delegated|--person # merge the head at the commit its review passed, verified against the base as it is now; a conflict or failed verify sends it back to its lane, and a branch that moved since its review leaves the queue to be reviewed again
496
+ code-kit queue merge --delegated|--person # merge the head at the commit its review passed, verified against the base as it is now; a conflict or failed verify sends it back to its lane, a branch that moved since its review leaves the queue to be reviewed again, and one a team provider's open drift finding holds waits in its place until the finding clears
496
497
  code-kit loop [--json] # whether the person paused the lead loop; other tools' background work pauses with it
497
498
  code-kit loop pause|resume # the person's act, as Pause and Resume in the band
498
499
  code-kit loop lead|release --session <id> [--take] # which session runs the loop: the mod's, and Lead from here in the band
@@ -502,7 +503,7 @@ code-kit journal [--json] # the build's line
502
503
  code-kit team [--json] [--fresh] # the team (preview): tech lead, owners, claims, intents and open pull requests (spec 16)
503
504
  code-kit team since [--json] [--peek] # what everyone pushed, opened, merged, reviewed, claimed and intended since you last looked
504
505
  code-kit team init --tech-lead <handle> [--owner <lane>=<handles>] [--stale-days n] [--intents category] [--write] | team init --off [--write] # show, then write, the team's setup; or make the project one developer's again
505
- code-kit team claim <story> [--lease globs] | team release <story> # claim a story for yourself, leasing what it changes; release it (yours, or any as the tech lead)
506
+ code-kit team claim <story> [--lease globs] [--intent n] | team release <story> # claim a story for yourself, leasing what it changes and naming the intent it carries out; release it (yours, or any as the tech lead)
506
507
  code-kit team keep <story> | team reassign <story> <handle> # keep your stale claim (its clock starts again); the tech lead hands a claim to someone else
507
508
  code-kit team codeowners [--write] # .github/CODEOWNERS from the config: the tech lead for their paths, each lane's owners for its paths
508
509
  code-kit team board # mirror the plan onto the team's GitHub Project: each story with Lane, Claimed by, Stale and State
package/bin/code-kit.mjs CHANGED
@@ -150,6 +150,7 @@ import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/har
150
150
  import { claimLead, readLoop, releaseLead, writeLoop } from '../hooks/lib/loop-state.mjs';
151
151
  import {
152
152
  claimChanges,
153
+ isIntentId,
153
154
  storyOfBranch,
154
155
  syncBoard,
155
156
  readCache,
@@ -158,7 +159,14 @@ import {
158
159
  teamProvider,
159
160
  whoami,
160
161
  } from '../hooks/lib/team.mjs';
161
- import { codeowners, decisionRecord, slugOf } from '../hooks/lib/teamfacts.mjs';
162
+ import {
163
+ codeowners,
164
+ decisionRecord,
165
+ driftHoldWords,
166
+ driftHolds,
167
+ driftUnchecked,
168
+ slugOf,
169
+ } from '../hooks/lib/teamfacts.mjs';
162
170
  import {
163
171
  APPROVAL_MINUTES,
164
172
  approvalLifetime,
@@ -255,6 +263,7 @@ const actGiven = option('--act');
255
263
  const foundGiven = option('--found');
256
264
  const howGiven = option('--how');
257
265
  const leaseGiven = option('--lease');
266
+ const intentGiven = option('--intent');
258
267
  const touchesGiven = option('--touches');
259
268
  const techLeadGiven = option('--tech-lead');
260
269
  const staleDaysGiven = option('--stale-days');
@@ -698,14 +707,41 @@ function publish() {
698
707
  out(publishAfter(config, byPerson).trim());
699
708
  }
700
709
 
710
+ /**
711
+ * HUBR-9: the team provider's word on drift for `branches`: which its open findings hold (`holds`,
712
+ * Map(branch → findings)), why in words (`words(branch, findings)`), and `note`, that nothing was
713
+ * checked, when it didn't answer. `fresh` asks it now, as a merge does; otherwise its state as last read,
714
+ * as the queue's list and `next` do. GitHub's provider checks no drift, so it's never asked.
715
+ */
716
+ function driftNow(config, branches, { fresh = false } = {}) {
717
+ const none = { holds: new Map(), note: null, words: () => '' };
718
+ const team = teamOf(config);
719
+ if (!team || team.provider === 'github' || !branches.length) return none;
720
+ const root = resolve('.');
721
+ const state = fresh ? teamProvider(root, team).state({ fresh: true }) : readCache(root);
722
+ if (!state && !fresh) return none;
723
+ return {
724
+ holds: driftHolds(state, branches),
725
+ note: driftUnchecked(state),
726
+ words: (branch, findings) =>
727
+ driftHoldWords(branch, findings, {
728
+ techLead: team.techLead,
729
+ provider: state?.provider?.name ?? team.provider.name ?? null,
730
+ }),
731
+ };
732
+ }
733
+
701
734
  function merge(branch) {
702
735
  const { config } = load();
703
736
  const byPerson = mergeMode();
737
+ const drift = driftNow(config, [branch], { fresh: true });
738
+ const findings = drift.holds.get(branch);
739
+ if (findings) die(`Nothing was merged. ${drift.words(branch, findings)}`);
704
740
  try {
705
741
  const { message } = mergeOne(branch, config, byPerson);
706
742
  // A branch merged outside the queue leaves it too, as one the queue merged would.
707
743
  settle(resolve('.'), branch, 'merged');
708
- out(`${message}${publishAfter(config, byPerson)}`);
744
+ out(`${message}${publishAfter(config, byPerson)}${drift.note ? ` ${drift.note}` : ''}`);
709
745
  } catch (e) {
710
746
  if (e instanceof MergeStop) die(e.message);
711
747
  throw e;
@@ -984,11 +1020,24 @@ function queue() {
984
1020
  const entries = readQueue(root);
985
1021
  if (!waiting(entries).length) return out('The merge queue is empty.');
986
1022
  // 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)
1023
+ // HUBR-9: and one the team provider's drift findings hold waits until they clear.
1024
+ const drift = driftNow(
1025
+ config,
1026
+ waiting(entries).map((e) => e.branch),
1027
+ { fresh: true },
1028
+ );
1029
+ const { head, partners, held, drifting } = nextToMerge(entries, drift.holds);
1030
+ const holding = drifting.map((d) => drift.words(d.branch, d.findings));
1031
+ const unchecked = drift.note ? ` ${drift.note}` : '';
1032
+ if (!head) {
1033
+ const waits = held.map(
1034
+ (h) =>
1035
+ `${h.branch} merges together with ${h.missing.join(', ')}, which ${h.missing.length === 1 ? "isn't" : "aren't"} queued yet`,
1036
+ );
989
1037
  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('; ')}.`,
1038
+ `Nothing can merge yet${waits.length ? `: ${waits.join('; ')}.` : '.'}${holding.length ? ` ${holding.join(' ')}` : ''}`,
991
1039
  );
1040
+ }
992
1041
  const group = [head, ...partners];
993
1042
  // One merge at a time: a second run while the first verifies would merge the same head twice.
994
1043
  if (mergingNow(head))
@@ -1024,7 +1073,7 @@ function queue() {
1024
1073
  const published = publishAfter(config, byPerson);
1025
1074
  const left = waiting(readQueue(root));
1026
1075
  return out(
1027
- `${message}${published}${left.length ? ` Next in the queue: ${left[0].branch}.` : ' The queue is empty.'}`,
1076
+ `${message}${published}${left.length ? ` Next in the queue: ${left[0].branch}.` : ' The queue is empty.'}${holding.length ? ` ${holding.join(' ')}` : ''}${unchecked}`,
1028
1077
  );
1029
1078
  } catch (e) {
1030
1079
  if (!(e instanceof MergeStop)) throw e;
@@ -1062,15 +1111,33 @@ function queue() {
1062
1111
  'code-kit queue [--json] | queue add <branch> [--with <branch>,…] | queue drop <branch> | queue rules | queue merge --delegated|--person',
1063
1112
  );
1064
1113
  const entries = readQueue(root);
1065
- if (flag('--json')) return out(JSON.stringify(entries, null, 2));
1066
1114
  const left = waiting(entries);
1115
+ // HUBR-9: what the team provider's findings hold, as last read (a merge asks it again).
1116
+ const drift = driftNow(
1117
+ config,
1118
+ left.map((e) => e.branch),
1119
+ );
1120
+ if (flag('--json'))
1121
+ return out(
1122
+ JSON.stringify(
1123
+ entries.map((e) =>
1124
+ left.includes(e) && drift.holds.has(e.branch)
1125
+ ? { ...e, drift: drift.holds.get(e.branch) }
1126
+ : e,
1127
+ ),
1128
+ null,
1129
+ 2,
1130
+ ),
1131
+ );
1067
1132
  if (!left.length) out('The merge queue is empty.');
1068
1133
  else out(`${left.length} waiting to merge, in order:`);
1069
1134
  left.forEach((e, i) =>
1070
1135
  out(
1071
- ` ${i + 1}. ${e.branch} (passed review ${e.passed}${e.commit ? ` at ${e.commit.slice(0, 7)}` : ''})`,
1136
+ ` ${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' : ''}`,
1072
1137
  ),
1073
1138
  );
1139
+ for (const [branch, findings] of drift.holds) out(drift.words(branch, findings));
1140
+ if (left.length && drift.note) out(drift.note);
1074
1141
  }
1075
1142
 
1076
1143
  /**
@@ -2104,16 +2171,22 @@ function teamCommand() {
2104
2171
  const holderWords = (h) =>
2105
2172
  `${h.story} is claimed by ${h.by} (${ago(h.at)}). Ask them, or the tech lead (${team.techLead}), to release it.`;
2106
2173
  if (sub === 'claim') {
2107
- if (!story) die('code-kit team claim <story> [--lease "<glob>,<glob>"]');
2174
+ if (!story) die('code-kit team claim <story> [--lease "<glob>,<glob>"] [--intent <number>]');
2108
2175
  const lease = (leaseGiven ?? '')
2109
2176
  .split(',')
2110
2177
  .map((g) => g.trim())
2111
2178
  .filter(Boolean);
2112
- const r = provider.claim(story, lease);
2179
+ // HUBR-2: the intent this story carries out, so its pull request is the intent's.
2180
+ const intent = intentGiven === undefined ? null : Number(intentGiven.replace(/^#/, ''));
2181
+ if (intentGiven !== undefined && !isIntentId(intent))
2182
+ die(
2183
+ `"${intentGiven}" isn't an intent's number: give it as code-kit intend printed it (#12).`,
2184
+ );
2185
+ const r = provider.claim(story, lease, intent);
2113
2186
  if (r.holder) die(holderWords(r.holder));
2114
2187
  if (!r.ok) die(r.why);
2115
2188
  return out(
2116
- `Claimed ${story} as ${r.claim.by}${lease.length ? `, leasing ${lease.join(', ')}` : ''}.`,
2189
+ `Claimed ${story} as ${r.claim.by}${lease.length ? `, leasing ${lease.join(', ')}` : ''}${intent ? `, carrying out intent #${intent}` : ''}.`,
2117
2190
  );
2118
2191
  }
2119
2192
  // TEAM-12: the plan mirrored onto the team's GitHub Project.
@@ -2234,7 +2307,7 @@ function teamCommand() {
2234
2307
  out(state.claims.length ? 'Claims:' : 'Nothing is claimed.');
2235
2308
  for (const c of state.claims)
2236
2309
  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(', ')}` : ''}`,
2310
+ ` ${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
2311
  );
2239
2312
  if (state.intents.length) out('Intents:');
2240
2313
  for (const i of state.intents)
@@ -2257,13 +2330,14 @@ function snapshotNow(team) {
2257
2330
  if (!config.docs?.specs || !config.docs?.plan) return null;
2258
2331
  const from = base(config, false);
2259
2332
  const status = buildStatus('.', config, from, tracked());
2260
- const claims = (readCache(resolve('.')) ?? {}).claims ?? [];
2333
+ const { claims = [], pulls = [] } = readCache(resolve('.')) ?? {};
2261
2334
  return buildSnapshot({
2262
2335
  root: resolve('.'),
2263
2336
  config,
2264
2337
  status,
2265
2338
  base: from,
2266
2339
  claims,
2340
+ pulls,
2267
2341
  version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
2268
2342
  });
2269
2343
  }
package/hooks/act.mjs CHANGED
@@ -1,7 +1,7 @@
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
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
4
+ // an API error, and the security reviewer's findings, on the story it reviewed (HUBR-2). It never blocks a call (DUR-2): it runs in the background (`async` in hooks.json), so
5
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';
@@ -9,14 +9,17 @@ import { basename, dirname, isAbsolute, join, relative } from 'node:path';
9
9
  import { apiStopOf, start } from './lib/hook.mjs';
10
10
  import { actorFor, currentBranch, sessionRoot } from './lib/rules.mjs';
11
11
  import {
12
+ agentIdOf,
12
13
  classify,
13
14
  headOf,
14
15
  recordEnd,
15
16
  recordNote,
16
17
  recordStart,
17
18
  resultOf,
19
+ securityReviewFor,
18
20
  storyOf,
19
21
  } from './lib/events.mjs';
22
+ import { isSecurityReviewer, securityOutcome } from './lib/security.mjs';
20
23
 
21
24
  const mode = process.argv[2];
22
25
 
@@ -53,6 +56,21 @@ try {
53
56
  }
54
57
  const who = actor.kind === 'lane' ? actor.lane : actor.kind === 'lead' ? 'lead' : actor.label;
55
58
  const ctx = { session: input.session_id ?? null, agent: input.agent_id ?? null, actor: who };
59
+ if (mode === 'handback' && isSecurityReviewer(input.agent_type)) {
60
+ // HUBR-2: the security review that ran, on the story it was started for, with what it found.
61
+ const review = securityReviewFor(root, input.agent_id ?? null);
62
+ if (review)
63
+ recordNote(root, {
64
+ ...ctx,
65
+ act: review.act,
66
+ story: review.story,
67
+ branch: review.branch,
68
+ kind: 'security-review',
69
+ agentType: input.agent_type,
70
+ result: securityOutcome(input.last_assistant_message) ?? { unread: true },
71
+ });
72
+ process.exit(0);
73
+ }
56
74
  if (mode === 'handback') {
57
75
  const story = storyOf({ kind: 'handback', target: '', branch }).story;
58
76
  // An agent Claude's API stopped (its usage limit) didn't hand back: it stopped, mid-story.
@@ -71,6 +89,9 @@ try {
71
89
  const { kind, target } = classify(input.tool_name, input.tool_input, config);
72
90
  const shown = kind === 'edit' || kind === 'read' ? inRoot(root, target) : target;
73
91
  const { story, branch: storyBranch } = storyOf({ kind, target: shown, branch, root });
92
+ const started = ['Agent', 'Task'].includes(input.tool_name)
93
+ ? (input.tool_input?.subagent_type ?? null)
94
+ : null;
74
95
  const act = {
75
96
  ...ctx,
76
97
  act: input.tool_use_id ?? null,
@@ -79,9 +100,16 @@ try {
79
100
  target: shown,
80
101
  branch: storyBranch ?? branch,
81
102
  head: headOf(root),
103
+ agentType: started,
82
104
  };
105
+ // A security reviewer started in the background: its id, so its findings find this review as it stops.
106
+ const launched = isSecurityReviewer(started) ? agentIdOf(input.tool_response) : null;
83
107
  if (mode === 'start') recordStart(root, act);
84
- else if (mode === 'end') recordEnd(root, act, resultOf(kind, null, root));
108
+ else if (mode === 'end')
109
+ recordEnd(root, act, {
110
+ ...resultOf(kind, null, root),
111
+ ...(launched ? { agent: launched } : {}),
112
+ });
85
113
  else if (mode === 'fail') recordEnd(root, act, resultOf(kind, input.error ?? 'failed', root));
86
114
  } catch (e) {
87
115
  // DUR-2: once per session, the person hears the log isn't being kept; the call goes on.
@@ -294,7 +294,13 @@ function mirrorClaim(root, op, input, result) {
294
294
  'commit-tree',
295
295
  tree,
296
296
  '-m',
297
- JSON.stringify({ story: c.story, by: c.by, at: c.at, lease: c.lease }),
297
+ JSON.stringify({
298
+ story: c.story,
299
+ by: c.by,
300
+ at: c.at,
301
+ lease: c.lease,
302
+ ...(Number.isInteger(c.intent) && c.intent > 0 ? { intent: c.intent } : {}),
303
+ }),
298
304
  ],
299
305
  { encoding: 'utf8', env },
300
306
  ).trim();
@@ -22,6 +22,7 @@ import { globToRegExp } from './glob.mjs';
22
22
  import { projectWorktrees } from './rules.mjs';
23
23
  import { readQueue, settle, waiting } from './queue.mjs';
24
24
  import { sessions } from './sessions.mjs';
25
+ import { isSecurityReviewer } from './security.mjs';
25
26
 
26
27
  export const EVENTS_DIR = '.claude/state/events';
27
28
  const OPEN_DIR = `${EVENTS_DIR}/.open`;
@@ -253,9 +254,55 @@ function base(ctx, now) {
253
254
  target: ctx.target ?? null,
254
255
  branch: ctx.branch ?? null,
255
256
  head: ctx.head ?? null,
257
+ // The agent type an Agent call starts, for the security review's record (HUBR-2).
258
+ ...(ctx.agentType ? { agentType: ctx.agentType } : {}),
256
259
  };
257
260
  }
258
261
 
262
+ /** An agent's id in a tool's response (a background agent's launch names it), or null. */
263
+ export function agentIdOf(response, depth = 0) {
264
+ if (!response || typeof response !== 'object' || depth > 4) return null;
265
+ for (const [k, v] of Object.entries(response)) {
266
+ if ((k === 'agentId' || k === 'agent_id') && typeof v === 'string' && v) return v;
267
+ const found = agentIdOf(v, depth + 1);
268
+ if (found) return found;
269
+ }
270
+ return null;
271
+ }
272
+
273
+ /**
274
+ * HUBR-2: the security review a stopping security reviewer was started for: the Agent call's end that
275
+ * named `agentId` (one run in the background), else the latest call starting a security reviewer that
276
+ * hasn't ended (one the lead waits on). Each review is recorded once; null when none is open.
277
+ */
278
+ export function securityReviewFor(root, agentId) {
279
+ let open = null;
280
+ for (const story of loggedStories(root)) {
281
+ const events = readEvents(root, story);
282
+ const done = new Set(events.filter((e) => e.kind === 'security-review').map((e) => e.act));
283
+ const ended = new Set(events.filter((e) => e.phase === 'end').map((e) => e.act));
284
+ for (const e of events) {
285
+ if (!isSecurityReviewer(e.agentType) || !e.act || done.has(e.act)) continue;
286
+ if (e.phase === 'end' && agentId && e.result?.agent === agentId) return e;
287
+ if (e.phase === 'start' && !ended.has(e.act) && (!open || e.at > open.at)) open = e;
288
+ }
289
+ }
290
+ return open;
291
+ }
292
+
293
+ /**
294
+ * HUBR-2: each story's last security review, from its log: { at, findings, blockers } or { at, unread }
295
+ * when the reviewer's report had no findings block that reads. Map(story → review).
296
+ */
297
+ export function securityReviews(root) {
298
+ const found = new Map();
299
+ for (const story of loggedStories(root))
300
+ for (const e of readEvents(root, story))
301
+ if (e.kind === 'security-review' && e.phase === 'note')
302
+ found.set(story, { at: e.at, branch: e.branch ?? null, ...(e.result ?? {}) });
303
+ return found;
304
+ }
305
+
259
306
  /** The commit a checkout is at, short; null outside git. */
260
307
  export const headOf = (cwd) => out(git(cwd, 'rev-parse', '--short', 'HEAD')) || null;
261
308
 
@@ -334,6 +381,8 @@ export function replay(events) {
334
381
  state.phase = 'stopped';
335
382
  continue;
336
383
  }
384
+ // What the security reviewer found is a record of its review, not the end of an act.
385
+ if (e.kind === 'security-review') continue;
337
386
  if (!e.act) continue;
338
387
  const act = acts.get(e.act) ?? { start: null, end: null, reconciled: null };
339
388
  acts.set(e.act, act);
@@ -19,6 +19,8 @@ import { ciFindings } from './ci.mjs';
19
19
  import { storyModels } from './dispatches.mjs';
20
20
  import { pickPerLane } from './schedule.mjs';
21
21
  import { reconcileAll } from './events.mjs';
22
+ import { readCache, teamOf } from './team.mjs';
23
+ import { driftHoldWords, driftHolds, driftUnchecked } from './teamfacts.mjs';
22
24
 
23
25
  export const DRAFT_FILE = '.claude/code-kit.draft.json';
24
26
  export const BRIEF_STATES = ['framed', 'explored', 'scoped', 'specified', 'planned', 'ready'];
@@ -276,9 +278,26 @@ export function nextStep(root, base) {
276
278
  // A branch already in the merge queue has passed its review: it isn't reviewed again.
277
279
  const entries = readQueue(root);
278
280
  const inQueue = waiting(entries);
281
+ // HUBR-9: the team provider's drift findings, as last read, hold the branches they're on.
282
+ const team = teamOf(config);
283
+ const teamState = team && team.provider !== 'github' && inQueue.length ? readCache(root) : null;
284
+ const drift = teamState
285
+ ? driftHolds(
286
+ teamState,
287
+ inQueue.map((e) => e.branch),
288
+ )
289
+ : new Map();
279
290
  // MQ-7: what can merge next; a branch queued with partners waits until they're queued too.
280
- const { head: mergeHead, held: heldGroups } = nextToMerge(entries);
291
+ const { head: mergeHead, held: heldGroups, drifting } = nextToMerge(entries, drift);
281
292
  const queued = inQueue.map((e) => e.branch);
293
+ const driftWords = drifting.map((d) =>
294
+ driftHoldWords(d.branch, d.findings, {
295
+ techLead: team?.techLead,
296
+ provider: teamState?.provider?.name ?? team?.provider?.name ?? null,
297
+ }),
298
+ );
299
+ const driftNote = teamState ? driftUnchecked(teamState) : null;
300
+ const heldByDrift = new Set(drifting.map((d) => d.branch));
282
301
  // MQ-1: a queue merge running now (its verify takes minutes) isn't asked for again.
283
302
  const merging = mergingNow(inQueue[0]) ? inQueue[0].branch : null;
284
303
  const ids = (state) =>
@@ -374,10 +393,13 @@ export function nextStep(root, base) {
374
393
  `${queued[0]} passed review and is next to merge, but ${delegation.into} has no code-kit rules committed yet. Put the rules the person approved onto it (code-kit queue rules); then the queue merges under them.`,
375
394
  { args: delegation.into },
376
395
  );
377
- if (queued.length && !leadMerges)
396
+ const mergeable = queued.filter((b) => !heldByDrift.has(b));
397
+ if (mergeable.length && !leadMerges)
378
398
  attention.push(
379
- `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} for the person to merge (code-kit queue merge --person, or Merge in the code-kit band).`,
399
+ `${mergeable.join(', ')} passed review and ${mergeable.length === 1 ? 'waits' : 'wait'} for the person to merge (code-kit queue merge --person, or Merge in the code-kit band).`,
380
400
  );
401
+ attention.push(...driftWords);
402
+ if (driftNote) attention.push(driftNote);
381
403
  if (merging)
382
404
  attention.push(
383
405
  `${merging} is being merged now (queue merge is running); it says when it's done.`,
@@ -485,11 +507,15 @@ export function nextStep(root, base) {
485
507
  'wait',
486
508
  `${building.join(', ')} ${building.length === 1 ? 'is' : 'are'} being built; nothing else can start until one finishes. A lane that stopped without finishing is dispatched again.`,
487
509
  );
488
- // Stories waiting on branches in the merge queue wait for the merge, not on a broken plan.
510
+ // Stories waiting on branches in the merge queue wait for the merge, not on a broken plan. HUBR-9: a
511
+ // queue that only drift findings hold says which, and how each clears.
512
+ const heldOnly = !mergeHead && driftWords.length ? driftWords.join(' ') : null;
489
513
  if (queued.length)
490
514
  return result(
491
515
  'wait',
492
- `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} to be merged; the stories that depend on ${queued.length === 1 ? 'it' : 'them'} start after.`,
516
+ heldOnly
517
+ ? `${heldOnly} The stories that depend on ${queued.length === 1 ? 'it' : 'them'} start after.`
518
+ : `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} to be merged; the stories that depend on ${queued.length === 1 ? 'it' : 'them'} start after.`,
493
519
  );
494
520
  if (unbuildable.length)
495
521
  return result(
@@ -510,7 +536,7 @@ export function nextStep(root, base) {
510
536
  if (queued.length)
511
537
  return result(
512
538
  'wait',
513
- `${queued.join(', ')} ${queued.length === 1 ? 'waits' : 'wait'} to be merged.`,
539
+ heldOnly ?? `${queued.join(', ')} ${queued.length === 1 ? 'waits' : 'wait'} to be merged.`,
514
540
  );
515
541
  return result(
516
542
  'done',
@@ -121,10 +121,12 @@ export function mergingNow(entry) {
121
121
  /**
122
122
  * MQ-7: what the queue merges next. A branch queued `with` others merges only together with them, once
123
123
  * each is queued too: verified as one tree, merged one after another. Until then it waits, and the
124
- * queue goes on with the next. `{ head, partners, held }`: `head` null when nothing can merge yet;
125
- * `held` lists each waiting branch with the partners it still needs queued.
124
+ * queue goes on with the next. HUBR-9: a branch the team provider's drift findings hold (`drift`,
125
+ * Map(branch → findings), from `driftHolds`) waits too, with its group, until they clear. `{ head,
126
+ * partners, held, drifting }`: `head` null when nothing can merge yet; `held` lists each waiting branch
127
+ * with the partners it still needs queued; `drifting` each one waiting on findings, with them.
126
128
  */
127
- export function nextToMerge(entries) {
129
+ export function nextToMerge(entries, drift = new Map()) {
128
130
  const queue = waiting(entries);
129
131
  const queued = new Set(queue.map((e) => e.branch));
130
132
  // A partner already merged on its own is no longer waited for.
@@ -148,8 +150,15 @@ export function nextToMerge(entries) {
148
150
  return group;
149
151
  };
150
152
  const held = [];
153
+ const drifting = [];
154
+ let head = null;
155
+ let partners = [];
151
156
  for (const e of queue) {
152
157
  const group = groupOf(e);
158
+ // A group lands as one, so a finding on any of its branches holds them all.
159
+ const findings = [...group].flatMap((b) => drift.get(b) ?? []);
160
+ if (findings.length) drifting.push({ branch: e.branch, findings });
161
+ if (head) continue;
153
162
  const missing = [...group]
154
163
  .flatMap((b) => queue.find((y) => y.branch === b)?.with ?? [])
155
164
  .filter((b) => !queued.has(b) && !merged.has(b));
@@ -157,10 +166,11 @@ export function nextToMerge(entries) {
157
166
  held.push({ branch: e.branch, missing: [...new Set(missing)] });
158
167
  continue;
159
168
  }
160
- const partners = queue.filter((x) => x.branch !== e.branch && group.has(x.branch));
161
- return { head: e, partners, held };
169
+ if (findings.length) continue;
170
+ head = e;
171
+ partners = queue.filter((x) => x.branch !== e.branch && group.has(x.branch));
162
172
  }
163
- return { head: null, partners: [], held };
173
+ return { head, partners, held, drifting };
164
174
  }
165
175
 
166
176
  /** MQ-7: a queued branch's partners, which it merges together with. */
@@ -13,6 +13,34 @@ import { storyOfBranch } from './teamfacts.mjs';
13
13
  export const SECURITY_AGENT = 'security-reviewer';
14
14
  export const SECURITY_AGENT_FILE = `.claude/agents/${SECURITY_AGENT}.md`;
15
15
 
16
+ /** Whether an agent type is the security reviewer: the project's, or a plugin's (`<plugin>:security-reviewer`). */
17
+ export const isSecurityReviewer = (type) =>
18
+ new RegExp(`(^|:)${SECURITY_AGENT}$`).test(String(type ?? ''));
19
+
20
+ const GRADES = ['blocker', 'concern', 'nit'];
21
+
22
+ /**
23
+ * HUBR-2: what the security reviewer's report found, from its last fenced json block (its template's
24
+ * `{"findings": [...]}`): { findings, blockers }, the findings graded blocker, concern or nit counted, or
25
+ * null when the report has no block that reads.
26
+ */
27
+ export function securityOutcome(report) {
28
+ const blocks = [...String(report ?? '').matchAll(/```json\s*\n([\s\S]*?)```/g)];
29
+ if (!blocks.length) return null;
30
+ let data;
31
+ try {
32
+ data = JSON.parse(blocks.at(-1)[1]);
33
+ } catch {
34
+ return null;
35
+ }
36
+ if (!Array.isArray(data?.findings)) return null;
37
+ const graded = data.findings.filter((f) => GRADES.includes(f?.severity));
38
+ return {
39
+ findings: graded.length,
40
+ blockers: graded.filter((f) => f.severity === 'blocker').length,
41
+ };
42
+ }
43
+
16
44
  // Tests, docs and design files describe the change; the review looks at the code that ships.
17
45
  const NOT_SHIPPED =
18
46
  /(^|\/)(tests?|__tests__|e2e|docs?|design)\/|\.(test|spec|stories)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$|\.(md|mdx|txt|png|jpe?g|gif|svg|webp)$/i;
@@ -13,9 +13,10 @@ import { readQueue, waiting } from './queue.mjs';
13
13
  import { sendBacks } from './reviews.mjs';
14
14
  import { readMilestones, readSpecs, specCheckRows } from './plan.mjs';
15
15
  import { handedOver, entryProblems, readRegister, toolOf } from './designs.mjs';
16
- import { SECURITY_KINDS, securityRules } from './security.mjs';
16
+ import { SECURITY_KINDS, securityReview, securityRules } from './security.mjs';
17
+ import { securityReviews } from './events.mjs';
17
18
  import { sessions } from './sessions.mjs';
18
- import { storyOfBranch } from './teamfacts.mjs';
19
+ import { isHandle, storyOfBranch } from './teamfacts.mjs';
19
20
  import { storyTimes } from './timeline.mjs';
20
21
  import { trail } from './storymap.mjs';
21
22
  import {
@@ -36,9 +37,11 @@ import { slicesOf } from './schedule.mjs';
36
37
  * story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
37
38
  * each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
38
39
  * 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.
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.
40
43
  */
41
- export const SNAPSHOT_VERSION = 5;
44
+ export const SNAPSHOT_VERSION = 6;
42
45
 
43
46
  /** A story's stage, as a report names it. */
44
47
  export const STAGES = [
@@ -56,6 +59,8 @@ export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'ba
56
59
  export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
57
60
  /** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
58
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'];
59
64
 
60
65
  /**
61
66
  * The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
@@ -128,11 +133,34 @@ export const SNAPSHOT_SCHEMA = {
128
133
  {
129
134
  story: 'id?',
130
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?',
131
138
  input: 'count',
132
139
  output: 'count',
133
140
  cache: 'count',
134
141
  },
135
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'] }],
136
164
  rules: {
137
165
  // `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
138
166
  layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
@@ -207,6 +235,9 @@ export const LATER_PARTS = [
207
235
  'sessions',
208
236
  'rules.lanes',
209
237
  'rules.security',
238
+ 'securityReviews',
239
+ 'intents',
240
+ 'claims',
210
241
  ];
211
242
 
212
243
  export const SUMMARY_MAX = 600;
@@ -291,6 +322,8 @@ export const EVENT_PARTS = [
291
322
  'rules',
292
323
  'standards',
293
324
  'designs',
325
+ 'securityReviews',
326
+ 'intents',
294
327
  ];
295
328
 
296
329
  /** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
@@ -366,8 +399,9 @@ export function recordedUsage(root) {
366
399
  for (const e of entries) {
367
400
  if (!AGENT_KINDS.includes(e.kind)) continue;
368
401
  const story = KINDS.id(e.story) ? e.story : null;
369
- const key = `${story}|${e.kind}`;
370
- 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 };
371
405
  for (const k of ['input', 'output', 'cache'])
372
406
  was[k] += Number.isInteger(e[k]) && e[k] > 0 ? e[k] : 0;
373
407
  sums.set(key, was);
@@ -388,7 +422,8 @@ function checkedRows(root, story) {
388
422
 
389
423
  /**
390
424
  * The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
391
- * 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.
392
427
  */
393
428
  export function buildSnapshot({
394
429
  root,
@@ -396,6 +431,7 @@ export function buildSnapshot({
396
431
  status,
397
432
  base,
398
433
  claims = [],
434
+ pulls = [],
399
435
  version,
400
436
  now = Date.now(),
401
437
  }) {
@@ -547,10 +583,91 @@ export function buildSnapshot({
547
583
  standards: reportedStandards(root, config, line),
548
584
  designs: reportedDesigns(root, config),
549
585
  sessions: reportedSessions(root, now),
586
+ securityReviews: reportedSecurityReviews(root, config, status, base),
587
+ intents: reportedIntents(claims, pulls),
588
+ claims: reportedClaims(claims),
550
589
  };
551
590
  return snapshot;
552
591
  }
553
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
+
554
671
  /** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
555
672
  function worstCheck(rows) {
556
673
  if (!rows.length) return 'none';
@@ -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 });
@@ -1,5 +1,5 @@
1
- // Teams (docs/specs/16-teams.md), the pure parts: names, story branches, staleness and what an intent
2
- // touches. Shared by the hooks and CLI (team.mjs) and the mod, which runs without Node.
1
+ // Teams (docs/specs/16-teams.md), the pure parts: names, story branches, staleness, what an intent
2
+ // touches and which drift findings hold a merge (spec 21, HUBR-9). Shared by the hooks and CLI (team.mjs) and the mod, which runs without Node.
3
3
 
4
4
  /** A GitHub handle: letters, digits and single hyphens, at most 39 characters. */
5
5
  export const isHandle = (h) =>
@@ -189,3 +189,81 @@ export const boardValues = (story, claim) => ({
189
189
  /** The fields whose value changed since the last sync: [[field, value]]. */
190
190
  export const boardChanges = (before = {}, now) =>
191
191
  BOARD_FIELDS.filter((f) => (before[f] ?? '') !== now[f]).map((f) => [f, now[f]]);
192
+
193
+ // --- drift holds (spec 21, HUBR-9) ---------------------------------------------------------------------
194
+
195
+ /**
196
+ * What a team provider's "What blocks a merge" setting may say: a finding against a spec or decision,
197
+ * any finding, or nothing. A provider that says none (GitHub, or an older hosted one) holds nothing.
198
+ */
199
+ export const MERGE_HOLDS = ['spec-or-decision', 'any', 'nothing'];
200
+
201
+ /** What a drift finding is against, from its `conflictsWith`: spec, decision, branch or intent. */
202
+ export const findingKind = (f) => String(f?.conflictsWith ?? '').split(/[\s#]/)[0] || null;
203
+
204
+ /** Whether a finding holds a merge at the provider's level. Its severity doesn't change that. */
205
+ export function holdsMerge(finding, level) {
206
+ if (level === 'any') return true;
207
+ if (level === 'spec-or-decision') return ['spec', 'decision'].includes(findingKind(finding));
208
+ return false;
209
+ }
210
+
211
+ /** Whether the team's state came from its provider, not its fallback or a cache it couldn't renew. */
212
+ export const providerAnswered = (state) =>
213
+ Boolean(state) && state.reachable !== false && !state.fallback;
214
+
215
+ /**
216
+ * The open drift findings that hold `branch` in the merge queue, by the provider's state: its level
217
+ * (`mergeHolds`) and its findings. None when the provider didn't answer: code-kit doesn't hold on what
218
+ * it couldn't check (`driftUnchecked` says so).
219
+ */
220
+ export function driftHoldsOf(state, branch) {
221
+ if (!providerAnswered(state)) return [];
222
+ const level = MERGE_HOLDS.includes(state.mergeHolds) ? state.mergeHolds : 'nothing';
223
+ if (level === 'nothing') return [];
224
+ return (Array.isArray(state.findings) ? state.findings : []).filter(
225
+ (f) => f && f.branch === branch && !f.resolved && holdsMerge(f, level),
226
+ );
227
+ }
228
+
229
+ /** Each of `branches` the provider's findings hold: Map(branch → findings). */
230
+ export function driftHolds(state, branches) {
231
+ const held = new Map();
232
+ for (const b of branches) {
233
+ const found = driftHoldsOf(state, b);
234
+ if (found.length) held.set(b, found);
235
+ }
236
+ return held;
237
+ }
238
+
239
+ const against = (f) =>
240
+ findingKind(f) === 'intent' ? f.conflictsWith : `the ${f.conflictsWith ?? 'work in flight'}`;
241
+ const oneLine = (s, max = 200) =>
242
+ String(s ?? '')
243
+ .replace(/\s+/g, ' ')
244
+ .trim()
245
+ .slice(0, max);
246
+
247
+ /**
248
+ * Why a branch is held, in words an agent or person can act on: each finding, who decides, and how it
249
+ * clears. `provider` is the team provider's name as its state gives it; `techLead` the team's.
250
+ */
251
+ export function driftHoldWords(branch, findings, { techLead = null, provider = null } = {}) {
252
+ const where = provider ?? 'the team provider';
253
+ const each = findings.map(
254
+ (f) =>
255
+ `against ${against(f)}${f.severity ? ` (a ${f.severity})` : ''}: ${oneLine(f.title || f.text)}${f.url ? ` (${f.url})` : ''}`,
256
+ );
257
+ const one = each.length === 1;
258
+ const found = one
259
+ ? `the drift check found it ${each[0]}`
260
+ : `the drift check found it ${each.length} times: ${each.join('; ')}`;
261
+ return `${branch} is held from merging: ${found}. ${techLead ? `The tech lead (${techLead})` : 'The tech lead'} decides: if the work still stands, resolve ${one ? 'the finding' : 'the findings'} on ${where}; otherwise push a fix to ${branch}, and the drift check clears ${one ? 'it' : 'each'} once a push no longer conflicts. It merges as soon as nothing holds it.`;
262
+ }
263
+
264
+ /** When the provider didn't answer, that drift findings weren't checked, in words; null when they were. */
265
+ export function driftUnchecked(state) {
266
+ if (providerAnswered(state)) return null;
267
+ const why = oneLine(state?.fallback ?? state?.why ?? "The team provider can't be reached.");
268
+ return `${why.replace(/\.$/, '')}, so drift findings weren't checked: merges don't wait on them until it answers.`;
269
+ }
@@ -226,7 +226,16 @@ const URGENCY = [
226
226
  'report',
227
227
  'worktree',
228
228
  ];
229
- const NOTES = new Set(['usage', 'paused', 'finish', 'done', 'teamDown', 'elsewhere', 'loop']);
229
+ const NOTES = new Set([
230
+ 'usage',
231
+ 'paused',
232
+ 'finish',
233
+ 'done',
234
+ 'teamDown',
235
+ 'elsewhere',
236
+ 'loop',
237
+ 'drift',
238
+ ]);
230
239
 
231
240
  /** What a line is, in a word or two, for the Needs you panel. */
232
241
  const NEED_WORD = {
@@ -1261,11 +1261,12 @@ export function register(on) {
1261
1261
  $.ui.invalidate('ui.render');
1262
1262
  },
1263
1263
  // USE-1: a model request's tokens, put down to the agent that made it and its story and lane.
1264
- measure: async (agentId, usage) => {
1264
+ measure: async (agentId, usage, ranOn = null) => {
1265
1265
  if (agentId && !agentsSeen.has(agentId))
1266
1266
  for (const a of (await $.agent.list().catch(() => [])) ?? []) agentsSeen.set(a.id, a);
1267
1267
  const who = attribution(agentId, agentsSeen.get(agentId) ?? null, model.check, model.state);
1268
- ledger = withUsage(ledger, who, usage);
1268
+ // HUBR-2, report version 6: by the model the request ran on, as the step names it.
1269
+ ledger = withUsage(ledger, who, usage, ranOn);
1269
1270
  $.ui.invalidate('ui.render');
1270
1271
  // LEAN-5: a lane agent past its context limit is told to wrap up; its story goes on fresh.
1271
1272
  const limit = harness().agents.lanes.contextLimit;
@@ -2436,7 +2437,7 @@ export function register(on) {
2436
2437
  on('turn.step', async function* ($, e, next) {
2437
2438
  const res = yield* next(e);
2438
2439
  if (e.agentId) activityOf(e.agentId, 0).at = await $.clock.now();
2439
- if (res?.usage && act) await act.measure(e.agentId, res.usage).catch(() => {});
2440
+ if (res?.usage && act) await act.measure(e.agentId, res.usage, e.model).catch(() => {});
2440
2441
  return res;
2441
2442
  });
2442
2443
  // USE-4: the plan's 5-hour use, as Claude Code measures it.
@@ -455,8 +455,16 @@ export function bandLines({
455
455
  text: `background agents paused: plan at ${plan.percent}%`,
456
456
  actions: [],
457
457
  });
458
- // MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge.
459
- const next = queue.find((e) => ['waiting', 'merging'].includes(e.state));
458
+ // MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge. HUBR-9: a
459
+ // branch the team provider's drift findings hold (`drift`, from `queue --json`) isn't offered; it's said.
460
+ const inQueue = queue.filter((e) => ['waiting', 'merging'].includes(e.state));
461
+ const next = inQueue.find((e) => !e.drift?.length);
462
+ for (const e of inQueue.filter((x) => x.drift?.length && !working))
463
+ lines.push({
464
+ kind: 'drift',
465
+ text: `${e.branch} is held by the drift check: ${e.drift[0].title || e.drift[0].conflictsWith}`,
466
+ actions: [],
467
+ });
460
468
  const autonomous = (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
461
469
  // SETUP-2: with no rules on the base yet, the lead puts them there first and then merges.
462
470
  const leadMerges = autonomous && (check?.delegatesMerge || check?.firstMerge);
@@ -1159,11 +1167,15 @@ export function attribution(agentId, agent, check, state) {
1159
1167
  return { key: agentId, lane, story: named ?? laneStory(lane), background: false };
1160
1168
  }
1161
1169
 
1162
- /** The ledger with one request added: entries by agent and story, their tokens summed. */
1163
- export function withUsage(ledger, who, usage) {
1164
- const id = `${who.key}|${who.story ?? ''}`;
1170
+ /**
1171
+ * The ledger with one request added: entries by agent, story and the model the request ran on (as
1172
+ * Claude Code names it on the step), their tokens summed.
1173
+ */
1174
+ export function withUsage(ledger, who, usage, model = null) {
1175
+ const named = typeof model === 'string' && model && !/[\r\n]/.test(model) ? model : null;
1176
+ const id = `${who.key}|${who.story ?? ''}${named ? `|${named}` : ''}`;
1165
1177
  const t = tokensOf(usage);
1166
- const was = ledger[id] ?? { ...who, input: 0, output: 0, cache: 0 };
1178
+ const was = ledger[id] ?? { ...who, model: named, input: 0, output: 0, cache: 0 };
1167
1179
  return {
1168
1180
  ...ledger,
1169
1181
  [id]: {
@@ -1176,9 +1188,9 @@ export function withUsage(ledger, who, usage) {
1176
1188
  }
1177
1189
 
1178
1190
  /**
1179
- * HUBR-2: the ledger as a report carries it: [{ story, kind, input, output, cache }], each entry's kind
1180
- * (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the agent's
1181
- * type. Tokens only: no prompt, no message.
1191
+ * HUBR-2: the ledger as a report carries it: [{ story, kind, model, input, output, cache }], each entry's
1192
+ * kind (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the
1193
+ * agent's type, and the model its requests ran on (report version 6). Tokens only: no prompt, no message.
1182
1194
  */
1183
1195
  export function usageForReport(ledger, typeOf = () => null) {
1184
1196
  return Object.fromEntries(
@@ -1196,7 +1208,14 @@ export function usageForReport(ledger, typeOf = () => null) {
1196
1208
  : 'background';
1197
1209
  return [
1198
1210
  id,
1199
- { story: e.story ?? null, kind, input: e.input, output: e.output, cache: e.cache },
1211
+ {
1212
+ story: e.story ?? null,
1213
+ kind,
1214
+ model: e.model ?? null,
1215
+ input: e.input,
1216
+ output: e.output,
1217
+ cache: e.cache,
1218
+ },
1200
1219
  ];
1201
1220
  }),
1202
1221
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.28.0",
3
+ "version": "0.29.0",
4
4
  "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
5
5
  "license": "MIT",
6
6
  "author": "Warren Langeveldt",
@@ -46,7 +46,7 @@ Commit everything the lanes need first. Each lane branches from the lead's branc
46
46
  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,<glob>"
47
47
  ```
48
48
 
49
- The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
49
+ When the story carries out an intent the team agreed (`code-kit intend`), add `--intent <its number>`, so the team sees which pull request is the intent's. The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
50
50
 
51
51
  One agent per story: never send a running lane agent a second story, or a send-back. A story that goes on (sent back, or handed back at its context limit) gets a fresh agent: first run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" worktrees release <branch>`, which keeps the branch's commits and moves its report to the main checkout, then start the agent as below with the brief, "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout", and what `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" replay <story> --brief` prints: the story's last commit, the tests last run, what changed since, and what was reconciled, from its event log, which holds them even when the stopped agent wrote no report. A long-lived agent rereads its whole context on every step, which is most of what a build costs.
52
52
 
@@ -78,7 +78,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
78
78
  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>
79
79
  ```
80
80
 
81
- Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree. Where the base's rules set `branches.publish`, the merge also reaches the remote's base on its own: pushed, or as a pull request code-kit opens from `code-kit/publish-<base>` (and merges, where pushing the base is delegated to you). Never merge a story into another branch to get it there: `code-kit publish --delegated` tries again when GitHub held it back. A branch that breaks the base merged on its own (a new API whose callers another story updates) is queued with the branches it lands with: `queue add <branch> --with <other>`. It waits in the queue, without asking for review again, until they're reviewed and queued too, and then they're verified and merged as one.
81
+ Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree. Where the base's rules set `branches.publish`, the merge also reaches the remote's base on its own: pushed, or as a pull request code-kit opens from `code-kit/publish-<base>` (and merges, where pushing the base is delegated to you). Never merge a story into another branch to get it there: `code-kit publish --delegated` tries again when GitHub held it back. A branch that breaks the base merged on its own (a new API whose callers another story updates) is queued with the branches it lands with: `queue add <branch> --with <other>`. It waits in the queue, without asking for review again, until they're reviewed and queued too, and then they're verified and merged as one. In a team whose provider checks pushes for drift, a branch with an open finding at the level the provider's setting names waits in its place too, and the queue goes on with the next: `queue` and `next` say which finding and that the tech lead decides. It clears when the finding is resolved on the provider, or a push fixes what it found; never merge around it.
82
82
 
83
83
  - **Send back.** List each problem, where it is, and what "fixed" looks like, with the requirement or the standard's id it breaks. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
84
84