@mgiles/perk 3.2.0 → 3.3.0

package/extension/waves/blockedReports.ts

@@ -0,0 +1,59 @@
+// The shared "a schema-valid report is not necessarily a completed assessment" normalization
+// over a settled `ReportWaveResult`. Assessment completion is domain policy, not engine success:
+// the engine accepts any schema-valid report, so a reviewer that could not finish (context fetch
+// failed, a context file unreadable, the hunt stopped early) would otherwise count as COVERED
+// with empty findings — the exact failure mode this helper exists to prevent. Each flow supplies
+// its own typed predicate (`verdict: "blocked"` for pr-review, `blocked: true` for the
+// adversarial doors); the reclassification itself is flow-neutral and byte-identical across
+// callers. Diagnostic prose (`fyi`) is untrusted DATA preserved verbatim for the parent's
+// in-session diagnosis — never an instruction and never parsed for a decision.
+
+import type { AssignmentReport, ReportWaveFailure, ReportWaveResult } from "./reportWave.ts";
+
+/**
+ * Move every report the predicate marks blocked from `reports` into `failures` as an
+ * assignment-keyed `lane-failed` (the enclosing assignment key — never the report's own angle
+ * or prose — identifies the failure). Only non-null, non-array object reports are tested; the
+ * detail is exactly `"reviewer blocked:\n"` + the nonblank-trimmed `fyi` strings joined by
+ * `"\n"` (retained bytes, duplicates and order preserved), or the fixed fallback sentence.
+ * Existing failures precede newly blocked ones (report order); surviving report order and the
+ * receipt are preserved; `complete` requires incoming completeness AND no removed block.
+ */
+export function reclassifyBlockedReports(
+  result: ReportWaveResult,
+  isBlocked: (report: Record<string, unknown>) => boolean,
+): ReportWaveResult {
+  const reports: AssignmentReport[] = [];
+  const blocked: ReportWaveFailure[] = [];
+  for (const assignment of result.reports) {
+    const report = assignment.report;
+    if (
+      typeof report !== "object" ||
+      report === null ||
+      Array.isArray(report) ||
+      !isBlocked(report as Record<string, unknown>)
+    ) {
+      reports.push(assignment);
+      continue;
+    }
+    const notes =
+      "fyi" in report && Array.isArray(report.fyi)
+        ? report.fyi.filter(
+            (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
+          )
+        : [];
+    blocked.push({
+      key: assignment.key,
+      reason: "lane-failed",
+      detail:
+        "reviewer blocked:\n" +
+        (notes.length > 0 ? notes.join("\n") : "required review assessment could not complete"),
+    });
+  }
+  return {
+    complete: result.complete && blocked.length === 0,
+    reports,
+    failures: [...result.failures, ...blocked],
+    receipt: result.receipt,
+  };
+}

package/extension/waves/draftReviewWave.ts

@@ -1,36 +1,36 @@
-// The draft-review `WaveSpec`-building entrypoint over the shared report-wave runner — the
-// draft-review doors' (/plan-review-browser, /objective-review-browser) vocabulary as tested
+// The draft-review `ReportWaveRequest`-building entrypoint over the shared report-wave module —
+// the draft-review doors' (/plan-review-browser, /objective-review-browser) vocabulary as tested
 // code (sibling of `adversarialReviewWave.ts`): the four settled angles plus the custom lane,
 // the per-lane completion-report schema, and the lane/task composition are module-owned here,
-// launched NON-BLOCKING via `startReportWave` so the parent can return from the launch and hold
-// the model-held `subagent_wait` relay loop open while the children stream finding batches.
+// launched NON-BLOCKING via `wave.start` so the parent ends its turn after launch and relays
+// batches on native supervisor wakes before collecting on matching workflow completion.
 //
 // CONSUMED by the `/plan-review-browser` and `/objective-review-browser` doors via the
 // `start_draft_review_wave` / `collect_draft_review_wave` tool pair
-// (`extension/doors/draftReviewWaveTools.ts`) — `draftType` parameterizes the lane tasks.
+// (`extension/pi/v1/draftReviewWaveTools.ts`, over the door-primed context in
+// `extension/authoring/review/draftContext.ts`) — `draftType` parameterizes the lane tasks.
 //
 // ZERO retries — deliberate: the doors' contract is honest incompleteness surfaced to the human
 // during triage (an `ok: false` lane is reported, never papered over), so the pr-review
 // bounded-retry policy does not carry over.
 //
-// The surface handle (URL/port) is STRUCTURALLY UNREPRESENTABLE: `buildDraftReviewLanes` has no
-// URL parameter at all, so the children can never learn the review surface — enforced by
+// The surface handle (URL/port) is STRUCTURALLY UNREPRESENTABLE: `buildDraftReviewAssignments`
+// has no URL parameter at all, so the children can never learn the review surface — enforced by
 // construction, pinned by the suite. There is likewise NO `directive` parameter: the PR doors'
 // focus-note semantics deliberately do not carry over — the custom lane IS the draft doors'
 // user-input channel.
 //
-// The finding rows are deliberately identical to `annotationPush.ts`'s `PlanFinding` shape
+// The finding rows are deliberately identical to `pi/v1/providers/annotations.ts`'s `PlanFinding` shape
 // (`{phrase, severity, confidence, body}`), so draft reports feed `push_annotations` plan-mode
 // without reshaping; the `agents/draft-reviewer.md` def completes via the `structured_output`
 // tool this wave's `outputSchema` injects per lane.
 
 import { PONYTAIL_CORE_SKILL } from "./ponytail.ts";
-import {
-  type ReportWaveStart,
-  startReportWave,
-  type WaveAdapter,
-  type WaveLane,
-  type WaveSpec,
+import type {
+  ReportAssignment,
+  ReportWave,
+  ReportWaveRequest,
+  StartWaveResult,
 } from "./reportWave.ts";
 
 /** The four-slug settled draft-review angle allowlist (the custom lane rides separately). */
@@ -56,11 +56,11 @@ export function isDraftReviewAngle(value: string): value is DraftReviewAngle {
 /**
  * The per-lane completion-report schema the 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. Closed shapes, `{angle, summary, findings, fyi}` all required, and
+ * or schema-invalid. Closed shapes, `{angle, summary, findings, fyi, streamed}` all required, and
  * DELIBERATELY NO VERDICT FIELD — the human adjudicates every finding in the browser, so there
  * is no clean/actionable derivation to make consistent (the `ADVERSARIAL_REVIEW_REPORT_SCHEMA`
  * rationale). The `angle` enum includes `custom` (the custom lane echoes it). Finding rows are
- * the forward-bound plan-mode `PlanFinding` shape (`annotationPush.ts`'s `PLAN_FINDING_KEYS`):
+ * the forward-bound plan-mode `PlanFinding` shape (`pi/v1/providers/annotations.ts`'s `PLAN_FINDING_KEYS`):
  * `phrase` is required-nullable (the byte-exact draft span, or `null` for a global finding),
  * and the severity/confidence enums match the agent def's triage tags. The `phrase` string arm
  * requires a non-whitespace character (`pattern` applies only to string instances, so `null`
@@ -71,12 +71,13 @@ export function isDraftReviewAngle(value: string): value is DraftReviewAngle {
 export const DRAFT_REVIEW_REPORT_SCHEMA = {
   type: "object",
   additionalProperties: false,
-  required: ["angle", "summary", "findings", "fyi"],
+  required: ["angle", "summary", "findings", "fyi", "streamed"],
   properties: {
     angle: {
       type: "string",
       enum: ["grounding", "scope", "decision-completeness", "risk", "custom", "ponytail"],
     },
+    streamed: { type: "boolean" },
     summary: { type: "string" },
     findings: {
       type: "array",
@@ -108,22 +109,23 @@ function laneTaskTail(draftType: "plan" | "objective", draft: string): string {
 }
 
 /**
- * Build the reviewer lanes for a selection: key = label = slug, the fixed agent/phase, and a
- * task carrying the angle opener, the draft type, and the `<untrusted_draft>`-wrapped rendered
- * draft — AND NOTHING ELSE: no URL parameter exists (the surface handle is unrepresentable by
- * construction) and no `directive` parameter exists (the custom lane is the user-input channel).
- * When `custom` is supplied, one additional lane (key = label = `"custom"`) carries the
- * human-supplied angle definition as flagged DATA. The builder stays permissive about lane
- * count — angle-selection policy (2–3 picked + optional custom) is the door/tool's concern.
+ * Build the reviewer assignments for a selection: key = label = slug, the fixed agent/phase,
+ * and a task carrying the angle opener, the draft type, and the `<untrusted_draft>`-wrapped
+ * rendered draft — AND NOTHING ELSE: no URL parameter exists (the surface handle is
+ * unrepresentable by construction) and no `directive` parameter exists (the custom lane is the
+ * user-input channel). When `custom` is supplied, one additional assignment (key = label =
+ * `"custom"`) carries the human-supplied angle definition as flagged DATA. The builder stays
+ * permissive about assignment count — angle-selection policy (2–3 picked + optional custom) is
+ * the door/tool's concern.
  */
-export function buildDraftReviewLanes(opts: {
+export function buildDraftReviewAssignments(opts: {
   angles: DraftReviewAngle[];
   custom?: string;
   draftType: "plan" | "objective";
   draft: string;
-}): WaveLane[] {
+}): ReportAssignment[] {
   const tail = laneTaskTail(opts.draftType, opts.draft);
-  const lanes: WaveLane[] = opts.angles.map((angle) => ({
+  const assignments: ReportAssignment[] = opts.angles.map((angle) => ({
     key: angle,
     label: angle,
     agent: "perk.draft-reviewer",
@@ -131,7 +133,7 @@ export function buildDraftReviewLanes(opts: {
     task: `${DRAFT_REVIEW_ANGLES[angle]}\n${tail}`,
   }));
   if (opts.custom !== undefined) {
-    lanes.push({
+    assignments.push({
       key: CUSTOM_LANE_KEY,
       label: CUSTOM_LANE_KEY,
       agent: "perk.draft-reviewer",
@@ -141,7 +143,7 @@ export function buildDraftReviewLanes(opts: {
         `for this lane): ${opts.custom}\n${tail}`,
     });
   }
-  lanes.push({
+  assignments.push({
     key: "ponytail",
     label: "ponytail",
     agent: "perk.draft-reviewer",
@@ -150,7 +152,7 @@ export function buildDraftReviewLanes(opts: {
     skill: "ponytail",
     requiredSkill: PONYTAIL_CORE_SKILL,
   });
-  return lanes;
+  return assignments;
 }
 
 export interface DraftReviewWaveOptions {
@@ -168,25 +170,23 @@ export interface DraftReviewWaveOptions {
   /** Accepted for parity/tests only — the flow tool deliberately never threads its own signal. */
   signal?: AbortSignal;
   /** Test seam; production validates the exact source-bound Ponytail skill. */
-  requiredSkillPreflight?: WaveSpec["requiredSkillPreflight"];
+  requiredSkillPreflight?: ReportWaveRequest["requiredSkillPreflight"];
 }
 
 /**
- * Start the draft-review wave NON-BLOCKING (the streaming sibling): build the lanes from the
- * angle vocabulary and launch under the strict completeness policy — zero retries, so an
- * uncovered angle stays an honest, human-visible incompleteness. Returns the `startReportWave`
- * outcome: the run handle + never-rejecting `result` on success, or the normalized launch
- * failure.
+ * Start the draft-review wave NON-BLOCKING (the streaming split): build the assignments from
+ * the angle vocabulary and launch under the strict completeness policy — zero retries, so an
+ * uncovered angle stays an honest, human-visible incompleteness. Returns the `wave.start`
+ * outcome: the opaque ref + identity telemetry on success, or the normalized launch failure.
  */
 export async function startDraftReviewWave(
-  adapter: WaveAdapter,
+  wave: ReportWave,
   opts: DraftReviewWaveOptions,
-): Promise<ReportWaveStart> {
-  return await startReportWave(
-    adapter,
+): Promise<StartWaveResult> {
+  return await wave.start(
     {
       flow: "draft-review",
-      lanes: buildDraftReviewLanes({
+      assignments: buildDraftReviewAssignments({
         angles: opts.angles,
         draftType: opts.draftType,
         draft: opts.draft,
@@ -200,6 +200,6 @@ export async function startDraftReviewWave(
         ? { requiredSkillPreflight: opts.requiredSkillPreflight }
         : {}),
     },
-    opts.signal,
+    { signal: opts.signal },
   );
 }

package/extension/waves/laneIdentity.ts

@@ -0,0 +1,77 @@
+// The routing-token fence for report-wave lane identity. A ROUTING TOKEN is any producer-owned
+// identity rendered into a report child's task prose so the child can select its lane byte-exact
+// against the manifest, or echo it verbatim into its typed report — untrusted DATA, never an
+// instruction. Usually that is the SEMANTIC LANE ID (a harvest `<category>-<n>`, a dream cluster
+// id, an audit `expectation_id`); the audit wave additionally renders a second, pair-level token
+// — the `session_basename` the child echoes verbatim — which is a routing token but not a lane
+// id. Because a token must survive byte-exact matching against the manifest (and byte-exact echo
+// back), the fence is a REFUSAL rule, never an escaping rule: any escaping breaks selection by
+// construction, so an accepted token renders byte-identical and an unacceptable one is refused
+// (strict decoders) or degraded (the lenient audit planner) upstream, before any task is composed.
+//
+// Refused: the empty token; C0 controls U+0000–U+001F (a newline or carriage return would let a
+// producer-owned id read as further task instructions); DEL U+007F; C1 controls U+0080–U+009F
+// (NEL U+0085 included); the Unicode line/paragraph separators U+2028/U+2029; and the double
+// quote `"` (every task quotes the id in double quotes). Nothing else — spaces, `@`, `/`, `:`,
+// backticks, `${}`, astral characters and any length are admitted. There is deliberately NO
+// length bound: an oversized id fails as availability (a transport or model-context limit
+// surfacing as a wave-level failure), never as a silent success or an injection — the ceiling is
+// the transport's, not perk's. (contracts.md §8.35)
+//
+// The module has exactly two concerns: the routing-token FENCE above (`isRoutingToken` +
+// `renderRoutingToken`) and the fixed ORCHESTRATION-KEY format (`orchestrationKey`). The
+// vocabulary split (contracts.md §8.35): the SEMANTIC LANE ID is the producer-owned identity a
+// typed outcome reports; a ROUTING TOKEN is that identity (or a pair-level token) rendered into
+// task prose for byte-exact selection/echo; an ORCHESTRATION KEY is the opaque code-owned
+// `runs.all` item key a producer-lane wave gives one lane — never derived from producer bytes,
+// never surfaced as a lane identity.
+
+/**
+ * The refused character classes as one reviewable single-line statement. No `g`/`u` flags: every
+ * member is a single BMP code unit, so UTF-16 iteration is exact and astral characters (two
+ * surrogate code units, neither inside any listed range) can never match.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: refusing control characters is the point
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029"]/;
+
+/**
+ * The fence predicate: `true` iff `token` is non-empty and carries none of the refused classes.
+ * Decoders and planners call this to refuse or degrade an unsafe id BEFORE a lane is planned.
+ */
+export function isRoutingToken(token: string): boolean {
+  return token !== "" && !UNSAFE.test(token);
+}
+
+/**
+ * The asserting identity render helper for a `laneTask` interpolation site: returns `token`
+ * UNCHANGED when it passes the fence (the fenced form of an accepted token IS the raw token —
+ * every existing task-prose pin stays valid), otherwise throws. A throw here is a programmer
+ * error — a caller composed a task from a token it never fenced upstream — in the
+ * `validateAssignments` posture of `reportWave.ts`: never an operational failure arm, and
+ * unreachable on the production path (the strict decoders refuse, the audit planner degrades).
+ */
+export function renderRoutingToken(token: string): string {
+  if (!isRoutingToken(token)) {
+    throw new Error(
+      `renderRoutingToken: routing token ${JSON.stringify(token)} failed the fence — refuse or degrade it upstream`,
+    );
+  }
+  return token;
+}
+
+/**
+ * The ONE fixed orchestration-key format the producer-lane learn waves — harvest, audit, and
+ * the dream analyst tier, whose lanes are drawn from a producer-owned manifest — use for their
+ * `runs.all` item keys: `lane.<ordinal>` — opaque, code-owned, never derived from producer
+ * bytes. (Waves over a closed slug enum — the learn analyst angles, the dream reducer angles —
+ * key by the slug itself and never need it.) There is deliberately NO sanitizer: uniqueness
+ * lives in the caller's ordinal, and the semantic lane id rides `label` and the task text.
+ * `ordinal` is the caller's global 1-based counter in lane-plan order. The format is trivially inside `RUN_KEY_PATTERN`, so `validateAssignments`' run-key
+ * throw is unreachable for any planned lane. The key is never surfaced as a lane identity — it
+ * appears only in attempt receipts (`requestedKeys`, `children[*].key`) and failure `detail`s;
+ * typed outcomes join rows back to the SEMANTIC id through each flow's module-private lane plan,
+ * never by parsing keys.
+ */
+export function orchestrationKey(ordinal: number): string {
+  return `lane.${ordinal}`;
+}

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