@gonrocca/zero-pi 0.1.48 → 0.1.50

package/README.md

@@ -67,7 +67,8 @@ into `/forge` for you.
 | ------- | ------------ |
 | **`/zero-models`** | Pick the model + provider for each SDD phase — a boxed-window picker, or set one directly. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
-| **`/zero-sync`** | Folds each run's spec delta into a canonical, project-wide spec store. |
+| **`/zero-sync` / `/zero-archive`** | Folds each run's spec delta into a canonical, project-wide spec store and archives approved runs. |
+| **Git / PR / Issues** | `/zero-branch`, `/zero-git-validate`, `/zero-pr`, and `/zero-issue` keep branches and GitHub links audit-ready. |
 | **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
 | **Provider guard** | Warns when the `anthropic` provider runs on a metered API key instead of your subscription. |
 | **Startup banner** | The violet ANSI-Shadow `ZERO` wordmark, drawn once at pi startup — `ZERO_HEADER=off` to disable. |
@@ -83,9 +84,76 @@ into `/forge` for you.
 | ------- | ---- |
 | `/forge <feature>` | Run the SDD pipeline — `--continue [slug]` resumes. |
 | `/zero-models [<phase>=[<provider>/]<model>]` | Show or set per-phase models — `autotune=auto\|ask\|off`. |
-| `/zero-sync <slug>` | Fold a run's delta into the canonical spec store. |
+| `/zero-sync <slug>` | Fold a run's spec delta into the canonical spec store; a first all-`## ADDED` delta creates the store lazily. |
+| `/zero-archive <slug>` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-<slug>/`, and persist `archivePath`. |
+| `/zero-validate <slug>` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
+| `/zero-status` | Show each `.sdd/` run's artifact, sync, latest-verdict, and GitHub-link status. |
+| `/zero-branch <slug>` | Create/reuse the configured SDD Git branch and persist `branch`/`baseBranch`. |
+| `/zero-git-validate <slug>` | Check worktree, branch, remote, `gh auth`, and verdict gating before PR/archive. |
+| `/zero-pr <slug>` | Create an audit-ready GitHub PR from a run that already has verdict `pasa`. |
+| `/zero-issue <slug>` | Create or reuse a GitHub issue for a run and persist the link. |
+| `/zero-diff <slug>` | Preview the logical spec-store merge without writing files. |
 | `/zero-resume` | Write the session handoff note now. |
 
+### Git / PR / Issues
+
+Recommended flow: `/zero-branch <slug>` → `/zero-issue <slug>` → `/forge <slug>` → `/zero-git-validate <slug> --for=pr` → `/zero-pr <slug>` → `/zero-archive <slug>`.
+
+`links.json` is forward-compatible and may contain:
+
+```json
+{
+  "issueNumber": 12,
+  "issueUrl": "https://github.com/org/repo/issues/12",
+  "branch": "sdd/my-feature",
+  "baseBranch": "main",
+  "prNumber": 34,
+  "prUrl": "https://github.com/org/repo/pull/34",
+  "archivePath": ".sdd/archive/2026-05-24-my-feature"
+}
+```
+
+`/zero-branch <slug>` uses `.sdd/config.json` when present:
+
+```json
+{ "git": { "branchPrefix": "sdd/", "numbering": false, "autoCommit": false, "commitStyle": "conventional", "baseBranch": "main" } }
+```
+
+
+`/zero-pr <slug>` builds a PR title/body from `.sdd/<slug>/proposal.md`,
+`spec.md`, `design.md`, and `tasks.md`, then saves the returned `prNumber` and
+`prUrl` into `.sdd/<slug>/links.json`. It only runs after the run's latest
+recorded verdict is `pasa`; if an issue was already linked, the PR body includes
+`Closes #N`.
+
+`/zero-issue <slug>` searches open GitHub issues for the exact normalized title
+before creating a new one, then saves `issueNumber` and `issueUrl` in the same
+`links.json`. Both commands require the `gh` CLI to be installed and
+authenticated (`gh auth login`). `--type=<label>` is optional: when the label
+exists in the repository it is passed to `gh`, and when it does not exist the
+command continues without it.
+
+The implementation shells out through `gh` rather than GitHub-specific Node
+SDKs, keeping zero-pi dependency-free and portable across Windows, macOS, and
+Linux as long as GitHub CLI is on `PATH`.
+
+### Spec deltas
+
+`/zero-sync` and `/zero-diff` understand four delta sections: `## ADDED`, `## MODIFIED`, `## REMOVED`, and `## RENAMED`. `RENAMED` keeps the requirement's store position while changing its stable name:
+
+```md
+## RENAMED
+
+### REQ: new-name
+
+from: old-name
+
+Updated requirement body.
+
+Acceptance criteria:
+- ...
+```
+
 ## 🔧 Configuration
 
 zero-pi keeps its state in `~/.pi/zero.json` (per-phase models + autotune mode)

package/extensions/gh-runner.ts

@@ -0,0 +1,79 @@
+export interface GhResult<T = unknown> { ok: boolean; data?: T; stderr?: string; exitCode?: number }
+export interface DetectData { available: boolean; version?: string; hint?: string }
+export interface SpawnLike { (command: string, args: string[], options?: Record<string, unknown>): { stdout?: NodeJS.ReadableStream; stderr?: NodeJS.ReadableStream; on(event: string, cb: (...args: any[]) => void): unknown } }
+
+function hint(): string {
+  return "no encontré el `gh` CLI. Instalalo:\n  Windows: winget install GitHub.cli\n  macOS:   brew install gh\n  Linux:   apt install gh   (o el equivalente de tu distro)\ny después corré `gh auth login` una vez.";
+}
+
+function run(spawn: SpawnLike, args: string[]): Promise<GhResult<string>> {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    try {
+      const child = spawn("gh", args, { stdio: ["ignore", "pipe", "pipe"] });
+      child.stdout?.on("data", (d) => { stdout += String(d); });
+      child.stderr?.on("data", (d) => { stderr += String(d); });
+      child.on("error", (err: Error) => {
+        if (!settled) { settled = true; resolve({ ok: false, stderr: err.message, exitCode: -1 }); }
+      });
+      child.on("close", (code: number) => {
+        if (!settled) { settled = true; resolve({ ok: code === 0, data: stdout.trim(), stderr: stderr.trim(), exitCode: code }); }
+      });
+    } catch (err) {
+      resolve({ ok: false, stderr: err instanceof Error ? err.message : String(err), exitCode: -1 });
+    }
+  });
+}
+
+function parseJson<T>(result: GhResult<string>, fallback: T): GhResult<T> {
+  if (!result.ok) return { ok: false, stderr: result.stderr, exitCode: result.exitCode };
+  if (!result.data) return { ok: true, data: fallback, stderr: result.stderr, exitCode: result.exitCode };
+  try { return { ok: true, data: JSON.parse(result.data) as T, stderr: result.stderr, exitCode: result.exitCode }; }
+  catch { return { ok: false, stderr: "gh devolvió JSON inválido", exitCode: result.exitCode }; }
+}
+
+function parseVersion(stdout: string | undefined): string | undefined {
+  const match = (stdout ?? "").match(/\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/);
+  return match?.[1];
+}
+
+function parseCreatedUrl(stdout: string | undefined, kind: "pull" | "issues"): { number?: number; url?: string } {
+  const lines = (stdout ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const url = [...lines].reverse().find((l) => /^https:\/\/github\.com\/.+/.test(l));
+  const number = url ? Number((new RegExp(`/${kind}/(\\d+)(?:$|[?#])`).exec(url) ?? /\/(?:pull|pulls|issues)\/(\d+)(?:$|[?#])/.exec(url))?.[1]) : undefined;
+  return { url, number: Number.isFinite(number) ? number : undefined };
+}
+
+export function createGhRunner({ spawn }: { spawn: SpawnLike }) {
+  return {
+    async detect(): Promise<GhResult<DetectData>> {
+      const r = await run(spawn, ["--version"]);
+      return r.ok ? { ok: true, data: { available: true, version: parseVersion(r.data) } } : { ok: true, data: { available: false, hint: hint() }, stderr: r.stderr, exitCode: r.exitCode };
+    },
+    async listLabels(): Promise<GhResult<string[]>> {
+      const r = await run(spawn, ["label", "list", "--json", "name", "--limit", "200"]);
+      const parsed = parseJson<Array<{ name?: string }>>(r, []);
+      if (!parsed.ok) return parsed as GhResult<string[]>;
+      return { ok: true, data: (parsed.data ?? []).map((l) => l.name).filter((n): n is string => typeof n === "string") };
+    },
+    async createPr(input: { title: string; bodyFile: string; labels?: string[]; label?: string; base?: string; head?: string }): Promise<GhResult<{ number?: number; url?: string }>> {
+      const args = ["pr", "create", "--title", input.title, "--body-file", input.bodyFile];
+      if (input.base) args.push("--base", input.base);
+      if (input.head) args.push("--head", input.head);
+      for (const label of input.labels ?? (input.label ? [input.label] : [])) args.push("--label", label);
+      const r = await run(spawn, args);
+      return r.ok ? { ok: true, data: parseCreatedUrl(r.data, "pull"), stderr: r.stderr, exitCode: r.exitCode } : { ok: false, stderr: r.stderr, exitCode: r.exitCode };
+    },
+    async searchIssues(query: string): Promise<GhResult<Array<{ number: number; title: string; url?: string }>>> {
+      return parseJson(await run(spawn, ["issue", "list", "--search", query, "--state", "open", "--json", "number,title,url", "--limit", "20"]), []);
+    },
+    async createIssue(input: { title: string; bodyFile: string; labels?: string[]; label?: string }): Promise<GhResult<{ number?: number; url?: string }>> {
+      const args = ["issue", "create", "--title", input.title, "--body-file", input.bodyFile];
+      for (const label of input.labels ?? (input.label ? [input.label] : [])) args.push("--label", label);
+      const r = await run(spawn, args);
+      return r.ok ? { ok: true, data: parseCreatedUrl(r.data, "issues"), stderr: r.stderr, exitCode: r.exitCode } : { ok: false, stderr: r.stderr, exitCode: r.exitCode };
+    },
+  };
+}

package/extensions/git-runner.ts

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+
+export interface GitResult { ok: boolean; stdout: string; stderr: string; code: number }
+export type SpawnLike = typeof spawn;
+
+export interface GitRunner {
+  run(args: string[]): Promise<GitResult>;
+  currentBranch(): Promise<string>;
+  isDirty(): Promise<boolean>;
+  branchExists(branch: string, remote?: boolean): Promise<boolean>;
+  createBranch(branch: string, base?: string): Promise<GitResult>;
+  switchBranch(branch: string): Promise<GitResult>;
+  revParse(ref: string): Promise<GitResult>;
+  hasRemote(name?: string): Promise<boolean>;
+}
+
+export function createGitRunner(spawnImpl: SpawnLike = spawn): GitRunner {
+  const run = (args: string[]): Promise<GitResult> => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let child: ReturnType<SpawnLike>;
+    try {
+      child = spawnImpl("git", args, { shell: false }) as ReturnType<SpawnLike>;
+    } catch (err) {
+      resolve({ ok: false, stdout: "", stderr: err instanceof Error ? err.message : String(err), code: -1 });
+      return;
+    }
+    child.stdout?.on("data", (d: Buffer | string) => { stdout += String(d); });
+    child.stderr?.on("data", (d: Buffer | string) => { stderr += String(d); });
+    child.on("error", (err: Error) => resolve({ ok: false, stdout, stderr: err.message, code: -1 }));
+    child.on("close", (code: number | null) => resolve({ ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim(), code: code ?? -1 }));
+  });
+
+  return {
+    run,
+    async currentBranch() { return (await run(["branch", "--show-current"])).stdout; },
+    async isDirty() { return (await run(["status", "--porcelain"])).stdout.trim() !== ""; },
+    async branchExists(branch: string, remote = false) { return (await run(remote ? ["ls-remote", "--exit-code", "--heads", "origin", branch] : ["rev-parse", "--verify", branch])).ok; },
+    createBranch(branch: string, base?: string) { return run(base ? ["switch", "-c", branch, base] : ["switch", "-c", branch]); },
+    switchBranch(branch: string) { return run(["switch", branch]); },
+    revParse(ref: string) { return run(["rev-parse", "--verify", ref]); },
+    async hasRemote(name = "origin") { return (await run(["remote", "get-url", name])).ok; },
+  };
+}

package/extensions/pr-body.ts

@@ -0,0 +1,152 @@
+export interface ArtifactTexts {
+  proposal?: string;
+  spec?: string;
+  specs?: Record<string, string>;
+  design?: string;
+  tasks?: string;
+  proposalMd?: string;
+  specMd?: string;
+  tasksMd?: string;
+  verdictReasoning?: string;
+  linkedIssueNumber?: number;
+}
+
+export interface PrBodyInput { slug?: string; links?: { issueNumber?: number; branch?: string; baseBranch?: string; prUrl?: string }; artifacts: ArtifactTexts }
+
+export interface BuiltBody { title: string; body: string }
+
+function normalize(text: string | undefined): string {
+  return (text ?? "").replace(/\r\n/g, "\n").trim();
+}
+
+function proposalOf(input: ArtifactTexts): string { return input.proposalMd ?? input.proposal ?? ""; }
+function specOf(input: ArtifactTexts): string { return input.specMd ?? input.spec ?? ""; }
+function tasksOf(input: ArtifactTexts): string { return input.tasksMd ?? input.tasks ?? ""; }
+function placeholder(value: string, fallback = "<!-- vacío -->"): string { return normalize(value) || fallback; }
+
+export function extractFirstParagraph(markdown: string | undefined): string {
+  const text = normalize(markdown);
+  if (text === "") return "";
+  const withoutTitle = text.replace(/^#\s+.*(?:\n+|$)/, "");
+  for (const block of withoutTitle.split(/\n{2,}/)) {
+    const cleaned = block.trim();
+    if (cleaned !== "" && !cleaned.startsWith("#")) return cleaned;
+  }
+  return "";
+}
+
+export function extractTitle(markdown: string | undefined, fallback = "run"): string {
+  const text = normalize(markdown);
+  const line = text.split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
+  return (line || fallback).slice(0, 250);
+}
+
+export function extractSectionByHeading(markdown: string | undefined, heading: string): string {
+  const text = normalize(markdown);
+  if (text === "") return "";
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^##\\s+${escaped}\\s*$`, "im");
+  const match = re.exec(text);
+  if (!match) return "";
+  const start = match.index + match[0].length;
+  const rest = text.slice(start);
+  const next = /^##\s+/m.exec(rest);
+  return rest.slice(0, next ? next.index : undefined).trim();
+}
+
+export function extractTasksTable(tasks: string | undefined): string {
+  const text = normalize(tasks);
+  if (text === "") return "";
+  const taskMatches = [...text.matchAll(/^(?:##\s+\[[ xX]\]\s+|###\s+)(T\d+[^\n]*)/gm)];
+  if (taskMatches.length === 0) return "";
+  const rows = ["| Task | Files | Evidence |", "| --- | --- | --- |"];
+  for (const match of taskMatches) {
+    const title = match[1].trim();
+    const start = match.index ?? 0;
+    const next = text.slice(start + match[0].length).search(/^#{2,3}\s+/m);
+    const block = next === -1 ? text.slice(start) : text.slice(start, start + match[0].length + next);
+    if (!/^\s*-\s+files:\s*$/m.test(block)) continue;
+    const files = [...block.matchAll(/^\s+-\s+`([^`]+)`/gm)].map((m) => m[1]);
+    const evidence = (/^\s*-\s+evidence:\s*(.+)$/m.exec(block)?.[1] ?? "").trim();
+    if (files.length === 0) continue;
+    rows.push(`| ${title} | ${files.join("<br>")} | ${evidence || "—"} |`);
+  }
+  return rows.length > 2 ? rows.join("\n") : "";
+}
+
+export function extractAcceptanceCriteria(spec: string | undefined): string {
+  const text = normalize(spec);
+  if (text === "") return "";
+  const out: string[] = [];
+  const reqBlocks = text.split(/(?=^###\s+REQ:)/m).filter((b) => /^###\s+REQ:/m.test(b));
+  const blocks = reqBlocks.length ? reqBlocks : [text];
+  for (const block of blocks) {
+    const match = /Acceptance criteria:\s*\n([\s\S]*?)(?=\n#{2,3}\s+|\n\S(?![^\n]*\n\s*-)|$)/i.exec(block);
+    if (match?.[1]) {
+      const bullets = match[1].split("\n").map((l) => l.trim()).filter((l) => /^[-*]\s+/.test(l));
+      out.push(...bullets);
+    }
+  }
+  return out.join("\n");
+}
+
+function issueSections(input: ArtifactTexts): string[] {
+  const proposal = proposalOf(input);
+  const spec = specOf(input);
+  const sections: string[] = [];
+  const contexto = extractFirstParagraph(proposal);
+  if (contexto) sections.push("## Contexto", contexto);
+  const alcance = extractSectionByHeading(proposal, "Alcance");
+  if (alcance) sections.push("## Alcance", alcance);
+  const criteria = extractAcceptanceCriteria(spec);
+  if (criteria) sections.push("## Criterios de aceptación", criteria);
+  return sections;
+}
+
+export function buildPrBody(inputOrWrapped: ArtifactTexts | PrBodyInput, linksArg: { issueNumber?: number; branch?: string; baseBranch?: string } = {}): BuiltBody {
+  const wrapped = "artifacts" in inputOrWrapped ? inputOrWrapped as PrBodyInput : null;
+  const input = wrapped?.artifacts ?? inputOrWrapped as ArtifactTexts;
+  const links = { ...linksArg, ...(wrapped?.links ?? {}) };
+  const issueNumber = input.linkedIssueNumber ?? links.issueNumber;
+  const linkedIssue = issueNumber ? `Closes #${issueNumber}` : "Closes #\n<!-- Reemplazá # por el número de issue si existe. -->";
+  const specText = input.specs ? Object.entries(input.specs).map(([domain, spec]) => `### ${domain}\n\n${spec}`).join("\n\n") : specOf(input);
+  const body = [
+    "## 🔗 Linked Issue",
+    linkedIssue,
+    "",
+    "## SDD artifacts",
+    `- Slug: ${wrapped?.slug ?? "n/a"}`,
+    `- Branch: ${links.branch ?? "n/a"}`,
+    `- Base branch: ${links.baseBranch ?? "n/a"}`,
+    "- Artifacts: proposal.md, spec.md/specs/*/spec.md, design.md, tasks.md, veredicto.md",
+    "",
+    "## Requirements",
+    placeholder(extractAcceptanceCriteria(specText)),
+    "",
+    "## 📝 Summary",
+    placeholder(extractFirstParagraph(proposalOf(input))),
+    "",
+    "## 📂 Changes",
+    placeholder(extractTasksTable(tasksOf(input))),
+    "",
+    "## 🧪 Test evidence",
+    placeholder(input.verdictReasoning ?? ""),
+    "",
+    "## Risks",
+    placeholder(extractSectionByHeading(proposalOf(input), "Riesgos") || extractSectionByHeading(input.design, "Riesgos")),
+    "",
+    "## Verdict",
+    placeholder(input.verdictReasoning ?? "Sin veredicto registrado."),
+    "",
+    "## ✅ Checklist",
+    "- [ ] Revisé el diff local",
+    "- [ ] Corrí los tests relevantes",
+    "- [ ] Actualicé artefactos SDD si correspondía",
+  ].join("\n");
+  return { title: extractTitle(proposalOf(input)), body };
+}
+
+export function buildIssueBody(input: ArtifactTexts): BuiltBody {
+  const body = issueSections(input).join("\n\n");
+  return { title: extractTitle(proposalOf(input)), body };
+}

package/extensions/scan-guard-extension.ts

@@ -0,0 +1,104 @@
+// zero-pi — filesystem-wide scan guard, pi wiring.
+//
+// A thin pi extension that wires the pure decision logic in `scan-guard.ts` to
+// the `tool_call` hook. Before any shell tool runs, it reads the command and,
+// when the command contains a `find`/`grep -r`/`rg` rooted at a filesystem root
+// (`/`, a bare drive mount, `~`, …), blocks the call and returns a reason that
+// tells the model to scope the search to the plan's code root instead.
+//
+// Why a hard block and not just the phase-prompt guidance: the veredicto prompt
+// already says "do not run a filesystem-wide find/grep", yet a model ignored it
+// and wedged the pipeline for 6+ hours on `find / -maxdepth 12 …` (OneDrive
+// placeholder hydration never returns on Windows). A `tool_call` block is the
+// enforcement the prompt cannot be.
+//
+// All decisions live in `scan-guard.ts`; this file declares the minimal pi-API
+// surface it uses, hooks `tool_call`, and returns the block verdict. Both
+// `register` and the handler are wrapped in a swallowing `try/catch` — a failure
+// must never break a pi session, and (critically) must never block a tool by
+// accident. Dependency-free: only `scan-guard.ts` is imported.
+
+import { classifyShellCommand, GUARDED_TOOLS } from "./scan-guard.ts";
+
+// ---------------------------------------------------------------------------
+// Minimal local pi-API interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * The `tool_call` event pi emits before a tool runs. The shell command lives at
+ * `input.command`; older/other shapes may carry it at `args.command`, so the
+ * handler reads both defensively.
+ */
+interface PiToolCallEvent {
+  toolName?: string;
+  input?: { command?: unknown };
+  args?: { command?: unknown };
+}
+
+/** What a `tool_call` handler may return to stop a tool from running. */
+interface PiToolCallResult {
+  block: true;
+  reason: string;
+}
+
+/** The slice of pi's extension API the guard uses. */
+interface PiExtensionAPI {
+  on(
+    event: string,
+    handler: (event: PiToolCallEvent, ctx: unknown) => PiToolCallResult | undefined,
+  ): void;
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/** Pull the shell command string out of either event shape. */
+function readCommand(event: PiToolCallEvent): unknown {
+  return event?.input?.command ?? event?.args?.command;
+}
+
+/**
+ * The `tool_call` guard handler.
+ *
+ * Returns `{ block, reason }` only for a guarded shell tool whose command is a
+ * root-rooted scan; otherwise returns `undefined` (allow). Wrapped so any
+ * failure degrades to "allow" — the guard must never wedge a session by
+ * throwing, nor block a tool because of its own bug.
+ */
+export function handleToolCall(event: PiToolCallEvent): PiToolCallResult | undefined {
+  try {
+    if (!event || typeof event.toolName !== "string") return undefined;
+    if (!GUARDED_TOOLS.has(event.toolName)) return undefined;
+
+    const decision = classifyShellCommand(readCommand(event));
+    if (decision.block && decision.reason) {
+      return { block: true, reason: decision.reason };
+    }
+    return undefined;
+  } catch {
+    // A guard failure degrades to "allow" — never block a tool by accident.
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * The pi extension entry point.
+ *
+ * pi calls this once when the extension loads. It wires the guard handler to
+ * the `tool_call` event. The body is wrapped in a swallowing `try/catch`, and
+ * the handler is wrapped again, so neither registration nor a later failure can
+ * break a pi session. Called with no or an invalid `pi`, it no-ops cleanly.
+ */
+export default function register(pi?: unknown): void {
+  try {
+    if (!pi || typeof (pi as PiExtensionAPI).on !== "function") return;
+    (pi as PiExtensionAPI).on("tool_call", handleToolCall);
+  } catch {
+    // Registration itself must never break a pi session.
+  }
+}

package/extensions/scan-guard.ts

@@ -0,0 +1,190 @@
+// zero-pi — filesystem-wide scan guard, pure-logic module.
+//
+// An SDD subagent (most often `zero-veredicto`) sometimes tries to *rediscover*
+// where the code lives by running an unbounded `find` from the filesystem root:
+//
+//     find / -maxdepth 12 -type d -iname "*admin-data-keys*"
+//
+// On Windows this does not merely run slow — it hangs effectively forever.
+// Git Bash's `/` traversal reaches the user tree under OneDrive, and `find`
+// blocks indefinitely forcing the hydration of every cloud-only placeholder it
+// touches. A real run was caught wedged on exactly this command for 6+ hours
+// with no output, stalling the whole pipeline. The phase prompt already tells
+// the agent not to do full-tree scans, but a prompt is guidance, not
+// enforcement — a model under pressure ignored it.
+//
+// This module is the enforcement half: a pure, dependency-free classifier that
+// decides whether a shell command contains a filesystem-wide scan rooted at a
+// top-level location. The pi wiring (the `tool_call` handler that reads the
+// command and returns `{ block, reason }`) lives in `scan-guard-extension.ts`.
+// No pi imports, no filesystem, no side effects — testable with plain strings.
+//
+// Design intent — block the dangerous class, never legitimate scoped work:
+//   • Only `find` / `grep -r` / `rg` *rooted at a filesystem root* are blocked
+//     (`/`, a bare drive mount like `/c`, `C:\`, `~`, `$HOME`, …).
+//   • A scan scoped to a real subtree (`find /e/zero/.sdd -name …`,
+//     `rg foo src/`) is always allowed — the root token must be the *entire*
+//     search path, not a prefix of it.
+//   • `.` / `./` (the cwd, i.e. the code root) is always allowed.
+
+/**
+ * The guard's decision for one shell command.
+ *
+ * - `block: false` — allow the command (the common case).
+ * - `block: true`  — refuse it; `reason` explains why and how to scope it, and
+ *   the wiring surfaces it back to the model as the blocked-tool reason.
+ */
+export interface ScanGuardDecision {
+  block: boolean;
+  reason?: string;
+}
+
+/** Shell tool names whose `command` this guard inspects. */
+export const GUARDED_TOOLS: ReadonlySet<string> = new Set(["bash", "shell", "sh"]);
+
+// ---------------------------------------------------------------------------
+// Root-path detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether `token` denotes a filesystem *root* — a location so broad that a
+ * recursive scan of it traverses the whole machine (and, on Windows, hangs on
+ * OneDrive placeholder hydration).
+ *
+ * Matches, ignoring a single trailing slash:
+ *   • POSIX root            `/`
+ *   • Git Bash drive mount  `/c`, `/d`, … (a single letter, nothing deeper)
+ *   • Windows drive root    `C:`, `C:\`, `c:/`
+ *   • Home                  `~`, `$HOME`, `${HOME}`, `%USERPROFILE%`, `%HOMEPATH%`
+ *
+ * Crucially it does NOT match a *scoped* path that merely starts at a root,
+ * e.g. `/e/zero/.sdd` or `C:\Users\gonza\proj` — those are bounded and allowed.
+ */
+export function isRootPath(token: string): boolean {
+  // Strip surrounding quotes a shell would remove, and one trailing slash.
+  let t = token.trim().replace(/^['"]|['"]$/g, "");
+  if (t.length > 1) t = t.replace(/[/\\]$/, "");
+
+  if (t === "/" || t === "\\") return true;
+  if (t === "~") return true;
+
+  // Git Bash single-letter drive mount: /c, /d, … but not /c/foo.
+  if (/^\/[a-zA-Z]$/.test(t)) return true;
+
+  // Windows drive root: C:, C:\, c:/ — but not C:\Users.
+  if (/^[a-zA-Z]:[\\/]?$/.test(t)) return true;
+
+  // Home-directory environment variables, with or without braces.
+  const home = t.replace(/[/\\]$/, "");
+  if (home === "$HOME" || home === "${HOME}") return true;
+  if (/^%(USERPROFILE|HOMEPATH|HOMEDRIVE|HOME)%$/i.test(home)) return true;
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Per-segment classification
+// ---------------------------------------------------------------------------
+
+/** Split a shell line into segments on `;`, `&&`, `||`, `|`, and newlines. */
+export function splitSegments(command: string): string[] {
+  return command
+    .split(/\n|;|&&|\|\||\|/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** Tokenize one segment on whitespace (quotes kept; good enough for path ops). */
+function tokenize(segment: string): string[] {
+  return segment.split(/\s+/).filter((t) => t.length > 0);
+}
+
+/**
+ * Whether a single command segment is a root-rooted `find`.
+ *
+ * `find`'s path operands are the tokens after `find` and before the first
+ * expression primary (a token starting with `-`, `(`, `!`). If any path operand
+ * is a root path, the scan is unbounded.
+ */
+function isRootedFind(tokens: string[]): boolean {
+  // Locate the `find` argv0, allowing an env-prefix like `command` is overkill;
+  // a leading path such as `/usr/bin/find` still ends in `find`.
+  const idx = tokens.findIndex((t) => t === "find" || /[/\\]find$/.test(t));
+  if (idx === -1) return false;
+
+  for (let i = idx + 1; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok.startsWith("-") || tok === "(" || tok === "!" || tok === ")") break; // expression begins
+    if (isRootPath(tok)) return true;
+  }
+  return false;
+}
+
+/** Whether `tokens` invoke `grep` recursively (`-r`/`-R`/`--recursive`, incl. combined flags like `-rn`). */
+function isRecursiveGrep(tokens: string[]): boolean {
+  const idx = tokens.findIndex((t) => t === "grep" || /[/\\]grep$/.test(t));
+  if (idx === -1) return false;
+  return tokens
+    .slice(idx + 1)
+    .some((t) => t === "--recursive" || /^-[a-zA-Z]*[rR]/.test(t));
+}
+
+/**
+ * Whether a `grep -r` / `rg` segment targets a root path.
+ *
+ * ripgrep recurses by default, so any root target is dangerous; plain `grep`
+ * is only dangerous with a recursive flag. The path target of either is taken
+ * to be any non-flag operand that is a root path.
+ */
+function isRootedRecursiveSearch(tokens: string[]): boolean {
+  const isRg = tokens.some((t) => t === "rg" || /[/\\]rg$/.test(t));
+  const isGrep = tokens.some((t) => t === "grep" || /[/\\]grep$/.test(t));
+  if (!isRg && !isGrep) return false;
+  if (isGrep && !isRg && !isRecursiveGrep(tokens)) return false;
+
+  // Any bare (non-flag) operand that is a root path is a whole-machine scan.
+  return tokens.some((t) => !t.startsWith("-") && isRootPath(t));
+}
+
+// ---------------------------------------------------------------------------
+// Public classifier
+// ---------------------------------------------------------------------------
+
+/** The reason returned to the model when a root-rooted scan is blocked. */
+export function blockReason(command: string): string {
+  const offending = splitSegments(command).find((seg) => {
+    const tokens = tokenize(seg);
+    return isRootedFind(tokens) || isRootedRecursiveSearch(tokens);
+  });
+  return (
+    `zero scan-guard: blocked a filesystem-wide scan` +
+    (offending ? ` (\`${offending}\`)` : "") +
+    `. On Windows a \`find\`/\`grep -r\`/\`rg\` rooted at \`/\`, a drive root, or \`~\` ` +
+    `hangs indefinitely hydrating OneDrive placeholders — it does not just run slow. ` +
+    `Do not rediscover code with a full-tree scan: read the code root from the plan ` +
+    `(\`## Code roots\` in design.md, or the \`Code root:\` line in tasks.md / your task input) ` +
+    `and scope the search to that absolute path (e.g. \`find <code-root> -name …\`).`
+  );
+}
+
+/**
+ * Classify a shell command into an allow/block decision.
+ *
+ * Pure and total — never throws. Blocks when any `;`/`&&`/`|`-separated segment
+ * is a `find`, recursive `grep`, or `rg` whose search path is a filesystem root
+ * (see {@link isRootPath}). A non-string or empty command is allowed (the guard
+ * never invents a reason to block).
+ */
+export function classifyShellCommand(command: unknown): ScanGuardDecision {
+  if (typeof command !== "string" || command.trim() === "") {
+    return { block: false };
+  }
+
+  for (const segment of splitSegments(command)) {
+    const tokens = tokenize(segment);
+    if (isRootedFind(tokens) || isRootedRecursiveSearch(tokens)) {
+      return { block: true, reason: blockReason(command) };
+    }
+  }
+  return { block: false };
+}