@warren-dean/code-kit 0.27.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,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.27.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.27.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,24 @@
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
+
14
+ ## 0.28.0 (2026-10-31)
15
+
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).
17
+
18
+ - **What a project reports to a team provider (report version 5, spec 21).** Beside what version 4 carries, a report now holds each spec's id, title, outcome line and requirement ids; each layer's and lane's deliverable kind; each lane's layers and paths; each approval's story, and the GitHub login of the person who gave it, when code-kit knows who was at the machine; the security review's rules; each story's spec-check result and place in the merge queue; the design register's entries; and the sessions at work, with the code-kit and model each runs, when it started and the file it last edited. Nothing else of the specs or the plan is sent: no acceptance criteria, requirement bodies or decisions. `code-kit team report --dry-run` shows it all before anything is sent. A report from an older code-kit is still valid.
19
+ - **Labels.** A layer or a lane can name what it delivers with `label` ("Screens", "API contract"). Without one, the kind is taken from its name.
20
+ - **Approvals** you give are recorded in the approval log with your GitHub login, when code-kit has it.
21
+ - **Sessions** record the model they run on (from Claude Code's session start, or the session's latest reply), the code-kit version that started them and the file they last edited. A hosted provider's presence carries the same, by path only.
22
+
5
23
  ## 0.27.0 (2026-10-30)
6
24
 
7
25
  Fixes for what projects reported: the loop respects Claude's usage limit, merges land as they were verified, claims end with their stories, and approved designs reach lanes as files.
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
@@ -535,10 +536,10 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
535
536
  | `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
536
537
  | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
537
538
  | `anyActor` | no | Paths every writer may change (e.g. the lockfile), read-only agents included. `.claude/state/**` is always included. An entry may be `{ "glob", "reviewer" }` to name the lane (or `"lead"`) that reviews changes to it; otherwise the lead reviews them, and `who` and `trace` say so. |
538
- | `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners? }`: the agent name maps a subagent to its lane; `owners` (GitHub handles) are the people whose sessions work it, in a team (needs `team`). A worktree with a `.lane` file holding the lane name makes the main session that lane. |
539
+ | `lanes.<name>` | yes (may be `{}`) | `{ agent, paths, exclude?, owners?, label? }`: the agent name maps a subagent to its lane; `label` names what the lane delivers ("Screens", "API contract"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the lane's name; `owners` (GitHub handles) are the people whose sessions work it, in a team (needs `team`). A worktree with a `.lane` file holding the lane name makes the main session that lane. |
539
540
  | `protected[]` | no | `{ glob, approval, why }`: logged on every commit. Anyone but the lead needs an approval: the lead's where `approvals.delegate.protected` names it, otherwise a person's (see [Approvals](#approvals)). `.claude/**` is always protected as `kit`. |
540
541
  | `designGate` | no | `{ register, screens: [{ glob, not? }], howTo }`: screen files wait until the register (`{ "screens": [{ "file": … }] }`) lists them. Init sets it for every lane that owns screens; `/code-kit:design` adds approved designs |
541
- | `layers[]` | no | `{ name, paths, mayImport, denyPackages? }`: the first layer whose paths match a file owns it. A layer may always import itself. |
542
+ | `layers[]` | no | `{ name, paths, mayImport, denyPackages?, label? }`: the first layer whose paths match a file owns it. A layer may always import itself. `label` names what the layer delivers ("Data", "Service"; one line, at most 60 characters), for a team provider's report, and is otherwise taken from the layer's name. |
542
543
  | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
543
544
  | `shell.block[]` | no | `{ pattern, why, person?, command? }`: never run. `person: true` marks a person's act, which the lead may do for them with `approvals.lead` on. `command: true` matches the pattern from the start of each command the line runs, so a heredoc or quoted text that mentions it isn't refused |
544
545
  | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
@@ -550,7 +551,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
550
551
  | `approvals.lead` | no | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals). |
551
552
  | `approvals.delegate` | no | `false`, or `{ protected?: [approval names], merge?: true, push?: true, tests?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`; with `push`, pushes the protected branch, never by force (yours unless you set it, since a push can deploy; read from the config committed on that branch); with `tests`, weakened tests on a lane's branch. Left out, the lead decides everything technical: every protected approval but `spec`, `design`, `ci` and `kit`, packages, merges and weakened tests (WHO-1); `false` keeps everything for you. Lanes ask the lead for these, never you. npm packages are also checked against the npm registry, and a Python lane's against PyPI; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals). |
552
553
  | `setup` | no | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it |
553
- | `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, approvals, token use and the rules; never code) to a provider that isn't GitHub. A provider may also supply an organisation's standards (`standards`, answering `{ standards, waivers, version }`, each standard in `docs.standards`' fields, each waiver `{ standard, paths?, expires?, reason?, approvedBy? }`): they apply as if in the project's file, which may extend or tighten one but weaken a required one only under a waiver. See docs/specs/16-teams.md, docs/specs/21-hub-adapter-and-reports.md and docs/specs/22-standards.md. |
554
+ | `team` | no | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, the specs' titles and outcome lines, approvals, token use, the rules, the design register and the sessions at work; never code) to a provider that isn't GitHub. A provider may also supply an organisation's standards (`standards`, answering `{ standards, waivers, version }`, each standard in `docs.standards`' fields, each waiver `{ standard, paths?, expires?, reason?, approvedBy? }`): they apply as if in the project's file, which may extend or tighten one but weaken a required one only under a waiver. See docs/specs/16-teams.md, docs/specs/21-hub-adapter-and-reports.md and docs/specs/22-standards.md. |
554
555
  | `branches.protected` | no | Default `["main", "master"]` |
555
556
  | `branches.publish` | no | How a merge reaches the remote's base: `push` (the base is pushed, fast-forward only) or `pull-request` (for a base the remote only lets change through pull requests: code-kit opens one from `code-kit/publish-<base>` after each merge, and merges it where `approvals.delegate.push` is on, otherwise it waits for you). Left out, code-kit leaves pushing the base to you |
556
557
  | `execution.unrepeatable` | no | Patterns (regular expressions) for commands that can't safely run twice, such as a seed or a deploy. With migrations, the commands `shell.block` and `shell.restricted` name, and `git push`, an interrupted one is never run again on its own after a crash: the lead finds out what happened first (spec 26) |
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.
@@ -22,6 +22,8 @@ import { entryProblems, readRegister } from './lib/designs.mjs';
22
22
  import { globToRegExp, matchesAny } from './lib/glob.mjs';
23
23
  import { noteBefore } from './lane-audit.mjs';
24
24
  import { storyMerges } from './lib/queue.mjs';
25
+ import { approverOf } from './lib/journal.mjs';
26
+ import { loginHere } from './lib/sessions.mjs';
25
27
  import { TESTS_APPROVAL, commitWeakenings } from './lib/regression.mjs';
26
28
  import {
27
29
  STANDARDS_APPROVAL,
@@ -569,11 +571,15 @@ function committedFiles() {
569
571
  function recordApprovals() {
570
572
  const { files, gone, git } = committedFiles();
571
573
  const lines = [];
574
+ // The person who gave an approval, by their GitHub login: the developer at this machine, where it was
575
+ // given. Only when code-kit has the login cached; the lead's own approvals have no approver.
576
+ const login = loginHere(root);
572
577
  const record = (file, fields) =>
573
578
  lines.push(
574
579
  JSON.stringify({
575
580
  at: new Date().toISOString(),
576
581
  ...fields,
582
+ ...(login && approverOf(fields) === 'person' ? { approver: login } : {}),
577
583
  file,
578
584
  branch,
579
585
  actor: actor.label,
@@ -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();
@@ -646,6 +652,7 @@ async function daemon({ root, session, watch }) {
646
652
  session,
647
653
  branch: git(root, 'symbolic-ref', '--short', '-q', 'HEAD'),
648
654
  agents: agents.map(({ type, tool, branch }) => ({ type, tool, branch })),
655
+ ...sessionFacts(root, session),
649
656
  });
650
657
  } catch {
651
658
  // reported on the next try
@@ -742,6 +749,27 @@ function trim(file) {
742
749
  } catch {}
743
750
  }
744
751
 
752
+ /**
753
+ * What code-kit recorded of the session (SESS-1): the code-kit and model it runs, when it started (ms),
754
+ * and the file it last edited, by path only, while that was in the last ten minutes.
755
+ */
756
+ export function sessionFacts(root, session, now = Date.now()) {
757
+ const record = readJson(
758
+ join(stateDir(root), 'sessions', `${String(session).replace(/[^\w.-]/g, '_')}.json`),
759
+ {},
760
+ );
761
+ const str = (v, max) =>
762
+ typeof v === 'string' && v && !/[\r\n]/.test(v) ? v.slice(0, max) : null;
763
+ const started = Date.parse(record?.started ?? '');
764
+ const edited = Date.parse(record?.editing?.at ?? '');
765
+ return {
766
+ codeKit: str(record?.codeKit, 40),
767
+ model: str(record?.model, 120),
768
+ started: Number.isFinite(started) ? started : null,
769
+ editing: now - edited < 10 * 60_000 ? str(record?.editing?.path, 300) : null,
770
+ };
771
+ }
772
+
745
773
  /** Starts the daemon for a session, detached; one per session. */
746
774
  export function startDaemon(root, session, watch, url) {
747
775
  const dir = stateDir(root);
@@ -439,6 +439,9 @@ export function validate(c) {
439
439
  return p;
440
440
  }
441
441
 
442
+ /** A deliverable kind's name (a layer's or lane's `label`): one line, at most 60 characters. */
443
+ const isLabel = (v) => isStr(v) && v.trim().length > 0 && v.length <= 60 && !/[\r\n]/.test(v);
444
+
442
445
  function validateLanes(c, need) {
443
446
  if (!need(isObj(c.lanes), '"lanes" must be an object (it may be empty)')) return;
444
447
  const agents = new Set();
@@ -453,6 +456,10 @@ function validateLanes(c, need) {
453
456
  lane.exclude === undefined || isList(lane.exclude),
454
457
  `lanes.${name}.exclude must be a list of globs`,
455
458
  );
459
+ need(
460
+ lane.label === undefined || isLabel(lane.label),
461
+ `lanes.${name}.label must be a short name for what the lane delivers, such as "Screens" or "API contract" (one line, at most 60 characters)`,
462
+ );
456
463
  need(!agents.has(lane.agent), `lanes.${name}.agent "${lane.agent}" is used by another lane`);
457
464
  agents.add(lane.agent);
458
465
  }
@@ -483,6 +490,10 @@ function validateLayers(c, need, each) {
483
490
  l.denyPackages === undefined || isList(l.denyPackages),
484
491
  `${at}.denyPackages must be a list of globs`,
485
492
  );
493
+ need(
494
+ l.label === undefined || isLabel(l.label),
495
+ `${at}.label must be a short name for what the layer delivers, such as "Data" or "Service" (one line, at most 60 characters)`,
496
+ );
486
497
  });
487
498
  const aliases = c.importAliases;
488
499
  need(
@@ -36,11 +36,12 @@ export function readRegister(root, config, text = null) {
36
36
  /** HAND-2: whether an entry's design is files in the repository rather than only in a design tool. */
37
37
  export const handedOver = (entry) => Array.isArray(entry?.states) && entry.states.length > 0;
38
38
 
39
- /** The tool an entry's design lives in, for an entry not handed over yet: "paper" from "paper:…". */
40
- export const toolOf = (entry) =>
41
- entry?.source?.tool ??
42
- String(entry?.design ?? '').match(/^([a-z][\w-]*):/i)?.[1] ??
43
- 'the design tool';
39
+ /**
40
+ * The tool an entry's design lives in: "paper" from "paper:…" for an entry not handed over yet, or
41
+ * `fallback` when the entry doesn't say.
42
+ */
43
+ export const toolOf = (entry, fallback = 'the design tool') =>
44
+ entry?.source?.tool ?? String(entry?.design ?? '').match(/^([a-z][\w-]*):/i)?.[1] ?? fallback;
44
45
 
45
46
  /**
46
47
  * HAND-2: the states the specs' `## Screens` sections give `screen`: its `**States:**` line, or else the