kaizen-agent 0.6.0 → 0.7.1

package/README.md

@@ -352,6 +352,8 @@ tells you what it concluded, so you correct a sentence instead of filling in a f
 | `/kaizen <request>` | Start a run |
 | `/kaizen-plan <request>` | Plan only — stop before anything is built |
 | `/kaizen-auto <request>` | No approval stops; report at the end |
+| `/kaizen-lite <request>` | Every stage in this session — cheap, and the reviewer has seen the work |
+| `/kaizen-full <request>` | Every stage its own cold agent — the independent review |
 | `/kaizen-review [target]` | Review something that already exists |
 | `/kaizen-status` | What is waiting on you, in flight, done |
 | `/kaizen-approve` | Approve whatever the run is waiting on |
@@ -391,6 +393,7 @@ in one can be finished in another. See [adapters.md](https://github.com/hfadhlul
 | Setting | Default | Meaning |
 |---|---|---|
 | `mode` | `approve` | `approve` stops for you; `auto` never does; `plan-only` stops after the plan |
+| `runner` | `full` | `full` gives each stage its own agent, so the reviewer never saw the work — several times the cost. `lite` runs every stage here, at about the cost of doing it by hand |
 | `build.executor` | `subagent` | Who does the work: a separate agent, `inline` in the current one, or `ask` each time |
 | `auto_fix.min_severity` | `high` | Findings this bad or worse get fixed without asking |
 | `approvals.plan` | `true` | Stop and show the plan before anything is built |

package/cli/dashboard.ts

@@ -1,10 +1,13 @@
 // What `kaizen` shows once it is installed: the state of this project's runs, and
 // the few things you would have opened a terminal to do.
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, appendFileSync, mkdirSync, statSync } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { homedir } from "node:os";
 
 const home = homedir();
+const rgb = (r: number, g: number, b: number, s: string) =>
+  `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m`;
+
 const c = {
   dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
   bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
@@ -16,29 +19,8 @@ const c = {
 type Run = { id: string; stage: string; awaiting: string | null };
 
 // The mascot, rendered from assets/kaizen.jpg. Braille packs 2x4 dots into one
-// character, which is the only way outline art survives a downsample this far;
-// sampling brightness onto a character ramp gives grey mush, having no midtones
-// to sample. Regenerate with the snippet in assets/tanuki.txt's history.
+// character, which is the only way outline art survives a downsample this far.
 const TANUKI = [
-  "⠀⠀⠀⠀⢀⡶⢶⣖⡒⠒⠛⠛⠛⠛⣛⡿⠟⢛⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀",
-  "⠀⠀⠀⢀⣾⡇⠀⠀⠉⠛⠲⣤⠴⠛⠁⢀⡴⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀",
-  "⠀⠀⠀⡾⢹⠇⠀⠀⣠⠴⠋⠁⠀⣠⠖⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀",
-  "⠀⠀⣼⠁⣸⣠⡴⠋⢁⡴⠦⣄⡚⢁⣀⣀⣀⣀⡀⢀⣠⠴⢦⡀⠀⠀⠀⠀⠀⠀⠀⠀",
-  "⠀⣸⢃⡴⠟⠁⠀⣀⢸⡇⠀⠈⠙⠉⠉⠀⠀⠉⠉⠋⠁⠀⢨⡇⠀⠀⠀⠀⠀⠀⠀⠀",
-  "⣰⡿⠋⢰⡏⢹⠋⠁⠈⣧⠀⠀⢀⡀⠀⠀⠀⠀⢀⡀⠀⠀⣸⠃⠀⠀⠀⠀⠀⠀⠀⠀",
-  "⠻⠖⠛⢹⡇⠘⣇⠀⢰⠇⣠⠞⢉⡉⢳⡀⢀⡞⢉⡉⠳⣄⠘⣆⠀⠀⢠⡤⣤⢀⡀⠀",
-  "⠀⠀⠀⠀⣧⠀⠉⣰⣋⡴⠃⠀⠈⠁⡞⣀⣀⢳⠈⠁⠀⠘⢦⣙⣆⠀⣰⠃⠹⡇⣸⣻",
-  "⠀⠀⠀⠀⠘⣆⠀⠈⠻⣄⠀⠀⠀⠀⠳⢬⡥⠞⠀⠀⠀⠀⣠⠝⠁⢀⡇⠀⠀⣷⢳⠃",
-  "⠀⠀⠀⠀⠀⠈⢧⡀⠀⠈⠙⠲⠦⣤⣤⣀⣀⣤⣤⠴⠖⠿⠷⠶⠚⠉⣳⠤⠴⠯⠏⠀",
-  "⠀⠀⠀⠀⠀⠀⠀⠙⠲⣄⠀⠀⠀⣀⡤⠶⠶⢤⣀⠀⠀⠀⠀⣀⣤⠞⣡⠶⠚⠒⢦⡀",
-  "⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⠀⠀⡼⠁⠀⠀⠀⠀⠈⢧⠀⠀⢾⠉⢀⡾⠻⣄⡀⠀⠈⡇",
-  "⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠐⡇⠀⠀⠀⠀⠀⠀⢸⠆⠀⢸⠚⠉⠀⠀⠀⢯⣀⡼⠃",
-  "⠀⠀⠀⠀⠀⠀⠀⠀⠀⢷⠀⠀⠻⣄⠀⠀⠀⠀⣠⠟⠀⠀⡾⢤⣤⣀⣤⡤⠶⠋⠀⠀",
-  "⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⢧⣄⣠⠤⠶⠒⠒⠻⠧⣄⣠⡼⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀",
-];
-
-// The same, for windows that cannot spare fifteen rows before the runs begin.
-const TANUKI_SMALL = [
   "⠀⠀⠀⣰⠖⠾⣟⣛⠋⢉⣩⠽⢛⡽⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀",
   "⠀⠀⢰⢻⠀⠀⢀⡬⠟⠉⢀⠴⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀",
   "⠀⢠⠇⣾⡠⠞⢩⠤⢄⡚⣁⣀⣀⣀⢀⣠⠤⡄⠀⠀⠀⠀⠀⠀",
@@ -52,6 +34,13 @@ const TANUKI_SMALL = [
   "⠀⠀⠀⠀⠀⠀⠀⠳⣀⣨⠥⠤⠶⠾⣅⣀⠞⠉⠉⠉⠉⠀⠀⠀",
 ];
 
+// Compact block wordmark (28 columns x 3 rows).
+const WORDMARK = [
+  "█ █  ▄▀█  █  ▀▀█  █▀▀  █▄ █",
+  "█▀▄  █▀█  █   ▄▀  ██▄  █ ▀█",
+  "█ █  █ █  █  █▄▄  █▄▄  █  █",
+];
+
 
 export async function dashboard(
   repo: string,
@@ -60,8 +49,32 @@ export async function dashboard(
 ) {
   const { stdin, stdout } = process;
   const state = locate();
+  // Opening a project is what makes it known; nothing else asks the user to register.
+  if (state && dirname(state) !== home) remember(dirname(state));
+
+  // Every known project's runs and open items, tagged with where they came from.
+  // draw() runs on every keypress, so this is gathered when the dashboard opens and
+  // after an action returns -- never inside draw().
+  type Seen = { runs: (Run & { where: string })[]; items: { text: string; where: string }[] };
+  let seen: Seen = { runs: [], items: [] };
+
+  const survey = () => {
+    const dirs = [...knownProjects().map((d) => join(d, ".kaizen")), join(home, ".kaizen")]
+      .filter((d, i, all) => all.indexOf(d) === i && existsSync(d));
+    const runs: Seen["runs"] = [], items: Seen["items"] = [];
+    for (const dir of dirs) {
+      const where = label(dir);
+      for (const r of readRuns(dir)) runs.push({ ...r, where });
+      for (const g of allBacklog(dir)) for (const t of g.items) items.push({ text: t, where });
+    }
+    seen = { runs, items };
+  };
+  survey();
 
   const actions = () => [
+    ...(knownProjects().length || !state ? [
+      { key: "projects", label: "All projects", hint: "every project kaizen knows about" },
+    ] : []),
     ...(state ? [
       { key: "runs", label: "Runs", hint: "every run, and what each is waiting on" },
       { key: "backlog", label: "Backlog", hint: "what runs noticed and did not do" },
@@ -78,10 +91,12 @@ export async function dashboard(
   for (;;) {
     const chosen = await menu();
     if (chosen === "quit") return;
+    if (chosen === "projects") { await projectsView(); continue; }
     if (chosen === "runs") { await runsView(); continue; }
     if (chosen === "backlog") { await backlogView(); continue; }
     const lines = await run(chosen);
     if (lines?.length) await report(lines);
+    survey();                                   // an action may have changed what exists
   }
 
   // An action that has something to say says it here, on its own screen, rather
@@ -115,13 +130,14 @@ export async function dashboard(
     rows: string[],
     footer = "enter open · backspace back",
     skip: (i: number) => boolean = () => false,
-  ) {
-    if (!rows.length) { await report([c.bold(title), "", c.dim("nothing here yet")]); return null; }
+    extra = "",                        // keys the caller wants to hear about
+  ): Promise<{ index: number | null; key?: string }> {
+    if (!rows.length) { await report([c.bold(title), "", c.dim("nothing here yet")]); return { index: null }; }
 
     // Headings are rows too, but they are not items: they are not counted, and
     // moving passes over them rather than landing on them.
     const pickable = rows.map((_, i) => i).filter((i) => !skip(i));
-    if (!pickable.length) { await report([c.bold(title), "", c.dim("nothing here yet")]); return null; }
+    if (!pickable.length) { await report([c.bold(title), "", c.dim("nothing here yet")]); return { index: null }; }
     let cursor = 0;                                  // index into pickable
     const move = (d: number) => { cursor = Math.min(pickable.length - 1, Math.max(0, cursor + d)); };
     let top = 0;
@@ -146,7 +162,7 @@ export async function dashboard(
     stdin.setRawMode(true);
     stdin.resume();
     draw();
-    let chosen: number | null = null;
+    let chosen: number | null = null, hit: string | undefined;
     await new Promise<void>((resolve) => {
       const onData = (chunk: Buffer) => {
         const keys = chunk.toString();
@@ -159,6 +175,8 @@ export async function dashboard(
           if (rest.startsWith("\r") || rest.startsWith("\n")) {
             chosen = pickable[cursor]!; stdin.off("data", onData); return resolve();
           }
+          const k = [...extra].find((x) => rest.startsWith(x));
+          if (k) { hit = k; stdin.off("data", onData); return resolve(); }
           if (rest.startsWith("\x1b[A")) { move(-1); i += 2; }
           else if (rest.startsWith("\x1b[B")) { move(1); i += 2; }
           else if (rest.startsWith("k")) move(-1);
@@ -172,12 +190,74 @@ export async function dashboard(
     stdin.setRawMode(false);
     stdin.pause();
     stdout.write("\x1b[?25h\x1b[?1049l");
-    return chosen;
+    return { index: hit ? pickable[cursor]! : chosen, key: hit };
+  }
+
+  // Every project kaizen knows about, with what each is waiting on. The global
+  // ~/.kaizen is one of them: it holds runs made outside any project.
+  async function projectsView() {
+    for (;;) {
+      const dirs = [...knownProjects(), join(home, ".kaizen")].filter(
+        (d, i, all) => all.indexOf(d) === i);
+
+      const rows: string[] = [];
+      const open: (string | null)[] = [];
+      const width = Math.max(...dirs.map((d) => tilde(d).length));
+
+      for (const dir of dirs) {
+        const st = dir.endsWith(".kaizen") ? dir : join(dir, ".kaizen");
+        if (!existsSync(st)) {
+          // Listed, not dropped: a project that moved should be visible and fixable,
+          // and the registry is a file the user can edit.
+          rows.push(`${c.dim(tilde(dir).padEnd(width))}  ${c.amber("missing")}`);
+          open.push(null);
+          continue;
+        }
+        const runs = readRuns(st);
+        const waiting = runs.filter((r) => r.awaiting && r.stage !== "abandoned").length;
+        const flight = runs.filter((r) => !r.awaiting && !["done", "abandoned"].includes(r.stage)).length;
+        const done = runs.filter((r) => r.stage === "done").length;
+        const items = allBacklog(st).reduce((n, g) => n + g.items.length, 0);
+        const bits = [
+          waiting ? c.amber(`${waiting} waiting`) : "",
+          flight ? c.cyan(`${flight} running`) : "",
+          done ? c.dim(`${done} done`) : "",
+          items ? c.dim(`${items} open`) : "",
+        ].filter(Boolean);
+        rows.push(`${tilde(dir).padEnd(width)}  ${bits.join(c.dim(" · ")) || c.dim("nothing yet")}`);
+        open.push(st);
+      }
+
+      const { index, key } = await pick("All projects", rows,
+        "enter runs · b backlog · s find more · backspace back", () => false, "sb");
+      if (index === null) return;
+      if (key === "s") { await sync(); continue; }     // the list rebuilds on the next pass
+      if (!open[index]) continue;                      // a project whose state has gone
+      if (key === "b") await backlogView(open[index]!);
+      else await runsView(open[index]!);
+    }
+  }
+
+  async function sync() {
+    const before = knownProjects().length;
+    const started = Date.now();
+    const found = findProjects(home);
+    for (const dir of found) remember(dir);
+    const added = knownProjects().length - before;
+    await report([
+      c.bold(added ? `Found ${added} project${added === 1 ? "" : "s"}` : "Nothing new"),
+      "",
+      ...found.map((d) => "  " + c.dim(tilde(d))),
+      "",
+      c.dim(`${found.length} found in ${((Date.now() - started) / 1000).toFixed(1)}s under ${tilde(home)}`),
+      c.dim(`the list lives in ${tilde(join(home, ".kaizen", "projects"))} and can be edited`),
+    ]);
   }
 
-  async function runsView() {
+  async function runsView(from?: string) {
     for (;;) {
-      const runs = readRuns(state!);
+      const here = from ?? state!;
+      const runs = readRuns(here);
       const width = Math.max(...runs.map((r) => r.id.length));
       const rows = runs.map((r) => {
         const mark = r.stage === "done" ? c.dim("done   ")
@@ -187,15 +267,15 @@ export async function dashboard(
         const tail = r.stage === "done" || r.stage === "abandoned" ? "" : (r.awaiting ?? r.stage);
         return `${mark}  ${r.id.padEnd(width)}  ${c.dim(tail)}`;
       });
-      const i = await pick("Runs", rows);
-      if (i === null) return;
-      await runDetail(runs[i]!);
+      const { index } = await pick(from ? `Runs — ${label(from)}` : "Runs", rows);
+      if (index === null) return;
+      await runDetail(runs[index]!, here);
     }
   }
 
   // What a run is, read off its own files rather than summarised from memory.
-  async function runDetail(r: Run) {
-    const dir = join(state!, "runs", r.id);
+  async function runDetail(r: Run, from?: string) {
+    const dir = join(from ?? state!, "runs", r.id);
     const lines: string[] = [c.bold(r.id), ""];
     lines.push(`  stage      ${r.stage}`);
     lines.push(`  waiting    ${r.awaiting ?? c.dim("nothing — it can carry on")}`);
@@ -234,8 +314,8 @@ export async function dashboard(
     return out + "…\x1b[0m";
   }
 
-  async function backlogView() {
-    const groups = allBacklog(state!);
+  async function backlogView(from?: string) {
+    const groups = allBacklog(from ?? state!);
     const parsed = groups.map((g) => ({ run: g.run, items: g.items.map(parseItem) }));
     const sevWidth = Math.max(0, ...parsed.flatMap((g) => g.items.map((i) => i.severity?.length ?? 0)));
     const whereWidth = Math.max(0, ...parsed.flatMap((g) => g.items.map((i) => i.where?.length ?? 0)));
@@ -258,11 +338,11 @@ export async function dashboard(
       }
     }
     for (;;) {
-      const i = await pick("Backlog — open items", rows, "enter read · backspace back",
-        (n) => full[n] === null);
-      if (i === null) return;
+      const { index } = await pick(from ? `Backlog — ${label(from)}` : "Backlog — open items",
+        rows, "enter read · backspace back", (n) => full[n] === null);
+      if (index === null) return;
       // Rows are cut to the window, so reading one means opening it.
-      const it = full[i];
+      const it = full[index];
       if (!it) continue;
       await report([
         c.bold(it.where ?? "Backlog item"),
@@ -288,29 +368,52 @@ export async function dashboard(
   async function menu() {
   const draw = () => {
     const acts = actions();
-    const runs = state ? readRuns(state) : [];
-    const waiting = runs.filter((r) => r.awaiting && r.stage !== "abandoned");
-    const flight = runs.filter((r) => !r.awaiting && !["done", "abandoned"].includes(r.stage));
-    const done = runs.filter((r) => r.stage === "done");
-
     stdout.write("\x1b[H\x1b[2J");
 
     // The mascot sits beside the header rather than above it; stacked, it pushes
     // the runs -- the thing you opened this for -- below the fold on a short window.
     const cols = stdout.columns ?? 80, rows = stdout.rows ?? 24;
     const wide = cols >= 64;
-    const art = rows >= 30 ? TANUKI : TANUKI_SMALL;
-    const at = art === TANUKI ? 6 : 2;          // where the text sits against it
+    const art = TANUKI;
+    const at = 2;          // where the text sits against it
+
+    // Every width below is measured, not guessed: the mascot's own width plus the
+    // gutter plus the wordmark's columns is exactly what the wide header occupies,
+    // and 2 more is the left margin every line is written with.
+    const gutter = Math.max(...art.map((l) => l.length)) + 4;
+    const setsWordmark = cols >= gutter + WORDMARK[0]!.length + 2;
 
     const beside = Array(art.length).fill("");
-    beside[at] = `${c.bold("kaizen")} ${c.dim(version(repo))}`;
-    beside[at + 1] = c.dim(state ? tilde(dirname(state)) : "no project here");
-    beside[at + 3] = c.dim(agents.join(", "));
+    if (setsWordmark) {
+      // Against the mascot's middle, with what kaizen is under it and where you are
+      // under that: the header says what the tool does before it says where it is.
+      const top = 2;
+      for (const [i, line] of WORDMARK.entries()) {
+        const t = i / (WORDMARK.length - 1);
+        beside[top + i] = rgb(
+          Math.round(222 - t * 120), Math.round(238 - t * 100), Math.round(255 - t * 30), line);
+      }
+      // The description is chosen from compact phrasings to fit cleanly beside the mascot.
+      const room = cols - gutter - 2 - (version(repo).length + 3);
+      const line = ["plan · approve · build · review",
+                    "plan · approve · build",
+                    "plan · build · review"].find((d) => d.length <= room);
+      beside[top + WORDMARK.length + 1] =
+        `${c.dim(version(repo))}${line ? "   " + c.dim(line) : ""}`;
+      beside[top + WORDMARK.length + 2] = c.dim(state ? tilde(dirname(state)) : "no project here");
+      beside[top + WORDMARK.length + 3] = c.dim(agents.join(", "));
+    } else {
+      beside[at] = `${c.bold("kaizen")} ${c.dim(version(repo))}`;
+      beside[at + 1] = c.dim(state ? tilde(dirname(state)) : "no project here");
+      beside[at + 3] = c.dim(agents.join(", "));
+    }
     stdout.write("\n");
     if (wide) {
-      const gutter = Math.max(...art.map((l) => l.length)) + 4;
+      // Cut what sits beside the mascot to the room left over. The agent list is
+      // long and grows with every agent installed, and it wrapped here before the
+      // wordmark existed -- a wrapped line pushes the whole header down a row.
       for (const [i, line] of art.entries()) {
-        stdout.write("  " + c.cyan(line.padEnd(gutter)) + (beside[i] ?? "") + "\n");
+        stdout.write("  " + c.cyan(line.padEnd(gutter)) + cut(beside[i] ?? "", cols - gutter - 2) + "\n");
       }
     } else {
       stdout.write(`  ${c.bold("kaizen")} ${c.dim(version(repo))}   ${c.dim(state ? tilde(dirname(state)) : "no project here")}\n`);
@@ -318,18 +421,28 @@ export async function dashboard(
     }
 
     if (state) {
+      // Across every project, not only this one. Where more than one is known each
+      // row says which, since "waiting on approvals.plan" means nothing on its own.
+      const many = new Set(seen.runs.map((r) => r.where)).size > 1;
+      const from = (w: string) => (many ? c.dim(w + "  ") : "");
+      const wait = seen.runs.filter((r) => r.awaiting && r.stage !== "abandoned");
+      const fly = seen.runs.filter((r) => !r.awaiting && !["done", "abandoned"].includes(r.stage));
+      const fin = seen.runs.filter((r) => r.stage === "done");
+
       const runLines = [
-        ...waiting.map((r) => `${c.amber("●")} ${short(r.id)}  ${c.dim(r.awaiting ?? "")}`),
-        ...flight.map((r) => `${c.cyan("●")} ${short(r.id)}  ${c.dim(r.stage)}`),
-        ...(done.length ? [c.dim(`● ${done.length} done`)] : []),
+        ...wait.map((r) => `${c.amber("●")} ${from(r.where)}${short(r.id)}  ${c.dim(r.awaiting ?? "")}`),
+        ...fly.map((r) => `${c.cyan("●")} ${from(r.where)}${short(r.id)}  ${c.dim(r.stage)}`),
+        ...(fin.length ? [c.dim(`● ${fin.length} done`)] : []),
       ];
       if (!runLines.length) runLines.push(c.dim("none yet"));
 
-      const items = allBacklog(state).flatMap((g) => g.items.map(parseItem));
+      // parseItem's `where` is the file the finding is in; the project is a separate
+      // thing and both belong on the row.
+      const items = seen.items.map((i) => ({ ...parseItem(i.text), project: i.where }));
       const backLines = items.slice(0, 6).map((it) => {
         const sev = it.severity ? (it.severity === "critical" || it.severity === "high"
           ? c.amber(it.severity) : c.dim(it.severity)) + " " : "";
-        return sev + (it.where ? c.dim(it.where) + "  " : "") + it.text;
+        return from(it.project) + sev + (it.where ? c.dim(it.where) + "  " : "") + it.text;
       });
       if (!backLines.length) backLines.push(c.dim("nothing open"));
       else if (items.length > 6) backLines.push(c.dim(`… ${items.length - 6} more`));
@@ -406,6 +519,50 @@ export async function dashboard(
   }
 }
 
+// The list of projects kaizen knows about. Appended to as kaizen sets one up or is
+// opened inside one, and seeded by the Find projects action. Plain lines so it can be
+// read and corrected in an editor; blanks and # lines ignored.
+const REGISTRY = join(home, ".kaizen", "projects");
+
+export function knownProjects(): string[] {
+  if (!existsSync(REGISTRY)) return [];
+  return readFileSync(REGISTRY, "utf8").split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith("#"));
+}
+
+// Never fails the command that triggered it: a read-only home is not a reason for a
+// dashboard to stop opening.
+export function remember(projectDir: string) {
+  try {
+    if (knownProjects().includes(projectDir)) return;
+    mkdirSync(dirname(REGISTRY), { recursive: true });
+    appendFileSync(REGISTRY, projectDir + "\n");
+  } catch { /* nothing here is worth an error */ }
+}
+
+// Bounded on purpose. Depth is what keeps this from becoming a filesystem walk, and
+// the skips are the directories that make one slow: node_modules, and anything dotted
+// (which includes .git, and every state directory that is not a project of its own).
+function findProjects(root: string, depth = 4): string[] {
+  const found: string[] = [];
+  const walk = (dir: string, left: number) => {
+    let entries: string[];
+    try { entries = readdirSync(dir); } catch { return; }
+    // $HOME holds ~/.kaizen, the global state, which is not a project and must not
+    // stop the walk before it has looked at anything.
+    if (dir !== root && entries.includes(".kaizen")) { found.push(dir); return; }
+    if (left === 0) return;
+    for (const name of entries) {
+      if (name.startsWith(".") || name === "node_modules") continue;
+      try { if (statSync(join(dir, name)).isDirectory()) walk(join(dir, name), left - 1); }
+      catch { /* unreadable or vanished mid-walk */ }
+    }
+  };
+  walk(root, depth);
+  return found;
+}
+
 function locate() {
   let dir = process.cwd();
   for (;;) {
@@ -444,6 +601,11 @@ function backlog(state: string) {
 function version(repo: string) {
   try { return JSON.parse(readFileSync(join(repo, "package.json"), "utf8")).version; } catch { return ""; }
 }
+// The global state directory is not a project and has no parent worth naming.
+function label(stateDir: string) {
+  return stateDir === join(home, ".kaizen") ? "global" : tilde(dirname(stateDir));
+}
+
 function tilde(p: string) { return p.startsWith(home) ? "~" + p.slice(home.length) : p; }
 
 // The first few real lines of a file's body, blank lines and headings dropped.
@@ -531,7 +693,7 @@ function panel(title: string, lines: string[], inner: number) {
     const body = cut(line, inner - 2);
     out.push(`${DIM}│${OFF} ${body}${" ".repeat(Math.max(0, inner - 2 - vis(body)))} ${DIM}│${OFF}`);
   }
-  out.push(`${DIM}╰${"─".repeat(inner)}╯${OFF}`);
+  out.push(`${DIM}╰${"─".repeat(Math.max(0, inner))}╯${OFF}`);
   return out;
 }
 

package/cli/install.ts

@@ -287,10 +287,10 @@ async function chooseRoot() {
   if (args.has("--project")) return process.cwd();
   if (args.has("--global") || !interactive) return home;
   // A project install only means something in a project. Standing in the home
-  // directory it is the global install under another name, and outside a
-  // repository there is nothing for it to belong to.
+  // directory it is the global install under another name; any other folder is
+  // a project worth installing into, git repository or not.
   const cwd = process.cwd();
-  if (cwd === home || !existsSync(join(cwd, ".git"))) return home;
+  if (cwd === home) return home;
 
   const names = (r: string) => found(r).map((a) => a.name).join(", ");
   return select("Install kaizen for", [
@@ -390,22 +390,43 @@ function installLauncher() {
   }
 }
 
-const inGitRepo = existsSync(join(process.cwd(), ".git"));
+const inProject = process.cwd() !== home;
 const kaizenDir = join(process.cwd(), ".kaizen");
 
-if (inGitRepo && !existsSync(kaizenDir)) {
+// A .kaizen/ in a parent already owns this folder's state, and setting up a child
+// would shadow it, hiding the parent's runs and leaving the child out of the root
+// .gitignore. Deliberately not shared with cli/dashboard.ts locate(): that one
+// resolves which state directory to read and so falls back to a global ~/.kaizen,
+// while this one decides whether a folder is already owned and must stop *before*
+// $HOME — a global ~/.kaizen would otherwise suppress the setup offer for every
+// non-repo folder under the home directory. Do not re-sync the two walks.
+function kaizenAbove() {
+  let dir = process.cwd();
+  for (;;) {
+    if (dir === home) return false;
+    if (existsSync(join(dir, ".kaizen"))) return true;
+    if (existsSync(join(dir, ".git"))) return false;
+    const up = dirname(dir);
+    if (up === dir) return false;
+    dir = up;
+  }
+}
+
+if (inProject && !kaizenAbove()) {
   const now = interactive
     ? await select(`Set up ${basename(process.cwd())}/ for kaizen now`, [
-        { label: "Yes", hint: "writes .kaizen/ and a CLAUDE.md line so it runs by default", value: true },
+        // "Not now" leads: the offer now appears in any folder outside home, so the
+        // safe answer is the one under the cursor.
         { label: "Not now", hint: "the first /kaizen run will do it", value: false },
+        { label: "Yes", hint: "writes .kaizen/ and a CLAUDE.md line so it runs by default", value: true },
       ])
     : false;
-  if (now) initRepo();
+  if (now) initProject();
 } else if (existsSync(kaizenDir)) {
   step(`${basename(process.cwd())}/.kaizen already set up`);
 }
 
-function initRepo() {
+function initProject() {
   mkdirSync(kaizenDir, { recursive: true });
   for (const f of readdirSync(join(repo, "skills/kaizen")).filter((f) => f.startsWith("spec"))) {
     copyFileSync(join(repo, "skills/kaizen", f), join(kaizenDir, f));
@@ -413,13 +434,18 @@ function initRepo() {
   copyFileSync(join(repo, "skills/kaizen/config.default.yml"), join(kaizenDir, "config.yml"));
 
   // Run state is local; the workflow itself is shared, so those files stay tracked.
-  const rules = ".kaizen/*\n!.kaizen/spec*.md\n!.kaizen/config.yml\n";
-  const gi = join(process.cwd(), ".gitignore");
-  const current = existsSync(gi) ? readFileSync(gi, "utf8") : "";
-  if (!current.includes(".kaizen/*")) {
-    appendFileSync(gi, (current && !current.endsWith("\n") ? "\n" : "") + "\n# kaizen run state\n" + rules);
+  // Nothing to ignore where there is no git, so a plain folder gets no .gitignore.
+  let ignored = false;
+  if (existsSync(join(process.cwd(), ".git"))) {
+    const rules = ".kaizen/*\n!.kaizen/spec*.md\n!.kaizen/config.yml\n";
+    const gi = join(process.cwd(), ".gitignore");
+    const current = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    if (!current.includes(".kaizen/*")) {
+      appendFileSync(gi, (current && !current.endsWith("\n") ? "\n" : "") + "\n# kaizen run state\n" + rules);
+      ignored = true;
+    }
   }
-  step("wrote .kaizen/ and the gitignore entry");
+  step(ignored ? "wrote .kaizen/ and the gitignore entry" : "wrote .kaizen/");
   writePointer();
 }
 
@@ -427,7 +453,7 @@ function initRepo() {
 // ("add a discount cap") does not reach kaizen unless the project says it should.
 // One line in the agent instructions is what makes it the default here.
 function writePointer() {
-  const block = `\n## Kaizen workflow\n\nNon-trivial work in this repository follows the staged workflow in\n\`.kaizen/spec.md\`: plan, human approval, build, independent review, bounded fix\nloop. Invoke the \`kaizen\` skill for it — do not carry the stages out inline.\n\nNon-trivial means work worth a plan: a change across more than one file, anything\nwith a migration or a rollback, or a document someone else will act on. Answering a\nquestion, reading code, or a one-line fix is not, and should not start a run.\n\nRun state lives in \`.kaizen/runs/<id>/\`. Read \`state.json\` first and continue from\nthe stage it names; never advance a run whose \`awaiting\` field is non-null without a\nrecorded human decision.\n`;
+  const block = `\n## Kaizen workflow\n\nNon-trivial work in this repository follows the staged workflow in\n\`.kaizen/spec.md\`: plan, human approval, build, independent review, bounded fix\nloop. Invoke the \`kaizen\` skill for it — do not carry the stages out inline.\n\nA run costs several times what the same change costs in one session, so spend it\nwhere being wrong is expensive: money, data loss, a migration or anything else hard\nto undo, work a customer sees, or a part of the system nobody has read in a year.\n\nWork where being wrong is cheap and obvious does not start a run. Answering a\nquestion, reading code, a one-line fix, a rename the compiler checks — do those\ndirectly. When it is genuinely unclear, ask rather than assuming the expensive path.\n\nRun state lives in \`.kaizen/runs/<id>/\`. Read \`state.json\` first and continue from\nthe stage it names; never advance a run whose \`awaiting\` field is non-null without a\nrecorded human decision.\n`;
 
   for (const name of ["CLAUDE.md", "AGENTS.md"]) {
     const f = join(process.cwd(), name);

package/cli/settings.ts

@@ -8,6 +8,7 @@ type Setting = { key: string; values: string[]; help: string };
 
 const SETTINGS: Setting[] = [
   { key: "mode", values: ["approve", "auto", "plan-only", "review-only"], help: "Where a run stops" },
+  { key: "runner", values: ["full", "lite"], help: "full: every stage its own cold agent. lite: this session runs them all, cheaper, reviewer has seen the work" },
   { key: "build.executor", values: ["subagent", "inline", "ask"], help: "Who carries out the approved plan" },
   { key: "approvals.plan", values: ["true", "false"], help: "Stop and show the plan before anything is built" },
   { key: "approvals.review", values: ["true", "false"], help: "Stop after the review, before the run is done" },
@@ -86,8 +87,13 @@ export async function settings(repoRoot: string, standalone = true) {
           const now = read(text, s.key) ?? s.values[0]!;
           const at = s.values.indexOf(now);
           const next = s.values[((at < 0 ? 0 : at) + step + s.values.length) % s.values.length]!;
-          writeFileSync(file, write(text, s.key, next));
-          saved = c.green(`saved ${s.key} = ${next || '""'}`);
+          const updated = write(text, s.key, next, readFileSync(join(repoRoot, "skills/kaizen/config.default.yml"), "utf8"));
+          writeFileSync(file, updated);
+          // Only claim a save that happened. Reporting one that did not is worse
+          // than failing loudly: the setting reads back unchanged and nobody knows why.
+          saved = read(updated, s.key) === next
+            ? c.green(`saved ${s.key} = ${next || '""'}`)
+            : `\x1b[33mcould not write ${s.key}\x1b[0m`;
           if (!rest.startsWith("\r")) i += 2;
         } else if (rest.startsWith("k")) active = (active - 1 + SETTINGS.length) % SETTINGS.length;
         else if (rest.startsWith("j")) active = (active + 1) % SETTINGS.length;
@@ -145,12 +151,54 @@ function read(text: string, key: string) {
   return v.replace(/^["']|["']$/g, "");
 }
 
-function write(text: string, key: string, value: string) {
-  const { lines, index, indent } = lineOf(text, key);
-  if (index < 0) return text;
+function write(text: string, key: string, value: string, defaults: string) {
   const name = key.split(".").pop()!;
   const shown = value === "" ? '""' : value;
-  lines[index] = `${" ".repeat(indent)}${name}: ${shown}`;
+  const { lines, index, indent } = lineOf(text, key);
+
+  if (index >= 0) {
+    lines[index] = `${" ".repeat(indent)}${name}: ${shown}`;
+    return lines.join("\n");
+  }
+
+  // A config written before this key existed does not have a line to change. Take
+  // the key from the defaults, comment and all, rather than silently doing nothing
+  // and reporting a save: an older config is the normal case for anyone who has had
+  // kaizen installed for a while.
+  return insert(text, key, shown, defaults);
+}
+
+function insert(text: string, key: string, shown: string, defaults: string) {
+  const parts = key.split(".");
+  const name = parts[parts.length - 1]!;
+  const indent = (parts.length - 1) * 2;
+  const src = defaults.split("\n");
+  const { index: at } = lineOf(defaults, key);
+
+  // The comment block above the key in the defaults explains it; carry it across.
+  const block: string[] = [];
+  if (at >= 0) {
+    let i = at - 1;
+    while (i >= 0 && /^\s*#/.test(src[i]!)) { block.unshift(src[i]!); i--; }
+  }
+  block.push(`${" ".repeat(indent)}${name}: ${shown}`);
+
+  const lines = text.split("\n");
+  if (parts.length === 1) {
+    while (lines.length && !lines[lines.length - 1]!.trim()) lines.pop();
+    return [...lines, "", ...block, ""].join("\n");
+  }
+
+  // Nested: put it under its parent if the parent is there, else write the parent too.
+  const parent = parts.slice(0, -1).join(".");
+  const { index: pi } = lineOf(text, parent);
+  if (pi < 0) {
+    while (lines.length && !lines[lines.length - 1]!.trim()) lines.pop();
+    return [...lines, "", `${parts[0]}:`, ...block, ""].join("\n");
+  }
+  let end = pi + 1;
+  while (end < lines.length && (/^\s+\S/.test(lines[end]!) || !lines[end]!.trim())) end++;
+  lines.splice(end, 0, ...block);
   return lines.join("\n");
 }
 

package/commands/kaizen-full.md

@@ -0,0 +1,5 @@
+---
+description: Run kaizen with every stage as its own cold agent — the independent review
+---
+
+Invoke the `kaizen` skill with argument `full $ARGUMENTS`.

package/commands/kaizen-init.md

@@ -1,5 +1,5 @@
 ---
-description: Install .kaizen/ (spec, config, gitignore entry) into the current repository
+description: Set up this project folder for kaizen (spec, config, and a gitignore entry when it is a git repo)
 ---
 
 Invoke the `kaizen` skill with argument `init`.

package/commands/kaizen-lite.md

@@ -0,0 +1,5 @@
+---
+description: Run kaizen with every stage in this session — cheaper, and the reviewer has seen the work
+---
+
+Invoke the `kaizen` skill with argument `lite $ARGUMENTS`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Staged workflow for AI agents \u2014 code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/SKILL.md

@@ -39,6 +39,8 @@ Porting the workflow to Codex or Antigravity is covered in [`adapters.md`](adapt
 | `/kaizen <request>` | Start a new run in the configured mode (default: `approve`) |
 | `/kaizen plan <request>` | Start a run and stop after the plan (`plan-only`) |
 | `/kaizen auto <request>` | Start a run in `auto` mode: every stage back to back, no approval stops |
+| `/kaizen lite <request>` | Run every stage in this session — cheap, and the reviewer has seen the work |
+| `/kaizen full <request>` | Dispatch every stage as its own agent — the reviewer starts cold |
 | `/kaizen run` | Resume the current run and execute the approved plan |
 | `/kaizen review [target]` | Review-only: audit existing code, no plan, no implementation (`review-only`) |
 | `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus the open backlog count |
@@ -47,7 +49,7 @@ Porting the workflow to Codex or Antigravity is covered in [`adapters.md`](adapt
 | `/kaizen reject <reason>` | Reject it; the reason is fed back to the stage that produced it |
 | `/kaizen abort` | Mark the current run abandoned |
 | `/kaizen config` | Show this project's settings and change them, one picker per setting |
-| `/kaizen init` | Install `.kaizen/` with the `spec*.md` files, config, and the gitignore entry into the current repository |
+| `/kaizen init` | Set up this project folder: `.kaizen/` with the `spec*.md` files, config, and — in a git repo — the gitignore entry |
 | `/kaizen install` | Install the workflow itself globally or per-project (see below) |
 
 If the user typed `/kaizen` with no argument and a run is in progress, treat it as
@@ -55,12 +57,14 @@ If the user typed `/kaizen` with no argument and a run is in progress, treat it
 
 ## Before doing anything
 
-1. Locate the state directory: `.kaizen/` in the repository root, else `~/.kaizen/`
-   keyed by working directory. If neither exists and the user is starting work, run
-   `/kaizen init` first: it creates `.kaizen/` with a copy of the `spec*.md` files, a config, and
-   the gitignore entry (see [`adapters.md`](adapters.md)).
+1. Locate the state directory: `.kaizen/` in the project folder's root, else
+   `~/.kaizen/` keyed by working directory. If neither exists and the user is starting
+   work, run `/kaizen init` first: it creates `.kaizen/` with a copy of the `spec*.md`
+   files, a config, and — where the folder is a git repository — the gitignore entry
+   (see [`adapters.md`](adapters.md)).
 2. Read `.kaizen/config.yml`, falling back to `config.default.yml` in this skill for
-   any key it does not set.
+   any key it does not set. `runner` decides whether this run dispatches subagents at
+   all; read it before the first stage, not when you reach one.
 3. Read `.kaizen/runs/<current>/state.json` if a run is active. Never assume the
    stage from conversation memory — the run may have been advanced by another tool
    or another session.
@@ -78,6 +82,7 @@ whichever the user picks.
 | Setting | Values | What it decides |
 |---|---|---|
 | `mode` | `approve`, `auto`, `plan-only`, `review-only` | Where a run stops |
+| `runner` | `full`, `lite` | Whether each stage is its own cold agent, or this session runs them all |
 | `build.executor` | `subagent`, `inline`, `ask` | Who carries out the approved plan |
 | `approvals.plan` | `true`, `false` | Stop and show the plan before anything is built |
 | `approvals.review` | `true`, `false` | Stop after the review, before the run is called done |
@@ -109,6 +114,31 @@ picker with thirty options.
 someone who would rather see the whole file at once. Mention it when the user is
 changing several at a time.
 
+## What is worth a run
+
+A run costs several times what the same change costs in one session, because every
+stage starts cold and the reviewer is deliberately kept ignorant of how the work was
+done. That price buys one thing: an agent with nothing to defend, which is the only
+kind that finds the bug in the fix.
+
+Spend it where being wrong is expensive — money, data loss, a migration, anything a
+customer sees, anything hard to undo, anything touching a part of the system nobody
+has read in a year. Do not spend it on work where being wrong is cheap and obvious.
+A tool that charges the same for a typo and a payroll change gets turned off for both.
+
+**Small changes take the short path.** Where the approved plan touches roughly two
+files or fifty lines, run the stages in this session (`runner: lite`, below)
+rather than dispatching them, then stop after the review: report the findings and let
+the user choose, rather than entering the fix loop. The loop
+exists because a fix to something intricate can be worse than the defect — it is not
+worth two more stages to confirm a one-line message now reads correctly. A finding at
+`high` or above pulls the run back onto the full path whatever its size, since that
+severity is the loop's whole reason for existing.
+
+This is a judgement, not a threshold to enforce: fifty lines that change how money is
+rounded are not a small change. Say which path you took and why, in one line, when the
+run starts.
+
 ## Modes
 
 Set by `mode` in config, overridable per invocation.
@@ -214,6 +244,37 @@ Each line is the run id, its stage, and what it is awaiting. Grouping is derived
 `state.json` at read time, never from the directory name — run directories are flat and
 are never renamed or moved, so a path written into another file cannot break.
 
+## Who runs the stages
+
+`runner` decides, and it is the difference between a run costing about what the work
+would cost in one session and several times that. Set it for the project with
+`/kaizen config` or `kaizen settings`; override it for one run with `/kaizen lite
+<request>` or `/kaizen full <request>`, which does not change the project's setting.
+
+- **`full`** (default) — each stage is dispatched as its own agent, started cold.
+  The reviewer has never seen how the work was done, so it has nothing to defend.
+  That is the entire reason its findings are worth reading, and it is what catches the
+  bug in a fix rather than the bug in the plan.
+- **`lite`** — this session runs every stage itself, in order, as
+  [`adapters.md`](adapters.md) already describes for tools that have no subagents.
+  Read only the stage's declared inputs, write its artifact before starting the next,
+  and when reviewing, judge the work on its own terms rather than defending the
+  reasoning you used producing it.
+
+Everything else holds in both: the plan, the approval stop, the numbered gate answered
+with evidence, numbered findings, the files, and a run another tool can pick up.
+
+**Be honest about what `lite` costs you.** Instructing an agent to be impartial
+about something it just did is weaker than an agent that cannot be partial, because it
+never saw it. A same-session review reliably finds what is visible in the diff. It is
+much less likely to find the defect that requires disbelieving the reasoning that
+produced it — and a fix that is worse than the finding it closes is exactly that shape.
+
+So: `lite` where being wrong is cheap and obvious, which is also where the short path
+above applies. `full` where being wrong is expensive. When a run is going to
+touch money, a migration, or anything hard to undo, say which runner it used at the
+final report, so nobody reads a same-session review as an independent one.
+
 ## Running a stage
 
 **If the tool you are running in has no subagents** — Codex, and anything else that
@@ -223,8 +284,16 @@ only its declared inputs, write its artifact before moving on, and when reviewin
 judge the work on its own terms rather than defending the reasoning you used writing
 it. Everything else in this file holds unchanged.
 
-Each stage runs as a subagent via the Agent tool, with the agent type named below.
-Pass it the run directory path and let it read its own inputs from there — do not
+**Check `runner` first.**
+
+- `runner: lite` — do not call the Agent tool. You run plan, build and review
+  yourself, in that order, reading only each stage's declared inputs and writing its
+  artifact before starting the next. The stage table below still applies; you are the
+  agent for every row.
+- `runner: full` — dispatch each stage as its own subagent, as follows.
+
+Under `full`, each stage runs as a subagent via the Agent tool, with the agent type
+named below. Pass it the run directory path and let it read its own inputs from there — do not
 paste plans or diffs into the prompt, since the file is the shared source of truth
 across tools. Name its spec files in the prompt: core `spec.md` plus its own stage
 file, never the whole set.
@@ -244,6 +313,13 @@ conversation the work happened in.
 After a subagent returns, update `state.json` yourself in the main thread. Subagents
 report; the main thread owns the state machine.
 
+**Name files, do not narrate them.** The prompt says which paths to read, which
+decisions bind the stage, and what to report back. It does not summarize those files:
+the subagent is about to read them, and a summary is the same content paid for twice —
+once in your prompt and once when it opens the file. Asking for analysis the stage's
+own contract does not require costs a stage's worth of tokens for an opinion nobody
+will act on.
+
 **Scope precisely, don't scope narrow.** Each subagent starts cold — no context from
 you carries over except what the prompt names. List exactly the files this stage's
 task actually touches; don't default to "read everything" for safety. But cutting a
@@ -280,12 +356,15 @@ shown automatically.
       state.json
 ```
 
-`state.json` is the resume point:
+`state.json` is the resume point, and records the runner the run started with, so a
+run picked up later keeps the shape it was reviewed under rather than silently
+changing because a setting moved:
 
 ```json
 {
   "id": "2026-09-02-add-oauth",
   "mode": "approve",
+  "runner": "full",
   "stage": "review",
   "awaiting": "approvals.review",
   "iteration": 1,
@@ -293,9 +372,11 @@ shown automatically.
 }
 ```
 
-`init` adds a gitignore entry that ignores run state but keeps the workflow: it
-ignores `.kaizen/*` and un-ignores `.kaizen/spec*.md` and `.kaizen/config.yml`, which
-are meant to be committed (see [`adapters.md`](adapters.md)).
+In a git repository, `init` also adds a gitignore entry that ignores run state but
+keeps the workflow: it ignores `.kaizen/*` and un-ignores `.kaizen/spec*.md` and
+`.kaizen/config.yml`, which are meant to be committed (see
+[`adapters.md`](adapters.md)). A project folder that is not a repository gets no
+gitignore.
 
 ## Install
 

package/skills/kaizen/adapters.md

@@ -64,8 +64,9 @@ completes. A stale `state.json` is the one way this breaks.
 
 ## Installing the adapter files
 
-`/kaizen init` writes `.kaizen/` with the `spec*.md` files, `config.yml`, and the gitignore
-entry. `/kaizen install` additionally offers to append the `AGENTS.md` block above.
+`/kaizen init` writes `.kaizen/` with the `spec*.md` files and `config.yml` into the
+project folder, plus the gitignore entry when that folder is a git repository.
+`/kaizen install` additionally offers to append the `AGENTS.md` block above.
 `.kaizen/spec*.md` and `.kaizen/config.yml` should be committed even though run state
 is ignored — the workflow is shared, the run data is not:
 

package/skills/kaizen/config.default.yml

@@ -14,6 +14,19 @@ approvals:
   # Confirm every individual file edit. Maximum control, slowest.
   each_file: false
 
+# How much machinery a run uses.
+#   full - each stage is its own agent, started cold. The reviewer never sees how the
+#          work was done, which is the only reason its findings are worth reading.
+#          Costs several times what the same change costs in one session.
+#   lite - the session you are talking to runs every stage itself, in order, keeping
+#          each stage to its own declared inputs. Roughly the cost of doing the work
+#          by hand, and you watch it happen. The reviewer has seen the work, so
+#          expect it to miss what it just did.
+# Everything else is the same either way: the plan, the approval, the gate, the
+# findings, the files, and resuming a run in another tool.
+# Override for one run with `/kaizen lite <request>` or `/kaizen full <request>`.
+runner: full
+
 build:
   # Who carries out the approved plan.
   #   subagent - dispatch the builder as its own agent. The main thread keeps its
@@ -55,12 +68,27 @@ review:
   # Additional checks per track, chosen by what the run actually is. The planner may
   # name a track not listed here; the reviewer then derives its checks from the
   # track's "what would make it wrong".
+  # Each check below is one question the reviewer asks; the line beside it says which.
   track_checks:
+    # security - no new way in, no secret or user data exposed
+    # reuse_simplification - nothing rebuilt that the codebase already had
+    # test_coverage - the changed behaviour has a check that fails when it breaks
     software: [security, reuse_simplification, test_coverage]
     # blast_radius and regression are universal — see spec-review.md — not listed here.
+    # completeness - every part the piece promises is actually present
+    # claim_accuracy - every checkable claim traced to a source
+    # reader_usability - its intended reader can act on it without asking
     writing: [completeness, claim_accuracy, reader_usability]
+    # audience_fit - written for the people who will actually read it
+    # voice_consistency - reads as the same voice as the surrounding material
     communication: [claim_accuracy, audience_fit, voice_consistency]
+    # prerequisites - everything needed before step one is stated
+    # rollback - a way back exists for every step that changes something
+    # executability - someone else can run it start to finish unaided
     operations: [prerequisites, rollback, executability]
+    # evidence_support - the conclusion follows from evidence shown, not asserted
+    # selection_bias - the evidence was not picked to fit the answer
+    # alternatives - the readings that were rejected are named and why
     research: [evidence_support, selection_bias, alternatives]
   # Let the reviewer append durable lessons to .kaizen/memory.md.
   write_memory: true
@@ -90,6 +118,8 @@ state:
 
 git:
   # Never commit, push, or open a PR unless the user explicitly asks.
+  # Ignored when the project is not a git repository.
   auto_commit: false
   # Create a branch before the implement stage when on the default branch.
+  # Ignored when the project is not a git repository.
   branch_before_implement: true

package/skills/kaizen/spec-build.md

@@ -35,6 +35,9 @@ Rules:
   abstraction, a new file, a new section — is allowed, and costs one written line
   saying what it serves. The line is the price of the technique, not a request for
   permission. No line means the reviewer records a finding.
+- The `git.*` settings apply only where the work sits in a git repository. In a plain
+  folder there is no branch to make and no commit to skip, and that absence is not a
+  finding.
 
 **Baseline first, in any track with an existing suite of checks.** Before changing
 anything, run whatever already proves the existing material correct — the test suite,
@@ -88,3 +91,14 @@ reports nothing at or above the threshold, or `max_iterations` is reached.
 A finding the loop could not close is escalated to the user with the reviewer's
 description intact — never quietly downgraded to make the run look clean.
 
+**An iteration reads the finding, the work, and the gate.** Not the plan. Fixing a
+named defect needs the reviewer's line, the diff so far, and the gate the result must
+still pass; it does not need the framing, the alternatives rejected, or the out-of-scope
+list, all of which were settled before the finding existed. Read `01-plan.md` only when
+a finding turns on what was approved — a scope question, or a fix that would take the
+work outside it.
+
+Fix what the finding names and stop. A second defect noticed while fixing the first is
+a note in the iteration file, not a second fix: it has not been reviewed, and the
+recheck is scoped to what the iteration claims to have changed.
+

package/skills/kaizen/spec-main.md

@@ -82,7 +82,9 @@ subagents at all.
 Controlled by `approvals.review`, skipped in `auto`.
 
 Report: what was built, verification results, findings fixed, findings still open,
-and anything the builder noted as out of scope. Then stop. Committing, pushing, or
+and anything the builder noted as out of scope. Where the run used `runner: lite`, say
+so in that report — the reviewer saw the work, and nobody should read a same-session
+review as an independent one because the output looked the same. Then stop. Committing, pushing, or
 opening a pull request happens only if the user asks.
 
 **Open findings are offered by number.** List them with the reviewer's numbering

package/skills/kaizen/spec-plan.md

@@ -76,6 +76,19 @@ The planner reads code but writes none. Its plan must contain:
 The plan is a proposal, not a decision. It never edits files, runs migrations, or
 installs packages.
 
+**Length is a cost the whole run pays.** Every later stage reads this file, and the
+fix loop reads it again per iteration, so a line written once is read five or six
+times. Sections 3 to 6 — the material to reuse, the file manifest, the steps, the
+verification — earn their length: they are what stop every later stage searching the
+material again, and cutting them costs more than it saves. Sections 0, 1, 7 and 9 are
+read once by a human at the approval and should be as short as they can be and still
+be correct: a paragraph of framing, a paragraph of goal, the risks that are real, the
+questions that are open. An alternative rejected gets a line saying what and why, not
+a case against it.
+
+A plan whose framing is longer than its steps is a plan that spent the run's budget
+explaining itself.
+
 ---
 
 ## Plan approval

package/skills/kaizen/spec-review.md

@@ -87,3 +87,20 @@ reports nothing at or above the threshold, or `max_iterations` is reached.
 A finding the loop could not close is escalated to the user with the reviewer's
 description intact — never quietly downgraded to make the run look clean.
 
+**A recheck is not a second review.** Re-answer the findings it was meant to close,
+the gate items the change could plausibly touch, and the regression check. Nothing
+else. State which items were skipped and why, in one line, so the reader can disagree
+with the judgement — a skipped item is a claim that the change could not have reached
+it, and that claim is checkable.
+
+Answering all of them again is not thoroughness, it is the same evidence gathered
+twice. A fix that touched one line of a message string cannot have broken an item
+about which directories the installer writes to, and re-running that item's live
+setup to prove it costs more than the fix did. Where a change genuinely could have
+reached everything — a rename across the run's files, a shared helper — say so and
+re-answer everything.
+
+The exception is the regression check, which runs every iteration whatever the fix
+touched. It is cheap, and it is the one that catches a fix breaking something nobody
+thought to connect it to.
+

package/skills/kaizen/spec.md

@@ -101,9 +101,15 @@ sentence and either nods or says "no, this is a blog post". They are never asked
 categorize their own request up front.
 
 Write into `00-request.md`: the verbatim request, the deliverable, what done means,
-and what wrong means. Record in `state.json`: `id`, `mode`, `track`,
+and what wrong means. Record in `state.json`: `id`, `mode`, `runner`, `track`,
 `stage: "plan"`, `awaiting: null`.
 
+`runner` is read from config at intake and written down here, because it decides
+whether the stages that follow are separate agents or this one. A run resumed later
+keeps the runner it started with: a review done in the same session as the work is a
+different thing from an independent one, and which happened should not depend on what
+the config said the day someone came back to it.
+
 If the request remains ambiguous enough that a plan would be guesswork, ask now. One
 round of questions here is cheaper than a rejected plan.
 

package/skills/kaizen-help/SKILL.md

@@ -23,6 +23,8 @@ anything.
 | `/kaizen <request>` | Start a new run in the configured mode (default: `approve`) |
 | `/kaizen plan <request>` | Start a run and stop after the plan (`plan-only`) |
 | `/kaizen auto <request>` | Start a run in `auto` mode: every stage back to back, no approval stops |
+| `/kaizen lite <request>` | Run the stages in this session — cheap, reviewer has seen the work |
+| `/kaizen full <request>` | Dispatch each stage as its own cold agent |
 | `/kaizen run` | Resume the current run and execute the approved plan |
 | `/kaizen review [target]` | Review-only: audit existing code, no plan, no implementation |
 | `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus open backlog count |
@@ -31,7 +33,7 @@ anything.
 | `/kaizen reject <reason>` | Reject it; the reason decides revise (back to planner) vs kill (abandon) |
 | `/kaizen abort` | Mark the current run abandoned |
 | `/kaizen config` | Show this project's settings and change them, one picker per setting |
-| `/kaizen init` | Install `.kaizen/` with `spec.md`, config, and the gitignore entry into the current repository |
+| `/kaizen init` | Set up this project folder: `.kaizen/` with `spec.md`, config, and — in a git repo — the gitignore entry |
 | `/kaizen install` | Install the workflow itself globally or per-project |
 
 `/kaizen` with no argument: `status` if a run is in progress, else ask what to build.
@@ -74,6 +76,7 @@ Each iteration is written to `runs/<id>/05-iterations/`.
 | Key | Default | Meaning |
 |---|---|---|
 | `mode` | `approve` | Default run mode |
+| `runner` | `full` | `full`: each stage a cold subagent. `lite`: this session runs every stage |
 | `approvals.plan` | `true` | Stop after the plan |
 | `approvals.review` | `false` | Stop after the review |
 | `approvals.each_file` | `false` | Confirm every file edit |