@warren-dean/code-kit 0.7.0 → 0.8.1

package/hooks/mod/view.mjs

@@ -8,6 +8,7 @@ const LEAD = 'lead';
 
 /** A CLI run's stdout as JSON, or null when it printed none. */
 import { BAR, POSE_GLYPH, rasterCells, runs, sprite, spriteSvg, timelineSvg } from './art.mjs';
+import { missionLines, nextText } from './mission.mjs';
 
 export function parseJson(stdout) {
   try {
@@ -94,6 +95,7 @@ export function projectState(check, status, next = null, atWork = new Set()) {
       worktree: s.worktree ?? null,
       requirements: s.requirements ?? [],
       waitingOn: s.waitingOn ?? [],
+      milestone: s.milestone ?? null,
     })),
   };
 }
@@ -101,6 +103,7 @@ export function projectState(check, status, next = null, atWork = new Set()) {
 export const STATE_COLOR = {
   building: 'blue',
   working: 'green',
+  orchestrating: 'yellow',
   'in review': 'yellow',
   'sent back': 'magenta',
   blocked: 'red',
@@ -112,6 +115,10 @@ export const STATE_COLOR = {
  * `working` while its agent (or the lead, mid-turn) is at work on nothing the plan names.
  */
 export function shownState(lane, queue = []) {
+  // LANES-2: the lead mid-turn is orchestrating unless it builds its own story; between turns, a story
+  // of its own that waits on another is the story's state, not the lead's.
+  if (lane.name === LEAD && lane.active && lane.state !== 'building') return 'orchestrating';
+  if (lane.name === LEAD && lane.state === 'blocked') return 'idle';
   if (lane.state === 'idle' && lane.active) return 'working';
   const waiting = queue.some(
     (e) => e.branch === lane.branch && ['waiting', 'merging'].includes(e.state),
@@ -212,11 +219,42 @@ export function lanesPane(
           .some((s) => s.toLowerCase().includes(needle))),
   );
   const LIVE = { quiet: 'yellow', stalled: 'red' };
+  // LANES-2: fixed columns that never wrap: name, state, then the story (and the agent's current tool
+  // beneath it), then tokens; another tool's facts only when they aren't zero.
+  const STATE_WIDTH = 13;
   const rows = shown.map((l) => {
+    const s = shownState(l, loop?.queue);
+    const facts = combined?.[l.name];
+    const chips = [
+      ...(facts?.without
+        ? [text(`${facts.without} edited without understanding`, { color: 'red' })]
+        : []),
+      ...(facts?.owed
+        ? [text(`${facts.owed} card${facts.owed === 1 ? '' : 's'} owed`, { color: 'yellow' })]
+        : []),
+      ...(loop?.laneNotes?.[l.name]
+        ? [
+            text(loop.laneNotes[l.name], {
+              color: loop.laneNotes[l.name] === 'stalled' ? 'red' : 'yellow',
+            }),
+          ]
+        : []),
+    ];
+    const story = l.story
+      ? `${l.story.id} ${l.story.title}${
+          l.story.state === 'blocked' && l.story.waitingOn?.length
+            ? ` · waits on ${l.story.waitingOn.join(', ')}`
+            : l.branch
+              ? ` · ${l.branch}`
+              : ''
+        }`
+      : l.name === LEAD
+        ? 'the main session'
+        : (l.agent ?? '');
     const lines = [
       Box({
         flexDirection: 'row',
-        columnGap: 2,
+        columnGap: 1,
         children: [
           text(l.name === selected ? '›' : l.active ? '●' : ' ', {
             color: l.name === selected ? 'cyan' : 'green',
@@ -226,86 +264,52 @@ export function lanesPane(
             ...(l.name === selected ? { color: 'cyan' } : {}),
           }),
           text(
-            shownState(l, loop?.queue).padEnd(9),
-            shownState(l, loop?.queue) === 'queued'
+            s.padEnd(STATE_WIDTH),
+            s === 'queued'
               ? { color: 'cyan' }
-              : STATE_COLOR[shownState(l, loop?.queue)]
-                ? { color: STATE_COLOR[shownState(l, loop?.queue)] }
-                : {},
+              : STATE_COLOR[s]
+                ? { color: STATE_COLOR[s] }
+                : { dimColor: true },
           ),
-          text(l.agent ?? 'the main session', { dimColor: true }),
-          ...(live[l.name]
-            ? [
+          Box({
+            flexGrow: 1,
+            flexShrink: 1,
+            children: [text(story, { wrap: 'truncate-end', dimColor: !l.story })],
+          }),
+          ...chips,
+          ...(usage?.lanes[l.name]
+            ? [text(tokens(usage.lanes[l.name]).padStart(6), { dimColor: true })]
+            : []),
+        ],
+      }),
+      // VIEW-4: what its agent is doing now, and since when, beneath the story.
+      ...(live[l.name]
+        ? [
+            Box({
+              flexDirection: 'row',
+              columnGap: 1,
+              children: [
+                text(''.padEnd(width + STATE_WIDTH + 3)),
                 text(`${live[l.name].tool} · ${live[l.name].ago}`, {
                   wrap: 'truncate-end',
                   ...(LIVE[live[l.name].level]
                     ? { color: LIVE[live[l.name].level] }
                     : { dimColor: true }),
                 }),
-              ]
-            : []),
-          ...(loop?.laneNotes?.[l.name]
-            ? [
-                text(loop.laneNotes[l.name], {
-                  color: loop.laneNotes[l.name] === 'stalled' ? 'red' : 'yellow',
-                }),
-              ]
-            : []),
-          ...(usage?.lanes[l.name] ? [text(tokens(usage.lanes[l.name]), { dimColor: true })] : []),
-          // JOIN-2: with an adapter that knows, the lane's edits without understanding and cards owed.
-          ...(combined?.[l.name]
-            ? [
-                text(
-                  `${combined[l.name].without} edit${combined[l.name].without === 1 ? '' : 's'} without understanding`,
-                  combined[l.name].without ? { color: 'red' } : { dimColor: true },
-                ),
-                text(
-                  `${combined[l.name].owed} card${combined[l.name].owed === 1 ? '' : 's'} owed`,
-                  combined[l.name].owed ? { color: 'yellow' } : { dimColor: true },
-                ),
-              ]
-            : []),
-        ],
-      }),
-      ...(l.story
-        ? [
-            text(
-              `    ${l.story.id} ${l.story.title}${l.branch ? ` · ${l.branch}` : ''}${
-                l.state === 'blocked' ? ` · waits on ${l.story.waitingOn.join(', ')}` : ''
-              }`,
-              { dimColor: true, wrap: 'truncate-end' },
-            ),
-          ]
-        : []),
-      ...bar(l),
-      // VIEW-6: the selected lane's detail: the paths it owns and its stories, each with its state.
-      ...(l.name === selected && detail
-        ? [
-            text(`    owns ${detail.owns.length ? detail.owns.join(', ') : 'nothing yet'}`, {
-              dimColor: true,
-              wrap: 'truncate-end',
+              ],
             }),
-            ...(detail.stories.length
-              ? detail.stories.map((s) =>
-                  text(
-                    `    ${s.id} ${s.title} · ${s.state}${s.state === 'blocked' && s.waitingOn.length ? ` on ${s.waitingOn.join(', ')}` : ''}`,
-                    {
-                      dimColor: s.state === 'done',
-                      ...(s.state === 'blocked' ? { color: 'red' } : {}),
-                      wrap: 'truncate-end',
-                    },
-                  ),
-                )
-              : [text('    no stories in the plan', { dimColor: true })]),
           ]
         : []),
+      ...bar(l),
+      // LANES-3: the selected lane's stories as cards, then what it owns.
+      ...(l.name === selected && detail ? laneDetail(detail, els, width) : []),
     ];
     return art
       ? Box({
           key: `lane-${l.name}`,
           flexDirection: 'row',
           columnGap: 1,
-          children: [character(l), Box({ flexDirection: 'column', children: lines })],
+          children: [character(l), Box({ flexDirection: 'column', flexGrow: 1, children: lines })],
         })
       : Box({ key: `lane-${l.name}`, flexDirection: 'column', children: lines });
   });
@@ -335,6 +339,7 @@ export function lanesPane(
     flexDirection: 'column',
     rowGap: 1,
     children: [
+      ...loopCard(loop, els),
       ...notes,
       Box({
         flexDirection: 'column',
@@ -342,11 +347,156 @@ export function lanesPane(
       }),
       Box({ flexDirection: 'column', children: ready }),
       ...reviewsSection(loop, text, Box),
-      ...loopSection(loop, text, Box),
     ],
   });
 }
 
+const CARD_STATE = {
+  done: { label: 'merged', color: 'gray' },
+  review: { label: 'in review', color: 'yellow' },
+  'in progress': { label: 'building', color: 'blue' },
+  'sent back': { label: 'sent back', color: 'magenta' },
+  blocked: { label: 'blocked', color: 'red' },
+  ready: { label: 'ready', color: 'green' },
+  todo: { label: 'to do', color: 'gray' },
+};
+
+/**
+ * LANES-3: a lane's stories as cards (id and state, title, requirements, and what it waits on or its
+ * branch), wrapping across the pane, then its agent and the paths it owns. `detail` is { agent, owns,
+ * stories }.
+ */
+export function laneDetail(detail, { Box, Text }, indent = 0) {
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  const cards = detail.stories.map((s) => {
+    const st = CARD_STATE[s.state] ?? { label: s.state, color: 'gray' };
+    return Box({
+      key: `card-${s.id}`,
+      flexDirection: 'column',
+      borderStyle: 'round',
+      borderColor: st.color,
+      ...(s.state === 'done' ? { borderDimColor: true } : {}),
+      paddingX: 1,
+      width: 30,
+      children: [
+        Box({
+          flexDirection: 'row',
+          justifyContent: 'space-between',
+          children: [
+            text(s.id, { bold: true, dimColor: s.state === 'done' }),
+            text(st.label, { color: st.color }),
+          ],
+        }),
+        text(s.title, { wrap: 'truncate-end', dimColor: s.state === 'done' }),
+        ...(s.requirements?.length
+          ? [text(s.requirements.join(' '), { dimColor: true, wrap: 'truncate-end' })]
+          : []),
+        ...(s.state === 'blocked' && s.waitingOn?.length
+          ? [text(`waits on ${s.waitingOn.join(', ')}`, { color: 'red', wrap: 'truncate-end' })]
+          : s.branch && s.state !== 'done'
+            ? [text(s.branch, { dimColor: true, wrap: 'truncate-end' })]
+            : []),
+      ],
+    });
+  });
+  return [
+    Box({
+      key: 'lane-cards',
+      flexDirection: 'row',
+      flexWrap: 'wrap',
+      columnGap: 1,
+      marginLeft: Math.min(indent + 2, 8),
+      children: cards.length
+        ? cards
+        : [text('No stories in the plan for this lane.', { dimColor: true })],
+    }),
+    Box({
+      key: 'lane-owns',
+      flexDirection: 'row',
+      flexWrap: 'wrap',
+      columnGap: 2,
+      marginLeft: Math.min(indent + 2, 8),
+      children: [
+        ...(detail.agent ? [text('agent', { dimColor: true }), text(detail.agent)] : []),
+        text('owns', { dimColor: true }),
+        ...(detail.owns.length
+          ? detail.owns.map((p) => text(p, { color: 'cyan' }))
+          : [text('nothing yet', { dimColor: true })]),
+      ],
+    }),
+  ];
+}
+
+/**
+ * LANES-1: the loop as a card at the top of the Lanes tab: its mode, then the steps it took, the one
+ * running and the one it takes next. None while the loop is off and has taken no step.
+ */
+export function loopCard(loop, { Box, Text }) {
+  if (!loop || (loop.state === 'off' && !loop.steps?.length)) return [];
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  const mode =
+    loop.state === 'paused'
+      ? { word: 'paused', color: 'yellow' }
+      : loop.state === 'off'
+        ? { word: 'off', color: 'gray' }
+        : loop.state === 'done' || loop.state === 'stopped'
+          ? { word: 'milestone done', color: 'green' }
+          : {
+              word:
+                loop.autonomy === 'propose'
+                  ? 'asks before each step'
+                  : 'acts while the lead is idle',
+              color: 'green',
+            };
+  // The step running now has its own chip; the ones before it are what the loop did.
+  const steps = [...(loop.steps ?? [])].slice(0, loop.current ? -1 : undefined).slice(-4);
+  const chip = (key, value, color, extra = {}) =>
+    Box({
+      key,
+      borderStyle: 'single',
+      borderColor: color,
+      paddingX: 1,
+      children: [text(value, { wrap: 'truncate-end', ...extra })],
+    });
+  return [
+    Box({
+      key: 'loop-card',
+      flexDirection: 'column',
+      borderStyle: 'round',
+      borderColor: 'gray',
+      paddingX: 1,
+      children: [
+        Box({
+          flexDirection: 'row',
+          columnGap: 2,
+          children: [
+            text('loop', { bold: true, color: 'yellow' }),
+            text(mode.word, { color: mode.color }),
+          ],
+        }),
+        Box({
+          flexDirection: 'row',
+          flexWrap: 'wrap',
+          columnGap: 1,
+          children: [
+            ...steps.map((s, i) =>
+              chip(
+                `loop-step-${i}`,
+                `${ago(loop.now - s.at).replace(' ago', '')} ${s.kind} ${s.target}`,
+                'gray',
+                { dimColor: true },
+              ),
+            ),
+            ...(loop.nextText
+              ? [chip('loop-next', `next: ${loop.nextText}`, 'cyan', { color: 'cyan' })]
+              : []),
+          ],
+        }),
+      ],
+    }),
+  ];
+}
+
 /** How long ago, as a person reads it: now, 40s ago, 12m ago, 2h ago. */
 export function ago(ms) {
   const s = Math.max(0, Math.round(ms / 1000));
@@ -425,32 +575,6 @@ export function reviewsSection(loop, text, Box) {
   ];
 }
 
-/** The loop's record (spec 05): its state and its latest steps, newest first. */
-export function loopSection(loop, text, Box) {
-  if (!loop || (!loop.steps?.length && loop.state !== 'paused')) return [];
-  const steps = [...(loop.steps ?? [])].reverse().slice(0, 8);
-  return [
-    Box({
-      flexDirection: 'column',
-      children: [
-        text(`Loop · ${loop.state === 'paused' ? 'paused' : loop.autonomy}`, { bold: true }),
-        ...steps.map((s, i) =>
-          Box({
-            key: `step-${i}`,
-            flexDirection: 'row',
-            columnGap: 2,
-            children: [
-              text(ago(loop.now - s.at).padEnd(8), { dimColor: true }),
-              text(s.kind.padEnd(8)),
-              text(s.target, { wrap: 'truncate-end' }),
-            ],
-          }),
-        ),
-      ],
-    }),
-  ];
-}
-
 /** USE-2: the plan's 5-hour use as a bar, each story's tokens, and the background agents' share. */
 export function usageSection(usage, plan, text, Box) {
   const lines = [];
@@ -560,8 +684,15 @@ export function bandLines({
   loop = null,
   queue = [],
   check = null,
+  leadBusy = false,
+  live = {},
+  nextStep = null,
+  combined = null,
 }) {
   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 });
+  lines.push(...mission);
   if (notice)
     lines.push({ kind: 'notice', text: notice, actions: [{ id: 'dismiss', label: 'Dismiss' }] });
   if (!state || state.kind !== 'ok') return lines;
@@ -620,7 +751,13 @@ export function bandLines({
       request: open[0],
       actions: [{ id: 'approve', label: 'Approve…' }],
     });
-  const inReview = state.lanes.filter((l) => l.state === 'in review').map((l) => l.story);
+  // DECIDE-1: reviewing a lane's work is the lead's. Only with the loop off, where the person runs the
+  // build themselves, does a finished story wait in the band for their Review or Merge; otherwise the
+  // loop prompts the lead (or, under propose, offers the step with Go).
+  const loopOff = (check?.harness?.autonomy ?? 'autonomous') === 'off';
+  const inReview = loopOff
+    ? state.lanes.filter((l) => l.state === 'in review').map((l) => l.story)
+    : [];
   if (inReview.length) {
     const [story] = inReview;
     const ids = inReview.map((s) => s.id).join(', ');
@@ -661,15 +798,13 @@ export function bandLines({
     });
   // MQ-2: where the lead doesn't merge, the head of the queue waits for the person's Merge.
   const next = queue.find((e) => ['waiting', 'merging'].includes(e.state));
-  const leadMerges =
-    check?.delegatesMerge && (check?.harness?.autonomy ?? 'autonomous') === 'autonomous';
+  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)
     lines.push({
       kind: 'queue',
-      // The first merge brings code-kit's rules onto the base, so it's the person's even under autonomy.
-      text: check?.firstMerge
-        ? `${next.branch} is next to merge: the first merge is yours, then the lead merges`
-        : `${next.branch} is next to merge`,
+      text: `${next.branch} is next to merge`,
       branch: next.branch,
       actions: [{ id: 'mergeQueue', label: 'Merge' }],
     });
@@ -680,7 +815,10 @@ export function bandLines({
       text: `Milestone done: ${plural(loop.doneCount, 'story', 'stories')} merged`,
       actions: [{ id: 'dismissDone', label: 'Dismiss' }],
     });
-  else if (loop?.state === 'paused')
+  // 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 === 'paused')
     lines.push({ kind: 'loop', text: 'loop paused', actions: [{ id: 'resume', label: 'Resume' }] });
   else if (loop?.state === 'running' && loop.started)
     lines.push({
@@ -710,31 +848,101 @@ export function band(lines, { Box, Text, Button }, onAction) {
     finish: 'red',
     usage: 'yellow',
     paused: 'yellow',
+    facts: 'yellow',
   };
-  return Box({
-    flexDirection: 'column',
-    children: lines.map((line) =>
-      Box({
-        key: `band-${line.kind}`,
-        flexDirection: 'row',
-        columnGap: 2,
+  const LIVE = { quiet: 'yellow', stalled: 'red' };
+  const LABEL = 8;
+  const buttons = (line) =>
+    line.actions.map((a) =>
+      Button({
+        key: `band-${a.id}`,
+        label: a.hotkey ? `${a.hotkey} ${a.label}` : a.label,
+        hotkey: a.hotkey,
+        onPress: () => onAction(a.id, line),
+      }),
+    );
+  // MISSION-2: what waits on the person is labelled "you", once, above its first line.
+  let saidYou = false;
+  const rows = lines.map((line) => {
+    if (line.kind === 'agents')
+      return Box({
+        key: 'band-agents',
+        flexDirection: 'column',
         children: [
-          Text({ color: COLOR[line.kind], children: ['code-kit'] }),
-          Text({ children: [line.text] }),
-          ...line.actions.map((a) =>
-            Button({
-              key: `band-${a.id}`,
-              label: a.hotkey ? `${a.hotkey} ${a.label}` : a.label,
-              hotkey: a.hotkey,
-              onPress: () => onAction(a.id, line),
+          ...line.agents.map((a) =>
+            Box({
+              key: `band-agent-${a.lane}`,
+              flexDirection: 'row',
+              columnGap: 1,
+              children: [
+                Text({
+                  dimColor: true,
+                  children: [(a === line.agents[0] ? line.label : '').padEnd(LABEL)],
+                }),
+                Text({ color: a.level ? LIVE[a.level] : 'green', children: ['●'] }),
+                Text({ bold: true, children: [a.lane.padEnd(8)] }),
+                Text({ wrap: 'truncate-end', children: [a.tool] }),
+                Text({ dimColor: true, children: [a.ago] }),
+              ],
             }),
           ),
+          ...(line.more
+            ? [Text({ dimColor: true, children: [`${''.padEnd(LABEL)}  and ${line.more} more`] })]
+            : []),
         ],
-      }),
-    ),
+      });
+    // DECIDE-3: what needs the person is labelled "you", once; notes (usage, the plan's pause) are "note".
+    const note = NOTE_KINDS.has(line.kind);
+    const label = line.mission ? line.label : note ? 'note' : saidYou ? '' : 'you';
+    if (!line.mission && !note) saidYou = true;
+    return Box({
+      key: `band-${line.kind}`,
+      flexDirection: 'row',
+      columnGap: 1,
+      children: [
+        Text({
+          ...(line.mission ? { dimColor: true } : { color: COLOR[line.kind] ?? 'yellow' }),
+          children: [label.padEnd(LABEL)],
+        }),
+        Text({
+          wrap: 'truncate-end',
+          ...(line.kind === 'facts' ? { color: COLOR.facts } : {}),
+          children: [line.text],
+        }),
+        // DECIDE-2: which story it's for, so it isn't a fragment.
+        ...(line.context
+          ? [Text({ dimColor: true, wrap: 'truncate-end', children: [line.context] })]
+          : []),
+        ...buttons(line),
+      ],
+    });
   });
+  // DECIDE-3: one key opens the decisions as cards, each with its lineage and what each choice does.
+  const first = lines.find((l) => !l.mission && !NOTE_KINDS.has(l.kind));
+  if (first)
+    rows.push(
+      Box({
+        key: 'band-why',
+        flexDirection: 'row',
+        columnGap: 1,
+        children: [
+          Text({ children: [''.padEnd(LABEL)] }),
+          Button({
+            key: 'band-decide',
+            label: 'Why, and what each choice does',
+            hotkey: 'd',
+            plain: true,
+            onPress: () => onAction('decide', first),
+          }),
+        ],
+      }),
+    );
+  return Box({ flexDirection: 'column', children: rows });
 }
 
+/** Band lines that inform rather than ask: they never need the person's answer. */
+const NOTE_KINDS = new Set(['usage', 'paused', 'finish', 'done']);
+
 /** The Approve… confirmation (ACT-1): what it grants, to whom, for how long, and the reason. */
 export function approvePane(
   approving,

package/package.json

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

@@ -67,7 +67,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
 - **`shell.restricted`:** commands that affect a shared local service, limited to the lanes that own it.
 - **`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.
+- **`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 `approvals.delegate`: `"merge": true` (the lead merges a reviewed branch once every check passes) and `"dependencies": {}` (it approves a new package within the default limits on licence, popularity and age), so neither comes to the person. Say these are the limits; anything outside them still comes to them as a decision.
 - **`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.
 
 Prove the draft:
@@ -124,9 +124,9 @@ Once they approve (with any changes):
    - make sure the lead owns the workflow file, and add it to `protected` (approval `ci`, why "the CI that enforces the rules"), so a lane can't switch it off;
    - tell the person to make the `code-kit` check required on the protected branches.
 7. Run `check` and `unowned` again, without `--config`.
-8. Commit on a branch. The kit records the protected files in `.claude/approval-log.jsonl`.
+8. Commit the setup straight onto the base branch (usually `main`), not a branch: while the base has no `.claude/code-kit.json` committed, the hooks let the lead make that one commit, so the rules the person just approved are in force on `main` and the lead can merge reviewed work from the start, with no first merge for anyone to make. The kit records the protected files in `.claude/approval-log.jsonl`. If the base already has rules (an update, section 4), commit on a branch as usual.
 
-Report what was set up, what's enforced from now on, how many existing violations the baseline holds, and the open questions. If the base branch had no `.claude/code-kit.json` committed before, say that the first merge into it is the person's, since that merge brings the rules onto it: once the branch has passed review, they press Merge in the code-kit band, or run `! node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue merge --person`. After that, the rules committed there decide who merges.
+Report what was set up, what's enforced from now on, how many existing violations the baseline holds, and the open questions. Say who does what from here: the person owns the intent and the rules; the lead owns delivery, so it dispatches, reviews, sends back and merges, and approves within the delegated limits, and only a real decision (scope, something outside those limits, a problem it couldn't solve) comes to the person.
 
 If the project has no `.ctx/` folder, end the report with one line about the companion plugin. If Context Graph is already installed (its `/context-graph:init` command is available to you), offer to run it now: "Context Graph is installed but has no graph here yet. `/context-graph:init` gives each lane agent the why behind the files it edits (cards, rules and decisions kept in git), with this spec's requirements and layer rules in them. Shall I run it?" If it isn't installed, don't install it unless the person asks: "Context Graph can give each lane agent the why behind the files it edits (cards, rules and decisions kept in git), with this spec's requirements and layer rules in them: `/plugin marketplace add warrendeanlangeveldt/context-graph`, then `/plugin install context-graph@context-graph`."