planrails 0.1.0

package/src/plan/fixtures/broken-root/.project-management/plans/broken/state.json

@@ -0,0 +1,67 @@
+{
+  "id": "broken",
+  "title": "A plan whose state lies: T1 is done with no recorded gate run",
+  "status": "active",
+  "created": "2026-09-12",
+  "activatedAt": "2026-09-12T10:00:00+05:30",
+  "closedAt": null,
+  "paths": [
+    "src/**"
+  ],
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "A task somebody marked done by hand",
+      "status": "done",
+      "gate": "G1",
+      "manualCheck": null,
+      "files": [],
+      "effort": null,
+      "dependsOn": [],
+      "notes": "",
+      "startedAt": "2026-09-12T10:00:00+05:30",
+      "doneAt": "2026-09-12T11:00:00+05:30",
+      "evidence": {
+        "kind": "gate",
+        "gate": "G1",
+        "runId": "never-happened",
+        "at": "2026-09-12T11:00:00+05:30"
+      },
+      "blocked": null,
+      "doneWhen": [],
+      "doneChecklist": []
+    }
+  ],
+  "doneWhen": [
+    {
+      "id": "C1",
+      "statement": "The task's gate ran in this very command and passed — or a manual reason names who checked it and how.",
+      "kind": "auto:gate"
+    },
+    {
+      "id": "C2",
+      "statement": "A log entry names this task and was written after it started, saying what landed and what comes next.",
+      "kind": "auto:logged"
+    },
+    {
+      "id": "C3",
+      "statement": "Every file this task lists exists on disk.",
+      "kind": "auto:files"
+    },
+    {
+      "id": "C4",
+      "statement": "The docs that describe this change shipped in the same change — name them, or say why none were needed.",
+      "kind": "manual"
+    },
+    {
+      "id": "C5",
+      "statement": "Every number in the log entry and in any report carries a locator (file:line, page, verse) or was re-derived — say which.",
+      "kind": "manual"
+    },
+    {
+      "id": "C6",
+      "statement": "Anything learned or decided while doing this is recorded with plan learn / plan decide — name the ids, or say nothing was.",
+      "kind": "manual"
+    }
+  ]
+}

package/src/plan/fixtures/broken-root/CLAUDE.md

@@ -0,0 +1,3 @@
+# fixture
+
+## Project management

package/src/plan/fixtures/broken-trial.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Builds a TAMPERED copy of a black-box trial's snapshots at .tmp/broken-trial/: every task
+ * that run 2 closed is rewritten as closed BY HAND (manual evidence, no gate run). Gate G7's
+ * known-fail case runs trial/check.mjs on that copy, and it must FAIL — proving the trial
+ * verdict cannot be passed by a run that never let a gate decide anything.
+ *   node node_modules/planrails/src/plan/fixtures/broken-trial.mjs <trial-dir>
+ */
+import { cpSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const trial = process.argv[2];
+if (!trial || !existsSync(join(trial, ".tmp", "trial", "snapshot-after-run2.json"))) { console.error("broken-trial: need a trial dir that has run (snapshot-after-run2.json missing)"); process.exit(3); }
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const out = join(root, ".tmp", "broken-trial");
+mkdirSync(join(out, ".tmp"), { recursive: true });
+cpSync(join(trial, ".tmp", "trial"), join(out, ".tmp", "trial"), { recursive: true });
+let tampered = 0;
+for (const f of ["snapshot-after-run2.json", "snapshot-after-run3.json"]) {
+  const p = join(out, ".tmp", "trial", f); const snap = JSON.parse(readFileSync(p, "utf8"));
+  for (const plan of Object.values(snap.plans)) { for (const t of plan.tasks) if (t.status === "done" && t.evidence?.kind === "gate") { t.evidence = { kind: "manual", by: "agent", at: t.evidence.at, reason: "TAMPERED: closed by hand, no gate ran" }; tampered++; } plan.gateRuns = 0; }
+  writeFileSync(p, JSON.stringify(snap, null, 2));
+}
+if (!tampered) { console.error("broken-trial: no gate-closed task to tamper with — the fixture would test nothing"); process.exit(3); }
+console.log(`tampered trial built at ${out} (${tampered} gate closes rewritten as manual)`);

package/src/plan/lib/brief.mjs

@@ -0,0 +1,116 @@
+/**
+ * The brief: what a fresh session (or one that just compacted) needs to know
+ * about a plan, in about a thousand tokens. Rendered from the files every
+ * time — never stored, so it cannot go stale.
+ *
+ * It answers, in order: what is this · where does it stand · what do I do
+ * NOW · what happened last · what is unverified · which rules apply · how to
+ * record. Everything else is a pointer into PLAN.md.
+ */
+import { lastRunFor, verifiedFor, taskCounts } from "./store.mjs";
+import { shortStamp } from "./time.mjs";
+import { pathMatches } from "./glob.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { JUDGMENT_SHORT } from "./judgment.mjs";
+
+const CAP = Number(process.env.PLAN_BRIEF_CAP || 6000);
+
+/** First paragraph under a "## Heading" in PLAN.md, or "". */
+export function sectionOf(md, heading) {
+  const re = new RegExp(`^##\\s+${heading}\\s*$`, "mi");
+  const m = re.exec(md);
+  if (!m) return "";
+  const rest = md.slice(m.index + m[0].length);
+  const end = rest.search(/^##\s+/m);
+  return (end === -1 ? rest : rest.slice(0, end)).replace(/<!--[\s\S]*?-->/g, "").trim();
+}
+function firstParagraph(text, max = 420) {
+  const p = text.split(/\n\s*\n/)[0]?.replace(/\s+/g, " ").trim() || "";
+  return p.length > max ? p.slice(0, max - 1) + "…" : p;
+}
+function clip(s, n) { s = String(s || "").replace(/\s+/g, " ").trim(); return s.length > n ? s.slice(0, n - 1) + "…" : s; }
+
+/**
+ * The AGENT BRIEF: what a subagent gets instead of the plan. Measured reason
+ * (CLAUDE.md § TOKEN DISCIPLINE): a subagent's fixed prompt is re-read on every
+ * turn, so it carries the task, its files, the rules for those files, what
+ * "done" means, where to write its report, and what it must never do — and
+ * nothing else. The hook re-injects the same rules at the tool call, per agent.
+ */
+export function renderAgentBrief(plan, task, { unit = null, label = null, cli = "npx planrails" } = {}) {
+  const { state } = plan;
+  const gate = task.gate ? plan.gates.gates.find((g) => g.id === task.gate) : null;
+  const rules = (plan.rules?.rules || []).filter((r) => r.when.path && task.files.some((f) => pathMatches(f, r.when.path)));
+  const ruleText = (r) => { if (r.text) return r.text; try { return readFileSync(join(plan.dir, r.file), "utf8").trim(); } catch { return `(rule ${r.id}: ${r.file} unreadable)`; } };
+  const reportName = `${task.id}-${(label || unit || "report").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "report"}.md`;
+  const reportPath = `${plan.dir.replace(/.*\/(\.project-management\/)/, "$1")}/reports/${reportName}`;
+  const out = [];
+  out.push(`AGENT BRIEF — plan ${state.id}, task ${task.id}: ${clip(task.title, 160)}`);
+  out.push("You are a subagent. This brief is your whole memory of the plan; the main session owns the plan and closes tasks.");
+  out.push(`DO: ${clip(unit || task.title, 400)}${task.effort ? ` · think at effort ${task.effort}` : ""}`);
+  out.push(`FILES YOU MAY WRITE: ${task.files.length ? task.files.join(", ") : "(none declared — write only under the paths the main session names)"} — nothing else.`);
+  if (task.notes) out.push(`NOTES FROM THE PLAN: ${clip(task.notes, 300)}`);
+  out.push(`DONE MEANS (the main session checks this, not you): ${gate ? `${gate.id} — ${clip(gate.question, 200)} — $ ${gate.command}` : clip(task.manualCheck || "(not stated)", 200)}`);
+  out.push(`REPORT: write ${reportPath} — what you wrote (paths); every number WITH its locator (file:line, page, verse); every doubt; what you did NOT do. Then return at most 10 lines that name that file. A report that lives only in your reply dies with you.`);
+  out.push(`NEVER: delete anything (move it aside instead); write outside the files above; run \`${cli} task done\` or \`close\`; settle a doubt by guessing — write it in the report; skip work already on disk without saying so.`);
+  // Rules last and clipped per rule: truncation, if it ever happens, cuts guidance, never the contract above.
+  for (const r of rules.slice(0, 3)) out.push(`RULE ${r.id} FOR THESE FILES: ${clip(ruleText(r), 600)}`);
+  const planRules = sectionOf(plan.planMd, "Rules for this plan").split("\n").filter((l) => l.trim()).slice(0, 4);
+  if (planRules.length) out.push(`PLAN RULES (first lines of PLAN.md § Rules): ${planRules.map((l) => clip(l, 140)).join(" ")}`);
+  let text = out.join("\n");
+  if (text.length > 3000) text = text.slice(0, 2960) + "\n…(guidance truncated at 3000 chars; the contract above is complete)";
+  return text;
+}
+
+export function renderBrief(plan, { cli = "npx planrails" } = {}) {
+  const { state, gates } = plan;
+  const c = taskCounts(state);
+  const doing = state.tasks.filter((t) => t.status === "doing");
+  const blocked = state.tasks.filter((t) => t.status === "blocked");
+  const todo = state.tasks.filter((t) => t.status === "todo");
+  const last = plan.log.at(-1);
+  const gateLine = (gid) => {
+    if (!gid) return "manual check";
+    const g = gates.gates.find((x) => x.id === gid);
+    const r = lastRunFor(plan, gid);
+    const v = g?.knownFail ? (verifiedFor(plan, gid) ? "" : " · never verified against its knownFail") : "";
+    return `${gid}${r ? ` (last ${r.result.toUpperCase()} ${shortStamp(r.at)})` : " (never run)"}${v}`;
+  };
+  const out = [];
+  out.push(`## Plan ${state.id} — ${state.title}`);
+  out.push(`${state.status} · ${c.done}/${state.tasks.length} tasks done · ${c.doing} doing · ${c.blocked} blocked · last log ${last ? shortStamp(last.at) : "never"}`);
+  const why = firstParagraph(sectionOf(plan.planMd, "Why"));
+  if (why) out.push(`WHY: ${why}`);
+  if (last) {
+    out.push(`RESUME: ${clip(last.next, 400)}`);
+    if (last.uncommitted) out.push(`UNCOMMITTED: ${clip(last.uncommitted, 200)}`);
+  } else out.push(`RESUME: no log entry yet — read PLAN.md § Method, start the first task with: ${cli} task start ${state.id} ${todo[0]?.id || "T1"}`);
+  for (const t of doing) out.push(`NOW ${t.id}: ${clip(t.title, 120)} — proves done by ${gateLine(t.gate)}${t.effort ? ` · effort ${t.effort}` : ""}`);
+  for (const t of blocked) out.push(`BLOCKED ${t.id}: ${clip(t.title, 80)} — ${clip(t.blocked?.reason, 160)} (needs ${t.blocked?.needs})`);
+  if (todo.length) out.push(`NEXT: ${todo.slice(0, 3).map((t) => `${t.id} ${clip(t.title, 70)}`).join(" · ")}${todo.length > 3 ? ` · +${todo.length - 3} more` : ""}`);
+  const recent = plan.log.slice(-3).reverse();
+  if (recent.length) {
+    out.push("LAST LOG:");
+    for (const e of recent) out.push(`- ${shortStamp(e.at)}${e.task ? ` [${e.task}]` : ""} ${clip(e.what, 220)}`);
+  }
+  const leads = plan.learnings.filter((l) => l.status === "lead");
+  if (leads.length) {
+    out.push(`LEADS (need a second reader before anyone acts on them):`);
+    for (const l of leads.slice(-4)) out.push(`- ${l.id}: ${clip(l.what, 160)}`);
+  }
+  const rules = sectionOf(plan.planMd, "Rules for this plan");
+  if (rules) {
+    const lines = rules.split("\n").filter((l) => l.trim()).slice(0, 14);
+    out.push("RULES FOR THIS PLAN (full text: PLAN.md § Rules for this plan):");
+    for (const l of lines) out.push(clip(l, 240));
+  }
+  const owner = sectionOf(plan.planMd, "Owner decides");
+  if (owner) out.push(`OWNER DECIDES (stop and ask before each): ${clip(owner.split("\n").map((l) => l.replace(/^\s*[-*]\s*/, "").trim()).filter(Boolean).join(" · "), 300)}`);
+  out.push(JUDGMENT_SHORT);
+  out.push(`RECORD AS YOU GO: ${cli} log ${state.id} --task <T> --what "…" --next "…"  ·  learn / decide / task done <T> (runs the gate)`);
+  out.push(`FULL METHOD: ${plan.dir.replace(/.*\/(\.project-management\/)/, "$1")}/PLAN.md`);
+  let text = out.join("\n");
+  if (text.length > CAP) text = text.slice(0, CAP - 40) + `\n…(brief truncated at ${CAP} chars; open PLAN.md)`;
+  return text;
+}

package/src/plan/lib/claude-md.mjs

@@ -0,0 +1,66 @@
+/**
+ * The ONE block the plan system owns in CLAUDE.md.
+ *
+ * CLAUDE.md is always in context, so the pointer to an active plan lives there
+ * and nowhere else. The block is generated: `activate` adds a line, `close`
+ * removes it, and `validate --all` fails if the block and the active plans
+ * disagree. That drift check is why a stale pointer cannot survive — the exact
+ * failure CLAUDE.md § ♻️ describes ("the line that used to stand here sent every
+ * session to a block saying 'coverage done'").
+ *
+ * The block carries NO counts or dates: those would change on every log entry
+ * and turn CLAUDE.md into a noisy diff. Live state comes from the brief.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+export const BEGIN = "<!-- plans:begin — generated by src/plan/plan.mjs; do not hand-edit this block -->";
+export const END = "<!-- plans:end -->";
+
+export function renderBlock(activePlans) {
+  const lines = [BEGIN];
+  if (activePlans.length) {
+    lines.push("**▶ ACTIVE PLANS — a SessionStart hook injects each plan's brief; if you do not see it, run `npx planrails brief` before any work on these.** Record progress with `plan log`, findings with `plan learn`, choices with `plan decide`; mark a task done only through `plan task done` (it runs the gate). Guide: docs/PLANNING_GUIDE.md.");
+    for (const p of activePlans) lines.push(`- **${p.id}** — ${p.title} — \`.project-management/plans/${p.id}/PLAN.md\``);
+  } else {
+    lines.push("_No active plans. Create one with `/plan <raw plan>` or `npx planrails new <id> --title \"…\"` (docs/PLANNING_GUIDE.md)._");
+  }
+  lines.push(END);
+  return lines.join("\n");
+}
+
+export function readBlock(md) {
+  const a = md.indexOf(BEGIN); const b = md.indexOf(END);
+  if (a === -1 || b === -1 || b < a) return null;
+  return md.slice(a, b + END.length);
+}
+/** How many blocks the file holds. More than one is a merge accident; validate fails on it. */
+export function blockCount(md) { return md.split(BEGIN).length - 1; }
+
+/** Plan ids currently listed in the block (for the drift check). */
+export function idsInBlock(md) {
+  const block = readBlock(md);
+  if (!block) return null;
+  return [...block.matchAll(/^- \*\*([a-z0-9-]+)\*\*/gm)].map((m) => m[1]);
+}
+
+/** Write the block in place; if absent, insert it before "## Project management", else append. Returns true if the file changed. */
+export function writeBlock(path, activePlans) {
+  const md = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const block = renderBlock(activePlans);
+  const existing = readBlock(md);
+  let next;
+  if (existing) {
+    // Every block is taken out (a merge can leave two, even two identical ones); the first one's place gets the
+    // fresh block. Function replacers throughout: a plain string replacement would $-expand a title holding "$&".
+    const HOLE = "\u0000plans-block\u0000";
+    next = md; let blk; let first = true;
+    while ((blk = readBlock(next)) !== null) { next = next.replace(blk, () => (first ? HOLE : "")); first = false; }
+    next = next.replace(HOLE, () => block).replace(/\n{3,}/g, "\n\n");
+  } else {
+    const anchor = md.search(/^## Project management\s*$/m);
+    next = anchor === -1 ? `${md.replace(/\s*$/, "")}\n\n${block}\n` : `${md.slice(0, anchor)}${block}\n\n${md.slice(anchor)}`;
+  }
+  if (next === md) return false;
+  writeFileSync(path, next);
+  return true;
+}

package/src/plan/lib/glob.mjs

@@ -0,0 +1,81 @@
+/**
+ * Path and tool matching for rules.
+ *
+ * Own glob matcher, on purpose: Node's path.matchesGlob follows shell rules and
+ * `**` does not cross a dot-directory, so `**\/ch*.json` never matched
+ * `.tmp/witness-full/x/ch01.json` (found in review, 2026-09-12). Here `**`
+ * crosses everything; `*` and `?` stay inside one segment; `{a,b}` alternates.
+ * Globs are repo-relative. A tool's file_path arrives absolute or relative to
+ * the session's cwd; we make it relative to the project root and refuse to
+ * match anything outside the project.
+ */
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+const cache = new Map();
+export function globToRegExp(glob) {
+  if (cache.has(glob)) return cache.get(glob);
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        const slash = glob[i + 2] === "/";
+        re += slash ? "(?:.*/)?" : ".*";
+        i += slash ? 2 : 1;
+      } else re += "[^/]*";
+    } else if (c === "?") re += "[^/]";
+    else if (c === "{") {
+      const end = glob.indexOf("}", i);
+      if (end === -1) { re += "\\{"; continue; }
+      re += "(?:" + glob.slice(i + 1, end).split(",").map((s) => s.replace(/[.+^$()|[\]\\]/g, "\\$&")).join("|") + ")";
+      i = end;
+    } else re += c.replace(/[.+^$()|[\]\\]/g, "\\$&");
+  }
+  const out = new RegExp("^" + re + "$");
+  cache.set(glob, out);
+  return out;
+}
+
+export function toRepoRelative(filePath, root, cwd = null) {
+  if (!filePath) return null;
+  const abs = isAbsolute(String(filePath)) ? String(filePath) : resolve(cwd || root, String(filePath));
+  const rel = relative(root, abs);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) return null;
+  return rel.split(sep).join("/");
+}
+
+export function pathMatches(relPath, glob) {
+  if (!relPath) return false;
+  return globToRegExp(glob).test(relPath);
+}
+
+export function anyPathMatches(relPath, globs) {
+  return (globs || []).some((g) => pathMatches(relPath, g));
+}
+
+/** `tool` in a rule is a regex over tool names, anchored: "Edit|Write" matches exactly those. */
+export function toolMatches(toolName, toolPattern) {
+  try { return new RegExp(`^(?:${toolPattern})$`).test(toolName); } catch { return false; }
+}
+
+function safeTest(pattern, text) {
+  try { return new RegExp(pattern, "i").test(text || ""); } catch { return false; }
+}
+
+/**
+ * Does this rule fire for this tool call? Every clause in `when` must hold.
+ * Returns false for tools the rule does not name, so a path-only rule never
+ * fires on Bash and a command-only rule never fires on Edit.
+ */
+export function ruleMatches(rule, { toolName, toolInput, root, cwd = null }) {
+  const w = rule.when;
+  if (!toolMatches(toolName, w.tool)) return false;
+  const ti = toolInput || {};
+  if (w.path) {
+    const rel = toRepoRelative(ti.file_path || ti.notebook_path || "", root, cwd);
+    if (!pathMatches(rel, w.path)) return false;
+  }
+  if (w.command && !safeTest(w.command, ti.command)) return false;
+  if (w.prompt && !safeTest(w.prompt, [ti.prompt, ti.script, ti.description, ti.skill, ti.args].filter(Boolean).join("\n"))) return false;
+  return true;
+}

package/src/plan/lib/judgment.mjs

@@ -0,0 +1,19 @@
+/**
+ * The words an agent sees at every moment it decides whether work is done:
+ * task check, the task done refusal, the brief, and the fresh-session prompt.
+ *
+ * Why (owner, 2026-09-12, decision D9): a gate is a proxy for the goal, and
+ * every proxy has cases where it is wrong. Under "you cannot be done until the
+ * gate is green" an agent will sometimes satisfy the proxy instead of the goal:
+ * weaken the gate, bend the data, patch a file by hand. The trial did exactly
+ * that on its first unattended run. So judgment is pointed in three directions,
+ * and the override is routed through the owner: the agent may say "the gate is
+ * wrong, here is why" (task block --needs owner), but never both judge and pass.
+ */
+export const JUDGMENT = [
+  "JUDGMENT OUTRANKS THE GATE. A gate is a script: it cannot read, cannot see, and answers only the one question it was written for. You can. Read what it computed, then rule on it:",
+  "· gate RED, work right → never make the gate pass. Write down what it literally computed and what is true. If the GATE is wrong, fix the gate and re-run gate verify (its known-fail case must still fail). Otherwise: task block --needs owner --reason \"…\" and stop. The owner's word closes it; yours does not.",
+  "· gate GREEN, work wrong → refuse to close. Say what the gate cannot see, and fix the work.",
+  "· anything crashed → never edit a plan file by hand. Log it, block, stop.",
+];
+export const JUDGMENT_SHORT = "JUDGMENT OUTRANKS THE GATE: a red gate is never made to pass, a green gate is never trusted blind, a crash is never patched by hand. task check prints the rest.";

package/src/plan/lib/paths.mjs

@@ -0,0 +1,65 @@
+/**
+ * Where planrails keeps things, and how it finds the project.
+ *
+ * One root, everything hangs off it. The root is, in order:
+ *   1. PLAN_PROJECT_ROOT   — set by tests, which point it at a throwaway directory
+ *   2. CLAUDE_PROJECT_DIR  — set by Claude Code for every hook command (measured on 2.1.269)
+ *   3. the nearest directory above the cwd holding .project-management/ or CLAUDE.md
+ *   4. the nearest directory above the cwd holding package.json or .git
+ *   5. the cwd
+ * So `npx planrails …` works from any subdirectory of a project, and a hook
+ * always sees the project the session was started in.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The installed package itself: src/plan/lib → ../../.. */
+export function packageRoot() { return resolve(HERE, "..", "..", ".."); }
+
+function findUp(start, markers) {
+  let d = resolve(start);
+  for (;;) {
+    if (markers.some((m) => existsSync(join(d, m)))) return d;
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+export function projectRoot() {
+  if (process.env.PLAN_PROJECT_ROOT) return resolve(process.env.PLAN_PROJECT_ROOT);
+  if (process.env.CLAUDE_PROJECT_DIR) return resolve(process.env.CLAUDE_PROJECT_DIR);
+  return findUp(process.cwd(), [".project-management", "CLAUDE.md"]) || findUp(process.cwd(), ["package.json", ".git"]) || process.cwd();
+}
+/** How the CLI is invoked in messages the tool prints for the agent. */
+export function cliName() { return process.env.PLAN_CLI_NAME || "npx planrails"; }
+
+export function plansRoot() { return join(projectRoot(), ".project-management", "plans"); }
+export function planDir(id) { return join(plansRoot(), id); }
+export function claudeMdPath() { return join(projectRoot(), "CLAUDE.md"); }
+export function claudeSettingsPath() { return join(projectRoot(), ".claude", "settings.json"); }
+/** Everything planrails writes that is NOT the plan itself lives under .planrails/ (gitignored by init). */
+export function stateRoot() { return join(projectRoot(), ".planrails"); }
+/** Per-session scratch for the hooks: injected rules, unlogged edits, reminders. */
+export function hookStateRoot() { return join(stateRoot(), "hooks"); }
+/** The pre-compaction progress journals, one file per session. */
+export function journalRoot() { return join(stateRoot(), "journal"); }
+/** Backups of .claude/settings.json taken before the installer writes it. */
+export function backupRoot() { return join(stateRoot(), "backups"); }
+/** What `planrails run` recorded about each fresh session. */
+export function runsRoot() { return join(stateRoot(), "runs"); }
+
+/** The files of one plan. Each has ONE job and ONE writer (see docs/PLANNING_GUIDE.md § The files). */
+export const FILES = {
+  planMd: "PLAN.md",            // narrative — hand-written, stable
+  state: "state.json",          // manifest + tasks — CLI-written after creation
+  gates: "gates.json",          // gate definitions — planner-written, validated
+  rules: "rules.json",          // just-in-time rules — planner-written, validated
+  log: "log.jsonl",             // progress — CLI append
+  learnings: "learnings.jsonl", // CLI append
+  decisions: "decisions.jsonl", // CLI append
+  gateRuns: "gate-runs.jsonl",  // CLI append — every gate execution
+};

package/src/plan/lib/schema.mjs

@@ -0,0 +1,199 @@
+/**
+ * The shape of every plan file, declared ONCE.
+ *
+ * Why strict objects: an unregistered key is refused, the same rule the corpus
+ * gate applies (scripts/corpus/structure.mjs). Before that rule, a field could
+ * appear in one book and be invisible in the other thirty. Same risk here: a
+ * plan that spells "evidence" as "proof" would pass a loose schema and the
+ * done-needs-evidence check would never see it.
+ *
+ * Why the minimum lengths: a task titled "fix" and a gate whose question is
+ * "works?" are the shapes that let a completion claim through unread.
+ */
+import { z } from "zod";
+
+export const PLAN_ID = z.string().regex(/^[a-z0-9][a-z0-9-]{1,63}$/, "kebab-case, 2–64 chars");
+export const TASK_ID = z.string().regex(/^T\d+$/, "T1, T2 …");
+export const GATE_ID = z.string().regex(/^G\d+$/, "G1, G2 …");
+export const RULE_ID = z.string().regex(/^R\d+$/, "R1, R2 …");
+export const LEARNING_ID = z.string().regex(/^L\d+$/, "L1, L2 …");
+export const DECISION_ID = z.string().regex(/^D\d+$/, "D1, D2 …");
+const ISO = z.iso.datetime({ offset: true });
+const DATE = z.iso.date();
+
+export const EFFORT = z.enum(["max", "xhigh", "high"]);
+export const TASK_STATUS = z.enum(["todo", "doing", "done", "blocked", "dropped"]);
+export const PLAN_STATUS = z.enum(["draft", "active", "paused", "done", "abandoned"]);
+
+/**
+ * How a task got to `done`. A gate run the CLI recorded, or a person's word
+ * with a reason. Nothing else. `by: "owner"` means the executor asked the
+ * owner in chat and the owner said yes — the guide says so, the schema
+ * cannot check it.
+ */
+export const Evidence = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("gate"), gate: GATE_ID, runId: z.string().min(8), at: ISO }),
+  z.strictObject({
+    kind: z.literal("manual"),
+    by: z.enum(["owner", "agent"]),
+    at: ISO,
+    reason: z.string().min(20, "say what was checked and how (≥ 20 chars)"),
+  }),
+]);
+
+export const STATEMENT_ID = z.string().regex(/^C\d+$/, "C1, C2 …");
+export const STATEMENT_KIND = z.enum(["auto:gate", "auto:logged", "auto:files", "manual"]);
+/** A condition of done. auto:* kinds are evaluated by the CLI; manual ones need an answer in words. */
+/** since: when a plan-level condition was added with `plan condition add`; a task closed before then is not held to it. Absent on the defaults. */
+export const Statement = z.strictObject({ id: STATEMENT_ID, statement: z.string().min(10), kind: STATEMENT_KIND, since: ISO.nullable().optional() });
+/** What was actually answered when the task was closed. Stored on the task so `plan review` can show it. */
+export const ChecklistEntry = z.strictObject({ id: STATEMENT_ID, statement: z.string().min(10), kind: STATEMENT_KIND, answer: z.string().min(10, "answer in at least 10 characters — say what you checked"), at: ISO });
+/** Every plan starts with these; a plan may edit them, a task may add its own. */
+export const DEFAULT_DONE_WHEN = [
+  { id: "C1", statement: "The task's gate ran in this very command and passed — or a manual reason names who checked it and how.", kind: "auto:gate" },
+  { id: "C2", statement: "A log entry names this task and was written after it started, saying what landed and what comes next.", kind: "auto:logged" },
+  { id: "C3", statement: "Every file this task lists exists on disk.", kind: "auto:files" },
+  { id: "C4", statement: "The docs that describe this change shipped in the same change — name them, or say why none were needed.", kind: "manual" },
+  { id: "C5", statement: "Every number in the log entry and in any report carries a locator (file:line, page, verse) or was re-derived — say which.", kind: "manual" },
+  { id: "C6", statement: "Anything learned or decided while doing this is recorded with plan learn / plan decide — name the ids, or say nothing was.", kind: "manual" },
+  { id: "C7", statement: "You read the changed files whole, against the task's purpose and the app they live in, and judged the result right yourself — say what you read, what you looked for, and what the gate could not see.", kind: "manual" },
+];
+
+export const Task = z.strictObject({
+  id: TASK_ID,
+  title: z.string().min(8),
+  status: TASK_STATUS,
+  /** The gate whose pass means done. null only when manualCheck says who verifies and how. */
+  gate: GATE_ID.nullable(),
+  manualCheck: z.string().min(12).nullable(),
+  files: z.array(z.string()),
+  effort: EFFORT.nullable(),
+  dependsOn: z.array(TASK_ID),
+  notes: z.string(),
+  startedAt: ISO.nullable(),
+  doneAt: ISO.nullable(),
+  evidence: Evidence.nullable(),
+  blocked: z.strictObject({ reason: z.string().min(8), since: ISO, needs: z.enum(["owner", "external", "self"]) }).nullable(),
+  /** Task-specific conditions of done, on top of the plan's doneWhen. */
+  doneWhen: z.array(Statement).default([]),
+  /** The answers given when the task was closed. Empty on a task that is not done. */
+  doneChecklist: z.array(ChecklistEntry).default([]),
+});
+
+export const State = z.strictObject({
+  id: PLAN_ID,
+  title: z.string().min(8),
+  status: PLAN_STATUS,
+  created: DATE,
+  activatedAt: ISO.nullable(),
+  closedAt: ISO.nullable(),
+  /** Repo-relative globs the plan's work lands in. The Stop hook watches them. */
+  paths: z.array(z.string().min(1)),
+  /** Conditions every task must satisfy before `task done` accepts it. Seeded with DEFAULT_DONE_WHEN. */
+  doneWhen: z.array(Statement).default(() => structuredClone(DEFAULT_DONE_WHEN)),
+  tasks: z.array(Task),
+});
+
+export const Gate = z.strictObject({
+  id: GATE_ID,
+  /** What the command LITERALLY answers. Not what you hope it answers. */
+  question: z.string().min(20),
+  /** The nearby question it does NOT answer — the one a reader will assume it does. */
+  notTheSameAs: z.string().min(10),
+  command: z.string().min(3),
+  passWhen: z.union([z.literal("exit0"), z.strictObject({ stdoutMatches: z.string().min(1) })]),
+  timeoutSec: z.number().int().positive().max(3600),
+  /** A case that MUST fail. Run by `gate verify`. A gate that has never failed has never been tested. */
+  /** expectExit: the exit code the failing case must produce (default: any non-zero). A usage error (127, 2) must not count as "the gate saw the problem". */
+  knownFail: z.strictObject({ command: z.string().min(3), description: z.string().min(10), expectExit: z.number().int().nullable().optional() }).nullable(),
+  /** The honest answer to "what would still pass if the thing this protects broke?" */
+  couldPassWhileWrongIf: z.string().min(20),
+  /** static reads files · runtime executes code · reality observes the live system · report never fails, only informs */
+  kind: z.enum(["static", "runtime", "reality", "report"]),
+});
+export const Gates = z.strictObject({ gates: z.array(Gate) });
+
+/** When a rule fires. `tool` is a regex over tool names; the others narrow it. */
+export const RuleWhen = z.strictObject({
+  tool: z.string().min(1),
+  path: z.string().min(1).optional(),      // glob, repo-relative, for Edit/Write/Read/NotebookEdit file_path
+  command: z.string().min(1).optional(),   // regex, for Bash command
+  prompt: z.string().min(1).optional(),    // regex, for Agent prompt / Workflow script
+});
+export const Rule = z.strictObject({
+  id: RULE_ID,
+  when: RuleWhen,
+  /** ≤ 1200 chars (~300 tokens). Longer belongs in `file`, and a file should still be short. */
+  text: z.string().min(10).max(1200).optional(),
+  file: z.string().min(1).optional(),
+  /** once per session (default) · always · every:N calls */
+  repeat: z.union([z.literal("once"), z.literal("always"), z.string().regex(/^every:\d+$/)]).default("once"),
+  /** The case that taught it. Kept for the reader; not injected. */
+  why: z.string().min(10),
+  learning: LEARNING_ID.nullable(),
+}).refine((r) => Boolean(r.text) !== Boolean(r.file), { message: "a rule has exactly one of text or file" });
+export const Rules = z.strictObject({ rules: z.array(Rule) });
+
+export const LogEntry = z.strictObject({
+  at: ISO,
+  session: z.string().nullable(),
+  task: TASK_ID.nullable(),
+  what: z.string().min(10),
+  /** The exact next action, executable by a stranger. This is what the brief shows as RESUME. */
+  next: z.string().min(5),
+  refs: z.array(z.string()),
+  uncommitted: z.string().nullable(),
+});
+
+export const Learning = z.strictObject({
+  id: LEARNING_ID,
+  at: ISO,
+  session: z.string().nullable(),
+  task: TASK_ID.nullable(),
+  /** The case, with its numbers and paths. */
+  what: z.string().min(20),
+  /** The general rule it teaches. */
+  rule: z.string().min(10),
+  appliesWhen: z.string().min(5),
+  /** prose = must be read · rule = injected by the hook (rules.json) · gate = machine-checked · docs = written into a guide */
+  enforcement: z.enum(["prose", "rule", "gate", "docs"]),
+  ref: z.string().nullable(),
+  /** lead = needs a second reader before anyone acts on it */
+  status: z.enum(["lead", "confirmed", "retracted"]),
+});
+
+export const Decision = z.strictObject({
+  id: DECISION_ID,
+  at: ISO,
+  session: z.string().nullable(),
+  task: TASK_ID.nullable(),
+  decision: z.string().min(10),
+  why: z.string().min(10),
+  rejected: z.array(z.strictObject({ option: z.string().min(1), why: z.string().min(1) })),
+  by: z.enum(["owner", "agent"]),
+  supersedes: DECISION_ID.nullable(),
+});
+
+export const GateRun = z.strictObject({
+  runId: z.string().min(8),
+  gate: GATE_ID,
+  /** run = the gate itself · verify = its knownFail case (which must FAIL) */
+  kind: z.enum(["run", "verify"]),
+  at: ISO,
+  session: z.string().nullable(),
+  command: z.string(),
+  exit: z.number().int().nullable(),
+  durationMs: z.number().int().nonnegative(),
+  result: z.enum(["pass", "fail", "error"]),
+  /** Last lines of output — enough to see WHY, never the whole log. */
+  tail: z.string().max(4000),
+  /** verify runs only: the gate's MAIN command at the time it was verified. A gate whose command changed since is not verified until gate verify runs again. */
+  gateCommand: z.string().nullable().optional(),
+});
+
+export const SCHEMAS = { State, Gates, Rules, LogEntry, Learning, Decision, GateRun, Task, Gate, Rule, Statement, ChecklistEntry };
+
+/** "state.json › tasks[2].evidence: expected …" — one line per issue, paths a reader can follow. */
+export function formatIssues(file, error) {
+  return error.issues.map((i) => `${file} › ${i.path.length ? i.path.join(".") : "(root)"}: ${i.message}`);
+}