@sreetej510/pi-shipd-checks 0.1.1

package/src/command.ts

@@ -0,0 +1,387 @@
+/** Registers the `/checks` command: argument parsing, the --config flow, and the main run orchestration. */
+
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { runGapFinder, runGapValidator, runReviewer } from "./agents.js";
+import {
+  getSupportedThinkingLevels,
+  loadEnabledModelRefs,
+  loadReviewConfig,
+  saveReviewConfig,
+  splitProviderModel,
+} from "./config.js";
+import { snapshotGitHead } from "./git.js";
+import { PROGRESS_WIDGET_KEY, renderProgressLines } from "./progress.js";
+import { buildRunSummary, loadExistingReport, mergeReport, REQUIRED_FILES } from "./report.js";
+import { ROLES } from "./roles.js";
+import { loadFairnessRules, loadGuidelinesSections } from "./rubric.js";
+import { endReview, isReviewInProgress, startReview } from "./state.js";
+import type {
+  CommandOption,
+  GapStageResult,
+  ReviewerRole,
+  ReviewReport,
+  TestGapCandidate,
+  TestGapFinal,
+  ThinkingLevel,
+} from "./types.js";
+
+export const CANCEL_SHORTCUT_LABEL = "Ctrl+Shift+X";
+
+const COMMAND_COMPLETIONS: readonly CommandOption[] = [
+  { value: "--all", label: "--all", description: "Run everything: 3 focus reviewers + test-gap finder/filter" },
+  {
+    value: "--review",
+    label: "--review",
+    description: "Run only the 3 focus reviewer agents (description/tests/solution)",
+  },
+  {
+    value: "--description",
+    label: "--description",
+    description: "Run only the problem-description (prompt) focus reviewer",
+  },
+  { value: "--tests", label: "--tests", description: "Run only the tests focus reviewer" },
+  { value: "--solution", label: "--solution", description: "Run only the solution focus reviewer" },
+  {
+    value: "--gap-finder",
+    label: "--gap-finder",
+    description: "Run only the 2-step behavioral test-gap finder + strict filter agents",
+  },
+  { value: "--config", label: "--config", description: "Set the reviewer model and thinking level" },
+];
+
+function getArgumentCompletions(prefix: string) {
+  // Flags are additive (e.g. "--tests --gap-finder"), so completions must
+  // account for flags already typed: drop them from suggestions, and keep
+  // --config mutually exclusive with everything else.
+  const trimmed = prefix.trimStart();
+  const trailingSpace = /\s$/.test(trimmed);
+  const tokens = trimmed.trimEnd().split(/\s+/).filter(Boolean);
+  const current = trailingSpace ? "" : (tokens.at(-1) ?? "");
+  const usedTokens = new Set(trailingSpace ? tokens : tokens.slice(0, -1));
+  const completionPrefix = trailingSpace ? trimmed : trimmed.slice(0, trimmed.length - current.length);
+
+  const hasConfig = usedTokens.has("--config");
+  const hasOtherFlag = [...usedTokens].some((t) => t !== "--config");
+
+  const candidates = COMMAND_COMPLETIONS.filter((o) => {
+    if (usedTokens.has(o.value)) return false;
+    if (hasConfig) return false;
+    if (hasOtherFlag && o.value === "--config") return false;
+    return o.value.startsWith(current);
+  });
+
+  return candidates.length > 0 ? candidates.map((o) => ({ ...o, value: `${completionPrefix}${o.value}` })) : null;
+}
+
+/** Interactive `/checks --config` flow: pick a model (highlighting the current one), then a thinking level. */
+async function runConfigFlow(ctx: ExtensionCommandContext) {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify("/checks --config requires interactive mode", "error");
+    return;
+  }
+  const refs = loadEnabledModelRefs();
+  if (refs.length === 0) {
+    ctx.ui.notify("No enabledModels configured in settings.json.", "error");
+    return;
+  }
+  const existingConfig = loadReviewConfig();
+  const available = ctx.modelRegistry.getAll();
+  const labeled = refs
+    .map((ref) => {
+      const parsed = splitProviderModel(ref);
+      if (!parsed) return null;
+      const found = available.find((m: any) => m.provider === parsed.provider && m.id === parsed.modelId);
+      const isCurrent = existingConfig?.provider === parsed.provider && existingConfig?.modelId === parsed.modelId;
+      const base = found ? `${found.name} (${ref})` : ref;
+      return { ref, parsed, display: isCurrent ? `${base} [current]` : base, found, isCurrent };
+    })
+    .filter((x): x is NonNullable<typeof x> => x !== null);
+
+  if (labeled.length === 0) {
+    ctx.ui.notify("Could not resolve any enabledModels entries.", "error");
+    return;
+  }
+
+  // Surface the currently configured model at the top of the list, alongside
+  // the "[current]" label, since ctx.ui.select can't pre-position the cursor.
+  const orderedModels = [...labeled].sort((a, b) => (a.isCurrent === b.isCurrent ? 0 : a.isCurrent ? -1 : 1));
+
+  const choice = await ctx.ui.select(
+    "Select model for checks reviewer agents",
+    orderedModels.map((l) => l.display),
+  );
+  if (!choice) return;
+  const selected = labeled.find((l) => l.display === choice);
+  if (!selected) return;
+
+  let thinkingLevel: ThinkingLevel = "off";
+  const supportedLevels = getSupportedThinkingLevels(selected.found);
+  if (supportedLevels.length > 1) {
+    const currentLevel = selected.isCurrent ? existingConfig?.thinkingLevel : undefined;
+    const levelOptions = [...supportedLevels].sort((a, b) =>
+      (a === currentLevel) === (b === currentLevel) ? 0 : a === currentLevel ? -1 : 1,
+    );
+    const levelDisplay = (l: ThinkingLevel) => (l === currentLevel ? `${l} [current]` : l);
+    const level = await ctx.ui.select("Select thinking level for reviewer agents", levelOptions.map(levelDisplay));
+    if (!level) return;
+    thinkingLevel = levelOptions.find((l) => levelDisplay(l) === level) ?? (level as ThinkingLevel);
+  }
+
+  saveReviewConfig({ provider: selected.parsed.provider, modelId: selected.parsed.modelId, thinkingLevel });
+  ctx.ui.notify(
+    `checks config saved: ${selected.parsed.provider}/${selected.parsed.modelId} (thinking: ${thinkingLevel})`,
+    "info",
+  );
+}
+
+export function registerChecksCommand(pi: ExtensionAPI) {
+  pi.registerCommand("checks", {
+    description: "Strict review of agent_prompt.md/test.patch/solution.patch. Requires an option — see /checks.",
+    getArgumentCompletions,
+
+    handler: async (args, ctx) => {
+      const sub = args.trim();
+
+      // ── /checks (no args) — list options, run nothing ──
+      if (sub === "") {
+        ctx.ui.notify(COMMAND_COMPLETIONS.map((o) => `${o.value}  —  ${o.description}`).join("\n"), "info");
+        return;
+      }
+
+      const tokens = [...new Set(sub.split(/\s+/).filter(Boolean))];
+      const knownFlags = new Set(COMMAND_COMPLETIONS.map((o) => o.value));
+      const unknown = tokens.filter((t) => !knownFlags.has(t));
+      if (unknown.length > 0) {
+        ctx.ui.notify(
+          `Unknown option(s): ${unknown.join(", ")}. Run /checks with no arguments to see the available options.`,
+          "warning",
+        );
+        return;
+      }
+
+      // ── /checks --config ───────────────────────────
+      if (tokens.includes("--config")) {
+        if (tokens.length > 1) {
+          ctx.ui.notify("--config cannot be combined with other options.", "warning");
+          return;
+        }
+        await runConfigFlow(ctx);
+        return;
+      }
+
+      // Flags are additive — any combination of role flags / --review / --all /
+      // --gap-finder may be passed together (e.g. "--tests --gap-finder" runs
+      // just the tests reviewer plus the gap-finder/filter stages).
+      const roleKeys = new Set<ReviewerRole["key"]>();
+      if (tokens.includes("--all") || tokens.includes("--review")) {
+        for (const role of ROLES) roleKeys.add(role.key);
+      }
+      for (const role of ROLES) {
+        if (tokens.includes(`--${role.key}`)) roleKeys.add(role.key);
+      }
+      const runGapStages = tokens.includes("--all") || tokens.includes("--gap-finder");
+      const activeRoles = ROLES.filter((r) => roleKeys.has(r.key));
+      const runReviewers = activeRoles.length > 0;
+
+      if (!runReviewers && !runGapStages) {
+        ctx.ui.notify(
+          `Nothing to run for: ${tokens.join(" ")}. Run /checks with no arguments to see the available options.`,
+          "warning",
+        );
+        return;
+      }
+      const runLabel = tokens.join(" ");
+
+      if (isReviewInProgress()) {
+        ctx.ui.notify("A checks run is already in progress.", "warning");
+        return;
+      }
+
+      const config = loadReviewConfig();
+      if (!config) {
+        ctx.ui.notify("No reviewer model configured. Run /checks --config first.", "error");
+        return;
+      }
+
+      const model = ctx.modelRegistry.find(config.provider, config.modelId);
+      if (!model) {
+        ctx.ui.notify(
+          `Configured model ${config.provider}/${config.modelId} not found. Run /checks --config again.`,
+          "error",
+        );
+        return;
+      }
+      if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
+        ctx.ui.notify(`No auth configured for ${config.provider}/${config.modelId}.`, "error");
+        return;
+      }
+
+      const missing = REQUIRED_FILES.filter((f) => !existsSync(join(ctx.cwd, f)));
+      if (missing.length > 0) {
+        ctx.ui.notify(`Missing required file(s) in project root: ${missing.join(", ")}`, "error");
+        return;
+      }
+
+      const reviewAbort = startReview();
+      // Stage count depends on which flags were passed: however many focus
+      // reviewers were selected, plus the gap-finder + gap-filter stages if requested.
+      const TOTAL_STAGES = (runReviewers ? activeRoles.length : 0) + (runGapStages ? 2 : 0);
+      ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("preparing clean snapshot", 0, TOTAL_STAGES));
+      ctx.ui.notify(`checks (${runLabel}) started. Press ${CANCEL_SHORTCUT_LABEL} to cancel.`, "info");
+
+      let tempDir: string | undefined;
+      try {
+        // Unique per-run directory (UUID) so concurrent runs — even across different
+        // projects/sessions — never collide on the same temp path.
+        const dir = join(tmpdir(), `checks-${randomUUID()}`);
+        mkdirSync(dir, { recursive: true });
+        tempDir = dir;
+
+        const snapshot = await snapshotGitHead(pi, ctx.cwd, dir);
+        if (snapshot.status === "error") {
+          ctx.ui.notify(`checks: ${snapshot.error}`, "error");
+          return;
+        }
+
+        for (const f of REQUIRED_FILES) {
+          copyFileSync(join(ctx.cwd, f), join(dir, f));
+        }
+
+        const sections = loadGuidelinesSections();
+        const fairnessRules = loadFairnessRules();
+        let completed = 0;
+
+        let reports: ReviewReport[] = [];
+        if (runReviewers) {
+          ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("reviewing", completed, TOTAL_STAGES));
+          reports = await Promise.all(
+            activeRoles.map((role) =>
+              runReviewer({
+                pi,
+                role,
+                tempDir: dir,
+                model,
+                thinkingLevel: config.thinkingLevel,
+                rubric: sections[role.key],
+                fairnessRules,
+                cancelSignal: reviewAbort.signal,
+              }).then((report) => {
+                completed += 1;
+                ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("reviewing", completed, TOTAL_STAGES));
+                return report;
+              }),
+            ),
+          );
+
+          if (reviewAbort.signal.aborted) {
+            ctx.ui.notify("checks: cancelled.", "warning");
+            return;
+          }
+        }
+
+        // ── Test-gap analysis: a research agent proposes candidate behavioral
+        // gaps (required-but-untested edge cases that could let an incorrect
+        // solution slip past test.patch), then a strict, independent filter
+        // agent verifies each one against the fairness rules before it's kept.
+        // This never turns a PASS into a FAIL — it only annotates the report.
+        let gapFinding: GapStageResult<TestGapCandidate> = { status: "ok", gaps: [] };
+        let gapFiltering: GapStageResult<TestGapFinal> = { status: "ok", gaps: [] };
+        if (runGapStages) {
+          ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("finding test gaps", completed, TOTAL_STAGES));
+          gapFinding = await runGapFinder({
+            tempDir: dir,
+            model,
+            thinkingLevel: config.thinkingLevel,
+            testRubric: sections.tests,
+            fairnessRules,
+            cancelSignal: reviewAbort.signal,
+          });
+          completed += 1;
+          ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("finding test gaps", completed, TOTAL_STAGES));
+
+          if (reviewAbort.signal.aborted) {
+            ctx.ui.notify("checks: cancelled.", "warning");
+            return;
+          }
+
+          if (gapFinding.status === "ok" && gapFinding.gaps.length > 0) {
+            ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("validating test gaps", completed, TOTAL_STAGES));
+            gapFiltering = await runGapValidator({
+              tempDir: dir,
+              model,
+              thinkingLevel: config.thinkingLevel,
+              testRubric: sections.tests,
+              fairnessRules,
+              candidates: gapFinding.gaps,
+              cancelSignal: reviewAbort.signal,
+            });
+          }
+          completed += 1;
+          ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("validating test gaps", completed, TOTAL_STAGES));
+
+          if (reviewAbort.signal.aborted) {
+            ctx.ui.notify("checks: cancelled.", "warning");
+            return;
+          }
+        }
+
+        ctx.ui.setWidget(PROGRESS_WIDGET_KEY, renderProgressLines("finalizing report", TOTAL_STAGES, TOTAL_STAGES));
+
+        // Each reviewer's structured report lives under its own key so per-agent
+        // detail is always preserved. Test gaps never affect `overall` — they're
+        // supplementary, filtered notes.
+        const byRole: Record<string, ReviewReport> = {};
+        activeRoles.forEach((role, i) => {
+          if (reports[i]) byRole[role.key] = reports[i];
+        });
+        const testGaps = gapFiltering.gaps;
+        const gapAnalysisIncomplete = runGapStages && (gapFinding.status !== "ok" || gapFiltering.status !== "ok");
+
+        // Merge into any existing shipd_report.json instead of clobbering it —
+        // running --review/--description/--tests/--solution/--gap-finder
+        // separately (in any order) should build up one combined report rather
+        // than each overwriting the others' results.
+        const reportPath = join(ctx.cwd, "shipd_report.json");
+        const existingReport = loadExistingReport(reportPath);
+        const merged = mergeReport({
+          existingReport,
+          config,
+          runReviewers,
+          byRole,
+          runGapStages,
+          testGaps,
+          gapAnalysisIncomplete,
+          gapFinderStatus: gapFinding.status,
+          gapFilterStatus: gapFiltering.status,
+        });
+
+        const summary = buildRunSummary({ merged, runReviewers, activeRoles, byRole, runGapStages });
+        pi.sendMessage({
+          customType: "shipd_checks_report",
+          content: summary.content,
+          display: true,
+          details: summary.details,
+        });
+
+        writeFileSync(reportPath, JSON.stringify(merged, null, 2), "utf-8");
+        ctx.ui.notify(`checks: wrote details to ${reportPath}`, "info");
+      } catch (err) {
+        ctx.ui.notify(`checks failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+      } finally {
+        ctx.ui.setWidget(PROGRESS_WIDGET_KEY, undefined);
+        if (tempDir) {
+          try {
+            rmSync(tempDir, { recursive: true, force: true });
+          } catch {
+            // best effort cleanup
+          }
+        }
+        endReview();
+      }
+    },
+  });
+}

package/src/config.ts

@@ -0,0 +1,84 @@
+/**
+ * Global config (~/.pi/agent/checks-config.json) for the reviewer model +
+ * thinking level, plus helpers for reading pi's own settings.json (enabled
+ * models, shell path) that the config flow and git snapshot step need.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ChecksConfig, ThinkingLevel } from "./types.js";
+
+export const CONFIG_PATH = join(getAgentDir(), "checks-config.json");
+export const SETTINGS_PATH = join(getAgentDir(), "settings.json");
+
+/**
+ * Mirrors `getSupportedThinkingLevels` from `@earendil-works/pi-ai` (not part of
+ * pi-coding-agent's public export surface, so re-implemented here): a level is
+ * available if the model supports reasoning at all, isn't explicitly mapped to
+ * `null` in `thinkingLevelMap`, and — for the opt-in `xhigh`/`max` tiers — is
+ * explicitly present (non-undefined) in that map.
+ */
+const EXTENDED_THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+export function getSupportedThinkingLevels(
+  model: { reasoning?: boolean; thinkingLevelMap?: Record<string, string | null> } | undefined,
+): ThinkingLevel[] {
+  if (!model?.reasoning) return ["off"];
+  return EXTENDED_THINKING_LEVELS.filter((level) => {
+    const mapped = model.thinkingLevelMap?.[level];
+    if (mapped === null) return false;
+    if (level === "xhigh" || level === "max") return mapped !== undefined;
+    return true;
+  });
+}
+
+export function loadReviewConfig(): ChecksConfig | null {
+  try {
+    if (!existsSync(CONFIG_PATH)) return null;
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as ChecksConfig;
+    if (parsed.provider && parsed.modelId && parsed.thinkingLevel) return parsed;
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+export function saveReviewConfig(config: ChecksConfig): void {
+  const dir = dirname(CONFIG_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
+}
+
+export function loadEnabledModelRefs(): string[] {
+  try {
+    if (!existsSync(SETTINGS_PATH)) return [];
+    const settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8")) as { enabledModels?: string[] };
+    return settings.enabledModels ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export function splitProviderModel(ref: string): { provider: string; modelId: string } | null {
+  const idx = ref.indexOf("/");
+  if (idx <= 0 || idx === ref.length - 1) return null;
+  return { provider: ref.slice(0, idx), modelId: ref.slice(idx + 1) };
+}
+
+function getAgentSettings(): { shellPath?: string } {
+  try {
+    if (existsSync(SETTINGS_PATH)) {
+      return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8")) as { shellPath?: string };
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+export function getShellExecutable(): string {
+  const fromSettings = getAgentSettings().shellPath;
+  if (fromSettings) return fromSettings;
+  return process.platform === "win32" ? "C:\\Program Files\\Git\\bin\\bash.exe" : "bash";
+}

package/src/git.ts

@@ -0,0 +1,30 @@
+/** Clean, non-mutating git HEAD snapshot into a scratch directory. */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getShellExecutable } from "./config.js";
+
+function toSlashPath(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+function bashQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export async function snapshotGitHead(
+  pi: ExtensionAPI,
+  repoDir: string,
+  tempDir: string,
+): Promise<{ status: "ok" } | { status: "error"; error: string }> {
+  const headCheck = await pi.exec("git", ["rev-parse", "HEAD"], { cwd: repoDir, timeout: 15_000 });
+  if (headCheck.code !== 0) {
+    return { status: "error", error: "Not a git repository, or it has no commits yet." };
+  }
+
+  const cmd = `git archive HEAD | tar -x -C ${bashQuote(toSlashPath(tempDir))}`;
+  const result = await pi.exec(getShellExecutable(), ["-c", cmd], { cwd: repoDir, timeout: 60_000 });
+  if (result.code !== 0) {
+    return { status: "error", error: result.stderr?.trim() || `git archive failed (exit ${result.code})` };
+  }
+  return { status: "ok" };
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * Shipd Checks Extension for pi
+ *
+ * Strict, parallel 3-agent review of a task's agent_prompt.md, test.patch, and
+ * solution.patch against a combined rubric (see rubric.ts): the per-focus
+ * P1-P5/T1-T6/S1-S4 checklist and the fairness methodology — agent-fault vs
+ * prompt-ambiguity vs test-flaw, fair/unfair test examples. Reviewers only
+ * FAIL for genuine blocking issues; everything else is captured as
+ * non-blocking notes, mirroring how real shipd reviews mostly surface
+ * optional/minor suggestions rather than hard failures.
+ *
+ * Flow (for whichever stages/roles the chosen option below runs):
+ *   1. Snapshot the current git HEAD (no working-dir mutation) into a temp dir
+ *      via `git archive HEAD | tar -x` (see git.ts).
+ *   2. Copy agent_prompt.md, solution.patch, test.patch from the project root
+ *      into that temp dir.
+ *   3. (--all / --review / --description / --tests / --solution) Spawn the
+ *      selected read-only reviewer agent(s) — description / tests / solution,
+ *      all 3 in parallel for --all/--review, or just the one requested —
+ *      each restricted to read/grep/find/ls plus a single
+ *      `submit_review_report` tool they must call with a structured verdict
+ *      (see agents.ts, tools.ts).
+ *   4. (--all / --gap-finder) Run a sequential 2-stage behavioral test-gap
+ *      analysis: an exhaustive researcher agent proposes as many candidate
+ *      gaps as it can find — required-but-untested edge cases that could let
+ *      an incorrect solution slip past test.patch — then a strict,
+ *      independent filter agent re-verifies each candidate against the
+ *      fairness rules and keeps only the ones that hold up. This never turns
+ *      a PASS into a FAIL; it only annotates the report/summary.
+ *   5. Post a one-line chat message and merge results into shipd_report.json
+ *      in the project root (merged, not overwritten — running any of
+ *      --review/--description/--tests/--solution/--gap-finder separately, in
+ *      any order, builds up one combined report; see report.ts). `overall`
+ *      only reflects a confident PASS/FAIL once all 3 focus reviewers have
+ *      run at least once; PASS gets "(with test gaps)" appended when the
+ *      filter stage kept any.
+ *
+ * Commands (all flags below except --config are additive/combinable, e.g.
+ * "/checks --tests --gap-finder" runs just the tests reviewer plus the
+ * gap-finder/filter stages; --config must be used alone):
+ *   /checks               list available options (runs nothing)
+ *   /checks --all         run all 3 focus reviewers + test-gap analysis
+ *   /checks --review      run only the 3 focus reviewer agents
+ *   /checks --description run only the problem-description (prompt) reviewer
+ *   /checks --tests       run only the tests reviewer
+ *   /checks --solution    run only the solution reviewer
+ *   /checks --gap-finder  run only the test-gap finder/filter agents
+ *   /checks --config      set the reviewer model and thinking level
+ * Shortcut: Ctrl+Shift+X cancels an in-progress /checks run.
+ *
+ * File layout:
+ *   index.ts     extension entry point (this file) — renderer, shortcut, command registration
+ *   command.ts   /checks command: arg parsing, --config flow, run orchestration
+ *   agents.ts     spawns/races the reviewer + gap-finder/validator agent sessions
+ *   prompts.ts    all prompt text sent to those agents
+ *   tools.ts      custom tools agents call to submit structured results
+ *   rubric.ts     embedded guidelines/fairness rubric text + section loaders
+ *   roles.ts      the 3 reviewer roles (description/tests/solution) metadata
+ *   report.ts     shipd_report.json load/merge/summary logic
+ *   config.ts     ~/.pi/agent/checks-config.json + settings.json helpers
+ *   git.ts        clean git HEAD snapshot into a scratch directory
+ *   progress.ts   progress-bar widget rendering
+ *   state.ts      shared "run in progress" / cancel state
+ *   types.ts      shared TypeScript types
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key, Text } from "@earendil-works/pi-tui";
+import { registerChecksCommand } from "./command.js";
+import { PROGRESS_WIDGET_KEY } from "./progress.js";
+import { cancelReview, isReviewInProgress } from "./state.js";
+import type { Verdict } from "./types.js";
+
+const CANCEL_SHORTCUT = Key.ctrlShift("x");
+
+export default function shipdChecksExtension(pi: ExtensionAPI) {
+  pi.registerMessageRenderer<{
+    overall?: Verdict;
+    hasTestGaps?: boolean;
+    gapsCount?: number;
+    roleVerdicts?: Record<string, Verdict>;
+    showGaps?: boolean;
+  }>("shipd_checks_report", (message, _options, theme) => {
+    const details = message.details ?? {};
+    const colorVerdict = (verdict: Verdict) =>
+      verdict === "PASS" ? theme.fg("success", verdict) : theme.fg("error", verdict);
+    const segments: string[] = [];
+
+    // Whichever reviewer(s) just ran, even if `overall` is still incomplete
+    // (e.g. only --tests has run so far) — a partial run must always show its
+    // own PASS/FAIL, not just silently defer to the gap-count message.
+    if (details.roleVerdicts) {
+      for (const [role, verdict] of Object.entries(details.roleVerdicts)) {
+        segments.push(`${role}: ${colorVerdict(verdict)}`);
+      }
+    }
+
+    if (details.overall) {
+      const suffix = details.overall === "PASS" && details.hasTestGaps ? " (with test gaps)" : "";
+      segments.push(`Overall: ${colorVerdict(details.overall)}${suffix}`);
+    }
+
+    if (details.showGaps) {
+      const count = details.gapsCount ?? 0;
+      segments.push(
+        count > 0 ? theme.fg("warning", `${count} test gap(s) found`) : theme.fg("success", "no test gaps found"),
+      );
+    }
+
+    const text = segments.length > 0 ? segments.join("  ") : theme.fg("dim", "nothing to report");
+    return new Text(`${theme.bold("Checks: ")}${text}`, 0, 0);
+  });
+
+  pi.registerShortcut(CANCEL_SHORTCUT, {
+    description: "Cancel an in-progress /checks run",
+    handler: (ctx) => {
+      if (!isReviewInProgress()) return;
+      if (!cancelReview()) return;
+      ctx.ui.setWidget(PROGRESS_WIDGET_KEY, [`checks: cancelling (${CANCEL_SHORTCUT})...`]);
+      ctx.ui.notify("checks: cancelling...", "warning");
+    },
+  });
+
+  registerChecksCommand(pi);
+}

package/src/progress.ts

@@ -0,0 +1,11 @@
+/** Text-based progress bar rendered via ctx.ui.setWidget while a run is in flight. */
+
+export const PROGRESS_WIDGET_KEY = "checks_progress";
+const PROGRESS_BAR_WIDTH = 24;
+
+export function renderProgressLines(label: string, done: number, total: number): string[] {
+  const ratio = total > 0 ? Math.min(1, done / total) : 0;
+  const filled = Math.round(PROGRESS_BAR_WIDTH * ratio);
+  const bar = "█".repeat(filled) + "░".repeat(Math.max(0, PROGRESS_BAR_WIDTH - filled));
+  return [`checks: ${label} [${bar}] ${done}/${total}`];
+}