pi-gauntlet 5.5.4 → 5.6.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v5.6.1 - 2026-09-17
+
+- `brainstorming`: the questionary looks up questions the code, docs, or issue tracker already answer instead of asking; every question it does ask ends with `Recommendation: <answer> - <why>` (including the ask to accept a corrected fact); before approaches, a plain-prose premise note in chat names which design-dependent claims the sources support, disprove (with the corrected fact and where), or leave unverified - a contradicted claim stops the flow until the user accepts the correction or explicitly overrides, with the outcome recorded in the draft. One checklist pointer, one Red Flags entry. (#32)
+- AGENTS core v4: exactness via the example, no inline SHAs, no spiderweb replies.
+
+## v5.6.0 - 2026-09-16
+
+- `plan-tracker`: pending-suffix rule enforced at runtime - an `update` that would leave a `pending` task ahead of a started or finished one is rejected with a message naming every offending task, the legal fixes, and the current snapshot; state is unchanged and widget replay / `phase_tracker` ignore the rejection. `update` never sets `pending`. New terminal status `skipped` (`⊘`, not applicable in this run, counted done). `init` accepts `{ name, status }` elements (mixable with strings) to recreate a list with known statuses. Registered with sequential execution. Counts are labelled `done` (`complete + skipped`).
+- `phase-tracker`: `implement` auto-completes when every task is `complete` or `skipped`.
+- `check-delivery`, `gatekeep-pr`, `subagent-driven-development`, `brainstorming`: tracker usage aligned with the rule - a skipped stage is `skipped`, gatekeep-pr inits four stages and adds claims/review/consent progressively, wave fan-out marks `in_progress` in increasing index order, the amendment path re-inits with statuses instead of setting tasks back to `pending`.
+
 ## v5.5.4 - 2026-09-14
 
 - `phase-tracker`: new `phase_tracker` action `grant_fix_rounds` records an explicit human approval of N more conformance fix rounds (reason quotes the human), accepted only while the cap block is live; each qualifying implementer wave spends one granted round, credits replay with the session and reset with the audit latch. The cap-block message now leads with that action and names the exact `.pi/settings.json` for the `enforce: false` last resort (applies without restart, whole-block precedence).

package/extensions/phase-tracker.test.ts

@@ -370,6 +370,27 @@ test("all-complete plan activity auto-completes an active implement phase", asyn
   assert.equal(status.details.phases.implement.status, "complete");
 });
 
+test("plan activity auto-completes implement with complete+skipped, not with failed, not from an errored result", async () => {
+  const implementStatus = async (tasks: { status: string }[], isError = false) => {
+    const h = harness({ branch: implementBranch() });
+    await h.emit("session_start");
+    await h.emitEvent("tool_execution_end", {
+      toolName: "plan_tracker",
+      isError,
+      result: { details: { tasks } },
+    });
+    const tool = h.tools.find((t) => t.name === "phase_tracker")!;
+    const status = (await tool.execute("t1", { action: "status" }, undefined, undefined, h.ctx)) as {
+      details: { phases: { implement: { status: string } } };
+    };
+    return status.details.phases.implement.status;
+  };
+  assert.equal(await implementStatus([{ status: "complete" }, { status: "skipped" }]), "complete");
+  assert.equal(await implementStatus([{ status: "skipped" }, { status: "skipped" }]), "complete");
+  assert.equal(await implementStatus([{ status: "complete" }, { status: "failed" }]), "in_progress");
+  assert.equal(await implementStatus([{ status: "complete" }, { status: "skipped" }], true), "in_progress");
+});
+
 test("cold implement and verify completions ignore unfinished snapshots", async () => {
   for (const phase of ["implement", "verify"] as const) {
     const h = harness({

package/extensions/phase-tracker.ts

@@ -417,7 +417,10 @@ export default function (pi: ExtensionAPI) {
   // skills; plan-tracker tracks tasks independently.
   const applyPlanActivity = (tasks?: { status: string }[]) => {
     if (!tasks || tasks.length === 0) return;
-    if (phases.implement.status === "in_progress" && tasks.every((t) => t.status === "complete")) {
+    if (
+      phases.implement.status === "in_progress" &&
+      tasks.every((t) => t.status === "complete" || t.status === "skipped")
+    ) {
       phases = { ...phases, implement: { status: "complete" } };
       firedGuards.clear();
     }

package/extensions/plan-tracker.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import registerPlanTracker from "./plan-tracker.ts";
+import registerPlanTracker, { validateSnapshot } from "./plan-tracker.ts";
 
 type ToolResult = {
   content: { type: string; text: string }[];
@@ -10,6 +10,9 @@ type ToolResult = {
 function harness(branch: unknown[] = []) {
   const tools: {
     name: string;
+    description: string;
+    executionMode?: string;
+    parameters: any;
     execute: (...args: any[]) => unknown;
     renderResult: (result: unknown, options: unknown, theme: unknown) => { text?: string };
   }[] = [];
@@ -39,7 +42,16 @@ function harness(branch: unknown[] = []) {
   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 };
+  return {
+    call,
+    fire,
+    tool: () => tools[0],
+    theme,
+    widget: () => widgetText,
+    parameters: () => tools[0].parameters,
+    description: () => tools[0].description,
+    executionMode: () => tools[0].executionMode,
+  };
 }
 
 test("add appends pending tasks and preserves existing statuses", async () => {
@@ -95,7 +107,7 @@ test("update to failed round-trips and is excluded from complete count", async (
     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\/3 done/);
   assert.match(res.content[0].text, /1 failed/);
 });
 
@@ -140,11 +152,11 @@ test("widget renders failed as \u2717, keeps failed out of complete count and cu
 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" });
+  await call({ action: "update", index: 0, 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, /0\/2 done/);
   assert.match(text, /\u2717/);
 });
 
@@ -156,7 +168,7 @@ test("renderResult status header appends failed count when a task has failed", a
   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/);
+  assert.match(text, /1\/3 done, 1 failed/);
 });
 
 test("renderResult status header omits failed count when no task has failed", async () => {
@@ -166,7 +178,7 @@ test("renderResult status header omits failed count when no task has failed", as
   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.match(text, /^1\/2 done\n/);
   assert.doesNotMatch(text, /failed/);
 });
 
@@ -177,7 +189,7 @@ test("renderResult update case appends failed count when a task has failed", asy
   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\)$/);
+  assert.match(text, /^\u2713 Updated \(1\/3 done, 1 failed\)$/);
 });
 
 test("renderResult update case omits failed count when no task has failed", async () => {
@@ -186,6 +198,196 @@ test("renderResult update case omits failed count when no task has failed", asyn
   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.match(text, /^\u2713 Updated \(1\/2 done\)$/);
   assert.doesNotMatch(text, /failed/);
 });
+
+const S = (code: string) =>
+  [...code].map((c, i) => ({
+    name: `t${i}`,
+    status: ({ o: "pending", ">": "in_progress", k: "complete", x: "failed", "/": "skipped" } as const)[c as "o" | ">" | "k" | "x" | "/"],
+  }));
+
+test("validateSnapshot: pending must trail every non-pending task", () => {
+  for (const code of ["kkkoo", "kk>>oo", "kk>kk", "x>o", "ooo", "///", "", "k"]) {
+    assert.deepEqual(validateSnapshot(S(code)), [], code);
+  }
+  assert.deepEqual(validateSnapshot(S("okoo")), [0]);
+  assert.deepEqual(validateSnapshot(S("kkk>ookkkk")), [4, 5]);
+  assert.deepEqual(validateSnapshot(S("o>")), [0]);
+  assert.deepEqual(validateSnapshot(S("ook")), [0, 1]);
+});
+
+test("update past a pending index is rejected with every offender, fixes, and the current snapshot", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["gather", "resolve evidence", "claim-check", "provision worktree", "review", "verify claims"] });
+  for (const i of [0, 1, 2]) await call({ action: "update", index: i, status: "complete" });
+  const res = await call({ action: "update", index: 5, status: "complete" });
+  assert.equal(res.details.error, "pending-suffix violation: 3,4");
+  assert.deepEqual(
+    res.details.tasks.map((t) => t.status),
+    ["complete", "complete", "complete", "pending", "pending", "pending"],
+  );
+  const text = res.content[0].text;
+  assert.equal(
+    text,
+    [
+      'Error: cannot set task 5 "verify claims" to complete: pending tasks precede it: 3 "provision worktree", 4 "review".',
+      "Rule: pending tasks must trail every started or finished task.",
+      "Fix first, then retry: update each listed task to in_progress (working on it now), complete, failed, or skipped (not applicable in this run); or, if the list order itself is wrong, re-init with {name, status}[] keeping every task and its true status so the untouched ones trail.",
+      "Never clear, drop tasks, or record a status the work has not actually reached.",
+      "Current: 0 gather=complete, 1 resolve evidence=complete, 2 claim-check=complete, 3 provision worktree=pending, 4 review=pending, 5 verify claims=pending",
+    ].join("\n"),
+  );
+  const after = await call({ action: "status" });
+  assert.deepEqual(after.details.tasks.map((t) => t.status), ["complete", "complete", "complete", "pending", "pending", "pending"]);
+});
+
+test("update -> pending is rejected in execute and names reopen and re-init", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["a", "b", "claim-check"] });
+  for (const i of [0, 1, 2]) await call({ action: "update", index: i, status: "complete" });
+  const res = await call({ action: "update", index: 2, status: "pending" });
+  assert.equal(res.details.error, "update cannot set pending");
+  assert.deepEqual(res.details.tasks.map((t) => t.status), ["complete", "complete", "complete"]);
+  assert.equal(
+    res.content[0].text,
+    [
+      'Error: cannot set task 2 "claim-check" to pending: update never sets pending; a task is pending only from init/add.',
+      "To redo it, update it to in_progress. To recreate the whole list, re-init with {name, status}[].",
+      "Current: 0 a=complete, 1 b=complete, 2 claim-check=complete",
+    ].join("\n"),
+  );
+});
+
+test("update at index 0 / first pending index, direct jumps, and reopens are accepted", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["a", "b", "c", "d"] });
+  assert.equal((await call({ action: "update", index: 0, status: "complete" })).details.error, undefined);
+  assert.equal((await call({ action: "update", index: 1, status: "failed" })).details.error, undefined);
+  assert.equal((await call({ action: "update", index: 2, status: "skipped" })).details.error, undefined);
+  assert.equal((await call({ action: "update", index: 0, status: "in_progress" })).details.error, undefined);
+  assert.equal((await call({ action: "update", index: 1, status: "in_progress" })).details.error, undefined);
+  const res = await call({ action: "status" });
+  assert.deepEqual(res.details.tasks.map((t) => t.status), ["in_progress", "in_progress", "skipped", "pending"]);
+});
+
+test("wave fan-out: in_progress in increasing order succeeds, out of order is rejected naming earlier pending indices", async () => {
+  const ok = harness();
+  await ok.call({ action: "init", tasks: ["a", "b", "c"] });
+  for (const i of [0, 1, 2]) assert.equal((await ok.call({ action: "update", index: i, status: "in_progress" })).details.error, undefined);
+  const bad = harness();
+  await bad.call({ action: "init", tasks: ["a", "b", "c"] });
+  const res = await bad.call({ action: "update", index: 2, status: "in_progress" });
+  assert.equal(res.details.error, "pending-suffix violation: 0,1");
+  assert.match(res.content[0].text, /pending tasks precede it: 0 "a", 1 "b"\./);
+});
+
+test("init: strings, objects, and mixed forms normalize; ordering violation rejects the whole list", async () => {
+  const { call } = harness();
+  const strings = await call({ action: "init", tasks: ["a", "b"] });
+  assert.deepEqual(strings.details.tasks, [{ name: "a", status: "pending" }, { name: "b", status: "pending" }]);
+  const objects = await call({ action: "init", tasks: [{ name: "a", status: "complete" }, { name: "b", status: "skipped" }, "c"] });
+  assert.equal(objects.details.error, undefined);
+  assert.deepEqual(objects.details.tasks, [
+    { name: "a", status: "complete" },
+    { name: "b", status: "skipped" },
+    { name: "c", status: "pending" },
+  ]);
+  const bad = await call({ action: "init", tasks: [{ name: "a", status: "complete" }, "b", { name: "c", status: "complete" }] });
+  assert.equal(bad.details.error, "pending-suffix violation: 1");
+  assert.equal(
+    bad.content[0].text,
+    [
+      'Error: cannot init: pending tasks precede started or finished ones: 1 "b".',
+      "Rule: pending tasks must trail every started or finished task.",
+      "Reorder the list or restate those statuses truthfully, then retry.",
+      "Proposed: 0 a=complete, 1 b=pending, 2 c=complete",
+    ].join("\n"),
+  );
+  assert.doesNotMatch(bad.content[0].text, /Current:/);
+  assert.deepEqual(bad.details.tasks.map((t) => t.status), ["complete", "skipped", "pending"]);
+});
+
+test("init ordering violation with no prior plan leaves no plan", async () => {
+  const { call, widget } = harness();
+  const bad = await call({ action: "init", tasks: ["a", { name: "b", status: "complete" }] });
+  assert.equal(bad.details.error, "pending-suffix violation: 0");
+  assert.deepEqual(bad.details.tasks, []);
+  assert.equal(widget(), undefined);
+});
+
+test("skipped round-trips, replays, renders \u2298, counts as done, and is never current", async () => {
+  const { call, widget, 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: "skipped" });
+  assert.equal(res.details.error, undefined);
+  assert.match(res.content[0].text, /Plan: 2\/3 done \(1 pending, 1 skipped\)/);
+  assert.match(res.content[0].text, /\u2298 \[1\] b/);
+  const w = widget()!;
+  assert.match(w, /\u2298/);
+  assert.match(w, /\(2\/3\)/);
+  assert.match(w, /c$/);
+  const rendered = (tool().renderResult(res as any, {}, theme as any) as any).text as string;
+  assert.match(rendered, /^\u2713 Updated \(2\/3 done, 1 skipped\)$/);
+  const status = await call({ action: "status" });
+  const statusText = (tool().renderResult(status as any, {}, theme as any) as any).text as string;
+  assert.match(statusText, /^2\/3 done, 1 skipped\n/);
+
+  const replay = harness([{ type: "message", message: { role: "toolResult", toolName: "plan_tracker", details: res.details } }]);
+  await replay.fire("session_start");
+  const after = await replay.call({ action: "status" });
+  assert.deepEqual(after.details.tasks.map((t) => t.status), ["complete", "skipped", "pending"]);
+});
+
+test("all tasks skipped renders (M/M)", async () => {
+  const { call, widget } = harness();
+  await call({ action: "init", tasks: ["a", "b"] });
+  await call({ action: "update", index: 0, status: "skipped" });
+  await call({ action: "update", index: 1, status: "skipped" });
+  assert.match(widget()!, /\(2\/2\)/);
+});
+
+test("legacy-invalid snapshot: first update is rejected listing legacy offenders; truthful object-form re-init repairs it", async () => {
+  const branch = [
+    {
+      type: "message",
+      message: {
+        role: "toolResult",
+        toolName: "plan_tracker",
+        details: {
+          action: "update",
+          tasks: [
+            { name: "a", status: "pending" },
+            { name: "b", status: "pending" },
+            { name: "c", status: "complete" },
+          ],
+        },
+      },
+    },
+  ];
+  const { call, fire } = harness(branch);
+  await fire("session_start");
+  const rejected = await call({ action: "update", index: 0, status: "complete" });
+  assert.equal(rejected.details.error, "pending-suffix violation: 1");
+  assert.deepEqual(rejected.details.tasks.map((t) => t.status), ["pending", "pending", "complete"]);
+  const repaired = await call({
+    action: "init",
+    tasks: [{ name: "a", status: "complete" }, { name: "b", status: "skipped" }, { name: "c", status: "complete" }],
+  });
+  assert.equal(repaired.details.error, undefined);
+  assert.deepEqual(repaired.details.tasks.map((t) => t.status), ["complete", "skipped", "complete"]);
+});
+
+test("registration: sequential, tasks schema is Array<Union<String, Object>>, description carries the contract", () => {
+  const { executionMode, parameters, description } = harness();
+  assert.equal(executionMode(), "sequential");
+  const tasksSchema = parameters().args[0].tasks.args[0];
+  assert.equal(tasksSchema.kind, "Array");
+  assert.equal(tasksSchema.args[0].kind, "Union");
+  assert.deepEqual(tasksSchema.args[0].args[0].map((s: { kind: string }) => s.kind), ["String", "Object"]);
+  assert.match(description(), /skipped/);
+  assert.match(description(), /pending tasks must trail every started or finished task/);
+  assert.match(description(), /update never sets pending/);
+});

package/extensions/plan-tracker.ts

@@ -11,87 +11,68 @@ 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" | "failed";
+const TASK_STATUSES = ["pending", "in_progress", "complete", "failed", "skipped"] as const;
+type TaskStatus = (typeof TASK_STATUSES)[number];
 
-interface Task {
-  name: string;
-  status: TaskStatus;
-}
-
-interface PlanTrackerDetails {
-  action: "init" | "add" | "update" | "status" | "clear";
-  tasks: Task[];
-  error?: string;
-}
+interface Task { name: string; status: TaskStatus; }
+interface PlanTrackerDetails { action: "init" | "add" | "update" | "status" | "clear"; tasks: Task[]; error?: string; }
 
 const PlanTrackerParams = Type.Object({
-  action: StringEnum(["init", "add", "update", "status", "clear"] as const, {
-    description: "Action to perform",
-  }),
-  tasks: Type.Optional(
-    Type.Array(Type.String(), {
-      description: "Task names (for init and add)",
-    }),
-  ),
-  index: Type.Optional(
-    Type.Integer({
-      minimum: 0,
-      description: "Task index, 0-based (for update)",
-    }),
-  ),
-  status: Type.Optional(
-    StringEnum(["pending", "in_progress", "complete", "failed"] as const, {
-      description: "New status (for update); failed is terminal-negative (ran and did not pass)",
-    }),
-  ),
+  action: StringEnum(["init", "add", "update", "status", "clear"] as const, { description: "Action to perform" }),
+  tasks: Type.Optional(Type.Array(Type.Union([
+    Type.String(),
+    Type.Object({ name: Type.String(), status: StringEnum(TASK_STATUSES, { description: "Status to recreate the task with (init only)" }) }),
+  ]), { description: "Tasks for init and add. A string is a pending task. init also accepts { name, status } to recreate a list with known statuses (fresh session, amendment re-init); the whole list must satisfy the pending-suffix rule." })),
+  index: Type.Optional(Type.Integer({ minimum: 0, description: "Task index, 0-based (for update)" })),
+  status: Type.Optional(StringEnum(TASK_STATUSES, { description: "New status (for update). failed is terminal-negative (ran and did not pass); skipped is terminal, not applicable in this run, counted as done. pending is set only by init/add; to redo a task, reopen it as in_progress, or re-init with {name, status}[] to recreate a whole list." })),
 });
 
 export type PlanTrackerInput = Static<typeof PlanTrackerParams>;
 
-function formatWidget(tasks: Task[], theme: Theme): string {
-  if (tasks.length === 0) return "";
+/** Indices of every pending task that has a non-pending task after it (empty = valid snapshot). */
+export function validateSnapshot(tasks: Task[]): number[] {
+  const offenders: number[] = [];
+  let seenNonPending = false;
+  for (let i = tasks.length - 1; i >= 0; i--) {
+    if (tasks[i].status !== "pending") seenNonPending = true;
+    else if (seenNonPending) offenders.unshift(i);
+  }
+  return offenders;
+}
 
-  const complete = tasks.filter((t) => t.status === "complete").length;
-  const icons = tasks
-    .map((t) => {
-      switch (t.status) {
-        case "complete":
-          return theme.fg("success", "✓");
-        case "in_progress":
-          return theme.fg("warning", "→");
-        case "failed":
-          return theme.fg("error", "✗");
-        default:
-          return theme.fg("dim", "○");
-      }
-    })
-    .join("");
+const RULE_LINE = "Rule: pending tasks must trail every started or finished task.";
+const snapshotLine = (tasks: Task[]): string => tasks.map((t, i) => `${i} ${t.name}=${t.status}`).join(", ");
+const offenderList = (tasks: Task[], indices: number[]): string => indices.map((i) => `${i} "${tasks[i].name}"`).join(", ");
+const normalizeTask = (t: string | { name: string; status: TaskStatus }): Task => typeof t === "string" ? { name: t, status: "pending" } : { name: t.name, status: t.status };
+
+const glyph = (status: TaskStatus, theme?: Theme): string => {
+  const [color, icon]: [string, string] = status === "complete" ? ["success", "✓"] : status === "in_progress" ? ["warning", "→"] : status === "failed" ? ["error", "✗"] : status === "skipped" ? ["dim", "⊘"] : ["dim", "○"];
+  return theme ? theme.fg(color as Parameters<Theme["fg"]>[0], icon) : icon;
+};
 
-  // Find current task (first in_progress, or first pending)
+const counts = (tasks: Task[]) => {
+  const by = (s: TaskStatus) => tasks.filter((t) => t.status === s).length;
+  const failed = by("failed");
+  const skipped = by("skipped");
+  return { done: by("complete") + skipped, inProgress: by("in_progress"), pending: by("pending"), failed, skipped, suffix: `${failed > 0 ? `, ${failed} failed` : ""}${skipped > 0 ? `, ${skipped} skipped` : ""}` };
+};
+
+function formatWidget(tasks: Task[], theme: Theme): string {
+  if (tasks.length === 0) return "";
+  const { done } = counts(tasks);
+  const icons = tasks.map((t) => glyph(t.status, theme)).join("");
   const current = tasks.find((t) => t.status === "in_progress") ?? tasks.find((t) => t.status === "pending");
   const currentName = current ? `  ${current.name}` : "";
-
-  return `${theme.fg("muted", "Tasks:")} ${icons} ${theme.fg("muted", `(${complete}/${tasks.length})`)}${currentName}`;
+  return `${theme.fg("muted", "Tasks:")} ${icons} ${theme.fg("muted", `(${done}/${tasks.length})`)}${currentName}`;
 }
 
 function formatStatus(tasks: Task[]): string {
   if (tasks.length === 0) return "No plan active.";
-
-  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, ${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" ? "→" : t.status === "failed" ? "✗" : "○";
-    lines.push(`  ${icon} [${i}] ${t.name}`);
-  }
+  const c = counts(tasks);
+  const groups = [[c.inProgress, "in progress"], [c.pending, "pending"], [c.failed, "failed"], [c.skipped, "skipped"]] as const;
+  const detail = groups.filter(([n]) => n > 0).map(([n, label]) => `${n} ${label}`);
+  const lines: string[] = [`Plan: ${c.done}/${tasks.length} done${detail.length > 0 ? ` (${detail.join(", ")})` : ""}`, ""];
+  for (let i = 0; i < tasks.length; i++) lines.push(`  ${glyph(tasks[i].status)} [${i}] ${tasks[i].name}`);
   return lines.join("\n");
 }
 
@@ -134,8 +115,9 @@ export default function (pi: ExtensionAPI) {
     name: "plan_tracker",
     label: "Plan Tracker",
     description:
-      "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.",
+      "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 (not yet touched), in_progress (started; several at once is fine), complete, failed (terminal-negative: ran and did not pass; never counted done), skipped (terminal: not applicable in this run; counted done). Rule: pending tasks must trail every started or finished task - an update that would leave a pending task ahead of a non-pending one is rejected with the fix. update never sets pending; init and add do. Actions: init (set task list; elements are task-name strings or { name, status } to recreate a list with known statuses), 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,
+    executionMode: "sequential",
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       switch (params.action) {
@@ -150,7 +132,20 @@ export default function (pi: ExtensionAPI) {
               } as PlanTrackerDetails,
             };
           }
-          tasks = params.tasks.map((name) => ({ name, status: "pending" as TaskStatus }));
+          const proposed = params.tasks.map(normalizeTask);
+          const offenders = validateSnapshot(proposed);
+          if (offenders.length > 0) {
+            return {
+              content: [{ type: "text", text: [
+                `Error: cannot init: pending tasks precede started or finished ones: ${offenderList(proposed, offenders)}.`,
+                RULE_LINE,
+                "Reorder the list or restate those statuses truthfully, then retry.",
+                `Proposed: ${snapshotLine(proposed)}`,
+              ].join("\n") }],
+              details: { action: "init", tasks: tasks.map((t) => ({ ...t })), error: `pending-suffix violation: ${offenders.join(",")}` } as PlanTrackerDetails,
+            };
+          }
+          tasks = proposed;
           updateWidget(ctx);
           return {
             content: [
@@ -174,7 +169,7 @@ export default function (pi: ExtensionAPI) {
               } as PlanTrackerDetails,
             };
           }
-          tasks.push(...params.tasks.map((name) => ({ name, status: "pending" as TaskStatus })));
+          tasks.push(...params.tasks.map((t) => ({ name: normalizeTask(t).name, status: "pending" as TaskStatus })));
           updateWidget(ctx);
           return {
             content: [
@@ -223,7 +218,32 @@ export default function (pi: ExtensionAPI) {
               } as PlanTrackerDetails,
             };
           }
-          tasks[params.index].status = params.status;
+          const target = tasks[params.index];
+          if (params.status === "pending") {
+            return {
+              content: [{ type: "text", text: [
+                `Error: cannot set task ${params.index} "${target.name}" to pending: update never sets pending; a task is pending only from init/add.`,
+                "To redo it, update it to in_progress. To recreate the whole list, re-init with {name, status}[].",
+                `Current: ${snapshotLine(tasks)}`,
+              ].join("\n") }],
+              details: { action: "update", tasks: tasks.map((t) => ({ ...t })), error: "update cannot set pending" } as PlanTrackerDetails,
+            };
+          }
+          const candidate = tasks.map((t, i) => (i === params.index ? { ...t, status: params.status as TaskStatus } : { ...t }));
+          const offenders = validateSnapshot(candidate);
+          if (offenders.length > 0) {
+            return {
+              content: [{ type: "text", text: [
+                `Error: cannot set task ${params.index} "${target.name}" to ${params.status}: pending tasks precede it: ${offenderList(tasks, offenders)}.`,
+                RULE_LINE,
+                "Fix first, then retry: update each listed task to in_progress (working on it now), complete, failed, or skipped (not applicable in this run); or, if the list order itself is wrong, re-init with {name, status}[] keeping every task and its true status so the untouched ones trail.",
+                "Never clear, drop tasks, or record a status the work has not actually reached.",
+                `Current: ${snapshotLine(tasks)}`,
+              ].join("\n") }],
+              details: { action: "update", tasks: tasks.map((t) => ({ ...t })), error: `pending-suffix violation: ${offenders.join(",")}` } as PlanTrackerDetails,
+            };
+          }
+          tasks = candidate;
           updateWidget(ctx);
           return {
             content: [
@@ -309,12 +329,9 @@ export default function (pi: ExtensionAPI) {
             0,
           );
         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` : "";
+          const c = counts(taskList);
           return new Text(
-            theme.fg("success", "✓ ") +
-              theme.fg("muted", `Updated (${complete}/${taskList.length} complete${suffix})`),
+            theme.fg("success", "✓ ") + theme.fg("muted", `Updated (${c.done}/${taskList.length} done${c.suffix})`),
             0,
             0,
           );
@@ -323,19 +340,10 @@ export default function (pi: ExtensionAPI) {
           if (taskList.length === 0) {
             return new Text(theme.fg("dim", "No plan active"), 0, 0);
           }
-          const complete = taskList.filter((t) => t.status === "complete").length;
-          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}`);
+          const c = counts(taskList);
+          let text = theme.fg("muted", `${c.done}/${taskList.length} done${c.suffix}`);
           for (const t of taskList) {
-            const icon =
-              t.status === "complete"
-                ? theme.fg("success", "✓")
-                : t.status === "in_progress"
-                  ? theme.fg("warning", "→")
-                  : t.status === "failed"
-                    ? theme.fg("error", "✗")
-                    : theme.fg("dim", "○");
+            const icon = glyph(t.status, theme);
             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": "5.5.4",
+  "version": "5.6.1",
   "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

@@ -61,7 +61,8 @@ Work through the items below **in order**. This is your own checklist to follow,
    substep. Unconditional, foreground, no user interaction — the next thing the user
    sees is a questionary question. This produces the draft; the step below consumes it.
 4. **Understand the idea against the draft** — `Read` the draft, verify load-bearing
-   claims against real code, ask questions one at a time, append citable findings
+   claims against real code, ask questions one at a time, append citable findings;
+   then state the chat premise note (section 3) before approaches
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in two rounds, one approval each
 7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](#marking-superseded-specs), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
@@ -143,13 +144,30 @@ path.
   section starts that answer; confirm it before designing from scratch.
 - Ask questions **one at a time** to refine the idea. Prefer multiple-choice; one
   question per message. Focus on: purpose, constraints, success criteria, who/what
-  it touches.
+  it touches. Before asking, check whether the code, the docs, or the issue tracker
+  already answer it - if so, look it up instead of asking (dispatch a subagent when
+  the lookup is costly), and ask only what no source can answer. Every question you
+  ask, including asking the user to accept a corrected fact, ends with the line
+  `Recommendation: <answer> - <why>` - the answer, then " - ", then the reason.
 - **Append bar:** append to the draft's `## Appended during questionary` only
   findings the spec will cite — schema shapes, hard constraints, ticket-vs-code
   contradictions, user answers that changed scope. Not a log of every grep.
   (Appending uses `edit`; the `edit` prohibition in the spec-writing step applies
   only there.)
 
+Before proposing approaches, state the premise note in chat: what the design depends
+on, which of those claims the sources support and where you saw it (a file and line,
+a doc, a ticket), which they disprove - give the corrected fact and where you found
+it - and which remain unverified, naming the lookup you tried. Write it as a note a
+person can act on: full sentences, no status-keyword lists, no template; when the
+design depends on no claims at all, one sentence saying so is enough. An unverified claim is not a stop - it enters the
+spec as an Open Question or a stated assumption. If a claim the design depends on was
+contradicted, the note is your next message and it ends by asking the user to accept
+the corrected fact or explicitly override it; nothing else continues - no other
+questions, no approaches - until they answer, and the outcome is recorded in the draft's
+`## Appended during questionary` so spec-writing carries it into `## Problem` or the relevant `## Design`
+decision.
+
 ### 4. Explore approaches
 
 - Propose 2-3 different approaches with trade-offs.
@@ -354,7 +372,7 @@ Execute this section in place from any later phase. Do not invoke `/skill:brains
 
 1. Edit the spec. Show `git --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
 2. Wait for approval. Change request -> revise, re-show.
-3. No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks, `update` for changed ones; anchor-changed completed tasks go back to `pending` and re-run the task loop. A removed task is deleted from the plan; then re-`init` the tracker with the remaining tasks in wave order and `update` every already-completed task back to `complete` (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
+3. No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
 
 Redraw test: the diff changes the problem statement, adds or removes a component, or moves a component boundary -> redraw. A change inside one component (a persistence mechanism, a worker's HTTP client, dropping a fallback and its task) -> amend. State the call in the same message as the diff; the user overrides either way.
 
@@ -382,6 +400,7 @@ Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "c
 - Running, deploying, or validating the proposed change before approval.
 - Proceeding to `/skill:writing-plans` before the user approves the spec, or invoking `/skill:brainstorming` to amend an approved spec.
 - Writing a replacement spec without the known predecessor's banner, or offering a multi-spec split that fails `../shape-ticket/reference/split-axes.md`.
+- Proposing approaches while a contradicted claim is unresolved.
 
 ## Project overrides
 

package/skills/check-delivery/SKILL.md

@@ -125,11 +125,12 @@ configured) all emitted for manual execution, none auto-posted.
 stage plus one task per AC - status mappings below apply only after that
 init: pass / `satisfied` / `not externally observable` /
 `unverified: no delivery target` / `allowed gap` / `proposed descope` ->
-`complete`; failed stage / `unexplained gap` -> `failed`; skipped stage 2 -> `complete`, skip named in
-the task title (e.g. "delivery target - skipped, none configured"), so a
-successful zero-config run still renders finished. Optional-degrading: a
-native task list, or no tracking at all, on harnesses without
-`plan_tracker`; absence is never a hard stop.
+`complete`; failed stage / `unexplained gap` -> `failed`; skipped stage 2 ->
+`skipped` (rendered ⊘, counted as done - never `complete` under a renamed
+title). AC tasks follow the four stage tasks; record each AC verdict while
+stage 3 is `in_progress` - the tracker rejects a verdict recorded behind a
+still-pending stage. Optional-degrading: a native task list, or no tracking
+at all, on harnesses without `plan_tracker`; absence is never a hard stop.
 
 **Stage 0 - Pre-flight.** Fetch the ticket and all comments. Check the
 current tracker status first: if it is already in a terminal/done state,

package/skills/gatekeep-pr/SKILL.md

@@ -83,14 +83,18 @@ configuration.
 
 ## Progress tracking
 
-Use `plan_tracker`, never `phase_tracker`. Init with the stage names: `gather`,
-`provision worktree`, `resolve evidence`, `claim-check`, `review`, `consent menu`.
-Append one task per material claim as the Verifier enumerates them. A passing stage or
-a matched claim -> `complete`. A failed stage or a contradicted claim -> `failed`
-(shown crossed, error color) and stays failed while the skill stops at the menu -
-never marked complete to move on. On a harness without the `plan_tracker` tool: fall
-back to a plain checklist (or skip if none is available); functionality is unchanged
-either way.
+Use `plan_tracker`, never `phase_tracker`. Init with the first four stages:
+`gather`, `provision worktree`, `resolve evidence`, `claim-check`. While
+`claim-check` is `in_progress`, `add` one task per material claim as the
+Verifier enumerates them and record each verdict: a matched claim ->
+`complete`, a contradicted claim -> `failed` (shown crossed, error color).
+Once every claim is terminal and `claim-check` is closed, `add` `review` and
+`consent menu` and continue. Stages are never inited ahead of the claims:
+the tracker rejects a verdict recorded behind a still-pending stage. A
+failed stage or claim stays `failed` while the skill stops at the menu -
+never marked complete to move on. On a harness without the `plan_tracker`
+tool: fall back to a plain checklist (or skip if none is available);
+functionality is unchanged either way.
 
 ## Assessment
 

package/skills/subagent-driven-development/SKILL.md

@@ -171,9 +171,9 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 **Progress tracking (`plan_tracker`).** `plan_tracker` is a flat list with no native group concept, so waves are *encoded*, not modeled:
 
 - **Consume, preserve, recover only if absent:** consume the wave-ordered list initialized at writing-plans handoff; indices are positional and stable, so never re-init on continuation or mid-run. Only direct recovery with no tracker initializes the full plan list once before dispatch.
-- **Wave fan-out → `in_progress`:** unconditionally mark every task index in the wave `in_progress` before dispatch. Multiple simultaneous entries are expected (sequential mode has one).
+- **Wave fan-out → `in_progress`:** unconditionally mark every task index in the wave `in_progress` before dispatch, in increasing index order (the tracker validates each call against the previous one and rejects a start while an earlier index is still `pending`). Multiple simultaneous entries are expected (sequential mode has one).
 - **Wave commit → `complete`:** after the wave's gate passes and it commits, unconditionally mark all those same indices `complete`. `complete` = durably committed, so a task in conflict fallback stays `in_progress` until its wave commits.
-- **Lifecycle per task:** `pending → in_progress (wave fan-out) → complete (wave commit)`.
+- **Lifecycle per task:** `pending → in_progress (wave fan-out) → complete (wave commit)`; `failed` when a task ran and did not pass; `skipped` when the plan drops it as not applicable (terminal, counted done). A rejected `update` names the earlier pending tasks and the legal fixes - record those tasks' true state, never `clear` or re-`init` to move on.
 - **Widget caveat (known, deliberately unfixed).** The persistent `plan_tracker` widget's icon strip (`○ → ✓`) and `(c/total)` count reflect every task, but its trailing *name* shows only the **first** `in_progress` task. In parallel mode the icon strip and the `status` action are the full in-flight view; a richer multi-task widget is a separate extension change, out of scope (YAGNI).
 - **Sequential mode:** consume the same existing full list, one `in_progress` index at a time; wave prefixes are harmless.
 

package/skills/verification-before-completion/reference/conformance-check.md

@@ -143,7 +143,7 @@ prerequisites hold.
 
 Per round:
 
-1. **Synchronize gap tasks** — append only a genuinely new gap that is entering remediation, named `Gn: <gap origin clause verbatim, truncated>`; never `init`. Find existing gaps by their exact `Gn:` prefix and reuse that index even if origin wording changes. Carried-OPEN inventory-only gaps add nothing. Before dispatch, mark every remediated gap's existing index `in_progress`; a re-audit needing more work reopens that same `Gn` index. The lifecycle traces `[T1,T2]`, then `[T1,T2,G1]`, then `[T1,T2,G1,G2]`; no test-retry or review-round wrapper task.
+1. **Synchronize gap tasks** — append only a genuinely new gap that is entering remediation, named `Gn: <gap origin clause verbatim, truncated>`; never `init`. Find existing gaps by their exact `Gn:` prefix and reuse that index even if origin wording changes. Carried-OPEN inventory-only gaps add nothing. Before dispatch, mark every remediated gap's existing index `in_progress`, in increasing index order (the tracker rejects a start while a lower index is still `pending`); a re-audit needing more work reopens that same `Gn` index. The lifecycle traces `[T1,T2]`, then `[T1,T2,G1]`, then `[T1,T2,G1,G2]`; no test-retry or review-round wrapper task.
 2. **Fix wave** — select gaps greedily in `Gn` order: take each `fix` gap unless a gap it `conflicts` with (per the report's `Parallel-safe:` line) is already taken; the certificate's `disjoint` grouping is ignored, and a certificate still malformed after the one re-ask means every gap `conflicts` with every other. Held gaps carry to the next round; the wave is never empty while an eligible `fix` gap exists. Dispatch **one** call - `subagent({ context: "fresh", async: false, tasks: [...] })` - with one `implementer` task per selected gap (`worktree: true`, `cwd` = the conformance worktree, task = the gap block verbatim with `touched-files` as the ownership boundary). A single gap is a one-task `tasks` call; a lone `agent: "implementer"` call never appears in this loop. For an `UNAUTHORIZED` `fix` gap
    whose `evidence` opens with the over-spec provenance (`spec "<section>" - "<clause>" (over-spec)`), the orchestrator adds the spec path to that gap's `touched-files` before dispatch,
    so the implementer deletes the surface **and** the clause/AC line in the same