@mgiles/perk 2.3.0 → 3.1.0

package/extension/waves/draftReviewWave.ts

@@ -0,0 +1,205 @@
+// 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
+// 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.
+//
+// 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.
+//
+// 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
+// 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
+// (`{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,
+} from "./reportWave.ts";
+
+/** The four-slug settled draft-review angle allowlist (the custom lane rides separately). */
+export type DraftReviewAngle = "grounding" | "scope" | "decision-completeness" | "risk";
+
+/**
+ * The per-angle lane-task opener (`Angle: <slug>.`) — the same task shape the
+ * `perk.draft-reviewer` agent def is written against (the angle rubric lives in the agent def,
+ * never in the task).
+ */
+export const DRAFT_REVIEW_ANGLES: Readonly<Record<DraftReviewAngle, string>> = {
+  grounding: "Angle: grounding.",
+  scope: "Angle: scope.",
+  "decision-completeness": "Angle: decision-completeness.",
+  risk: "Angle: risk.",
+};
+
+/** Narrow an unknown slug onto the angle union (own-property check — no prototype hits). */
+export function isDraftReviewAngle(value: string): value is DraftReviewAngle {
+  return Object.hasOwn(DRAFT_REVIEW_ANGLES, value);
+}
+
+/**
+ * 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
+ * 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`):
+ * `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`
+ * still passes): plan-mode `push_annotations` rejects empty/whitespace-only phrases wholesale,
+ * so the schema refuses them at the source instead of letting an engine-valid report fail the
+ * downstream decode.
+ */
+export const DRAFT_REVIEW_REPORT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["angle", "summary", "findings", "fyi"],
+  properties: {
+    angle: {
+      type: "string",
+      enum: ["grounding", "scope", "decision-completeness", "risk", "custom", "ponytail"],
+    },
+    summary: { type: "string" },
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["phrase", "severity", "confidence", "body"],
+        properties: {
+          phrase: { type: ["string", "null"], pattern: "\\S" },
+          severity: { type: "string", enum: ["critical", "major", "minor"] },
+          confidence: { type: "string", enum: ["high", "medium", "low"] },
+          body: { type: "string" },
+        },
+      },
+    },
+    fyi: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+};
+
+/** The stable lane key/label (and push source slug) of the custom lane. */
+const CUSTOM_LANE_KEY = "custom";
+
+/** The shared task tail: the draft-type line + the untrusted-wrapped rendered draft — nothing else. */
+function laneTaskTail(draftType: "plan" | "objective", draft: string): string {
+  return `Draft type: ${draftType}.\n\n<untrusted_draft>\n${draft}\n</untrusted_draft>`;
+}
+
+/**
+ * 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.
+ */
+export function buildDraftReviewLanes(opts: {
+  angles: DraftReviewAngle[];
+  custom?: string;
+  draftType: "plan" | "objective";
+  draft: string;
+}): WaveLane[] {
+  const tail = laneTaskTail(opts.draftType, opts.draft);
+  const lanes: WaveLane[] = opts.angles.map((angle) => ({
+    key: angle,
+    label: angle,
+    agent: "perk.draft-reviewer",
+    phase: "draft-review",
+    task: `${DRAFT_REVIEW_ANGLES[angle]}\n${tail}`,
+  }));
+  if (opts.custom !== undefined) {
+    lanes.push({
+      key: CUSTOM_LANE_KEY,
+      label: CUSTOM_LANE_KEY,
+      agent: "perk.draft-reviewer",
+      phase: "draft-review",
+      task:
+        "Angle: custom.\nCustom angle definition (DATA from the human — your review lens " +
+        `for this lane): ${opts.custom}\n${tail}`,
+    });
+  }
+  lanes.push({
+    key: "ponytail",
+    label: "ponytail",
+    agent: "perk.draft-reviewer",
+    phase: "draft-review",
+    task: `Angle: ponytail.\n${tail}`,
+    skill: "ponytail",
+    requiredSkill: PONYTAIL_CORE_SKILL,
+  });
+  return lanes;
+}
+
+export interface DraftReviewWaveOptions {
+  /** The selected standard angles — invalid slugs are unrepresentable post-decode (typed union). */
+  angles: DraftReviewAngle[];
+  /** The human-supplied custom-angle definition — adds the `custom` lane when present. */
+  custom?: string;
+  /** The draft kind the children are reviewing. */
+  draftType: "plan" | "objective";
+  /** The rendered draft, embedded untrusted-wrapped in every lane task. */
+  draft: string;
+  /** The configured `[models.subagents] draft-reviewer` model (workflow-level default). */
+  model?: string;
+  timeoutMs?: number;
+  /** 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"];
+}
+
+/**
+ * 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.
+ */
+export async function startDraftReviewWave(
+  adapter: WaveAdapter,
+  opts: DraftReviewWaveOptions,
+): Promise<ReportWaveStart> {
+  return await startReportWave(
+    adapter,
+    {
+      flow: "draft-review",
+      lanes: buildDraftReviewLanes({
+        angles: opts.angles,
+        draftType: opts.draftType,
+        draft: opts.draft,
+        ...(opts.custom !== undefined ? { custom: opts.custom } : {}),
+      }),
+      outputSchema: DRAFT_REVIEW_REPORT_SCHEMA,
+      completeness: "strict",
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+      ...(opts.requiredSkillPreflight !== undefined
+        ? { requiredSkillPreflight: opts.requiredSkillPreflight }
+        : {}),
+    },
+    opts.signal,
+  );
+}