@warren-dean/code-kit 0.30.1 → 0.30.2

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.30.1",
12
+ "version": "0.30.2",
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.30.1",
3
+ "version": "0.30.2",
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,19 @@
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.30.2 (2026-11-04)
6
+
7
+ Fixes from how code-kit is used: fewer commits refused after commands that write nothing, the setup commit takes the person's approval of the setup, and the fix check and the merge queue see more of a project.
8
+
9
+ - **A commit after a tool records its notes.** With Context Graph on, a commit in the same command after `ctx record` or `ctx card` is no longer refused as possibly writing files: they write only Context Graph's own records, which any actor may write. An adapter names such commands in its `shell.records`.
10
+ - **Committing the setup.** Until code-kit's config has first been committed, the lead's protected files (the specs, the standards, the design register) need no approval of their own: the person approved them with the setup init showed. The commit that switches code-kit on no longer asks for an approval for each, and the stop check no longer asks the lead to revert the new specs; the approval log records each file as part of the setup. Once any commit has held the config, protected files need their approvals as before, even if a later commit takes the config away.
11
+ - **A screen state with commas in brackets.** A spec's `**States:**` line such as `default, error (timed out, offline)` is read as two states, not three, so the design register's entry for it matches.
12
+ - **A commit after code-kit's own reads.** A commit in the same command after `code-kit designs`, `status`, `check`, `next`, `who`, `trace` and its other commands that only read and print is no longer refused as possibly writing files, however code-kit is run (installed, through node or npx). `designs evidence` and anything with `--write` still are.
13
+ - **Setting a shell variable before a commit.** A commit in the same command after `f=docs/x.md` or `export MSG="…"` is no longer refused: setting a variable writes no file. A value that runs a command (`$(…)` or backticks) is still refused, and a `git add "$f"` still counts as staging every changed file, since what it names can't be read in advance.
14
+ - **Releasing a worktree while the lead's reviewer works on its story.** `code-kit worktrees release` no longer says the lane's agent is still at work because a reviewer the lead started is acting on the same story. Only the branch's own lane agent counts.
15
+ - **A fix's test the checks never run.** Where a check passes without running a fix's test (the test runner's default config leaves the file out), verify no longer says the test passes without the fix. It breaks the test on purpose, sees the check still pass, and says the check doesn't run it, so it can't tell.
16
+ - **A lockfile in a subfolder.** When a branch changes the lockfile of a service in a subfolder (a Python service's `uv.lock` beside its `pyproject.toml`, say), the merge queue now runs that lockfile's install in that folder of the merged tree, so the checks see the new dependency. Before, it only looked for lockfiles at the top.
17
+
5
18
  ## 0.30.1 (2026-11-02)
6
19
 
7
20
  More fixes from how code-kit is used: reads no longer stop a commit or trip a blocked command, a test-only fix may carry a tool's records, and file paths reach git literally.
@@ -57,6 +57,7 @@ import {
57
57
  owns,
58
58
  protectedEntry,
59
59
  leadNeedsApproval,
60
+ beforeSetup,
60
61
  approvalEnded,
61
62
  recordRequest,
62
63
  sessionRoot,
@@ -634,6 +635,8 @@ function recordApprovals() {
634
635
  );
635
636
  }
636
637
  }
638
+ // The commit that switches code-kit on: the person approved the setup it holds as init showed it.
639
+ const setup = settingUp && files.includes(CONFIG_FILE) && beforeSetup(root);
637
640
  for (const file of files) {
638
641
  // Concluding a merge: what arrives as the other branch has it was logged there, with its approvals.
639
642
  if (arrivesWithMerge(root, file, { staged: true })) continue;
@@ -646,6 +649,14 @@ function recordApprovals() {
646
649
  const granted = entry && approval(root, entry.approval, actor);
647
650
  const byDependency = actor.kind === 'lane' && dependencyChange(actor, file, root, config);
648
651
  const leadFree = actor.kind === 'lead' && !leadNeedsApproval(entry?.approval, config);
652
+ if (entry && !granted && setup) {
653
+ record(file, {
654
+ approval: entry.approval,
655
+ reason: 'The setup that switches code-kit on, as the person approved it in init.',
656
+ setup: true,
657
+ });
658
+ continue;
659
+ }
649
660
  if (entry && !granted && !leadFree && !byDependency) {
650
661
  recordRequest(root, actor, entry.approval, file, entry.why);
651
662
  block(
@@ -768,12 +779,26 @@ ${approvalHowTo(TESTS_APPROVAL, actor, root, 'weakening tests in one commit', pe
768
779
  const BEFORE_COMMIT = new RegExp(
769
780
  String.raw`^(?:cd\s|${GIT}(?:add|rm|mv|restore\s+--staged|reset\s+--soft)(?![\w-]))`,
770
781
  );
782
+ // Setting shell variables (`f=docs/x.md`, `export MSG="…"`) writes no file, unless a value runs a
783
+ // command. What a later `git add "$f"` stages can't be read, so it counts as every changed file.
784
+ const ASSIGNS_ONLY = /^(?:export\s+)?[A-Za-z_]\w*=\S*(?:\s+[A-Za-z_]\w*=\S*)*$/;
785
+ const assignsOnly = (c) => ASSIGNS_ONLY.test(c.code) && !/`|\$\(|<\(/.test(c.text);
786
+ // A tool's command that writes only the tool's own records (an adapter's `shell.records`), which any
787
+ // actor may write and no check covers, with no redirect of its own.
788
+ const recordsOnly = (c) =>
789
+ !/[<>]/.test(c.code) && (config.shell.records ?? []).some((re) => new RegExp(re).test(c.text));
771
790
  function writesBeforeCommit() {
772
791
  const pieces = commandsOf(withoutHarmlessRedirects(cmd));
773
792
  const at = pieces.findIndex((c) => new RegExp(String.raw`^${GIT}commit(?![\w-])`).test(c.text));
774
793
  return pieces
775
794
  .slice(0, Math.max(at, 0))
776
- .find((c) => (!BEFORE_COMMIT.test(c.text) || /[<>]/.test(c.code)) && !readsOnly(c.whole));
795
+ .find(
796
+ (c) =>
797
+ (!BEFORE_COMMIT.test(c.text) || /[<>]/.test(c.code)) &&
798
+ !readsOnly(c.whole) &&
799
+ !assignsOnly(c) &&
800
+ !recordsOnly(c),
801
+ );
777
802
  }
778
803
 
779
804
  if (commits) {
@@ -68,6 +68,9 @@ export default {
68
68
  why: "Ratifying a Context Graph proposal with --commit, dropping one, and changing Context Graph's harness settings are the person's own acts: they run them themselves, with a `!` command, or from the Context Graph pane.",
69
69
  },
70
70
  ],
71
+ // Recording a decision or writing a card writes only ctx's own records (anyActor above), so a commit
72
+ // may follow it in the same command.
73
+ records: [String.raw`^${CTX}\s+(?:record|card)\b`],
71
74
  restricted: [
72
75
  {
73
76
  pattern: 'Ctx-Ratified-By\\s*[:=][^\\n"\']*\\(delegated\\)',
@@ -99,6 +99,7 @@ export function applyAdapters(config, raw, root) {
99
99
  merged.protected.push(...(c.protected ?? []));
100
100
  merged.shell.block.push(...(a.shell?.block ?? []));
101
101
  merged.shell.restricted.push(...(a.shell?.restricted ?? []));
102
+ (merged.shell.records ??= []).push(...(a.shell?.records ?? []));
102
103
  }
103
104
  merged.adapters = active.map((a) => a.name);
104
105
  return merged;
@@ -140,6 +140,7 @@ const JS = [
140
140
  'npm-shrinkwrap.json',
141
141
  'yarn.lock',
142
142
  ];
143
+ const shellQuote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
143
144
  const INSTALLERS = [
144
145
  ['pnpm-lock.yaml', 'pnpm install --frozen-lockfile --prefer-offline', JS],
145
146
  ['package-lock.json', 'npm ci --prefer-offline --no-audit --no-fund', JS],
@@ -163,10 +164,25 @@ const INSTALLERS = [
163
164
  export function matchInstalls(dir, from, { prepare = null, timeout = 900000 } = {}) {
164
165
  const differ = dependencyDifferences(from, dir);
165
166
  const copied = installsOf(dir).length > 0;
166
- const present = INSTALLERS.filter(([lock]) => existsSync(join(dir, lock)));
167
- const known = present.find(([, , files]) => differ.some((f) => files.includes(basename(f))));
168
- const command = differ.length ? (prepare ?? known?.[1] ?? null) : null;
169
- const facts = { differ, copied, lockfile: present.length > 0 };
167
+ // Each file that differs is installed by the nearest lockfile of its ecosystem at or above its folder
168
+ // (a service in a subfolder with its own lockfile, a workspace package under the top one's), run there.
169
+ const installs = [];
170
+ for (const f of differ) {
171
+ for (let folder = dirname(f); ; folder = dirname(folder)) {
172
+ const found = INSTALLERS.find(
173
+ ([lock, , files]) => files.includes(basename(f)) && existsSync(join(dir, folder, lock)),
174
+ );
175
+ if (found) {
176
+ const run = folder === '.' ? found[1] : `(cd ${shellQuote(folder)} && ${found[1]})`;
177
+ if (!installs.includes(run)) installs.push(run);
178
+ break;
179
+ }
180
+ if (folder === '.') break;
181
+ }
182
+ }
183
+ const present = INSTALLERS.some(([lock]) => existsSync(join(dir, lock))) || installs.length > 0;
184
+ const command = differ.length ? (prepare ?? (installs.join(' && ') || null)) : null;
185
+ const facts = { differ, copied, lockfile: present };
170
186
  if (!command) return { ...facts, command: null, failed: null };
171
187
  const res = spawnSync(command, { cwd: dir, shell: true, encoding: 'utf8', timeout });
172
188
  if (res.status === 0) return { ...facts, command, failed: null };
@@ -93,12 +93,18 @@ export const screenKey = (name) =>
93
93
  .toLowerCase();
94
94
 
95
95
  /** The states a `**States:**` line or a States cell lists, in lower case. */
96
- const statesOf = (text) =>
97
- String(text)
98
- .replace(/<br\s*\/?>/gi, ',')
99
- .split(/[,;/]/)
100
- .map((s) => screenKey(s).replace(/\.$/, ''))
101
- .filter(Boolean);
96
+ // A state's own brackets keep their commas: `error (timed out, offline)` is one state.
97
+ const statesOf = (text) => {
98
+ const states = [''];
99
+ let depth = 0;
100
+ for (const ch of String(text).replace(/<br\s*\/?>/gi, ',')) {
101
+ if ('([{'.includes(ch)) depth++;
102
+ else if (')]}'.includes(ch)) depth = Math.max(0, depth - 1);
103
+ if (depth === 0 && ',;/'.includes(ch)) states.push('');
104
+ else states[states.length - 1] += ch;
105
+ }
106
+ return states.map((s) => screenKey(s).replace(/\.$/, '')).filter(Boolean);
107
+ };
102
108
 
103
109
  /** A `- **Name** …` bullet that lists a screen: { indent, title }, or null (a field such as `**States:**`). */
104
110
  function screenBullet(line) {
@@ -4,7 +4,7 @@
4
4
  // WHO-2), the person's otherwise and always on the lead's own. The commit hook
5
5
  // refuses a weakening commit; verify finds what a branch weakened, from git.
6
6
  import { execFileSync, spawnSync } from 'node:child_process';
7
- import { existsSync, readFileSync, rmSync } from 'node:fs';
7
+ import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
8
8
  import { join } from 'node:path';
9
9
  import { freshCheckout } from './checkout.mjs';
10
10
  import { runChecks } from './checks.mjs';
@@ -227,6 +227,9 @@ const UNREACHABLE =
227
227
  const ASSERTED =
228
228
  /AssertionError|AssertionFailedError|Expected:|Received:|expected .+ to |toBe|toEqual|assert\w* failed|^\s*--- FAIL|Error: expect\(/m;
229
229
 
230
+ // What a test file holds to break it: unbalanced, so no language's parser takes it.
231
+ const UNPARSEABLE = 'broken on purpose by code-kit, to see whether a check runs this test (\n';
232
+
230
233
  /** The names a failure says can't be reached: quoted ones on its unreachable lines. */
231
234
  function missingNames(output) {
232
235
  const names = new Set();
@@ -326,6 +329,16 @@ export function proveFix({ root, from, base, changed, config, fix }) {
326
329
  `${what}, but its tests (${tests.join(', ')}) pass without the fix's other changes, and fail without it only because they load test code the fix adds (${added.join(', ')}), which the base never had. A test that goes through the code the fix changed fails on an assertion when the bug is there: write that one. If the fix is only in the tests and their helpers, keep the branch to test files.`,
327
330
  ];
328
331
  }
332
+ if (!without) {
333
+ // A check can pass without running a test at all (its runner's config leaves the file out). Broken
334
+ // on purpose, a test it runs fails: one that still passes was never run, so it shows nothing.
335
+ for (const f of tests) writeFileSync(join(dir, f), UNPARSEABLE);
336
+ const { failure: broken } = runChecks(strict, tests, dir, actor);
337
+ if (!broken)
338
+ return [
339
+ `${what}, but the checks covering its tests (${covering.map((c) => c.name).join(', ')}) pass even with them broken, so they don't run them (${tests.join(', ')}), and code-kit can't tell whether they fail without the fix. Give the tests a check that runs them: where the test runner's default config leaves them out, a check that runs them with the config that includes them.`,
340
+ ];
341
+ }
329
342
  if (!without)
330
343
  return [
331
344
  `${what}, but its tests (${tests.join(', ')}) also pass without the fix, so they don't prove the bug and it can come back. Write a test that fails on ${base} and passes here.`,
@@ -31,6 +31,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
31
31
  import { fileURLToPath } from 'node:url';
32
32
  import { DEPENDENCY_APPROVAL, isDependencyFile } from './dependencies.mjs';
33
33
  import { globToRegExp, literalPath, matchesAny } from './glob.mjs';
34
+ import { CONFIG_FILE } from './config.mjs';
34
35
  import { noteFor } from './standards.mjs';
35
36
 
36
37
  export const APPROVAL_LOG = '.claude/approval-log.jsonl';
@@ -105,6 +106,29 @@ export const leadNeedsApproval = (name, config) =>
105
106
  Boolean(config?.approvals?.delegate?.merge) &&
106
107
  !leadDecides(name, config, { kind: 'lead' });
107
108
 
109
+ /**
110
+ * Whether code-kit is being set up in `root`: its config is in the checkout, not ignored, and no commit
111
+ * the repository has ever held it. The person approves the setup as init shows it, the specs, standards
112
+ * and design register it protects included, so until the commit that switches code-kit on the lead
113
+ * writes and commits them with no approval of their own. Once any commit has held the config it never
114
+ * is again, even after a commit takes the config away.
115
+ */
116
+ export function beforeSetup(root) {
117
+ const git = (...args) => {
118
+ try {
119
+ return execFileSync('git', ['-C', root, ...args], {
120
+ encoding: 'utf8',
121
+ stdio: ['ignore', 'pipe', 'ignore'],
122
+ });
123
+ } catch {
124
+ return null;
125
+ }
126
+ };
127
+ if (!existsSync(join(root, CONFIG_FILE))) return false;
128
+ if (git('check-ignore', '-q', CONFIG_FILE) !== null) return false;
129
+ return git('log', '--all', '--format=%H', '-1', '--', CONFIG_FILE) === '';
130
+ }
131
+
108
132
  /** HELM-2: whose decision approvals `names` are: the lead's when it may grant every one, else the person's. */
109
133
  export const decidedBy = (names, config, actor) =>
110
134
  [names].flat().every((n) => leadDecides(n, config, actor)) ? 'lead' : 'person';
@@ -810,7 +834,9 @@ export function writeProblem(actor, rel, root, config) {
810
834
  // The lead writes protected files without an approval where the person merges: they review them in
811
835
  // the pull request, and every committed change is in the audit log. Where the lead merges, what the
812
836
  // person keeps needs their approval (WHO-1). Anyone else needs an approval as well.
813
- const leadFree = actor.kind === 'lead' && !leadNeedsApproval(guarded?.approval, config);
837
+ const leadFree =
838
+ actor.kind === 'lead' &&
839
+ (!leadNeedsApproval(guarded?.approval, config) || (guarded && beforeSetup(root)));
814
840
  if (guarded && !leadFree && !approval(root, guarded.approval, actor)) {
815
841
  recordRequest(root, actor, guarded.approval, rel, guarded.why);
816
842
  const who =
@@ -119,6 +119,13 @@ const READERS = [
119
119
  /^(?!.*\s(?:-[a-zA-Z]*o|--output\b|--compress-program\b))sort(?:\s|$)/,
120
120
  ];
121
121
 
122
+ // code-kit's own commands that only read and print: what the config says, who owns a path, the
123
+ // imports, a requirement's trail, the build's state, the next step and the approved designs (not their
124
+ // `evidence`, which records a screenshot), with nothing written but code-kit's own state.
125
+ const CODE_KIT_READS = new RegExp(
126
+ String.raw`^(?!.*\s--write\b)${CODE_KIT}\s+(?:check|who|unowned|diff|graph|trace|adapters|status|next|designs(?!\s+evidence\b))(?:\s|$)`,
127
+ );
128
+
122
129
  /** A command's words, quotes taken off. */
123
130
  const wordsOf = (text) =>
124
131
  (text.match(/'[^']*'|"(?:\\.|[^"\\])*"|\S+/g) ?? []).map((w) =>
@@ -189,6 +196,7 @@ export function readsOnly(cmd) {
189
196
  parts.length > 0 &&
190
197
  parts.every(({ text, code: c }) => {
191
198
  if (READERS.some((re) => re.test(c))) return true;
199
+ if (CODE_KIT_READS.test(text)) return true;
192
200
  if (/^sed(?:\s|$)/.test(c)) return sedPrints(text);
193
201
  if (/^awk(?:\s|$)/.test(c)) return awkPrints(text);
194
202
  if (/^uniq(?:\s|$)/.test(c)) return uniqPrints(text);
@@ -161,12 +161,14 @@ export const BUSY_MS = 3 * 60_000;
161
161
  /**
162
162
  * LEAN-6: whether a lane agent is still at work on a worktree's story, by the story's event log (spec
163
163
  * 26): its lane's last act is still open, or came within BUSY_MS, with no hand-back or stop after it. Releasing
164
- * a worktree under a running agent takes its git away mid-step.
164
+ * a worktree under a running agent takes its git away mid-step. Only the branch's own lane counts: the
165
+ * lead's helpers (a reviewer, a security reviewer) act on the story too, but never commit on its branch.
165
166
  */
166
167
  export function agentBusy(root, w, now = Date.now()) {
167
- if (!w.story) return false;
168
+ if (!w.story || !w.branch?.includes('/')) return false;
169
+ const lane = w.branch.split('/')[0];
168
170
  const last = readEvents(root, w.story)
169
- .filter((e) => e.actor && e.actor !== 'lead' && e.agent)
171
+ .filter((e) => e.actor === lane && e.agent)
170
172
  .at(-1);
171
173
  if (!last || ['handback', 'stopped'].includes(last.kind)) return false;
172
174
  return last.phase === 'start' || now - Date.parse(last.at) < BUSY_MS;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@warren-dean/code-kit",
3
- "version": "0.30.1",
3
+ "version": "0.30.2",
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",
@@ -162,7 +162,7 @@ Once they approve (with any changes):
162
162
  - tell the person to make the `code-kit` check required on the protected branches;
163
163
  - run `code-kit ci check` on the project's own workflows. Each story is its own branch, pull request and merge, so a workflow that runs its full suite on every push to the base or every pull request runs once per story, after the merge queue has already run the checks. Show the person what it found and the changes you propose: the full suite on `release/**` instead (`code-kit release <version>` cuts one when they release), a `timeout-minutes` on each job, and `concurrency` with `cancel-in-progress` on pull requests. Changing CI is theirs to approve (approval `ci`); make only the changes they approve.
164
164
  7. Run `check` and `unowned` again, without `--config`.
165
- 8. Commit the setup straight onto the base branch (usually `main`), not a branch: while the base has no `.claude/code-kit.json` committed, the hooks let the lead make that one commit, so the rules the person just approved are in force on `main` and the lead can merge reviewed work from the start, with no first merge for anyone to make. The kit records the protected files in `.claude/approval-log.jsonl`. If the base already has rules (an update, section 4), commit on a branch as usual.
165
+ 8. Commit the setup straight onto the base branch (usually `main`), not a branch: while the base has no `.claude/code-kit.json` committed, the hooks let the lead make that one commit, so the rules the person just approved are in force on `main` and the lead can merge reviewed work from the start, with no first merge for anyone to make. The person's approval of the setup covers the protected files in it (the specs, the standards, the design register): they need no approvals of their own in that commit, and the kit records each in `.claude/approval-log.jsonl` as part of the setup. Don't ask the person for them. If the base already has rules (an update, section 4), commit on a branch as usual.
166
166
  9. **A team, only if there is one.** Not every developer works in a team. Ask once: "Do other developers work in this repository with their own Claude Code sessions?" If yes, run `/code-kit:team-init` now (it asks who the tech lead is and who owns which lanes, and writes the `team` section). If no, or not yet, leave it out and say `/code-kit:team-init` sets it up any time.
167
167
  10. Set up each companion the config now wants (`"adapters": { "<name>": true }`) by running its init skill, for example `/context-graph:init`, which asks nothing. Do it before reporting, so it's in place before the coding loop starts; `code-kit next` also gives `setup` until it is.
168
168