planrails 0.1.0

package/src/hooks/precompact-journal.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// PreCompact — writes what this stretch of work actually DID to disk, before
+// compaction throws it away.
+//
+// Why this exists. Compaction keeps the user's messages and discards every tool
+// result. Project instructions (CLAUDE.md) survive, because they are rebuilt each
+// request; what is lost is progress state: which files were written, which
+// commands and gates were run, which searches came back empty. That is the real
+// cause of re-doing work after a compaction. This hook writes that record to
+// .planrails/journal/<session>.md, and postcompact-journal.mjs hands the path back.
+//
+// Reads only the TAIL of the transcript (it can be hundreds of MB). That is
+// correct, not a shortcut: this hook runs at EVERY compaction, so earlier
+// stretches were already journaled by earlier runs.
+
+import { openSync, fstatSync, readSync, closeSync, mkdirSync, appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { projectRoot, journalRoot } from "../plan/lib/paths.mjs";
+const TAIL_BYTES = 12 * 1024 * 1024;
+const PROJECT = projectRoot();
+const OUT_DIR = journalRoot();
+
+function readTail(path, bytes) {
+  const fd = openSync(path, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - bytes);
+    const len = size - start;
+    const buf = Buffer.allocUnsafe(len);
+    readSync(fd, buf, 0, len, start);
+    const text = buf.toString("utf8");
+    return start > 0 ? text.slice(text.indexOf("\n") + 1) : text;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, "utf8")); } catch { process.exit(0); }
+
+const transcript = String(input.transcript_path || "");
+const sid = String(input.session_id || "unknown").replace(/[^A-Za-z0-9_-]/g, "");
+const trigger = String(input.trigger || input.matcher || "auto");
+
+if (!transcript || !existsSync(transcript)) process.exit(0);
+
+let lines = [];
+try { lines = readTail(transcript, TAIL_BYTES).split("\n"); } catch { process.exit(0); }
+
+const wrote = new Set();      // files created or edited
+const ran = [];               // gates, scripts, commits
+const readNonImage = new Set();
+let images = 0;
+let lastUser = "";
+let sinceBoundary = false;
+
+// Walk backwards to the most recent compaction boundary, then forward from there.
+let startIdx = 0;
+for (let i = lines.length - 1; i >= 0; i--) {
+  if (lines[i].includes("compact_boundary") || lines[i].includes('"isCompactSummary":true')) { startIdx = i; break; }
+}
+
+for (let i = startIdx; i < lines.length; i++) {
+  const raw = lines[i];
+  if (!raw) continue;
+  let d;
+  try { d = JSON.parse(raw); } catch { continue; }
+  sinceBoundary = true;
+  const m = d.message || {};
+  // Real user intent only — skip slash-command echoes and local-command stdout,
+  // which are shaped like user messages but say nothing about the work.
+  if (m.role === "user" && typeof m.content === "string" && !d.isMeta &&
+      !/^\s*<(local-command|command-name|command-message|command-args)/.test(m.content)) {
+    lastUser = m.content.slice(0, 400);
+  }
+  const c = m.content;
+  if (!Array.isArray(c)) continue;
+  for (const b of c) {
+    if (!b || b.type !== "tool_use") continue;
+    const i_ = b.input || {};
+    if (b.name === "Write" || b.name === "Edit" || b.name === "NotebookEdit") {
+      const f = String(i_.file_path || "");
+      if (f) wrote.add(f.replace(PROJECT + "/", ""));
+    } else if (b.name === "Read") {
+      const f = String(i_.file_path || "");
+      if (/\.(png|jpe?g|webp|tiff?|gif)$/i.test(f)) images++;
+      else if (f) readNonImage.add(f.replace(PROJECT + "/", ""));
+    } else if (b.name === "Bash") {
+      // Match the FIRST LINE only. A heredoc body often quotes "npm run …" inside
+      // prose, which made the journal record documents as if they were commands.
+      const first = String(i_.command || "").split("\n")[0].replace(/\s+/g, " ").trim();
+      if (/(^|\s|&&|;)(node |npm |npx |pnpm |yarn |git commit|git push|make |cargo |go |python)/.test(first)) {
+        ran.push(first.slice(0, 160));
+      }
+    }
+  }
+}
+
+if (!sinceBoundary) process.exit(0);
+
+const stamp = new Date().toISOString();
+const out = [];
+out.push(`\n## ${stamp} — before ${trigger} compaction`);
+if (lastUser) out.push(`\n**Working on:** ${lastUser.replace(/\n/g, " ")}`);
+const section = (title, items, cap = 40) => {
+  const a = [...items];
+  if (!a.length) return;
+  out.push(`\n**${title}** (${a.length})`);
+  for (const x of a.slice(0, cap)) out.push(`- ${x}`);
+  if (a.length > cap) out.push(`- …and ${a.length - cap} more`);
+};
+section("Files written or edited", wrote);
+section("Scripts, gates and git run", ran, 25);
+section("Files read (not images)", readNonImage, 30);
+if (images) out.push(`\n**Images read in this thread:** ${images}`);
+out.push(`\n> Written by planrails (precompact-journal.mjs). Tool results are gone after this point; this file is what survives.\n`);
+
+try {
+  mkdirSync(OUT_DIR, { recursive: true });
+  const path = join(OUT_DIR, `${sid}.md`);
+  appendFileSync(path, out.join("\n"));
+  process.stdout.write(JSON.stringify({
+    systemMessage: `Progress journalled before compaction → .planrails/journal/${sid}.md`,
+    suppressOutput: true,
+  }));
+} catch { /* never block a compaction */ }
+process.exit(0);

package/src/hooks/selftest.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Self-test for the plan-system hooks. Every payload shape below was captured
+ * from a real Claude Code 2.1.269 run on 2026-09-12 (SessionStart carries
+ * `source`; Stop carries `stop_hook_active` and `last_assistant_message`;
+ * subagents add `agent_id`). The hooks run against a throwaway project root
+ * with one active plan, so nothing here touches the real repository.
+ *
+ * Run: npx planrails hooks selftest   (also: npx planrails hooks selftest)
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const box = mkdtempSync(join(tmpdir(), "plan-hooks-selftest-"));
+const env = { ...process.env, PLAN_PROJECT_ROOT: box, TMPDIR: box };
+const plan = join(box, ".project-management", "plans", "p1");
+mkdirSync(plan, { recursive: true });
+mkdirSync(join(box, "src"), { recursive: true });
+writeFileSync(join(box, "CLAUDE.md"), "# t\n\n## Project management\n");
+writeFileSync(join(plan, "PLAN.md"), "# p1\n\n## Why\nTo test the hooks.\n\n## Rules for this plan\n1. Rule one.\n");
+writeFileSync(join(plan, "state.json"), JSON.stringify({
+  id: "p1", title: "hook selftest plan", status: "active", created: "2026-09-12", activatedAt: "2026-09-12T10:00:00+05:30", closedAt: null, paths: ["src/**"],
+  tasks: [{ id: "T1", title: "the only task", status: "doing", gate: "G1", manualCheck: null, files: [], effort: null, dependsOn: [], notes: "", startedAt: "2026-09-12T10:00:00+05:30", doneAt: null, evidence: null, blocked: null }],
+}));
+writeFileSync(join(plan, "gates.json"), JSON.stringify({ gates: [{ id: "G1", question: "does true exit zero in this shell", notTheSameAs: "anything real", command: "true", passWhen: "exit0", timeoutSec: 10, knownFail: null, couldPassWhileWrongIf: "true is always true, which is the point", kind: "static" }] }));
+writeFileSync(join(plan, "rules.json"), JSON.stringify({ rules: [
+  { id: "R1", when: { tool: "Edit|Write", path: "src/**/*.ts" }, text: "RULE-MARKER-XYZ: check the thing before editing.", repeat: "once", why: "selftest", learning: null },
+  { id: "R2", when: { tool: "Bash", command: "npm run check" }, text: "BASH-RULE-MARKER: save the output to a file, read the exit code.", repeat: "always", why: "selftest", learning: null },
+] }));
+writeFileSync(join(plan, "log.jsonl"), JSON.stringify({ at: "2026-01-01T00:00:00+05:30", session: null, task: "T1", what: "an old entry", next: "RESUME-MARKER do the next thing", refs: [], uncommitted: null }) + "\n");
+for (const f of ["learnings.jsonl", "decisions.jsonl", "gate-runs.jsonl"]) writeFileSync(join(plan, f), "");
+
+const BASE = { session_id: "sess-selftest-1", transcript_path: join(box, "t.jsonl"), cwd: box, permission_mode: "bypassPermissions" };
+function run(hook, payload, opts = {}) {
+  const r = spawnSync(opts.runner || "node", [join(HERE, hook)], { input: JSON.stringify(payload), env, encoding: "utf8" });
+  return { out: r.stdout || "", err: r.stderr || "", status: r.status };
+}
+const results = [];
+const check = (name, cond, detail = "") => { results.push([name, Boolean(cond), detail]); };
+
+// SessionStart injects the brief
+let r = run("plan-session-start.mjs", { ...BASE, hook_event_name: "SessionStart", source: "startup" });
+check("SessionStart injects the active plan's brief", r.out.includes("additionalContext") && r.out.includes("Plan p1") && r.out.includes("RESUME-MARKER"), r.out.slice(0, 200) + r.err.slice(0, 300));
+check("SessionStart records the session id for the CLI", existsSync(join(box, ".planrails", "hooks", "current-session.json")));
+
+// PreToolUse: rule fires once on a matching Edit, records the edit
+const edit = (file) => ({ ...BASE, hook_event_name: "PreToolUse", tool_name: "Edit", tool_input: { file_path: join(box, file), old_string: "a", new_string: "b" } });
+r = run("plan-pre-tool.mjs", edit("src/a.ts"));
+check("PreToolUse injects R1 on a matching Edit", r.out.includes("RULE-MARKER-XYZ") && r.out.includes("additionalContext"), r.out.slice(0, 200) + r.err.slice(0, 300));
+r = run("plan-pre-tool.mjs", edit("src/a.ts"));
+check("R1 (repeat once) does not fire a second time", !r.out.includes("RULE-MARKER-XYZ"), r.out);
+r = run("plan-pre-tool.mjs", edit("docs/x.md"));
+check("no rule fires on a path no rule names", r.out === "", r.out);
+const editsPath = join(box, ".planrails", "hooks", "sess-selftest-1", "edits.jsonl");
+const edits = existsSync(editsPath) ? readFileSync(editsPath, "utf8").trim().split("\n") : [];
+check("edits under the plan's paths are recorded (2), the docs edit is not", edits.length === 2 && edits.every((l) => l.includes("src/a.ts")), `${edits.length}`);
+r = run("plan-pre-tool.mjs", { ...BASE, hook_event_name: "PreToolUse", tool_name: "Bash", tool_input: { command: "npm run check > /tmp/x 2>&1" } });
+const r2 = run("plan-pre-tool.mjs", { ...BASE, hook_event_name: "PreToolUse", tool_name: "Bash", tool_input: { command: "npm run check" } });
+check("R2 (repeat always) fires on every matching Bash", r.out.includes("BASH-RULE-MARKER") && r2.out.includes("BASH-RULE-MARKER"));
+r = run("plan-pre-tool.mjs", { ...BASE, hook_event_name: "PreToolUse", tool_name: "Bash", tool_input: { command: "ls" } });
+check("a Bash rule does not fire on an unrelated command", r.out === "");
+r = run("plan-pre-tool.mjs", { ...edit("src/b.ts"), agent_id: "agent-1", agent_type: "general-purpose" });
+check("a subagent's edit is recorded and marked agent:true", readFileSync(editsPath, "utf8").includes('"agent":true'));
+check("a subagent gets the once-rule even though the main thread already consumed it (dedupe is per agent)", r.out.includes("RULE-MARKER-XYZ"), r.out.slice(0, 120));
+const r4 = run("plan-pre-tool.mjs", { ...edit("src/c.ts"), agent_id: "agent-1", agent_type: "general-purpose" });
+check("…and only once per agent", !r4.out.includes("RULE-MARKER-XYZ"), r4.out);
+
+// Stop: unlogged edits block once; a log entry clears it; stop_hook_active never blocks
+r = run("plan-stop.mjs", { ...BASE, hook_event_name: "Stop", stop_hook_active: false, last_assistant_message: "done" });
+check("Stop blocks when edits under the plan are newer than its last log entry", r.out.includes('"block"') && r.out.includes("src/a.ts") && r.out.includes("planrails log p1 --task T1"), r.out.slice(0, 300) + r.err.slice(0, 300));
+r = run("plan-stop.mjs", { ...BASE, hook_event_name: "Stop", stop_hook_active: false, last_assistant_message: "done" });
+check("Stop does not nag twice for the same unlogged stretch", r.out === "", r.out);
+r = run("plan-stop.mjs", { ...BASE, hook_event_name: "Stop", stop_hook_active: true, last_assistant_message: "done" });
+check("Stop with stop_hook_active never blocks", r.out === "");
+appendFileSync(join(plan, "log.jsonl"), JSON.stringify({ at: new Date(Date.now() + 60_000).toISOString(), session: null, task: "T1", what: "logged the edits", next: "carry on", refs: [], uncommitted: null }) + "\n");
+r = run("plan-stop.mjs", { ...BASE, session_id: "sess-selftest-2", hook_event_name: "Stop", stop_hook_active: false });
+check("Stop allows once a log entry is newer than the edits", r.out === "", r.out);
+
+// SubagentStart: the do-nots reach a subagent; silent with no active plan
+r = run("plan-subagent-start.mjs", { ...BASE, hook_event_name: "SubagentStart", agent_id: "afa51b8bffc11199f", agent_type: "general-purpose" });
+check("SubagentStart injects the subagent note naming the plan's reports directory", r.out.includes("SUBAGENT NOTE") && r.out.includes("plans/p1/reports/") && r.out.includes("never run"), r.out.slice(0, 200) + r.err.slice(0, 200));
+check("the subagent note stays under 900 chars", (JSON.parse(r.out || "{}").hookSpecificOutput?.additionalContext || "").length < 900);
+
+// compaction resets once-per-session injections
+r = run("plan-session-start.mjs", { ...BASE, hook_event_name: "SessionStart", source: "compact" });
+check("SessionStart(compact) re-injects the brief and says tool results are gone", r.out.includes("Plan p1") && r.out.includes("compacted"));
+r = run("plan-pre-tool.mjs", edit("src/a.ts"));
+check("after compaction, a once-rule fires again", r.out.includes("RULE-MARKER-XYZ"), r.out.slice(0, 100));
+
+// no active plan → hooks are silent
+writeFileSync(join(plan, "state.json"), readFileSync(join(plan, "state.json"), "utf8").replace('"status":"active"', '"status":"paused"'));
+r = run("plan-session-start.mjs", { ...BASE, session_id: "sess-3", hook_event_name: "SessionStart", source: "startup" });
+const r3 = run("plan-pre-tool.mjs", { ...edit("src/a.ts"), session_id: "sess-3" });
+const r5 = run("plan-subagent-start.mjs", { ...BASE, session_id: "sess-3", hook_event_name: "SubagentStart", agent_id: "x", agent_type: "general-purpose" });
+check("with no active plan, SessionStart, PreToolUse and SubagentStart output nothing", r.out === "" && r3.out === "" && r5.out === "");
+
+// the optional never-delete guard (needs jq). The delete command is
+// assembled at runtime so this file never contains it as a word: the hook under
+// test fires on the WORD, wherever it appears — including inside a heredoc that
+// writes this file.
+if (spawnSync("which", ["jq"]).status === 0) {
+  const deleteCmd = ["r", "m"].join("") + " -rf build/x";
+  r = run("guard-never-delete.sh", { ...BASE, hook_event_name: "PreToolUse", tool_name: "Bash", tool_input: { command: deleteCmd } }, { runner: "bash" });
+  const ok = run("guard-never-delete.sh", { ...BASE, hook_event_name: "PreToolUse", tool_name: "Bash", tool_input: { command: "npm run check" } }, { runner: "bash" });
+  check("the never-delete guard denies a delete command and allows npm", r.out.includes('"deny"') && ok.out === "");
+} else check("never-delete guard: jq missing — SKIPPED (brew install jq)", true);
+
+// journal pair
+const transcript = join(box, "t.jsonl");
+writeFileSync(transcript, [
+  JSON.stringify({ message: { role: "user", content: "Working on the selftest" } }),
+  JSON.stringify({ message: { role: "assistant", content: [{ type: "tool_use", name: "Edit", input: { file_path: join(box, "src/a.ts") } }] } }),
+  JSON.stringify({ message: { role: "assistant", content: [{ type: "tool_use", name: "Bash", input: { command: "npx planrails validate" } }] } }),
+].join("\n") + "\n");
+r = run("precompact-journal.mjs", { ...BASE, hook_event_name: "PreCompact", trigger: "auto" });
+const journal = join(box, ".planrails", "journal", "sess-selftest-1.md");
+check("PreCompact writes the session journal with the edited file and the command", existsSync(journal) && readFileSync(journal, "utf8").includes("src/a.ts") && readFileSync(journal, "utf8").includes("planrails validate"), r.out + r.err.slice(0, 200));
+r = run("postcompact-journal.mjs", { ...BASE, hook_event_name: "PostCompact" });
+check("PostCompact hands back the journal path", r.out.includes(".planrails/journal/sess-selftest-1.md"));
+
+let bad = 0;
+for (const [name, ok, detail] of results) { if (!ok) bad++; process.stdout.write(`${ok ? "ok  " : "FAIL"} ${name}${ok ? "" : ` — ${detail}`}\n`); }
+process.stdout.write(bad ? `\nhooks selftest: ${bad} FAILED\n` : `\nhooks selftest: ${results.length} checks pass\n`);
+process.exit(bad ? 1 : 0);

package/src/init.mjs

@@ -0,0 +1,155 @@
+/**
+ * `planrails init` — set a project up, new or existing, without breaking anything
+ * that is already there. Idempotent: run it twice and the second run changes
+ * nothing and says so.
+ *
+ * What it does, in order:
+ *   1. finds the project root (the cwd, or --dir)
+ *   2. writes a minimal package.json if there is none
+ *   3. installs planrails as a devDependency, unless it already is (or --no-install)
+ *   4. copies docs/PLANNING_GUIDE.md into the project (kept if it already exists; --force overwrites)
+ *   5. creates .project-management/plans/
+ *   6. creates CLAUDE.md, or adds a "## Project management" section to the existing one,
+ *      and puts the generated plans block above it
+ *   7. adds npm scripts: plan, plan:doctor, plan:brief, plan:validate — and appends
+ *      the validator to an existing "check" script
+ *   8. adds .planrails/ to .gitignore
+ *   9. installs the hooks into .claude/settings.json and the /plan skill
+ *  10. runs doctor
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, appendFileSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { spawnSync } from "node:child_process";
+import { projectRoot, packageRoot, claudeMdPath, plansRoot, cliName } from "./plan/lib/paths.mjs";
+import { writeBlock, readBlock } from "./plan/lib/claude-md.mjs";
+
+const PM_SECTION = `## Project management
+
+Multi-session work is tracked as **plans** under \`.project-management/plans/<id>/\`
+(planrails). Create one with \`/plan <raw plan>\`. A SessionStart hook injects every
+active plan's brief at the start of a session and after every compaction;
+\`npx planrails brief\` prints it. A task is done only when \`npx planrails task done\`
+has run its gate and every condition of done is answered. Judgment outranks the
+gate: never make a red gate pass, never trust a green one blind. Guide:
+\`docs/PLANNING_GUIDE.md\`.
+`;
+
+function pkgVersion() { return JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8")).version; }
+function readJson(p, fallback) { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return fallback; } }
+
+export async function init({ dir = null, force = false, noInstall = false, withNeverDelete = false, dryRun = false, log = console.log } = {}) {
+  if (dir) process.env.PLAN_PROJECT_ROOT = resolve(dir);
+  const root = projectRoot();
+  const cli = cliName();
+  const did = []; const kept = [];
+  const note = (changed, text) => (changed ? did : kept).push(text);
+  const write = (p, text) => { if (!dryRun) writeFileSync(p, text); };
+  log(`planrails ${pkgVersion()} → ${root}${dryRun ? "  (dry run: nothing is written)" : ""}`);
+  mkdirSync(root, { recursive: true });
+
+  // 2. package.json
+  const pkgPath = join(root, "package.json");
+  let pkg = readJson(pkgPath, null);
+  if (!pkg) { pkg = { name: basename(root).toLowerCase().replace(/[^a-z0-9._-]+/g, "-") || "project", version: "0.0.0", private: true }; write(pkgPath, JSON.stringify(pkg, null, 2) + "\n"); note(true, "wrote a minimal package.json"); }
+  else note(false, "package.json exists");
+
+  // 3. the devDependency
+  const installed = existsSync(join(root, "node_modules", "planrails", "package.json"));
+  const declared = Boolean(pkg.devDependencies?.planrails || pkg.dependencies?.planrails);
+  if (installed && declared) note(false, `planrails is a dependency (${readJson(join(root, "node_modules", "planrails", "package.json"), {}).version || "?"})`);
+  else if (noInstall || dryRun) note(false, `planrails not installed as a dependency (${noInstall ? "--no-install" : "dry run"}); hooks will use this copy's absolute path`);
+  else {
+    log(`installing planrails@${pkgVersion()} as a devDependency…`);
+    const r = spawnSync("npm", ["install", "--save-dev", `planrails@${pkgVersion()}`], { cwd: root, stdio: "inherit" });
+    if (r.status !== 0) { log(`npm install failed (exit ${r.status}). Fix that, or run with --no-install to continue with absolute hook paths.`); return 1; }
+    note(true, `installed planrails@${pkgVersion()} as a devDependency`);
+    pkg = readJson(pkgPath, pkg);
+  }
+
+  // 4. the guide
+  const guideSrc = join(packageRoot(), "docs", "PLANNING_GUIDE.md");
+  const guideDest = join(root, "docs", "PLANNING_GUIDE.md");
+  if (!existsSync(guideDest)) { if (!dryRun) { mkdirSync(join(root, "docs"), { recursive: true }); copyFileSync(guideSrc, guideDest); } note(true, "copied docs/PLANNING_GUIDE.md"); }
+  else if (readFileSync(guideDest, "utf8") === readFileSync(guideSrc, "utf8")) note(false, "docs/PLANNING_GUIDE.md is current");
+  else if (force) { if (!dryRun) copyFileSync(guideSrc, guideDest); note(true, "overwrote docs/PLANNING_GUIDE.md (--force)"); }
+  else note(false, `docs/PLANNING_GUIDE.md differs from this version's copy — keep yours, or refresh it with: ${cli} update`);
+
+  // 5. plans directory
+  const plans = plansRoot();
+  if (!existsSync(plans)) { if (!dryRun) { mkdirSync(plans, { recursive: true }); writeFileSync(join(plans, ".gitkeep"), ""); } note(true, "created .project-management/plans/"); }
+  else note(false, ".project-management/plans/ exists");
+
+  // 6. CLAUDE.md
+  const md = claudeMdPath();
+  if (!existsSync(md)) { write(md, `# CLAUDE.md\n\nInstructions for AI agents working in this repository. Keep this file short; put depth in docs/.\n\n${PM_SECTION}`); note(true, "created CLAUDE.md with a Project management section"); }
+  else {
+    const text = readFileSync(md, "utf8");
+    if (!/^## Project management\s*$/m.test(text)) { write(md, `${text.replace(/\s*$/, "")}\n\n${PM_SECTION}`); note(true, "added a Project management section to CLAUDE.md"); }
+    else note(false, "CLAUDE.md has a Project management section");
+  }
+  if (!dryRun) {
+    const before = existsSync(md) ? readFileSync(md, "utf8") : "";
+    if (!readBlock(before)) {
+      // Reflect the plans that already exist (an existing project may have some).
+      const active = [];
+      try { const { activePlanIds, loadPlanCheap } = await import("./plan/lib/store.mjs"); for (const id of activePlanIds()) { const p = loadPlanCheap(id); active.push({ id, title: p.state?.title || id }); } } catch { /* none */ }
+      writeBlock(md, active);
+      note(true, "added the generated plans block to CLAUDE.md");
+    } else note(false, "CLAUDE.md has the plans block");
+  }
+
+  // 7. npm scripts
+  pkg = readJson(pkgPath, pkg);
+  pkg.scripts = pkg.scripts || {};
+  const want = { plan: "planrails", "plan:doctor": "planrails doctor", "plan:brief": "planrails brief", "plan:validate": "planrails validate --all --quiet" };
+  let scriptsChanged = false;
+  for (const [k, v] of Object.entries(want)) if (!pkg.scripts[k]) { pkg.scripts[k] = v; scriptsChanged = true; }
+  if (pkg.scripts.check && !/planrails validate/.test(pkg.scripts.check)) { pkg.scripts.check = `${pkg.scripts.check} && planrails validate --all --quiet`; scriptsChanged = true; }
+  if (scriptsChanged) { write(pkgPath, JSON.stringify(pkg, null, 2) + "\n"); note(true, `added npm scripts (plan, plan:doctor, plan:brief, plan:validate${pkg.scripts.check ? "; validator appended to check" : ""})`); }
+  else note(false, "npm scripts present");
+
+  // 8. .gitignore
+  const gi = join(root, ".gitignore");
+  const giText = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/^\.planrails\/?\s*$/m.test(giText)) { if (!dryRun) appendFileSync(gi, `${giText && !giText.endsWith("\n") ? "\n" : ""}.planrails/\n`); note(true, "added .planrails/ to .gitignore"); }
+  else note(false, ".gitignore ignores .planrails/");
+
+  // 9. hooks + skill
+  const { install, status } = await import("./hooks/install.mjs");
+  const r = install({ dryRun, withNeverDelete });
+  note(r.changed, r.changed ? "wrote the hooks into .claude/settings.json" : "hooks already installed");
+
+  log("");
+  for (const d of did) log(`  + ${d}`);
+  for (const k of kept) log(`  = ${k}`);
+  if (dryRun) { log("\n(dry run) nothing was written."); return 0; }
+  // 10. doctor
+  const { problems } = status({ print: false });
+  log(problems ? `\ndoctor: ${problems} problem(s) — run: ${cli} doctor` : "\ndoctor: healthy");
+  log(`\nNext: restart Claude Code (or run /hooks), then type:  /plan <your raw plan>\nGuide: docs/PLANNING_GUIDE.md · commands: ${cli} --help`);
+  return problems ? 1 : 0;
+}
+
+/** Refresh the guide, the skill and the hook entries to this version. Plans are never touched. */
+export async function update({ dir = null, log = console.log } = {}) {
+  if (dir) process.env.PLAN_PROJECT_ROOT = resolve(dir);
+  const root = projectRoot();
+  const guideSrc = join(packageRoot(), "docs", "PLANNING_GUIDE.md");
+  const guideDest = join(root, "docs", "PLANNING_GUIDE.md");
+  if (!existsSync(guideDest) || readFileSync(guideDest, "utf8") !== readFileSync(guideSrc, "utf8")) { mkdirSync(join(root, "docs"), { recursive: true }); copyFileSync(guideSrc, guideDest); log("refreshed docs/PLANNING_GUIDE.md"); }
+  else log("docs/PLANNING_GUIDE.md is current");
+  const { install, status } = await import("./hooks/install.mjs");
+  install({});
+  const { problems } = status({ print: false });
+  log(problems ? `doctor: ${problems} problem(s) — run: ${cliName()} doctor` : "doctor: healthy");
+  return problems ? 1 : 0;
+}
+
+/** Remove the hooks and the skill. Plans, the guide, CLAUDE.md and package.json are left as they are. */
+export async function uninstall({ dir = null, log = console.log } = {}) {
+  if (dir) process.env.PLAN_PROJECT_ROOT = resolve(dir);
+  const { install } = await import("./hooks/install.mjs");
+  install({ remove: true });
+  log(`Left in place on purpose: .project-management/plans/, docs/PLANNING_GUIDE.md, the CLAUDE.md section and block, the npm scripts. Remove those by hand if you want them gone; npm uninstall planrails removes the package.`);
+  return 0;
+}

package/src/issue.mjs

@@ -0,0 +1,55 @@
+/**
+ * `planrails issue [bug|wish|edge] [--title "…"] [--print] [--gh]`
+ *
+ * Opens a prefilled GitHub issue for this project's planrails install: the
+ * version, Node, the platform, the Claude Code version, and what doctor and
+ * validate say — never file contents, never plan text. Opens the browser by
+ * default; --print prints the URL; --gh uses the GitHub CLI instead.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { packageRoot, projectRoot } from "./plan/lib/paths.mjs";
+
+export const REPO = "vivmagarwal/planrails";
+const TEMPLATES = { bug: "bug.yml", wish: "wish.yml", edge: "edge-case.yml" };
+
+function versionOf(cmd, args) { try { const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 4000 }); return r.status === 0 ? r.stdout.trim().split("\n")[0] : null; } catch { return null; } }
+
+export async function environment() {
+  const pkg = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8"));
+  const lines = [`planrails ${pkg.version}`, `node ${process.version} · ${process.platform} ${process.arch}`, `claude: ${versionOf("claude", ["--version"]) || "not on PATH"}`];
+  try {
+    const { status } = await import("./hooks/install.mjs");
+    const s = status({ print: false });
+    lines.push(`hooks: ${s.problems ? `${s.problems} problem(s)` : "ok"} — ${s.lines.filter((l) => !l.ok).map((l) => l.text.replace(projectRoot(), "<project>")).slice(0, 4).join(" | ") || "all installed"}`);
+  } catch (e) { lines.push(`hooks: could not check (${e.message})`); }
+  try {
+    const { listPlanIds, loadPlan, validatePlan } = await import("./plan/lib/store.mjs");
+    const ids = listPlanIds();
+    let errors = 0, warnings = 0; const first = [];
+    for (const id of ids) { try { const v = validatePlan(loadPlan(id)); errors += v.errors.length; warnings += v.warnings.length; for (const e of v.errors.slice(0, 2)) first.push(e); } catch (e) { errors++; first.push(`${id}: ${e.message}`); } }
+    lines.push(`plans: ${ids.length} — ${errors} error(s), ${warnings} warning(s)${first.length ? ` — e.g. ${first.slice(0, 3).join(" | ")}` : ""}`);
+  } catch (e) { lines.push(`plans: could not validate (${e.message})`); }
+  return lines.join("\n");
+}
+
+export async function issue({ kind = "bug", title = "", print = false, gh = false, log = console.log } = {}) {
+  const template = TEMPLATES[kind];
+  if (!template) { log(`issue kind must be one of: ${Object.keys(TEMPLATES).join(", ")}`); return 2; }
+  const env = await environment();
+  const params = new URLSearchParams({ template, title: title || "", environment: env });
+  const url = `https://github.com/${REPO}/issues/new?${params.toString()}`;
+  if (gh) {
+    const body = `### Environment\n\n\`\`\`\n${env}\n\`\`\`\n\n### What happened / what you wish\n\n(fill in)\n\n### Steps or the case\n\n(fill in)\n`;
+    const r = spawnSync("gh", ["issue", "create", "--repo", REPO, "--title", title || `${kind}: (describe)`, "--body", body, "--label", kind === "bug" ? "bug" : kind === "wish" ? "enhancement" : "edge-case"], { stdio: "inherit" });
+    if (r.status === 0) return 0;
+    log(`gh failed (exit ${r.status}); here is the URL instead:`);
+  }
+  log(url);
+  if (print || gh) return 0;
+  const opener = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  const r = spawnSync(opener[0], opener[1], { stdio: "ignore" });
+  if (r.status !== 0) log("(could not open a browser — copy the URL above)");
+  return 0;
+}

package/src/plan/fixtures/README.md

@@ -0,0 +1,7 @@
+# Plan-system fixtures
+
+`broken-root/` is a project root whose one plan LIES: task T1 is `done` citing a
+gate run that is not in `gate-runs.jsonl`. It is the known-fail case for the
+validator gate — `PLAN_PROJECT_ROOT=node_modules/planrails/src/plan/fixtures/broken-root node
+src/plan/plan.mjs validate --all --quiet` must exit 1. If it ever exits 0,
+the validator has stopped seeing fabricated evidence.

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Builds a deliberately BROKEN copy of the plan CLI at .tmp/broken-cli/: the validator no
+ * longer refuses a task that cites a gate run which never happened. Gate G3's known-fail
+ * case runs the vitest suite against this copy (PLAN_CLI=.tmp/broken-cli/plan.mjs) and the
+ * suite must FAIL — that is what proves the suite can see a validator regression, instead of
+ * "vitest exits 1 on a missing file", which proved nothing about the gate.
+ * Refuses to build if the line it removes is not found (the fixture would then test nothing).
+ */
+import { cpSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const src = join(dirname(fileURLToPath(import.meta.url)), "..");
+const root = join(src, "..", "..");
+const out = join(root, ".tmp", "broken-cli");
+mkdirSync(out, { recursive: true });
+for (const f of ["plan.mjs", "run.mjs"]) cpSync(join(src, f), join(out, f));
+cpSync(join(src, "lib"), join(out, "lib"), { recursive: true });
+cpSync(join(src, "skill"), join(out, "skill"), { recursive: true });
+const storePath = join(out, "lib", "store.mjs");
+let store = readFileSync(storePath, "utf8");
+const anchor = "if (!run) E(`${t.id} cites gate run ${t.evidence.runId}, but gate-runs.jsonl has no passing run with that id`);";
+if (!store.includes(anchor)) { console.error("broken-cli: the refusal this fixture removes was not found in store.mjs — update the fixture"); process.exit(3); }
+store = store.replace(anchor, "if (!run) { /* BROKEN ON PURPOSE: a fabricated run is accepted */ }");
+writeFileSync(storePath, store);
+if (!existsSync(join(out, "plan.mjs"))) process.exit(3);
+console.log(`broken CLI built at ${out} (validator accepts a fabricated gate run)`);

package/src/plan/fixtures/broken-hooks-root/.claude/settings.json

@@ -0,0 +1,83 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/plan-session-start.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"/nonexistent-machine/src/hooks/guard-never-delete.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/guard-read.mjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash|Read|Agent|Skill|Workflow",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/plan-pre-tool.mjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/plan-subagent-start.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/plan-stop.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/precompact-journal.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"/nonexistent-machine/src/hooks/postcompact-journal.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,9 @@
+# fixture — a project whose hooks point at files that do not exist
+
+<!-- plans:begin — generated by src/plan/plan.mjs; do not hand-edit this block -->
+## Active plans
+
+_No active plans. Create one with `/plan <raw plan>` or `npx planrails new <id> --title "…"` (docs/PLANNING_GUIDE.md)._
+<!-- plans:end -->
+
+## Project management

package/src/plan/fixtures/broken-root/.project-management/plans/broken/PLAN.md

@@ -0,0 +1,4 @@
+# broken
+
+## Why
+This fixture exists so `plan validate` has a known-fail case: its one task claims a gate run that never happened.

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

@@ -0,0 +1 @@
+{ "gates": [ { "id": "G1", "question": "does the fixture command exit zero", "notTheSameAs": "anything about a real system", "command": "true", "passWhen": "exit0", "timeoutSec": 10, "knownFail": null, "couldPassWhileWrongIf": "it is a fixture; it always passes", "kind": "static" } ] }

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

@@ -0,0 +1 @@
+{ "rules": [] }