kaizen-agent 1.43.1 → 1.43.3

package/cli/board.test.ts

@@ -254,3 +254,46 @@ test("a capitalised phrase mid-sentence is prose, not a label", () => {
 test("criteria not numbered from 1 keep their own numbers", () => {
   expect(brief("X Goal: g. Criteria: (2) two. (3) three.").parts[1].body).toBe("- (2) two.\n- (3) three.");
 });
+
+// pretty(): a one-line idea note splits into one paragraph per label.
+test("pretty splits a labelled plain line in a note by its labels", async () => {
+  const { pretty } = await import("../web/board/chat.ts");
+  const t = "Parent: run-x add a timezone. OPEN QUESTION (waiting on Johan): recalc old rows? Context: PR #452.";
+  expect(pretty(t)).toBe("**Parent:** run-x add a timezone.\n\n**OPEN QUESTION (waiting on Johan):** recalc old rows?\n\n**Context:** PR #452.");
+  expect(pretty("just a note")).toBe("just a note");
+  expect(pretty("Goal: a\nScope: b")).toBe("Goal: a\nScope: b");
+  expect(pretty("Parent: x\ndo y. NOTE: a. Context: b.")).toBe("Parent: x\n\ndo y.\n\n**NOTE:** a.\n\n**Context:** b.");
+  expect(pretty("- Goal: a. Scope: b.")).toBe("- Goal: a. Scope: b.");
+});
+
+test("the note editor turns its DOM back into the markdown md() rendered it from", async () => {
+  const { toMd } = await import("../web/board/rich.ts");
+  // A minimal DOM: element nodes from md()'s tag soup, enough for toMd.
+  const parse = (h) => {
+    const root = { nodeType: 1, nodeName: "DIV", childNodes: [], getAttribute: () => null };
+    const stack = [root];
+    for (const m of h.matchAll(/<(\/?)(\w+)([^>]*)>|([^<]+)/g)) {
+      const top = stack[stack.length - 1];
+      if (m[4]) top.childNodes.push({ nodeType: 3, nodeName: "#text", textContent: m[4].replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&") });
+      else if (m[1]) stack.pop();
+      else {
+        const attrs = Object.fromEntries([...m[3].matchAll(/(\w+)="([^"]*)"/g)].map((a) => [a[1], a[2]]));
+        const el = { nodeType: 1, nodeName: m[2].toUpperCase(), childNodes: [], getAttribute: (k) => attrs[k] ?? null };
+        Object.defineProperty(el, "textContent", { get: () => el.childNodes.map((c) => c.textContent).join("") });
+        top.childNodes.push(el);
+        if (!/^(img|br)$/.test(m[2])) stack.push(el);
+      }
+    }
+    return root;
+  };
+  const src = "# Title\n\nsome **bold**, *em* and `code` here  \nnext\n\n- one\n- two\n\n1. first\n2. second\n\n![shot](/f/a.png) [link](http://x)";
+  expect(toMd(parse(md(src)))).toBe(src);
+  // A fresh line typed straight into the box, then one Chrome wrapped in a div.
+  expect(toMd(parse("plain <b>b</b>​<div>next line</div>"))).toBe("plain **b**\n\nnext line");
+});
+
+test("md() renders italic and two-space hard breaks, and leaves globs in code alone", () => {
+  expect(md("an *em* word")).toBe("<p>an <i>em</i> word</p>");
+  expect(md("`*.ts` and `*.md`, a * b * c")).toBe("<p><code>*.ts</code> and <code>*.md</code>, a * b * c</p>");
+  expect(md("one  \ntwo\nthree")).toBe("<p>one<br>two three</p>");
+});

package/cli/install.ts

@@ -96,15 +96,17 @@ if (Bun.argv[2] === "browser") {
   process.exit(0);
 }
 
-// `kaizen card add "<text>" [--parent <run id>]`: what a run files as new work, linked
-// to the run it came from.
+// `kaizen card add "<title>" [--parent <run id>] [--notes "<details>"]`: what a run
+// files as new work, linked to the run it came from.
 if (Bun.argv[2] === "card") {
   const { locate, label, addCard } = await import("./state.ts");
   const state = locate() ?? join(home, ".kaizen");
   const args = Bun.argv.slice(4), at = args.indexOf("--parent");
   const parent = at >= 0 ? args.splice(at, 2)[1] : undefined;
-  if (Bun.argv[3] !== "add" || !args.length || (at >= 0 && !parent)) { console.log(`\n  kaizen card add "<text>" [--parent <run id>]\n`); process.exit(1); }
-  const r = addCard(state, args.join(" "), parent);
+  const nt = args.indexOf("--notes");
+  const details = nt >= 0 ? args.splice(nt, 2)[1] : undefined;
+  if (Bun.argv[3] !== "add" || !args.length || (at >= 0 && !parent) || (nt >= 0 && !details)) { console.log(`\n  kaizen card add "<title>" [--parent <run id>] [--notes "<details>"]\n`); process.exit(1); }
+  const r = addCard(state, args.join(" "), parent, details);
   if (typeof r === "string") { console.log(`\n  ${r}\n`); process.exit(1); }
   console.log(`\n  ${c.green("added")}  ${args.join(" ")}\n  ${c.dim(`parent ${r.parent}  ·  project ${label(state)}`)}\n`);
   process.exit(0);

package/cli/pty.test.ts

@@ -186,6 +186,16 @@ test.skipIf(process.platform === "win32")("the done sweep keeps a session the us
   await Bun.sleep(200);
   expect(alive(used)).toBe(true);
   process.kill(used, "SIGTERM");
+
+  // Only looked at: the page's focus and query answers reach the tty but are not typing.
+  done(Date.now() - 60_000);
+  const looked = launch("looked");
+  await Bun.sleep(200);
+  writePty("looked", "\x1b[I\x1b[O\x1b[?0u\x1b[<64;10;5M\x1bP>|xterm.js(6.0)\x1b\\");
+  await Bun.sleep(200);
+  expect(ptyState("looked")!.typed).toBe(0);
+  sweepSessions(st, Date.now() + CLOSE_GRACE_MS);
+  expect(await gone(looked)).toBe(true);
 });
 
 test("asking: Claude Code and Codex prompts count as a question, ordinary output does not", async () => {

package/cli/pty.ts

@@ -11,7 +11,7 @@ const WIN = process.platform === "win32";
 // Windows PowerShell, which every Windows has, both hosts the console and runs the agent in it.
 const winPs = () => join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
 
-type Pty = { proc: Bun.Subprocess; out: string[]; size: number; listeners: Set<(d: string | null) => void>; exit: number | null; asking: boolean; quiet?: Timer; total: number; since: number; onChange?: () => void };
+type Pty = { proc: Bun.Subprocess; out: string[]; size: number; listeners: Set<(d: string | null) => void>; exit: number | null; asking: boolean; quiet?: Timer; total: number; since: number; typed: number; onChange?: () => void };
 
 // What a page attaching late gets replayed. A full-screen tool redraws often, so the
 // tail of its output is enough to rebuild the screen.
@@ -38,7 +38,7 @@ export const ptySupported = WIN || typeof (Bun as any).Terminal === "function";
 // onChange: called when the agent ends or starts or stops asking, so the board can redraw.
 export function startPty(key: string, cmd: string[], cwd: string, pidFile?: string, onChange?: () => void): number {
   const dec = new TextDecoder();
-  const p: Pty = { proc: null as unknown as Bun.Subprocess, out: [], size: 0, listeners: new Set(), exit: null, asking: false, total: 0, since: 0, onChange };
+  const p: Pty = { proc: null as unknown as Bun.Subprocess, out: [], size: 0, listeners: new Set(), exit: null, asking: false, total: 0, since: 0, typed: 0, onChange };
   const flag = (v: boolean) => { if (p.asking !== v) { p.asking = v; onChange?.(); } };
   const push = (d: string) => {
     p.out.push(d);
@@ -99,11 +99,19 @@ export function attachPty(key: string, fn: (d: string | null) => void): (() => v
   return () => p.listeners.delete(fn);
 }
 
+// What the page's terminal sends by itself: focus in/out (Claude Code turns focus
+// reporting on), mouse and wheel reports, and answers to the agent's queries (cursor,
+// device, mode, colour, version). None of it is the user typing.
+const REPORT = /\x1b\[[IO]|\x1b\[<[\d;]*[Mm]|\x1b\[\?[\d;]*(?:[cnu]|\$y)|\x1b\[>[\d;]*c|\x1b\[\d+;\d+R|\x1b\[\d*n|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1bP[^\x1b]*\x1b\\/g;
+
 export function writePty(key: string, d: string) {
   const p = ptys.get(key);
   if (!p || p.exit !== null) return;
-  p.since = p.total;
-  if (p.asking) { p.asking = false; p.onChange?.(); }
+  if (d.replace(REPORT, "")) {
+    p.typed = Date.now();
+    p.since = p.total;
+    if (p.asking) { p.asking = false; p.onChange?.(); }
+  }
   send(p, d);
 }
 
@@ -122,7 +130,7 @@ export const ptyKeys = () => [...ptys.keys()];
 
 export const ptyState = (key: string) => {
   const p = ptys.get(key);
-  return p ? { alive: p.exit === null, exit: p.exit, asking: p.asking } : null;
+  return p ? { alive: p.exit === null, exit: p.exit, asking: p.asking, typed: p.typed } : null;
 };
 
 // The environment the user's login shell builds: PATH and anything exported in their

package/cli/state.test.ts

@@ -1228,6 +1228,8 @@ test("parent/child: a Parent line links a run and an idea to the run that filed
   expect(addCard(st, "next thing")).toEqual({ parent: "2026-01-02-b" });
   expect(addCard(st, "next thing")).toMatch(/already/);
   expect(addCard(st, "other", "nope")).toMatch(/no such run/);
+  addCard(st, "titled", "2026-01-02-b", "the details\nline two");
+  expect(readInbox(st).find((l) => l.text === "titled")?.notes).toContain("Parent: 2026-01-02-b\nthe details");
   expect(boardCards([st], Date.now()).find((k) => k.text === "next thing")!.parent).toBe("2026-01-02-b");
   rmSync(dirname(st), { recursive: true, force: true });
 });

package/cli/state.ts

@@ -5,7 +5,7 @@ import { existsSync, readFileSync, readdirSync, appendFileSync, writeFileSync, m
 import { Database } from "bun:sqlite";
 import { join, dirname, win32, posix } from "node:path";
 import { homedir, arch, cpus, release, totalmem, version as osVersion } from "node:os";
-import { startPty, ptySupported } from "./pty.ts";
+import { startPty, ptySupported, ptyState } from "./pty.ts";
 import { codeDir, projectFromWorktree } from "./worktree.ts";
 
 // The real path: process.cwd() is always physical, so a raw $HOME that crosses a
@@ -915,8 +915,9 @@ export function appendNote(state: string, target: { id: string } | { text: strin
 }
 
 // A card filed by a run: an open idea whose note names the run as its parent. The
-// parent is the one named, else the newest run still in flight.
-export function addCard(state: string, text: string, parent?: string): { parent: string } | string {
+// parent is the one named, else the newest run still in flight. `details` go in the
+// idea's notes below the Parent line, so the title stays a title.
+export function addCard(state: string, text: string, parent?: string, details?: string): { parent: string } | string {
   text = text.trim().replace(/\s+/g, " ");
   if (!text) return "empty card";
   const id = parent ?? readRuns(state).find((r) => r.stage !== "done" && r.stage !== "abandoned")?.id;
@@ -924,7 +925,7 @@ export function addCard(state: string, text: string, parent?: string): { parent:
   if (!existsSync(join(state, "runs", id, "state.json"))) return `no such run: ${id}`;
   const lines = readInbox(state);
   if (lines.some((l) => l.status === "open" && l.text === text)) return "that card is already on the board";
-  writeInbox(state, [...lines, { status: "open", text, notes: `Parent: ${id}` }]);
+  writeInbox(state, [...lines, { status: "open", text, notes: [`Parent: ${id}`, details?.trim()].filter(Boolean).join("\n") }]);
   return { parent: id };
 }
 
@@ -1343,7 +1344,7 @@ function opencodeRows(sql: string, ...args: (string | number)[]): string[] {
   } catch { return []; }
 }
 
-export const CLOSE_GRACE_MS = 2 * 60_000;
+export const CLOSE_GRACE_MS = 60_000;
 const sessionsDir = (st: string) => join(st, "sessions");
 
 export function readSessions(st: string): Session[] {
@@ -1509,7 +1510,11 @@ export function sweepSessions(st: string, now: number) {
 // Whether the user typed into the session's terminal after `t`: its tty's access time
 // moves when input is read. Such a session is the user's now, not the run's to close.
 // No tty (Windows, a stranger's PID): false, so the sweep closes as before.
+// A board card's session is judged by its keystrokes: the page's terminal answers the
+// agent's focus and query reports on that tty too, which moved its time on every look.
 function typedSince(st: string, s: Session, t: number): boolean {
+  const card = ptyState(s.key);
+  if (card) return card.typed > t;
   try {
     if (process.platform === "win32") return false;
     const pid = parseInt(readText(join(sessionsDir(st), s.key + ".pid")));

package/cli/web.ts

@@ -209,6 +209,8 @@ export async function web(repoDir: string, opts: Opts = {}) {
       const key = c.kind === "run" ? runs.get(`${c.state}\0${c.id}`) : ideaPty.get(`${c.state}\0${c.text}`);
       if (!key || !live.has(key)) return undefined;
       const st = ptyState(key)!;
+      // A finished run's agent that has ended has nothing left to show or resume.
+      if (!st.alive && (c.status === "done" || c.status === "abandoned")) return undefined;
       return { key, alive: st.alive, asking: st.asking };
     };
   };

package/package.json

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

package/skills/kaizen/SKILL.md

@@ -245,6 +245,12 @@ it. Everything else in this file holds unchanged.
   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.
+  Read `spec-build.md` before building and `spec-main.md` before moving the run to
+  `review`: being the main thread does not excuse a stage its contract. Its *Preview
+  gate* holds in full — a result that shows on a screen needs a real screenshot under
+  `runs/<id>/attachments/` embedded in `## Preview`, taken by driving a headless browser
+  against the running app; "no browser session" or "same renderer as before" is not a
+  reason, it is the gate failing. Short path or not, no screenshot means not built.
 - `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

package/skills/kaizen/config.default.yml

@@ -114,7 +114,7 @@ agent:
   # auto picks Claude Code if installed, otherwise the first agent found on PATH.
   default: auto
   # on: a board decision ends the run's waiting session before continuing its
-  # conversation, and abandoned or done runs (after 2 minutes) have theirs ended.
+  # conversation, and abandoned or done runs (after 1 minute) have theirs ended.
   # Only sessions the board or dashboard launched are touched. off: nothing is
   # ended, and a resumed conversation opens beside the window still waiting.
   close: on

package/skills/kaizen/docs.md

@@ -108,7 +108,9 @@ updated: YYYY-MM-DD
 2. Split it into 5–12 areas a newcomer would name — by what the parts do, not by
    folder alone. Fewer for a small project.
 3. Write one note per area in the shape above, then `Index.md`, then `Log.md` with the
-   first line.
+   first line. Every source file lands in some note's `sources` — the area's helpers,
+   small screens and scripts too, not only its main files — named directly or through a
+   folder that holds it (see *Coverage* below).
 4. Write the pointer (below).
 5. Lint, and report.
 
@@ -124,8 +126,9 @@ updated: YYYY-MM-DD
    rewrite the sections they affect — never `## Notes` — and set `updated`.
 3. Every `sources` path is gone: move the note to `Project/Archive/` and drop it from
    the Index. Never delete a note.
-4. A part of the repository no note covers (a new top-level folder, a new entry point):
-   write a note for it.
+4. A source file no note covers (see *Coverage*): add it to the `sources` of the note
+   whose area it belongs to, and mention it there; where it fits no area (a new top-level
+   folder, a new entry point), write a note for it.
 5. Refresh the Index lines whose description changed, append one Log line naming every
    note touched, refresh the pointer, lint, and report.
 
@@ -138,10 +141,20 @@ Checks, reported and not silently fixed:
 - every note has `description`, `tags`, `sources` and `updated` (the Index and Log need
   no `sources`), and is listed in the Index;
 - every `sources` path exists;
+- **uncovered**: source files no note's `sources` names or holds, listed one per line;
 - **stale**: notes whose `sources` changed after their `updated` day, found as in
   *Update* step 1;
 - `Index.md` is under 60 lines.
 
+## Coverage
+
+A **source file** is one the repository tracks (`git ls-files`; outside git, every file
+not ignored), leaving out lockfiles, generated or built output, vendored code, binaries,
+and bulk data folders. A note covers a file when its `sources` names the file or a folder
+that holds it, so a data folder such as `public/quran` is covered by naming the folder.
+Lint's *uncovered* list is what makes this checkable: a file no note covers is also a file
+whose changes *stale* never sees, so the vault falls behind without saying so.
+
 ## The pointer
 
 What makes an agent open the Index first. One block, identical everywhere:

package/skills/kaizen/spec-main.md

@@ -183,7 +183,10 @@ failed commit is reported as printed; the run is still `done`. With the setting
 
 A run may file new work as its own card instead of growing its scope — under either
 runner. Under `full`, subagents only suggest it in their report; the main thread files it,
-from the project folder: `kaizen card add "<the work, one line>"`. It links the card to
+from the project folder: `kaizen card add "<short title>" --notes "<details>"`. The title
+is what the card shows — a few words, like a commit subject; everything else (scope,
+context, open questions, where it came from) goes in `--notes`, never in the title.
+It links the card to
 the run in flight (`--parent <run id>` names another), and the link follows the card into
 the run it becomes. The board shows the parent's name on the child.
 
@@ -191,3 +194,31 @@ When a child run reaches `done`, the board appends `Child <child id> done: <titl
 the parent's `notes.md` by itself. The parent documents it from there: if it is still in
 flight its next stage reads `notes.md`; if it is already `done`, the entry is the record.
 Never reopen a finished parent.
+
+**A roadmap's increments are filed at its approval.** When the approved plan has a
+`## Roadmap` (see *A whole application is a roadmap* in `spec-plan.md`), the same write
+that records the approval files increments 2 to N, in order, from the project folder:
+`kaizen card add "<title> (roadmap #N · after #a, #b)" --parent <run id>`, with
+`any time` in place of `after …` where it has no prerequisite and its `blocked: <reason>`
+kept in the text where it has one. Increment 1 is this run's own build. Nothing starts
+by itself: the user starts an increment from its card when they choose, and the parent's
+card lists its children with their status. An increment cut at the approval is not
+filed; it goes to the backlog like anything else cut there.
+
+## Discovery rounds
+
+A roadmap plan's Discovery and any run's REA offer reach the user through the main
+thread, under every runner: each round's questions are asked with the tool's structured
+question mechanism (AskUserQuestion in Claude Code), all of a round's questions in one
+call, each with the planner's recommended option first. Under `runner: full`, the
+planner stops after writing a round; dispatch it again with the answers, recorded in
+`02-approval.md` as that round's decisions, until it writes a plan with no round left
+to ask, then present that plan at the plan approval as usual. Answers are not an
+approval: the run stays at `stage: "plan"` with `awaiting: null` throughout, and
+`awaiting: "approvals.plan"` is set only once `01-plan.md` has a `## Roadmap` — a round
+written to that file is not a plan to approve, and a tool resuming the run re-asks its
+questions. Where the user says yes to REA before the plan exists, run the study here,
+write what it found to the run's `notes.md`, and dispatch the planner with it. Where
+REA has to be installed first, the install in *Offer REA* (`spec-plan.md`) is the main
+thread's too: doctor, the dry-run shown to the user, setup only on their approval,
+then the restart, after which the run resumes at `stage: "plan"` from `state.json`.

package/skills/kaizen/spec-plan.md

@@ -27,6 +27,39 @@ different work behind each, nothing available to break the tie — and even then
 its recommendation with the question. Questions the existing material can answer are
 never asked; that is the planner's own work.
 
+**Offer REA for what exists but is not here.** In every run and every track: when the
+request or what came with it names something that already exists but whose source is
+not at hand — an app or site to copy, replace or integrate with, an APK or IPA, a
+binary, a package, a file format, a device or its firmware, a protocol or a capture —
+and REA's tools are connected in the session, the plan asks once:
+`Q: Study <the thing> with REA first?`, with `yes` (recommended where how it works
+inside decides the design) and `no`. Under `runner: lite` or an inline planner, a yes
+given before the plan is written lets the planner run REA itself and plan from what it
+found. Under `full`, where the planner has no REA tools, the main thread runs the study
+on a yes, writes what it found to the run's `notes.md`, and dispatches the planner
+again; a yes given at the plan approval instead makes the study the build's first
+step. What REA
+returns is cited with its limitations, as *the track* in `spec.md` already requires.
+REA not connected: ask instead
+`Q: REA isn't installed — set it up first?`, with `help me install it` (recommended
+where how it works inside decides the design), `I'll install it myself` and `skip
+REA`. On *help me install it* the main thread follows REA's own setup: it runs
+`npx -y rea-agents@<version> doctor --client <client> --json` — the version pinned,
+as REA's own guide pins it, taken from `npm view rea-agents version` and shown to the
+user; the client from the run's `agent` (`claude` → `claude_code`, `codex` → `codex`,
+`agy` → `antigravity`, `opencode` → `opencode`, `gemini` → `gemini_cli`, `cursor` →
+`cursor`) — then `setup --client <client> --dry-run --json` with the same version, shows the user the exact files it
+would change, and runs `setup --client <client> --yes` only after they approve it —
+setup writes the agent's own configuration, so it is never run unseen, in any mode.
+On *I'll install it myself* it gives that same command and waits. Either way the new
+tools appear only after the agent restarts: say so, and the run resumes from its
+`state.json`, the yes to REA recorded beforehand in `02-approval.md` so the resumed
+session studies the thing rather than asking again. REA's prerequisites (Node, and
+Java, Ghidra or JADX for some targets) are named where doctor reports them missing,
+never installed by the run. On *skip REA*, or when setup fails, the plan says so
+once and claims about that thing's internals are marked unverified. Nothing of the
+kind named: REA is not mentioned.
+
 **Building from nothing is the exception: settle the foundation first.** When the
 track is a new product or app, there is no material to answer the questions that
 decide everything after them, and "wrong" for this track is a wrong foundation — the
@@ -39,6 +72,67 @@ materially different builds — put to the user as an *Open question* with optio
 all in one round, before anything is built. Three quick questions and a default for
 the rest is how a run ends up writing the second app instead of the first.
 
+**A whole application is a roadmap, not a run.** When the track is a new product or
+app — web, mobile, PWA, desktop, anything — and it covers more than one independent
+module, one run cannot hold it: the plan, the diff and the review all outgrow what a
+reader can check. A single screen or a single feature stays one run. The Framing says
+in one line that the plan is a roadmap, so the user can refuse it. A roadmap plan adds
+three sections right after the Goal, each written for a person, and the
+foundation round above becomes up to three rounds:
+
+- **`## Discovery`** — the planner goes deep before it designs. It reads everything the
+  user brought first (decks, forms, sheets, screenshots, an existing repo, REA's
+  findings), then asks only what is still open, in up to three rounds of `Q:` pick
+  lists, each question with a recommended option: (1) purpose, who uses it and in what
+  roles, what it replaces; (2) the flows of each module and their domain rules;
+  (3) the foundation choices, among them how it ships, as a multi-select — full CI/CD
+  (tests and deploy on every merge), Docker (an image and a compose file that run
+  anywhere), a managed platform (Vercel, Fly, Railway or similar), mobile app ready
+  (store builds with signing, for example Capacitor or Expo/EAS), or a simple manual
+  deploy — and, where the app has a screen and no design system exists, its look and
+  feel, asked as item 7 *Design direction* below says: the feel (for example rich and
+  animated, calm and simple, enterprise and dense, gen-z and playful) and how much
+  motion. A round with nothing left to ask is skipped. Under `runner: full` the
+  planner writes `01-plan.md` with the Framing, `## Discovery` so far and the round's
+  questions as *Open questions*, and no `## Roadmap`, then stops; that file is a
+  round, not a plan. The main thread asks them and dispatches it again with the
+  answers. Under
+  `lite` or inline, the session asks them directly. The section records the roles, the
+  main flows, the things the app keeps track of and how they relate, a glossary of
+  the domain's words, and every answer given.
+- **`## Foundation`** — a decision with its reason, derived from Discovery, for each
+  of: platform; frontend (framework, UI kit, state, the design direction chosen);
+  backend (runtime, framework, API style); the contract between them (REST, RPC or
+  realtime, and where its types live); hosting and deploy, as chosen in discovery;
+  database (engine, where it runs, the main tables or collections and their
+  relations, how migrations are done); auth and access; repo layout and conventions.
+  Every increment builds on it.
+- **`## Roadmap`** — the increments, numbered, one line each:
+  `N. <title> — <what it delivers> — after: #a, #b` (or `any time`), with
+  `— blocked: <reason>` when something outside the work holds it. Increment 1 is always
+  the skeleton: the scaffold, the stack wired, the database schema and migration setup,
+  an auth stub, and a deploy of the empty app the way the Foundation ships (in its
+  Docker image, through its pipeline, as a store test build). Every feature increment
+  after it is one feature end to end — its screens, its API, its tables and migration,
+  and its tests — so each can be tried on its own; splitting by layer ("all the APIs", then "all the screens")
+  is only for an app with no UI or no backend. Each increment is sized to one ordinary
+  run. Where real people will use the app, the last increment is going live: what
+  the deploy choice still needs (the full pipeline, the production image, store
+  listings and release builds), backups, monitoring and error tracking, and the
+  production deploy. A last line says which must go in order and which can start any
+  time.
+
+The rest of a roadmap plan — Work list, Steps, File manifest, gate — covers increment 1
+only; it is this run's build. The others become child cards at the approval (see
+*Child cards* in `spec-main.md`).
+
+**An increment run builds inside its parent's decisions.** A request with a `Parent:`
+line whose parent run's `01-plan.md` has a `## Roadmap` is an increment. Its planner
+reads that plan's Discovery, Foundation and its own Roadmap line before anything else.
+They bind it: a deviation from the Foundation is an *Open question* to the user, and a
+change to the roadmap is an *Out of scope suggestion*, never a silent edit of the
+parent's plan.
+
 The goals stay the user's. The planner may propose a better solution to what was
 asked, or argue that the request as stated will not achieve what the user wants, but
 it may not widen the goal on its own. Anything beyond the request goes in *Out of
@@ -132,7 +226,7 @@ questions that are open. An alternative rejected gets a line saying what and why
 a case against it.
 
 **Write the parts a person reads for a person.** Framing, the Work list, Goal, Scope,
-Risks and Out of scope suggestions are read by someone deciding whether to approve,
+Discovery, Foundation, Roadmap, Risks and Out of scope suggestions are read by someone deciding whether to approve,
 often on a narrow panel. Write them in everyday words: short sentences, one idea per
 bullet, things named by what the user sees ("the chat bubble", "the Plan tab") rather
 than by function, file, CSS value or gate id. Code names, `path:line` and gate ids

package/skills/kaizen-help/SKILL.md

@@ -31,7 +31,7 @@ anything.
 | `/kaizen backlog` | Print open backlog items across all runs, grouped by source run, rescued items last under `Orphaned` |
 | `/kaizen gather` | Read request sources kaizen cannot read by itself; their requests land in the icebox, nothing starts |
 | `/kaizen discover` | Group what is in the icebox and promote the ideas you pick; nothing starts |
-| `/kaizen docs [lint]` | Write or refresh the project's docs vault in the notebook, which agents read first; `lint` only reports what is stale or broken |
+| `/kaizen docs [lint]` | Write or refresh the project's docs vault in the notebook, which agents read first; `lint` only reports what is stale, broken or uncovered |
 | `/kaizen approve` | Approve whatever the current run is waiting on |
 | `/kaizen reject <reason>` | Reject it; the reason decides revise (back to planner) vs kill (abandon) |
 | `/kaizen abort` | Mark the current run abandoned |

package/web/board/chat.ts

@@ -4,6 +4,7 @@ import { mic, stopDictation } from "./dictation.ts";
 import { $, html, raw as rawHtml } from "./dom.ts";
 import { DK, draft } from "./drafts.ts";
 import { attach, brief, md } from "./markdown.ts";
+import { rich } from "./rich.ts";
 import { toast } from "./toast.ts";
 
 // Notes are a chat: one entry per message, files attached by paste or picker.
@@ -21,6 +22,23 @@ function parseNotes(src) {
   }
   return out.map((n) => ({ ...n, text: n.text.trim() })).filter((n) => n.text);
 }
+// A plain line written as "Label: … Label: …" reads as one paragraph per label.
+// Markdown lines and fenced code are left as written.
+export function pretty(t) {
+  let fence = false;
+  return t
+    .split("\n")
+    .map((l) => {
+      if (/^```/.test(l)) fence = !fence;
+      if (fence || /^\s*(#|```|\||[-*]\s|\d+\.\s|>)/.test(l)) return l;
+      const b = brief(l);
+      if (!b.parts.length) return l;
+      const head = l.startsWith(b.parts[0].label + ":") ? [] : [b.head];
+      return "\n" + [...head, ...b.parts.map((p) => `**${p.label}:** ${p.body}`)].join("\n\n") + "\n";
+    })
+    .join("\n")
+    .trim();
+}
 let nfocus = null;
 export function chat(c, src, ro) {
   const fix = (t) => attach(t, c);
@@ -28,9 +46,13 @@ export function chat(c, src, ro) {
   const b = c.kind === "idea" ? brief(c.text) : { parts: [] };
   let h =
     (b.parts.length
-      ? html`<section class="desc">${rawHtml(md(b.parts.map((p) => `### ${p.label}\n${p.body}`).join("\n\n")))}</section>`
+      ? html`<section class="desc">
+          ${rawHtml(md(b.parts.map((p) => `### ${p.label}\n${p.body}`).join("\n\n")))}
+        </section>`
       : "") +
-    html`<div class="chat">${entries.map((n) => html`<div class="msg">${n.at ? html`<time>${n.at}</time>` : ""}${rawHtml(md(fix(n.text)))}</div>`)}${entries.length ? "" : html`<p style="color:var(--dim)">No notes yet.</p>`}</div>`;
+    html`<div class="chat">
+      ${entries.map((n) => html`<div class="msg">${n.at ? html`<time>${n.at}</time>` : ""}${rawHtml(md(fix(pretty(n.text))))}</div>`)}${entries.length ? "" : html`<p style="color:var(--dim)">No notes yet.</p>`}
+    </div>`;
   if (!ro)
     h += `<div class="notes"><textarea placeholder="Add a note. Paste a screenshot, or attach files."></textarea><div class="att" id="natt"></div><div class="tools"><input type="file" id="nfile" multiple hidden><button class="btn ghost" id="npick">Attach</button><span>Enter sends, Shift+Enter newline</span><button class="btn pri" id="nsend">Send</button></div></div>`;
   $("pbody").innerHTML = rawHtml(h);
@@ -38,11 +60,12 @@ export function chat(c, src, ro) {
   const ta = $("pbody").querySelector("textarea"),
     files = [];
   draft(ta, "n:" + key(c));
+  const ed = rich(ta);
   // Enter leaves focus in the box, and a focused box blocks the redraw: send blurs it
   // so the note shows, and the new box takes focus back for the next note.
   if (nfocus === key(c)) {
     nfocus = null;
-    ta.focus();
+    ed.focus();
   }
   {
     const m = mic([ta]);
@@ -60,7 +83,7 @@ export function chat(c, src, ro) {
     [...e.target.files].forEach(add);
     e.target.value = "";
   };
-  ta.onpaste = (e) => {
+  ed.onpaste = (e) => {
     for (const it of e.clipboardData.items)
       if (it.kind === "file") {
         const f = it.getAsFile();
@@ -93,12 +116,12 @@ export function chat(c, src, ro) {
       } catch (e) {}
       toast("Noted");
       nfocus = key(c);
-      ta.blur();
+      ed.blur();
       load();
     }
   };
   $("nsend").onclick = send;
-  ta.onkeydown = (e) => {
+  ed.onkeydown = (e) => {
     if (e.key === "Enter" && !e.shiftKey) {
       e.preventDefault();
       send();

package/web/board/markdown.ts

@@ -64,7 +64,8 @@ export function planQuestions(src) {
 export function brief(t) {
   // A label opens a sentence; only the first may follow the head without punctuation,
   // and then only as one word ("… previews Problem:"), so "the Board shows: x" is prose.
-  const re = /(^|[.!?)]\s+|\s)([A-Z][\w-]*(?: [a-z][\w-]*){0,3}):\s+/g,
+  const re =
+      /(^|[.!?)]\s+|\s)((?:[A-Z][A-Z-]+(?: [A-Z][A-Z-]+){1,3}|[A-Z][\w-]*(?: [a-z][\w-]*){0,3})(?: \([^)]*\))?):\s+/g,
     cut = [];
   let m;
   while ((m = re.exec(t)))
@@ -88,7 +89,7 @@ export function brief(t) {
 }
 
 // Enough markdown for kaizen's own files: headings, lists, fences, tables,
-// inline code, bold. Everything is escaped first. With `tick`, a backlog item
+// inline code, bold, italic, hard line breaks. Everything is escaped first. With `tick`, a backlog item
 // (`- open: …`, `- done: …`, `- rejected: …`) shows its status as a checkbox.
 export function md(src, tick) {
   const lines = src.split("\n"),
@@ -99,6 +100,7 @@ export function md(src, tick) {
     esc(s)
       .replace(/`([^`]+)`/g, "<code>$1</code>")
       .replace(/\*\*([^*]+)\*\*/g, "<b>$1</b>")
+      .replace(/(^|[^*])\*([^*\s<][^*<]*?)\*(?!\*)/g, "$1<i>$2</i>")
       .replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, '<a href="$2" target="_blank"><img src="$2" alt="$1"></a>')
       .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, '<a href="$2" target="_blank">$1</a>');
   const endList = () => {
@@ -182,7 +184,10 @@ export function md(src, tick) {
     i++;
     while (i < lines.length && lines[i].trim() && !/^(#|```|\||\s*[-*]\s|\s*\d+\.\s|---)/.test(lines[i]))
       buf.push(lines[i++]);
-    out.push(`<p>${inl(buf.join(" "))}</p>`);
+    // A line ending in two spaces is a hard line break.
+    out.push(
+      `<p>${inl(buf.map((l, k) => (k < buf.length - 1 && / {2}$/.test(l) ? l.trimEnd() + "\0" : l)).join(" ")).replace(/\0 /g, "<br>")}</p>`,
+    );
   }
   endList();
   return out.join("");