zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/runtime/goal-todo-overlay.ts

@@ -0,0 +1,214 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+
+import { formatGoalTodoSummary, summarizeGoalTodos, type GoalTodoNode } from "../goal-todos.js";
+import type { HarnessRuntimeState } from "./state.js";
+
+function padToWidth(text: string, width: number): string {
+  const clipped = truncateToWidth(text, Math.max(1, width), "…");
+  return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+function statusIcon(status: GoalTodoNode["status"]): string {
+  if (status === "done") return "✓";
+  if (status === "skipped") return "↷";
+  if (status === "blocked") return "▲";
+  if (status === "delegated") return "⇄";
+  if (status === "claim_returned") return "◇";
+  if (status === "needs_oracle") return "◆";
+  if (status === "needs_user") return "?";
+  if (status === "in_progress") return "●";
+  return "○";
+}
+
+function statusColor(status: GoalTodoNode["status"]): "success" | "warning" | "error" | "muted" {
+  if (status === "done" || status === "skipped") return "success";
+  if (status === "blocked" || status === "needs_user") return "error";
+  if (status === "delegated" || status === "claim_returned" || status === "needs_oracle" || status === "in_progress") return "warning";
+  return "muted";
+}
+
+function goalNodes(state: HarnessRuntimeState): GoalTodoNode[] {
+  const goalId = state.runtimeGoal?.goalId;
+  if (!goalId) return [];
+  return state.goalTodos.nodes
+    .filter((node) => node.goalId === goalId)
+    .sort((left, right) => left.path.localeCompare(right.path, undefined, { numeric: true }) || left.createdAt - right.createdAt);
+}
+
+export class GoalTodoOverlayComponent implements Component {
+  private selectedTodoId?: string;
+  private listScroll = 0;
+  private detailScroll = 0;
+  private filter = "";
+  private filterEditing = false;
+  private readonly height = 22;
+
+  constructor(
+    private readonly runtimeState: HarnessRuntimeState,
+    private readonly theme: Theme,
+    private readonly done: () => void,
+    initialTodoId?: string,
+  ) {
+    this.selectedTodoId = initialTodoId;
+    this.ensureSelection();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "ctrl+c") || matchesKey(data, "escape")) {
+      if (this.filterEditing || this.filter) {
+        this.filterEditing = false;
+        this.filter = "";
+        this.listScroll = 0;
+        this.ensureSelection();
+        return;
+      }
+      this.done();
+      return;
+    }
+    if (this.filterEditing) {
+      if (matchesKey(data, "enter")) {
+        this.filterEditing = false;
+        return;
+      }
+      if (matchesKey(data, "backspace") || data === "\x7f") {
+        this.filter = this.filter.slice(0, -1);
+        this.listScroll = 0;
+        this.ensureSelection();
+        return;
+      }
+      if (data.length === 1 && data >= " " && data !== "\x7f") {
+        this.filter += data;
+        this.listScroll = 0;
+        this.ensureSelection();
+      }
+      return;
+    }
+    if (data === "/") {
+      this.filterEditing = true;
+      return;
+    }
+    if (matchesKey(data, "up")) this.moveSelection(-1);
+    else if (matchesKey(data, "down")) this.moveSelection(1);
+    else if (data === "\x1b[5~") this.detailScroll = Math.max(0, this.detailScroll - 8);
+    else if (data === "\x1b[6~") this.detailScroll += 8;
+    else if (data === "r") this.ensureSelection();
+  }
+
+  invalidate(): void {
+    this.ensureSelection();
+  }
+
+  render(width: number): string[] {
+    const th = this.theme;
+    const w = Math.max(60, width);
+    const inner = Math.max(1, w - 2);
+    const leftWidth = Math.min(48, Math.max(28, Math.floor(inner * 0.46)));
+    const rightWidth = Math.max(20, inner - leftWidth - 1);
+    const rows = this.filteredRows();
+    this.ensureSelection();
+    this.listScroll = Math.max(0, Math.min(this.listScroll, Math.max(0, rows.length - this.height)));
+    const selected = rows.find((node) => node.id === this.selectedTodoId) ?? rows[0];
+    const detail = this.detailLines(selected, rightWidth);
+    this.detailScroll = Math.max(0, Math.min(this.detailScroll, Math.max(0, detail.length - this.height)));
+
+    const title = ` ZOB Goal TODOs · ${this.runtimeState.runtimeGoal?.goalId ?? "no-goal"} `;
+    const leftRule = "─".repeat(Math.max(0, Math.floor((inner - visibleWidth(title)) / 2)));
+    const rightRule = "─".repeat(Math.max(0, inner - visibleWidth(title) - leftRule.length));
+    const lines: string[] = [th.fg("border", `╭${leftRule}`) + th.fg("accent", title) + th.fg("border", `${rightRule}╮`)];
+    const summary = this.runtimeState.runtimeGoal ? formatGoalTodoSummary(summarizeGoalTodos(this.runtimeState.goalTodos, this.runtimeState.runtimeGoal.goalId)) : "no active goal";
+    lines.push(this.row(th.fg("accent", padToWidth(summary, leftWidth)) + th.fg("dim", "│") + padToWidth(selected ? `${selected.path} ${selected.title}` : "No TODO selected", rightWidth), inner));
+    lines.push(th.fg("border", `├${"─".repeat(leftWidth)}┼${"─".repeat(rightWidth)}┤`));
+
+    const visibleRows = rows.slice(this.listScroll, this.listScroll + this.height);
+    const visibleDetail = detail.slice(this.detailScroll, this.detailScroll + this.height);
+    for (let index = 0; index < this.height; index++) {
+      const node = visibleRows[index];
+      const left = node ? this.renderNode(node, leftWidth) : index === 0 && rows.length === 0 ? th.fg("warning", "No TODOs match") : "";
+      const right = visibleDetail[index] ?? "";
+      lines.push(this.row(`${padToWidth(left, leftWidth)}${th.fg("dim", "│")}${padToWidth(right, rightWidth)}`, inner));
+    }
+
+    const filterInfo = this.filter || this.filterEditing ? ` · filter=${this.filterEditing ? ">" : ""}${this.filter || "<type>"}` : "";
+    const footer = `${rows.length} TODO rows${filterInfo} · / filter · ↑↓ select · PgUp/PgDn detail · Esc close`;
+    lines.push(th.fg("border", `├${"─".repeat(inner)}┤`));
+    lines.push(this.row(th.fg("dim", truncateToWidth(footer, inner, "…")), inner));
+    lines.push(th.fg("border", `╰${"─".repeat(inner)}╯`));
+    return lines.map((line) => truncateToWidth(line, w, ""));
+  }
+
+  private row(content: string, width: number): string {
+    return this.theme.fg("border", "│") + padToWidth(content, width) + this.theme.fg("border", "│");
+  }
+
+  private renderNode(node: GoalTodoNode, width: number): string {
+    const prefix = "  ".repeat(Math.max(0, node.depth - 1));
+    const selected = node.id === this.selectedTodoId ? "›" : " ";
+    const required = node.required ? "req" : "opt";
+    const text = `${selected}${prefix}${statusIcon(node.status)} ${node.path} ${node.title} [${required}]`;
+    return this.theme.fg(statusColor(node.status), truncateToWidth(text, width, "…"));
+  }
+
+  private detailLines(node: GoalTodoNode | undefined, width: number): string[] {
+    if (!node) return ["No TODO selected."];
+    return [
+      `${node.path} ${node.title}`,
+      `id: ${node.id}`,
+      `status: ${node.status}`,
+      `owner: ${node.owner}`,
+      `required: ${node.required}`,
+      `priority: ${node.priority}`,
+      `depth: ${node.depth}`,
+      node.parentId ? `parent: ${node.parentId}` : "parent: root",
+      node.delegation ? `delegation: ${node.delegation.status} run=${node.delegation.runId ?? "n/a"} agent=${node.delegation.agent ?? "n/a"} depth=${node.delegation.delegationDepth}` : "delegation: none",
+      node.blocker ? `blocker: ${node.blocker}` : "blocker: none",
+      node.skipReason ? `skip: ${node.skipReason}` : undefined,
+      "acceptance:",
+      ...(node.acceptanceCriteria.length ? node.acceptanceCriteria.map((item) => `- ${item}`) : ["- none"]),
+      "evidence_refs:",
+      ...(node.evidenceRefs.length ? node.evidenceRefs.map((item) => `- ${item}`) : ["- none"]),
+      "validation_commands:",
+      ...(node.validationCommands.length ? node.validationCommands.map((item) => `- ${item}`) : ["- none"]),
+    ].filter((line): line is string => typeof line === "string").map((line) => truncateToWidth(line, width, "…"));
+  }
+
+  private filteredRows(): GoalTodoNode[] {
+    const filter = this.filter.toLowerCase().trim();
+    const rows = goalNodes(this.runtimeState);
+    if (!filter) return rows;
+    return rows.filter((node) => `${node.id} ${node.path} ${node.title} ${node.status} ${node.owner}`.toLowerCase().includes(filter));
+  }
+
+  private ensureSelection(): void {
+    const rows = this.filteredRows();
+    if (rows.length === 0) {
+      this.selectedTodoId = undefined;
+      return;
+    }
+    if (!this.selectedTodoId || !rows.some((node) => node.id === this.selectedTodoId)) this.selectedTodoId = rows[0].id;
+    const selectedIndex = rows.findIndex((node) => node.id === this.selectedTodoId);
+    if (selectedIndex < this.listScroll) this.listScroll = selectedIndex;
+    if (selectedIndex >= this.listScroll + this.height) this.listScroll = selectedIndex - this.height + 1;
+  }
+
+  private moveSelection(delta: number): void {
+    const rows = this.filteredRows();
+    if (rows.length === 0) return;
+    const current = Math.max(0, rows.findIndex((node) => node.id === this.selectedTodoId));
+    const next = Math.max(0, Math.min(rows.length - 1, current + delta));
+    this.selectedTodoId = rows[next].id;
+    this.detailScroll = 0;
+    this.ensureSelection();
+  }
+}
+
+export async function showGoalTodoOverlay(ctx: ExtensionContext, state: HarnessRuntimeState, initialTodoId?: string): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("Goal TODO overlay requires an interactive UI; use /goal todo tree instead.", "warning");
+    return;
+  }
+  await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => new GoalTodoOverlayComponent(state, theme, done, initialTodoId), {
+    overlay: true,
+    overlayOptions: { anchor: "center", width: "90%", maxHeight: "80%", margin: 2 },
+  });
+}

package/.pi/extensions/zob-harness/src/runtime/mode-intent.ts

@@ -0,0 +1,144 @@
+import type { ModeName } from "../types.js";
+
+export type ZobModeIntentConfidence = "low" | "medium" | "high";
+export type ZobModeIntentRisk = "low" | "medium" | "high";
+
+export interface ZobModeIntent {
+  mode: ModeName;
+  confidence: ZobModeIntentConfidence;
+  reason: string;
+  risk?: ZobModeIntentRisk;
+}
+
+export interface ZobModeIntentValidation {
+  accepted: boolean;
+  reason: string;
+}
+
+const VALID_MODES: readonly ModeName[] = ["explore", "plan", "implement", "oracle", "factory", "orchestrator"];
+
+function modeName(value: string | undefined): ModeName | undefined {
+  return VALID_MODES.includes(value as ModeName) ? value as ModeName : undefined;
+}
+
+function confidence(value: string | undefined): ZobModeIntentConfidence | undefined {
+  if (value === "low" || value === "medium" || value === "high") return value;
+  return undefined;
+}
+
+function risk(value: string | undefined): ZobModeIntentRisk | undefined {
+  if (value === "low" || value === "medium" || value === "high") return value;
+  return undefined;
+}
+
+function decodeAttribute(value: string): string {
+  return value
+    .replace(/"/g, '"')
+    .replace(/"/g, '"')
+    .replace(/'/g, "'")
+    .replace(/'/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function attributes(source: string): Record<string, string> {
+  const parsed: Record<string, string> = {};
+  for (const match of source.matchAll(/([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g)) {
+    parsed[match[1]!] = decodeAttribute(match[2] ?? "");
+  }
+  return parsed;
+}
+
+export function extractModeIntent(text: string): ZobModeIntent | undefined {
+  const match = text.match(/<zob_mode_intent\b([^>]*)\/?\s*>/i);
+  if (!match) return undefined;
+  const attrs = attributes(match[1] ?? "");
+  const mode = modeName(attrs.mode);
+  const intentConfidence = confidence(attrs.confidence);
+  if (!mode || !intentConfidence) return undefined;
+  const reason = (attrs.reason || "same-agent mode intent").slice(0, 240);
+  return { mode, confidence: intentConfidence, reason, risk: risk(attrs.risk) };
+}
+
+export function stripModeIntentMarkup(text: string): string {
+  return text
+    .replace(/^\s*<zob_mode_intent\b[^>]*\/?\s*>\s*$\n?/gim, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function looksLikeCompletePlanResponse(text: string): boolean {
+  const visible = stripModeIntentMarkup(text);
+  if (visible.length < 240) return false;
+  const sample = visible.slice(0, 2_400);
+  let score = 0;
+  if (/^\s*#{1,3}\s+.*\bplan\b/im.test(sample) || /^\s*(?:plan|planning|roadmap)\b/im.test(sample)) score += 2;
+  if ((sample.match(/^\s*(?:#{1,4}\s*)?(?:phase|patch|étape|etape|step)\s+\d+/gim) ?? []).length >= 1) score += 1;
+  if ((sample.match(/^\s*\d+[.)]\s+/gm) ?? []).length >= 3) score += 1;
+  if ((sample.match(/^\s*[-*]\s+/gm) ?? []).length >= 4) score += 1;
+  if (/\b(validation|tests?|risques?|risks?|fichiers?|files|scope|p[eé]rim[eè]tre|objectifs?|success looks like|r[eé]sultat attendu)\b/i.test(sample)) score += 1;
+  if (/\b(impl[eé]mentation|patch|tdd|ordre recommandé|roadmap|architecture|phases?)\b/i.test(sample)) score += 1;
+  if (/<answer>|<files>|<next_steps>/i.test(sample)) score += 1;
+  return score >= 3;
+}
+
+const DESTRUCTIVE_COMMAND_PATTERN = /\b(rm\s+-rf|git\s+reset\s+--hard|git\s+clean\b|shutdown\b|reboot\b|mkfs\b)\b/i;
+const SECRET_REF_PATTERN = /(?:\.env\b|~\/\.ssh|~\/\.aws|\bssh\b|\baws\b|\b(?:api[_-]?key|private key|secret key|keys?|credentials?|secrets?)\b)/i;
+const SECRET_TOUCH_ACTION_PATTERN = /\b(read|open|cat|print|show|copy|upload|exfiltrate|inspect|touch|modify|edit|write|access|use|load|source|dump|list)\b/i;
+const NEGATIVE_SAFETY_INSTRUCTION_PATTERN = /\b(?:do not|don't|must not|never|avoid|without|forbidden_paths?|forbidden|deny(?:list)?|no secrets?|ne pas|n['’]?(?:ouvre|ouvre pas|acc[eè]de|acc[eè]de pas|lis|lis pas)|interdit|sans)\b/i;
+const PROMPT_INJECTION_NEGATIVE_PATTERN = /\b(?:do not|don't|must not|never)\s+(?:ignore|obey|follow|respect|comply|listen|refuse|decline)\b/i;
+const NEGATIVE_SECRET_CLAUSE_SPLIT_PATTERN = /\b(?:but|however|except|unless|then|also|or|and)\b|[:,]/i;
+
+function hasSecretTouchAction(part: string): boolean {
+  return SECRET_REF_PATTERN.test(part) && SECRET_TOUCH_ACTION_PATTERN.test(part);
+}
+
+function isBenignNegativeSecretInstruction(part: string): boolean {
+  if (!NEGATIVE_SAFETY_INSTRUCTION_PATTERN.test(part) || !hasSecretTouchAction(part)) return false;
+  if (PROMPT_INJECTION_NEGATIVE_PATTERN.test(part)) return false;
+
+  const [, ...tails] = part.split(NEGATIVE_SECRET_CLAUSE_SPLIT_PATTERN);
+  return !tails.some((tail) => hasSecretTouchAction(tail) && !NEGATIVE_SAFETY_INSTRUCTION_PATTERN.test(tail));
+}
+
+function looksSecretTouching(text: string): boolean {
+  return text
+    .split(/[!?;\n]+|(?<=\S)\.(?=\s|$)/)
+    .some((part) => hasSecretTouchAction(part) && !isBenignNegativeSecretInstruction(part));
+}
+
+function looksDestructive(text: string): boolean {
+  return DESTRUCTIVE_COMMAND_PATTERN.test(text) || looksSecretTouching(text);
+}
+
+function hasModeEvidence(mode: ModeName, text: string): boolean {
+  if (mode === "orchestrator") return /\b(orchestrator|orchestrat(?:e|ion|or)|orchestrer|multi[- ]?agent|lead(?:s)?|worker(?:s)?|chief vision|coordonn(?:e|er|ation)|d[eé]l[eè]gu(?:e|er|ation)|delegat(?:e|ion)|sub[- ]?agents?|subtasks?|work graph|todo graph|graphe de travail|graphe todo)\b/i.test(text);
+  if (mode === "factory") return /\b(factory|factory_run|pilot|batch|sentinel|manifest|quarantine|software factory)\b/i.test(text);
+  if (mode === "implement") return /\b(update|modify|modifier|change|changer|fix|patch|implement|impl[eé]mente|edit|write|[eé]cris|ajoute|add|create|cr[eé]e|refactor|refactorise|remplace|am[eé]lior(?:e|er)|appliqu(?:e|er)|mets?|mettre|rends?|rendre|fais\s+en\s+sorte)\b/i.test(text);
+  if (mode === "oracle") return /\b(review|validate|validation|oracle|no[_-]?ship|v[eé]rifie|audit|qa|risks?|blocker)\b/i.test(text);
+  if (mode === "plan") return /\b(plan|design|architecture|propose|roadmap|spec|sp[eé]cifie|comment|how would|strat[eé]gie)\b/i.test(text);
+  return /\b(read|explore|inspect|analy[sz]e|cherche|comprends?|trouve|diagnostic)\b/i.test(text);
+}
+
+export function validateModeIntent(intent: ZobModeIntent | undefined, currentMode: ModeName, lastUserText = "", assistantText = ""): ZobModeIntentValidation {
+  if (!intent) return { accepted: false, reason: "missing or invalid mode intent" };
+  if (intent.mode === currentMode) return { accepted: false, reason: "mode already active" };
+  if (intent.confidence === "low") return { accepted: false, reason: "low confidence mode intent ignored" };
+  if (intent.risk === "high") return { accepted: false, reason: "high-risk mode intent requires explicit user action" };
+  if (looksDestructive(`${lastUserText}\n${intent.reason}`)) return { accepted: false, reason: "destructive or secret-touching intent cannot auto-switch mode" };
+  if (intent.mode === "plan" && looksLikeCompletePlanResponse(assistantText)) {
+    return { accepted: false, reason: "plan mode intent ignored because this response already includes a complete plan" };
+  }
+
+  const evidence = hasModeEvidence(intent.mode, `${lastUserText}\n${intent.reason}`);
+  if ((intent.mode === "implement" || intent.mode === "factory" || intent.mode === "orchestrator") && intent.confidence !== "high" && !evidence) {
+    return { accepted: false, reason: `mode ${intent.mode} requires high confidence or explicit evidence` };
+  }
+  if (intent.mode === "oracle" && intent.confidence === "medium" && !evidence) {
+    return { accepted: false, reason: "oracle mode requires review/validation evidence" };
+  }
+  return { accepted: true, reason: evidence ? "accepted with user-text evidence" : "accepted high-confidence same-agent intent" };
+}

package/.pi/extensions/zob-harness/src/runtime/plan-capture.ts

@@ -0,0 +1,270 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { ModeName } from "../types.js";
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+import { looksLikeCompletePlanResponse, stripModeIntentMarkup } from "./mode-intent.js";
+
+const PLAN_INDEX_SCHEMA = "zob.plan-index.v1";
+const PLAN_CAPTURE_SCHEMA = "zob.plan-capture.v1";
+
+type PlanCaptureStatus = "draft";
+
+export interface PlanIndexEntry {
+  plan_id: string;
+  title: string;
+  created_at: string;
+  mode: ModeName | "unknown";
+  status: PlanCaptureStatus;
+  relative_path: string;
+  body_hash: string;
+  user_request_hash: string;
+  assistant_output_hash: string;
+}
+
+interface PlanIndex {
+  schema: typeof PLAN_INDEX_SCHEMA;
+  updated_at: string;
+  entries: PlanIndexEntry[];
+}
+
+export interface PlanCaptureInput {
+  assistantText: string;
+  userText?: string;
+  mode?: ModeName;
+  now?: Date;
+}
+
+export interface PlanCaptureResult {
+  captured: boolean;
+  reason: "captured" | "not_plan" | "duplicate";
+  planId?: string;
+  title?: string;
+  relativePath?: string;
+  duplicateOf?: string;
+  bodyHash?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function plansDir(repoRoot: string): string {
+  return join(repoRoot, "plans");
+}
+
+function planIndexPath(repoRoot: string): string {
+  return join(plansDir(repoRoot), "index.json");
+}
+
+function planIndexMarkdownPath(repoRoot: string): string {
+  return join(plansDir(repoRoot), "index.md");
+}
+
+function planReadmePath(repoRoot: string): string {
+  return join(plansDir(repoRoot), "README.md");
+}
+
+function normalizePlanText(text: string): string {
+  return stripModeIntentMarkup(text).replace(/\s+$/g, "").trim();
+}
+
+function userAskedForPlan(text: string | undefined): boolean {
+  if (!text) return false;
+  return /\b(plan|planning|roadmap|architecture|strat[eé]gie|sp[eé]cification|spec|conception|design|impl[eé]mentation|ordre de patch|tdd|étapes?|etapes?)\b/i.test(text);
+}
+
+export function shouldCapturePlanResponse(input: PlanCaptureInput): boolean {
+  const text = normalizePlanText(input.assistantText);
+  if (text.length < 160) return false;
+
+  // Plan capture must be intentional. Delivery reports in implement/oracle/explore modes can
+  // share plan-like formatting (files, validation, risks), so formatting alone is not enough.
+  if (input.mode !== "plan") return false;
+
+  if (looksLikeCompletePlanResponse(text)) return true;
+  const structuralSignals = [
+    /^\s*#{1,3}\s+.*\bplan\b/im.test(text),
+    /^\s*(?:plan|roadmap|objectif|objectifs|scope|p[eé]rim[eè]tre)\b/im.test(text),
+    (text.match(/^\s*(?:#{1,4}\s*)?(?:phase|patch|étape|etape|step)\s+\d+/gim) ?? []).length >= 1,
+    (text.match(/^\s*\d+[.)]\s+/gm) ?? []).length >= 3,
+    /\b(validation|tests?|risques?|risks?|fichiers?|files|succ[eè]s|success)\b/i.test(text),
+  ].filter(Boolean).length;
+  return userAskedForPlan(input.userText) ? structuralSignals >= 2 : structuralSignals >= 3;
+}
+
+export function extractPlanTitle(text: string): string {
+  const normalized = normalizePlanText(text);
+  const lines = normalized.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const heading = lines.find((line) => /^#{1,3}\s+/.test(line));
+  const candidate = heading?.replace(/^#{1,3}\s+/, "")
+    ?? lines.find((line) => /\bplan\b/i.test(line))
+    ?? lines[0]
+    ?? "ZOB plan";
+  return candidate.replace(/[<>]/g, "").slice(0, 120).trim() || "ZOB plan";
+}
+
+function emptyPlanIndex(now: Date): PlanIndex {
+  return { schema: PLAN_INDEX_SCHEMA, updated_at: now.toISOString(), entries: [] };
+}
+
+function asPlanIndexEntry(value: unknown): PlanIndexEntry | undefined {
+  if (!isRecord(value)) return undefined;
+  const planId = typeof value.plan_id === "string" ? value.plan_id : "";
+  const title = typeof value.title === "string" ? value.title : "";
+  const createdAt = typeof value.created_at === "string" ? value.created_at : "";
+  const mode = typeof value.mode === "string" ? value.mode : "unknown";
+  const status = value.status === "draft" ? "draft" : undefined;
+  const relativePath = typeof value.relative_path === "string" ? value.relative_path : "";
+  const bodyHash = typeof value.body_hash === "string" ? value.body_hash : "";
+  const userRequestHash = typeof value.user_request_hash === "string" ? value.user_request_hash : "";
+  const assistantOutputHash = typeof value.assistant_output_hash === "string" ? value.assistant_output_hash : "";
+  if (!planId || !title || !createdAt || !status || !relativePath || !bodyHash || !userRequestHash || !assistantOutputHash) return undefined;
+  return {
+    plan_id: planId,
+    title,
+    created_at: createdAt,
+    mode: mode === "explore" || mode === "plan" || mode === "implement" || mode === "oracle" || mode === "factory" ? mode : "unknown",
+    status,
+    relative_path: relativePath,
+    body_hash: bodyHash,
+    user_request_hash: userRequestHash,
+    assistant_output_hash: assistantOutputHash,
+  };
+}
+
+function readPlanIndex(repoRoot: string, now: Date): PlanIndex {
+  const indexPath = planIndexPath(repoRoot);
+  if (!existsSync(indexPath)) return emptyPlanIndex(now);
+  try {
+    const parsed = JSON.parse(readFileSync(indexPath, "utf8"));
+    if (!isRecord(parsed) || parsed.schema !== PLAN_INDEX_SCHEMA || !Array.isArray(parsed.entries)) return emptyPlanIndex(now);
+    return {
+      schema: PLAN_INDEX_SCHEMA,
+      updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : now.toISOString(),
+      entries: parsed.entries.map(asPlanIndexEntry).filter((entry): entry is PlanIndexEntry => Boolean(entry)),
+    };
+  } catch {
+    return emptyPlanIndex(now);
+  }
+}
+
+function escapeMarkdownTableCell(value: string): string {
+  return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function markdownLink(entry: PlanIndexEntry): string {
+  const href = entry.relative_path.replace(/^plans\//, "");
+  return `[${escapeMarkdownTableCell(entry.title)}](${href})`;
+}
+
+function renderPlanIndexMarkdown(index: PlanIndex): string {
+  const rows = index.entries.map((entry) => `| ${entry.created_at.slice(0, 10)} | ${markdownLink(entry)} | ${entry.mode} | ${entry.status} | ${entry.body_hash.slice(0, 12)} |`);
+  return [
+    "# ZOB Plans Index",
+    "",
+    "Visible auto-captured planning artifacts. Source user prompts are stored as hashes only; captured assistant plans are stored in the linked Markdown files.",
+    "",
+    "| Date | Plan | Mode | Status | Hash |",
+    "|---|---|---|---|---|",
+    ...(rows.length > 0 ? rows : ["| — | — | — | — | — |"]),
+    "",
+  ].join("\n");
+}
+
+function ensurePlansReadme(repoRoot: string): void {
+  const readmePath = planReadmePath(repoRoot);
+  if (existsSync(readmePath)) return;
+  writeFileSync(readmePath, [
+    "# ZOB Plans",
+    "",
+    "This directory stores visible planning artifacts automatically captured by the ZOB harness.",
+    "",
+    "- `index.md` is the human-readable index.",
+    "- `index.json` is the machine-readable duplicate-detection manifest.",
+    "- Date folders contain the captured Markdown plans.",
+    "- Source user prompts are not persisted here; hashes are used for correlation.",
+    "",
+  ].join("\n"), "utf8");
+}
+
+function writePlanIndex(repoRoot: string, index: PlanIndex): void {
+  mkdirSync(plansDir(repoRoot), { recursive: true });
+  ensurePlansReadme(repoRoot);
+  writeFileSync(planIndexPath(repoRoot), JSON.stringify(index, null, 2), "utf8");
+  writeFileSync(planIndexMarkdownPath(repoRoot), renderPlanIndexMarkdown(index), "utf8");
+}
+
+function quoted(value: string): string {
+  return JSON.stringify(value);
+}
+
+function renderPlanMarkdown(entry: PlanIndexEntry, assistantText: string): string {
+  return [
+    "---",
+    `schema: ${quoted(PLAN_CAPTURE_SCHEMA)}`,
+    `plan_id: ${quoted(entry.plan_id)}`,
+    `created_at: ${quoted(entry.created_at)}`,
+    `mode: ${quoted(entry.mode)}`,
+    `status: ${quoted(entry.status)}`,
+    `title: ${quoted(entry.title)}`,
+    `user_request_hash: ${quoted(entry.user_request_hash)}`,
+    `assistant_output_hash: ${quoted(entry.assistant_output_hash)}`,
+    `body_hash: ${quoted(entry.body_hash)}`,
+    "---",
+    "",
+    `# ${entry.title}`,
+    "",
+    "> Captured automatically by the ZOB harness. Source user prompt text is not persisted in this artifact; hashes are retained for duplicate detection.",
+    "",
+    "## Captured Plan",
+    "",
+    assistantText.trim(),
+    "",
+    "## Metadata",
+    "",
+    `- plan_id: ${entry.plan_id}`,
+    `- mode: ${entry.mode}`,
+    `- status: ${entry.status}`,
+    `- body_hash: ${entry.body_hash}`,
+    "",
+  ].join("\n");
+}
+
+export function capturePlanArtifact(repoRoot: string, input: PlanCaptureInput): PlanCaptureResult {
+  const assistantText = normalizePlanText(input.assistantText);
+  if (!shouldCapturePlanResponse({ ...input, assistantText })) return { captured: false, reason: "not_plan" };
+
+  const now = input.now ?? new Date();
+  const createdAt = now.toISOString();
+  const userText = input.userText?.trim() ?? "";
+  const bodyHash = sha256(JSON.stringify({ userText, assistantText }));
+  const index = readPlanIndex(repoRoot, now);
+  const duplicate = index.entries.find((entry) => entry.body_hash === bodyHash);
+  if (duplicate) return { captured: false, reason: "duplicate", duplicateOf: duplicate.relative_path, bodyHash };
+
+  const title = extractPlanTitle(assistantText);
+  const dateDir = createdAt.slice(0, 10);
+  const planId = safeFileStem(`plan-${createdAt.replace(/\D/g, "").slice(0, 14)}-${bodyHash.slice(0, 8)}`);
+  const slug = safeFileStem(title).toLowerCase();
+  const relativePath = `plans/${dateDir}/${planId}-${slug}.md`;
+  const absolutePath = join(repoRoot, relativePath);
+  const entry: PlanIndexEntry = {
+    plan_id: planId,
+    title,
+    created_at: createdAt,
+    mode: input.mode ?? "unknown",
+    status: "draft",
+    relative_path: relativePath,
+    body_hash: bodyHash,
+    user_request_hash: sha256(userText),
+    assistant_output_hash: sha256(assistantText),
+  };
+
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  writeFileSync(absolutePath, renderPlanMarkdown(entry, assistantText), "utf8");
+  const updatedIndex: PlanIndex = { schema: PLAN_INDEX_SCHEMA, updated_at: createdAt, entries: [entry, ...index.entries] };
+  writePlanIndex(repoRoot, updatedIndex);
+  return { captured: true, reason: "captured", planId, title, relativePath, bodyHash };
+}