planrails 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "planrails",
+  "version": "0.1.0",
+  "description": "Plans that survive compaction, for Claude Code: gates that prove a task done, conditions answered before it closes, briefs and rules injected by hooks, one fresh session per task.",
+  "type": "module",
+  "bin": {
+    "planrails": "bin/planrails.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs/PLANNING_GUIDE.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "scripts": {
+    "test": "node scripts/run-tests.mjs",
+    "selftest": "node bin/planrails.mjs selftest && node src/hooks/selftest.mjs",
+    "acceptance": "node scripts/acceptance.mjs",
+    "trial": "node scripts/trial/run.mjs",
+    "prepack": "npm test"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vivmagarwal/planrails.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vivmagarwal/planrails/issues"
+  },
+  "homepage": "https://github.com/vivmagarwal/planrails#readme",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "agent",
+    "planning",
+    "hooks",
+    "compaction",
+    "gates",
+    "project-management",
+    "ai-agents"
+  ],
+  "author": "vivmagarwal",
+  "license": "MIT"
+}

package/src/hooks/_lib.mjs

@@ -0,0 +1,32 @@
+/**
+ * Shared bits for the plan-system hooks. Hooks run on every tool call, so
+ * everything here is small and synchronous, and NOTHING here may throw out —
+ * a hook that crashes blocks the tool call it was meant to inform.
+ */
+import { readFileSync, mkdirSync, existsSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { hookStateRoot } from "../plan/lib/paths.mjs";
+
+export function readInput() {
+  try { return JSON.parse(readFileSync(0, "utf8")); } catch { return {}; }
+}
+export function sid(input) { return String(input.session_id || "unknown").replace(/[^A-Za-z0-9_-]/g, "") || "unknown"; }
+export function sessionDir(input) {
+  const d = join(hookStateRoot(), sid(input));
+  try { mkdirSync(d, { recursive: true }); } catch { /* best effort */ }
+  return d;
+}
+export function readJsonSafe(path, fallback) {
+  try { return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : fallback; } catch { return fallback; }
+}
+export function writeJsonSafe(path, obj) {
+  try { writeFileSync(path, JSON.stringify(obj)); } catch { /* best effort */ }
+}
+export function appendSafe(path, line) {
+  try { appendFileSync(path, line + "\n"); } catch { /* best effort */ }
+}
+export function emit(obj) { process.stdout.write(JSON.stringify(obj)); }
+/** Add text to Claude's context without blocking anything. Measured to work on 2.1.269 for SessionStart and PreToolUse. */
+export function addContext(eventName, text) {
+  emit({ hookSpecificOutput: { hookEventName: eventName, additionalContext: text }, suppressOutput: true });
+}

package/src/hooks/guard-never-delete.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) — the optional never-delete guard (npx planrails hooks install --with-never-delete).
+# Why: a delete command needs a person to approve it, which turns an unattended run into a stall,
+# and a mistaken delete of ungitted work cannot be undone. Moving aside is always reversible.
+# Uses jq (~8ms) rather than node (~20ms) because this fires on every Bash call.
+# Turn it off with: npx planrails hooks install (without the flag) after removing it, or delete
+# the PreToolUse/Bash entry from .claude/settings.json.
+
+cmd=$(jq -r '.tool_input.command // ""' 2>/dev/null)
+[ -z "$cmd" ] && exit 0
+
+# A leading word boundary that is start-of-string, whitespace, or a shell separator.
+# Deliberately does NOT match "--rm" (docker), "npm", "charm", "./rm" — the char
+# before the word must be a real separator.
+if printf '%s' "$cmd" | grep -qE '(^|[;&|(`]|[[:space:]])(rm|rmdir|unlink|shred)([[:space:]]|$)'; then
+  trash=".planrails/trash/<what>-$(date +%Y-%m-%d)"
+  jq -n --arg t "$trash" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: (
+        "BLOCKED by the never-delete guard (planrails).\n\n" +
+        "A delete needs a person to approve it, which stalls an unattended run; and a mistaken delete of work that is not in git cannot be undone. Move it aside instead:\n  mkdir -p " + $t + " && mv <path> " + $t + "/\n\n" +
+        "Name the reason in the directory name. Emptying the trash is a person'\''s deliberate act, never a step in a flow."
+      )
+    }
+  }'
+fi
+exit 0

package/src/hooks/install.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Install (or remove) the planrails hooks and the /plan skill in a project.
+ *
+ *   npx planrails hooks install [--with-never-delete] [--dry-run]
+ *   npx planrails hooks status
+ *   npx planrails hooks uninstall
+ *
+ * What it writes: the hook entries in <project>/.claude/settings.json, keeping
+ * every other setting exactly as it was (a backup goes to .planrails/backups/
+ * first), and the /plan skill at <project>/.claude/skills/plan/SKILL.md.
+ *
+ * Hook commands use `$CLAUDE_PROJECT_DIR`, which Claude Code sets for every hook
+ * command (measured on 2.1.269), so settings.json is portable: commit it once
+ * and every teammate's machine runs the copy in THEIR node_modules. If planrails
+ * is not installed under the project's node_modules (a checkout, a global
+ * install), the command falls back to the absolute path of this copy and
+ * `doctor` says so. Paths are always quoted: an unquoted path with a space runs
+ * `node /Users/x/My` and silently disables every hook.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, realpathSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { projectRoot, packageRoot, claudeSettingsPath, backupRoot, cliName } from "../plan/lib/paths.mjs";
+import { nowIso } from "../plan/lib/time.mjs";
+
+const HOOKS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** The managed set. Order within an event is the order Claude Code runs them. */
+export const MANAGED = [
+  { event: "SessionStart", file: "plan-session-start.mjs", runner: "node", timeout: 20, statusMessage: "Loading active plan briefs" },
+  { event: "PreToolUse", matcher: "Edit|Write|MultiEdit|NotebookEdit|Bash|Read|Agent|Workflow|WebSearch|WebFetch|Skill", file: "plan-pre-tool.mjs", runner: "node", timeout: 10 },
+  { event: "SubagentStart", file: "plan-subagent-start.mjs", runner: "node", timeout: 10 },
+  { event: "Stop", file: "plan-stop.mjs", runner: "node", timeout: 15 },
+  { event: "PreCompact", file: "precompact-journal.mjs", runner: "node", timeout: 60, statusMessage: "Writing progress journal before compaction" },
+  { event: "PostCompact", file: "postcompact-journal.mjs", runner: "node", timeout: 15 },
+];
+/** Opt-in: blocks rm/rmdir/unlink/shred in Bash so an unattended run never stalls on a delete prompt, and nothing is lost by mistake. Needs jq. */
+export const OPTIONAL = {
+  "never-delete": { event: "PreToolUse", matcher: "Bash", file: "guard-never-delete.sh", runner: "bash", timeout: 10 },
+};
+const ALL_FILES = new Set([...MANAGED, ...Object.values(OPTIONAL)].map((m) => m.file));
+const SKILL_SRC = join(HOOKS_DIR, "..", "plan", "skill", "SKILL.md");
+
+function same(a, b) { try { return realpathSync(a) === realpathSync(b); } catch { return false; } }
+/** Portable when the package sits in the project's node_modules; absolute otherwise. */
+export function commandFor(m) {
+  const viaNodeModules = same(packageRoot(), join(projectRoot(), "node_modules", "planrails"));
+  const path = viaNodeModules ? `$CLAUDE_PROJECT_DIR/node_modules/planrails/src/hooks/${m.file}` : join(HOOKS_DIR, m.file);
+  return `${m.runner} "${path}"`;
+}
+function entryFor(m) {
+  const hook = { type: "command", command: commandFor(m), timeout: m.timeout };
+  if (m.statusMessage) hook.statusMessage = m.statusMessage;
+  return m.matcher ? { matcher: m.matcher, hooks: [hook] } : { hooks: [hook] };
+}
+/** Is this command one of ours? Also matches the pre-package layouts (scripts/hooks, .claude/hooks) so an upgrade replaces them. */
+function isManaged(cmd) {
+  const m = /(?:\/src\/hooks\/|\/scripts\/hooks\/|\/\.claude\/hooks\/)([A-Za-z0-9_.-]+)/.exec(String(cmd || ""));
+  return Boolean(m && ALL_FILES.has(m[1]));
+}
+function readSettings() {
+  const p = claudeSettingsPath();
+  if (!existsSync(p)) return {};
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+export function skillDest() { return join(projectRoot(), ".claude", "skills", "plan", "SKILL.md"); }
+function skillText() { return readFileSync(SKILL_SRC, "utf8").replace(/npx planrails/g, cliName()); }
+/** Expand $CLAUDE_PROJECT_DIR the way the shell will, for existence checks. */
+function namedPath(cmd) {
+  const q = String(cmd).match(/"([^"]+)"/)?.[1] || String(cmd).split(/\s+/)[1] || "";
+  return q.replace(/^\$CLAUDE_PROJECT_DIR/, projectRoot());
+}
+
+export function install({ dryRun = false, withNeverDelete = false, remove = false } = {}) {
+  const cli = cliName();
+  const p = claudeSettingsPath();
+  const before = readSettings();
+  const settings = JSON.parse(JSON.stringify(before));
+  settings.hooks = settings.hooks || {};
+  const replaced = [];
+  const wanted = remove ? [] : [...MANAGED, ...(withNeverDelete ? [OPTIONAL["never-delete"]] : [])];
+  // Keep an optional guard that was installed earlier, even if this run did not ask for it.
+  const hadNeverDelete = Object.values(settings.hooks).some((es) => (es || []).some((e) => (e.hooks || []).some((h) => String(h.command).includes("guard-never-delete.sh"))));
+  if (!remove && hadNeverDelete && !withNeverDelete) wanted.push(OPTIONAL["never-delete"]);
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    const kept = [];
+    for (const e of entries || []) {
+      const ours = (e.hooks || []).filter((h) => isManaged(h.command));
+      const theirs = (e.hooks || []).filter((h) => !isManaged(h.command));
+      for (const h of ours) if (!String(h.command).includes("/src/hooks/")) replaced.push(`${event}: ${h.command}`);
+      if (theirs.length) kept.push({ ...e, hooks: theirs });
+    }
+    settings.hooks[event] = kept;
+  }
+  for (const m of wanted) (settings.hooks[m.event] = settings.hooks[m.event] || []).push(entryFor(m));
+  for (const k of Object.keys(settings.hooks)) if (!settings.hooks[k].length) delete settings.hooks[k];
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  const changed = JSON.stringify(before) !== JSON.stringify(settings);
+  const lines = [];
+  if (replaced.length) lines.push(`replacing ${replaced.length} older entr${replaced.length === 1 ? "y" : "ies"}:\n  ${replaced.join("\n  ")}`);
+  lines.push(`${changed ? (dryRun ? "would write" : "writing") : "no change to"} ${p}`);
+  if (!dryRun) {
+    if (changed) {
+      if (existsSync(p)) {
+        const bk = join(backupRoot(), `claude-settings-${nowIso().replace(/[:+]/g, "-")}.json`);
+        mkdirSync(dirname(bk), { recursive: true });
+        copyFileSync(p, bk);
+        lines.push(`previous settings backed up to ${bk}`);
+      }
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, JSON.stringify(settings, null, 2) + "\n");
+    }
+    const dest = skillDest();
+    if (remove) {
+      if (existsSync(dest)) { unlinkSync(dest); lines.push(`removed /plan skill at ${dest}`); }
+    } else {
+      const current = existsSync(dest) && readFileSync(dest, "utf8") === skillText();
+      if (!current) { mkdirSync(dirname(dest), { recursive: true }); writeFileSync(dest, skillText()); lines.push(`installed /plan skill → ${dest}`); }
+      else lines.push(`/plan skill already current at ${dest}`);
+    }
+  } else if (!remove) lines.push(`(dry run) would install /plan skill → ${skillDest()}`);
+  if (wanted.some((m) => m.file === "guard-never-delete.sh") && spawnSync("which", ["jq"]).status !== 0) lines.push("warn: jq not found — the never-delete guard needs it (brew install jq / apt install jq)");
+  if (!remove && !same(packageRoot(), join(projectRoot(), "node_modules", "planrails"))) lines.push(`note: planrails is not installed under ${join(projectRoot(), "node_modules")} — hook commands use the absolute path of this copy (${packageRoot()}), which only works on this machine. Run: npm install --save-dev planrails, then ${cli} hooks install`);
+  lines.push(remove ? "Restart Claude Code (or run /hooks) so the removal takes effect." : "Restart Claude Code (or run /hooks) so the new hooks load.");
+  process.stdout.write(lines.join("\n") + "\n");
+  return { changed, replaced };
+}
+
+export function status({ print = true } = {}) {
+  const cli = cliName();
+  const p = claudeSettingsPath();
+  const lines = [];
+  let problems = 0;
+  const settings = existsSync(p) ? readSettings() : null;
+  if (!settings) { lines.push({ ok: false, text: `no ${p} — run: ${cli} hooks install` }); problems++; }
+  else {
+    const all = Object.entries(settings.hooks || {}).flatMap(([event, es]) => (es || []).flatMap((e) => (e.hooks || []).map((h) => ({ event, matcher: e.matcher, command: h.command }))));
+    const expected = [...MANAGED, ...(all.some((h) => String(h.command).includes("guard-never-delete.sh")) ? [OPTIONAL["never-delete"]] : [])];
+    for (const m of expected) {
+      const hit = all.find((h) => h.event === m.event && String(h.command).includes(`/src/hooks/${m.file}`) && (m.matcher ? h.matcher === m.matcher : true));
+      const old = all.find((h) => h.event === m.event && /\/(scripts|\.claude)\/hooks\//.test(String(h.command)) && String(h.command).includes(m.file));
+      // The path the command names must exist: a settings.json copied from another machine can point at files that are not there,
+      // and Claude Code runs the command anyway — exit 1 on every event, every rail silently off.
+      const named = hit ? namedPath(hit.command) : null;
+      if (hit && named && !existsSync(named)) { lines.push({ ok: false, text: `hook ${m.event} → ${named} does NOT exist on disk — run: npm install, then ${cli} hooks install` }); problems++; }
+      else if (hit) lines.push({ ok: true, text: `hook ${m.event}${m.matcher ? `(${m.matcher.length > 24 ? m.matcher.slice(0, 21) + "…" : m.matcher})` : ""} → ${m.file}${String(hit.command).includes("$CLAUDE_PROJECT_DIR") ? "" : " (absolute path: this machine only)"}` });
+      else if (old) lines.push({ ok: false, warn: true, text: `hook ${m.event} still points at an older copy of ${m.file} — run: ${cli} hooks install` });
+      else { lines.push({ ok: false, text: `hook ${m.event} → ${m.file} NOT installed — run: ${cli} hooks install` }); problems++; }
+    }
+    if (settings.disableAllHooks) { lines.push({ ok: false, text: "disableAllHooks is true — every hook is off" }); problems++; }
+    if (expected.some((m) => m.file === "guard-never-delete.sh") && spawnSync("which", ["jq"]).status !== 0) lines.push({ ok: false, warn: true, text: "jq not on PATH — the never-delete guard cannot run (brew install jq)" });
+  }
+  const dest = skillDest();
+  if (!existsSync(dest)) lines.push({ ok: false, warn: true, text: `/plan skill not installed at ${dest} — run: ${cli} hooks install` });
+  else if (readFileSync(dest, "utf8") !== skillText()) lines.push({ ok: false, warn: true, text: `/plan skill is stale — run: ${cli} hooks install` });
+  else lines.push({ ok: true, text: "/plan skill installed and current" });
+  if (print) for (const l of lines) process.stdout.write(`${l.ok ? "ok   " : l.warn ? "warn " : "FAIL "} ${l.text}\n`);
+  return { lines, problems };
+}
+
+export function selftest() {
+  const r = spawnSync("node", [join(HOOKS_DIR, "selftest.mjs")], { stdio: "inherit" });
+  if (r.status !== 0) process.exit(r.status || 1);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  if (process.argv.includes("--status")) { const { problems } = status(); process.exit(problems ? 1 : 0); }
+  else if (process.argv.includes("--selftest")) selftest();
+  else if (process.argv.includes("--uninstall")) install({ remove: true });
+  else install({ dryRun: process.argv.includes("--dry-run"), withNeverDelete: process.argv.includes("--with-never-delete") });
+}

package/src/hooks/plan-pre-tool.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse (Edit · Write · MultiEdit · NotebookEdit · Bash · Read · Agent ·
+ * Workflow · WebSearch · WebFetch · Skill) — two jobs, one process:
+ *
+ *  1. JUST-IN-TIME RULES. Each active plan's rules.json attaches a short rule
+ *     to a trigger (tool + path / command / prompt). When the call matches, the
+ *     rule text is added to Claude's context — at the moment it applies, and
+ *     otherwise never. This is what lets a rule leave CLAUDE.md without being
+ *     forgotten: the hook cannot forget. Default policy `once` per session
+ *     (reset on compaction by plan-session-start.mjs).
+ *
+ *  2. UNLOGGED-WORK LEDGER. An Edit/Write under a plan's `paths` is noted in
+ *     .planrails/hooks/<session>/edits.jsonl. plan-stop.mjs compares that with
+ *     the plan's last log entry.
+ *
+ * Never blocks. Never throws out. Subagents get rules too (they edit files);
+ * their edits are marked agent:true.
+ */
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { readInput, sessionDir, readJsonSafe, writeJsonSafe, appendSafe, addContext } from "./_lib.mjs";
+import { projectRoot } from "../plan/lib/paths.mjs";
+import { activePlanIds, loadPlanCheap } from "../plan/lib/store.mjs";
+import { ruleMatches, toRepoRelative, anyPathMatches } from "../plan/lib/glob.mjs";
+import { nowIso } from "../plan/lib/time.mjs";
+
+const input = readInput();
+const toolName = String(input.tool_name || "");
+const toolInput = input.tool_input || {};
+if (!toolName) process.exit(0);
+
+let ids = [];
+try { ids = activePlanIds(); } catch { ids = []; }
+if (!ids.length) process.exit(0);
+
+const root = projectRoot();
+const dir = sessionDir(input);
+const injectedPath = join(dir, "injected.json");
+const injected = readJsonSafe(injectedPath, {});
+const EDIT_TOOLS = /^(Edit|Write|MultiEdit|NotebookEdit)$/;
+const fired = [];
+
+for (const id of ids) {
+  let plan;
+  try { plan = loadPlanCheap(id); } catch { continue; }
+  if (!plan.state) continue;
+  for (const rule of plan.rules?.rules || []) {
+    let hit = false;
+    try { hit = ruleMatches(rule, { toolName, toolInput, root, cwd: input.cwd || null }); } catch { hit = false; }
+    if (!hit) continue;
+    // Keyed per agent: subagents share the parent's session_id, so a session-wide key would starve them of once-rules.
+    const key = `${input.agent_id ? `agent:${input.agent_id}` : "main"}:${id}/${rule.id}`;
+    const n = injected[key] || 0;
+    const policy = rule.repeat || "once";
+    const fire = policy === "always" ? true : policy === "once" ? n === 0 : n % Math.max(1, Number(policy.split(":")[1] || 1)) === 0;
+    injected[key] = n + 1;
+    if (!fire) continue;
+    let text = rule.text || "";
+    if (rule.file) { try { text = readFileSync(join(plan.dir, rule.file), "utf8").trim(); } catch { text = `(rule ${rule.id}: file ${rule.file} could not be read)`; } }
+    fired.push(`RULE ${rule.id} (plan ${id}, fires ${policy} — from ${id}/rules.json):\n${text}`);
+  }
+  if (EDIT_TOOLS.test(toolName)) {
+    const rel = toRepoRelative(toolInput.file_path || toolInput.notebook_path || "", root, input.cwd || null);
+    if (rel && anyPathMatches(rel, plan.state.paths)) {
+      appendSafe(join(dir, "edits.jsonl"), JSON.stringify({ at: nowIso(), plan: id, file: rel, agent: Boolean(input.agent_id) }));
+    }
+  }
+}
+writeJsonSafe(injectedPath, injected);
+if (fired.length) addContext("PreToolUse", fired.join("\n\n"));

package/src/hooks/plan-session-start.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * SessionStart (startup · resume · clear · compact) — inject the brief of every
+ * active plan.
+ *
+ * This is the piece that makes "the plan is re-read, never remembered" true
+ * without anyone remembering to do it. The brief is rendered from disk at this
+ * moment (src/plan/lib/brief.mjs), so it cannot be stale. After a
+ * compaction the tool results are gone; the log and the brief are the record.
+ *
+ * Also records the session id at .planrails/hooks/current-session.json so the
+ * CLI can stamp log entries, and on `compact` resets the once-per-session rule
+ * injections (the context they were injected into no longer exists).
+ */
+import { join } from "node:path";
+import { unlinkSync, existsSync } from "node:fs";
+import { readInput, sessionDir, writeJsonSafe, appendSafe, addContext } from "./_lib.mjs";
+import { hookStateRoot, cliName } from "../plan/lib/paths.mjs";
+import { activePlanIds, loadPlan } from "../plan/lib/store.mjs";
+import { renderBrief } from "../plan/lib/brief.mjs";
+import { nowIso } from "../plan/lib/time.mjs";
+
+const input = readInput();
+const source = String(input.source || input.matcher || "startup");
+try {
+  const dir = sessionDir(input);
+  writeJsonSafe(join(hookStateRoot(), "current-session.json"), { session_id: input.session_id || null, startedAt: nowIso(), source, cwd: input.cwd || null });
+  appendSafe(join(dir, "starts.jsonl"), JSON.stringify({ at: nowIso(), source }));
+  if (source === "compact" || source === "clear") { const f = join(dir, "injected.json"); if (existsSync(f)) unlinkSync(f); }
+} catch { /* never block a session start */ }
+
+let ids = [];
+try { ids = activePlanIds(); } catch { ids = []; }
+if (!ids.length) process.exit(0);
+
+const MAX = 3;
+const parts = [];
+parts.push(`PLAN SYSTEM — ${ids.length} active plan(s): ${ids.join(", ")}. The briefs below were rendered from disk just now; they outrank anything you remember about where the work stood.` +
+  (source === "compact" ? " You have just compacted: every tool result is gone, and the log + brief are the record of what was already done." : "") +
+  (source === "resume" ? " This is a resumed session: check the brief's RESUME line against git status before continuing." : ""));
+for (const id of ids.slice(0, MAX)) {
+  try { parts.push(renderBrief(loadPlan(id))); } catch (e) { parts.push(`## Plan ${id} — brief failed to render: ${e.message}. Run: ${cliName()} validate ${id}`); }
+}
+if (ids.length > MAX) parts.push(`(+${ids.length - MAX} more: ${cliName()} brief <id>)`);
+parts.push("Before the first command on a plan this session: read its PLAN.md § Method and § Rules. Rules attached to specific steps arrive automatically when you take that step. Record as you go — the Stop hook will remind you if files under a plan's paths change and nothing is logged. Guide: docs/PLANNING_GUIDE.md § Executing a plan.");
+addContext("SessionStart", parts.join("\n\n"));

package/src/hooks/plan-stop.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Stop — "you changed files under a plan and logged nothing."
+ *
+ * The rule it enforces: update the plan after every landed piece of work, not
+ * at the end of the session, because the chat is lost and the plan is not.
+ * This hook makes that a check. If this session (main thread or its subagents)
+ * edited files under an active plan's `paths` after that plan's last log entry,
+ * the stop is blocked ONCE with the exact command to run. `stop_hook_active`
+ * guards against a loop: the second stop of the same turn always passes.
+ *
+ * It reminds once per unlogged stretch (keyed on the plan's last log time), and
+ * again only if the stretch has grown by five or more files — a nag on every
+ * turn would train everyone to ignore it, which is worse than no hook.
+ */
+import { join } from "node:path";
+import { readInput, sessionDir, readJsonSafe, writeJsonSafe, emit } from "./_lib.mjs";
+import { activePlanIds, loadPlan } from "../plan/lib/store.mjs";
+import { shortStamp } from "../plan/lib/time.mjs";
+import { cliName } from "../plan/lib/paths.mjs";
+import { readFileSync, existsSync } from "node:fs";
+
+const input = readInput();
+if (input.stop_hook_active) process.exit(0);
+
+const dir = sessionDir(input);
+const editsPath = join(dir, "edits.jsonl");
+if (!existsSync(editsPath)) process.exit(0);
+let edits = [];
+try { edits = readFileSync(editsPath, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)); } catch { process.exit(0); }
+if (!edits.length) process.exit(0);
+
+let ids = [];
+try { ids = activePlanIds(); } catch { process.exit(0); }
+const remindedPath = join(dir, "reminded.json");
+const reminded = readJsonSafe(remindedPath, {});
+const reasons = [];
+
+for (const id of ids) {
+  let plan;
+  try { plan = loadPlan(id); } catch { continue; }
+  const last = plan.log.at(-1);
+  const lastAt = last ? Date.parse(last.at) : 0;
+  const unlogged = edits.filter((e) => e.plan === id && Date.parse(e.at) > lastAt);
+  if (!unlogged.length) continue;
+  const files = [...new Set(unlogged.map((e) => e.file))];
+  const prev = reminded[id];
+  if (prev && prev.lastAt === lastAt && files.length < prev.files + 5) continue;
+  reminded[id] = { lastAt, files: files.length };
+  const doing = plan.state.tasks.find((t) => t.status === "doing");
+  reasons.push(
+    `PLAN ${id}: ${files.length} file(s) under its paths changed since its last log entry (${last ? shortStamp(last.at) : "never"}): ` +
+    `${files.slice(0, 6).join(", ")}${files.length > 6 ? `, +${files.length - 6} more` : ""}.\n` +
+    `Record what landed and the exact next step BEFORE stopping — a compaction or a fresh session reads the log, not this chat:\n` +
+    `  ${cliName()} log ${id}${doing ? ` --task ${doing.id}` : ""} --what "<what changed, with numbers/paths>" --next "<the next action, executable by a stranger>"\n` +
+    `Anything learned → plan learn; any choice → plan decide; a task that landed → plan task done (it runs the gate). Then stop.`
+  );
+}
+writeJsonSafe(remindedPath, reminded);
+if (reasons.length) emit({ decision: "block", reason: reasons.join("\n\n") });

package/src/hooks/plan-subagent-start.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * SubagentStart — the do-nots every subagent must carry, as a rail.
+ *
+ * Measured 2026-09-12 (scratchpad hooktest, Claude Code 2.1.269): a SubagentStart
+ * hook's additionalContext reaches the SUBAGENT and not the main thread; the
+ * payload carries agent_id, agent_type and the PARENT's session_id. So this is
+ * the one place a note can be put in front of every subagent without the main
+ * session remembering to write it into every prompt.
+ *
+ * It stays short (< 700 chars): a subagent's fixed prompt is re-read every turn
+ * (CLAUDE.md § TOKEN DISCIPLINE). The task-specific brief comes from the main
+ * session (`plan agent-brief <id> <T>`); the rules for a file arrive from
+ * plan-pre-tool.mjs at the tool call. Silent when no plan is active.
+ */
+import { readInput, addContext } from "./_lib.mjs";
+import { activePlanIds } from "../plan/lib/store.mjs";
+
+const input = readInput();
+let ids = [];
+try { ids = activePlanIds(); } catch { ids = []; }
+if (!ids.length) process.exit(0);
+const reports = ids.map((id) => `.project-management/plans/${id}/reports/`).join(" or ");
+addContext("SubagentStart",
+  `SUBAGENT NOTE (plan system; active plan${ids.length > 1 ? "s" : ""}: ${ids.join(", ")}). Your prompt is your whole memory of the plan; the main session owns it. ` +
+  `Write only the files your prompt names. Put your findings in a report file under ${reports} (every number WITH its locator: file:line, page, verse) and name it in your reply — a finding that lives only in your reply is lost. ` +
+  `Never delete (move it aside instead), never run \`plan task done\` or \`plan close\`, never settle a doubt by guessing: write the doubt down. Rules for a file arrive when you touch it; follow them.`);

package/src/hooks/postcompact-journal.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// PostCompact — closes the loop opened by precompact-journal.mjs.
+//
+// Compaction has just discarded every tool result. This injects the path of the
+// journal that was written a moment earlier, so the next turn re-reads what was
+// already done instead of doing it again.
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { journalRoot, projectRoot } from "../plan/lib/paths.mjs";
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, "utf8")); } catch { process.exit(0); }
+
+const sid = String(input.session_id || "").replace(/[^A-Za-z0-9_-]/g, "");
+if (!sid) process.exit(0);
+
+const path = join(journalRoot(), `${sid}.md`);
+if (!existsSync(path)) process.exit(0);
+
+let kb = 0;
+try { kb = Math.round(statSync(path).size / 1024); } catch { /* ignore */ }
+const rel = relative(projectRoot(), path);
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PostCompact",
+    additionalContext:
+      `A progress journal for this session exists at ${rel} (${kb} KB). ` +
+      `The compaction you just went through discarded every tool result, so your record of what ` +
+      `was already done is in that file, not in this context. Read its most recent section before ` +
+      `resuming — especially the files already written and the commands already run — so you do not repeat work.`,
+  },
+  suppressOutput: true,
+}));
+process.exit(0);