@warren-dean/code-kit 0.20.0 → 0.22.0

package/hooks/mod/view.mjs

@@ -256,7 +256,7 @@ export function lanesPane(
             : l.branch
               ? ` · ${l.branch}`
               : ''
-        }`
+        }${l.story.slice ? ` · slice ${l.story.slice}` : ''}`
       : l.name === LEAD
         ? 'the main session'
         : (l.agent ?? '');
@@ -728,13 +728,25 @@ export function bandLines({
   team = null,
   questions = [],
   brief = [],
-  denied = [],
   reports = [],
+  working = false,
+  task = null,
+  elsewhere = [],
 }) {
   const lines = [];
-  // MISSION-1: the goal, now, next and the agents at work, above what needs the person.
-  const mission = missionLines({ state, loop, leadBusy, live, nextStep, combined });
+  // MISSION-1: the goal, now, next and the agents at work, above what needs the person. SESS-3: a working
+  // session's band holds only its own: no mission, queue, reviews or team.
+  const mission = working ? [] : missionLines({ state, loop, leadBusy, live, nextStep, combined });
   lines.push(...mission);
+  // SESS-4: a working session's task, or that it records one before changing code.
+  if (working)
+    lines.push({
+      kind: 'task',
+      text: task
+        ? `your task: ${task.title}${task.paths?.length ? ` · leasing ${task.paths.join(', ')}` : ''}`
+        : 'a working session: record your task before changing code (code-kit task "…" --touches …)',
+      actions: [],
+    });
   if (notice)
     lines.push({ kind: 'notice', text: notice, actions: [{ id: 'dismiss', label: 'Dismiss' }] });
   if (!state || state.kind !== 'ok') return lines;
@@ -758,31 +770,15 @@ export function bandLines({
       ],
     });
   }
-  // PERM-1: Claude Code's own permission check refused a call only the person can let through.
-  if (denied.length) {
-    const [d] = denied;
-    lines.push({
-      kind: 'denied',
-      text: `${denied.length > 1 ? `${denied.length} calls refused by Claude Code: ` : 'Claude Code refused '}${d.who}'s ${d.what}`,
-      denial: d,
-      denials: denied,
-      actions: [
-        ...(d.command ? [{ id: 'runDenied', label: 'Put it in the prompt' }] : []),
-        { id: 'deniedDone', label: 'Done it' },
-        { id: 'deniedNo', label: 'Not now' },
-      ],
-    });
-  }
-  // LOOP-3: a lane stalled past its restarts waits for the person.
+  // OWN-2: a call Claude Code's own permission check refused is the Lanes pane's activity, not a
+  // decision: the agent finds another way, or the lead asks the person (`code-kit ask`).
+  // LOOP-3, WHO-4: a lane stalled past its restarts is the lead's to sort out; the person sees a note.
   for (const f of loop?.flagged ?? [])
     lines.push({
       kind: 'stalled',
-      text: `${f.lane} stalled ${f.count} times on ${f.story}`,
+      text: `${f.lane} stalled ${f.count} times on ${f.story}: the lead decides how it goes on`,
       stall: f,
-      actions: [
-        { id: 'lanes', label: 'Lanes' },
-        { id: 'resumeStall', label: 'Resume' },
-      ],
+      actions: [{ id: 'lanes', label: 'Lanes' }],
     });
   // LOOP-5: under autonomy propose, each step waits for Go.
   if (loop?.proposal?.first)
@@ -797,15 +793,20 @@ export function bandLines({
         { id: 'loopOff', label: 'Off' },
       ],
     });
+  else if (loop?.proposal?.repeated)
+    // LOOP-8, WHO-4: a step the lead was asked for three times and didn't take is a note, not a decision.
+    lines.push({
+      kind: 'stuck',
+      text: `${loop.proposal.label}: still next after ${loop.proposal.repeated} prompts to the lead`,
+      proposal: loop.proposal,
+      actions: [{ id: 'go', label: 'Ask again' }],
+    });
   else if (loop?.proposal)
     lines.push({
       kind: 'proposal',
-      // LOOP-8: a step the lead was asked for and didn't take waits for the person to ask again.
-      text: loop.proposal.repeated
-        ? `${loop.proposal.label}: still next after ${loop.proposal.repeated} prompts. Ask the lead again?`
-        : `${loop.proposal.label}?`,
+      text: `${loop.proposal.label}?`,
       proposal: loop.proposal,
-      actions: [{ id: 'go', label: loop.proposal.repeated ? 'Ask again' : 'Go' }],
+      actions: [{ id: 'go', label: 'Go' }],
     });
   // LOOP-11, LOOP-12: what the loop read in the lead's reply holds it until the person says.
   const waitingLine = waitingOf(loop?.waiting);
@@ -833,7 +834,7 @@ export function bandLines({
       actions: [{ id: 'openDecision', label: 'Answer…' }],
     });
   // ASK-4: the brief's open questions, the person's to answer.
-  if (brief.length)
+  if (brief.length && !working)
     lines.push({
       kind: 'brief',
       text: `${plural(brief.length, 'open question', 'open questions')} in your brief: ${brief[0].question}`,
@@ -848,7 +849,7 @@ export function bandLines({
   const inReview = loopOff
     ? state.lanes.filter((l) => l.state === 'in review').map((l) => l.story)
     : [];
-  if (inReview.length) {
+  if (inReview.length && !working) {
     const [story] = inReview;
     const ids = inReview.map((s) => s.id).join(', ');
     lines.push(
@@ -891,7 +892,7 @@ export function bandLines({
   const autonomous = (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
   // SETUP-2: with no rules on the base yet, the lead puts them there first and then merges.
   const leadMerges = autonomous && (check?.delegatesMerge || check?.firstMerge);
-  if (next && !leadMerges)
+  if (next && !leadMerges && !working)
     lines.push({
       kind: 'queue',
       text: `${next.branch} is next to merge`,
@@ -899,9 +900,9 @@ export function bandLines({
       actions: [{ id: 'mergeQueue', label: 'Merge' }],
     });
   // TEAM-7, TEAM-9: what of the team needs this person.
-  lines.push(...teamLines(team, check?.lanes ?? {}));
+  if (!working) lines.push(...teamLines(team, check?.lanes ?? {}));
   // REPORT-3: a bug report for code-kit an agent drafted, for the person to read and send, or not.
-  if (reports.length)
+  if (reports.length && !working)
     lines.push({
       kind: 'report',
       text: `${reports.length > 1 ? `${reports.length} bug reports for code-kit to send: ` : 'A bug report for code-kit to send: '}${reports[0].title}`,
@@ -922,11 +923,14 @@ export function bandLines({
   // With the mission rows drawn, the loop's state and its Pause or Resume are on the `now` row.
   else if (mission.length) {
     // nothing more
-  } else if (loop?.state === 'elsewhere')
-    // LOOP-10: another session in this project runs the loop; this one never prompts its lead.
+  } else if (loop?.state === 'elsewhere' || loop?.state === 'unled')
+    // SESS-2: another session leads the project, or none does; this one never prompts its lead.
     lines.push({
       kind: 'loop',
-      text: 'the loop runs in another session',
+      text:
+        loop.state === 'elsewhere'
+          ? 'the lead is in another session'
+          : 'no session leads the project: the loop waits for one',
       actions: [{ id: 'leadHere', label: 'Lead from here' }],
     });
   else if (loop?.state === 'paused')
@@ -937,6 +941,13 @@ export function bandLines({
       text: `loop on${loop.last ? ` · last: ${loop.last}` : ''}`,
       actions: [{ id: 'pause', label: 'Pause' }],
     });
+  // OWN-1: another session's decisions are answered there: here, only how many.
+  for (const e of elsewhere)
+    lines.push({
+      kind: 'elsewhere',
+      text: `${plural(e.count, 'decision', 'decisions')} in session ${e.member}, answered there`,
+      actions: [],
+    });
   // BAND-4: a digit for every action, in the order they're drawn.
   let digit = 0;
   for (const line of lines)
@@ -969,9 +980,10 @@ export function waitingOf(waiting) {
       waiting,
       actions: [{ id: 'carryOn', label: 'Carry on' }],
     };
+  // WHO-4: a step the lead said it couldn't take is a note: the loop asks again once the project moves.
   if (waiting.kind === 'blocked')
     return {
-      kind: 'waiting',
+      kind: 'stuck',
       text: `${waiting.label}: the lead didn't take it${waiting.reason ? `: ${waiting.reason}` : ''}`,
       waiting,
       actions: [{ id: 'askAgain', label: 'Ask again' }],
@@ -1006,8 +1018,8 @@ export function band(lines, { Box, Text, Button }, onAction) {
     facts: 'yellow',
     question: 'cyan',
     brief: 'cyan',
-    denied: 'red',
     report: 'magenta',
+    stuck: 'yellow',
   };
   const LIVE = { quiet: 'yellow', stalled: 'red' };
   const LABEL = 8;
@@ -1516,7 +1528,17 @@ const CHOICES = {
   'compact.milestone': ['ask', 'auto', 'off'],
 };
 const shown = (v) =>
-  v === null || v === '' ? "the session's" : v === true ? 'on' : v === false ? 'off' : String(v);
+  v === null || v === ''
+    ? "the session's"
+    : v === true
+      ? 'on'
+      : v === false
+        ? 'off'
+        : v === 'lead'
+          ? 'the lead'
+          : v === 'person'
+            ? 'you'
+            : String(v);
 
 /**
  * The Settings view: each setting from `code-kit settings --json` with a control, and, once one is
@@ -1524,7 +1546,8 @@ const shown = (v) =>
  */
 export function settingsView(rows, pending, { Box, Text, Select, Input, Button }, handlers) {
   const control = (r) => {
-    const listed = CHOICES[r.key] ?? (typeof r.default === 'boolean' ? [true, false] : null);
+    const listed =
+      r.choices ?? CHOICES[r.key] ?? (typeof r.default === 'boolean' ? [true, false] : null);
     // A value the list doesn't name (a model given by its id) is still shown, as the one chosen.
     const choices =
       listed && !listed.map(String).includes(String(r.value ?? '')) ? [...listed, r.value] : listed;
@@ -1544,7 +1567,7 @@ export function settingsView(rows, pending, { Box, Text, Select, Input, Button }
       onSubmit: (v) => handlers.onChoose(r.key, v.trim()),
     });
   };
-  const rowsView = rows.map((r) =>
+  const rowView = (r) =>
     Box({
       key: `setting-${r.key}`,
       flexDirection: 'column',
@@ -1553,7 +1576,15 @@ export function settingsView(rows, pending, { Box, Text, Select, Input, Button }
           flexDirection: 'row',
           columnGap: 2,
           children: [
-            Box({ width: 28, children: [Text({ bold: true, children: [r.key] })] }),
+            Box({
+              width: 34,
+              children: [
+                Text({
+                  bold: true,
+                  children: [r.section === 'Approvals' ? r.key.replace(/^approvals\./, '') : r.key],
+                }),
+              ],
+            }),
             control(r),
             ...(r.value !== r.default
               ? [Text({ dimColor: true, children: [`default ${shown(r.default)}`] })]
@@ -1570,8 +1601,26 @@ export function settingsView(rows, pending, { Box, Text, Select, Input, Button }
         }),
         Text({ dimColor: true, children: [`  ${r.about}`] }),
       ],
-    }),
-  );
+    });
+  // WHO-3: the harness, then who decides each approval.
+  const section = (name) => rows.filter((r) => (r.section ?? 'Harness') === name);
+  const approvals = section('Approvals');
+  const rowsView = [
+    ...section('Harness').map(rowView),
+    ...(approvals.length
+      ? [
+          Text({ key: 'approvals-heading', bold: true, color: 'cyan', children: ['APPROVALS'] }),
+          Text({
+            key: 'approvals-about',
+            dimColor: true,
+            children: [
+              "Who decides what a lane can't do on its own. The lead decides what's technical; you keep product, design, CI and the kit.",
+            ],
+          }),
+          ...approvals.map(rowView),
+        ]
+      : []),
+  ];
   const confirm = pending
     ? [
         Box({
@@ -1627,7 +1676,9 @@ export function settingsView(rows, pending, { Box, Text, Select, Input, Button }
       Box({ flexDirection: 'column', children: rowsView }),
       Text({
         dimColor: true,
-        children: ['Lanes, paths, layers and protected paths change through /code-kit:init.'],
+        children: [
+          'Lanes, paths, layers and which paths are protected change through /code-kit:init.',
+        ],
       }),
     ],
   });

package/hooks/post-edit-check.mjs

@@ -7,8 +7,10 @@ import { join } from 'node:path';
 import { matchesAny } from './lib/glob.mjs';
 import { loadBaseline, newProblems } from './lib/baseline.mjs';
 import { block, start } from './lib/hook.mjs';
-import { layerProblems } from './lib/layers.mjs';
+import { brokenLayerRule, layerProblems } from './lib/layers.mjs';
+import { noteFor } from './lib/standards.mjs';
 import { projectWorktrees, relativeTo, worktreeRoot } from './lib/rules.mjs';
+import { noteWrite } from './lib/sessions.mjs';
 
 const { input, project, config, error } = start();
 const target = input.tool_input?.file_path;
@@ -19,10 +21,15 @@ const root = found && projectWorktrees(project).includes(found) ? found : null;
 if (!root) process.exit(0); // another repository, or Claude's memory: not this project's code
 const rel = relativeTo(root, target);
 if (!existsSync(join(root, rel))) process.exit(0);
+// SESS-5: in the checkout every session shares, which session wrote the file, for a blocked git to name.
+if (root === projectWorktrees(project)[0]) noteWrite(project, input.session_id, rel);
 
 // Violations recorded in the baseline (brownfield code as it was adopted) don't block; new ones do.
 const layers = layerProblems(rel, readFileSync(join(root, rel), 'utf8'), config);
 const problems = newProblems(rel, layers, loadBaseline(project));
+// STD-4: a layer rule a project standard names says which standard it is.
+const note = problems.length ? noteFor(root, config, problems.map(brokenLayerRule)) : '';
+if (note) problems.push(note.trim());
 const quoted = `'${rel.replace(/'/g, `'\\''`)}'`;
 for (const check of config.postEdit) {
   if (!matchesAny(rel, check.files) || matchesAny(rel, check.exclude)) continue;

package/hooks/session.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// SessionStart and SessionEnd (docs/specs/23-the-team.md): a session starting is recorded as a member
+// of the team, the lead session when no other live session leads (SESS-2); as it ends, it leads nothing
+// more, and the lanes its agents had claimed are free again (SCHED-1). Its task stays, stale (SESS-4).
+import { readFileSync } from 'node:fs';
+import { loadConfig } from './lib/config.mjs';
+import { releaseSession } from './lib/laneclaims.mjs';
+import { endSession, startSession } from './lib/sessions.mjs';
+import { projectDir } from './lib/rules.mjs';
+
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8') || '{}');
+} catch {
+  // no input: nothing to do
+}
+const project = projectDir();
+const { config } = loadConfig(project);
+const session = input.session_id ?? null;
+if (config && session && process.argv[2] === 'start') startSession(project, session);
+if (config && session && process.argv[2] === 'end') {
+  endSession(project, session);
+  releaseSession(project, session);
+}

package/hooks/stop-check.mjs

@@ -7,13 +7,26 @@ import { join } from 'node:path';
 import { loadBaseline, newProblems } from './lib/baseline.mjs';
 import { runChecks } from './lib/checks.mjs';
 import { block, start } from './lib/hook.mjs';
-import { layerProblems } from './lib/layers.mjs';
+import { brokenLayerRule, layerProblems } from './lib/layers.mjs';
+import { noteFor } from './lib/standards.mjs';
 import { actorFor, actorRoot, currentBranch, reportPath } from './lib/rules.mjs';
 import { storyOfBranch } from './lib/teamfacts.mjs';
+import { releaseLane } from './lib/laneclaims.mjs';
 import { auditProblems, changedFiles } from './lane-audit.mjs';
 
 const { input, project, config, error } = start();
 
+// SCHED-1: a lane agent whose finish goes through frees its lane for the next story. A refused finish
+// (exit 2) keeps it: the agent carries on.
+const finishingLane =
+  input.agent_id && config
+    ? Object.entries(config.lanes).find(([, l]) => l.agent === input.agent_type)?.[0]
+    : null;
+if (finishingLane)
+  process.on('exit', (code) => {
+    if (code === 0) releaseLane(project, finishingLane, { session: input.session_id ?? null });
+  });
+
 // Stop hooks share one `stop_hook_active` flag, so another plugin's block would make this check skip
 // itself. Instead this hook remembers its own last block per session and agent. The same problem
 // reported MAX_REPEATS times in a row means no progress: say so and let the finish through rather than
@@ -84,10 +97,17 @@ const layers = changed
     newProblems(f, layerProblems(f, readFileSync(join(root, f), 'utf8'), config), baseline),
   );
 if (layers.length)
-  fail('Imports break the layer rules (.claude/code-kit.json › layers):', layers.join('\n'));
+  fail(
+    `Imports break the layer rules (.claude/code-kit.json › layers):${noteFor(root, config, layers.map(brokenLayerRule))}`,
+    layers.join('\n'),
+  );
 
 const { failure } = runChecks(config, changed, root, actor);
-if (failure) fail(failure.title, failure.output);
+if (failure)
+  fail(
+    `${failure.title}${noteFor(root, config, { kind: 'check', name: failure.check })}`,
+    failure.output,
+  );
 
 // A lane hands back committed work on its own branch; the lead reviews and merges it.
 if (actor.kind === 'lane' && changed.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "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",
   "license": "MIT",
   "author": "Warren Langeveldt",

package/skills/decide/SKILL.md

@@ -5,7 +5,7 @@ description: The lead decides what a lane asked for and couldn't do itself (a ne
 
 # Decide a lane's request
 
-The person sets the guardrails: the specs, the architecture (contracts, layers, the rules in `.claude/code-kit.json`), the screens' visual design, CI, weakened tests, and product questions the spec doesn't answer. Inside them, you run the team. A lane that needs something it can't do itself asks you, and you decide on the merits. Passing a request to the person because you could is not deciding: they'd approve it by default, and the check would be gone.
+The person is the product owner and sets the guardrails: the specs, the screens' visual design, CI and the pipelines, the kit (the rules in `.claude/code-kit.json`), and product questions the spec doesn't answer, plus anything with production, cost or strategy implications. Everything technical is yours by default: contracts, migrations, packages, merges into the base, and a weakened test on a lane's branch once you've reviewed it (`code-kit approve tests --lane <lane> --delegated --story ST-n --reason "…"`); on your own branch a weakened test is the person's. Inside them, you run the team. A lane that needs something it can't do itself asks you, and you decide on the merits. Passing a request to the person because you could is not deciding: they'd approve it by default, and the check would be gone.
 
 The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
 

package/skills/dispatch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch
-description: Hand stories from the plan to their lane agents, as many at once as can safely run in parallel. Picks the ready stories, checks each is buildable, briefs each lane agent with its story, requirements and acceptance criteria, and starts it on its own branch and worktree. Use when the lead is ready to start building, asks what to work on next, or runs /code-kit:dispatch [story IDs, a milestone, or "next"].
+description: Hand stories from the plan to their lane agents, one per lane, every free lane at once. Picks the ready stories, checks each is buildable, briefs each lane agent with its story, requirements and acceptance criteria, and starts it on its own branch and worktree. Use when the lead is ready to start building, asks what to work on next, or runs /code-kit:dispatch [story IDs, a milestone, or "next"].
 ---
 
 # Dispatch stories to lanes
@@ -34,7 +34,7 @@ Then check:
 - **No open question blocks it.** If a spec's open questions touch a cited requirement, don't dispatch the story; list the question for the person.
 - **The contracts exist.** If the story needs an API schema, event or database contract that isn't written yet, that's the lead's work first. Write it (the lead owns contracts), commit it on the lead's branch, then dispatch. A lane never invents a contract.
 - **The lane is right.** Run `who` on the paths the story will touch. If they belong to two lanes, split the story or sequence it; don't hand one lane another's files.
-- **Nothing overlaps.** At most one story per lane at a time, unless two stories touch disjoint folders. Two lanes may run in parallel; that's the point of lanes.
+- **One story per lane.** A lane runs one story at a time across the whole project, every session included: two agents in one lane build on the same files in their worktrees and conflict at merge. Different lanes run in parallel; that's what the plan's dependencies are for. `code-kit next` offers at most one story for each free lane, the open slice's first (`**Slice:**`), and starting a second agent for a lane that's running one is refused, naming the story and the session that has it. `code-kit lanes` lists what each lane is running. If a lane's agent stopped without finishing (it was stopped, or its session ended), `code-kit lanes release <lane>` frees the lane for its next story.
 
 Commit everything the lanes need first. Each lane branches from the lead's branch as committed, so uncommitted work isn't there.
 

package/skills/init/SKILL.md

@@ -17,7 +17,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project
 - **No config, and the docs describe the architecture** → **New from docs** (sections 1–3).
 - **No config, and the docs are thin or missing** → **Brownfield** (sections 1–3, with the brownfield steps). The code is the main source, and the docs fill in what they can.
 
-- **No config, no code and no docs** (just an idea) → stop and suggest `/code-kit:spec-design` first. It writes the brief, specs, architecture, principles and plan this skill works from.
+- **No config, no code and no docs** (just an idea) → stop and suggest `/code-kit:spec-design` first. It writes the brief, specs, architecture, standards, principles and plan this skill works from.
 
 Say which one applies and why before you start.
 
@@ -74,11 +74,23 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
 - **`postEdit`:** the project's existing per-file linters and formatters, with `{file}`.
 - **`checks`:** the typecheck, test, architecture and database commands, each scoped by `files`. Only include commands that pass on the current code, or ones the person chose to keep.
 - **`harness.autonomy`:** ask the person how hands-off they want the build. With the code-kit mod (Claude Code 2.1.287 or later), once the plan has stories, a lead loop can keep the work moving between their prompts: it prompts the lead to dispatch ready stories, review finished ones and merge them where merges are delegated. Offer the three choices in plain words: `autonomous` (it keeps going on its own; they can pause it from the band), `propose` (each step waits in the band for their Go), or `off`. Put their answer in the draft as `"harness": { "autonomy": "…" }`. If they'd rather decide later, leave it out: the loop then asks them in the band before its first step. With `autonomous`, the lead owns delivery, so also draft `"merge": true` in `approvals.delegate`: the lead merges a reviewed branch once every check passes.
-- **`approvals.delegate`, who decides what (HELM-1):** the person sets the guardrails and decides what crosses them; the lead decides everything inside them, so lanes ask the lead, never the person. Draft `"dependencies": {}` (the lead approves a package only when the story's requirements need it and it fits the spec, the principles and the architecture; npm packages must also pass the default registry limits on licence, popularity and age) and `"protected"` listing every protected approval except those guarding the specs, contracts and the architecture's rules, the screens' designs (`design`), and CI. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. `tests` (weakening a test) is always theirs.
+- **`approvals.delegate`, who decides what (HELM-1, WHO-1):** the person is the product owner; the lead decides everything technical, so lanes ask the lead, never the person. With no `approvals.delegate`, that's the default: the lead approves new packages (only when the story's requirements need them and they fit the spec, the principles and the architecture; npm packages must also pass the registry limits on licence, popularity and age), every protected change except the specs (`spec`), the screens' designs (`design`), CI (`ci`) and the kit, merges into the base, and weakened tests on a lane's branch after its review. Show the person the split in two lines, what they keep and what the lead decides, and ask if they want to keep anything else. Only if they do, draft `approvals.delegate` with exactly what the lead keeps (`{ "protected": [...], "merge": true, "tests": true, "dependencies": {} }`, leaving out what they keep), or `false` to keep everything. They can change it later in the Settings tab's Approvals section.
 - **`harness.agents.lanes.model`:** ask which model the lane agents run on. Each lane agent builds one story inside its own paths, with its requirements and acceptance criteria in its brief, and the hooks, `verify` and the lead's review catch what it gets wrong, so Sonnet usually does the work well for much less than the session's model; recommend `sonnet`, and say the lead, the reviewer and the security reviewer keep the session's model. The mod sets it as each lane agent starts; a lane's agent file with its own `model:` keeps that. Put their answer in `harness` as `"agents": { "lanes": { "model": "sonnet" } }`, or leave it out for the session's model.
 - **`harness.report.on`:** ask whether agents may draft bug reports for code-kit itself when code-kit gets in their way (a refusal that shouldn't have happened, a crash). Each report holds only code-kit's own facts (its version, the rule, what it said, the command), never the project's code, paths or data, and waits in their Decisions tab: they read it and send it to code-kit's public GitHub under their own account, or discard it. Off unless they say yes; put `"report": { "on": true }` in `harness` if they do.
+- **`docs.standards`:** `docs/standards.md` unless the project keeps its standards elsewhere (see Standards, below).
 - **`approvals.lead`:** ask the person whether they'll ever approve from a phone or another chat-only client, where a `!` command arrives as plain text. If so, set it to `true`: the lead then records approvals they give in chat (`code-kit approve`), and runs the `shell.block` commands marked `person: true` when they say so. Mark a `shell.block` command `person: true` only if the person wants to be able to have the lead run it on their say-so. Leave the setting out if the lead will run unattended.
 
+### Standards (spec 22)
+
+After the layers, suggest the project's standards: named engineering rules every agent builds to, each graded and saying how firmly code-kit applies it. Standards are guardrails, and guardrails are the person's: suggest them, and write nothing until the person has approved, edited or dropped each one.
+
+- **Format.** Each standard is a `### <id> <title>` heading in `docs/standards.md`, followed by its fields, one per line: `level` (required or recommended), `applied` (enforced, checked or advice), `layers` (layer names, or all), `why` (one or two sentences), `source` (where it came from) and, for an enforced one, `enforced by`. The id's prefix is its category: `PRI-` principles (judgement, such as single responsibility; never enforced), `PAT-` patterns (how a kind of problem is solved here), `ARC-` architecture (what may depend on what, where things live), `CON-` conventions (naming, layout, tests' shape), `POL-` policies (what must or must never happen). The title is one sentence an agent can act on.
+- **How firmly.** Mark a standard `enforced` only where a rule the draft already has refuses the change, and name it: `enforced by: layers (domain may not import infrastructure)`, `layers (web may not import the package pg)`, `protected (<approval>)`, `check (<name>)` or `shell (<words of its why>)`. code-kit then names the standard in that rule's refusal. Everything else review can judge is `checked`; the rest is `advice`.
+- **With specs**, suggest them from the architecture, the principles, the specs' threat models and the brief's decision log, each citing its source (`source: the threat model in docs/specs/03-payments.md`). A threat model saying card numbers are never stored is a `POL-` standard; a layer rule the architecture sets is an `ARC-` standard enforced by that layer rule. The engineering rules in `docs/principles.md` move into standards; principles keeps the definition of done, the commands and the privacy and residency targets.
+- **With no specs but code**, infer them from the code: the import graph (`graph`) for layering and import directions; naming and folder layout; the data-access pattern (repositories, direct queries, an ORM); the formatter's and linter's configs; the tests' shape and where they live. Count, don't guess: each inferred standard carries its evidence (`source: the code: 41 of 43 modules reach the database through *Repository classes`), names the files that don't follow it, and starts as `recommended`. A pattern the code follows inconsistently (3 of 5 services through repositories, 2 querying directly) isn't a standard yet: put it to the person as a choice, with both counts, and write the way they pick.
+- **Protect the file.** Add `{ "glob": "docs/standards.md", "approval": "standards", "why": "the project's standards" }` to `protected`, before any broader glob that also covers `docs/`. The lead may approve adding a recommended standard if the person puts `standards` in `approvals.delegate.protected`; removing a standard, or weakening a required one, is always the person's, whatever the config delegates.
+- **Check it** once the config is written: `code-kit standards` reports a duplicate id, an unknown category, an enforced principle, or an `enforced by` that names no rule the config has. Each lane agent's rules then list the standards for its layers, one line each, and CLAUDE.md lists them all.
+
 Prove the draft:
 
 ```bash
@@ -124,6 +136,7 @@ Show the person:
 3. protected paths, blocked and restricted commands, and checks (including any left out because they fail today);
    and whether the lead may record approvals given in chat (`approvals.lead`), how hands-off the build is (`harness.autonomy`), the lane agents' model (`harness.agents.lanes.model`), and whether agents may draft bug reports for code-kit (`harness.report.on`);
 4. the project skills, and which lane agents use each;
+   and the standards you suggest, each with its category, level, how it's applied and its source (for inferred ones, the evidence and the files that don't follow it), with the choices where the code is inconsistent;
 5. the active adapters and what each adds, from `adapters`. A companion tool that's installed but not set up here (its init skill is in your skills list, for example `/context-graph:init` with no `.ctx/` folder): add `"adapters": { "<name>": true }` to the draft and say it will be set up before any code is written;
 6. every **question**: where the docs or the code are silent, ambiguous or contradictory. Don't guess; a wrong owner or layer blocks real work.
 
@@ -155,13 +168,14 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
 
 1. **Re-read** the docs and the repository as in section 1, including the brownfield steps if the code has grown past the docs.
 2. **Draft** the whole config again into `.claude/code-kit.draft.json`, starting from the live one. Keep everything that's still right, so the diff shows only real changes. If the live config has no `harness.autonomy`, ask the person about it as in section 2.
-   Bring code-kit's own instructions up to date: run `code-kit instructions`. Parts between markers are rewritten with `--write`. A part written before the markers (CLAUDE.md's `## Enforced, not advised` section, an agent's `Always:` list) is merged once: replace it with what `code-kit instructions show lead` or `show lane` prints, and move every line the project wrote itself into a section of its own outside the markers. Show the person the difference with the rest.
+   Bring code-kit's own instructions up to date: run `code-kit instructions`. Parts between markers are rewritten with `--write`. A part written before the markers (CLAUDE.md's `## Enforced, not advised` section, an agent's `Always:` list) is merged once: replace it with what `code-kit instructions show lead` or `show lane <lane>` prints, and move every line the project wrote itself into a section of its own outside the markers. Show the person the difference with the rest.
    A config without `"setup": 3` predates what setup now includes; add whichever of these the project is missing, as section 2 and 3 describe, and set `"setup": 3`:
    - project skills for the recipes in the docs (or, without recipes, the patterns the code follows), listed on the lane agents;
    - the design gate for every lane that owns screens, with its register; and design stories in the plan for screens not yet built (ask the person before adding stories);
    - the QA lane, its agent and its checks, when there are screens or journeys across lanes;
    - the security reviewer (`.claude/agents/security-reviewer.md`), unless the product handles no sign-in, personal data, payments, outside input or secrets; and, as a proposal for the person, a threat model and security requirements for each spec that lacks them (spec-design's section 4);
    - `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
+   - project standards, when the project has no `docs/standards.md`: suggest them as section 2's Standards describes, moving the engineering rules out of `docs/principles.md`, and protect the file.
 3. **Show the difference:**
 
    ```bash

package/skills/lead/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: lead
+description: Make this Claude Code session the project's lead session, where code-kit's loop runs and the plan's stories are dispatched from, when several sessions work one project. Says which session leads now and what moving the lead does, then gives the person the command that moves it. Use when the person says this session should lead, asks which session leads, or runs /code-kit:lead.
+---
+
+# Lead from this session
+
+Several Claude Code sessions can work one project at once. One is the lead session: code-kit's loop runs there, and the plan's stories are dispatched from it. The others are working sessions: they stay quiet (no loop prompts, no other session's decisions), and each records its ad hoc task, with the paths it leases, before it changes code.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project root.
+
+1. See who leads now:
+
+   ```bash
+   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" who
+   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sessions
+   ```
+
+2. If this session already leads, say so and stop.
+3. Otherwise, tell the person what moving the lead does: this session starts running the loop and dispatching the plan's stories, and the session that led becomes a working session, which stops prompting its lead. Choosing the lead is theirs, so give them the command to run themselves (the hooks refuse it from an agent), or point them to **Lead from here** in the code-kit band:
+
+   ```text
+   ! node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sessions lead
+   ```
+
+4. Once they have, run `who` again and confirm this session leads.
+
+A working session doesn't need this to work: it records its task (`code-kit task "<what>" --touches "<globs>"`), works in a worktree of its own, and `code-kit task done` when it's finished.

package/skills/next/SKILL.md

@@ -44,9 +44,9 @@ Run the named skill with the Skill tool: `code-kit:<step>`, with `args` (and the
 
 - **`setup`:** run the skill named in `args` (for example `context-graph:init`); it's another plugin's, so call it by that full name.
 - **`update`:** run `code-kit:init`. `why` names what the setup is missing (the design gate, design stories, a QA lane, a security reviewer); init adds those, shows the person the difference, and sets `"setup": 3`. Until then no new story starts; work already started goes on to review and merge.
-- **`instructions`:** there's no skill to run. With `args` `write`, run `code-kit instructions --write`. With `merge`, some files were written before code-kit marked its part: run `code-kit instructions` to list them, replace each old part with what `code-kit instructions show lead` (CLAUDE.md) or `show lane` (an agent file) prints, keep every line the project wrote itself outside the markers, then run `--write` for the rest. Commit it on a branch and merge it like your own stories.
+- **`instructions`:** there's no skill to run. With `args` `write`, run `code-kit instructions --write`. With `merge`, some files were written before code-kit marked its part: run `code-kit instructions` to list them, replace each old part with what `code-kit instructions show lead` (CLAUDE.md) or `show lane <lane>` (that lane's agent file) prints, keep every line the project wrote itself outside the markers, then run `--write` for the rest. Commit it on a branch and merge it like your own stories.
 - **`lead`:** there's no skill to run. Build each story yourself, on the branch `lead/st-<n>`: spec-check it first if it cites requirements, do the work, commit, then run `code-kit:review` on the branch like any other. A spike's result goes in the docs it names.
-- **`wait`:** say which stories are being built and on which branches, then stop. When a lane agent finishes, its notification arrives in this session; run this skill again then. If a story has been in progress with no agent running (the session ended, or the agent stopped without committing), dispatch it again.
+- **`wait`:** say which stories are being built and on which branches, and which ready stories wait for their lane (a lane runs one story at a time), then stop. When a lane agent finishes, its notification arrives in this session; run this skill again then. If a story has been in progress with no agent running (the session ended, or the agent stopped without committing), dispatch it again.
 - **`done`:** give the `status` summary in a few lines, then offer to run spec-design for the next milestone or feature.
 
 ## 3. Keep going until the person is needed

package/skills/review/SKILL.md

@@ -49,6 +49,7 @@ Read the story and every requirement it cites. Then start from what's already be
 - **The spec-check report matches:** its table has no row still `missing` or `conflicts` without an answer, and its questions were answered, not guessed.
 - **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements) are sent back, or split into their own story. A new dependency is yours to judge, as in `/code-kit:decide`: the story's requirements need it, nothing the project has does the job, and it fits the principles and the layer. Only what crosses a guardrail (the spec, a contract, the architecture) is the person's call.
 - **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
+- **Standards kept:** `code-kit standards --for <changed files>` lists the project's standards for those files' layers. Check each changed file against the ones marked `checked` (the hooks already refuse what an `enforced` one names). A broken required standard sends the branch back, naming the standard's id and where; a broken recommended one is a concern; advice is at most a nit.
 
 ## 4. The security review
 
@@ -78,7 +79,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
 
   Branches merge from the queue one at a time, in the order their reviews passed, each verified against the base as it is then. Where `approvals.delegate.merge` is on and the harness's autonomy is `autonomous`, you merge the head: `code-kit queue merge --delegated` (code-kit's loop asks you when it's its turn). Otherwise the person merges it, with Merge in the code-kit band or `code-kit queue merge --person`. The queue records the commit your review passed and merges exactly that commit. A branch that moves on after your review leaves the queue: review it again, then queue it again. A head that no longer merges cleanly, or fails verify against the moved base, is sent back to its lane on its own; dispatch the fix as for any send-back. When the branch is merged, remove its worktree.
 
-- **Send back.** List each problem, where it is, and what "fixed" looks like. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
+- **Send back.** List each problem, where it is, and what "fixed" looks like, with the requirement or the standard's id it breaks. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
 
   ```bash
   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sent-back <branch> --reason "<the problems, in one line>"