pi-gauntlet 4.9.0 → 4.11.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v4.11.0 - 2026-08-18
+
+- New skill: `gatekeep-pr` - consent-gated pre-merge PR verification: read-only three-role brief, `REVIEW.md` rubric convention with a shipped baseline, deterministic authorship-aware consent menu, thin-wrapper contract.
+- `plan_tracker`: additive `failed` task status (terminal-negative `✗`), excluded from the complete count.
+
+## v4.10.0 - 2026-08-18
+
+New skill: `shape-ticket` - the tracker-facing entry stage ahead of brainstorming.
+
+- `shape-ticket` (user-invoked only, `disable-model-invocation: true`): creates or repairs exactly one tracker issue per run - Context/Problem/Idea/AC template, AC integrity gate (wishful/tautological hard stops, unspecified/external-input parking, deploy-window relocation, discovery-ticket conversion), vertical-only split rule, metadata audit, evidence gate, cheap council roast (`:low` model-suffix over the xhigh pin; worker fallback; failure never blocks), and a single human-gated batched write with post-approval re-fetch. Zero-config on `gh`/`linearis`; other trackers via the overrides `## Issue tracker` section.
+- Overrides discovery ladder: the gauntlet overrides file is now found at `.pi/gauntlet-overrides.md` -> `<repo root>/gauntlet-overrides.md` -> `<repo root>/doc/gauntlet-overrides.md` (first found wins) - migrated across all skills' "Project overrides" blocks and inline references (Claude Code prep for #11).
+- Shared AGENTS core v2: the "Ticket convention" section now points at `/skill:shape-ticket` (roast applied to the ticket body pre-write; no roast comments); propagated to pi-quiver, pi-cohort, pi-condense.
+- `spec-council-member`/`spec-council-synthesizer` gain shape-ticket as a second sanctioned dispatcher (docs).
+
 ## v4.9.0 - 2026-08-14
 
 Review fix rounds parallelize when the reviewer certifies disjoint findings.

package/README.md

@@ -35,17 +35,20 @@ pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a r
 
 Concretely, one change through the gauntlet:
 
+0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create or repair a single tracker issue - shaping a raw ask into a Context/Problem/Idea/Acceptance Criteria ticket, gated by an AC integrity check, a cheap council roast, and one human-confirmed write. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. It never activates on its own (`disable-model-invocation: true`) - invoke it explicitly.
 1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; event-driven only — gauntlet never sweeps historical specs). **You read and approve the spec - human gate 1.** No implementation code exists yet.
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor.
 4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
-5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. **Human gate 2** - the only other decision you make.
+5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it against its issue before merging. **Human gate 2** - the only other decision you make.
 
 Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive a branch-local one-shot nudge after an unexpected settled stop; it is fire-and-forget, does not bypass either human gate, and older Pi hosts without `agent_settled` retain existing behavior.
 
 ```mermaid
 flowchart LR
+    T["shape-ticket<br/>(optional, explicit)"]
     R([request]) --> B[brainstorm<br/>+ spec]
+    T -.-> R
     B --> G1{{human gate 1:<br/>approve spec}}
     G1 --> P[plan]
     P --> I[implement<br/>waves + reviews]
@@ -64,7 +67,7 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **13 skills** - the workflow logic. They activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`.
+- **15 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`. The fourteenth, `shape-ticket`, is explicit-invocation-only (`disable-model-invocation: true`): create or repair one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write. Run it with `/skill:shape-ticket`. The fifteenth, `gatekeep-pr`, is also explicit-invocation-only: consent-gated pre-merge verification of a PR against its issue - read-only gathering, running the project's verification command, a rubric-based review, then a deterministic authorship-aware menu; nothing mutates (fixes, pushes, reviews, merges) until you pick a row. Run it with `/skill:gatekeep-pr <pr>`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
@@ -89,7 +92,7 @@ pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) ≥ 0.1.0
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 - required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `writing-skills`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 - required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `writing-skills`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both.
 
@@ -137,6 +140,85 @@ database and copies `.env.local`. Never call `git worktree add` directly.
 
 Section headers should match skill names (`## verification-before-completion`) or skill topics (`## worktrees`, `## routing`). The override file is read by the skill instructions at runtime, not by the pi runtime itself, so adding a section only matters once the matching skill is active.
 
+**Discovery ladder:** skills check three locations, in order, and use the first one found - never merged: `.pi/gauntlet-overrides.md`, then `<repo root>/gauntlet-overrides.md`, then `<repo root>/doc/gauntlet-overrides.md` (`<repo root>` = `git rev-parse --show-toplevel`, or the current directory outside a repo). Pick one location per repo.
+
+**`## Issue tracker` section:** `shape-ticket` resolves tracker access through a capability ladder, and this is its first rung - it overrides the zero-config `gh` (GitHub) / `linearis` (Linear) defaults for any other tracker. Name the CLI's read, search, create, and update commands explicitly. For a Jira CLI, for example:
+
+```markdown
+## Issue tracker
+
+Use the `jira` CLI (authenticated via `jira login`), not `gh` or `linearis`.
+
+- read (full, incl. comments): `jira issue view ABC-123 --comments`
+- search (dup/reversal check): `jira issue search --jql "project = ABC AND text ~ '<query>'"`
+- create: `jira issue create --project ABC --type Task --summary "<title>" --description "<body>"`
+- update: `jira issue edit ABC-123 --summary "<title>" --description "<body>"`
+```
+
+## REVIEW.md convention
+
+`/skill:gatekeep-pr` (the pre-merge gate) reads an optional root-level `REVIEW.md` -
+discovered at the repo root only, read from the PR's base (never the PR's own head,
+so a PR can't weaken the rubric that gates it). It's a plain data file, not agent
+instructions: a rubric other tooling can read too. The skill is fully functional with
+no `REVIEW.md` present - it falls back to the shipped baseline rubric
+(`skills/gatekeep-pr/review-baseline.md`).
+
+**Overlay precedence**, first match wins on any conflict:
+
+1. Repo root `REVIEW.md` - always wins over everything below it.
+2. Shipped `skills/gatekeep-pr/review-baseline.md` - the generic default rubric.
+3. Reviewer-persona defaults.
+
+A `REVIEW.md` entry that names a baseline concern (e.g. a severity mapping) replaces
+it; everything it doesn't name stays baseline. Severities it introduces but doesn't
+map to blocking/non-blocking are treated as **blocking** (fail-safe), noted in the
+gate's output.
+
+`REVIEW.md` is a diff over the baseline, not a full rewrite. Starter template:
+
+```markdown
+# REVIEW.md
+
+Severity mapping: Critical and Moderate findings block merge; Minor is a
+non-blocking follow-up. Migration-safety findings also block merge.
+
+Project checks (in addition to the baseline):
+- Schema migrations are additive and reversible - no destructive column drops
+  without a documented backfill/rollback plan.
+- New background jobs declare an explicit retry/backoff policy - unbounded
+  retries block merge.
+
+Everything else follows the shipped baseline rubric.
+```
+
+## Thin-wrapper contract
+
+A consumer repo that wants its own trigger phrases for the pre-merge gate (e.g. "gate
+ this PR", "ready to merge?") adds a wrapper skill that carries **zero data** - only a
+name, its trigger phrases, and an instruction to follow `/skill:gatekeep-pr`. All
+customization lives in two places, never in the wrapper itself:
+
+- **`REVIEW.md`** - the review rubric (see above).
+- **The gauntlet overrides file, `## PR gate` section** - everything operational:
+
+```markdown
+## PR gate
+- verification command: <command>            # required unless documented elsewhere
+- timeout minutes: 15                        # optional; default 15
+- requires credentials: false                # optional; true => skill reports "not run" as missing evidence
+- worktree wrapper: <command>                # optional
+- issue fetch: <command with <ref> placeholder>   # optional, replaces gh issue view
+- merge policy: squash | merge-commit        # optional
+```
+
+An existing `## verification-before-completion` overrides section is an accepted
+equivalent source for the verification command only; all other PR-gate keys
+still live under `## PR gate`.
+
+Anything a wrapper skill contains beyond trigger phrases is misplaced - move it to
+`REVIEW.md` or the overrides file instead.
+
 ## Configuring the gates
 
 The conformance gate's model, the spec council's roster, and the phase-tracker's flow guards are all configured per pi preset (or per repo, via `.pi/settings.json`). See [doc/configuration.md](./doc/configuration.md) for every setting, its default, and how repo-local config overrides a preset.

package/agents/conformance-reviewer.md

@@ -26,7 +26,7 @@ Work flows `origin (prompt + spec) → plan → code/doc`. Every hop is lossy: a
 |---|---|---|
 | 1 | The written spec (`doc/specs/…`) | Canonical. Brainstorm already fetched the ticket, reconciled its ACs, and recorded deviations here. |
 | 2 | Original prompt (verbatim) | Catches inline requirements never folded into the spec. |
-| 3 | Re-fetch the ticket | **Fallback only**, when no spec exists. Skip when a spec exists — the live ticket may have drifted. The project's issue-tracker skill (for this fallback) is named in `.pi/gauntlet-overrides.md`. |
+| 3 | Re-fetch the ticket | **Fallback only**, when no spec exists. Skip when a spec exists — the live ticket may have drifted. The project's issue-tracker skill (for this fallback) is named in the gauntlet overrides file (see Project overrides in the dispatching skill). |
 
 ## Process
 

package/agents/spec-council-member.md

@@ -1,6 +1,6 @@
 ---
 name: spec-council-member
-description: Adversarial single-model spec critic dispatched by the roasting-the-spec skill; assesses whether a spec is sound, complete, and actionable. Not for direct dispatch.
+description: Adversarial single-model spec critic dispatched by the roasting-the-spec or shape-ticket skills; assesses whether a spec is sound, complete, and actionable. Not for direct dispatch.
 tools: read, grep, find, ls, bash
 thinking: xhigh
 defaultContext: fresh

package/agents/spec-council-synthesizer.md

@@ -1,6 +1,6 @@
 ---
 name: spec-council-synthesizer
-description: Neutral chair that consolidates and adjudicates spec-council member critiques into a single ranked, conflict-resolved report. Dispatched by the roasting-the-spec skill; not for direct dispatch.
+description: Neutral chair that consolidates and adjudicates spec-council member critiques into a single ranked, conflict-resolved report. Dispatched by the roasting-the-spec or shape-ticket skills; not for direct dispatch.
 tools: read, grep, find, ls, bash
 thinking: xhigh
 defaultContext: fresh

package/extensions/plan-tracker.test.ts

@@ -8,18 +8,38 @@ type ToolResult = {
 };
 
 function harness(branch: unknown[] = []) {
-  const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
+  const tools: {
+    name: string;
+    execute: (...args: any[]) => unknown;
+    renderResult: (result: unknown, options: unknown, theme: unknown) => { text?: string };
+  }[] = [];
+  const handlers: { event: string; handler: (event: unknown, ctx: unknown) => Promise<void> }[] = [];
   const pi = {
-    on(_event: string, _handler: unknown) {},
-    registerTool(tool: { name: string; execute: (...args: any[]) => unknown }) {
+    on(event: string, handler: (event: unknown, ctx: unknown) => Promise<void>) {
+      handlers.push({ event, handler });
+    },
+    registerTool(tool: any) {
       tools.push(tool);
     },
   };
   registerPlanTracker(pi as any);
-  const ctx = { hasUI: false, sessionManager: { getBranch: () => branch } };
+  let widgetText: string | undefined;
+  const theme = { fg: (_c: string, s: string) => s, bold: (s: string) => s };
+  const ctx = {
+    hasUI: true,
+    ui: {
+      setWidget(_id: string, cb?: (tui: unknown, theme: unknown) => { text: string }) {
+        widgetText = cb ? cb(undefined, theme).text : undefined;
+      },
+    },
+    sessionManager: { getBranch: () => branch },
+  };
   const call = async (params: Record<string, unknown>): Promise<ToolResult> =>
     (await tools[0].execute("id", params, undefined, undefined, ctx)) as ToolResult;
-  return { call };
+  const fire = async (event: string) => {
+    for (const h of handlers) if (h.event === event) await h.handler({}, ctx);
+  };
+  return { call, fire, tool: () => tools[0], theme, widget: () => widgetText };
 }
 
 test("add appends pending tasks and preserves existing statuses", async () => {
@@ -64,3 +84,108 @@ test("add with empty/missing tasks errors and preserves state", async () => {
   const res2 = await call({ action: "add" });
   assert.equal(res2.details.error, "tasks required");
 });
+
+test("update to failed round-trips and is excluded from complete count", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["a", "b", "c"] });
+  await call({ action: "update", index: 0, status: "complete" });
+  const res = await call({ action: "update", index: 1, status: "failed" });
+  assert.equal(res.details.error, undefined);
+  assert.deepEqual(
+    res.details.tasks.map((t) => [t.name, t.status]),
+    [["a", "complete"], ["b", "failed"], ["c", "pending"]],
+  );
+  assert.match(res.content[0].text, /1\/3 complete/);
+  assert.match(res.content[0].text, /1 failed/);
+});
+
+test("reconstruction preserves failed status from serialized details", async () => {
+  const branch = [
+    {
+      type: "message",
+      message: {
+        role: "toolResult",
+        toolName: "plan_tracker",
+        details: {
+          action: "update",
+          tasks: [
+            { name: "a", status: "complete" },
+            { name: "b", status: "failed" },
+          ],
+        },
+      },
+    },
+  ];
+  const { call, fire } = harness(branch);
+  await fire("session_start");
+  const res = await call({ action: "status" });
+  assert.deepEqual(
+    res.details.tasks.map((t) => [t.name, t.status]),
+    [["a", "complete"], ["b", "failed"]],
+  );
+  assert.match(res.content[0].text, /\u2717 \[1\] b/);
+});
+
+test("widget renders failed as \u2717, keeps failed out of complete count and current", async () => {
+  const { call, widget } = harness();
+  await call({ action: "init", tasks: ["a", "b"] });
+  await call({ action: "update", index: 0, status: "failed" });
+  const w = widget();
+  assert.ok(w);
+  assert.match(w!, /\u2717/);
+  assert.match(w!, /\(0\/2\)/);
+  assert.match(w!, /b$/); // current = first pending, never the failed task
+});
+
+test("renderResult status path shows \u2717 for failed and excludes it from complete", async () => {
+  const { call, tool, theme } = harness();
+  await call({ action: "init", tasks: ["a", "b"] });
+  await call({ action: "update", index: 1, status: "failed" });
+  const res = await call({ action: "status" });
+  const rendered = tool().renderResult(res as any, {}, theme as any);
+  const text = (rendered as any).text as string;
+  assert.match(text, /0\/2 complete/);
+  assert.match(text, /\u2717/);
+});
+
+test("renderResult status header appends failed count when a task has failed", async () => {
+  const { call, tool, theme } = harness();
+  await call({ action: "init", tasks: ["a", "b", "c"] });
+  await call({ action: "update", index: 0, status: "complete" });
+  await call({ action: "update", index: 1, status: "failed" });
+  const res = await call({ action: "status" });
+  const rendered = tool().renderResult(res as any, {}, theme as any);
+  const text = (rendered as any).text as string;
+  assert.match(text, /1\/3 complete, 1 failed/);
+});
+
+test("renderResult status header omits failed count when no task has failed", async () => {
+  const { call, tool, theme } = harness();
+  await call({ action: "init", tasks: ["a", "b"] });
+  await call({ action: "update", index: 0, status: "complete" });
+  const res = await call({ action: "status" });
+  const rendered = tool().renderResult(res as any, {}, theme as any);
+  const text = (rendered as any).text as string;
+  assert.match(text, /^1\/2 complete\n/);
+  assert.doesNotMatch(text, /failed/);
+});
+
+test("renderResult update case appends failed count when a task has failed", async () => {
+  const { call, tool, theme } = harness();
+  await call({ action: "init", tasks: ["a", "b", "c"] });
+  await call({ action: "update", index: 0, status: "complete" });
+  const res = await call({ action: "update", index: 1, status: "failed" });
+  const rendered = tool().renderResult(res as any, {}, theme as any);
+  const text = (rendered as any).text as string;
+  assert.match(text, /^\u2713 Updated \(1\/3 complete, 1 failed\)$/);
+});
+
+test("renderResult update case omits failed count when no task has failed", async () => {
+  const { call, tool, theme } = harness();
+  await call({ action: "init", tasks: ["a", "b"] });
+  const res = await call({ action: "update", index: 0, status: "complete" });
+  const rendered = tool().renderResult(res as any, {}, theme as any);
+  const text = (rendered as any).text as string;
+  assert.match(text, /^\u2713 Updated \(1\/2 complete\)$/);
+  assert.doesNotMatch(text, /failed/);
+});

package/extensions/plan-tracker.ts

@@ -11,7 +11,7 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-c
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
 
-type TaskStatus = "pending" | "in_progress" | "complete";
+type TaskStatus = "pending" | "in_progress" | "complete" | "failed";
 
 interface Task {
   name: string;
@@ -40,8 +40,8 @@ const PlanTrackerParams = Type.Object({
     }),
   ),
   status: Type.Optional(
-    StringEnum(["pending", "in_progress", "complete"] as const, {
-      description: "New status (for update)",
+    StringEnum(["pending", "in_progress", "complete", "failed"] as const, {
+      description: "New status (for update); failed is terminal-negative (ran and did not pass)",
     }),
   ),
 });
@@ -59,6 +59,8 @@ function formatWidget(tasks: Task[], theme: Theme): string {
           return theme.fg("success", "✓");
         case "in_progress":
           return theme.fg("warning", "→");
+        case "failed":
+          return theme.fg("error", "✗");
         default:
           return theme.fg("dim", "○");
       }
@@ -78,13 +80,16 @@ function formatStatus(tasks: Task[]): string {
   const complete = tasks.filter((t) => t.status === "complete").length;
   const inProgress = tasks.filter((t) => t.status === "in_progress").length;
   const pending = tasks.filter((t) => t.status === "pending").length;
+  const failed = tasks.filter((t) => t.status === "failed").length;
 
   const lines: string[] = [];
-  lines.push(`Plan: ${complete}/${tasks.length} complete (${inProgress} in progress, ${pending} pending)`);
+  lines.push(
+    `Plan: ${complete}/${tasks.length} complete (${inProgress} in progress, ${pending} pending, ${failed} failed)`,
+  );
   lines.push("");
   for (let i = 0; i < tasks.length; i++) {
     const t = tasks[i];
-    const icon = t.status === "complete" ? "✓" : t.status === "in_progress" ? "→" : "○";
+    const icon = t.status === "complete" ? "✓" : t.status === "in_progress" ? "→" : t.status === "failed" ? "✗" : "○";
     lines.push(`  ${icon} [${i}] ${t.name}`);
   }
   return lines.join("\n");
@@ -129,7 +134,7 @@ export default function (pi: ExtensionAPI) {
     name: "plan_tracker",
     label: "Plan Tracker",
     description:
-      "Track progress while EXECUTING an implementation plan (the implement phase) or a verify-phase conformance fix wave. Actions: init (set task list), add (append tasks as pending; existing statuses preserved), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
+      "Track progress while EXECUTING an implementation plan (the implement phase), a verify-phase conformance fix wave, or another bounded gate checklist (e.g. pre-merge PR verification). Statuses: pending, in_progress, complete, failed (terminal-negative: the task ran and did not pass; never counted complete). Actions: init (set task list), add (append tasks as pending; existing statuses preserved), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
     parameters: PlanTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -305,8 +310,11 @@ export default function (pi: ExtensionAPI) {
           );
         case "update": {
           const complete = taskList.filter((t) => t.status === "complete").length;
+          const failed = taskList.filter((t) => t.status === "failed").length;
+          const suffix = failed > 0 ? `, ${failed} failed` : "";
           return new Text(
-            theme.fg("success", "✓ ") + theme.fg("muted", `Updated (${complete}/${taskList.length} complete)`),
+            theme.fg("success", "✓ ") +
+              theme.fg("muted", `Updated (${complete}/${taskList.length} complete${suffix})`),
             0,
             0,
           );
@@ -316,14 +324,18 @@ export default function (pi: ExtensionAPI) {
             return new Text(theme.fg("dim", "No plan active"), 0, 0);
           }
           const complete = taskList.filter((t) => t.status === "complete").length;
-          let text = theme.fg("muted", `${complete}/${taskList.length} complete`);
+          const failed = taskList.filter((t) => t.status === "failed").length;
+          const suffix = failed > 0 ? `, ${failed} failed` : "";
+          let text = theme.fg("muted", `${complete}/${taskList.length} complete${suffix}`);
           for (const t of taskList) {
             const icon =
               t.status === "complete"
                 ? theme.fg("success", "✓")
                 : t.status === "in_progress"
                   ? theme.fg("warning", "→")
-                  : theme.fg("dim", "○");
+                  : t.status === "failed"
+                    ? theme.fg("error", "✗")
+                    : theme.fg("dim", "○");
             text += `\n${icon} ${theme.fg("muted", t.name)}`;
           }
           return new Text(text, 0, 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -176,7 +176,7 @@ Cover at minimum:
   - Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
   ```
 
-  Each entry answers with a doc name, "none", or "deferred: <trigger>". A new standalone `.md` appears only where no existing doc already owns the topic. Project-specific doc taxonomy goes in a `## documentation` block in `.pi/gauntlet-overrides.md` (no new settings key; guidance only). Doc updates ship in the same commit and are verified against the spec by the conformance gate.
+  Each entry answers with a doc name, "none", or "deferred: <trigger>". A new standalone `.md` appears only where no existing doc already owns the topic. Project-specific doc taxonomy goes in a `## documentation` block in the gauntlet overrides file (see Project overrides) (no new settings key; guidance only). Doc updates ship in the same commit and are verified against the spec by the conformance gate.
 
 Be ready to go back and clarify when something doesn't make sense.
 
@@ -240,7 +240,7 @@ When the new spec replaces a prior spec — fully or in part — and you **alrea
 - **Mark, never delete.** Delete/archive policy is consumer territory via overrides.
 - **Coverage limits**: unmarked does NOT mean current (code drift, abandoned designs, and partial ships produce no successor spec); marked does NOT mean dead (partial supersession leaves live sections).
 - Predecessor in a **different service's spec directory**: out of scope — record it in the new spec's Open Questions instead of editing outside the write grant.
-- **Override contract**: `.pi/gauntlet-overrides.md` may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).
+- **Override contract**: the gauntlet overrides file (see Project overrides) may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).
 
 ## Spec Self-Review (Before User Review Gate)
 
@@ -384,4 +384,4 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 
 ## Project overrides
 
-If `.pi/gauntlet-overrides.md` exists, read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
+If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.

package/skills/brainstorming/gatherer.md

@@ -68,7 +68,7 @@ contains any of:
 
 - an `http(s)://` URL;
 - a tracker-style ID matching `[A-Z][A-Z0-9]+-\d+` (Linear/Jira form) **when a fetch
-  path exists** (a tracker tool/MCP, or a URL pattern in `.pi/gauntlet-overrides.md`);
+  path exists** (a tracker tool/MCP, or a URL pattern in the gauntlet overrides file, see Project overrides);
 - a GitHub-style ref `owner/repo#N`, or a bare `#N` when the repo's tracker is
   GitHub Issues.
 

package/skills/brainstorming/reference/documentation-impact.md

@@ -130,5 +130,6 @@ Keep this list in sync with the skills that cite this doc:
 ## Project-specific taxonomy
 
 This doc is generic. Project-specific doc taxonomy (which docs a given
-project treats as canonical for which topic) lives in a project's
-`.pi/gauntlet-overrides.md`, in a `## documentation` section - not here.
+project treats as canonical for which topic) lives in the gauntlet
+overrides file (see Project overrides in `brainstorming/SKILL.md`), in a
+`## documentation` section - not here.

package/skills/dispatching-parallel-agents/SKILL.md

@@ -203,4 +203,4 @@ After agents return:
 
 ## Project overrides
 
-If `.pi/gauntlet-overrides.md` exists, read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
+If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.

package/skills/finishing-a-development-branch/SKILL.md

@@ -358,4 +358,4 @@ phase_tracker({ action: "complete", phase: "ship" })
 
 ## Project overrides
 
-If `.pi/gauntlet-overrides.md` exists, read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.
+If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.

package/skills/finishing-a-development-branch/reference/disposition-protocol.md

@@ -38,7 +38,7 @@ Take **no** disposition action before the reply. Then, once, in order:
 3. **Re-audit if step 2 changed the spec**; regenerate the inventory and re-render if it changed. Project `fix-now` only from the refreshed inventory.
 4. **fix-now + code-changing custom:** project the selected concerns per gap into the reference's concern-scoped fix contract (excluding accepted/rescoped/followed-up siblings); run the reference "Fix loop" (unchanged - do not re-describe it). A code-changing `custom` runs the project's tests + `code-reviewer` on its delta before proceeding. Re-run Step 1's canonical tests.
 5. **Re-audit after all state-changing work;** obtain fresh decisions **only if** the refreshed inventory differs from the approved one, else proceed.
-6. **follow-up** from the current inventory: create the item via the project's issue-tracker convention (`.pi/gauntlet-overrides.md`), record the ticket ID/URL; on failure keep the concern open.
+6. **follow-up** from the current inventory: create the item via the project's issue-tracker convention (the gauntlet overrides file, see Project overrides in `finishing-a-development-branch/SKILL.md`), record the ticket ID/URL; on failure keep the concern open.
 7. **Non-state-changing custom:** execute and record the result.
 8. **revert** (`revert conformance fix Gn`): light-revert the indexed commit, re-run Step 1's canonical tests; on failure stop; on pass re-audit and regenerate.
 9. Re-enter Step 3.5 with the re-audited block if any concern remains open.