@mgiles/perk 3.1.0 → 3.3.0

package/extension/waves/objectiveExplorerWave.ts

@@ -1,24 +1,25 @@
 // The objective-plan factory's OPTIONAL explore step as a per-flow wave entrypoint over the
-// shared report-wave runner: the ONE `perk.objective-explorer` lane as CODE. The explorer report
-// schema was previously a shared prompt include the parent model had to hand-transcribe onto a
-// borrowed `subagent` call (the same prompt-drift risk the /address classify step carried); this
-// module makes the schema and the lane/task composition module constants, delegating
-// spawn/timeout/aggregate mechanics to `runReportWave` under the `strict` completeness policy.
+// shared report-wave module: the ONE `perk.objective-explorer` assignment as CODE. The explorer
+// report schema was previously a shared prompt include the parent model had to hand-transcribe
+// onto a borrowed `subagent` call (the same prompt-drift risk the /address classify step
+// carried); this module makes the schema and the assignment/task composition module constants,
+// delegating
+// spawn/timeout/aggregate mechanics to `wave.run` under the `strict` completeness policy.
 // No retry — the flow's posture on failure is "explore directly instead" (guidance-owned).
 // `node`/`description`/`focus` are model-relayed and embedded in the code-owned task as
 // untrusted DATA; the report content is likewise untrusted DATA, never instructions.
 
-import { runReportWave, type WaveAdapter, type WaveResult } from "./reportWave.ts";
+import type { ReportWave, ReportWaveResult } from "./reportWave.ts";
 
-/** The flow name — feeds `WaveSpec.flow` AND the door's `toAttemptReceipt` call. */
+/** The flow name — feeds `ReportWaveRequest.flow` AND the door's `toAttemptReceipt` call. */
 export const OBJECTIVE_EXPLORER_FLOW = "objective-explorer";
 
-/** The single lane's stable key. */
-export const EXPLORE_LANE_KEY = "explore";
+/** The single assignment's stable key. */
+export const EXPLORE_ASSIGNMENT_KEY = "explore";
 
 /**
  * The explorer report schema (the workflow-level `outputSchema` — the engine injects a
- * `structured_output` tool and fails the lane on a missing/invalid report): closed shapes, all
+ * `structured_output` tool and fails the assignment on a missing/invalid report): closed shapes, all
  * six root keys required. Same vocabulary as the `perk.objective-explorer` agent def's report
  * contract (the def↔schema lockstep test).
  */
@@ -73,9 +74,9 @@ export interface ObjectiveExplorerWaveOptions {
 }
 
 /**
- * Compose the single lane's task text IN CODE (the prompt-drift-proof half of the migration):
- * the node id + the fenced untrusted node text, plus the optional focus. The agent def requires
- * the node id and a description of the work to reach the child.
+ * Compose the single assignment's task text IN CODE (prompt-drift-proof: task text composed in
+ * code, never a template): the node id + the fenced untrusted node text, plus the optional focus. The agent
+ * def requires the node id and a description of the work to reach the child.
  */
 export function explorerLaneTask(node: string, description: string, focus?: string): string {
   return [
@@ -89,22 +90,21 @@ export function explorerLaneTask(node: string, description: string, focus?: stri
 }
 
 /**
- * Run the objective-explorer wave: ONE fresh-context `perk.objective-explorer` lane over the
- * code-owned task, `strict` completeness, no retry, module-default timeout. Returns the runner's
- * `WaveResult` unchanged — the only projection lives in the tool.
+ * Run the objective-explorer wave: ONE fresh-context `perk.objective-explorer` assignment over
+ * the code-owned task, `strict` completeness, no retry, module-default timeout. Returns the
+ * wave's `ReportWaveResult` unchanged — the only projection lives in the tool.
  */
 export async function runObjectiveExplorerWave(
-  adapter: WaveAdapter,
+  wave: ReportWave,
   opts: ObjectiveExplorerWaveOptions,
-): Promise<WaveResult> {
-  return await runReportWave(
-    adapter,
+): Promise<ReportWaveResult> {
+  return await wave.run(
     {
       flow: OBJECTIVE_EXPLORER_FLOW,
-      lanes: [
+      assignments: [
         {
-          key: EXPLORE_LANE_KEY,
-          label: EXPLORE_LANE_KEY,
+          key: EXPLORE_ASSIGNMENT_KEY,
+          label: EXPLORE_ASSIGNMENT_KEY,
           agent: "perk.objective-explorer",
           phase: "objective-plan",
           task: explorerLaneTask(opts.node, opts.description, opts.focus),
@@ -115,6 +115,6 @@ export async function runObjectiveExplorerWave(
       ...(opts.model !== undefined ? { model: opts.model } : {}),
       ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
     },
-    opts.signal,
+    { signal: opts.signal },
   );
 }

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);