pi-baton 0.7.5 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows semantic versioning.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-14
+
+### Added
+
+- `/baton:history` lists recent completed or failed Baton runs from persisted `.pi/baton/runs/` manifests, with bounded scan/output limits, skip diagnostics for unreadable manifests, and tests for empty, single, multi-run, exclusion, scan-cap ordering, and command registration cases.
+- `/baton:status` and `formatStatusSummary` now include the stored `failure` reason for terminal failed runs, with status tests covering iteration-cap exhaustion and other failure paths.
+
+### Changed
+
+- README quick start and `docs/workflows.md` now document when to use `/baton:history` versus `/baton:status`, including the terminal-run fallback behavior for status.
+- README quick start and `docs/workflows.md` now document that `/baton:status` falls back to the most recent finished run when no active run exists.
+- Refreshed ROADMAP.md: marked S-109 done, updated release direction for 0.8.0/0.9.0, and added maintenance seed candidates S-110 through S-113 for the weekly seed planner.
+- Updated ROADMAP.md to mark S-108 done and refresh the security status table after the two-stage review gauntlet shipped in 0.7.5.
+- Aligned ROADMAP S-109 status with the shipped `docs/workflows.md` authoring guide.
+
 ## [0.7.5] - 2026-08-22
 
 ### Changed

package/README.md

@@ -39,7 +39,7 @@ pi install npm:pi-baton
 Pin a specific version when you want reproducible installs:
 
 ```bash
-pi install npm:pi-baton@0.7.5
+pi install npm:pi-baton@0.8.0
 ```
 
 Install into the current project instead of your user Pi settings:
@@ -74,9 +74,12 @@ Then run:
 /baton:new        create a workflow scaffold
 /baton:start      choose workflow + task brief → idle run
 /baton:run        execute run to terminal state (with live widget)
-/baton:status     show the active run summary
+/baton:status     show the active run summary, or the most recent finished run
+/baton:history    list recent completed or failed runs from persisted history
 ```
 
+Use `/baton:status` for the active run or the single most recent finished run. Use `/baton:history` when you need a short list of recent completed or failed runs and their `.pi/baton/runs/<id>` directories.
+
 Builtin workflows work out of the box — no agent setup required:
 
 - `Default Review Loop` (`implement → review → fix`)
@@ -97,6 +100,8 @@ Discovery order: project `.pi/agents/` → user `~/.pi/agent/agents/` → pi-bat
 
 ## Workflow authoring
 
+See [`docs/workflows.md`](docs/workflows.md) for an end-to-end walkthrough: step kinds, transitions, the review contract, `iteration_cap`, model overrides, and agent discovery order.
+
 ```txt
 /baton:new
 ```
@@ -137,12 +142,12 @@ steps:
 
 | Path | Purpose |
 |---|---|
-| `extensions/` | Slash-command entrypoints (`/baton:new`, `/baton:start`, `/baton:run`, `/baton:status`) |
+| `extensions/` | Slash-command entrypoints (`/baton:new`, `/baton:start`, `/baton:run`, `/baton:status`, `/baton:history`) |
 | `lib/` | Workflow parser, run engine, subagent runner, review contract, UI widget |
 | `agents/` | Builtin `worker` and `reviewer` subagent definitions |
 | `workflows/` | Builtin workflows (`default-review-loop.yaml`, `two-stage-review-gauntlet.yaml`) |
 | `assets/` | README / package branding assets |
-| `docs/` | Release and maintainer documentation |
+| `docs/` | Workflow authoring guide, release and maintainer documentation |
 
 ## Development
 

package/docs/workflows.md

@@ -0,0 +1,154 @@
+# Custom workflow authoring
+
+This guide walks through authoring a custom Pi Baton workflow YAML. For a compact field reference, see the [Workflow YAML reference](../README.md#workflow-yaml-reference) in the README.
+
+## Where workflows live
+
+| Location | Source | Notes |
+|---|---|---|
+| `.pi/baton/workflows/*.yaml` | user | Your custom workflows; listed first in `/baton:start` |
+| `workflows/*.yaml` (package) | builtin | Shipped with pi-baton (`default-review-loop`, `two-stage-review-gauntlet`) |
+
+Run `/baton:new` to scaffold a new file under `.pi/baton/workflows/`. The scaffold copies the default review loop and adds `<your-fast-model>` / `<your-strong-model>` placeholders on worker and reviewer steps.
+
+The **first step key** in `steps:` is the entry step when a run starts.
+
+## Step kinds
+
+Every step requires `agent` and `prompt`. Pi Baton infers the step kind from its transition fields.
+
+### Linear steps
+
+Use `next` to move unconditionally to the next step. Linear steps are for implement, fix, draft, or any work that always proceeds forward.
+
+```yaml
+implement:
+  agent: worker
+  prompt: |
+    Complete the task brief. End with a JSON summary block.
+  next: review
+```
+
+### Review steps
+
+Use `on_accept` and `on_reject` instead of `next`. Review steps gate progress on a structured judgment.
+
+```yaml
+review:
+  agent: reviewer
+  prompt: |
+    Review the work. Return accept or reject using the JSON contract.
+  on_accept: _complete   # or another step name
+  on_reject: fix
+```
+
+A step **cannot** mix `next` with `on_accept` / `on_reject`. Each step is either linear or review.
+
+## Transitions
+
+| Field | Used by | Target |
+|---|---|---|
+| `next` | linear | Another step name |
+| `on_accept` | review | `_complete` or another step name |
+| `on_reject` | review | Another step name (typically a fix step) |
+
+`_complete` is the only special token. It marks a successful terminal state — the run completes when a review step accepts into `_complete`.
+
+Transition targets must reference steps defined in the same `steps:` map (except `_complete`).
+
+### Choosing `on_accept` vs `next`
+
+- **`next`** — the step always hands off to the same successor. Use for deterministic pipelines (`draft → technical_review`).
+- **`on_accept` / `on_reject`** — the successor depends on reviewer judgment. Use when a gate can block or redirect work.
+
+### Chaining review gates
+
+The builtin `two-stage-review-gauntlet` demonstrates two review steps before completion:
+
+```
+draft → technical_review ──accept──→ editorial_review ──accept──→ _complete
+              │                              │
+              └──────── reject ──→ fix ──────┘
+                                    │
+                                    └── next → technical_review
+```
+
+After a reject, route through a fix step and re-enter the earliest gate that must re-validate the changes.
+
+## Review contract
+
+Review steps require agents to end with a fenced JSON block. Pi Baton parses `judgment`, and validates the payload before choosing a branch.
+
+**Accept** — `judgment` must be `"accept"` and `acceptanceNote` must be non-empty:
+
+```json
+{"summary":"Short review summary","judgment":"accept","acceptanceNote":"Why this passes"}
+```
+
+**Reject** — `judgment` must be `"reject"` and `findings` must be a non-empty string array:
+
+```json
+{"summary":"Short review summary","judgment":"reject","findings":["Actionable issue 1"]}
+```
+
+Non-review steps use `summary` when present and fall back to the output text when it is absent. If parsing fails on a review step, the run fails with a `ReviewContractError`.
+
+Builtin `reviewer` agent prompts include the contract. Custom review agents should instruct the model to follow the same shape.
+
+## `iteration_cap`
+
+`iteration_cap` is a required positive integer. It limits how many times a review step can **reject** before the run fails.
+
+- The counter starts at `0` when a run begins.
+- Each review **reject** increments the counter by one.
+- Before executing a review step, if `iteration >= iteration_cap`, the run fails with `Iteration cap (N) reached`.
+- Accepts and linear steps do not increment the counter.
+
+Example: `iteration_cap: 5` allows up to five review reject cycles (reviews at iterations 0–4). After the fifth reject raises the counter to 5, the next review attempt is blocked.
+
+Set the cap high enough for your loop depth but low enough to prevent runaway reject cycles.
+
+## Model overrides
+
+Each step may set an optional `model` field (`provider/model-id`, e.g. `openai/gpt-5.4`).
+
+| Situation | Model used |
+|---|---|
+| Step defines a concrete `model` | That model |
+| Step omits `model` | Current Pi session model |
+| Scaffold placeholder (`<your-fast-model>`) | Current Pi session model |
+
+Convention: use a faster model on worker/linear steps and a stronger model on review steps. `/baton:new` inserts placeholders as a reminder — replace them with real model IDs or remove them to inherit the session model.
+
+Step-level overrides apply per subagent invocation; other steps in the same run can use different models.
+
+## Agent discovery order
+
+Each step's `agent` value must match a Pi subagent `name` from frontmatter. Pi Baton merges agents from three locations; when names collide, **project overrides user overrides builtin**:
+
+1. **Project** — nearest `.pi/agents/*.md` walking up from the run's target directory
+2. **User** — `~/.pi/agent/agents/*.md`
+3. **pi-baton builtin** — `agents/` in the package (`worker`, `reviewer`)
+
+If a workflow references an agent name that cannot be resolved, validation fails before the run starts.
+
+To customize behavior, add `.pi/agents/worker.md` or `.pi/agents/reviewer.md` in your project. Use the same `name` as the workflow references so your file overrides the builtin definition.
+
+## End-to-end checklist
+
+1. Run `/baton:new` (or copy a builtin workflow into `.pi/baton/workflows/`).
+2. Set `name`, `iteration_cap`, and define `steps:` with the first step as entry.
+3. Assign `agent` values that exist in your agent discovery path.
+4. Add optional `model` overrides on steps that need a different model.
+5. Write prompts that end with the JSON contract (review steps must include judgment rules).
+6. Wire transitions: linear steps use `next`; review steps use `on_accept` / `on_reject`.
+7. Run `/baton:start` to pick the workflow, then `/baton:run` to execute.
+8. Run `/baton:status` to inspect the active run, or the most recent finished run after `/baton:run` completes.
+9. Run `/baton:history` to list recent completed or failed runs when you need older terminal outcomes or run directories. `/baton:status` stays focused on the active run or the latest finished run only.
+
+## Examples
+
+Study the shipped workflows for complete, working graphs:
+
+- [`workflows/default-review-loop.yaml`](../workflows/default-review-loop.yaml) — classic `implement → review → fix` loop
+- [`workflows/two-stage-review-gauntlet.yaml`](../workflows/two-stage-review-gauntlet.yaml) — chained review gates with a shared fix step

package/extensions/index.ts

@@ -10,8 +10,13 @@ import {
   createIdleRun,
   loadActiveRun,
   loadMostRecentTerminalRun,
+  loadTerminalRunHistory,
 } from "../lib/run-store.ts";
-import { NO_ACTIVE_RUN_MESSAGE, formatStatusSummary } from "../lib/status.ts";
+import {
+  NO_ACTIVE_RUN_MESSAGE,
+  formatHistorySummary,
+  formatStatusSummary,
+} from "../lib/status.ts";
 import { createSubagentRunner } from "../lib/subagent-runner.ts";
 import { WorkflowNameCollisionError, createWorkflowScaffold } from "../lib/workflow-scaffold.ts";
 import { WorkflowValidationError } from "../lib/workflow-schema.ts";
@@ -199,4 +204,12 @@ export default function (pi: ExtensionAPI) {
       ctx.ui.notify(formatStatusSummary(manifest), "info");
     },
   });
+
+  pi.registerCommand("baton:history", {
+    description: "List recent completed or failed Baton runs from persisted history",
+    handler: async (_args, ctx) => {
+      const history = await loadTerminalRunHistory(ctx.cwd);
+      ctx.ui.notify(formatHistorySummary(history), "info");
+    },
+  });
 }

package/lib/run-store.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readdir, readFile, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import {
   ensureBatonScaffolding,
@@ -6,6 +6,7 @@ import {
   getActiveRunPointerPath,
   getRunManifestPath,
   getRunStepsDir,
+  getRunsDir,
 } from "./paths.ts";
 import type { ActiveRunPointer, RunManifest, RunState, StepRecord } from "./types.ts";
 
@@ -60,6 +61,106 @@ export async function loadActiveRun(cwd: string): Promise<RunManifest | null> {
   }
 }
 
+export const TERMINAL_HISTORY_DEFAULT_LIMIT = 10;
+export const TERMINAL_HISTORY_HARD_CAP = 20;
+export const TERMINAL_HISTORY_MAX_SCAN = 200;
+
+export interface TerminalRunHistoryResult {
+  runs: RunManifest[];
+  skippedCount: number;
+}
+
+function isCompleteManifest(value: unknown): value is RunManifest {
+  if (!value || typeof value !== "object") return false;
+
+  const manifest = value as Partial<RunManifest>;
+  return (
+    typeof manifest.id === "string" &&
+    typeof manifest.state === "string" &&
+    typeof manifest.workflowName === "string" &&
+    typeof manifest.updatedAt === "string" &&
+    typeof manifest.createdAt === "string" &&
+    typeof manifest.iteration === "number" &&
+    (manifest.lastStep === null || typeof manifest.lastStep === "string")
+  );
+}
+
+function runIdTimestamp(runId: string): string {
+  const prefix = runId.slice(0, 14);
+  return /^\d{14}$/.test(prefix) ? prefix : "";
+}
+
+function compareRunIdsNewestFirst(a: string, b: string): number {
+  const aTimestamp = runIdTimestamp(a);
+  const bTimestamp = runIdTimestamp(b);
+  if (aTimestamp && bTimestamp && aTimestamp !== bTimestamp) {
+    return bTimestamp.localeCompare(aTimestamp);
+  }
+
+  return b.localeCompare(a);
+}
+
+function compareRunsNewestFirst(a: RunManifest, b: RunManifest): number {
+  const updatedCompare = b.updatedAt.localeCompare(a.updatedAt);
+  if (updatedCompare !== 0) return updatedCompare;
+
+  const createdCompare = b.createdAt.localeCompare(a.createdAt);
+  if (createdCompare !== 0) return createdCompare;
+
+  return compareRunIdsNewestFirst(a.id, b.id);
+}
+
+export async function loadTerminalRunHistory(
+  cwd: string,
+  options: { limit?: number } = {},
+): Promise<TerminalRunHistoryResult> {
+  await ensureBatonScaffolding(cwd);
+
+  const limit = Math.min(
+    Math.max(1, options.limit ?? TERMINAL_HISTORY_DEFAULT_LIMIT),
+    TERMINAL_HISTORY_HARD_CAP,
+  );
+
+  let entries;
+  try {
+    entries = await readdir(getRunsDir(cwd), { withFileTypes: true });
+  } catch {
+    return { runs: [], skippedCount: 0 };
+  }
+
+  const runIds = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort(compareRunIdsNewestFirst)
+    .slice(0, TERMINAL_HISTORY_MAX_SCAN);
+
+  const terminalRuns: RunManifest[] = [];
+  let skippedCount = 0;
+
+  for (const runId of runIds) {
+    try {
+      const manifest = await readJson<unknown>(getRunManifestPath(cwd, runId));
+      if (!isCompleteManifest(manifest)) {
+        skippedCount++;
+        continue;
+      }
+      if (!isTerminalRunState(manifest.state)) {
+        continue;
+      }
+      terminalRuns.push(manifest);
+    } catch {
+      skippedCount++;
+    }
+  }
+
+  terminalRuns.sort(compareRunsNewestFirst);
+
+  return {
+    runs: terminalRuns.slice(0, limit),
+    skippedCount,
+  };
+}
+
 export async function loadMostRecentTerminalRun(cwd: string): Promise<RunManifest | null> {
   const pointer = await readActiveRunPointer(cwd);
   if (!pointer?.runId) return null;

package/lib/status.ts

@@ -1,3 +1,4 @@
+import type { TerminalRunHistoryResult } from "./run-store.ts";
 import type { RunManifest } from "./types.ts";
 
 function isTerminalRunState(state: RunManifest["state"]): boolean {
@@ -21,8 +22,50 @@ export function formatStatusSummary(manifest: RunManifest): string {
     `run directory: .pi/baton/runs/${manifest.id}`,
   );
 
+  if (manifest.failureReason) {
+    lines.push(`failure: ${manifest.failureReason}`);
+  }
+
   return lines.join("\n");
 }
 
 export const NO_ACTIVE_RUN_MESSAGE =
   "No active Baton run. Start one with /baton:start after choosing a workflow and task brief.";
+
+export const NO_TERMINAL_HISTORY_MESSAGE =
+  "No completed or failed Baton runs yet. Start one with /baton:start, then /baton:run.";
+
+function formatRelativeRunDirectory(runId: string): string {
+  return `.pi/baton/runs/${runId}`.replace(/\\/g, "/");
+}
+
+function formatHistoryRow(manifest: RunManifest): string {
+  const lastStep = manifest.lastStep ?? "(none)";
+  return [
+    manifest.state,
+    manifest.id,
+    manifest.workflowName,
+    `last: ${lastStep}`,
+    `iter: ${manifest.iteration}`,
+    `updated: ${manifest.updatedAt}`,
+    formatRelativeRunDirectory(manifest.id),
+  ].join(" | ");
+}
+
+export function formatHistorySummary(result: TerminalRunHistoryResult): string {
+  const lines: string[] = [];
+
+  if (result.runs.length === 0) {
+    lines.push(NO_TERMINAL_HISTORY_MESSAGE);
+  } else {
+    for (const manifest of result.runs) {
+      lines.push(formatHistoryRow(manifest));
+    }
+  }
+
+  if (result.skippedCount > 0) {
+    lines.push(`(${result.skippedCount} run(s) skipped: unreadable or incomplete manifest)`);
+  }
+
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-baton",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "Pi-native workflow baton runner with per-step model switching and isolated step context.",
   "type": "module",
   "engines": {