@warren-dean/code-kit 0.16.1 → 0.18.0

package/hooks/mod/decisions.mjs

@@ -437,3 +437,32 @@ export function nativeChoice(card) {
       card.kind === 'question' ? 'answerTyped' : card.kind === 'waiting' ? 'answerLeadTyped' : null,
   };
 }
+
+/** NOTIFY-1: a decision's identity across refreshes: its kind and what it asks. */
+export const decisionKey = (card) => `${card.kind}|${card.headline}`;
+
+/**
+ * NOTIFY-1: the decisions that weren't waiting at the last look, each as a system notification: what it
+ * asks, headed by what kind of decision it is. `seen` holds the keys from the last look.
+ */
+export function newDecisions(cards, seen) {
+  return cards
+    .filter((c) => NOTIFY_TITLE[c.kind] && !seen.has(decisionKey(c)))
+    .map((c) => ({
+      key: decisionKey(c),
+      title: `code-kit: ${NOTIFY_TITLE[c.kind] ?? 'a decision for you'}`,
+      text: `${c.headline}${c.story ? ` (${c.story.id})` : ''}`,
+    }));
+}
+
+const NOTIFY_TITLE = {
+  held: 'an approval to give',
+  approvals: 'an approval to give',
+  question: 'the lead asks you',
+  brief: 'a question in your brief',
+  waiting: 'the lead waits on you',
+  stalled: 'a lane stalled',
+  denied: 'Claude Code refused a call',
+  proposal: 'a step to approve',
+  queue: 'a merge for you',
+};

package/hooks/mod/loop.mjs

@@ -4,6 +4,7 @@
 
 /** The steps the loop hands the lead; the rest (spec-design, init, check) wait for the person. */
 const LEAD_STEPS = new Set([
+  'instructions',
   'decide',
   'dispatch',
   'review',
@@ -96,13 +97,16 @@ export function parkWatch(id, on = [], stories = []) {
 }
 
 /**
- * LOOP-13: where the watched stories stand, as one string: each one's state, its branch's commit and
- * whether an agent is at work on it. A parked story wakes when this changes.
+ * LOOP-13: where the watched stories stand, as one string. The parked story itself (the first) counts
+ * its state, its branch's commit and whether an agent is at work on it; each story it waits on counts its
+ * state alone, so the commits of a story still being built don't wake the one waiting for it to finish.
+ * A parked story wakes when this changes.
  */
 export function storiesSignature(ids, stories = [], heads = new Map(), inFlight = new Set()) {
   return ids
-    .map((id) => {
+    .map((id, i) => {
       const s = stories.find((x) => x.id === id);
+      if (i > 0) return `${id}:${s?.state ?? '?'}`;
       return `${id}:${s?.state ?? '?'}:${s?.branch ? (heads.get(s.branch) ?? '') : ''}:${inFlight.has(id) ? 'busy' : ''}`;
     })
     .join('|');
@@ -134,6 +138,14 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
   // SETUP-2: the base has no rules yet; the lead puts the approved ones there, then merges as usual.
   if (step.step === 'rules')
     return `Put code-kit's approved rules onto ${ids[0] ?? 'the base'}: run node "${cli}" queue rules. It commits the rules as committed on this branch, without switching branches; after it, merge the queue as usual.`;
+  // ONB-8: code-kit's instructions brought up to date, then committed like any change to the kit.
+  if (step.step === 'instructions') {
+    const how =
+      step.args === 'merge'
+        ? `Run node "${cli}" instructions to see which files, then merge each one: replace its old code-kit part with what node "${cli}" instructions show lead (CLAUDE.md) or show lane (an agent file) prints, and keep every line the project wrote itself outside the markers, under a heading of its own. Then run node "${cli}" instructions --write for the rest.`
+        : `Run node "${cli}" instructions --write.`;
+    return `${step.why ?? "code-kit's instructions are behind."} ${how} Commit the change on a branch and merge it like your own stories, so new lane agents start with the current rules.`;
+  }
   // HELM-4: a lane waits on the lead's decision; the decide skill takes each request on its merits.
   if (step.step === 'decide')
     return ids.length
@@ -175,6 +187,7 @@ export function stepLabel(step) {
   const verb =
     {
       decide: 'Decide requests',
+      instructions: 'Update the instructions',
       dispatch: 'Dispatch',
       review: 'Review',
       lead: 'Build',
@@ -310,3 +323,27 @@ export function laneModel({ type, model = null, lanes = {}, setting = null, file
   if (fileModel && fileModel !== 'inherit') return null;
   return setting;
 }
+
+/** LEAN-3: compacting a context below this share of its window isn't worth the summary it costs. */
+export const COMPACT_FLOOR = 25;
+
+/**
+ * LEAN-3: the milestones every story of which is done, in the plan's order. A milestone with no stories
+ * isn't one.
+ */
+export function milestonesDone(stories = []) {
+  const by = new Map();
+  for (const s of stories) {
+    if (!s.milestone) continue;
+    by.set(s.milestone, [...(by.get(s.milestone) ?? []), s]);
+  }
+  return [...by].filter(([, list]) => list.every((s) => s.state === 'done')).map(([m]) => m);
+}
+
+/** LEAN-3: what the lead's summary keeps when its context is compacted after a milestone. */
+export const compactInstructions = (milestone) =>
+  [
+    `${milestone} is done; the build goes on with the next milestone.`,
+    'Keep: the milestone just finished, in a line; every story in flight now, with its lane, its branch and where it stands (building, in review, in the merge queue, waiting and on what); the decisions and questions waiting on the person; what the person decided or asked for in this session that still applies; and the rules and preferences they set.',
+    "Drop: the finished stories' details, lane reports and hand-backs, command output, diffs and file contents. Each is in git, the plan or the lanes' report files, to read again when it's needed.",
+  ].join('\n');

package/hooks/mod/panes.mjs

@@ -120,6 +120,8 @@ export function laneActions(lane, { queue = [], held = [], requests = [] } = {})
   const head = queue.find((e) => ['waiting', 'merging'].includes(e.state));
   if (head && head.branch === lane.branch) acts.push({ id: 'merge', label: 'Merge', hotkey: 'm' });
   if (lane.active && lane.agent) {
+    // WATCH-1: the lane agent's own transcript, in the main view.
+    acts.push({ id: 'watch', label: 'Watch', hotkey: 'w' });
     acts.push({ id: 'nudge', label: 'Nudge', hotkey: 'n' });
     acts.push({ id: 'stop', label: 'Stop', hotkey: 'x' });
   }

package/hooks/mod/register.mjs

@@ -58,7 +58,10 @@ import {
   leadPrompt,
   nudgeText,
   outcomePrompt,
+  COMPACT_FLOOR,
   PARK_MS,
+  compactInstructions,
+  milestonesDone,
   parkWatch,
   readOutcome,
   restartPrompt,
@@ -71,7 +74,7 @@ import {
   withoutInFlight,
 } from './loop.mjs';
 import { goalOf, nextText } from './mission.mjs';
-import { contextOf, decisionCards, nativeChoice } from './decisions.mjs';
+import { contextOf, decisionCards, decisionKey, nativeChoice, newDecisions } from './decisions.mjs';
 import { DEFAULT_TEAM_UI, TEAM_ID, teamFrame } from './teamview.mjs';
 import { glowOf, mapStoryOf, touchOf } from './codemap.mjs';
 import { harnessSettings } from '../lib/harness.mjs';
@@ -128,6 +131,8 @@ const loop = {
   handedDesign: new Set(), // LOOP-12: design stories handed to the lead this session
   // LOOP-13: stories the lead said wait on other work: id → { on, why, watch, sig, at }
   parked: new Map(),
+  // LEAN-3: the milestones already done when this session first looked, and those finished since.
+  milestones: null,
 };
 // LOOP-10: whether this session runs the loop, the session that does when another does, and when this
 // one last renewed its lease.
@@ -139,6 +144,8 @@ let turnQuestions = []; // the open questions as the lead's running turn started
 // DECIDE-4: decisions asked in Claude Code's own question dialog this session, and whether one is open.
 const offered = new Set();
 let offering = false;
+// NOTIFY-1: the decisions waiting at the last look, by key; null until the first look.
+let notified = null;
 /** LOOP-8: the times in a row the lead is prompted with one step before the person is asked. */
 const ASK_LIMIT = 2;
 let leadTurn = null; // the lead's running turn, if any
@@ -1058,10 +1065,19 @@ export function register(on) {
       ) => {
         loop.started = true;
         loop.proposal = null;
-        loop.sent = { prompt, key, label, kind, target };
+        const sent = { prompt, key, label, kind, target, before: new Map() };
+        loop.sent = sent;
         // LOOP-12: a design story is handed to the lead once; the person designs it with the lead.
         if (kind === 'design')
           for (const id of String(target).split(/\s+/).filter(Boolean)) loop.handedDesign.add(id);
+        // LOOP-13: where the step's stories stood when the lead was prompted, to tell after its turn
+        // whether it moved them.
+        // A design is made with the person over many turns (LOOP-12), so it's never counted as unmoved.
+        const ids = kind === 'design' ? [] : stepStories({ kind, target });
+        if (ids.length) {
+          const seen = await act.storiesNow();
+          for (const id of ids) sent.before.set(id, seen.sig([id]));
+        }
         await act.record(kind, target, prompt);
         $.ui.invalidate('ui.render');
         $.prompt.submit({ text: prompt }).catch((err) => {
@@ -1136,6 +1152,16 @@ export function register(on) {
         }
         $.ui.invalidate('ui.render');
       },
+      // LOOP-13: the stories of the step the lead was prompted with that its turn left where they stood.
+      parkUnmoved: async (sent, reason) => {
+        if (!sent?.before?.size) return;
+        const seen = await act.storiesNow();
+        await act.park(
+          [...sent.before]
+            .filter(([id, sig]) => !loop.parked.has(id) && seen.sig([id]) === sig)
+            .map(([id]) => ({ id, on: [], why: reason ?? "the lead's turn didn't move it" })),
+        );
+      },
       // LOOP-13: a parked story wakes when anything it watches moves, or after PARK_MS with nothing moving.
       unpark: async () => {
         if (!loop.parked.size) return;
@@ -1144,6 +1170,55 @@ export function register(on) {
         for (const [id, p] of loop.parked)
           if (now - p.at >= PARK_MS || seen.sig(p.watch) !== p.sig) loop.parked.delete(id);
       },
+      // LEAN-3: a milestone finished in this session: the lead's context is compacted before the next,
+      // asked in Claude Code's dialog or done at once, as compact.milestone says. True when it took over
+      // the turn's end, so the loop's step waits until the compaction is done or declined.
+      compactAtMilestone: async () => {
+        const done = milestonesDone(model.state?.stories ?? []);
+        if (loop.milestones === null) {
+          loop.milestones = new Set(done);
+          return false;
+        }
+        const fresh = done.filter((m) => !loop.milestones.has(m));
+        if (!fresh.length) return false;
+        const mode = harness().compact?.milestone ?? 'ask';
+        if (mode === 'off' || offering || !where.interactive || (lease.other && !lease.mine)) {
+          for (const m of fresh) loop.milestones.add(m);
+          return false;
+        }
+        const box = await $.prompt.read().catch(() => null);
+        if (box?.text?.trim()) return false;
+        for (const m of fresh) loop.milestones.add(m);
+        const percent = (await $.session.usage().catch(() => null))?.context?.percent ?? 0;
+        if (percent < COMPACT_FLOOR) return false;
+        const milestone = fresh.at(-1);
+        const compact = async () => {
+          const r = await $.session
+            .compact({ instructions: compactInstructions(milestone) })
+            .catch((err) => ({ skip: String(err?.message ?? err) }));
+          if (r?.skip) notice = `The lead's context wasn't compacted: ${r.skip}`;
+          await act.record('compact', milestone);
+          $.ui.invalidate('ui.render');
+          await act.step('resume').catch(() => {});
+        };
+        if (mode === 'auto') {
+          compact().catch(() => {});
+          return true;
+        }
+        offering = true;
+        $.ui
+          .ask(
+            `${milestone} is done, and the lead's context is ${Math.round(percent)}% full. Compact it before the next milestone? The summary keeps what's in flight and what waits on you, and drops the finished stories' detail.`,
+            { options: ['Compact now', 'Not now'], header: 'Context' },
+          )
+          .catch(() => null)
+          .then(async (answer) => {
+            offering = false;
+            if (answer === 'Compact now') await compact();
+            else await act.step('resume').catch(() => {});
+          });
+        return true;
+      },
       // LOOP-11: the lead's last reply, read once before the loop prompts it again. A reply that waits on
       // the person, or a turn they stopped, holds the loop until they speak; a step the lead didn't take
       // holds that step while it's still next.
@@ -1182,7 +1257,7 @@ export function register(on) {
           $.ui.invalidate('ui.render');
           return;
         }
-        if (!reply.text.trim()) return;
+        if (!reply.text.trim()) return act.parkUnmoved(sent, null);
         const said = await act.sideCall(
           outcomePrompt({ prompt: sent?.prompt ?? null, answer: reply.text }),
         );
@@ -1205,6 +1280,10 @@ export function register(on) {
             })),
           );
         }
+        // LOOP-13: a story the lead's turn left exactly where it stood wasn't taken, whatever the reply
+        // reads as; it's parked like one the lead said waits, so the loop doesn't prompt it again until
+        // it moves.
+        if (heard?.outcome !== 'needs-person') await act.parkUnmoved(sent, heard?.reason);
         if (heard?.outcome === 'needs-person')
           loop.waiting = {
             kind: 'person',
@@ -1256,6 +1335,28 @@ export function register(on) {
       // DECIDE-4: the next decision the person settles with a choice, asked in Claude Code's own question
       // dialog while the lead is idle. Each is asked once: dismissed, it stays in the band and the
       // Decisions tab. Never in a session another one runs the loop for, nor over what the person types.
+      // NOTIFY-1: what newly needs the person, as a system notification, from the session that runs the
+      // loop. What waited before this session looked isn't news. On a Claude Code without $.ui.notify,
+      // the call fails and nothing is raised.
+      notifyNew: async () => {
+        if (model.state?.kind !== 'ok' || !where.interactive) return;
+        const cards = cardsNow(await $.clock.now());
+        const fresh = newDecisions(cards, notified ?? new Set());
+        const first = notified === null;
+        notified = new Set(cards.map(decisionKey));
+        if (first || !fresh.length || harness().notify?.on === false) return;
+        if (lease.other && !lease.mine) return;
+        const one =
+          fresh.length === 1
+            ? fresh[0]
+            : {
+                title: `code-kit: ${fresh.length} things need you`,
+                text: fresh.map((f) => f.text).join('; '),
+              };
+        await Promise.resolve()
+          .then(() => $.ui.notify(one.text, { title: one.title }))
+          .catch(() => {});
+      },
       offer: async () => {
         if (offering || leadTurn || loop.sent || !where.interactive) return;
         if (lease.other && !lease.mine) return;
@@ -1577,6 +1678,24 @@ export function register(on) {
         ((await $.agent.list().catch(() => [])) ?? []).find(
           (a) => a.status === 'running' && a.type === lane.agent,
         ) ?? null,
+      // WATCH-1: the person's press puts the lane agent's transcript in the main view, as the tasks list
+      // does; the tasks list (or Escape there) brings the main conversation back.
+      watchLane: async (lane) => {
+        const agent = await act.runningAgentOf(lane);
+        if (!agent) {
+          notice = `No agent is at work in the ${lane.name} lane to watch.`;
+          $.ui.invalidate('ui.render');
+          return;
+        }
+        const r = await Promise.resolve()
+          .then(() => $.ui.view({ agentId: agent.id }))
+          .catch(() => ({
+            deny: 'this Claude Code shows an agent only from its tasks list (2.1.301 or later shows it from here)',
+          }));
+        notice = r?.deny ? `Couldn't show the ${lane.name} lane's agent: ${r.deny}.` : null;
+        if (!r?.deny) await act.record('watch', `${lane.name} · ${agent.type}`);
+        $.ui.invalidate('ui.render');
+      },
       nudgeLane: async (lane) => {
         const agent = await act.runningAgentOf(lane);
         if (!agent) return;
@@ -1683,6 +1802,7 @@ export function register(on) {
           return act.review({ story: { ...lane.story, branch: lane.branch } });
         if (id === 'merge') return act.mergeQueue({ branch: lane.branch });
         if (id === 'sendBack') return act.sendBack(lane);
+        if (id === 'watch') return act.watchLane(lane);
         if (id === 'nudge') return act.nudgeLane(lane);
         if (id === 'stop') return act.stopLane(lane);
       },
@@ -1704,6 +1824,7 @@ export function register(on) {
         // LOOP-10: the lead session renews its lease; DECIDE-4: with the lead idle, a decision waiting.
         if (lease.mine) await act.lead();
         if (!leadTurn) act.offer().catch(() => {});
+        await act.notifyNew().catch(() => {});
         await act.stalls();
         await act.animate();
         const now = await act.fingerprint();
@@ -1981,6 +2102,8 @@ export function register(on) {
         $.prompt.submit({ text }).catch(() => {});
         return res;
       }
+      // LEAN-3: a milestone just finished: its compaction comes before the next step.
+      if (await act?.compactAtMilestone().catch(() => false)) return res;
       await act?.step('turn').catch(() => {});
       // DECIDE-4: a decision waiting, asked in Claude Code's own dialog; not awaited, the person answers.
       act?.offer().catch(() => {});

package/hooks/mod/register.test.ts

@@ -74,6 +74,9 @@ function project() {
     refs: ' aaa refs/heads/main\n bbb refs/heads/web/st-4\n',
     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',
@@ -403,8 +406,19 @@ function stub(on: any, w: World) {
     w.spawned.push(e);
     return { model: e.model ?? 'claude-opus-5-5', agentId: `a-${w.spawned.length}` };
   });
-  on('session.usage', () => ({ value: { startedAt: 0, context: {}, rateLimits: w.limits } }));
+  on('session.usage', () => ({
+    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 {
@@ -2131,7 +2145,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) => {
@@ -2510,6 +2526,92 @@ test('LOOP-11 dismissed, what the lead waits on stays in the band, and the loop
   expect(w.prompts.at(-1)).toBe('Review ST-4: run /code-kit:review ST-4.');
 });
 
+test("LEAN-3 when a milestone finishes, the person is asked to compact the lead's context first, and the loop goes on after", async ($, on) => {
+  const w = project();
+  w.stories = [
+    {
+      id: 'ST-1',
+      title: 'Foundations',
+      lane: 'web',
+      state: 'in review',
+      branch: 'web/st-1',
+      milestone: 'M0',
+      waitingOn: [],
+    },
+    ...w.stories.map((s) => ({ ...s, milestone: 'M1' })),
+  ];
+  const compacted: string[] = [];
+  w.contextPercent = 62;
+  on('session.compact', ($: any, e: any) => {
+    compacted.push(e.instructions);
+    // A compaction leaves the summary in the conversation's place.
+    return {
+      messages: [
+        { role: 'user', text: 'Summary: M0 done; ST-4 in progress on web/st-4.', toolUses: [] },
+      ],
+    };
+  });
+  const clock = await start($, on, w);
+  await leadTurn($);
+  await settle(clock);
+  expect(compacted).toEqual([]);
+  const prompted = w.prompts.length;
+  // ST-1 merges: M0 is done, and the next turn's end asks before the loop's next step.
+  w.stories[0] = { ...w.stories[0], state: 'done' };
+  w.refs += ' m1 refs/heads/main-moved\n';
+  await clock.advance(2000);
+  w.answer = 'Compact now';
+  await leadTurn($, 't-2');
+  await settle(clock);
+  expect(w.asked.at(-1)?.question).toMatch(
+    /^M0 is done, and the lead's context is 62% full\. Compact it/,
+  );
+  expect(w.asked.at(-1)?.options).toEqual(['Compact now', 'Not now']);
+  expect(compacted).toHaveLength(1);
+  expect(compacted[0]).toMatch(/^M0 is done/);
+  expect(compacted[0]).toMatch(/every story in flight now/);
+  // The loop's step follows the compaction.
+  expect(w.prompts.length).toBeGreaterThan(prompted);
+  // The same milestone isn't offered twice, and a context below the floor isn't worth compacting.
+  w.contextPercent = 10;
+  await leadTurn($, 't-3');
+  await settle(clock);
+  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(
@@ -2579,10 +2681,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);
 });
@@ -3295,6 +3404,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([
@@ -3310,6 +3423,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/mod/view.mjs

@@ -1513,6 +1513,7 @@ const CHOICES = {
   autonomy: ['autonomous', 'propose', 'off'],
   'agents.reviewer.model': ['', 'haiku', 'sonnet', 'opus'],
   'agents.lanes.model': ['', 'haiku', 'sonnet', 'opus'],
+  'compact.milestone': ['ask', 'auto', 'off'],
 };
 const shown = (v) =>
   v === null || v === '' ? "the session's" : v === true ? 'on' : v === false ? 'off' : String(v);

package/hooks/stop-check.mjs

@@ -8,7 +8,8 @@ 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 { actorFor, actorRoot } from './lib/rules.mjs';
+import { actorFor, actorRoot, currentBranch, reportPath } from './lib/rules.mjs';
+import { storyOfBranch } from './lib/teamfacts.mjs';
 import { auditProblems, changedFiles } from './lane-audit.mjs';
 
 const { input, project, config, error } = start();
@@ -18,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',
@@ -92,4 +96,21 @@ if (actor.kind === 'lane' && changed.length) {
     changed.join('\n'),
   );
 }
+
+// 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);
+  // 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.16.1",
+  "version": "0.18.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

@@ -13,7 +13,7 @@ The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`.
 
 `requests --json` lists each open request with its number (`n`), the lane, what it asked for (`names`, `what`), and whose decision it is (`by`). The argument, if given, names the numbers to take. Take every request `by: "lead"`. A request `by: "person"` is theirs: see step 4.
 
-For each, read the lane's change request (its last report, or ask the lane with SendMessage if it's still running), its story in the plan, and the requirements the story cites, in the specs.
+For each, read the lane's change request (its report, in `.claude/state/reports/<branch>.md` in its worktree), its story in the plan, and the requirements the story cites, in the specs.
 
 ## 2. Judge it
 

package/skills/dispatch/SKILL.md

@@ -89,4 +89,4 @@ Give them the same brief. Claude Code opened in that worktree then acts as the l
 
 - Set each dispatched story's `**Status:**` in the plan to `in progress`, and commit it on the lead's branch.
 - Tell the person, in a few lines: what was dispatched, to which lane and branch, what's still blocked and on what, and what's ready next.
-- As each agent finishes, read its report. If it came back with a change request or a question, decide it yourself with `/code-kit:decide`, and bring to the person only what crosses a guardrail. If it came back done, run the review skill on its branch.
+- As each agent finishes, read its hand-back: a few lines saying done or blocked, and the path of its full report (`.claude/state/reports/<branch>.md`). Open the report only when you need its detail: in the review, or to decide what it asks. If it came back with a change request or a question, decide it yourself with `/code-kit:decide`, and bring to the person only what crosses a guardrail. If it came back done, run the review skill on its branch.

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);