@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +9 -0
- package/README.md +3 -3
- package/hooks/guard-bash.mjs +6 -0
- package/hooks/lib/adapters/hub/client.mjs +22 -0
- package/hooks/lib/config.mjs +11 -0
- package/hooks/lib/designs.mjs +6 -5
- package/hooks/lib/hook.mjs +33 -14
- package/hooks/lib/plan.mjs +29 -0
- package/hooks/lib/security.mjs +20 -0
- package/hooks/lib/sessions.mjs +49 -9
- package/hooks/lib/snapshot.mjs +227 -22
- package/hooks/post-edit-check.mjs +3 -1
- package/hooks/session.mjs +3 -1
- package/package.json +1 -1
- package/skills/init/SKILL.md +2 -0
|
@@ -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.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.
|
|
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
|
|
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) |
|
package/hooks/guard-bash.mjs
CHANGED
|
@@ -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);
|
package/hooks/lib/config.mjs
CHANGED
|
@@ -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(
|
package/hooks/lib/designs.mjs
CHANGED
|
@@ -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
|
-
/**
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
package/hooks/lib/hook.mjs
CHANGED
|
@@ -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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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 {
|
package/hooks/lib/plan.mjs
CHANGED
|
@@ -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()));
|
package/hooks/lib/security.mjs
CHANGED
|
@@ -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('; ');
|
package/hooks/lib/sessions.mjs
CHANGED
|
@@ -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
|
|
30
|
-
export function
|
|
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
|
|
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
|
-
/**
|
|
111
|
-
|
|
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);
|
package/hooks/lib/snapshot.mjs
CHANGED
|
@@ -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 =
|
|
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: '
|
|
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
|
-
|
|
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
|
-
/**
|
|
132
|
-
|
|
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]) => !(
|
|
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
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
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
|
|
356
|
-
|
|
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
|
|
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) => ({
|
|
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
|
-
|
|
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.
|
|
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",
|
package/skills/init/SKILL.md
CHANGED
|
@@ -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.
|