@warren-dean/code-kit 0.17.0 → 0.19.0

package/hooks/mod/register.test.ts

@@ -75,6 +75,8 @@ function project() {
     agents: [] as { type: string; status: string; id?: string; description?: string }[],
     limits: [] as { kind: string; percentUsed: number }[],
     contextPercent: 0, // LEAN-3: how full the lead's context is
+    notified: [] as { text: string; title?: string }[], // NOTIFY-1
+    viewed: [] as (string | null)[], // WATCH-1
     approveExit: 0,
     mergeExit: 0,
     answer: 'Merge',
@@ -380,6 +382,8 @@ function stub(on: any, w: World) {
   });
   on('model.complete', ($: any, e: any) => {
     w.sideAsks.push({ model: e.model, prompt: e.prompt });
+    // LEAN-6: the loop reads the lead's reply with a small model; the test's reading answers it.
+    if (/Say where that reply left things/.test(e.prompt)) return { value: w.sideReply };
     return { value: { isAnswered: true, text: 'From the facts alone.', usage: null } };
   });
   // Claude Code's own settings hooks beneath: none answer a permission denial.
@@ -408,6 +412,15 @@ function stub(on: any, w: World) {
     value: { startedAt: 0, context: { percent: w.contextPercent }, rateLimits: w.limits },
   }));
   on('session.measure', ($: any, e: any) => ({ changed: e.changed }));
+  // NOTIFY-1: the person's notification channel; WATCH-1: the main view.
+  on('ui.notify', ($: any, e: any) => {
+    w.notified.push({ text: e.text, title: e.title });
+    return { value: { isSent: true, channel: 'iterm2' } };
+  });
+  on('ui.view', ($: any, e: any) => {
+    w.viewed.push(e.agentId ?? null);
+    return { value: {} };
+  });
   // A model request, answered with the usage the test gave it.
   on('turn.step', async function* ($: any, e: any) {
     return {
@@ -2134,7 +2147,9 @@ test('LOOP-1 nothing is submitted mid-turn, or while the person has a draft, or
   expect(w.prompts).toEqual(['Dispatch ST-9: run /code-kit:dispatch ST-9.']);
   await leadTurn($, 't-3');
   await settle(clock);
-  expect(w.prompts).toHaveLength(1);
+  // LOOP-13: the turn left ST-9 where it stood, so it's parked, and the next step goes instead.
+  expect(w.prompts.filter((p: string) => p.startsWith('Dispatch ST-9'))).toHaveLength(1);
+  expect(w.prompts.at(-1)).toMatch(/^Build ST-6, ST-7 yourself/);
 });
 
 test("LOOP-1 review and the lead's own stories are prompted with their skill", async ($, on) => {
@@ -2299,6 +2314,60 @@ test(
   },
 );
 
+test('LEAN-5 a lane agent past its context limit is told to wrap up, and its story goes on with a fresh agent', async ($, on) => {
+  const w = project();
+  w.next = { step: 'wait', args: '', then: [] };
+  w.agents = [
+    { id: 'a1', type: 'web-engineer', description: 'ST-4 booking form', status: 'running' },
+  ];
+  const clock = await start($, on, w);
+  await clock.advance(2000);
+  await request($, 'a1', 100);
+  expect(w.sent).toEqual([]);
+  // 270k of context, past the 250k limit: told once, however many requests follow.
+  await request($, 'a1', 300);
+  await request($, 'a1', 320);
+  expect(w.sent).toHaveLength(1);
+  expect(w.sent[0].text).toMatch(/^Your context is past 250k tokens/);
+  await $.turn.complete({
+    turnId: 't-a1',
+    agentId: 'a1',
+    answer: 'ST-4: committed, report written.',
+    durationMs: 1,
+    isAborted: false,
+  } as any);
+  await leadTurn($, 't-2');
+  await settle(clock);
+  expect(w.prompts.at(-1)).toMatch(
+    /^web-engineer handed ST-4 back at its context limit, with its work committed on web\/st-4\. Carry the story on with a fresh agent: run node ".*" worktrees release web\/st-4/,
+  );
+  expect(w.prompts.at(-1)).toMatch(
+    /Read your earlier report first: \.claude\/state\/reports\/web_st-4\.md/,
+  );
+});
+
+test("LEAN-4 past compact.at the lead's context is compacted between turns, without asking", async ($, on) => {
+  const w = project();
+  const compacted: string[] = [];
+  on('session.compact', ($: any, e: any) => {
+    compacted.push(e.instructions);
+    return {
+      messages: [{ role: 'user', text: 'Summary: ST-4 in progress on web/st-4.', toolUses: [] }],
+    };
+  });
+  w.contextPercent = 35;
+  const clock = await start($, on, w);
+  await leadTurn($);
+  await settle(clock);
+  expect(compacted).toEqual([]);
+  w.contextPercent = 46;
+  await leadTurn($, 't-2');
+  await settle(clock);
+  expect(compacted).toHaveLength(1);
+  expect(compacted[0]).toMatch(/^The lead's context is compacted between turns/);
+  expect(w.asked.filter((a) => /Compact/.test(a.question))).toEqual([]);
+});
+
 test('LOOP-3 an agent whose work is done is never nudged or restarted: it handed back, or its branch waits in the merge queue', async ($, on) => {
   const w = project();
   w.next = { step: 'wait', args: '', then: [] };
@@ -2464,7 +2533,9 @@ test("LOOP-11 a reply that waits on the person holds the loop; the dialog asks t
   await leadSays($, 't-2', 'Before I dispatch ST-9: should its prices include GST?');
   await settle(clock);
   // The side call read the reply over the lead's own conversation, with the step it answered.
-  expect(w.sideAsks.at(-1).fork).toBe(true);
+  // LEAN-6: read by a small model from the reply itself, not a fork over the lead's conversation.
+  expect(w.sideAsks.at(-1).fork).toBeUndefined();
+  expect(w.sideAsks.at(-1).model).toBe('sonnet');
   expect(w.sideAsks.at(-1).prompt).toMatch(/prompted you: "Dispatch ST-9/);
   expect(w.sideAsks.at(-1).prompt).toMatch(/should its prices include GST\?/);
   expect(w.asked.at(-1)).toEqual({
@@ -2528,7 +2599,8 @@ test("LEAN-3 when a milestone finishes, the person is asked to compact the lead'
     ...w.stories.map((s) => ({ ...s, milestone: 'M1' })),
   ];
   const compacted: string[] = [];
-  w.contextPercent = 62;
+  // Under compact.at (40%), so only the milestone brings the question.
+  w.contextPercent = 30;
   on('session.compact', ($: any, e: any) => {
     compacted.push(e.instructions);
     // A compaction leaves the summary in the conversation's place.
@@ -2548,6 +2620,7 @@ test("LEAN-3 when a milestone finishes, the person is asked to compact the lead'
   w.refs += ' m1 refs/heads/main-moved\n';
   await clock.advance(2000);
   w.answer = 'Compact now';
+  w.contextPercent = 62;
   await leadTurn($, 't-2');
   await settle(clock);
   expect(w.asked.at(-1)?.question).toMatch(
@@ -2566,6 +2639,39 @@ test("LEAN-3 when a milestone finishes, the person is asked to compact the lead'
   expect(compacted).toHaveLength(1);
 });
 
+test("LOOP-13 a review the lead's turn didn't move isn't prompted again while other lanes commit, whatever the reply reads as", async ($, on) => {
+  const w = project();
+  w.stories.push({
+    id: 'ST-160',
+    title: 'Content security policy',
+    lane: 'web',
+    state: 'in review',
+    branch: 'web/st-160',
+    waitingOn: [],
+  });
+  w.refs += ' p1 refs/heads/web/st-160\n';
+  w.next = { step: 'review', args: 'ST-160', then: [] };
+  w.sideReply = unread;
+  const clock = await start($, on, w);
+  await leadTurn($);
+  await settle(clock);
+  expect(w.prompts).toEqual(['Review ST-160: run /code-kit:review ST-160.']);
+  // The lead says it waits, the reading comes back done, and lanes keep committing.
+  w.sideReply = outcome({ outcome: 'done' });
+  for (const [i, turn] of ['t-2', 't-3', 't-4', 't-5'].entries()) {
+    w.refs += ` x${i} refs/heads/core/st-${i}\n`;
+    await leadSays($, turn, 'ST-160 waits on ST-165; nothing to review yet.');
+    await settle(clock);
+    w.sideReply = unread;
+  }
+  expect(w.prompts).toHaveLength(1);
+  // Its own branch moves: it's prompted again.
+  w.refs = w.refs.replace(' p1 refs/heads/web/st-160', ' p2 refs/heads/web/st-160');
+  await leadTurn($, 't-6');
+  await settle(clock);
+  expect(w.prompts).toHaveLength(2);
+});
+
 test('LOOP-13 stories the lead says wait on other work are parked, each until what it waits on moves', async ($, on) => {
   const w = project();
   w.stories.push(
@@ -2635,10 +2741,17 @@ test('LOOP-13 stories the lead says wait on other work are parked, each until wh
   await leadTurn($, 't-3');
   await settle(clock);
   expect(w.prompts).toHaveLength(asked);
-  // The story building on ST-158 commits: ST-158 wakes, and ST-172 still waits.
+  // The story building on ST-158 commits: that alone doesn't wake it.
   w.refs = w.refs.replace(' s2 refs/heads/api/st-164', ' s9 refs/heads/api/st-164');
   await leadTurn($, 't-4');
   await settle(clock);
+  expect(w.prompts).toHaveLength(asked);
+  // It finishes: ST-158 wakes, and ST-172 still waits.
+  w.stories = w.stories.map((s: any) => (s.id === 'ST-164' ? { ...s, state: 'in review' } : s));
+  w.refs += ' s10 refs/heads/api/st-164-done\n';
+  await clock.advance(2000);
+  await leadTurn($, 't-5');
+  await settle(clock);
   expect(w.prompts.at(-1)).toBe('Review ST-158: run /code-kit:review ST-158.');
   expect(w.prompts).toHaveLength(asked + 1);
 });
@@ -2850,6 +2963,17 @@ test('SET-4 with no lane model set, lane agents start as Claude Code decides', a
   expect(w.spawned[0].model ?? null).toBe(null);
 });
 
+test("LEAN-7 the security reviewer starts on the reviewers' model, Sonnet unless set, and its own file's model wins", async ($, on) => {
+  const w = project();
+  await start($, on, w);
+  await dispatch($, 'security-reviewer');
+  await dispatch($, 'security-reviewer', 'opus');
+  w.agentFiles['/work/.claude/agents/security-reviewer.md'] =
+    '---\nname: security-reviewer\nmodel: opus\n---\n';
+  await dispatch($, 'security-reviewer');
+  expect(w.spawned.map((e) => e.model ?? null)).toEqual(['sonnet', 'opus', null]);
+});
+
 // --- the reviewer -----------------------------------------------------------------------------------
 
 /** ST-4 finished on web/st-4, the reviewer on. */
@@ -3351,6 +3475,10 @@ test('VIEW-6 tabs on 1 to 7, j and k move between lanes, and the selected lane h
   await press($, 'lane-next', PANE);
   await press($, 'lane-next', PANE);
   expect((await ui.find({ key: 'lane-web' }))?.text).toMatch(/^›/);
+  // WATCH-1: w puts the lane agent's transcript in the main view.
+  expect((await ui.find({ key: 'act-watch' }))?.props.hotkey).toBe('w');
+  await press($, 'act-watch', PANE);
+  expect(w.viewed).toEqual(['a1']);
   expect((await ui.find({ key: 'act-nudge' }))?.props.hotkey).toBe('n');
   await press($, 'act-nudge', PANE);
   expect(w.sent).toEqual([
@@ -3366,6 +3494,30 @@ test('VIEW-6 tabs on 1 to 7, j and k move between lanes, and the selected lane h
   await ui.unmount();
 });
 
+test('NOTIFY-1 a decision new since the last look raises one notification; what waited before, and notify.on false, raise none', async ($, on) => {
+  const w = project();
+  w.requests = [dayjs];
+  const clock = await start($, on, w);
+  await clock.advance(2000);
+  // The approval waiting when the session first looked isn't news.
+  expect(w.notified).toEqual([]);
+  w.questions = [question()];
+  w.refs += ' q1 refs/heads/web/st-4-q\n';
+  await clock.advance(2000);
+  await clock.advance(2000);
+  expect(w.notified).toHaveLength(1);
+  expect(w.notified[0].title).toBe('code-kit: the lead asks you');
+  await clock.advance(2000);
+  expect(w.notified).toHaveLength(1);
+  // Turned off, a new decision raises nothing.
+  (w.check as any).harness = { notify: { on: false } };
+  w.questions = [question(), question({ id: 'Q-2', question: 'Which payment provider?' })];
+  w.refs += ' q2 refs/heads/web/st-4-q2\n';
+  await clock.advance(2000);
+  await clock.advance(2000);
+  expect(w.notified).toHaveLength(1);
+});
+
 test('VIEW-6 s sends the selected story back, with the reason the person gives', async ($, on) => {
   const w = project();
   w.stories[0] = { ...w.stories[0], state: 'review' };

package/hooks/stop-check.mjs

@@ -19,6 +19,9 @@ const { input, project, config, error } = start();
 // reported MAX_REPEATS times in a row means no progress: say so and let the finish through rather than
 // loop. A different problem means progress, and counts from one again.
 const MAX_REPEATS = 3;
+// LEAN-1: the most a lane's hand-back holds.
+const HAND_BACK_LINES = 10;
+const HAND_BACK_CHARS = 1200;
 const memory = join(
   project,
   '.claude/state/stop-blocks',
@@ -97,9 +100,17 @@ if (actor.kind === 'lane' && changed.length) {
 // LEAN-1: the lead's context gets a short hand-back; the detail waits in a file it reads when it reviews.
 if (actor.kind === 'lane' && storyOfBranch(currentBranch(root))) {
   const report = reportPath(root);
-  if (!existsSync(join(root, report)))
+  // Written in the lane's worktree, or by its absolute path in the main checkout: either is found.
+  if (!existsSync(join(root, report)) && !existsSync(join(project, report)))
     blockCounted(
       `Write your full report to ${report} before you finish: what you did and why, the spec section, the commands you ran with their output, what's left, and anything you need decided (with the choices, and any text you'd have pasted, such as a migration you can't write yet). Then finish with a short hand-back of at most ten lines: the story and branch, done or blocked, any decision the lead must make, and that report's path. Don't paste output or code into the hand-back; the lead reads the file when it reviews.`,
     );
+  // The hand-back is what reaches the lead's context: a few lines, the detail left in the report.
+  const handBack = String(input.last_assistant_message ?? '').trim();
+  const lines = handBack.split('\n').filter((l) => l.trim()).length;
+  if (lines > HAND_BACK_LINES || handBack.length > HAND_BACK_CHARS)
+    blockCounted(
+      `Your hand-back is ${lines} lines and ${handBack.length} characters, and all of it goes into the lead's context. Finish again with at most ${HAND_BACK_LINES} short lines: the story and branch, done or blocked, any decision the lead must make, and ${report}. Don't restate the report: the lead reads it when it reviews.`,
+    );
 }
 passed();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.17.0",
+  "version": "0.19.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/dispatch/SKILL.md

@@ -48,6 +48,8 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,
 
 The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
 
+One agent per story: never send a running lane agent a second story, or a send-back. A story that goes on (sent back, or handed back at its context limit) gets a fresh agent: first run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" worktrees release <branch>`, which keeps the branch's commits and moves its report to the main checkout, then start the agent as below with the brief and "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout". A long-lived agent rereads its whole context on every step, which is most of what a build costs.
+
 Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
 
 The brief is the agent's whole context. Write it so the agent needs nothing else:

package/skills/init/SKILL.md

@@ -102,7 +102,8 @@ Draft, alongside the config:
   - its layers and what they may depend on;
   - the specs it reads;
   - the command that proves its work;
-  - its lane rules.
+  - its lane rules: the rules the docs set for this lane, and anything the project adds to code-kit's own (its principles and architecture docs, its own words for what's banned). These are the project's, so they stay outside code-kit's part.
+  - Leave out the template's `Always:` list: it's code-kit's part, which `code-kit instructions --write` adds once the config is written, between its markers.
   - If an agent already exists, keep its content and add only what's missing.
   - Drop the spec-check lines if the config has no `docs.specs`.
 - **A security reviewer:** write `.claude/agents/security-reviewer.md` from `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, in the same approval as the lane agents, whenever the product handles sign-in, personal data, payments, input from outside (forms, APIs, webhooks, uploads) or secrets. That's almost every product; leave it out only for one with none of these, such as a static site or a local tool with no accounts, and say why. It is a reviewer, not a lane: no entry in `lanes`, no paths, and only read-only tools (Read, Grep, Glob, and Bash for commands that change nothing), so the hooks treat it as read-only too. Fill it in from the docs (or the code, for brownfield):
@@ -111,7 +112,7 @@ Draft, alongside the config:
   - the privacy and data residency targets in the principles;
   - the project's audit commands (for example `npm audit --omit=dev`, `pip-audit`), each run once now; leave out one that isn't installed, and say so.
   - If the agent already exists, keep its content and add only what's missing.
-- **CLAUDE.md:** add the section from `${CLAUDE_PLUGIN_ROOT}/templates/claude-md.md`.
+- **CLAUDE.md:** code-kit's section is rendered from the config, not written by hand: once the config is written, `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" instructions --write` adds it between its markers (`<!-- code-kit:begin vN -->` … `<!-- code-kit:end -->`). Anything the project wants to say beyond it (its layer order in words, its docs, its own rules) goes in a section of its own, outside the markers, so a later code-kit never touches it.
 - **Project skills, with the agents** (recipes like "new screen", "new migration" or "new endpoint"): one per recipe in the architecture's `## Recipes`, or any other doc that describes one step by step. Draft them now, alongside the agents, and show them in the same approval; the agents and their skills are one piece of work. Brownfield code without recipes in its docs: propose recipes from the patterns the code already follows (how its existing screens, endpoints or migrations are built), as drafts the person approves. Never write an empty one.
   - Write each as `.claude/skills/<name>/SKILL.md`, saying in its description which recipe in which doc it comes from, so an update can find it again.
   - List it under **Skills to use** on every lane agent whose paths the recipe touches, not only one: a recipe that adds a migration and the endpoint that uses it belongs to both lanes. A recipe only the lead follows goes in the CLAUDE.md section instead.
@@ -154,6 +155,7 @@ 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.
    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);

package/skills/next/SKILL.md

@@ -26,6 +26,7 @@ It returns `step`, `why`, `args`, `then` (steps that can follow straight after)
 | Config, but no specs, plan or stories                        | `spec-design`                                             |
 | A companion the config wants, not set up yet                 | `setup`: run that tool's init skill (`args`), before code |
 | An older setup missing what init now adds, nothing in flight | `update`: re-run init, before any new story               |
+| code-kit's instructions behind this code-kit                 | `instructions`: bring CLAUDE.md and the agents up to date |
 | A lane waits on a request you decide                         | `decide`: approve it, or answer with an alternative       |
 | Stories finished on their branches                           | `review`, then `dispatch` what's ready                    |
 | Design stories ready (`**Lane:** design`)                    | `design`, then `dispatch` what needs no design            |
@@ -43,6 +44,7 @@ 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.
 - **`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.
 - **`done`:** give the `status` summary in a few lines, then offer to run spec-design for the next milestone or feature.

package/skills/review/SKILL.md

@@ -38,7 +38,7 @@ Any problem it reports means the branch goes back. Don't fix a lane's code yours
 
 ## 3. Check the work against the story
 
-Read the story, every requirement it cites, and the full diff (`git diff <base>...<branch>`). Read each changed file in full where the diff alone doesn't show the behaviour. Then, for each requirement:
+Read the story and every requirement it cites. Then start from what's already been worked out, not the whole diff: the lane's report (`.claude/state/reports/<branch with / as _>.md`, in its worktree or the main checkout), the reviewer's findings when the background reviewer ran, and `git diff --stat <base>...<branch>`. Open the diff one file at a time (`git diff <base>...<branch> -- <file>`) for the files each requirement depends on and the files a finding names, and a changed file in full only where its diff doesn't show the behaviour. Everything you open stays in your context for the rest of the build, so open what the verdict needs. Then, for each requirement:
 
 | Requirement | Acceptance criterion | Built (where) | Test (which) | Verdict |
 | ----------- | -------------------- | ------------- | ------------ | ------- |
@@ -84,7 +84,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sent-back <branch> --reason "<the problems, in one line>"
   ```
 
-  Send the list to the same lane agent if it's still running (SendMessage), or dispatch the story again with the list added to the brief. Set the story's status to `in progress`.
+  Dispatch the story again to a fresh agent with the list added to the brief (`/code-kit:dispatch`, which first releases the branch's worktree), never to the agent that built it: its context is already large. Set the story's status to `in progress`.
 
 - **Ask the person.** When the right answer is a product or scope decision (the spec is silent, or the lane found a real conflict), put the question to the person with your recommendation. Don't merge around it.
 

package/skills/spec-check/SKILL.md

@@ -12,7 +12,7 @@ The project's specs are in the folder named by `docs.specs` in `.claude/code-kit
 1. **Find the section.** The task should name its requirement IDs (`BOOK-4`, headings in the specs) or a spec section. If it doesn't, search the specs folder for the domain nouns. Read the whole section, not just the matching lines, plus every section it references.
 2. **Read the principles.** Re-read the parts of `docs.principles` that apply: layers, ports and providers, events, testing and the rules for agents. Note this lane's layer rules from `layers` in the config.
 3. **Make a checklist.** One line per requirement: behaviour, fields, error cases, permissions, states, tests.
-4. **Compare with the code.** For each line, search for where it's implemented, then read those files in full.
+4. **Compare with the code.** For each line, search for where it's implemented, then read what implements it: the functions and types the requirement touches, not every file around them.
 5. **Report** as a table:
 
 | Requirement | Status (done / partial / missing / conflicts) | Where | Note |

package/templates/agent.md

@@ -18,8 +18,8 @@ Lane rules:
 Always:
 
 - Work on the branch the brief names (`<lane>/st-<n>`). Start every task with the spec-check skill and save its report to .claude/state/spec-check/<branch>.md; the path guard blocks code until it exists.
-- Follow {{docs.principles}}, including the rules for AI agents. Hooks enforce ownership, layers and the project's checks; if one blocks you, fix the cause, never work around it.
-- Read every file you change in full, plus its imports and its callers.
+- Follow `{{docs.principles}}`, including the rules for AI agents. Hooks enforce ownership, layers and the project's checks; if one blocks you, fix the cause, never work around it.
+- Read every file you change in full. Of what it imports and what calls it, read what your change needs: the definitions it uses and the call sites it changes. A context tool's fresh card for a file stands for reading it whole; read the source where the card is missing, stale or not enough.
 - Search before you build; reuse existing services, providers, components and schemas.
 - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
 - You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
@@ -28,7 +28,9 @@ Always:
 - Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.
 - Fixing a bug: first write a test that fails because of the bug, through the code that's already there, then fix it. `verify` runs your test without the fix, and it must fail on an assertion, not because it calls something the fix adds.
 - Never weaken a test to get to green: no deleting, skipping or focusing tests, cutting cases or assertions, or rewriting snapshots. The commit is refused without the person's approval. Fix the code; if the test itself is wrong, say why in a change request for the lead.
+- Run the narrowest tests that prove each step, with failures only in the output (a quiet reporter, or `| tail -40` on failure); run the full suite once, before you commit. Long output stays in your context and is paid for on every step after it.
 - Commit your work on your branch before finishing; the stop hook runs the checks and requires it.
 - Don't message the lead while you work: it hears from you once, when you finish. If you're blocked on something only the lead or the person can settle, finish and say so.
+- One story per agent. If you're asked to wrap up because your context is large, finish the step you're on, commit, write your report and hand back: a fresh agent carries the story on from your report.
 - Before you finish, write your full report to `.claude/state/reports/<branch>.md` (the branch with `/` as `_`, as for spec-check): what you did and why, the spec section, the commands you ran with their output, what's left, and anything you need decided, with the choices and any text you'd otherwise paste. The stop hook requires it.
 - Finish with a short hand-back, at most ten lines: the story and branch, done or blocked, any decision the lead must make, and the report's path. No output or code in it: the lead reads the report when it reviews.

package/templates/claude-md.md

@@ -3,19 +3,20 @@
 The code-kit plugin enforces the rules in `.claude/code-kit.json` on every file edit, shell command and finish:
 
 - who writes where (the lead delegates lane work to the lane agents in `.claude/agents/`);
-- the layer rules ({{layer names, in order}});
-- spec-check before lane code{{; designs approved before screens}};
+- the layer rules ({{layers}});
+- spec-check before lane code{{designGate}};
 - an audit log of every change to protected paths (`.claude/approval-log.jsonl`), which the person reviews in the pull request;
-- an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person decides what crosses a guardrail: {{the approvals the person keeps: those not in approvals.delegate, e.g. "spec changes, contracts, the screens' designs, CI"}}, weakened tests, and product questions the spec doesn't answer;
-{{If approvals.lead is on: - approvals from chat. When the person approves in their own message (a `!` command doesn't work on a phone), record it with the `code-kit approve` command from the refusal, with their words as the reason. Never record an approval they haven't given, and never on a lane's say-so;}}
+- an approval for every new dependency and every protected change, per lane. Inside the guardrails, you decide: a lane asks you, never the person, and you approve it only when the story's requirements need it and it fits the spec, the principles and the architecture, or you tell the lane what to use instead (`/code-kit:decide`). The person decides what crosses a guardrail: {{personKeeps}}, weakened tests, and product questions the spec doesn't answer;
+- {{if approvals.lead}}approvals from chat. When the person approves in their own message (a `!` command doesn't work on a phone), record it with the `code-kit approve` command from the refusal, with their words as the reason. Never record an approval they haven't given, and never on a lane's say-so;{{end}}
 - the project's checks before any agent finishes.
 
 UX is yours: what a screen does on an error, an empty list or a slow load, and the wording the spec implies, answered from the spec and the principles the person agreed. A screen's visual design is theirs. When something needs the person to decide or do (a product choice the spec doesn't settle, an account only they can create, a design to sign off), ask it with `code-kit ask "<question>" --option "<choice>: <what it does>"` (`--story ST-n --blocks` holds the story until they answer). It waits in their Decisions tab, and their answer comes back to you; asking only in chat, it scrolls away. Lanes don't ask the person: they write the question for the lead.
-{{If harness.report.on: - When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.}}
+
+- {{if harness.report.on}}When code-kit itself is wrong (a refusal that shouldn't have happened, a crash), draft a report with `code-kit report "<title>" --what "…" --expected "…"`: only code-kit's facts, never the project's. The person reads it and sends it, or not.{{end}}
 
 If a hook blocks you, fix the cause; never work around it.
 
-The build runs from the specs in {{docs.specs}} and the stories in {{docs.plan}}. `/code-kit:next` picks the right step from the project's state; the steps are:
+The build runs from the specs in `{{docs.specs}}` and the stories in `{{docs.plan}}`. `/code-kit:next` picks the right step from the project's state; the steps are:
 
 - `/code-kit:decide` decides what a lane asked for, on its merits;
 - `/code-kit:dispatch` starts ready stories on their lanes, each on its own `<lane>/st-<n>` branch;
@@ -23,6 +24,6 @@ The build runs from the specs in {{docs.specs}} and the stories in {{docs.plan}}
 - `/code-kit:status` shows what's done, in review, ready and blocked, and what's untested;
 - `/code-kit:spec-design` changes the specs when a decision changes. It updates the spec, the decision log and the plan together.
 
-{{If the CI workflow is installed: pull requests run `code-kit verify`, and it must pass before a person merges to a protected branch.}}
+{{if ci}}Pull requests run `code-kit verify`, and it must pass before a person merges to a protected branch.{{end}}
 
 Changing the rules means editing `.claude/code-kit.json` (the lead only), then running the `code-kit:check` skill.