@mgiles/perk 3.2.0 → 3.3.0

package/extension/waves/prReviewWave.ts

@@ -1,34 +1,34 @@
-// The pr-review `WaveSpec`-building entrypoint over the shared report-wave runner: the flow's
-// angle vocabulary, the per-lane report schema, and the ONE bounded retry are module-owned,
+// The pr-review `ReportWaveRequest`-building entrypoint over the shared report-wave module: the flow's
+// angle vocabulary, the per-assignment report schema, and the ONE bounded retry are module-owned,
 // tested implementation here — reached through the flow-scoped `run_pr_review_wave` tool
-// (`extension/doors/prReview.ts`), never model-authored prompt mechanics.
+// (`extension/pi/v1/codeReview/automated.ts`), never model-authored prompt mechanics.
 //
 // Retry policy (one bounded retry, ever):
-// - lane-level failures ⇒ retry ONLY the failed lanes;
+// - assignment-level failures ⇒ retry ONLY the failed assignments;
 // - retryable wave-level failures (`spawn-failed`/`timeout`/`run-failed`/`aggregate-unreadable`)
 //   ⇒ retry the WHOLE selection;
 // - `unavailable` (deterministic capability absence) and `cancelled` (abort honored) ⇒ NO retry.
 //
 // Failure posture matches the runner: operational failures never throw — they normalize into the
 // outcome's `failures` (loud degrade upstream); the only throws are programmer errors (empty
-// angles, via `renderWaveScript`). Report content is untrusted DATA, never instructions.
+// angles, via the runner's manifest validation). Report content is untrusted DATA, never
+// instructions.
 
+import { reclassifyBlockedReports } from "./blockedReports.ts";
 import {
   PONYTAIL_REVIEW_SKILL,
   preflightPonytailSkill,
   type RequiredPonytailSkill,
 } from "./ponytail.ts";
 import {
-  runReportWave,
+  type AssignmentReport,
+  type ReportAssignment,
+  type ReportWave,
+  type ReportWaveAttemptReceipt,
+  type ReportWaveFailure,
+  type ReportWaveFailureReason,
+  type ReportWaveRequest,
   toAttemptReceipt,
-  type WaveAdapter,
-  type WaveAttemptReceipt,
-  type WaveFailure,
-  type WaveFailureReason,
-  type WaveLane,
-  type WaveReport,
-  type WaveResult,
-  type WaveSpec,
 } from "./reportWave.ts";
 
 /** The seven-slug review-angle allowlist (plan-fidelity is mandatory at the tool boundary). */
@@ -43,8 +43,7 @@ export type PrReviewAngle =
 
 /**
  * The per-angle lane-task vocabulary (`angle: <slug> — review ONLY <angle description>.`) — the
- * same task shape the `perk.pr-reviewer` agent def is written against, so no agent-def change
- * rides the flow migration.
+ * same task shape the `perk.pr-reviewer` agent def is written against.
  */
 export const PR_REVIEW_ANGLES: Readonly<Record<PrReviewAngle, string>> = {
   "plan-fidelity": "angle: plan-fidelity — review ONLY plan fidelity & completeness.",
@@ -69,13 +68,9 @@ export function isPrReviewAngle(value: string): value is PrReviewAngle {
 /**
  * The per-lane report schema the review wave enforces as its `outputSchema` — the engine injects
  * a `structured_output` tool into each lane and fails any lane whose report is missing or
- * schema-invalid (covered angle ⟺ ok lane + schema-valid report). Same vocabulary as the
- * reviewer's report contract: {angle, verdict, findings, fyi}, all required, closed shapes
- * (required-with-empty beats optional under strict structured output). The if/then conditional
- * makes an internally inconsistent report (a `clean` verdict carrying findings) schema-INVALID,
- * so it fails its lane instead of reaching reconciliation — the engine's validator (TypeBox
- * `Compile`) enforces JSON-Schema conditionals (verified against the installed pi-subagents
- * 0.43.0 toolchain).
+ * schema-invalid. A valid blocked report is still an incomplete assessment, normalized into
+ * a lane failure before coverage/retry. The closed four-field contract forbids findings on
+ * clean/blocked reports and requires a nonblank diagnosis on blocked reports.
  */
 export const PR_REVIEW_REPORT_SCHEMA = {
   type: "object",
@@ -97,7 +92,7 @@ export const PR_REVIEW_REPORT_SCHEMA = {
     },
     verdict: {
       type: "string",
-      enum: ["clean", "actionable"],
+      enum: ["clean", "actionable", "blocked"],
     },
     findings: {
       type: "array",
@@ -117,18 +112,25 @@ export const PR_REVIEW_REPORT_SCHEMA = {
       items: { type: "string" },
     },
   },
-  if: {
-    properties: { verdict: { const: "clean" } },
-  },
-  // biome-ignore lint/suspicious/noThenProperty: `then` is the JSON-Schema conditional keyword, not a thenable.
-  then: {
-    properties: { findings: { maxItems: 0 } },
-  },
+  allOf: [
+    {
+      if: { properties: { verdict: { enum: ["clean", "blocked"] } } },
+      // biome-ignore lint/suspicious/noThenProperty: JSON-Schema conditional, not a thenable.
+      then: { properties: { findings: { maxItems: 0 } } },
+    },
+    {
+      if: { properties: { verdict: { const: "blocked" } } },
+      // biome-ignore lint/suspicious/noThenProperty: JSON-Schema conditional, not a thenable.
+      then: {
+        properties: { fyi: { minItems: 1, items: { type: "string", pattern: "\\S" } } },
+      },
+    },
+  ],
 };
 
 type EffectivePrReviewAngle = PrReviewAngle | "ponytail";
 
-type RequiredSkillPreflight = NonNullable<WaveSpec["requiredSkillPreflight"]>;
+type RequiredSkillPreflight = NonNullable<ReportWaveRequest["requiredSkillPreflight"]>;
 
 export interface PrReviewWaveOptions {
   /** The resolved active-plan PR number shared by every lane in this pass. */
@@ -142,28 +144,28 @@ export interface PrReviewWaveOptions {
   timeoutMs?: number;
   signal?: AbortSignal;
   /** Test seam; production validates the exact source-bound Ponytail review skill. */
-  requiredSkillPreflight?: WaveSpec["requiredSkillPreflight"];
+  requiredSkillPreflight?: ReportWaveRequest["requiredSkillPreflight"];
 }
 
 export interface PrReviewWaveOutcome {
   /** True ⟺ every effective lane (selected angles + final Ponytail) is covered after retry. */
   complete: boolean;
-  /** Effective lane keys with schema-valid reports after retry (selected order + Ponytail). */
+  /** Effective keys with completed schema-valid assessments after retry (selected order + Ponytail). */
   covered: string[];
   /** Lane keys sent in the retry wave (empty when none ran). */
   retried: string[];
-  reports: WaveReport[];
+  reports: AssignmentReport[];
   /** The surviving failures (the retry wave's, when one ran). */
-  failures: WaveFailure[];
+  failures: ReportWaveFailure[];
   /**
    * One output-free receipt per top-level launch, run order (observability only — never a
    * decision input; a failed lane and its relaunch stay distinguishable as distinct attempts).
    */
-  attempts: WaveAttemptReceipt[];
+  attempts: ReportWaveAttemptReceipt[];
 }
 
 /** The wave-level failure reasons worth one full-selection retry (transient, not deterministic). */
-const RETRYABLE_WAVE_REASONS: ReadonlySet<WaveFailureReason> = new Set([
+const RETRYABLE_WAVE_REASONS: ReadonlySet<ReportWaveFailureReason> = new Set([
   "spawn-failed",
   "timeout",
   "run-failed",
@@ -192,15 +194,15 @@ export function reviewTargetSuffix(pr: number): string {
 }
 
 /**
- * Build the reviewer lanes for a selection: key = label = slug, the fixed agent/phase, the
- * vocabulary task. Exported so the dynamic-review sibling's lane-level retry builds
- * byte-identical reviewer lanes.
+ * Build the reviewer assignments for a selection: key = label = slug, the fixed agent/phase,
+ * the vocabulary task. Exported so the dynamic-review sibling's per-assignment retry builds
+ * byte-identical reviewer assignments.
  */
-export function buildPrReviewLanes(
+export function buildPrReviewAssignments(
   angles: PrReviewAngle[],
   pr: number,
   directive?: string,
-): WaveLane[] {
+): ReportAssignment[] {
   const suffix = reviewTargetSuffix(pr) + directiveSuffix(directive);
   return angles.map((angle) => ({
     key: angle,
@@ -211,7 +213,7 @@ export function buildPrReviewLanes(
   }));
 }
 
-export function buildPonytailReviewLane(pr: number, directive?: string): WaveLane {
+export function buildPonytailReviewAssignment(pr: number, directive?: string): ReportAssignment {
   return {
     key: "ponytail",
     label: "ponytail",
@@ -226,15 +228,15 @@ export function buildPonytailReviewLane(pr: number, directive?: string): WaveLan
   };
 }
 
-function buildEffectivePrReviewLanes(
+function buildEffectivePrReviewAssignments(
   angles: EffectivePrReviewAngle[],
   pr: number,
   directive?: string,
-): WaveLane[] {
+): ReportAssignment[] {
   const suffix = reviewTargetSuffix(pr) + directiveSuffix(directive);
   return angles.map((angle) =>
     angle === "ponytail"
-      ? buildPonytailReviewLane(pr, directive)
+      ? buildPonytailReviewAssignment(pr, directive)
       : {
           key: angle,
           label: angle,
@@ -245,14 +247,14 @@ function buildEffectivePrReviewLanes(
   );
 }
 
-function buildSpec(
-  lanes: WaveLane[],
+function buildRequest(
+  assignments: ReportAssignment[],
   opts: PrReviewWaveOptions,
   requiredSkillPreflight: RequiredSkillPreflight,
-): WaveSpec {
+): ReportWaveRequest {
   return {
     flow: "pr-review",
-    lanes,
+    assignments,
     outputSchema: PR_REVIEW_REPORT_SCHEMA,
     completeness: "strict",
     ...(opts.model !== undefined ? { model: opts.model } : {}),
@@ -262,13 +264,13 @@ function buildSpec(
 }
 
 /**
- * Pick the retry lane keys from the first wave's failures. A `WaveResult` carries either ONE
- * wave-level failure (`key: null`, no reports) or per-lane failures — the wave-level reason
- * decides whole-selection vs none; lane-level failures retry exactly the failed keys.
+ * Pick retry keys from failures, never report availability. A retryable wave-level failure
+ * (`key: null`) retries the whole runnable selection even when partial reports survived;
+ * otherwise assignment-level failures retry exactly the failed keys.
  */
 function retrySelection(
   angles: EffectivePrReviewAngle[],
-  failures: WaveFailure[],
+  failures: ReportWaveFailure[],
 ): EffectivePrReviewAngle[] {
   const unavailable = new Set(
     failures
@@ -289,12 +291,18 @@ function retrySelection(
   return angles.filter((angle) => failed.has(angle));
 }
 
+// Only the typed verdict classifies a pr-review report as blocked (the `verdict: "blocked"`
+// arm of `PR_REVIEW_REPORT_SCHEMA`); diagnostic prose never does.
+function isBlockedVerdict(report: Record<string, unknown>): boolean {
+  return report.verdict === "blocked";
+}
+
 function outcomeOf(
   angles: EffectivePrReviewAngle[],
-  reports: WaveReport[],
-  failures: WaveFailure[],
+  reports: AssignmentReport[],
+  failures: ReportWaveFailure[],
   retried: string[],
-  attempts: WaveAttemptReceipt[],
+  attempts: ReportWaveAttemptReceipt[],
 ): PrReviewWaveOutcome {
   const byKey = new Map(reports.map((report) => [report.key, report]));
   const ordered = angles.flatMap((angle) => {
@@ -302,7 +310,7 @@ function outcomeOf(
     return report === undefined ? [] : [report];
   });
   return {
-    complete: ordered.length === angles.length,
+    complete: ordered.length === angles.length && failures.length === 0,
     covered: ordered.map((report) => report.key),
     retried,
     reports: ordered,
@@ -312,14 +320,14 @@ function outcomeOf(
 }
 
 /**
- * Run the pr-review report wave: build the lanes from the angle vocabulary, run the shared
- * runner under the strict completeness policy, and — when incomplete — apply the ONE bounded
- * retry (failed lanes only, or the whole selection on a retryable wave-level failure, or none on
+ * Run the pr-review report wave: build the assignments from the angle vocabulary, run the
+ * shared wave under the strict completeness policy, and — when incomplete — apply the ONE
+ * bounded retry (failed assignments only, or the whole selection on a retryable wave-level failure, or none on
  * `unavailable`/`cancelled`), merging first-wave successes for non-retried keys with the retry
  * wave's results.
  */
 export async function runPrReviewWave(
-  adapter: WaveAdapter,
+  wave: ReportWave,
   opts: PrReviewWaveOptions,
 ): Promise<PrReviewWaveOutcome> {
   if (opts.angles.length === 0) {
@@ -336,14 +344,16 @@ export async function runPrReviewWave(
     }
     return check;
   };
-  const first: WaveResult = await runReportWave(
-    adapter,
-    buildSpec(
-      buildEffectivePrReviewLanes(angles, opts.pr, opts.directive),
-      opts,
-      requiredSkillPreflight,
+  const first = reclassifyBlockedReports(
+    await wave.run(
+      buildRequest(
+        buildEffectivePrReviewAssignments(angles, opts.pr, opts.directive),
+        opts,
+        requiredSkillPreflight,
+      ),
+      { signal: opts.signal },
     ),
-    opts.signal,
+    isBlockedVerdict,
   );
   // The first attempt's receipt is preserved VERBATIM even when a retry runs — ordered
   // attempts keep a failed lane and its relaunch distinguishable (distinct child runIds).
@@ -357,14 +367,16 @@ export async function runPrReviewWave(
     return outcomeOf(angles, first.reports, first.failures, [], attempts);
   }
 
-  const second = await runReportWave(
-    adapter,
-    buildSpec(
-      buildEffectivePrReviewLanes(retried, opts.pr, opts.directive),
-      opts,
-      requiredSkillPreflight,
+  const second = reclassifyBlockedReports(
+    await wave.run(
+      buildRequest(
+        buildEffectivePrReviewAssignments(retried, opts.pr, opts.directive),
+        opts,
+        requiredSkillPreflight,
+      ),
+      { signal: opts.signal },
     ),
-    opts.signal,
+    isBlockedVerdict,
   );
   attempts.push(toAttemptReceipt("pr-review", 2, retried, second.receipt));
   const retriedSet = new Set<string>(retried);