kaizen-agent 1.9.3 → 1.10.0

package/README.md

@@ -301,6 +301,7 @@ and every `kaizen settings` knob, same rows, same `config.yml`. `--port N` picks
 serves, the board opens on every project, or on the one picked last time in that browser; `?all=0` in the URL narrows it to the one it was started in. `--daemon` starts the server
 detached so it outlives the terminal (pid kept in `~/.kaizen/web.pid`); `--stop` ends it. `kaizen web --shortcut` adds a launcher
 the OS can find — Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows. Each one starts the board in the background (`--daemon`) and opens it; `kaizen web --stop` ends it.
+On Windows `kaizen web` starts in the background unless `--foreground` is given; `kaizen web --stop` ends it.
 
 **A notebook beside the board.** The note icon in the board's header opens
 `/notebook`: markdown notes for the project, kept as plain files in `.kaizen/notes/`
@@ -327,10 +328,14 @@ slower CPU path); a browser without a microphone API or WebAssembly shows no mic
 
 Requests that already live somewhere else — a team's Google Sheet, a Doc, a shared
 note — do not have to be retyped. The link icon beside the gear opens **Request
-sources**: paste a link, and kaizen reads it and adds every request it has not seen
-before to Ideas, each with a note saying where it came from. In a sheet, a column headed
-`Request`, `Idea`, `Title`, `Task`, `PBI`, `Summary` or `Name` is the request and the
-other cells become its notes; without such a header the request is one column for the whole sheet, the one holding the most text. A row whose `Status` column says `Done`,
+sources**: paste a link, and kaizen reads it at once and adds every request it has not
+seen before to Ideas, each with a note saying where it came from and a *gathered* chip;
+the panel says what came back, or why the link could not be read. In a sheet, the header
+is looked for in the first five rows that hold anything, and a column headed `Request`,
+`Idea`, `Title`, `Task`, `PBI`, `Summary`, `Name`, `Detail`, `Details`, `Description`,
+`Deskripsi`, `Feedback`, `Issue`, `Permintaan` or `Judul` is the request; the other
+cells become its notes. Without such
+a header the request is one column for the whole sheet, the one holding the most text. A row whose `Status` column says `Done`,
 `Finish` or `Finished` is left out, and gathered later if its status changes. A doc or
 a plain-text link gives one idea per line.
 
@@ -657,14 +662,14 @@ with a comment on each key, if you would rather edit the file.
 | `--yes` | Take every default, ask nothing |
 | `--verbose` | List every link instead of a one-line summary |
 | `upgrade` | Pull, relink, and clear the installer cache. No prompts. |
-| `uninstall` | Remove the links, the clone, and the launcher. Asks whether to keep your runs and settings. |
+| `uninstall` | Remove the links, the clone, and the launcher. Asks whether to keep your runs and settings. The clone goes only when it is `~/kaizen`, cloned from kaizen's repository, with no local changes; any other `KAIZEN_HOME` is kept and named. |
 | `uninstall --purge` | The same, and delete `~/.kaizen` and this project's `.kaizen/` too. |
 | `settings` | Open the settings browser for the nearest `.kaizen/`. Also `config`. |
 
 Uninstalling works the same on Linux, macOS and Windows — `kaizen uninstall`, or
 `bunx kaizen-agent uninstall` when the command itself is already gone. It offers three
 answers — keep your runs and settings, remove everything, or cancel — and takes the
-first without asking when the output is not a terminal. It lists what it removed; the `## Kaizen workflow` line in each project's `CLAUDE.md` is left for
+first without asking when the output is not a terminal. It lists what it removed and what it kept; the `## Kaizen workflow` line in each project's `CLAUDE.md` is left for
 you to delete, since you may have edited around it.
 
 A global install also writes `~/.local/bin/kaizen` (`kaizen.cmd` in bun's bin

package/agents/kaizen-builder.md

@@ -68,7 +68,10 @@ change — do not refactor around it. Write what you changed to
 - **Verification** — each check carried out, with its actual result. Quote failures.
 - **Not done** — steps skipped, out-of-scope observations, known gaps.
 - **Preview** — how to see the result: commands to run it locally and the URL for an
-  app; the path to open, or the result itself, for anything else. The board shows it.
+  app; the path to open, or the result itself, for anything else. Then `### How to test`:
+  numbered steps from the plan's gate, each an action and what the person should see,
+  plus any test command with its expected result. `###` subheads only — the board ends
+  the section at the next `##`. The board shows it.
 - **Commit** — in a git repository, the commit message for the work: a subject
   `<type>(<scope>): <what changed>` (type one of `feat`, `fix`, `refactor`, `perf`,
   `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`; at most 72 characters)

package/cli/board.test.ts

@@ -53,3 +53,51 @@ test("undraft removes by prefix and leaves the rest", () => {
   undraft("f:");
   expect(Object.keys(ss).sort()).toEqual(["kz-d:n:x", "kz-form"]);
 });
+
+// A building run's progress list, lifted the same way.
+const pat = html.indexOf("function progress(");
+const progress = new Function(`${esc}\n${html.slice(pat, html.indexOf("\n\n", pat))}\nreturn progress`)() as (src: string, prev?: string[]) => string;
+
+test("progress: each item marked done, working on or to do, with the count", () => {
+  const out = progress("# Progress\n- done: one\n- doing: two <b>x</b>\n- todo: `three`\n- open: not an item\n");
+  expect(out).toContain("1 of 3 done");
+  expect(out).toContain("width:33%");
+  expect(out.match(/<li class="p-(\w+)/g)).toEqual(['<li class="p-done', '<li class="p-doing', '<li class="p-todo']);
+  expect(out).toContain("two &lt;b&gt;x&lt;/b&gt;");
+  expect(out).toContain("<code>three</code>");
+  expect(out).not.toContain("chg");
+});
+
+test("progress: only an item whose status moved animates", () => {
+  const out = progress("- done: one\n- doing: two\n- todo: three\n", ["done", "todo", "todo"]);
+  expect(out.match(/<li class="[^"]*"/g)).toEqual(['<li class="p-done"', '<li class="p-doing chg"', '<li class="p-todo"']);
+});
+
+test("progress: a file with no items draws nothing", () => {
+  expect(progress("# Progress\n\nnothing yet\n")).toBe("");
+});
+
+// A plan's open questions, lifted the same way: the function ends at the first line not indented.
+const pq = html.indexOf("function planQuestions(");
+type Q = { q: string; multi: boolean; options: { text: string; label: string; rec: boolean }[] };
+const planQuestions = new Function(`${html.slice(pq).split(/\n(?! )/)[0]}\nreturn planQuestions`)() as (src: string) => Q[] | null;
+
+test("planQuestions: Q lines with options, recommended and multi-select read", () => {
+  const qs = planQuestions(`# Plan\n## 9. Open questions\n\nQ: Which improvements to build? (multi-select)\n   - Own project in row (recommended) — fixes Move; XS\n   - Gather on add — instant result\nQ: Where the progress shows\n   - Top of the Backlog tab (recommended): what you asked for.\n   - Its own tab: adds an eighth tab\n\n- Note: not an option\n## 10. Out of scope suggestions\n- not a question\n`);
+  expect(qs!.map((q) => [q.q, q.multi])).toEqual([["Which improvements to build? (multi-select)", true], ["Where the progress shows", false]]);
+  expect(qs[0]!.options.map((o) => [o.label, o.rec])).toEqual([["Own project in row", true], ["Gather on add", false]]);
+  expect(qs[1]!.options.map((o) => o.label)).toEqual(["Top of the Backlog tab", "Its own tab"]);
+});
+
+test("planQuestions: fenced and numbered questions, sub-headings kept, none and missing read as nothing", () => {
+  const qs = planQuestions("## Open questions\n### Board\n```\nQ1: How should it run?\n   - Detach (recommended): prompt comes back\n   - Foreground: as is\n```\n");
+  expect(qs!.map((q) => [q.q, q.options.length])).toEqual([["How should it run?", 2]]);
+  expect(planQuestions("## 9. Open questions\n\nNone.\n")).toEqual([]);
+  expect(planQuestions("## 9. Open questions\n- Building → Backlog taken literally.\n")).toBeNull();
+  expect(planQuestions("# Plan\nno section\n")).toEqual([]);
+});
+
+test("planQuestions: a bullet after a blank line is not one more option", () => {
+  const qs = planQuestions("## Open questions\nQ: One?\n   - A (recommended)\n   - B\n\n- Note: aside\n")!;
+  expect(qs[0]!.options.map((o) => o.label)).toEqual(["A", "B"]);
+});

package/cli/install.test.ts

@@ -0,0 +1,85 @@
+// `kaizen uninstall` against throwaway folders only. Every path it may delete comes
+// from the env built here (HOME, KAIZEN_HOME, TMPDIR all scratch), never from the
+// real environment: on 2026-10-01 an uninstall pointed at a checkout deleted it.
+// Skipped on Windows: there uninstall also walks every drive (searchRoots) and
+// strips kaizen links from real projects, whatever HOME says.
+import { test, expect } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync, symlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+
+const script = join(dirname(import.meta.path), "install.ts");
+const it = test.skipIf(process.platform === "win32");
+const REPO = "https://github.com/hfadhlullah/kaizen.git";
+
+// `custom` sets KAIZEN_HOME to a folder outside HOME; otherwise it is unset and the
+// install is the scratch home's own ~/kaizen.
+const uninstall = (make: (k: string) => void, custom = false) => {
+  const root = mkdtempSync(join(tmpdir(), "kz-uninstall-"));
+  const home = join(root, "home"), k = custom ? join(root, "kaizen") : join(home, "kaizen");
+  mkdirSync(home);
+  make(k);
+  const env: Record<string, string> = { PATH: process.env.PATH ?? "", HOME: home, USERPROFILE: home, TMPDIR: root };
+  if (custom) env.KAIZEN_HOME = k;
+  const p = Bun.spawnSync([process.execPath, script, "uninstall", "--yes"], { cwd: home, env });
+  const left = existsSync(k), out = p.stdout.toString();
+  rmSync(root, { recursive: true, force: true });
+  if (p.exitCode !== 0) throw new Error(p.stderr.toString());
+  return { left, out };
+};
+const kaizenFiles = (k: string) => { mkdirSync(join(k, "cli"), { recursive: true }); writeFileSync(join(k, "cli", "install.ts"), ""); };
+// A clone without the network: an empty repository whose origin is `url`.
+const clone = (url: string, dirty = false, more?: (k: string) => void) => (k: string) => {
+  mkdirSync(k, { recursive: true });
+  Bun.spawnSync(["git", "init", "-q", k]);
+  Bun.spawnSync(["git", "-C", k, "remote", "add", "origin", url]);
+  if (dirty) writeFileSync(join(k, "mine.txt"), "uncommitted");
+  more?.(k);
+};
+// The clone used as a project: its .kaizen/ is ignored, so `status --porcelain` alone reads clean.
+const runs = (k: string) => {
+  writeFileSync(join(k, ".git", "info", "exclude"), ".kaizen/\n");
+  mkdirSync(join(k, ".kaizen", "runs", "r1"), { recursive: true });
+  writeFileSync(join(k, ".kaizen", "runs", "r1", "state.json"), "{}");
+};
+const commit = (k: string) => {
+  Bun.spawnSync(["git", "-C", k, "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", "mine"]);
+};
+
+it("uninstall leaves a KAIZEN_HOME other than ~/kaizen, git checkout or not", () => {
+  const r = uninstall((k) => { kaizenFiles(k); mkdirSync(join(k, ".git")); }, true);
+  expect(r.left).toBe(true);
+  expect(r.out).toContain("KAIZEN_HOME is not ~/kaizen");
+  expect(uninstall(kaizenFiles, true).left).toBe(true);
+  // ~/kaizen is a link to the checkout KAIZEN_HOME names: same realpath, still refused.
+  const linked = uninstall((k) => { kaizenFiles(k); mkdirSync(join(k, ".git")); symlinkSync(k, join(dirname(k), "home", "kaizen")); }, true);
+  expect(linked.left).toBe(true);
+  expect(linked.out).toContain("KAIZEN_HOME is not ~/kaizen");
+});
+
+it("uninstall leaves a ~/kaizen that is not a kaizen install", () => {
+  const r = uninstall((k) => { mkdirSync(k); writeFileSync(join(k, "notes.txt"), "mine"); });
+  expect(r.left).toBe(true);
+  expect(r.out).toContain("not a kaizen install");
+});
+
+it("uninstall still removes the copy kaizen made without git", () => {
+  expect(uninstall(kaizenFiles).left).toBe(false);
+});
+
+it.skipIf(!Bun.which("git"))("uninstall removes a clean clone of kaizen and keeps any other", () => {
+  expect(uninstall(clone(REPO)).left).toBe(false);
+  expect(uninstall(clone(REPO.replace(/\.git$/, ""))).left).toBe(false);
+  const dirty = uninstall(clone(REPO, true));
+  expect(dirty.left).toBe(true);
+  expect(dirty.out).toContain("local changes");
+  const other = uninstall(clone("https://example.com/someone/else.git"));
+  expect(other.left).toBe(true);
+  expect(other.out).toContain("another repository");
+  const used = uninstall(clone(REPO, false, runs));
+  expect(used.left).toBe(true);
+  expect(used.out).toContain("ignored files");
+  const unpushed = uninstall(clone(REPO, false, commit));
+  expect(unpushed.left).toBe(true);
+  expect(unpushed.out).toContain("commits not pushed");
+});

package/cli/install.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 import {
-  symlinkSync, mkdirSync, readdirSync, lstatSync, readlinkSync, unlinkSync,
+  symlinkSync, mkdirSync, readdirSync, lstatSync, unlinkSync,
   existsSync, copyFileSync, readFileSync, appendFileSync, rmSync, writeFileSync, renameSync,
-  statSync, cpSync, realpathSync,
+  statSync, cpSync, realpathSync, rmdirSync,
 } from "node:fs";
-import { join, dirname, basename } from "node:path";
+import { join, dirname, basename, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { applyPreset, detectPreset, PRESETS, type PresetName } from "./settings.ts";
 
@@ -141,11 +141,14 @@ async function removeEverything() {
   }
   const gone: string[] = [];
   const stuck: string[] = [];
+  const kept: string[] = [];
   const drop = (p: string) => {
     if (!existsSync(p) && !isLink(p)) return;
     // Windows refuses to delete a file another process holds open, and a silent
     // failure here would read as a clean uninstall that removed nothing.
-    try { rmSync(p, { recursive: true, force: true }); gone.push(tilde(p)); }
+    // A link goes as a link: a recursive delete aimed at a junction can walk into
+    // the clone it points at.
+    try { if (isLink(p)) removeLink(p); else rmSync(p, { recursive: true, force: true }); gone.push(tilde(p)); }
     catch { stuck.push(tilde(p)); }
   };
 
@@ -172,7 +175,26 @@ async function removeEverything() {
     }
   }
 
-  drop(process.env.KAIZEN_HOME ?? join(home, "kaizen"));
+  // KAIZEN_HOME can point anywhere, a development checkout included, and deleting
+  // that takes .git and every uncommitted edit with it. Only ~/kaizen is deleted,
+  // and only as kaizen left it: its own clone with a clean tree, or the copy made
+  // without git. Anything else is named and left for its owner. The path is compared
+  // as written, so a KAIZEN_HOME that reaches ~/kaizen through a link is refused too.
+  // A clone holds no ignored files unless someone used it (.kaizen/ is ignored), and
+  // no commits that are not on a remote.
+  const install = process.env.KAIZEN_HOME ?? join(home, "kaizen");
+  const git = async (...a: string[]) => {
+    try { return (await Bun.$`git -C ${install} ${a}`.quiet().text()).trim(); } catch { return null; }
+  };
+  const repo = (u: string | null) => u?.replace(/\/+$/, "").replace(/\.git$/, "");
+  const why = !existsSync(install) ? ""
+    : resolve(install) !== join(home, "kaizen") ? "KAIZEN_HOME is not ~/kaizen"
+    : !existsSync(join(install, ".git")) ? (existsSync(join(install, "cli", "install.ts")) ? "" : "not a kaizen install")
+    : repo(await git("remote", "get-url", "origin")) !== repo(REPO_URL) ? "a git checkout of another repository"
+    : (await git("status", "--porcelain", "--ignored")) !== "" ? "a git checkout with local changes or ignored files"
+    : (await git("rev-list", "--branches", "--not", "--remotes")) !== "" ? "a git checkout with commits not pushed" : "";
+  if (why) kept.push(`${tilde(install)} ${c.dim(`(${why}; delete it yourself if it is only kaizen)`)}`);
+  else drop(install);
   drop(join(process.env.BUN_INSTALL ?? join(home, ".bun"), "bin", "kaizen.cmd"));
   drop(join(home, ".local", "bin", "kaizen"));
   await clearBunxCache();
@@ -184,7 +206,8 @@ async function removeEverything() {
 
   console.log(`\n  ${c.bold("Uninstalled")}`);
   for (const p of gone) console.log(`  ${c.dim("removed  " + p)}`);
-  if (!gone.length && !stuck.length) console.log(`  ${c.dim("nothing left to remove")}`);
+  for (const p of kept) console.log(`  ${c.dim("kept     ")}${p}`);
+  if (!gone.length && !stuck.length && !kept.length) console.log(`  ${c.dim("nothing left to remove")}`);
   if (stuck.length) {
     console.log(`\n  ${c.bold("could not remove")} ${c.dim("— close any dashboard or agent still using these, then run it again")}`);
     for (const p of stuck) console.log(`  ${c.dim(p)}`);
@@ -201,6 +224,12 @@ function isLink(p: string) {
   try { return lstatSync(p).isSymbolicLink(); } catch { return false; }
 }
 
+// Removes the link itself, never what it points at. A Windows junction is a
+// directory to unlink(), so rmdir() is the fallback; neither one recurses.
+function removeLink(p: string) {
+  try { unlinkSync(p); } catch { rmdirSync(p); }
+}
+
 // Nothing to install into. kaizen is a workflow an agent runs; on its own it does
 // nothing, so send them to the agent first rather than laying out files no reader
 // will ever load.
@@ -296,7 +325,10 @@ if (wantWeb) {
     process.exit(0);
   }
 
-  if (args.has("--daemon")) {
+  // On Windows a board in the foreground shares its console with every child it
+  // starts and Ctrl+C on kaizen.cmd asks "Terminate batch job (Y/N)?", so there a
+  // bare `kaizen web` detaches like the shortcut; --foreground keeps it here.
+  if (args.has("--daemon") || (process.platform === "win32" && !args.has("--foreground"))) {
     // The daemon is this same command, detached, with the browser left to us:
     // ignored stdio is what lets it outlive the terminal.
     // A board running an older kaizen is not "already running": the child finds
@@ -306,7 +338,7 @@ if (wantWeb) {
       console.log(`  kaizen web already running at ${url}`);
     } else {
       const argv = Bun.argv.slice(2).filter((a) => a !== "--daemon" && a !== "--no-open");
-      const child = Bun.spawn([process.execPath, Bun.main, ...argv, "--no-open"], {
+      const child = Bun.spawn([process.execPath, Bun.main, ...argv, "--no-open", "--foreground"], {
         detached: true, stdio: ["ignore", "ignore", "ignore"], windowsHide: true,
       });
       child.unref();
@@ -661,7 +693,10 @@ function linkState(src: string, dest: string) {
       if (isWindows && st.isFile()) return sameFile(src, dest) ? "linked" : "stale";
       return "occupied";
     }
-    return readlinkSync(dest) === src ? "linked" : "stale";
+    // Compared by where they lead, not by spelling: a junction reads back with a
+    // trailing \ or a \\?\ prefix, which made every upgrade relink every skill.
+    try { return realpathSync(dest) === realpathSync(src) ? "linked" : "stale"; }
+    catch { return "stale"; } // dangling: still a link to replace, not a free slot
   } catch {
     return "missing";
   }
@@ -686,7 +721,8 @@ for (const [src, sub] of links) {
     continue;
   }
   mkdirSync(dir, { recursive: true });
-  if (state !== "missing") rmSync(dest, { recursive: true, force: true });
+  if (state === "occupied") rmSync(dest, { recursive: true, force: true });
+  else if (state === "stale") removeLink(dest);
   makeLink(src, dest);
   wrote++;
   if (verbose) console.log(c.dim(`  link  ${name}`));

package/cli/notes.test.ts

@@ -210,7 +210,7 @@ test("the notebook's design tokens are the board's, line for line", () => {
   expect(block("board.html")).toContain("data-theme=dark]{--shade");
   const syms = (f: string) => readFileSync(join(root, "web", f), "utf8").split("\n").filter((l) => l.startsWith('<symbol id="s-')).join("\n");
   expect(syms("notes.html")).toBe(syms("board.html"));
-  expect(syms("board.html").split("\n").length).toBe(6);
+  expect(syms("board.html").split("\n").length).toBe(7);
   const mascot = (f: string) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(".mascot{"));
   expect(mascot("notes.html")).toBe(mascot("board.html")!);
 });

package/cli/settings.test.ts

@@ -0,0 +1,50 @@
+// Settings against a throwaway home and project: a project with its own config.yml
+// must not hide the board's machine-wide settings. Bun reads HOME once at startup,
+// so the settings code runs in a child process with a fake HOME; setting HOME here
+// would write to the real ~/.kaizen/config.yml.
+import { test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+
+const repo = join(dirname(import.meta.path), "..");
+const defaults = join(repo, "skills/kaizen/config.default.yml");
+let root: string, home: string, project: string;
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "kaizen-settings-"));
+  home = join(root, "home");
+  mkdirSync(join(home, ".kaizen"), { recursive: true });
+  writeFileSync(join(home, ".kaizen", "config.yml"), readFileSync(defaults, "utf8").replace('projects_dir: ""', "projects_dir: ~/Projects"));
+  // A project that carries its own config, as a cloned repo with .kaizen/config.yml does.
+  project = join(home, "Projects", "app");
+  mkdirSync(join(project, ".git"), { recursive: true });
+  mkdirSync(join(project, ".kaizen"), { recursive: true });
+  copyFileSync(defaults, join(project, ".kaizen", "config.yml"));
+});
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+// Runs `code` with listSettings/setSetting in scope, from inside the project, and returns what it prints.
+const inProject = (code: string) => {
+  const script = `import { listSettings, setSetting } from ${JSON.stringify(join(repo, "cli/settings.ts"))};
+const repo = ${JSON.stringify(repo)};
+const value = (k) => listSettings(repo).rows.find((r) => r.key === k)?.value;
+console.log(JSON.stringify(await (async () => { ${code} })()));`;
+  const p = Bun.spawnSync(["bun", "-e", script], { cwd: project, env: { ...process.env, HOME: home, USERPROFILE: home } });
+  if (p.exitCode !== 0) throw new Error(p.stderr.toString());
+  return JSON.parse(p.stdout.toString());
+};
+
+test("the projects folder survives moving into a project with its own config", () => {
+  expect(inProject(`return value("board.projects_dir")`)).toBe("~/Projects");
+});
+
+test("board settings save to the global config, project settings to the project", () => {
+  expect(inProject(`return [setSetting(repo, "board.projects_dir", "~/Work"), value("board.projects_dir")]`)).toEqual([{ ok: true }, "~/Work"]);
+  expect(readFileSync(join(home, ".kaizen", "config.yml"), "utf8")).toContain("projects_dir: ~/Work");
+  expect(readFileSync(join(project, ".kaizen", "config.yml"), "utf8")).toContain('projects_dir: ""');
+
+  expect(inProject(`return setSetting(repo, "git.auto_commit", "true")`)).toEqual({ ok: true });
+  expect(readFileSync(join(project, ".kaizen", "config.yml"), "utf8")).toMatch(/auto_commit: true/);
+});