@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +9 -0
- package/README.md +5 -4
- package/bin/code-kit.mjs +87 -13
- package/hooks/act.mjs +30 -2
- package/hooks/lib/adapters/hub/client.mjs +7 -1
- package/hooks/lib/events.mjs +49 -0
- package/hooks/lib/next.mjs +32 -6
- package/hooks/lib/queue.mjs +16 -6
- package/hooks/lib/security.mjs +28 -0
- package/hooks/lib/snapshot.mjs +124 -7
- package/hooks/lib/team.mjs +35 -13
- package/hooks/lib/teamfacts.mjs +80 -2
- package/hooks/mod/board.mjs +10 -1
- package/hooks/mod/register.mjs +4 -3
- package/hooks/mod/view.mjs +29 -10
- package/package.json +1 -1
- package/skills/dispatch/SKILL.md +1 -1
- package/skills/review/SKILL.md +1 -1
|
@@ -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.
|
|
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.
|
|
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,
|
|
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 {
|
|
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
|
-
|
|
988
|
-
|
|
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
|
|
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
|
-
|
|
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 =
|
|
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')
|
|
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({
|
|
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();
|
package/hooks/lib/events.mjs
CHANGED
|
@@ -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);
|
package/hooks/lib/next.mjs
CHANGED
|
@@ -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
|
-
|
|
396
|
+
const mergeable = queued.filter((b) => !heldByDrift.has(b));
|
|
397
|
+
if (mergeable.length && !leadMerges)
|
|
378
398
|
attention.push(
|
|
379
|
-
`${
|
|
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
|
-
|
|
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',
|
package/hooks/lib/queue.mjs
CHANGED
|
@@ -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.
|
|
125
|
-
* `
|
|
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
|
-
|
|
161
|
-
|
|
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
|
|
173
|
+
return { head, partners, held, drifting };
|
|
164
174
|
}
|
|
165
175
|
|
|
166
176
|
/** MQ-7: a queued branch's partners, which it merges together with. */
|
package/hooks/lib/security.mjs
CHANGED
|
@@ -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;
|
package/hooks/lib/snapshot.mjs
CHANGED
|
@@ -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 =
|
|
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
|
|
370
|
-
const
|
|
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
|
|
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';
|
package/hooks/lib/team.mjs
CHANGED
|
@@ -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 }`).
|
|
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
|
-
? {
|
|
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
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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
|
-
|
|
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
|
|
427
|
-
const
|
|
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
|
|
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({
|
|
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 = []
|
|
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 });
|
package/hooks/lib/teamfacts.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
// Teams (docs/specs/16-teams.md), the pure parts: names, story branches, staleness
|
|
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
|
+
}
|
package/hooks/mod/board.mjs
CHANGED
|
@@ -226,7 +226,16 @@ const URGENCY = [
|
|
|
226
226
|
'report',
|
|
227
227
|
'worktree',
|
|
228
228
|
];
|
|
229
|
-
const NOTES = new Set([
|
|
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 = {
|
package/hooks/mod/register.mjs
CHANGED
|
@@ -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
|
-
|
|
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.
|
package/hooks/mod/view.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
1163
|
-
|
|
1164
|
-
|
|
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
|
|
1180
|
-
* (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the
|
|
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
|
-
{
|
|
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.
|
|
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",
|
package/skills/dispatch/SKILL.md
CHANGED
|
@@ -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
|
|
package/skills/review/SKILL.md
CHANGED
|
@@ -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
|
|