@senomas/pi-git-hat 0.2.5 → 0.2.6

package/git-hat.ts

@@ -29,16 +29,25 @@
  * Post-switch log can be disabled by setting `"postSwitchLog": false` in roles.json
  *
  * Inspired by "wearing a different hat" -- architect hat vs builder hat.
+ *
+ * -- Library modules (lib/) --
+ *
+ * Types:         lib/types.ts
+ * Config:        lib/config.ts          (loadConfig, detectRole)
+ * Branch hist:   lib/branch-history.ts  (loadBranchHistory, recordBranchUsage, listBranchesByRole)
+ * Path utils:    lib/paths.ts           (normalisePath, stripCdPrefix, isInside, isWritablePath)
+ * Role files:    lib/role-file.ts       (loadRoleFile, BUILTIN_INSTRUCTIONS, EXTENSION_DIR)
+ * Todo utils:    lib/todo-utils.ts      (extractNN, findMaxNN, verifyAncestry, isMasterOrMainAncestor, handleTodo)
+ * Git UI:        lib/git-ui.ts          (roleIcon, showGitLog)
+ * Enforcement:   lib/tool-enforcement.ts (testRegex, evaluateToolRules, ToolRule, RegexObj)
+ * TUI:           lib/searchable-select-list.ts (SearchableSelectList)
  */
 
 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 { readFile, readdir, mkdir, copyFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import {
   Container,
   type SelectItem,
@@ -46,918 +55,18 @@ import {
 } from "@earendil-works/pi-tui";
 import { SearchableSelectList } from "./lib/searchable-select-list.js";
 import {
-  type RegexObj,
-  type ToolRule,
   testRegex,
   evaluateToolRules,
 } from "./lib/tool-enforcement.js";
 
-// -- Types ---------------------------------------------------------
-
-interface WritablePathEntry {
-  /** Directory or file path (relative to project root). Empty string = project root. */
-  path: string;
-  /** Optional file extension filter, e.g. "md" — if set, only files with this extension are writable. */
-  extension?: string;
-}
-
-interface RoleDef {
-  pattern: string;
-  description?: string;
-  ancestorRoles?: string[];
-  tool?: ToolRule[];
-  /** Tool rules evaluated after default post-tool rules (snake_case key "post-tool" in JSON). */
-  postTool?: ToolRule[];
-  writablePaths?: WritablePathEntry[];
-}
-
-interface RolesConfig {
-  version?: number;
-  roles?: Record<string, RoleDef>;
-  defaultRole?: string;
-  fileDir?: string;
-  caseInsensitive?: boolean;
-
-  default?: {
-    /** Tool rules evaluated before role-specific rules (snake_case key "pre-tool" in JSON). */
-    preTool?: ToolRule[];
-    /** Tool rules evaluated after role-specific rules (snake_case key "post-tool" in JSON). */
-    postTool?: ToolRule[];
-  };
-
-  postSwitchLog?: boolean;
-}
-
-interface MergedConfig {
-  roles: Record<string, RoleDef>;
-  fileDir: string;
-  caseInsensitive: boolean;
-
-  /** Default pre-tool rules loaded from roles.json default.pre-tool */
-  preTool?: ToolRule[];
-  /** Default post-tool rules loaded from roles.json default.post-tool */
-  postTool?: ToolRule[];
-
-  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,
-
-    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.postSwitchLog !== undefined) merged.postSwitchLog = raw.postSwitchLog;
-        if (raw.default) {
-          if (raw.default["pre-tool"] !== undefined) merged.preTool = raw.default["pre-tool"];
-          if (raw.default["post-tool"] !== undefined) merged.postTool = raw.default["post-tool"];
-        }
-      } 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;
-}
-
-/**
- * Strip a leading `cd <dir> && ` prefix from a bash command if <dir> resolves
- * to a path inside the project. Supports relative paths (resolved against cwd).
- *
- * Examples:
- *   "cd docs && ls -la"         → "ls -la"
- *   "cd ../outside && ls"      → "cd ../outside && ls" (unchanged — outside project)
- *   "ls -la"                    → "ls -la" (unchanged — no cd prefix)
- */
-function stripCdPrefix(cmd: string, cwd: string, cwdAbsolute: string): string {
-  const match = cmd.match(/^cd\s+(\S+)\s*&&\s*/);
-  if (!match) return cmd;
-  const dir = match[1];
-  const rest = cmd.slice(match[0].length);
-  // Resolve the directory: absolute path, relative path, or ~
-  let resolved: string;
-  if (dir.startsWith("/")) {
-    resolved = dir;
-  } else if (dir.startsWith("~")) {
-    return cmd; // home dir — can't guarantee it's inside project, keep as-is
-  } else {
-    resolved = resolve(cwd, dir);
-  }
-  // Check if resolved path is inside the project
-  if (resolved.startsWith(cwdAbsolute)) {
-    return rest;
-  }
-  return cmd;
-}
-
-/** 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 + "/"));
-}
-
-/**
- * Check if a path matches one of the given writable path entries.
- *
- * - If `entry.path` is empty string, only root-level files match.
- * - If `entry.extension` is set, the path must end with that extension.
- * - A trailing slash is appended automatically when matching directories.
- */
-function isWritablePath(path: string, writablePaths: WritablePathEntry[]): boolean {
-  return writablePaths.some((entry) => {
-    const dir = entry.path;
-    const ext = entry.extension;
-    // Check directory match
-    const inDir =
-      dir === ""
-        ? !path.includes("/") // root level only
-        : path === dir || path.startsWith(dir + "/");
-    if (!inDir) return false;
-    // Check extension filter (if set)
-    if (ext) {
-      return path.endsWith("." + ext);
-    }
-    return true; // no extension filter = allow any file in this dir
-  });
-}
-
-/**
- * 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)
-`,
-
-  researcher: `
-
-## Your Role: Researcher
-
-You are **RESEARCHER**. Switching branch does not switch your role.
-
-## What you do
-- Research with \`find\` / \`grep\` / \`ls\` / \`web_search\` / \`read\`
-- Write findings to \`docs/*.md\` and root \`*.md\` files
-
-## 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;
-  }
-
-  const remaining = result.totalPending - result.totalCovered;
-
-  if (remaining === 0) {
-    ctx.ui.notify("\u2714\uFE0F No more task in todo", "info");
-    return;
-  }
-
-  ctx.ui.notify(result.summary, "info");
-
-  if (remaining > 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";
-  if (lower === "researcher") return "\uD83D\uDD2C";
-  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
-  }
-}
+import type { MergedConfig } from "./lib/types.js";
+import { loadConfig, detectRole } from "./lib/config.js";
+import { recordBranchUsage, listBranchesByRole } from "./lib/branch-history.js";
+import { loadRoleFile, BUILTIN_INSTRUCTIONS, EXTENSION_DIR } from "./lib/role-file.js";
+import { normalisePath, stripCdPrefix, isInside, isWritablePath } from "./lib/paths.js";
+import { extractNN, findMaxNN, verifyAncestry, isMasterOrMainAncestor, handleTodo } from "./lib/todo-utils.js";
+import { roleIcon, showGitLog, showGitStatus, colorizeLog } from "./lib/git-ui.js";
+import type { ExecFunction } from "./lib/git-ui.js";
 
 // -- Extension -----------------------------------------------------
 
@@ -967,6 +76,9 @@ export default function (pi: ExtensionAPI) {
   let config: MergedConfig = loadConfig();
   let cwdAbsolute = "";
 
+  // -- Wrapper around pi.exec for lib functions that accept ExecFunction --
+  const execFn: ExecFunction = (cmd, args) => pi.exec(cmd, args);
+
   // -- Helpers -------------------------------------------------
 
   async function detectBranch(): Promise<string | null> {
@@ -1039,31 +151,6 @@ export default function (pi: ExtensionAPI) {
         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 ?? "" : "";
@@ -1148,19 +235,15 @@ export default function (pi: ExtensionAPI) {
             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,
+              theme.fg(
+                "muted",
+                "Type to filter \u00B7 \u2191/\u2193 navigate \u00B7 Enter select \u00B7 Esc/q cancel",
+              ),
+              1, 0,
             ),
           );
 
@@ -1168,6 +251,11 @@ export default function (pi: ExtensionAPI) {
             new DynamicBorder((s: string) => theme.fg("accent", s)),
           );
 
+          selectList.onSelect = (item) => {
+            done(item.value);
+          };
+          selectList.onCancel = () => done(null);
+
           return {
             render: (w) => container.render(w),
             invalidate: () => container.invalidate(),
@@ -1180,13 +268,20 @@ export default function (pi: ExtensionAPI) {
         { overlay: true },
       );
 
+      if (!result) {
+        ctx.ui.notify("Branch switch cancelled.", "info");
+        return;
+      }
+
+      // Switch to selected branch
       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;
+        // Check `/hat switch`-style direct branch switching
+        if (sub && !["info", "todo", "log"].includes(sub)) {
+          // "/hat somebranch": generate a TUI selector for extra safety
+          const candidates = selectItems.filter((s) => s.value === sub);
+          if (candidates.length > 0) {
+            // Already handled by TUI above — this path is for direct branch switching
+            // For direct /hat branch, fall through to switch
           }
         }
         try {
@@ -1196,7 +291,7 @@ export default function (pi: ExtensionAPI) {
             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);
+              await showGitLog(ctx, 10, execFn);
             }
           } else {
             ctx.ui.notify(`\x1b[31mFailed to switch: ${switchResult.stderr}\x1b[0m`, "error");
@@ -1211,42 +306,80 @@ export default function (pi: ExtensionAPI) {
   // -- /hatt command (alias for /hat todo) ----------------------
 
   pi.registerCommand("hatt", {
-    description: "Ancestry check + list pending todo items",
+    description: "Check ancestry + list todos",
     handler: async (_args, ctx) => {
-      // Ancestry check first (blocking check)
+      // Check ancestry first
       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}`,
+          (v) => `  \u274C ${v.branch}: not ancestor of ${v.currentBranch}`,
         );
         ctx.ui.notify(
-          `\u26A0\uFE0F Ancestry violations — upstream branches not merged in:\n${lines.join("\n")}`,
+          `Ancestry violations:\n${lines.join("\n")}\n\n` +
+            `Rebase or merge these branches into ${currentBranch} first, then retry.`,
           "warning",
         );
-        return; // block further processing until ancestry is fixed
+        return;
       }
 
       await handleTodo(pi, ctx);
-
-      ctx.ui.notify("\u2705 Ancestry check passed", "info");
     },
   });
 
-  // -- /hatl command: colored git log ---------------------------
+  // -- /hatl command: colored git log + separator + git status --
 
   pi.registerCommand("hatl", {
-    description: "Show colored git log with branch graph",
+    description: "Show colored git log + git status. /hatl N for N lines (default 10).",
     handler: async (args, ctx) => {
-      const count = args?.trim() ? parseInt(args.trim(), 10) : 10;
-      await showGitLog(ctx, count);
+      const count = parseInt(args?.trim() || "10", 10);
+      const validCount = Number.isFinite(count) && count > 0 ? count : 10;
+      const SEPARATOR = "\n\x1b[90m\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\x1b[0m\n";
+
+      try {
+        // Single shell command: git log then separator then git status
+        const result = await pi.exec("sh", ["-c",
+          `git log --graph --oneline --decorate --all -${validCount} && echo "__SEP__" && git status --short`,
+        ]);
+        const output = result.stdout;
+
+        // Split at the separator marker
+        const sepIdx = output.indexOf("__SEP__");
+        if (sepIdx === -1) {
+          // No separator found — show raw output as fallback
+          ctx.ui.notify(output.trim(), "info");
+          return;
+        }
+
+        const logRaw = output.slice(0, sepIdx).trim();
+        const statusRaw = output.slice(sepIdx + 7).trim(); // 7 = length of "__SEP__"
+
+        // Build output: colored log + styled separator + status
+        let display = "";
+
+        if (logRaw) {
+          display += colorizeLog(logRaw);
+        }
+
+        display += SEPARATOR;
+
+        if (statusRaw) {
+          display += statusRaw;
+        } else {
+          display += `\x1b[32m\u2713\x1b[0m working tree clean`;
+        }
+
+        const footer = `\n\x1b[90m\u2022 /hatl N  for more lines\x1b[0m`;
+        ctx.ui.notify(display + footer, "info");
+      } catch (e) {
+        ctx.ui.notify(`\x1b[31m/hatl error: ${(e as Error).message}\x1b[0m`, "error");
+      }
     },
   });
 
   // -- /hatr command: TUI branch selector for rebase ------------------
 
   pi.registerCommand("hatr", {
-    description: "TUI branch selector — pick a role-matched branch to rebase onto",
+    description: "TUI branch selector for rebase",
     handler: async (_args, ctx) => {
       // Edge case: detached HEAD or non-git directory
       const branch = await detectBranch();
@@ -1409,7 +542,8 @@ export default function (pi: ExtensionAPI) {
             `Rebase onto ${result} succeeded. Updated commit tree:`,
             "info",
           );
-          await showGitLog(ctx, 10);
+          await showGitLog(ctx, 10, execFn);
+          await showGitStatus(ctx, currentBranch, execFn);
         } else {
           ctx.ui.notify(
             `Rebase onto ${result} failed:\n${rebaseResult.stderr}\n\nResolve conflicts manually, then run \`git rebase --continue\`.`,
@@ -1528,7 +662,6 @@ export default function (pi: ExtensionAPI) {
     if (!currentRole || !currentBranch) {
       return {
         systemPrompt:
-          event.systemPrompt +
           `
 
 ## Restricted Mode: Read-Only
@@ -1549,28 +682,27 @@ If the user asks you to make changes, tell them to switch to an appropriate bran
       };
     }
 
-    // Try loading a custom .md file for this role
+    // Load _default.md first (base workflow rules), then the role file
+    const defaultFile = await loadRoleFile(ctx.cwd, "_default", config);
     const roleFile = await loadRoleFile(ctx.cwd, currentRole, config);
+    if (defaultFile && roleFile) {
+      return { systemPrompt: roleFile + "\n\n" + defaultFile };
+    }
     if (roleFile) {
-      return {
-        systemPrompt:
-          event.systemPrompt +
-          `\n\n## Your Role: ${currentRole} (from ${config.fileDir}/${currentRole}.md)\n\n${roleFile}`,
-      };
+      return { systemPrompt: 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 };
+      return { 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}` : ""}`,
     };
   });
@@ -1675,7 +807,17 @@ If the user asks you to make changes, tell them to switch to an appropriate bran
           block: true,
           reason:
             "Piping to a shell interpreter is blocked for security. " +
-            "Use the `write` or `edit` tool to create or modify files.",
+            "Use `execFileSync` or direct commands instead.",
+        };
+      }
+
+      // Block curl/wget/fetch to unknown hosts (data exfiltration)
+      if (/\b(curl|wget)\s+/.test(cmd)) {
+        return {
+          block: true,
+          reason:
+            "`curl` and `wget` are blocked by default. " +
+            "Contact the project admin to add an exception for specific hosts.",
         };
       }