@warren-dean/code-kit 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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.28.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.28.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.28.0 (2026-10-31)
6
+
7
+ 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).
8
+
9
+ - **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.
10
+ - **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.
11
+ - **Approvals** you give are recorded in the approval log with your GitHub login, when code-kit has it.
12
+ - **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.
13
+
5
14
  ## 0.27.0 (2026-10-30)
6
15
 
7
16
  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
@@ -535,10 +535,10 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
535
535
  | `lead.paths` | yes | What the main session writes. `.claude/**` and `.mcp.json` are always added. |
536
536
  | `lead.outside` | no | Paths outside the repository the lead may write, e.g. `../shared-lib/**`. Claude's memory and scratchpad are always included. |
537
537
  | `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. |
538
+ | `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
539
  | `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
540
  | `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. |
541
+ | `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
542
  | `importAliases` | no | `{ "@app/domain": "packages/domain/src" }`: resolves non-relative imports to repository paths |
543
543
  | `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
544
  | `shell.restricted[]` | no | `{ pattern, lanes, why }`: only the lead and these lanes |
@@ -550,7 +550,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
550
550
  | `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
551
  | `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
552
  | `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. |
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, 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
554
  | `branches.protected` | no | Default `["main", "master"]` |
555
555
  | `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
556
  | `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) |
@@ -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,
@@ -646,6 +646,7 @@ async function daemon({ root, session, watch }) {
646
646
  session,
647
647
  branch: git(root, 'symbolic-ref', '--short', '-q', 'HEAD'),
648
648
  agents: agents.map(({ type, tool, branch }) => ({ type, tool, branch })),
649
+ ...sessionFacts(root, session),
649
650
  });
650
651
  } catch {
651
652
  // reported on the next try
@@ -742,6 +743,27 @@ function trim(file) {
742
743
  } catch {}
743
744
  }
744
745
 
746
+ /**
747
+ * What code-kit recorded of the session (SESS-1): the code-kit and model it runs, when it started (ms),
748
+ * and the file it last edited, by path only, while that was in the last ten minutes.
749
+ */
750
+ export function sessionFacts(root, session, now = Date.now()) {
751
+ const record = readJson(
752
+ join(stateDir(root), 'sessions', `${String(session).replace(/[^\w.-]/g, '_')}.json`),
753
+ {},
754
+ );
755
+ const str = (v, max) =>
756
+ typeof v === 'string' && v && !/[\r\n]/.test(v) ? v.slice(0, max) : null;
757
+ const started = Date.parse(record?.started ?? '');
758
+ const edited = Date.parse(record?.editing?.at ?? '');
759
+ return {
760
+ codeKit: str(record?.codeKit, 40),
761
+ model: str(record?.model, 120),
762
+ started: Number.isFinite(started) ? started : null,
763
+ editing: now - edited < 10 * 60_000 ? str(record?.editing?.path, 300) : null,
764
+ };
765
+ }
766
+
745
767
  /** Starts the daemon for a session, detached; one per session. */
746
768
  export function startDaemon(root, session, watch, url) {
747
769
  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
@@ -18,7 +18,7 @@ export function start() {
18
18
  if (!config && !error) process.exit(0);
19
19
  // SESS-1: the session acting is still there; one code-kit hadn't seen starts here.
20
20
  try {
21
- seeSession(project, input.session_id);
21
+ seeSession(project, input.session_id, Date.now(), () => ({ model: modelOf(input) }));
22
22
  } catch {
23
23
  // a read-only checkout: the session goes unrecorded
24
24
  }
@@ -36,6 +36,24 @@ const TAIL_BYTES = 64 * 1024;
36
36
  export function apiStopOf(input) {
37
37
  // A lane agent's own transcript: the session's ends where the lead is, not where the agent stopped.
38
38
  const path = input?.agent_id ? input.agent_transcript_path : input?.transcript_path;
39
+ const entry = lastAssistant(path);
40
+ return entry?.isApiErrorMessage ? (entry.error ?? 'unknown') : null;
41
+ }
42
+
43
+ /**
44
+ * The model the session runs on: the one SessionStart names, or the one its transcript's last reply
45
+ * came from (Claude Code writes it on each), or null. Never a lane agent's: that's the session's lead.
46
+ */
47
+ export function modelOf(input) {
48
+ if (typeof input?.model === 'string' && input.model) return input.model.slice(0, 120);
49
+ // A reply Claude Code made up itself (an error, a cut-off turn) names `<synthetic>`: not a model.
50
+ const named = (e) =>
51
+ !e.isApiErrorMessage && typeof e.message?.model === 'string' && /^[^<\s]/.test(e.message.model);
52
+ return lastAssistant(input?.transcript_path, named)?.message.model.slice(0, 120) ?? null;
53
+ }
54
+
55
+ /** The last of the model's entries in a transcript's end that `keep` accepts, or null. */
56
+ function lastAssistant(path, keep = () => true) {
39
57
  if (!path) return null;
40
58
  let fd;
41
59
  try {
@@ -45,19 +63,20 @@ export function apiStopOf(input) {
45
63
  const buffer = Buffer.alloc(length);
46
64
  readSync(fd, buffer, 0, length, size - length);
47
65
  // The last of the model's entries: what Claude Code adds after it (a hook's note) says nothing.
48
- const entry = buffer
49
- .toString('utf8')
50
- .split('\n')
51
- .reverse()
52
- .map((line) => {
53
- try {
54
- return JSON.parse(line);
55
- } catch {
56
- return null;
57
- }
58
- })
59
- .find((e) => e?.type === 'assistant');
60
- return entry?.isApiErrorMessage ? (entry.error ?? 'unknown') : null;
66
+ return (
67
+ buffer
68
+ .toString('utf8')
69
+ .split('\n')
70
+ .reverse()
71
+ .map((line) => {
72
+ try {
73
+ return JSON.parse(line);
74
+ } catch {
75
+ return null;
76
+ }
77
+ })
78
+ .find((e) => e?.type === 'assistant' && keep(e)) ?? null
79
+ );
61
80
  } catch {
62
81
  return null;
63
82
  } finally {
@@ -56,6 +56,35 @@ const field = (lines, name) =>
56
56
  .find(Boolean)?.[1]
57
57
  .trim() ?? '';
58
58
 
59
+ /**
60
+ * Every spec in the specs (code-kit's spec template): [{ id, file, title, outcome, requirements }]. `id`
61
+ * is the number its `# ` heading starts with ("# 21. The hub adapter" → "21"), or else the file's name;
62
+ * `title` the rest of that heading; `outcome` its `**Outcome:**` line, or null; `requirements` the ids of
63
+ * the requirements it holds (removed ones left out). A file with neither an outcome nor a requirement
64
+ * (principles, architecture) isn't a spec. `plan` is the plan, left out where it sits among the specs.
65
+ */
66
+ export function readSpecs(root, specsPath, plan = null) {
67
+ const requirements = readRequirements(root, specsPath);
68
+ const found = [];
69
+ for (const file of markdownFiles(root, specsPath)) {
70
+ if (file === plan) continue;
71
+ const lines = readFileSync(join(root, file), 'utf8').split('\n');
72
+ const heading = lines.map((l) => l.match(/^#\s+(.+?)\s*$/)).find(Boolean)?.[1] ?? null;
73
+ const numbered = heading?.match(/^(\d+[A-Za-z]?)[.:)]?\s+(.+)$/);
74
+ const outcome = field(lines, 'Outcome') || null;
75
+ const ids = requirements.filter((r) => r.file === file && !r.removed).map((r) => r.id);
76
+ if (!outcome && !ids.length) continue;
77
+ found.push({
78
+ id: numbered ? numbered[1] : file.split('/').pop().replace(/\.md$/, ''),
79
+ file,
80
+ title: numbered ? numbered[2] : heading,
81
+ outcome,
82
+ requirements: ids,
83
+ });
84
+ }
85
+ return found;
86
+ }
87
+
59
88
  /** The first paragraph under a story's `**Field:**` lines, on one line, or null. */
60
89
  function summaryOf(body) {
61
90
  const start = body.findIndex((l) => l.trim() && !/^\*\*[^*]+:\*\*/.test(l.trim()));
@@ -142,6 +142,26 @@ export function securityReasons({ files = [], added = [], cites = [], security =
142
142
  return reasons;
143
143
  }
144
144
 
145
+ /** Every kind of reason a change gets the security review for: the sensitive kinds, then the rest. */
146
+ export const SECURITY_KINDS = [...SENSITIVE.map((s) => s.kind), 'dependencies', 'requirements'];
147
+
148
+ /**
149
+ * The security review's rules for a project: whether it has the reviewer agent, the kinds of change
150
+ * that get the review, and the ids of its specs' security requirements, a story citing any of which
151
+ * gets it too. { reviewer, kinds, requirements }.
152
+ */
153
+ export function securityRules(root, config) {
154
+ const specs = config.docs?.specs;
155
+ const texts = specs
156
+ ? markdownFiles(root, specs).map((f) => readFileSync(join(root, f), 'utf8'))
157
+ : [];
158
+ return {
159
+ reviewer: existsSync(join(root, SECURITY_AGENT_FILE)),
160
+ kinds: SECURITY_KINDS,
161
+ requirements: [...securityRequirementIds(texts)],
162
+ };
163
+ }
164
+
145
165
  /** The reasons as one sentence: "sign-in or sessions (src/auth/login.ts), dependencies (package.json)". */
146
166
  export const reasonsInWords = (reasons) =>
147
167
  reasons.map((r) => `${r.why} (${examples(r.where)})`).join('; ');
@@ -11,6 +11,7 @@ import { join } from 'node:path';
11
11
  import { matchesAny } from './glob.mjs';
12
12
  import { CLI, projectWorktrees } from './rules.mjs';
13
13
  import { shortSession } from './laneclaims.mjs';
14
+ import { isHandle } from './teamfacts.mjs';
14
15
 
15
16
  export { shortSession };
16
17
  export const SESSIONS_DIR = '.claude/state/sessions';
@@ -20,20 +21,37 @@ export const SESSION_LIVE_MS = 15 * 60_000;
20
21
  const SEEN_EVERY_MS = 60_000;
21
22
  /** The uncommitted files a session wrote, kept for SESS-5: at most this many. */
22
23
  const WROTE_KEPT = 500;
24
+ /** The file a session edits is noted again at most this often, unless it's another file. */
25
+ const EDITING_EVERY_MS = 30_000;
26
+ /** The code-kit a session runs, as it starts: the plugin can be updated while other sessions run. */
27
+ const KIT_VERSION = (() => {
28
+ try {
29
+ return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
30
+ } catch {
31
+ return null;
32
+ }
33
+ })();
23
34
 
24
35
  const main = (root) => projectWorktrees(root)[0] ?? root;
25
36
  const dirOf = (root) => join(main(root), SESSIONS_DIR);
26
37
  const safe = (id) => String(id).replace(/[^\w.-]/g, '_');
27
38
  const fileOf = (root, id) => join(dirOf(root), `${safe(id)}.json`);
28
39
 
29
- /** The person at this machine: their GitHub login if code-kit has it cached, or the OS user. */
30
- export function personHere(root) {
40
+ /** The person at this machine by their GitHub login, when code-kit has it cached, or null. */
41
+ export function loginHere(root) {
31
42
  try {
32
43
  const cached = JSON.parse(readFileSync(join(main(root), '.claude/state/whoami.json'), 'utf8'));
33
- if (cached?.login) return cached.login;
44
+ if (isHandle(cached?.login)) return cached.login;
34
45
  } catch {
35
- // not cached: the OS user
46
+ // not cached
36
47
  }
48
+ return null;
49
+ }
50
+
51
+ /** The person at this machine: their GitHub login if code-kit has it cached, or the OS user. */
52
+ export function personHere(root) {
53
+ const login = loginHere(root);
54
+ if (login) return login;
37
55
  try {
38
56
  return userInfo().username || null;
39
57
  } catch {
@@ -89,40 +107,62 @@ export const leadSession = (root, now = Date.now()) =>
89
107
  /**
90
108
  * SESS-2: a session starting (or resumed). It's the lead when no other live session is; otherwise a
91
109
  * working session. A resumed session keeps the role it had, unless it was the lead and another session
92
- * has led since.
110
+ * has led since. `model` is the model it runs on, when Claude Code says (SessionStart's `model`); the
111
+ * session also keeps its person's GitHub login, when code-kit knows it, and the code-kit it runs.
93
112
  */
94
- export function startSession(root, id, now = Date.now()) {
113
+ export function startSession(root, id, now = Date.now(), { model = null } = {}) {
95
114
  const at = new Date(now).toISOString();
96
115
  const had = readSession(root, id);
97
116
  const lead = leadSession(root, now);
98
117
  return write(root, {
99
118
  id,
100
119
  person: had?.person ?? personHere(root),
120
+ login: loginHere(root) ?? had?.login ?? null,
101
121
  role: lead && lead.id !== id ? 'working' : 'lead',
102
122
  started: had?.started ?? at,
103
123
  seen: at,
104
124
  ended: null,
105
125
  task: had?.task ?? null,
106
126
  wrote: had?.wrote ?? [],
127
+ model: model ?? had?.model ?? null,
128
+ codeKit: KIT_VERSION,
129
+ editing: had?.editing ?? null,
107
130
  });
108
131
  }
109
132
 
110
- /** A hook saw the session act: it's still there. A session code-kit hadn't seen starts here. */
111
- export function seeSession(root, id, now = Date.now()) {
133
+ /**
134
+ * A hook saw the session act: it's still there. A session code-kit hadn't seen starts here. `facts()`
135
+ * gives what's read only when the record is written (the model it runs on now), at most once a minute.
136
+ */
137
+ export function seeSession(root, id, now = Date.now(), facts = () => ({})) {
112
138
  if (!id) return null;
113
139
  const had = readSession(root, id);
114
- if (!had || had.ended) return startSession(root, id, now);
140
+ if (!had || had.ended) return startSession(root, id, now, facts());
115
141
  // A lead that went quiet past SESSION_LIVE_MS, while another session took the lead, works now.
116
142
  const lead = had.role === 'lead' ? leadSession(root, now) : null;
117
143
  const demoted = lead && lead.id !== id;
118
144
  if (!demoted && now - Date.parse(had.seen) < SEEN_EVERY_MS) return had;
145
+ const { model } = facts();
119
146
  return write(root, {
120
147
  ...had,
121
148
  seen: new Date(now).toISOString(),
122
149
  ...(demoted ? { role: 'working' } : {}),
150
+ ...(model ? { model } : {}),
123
151
  });
124
152
  }
125
153
 
154
+ /**
155
+ * The file the session last edited, in any of the project's checkouts: { path, at }, for the team
156
+ * provider's presence and the report. `rel` is relative to the checkout it's in.
157
+ */
158
+ export function noteEditing(root, id, rel, now = Date.now()) {
159
+ if (!id || !rel) return;
160
+ const had = readSession(root, id) ?? startSession(root, id, now);
161
+ const was = had.editing;
162
+ if (was?.path === rel && now - Date.parse(was.at) < EDITING_EVERY_MS) return;
163
+ write(root, { ...had, editing: { path: rel, at: new Date(now).toISOString() } });
164
+ }
165
+
126
166
  /** The session ended: it's no longer live, and leads nothing. Its task stays, stale, for SESS-4. */
127
167
  export function endSession(root, id, now = Date.now()) {
128
168
  const had = readSession(root, id);
@@ -9,9 +9,13 @@ import { execFileSync } from 'node:child_process';
9
9
  import { dirname, join } from 'node:path';
10
10
  import { APPROVAL_LOG } from './rules.mjs';
11
11
  import { approverOf } from './journal.mjs';
12
- import { readQueue } from './queue.mjs';
12
+ import { readQueue, waiting } from './queue.mjs';
13
13
  import { sendBacks } from './reviews.mjs';
14
- import { readMilestones, specCheckRows } from './plan.mjs';
14
+ import { readMilestones, readSpecs, specCheckRows } from './plan.mjs';
15
+ import { handedOver, entryProblems, readRegister, toolOf } from './designs.mjs';
16
+ import { SECURITY_KINDS, securityRules } from './security.mjs';
17
+ import { sessions } from './sessions.mjs';
18
+ import { storyOfBranch } from './teamfacts.mjs';
15
19
  import { storyTimes } from './timeline.mjs';
16
20
  import { trail } from './storymap.mjs';
17
21
  import {
@@ -20,6 +24,7 @@ import {
20
24
  LEVELS,
21
25
  ORIGINS,
22
26
  SOURCES,
27
+ laneLayers,
23
28
  projectStandards,
24
29
  sourceOf,
25
30
  } from './standards.mjs';
@@ -28,9 +33,12 @@ import { slicesOf } from './schedule.mjs';
28
33
 
29
34
  /**
30
35
  * 2 adds the project's standards (code-kit spec 22); 3 the plan's slices (spec 23, SCHED-2); 4 each
31
- * story's summary and each requirement's title.
36
+ * story's summary and each requirement's title; 5 the specs (id, title, outcome line, requirement ids),
37
+ * each layer's and lane's deliverable kind, the lanes with their layers and paths, each approval's
38
+ * approver and story, the security review's rules, each story's spec-check result and place in the
39
+ * merge queue, the design register's entries, and the sessions at work.
32
40
  */
33
- export const SNAPSHOT_VERSION = 4;
41
+ export const SNAPSHOT_VERSION = 5;
34
42
 
35
43
  /** A story's stage, as a report names it. */
36
44
  export const STAGES = [
@@ -44,6 +52,10 @@ export const STAGES = [
44
52
  'done',
45
53
  ];
46
54
  export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
55
+ /** A spec-check report's status for a requirement, and for a story, its worst requirement's. */
56
+ export const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
57
+ /** A design register entry's state: its files handed over and as approved, only in a tool, or not as approved. */
58
+ export const DESIGN_STATES = ['handed-over', 'in-tool', 'problems'];
47
59
 
48
60
  /**
49
61
  * The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
@@ -79,6 +91,10 @@ export const SNAPSHOT_SCHEMA = {
79
91
  claimedBy: 'handle?',
80
92
  // Added in version 4.
81
93
  summary: 'summary?',
94
+ // Added in version 5: the spec-check report's worst status on its branch (`none` with no report),
95
+ // and its place in the merge queue (1 merges next) while its branch waits there.
96
+ check: `enum:${[...CHECKS, 'none'].join('|')}?`,
97
+ queuePosition: 'count?',
82
98
  },
83
99
  ],
84
100
  sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
@@ -90,10 +106,24 @@ export const SNAPSHOT_SCHEMA = {
90
106
  stories: ['id'],
91
107
  built: ['path'],
92
108
  tested: ['path'],
93
- check: 'enum:done|partial|missing|conflicts|none',
109
+ check: `enum:${[...CHECKS, 'none'].join('|')}`,
110
+ },
111
+ ],
112
+ // Version 5: each spec, by the id the project gives it, its title, its outcome line and its
113
+ // requirements' ids. Nothing else of its text.
114
+ specs: [{ id: 'name', file: 'path', title: 'title?', outcome: 'summary?', requirements: ['id'] }],
115
+ approvals: [
116
+ {
117
+ what: 'name',
118
+ path: 'path?',
119
+ who: 'enum:person|lead',
120
+ at: 'ms',
121
+ branch: 'name?',
122
+ // Added in version 5: the person's GitHub login, when code-kit knew it; the story of its branch.
123
+ approver: 'handle?',
124
+ story: 'id?',
94
125
  },
95
126
  ],
96
- approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
97
127
  usage: [
98
128
  {
99
129
  story: 'id?',
@@ -104,11 +134,48 @@ export const SNAPSHOT_SCHEMA = {
104
134
  },
105
135
  ],
106
136
  rules: {
107
- layers: [{ name: 'name', mayImport: ['name'] }],
137
+ // `label`, added in version 5: the layer's deliverable kind ("Data", "Service").
138
+ layers: [{ name: 'name', mayImport: ['name'], label: 'name?' }],
108
139
  protected: [{ glob: 'path', approval: 'name' }],
109
140
  delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
110
141
  designGate: 'bool',
142
+ // Version 5: each lane, its deliverable kind, the layers its paths fall in, and what it owns.
143
+ lanes: [{ name: 'name', label: 'name', layers: ['name'], paths: ['path'], exclude: ['path'] }],
144
+ // Version 5: whether the project has the security reviewer, the kinds of change it reviews, and
145
+ // the security requirements a story citing gets it for.
146
+ security: {
147
+ reviewer: 'bool',
148
+ kinds: [`enum:${SECURITY_KINDS.join('|')}`],
149
+ requirements: ['id'],
150
+ },
111
151
  },
152
+ // Version 5: the design register's entries, by screen, the code file, the design story, when it was
153
+ // approved, the tool it was drawn in, its state and its states' names.
154
+ designs: [
155
+ {
156
+ screen: 'name',
157
+ file: 'path',
158
+ story: 'id?',
159
+ approved: 'date?',
160
+ tool: 'name?',
161
+ state: `enum:${DESIGN_STATES.join('|')}`,
162
+ states: ['name'],
163
+ },
164
+ ],
165
+ // Version 5: the sessions at work on this machine: the lead or a working one, its person's GitHub
166
+ // login, the code-kit and model it runs, when it started, and the file it last edited, and when.
167
+ sessions: [
168
+ {
169
+ id: 'name',
170
+ role: 'enum:lead|working',
171
+ person: 'handle?',
172
+ codeKit: 'name?',
173
+ model: 'name?',
174
+ started: 'ms',
175
+ editing: 'path?',
176
+ editedAt: 'ms?',
177
+ },
178
+ ],
112
179
  // Spec 22: each standard that applies, by id and title, how it's applied and where it came from;
113
180
  // its why in one line at most, and its evidence only as counts.
114
181
  standards: [
@@ -128,8 +195,19 @@ export const SNAPSHOT_SCHEMA = {
128
195
  ],
129
196
  };
130
197
 
131
- /** Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. */
132
- export const LATER_PARTS = ['standards', 'slices'];
198
+ /**
199
+ * Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. Each
200
+ * is a dotted path into the allow-list, `[]` for a list's items; a leaf that may be missing ends in `?`.
201
+ */
202
+ export const LATER_PARTS = [
203
+ 'standards',
204
+ 'slices',
205
+ 'specs',
206
+ 'designs',
207
+ 'sessions',
208
+ 'rules.lanes',
209
+ 'rules.security',
210
+ ];
133
211
 
134
212
  export const SUMMARY_MAX = 600;
135
213
 
@@ -167,6 +245,8 @@ const KINDS = {
167
245
 
168
246
  /** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
169
247
  export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
248
+ const later = (k) =>
249
+ LATER_PARTS.includes(`${at}.${k}`.replace(/^snapshot\./, '').replace(/\[\d+\]/g, '[]'));
170
250
  if (typeof shape === 'string') {
171
251
  const optional = shape.endsWith('?');
172
252
  const kind = optional ? shape.slice(0, -1) : shape;
@@ -185,7 +265,7 @@ export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot'
185
265
  return [
186
266
  ...extra.map((k) => `${at}.${k}: not a field a report may hold`),
187
267
  ...Object.entries(shape)
188
- .filter(([k]) => !(shape === SNAPSHOT_SCHEMA && LATER_PARTS.includes(k) && !(k in value)))
268
+ .filter(([k]) => !(later(k) && !(k in value)))
189
269
  .flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
190
270
  ];
191
271
  }
@@ -206,11 +286,40 @@ export const EVENT_PARTS = [
206
286
  'stories',
207
287
  'sendBacks',
208
288
  'requirements',
289
+ 'specs',
209
290
  'approvals',
210
291
  'rules',
211
292
  'standards',
293
+ 'designs',
212
294
  ];
213
295
 
296
+ /** The deliverable kinds a layer's or lane's name gives, when the config gives it no `label`. */
297
+ const KINDS_BY_NAME = [
298
+ [/^(schemas?|contracts?|api|types|openapi|graphql|protos?)$/, 'API contract'],
299
+ [/^(web|mobile|ui|app|apps|screens?|frontend|client|pages|views?)$/, 'Screens'],
300
+ [/^(data|db|database|migrations?|storage|sql)$/, 'Data'],
301
+ [/^(domain|core|services?|backend|server|workers?|functions|logic|ai|jobs)$/, 'Service'],
302
+ [/^(tests?|qa|e2e|quality)$/, 'Tests'],
303
+ [/^(design|designs|ux)$/, 'Design'],
304
+ [/^(infra|infrastructure|platform|ops|devops|deploy|ci)$/, 'Infrastructure'],
305
+ [/^(docs?|documentation|runbooks?)$/, 'Docs'],
306
+ ];
307
+
308
+ /**
309
+ * A layer's or lane's deliverable kind: its `label`, or else what its name gives ("schemas" →
310
+ * "API contract", "web" → "Screens"), or else its name, capitalised, its hyphens as spaces.
311
+ */
312
+ export function deliverableKind(name, label = null) {
313
+ if (typeof label === 'string' && label.trim()) return label.trim().slice(0, 120);
314
+ const n = String(name ?? '').toLowerCase();
315
+ const found = KINDS_BY_NAME.find(([re]) => re.test(n))?.[1];
316
+ if (found) return found;
317
+ const words = String(name ?? '')
318
+ .replace(/[-_]+/g, ' ')
319
+ .trim();
320
+ return (words.charAt(0).toUpperCase() + words.slice(1)).slice(0, 120) || 'Code';
321
+ }
322
+
214
323
  const git = (root, ...args) => {
215
324
  try {
216
325
  return execFileSync('git', ['-C', root, ...args], {
@@ -277,8 +386,6 @@ function checkedRows(root, story) {
277
386
  return [];
278
387
  }
279
388
 
280
- const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
281
-
282
389
  /**
283
390
  * The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
284
391
  * branch stories merge into, `claims` the team's claims as last read, `version` code-kit's.
@@ -293,10 +400,14 @@ export function buildSnapshot({
293
400
  now = Date.now(),
294
401
  }) {
295
402
  const times = new Map(storyTimes(root, status.stories, base).map((t) => [t.id, t]));
296
- const queued = new Map(
297
- readQueue(root)
298
- .filter((e) => e.state === 'waiting' || e.state === 'merging')
299
- .map((e) => [e.branch, Date.parse(e.passed)]),
403
+ const inQueue = waiting(readQueue(root));
404
+ const queued = new Map(inQueue.map((e) => [e.branch, Date.parse(e.passed)]));
405
+ const place = new Map(inQueue.map((e, i) => [e.branch, i + 1]));
406
+ // Each story's spec-check report, on its branch: the requirements' statuses, and the story's worst.
407
+ const rowsOf = new Map(
408
+ status.stories
409
+ .filter((s) => s.branchExists)
410
+ .map((s) => [s.id, checkedRows(root, s).filter((r) => CHECKS.includes(r.status))]),
300
411
  );
301
412
  const backs = sendBacks(root);
302
413
  const claimed = new Map(claims.map((c) => [c.story, c.by]));
@@ -332,6 +443,8 @@ export function buildSnapshot({
332
443
  },
333
444
  claimedBy: claimed.get(s.id) ?? null,
334
445
  summary: reportedSummary(s.summary),
446
+ check: worstCheck(rowsOf.get(s.id) ?? []),
447
+ queuePosition: place.get(s.branch) ?? null,
335
448
  };
336
449
  });
337
450
 
@@ -352,10 +465,8 @@ export function buildSnapshot({
352
465
  .map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
353
466
 
354
467
  const checks = new Map();
355
- for (const s of status.stories)
356
- if (s.branchExists)
357
- for (const row of checkedRows(root, s))
358
- if (CHECKS.includes(row.status)) checks.set(row.requirement, row.status);
468
+ for (const rows of rowsOf.values())
469
+ for (const row of rows) checks.set(row.requirement, row.status);
359
470
  const requirements = trail(root, status, base).map((r) => ({
360
471
  id: r.id,
361
472
  title: line(r.title),
@@ -379,12 +490,16 @@ export function buildSnapshot({
379
490
  const key = `${e.approval}|${e.file ?? ''}|${at}`;
380
491
  if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
381
492
  seen.add(key);
493
+ const who = approverOf(e);
494
+ const story = KINDS.name(e.branch) ? storyOfBranch(e.branch) : null;
382
495
  approvals.push({
383
496
  what: e.approval,
384
497
  path: KINDS.path(e.file) ? e.file : null,
385
- who: approverOf(e),
498
+ who,
386
499
  at,
387
500
  branch: KINDS.name(e.branch) ? e.branch : null,
501
+ approver: who === 'person' && KINDS.handle(e.approver) ? e.approver : null,
502
+ story: KINDS.id(story) ? story : null,
388
503
  });
389
504
  }
390
505
 
@@ -402,10 +517,15 @@ export function buildSnapshot({
402
517
  stories,
403
518
  sendBacks: sendBackList,
404
519
  requirements,
520
+ specs: reportedSpecs(root, config, line),
405
521
  approvals,
406
522
  usage: recordedUsage(root),
407
523
  rules: {
408
- layers: (config.layers ?? []).map((l) => ({ name: l.name, mayImport: l.mayImport ?? [] })),
524
+ layers: (config.layers ?? []).map((l) => ({
525
+ name: l.name,
526
+ mayImport: l.mayImport ?? [],
527
+ label: deliverableKind(l.name, l.label),
528
+ })),
409
529
  protected: (config.protected ?? [])
410
530
  .filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
411
531
  .map((p) => ({ glob: p.glob, approval: p.approval })),
@@ -415,12 +535,97 @@ export function buildSnapshot({
415
535
  merge: Boolean(delegate?.merge),
416
536
  },
417
537
  designGate: Boolean(config.designGate),
538
+ lanes: Object.entries(config.lanes ?? {}).map(([name, lane]) => ({
539
+ name,
540
+ label: deliverableKind(name, lane.label),
541
+ layers: laneLayers(lane, config),
542
+ paths: (lane.paths ?? []).filter((p) => KINDS.path(p)),
543
+ exclude: (lane.exclude ?? []).filter((p) => KINDS.path(p)),
544
+ })),
545
+ security: securityRules(root, config),
418
546
  },
419
547
  standards: reportedStandards(root, config, line),
548
+ designs: reportedDesigns(root, config),
549
+ sessions: reportedSessions(root, now),
420
550
  };
421
551
  return snapshot;
422
552
  }
423
553
 
554
+ /** A story's spec-check result: its report's worst status (conflicts, missing, partial), `none` without one. */
555
+ function worstCheck(rows) {
556
+ if (!rows.length) return 'none';
557
+ return [...CHECKS].reverse().find((c) => rows.some((r) => r.status === c));
558
+ }
559
+
560
+ /** Each spec as a report holds it: its id, file, title, outcome line and requirements' ids. */
561
+ function reportedSpecs(root, config, line) {
562
+ const { specs, plan } = config.docs ?? {};
563
+ if (!specs) return [];
564
+ return readSpecs(root, specs, plan)
565
+ .filter((sp) => KINDS.name(sp.id) && KINDS.path(sp.file))
566
+ .map((sp) => ({
567
+ id: sp.id,
568
+ file: sp.file,
569
+ title: line(sp.title),
570
+ outcome: reportedSummary(sp.outcome),
571
+ requirements: sp.requirements,
572
+ }));
573
+ }
574
+
575
+ /**
576
+ * The design register's entries (spec 24): handed over (its files there, as approved), only in a design
577
+ * tool, or with problems (a file missing or changed, a state the spec lists without a design).
578
+ */
579
+ function reportedDesigns(root, config) {
580
+ const { entries } = readRegister(root, config);
581
+ const one = (v, max = 120) =>
582
+ typeof v === 'string' && v.trim() ? v.replace(/\s+/g, ' ').trim().slice(0, max) : null;
583
+ return entries
584
+ .filter((e) => e && KINDS.path(e.file))
585
+ .map((e) => {
586
+ const approved = String(e.approved ?? '').slice(0, 10);
587
+ return {
588
+ screen: one(e.screen) ?? e.file.slice(0, 120),
589
+ file: e.file,
590
+ story: KINDS.id(e.story) ? e.story : null,
591
+ approved: KINDS.date(approved) ? approved : null,
592
+ tool: one(toolOf(e, null)),
593
+ state: !handedOver(e)
594
+ ? 'in-tool'
595
+ : entryProblems(root, e, config.docs?.specs).length
596
+ ? 'problems'
597
+ : 'handed-over',
598
+ states: (handedOver(e) ? e.states : []).map((st) => one(st?.name)).filter(Boolean),
599
+ };
600
+ });
601
+ }
602
+
603
+ /**
604
+ * The sessions at work on this machine's checkout (SESS-1): what code-kit recorded as each started and
605
+ * acted. A session that has ended, or gone quiet past SESSION_LIVE_MS, isn't at work.
606
+ */
607
+ function reportedSessions(root, now) {
608
+ const ms = (iso) => {
609
+ const t = Date.parse(iso ?? '');
610
+ return Number.isInteger(t) && t > 0 ? t : null;
611
+ };
612
+ return sessions(root, now)
613
+ .filter((s) => s.live && KINDS.name(s.id) && ms(s.started))
614
+ .map((s) => {
615
+ const editing = s.editing && KINDS.path(s.editing.path) ? s.editing : null;
616
+ return {
617
+ id: s.id,
618
+ role: s.role === 'lead' ? 'lead' : 'working',
619
+ person: KINDS.handle(s.login) ? s.login : null,
620
+ codeKit: KINDS.name(s.codeKit) ? s.codeKit : null,
621
+ model: KINDS.name(s.model) ? s.model : null,
622
+ started: ms(s.started),
623
+ editing: editing?.path ?? null,
624
+ editedAt: editing ? ms(editing.at) : null,
625
+ };
626
+ });
627
+ }
628
+
424
629
  /**
425
630
  * Spec 22: the standards that apply, as a report holds them. One that the file can't make sense of (an
426
631
  * unknown category, no level) is left out: `code-kit standards` tells the project what's wrong with it.
@@ -10,7 +10,7 @@ import { block, start } from './lib/hook.mjs';
10
10
  import { brokenLayerRule, layerProblems } from './lib/layers.mjs';
11
11
  import { noteFor } from './lib/standards.mjs';
12
12
  import { projectWorktrees, relativeTo, worktreeRoot } from './lib/rules.mjs';
13
- import { noteWrite } from './lib/sessions.mjs';
13
+ import { noteEditing, noteWrite } from './lib/sessions.mjs';
14
14
 
15
15
  const { input, project, config, error } = start();
16
16
  const target = input.tool_input?.file_path;
@@ -23,6 +23,8 @@ const rel = relativeTo(root, target);
23
23
  if (!existsSync(join(root, rel))) process.exit(0);
24
24
  // SESS-5: in the checkout every session shares, which session wrote the file, for a blocked git to name.
25
25
  if (root === projectWorktrees(project)[0]) noteWrite(project, input.session_id, rel);
26
+ // The file the session is editing, in whichever checkout: for the team provider's presence and report.
27
+ noteEditing(project, input.session_id, rel);
26
28
 
27
29
  // Violations recorded in the baseline (brownfield code as it was adopted) don't block; new ones do.
28
30
  const layers = layerProblems(rel, readFileSync(join(root, rel), 'utf8'), config);
package/hooks/session.mjs CHANGED
@@ -9,6 +9,7 @@ import { readFileSync } from 'node:fs';
9
9
  import { fileURLToPath } from 'node:url';
10
10
  import { loadConfig } from './lib/config.mjs';
11
11
  import { releaseSession } from './lib/laneclaims.mjs';
12
+ import { modelOf } from './lib/hook.mjs';
12
13
  import { endSession, startSession } from './lib/sessions.mjs';
13
14
  import { projectDir } from './lib/rules.mjs';
14
15
 
@@ -22,7 +23,8 @@ const project = projectDir();
22
23
  const { config } = loadConfig(project);
23
24
  const session = input.session_id ?? null;
24
25
  if (config && session && process.argv[2] === 'start') {
25
- startSession(project, session);
26
+ // The model the session starts on, when Claude Code names it, or its transcript's (a resumed one).
27
+ startSession(project, session, Date.now(), { model: modelOf(input) });
26
28
  // LEAN-8: the worktrees left done with since the last session go, in the background: a project with
27
29
  // many of them never holds up a session's start.
28
30
  const cli = fileURLToPath(new URL('../bin/code-kit.mjs', import.meta.url));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.27.0",
3
+ "version": "0.28.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",
@@ -54,11 +54,13 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
54
54
  - `paths`: globs matching where that layer's code really lives;
55
55
  - `mayImport`: the direction the docs set. For brownfield code, the direction most of the code already follows;
56
56
  - `denyPackages`: packages forbidden for that layer, for example `node:*` or a vendor SDK outside its adapter.
57
+ - `label` (optional): what the layer delivers, in a few words ("API contract", "Data", "Service"), when its name doesn't say it.
57
58
  - Also add `importAliases` for path aliases in `tsconfig` `paths` that the graph can't see. Workspace package names are found automatically.
58
59
  - The import check reads JavaScript and TypeScript. For another language, record the layers anyway (agents and spec-check use them), and say the import check doesn't cover that language yet.
59
60
  - **`lanes`:** one per documented or discovered ownership area. Each needs:
60
61
  - `agent`: a kebab-case agent name, for example `api-engineer`;
61
62
  - `paths` and `exclude`: every path must have exactly one owner.
63
+ - `label` (optional): what the lane delivers, in a few words ("Screens", "Tests"), when its name doesn't say it.
62
64
  - **A QA lane:** when lanes own screens, or the plan's journeys cross lanes, a `qa` lane with a `test-engineer` agent owning the end-to-end suites (the plan's work split names them; brownfield: the folders the existing end-to-end tests live in), even if the docs forgot it. Its agent's proving command runs the suites. Add a `checks` entry for them scoped by `files` to the suites, so verify runs them when they change. Unit tests stay with each lane.
63
65
  - **`setup`:** `3`, the version of this setup, so `code-kit next` can tell an older project what re-running init adds.
64
66
  - **`lead.paths`:** contracts, specs, design, root config, and anything the docs reserve for the lead.