@senomas/pi-git-hat 0.2.3 → 0.2.6

package/lib/role-file.ts

@@ -0,0 +1,194 @@
+/**
+ * Role file loading for git-hat.
+ *
+ * Loads role-specific .md files from the project .pi/ directory or
+ * the extension-bundled roles/ directory. Also contains the built-in
+ * instruction constants used as fallback when no .md file exists.
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { MergedConfig } from "./types.js";
+
+/** Directory containing this extension file. Used to resolve bundled roles/ directory. */
+export const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Load a role's .md file from the project's fileDir directory.
+ * Case-insensitive lookup if config.caseInsensitive is true.
+ *
+ * Search order:
+ *   1. {cwd}/{fileDir}/{role}.md (project-local, highest priority)
+ *   2. {extensionDir}/roles/{role}.md (extension-bundled fallback)
+ */
+export 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.
+
+export 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)
+`,
+};

package/lib/todo-utils.ts

@@ -0,0 +1,244 @@
+/**
+ * Todo utilities for git-hat.
+ *
+ * Functions for scanning todo/ files, verifying ancestry of branches,
+ * checking master/main ancestry, and the /hat todo handler.
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { MergedConfig, PendingItem, TodoFile } from "./types.js";
+import { detectRole } from "./config.js";
+
+/** Extract NN sequence number from a todo/ or report/ filename. */
+export 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. */
+export 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;
+}
+
+/** Scan todos and cross-reference with reports. */
+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") };
+}
+
+/** Ancestry check: verify current branch descends from ancestor role branches. */
+export 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. */
+export 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" };
+}
+
+/** /hat todo handler: scan todos, notify user, and send follow-up for pending items. */
+export 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" },
+    );
+  }
+}

package/lib/tool-enforcement.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool enforcement engine — reusable by extensions and packages.
+ *
+ * Provides types and functions for config-driven tool rule evaluation.
+ *
+ * Exports:
+ *   - RegexObj, ToolRule (types)
+ *   - testRegex()      — recursive regex matching (string / any / all)
+ *   - evaluateToolRules()  — first-match-wins rule evaluation
+ */
+
+// -- Types ---------------------------------------------------------
+
+export interface RegexObj {
+  type: "any" | "all";
+  regex: (string | RegexObj)[];
+}
+
+export interface ToolRule {
+  type: "allow" | "block" | "confirm";
+  regex: string | RegexObj;
+  reason?: string;
+}
+
+// -- Regex matching ------------------------------------------------
+
+/**
+ * Recursively test a command against a regex pattern.
+ *
+ * - **string**: direct `new RegExp(regex).test(command)`, invalid patterns skipped
+ * - **`{ type: "any", regex: [...] }`**: true if **any** sub-regex matches (OR)
+ * - **`{ type: "all", regex: [...] }`**: true if **all** sub-regexes match (AND)
+ *
+ * Sub-regexes can themselves be strings or nested `RegexObj` values.
+ */
+export function testRegex(regex: string | RegexObj, command: string): boolean {
+  if (typeof regex === "string") {
+    try {
+      return new RegExp(regex).test(command);
+    } catch {
+      return false;
+    }
+  }
+  // RegexObj
+  if (regex.type === "any") {
+    return regex.regex.some((r) => testRegex(r, command));
+  }
+  // type === "all"
+  return regex.regex.every((r) => testRegex(r, command));
+}
+
+// -- Rule evaluation -----------------------------------------------
+
+/**
+ * Evaluate a command against an ordered list of tool rules.
+ *
+ * **First matching rule wins**: if a rule matches and its type is `"allow"`,
+ * the command is permitted. If `"block"`, the command is denied with an
+ * optional reason. If `"confirm"`, the command requires user confirmation.
+ * If no rule matches, the command also requires user confirmation (safe default).
+ *
+ * @param rules - Array of `ToolRule` objects, or `undefined` (treated as "not configured")
+ * @param command - The string to test (bash command, tool name, etc.)
+ * @returns
+ *   - `{ allowed: true }` — command is permitted unconditionally
+ *   - `{ allowed: false, reason }` — command is denied
+ *   - `{ allowed: true, confirm: true, reason }` — command requires user confirmation
+ */
+export function evaluateToolRules(
+  rules: ToolRule[] | undefined,
+  command: string,
+): { allowed: boolean; confirm?: boolean; reason?: string; matched: boolean } {
+  if (!rules || rules.length === 0) {
+    // No rules defined or empty array = caller should fall back to hardcoded behaviour
+    return { allowed: true, matched: false };
+  }
+  for (const rule of rules) {
+    if (testRegex(rule.regex, command)) {
+      if (rule.type === "allow") {
+        return { allowed: true, matched: true };
+      }
+      if (rule.type === "confirm") {
+        return { allowed: true, confirm: true, reason: rule.reason, matched: true };
+      }
+      // block
+      return { allowed: false, reason: rule.reason, matched: true };
+    }
+  }
+  // No rule matched — caller should continue to next stage
+  return { allowed: true, matched: false };
+}

package/lib/types.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared type definitions for git-hat extension.
+ *
+ * Re-exported from git-hat.ts into lib/ to reduce file size.
+ */
+
+export 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;
+}
+
+export 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[];
+}
+
+export 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;
+}
+
+export 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;
+}
+
+import type { ToolRule } from "./tool-enforcement.js";
+
+// -- Re-export for convenience
+export type { ToolRule };
+
+export interface SwitchLogEntry {
+  ts: string;
+  role: string;
+  branch: string;
+}
+
+export interface BranchHistory {
+  [role: string]: string | undefined;
+}
+
+export interface BranchEntry {
+  branch: string;
+  role: string;
+  isCurrent: boolean;
+  isLastUsed: boolean;
+}
+
+export interface PendingItem {
+  lineno: number;
+  header: string;
+  covered: boolean;
+}
+
+export interface TodoFile {
+  file: string;
+  pending: PendingItem[];
+  reportExists: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@senomas/pi-git-hat",
-	"version": "0.2.3",
+	"version": "0.2.6",
 	"description": "Pi extension for role-based Git branch workflows — wear different hats by switching branches",
 	"type": "module",
 	"keywords": ["pi-package", "git", "workflow", "branching", "roles"],

package/roles/_default.md

@@ -0,0 +1,26 @@
+# Workflow Rules
+
+## Role boundaries
+- Different roles (planner, implementor, reviewer, admin) may be run by different people or on different machines.
+- Do **not** assume another role will act on your suggestions or that the current user manages all roles.
+- Focus only on the work assigned to your current role.
+- If a task requires a different role, report it in the report and stop.
+- **Follow your role strictly to the letter.** Do not deviate from your role's defined write permissions and responsibilities.
+
+## Branch discipline
+- Do NOT switch branches unless the user explicitly asks.
+- Do NOT create new branches on your own.
+- Let the user handle all git branch operations.
+- When the user tells you to "switch to X" or "go to branch X", they mean **you should run `git switch X` yourself** — treat it as an explicit instruction to execute the command.
+- When the user says "rebase X", they mean **run `git rebase X`** — rebase the current branch onto X. Do NOT interpret it as "switch to X".
+- After a successful rebase, **show the commit tree** (`git log --oneline --graph --all --decorate` or `/hatl`) so the user can see the new state.
+- When the user says "commit", they mean **run `git add` and `git commit` yourself** — treat it as an explicit instruction to execute.
+
+## Enforcement
+- If an enforcement rule blocks you, respect it.
+- Do NOT try to sidestep enforcement with scripts, alternative tools, or workarounds.
+- Explain to the user what is blocked and why, and show the command they can run manually to unblock.
+
+## Never suggest branch switching
+- **Never suggest or recommend switching branches.** Not as advice, not as a next step — under any circumstance.
+- Wait for the user to explicitly ask or tell you.