@mgiles/perk 3.0.0 → 3.2.0

package/extension/waves/harvestWave.ts

@@ -91,7 +91,7 @@ function stringOrNull(value: unknown): value is string | null {
  * The lexical doc-containment layer (pure): relative, POSIX-normalizes without escaping, and
  * stays under `docs/learned/`. Returns the human-readable violation, or null when contained.
  */
-function lexicalContainmentError(path: string): string | null {
+export function lexicalContainmentError(path: string): string | null {
   if (posix.isAbsolute(path) || isAbsolute(path)) {
     return "is absolute";
   }

package/extension/waves/ponytail.ts

@@ -0,0 +1,104 @@
+// The source-identity boundary for Perk's automatic Ponytail review lanes. Ponytail is installed
+// as an all-resource-disabled project package, so ordinary Pi sessions never discover any of its
+// resources. A review lane opts into exactly one skill through its agent's invocation-local
+// `skillPath`; this module preflights the exact project package + file before that lane can spawn.
+// A same-named project/user skill is never a fallback source.
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { parse as parseMiniYaml } from "../substrate/miniYaml.ts";
+
+export const PONYTAIL_PACKAGE_NAME = "@dietrichgebert/ponytail";
+export const PONYTAIL_PACKAGE_ROOT = ".pi/npm/node_modules/@dietrichgebert/ponytail";
+
+export type PonytailSkillName = "ponytail" | "ponytail-review";
+
+/** Non-serialized lane metadata: the exact package skill a lane requires. */
+export interface RequiredPonytailSkill {
+  skill: PonytailSkillName;
+  skillFile: string;
+}
+
+export const PONYTAIL_CORE_SKILL: RequiredPonytailSkill = {
+  skill: "ponytail",
+  skillFile: `${PONYTAIL_PACKAGE_ROOT}/skills/ponytail/SKILL.md`,
+};
+
+export const PONYTAIL_REVIEW_SKILL: RequiredPonytailSkill = {
+  skill: "ponytail-review",
+  skillFile: `${PONYTAIL_PACKAGE_ROOT}/skills/ponytail-review/SKILL.md`,
+};
+
+export type PonytailPreflight = { ok: true } | { ok: false; detail: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function frontmatter(text: string): Record<string, unknown> | null {
+  if (!text.startsWith("---\n")) return null;
+  const lines = text.split("\n");
+  const end = lines.findIndex((line, index) => index > 0 && line === "---");
+  if (end < 0) return null;
+
+  // Preflight needs only the one top-level `name` field. Parse that field through Perk's
+  // dependency-free YAML seam without widening the contract-file parser to every metadata shape
+  // an external skill may carry (notably folded description prose).
+  const nameLines = lines.slice(1, end).filter((line) => line.startsWith("name:"));
+  if (nameLines.length !== 1) return null;
+  try {
+    const parsed = parseMiniYaml(nameLines[0] ?? "");
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate one exact source-bound skill against the project install. The check is deliberately
+ * self-contained and fail-closed: package identity, `pi.skills`, exact file readability, and
+ * frontmatter name must all agree. Callers invoke it once per review pass and skip only the
+ * affected lane on failure.
+ */
+export async function preflightPonytailSkill(
+  requirement: RequiredPonytailSkill,
+  repoRoot = process.cwd(),
+): Promise<PonytailPreflight> {
+  const packageRoot = path.resolve(repoRoot, PONYTAIL_PACKAGE_ROOT);
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+  } catch {
+    return { ok: false, detail: "Ponytail package.json is missing, unreadable, or invalid JSON" };
+  }
+  if (!isRecord(manifest) || manifest.name !== PONYTAIL_PACKAGE_NAME) {
+    return {
+      ok: false,
+      detail: `Ponytail package identity does not match ${PONYTAIL_PACKAGE_NAME}`,
+    };
+  }
+  const pi = manifest.pi;
+  const advertised = isRecord(pi) ? pi.skills : undefined;
+  if (!Array.isArray(advertised) || !advertised.includes("./skills")) {
+    return { ok: false, detail: "Ponytail package.json does not advertise ./skills in pi.skills" };
+  }
+
+  let skillText: string;
+  try {
+    skillText = await readFile(path.resolve(repoRoot, requirement.skillFile), "utf8");
+  } catch {
+    return {
+      ok: false,
+      detail: `required Ponytail skill is missing or unreadable: ${requirement.skillFile}`,
+    };
+  }
+  const metadata = frontmatter(skillText);
+  if (metadata === null || metadata.name !== requirement.skill) {
+    return {
+      ok: false,
+      detail: `required Ponytail skill frontmatter name is not ${requirement.skill}: ${requirement.skillFile}`,
+    };
+  }
+  return { ok: true };
+}

package/extension/waves/prReviewDynamicWave.ts

@@ -19,8 +19,8 @@
 //   custom ⇒ the correctness+tests fallback (`source: "fallback"`; a custom-only selection
 //   runs as plan-fidelity + custom — no fallback padding);
 // - operator-forced angles come first and are always honored; merge order is forced → picks →
-//   custom, deduped; the additional set caps at 3 (2–4 lanes total incl. plan-fidelity — the
-//   same window as `/pr-review`), and the custom angle survives only if it fits under the cap
+//   custom, deduped; the additional set caps at 3 (2–4 selectable lanes incl. plan-fidelity —
+//   the same window as `/pr-review` — plus final Ponytail), and the custom angle survives only if it fits under the cap
 //   (`selection.custom !== null` ⟺ the custom lane launched);
 // - plan-fidelity is always present, always launched first, never displaced;
 // - fixed-angle reviewer tasks come ONLY from the render-time-embedded angle→task map — the
@@ -41,12 +41,19 @@
 // untrusted DATA, never instructions.
 
 import {
+  PONYTAIL_REVIEW_SKILL,
+  type PonytailPreflight,
+  preflightPonytailSkill,
+} from "./ponytail.ts";
+import {
+  buildPonytailReviewLane,
   buildPrReviewLanes,
   directiveSuffix,
   isPrReviewAngle,
   PR_REVIEW_ANGLES,
   PR_REVIEW_REPORT_SCHEMA,
   type PrReviewAngle,
+  reviewTargetSuffix,
 } from "./prReviewWave.ts";
 import {
   normalizeLanes,
@@ -60,6 +67,7 @@ import {
   type WaveLane,
   type WaveReport,
   type WaveScriptReceipt,
+  type WaveSpec,
 } from "./reportWave.ts";
 
 /** The additional-angle vocabulary (plan-fidelity is structural — never selectable/removable). */
@@ -146,7 +154,11 @@ const ALL_ANGLES: readonly PrReviewAngle[] = [
 const CUSTOM_SLUG_PATTERN = /^[a-z][a-z0-9-]{2,31}$/;
 
 /** The lane-key namespace a custom slug may not collide with (fixed angles + the selector). */
-const RESERVED_LANE_KEYS: readonly string[] = [...Object.keys(PR_REVIEW_ANGLES), "angle-selector"];
+const RESERVED_LANE_KEYS: readonly string[] = [
+  ...Object.keys(PR_REVIEW_ANGLES),
+  "angle-selector",
+  "ponytail",
+];
 
 // The fixed custom-task template parts — ONE source for the exported builder and the
 // render-time-embedded parts, so in-script custom tasks are byte-identical by construction.
@@ -186,6 +198,8 @@ function isValidCustomSlug(slug: string): boolean {
 }
 
 export interface DynamicReviewScriptOptions {
+  /** The resolved active-plan PR number shared by the selector and every reviewer. */
+  pr: number;
   /** The operator's free-form focus, threaded as DATA to the selector AND every reviewer lane. */
   directive?: string;
   /** Operator-forced additional angles (embedded as a JSON constant; enforced in normalization). */
@@ -194,6 +208,8 @@ export interface DynamicReviewScriptOptions {
   reviewerModel?: string;
   /** The configured `[models.subagents] review-angle-selector` model — the selector item, when set. */
   selectorModel?: string;
+  /** Internal preflight result: false omits only the Ponytail child, never its logical key. */
+  includePonytail?: boolean;
 }
 
 /**
@@ -201,7 +217,11 @@ export interface DynamicReviewScriptOptions {
  * rubric), plus — as DATA — the forced angles when present and the same uniform operator-focus
  * suffix `buildPrReviewLanes` appends to reviewer lanes.
  */
-function buildSelectorTask(forceAngles: AdditionalPrReviewAngle[], suffix: string): string {
+function buildSelectorTask(
+  pr: number,
+  forceAngles: AdditionalPrReviewAngle[],
+  suffix: string,
+): string {
   const forcedNote =
     forceAngles.length === 0
       ? ""
@@ -209,9 +229,10 @@ function buildSelectorTask(forceAngles: AdditionalPrReviewAngle[], suffix: strin
           ", ",
         )} — they will run regardless of your selection; recommend complementary coverage.`;
   return (
-    "Classify the active plan's PR for dynamic review-angle coverage: fetch the review context " +
-    "yourself (`perk pr review-context --json`), classify the change profile, and select the " +
-    "review angles per your agent instructions (they own the rubric). Your final action is ONE " +
+    `Classify active-plan PR #${pr} for dynamic review-angle coverage: fetch the review context ` +
+    `yourself only with \`perk pr review-context --expected-pr ${pr} --json\`, classify the ` +
+    "change profile, and select the review angles per your agent instructions (they own the " +
+    "rubric). Your final action is ONE " +
     "structured_output call." +
     forcedNote +
     suffix
@@ -232,12 +253,16 @@ function buildSelectorTask(forceAngles: AdditionalPrReviewAngle[], suffix: strin
 export function renderDynamicReviewScript(opts: DynamicReviewScriptOptions): string {
   // Byte-identical reviewer tasks to the static flow: the map is built by the SAME lane builder
   // (vocabulary + the uniform directive suffix) over all seven angles.
-  const lanes = buildPrReviewLanes([...ALL_ANGLES], opts.directive);
-  const tasks = Object.fromEntries(lanes.map((lane) => [lane.key, lane.task]));
+  const lanes = buildPrReviewLanes([...ALL_ANGLES], opts.pr, opts.directive);
+  const ponytailLane = buildPonytailReviewLane(opts.pr, opts.directive);
+  const tasks = Object.fromEntries([
+    ...lanes.map((lane) => [lane.key, lane.task]),
+    [ponytailLane.key, ponytailLane.task],
+  ]);
   const suffix = directiveSuffix(opts.directive);
   const selectorItem = {
     agent: "perk.review-angle-selector",
-    task: buildSelectorTask(opts.forceAngles, suffix),
+    task: buildSelectorTask(opts.pr, opts.forceAngles, suffix),
     outputSchema: REVIEW_ANGLE_SELECTOR_SCHEMA,
     ...(opts.selectorModel !== undefined ? { model: opts.selectorModel } : {}),
     label: "angle-selector",
@@ -247,11 +272,13 @@ export function renderDynamicReviewScript(opts: DynamicReviewScriptOptions): str
     `const TASKS = ${JSON.stringify(tasks, null, 2)};`,
     `const FORCED = ${JSON.stringify(opts.forceAngles)};`,
     `const REVIEWER_MODEL = ${JSON.stringify(opts.reviewerModel ?? null)};`,
+    `const PONYTAIL_ENABLED = ${JSON.stringify(opts.includePonytail !== false)};`,
     `const ALLOWLIST_ADDITIONAL = ${JSON.stringify(DYNAMIC_ADDITIONAL_ANGLES)};`,
     `const FALLBACK_ANGLES = ${JSON.stringify(DYNAMIC_FALLBACK_ANGLES)};`,
     `const RESERVED = ${JSON.stringify(RESERVED_LANE_KEYS)};`,
     `const REPORT_SCHEMA = ${JSON.stringify(PR_REVIEW_REPORT_SCHEMA)};`,
     `const CUSTOM_TASK_PARTS = ${JSON.stringify([CUSTOM_TASK_PREFIX, CUSTOM_TASK_MID])};`,
+    `const TARGET_SUFFIX = ${JSON.stringify(reviewTargetSuffix(opts.pr))};`,
     `const DIRECTIVE_SUFFIX = ${JSON.stringify(suffix)};`,
     `const CUSTOM_SLUG_RE = new RegExp(${JSON.stringify(CUSTOM_SLUG_PATTERN.source)});`,
     "const reviewerParams = (angle) => ({",
@@ -259,13 +286,14 @@ export function renderDynamicReviewScript(opts: DynamicReviewScriptOptions): str
     "  task: TASKS[angle],",
     "  label: angle,",
     '  phase: "review",',
+    '  ...(angle === "ponytail" ? { skill: "ponytail-review" } : {}),',
     "  ...(REVIEWER_MODEL === null ? {} : { model: REVIEWER_MODEL }),",
     "});",
     "// The ONE sanctioned custom lane: the validated scope enters through the fixed template",
     "// (scope-definition-only framing); the per-item schema locks the report's angle echo.",
     "const customParams = (slug, scope) => ({",
     '  agent: "perk.pr-reviewer",',
-    "  task: CUSTOM_TASK_PARTS[0] + slug + CUSTOM_TASK_PARTS[1] + scope + DIRECTIVE_SUFFIX,",
+    "  task: CUSTOM_TASK_PARTS[0] + slug + CUSTOM_TASK_PARTS[1] + scope + TARGET_SUFFIX + DIRECTIVE_SUFFIX,",
     "  label: slug,",
     '  phase: "review",',
     "  outputSchema: {",
@@ -278,8 +306,11 @@ export function renderDynamicReviewScript(opts: DynamicReviewScriptOptions): str
     "  (r) => ({ key, ok: r.ok === true, error: r.error ?? null, report: r.structuredOutput ?? null }),",
     "  (error) => ({ key, ok: false, error: error instanceof Error ? error.message : String(error), report: null }),",
     ");",
-    "// plan-fidelity launches FIRST and runs concurrently with the selector (held promise).",
+    "// Deterministic lanes launch before and independently of selector output (held promises).",
     'const planFidelity = laneOf("plan-fidelity", runs.run("plan-fidelity", reviewerParams("plan-fidelity")));',
+    "const ponytail = PONYTAIL_ENABLED",
+    '  ? laneOf("ponytail", runs.run("ponytail", reviewerParams("ponytail")))',
+    "  : null;",
     "let sel = null;",
     "let selectorError = null;",
     "try {",
@@ -338,11 +369,12 @@ export function renderDynamicReviewScript(opts: DynamicReviewScriptOptions): str
     "  await planFidelity,",
     "  ...reviewers.map(({ key, ok, error, structuredOutput }) =>",
     "    ({ key, ok, error: error ?? null, report: structuredOutput ?? null })),",
+    "  ...(ponytail === null ? [] : [await ponytail]),",
     "];",
     "return {",
     "  selection: {",
     "    source,",
-    '    effective: ["plan-fidelity", ...additional],',
+    '    effective: ["plan-fidelity", ...additional, "ponytail"],',
     "    forced: FORCED,",
     "    custom,",
     "    selector_ok: report !== null,",
@@ -357,7 +389,7 @@ export function renderDynamicReviewScript(opts: DynamicReviewScriptOptions): str
 /** The parent-facing selection metadata (observability for the dogfood — DATA only). */
 export interface DynamicSelection {
   source: "selector" | "fallback";
-  /** The effective lanes: plan-fidelity + ≤3 additional angles, launch order. */
+  /** The effective lanes: plan-fidelity + ≤3 additional angles + final Ponytail, launch order. */
   effective: string[];
   /** The operator-forced additional angles (echoed from the tool param). */
   forced: string[];
@@ -375,6 +407,8 @@ export interface DynamicSelection {
 }
 
 export interface PrReviewDynamicOptions {
+  /** The resolved active-plan PR number shared by the selector and every reviewer. */
+  pr: number;
   /** The operator's free-form focus, threaded as DATA to the selector and every reviewer lane. */
   directive?: string;
   /** Operator-forced additional angles (≤3; plan-fidelity is structural, never forced). */
@@ -385,6 +419,8 @@ export interface PrReviewDynamicOptions {
   selectorModel?: string;
   timeoutMs?: number;
   signal?: AbortSignal;
+  /** Test seam; production validates the exact source-bound Ponytail review skill. */
+  requiredSkillPreflight?: WaveSpec["requiredSkillPreflight"];
 }
 
 export interface PrReviewDynamicOutcome {
@@ -401,9 +437,9 @@ export interface PrReviewDynamicOutcome {
   selection: DynamicSelection | null;
   /**
    * One output-free receipt per top-level launch, run order (observability only — never a
-   * decision input). A dynamic launch's `requestedKeys` is the PRE-LAUNCH manifest
-   * (plan-fidelity + angle-selector) — the fan-out lanes appear as receipt children, never
-   * reconstructed into the manifest.
+   * decision input). A dynamic launch's `requestedKeys` is the pre-launch manifest
+   * (plan-fidelity + angle-selector + Ponytail); selector-dependent fan-out lanes appear only as
+   * receipt children, never reconstructed into that manifest.
    */
   attempts: WaveAttemptReceipt[];
 }
@@ -476,15 +512,18 @@ function parseDynamicValue(
   }
   // Re-validate the effective selection against the normalization guarantees.
   const isEffectiveKey = (slug: string): boolean =>
-    isPrReviewAngle(slug) || (custom !== null && slug === custom.slug);
+    isPrReviewAngle(slug) || slug === "ponytail" || (custom !== null && slug === custom.slug);
   if (!effective.every(isEffectiveKey)) {
     return `dynamic selection carries an out-of-allowlist effective angle (${effective.join(", ")})`;
   }
-  if (!effective.includes("plan-fidelity")) {
-    return "dynamic selection dropped the mandatory plan-fidelity lane";
+  if (effective[0] !== "plan-fidelity") {
+    return "dynamic selection dropped or displaced the mandatory plan-fidelity lane";
+  }
+  if (effective.at(-1) !== "ponytail") {
+    return "dynamic selection dropped or displaced the final Ponytail lane";
   }
-  if (effective.length > 4) {
-    return `dynamic selection exceeds the 4-lane cap (${effective.join(", ")})`;
+  if (effective.length > 5) {
+    return `dynamic selection exceeds the 5-lane effective cap (${effective.join(", ")})`;
   }
   if (new Set(effective).size !== effective.length) {
     return `dynamic selection carries duplicate effective angles (${effective.join(", ")})`;
@@ -507,7 +546,7 @@ function parseDynamicValue(
 }
 
 /** The pre-launch lane manifest of every dynamic script run (the fan-out is unknowable). */
-const DYNAMIC_REQUESTED_KEYS: readonly string[] = ["plan-fidelity", "angle-selector"];
+const DYNAMIC_REQUESTED_KEYS: readonly string[] = ["plan-fidelity", "angle-selector", "ponytail"];
 
 /**
  * Enrich receipt children's `agent` via the module's deterministic mapping (the dynamic
@@ -541,12 +580,15 @@ type DynamicRun =
 async function runDynamicOnce(
   adapter: WaveAdapter,
   opts: PrReviewDynamicOptions,
+  ponytailCheck: PonytailPreflight,
 ): Promise<DynamicRun> {
   const workflowScript = renderDynamicReviewScript({
+    pr: opts.pr,
     forceAngles: opts.forceAngles ?? [],
     ...(opts.directive !== undefined ? { directive: opts.directive } : {}),
     ...(opts.reviewerModel !== undefined ? { reviewerModel: opts.reviewerModel } : {}),
     ...(opts.selectorModel !== undefined ? { selectorModel: opts.selectorModel } : {}),
+    includePonytail: ponytailCheck.ok,
   });
   const run = await runWaveScript(
     adapter,
@@ -571,7 +613,17 @@ async function runDynamicOnce(
       receipt,
     };
   }
-  const { reports, failures } = normalizeLanes(parsed.selection.effective, parsed.lanes);
+  const runnableKeys = parsed.selection.effective.filter(
+    (key) => key !== "ponytail" || ponytailCheck.ok,
+  );
+  const { reports, failures } = normalizeLanes(runnableKeys, parsed.lanes);
+  if (!ponytailCheck.ok) {
+    failures.push({
+      key: "ponytail",
+      reason: "skill-unavailable",
+      detail: ponytailCheck.detail,
+    });
+  }
   return { kind: "parsed", selection: parsed.selection, reports, failures, receipt };
 }
 
@@ -609,9 +661,21 @@ function outcomeOf(
  */
 export async function runPrReviewDynamicWave(
   adapter: WaveAdapter,
-  opts: PrReviewDynamicOptions = {},
+  opts: PrReviewDynamicOptions,
 ): Promise<PrReviewDynamicOutcome> {
-  const first = await runDynamicOnce(adapter, opts);
+  const preflight = opts.requiredSkillPreflight ?? preflightPonytailSkill;
+  const ponytailCheck = await preflight(PONYTAIL_REVIEW_SKILL);
+  const skillFailures = (): WaveFailure[] =>
+    ponytailCheck.ok
+      ? []
+      : [
+          {
+            key: "ponytail",
+            reason: "skill-unavailable",
+            detail: ponytailCheck.detail,
+          },
+        ];
+  const first = await runDynamicOnce(adapter, opts, ponytailCheck);
   // Ordered attempts — the first attempt's receipt is preserved verbatim when a retry runs.
   const attempts = [
     toAttemptReceipt("pr-review-dynamic", 1, [...DYNAMIC_REQUESTED_KEYS], first.receipt),
@@ -619,22 +683,22 @@ export async function runPrReviewDynamicWave(
 
   if (first.kind === "wave-failure") {
     if (!RETRYABLE_WAVE_REASONS.has(first.failure.reason)) {
-      return outcomeOf(null, [], [first.failure], [], attempts);
+      return outcomeOf(null, [], [first.failure, ...skillFailures()], [], attempts);
     }
     // Retryable wave-level failure ⇒ ONE full dynamic re-run (fresh selector); its selection
     // supersedes. The re-run's outcome is final — never a second retry.
-    const second = await runDynamicOnce(adapter, opts);
+    const second = await runDynamicOnce(adapter, opts, ponytailCheck);
     attempts.push(
       toAttemptReceipt("pr-review-dynamic", 2, [...DYNAMIC_REQUESTED_KEYS], second.receipt),
     );
     if (second.kind === "wave-failure") {
-      return outcomeOf(null, [], [second.failure], [], attempts);
+      return outcomeOf(null, [], [second.failure, ...skillFailures()], [], attempts);
     }
     return outcomeOf(
       second.selection,
       second.reports,
       second.failures,
-      second.selection.effective,
+      second.selection.effective.filter((key) => key !== "ponytail" || ponytailCheck.ok),
       attempts,
     );
   }
@@ -647,16 +711,21 @@ export async function runPrReviewDynamicWave(
   // the custom lane via the fixed template + its per-lane report schema); the selector is never
   // re-run.
   const failedKeys = first.selection.effective.filter((key) =>
-    first.failures.some((failure) => failure.key === key),
+    first.failures.some((failure) => failure.key === key && failure.reason !== "skill-unavailable"),
   );
   const custom = first.selection.custom;
   const retryAngles = failedKeys.filter(isPrReviewAngle);
   const customRetry = custom !== null && failedKeys.includes(custom.slug) ? custom : null;
-  const retryKeys = [...retryAngles, ...(customRetry !== null ? [customRetry.slug] : [])];
+  const ponytailRetry = ponytailCheck.ok && failedKeys.includes("ponytail");
+  const retryKeys = [
+    ...retryAngles,
+    ...(customRetry !== null ? [customRetry.slug] : []),
+    ...(ponytailRetry ? ["ponytail"] : []),
+  ];
   if (retryKeys.length === 0) return firstOutcome;
 
   const retryLanes: WaveLane[] = [
-    ...buildPrReviewLanes(retryAngles, opts.directive),
+    ...buildPrReviewLanes(retryAngles, opts.pr, opts.directive),
     ...(customRetry !== null
       ? [
           {
@@ -666,11 +735,13 @@ export async function runPrReviewDynamicWave(
             phase: "review",
             task:
               buildCustomLaneTask(customRetry.slug, customRetry.scope) +
+              reviewTargetSuffix(opts.pr) +
               directiveSuffix(opts.directive),
             outputSchema: customReportSchema(customRetry.slug),
           },
         ]
       : []),
+    ...(ponytailRetry ? [buildPonytailReviewLane(opts.pr, opts.directive)] : []),
   ];
   const staticRetry = await runReportWave(
     adapter,
@@ -681,6 +752,7 @@ export async function runPrReviewDynamicWave(
       completeness: "strict",
       ...(opts.reviewerModel !== undefined ? { model: opts.reviewerModel } : {}),
       ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+      requiredSkillPreflight: async () => ponytailCheck,
     },
     opts.signal,
   );
@@ -692,5 +764,14 @@ export async function runPrReviewDynamicWave(
     ...first.reports.filter((report) => !retriedSet.has(report.key)),
     ...staticRetry.reports,
   ];
-  return outcomeOf(first.selection, merged, staticRetry.failures, retryKeys, attempts);
+  const carried = first.failures.filter(
+    (failure) => failure.reason === "skill-unavailable" && failure.key === "ponytail",
+  );
+  return outcomeOf(
+    first.selection,
+    merged,
+    [...staticRetry.failures, ...carried],
+    retryKeys,
+    attempts,
+  );
 }