@akagilnc/pi-workflow-roles 0.1.1751

package/src/public-cli/terminal.ts

@@ -0,0 +1,325 @@
+/**
+ * Terminal result: typed semantic regions for one admitted Role run (ADR 0052 / #106).
+ * Presentation may rearrange labels/order; only regions and typed facts are stable.
+ *
+ * Free-text cells are JSON-string encoded so legitimate newlines/tabs cannot forge
+ * extra rows or shift column boundaries (note / fix.summary / decision question / reason).
+ */
+import { renderPublicAkRoleCommand } from "./command-renderer.ts";
+import type { ComplianceAuditIncomplete } from "../compliance-transport.ts";
+import type { NavigatorPhase } from "../navigator-attendance.ts";
+
+/** Encode one free-text Terminal cell. JSON string form cannot embed raw tab/newline. */
+export function encodeTerminalField(value: string): string {
+  return JSON.stringify(value);
+}
+
+export type TerminalArtifactRef = {
+  kind: "report" | "evidence" | "error";
+  /** Openable local reference (path). Layout is private; the ref value is the contract. */
+  path: string;
+};
+
+/** Controlled post-admission failure classes (ADR 0052 / #107). */
+export type ControlledFailureCause =
+  | "activation"
+  | "provider"
+  | "session"
+  | "output"
+  | "timeout"
+  | "unrecognized";
+
+/** Public callable roles that currently produce Terminal outcomes. */
+export type TerminalRoleName =
+  | "judge"
+  | "coder"
+  | "fixer"
+  | "collector"
+  | "doctor"
+  | "reviewer"
+  | "merger";
+
+export type ResidualIncompleteTerminalOutcome = {
+  kind: "incomplete";
+  role: "merger" | "collector";
+  status: "incomplete";
+  decision: "no-usable-result";
+  candidate: unknown;
+  diagnostic: string;
+  acceptedReceipt: false;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+export type AuditIncompleteTerminalOutcome = {
+  kind: "audit_incomplete";
+  role: TerminalRoleName;
+  status: "audit-incomplete";
+  decision: "no-usable-decision";
+  /** The original role submission arguments, retained independently. */
+  roleCandidate: unknown;
+  /** The malformed auditor candidate and observation retained by compliance transport. */
+  audit: ComplianceAuditIncomplete;
+  acceptedReceipt: false;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+/** JSON-safe public stand-in for an omitted tool-call `arguments` member. */
+export const JSON_SAFE_UNDEFINED_ARGUMENT = Object.freeze({
+  kind: "json-safe-sentinel",
+  type: "undefined",
+} as const);
+
+export type AuditIncompleteResidual = {
+  readonly roleCandidate: unknown;
+  readonly audit: ComplianceAuditIncomplete;
+  readonly acceptedReceipt: false;
+};
+
+export function jsonSafeComplianceCandidate(value: unknown): unknown {
+  return value === undefined ? JSON_SAFE_UNDEFINED_ARGUMENT : value;
+}
+
+export type TerminalRoleOutcome =
+  | {
+      kind: "accepted";
+      role: TerminalRoleName;
+      status: string;
+      /** Few decisive facts drawn from the typed receipt. */
+      decisiveFacts: Readonly<Record<string, unknown>>;
+    }
+  | {
+      kind: "audit_escalation";
+      role: TerminalRoleName;
+      status: "audit_escalation";
+      decisiveFacts: Readonly<Record<string, unknown>>;
+    }
+  | AuditIncompleteTerminalOutcome
+  | ResidualIncompleteTerminalOutcome
+  | {
+      kind: "failure";
+      role: TerminalRoleName;
+      /** Typed cause class — never a fabricated role Receipt status. */
+      cause: ControlledFailureCause;
+      /** Original diagnostic identity retained for the caller. */
+      diagnostic: string;
+      decisiveFacts: Readonly<Record<string, unknown>>;
+      /** Retained audit residual when publication itself failed. */
+      auditResidual?: AuditIncompleteResidual;
+    };
+
+/** Lawful typed terminal results exit zero (including audit_escalation). */
+export function isLawfulTypedTerminalOutcome(
+  outcome: TerminalRoleOutcome,
+): boolean {
+  return outcome.kind === "accepted" || outcome.kind === "audit_escalation";
+}
+
+export function exitCodeForTerminalOutcome(
+  outcome: TerminalRoleOutcome,
+): number {
+  return isLawfulTypedTerminalOutcome(outcome) ? 0 : 1;
+}
+
+export function buildResidualIncompleteTerminalOutcome(input: {
+  role: "merger" | "collector";
+  candidate: unknown;
+  diagnostic: string;
+}): ResidualIncompleteTerminalOutcome {
+  return {
+    kind: "incomplete",
+    role: input.role,
+    status: "incomplete",
+    decision: "no-usable-result",
+    candidate: input.candidate,
+    diagnostic: input.diagnostic,
+    acceptedReceipt: false,
+    decisiveFacts: {
+      decision: "no-usable-result",
+      candidate: input.candidate,
+      diagnostic: input.diagnostic,
+      acceptedReceipt: false,
+    },
+  };
+}
+
+export function buildAuditIncompleteTerminalOutcome(input: {
+  role: TerminalRoleName;
+  roleCandidate: unknown;
+  audit: ComplianceAuditIncomplete;
+}): AuditIncompleteTerminalOutcome {
+  const roleCandidate = jsonSafeComplianceCandidate(input.roleCandidate);
+  const audit = {
+    ...input.audit,
+    candidate: jsonSafeComplianceCandidate(input.audit.candidate),
+  };
+  return {
+    kind: "audit_incomplete",
+    role: input.role,
+    status: "audit-incomplete",
+    decision: "no-usable-decision",
+    roleCandidate,
+    audit,
+    acceptedReceipt: false,
+    decisiveFacts: {
+      decision: "no-usable-decision",
+      roleCandidate,
+      auditCandidate: audit.candidate,
+      auditObservation: audit.observation,
+      observationKind: audit.observation.kind,
+      observationType: audit.observation.kind === "non-object-arguments"
+        ? audit.observation.type
+        : audit.observation.kind === "object-status-unreadable"
+          ? audit.observation.status
+          : audit.observation.kind === "missing-subject"
+            ? audit.observation.subject
+            : audit.observation.kind,
+      acceptedReceipt: false,
+    },
+  };
+}
+
+export type TerminalNavigatorFact =
+  | {
+      disposition: "recommendation";
+      next: { role: string; phase: NavigatorPhase };
+      reason: string;
+      /** Registry-rendered public command — never model prose. */
+      command: string;
+      route?: ReadonlyArray<{ role: string; phase: NavigatorPhase }>;
+      advisoryDiagnostic?: string;
+    }
+  | {
+      disposition: "no-advice";
+      advisoryDiagnostic?: string;
+    }
+  | {
+      disposition: "unavailable";
+      source: string;
+      reason: string;
+      advisoryDiagnostic?: string;
+    };
+
+/** Present only when a controlled failure is v1-resumable (typed HTTP 429). */
+export type TerminalResume = {
+  /** Complete public command; run ID is revealed only here. */
+  readonly command: string;
+};
+
+/** Public free-text stand-in when an exact Role run ID is stripped outside resume.command. */
+export const REDACTED_RUN_ID_TOKEN = "[run-id]" as const;
+
+/**
+ * Remove an exact Role run ID from untrusted free text at the public Terminal boundary.
+ * Private durable artifacts keep the original bytes; only resume.command may disclose it.
+ */
+export function redactExactRunId(text: string, runId: string): string {
+  if (runId.length === 0) return text;
+  if (!text.includes(runId)) return text;
+  return text.split(runId).join(REDACTED_RUN_ID_TOKEN);
+}
+
+/**
+ * One admitted Role run's typed Terminal aggregate.
+ * Resumable failures carry `resume` and must not re-disclose the run ID via
+ * top-level `runId` or public artifact path components — only `resume.command`.
+ */
+export type TerminalResult = {
+  roleOutcome: TerminalRoleOutcome;
+  navigator: TerminalNavigatorFact;
+  artifacts: readonly TerminalArtifactRef[];
+} & (
+  | {
+      /** Resumable failure: run ID appears only inside resume.command. */
+      resume: TerminalResume;
+      runId?: undefined;
+    }
+  | {
+      runId: string;
+      resume?: undefined;
+    }
+);
+
+/**
+ * Build a recommendation navigator fact. Command is always registry-rendered;
+ * any model-authored command string is ignored.
+ */
+export function recommendationNavigatorFact(input: {
+  next: { role: string; phase: NavigatorPhase };
+  reason: string;
+  route?: ReadonlyArray<{ role: string; phase: NavigatorPhase }>;
+  advisoryDiagnostic?: string;
+  /** Ignored — retained only so callers can pass through raw attendance without using it. */
+  modelCommand?: string;
+}): TerminalNavigatorFact {
+  void input.modelCommand;
+  const command = renderPublicAkRoleCommand(input.next);
+  if (command === undefined) {
+    return {
+      disposition: "unavailable",
+      source: "unknown",
+      reason: `recommended role is not a public callable seat: ${input.next.role}`,
+    };
+  }
+  return {
+    disposition: "recommendation",
+    next: input.next,
+    reason: input.reason,
+    command,
+    ...(input.route === undefined ? {} : { route: input.route }),
+    ...(input.advisoryDiagnostic === undefined ? {} : { advisoryDiagnostic: input.advisoryDiagnostic }),
+  };
+}
+
+/**
+ * Present one Terminal result for humans. Labels, row order, wording, and layout
+ * are unfrozen (ADR 0052). Machine consumers and tests must read typed
+ * TerminalResult / settlement owners — never bite this presentation.
+ */
+export function formatTerminalResult(result: TerminalResult): string {
+  const lines: string[] = [];
+  lines.push("role\toutcome\tstatus");
+  const outcomeStatus =
+    result.roleOutcome.kind === "failure"
+      ? result.roleOutcome.cause
+      : result.roleOutcome.status;
+  lines.push(
+    `${result.roleOutcome.role}\t${result.roleOutcome.kind}\t${encodeTerminalField(outcomeStatus)}`,
+  );
+  if (result.roleOutcome.kind === "failure") {
+    lines.push(
+      `diagnostic\t${encodeTerminalField(result.roleOutcome.diagnostic)}`,
+    );
+  }
+  const facts = result.roleOutcome.decisiveFacts;
+  for (const [key, value] of Object.entries(facts)) {
+    if (value === undefined) continue;
+    const rendered =
+      typeof value === "string" ? value : JSON.stringify(value);
+    lines.push(`fact\t${encodeTerminalField(key)}\t${encodeTerminalField(rendered)}`);
+  }
+  lines.push(`navigator\t${result.navigator.disposition}`);
+  if (result.navigator.advisoryDiagnostic !== undefined) {
+    lines.push(`navigator-advisory\t${encodeTerminalField(result.navigator.advisoryDiagnostic)}`);
+  }
+  if (result.navigator.disposition === "recommendation") {
+    lines.push(
+      `next\t${result.navigator.next.role}\t${result.navigator.next.phase ?? "none"}`,
+    );
+    lines.push(`reason\t${encodeTerminalField(result.navigator.reason)}`);
+    lines.push(`command\t${encodeTerminalField(result.navigator.command)}`);
+  } else if (result.navigator.disposition === "unavailable") {
+    lines.push(
+      `unavailable\t${result.navigator.source}\t${encodeTerminalField(result.navigator.reason)}`,
+    );
+  }
+  for (const artifact of result.artifacts) {
+    lines.push(`artifact\t${artifact.kind}\t${encodeTerminalField(artifact.path)}`);
+  }
+  if (result.resume !== undefined) {
+    // Resumable failure: run ID is revealed only inside the complete resume command.
+    lines.push(`resume\t${encodeTerminalField(result.resume.command)}`);
+  } else if (result.runId !== undefined) {
+    lines.push(`run\t${encodeTerminalField(result.runId)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/public-command-renderer.ts

@@ -0,0 +1,43 @@
+/**
+ * Registry-owned public command renderer (ADR 0052 / #106).
+ * Typed role/phase facts → public `ak-role` command text.
+ * Model-authored command prose is never executable output.
+ *
+ * Low-level shared owner: Navigator attendance and the public CLI both import
+ * this module so dist/navigator-attendance.js keeps a complete dependency closure
+ * without duplicating renderer logic into the preparation graph or bin bundle.
+ */
+import {
+  PACKAGED_ROLE_REGISTRY,
+  type PackagedRole,
+} from "./packaged-role-registry.ts";
+
+export type PublicCommandPhase = "plan" | "apply" | null;
+
+export type PublicCommandTarget = {
+  role: string;
+  phase: PublicCommandPhase;
+};
+
+const PUBLIC_CALLABLE_ROLES = new Set<string>(
+  PACKAGED_ROLE_REGISTRY.map((entry) => entry.role),
+);
+
+/**
+ * Render one public ak-role invocation from typed next-role facts.
+ * Returns undefined when the target is not a public callable role.
+ */
+export function renderPublicAkRoleCommand(
+  target: PublicCommandTarget,
+): string | undefined {
+  if (!PUBLIC_CALLABLE_ROLES.has(target.role)) return undefined;
+  const role = target.role as PackagedRole;
+  if (target.phase === null || target.phase === undefined) {
+    return `ak-role ${role}`;
+  }
+  // Coder/Fixer expose plan|apply; other roles have no public phase selector.
+  if (role === "coder" || role === "fixer") {
+    return `ak-role ${role} ${target.phase}`;
+  }
+  return `ak-role ${role}`;
+}

package/src/reviewer-agent.ts

@@ -0,0 +1,94 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isReviewerPromptText, type ReviewerPromptText } from "./reviewer-prompt-identity.ts";
+import type { AcceptedReviewerExecution } from "./reviewer-dispatch.ts";
+import type { ReviewerTargetSnapshot, ReviewerWorkspaceDisposition, ReviewerFailureClassification, ReviewerUsage } from "./reviewer-execution-ledger.ts";
+import { executeReviewerChild } from "./reviewer-child-executor.ts";
+import { createReviewerWorkspaceOwner, type ReviewerWorkspaceFaultPoint } from "./reviewer-workspace.ts";
+import { normalizeReviewerFailureDiagnostic } from "./reviewer-failure-diagnostic.ts";
+
+type ReviewerLegRunResultCommon = Readonly<{ target: ReviewerTargetSnapshot; prompt: ReviewerPromptText; workspaceDisposition: ReviewerWorkspaceDisposition }>;
+export type ReviewerSuccessfulLegRunResult = ReviewerLegRunResultCommon & Readonly<{ status: "successful"; report: string; usage: ReviewerUsage; failure?: never }>;
+export type ReviewerFailedLegRunResult = ReviewerLegRunResultCommon & Readonly<{ status: "failed"; failure: ReviewerFailureClassification; diagnostic: string; cause?: unknown; report?: never; usage?: never }>;
+export type ReviewerLegRunResult = ReviewerSuccessfulLegRunResult | ReviewerFailedLegRunResult;
+type Envelope<L> = Readonly<{ identity: string; target: ReviewerTargetSnapshot; legs: Readonly<L> }>;
+export type ReviewerDispatchRunResult = Envelope<{ standards: ReviewerLegRunResult; spec?: never }> | Envelope<{ standards: ReviewerLegRunResult; spec: ReviewerLegRunResult }>;
+export type ReviewerSuccessfulDispatchRunResult = Envelope<{ standards: ReviewerSuccessfulLegRunResult; spec?: never }> | Envelope<{ standards: ReviewerSuccessfulLegRunResult; spec: ReviewerSuccessfulLegRunResult }>;
+function reviewerDispatchFailureMessage(outcome: ReviewerDispatchRunResult): string {
+  const diagnostics = [...new Set(
+    Object.values(outcome.legs)
+      .filter((leg): leg is ReviewerFailedLegRunResult => leg?.status === "failed")
+      .map((leg) => leg.diagnostic.trim())
+      .filter((diagnostic) => diagnostic.length > 0),
+  )];
+  if (diagnostics.length === 0) return "Reviewer dispatch execution failed";
+  return diagnostics.length === 1 ? diagnostics[0]! : diagnostics.join("; ");
+}
+export class ReviewerDispatchExecutionError extends Error {
+  constructor(readonly outcome: ReviewerDispatchRunResult) {
+    super(reviewerDispatchFailureMessage(outcome));
+    this.name = "ReviewerDispatchExecutionError";
+  }
+}
+export type ReviewerAgentRunner = { run(dispatch: AcceptedReviewerExecution, options: { context: ExtensionContext; signal?: AbortSignal }): Promise<ReviewerSuccessfulDispatchRunResult>; shutdown(): Promise<void> };
+export type ReviewerAgentFaultPoint = ReviewerWorkspaceFaultPoint;
+type Dependencies = Readonly<{
+  fault?(operation: ReviewerAgentFaultPoint): void;
+  /** When set, child credential/config scratch is created under this parent so cleanup proofs stay process-local. */
+  credentialScratchParent?: string;
+}>;
+function classify(error: unknown, signal?: AbortSignal): ReviewerFailureClassification { if (signal?.aborted) return "cancelled"; if (typeof error === "object" && error !== null && "reviewerFailure" in error) return (error as { reviewerFailure: ReviewerFailureClassification }).reviewerFailure; return "unknown"; }
+function failed(error: unknown, target: ReviewerTargetSnapshot, prompt: ReviewerPromptText, signal?: AbortSignal, retained?: string): ReviewerFailedLegRunResult {
+  const attached = typeof error === "object" && error !== null ? error as { targetSnapshot?: ReviewerTargetSnapshot; workspaceDisposition?: ReviewerWorkspaceDisposition } : {};
+  const failure = classify(error, signal);
+  const diagnostic = normalizeReviewerFailureDiagnostic(error, failure);
+  return Object.freeze({
+    status: "failed",
+    failure,
+    diagnostic,
+    cause: error,
+    target: attached.targetSnapshot ?? target,
+    prompt,
+    workspaceDisposition: retained === undefined ? attached.workspaceDisposition ?? "not-created" : { retained },
+  });
+}
+export function createReviewerAgentRunner(dependencies: Dependencies = {}): ReviewerAgentRunner {
+  const workspaceOwner = createReviewerWorkspaceOwner(dependencies.fault === undefined ? {} : { fault: dependencies.fault }); let accepted = false;
+  return {
+    async run(dispatch, options) {
+      if (dispatch.recipe !== "reviewer-common-bundle-v1" || dispatch.legs.length < 1 || dispatch.legs.length > 2 || dispatch.legs[0]?.axis !== "standards" || (dispatch.legs.length === 2 && dispatch.legs[1]?.axis !== "spec")) throw new Error("Invalid accepted Reviewer dispatch cardinality or axes");
+      if (accepted) throw new Error("Reviewer runner accepts exactly one dispatch"); accepted = true;
+      for (const leg of dispatch.legs) if (!isReviewerPromptText(leg.prompt)) throw new Error("Accepted Reviewer prompt evidence mismatch");
+      let batch;
+      try { batch = await workspaceOwner.prepare(dispatch.targetSnapshot, dispatch.legs.map(l => l.axis), options.signal); }
+      catch (error) {
+        const prepared = typeof error === "object" && error !== null && "preparedWorkspaces" in error ? (error as { preparedWorkspaces?: readonly { axis: string; path: string }[] }).preparedWorkspaces ?? [] : [];
+        const failedIndex = prepared.length;
+        const legs = Object.fromEntries(dispatch.legs.map((leg, index) => [leg.axis, failed(error, dispatch.targetSnapshot, leg.prompt, options.signal, index < failedIndex ? prepared[index]!.path : undefined)]));
+        // Siblings not yet attempted have no workspace; do not borrow the failed leg's retained path.
+        for (let index = failedIndex + 1; index < dispatch.legs.length; index += 1) { const axis = dispatch.legs[index]!.axis; legs[axis] = Object.freeze({ ...legs[axis]!, workspaceDisposition: "not-created" }); }
+        const target = Object.values(legs)[0]!.target; throw new ReviewerDispatchExecutionError(Object.freeze({ identity: dispatch.identity, target, legs: Object.freeze(legs) }) as ReviewerDispatchRunResult);
+      }
+      const settled = await Promise.allSettled(batch.workspaces.map(async workspace => {
+        const leg = dispatch.legs.find(candidate => candidate.axis === workspace.axis)!;
+        try {
+          const child = await executeReviewerChild(workspace.path, leg, options.context, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(dependencies.credentialScratchParent === undefined
+              ? {}
+              : { credentialScratchParent: dependencies.credentialScratchParent }),
+          });
+          const disposition = await workspaceOwner.dispose(workspace);
+          return [leg.axis, Object.freeze({ status: "successful" as const, report: child.report, usage: child.usage, target: batch.target, prompt: child.prompt, workspaceDisposition: disposition })] as const;
+        } catch (error) {
+          // Failed legs retain their workspace for the durable failure evidence and caller cleanup.
+          return [leg.axis, failed(error, batch.target, leg.prompt, options.signal, workspace.path)] as const;
+        }
+      }));
+      const pairs = settled.map(item => item.status === "fulfilled" ? item.value : (() => { throw item.reason; })());
+      const outcome = Object.freeze({ identity: dispatch.identity, target: batch.target, legs: Object.freeze(Object.fromEntries(pairs)) }) as ReviewerDispatchRunResult;
+      if (Object.values(outcome.legs).some(leg => leg?.status === "failed")) throw new ReviewerDispatchExecutionError(outcome);
+      return outcome as ReviewerSuccessfulDispatchRunResult;
+    },
+    shutdown: () => workspaceOwner.shutdown(),
+  };
+}

package/src/reviewer-auditor.ts

@@ -0,0 +1,53 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { auditorRunDirectory } from "./auditor-dossier-tool.ts";
+import { loadAuditorSoul } from "./auditor-soul.ts";
+import {
+  createComplianceDecisionTool,
+  runComplianceAudit,
+  type ComplianceCompletion,
+  type ComplianceDecision,
+} from "./compliance-transport.ts";
+import {
+  readReviewerAuditSubjects,
+  resolveAuditDossier,
+  toAuditIncomplete,
+} from "./dossier-resolution.ts";
+
+export const REVIEWER_AUDIT_TOOL_NAME = "ak_reviewer_audit_decision";
+
+export type ReviewerAuditOptions = {
+  context: ExtensionContext;
+  signal?: AbortSignal;
+};
+
+const reviewerDecisionTool = createComplianceDecisionTool(
+  REVIEWER_AUDIT_TOOL_NAME,
+  "Decide whether the Reviewer receipt demonstrably followed its method and boundaries from the dossier.",
+);
+
+/**
+ * Reviewer auditor: zero hand-delivered materials / no readiness projection.
+ * Candidate receipt must already be on the parent-session books.
+ */
+export function createPiReviewerAuditor(
+  runCompletion?: ComplianceCompletion,
+): (options: ReviewerAuditOptions) => Promise<ComplianceDecision> {
+  return async (options) => {
+    const dossier = resolveAuditDossier();
+    if (dossier.status === "incomplete") return toAuditIncomplete(dossier.observation);
+    const subjects = readReviewerAuditSubjects(options.context);
+    if (subjects.status === "incomplete") return toAuditIncomplete(subjects.observation);
+
+    return runComplianceAudit({
+      tool: reviewerDecisionTool,
+      systemPrompt: await loadAuditorSoul("reviewer"),
+      roleLabel: "Reviewer compliance audit",
+      invalidDecisionLabel: "invalid reviewer audit decision",
+      ...(runCompletion === undefined ? {} : { runCompletion }),
+      context: options.context,
+      ...(auditorRunDirectory(options.context) === undefined ? {} : { runDirectory: auditorRunDirectory(options.context) }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+  };
+}

package/src/reviewer-child-executor.ts

@@ -0,0 +1,31 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { executeEvidenceChild } from "./evidence-child-executor.ts";
+import type { AcceptedReviewerLeg } from "./reviewer-dispatch.ts";
+
+export type ReviewerChildExecuteOptions = Readonly<{
+  signal?: AbortSignal;
+  credentialScratchParent?: string;
+}>;
+
+/**
+ * Single conversion at the Reviewer adapter boundary: shared child classifications
+ * become Reviewer failure classifications without a second error taxonomy.
+ */
+export function projectSharedChildFailure(error: unknown): unknown {
+  if (typeof error === "object" && error !== null && "evidenceChildFailure" in error) {
+    const classification = (error as { evidenceChildFailure?: unknown }).evidenceChildFailure;
+    if (classification === "provider" || classification === "child") {
+      Object.assign(error, { reviewerFailure: classification });
+    }
+  }
+  return error;
+}
+
+/** Reviewer policy adapter over the shared evidence-child lifecycle seam. */
+export async function executeReviewerChild(workspace: string, leg: AcceptedReviewerLeg, context: ExtensionContext, options: ReviewerChildExecuteOptions = {}) {
+  try {
+    return await executeEvidenceChild(workspace, leg.prompt, context, options);
+  } catch (error) {
+    throw projectSharedChildFailure(error);
+  }
+}