fapony 0.1.0

package/src/init-mem.ts

@@ -0,0 +1,71 @@
+// src/init-mem.ts — scaffold the canonical .memory/ system into a new worktree.
+// Source of truth lives in fapony/templates/mem/ — named after the CLI it implements
+// (`mem`), not after where it lands; the destination keeps the .memory name because that
+// is where the log lives.
+// Destination is <worktree>/.fapony/.memory/ (plans/specs/memory all live under
+// .fapony/; run state stays in ~/.config/fapony/state.db, never in the worktree).
+// Re-run to re-sync after editing the template — not automatic, on purpose.
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadConfig, memoryEntry } from "./db/index.js";
+
+export function copyDir(src: string, dest: string): string[] {
+  mkdirSync(dest, { recursive: true });
+  const copied: string[] = [];
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const s = join(src, entry.name);
+    const d = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copied.push(...copyDir(s, d));
+    } else {
+      copyFileSync(s, d);
+      copied.push(d);
+    }
+  }
+  return copied;
+}
+
+export function cmdInitMem(args: string[]): void {
+  const update = args.includes("--update");
+  const worktreeKey = args.find((x) => !x.startsWith("-"));
+  const config = loadConfig();
+
+  // ไม่ระบุ key = repo ที่ยืนอยู่ตอนนี้ — ทำให้ `fapony init-mem --update` รันในโปรเจกต์ของใครก็ได้
+  // โดยไม่ต้องลงทะเบียน worktree ก่อน (loadConfig อ่าน fapony.config.json ของ cwd อยู่แล้ว
+  // จึงได้ paths.memoryEntry ของโปรเจกต์นั้นมาเอง)
+  const worktree = worktreeKey ? config.worktrees[worktreeKey] : process.cwd();
+  if (!worktree) {
+    console.error(`unknown worktree key: ${worktreeKey}`);
+    console.error(`available: ${Object.keys(config.worktrees).join(", ")}`);
+    process.exit(1);
+  }
+
+  const templateDir = join(import.meta.dir, "..", "templates", "mem");
+  const memEntry = memoryEntry(config);
+  const destDir = join(worktree, dirname(memEntry));
+  const destFile = join(worktree, memEntry);
+
+  if (existsSync(destFile) && !update) {
+    console.error(
+      `${destFile} already exists — re-running would overwrite local edits.\nRun \`fapony init-mem --update\` to refresh it from the template (log.jsonl is kept).`,
+    );
+    process.exit(1);
+  }
+  if (update && !existsSync(destFile)) {
+    console.error(`${destFile} not found — run \`fapony init\` first.`);
+    process.exit(1);
+  }
+
+  const files = copyDir(templateDir, destDir);
+  if (update) {
+    console.log(`updated ${files.length} files in ${destDir}`);
+    console.log(`(log.jsonl and other data files left untouched)`);
+    return;
+  }
+  console.log(`scaffolded ${files.length} files into ${destDir}`);
+  console.log(`\nAdd to fapony.config.json:`);
+  console.log(
+    `  "memory": {\n    "claim": ["bun", "${memEntry}", "claim", "{id}"],\n    "close": ["bun", "${memEntry}", "close", "{id}", "{msg}"],\n    "add":   ["bun", "${memEntry}", "add", "{kind}", "{text}"],\n    "kickoff": ["bun", "${memEntry}", "kickoff"]\n  }`,
+  );
+}

package/src/init.ts

@@ -0,0 +1,237 @@
+// src/init.ts — scaffold fapony project structure at a target path.
+// Creates .fapony/plan/, .fapony/done/, .fapony/spec/, .fapony/.memory/ (from template).
+// state.db stays in ~/.config/fapony/ by design (security boundary — see db.ts),
+// never inside the worktree where agents have full write access.
+
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { createInterface } from "node:readline";
+import { seedConventionsFile } from "./conventions-seed.js";
+import {
+  type Config,
+  doneDir,
+  evidenceFile,
+  memoryEntry,
+  planDir,
+  specDir,
+} from "./db/index.js";
+import { copyDir } from "./init-mem.js";
+import { isAffirmative } from "./util.js";
+
+const FAPONY_README = `# .fapony/ — fapony project dir (plans, specs, memory)
+# plan/ holds live plans, done/ the shipped ones, spec/ every spec (specs are a
+# reference library — they are not archived). done/ sits beside plan/ rather
+# than inside it so archiving never changes a file's depth, and the relative
+# links inside it keep working.
+# memory lives in .fapony/.memory/, the evidence allowlist in .fapony/evidence.json.
+#
+# evidence.json SHOULD be committed — it is the shared allowlist that decides
+# which commands 'fapony report' may run, and the team must run the same
+# set. If your .gitignore ignores .fapony/ wholesale, re-include it:
+#   **/.fapony/*
+#   !**/.fapony/evidence.json
+# (dir before file — git cannot re-include a file inside an excluded dir;
+# patterns with a mid-string slash anchor at the repo root, so keep the **/).
+#
+# state.db is NOT here by design — it lives in ~/.config/fapony/ where agents
+# running in this worktree cannot rewrite run state / audit trail.
+#
+# Ask your agent for the plan picture instead of listing these by hand:
+#   "run plan_list" — what is active, blocked, untouched, archived
+`;
+
+// Static template — deliberately NOT derived from the repo (reading package.json
+// etc. to guess commands would produce a fake allowlist, which is worse than none).
+// `fapony report` only runs commands listed here; agent-proposed commands
+// outside the allowlist are reported, never executed.
+const EVIDENCE_JSON = `{
+  "commands": [
+    { "name": "test", "cmd": "echo 'edit me: the real test command'", "timeout_ms": 30000 },
+    { "name": "typecheck", "cmd": "echo 'edit me: the real typecheck command'", "timeout_ms": 30000 }
+  ]
+}
+`;
+
+// Rules snippet for the user's own agent-rules file. Printed, never written:
+// nothing writes log.<person>.jsonl on its own — an agent does, because the rules
+// file it already reads says to. That file is the user's (CLAUDE.md / AGENTS.md /
+// opencode.json instructions), so fapony hands over the text and stays out of it.
+// Not in SERVER_INSTRUCTIONS either: that reaches every MCP session of every user,
+// and most of them never ran `fapony init` — it would tell them to run a command
+// that does not exist.
+const RULES_SNIPPET = (
+  memEntry: string,
+) => `## Memory: ${dirname(memEntry)}/log.<you>.jsonl (append-only)
+
+The log is this project's shared brain — it lives in git, so anyone who clones the
+repo gets every decision, bug and note with it. The filename comes from
+\`git config user.name\`, one file per person, so there is nothing to merge.
+
+Log as you work — do not wait to be asked. Nothing writes it for you:
+
+    bun ${memEntry} kickoff <plan.md>      # start a session with this
+    bun ${memEntry} add decision "what was locked, and why" --files src/x.ts
+    bun ${memEntry} add bug "what is broken" --files src/x.ts
+    bun ${memEntry} add note "state the next session needs" --files src/x.ts
+    bun ${memEntry} close <id> "fixed in <sha>"
+    bun ${memEntry} find "<text>"
+
+Write each entry standalone — it is read months later with no chat to refer to.
+--files is required: rows that name no file cannot be recalled when that file is
+touched later (add refuses without it).
+
+## Executing a plan chunk-by-chunk
+
+A long plan run in one unbroken session accumulates context with nothing to shrink
+it — token cost and coherence both degrade with session length, not with amount of
+work done. Cut at chunk boundaries instead:
+
+Finish a chunk, before starting the next:
+1. Tick its checkbox + stamp the TL;DR in the plan file
+2. Commit — separate from other chunks
+3. \`verdict_submit\` (fapony MCP), grading what actually happened
+4. \`bun ${memEntry} add note "what the next chunk needs" --files f1,f2 <path/to/PLAN-x.md>\`
+   — pass the exact same plan path every time; kickoff matches it as a literal string
+5. Stop. Do not continue to the next chunk in the same session unless told to.
+
+Next chunk, new session — open with \`bun ${memEntry} kickoff <path/to/PLAN-x.md>\` (same
+path) instead of carrying the old transcript forward. kickoff already filters to the
+rows written against that exact path.`;
+
+export function initProject(targetPath: string, config?: Config): void {
+  // Create target root
+  mkdirSync(targetPath, { recursive: true });
+
+  // --- .fapony/ marker ---
+  const faponyDir = join(targetPath, ".fapony");
+  if (existsSync(faponyDir)) {
+    throw new Error(
+      `${faponyDir} already exists — delete it first if you want a fresh scaffold.`,
+    );
+  }
+  mkdirSync(faponyDir, { recursive: true });
+  writeFileSync(join(faponyDir, "README"), FAPONY_README);
+
+  // --- evidence.json (verification_report allowlist — see src/mcp/evidence.ts) ---
+  const evidencePath = join(targetPath, evidenceFile(config));
+  if (existsSync(evidencePath)) {
+    throw new Error(`${evidencePath} already exists — not overwriting.`);
+  }
+  mkdirSync(dirname(evidencePath), { recursive: true });
+  writeFileSync(evidencePath, EVIDENCE_JSON);
+
+  // --- plan/ spec/ .memory/ — all under .fapony/ ---
+  const planDirAbs = join(targetPath, planDir(config));
+  if (existsSync(planDirAbs)) {
+    throw new Error(`${planDirAbs} already exists — not overwriting.`);
+  }
+  mkdirSync(planDirAbs, { recursive: true });
+
+  // --- done/ (archive, sibling of plan/) ---
+  const doneDirAbs = join(targetPath, doneDir(config));
+  if (existsSync(doneDirAbs)) {
+    throw new Error(`${doneDirAbs} already exists — not overwriting.`);
+  }
+  mkdirSync(doneDirAbs, { recursive: true });
+
+  // --- spec/ ---
+  const specDirAbs = join(targetPath, specDir(config));
+  if (existsSync(specDirAbs)) {
+    throw new Error(`${specDirAbs} already exists — not overwriting.`);
+  }
+  mkdirSync(specDirAbs, { recursive: true });
+
+  // --- .memory/ (from template) ---
+  const memEntry = memoryEntry(config); // e.g. .fapony/.memory/mem.ts
+  const memoryDir = join(
+    targetPath,
+    memEntry.split("/").slice(0, -1).join("/"),
+  );
+  if (existsSync(join(targetPath, memEntry))) {
+    throw new Error(
+      `${join(targetPath, memEntry)} already exists — delete it first if you want a fresh copy.`,
+    );
+  }
+  const templateDir = join(import.meta.dir, "..", "templates", "mem");
+  const files = copyDir(templateDir, memoryDir);
+
+  console.log(`scaffolded ${targetPath}/`);
+  console.log(
+    `  .fapony/         — project dir (plans, specs, memory, evidence)`,
+  );
+  console.log(`  ${planDir(config)}/    — live plan files`);
+  console.log(`  ${doneDir(config)}/    — shipped plans (archive)`);
+  console.log(`  ${specDir(config)}/    — spec files`);
+  console.log(
+    `  ${evidenceFile(config)}    — allowlist for 'fapony report' (edit the cmds!)`,
+  );
+  console.log(
+    `  ${relative(targetPath, memoryDir)}/ — ${files.length} files from template`,
+  );
+  console.log(`\nNext: add "${targetPath}" to fapony.config.json worktrees`);
+  console.log(
+    `\nThen paste this into your agent-rules file (CLAUDE.md / AGENTS.md / opencode.json\ninstructions) — the memory log only fills up if the rules your agent already reads\ntell it to write:\n`,
+  );
+  console.log(RULES_SNIPPET(memEntry));
+}
+
+const AGENT_RULE_FILES = ["CLAUDE.md", "AGENTS.md"];
+
+function ask(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function cmdInit(args: string[]): Promise<void> {
+  const targetPath = args[0];
+  if (!targetPath) {
+    console.error("usage: fapony init <path>");
+    process.exit(1);
+  }
+  try {
+    initProject(targetPath);
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(1);
+  }
+
+  // --- conventions.json fill-signal (PLAN-convention-debt chunk 2) ---
+  // eslint no-restricted-* rows carry their checker; the wrapper detector adds
+  // live-migration candidates. Nothing derivable = empty file, never an error.
+  const seed = await seedConventionsFile(targetPath);
+  if (seed.kept) {
+    console.log(
+      `  ${relative(targetPath, seed.file)} — already exists, left untouched`,
+    );
+  } else {
+    console.log(
+      `  ${relative(targetPath, seed.file)} — ${seed.eslintRows} from eslint, ${seed.wrapperRows} from wrappers`,
+    );
+    console.log(
+      `    'fapony debt' reads it; commit it (!**/.fapony/conventions.json in .gitignore)`,
+    );
+  }
+  for (const s of seed.skipped) console.log(`    ⚠ eslint config ${s}`);
+
+  const found = AGENT_RULE_FILES.map((f) => join(targetPath, f)).filter(
+    existsSync,
+  );
+  if (found.length === 0) return;
+
+  const answer = await ask(
+    `\nAppend the memory-logging rules above to ${found.map((f) => relative(targetPath, f)).join(" and ")}? [y/N]`,
+  );
+  if (!isAffirmative(answer)) return;
+
+  const memEntry = memoryEntry();
+  const snippet = `\n\n${RULES_SNIPPET(memEntry)}\n`;
+  for (const f of found) {
+    appendFileSync(f, snippet);
+    console.log(`  appended to ${relative(targetPath, f)}`);
+  }
+}

package/src/install/claude.ts

@@ -0,0 +1,361 @@
+// src/install/claude.ts — Claude Code install provider
+//
+// Shells out to `claude mcp add` (never parses/writes ~/.claude.json directly).
+
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { assertSafe } from "../safety.js";
+import { claudeSkillsDir, linkSkills, reportSkills } from "./skills.js";
+import {
+  type ClaudeRunResult,
+  defaultExit,
+  INSTALL_ROOT,
+  type InstallDeps,
+} from "./types.js";
+
+function defaultRun(argv: string[]): ClaudeRunResult {
+  assertSafe(argv);
+  try {
+    const proc = Bun.spawnSync(argv, {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    return {
+      exitCode: proc.exitCode,
+      stdout: proc.stdout.toString(),
+      stderr: proc.stderr.toString(),
+    };
+  } catch (e) {
+    // `claude` binary missing (ENOENT) or spawn failed outright.
+    return { exitCode: 127, stdout: "", stderr: (e as Error).message };
+  }
+}
+
+/** `claude mcp get fapony` — read-only probe. exit 0 = an entry named fapony exists. */
+export function claudeGetArgs(): string[] {
+  return ["claude", "mcp", "get", "fapony"];
+}
+
+/** Absolute-path add command — works even before `bun link` puts `fapony` on PATH. */
+export function claudeAddArgs(): string[] {
+  return [
+    "claude",
+    "mcp",
+    "add",
+    "fapony",
+    "-s",
+    "user",
+    "--",
+    "bun",
+    join(INSTALL_ROOT, "fapony.ts"),
+    "mcp",
+  ];
+}
+
+function isClaudeMissing(res: ClaudeRunResult): boolean {
+  return (
+    res.exitCode === 127 ||
+    /ENOENT|command not found|not found/i.test(res.stderr) ||
+    /ENOENT|command not found|not found/i.test(res.stdout)
+  );
+}
+
+/**
+ * An existing `fapony` entry counts as ours when its Command:/Args: lines
+ * mention fapony (covers both `bun <abs>/fapony.ts mcp` and `fapony mcp`
+ * launchers). Only those lines are inspected — the `fapony:` header matches
+ * trivially and proves nothing. Anything else under our name is someone
+ * else's entry — never overwrite it silently.
+ */
+export function claudeGetPointsToFapony(getOutput: string): boolean {
+  const cmdLines = getOutput
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith("Command:") || l.startsWith("Args:"));
+  return cmdLines.join("\n").includes("fapony");
+}
+
+export function cmdInstallClaude(
+  dryRun: boolean,
+  deps: InstallDeps = {},
+): void {
+  const run = deps.run ?? defaultRun;
+  const exitFn = deps.exit ?? defaultExit;
+
+  const getArgs = claudeGetArgs();
+  assertSafe(getArgs);
+  const get = run(getArgs);
+  if (isClaudeMissing(get)) {
+    console.error(`claude CLI not found — install Claude Code first`);
+    exitFn(1);
+    return;
+  }
+
+  if (get.exitCode === 0) {
+    if (claudeGetPointsToFapony(`${get.stdout}\n${get.stderr}`)) {
+      console.error(`✓ mcp.fapony already configured — no change needed`);
+      console.error(`  (Claude Code user scope)`);
+      const dir = claudeSkillsDir(deps.homedir ?? homedir);
+      reportSkills(linkSkills(dir, dryRun), dir, dryRun);
+      return;
+    }
+    console.error(
+      `an MCP server named "fapony" exists but points elsewhere — not overwriting.`,
+    );
+    console.error(`  inspect with: claude mcp get fapony`);
+    console.error(`  then remove it first: claude mcp remove fapony -s user`);
+    exitFn(1);
+    return;
+  }
+
+  const addArgs = claudeAddArgs();
+  if (dryRun) {
+    console.error(`── dry-run: would run ──`);
+    console.error(`  ${addArgs.join(" ")}`);
+    return;
+  }
+
+  assertSafe(addArgs);
+  const add = run(addArgs);
+  if (isClaudeMissing(add)) {
+    console.error(`claude CLI not found — install Claude Code first`);
+    exitFn(1);
+    return;
+  }
+  if (add.exitCode !== 0) {
+    console.error(
+      `failed to add mcp.fapony to Claude Code (exit ${add.exitCode})`,
+    );
+    const detail = `${add.stdout}\n${add.stderr}`.trim();
+    if (detail) console.error(detail);
+    console.error(`verify with: claude mcp add --help`);
+    exitFn(1);
+    return;
+  }
+  console.error(`✓ mcp.fapony configured for Claude Code (user scope)`);
+  const skillsDir = claudeSkillsDir(deps.homedir ?? homedir);
+  reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
+
+  // Wire statusline: copy script + update settings.json.
+  installStatusline(dryRun, deps);
+
+  // Wire the Stop hook that refuses to end a turn with ungraded commits,
+  // and the Read hint that annotates large-file reads (annotate-only).
+  installStopHook(dryRun, deps);
+  installReadHintHook(dryRun, deps);
+}
+
+/**
+ * Copy the statusline script to ~/.claude/statusline.sh and add the
+ * statusLine field to ~/.claude/settings.json. Best-effort — never fails
+ * the install if settings.json is unreadable or has unexpected shape.
+ */
+function installStatusline(dryRun: boolean, deps: InstallDeps): void {
+  const home = deps.homedir ? deps.homedir() : homedir();
+  const claudeDir = join(home, ".claude");
+  const scriptSrc = join(INSTALL_ROOT, "statusline", "claude-statusline.sh");
+  const scriptDest = join(claudeDir, "statusline.sh");
+  const settingsPath = join(claudeDir, "settings.json");
+
+  // 1. Copy the statusline script — never overwrite someone else's.
+  // Mirrors the mcp-entry policy above: an existing script that isn't ours
+  // is left alone (the settings guard below will also refuse to repoint it).
+  if (!existsSync(scriptSrc)) {
+    console.error(`  statusline: script not found at ${scriptSrc} — skipping`);
+    return;
+  }
+  if (existsSync(scriptDest)) {
+    let current = "";
+    try {
+      current = readFileSync(scriptDest, "utf-8");
+    } catch {
+      current = "";
+    }
+    if (!current.includes("fapony")) {
+      console.error(
+        `  statusline: ${scriptDest} exists but isn't fapony's — not overwriting.`,
+      );
+      console.error(
+        `  inspect it first, then remove it to let fapony install its own.`,
+      );
+      return;
+    }
+  }
+  try {
+    if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
+    if (!dryRun) copyFileSync(scriptSrc, scriptDest);
+    // Claude Code execs this file — the copy must stay executable.
+    if (!dryRun) chmodSync(scriptDest, 0o755);
+    console.error(
+      `  statusline: ${dryRun ? "would copy" : "copied"} ${scriptDest}`,
+    );
+  } catch (e) {
+    console.error(
+      `  statusline: failed to copy script — ${(e as Error).message}`,
+    );
+    return;
+  }
+
+  // 2. Update settings.json with statusLine field.
+  let settings: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+    } catch {
+      console.error(
+        `  statusline: ${settingsPath} is unreadable or malformed — skipping settings update`,
+      );
+      return;
+    }
+  }
+
+  // Don't overwrite if already configured (same command path). A foreign
+  // statusLine (someone else's command) is left alone — same policy as the
+  // mcp-entry "points elsewhere" refusal above. Match on our exact dest:
+  // any *statusline.sh substring (e.g. another plugin's script) is not ours.
+  const existing = settings.statusLine as Record<string, unknown> | undefined;
+  if (
+    existing &&
+    existing.type === "command" &&
+    typeof existing.command === "string" &&
+    existing.command === scriptDest
+  ) {
+    console.error(
+      `  statusline: already configured in settings.json — no change`,
+    );
+    return;
+  }
+  if (existing && typeof existing === "object") {
+    console.error(
+      `  statusline: settings.json already has a statusLine that isn't fapony's — not overwriting.`,
+    );
+    console.error(
+      `  inspect it first, then remove it to let fapony wire its own.`,
+    );
+    return;
+  }
+
+  settings.statusLine = {
+    type: "command",
+    command: scriptDest,
+  };
+
+  if (!dryRun) {
+    writeFileSync(
+      settingsPath,
+      `${JSON.stringify(settings, null, 2)}\n`,
+      "utf-8",
+    );
+  }
+  console.error(
+    `  statusline: ${dryRun ? "would write" : "wrote"} statusLine → ${settingsPath}`,
+  );
+}
+
+/**
+ * Shared append-to-settings.json hook installer. Both fapony hooks live
+ * here now (Stop since PLAN-mem-mcp, PreToolUse read hint since the
+ * large-file annotate feature) — the read/write/idempotence/append shape
+ * is one implementation with two callers, not a scaffold.
+ * Same policy as installStatusline: never touch a hook someone else
+ * registered, never fail the install over it.
+ */
+function ensureClaudeHook(
+  dryRun: boolean,
+  deps: InstallDeps,
+  hook: { event: string; matcher?: string; subcommand: string; label: string },
+): void {
+  const home = deps.homedir ? deps.homedir() : homedir();
+  const claudeDir = join(home, ".claude");
+  const settingsPath = join(claudeDir, "settings.json");
+  const command = `bun ${join(INSTALL_ROOT, "fapony.ts")} ${hook.subcommand}`;
+
+  let settings: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+    } catch {
+      console.error(
+        `  ${hook.label}: ${settingsPath} is unreadable or malformed — skipping`,
+      );
+      return;
+    }
+  }
+
+  const hooks = (settings.hooks ?? {}) as Record<string, unknown>;
+  const list = Array.isArray(hooks[hook.event])
+    ? (hooks[hook.event] as unknown[])
+    : [];
+  if (JSON.stringify(list).includes(hook.subcommand)) {
+    console.error(
+      `  ${hook.label}: already configured in settings.json — no change`,
+    );
+    return;
+  }
+
+  // Append rather than replace: other tools register hooks too, and
+  // Claude Code runs every entry in the array.
+  list.push({
+    ...(hook.matcher ? { matcher: hook.matcher } : {}),
+    hooks: [{ type: "command", command }],
+  });
+  hooks[hook.event] = list;
+  settings.hooks = hooks;
+
+  if (!dryRun) {
+    try {
+      if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
+      writeFileSync(
+        settingsPath,
+        `${JSON.stringify(settings, null, 2)}\n`,
+        "utf-8",
+      );
+    } catch (e) {
+      console.error(
+        `  ${hook.label}: failed to write — ${(e as Error).message}`,
+      );
+      return;
+    }
+  }
+  console.error(
+    `  ${hook.label}: ${dryRun ? "would write" : "wrote"} hooks.${hook.event} → ${settingsPath}`,
+  );
+}
+
+function installStopHook(dryRun: boolean, deps: InstallDeps): void {
+  ensureClaudeHook(dryRun, deps, {
+    event: "Stop",
+    subcommand: "hook-stop",
+    label: "stop hook",
+  });
+}
+
+/**
+ * PreToolUse hook on Read: annotates a full-file read of a large source file
+ * with one factual line (size + the review-seed command). Annotate only —
+ * no permissionDecision is ever returned, the read always proceeds; and no
+ * "already read" dedupe (context compaction makes that claim false). The
+ * matcher "Read" keeps the spawn off every other tool call.
+ */
+function installReadHintHook(dryRun: boolean, deps: InstallDeps): void {
+  ensureClaudeHook(dryRun, deps, {
+    event: "PreToolUse",
+    matcher: "Read",
+    subcommand: "hook-read-hint",
+    label: "read hint",
+  });
+}