@senomas/pi-git-hat 0.1.0

package/git-hat.ts

@@ -0,0 +1,1456 @@
+/**
+ * git-hat: Wear different hats by switching git branches
+ *
+ * -- Config-driven (replaces hardcoded patterns) --
+ *
+ *   Search order for roles.json:
+ *     1. {PROJECT_ROOT}/.pi/roles.json   (project-specific, inside .pi/)
+ *     2. ~/.pi/agent/roles.json           (global fallback, inside git repo)
+ *     If none found, built-in fallback patterns are used.
+ *
+ *   Overrides: .pi-project.json roles (project-specific, overrides per-role)
+ *
+ *   Resolution:
+ *     1. .pi-project.json roles (project override, highest priority)
+ *     2. roles.json              (base definitions)
+ *     3. no match -> read-only + branch-switching only
+ *
+ *   Role prompts: .pi/{role}.md (case-insensitive, loaded per detected role)
+ *   Seeded from {extensionDir}/roles/ on startup (bundled with the extension)
+ *
+ * Commands:
+ *   /hat       - TUI branch selector: pick a branch grouped by role (with history);
+ *                shows colored git log after a successful branch switch
+ *   /hat info  - show current role and branch info
+ *   /hat todo  - list pending items across todo/ files
+ *   /hatt      - ancestry check + todo listing (blocks if upstream branches missing)
+ *   /hatl      - show colored git log with branch graph
+ *
+ * Post-switch log can be disabled by setting `"postSwitchLog": false` in roles.json
+ *
+ * Inspired by "wearing a different hat" -- architect hat vs builder hat.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { readFile, readdir, writeFile, mkdir, copyFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import {
+  Container,
+  type SelectItem,
+  Text,
+} from "@earendil-works/pi-tui";
+import { SearchableSelectList } from "./lib/searchable-select-list.js";
+
+// -- Types ---------------------------------------------------------
+
+interface RoleDef {
+  pattern: string;
+  description?: string;
+  ancestorRoles?: string[];
+}
+
+interface RolesConfig {
+  version?: number;
+  roles?: Record<string, RoleDef>;
+  defaultRole?: string;
+  fileDir?: string;
+  caseInsensitive?: boolean;
+  redetectOnInput?: boolean;
+  postSwitchLog?: boolean;
+}
+
+interface MergedConfig {
+  roles: Record<string, RoleDef>;
+  fileDir: string;
+  caseInsensitive: boolean;
+  redetectOnInput: boolean;
+  postSwitchLog: boolean;
+  configFile: string;
+}
+
+// -- Branch history persistence -------------------------------------
+
+const AGENT_DIR = resolve(os.homedir(), ".pi", "agent");
+const BRANCH_HISTORY_FILE = resolve(AGENT_DIR, "role_branch.json");
+
+/** Directory containing this extension file. Used to resolve bundled roles/ directory. */
+const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
+
+interface SwitchLogEntry {
+  ts: string;
+  role: string;
+  branch: string;
+}
+
+interface BranchHistory {
+  [role: string]: string | undefined;
+}
+
+/** Load branch history from disk. Handles backward compat: old flat format {role: branch}
+ *  is converted to new format with a history array.
+ *  Returns the role→branch mapping and the switch history entries separately. */
+function loadBranchHistory(): { mapping: BranchHistory; history: SwitchLogEntry[] } {
+  try {
+    const raw = JSON.parse(readFileSync(BRANCH_HISTORY_FILE, "utf-8"));
+    // Detect new format (has "history" array) vs old format (flat {role: branch})
+    if (raw && typeof raw === "object" && !Array.isArray(raw) && "history" in raw) {
+      const { history, ...mapping } = raw;
+      return {
+        mapping: mapping as BranchHistory,
+        history: Array.isArray(history) ? (history as SwitchLogEntry[]) : [],
+      };
+    }
+    // Old format: flat object — wrap into new shape with empty history
+    return { mapping: raw as BranchHistory, history: [] };
+  } catch {
+    return { mapping: {}, history: [] };
+  }
+}
+
+/** Persist mapping + history to disk. */
+async function saveBranchHistory(mapping: BranchHistory, history: SwitchLogEntry[]): Promise<void> {
+  await mkdir(AGENT_DIR, { recursive: true });
+  await writeFile(
+    BRANCH_HISTORY_FILE,
+    JSON.stringify({ ...mapping, history }, null, 2),
+    "utf-8",
+  );
+}
+
+async function recordBranchUsage(role: string, branch: string): Promise<void> {
+  if (!role || !branch) return;
+  const { mapping, history } = loadBranchHistory();
+  mapping[role] = branch;
+  history.push({ ts: new Date().toISOString(), role, branch });
+  // Cap at 50 entries (trim oldest)
+  if (history.length > 50) {
+    history.splice(0, history.length - 50);
+  }
+  await saveBranchHistory(mapping, history);
+}
+
+interface BranchEntry {
+  branch: string;
+  role: string;
+  isCurrent: boolean;
+  isLastUsed: boolean;
+}
+
+/** List all git branches and match them to roles. */
+async function listBranchesByRole(config: MergedConfig, cwd: string): Promise<{
+  entries: BranchEntry[];
+  grouped: Record<string, BranchEntry[]>;
+  roleOrder: string[];
+  unmatched: string[];
+}> {
+  const { mapping: history } = loadBranchHistory();
+  const entries: BranchEntry[] = [];
+  const grouped: Record<string, BranchEntry[]> = {};
+  const unmatched: string[] = [];
+
+  // Get current branch
+  let currentBranch: string | null = null;
+  try {
+    const stdout = execFileSync("git", ["branch", "--show-current"], {
+      cwd,
+      encoding: "utf-8",
+    }) as string;
+    currentBranch = stdout.trim() || null;
+  } catch {
+    /* not a git repo */
+  }
+
+  // Get all branches
+  let branches: string[] = [];
+  try {
+    const stdout = execFileSync("git", ["branch", "--format", "%(refname:short)"], {
+      cwd,
+      encoding: "utf-8",
+    }) as string;
+    branches = stdout.trim().split("\n").filter(Boolean);
+  } catch {
+    return { entries, grouped, roleOrder: [], unmatched };
+  }
+
+  // Match each branch to a role
+  for (const branch of branches) {
+    const role = detectRole(branch, config);
+    if (!role) {
+      unmatched.push(branch);
+      continue;
+    }
+
+    const isCurrent = branch === currentBranch;
+    const isLastUsed = history[role] === branch;
+    const entry: BranchEntry = { branch, role, isCurrent, isLastUsed };
+    entries.push(entry);
+    if (!grouped[role]) grouped[role] = [];
+    grouped[role].push(entry);
+  }
+
+  // Sort within each role: current -> last-used -> rest (alpha)
+  for (const role of Object.keys(grouped)) {
+    grouped[role].sort((a, b) => {
+      if (a.isCurrent) return -1;
+      if (b.isCurrent) return 1;
+      if (a.isLastUsed) return -1;
+      if (b.isLastUsed) return 1;
+      return a.branch.localeCompare(b.branch);
+    });
+  }
+
+  // Role order: roles with current branch first, then last-used, then alpha
+  const roleOrder = [...new Set(entries.map((e) => e.role))].sort((a, b) => {
+    const aHasCurrent = grouped[a]?.some((e) => e.isCurrent);
+    const bHasCurrent = grouped[b]?.some((e) => e.isCurrent);
+    if (aHasCurrent && !bHasCurrent) return -1;
+    if (!aHasCurrent && bHasCurrent) return 1;
+    const aHasLast = grouped[a]?.some((e) => e.isLastUsed);
+    const bHasLast = grouped[b]?.some((e) => e.isLastUsed);
+    if (aHasLast && !bHasLast) return -1;
+    if (!aHasLast && bHasLast) return 1;
+    return a.localeCompare(b);
+  });
+
+  return { entries, grouped, roleOrder, unmatched };
+}
+
+// -- Config loading -------------------------------------------------
+
+const HOME_PI_DIR = resolve(os.homedir(), ".pi");
+
+function loadConfig(): MergedConfig {
+  const merged: MergedConfig = {
+    roles: {},
+    fileDir: ".pi",
+    caseInsensitive: true,
+    redetectOnInput: true,
+    postSwitchLog: true,
+  };
+
+  // Search paths for roles.json (first found wins):
+  //   1. {PROJECT_ROOT}/.pi/roles.json  (project-specific, inside .pi/)
+  //   2. ~/.pi/agent/roles.json          (global fallback, inside git repo)
+  const roleFileCandidates = [
+    resolve(process.cwd(), ".pi", "roles.json"),
+    resolve(HOME_PI_DIR, "agent", "roles.json"),
+  ];
+
+  let loadedRoles = false;
+  for (const candidatePath of roleFileCandidates) {
+    if (existsSync(candidatePath)) {
+      try {
+        const raw = JSON.parse(readFileSync(candidatePath, "utf-8")) as RolesConfig;
+        if (raw.roles) {
+          Object.assign(merged.roles, raw.roles);
+          loadedRoles = true;
+        }
+        if (raw.fileDir) merged.fileDir = raw.fileDir;
+        if (raw.caseInsensitive !== undefined) merged.caseInsensitive = raw.caseInsensitive;
+        if (raw.redetectOnInput !== undefined) merged.redetectOnInput = raw.redetectOnInput;
+        if (raw.postSwitchLog !== undefined) merged.postSwitchLog = raw.postSwitchLog;
+      } catch {
+        // ignore parse errors
+      }
+      merged.configFile = candidatePath;
+      break; // first matching path wins
+    }
+  }
+
+  if (!loadedRoles) {
+    const searched = roleFileCandidates.join(", ");
+    throw new Error(
+      `roles.json not found. Searched:\n  ${searched}\n\n` +
+        `Create one at the project root (~/.pi/agent/roles.json) or inside `.pi/` ({project}/.pi/roles.json).`
+    );
+  }
+
+  // Walk up from CWD to find .pi-project.json for project overrides
+  // Project-level roles fully override matching base roles
+  let dir = process.cwd();
+  while (true) {
+    const candidate = resolve(dir, ".pi-project.json");
+    if (existsSync(candidate)) {
+      try {
+        const projectRaw = JSON.parse(readFileSync(candidate, "utf-8")) as RolesConfig;
+        if (projectRaw.roles) {
+          for (const [name, def] of Object.entries(projectRaw.roles)) {
+            merged.roles[name] = def;
+          }
+        }
+      } catch {
+        // ignore parse errors
+      }
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return merged;
+}
+
+/** Detect the role for a given branch name by iterating merged roles. */
+function detectRole(branch: string, config: MergedConfig): string | null {
+  for (const [roleName, roleDef] of Object.entries(config.roles)) {
+    try {
+      if (new RegExp(roleDef.pattern).test(branch)) return roleName;
+    } catch {
+      // skip invalid regex
+    }
+  }
+  return null; // no match -> "unknown"
+}
+
+// -- File helpers ---------------------------------------------------
+
+/** Extract NN sequence number from a todo/ or report/ filename. */
+function extractNN(filename: string): number | null {
+  const match = filename.match(/^(\d+)-/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/** Scan todo/ and report/ dirs for the highest NN in use. */
+async function findMaxNN(cwd: string): Promise<number> {
+  let max = 0;
+  for (const dirName of ["todo", "report"]) {
+    try {
+      const entries = await readdir(resolve(cwd, dirName));
+      for (const entry of entries) {
+        const nn = extractNN(entry);
+        if (nn !== null && nn > max) max = nn;
+      }
+    } catch {
+      // dir doesn't exist yet
+    }
+  }
+  return max;
+}
+
+/** Normalise a file path argument: strip leading ./, absolute -> relative. */
+function normalisePath(raw: string, cwd: string, cwdAbsolute: string): string {
+  let path = raw;
+  if (path.startsWith(cwdAbsolute + "/")) path = path.slice(cwdAbsolute.length + 1);
+  if (path.startsWith("./")) path = path.slice(2);
+  return path;
+}
+
+/** Check if a path is inside one of the given directories. */
+function isInside(path: string, dirs: string[]): boolean {
+  return dirs.some((d) => path === d || path.startsWith(d + "/"));
+}
+
+/**
+ * Load a role's .md file from the project's fileDir directory.
+ * Case-insensitive lookup if config.caseInsensitive is true.
+ */
+async function loadRoleFile(
+  cwd: string,
+  role: string,
+  config: MergedConfig,
+): Promise<string | null> {
+  // 1. Project-local: {cwd}/{fileDir}/{role}.md (highest priority)
+  const roleDir = resolve(cwd, config.fileDir);
+  const exactPath = resolve(roleDir, `${role}.md`);
+  try {
+    return await readFile(exactPath, "utf8");
+  } catch {
+    // not found with exact case
+  }
+
+  if (config.caseInsensitive) {
+    try {
+      const entries = await readdir(roleDir);
+      for (const entry of entries) {
+        if (entry.toLowerCase() === `${role}.md`) {
+          return await readFile(resolve(roleDir, entry), "utf8");
+        }
+      }
+    } catch {
+      // roleDir doesn't exist
+    }
+  }
+
+  // 2. Extension-bundled: {extensionDir}/roles/{role}.md (fallback)
+  const bundledRoleDir = resolve(EXTENSION_DIR, "roles");
+  const bundledExact = resolve(bundledRoleDir, `${role}.md`);
+  try {
+    return await readFile(bundledExact, "utf8");
+  } catch {
+    // not found with exact case
+  }
+
+  if (config.caseInsensitive) {
+    try {
+      const entries = await readdir(bundledRoleDir);
+      for (const entry of entries) {
+        if (entry.toLowerCase() === `${role}.md`) {
+          return await readFile(resolve(bundledRoleDir, entry), "utf8");
+        }
+      }
+    } catch {
+      // bundledRoleDir doesn't exist
+    }
+  }
+
+  return null;
+}
+
+// -- Built-in role instructions (fallback when no .md file exists) ---
+// Canonical source: roles/{role}.md in the extension directory.
+// Run `python3 scripts/validate-role-prompts.py` to verify alignment.
+
+const BUILTIN_INSTRUCTIONS: Record<string, string> = {
+  planner: `
+
+## Your Role: Planner
+
+You are **PLANNER**. Your sole responsibility is to research (just collecting data for others to solved the problem) and create
+\`todo/NN-name.md\` files. That is it. Switching branch does not switch your role.
+
+## What you do
+1. Research with \`read\` / \`grep\` / \`find\` / \`ls\`
+2. Create \`todo/NN-name.md\` with sequenced, actionable items
+3. Present the plan to the user
+
+## What you do NOT do
+- \`edit\`/\`write\` any file outside \`todo/\`
+- Switch branches (the user handles that)
+- Implement anything (that's the implementor)
+- Write reports (that's the implementor)
+
+## File format: \`todo/NN-name.md\`
+- \`- [ ]\` pending, \`- [x]\` done
+- First line after checkbox = **header**
+- Indented lines = **body**
+- Blank lines separate items
+
+## NN sequence rule
+Every \`todo/NN-name.md\` must use NN **higher** than the highest NN in both
+\`todo/\` **and** \`report/\`.
+`,
+
+  implementor: `
+
+## Your Role: Implementor
+
+You are **IMPLEMENTOR**. Your responsibility is to read todo/*.md files, implement and write reports. That is it. Switching branch does not switch your role.
+
+## Report format: \`report/NN-name.md\`
+- Same NN and same headers as the todo
+- Add implementation notes, decisions, and \`\`\`bash results
+
+## How to implement
+1. Read \`todo/NN-name.md\` (lowest NN first)
+2. If \`todo/NN-name.detail.md\` exists, read it too
+3. Implement each \`- [ ]\` item using \`edit\`/\`write\`
+4. After each item (or batch), update \`report/NN-name.md\`
+5. When done, move to the next NN
+
+## What you do NOT do
+- Switch branches (the user handles that)
+- Write to \`todo/\`, \`plan/\`, or \`.pi/\` — create reports only; let others verify and mark items done
+- Create todo files (that's the planner's job)
+- Modify or mark items in todo files (that's the reviewer's job after verification)
+`,
+
+  reviewer: `
+
+## Your Role: Reviewer
+
+You are **REVIEWER**. Your sole responsibility is to verify that reports fully cover their corresponding todos, and mark items done in \`todo/\`. That is it. Switching branch does not switch your role.
+
+## What you do
+1. Read \`todo/NN-name.md\` and \`report/NN-name.md\`
+2. Match each pending \`- [ ]\` todo item against a section in the report
+3. **Covered** → mark \`- [x]\` in the todo file
+4. **Missing** → leave \`- [ ]\`, tell the user
+5. Also check for orphan reports and stale todos
+
+## What you do NOT do
+- \`edit\`/\`write\` any file outside \`todo/\`
+- Write reports (that's the implementor)
+- Create \`todo/\` or \`plan/\` files (that's the planner)
+- Switch branches (the user handles that)
+- Write to \`.pi/\`
+
+## Key rules
+- **Covered** items get \`- [x]\` in the todo file
+- **Missing** items stay \`- [ ]\` — explain why to the user
+- Read source files and \`review/\` and \`todo/\` as needed to verify
+`,
+
+  admin: `
+
+## Your Role: Admin
+
+You are **ADMIN**. Switching branch does not switch your role.
+
+## What you do
+- Edit \`.pi/\` files — role prompts, roles.json
+- Edit \`README.md\` and \`AGENTS.md\`
+- Explore the codebase (read-only)
+
+## What you do NOT do
+- Edit source code
+- Create or modify \`todo/\`, \`plan/\`, \`report/\` files
+- Switch branches (the user handles that)
+`,
+};
+
+// -- Shared: scan todos and cross-reference with reports -----------
+
+interface PendingItem {
+  lineno: number;
+  header: string;
+  covered: boolean;
+}
+
+interface TodoFile {
+  file: string;
+  pending: PendingItem[];
+  reportExists: boolean;
+}
+
+async function scanTodos(cwd: string): Promise<{
+  files: TodoFile[];
+  totalPending: number;
+  totalCovered: number;
+  summary: string;
+}> {
+  const files: TodoFile[] = [];
+  let totalPending = 0;
+  let totalCovered = 0;
+
+  try {
+    const entries = await readdir(resolve(cwd, "todo"));
+    for (const entry of entries.sort()) {
+      if (!entry.endsWith(".md") || entry.endsWith(".detail.md")) continue;
+      const content = await readFile(resolve(cwd, "todo", entry), "utf8");
+      const pending: PendingItem[] = [];
+      for (const [i, line] of content.split("\n").entries()) {
+        const m = line.match(/^- \[ \] (.+)$/);
+        if (m) pending.push({ lineno: i + 1, header: m[1].trim(), covered: false });
+      }
+      if (pending.length === 0) continue;
+
+      let reportHeaders: string[] = [];
+      try {
+        const reportContent = await readFile(resolve(cwd, "report", entry), "utf8");
+        for (const line of reportContent.split("\n")) {
+          const m = line.match(/^- (.+)$/);
+          if (m && !line.includes("[ ]") && !line.includes("[x]")) {
+            reportHeaders.push(m[1].trim().toLowerCase());
+          }
+        }
+      } catch {
+        // no matching report
+      }
+
+      const reportExists = reportHeaders.length > 0;
+      for (const p of pending) {
+        p.covered = reportHeaders.some(
+          (h) => p.header.toLowerCase().includes(h) || h.includes(p.header.toLowerCase()),
+        );
+        if (p.covered) totalCovered++;
+      }
+      totalPending += pending.length;
+      files.push({ file: entry, pending, reportExists });
+    }
+  } catch {
+    // todo/ doesn"t exist
+  }
+
+  const displayLines: string[] = [];
+  for (const f of files) {
+    const tag = f.reportExists ? "" : " (no report)";
+    displayLines.push(`todo/${f.file}${tag}`);
+    for (const p of f.pending) {
+      displayLines.push(`  ${p.covered ? "\u2705" : "\u274C"} line ${p.lineno}: ${p.header}`);
+    }
+  }
+  displayLines.push(
+    `\u2500\u2500 ${totalPending - totalCovered} missing \u00B7 ${totalCovered} covered \u00B7 ${totalPending} total \u2500\u2500`,
+  );
+
+  return { files, totalPending, totalCovered, summary: displayLines.join("\n") };
+}
+
+/** Handle /hat todo display: scan todos and send follow-up for pending items. */
+/** Ancestry check: verify current branch descends from ancestor role branches. */
+async function verifyAncestry(config: MergedConfig, cwd: string): Promise<{
+  ok: boolean;
+  violations: { role: string; branch: string; currentBranch: string }[];
+}> {
+  const violations: { role: string; branch: string; currentBranch: string }[] = [];
+
+  let currentBranch: string;
+  try {
+    currentBranch = execFileSync("git", ["branch", "--show-current"], {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+    if (!currentBranch) return { ok: true, violations }; // not on a branch (detached)
+  } catch {
+    return { ok: true, violations }; // not a git repo
+  }
+
+  const role = detectRole(currentBranch, config);
+  if (!role) return { ok: true, violations }; // unknown role
+
+  const ancestorRoles = config.roles[role]?.ancestorRoles;
+  if (!ancestorRoles || ancestorRoles.length === 0) return { ok: true, violations }; // no ancestors required
+
+  // Get all local branches
+  let allBranches: string[];
+  try {
+    const stdout = execFileSync("git", ["branch", "--format", "%(refname:short)"], {
+      cwd,
+      encoding: "utf-8",
+    });
+    allBranches = stdout.trim().split("\n").filter(Boolean);
+  } catch {
+    return { ok: true, violations };
+  }
+
+  for (const ancestorRole of ancestorRoles) {
+    const pattern = config.roles[ancestorRole]?.pattern;
+    if (!pattern) continue;
+
+    const regex = new RegExp(pattern);
+    const candidates = allBranches.filter((b) => regex.test(b));
+
+    for (const candidate of candidates) {
+      if (candidate === currentBranch) continue; // same branch, trivially ancestor
+
+      try {
+        execFileSync("git", ["merge-base", "--is-ancestor", candidate, currentBranch], {
+          cwd,
+          stdio: "pipe",
+        });
+        // exit code 0 = is ancestor, no violation
+      } catch {
+        // exit code 1 or error = not ancestor, or deleted branch — record violation
+        violations.push({ role: ancestorRole, branch: candidate, currentBranch });
+      }
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/** Check if master/main is an ancestor of the current branch. */
+async function isMasterOrMainAncestor(cwd: string): Promise<{ ok: boolean; branch: string }> {
+  let currentBranch: string;
+  try {
+    currentBranch = execFileSync("git", ["branch", "--show-current"], {
+      cwd,
+      encoding: "utf-8",
+    }).trim();
+    if (!currentBranch) return { ok: true, branch: "master" }; // detached
+  } catch {
+    return { ok: true, branch: "master" }; // not a git repo
+  }
+
+  // try master first, then main
+  for (const candidate of ["master", "main"]) {
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `refs/heads/${candidate}`], {
+        cwd,
+        stdio: "pipe",
+      });
+      // branch exists
+      if (currentBranch === candidate) return { ok: true, branch: candidate }; // already on it
+      try {
+        execFileSync("git", ["merge-base", "--is-ancestor", candidate, currentBranch], {
+          cwd,
+          stdio: "pipe",
+        });
+        return { ok: true, branch: candidate }; // is ancestor
+      } catch {
+        return { ok: false, branch: candidate }; // not ancestor
+      }
+    } catch {
+      continue; // branch doesn't exist locally, try next
+    }
+  }
+
+  // neither master nor main exists locally — skip check
+  return { ok: true, branch: "master" };
+}
+
+async function handleTodo(
+  pi: ExtensionAPI,
+  ctx: { cwd: string; ui: { notify: (msg: string, level: string) => void } },
+): Promise<void> {
+  // plan/*.md files are excluded from /hat todo — they store future ideas,
+  // not actionable todos. scanTodos() already reads only from the todo/ directory.
+  const result = await scanTodos(ctx.cwd);
+  if (result.files.length === 0) {
+    ctx.ui.notify("\uD83D\uDCED No pending todos found", "info");
+    return;
+  }
+  ctx.ui.notify(result.summary, "info");
+
+  if (result.totalPending - result.totalCovered > 0) {
+    const detail = result.files
+      .map((f) => {
+        const items = f.pending
+          .map((p) => `  ${p.covered ? "\u2705" : "\u274C"} ${p.header}`)
+          .join("\n");
+        return `todo/${f.file}${f.reportExists ? "" : " (no report)"}\n${items}`;
+      })
+      .join("\n");
+    pi.sendUserMessage(
+      `Analyze these pending todos against their reports:\n\n${detail}\n\n` +
+        `For each \u274C item, check if it"s truly not implemented yet or if the report ` +
+        `just uses different wording. If it"s genuinely missing, suggest next steps.`,
+      { deliverAs: "followUp" },
+    );
+  }
+}
+
+/** Role icon for status bar display. */
+function roleIcon(role: string): string {
+  const lower = role.toLowerCase();
+  if (lower === "planner") return "\uD83D\uDCCB";
+  if (lower === "implementor") return "\uD83D\uDEE0";
+  if (lower === "reviewer") return "\uD83D\uDD0D";
+  if (lower === "admin") return "\u2699";
+  return "\uD83E\uDDE2";
+}
+
+// -- ANSI color palette for git ref log decoration ----------------
+
+const REF_COLORS = [
+  "38;5;51",   // cyan
+  "38;5;118",  // green
+  "38;5;226",  // yellow
+  "38;5;207",  // magenta
+  "38;5;196",  // red
+  "38;5;75",   // blue
+  "38;5;214",  // orange
+  "38;5;201",  // purple
+];
+
+const HEAD_ANSI = "1;37"; // bold bright white
+
+/**
+ * Colorize ref names in `git log --oneline --decorate` output.
+ * Parses `(ref-list)` patterns and wraps each ref in distinct ANSI
+ * 256-color codes. HEAD gets a fixed bold white. All other refs
+ * (branches, tags) rotate through an 8-color palette consistently.
+ */
+function colorizeLog(log: string): string {
+  // First pass: collect all unique ref names for consistent color assignment
+  const refNames = new Set<string>();
+  const refListRe = /\(([^)]+)\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = refListRe.exec(log)) !== null) {
+    for (const part of m[1].split(/,\s*/)) {
+      const trimmed = part
+        .replace(/^(HEAD -> |HEAD\b|tag: |tags: )/g, "")
+        .trim();
+      if (trimmed) refNames.add(trimmed);
+    }
+  }
+
+  // Assign a rotating color to each unique ref name
+  const colorMap = new Map<string, string>();
+  let idx = 0;
+  for (const name of refNames) {
+    colorMap.set(name, REF_COLORS[idx % REF_COLORS.length]);
+    idx++;
+  }
+
+  // Second pass: wrap each ref in the `(...)` list with ANSI codes
+  return log
+    .split("\n")
+    .map((line) => {
+      return line.replace(
+        /\(([^)]+)\)/g,
+        (_, refList: string) => {
+          const colored = refList
+            .split(/,\s*/)
+            .map((ref: string) => {
+              // "HEAD -> branchname"
+              const headArrow = ref.match(/^(HEAD)\s*->\s*(.+)$/);
+              if (headArrow) {
+                const head = `\x1b[${HEAD_ANSI}mHEAD\x1b[0m`;
+                const branchColor = colorMap.get(headArrow[2]) || REF_COLORS[0];
+                const branch = `\x1b[${branchColor}m${headArrow[2]}\x1b[0m`;
+                return `${head} -> ${branch}`;
+              }
+              // bare HEAD (detached)
+              if (ref === "HEAD") {
+                return `\x1b[${HEAD_ANSI}mHEAD\x1b[0m`;
+              }
+              // "tag: tagname"
+              const tagMatch = ref.match(/^tag:\s*(.+)$/);
+              if (tagMatch) {
+                const color = colorMap.get(tagMatch[1]) || REF_COLORS[0];
+                return `\x1b[${color}m${ref}\x1b[0m`;
+              }
+              // plain ref (branch, remote)
+              const color = colorMap.get(ref) || REF_COLORS[0];
+              return `\x1b[${color}m${ref}\x1b[0m`;
+            })
+            .join(", ");
+          return `(${colored})`;
+        },
+      );
+    })
+    .join("\n");
+}
+
+// -- Shared git log helper -----------------------------------------
+
+/**
+ * Run a colored git log and display it in the TUI.
+ * Shared between /hatl and the post-switch log in /hat.
+ */
+async function showGitLog(
+  ctx: { ui: { notify: (msg: string, level: string) => void } },
+  count: number = 10,
+): Promise<void> {
+  const validCount = Number.isFinite(count) && count > 0 ? count : 10;
+
+  try {
+    const result = await import("child_process").then((cp) =>
+      cp.execFileSync("git", [
+        "log",
+        "--graph",
+        "--oneline",
+        "--decorate",
+        "--all",
+        `-${validCount}`,
+      ], { encoding: "utf-8" }),
+    ) as string;
+
+    const raw = result.trim();
+    if (!raw) {
+      return; // silently ignore empty log
+    }
+
+    const colored = colorizeLog(raw);
+    const footer = `\n\x1b[90m\u2022 /hatl N  for more lines\x1b[0m`;
+    ctx.ui.notify(colored + footer, "info");
+  } catch {
+    // non-critical — silently ignore
+  }
+}
+
+// -- Extension -----------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+  let currentBranch: string | null = null;
+  let currentRole: string | null = null; // null = no match (read-only)
+  let config: MergedConfig = loadConfig();
+  let cwdAbsolute = "";
+
+  // -- Helpers -------------------------------------------------
+
+  async function detectBranch(): Promise<string | null> {
+    try {
+      const result = await pi.exec("git", ["branch", "--show-current"]);
+      const branch = result.stdout.trim();
+      if (branch.length > 0) return branch;
+    } catch {
+      return null;
+    }
+
+    // Detached HEAD — check for in-progress rebase
+    try {
+      const gitDirResult = await pi.exec("git", ["rev-parse", "--git-dir"]);
+      const gitDir = gitDirResult.stdout.trim();
+      const rebaseHead = resolve(gitDir, "rebase-merge", "head-name");
+      const content = await readFile(rebaseHead, "utf8");
+      const ref = content.trim();
+      const branchName = ref.replace("refs/heads/", "");
+      return branchName || null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function updateRole(ctx?: {
+    ui: { setStatus: (key: string, value: string | undefined) => void };
+  }): Promise<void> {
+    // Save old state for change detection
+    const oldBranch = currentBranch;
+    const oldRole = currentRole;
+
+    const branch = await detectBranch();
+    currentBranch = branch;
+    config = loadConfig();
+    currentRole = branch ? detectRole(branch, config) : null;
+
+    // Only log on actual branch or role change
+    if (currentRole && currentBranch &&
+        (currentBranch !== oldBranch || currentRole !== oldRole)) {
+      await recordBranchUsage(currentRole, currentBranch);
+    }
+
+    if (ctx) {
+      const label = currentBranch
+        ? currentRole
+          ? `${roleIcon(currentRole)} ${currentRole} (${currentBranch})`
+          : `\u2753 no-role (${currentBranch})`
+        : "no-git";
+      ctx.ui.setStatus("git-hat", label);
+    }
+  }
+
+  function getEffectiveRole(): string | null {
+    return currentRole;
+  }
+
+  // -- /hat command ---------------------------------------------
+
+  pi.registerCommand("hat", {
+    description: "TUI branch selector. /hat info | /hat todo | /hat log",
+    handler: async (args, ctx) => {
+      const sub = args?.trim().toLowerCase();
+
+      // /hat todo: show pending vs report coverage
+      // Note: plan/*.md files are excluded — they store future ideas, not actionable todos.
+      // scanTodos() already reads only from the todo/ directory.
+      if (sub === "todo") {
+        await handleTodo(pi, ctx);
+        return;
+      }
+
+      // /hat log: show last 5 switch history entries (most recent first)
+      if (sub === "log") {
+        const { history } = loadBranchHistory();
+        if (history.length === 0) {
+          ctx.ui.notify("No switches recorded yet", "info");
+          return;
+        }
+        const entries = history.slice(-5).reverse();
+        const lines = entries.map((e) => {
+          const ts = new Date(e.ts);
+          const now = new Date();
+          const diffMs = now.getTime() - ts.getTime();
+          const diffSec = Math.floor(diffMs / 1000);
+          let relative: string;
+          if (diffSec < 60) relative = `${diffSec}s ago`;
+          else if (diffSec < 3600) relative = `${Math.floor(diffSec / 60)}m ago`;
+          else if (diffSec < 86400) relative = `${Math.floor(diffSec / 3600)}h ago`;
+          else relative = `${Math.floor(diffSec / 86400)}d ago`;
+          const iso = ts.toISOString().replace("T", " ").slice(0, 19);
+          return `[${e.role}] ${e.branch}  @ ${iso} (${relative})`;
+        });
+        ctx.ui.notify(lines.join("\n"), "info");
+        return;
+      }
+
+      // /hat info: show role status
+      if (sub === "info") {
+        const desc = currentRole ? config.roles[currentRole]?.description ?? "" : "";
+        const roleFile = currentRole ? await loadRoleFile(ctx.cwd, currentRole, config) : null;
+        const usingFile = roleFile ? ` | using ${config.fileDir}/${currentRole}.md` : "";
+
+        const roleDisplay = currentRole
+          ? `${roleIcon(currentRole)} ${currentRole}${usingFile}`
+          : "\u2753 No matching role (read-only mode)";
+
+        ctx.ui.notify(
+          `${roleDisplay}\n` +
+            `branch: ${currentBranch ?? "not a git repo"}\n` +
+            `${desc ? `desc: ${desc}\n` : ""}` +
+            `roles: ${config.configFile}`,
+          "info",
+        );
+        return;
+      }
+
+      // /hat: TUI role/branch selector (default, no args)
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/hat requires TUI mode", "warning");
+        return;
+      }
+
+      const { grouped, roleOrder, unmatched } = await listBranchesByRole(config, ctx.cwd);
+
+      // Build flat items for SelectList, grouped by role (no role headers)
+      const selectItems: SelectItem[] = [];
+      for (const role of roleOrder) {
+        const entries = grouped[role] || [];
+        for (const entry of entries) {
+          const suffix = entry.isCurrent
+            ? " \u2190 current"
+            : entry.isLastUsed
+              ? " \u2190 last"
+              : "";
+          selectItems.push({
+            value: entry.branch,
+            label: `${entry.branch}${suffix}`,
+          });
+        }
+      }
+
+      // Add unmatched branches (at bottom, no header)
+      for (const branch of unmatched) {
+        selectItems.push({
+          value: branch,
+          label: branch,
+        });
+      }
+
+      if (selectItems.length === 0) {
+        ctx.ui.notify("No branches match any role pattern", "info");
+        return;
+      }
+
+      const result = await ctx.ui.custom<string | null>(
+        (tui, theme, _kb, done) => {
+          const container = new Container();
+
+          container.addChild(
+            new DynamicBorder((s: string) => theme.fg("accent", s)),
+          );
+
+          container.addChild(
+            new Text(theme.fg("accent", theme.bold("Switch Branch")), 1, 0),
+          );
+
+          const selectList = new SearchableSelectList(selectItems, Math.min(selectItems.length, 20), {
+            selectedPrefix: (t) => theme.fg("accent", t),
+            selectedText: (t) => theme.fg("accent", t),
+            description: (t) => theme.fg("muted", t),
+            scrollInfo: (t) => theme.fg("dim", t),
+            noMatch: (t) => theme.fg("warning", t),
+          });
+
+          selectList.onSelect = (item) => {
+            if (item.value.startsWith("__header_")) return; // ignore headers
+            done(item.value);
+          };
+          selectList.onCancel = () => done(null);
+
+          container.addChild(selectList);
+
+          container.addChild(
+            new Text(
+              theme.fg("dim", "\u2191\u2193 navigate \u2022 enter switch \u2022 esc cancel \u2022 type to search"),
+              1,
+              0,
+            ),
+          );
+
+          container.addChild(
+            new DynamicBorder((s: string) => theme.fg("accent", s)),
+          );
+
+          return {
+            render: (w) => container.render(w),
+            invalidate: () => container.invalidate(),
+            handleInput: (data) => {
+              selectList.handleInput(data);
+              tui.requestRender();
+            },
+          };
+        },
+        { overlay: true },
+      );
+
+      if (result) {
+        // Require confirmation before switching branches
+        if (ctx.hasUI) {
+          const confirmed = await ctx.ui.confirm(`Switch to branch "${result}"?`);
+          if (!confirmed) {
+            ctx.ui.notify("Switch cancelled", "info");
+            return;
+          }
+        }
+        try {
+          const switchResult = await pi.exec("git", ["switch", result]);
+          if (switchResult.code === 0) {
+            ctx.ui.notify(`Switched to branch: ${result}`, "info");
+            await updateRole(ctx);  // updateRole handles history logging via change detection
+            // Show colored git log after switch (opt-out via roles.json postSwitchLog: false)
+            if (config.postSwitchLog) {
+              await showGitLog(ctx, 10);
+            }
+          } else {
+            ctx.ui.notify(`\x1b[31mFailed to switch: ${switchResult.stderr}\x1b[0m`, "error");
+          }
+        } catch (e) {
+          ctx.ui.notify(`\x1b[31mFailed to switch: ${(e as Error).message}\x1b[0m`, "error");
+        }
+      }
+    },
+  });
+
+  // -- /hatt command (alias for /hat todo) ----------------------
+
+  pi.registerCommand("hatt", {
+    description: "Ancestry check + list pending todo items",
+    handler: async (_args, ctx) => {
+      // Ancestry check first (blocking check)
+      const ancestry = await verifyAncestry(config, ctx.cwd);
+
+      if (!ancestry.ok) {
+        const lines = ancestry.violations.map(
+          (v) => `  \u274C ${v.branch} (${v.role}) — run: git rebase ${v.branch}`,
+        );
+        ctx.ui.notify(
+          `\u26A0\uFE0F Ancestry violations — upstream branches not merged in:\n${lines.join("\n")}`,
+          "warning",
+        );
+        return; // block further processing until ancestry is fixed
+      }
+
+      await handleTodo(pi, ctx);
+
+      ctx.ui.notify("\u2705 Ancestry check passed", "info");
+    },
+  });
+
+  // -- /hatl command: colored git log ---------------------------
+
+  pi.registerCommand("hatl", {
+    description: "Show colored git log with branch graph",
+    handler: async (args, ctx) => {
+      const count = args?.trim() ? parseInt(args.trim(), 10) : 10;
+      await showGitLog(ctx, count);
+    },
+  });
+
+  // -- Session lifecycle ----------------------------------------
+
+  pi.on("session_start", async (event, ctx) => {
+    cwdAbsolute = ctx.cwd;
+
+    // Seed bundled roles/ files to project .pi/ before loading config
+    // (this ensures roles.json exists on first startup so loadConfig() doesn't throw)
+    if (event.reason === "startup") {
+      const bundledRoleDir = resolve(EXTENSION_DIR, "roles");
+      let bundledEntries: string[] = [];
+      try {
+        bundledEntries = await readdir(bundledRoleDir);
+      } catch {
+        // directory doesn't exist or can't read — skip silently
+      }
+
+      const mdFiles = bundledEntries.filter((e) => e.endsWith(".md"));
+      if (mdFiles.length > 0) {
+        // Ensure .pi/ directory exists before copying into it
+        await mkdir(resolve(ctx.cwd, ".pi"), { recursive: true });
+      }
+      const copied: string[] = [];
+      for (const file of mdFiles) {
+        // Lowercase the filename so exact match in loadRoleFile() works on first try
+        const lowerName = file.toLowerCase();
+        const target = resolve(ctx.cwd, ".pi", lowerName);
+        if (existsSync(target)) continue; // skip existing files
+        try {
+          await copyFile(resolve(bundledRoleDir, file), target);
+          copied.push(lowerName);
+        } catch {
+          // copy failed (permissions, disk full, etc.) — skip silently
+        }
+      }
+
+      // Also seed roles.json from bundled roles/ to project .pi/ if not present
+      const bundledRolesJson = resolve(bundledRoleDir, "roles.json");
+      const projectRolesJson = resolve(ctx.cwd, ".pi", "roles.json");
+      if (!existsSync(projectRolesJson)) {
+        try {
+          await copyFile(bundledRolesJson, projectRolesJson);
+          copied.push("roles.json");
+        } catch {
+          // copy failed — skip silently
+        }
+      }
+
+      if (copied.length > 0) {
+        ctx.ui.notify(`Seeded: ${copied.join(", ")}`, "info");
+      }
+    }
+
+    config = loadConfig();
+    await updateRole(ctx);
+
+    // Print startup info (same as /hat info, plus config file path)
+    const desc = currentRole ? config.roles[currentRole]?.description ?? "" : "";
+    const roleFile = currentRole
+      ? await loadRoleFile(ctx.cwd, currentRole, config)
+      : null;
+    const usingFile = roleFile ? ` | using ${config.fileDir}/${currentRole}.md` : "";
+
+    const roleDisplay = currentRole
+      ? `${roleIcon(currentRole)} ${currentRole}${usingFile}`
+      : "\u2753 No matching role (read-only mode)";
+
+    ctx.ui.notify(
+      `${roleDisplay}\n` +
+        `branch: ${currentBranch ?? "not a git repo"}\n` +
+        `${desc ? `desc: ${desc}\n` : ""}` +
+        `roles: ${config.configFile}`,
+      "info",
+    );
+  });
+
+  pi.on("input", async (event, ctx) => {
+    if (config.redetectOnInput) {
+      await updateRole(ctx);
+    }
+    return { action: "continue" };
+  });
+
+  // -- Re-detect after every turn (catches git checkout/switch) --
+
+  pi.on("turn_end", async (_event, ctx) => {
+    if (config.redetectOnInput) {
+      await updateRole(ctx);
+    }
+  });
+
+  // -- System prompt injection ----------------------------------
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    cwdAbsolute = ctx.cwd;
+    config = loadConfig();
+    await updateRole();
+
+    // No match -> strict read-only mode
+    if (!currentRole || !currentBranch) {
+      return {
+        systemPrompt:
+          event.systemPrompt +
+          `
+
+## Restricted Mode: Read-Only
+
+No role matched the current branch (\`${currentBranch ?? "no git repo"}\`).
+You are in **strict read-only mode**. You can:
+
+- Read any file with \`read\` / \`grep\` / \`find\`
+- Run read-only bash commands (ls, cd, pwd, git status/log/diff/branch)
+- Switch to a matching branch via /hat (TUI selector)
+
+**What you CANNOT do:**
+- \`write\` or \`edit\` any file
+- Run destructive bash commands
+- Make any changes to the repository
+
+If the user asks you to make changes, tell them to switch to an appropriate branch first.`,
+      };
+    }
+
+    // Try loading a custom .md file for this role
+    const roleFile = await loadRoleFile(ctx.cwd, currentRole, config);
+    if (roleFile) {
+      return {
+        systemPrompt:
+          event.systemPrompt +
+          `\n\n## Your Role: ${currentRole} (from ${config.fileDir}/${currentRole}.md)\n\n${roleFile}`,
+      };
+    }
+
+    // Fall back to built-in instructions if available
+    const lower = currentRole.toLowerCase();
+    const builtin = BUILTIN_INSTRUCTIONS[lower];
+    if (builtin) {
+      return { systemPrompt: event.systemPrompt + builtin };
+    }
+
+    // No custom file and no builtin -> just use the role name as context
+    const desc = config.roles[currentRole]?.description;
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        `\n\n## Your Role: ${currentRole}\n\nYou are in **${currentRole.toUpperCase()}** mode on branch \`${currentBranch}\`.${desc ? `\n${desc}` : ""}`,
+    };
+  });
+
+  // -- Guard rails: tool_call interception ----------------------
+
+  pi.on("tool_call", async (event, ctx) => {
+    const isWrite = event.toolName === "edit" || event.toolName === "write";
+    const isBash = event.toolName === "bash";
+
+    // No match (unknown role): read-only + branch switching only
+    if (!currentRole) {
+      if (isWrite) {
+        return {
+          block: true,
+          reason:
+            `\u2753 No role matched branch "${currentBranch ?? "no-git"}". ` +
+            `All edits and writes are blocked. Switch to a matching branch via /hat (TUI selector).`,
+        };
+      }
+      if (isBash) {
+        const cmd = ((event.input as { command?: string }).command ?? "").trim();
+
+        // Allow: read-only commands
+        if (
+          /^(ls|cd|pwd|echo|date|which|whoami|uname|hostname|env|true|false|yes|time|seq|head|tail|wc|sort|uniq|jq|dirname|basename|cat|printf)\b/.test(
+            cmd,
+          )
+        ) {
+          return;
+        }
+
+        // Allow: git read-only commands
+        if (
+          /^git\s+(status|log|diff|branch|show|grep|blame|describe|rev-parse|rev-list|shortlog|config|check-ignore|whatchanged|cherry|name-rev|ls-tree|ls-files|ls-remote|stash\s+list|tag)\b/.test(
+            cmd,
+          )
+        ) {
+          return;
+        }
+
+        // Allow: git branch switching
+        if (/^git\s+(switch|checkout)\b/.test(cmd)) {
+          return;
+        }
+
+        // Allow: git add and git rebase --continue during an active rebase
+        let rebasing = false;
+        try {
+          const gitDirResult = await pi.exec("git", ["rev-parse", "--git-dir"]);
+          rebasing = existsSync(resolve(gitDirResult.stdout.trim(), "rebase-merge"));
+        } catch { /* not a git repo */ }
+        if (rebasing && /^git\s+(add|rebase\s+--continue)\b/.test(cmd)) {
+          return;
+        }
+
+        return {
+          block: true,
+          reason:
+            `\u2753 No role matched branch "${currentBranch ?? "no-git"}". ` +
+            `Only read-only commands and git branch-switching are allowed.`,
+        };
+      }
+      return;
+    }
+
+    // Planner: branch must be based on master/main
+    if (currentRole?.toLowerCase() === "planner") {
+      const ancestry = await isMasterOrMainAncestor(ctx.cwd);
+      if (!ancestry.ok) {
+        if (isWrite) {
+          return {
+            block: true,
+            reason: `\uD83D\uDCCB Planner: branch not based on ${ancestry.branch}. Run \`git rebase ${ancestry.branch}\` first.`,
+          };
+        }
+        if (isBash) {
+          const cmd = ((event.input as { command?: string }).command ?? "").trim();
+          if (!/^git\s+(rebase\s+(master|main)|switch|checkout)\b/.test(cmd)) {
+            return {
+              block: true,
+              reason: `\uD83D\uDCCB Planner: branch not based on ${ancestry.branch}. Run \`git rebase ${ancestry.branch}\` first.`,
+            };
+          }
+        }
+      }
+    }
+
+    // Known roles: only intercept edit/write
+    if (!isWrite) return;
+
+    const rawPath = (event.input as { path?: string }).path ?? "";
+    const path = normalisePath(rawPath, ctx.cwd, cwdAbsolute);
+
+    const lowerRole = currentRole.toLowerCase();
+
+    // Planner: only todo/, plan/, docs/*.md
+    if (lowerRole === "planner") {
+      if (isInside(path, ["todo", "plan", "docs"])) {
+        if (path.startsWith("todo/")) {
+          const nn = extractNN(path.replace("todo/", ""));
+          if (nn !== null && nn <= (await findMaxNN(ctx.cwd))) {
+            return {
+              block: true,
+              reason: `\uD83D\uDCCB Planner: NN must be > max in todo/ and report/. You used ${String(nn).padStart(2, "0")}. Use ${String((await findMaxNN(ctx.cwd)) + 1).padStart(2, "0")} or higher.`,
+            };
+          }
+        }
+        return;
+      }
+      return {
+        block: true,
+        reason: `\uD83D\uDCCB Planner: can only write to todo/, plan/, and docs/*.md. Blocked: ${rawPath}`,
+      };
+    }
+
+    // Implementor: block todo/, plan/, .pi/
+    if (lowerRole === "implementor") {
+      if (isInside(path, ["todo", "plan", ".pi"])) {
+        const name = path.startsWith(".pi") ? ".pi/" : path.split("/")[0] + "/";
+        return {
+          block: true,
+          reason: `\uD83D\uDEE0 Implementor: cannot write to ${name}. Blocked: ${rawPath}`,
+        };
+      }
+      return;
+    }
+
+    // Reviewer: only todo/
+    if (lowerRole === "reviewer") {
+      if (isInside(path, ["todo"])) return;
+      return {
+        block: true,
+        reason: `\uD83D\uDD0D Reviewer: can only write to todo/ (to mark items done). Blocked: ${rawPath}`,
+      };
+    }
+
+    // Admin: only .pi/ and *.md in the project root
+    if (lowerRole === "admin") {
+      if (isInside(path, [".pi"]) || (path.endsWith(".md") && !path.includes("/"))) return;
+      return {
+        block: true,
+        reason: `\u2699 Admin: can only write to .pi/ and *.md in the project root. Blocked: ${rawPath}`,
+      };
+    }
+
+    // Custom roles: no hard write restrictions (base-enforce handles it)
+    return;
+  });
+
+  // -- Post-write validation (planner only) ---------------------
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (currentRole !== "planner") return;
+    if (event.toolName !== "write" && event.toolName !== "edit") return;
+
+    const rawPath = (event.input as { path?: string }).path ?? "";
+    const path = normalisePath(rawPath, ctx.cwd, cwdAbsolute);
+    if (!path.startsWith("todo/")) return;
+
+    const validatorPath = resolve(ctx.cwd, "scripts", "validate-todo.py");
+    try {
+      await readFile(validatorPath, "utf8");
+    } catch {
+      return;
+    }
+
+    try {
+      const result = await pi.exec("python3", [validatorPath, resolve(ctx.cwd, path)]);
+      if (result.code !== 0) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `\u26A0\uFE0F Validation failed for ${path}:\n${result.stderr || result.stdout}\nFix and retry.`,
+            },
+          ],
+          isError: true,
+          details: {},
+        };
+      }
+    } catch {
+      return;
+    }
+  });
+}