@flavor-code/superharness 1.0.0

package/HARNESS.md

@@ -0,0 +1,56 @@
+# Superharness Bootstrap
+
+You have superharness: a project-level engineering discipline harness. It is loaded
+as a plugin of your host — from the local marketplace at `.claude/superharness`
+under Claude Code, or as a native plugin under `.flavor/plugins/superharness`
+under flavor-code — and this document is injected at session start by its
+SessionStart hook. The state root follows the host: `.claude/superharness/`
+under Claude Code, `.flavor/superharness/` under flavor-code.
+
+## The Rule
+
+**Before responding to ANY engineering task — including "simple" ones — check whether a
+superharness skill applies. If there is even a 1% chance a skill applies, invoke it with
+the Skill tool before doing anything else.**
+
+## Available Skills
+
+| Skill | Invoke when |
+|-------|-------------|
+| `superharness:go` | The user gives a task goal to complete end-to-end (also triggered by `/superharness:go <goal>`) |
+| `superharness:brainstorm` | ONLY when the user explicitly runs `/superharness:brainstorm <topic>` — never self-invoke. Requirements/design dialogue with a live browser mind map |
+| `superharness:light` | Small, focused tasks that need discipline without the full go machinery — quick fixes, small features, config/docs tweaks, prototypes. Lighter go: TDD with explicit exemptions, real-output verification, root-cause debugging; no worktree, no plan file, no ralph tracking |
+| `superharness:writing-plans` | A multi-step task needs an implementation plan, before touching code |
+| `superharness:using-git-worktrees` | Starting feature work that needs an isolated workspace, before implementation (go Phase 0.5) |
+| `superharness:finishing-a-development-branch` | Worktree/branch work is done, verified, and reviewed — merge it back, remove the worktree, delete the branch (go Phase 5) |
+| `superharness:subagent-driven-development` | Executing a multi-task plan with independent tasks in the current session (go Phase 2) |
+| `superharness:test-driven-development` | Implementing ANY feature or bugfix, before writing implementation code |
+| `superharness:systematic-debugging` | Any bug, test failure, or unexpected behavior, before proposing fixes |
+| `superharness:requesting-code-review` | A task or major feature is complete, before moving on or merging |
+| `superharness:verification-before-completion` | About to claim work is complete, fixed, or passing |
+
+## Non-Negotiable Constraints
+
+1. **TDD always.** Write the failing test first, watch it fail (RED), write minimal code,
+   watch it pass (GREEN), refactor, commit. Implementation code written before its test
+   gets deleted and redone. See `superharness:test-driven-development`.
+2. **Evidence before claims.** Never say "done", "fixed", or "passing" without running the
+   verification command in this session and seeing the output. See
+   `superharness:verification-before-completion`.
+3. **Root cause over quick fix.** When something breaks, follow the 4-phase process in
+   `superharness:systematic-debugging`. No "let me just try this" patches.
+4. **Plan before multi-step work.** Tasks with 3+ steps get a written plan
+   (`superharness:writing-plans`) saved to `<state-root>/superharness/plans/` in the
+   project, with bite-sized 2–5 minute TDD steps.
+5. **Review before declaring victory.** Significant changes get a code review pass
+   (`superharness:requesting-code-review`); Critical issues block progress.
+
+## Red Flags — STOP if you catch yourself thinking:
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple for TDD" | Simple things break too. Test first. |
+| "I'll write tests after" | That's not TDD. RED comes first. |
+| "It should work now" | Run it. Show the output. Then say it works. |
+| "Let me just try changing this" | That's guessing, not debugging. Find the root cause. |
+| "The plan is in my head" | Write it down. Plans in heads evaporate. |

package/flavor-plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "superharness",
+  "version": "1.0.0",
+  "apiVersion": "1",
+  "main": "./index.js",
+  "permissions": [],
+  "contributes": {
+    "commands": [],
+    "tools": [],
+    "hooks": [
+      { "name": "SessionStart" },
+      { "name": "UserPromptSubmit" },
+      { "name": "Stop" },
+      { "name": "SessionEnd" },
+      { "name": "BeforePlan" },
+      { "name": "AfterPlan" },
+      { "name": "SubagentStart" },
+      { "name": "SubagentStop" }
+    ],
+    "skillRoots": [
+      { "name": "superharness", "path": "./skills" }
+    ],
+    "modelAdapters": []
+  }
+}

package/index.js

@@ -0,0 +1,238 @@
+// superharness flavor-code plugin
+// Registers the superharness skill root so that go, brainstorm, tdd, etc.
+// are discovered under the /superharness namespace, and registers three
+// lifecycle hooks mirroring the Claude Code hooks:
+//   SessionStart     inject HARNESS.md (+ STACK.md when present) as additionalContext
+//   UserPromptSubmit auto-bootstrap ralph tracking on `/superharness:go <goal>`
+//   Stop             append a 'round' heartbeat to trace.jsonl while a go task runs
+// All hooks are best-effort and always return { decision: "allow" }.
+
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PLUGIN_ROOT = dirname(fileURLToPath(import.meta.url));
+const ALLOW = Object.freeze({ decision: "allow" });
+
+// The workspace path is cached from SessionStart (payload.workspace is a string);
+// hooks fall back to the process working directory when it is unavailable.
+let workspaceRoot;
+
+function projectRoot(event) {
+  const workspace = event?.payload?.workspace;
+  if (typeof workspace === "string" && workspace.length > 0) return workspace;
+  if (typeof workspaceRoot === "string" && workspaceRoot.length > 0) return workspaceRoot;
+  return process.cwd();
+}
+
+function ralphDir(root) {
+  // flavor-code host: runtime state lives under the .flavor state root
+  // (the Claude Code counterpart uses .claude/superharness/ralph).
+  return join(root, ".flavor", "superharness", "ralph");
+}
+
+function isoNow() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00");
+}
+
+function atomicWrite(path, text) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, text, "utf8");
+  renameSync(tmp, path);
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; }
+}
+
+function readText(path) {
+  try {
+    const text = readFileSync(path, "utf8");
+    return text.length > 0 ? text : undefined;
+  } catch { return undefined; }
+}
+
+function currentTaskPath(root) {
+  return join(ralphDir(root), ".current-task");
+}
+
+function getCurrentTask(root) {
+  const raw = readText(currentTaskPath(root));
+  const line = raw === undefined ? "" : raw.trim();
+  return line.length > 0 ? line : undefined;
+}
+
+function appendTrace(root, phase, traceEvent, detail) {
+  const line = JSON.stringify({ ts: isoNow(), phase, event: traceEvent, detail: detail ?? "" });
+  const path = join(ralphDir(root), "trace.jsonl");
+  mkdirSync(dirname(path), { recursive: true });
+  const existing = readText(path) ?? "";
+  writeFileSync(path, `${existing}${line}\n`, "utf8");
+}
+
+// Parse a go invocation at the start of the prompt. flavor-code invokes skills
+// as `/go <goal>`; the Claude-style `superharness:go <goal>` is also accepted.
+// Returns { goal, slug } or undefined.
+function goInvocation(prompt) {
+  if (typeof prompt !== "string") return undefined;
+  const match = /^\s*(?:\/go|superharness:go)(?:[^A-Za-z0-9_]|$)/.exec(prompt);
+  if (match === null) return undefined;
+  const goal = prompt.replace(/^\s*(?:\/go|superharness:go)[ \t]*/, "").trim();
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10);
+  const tokens = (goal.toLowerCase().match(/[a-z0-9]+/g) ?? []).slice(0, 6);
+  const kebab = tokens.length > 0
+    ? tokens.join("-")
+    : `task-${String(now.getUTCHours()).padStart(2, "0")}${String(now.getUTCMinutes()).padStart(2, "0")}${String(now.getUTCSeconds()).padStart(2, "0")}`;
+  return { goal, slug: `${date}-${kebab}` };
+}
+
+// Bootstrap a fresh go task: point .current-task, seed an empty task.json
+// (planning/plan), open the trace ledger with task:started, reset retry state.
+function startTask(root, taskId, goal) {
+  atomicWrite(currentTaskPath(root), taskId.trim());
+  atomicWrite(join(ralphDir(root), "task.json"), JSON.stringify({
+    status: "planning",
+    phase: "plan",
+    sprint: { current: 0, total: 0 },
+    tasks: [],
+    updated_at: isoNow(),
+  }));
+  appendTrace(root, "plan", "task:started", goal);
+  atomicWrite(join(ralphDir(root), ".ralph-state.json"), JSON.stringify({
+    retries: 0, max: 5, updated_at: isoNow(),
+  }));
+}
+
+function onSessionStart(event) {
+  const workspace = event?.payload?.workspace;
+  if (typeof workspace === "string" && workspace.length > 0) workspaceRoot = workspace;
+  const harness = readText(join(PLUGIN_ROOT, "HARNESS.md"));
+  if (harness === undefined) return ALLOW;
+  let context = `<EXTREMELY_IMPORTANT>\nYou have superharness. Follow it for all engineering work in this project.\n\n${harness}\n</EXTREMELY_IMPORTANT>`;
+  const stack = readText(join(PLUGIN_ROOT, "STACK.md"));
+  if (stack !== undefined) {
+    context += `\n\n<EXTREMELY_IMPORTANT>\nThis project targets a specific tech stack. Follow this guidance.\n\n${stack}\n</EXTREMELY_IMPORTANT>`;
+  }
+  return { decision: "allow", additionalContext: context };
+}
+
+function onUserPromptSubmit(event) {
+  const root = projectRoot(event);
+  const prompt = typeof event?.payload?.prompt === "string" ? event.payload.prompt : "";
+
+  // 1. Auto-trigger on a go invocation (start/repoint a task automatically).
+  const invocation = goInvocation(prompt);
+  if (invocation !== undefined && invocation.slug !== getCurrentTask(root)) {
+    startTask(root, invocation.slug, invocation.goal);
+  }
+
+  // 2. Stash the pending round so the Stop hook can record a heartbeat.
+  atomicWrite(join(ralphDir(root), ".pending-prompt.json"), JSON.stringify({ ts: isoNow(), query: prompt }));
+  return ALLOW;
+}
+
+function onStop(event) {
+  const root = projectRoot(event);
+  const pendingPath = join(ralphDir(root), ".pending-prompt.json");
+  const current = getCurrentTask(root);
+  if (current === undefined) {
+    // Not tracking a go task — drop any stray pending prompt and bail.
+    try { rmSync(pendingPath, { force: true }); } catch { /* ignore */ }
+    return ALLOW;
+  }
+  const pending = readJson(pendingPath);
+  const query = typeof pending?.query === "string" ? pending.query : "";
+  const tasks = readJson(join(ralphDir(root), "task.json"));
+  const phase = typeof tasks?.phase === "string" && tasks.phase.length > 0 ? tasks.phase : "go";
+  appendTrace(root, phase, "round", query);
+  try { rmSync(pendingPath, { force: true }); } catch { /* ignore */ }
+  return ALLOW;
+}
+
+// Called when the session ends (host fires SessionEnd). Records a final
+// trace event and clears any remaining ralph state so the next session
+// starts with a clean slate.
+function onSessionEnd(event) {
+  const root = projectRoot(event);
+  const current = getCurrentTask(root);
+  if (current === undefined) return ALLOW;
+  const tasks = readJson(join(ralphDir(root), "task.json"));
+  const phase = typeof tasks?.phase === "string" && tasks.phase.length > 0 ? tasks.phase : "go";
+  appendTrace(root, phase, "session:end", "session ended");
+  // Clear the active-task pointer so the Stop hook no longer records heartbeats.
+  try { rmSync(currentTaskPath(root), { force: true }); } catch { /* ignore */ }
+  return ALLOW;
+}
+
+// Called before the planning phase begins. Injects a lightweight context
+// flagging that plan mode is about to start so the model can prepare.
+function onBeforePlan(event) {
+  const root = projectRoot(event);
+  const current = getCurrentTask(root);
+  if (current === undefined) return ALLOW;
+  appendTrace(root, "plan", "plan:before", "planning phase starting");
+  return ALLOW;
+}
+
+// Called after the planning phase ends. Records the plan result and
+// advances the ralph task status so the next phase is clear.
+function onAfterPlan(event) {
+  const root = projectRoot(event);
+  const current = getCurrentTask(root);
+  if (current === undefined) return ALLOW;
+  const tasks = readJson(join(ralphDir(root), "task.json"));
+  const phase = typeof tasks?.phase === "string" && tasks.phase.length > 0 ? tasks.phase : "go";
+  appendTrace(root, phase, "plan:after", "planning phase complete");
+  return ALLOW;
+}
+
+// Called when a subagent is about to start. Records the subagent
+// launch so the trace has a clear subagent lifecycle boundary.
+function onSubagentStart(event) {
+  const root = projectRoot(event);
+  const current = getCurrentTask(root);
+  if (current === undefined) return ALLOW;
+  const tasks = readJson(join(ralphDir(root), "task.json"));
+  const phase = typeof tasks?.phase === "string" && tasks.phase.length > 0 ? tasks.phase : "go";
+  appendTrace(root, phase, "subagent:start", "subagent starting");
+  return ALLOW;
+}
+
+// Called when a subagent finishes. Records the subagent completion
+// and any errors so trace.jsonl has a complete subagent picture.
+function onSubagentStop(event) {
+  const root = projectRoot(event);
+  const current = getCurrentTask(root);
+  if (current === undefined) return ALLOW;
+  const tasks = readJson(join(ralphDir(root), "task.json"));
+  const phase = typeof tasks?.phase === "string" && tasks.phase.length > 0 ? tasks.phase : "go";
+  const outcome = typeof event?.payload?.outcome === "string" ? event.payload.outcome : "completed";
+  appendTrace(root, phase, "subagent:stop", `subagent ${outcome}`);
+  return ALLOW;
+}
+
+export function activate(context) {
+  context.registerSkillRoot("superharness", "./skills");
+
+  const guard = (fn) => (event, signal) => {
+    try { return fn(event, signal); } catch { return ALLOW; }
+  };
+  const options = { failurePolicy: "allow" };
+
+  const disposers = [
+    context.registerHook("SessionStart", guard(onSessionStart), options),
+    context.registerHook("UserPromptSubmit", guard(onUserPromptSubmit), options),
+    context.registerHook("Stop", guard(onStop), options),
+    context.registerHook("SessionEnd", guard(onSessionEnd), options),
+    context.registerHook("BeforePlan", guard(onBeforePlan), options),
+    context.registerHook("AfterPlan", guard(onAfterPlan), options),
+    context.registerHook("SubagentStart", guard(onSubagentStart), options),
+    context.registerHook("SubagentStop", guard(onSubagentStop), options),
+  ];
+  return () => { for (const dispose of disposers.reverse()) dispose(); };
+}
+
+// Exported for tests.
+export const __test = { goInvocation, onSessionStart, onUserPromptSubmit, onStop, onSessionEnd, onBeforePlan, onAfterPlan, onSubagentStart, onSubagentStop, ralphDir };

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@flavor-code/superharness",
+  "version": "1.0.0",
+  "description": "为 flavor-code 注入规划、调试、测试与交付工作流的工程增强插件。",
+  "type": "module",
+  "main": "./index.js",
+  "files": [
+    "**/*"
+  ],
+  "scripts": {},
+  "keywords": [
+    "flavor-code",
+    "flavor-plugin",
+    "workflow",
+    "skills",
+    "hooks"
+  ],
+  "author": "Flavor Code",
+  "repository": "C:\\Users\\wangzh\\Desktop\\idea\\superharness",
+  "flavorPlugin": {
+    "apiVersion": "1"
+  }
+}

package/scripts/ralph-lib.ps1

@@ -0,0 +1,297 @@
+# Ralph state mechanism — zero-dependency PowerShell state library.
+#
+# Manages the four runtime files of a resumable autonomous-task loop, all under
+# <project>/<state-root>/superharness/ralph/ where <state-root> follows the host:
+#   .claude  (Claude Code install: .claude/superharness marketplace)
+#   .flavor  (flavor-code install: .flavor/plugins/superharness)
+#   .current-task      one-line pointer to the active task (switch = rewrite the line)
+#   task.json          task-list snapshot {status,phase,sprint,tasks[],updated_at}
+#   trace.jsonl        append-only ledger, one {ts,phase,event,detail} JSON per line
+#   .ralph-state.json  retry counter {retries,max,updated_at}, capped at 5
+#
+# Dot-source this file to use the functions. The trace hooks (hooks/stop.ps1,
+# hooks/user-prompt-submit.ps1) dot-source it for go task tracking. Conventions:
+# UTF-8 without BOM, atomic temp-then-move for JSON snapshots, ISO-8601 timestamps.
+
+# ---------------------------------------------------------------- paths & helpers
+
+function Get-RalphStateRoot {
+    # Host detection: this library ships inside the host install, so its own path
+    # names the state root. $env:SUPERHARNESS_STATE_ROOT ('.claude' | '.flavor')
+    # forces a choice for unusual layouts; Claude Code is the historical default.
+    $forced = $env:SUPERHARNESS_STATE_ROOT
+    if ($forced -eq '.flavor' -or $forced -eq 'flavor') { return '.flavor' }
+    if ($forced -eq '.claude' -or $forced -eq 'claude') { return '.claude' }
+    if ($PSScriptRoot -match '[/\\]\.flavor[/\\]plugins[/\\]superharness[/\\]scripts') { return '.flavor' }
+    return '.claude'
+}
+
+function Get-RalphDir {
+    param([Parameter(Mandatory)][string]$Root)
+    $stateRoot = Get-RalphStateRoot   # '.claude' or '.flavor'
+    Join-Path $Root (Join-Path $stateRoot 'superharness\ralph')
+}
+
+function Get-RalphIso { (Get-Date).ToString('yyyy-MM-ddTHH:mm:sszzz') }
+
+function Get-RalphGoInvocation {
+    # Parse a UserPromptSubmit prompt. If it is a `/superharness:go <goal>` invocation
+    # (leading slash optional, must be at the start of the prompt), return
+    # { Goal; Slug='YYYY-MM-DD-<kebab|task-HHmmss>' }; otherwise return $null. Pure.
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string]$Prompt,
+        [datetime]$Now = (Get-Date)
+    )
+    if ($null -eq $Prompt) { return $null }
+    $m = [regex]::Match($Prompt, '^\s*/?superharness:go\b[ \t]*(?<goal>[\s\S]*)$')
+    if (-not $m.Success) { return $null }
+    $goal = $m.Groups['goal'].Value.Trim()
+    $date = $Now.ToString('yyyy-MM-dd')
+    $tokens = [regex]::Matches($goal.ToLower(), '[a-z0-9]+') | ForEach-Object { $_.Value }
+    if ($tokens.Count -gt 0) {
+        $kebab = (@($tokens) | Select-Object -First 6) -join '-'
+    } else {
+        $kebab = 'task-' + $Now.ToString('HHmmss')
+    }
+    [PSCustomObject]@{ Goal = $goal; Slug = "$date-$kebab" }
+}
+
+function New-RalphDir {
+    param([string]$Root)
+    $dir = Get-RalphDir $Root
+    if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Force $dir | Out-Null }
+    return $dir
+}
+
+function Read-RalphJson {
+    param([string]$Path)
+    if (-not (Test-Path $Path)) { return $null }
+    try { return Get-Content $Path -Raw | ConvertFrom-Json } catch { return $null }
+}
+
+function Write-RalphText {
+    # Atomic write: temp file then move-replace. UTF-8 without BOM.
+    param([string]$Path, [string]$Text)
+    $dir = Split-Path -Parent $Path
+    if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Force $dir | Out-Null }
+    $enc = New-Object System.Text.UTF8Encoding($false)
+    $tmp = "$Path.tmp"
+    [IO.File]::WriteAllText($tmp, $Text, $enc)
+    Move-Item -Path $tmp -Destination $Path -Force
+}
+
+function Write-RalphJson {
+    param([string]$Path, $Object)
+    Write-RalphText $Path (ConvertTo-Json -InputObject $Object -Depth 12 -Compress)
+}
+
+# ---------------------------------------------------------------- .current-task
+
+function Get-RalphCurrentTaskPath { param([string]$Root) Join-Path (Get-RalphDir $Root) '.current-task' }
+
+function Set-RalphCurrentTask {
+    # The pointer is a single line; switching a task rewrites only this line.
+    param([Parameter(Mandatory)][string]$Root, [Parameter(Mandatory)][string]$TaskId)
+    Write-RalphText (Get-RalphCurrentTaskPath $Root) ($TaskId.Trim())
+}
+
+function Get-RalphCurrentTask {
+    param([Parameter(Mandatory)][string]$Root)
+    $p = Get-RalphCurrentTaskPath $Root
+    if (-not (Test-Path $p)) { return $null }
+    $raw = (Get-Content $p -Raw)
+    if ($null -eq $raw) { return $null }
+    $line = $raw.Trim()
+    if ($line -eq '') { return $null }
+    return $line
+}
+
+# ---------------------------------------------------------------- task.json
+
+$script:RalphStatuses = @('pending', 'in_progress', 'done')
+
+function Get-RalphTaskPath { param([string]$Root) Join-Path (Get-RalphDir $Root) 'task.json' }
+
+function Initialize-RalphTasks {
+    # Write the task-list snapshot. Each task defaults to status 'pending'.
+    param(
+        [Parameter(Mandatory)][string]$Root,
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Tasks,
+        [string]$Status = 'planning',
+        [string]$Phase = 'implement',
+        [int]$SprintCurrent = 0,
+        [int]$SprintTotal = 0
+    )
+    $norm = @()
+    foreach ($t in $Tasks) {
+        $st = if ($t.status) { [string]$t.status } else { 'pending' }
+        if ($script:RalphStatuses -notcontains $st) { throw "Invalid task status '$st' (allowed: $($script:RalphStatuses -join ', '))" }
+        $norm += [ordered]@{ id = $t.id; name = [string]$t.name; status = $st }
+    }
+    $snapshot = [ordered]@{
+        status     = $Status
+        phase      = $Phase
+        sprint     = [ordered]@{ current = $SprintCurrent; total = $SprintTotal }
+        tasks      = $norm
+        updated_at = (Get-RalphIso)
+    }
+    Write-RalphJson (Get-RalphTaskPath $Root) $snapshot
+}
+
+function Get-RalphTasks {
+    param([Parameter(Mandatory)][string]$Root)
+    Read-RalphJson (Get-RalphTaskPath $Root)
+}
+
+function Get-RalphNextTask {
+    # The first task whose status is not 'done' — the resume entry point.
+    param([Parameter(Mandatory)][string]$Root)
+    $snap = Get-RalphTasks $Root
+    if (-not $snap) { return $null }
+    foreach ($t in @($snap.tasks)) {
+        if ($t.status -ne 'done') { return $t }
+    }
+    return $null
+}
+
+function Set-RalphTaskStatus {
+    # Idempotently set one task's status and refresh updated_at. Order preserved.
+    param(
+        [Parameter(Mandatory)][string]$Root,
+        [Parameter(Mandatory)]$Id,
+        [Parameter(Mandatory)][string]$Status
+    )
+    if ($script:RalphStatuses -notcontains $Status) { throw "Invalid task status '$Status' (allowed: $($script:RalphStatuses -join ', '))" }
+    $snap = Get-RalphTasks $Root
+    if (-not $snap) { throw "No task.json under $(Get-RalphDir $Root)" }
+    $tasks = @()
+    foreach ($t in @($snap.tasks)) {
+        $st = if ("$($t.id)" -eq "$Id") { $Status } else { [string]$t.status }
+        $tasks += [ordered]@{ id = $t.id; name = [string]$t.name; status = $st }
+    }
+    $snapshot = [ordered]@{
+        status     = [string]$snap.status
+        phase      = [string]$snap.phase
+        sprint     = [ordered]@{ current = $snap.sprint.current; total = $snap.sprint.total }
+        tasks      = $tasks
+        updated_at = (Get-RalphIso)
+    }
+    Write-RalphJson (Get-RalphTaskPath $Root) $snapshot
+}
+
+# ---------------------------------------------------------------- trace.jsonl
+
+function Get-RalphTracePath { param([string]$Root) Join-Path (Get-RalphDir $Root) 'trace.jsonl' }
+
+function Add-RalphTrace {
+    # Append a single minified {ts,phase,event,detail} line. Never rewrites earlier
+    # lines — the worst a crash can corrupt is the final line.
+    param(
+        [Parameter(Mandatory)][string]$Root,
+        [Parameter(Mandatory)][string]$Phase,
+        [Parameter(Mandatory)][string]$Event,
+        [string]$Detail = ''
+    )
+    New-RalphDir $Root | Out-Null
+    $line = ConvertTo-Json -InputObject ([ordered]@{
+        ts = (Get-RalphIso); phase = $Phase; event = $Event; detail = $Detail
+    }) -Depth 12 -Compress
+    $enc = New-Object System.Text.UTF8Encoding($false)
+    [IO.File]::AppendAllText((Get-RalphTracePath $Root), ($line + "`n"), $enc)
+}
+
+function Get-RalphTraceTail {
+    # Return the last N events (parsed), oldest-first. Empty array if no ledger.
+    param([Parameter(Mandatory)][string]$Root, [int]$Count = 1)
+    $p = Get-RalphTracePath $Root
+    if (-not (Test-Path $p)) { return @() }
+    $lines = @(Get-Content $p -Tail $Count | Where-Object { $_.Trim() -ne '' })
+    $out = @()
+    foreach ($l in $lines) { try { $out += ($l | ConvertFrom-Json) } catch {} }
+    return $out
+}
+
+# ---------------------------------------------------------------- .ralph-state.json (retry counter)
+
+function Get-RalphRetryPath { param([string]$Root) Join-Path (Get-RalphDir $Root) '.ralph-state.json' }
+
+function Get-RalphRetryState {
+    # Defaults to {retries:0, max:5} when the file is absent or malformed.
+    param([Parameter(Mandatory)][string]$Root)
+    $s = Read-RalphJson (Get-RalphRetryPath $Root)
+    $retries = 0; $max = 5; $upd = $null
+    if ($s) {
+        if ($null -ne $s.retries) { $retries = [int]$s.retries }
+        if ($null -ne $s.max)     { $max = [int]$s.max }
+        $upd = $s.updated_at
+    }
+    [PSCustomObject]@{ retries = $retries; max = $max; updated_at = $upd }
+}
+
+function Set-RalphRetryState {
+    param([Parameter(Mandatory)][string]$Root, [int]$Retries, [int]$Max)
+    $obj = [ordered]@{ retries = $Retries; max = $Max; updated_at = (Get-RalphIso) }
+    Write-RalphJson (Get-RalphRetryPath $Root) $obj
+    [PSCustomObject]@{ retries = $Retries; max = $Max; updated_at = $obj.updated_at }
+}
+
+function Add-RalphRetry {
+    # Increment the retry counter, clamped at max. Returns the new state.
+    param([Parameter(Mandatory)][string]$Root)
+    $st = Get-RalphRetryState $Root
+    $n = $st.retries + 1
+    if ($n -gt $st.max) { $n = $st.max }
+    Set-RalphRetryState -Root $Root -Retries $n -Max $st.max
+}
+
+function Test-RalphRetryExhausted {
+    param([Parameter(Mandatory)][string]$Root)
+    $st = Get-RalphRetryState $Root
+    return ($st.retries -ge $st.max)
+}
+
+function Reset-RalphRetry {
+    param([Parameter(Mandatory)][string]$Root)
+    $st = Get-RalphRetryState $Root
+    Set-RalphRetryState -Root $Root -Retries 0 -Max $st.max
+}
+
+# ---------------------------------------------------------------- task bootstrap
+
+function Start-RalphTask {
+    # Auto-bootstrap a fresh go task: point .current-task, seed an empty task.json
+    # (planning/plan — the agent enriches the task list later), open the trace ledger
+    # with a task:started event, and reset the retry counter. Idempotent-ish: calling
+    # again repoints to a new TaskId and appends another task:started line.
+    param(
+        [Parameter(Mandatory)][string]$Root,
+        [Parameter(Mandatory)][string]$TaskId,
+        [string]$Goal = ''
+    )
+    Set-RalphCurrentTask -Root $Root -TaskId $TaskId
+    Initialize-RalphTasks -Root $Root -Tasks @() -Status 'planning' -Phase 'plan'
+    Add-RalphTrace -Root $Root -Phase 'plan' -Event 'task:started' -Detail $Goal
+    Reset-RalphRetry -Root $Root | Out-Null
+}
+
+# ---------------------------------------------------------------- cold-start recovery
+
+function Get-RalphResumeContext {
+    # Assemble the deterministic file-based facts a freshly-started agent needs to
+    # resume: the active pointer, the task snapshot, the first not-done task, the
+    # last ledger event, and the retry state. The agent then reconciles these
+    # against `git diff` (code wins) and fixes task.json via Set-RalphTaskStatus.
+    param([Parameter(Mandatory)][string]$Root)
+    $snap = Get-RalphTasks $Root
+    $next = Get-RalphNextTask $Root
+    $tail = @(Get-RalphTraceTail -Root $Root -Count 1)
+    $last = if ($tail.Count -gt 0) { $tail[0] } else { $null }
+    [PSCustomObject]@{
+        current_task = (Get-RalphCurrentTask $Root)
+        tasks        = $snap
+        next_task    = $next
+        last_trace   = $last
+        all_done     = [bool]($snap -and ($null -eq $next))
+        retry        = (Get-RalphRetryState $Root)
+    }
+}