@akagilnc/pi-workflow-roles 0.1.1751

package/src/reviewer-construction.ts

@@ -0,0 +1,137 @@
+import { sha256Hex } from "./sha256.ts";
+import { reviewerScopePrompt } from "./reviewer-scope-prompt.ts";
+import type { ReviewerPinnedTarget, ReviewerRange } from "./reviewer-pinned-git.ts";
+import type { ReviewerPromptText } from "./reviewer-prompt-identity.ts";
+
+export const REVIEWER_CONSTRUCTION_RECIPE = Object.freeze({
+  recipeId: "reviewer-common-bundle",
+  version: 1,
+  runtimeVersion: "1",
+  implementationSha256: sha256Hex("reviewer-common-bundle:v1:direct-text-prompts"),
+});
+export type ReviewerConstructionIdentity = typeof REVIEWER_CONSTRUCTION_RECIPE;
+export type ReviewerAxis = "standards" | "spec";
+
+export const REVIEWER_AXIS_OUTPUT_ADAPTER = Object.freeze({
+  adapterId: "reviewer-axis-output",
+  version: 1,
+  implementationSha256: sha256Hex("reviewer-axis-output:v1:single-axis-verbatim-report+standards-three-priorities"),
+});
+
+/** Typed Standards conclusion keys owned by reviewer construction (presentation labels are not the contract). */
+export const REVIEWER_STANDARDS_CONCLUSION_KEYS = Object.freeze([
+  "constitutionality",
+  "minimum-necessary-test-cost",
+  "complexity",
+] as const);
+export type ReviewerStandardsConclusionKey = (typeof REVIEWER_STANDARDS_CONCLUSION_KEYS)[number];
+
+const REVIEWER_STANDARDS_CONCLUSION_LABELS = Object.freeze({
+  constitutionality: "constitutionality",
+  "minimum-necessary-test-cost": "minimum-necessary test cost",
+  complexity: "complexity",
+} as const satisfies Record<ReviewerStandardsConclusionKey, string>);
+
+/** Axis-owned required/excluded Standards conclusions — machine contract for prompt rendering and tests. */
+export type ReviewerAxisOutputContract = Readonly<{
+  axis: ReviewerAxis;
+  requiredConclusions: readonly ReviewerStandardsConclusionKey[];
+  excludedConclusions: readonly ReviewerStandardsConclusionKey[];
+}>;
+
+export function reviewerAxisOutputContract(axis: ReviewerAxis): ReviewerAxisOutputContract {
+  const three = REVIEWER_STANDARDS_CONCLUSION_KEYS;
+  return axis === "standards"
+    ? Object.freeze({ axis, requiredConclusions: three, excludedConclusions: Object.freeze([]) })
+    : Object.freeze({ axis, requiredConclusions: Object.freeze([]), excludedConclusions: three });
+}
+
+function renderConclusionList(
+  keys: readonly ReviewerStandardsConclusionKey[],
+  finalJoiner: "and" | "or",
+): string {
+  const labels = keys.map((key) => REVIEWER_STANDARDS_CONCLUSION_LABELS[key]);
+  if (labels.length === 0) return "";
+  if (labels.length === 1) return labels[0]!;
+  if (labels.length === 2) return `${labels[0]} ${finalJoiner} ${labels[1]}`;
+  return `${labels.slice(0, -1).join(", ")}, ${finalJoiner} ${labels[labels.length - 1]}`;
+}
+
+function renderAxisPriorityClause(contract: ReviewerAxisOutputContract): string {
+  if (contract.requiredConclusions.length > 0) {
+    return `Inside that single Standards report, explicitly conclude on ${renderConclusionList(contract.requiredConclusions, "and")}; a finding or clear no-finding on each counts as a conclusion.`;
+  }
+  return `Do not discuss ${renderConclusionList(contract.excludedConclusions, "or")}; those are Standards judgements.`;
+}
+
+/** Package-owned mechanics layered over the unchanged canonical Skill semantics. */
+export function reviewerAxisMethodAdapter(axis: ReviewerAxis): string {
+  const contract = reviewerAxisOutputContract(axis);
+  const question = axis === "standards"
+    ? "Answer only the canonical Standards question, including its complete smell baseline and burden."
+    : "Answer only the canonical Spec question.";
+  return [
+    `Axis-Output-Adapter: ${REVIEWER_AXIS_OUTPUT_ADAPTER.adapterId}@${REVIEWER_AXIS_OUTPUT_ADAPTER.version}:${axis}`,
+    "The complete canonical Skill text below remains authoritative semantic input.",
+    "For this already-isolated leg, this package adapter supersedes that Skill's dual-agent orchestration, dual-axis aggregation, and dual-section presentation mechanics.",
+    question,
+    `Emit one substantive ${axis === "standards" ? "Standards" : "Spec"} report. Incidental cross-axis content, headings, and finding-count annotations are presentation matters, not defects.`,
+    renderAxisPriorityClause(contract),
+    "Before making any substantive claim, actually use the canonical Skill and fixed range facts; a citation without reading those facts is not evidence.",
+    "Independently acquire issue, authority, and context; do not treat caller prose as controlling authority or as the Spec source.",
+    "You may use any supplied common fact, including facts relevant to the other axis; access and citation do not change the assigned question.",
+    "The returned report is the complete output envelope and its UTF-8 bytes are preserved verbatim; no heading parser, sanitizer, section splitter, rewrite, aggregation, or replacement leg follows.",
+  ].join("\n");
+}
+
+export type ConstructedReviewerLeg = Readonly<{ axis: "standards" | "spec"; prompt: ReviewerPromptText }>;
+export type ConstructedReviewerDispatch = Readonly<{
+  identity: string;
+  recipe: "reviewer-common-bundle-v1";
+  input: Readonly<{
+    canonicalSkill: ReviewerPromptText;
+    construction: ReviewerConstructionIdentity;
+  }>;
+  targetSnapshot: ReviewerPinnedTarget;
+  range: ReviewerRange;
+  legs: readonly ConstructedReviewerLeg[];
+}>;
+
+/** Deterministic compiler: fixed target/range plus packaged Skill in, dispatch text out. */
+export function constructReviewerDispatch(input: {
+  identity: string;
+  canonicalSkill: string;
+  target: ReviewerPinnedTarget;
+  range: ReviewerRange;
+  reviewScopeKeys?: readonly string[];
+}): ConstructedReviewerDispatch {
+  const common = [
+    `Target: ${input.range.target}`,
+    `Base: ${input.range.base}`,
+    `Diff: ${input.range.diffCommand}`,
+    reviewerScopePrompt(input.reviewScopeKeys),
+    `Recipe: ${REVIEWER_CONSTRUCTION_RECIPE.recipeId}@${REVIEWER_CONSTRUCTION_RECIPE.version}`,
+    "Canonical-Skill:",
+    input.canonicalSkill,
+    "Fixed-Range:",
+    JSON.stringify(input.range, null, 2),
+  ].join("\n");
+  const axes = [{ axis: "standards" as const }, { axis: "spec" as const }];
+  const legs = axes.map((x) =>
+    Object.freeze({
+      axis: x.axis,
+      prompt: `${common}\n${reviewerAxisMethodAdapter(x.axis)}\n`,
+    }),
+  );
+  return Object.freeze({
+    identity: input.identity,
+    recipe: "reviewer-common-bundle-v1",
+    input: Object.freeze({
+      canonicalSkill: input.canonicalSkill,
+      construction: REVIEWER_CONSTRUCTION_RECIPE,
+    }),
+    targetSnapshot: input.target,
+    range: input.range,
+    legs: Object.freeze(legs),
+  });
+}

package/src/reviewer-dispatch.ts

@@ -0,0 +1,94 @@
+import { sameReviewerPinnedTarget } from "./reviewer-git-snapshot.ts";
+import { immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget } from "./reviewer-pinned-git.ts";
+export { createReviewerPinnedGitReader, immutableReviewerPin, type ReviewerPinnedGitReader, type ReviewerPinnedTarget, type ReviewerRange } from "./reviewer-pinned-git.ts";
+import { isReviewerPromptText, sameReviewerPromptText, type ReviewerPromptText } from "./reviewer-prompt-identity.ts";
+import { sha256Hex } from "./sha256.ts";
+import { constructReviewerDispatch, type ConstructedReviewerDispatch } from "./reviewer-construction.ts";
+import { ReviewerCorrectablePreflightError } from "./reviewer-preflight-error.ts";
+export { sha256Hex } from "./sha256.ts";
+export { isReviewerPromptText as isReviewerPromptIdentity, sameReviewerPromptText as sameReviewerPromptIdentity, type ReviewerPromptText as ReviewerPromptIdentity } from "./reviewer-prompt-identity.ts";
+
+export type AcceptedReviewerLeg = ConstructedReviewerDispatch["legs"][number];
+export type AcceptedReviewerDispatch = ConstructedReviewerDispatch;
+export type AcceptedReviewerExecution = Readonly<{
+  identity: string;
+  recipe: "reviewer-common-bundle-v1";
+  targetSnapshot: ReviewerPinnedTarget;
+  legs: readonly AcceptedReviewerLeg[];
+}>;
+export const REVIEWER_PREFLIGHT_VIOLATIONS = ["base-invalid", "range-invalid", "prompt-identity-invalid", "target-drift"] as const;
+export type ReviewerPreflightViolation = (typeof REVIEWER_PREFLIGHT_VIOLATIONS)[number];
+export type ReviewerDispatchResult =
+  | Readonly<{ status: "rejected"; identity: string; violations: readonly ReviewerPreflightViolation[]; diagnostic: string }>
+  | Readonly<{ status: "accepted"; dispatch: AcceptedReviewerDispatch; results: unknown }>;
+export type ReviewerDecisionEvidence =
+  | Readonly<{ disposition: "rejected"; identity: string; violations: readonly ReviewerPreflightViolation[]; started: false }>
+  | Readonly<{ disposition: "accepted"; identity: string; dispatch: AcceptedReviewerDispatch }>;
+type DispatcherDependencies = Readonly<{
+  canonicalSkill: string;
+  reader: ReviewerPinnedGitReader;
+  reviewScopeKeys?: readonly string[];
+  run(execution: AcceptedReviewerExecution, invocation: unknown): Promise<unknown>;
+  decisionEvidence?(decision: ReviewerDecisionEvidence): void;
+}>;
+export class ReviewerPreflightError extends Error {
+  constructor(readonly code: ReviewerPreflightViolation, readonly diagnostic = `${code} constraint failed`) {
+    super(`${code}: ${diagnostic}`);
+  }
+}
+export function toReviewerExecution(dispatch: AcceptedReviewerDispatch): AcceptedReviewerExecution {
+  return Object.freeze({
+    identity: dispatch.identity,
+    recipe: dispatch.recipe,
+    targetSnapshot: immutableReviewerPin(dispatch.targetSnapshot),
+    legs: Object.freeze(dispatch.legs.map((l) => Object.freeze({ axis: l.axis, prompt: l.prompt }))),
+  });
+}
+const preflight = (error: unknown): ReviewerPreflightError | undefined => {
+  if (error instanceof ReviewerPreflightError) return error;
+  if (error instanceof ReviewerCorrectablePreflightError) {
+    return new ReviewerPreflightError(error.code as ReviewerPreflightViolation, error.diagnostic);
+  }
+  return undefined;
+};
+export function createReviewerDispatcher(d: DispatcherDependencies) {
+  const target = immutableReviewerPin(d.reader.pin);
+  let started = false;
+  return Object.freeze({
+    async dispatch(baseRevision: string, invocation?: unknown): Promise<ReviewerDispatchResult> {
+      if (started) throw new Error("Reviewer fixed dispatch can start exactly once");
+      const identity = sha256Hex(JSON.stringify({
+        baseRevision,
+        target: target.targetHead,
+        canonicalSkill: sha256Hex(d.canonicalSkill),
+      }));
+      let dispatch: AcceptedReviewerDispatch;
+      try {
+        const base = await d.reader.resolve(baseRevision);
+        const range = await d.reader.range(base);
+        dispatch = constructReviewerDispatch({
+          identity,
+          canonicalSkill: d.canonicalSkill,
+          target,
+          range,
+          ...(d.reviewScopeKeys === undefined ? {} : { reviewScopeKeys: d.reviewScopeKeys }),
+        });
+        if (!sameReviewerPinnedTarget(await d.reader.snapshot(), target)) {
+          throw new ReviewerPreflightError("target-drift", "pinned target snapshot changed before child execution");
+        }
+      } catch (error) {
+        const p = preflight(error);
+        if (!p) throw error;
+        d.decisionEvidence?.(Object.freeze({ disposition: "rejected", identity, violations: Object.freeze([p.code]), started: false }));
+        return Object.freeze({ status: "rejected", identity, violations: Object.freeze([p.code]), diagnostic: p.diagnostic });
+      }
+      started = true;
+      d.decisionEvidence?.(Object.freeze({ disposition: "accepted", identity, dispatch }));
+      const results = await d.run(toReviewerExecution(dispatch), invocation);
+      return Object.freeze({ status: "accepted", dispatch, results });
+    },
+  });
+}
+
+export type { ReviewerPromptText };
+export { isReviewerPromptText, sameReviewerPromptText };

package/src/reviewer-execution-ledger.ts

@@ -0,0 +1,206 @@
+import { sameReviewerPinnedTarget } from "./reviewer-git-snapshot.ts";
+import { isReviewerPromptText, sameReviewerPromptText, type ReviewerPromptText } from "./reviewer-prompt-identity.ts";
+import type { ReviewerDispatchRunResult } from "./reviewer-agent.ts";
+import {
+  REVIEWER_PREFLIGHT_VIOLATIONS,
+  type ReviewerPreflightViolation,
+  type ReviewerPinnedTarget,
+  type AcceptedReviewerDispatch,
+} from "./reviewer-dispatch.ts";
+
+export type ReviewerUsage = Readonly<{
+  input: number; output: number; cacheRead: number; cacheWrite: number;
+  cacheWrite1h?: number; reasoning?: number; totalTokens: number;
+  cost: Readonly<{ input: number; output: number; cacheRead: number; cacheWrite: number; total: number }>;
+}>;
+export type ReviewerTargetSnapshot = ReviewerPinnedTarget;
+export type ReviewerWorkspaceDisposition = "deleted" | "not-created" | Readonly<{ retained: string }>;
+export type ReviewerFailureClassification = "cancelled" | "provider" | "snapshot" | "workspace" | "child" | "unknown";
+
+export type ReviewerCompiledLegEvidence = AcceptedReviewerDispatch["legs"][number];
+export type ReviewerAcceptedEvidence = Readonly<
+  Omit<AcceptedReviewerDispatch, "targetSnapshot"> & {
+    target: AcceptedReviewerDispatch["targetSnapshot"];
+  }
+>;
+export function projectAcceptedDispatch(dispatch: AcceptedReviewerDispatch): ReviewerEvidenceEvent {
+  return {
+    source: "reviewer-dispatch", type: "accepted", identity: dispatch.identity,
+    recipe: dispatch.recipe, input: dispatch.input, target: dispatch.targetSnapshot,
+    range: dispatch.range, legs: dispatch.legs,
+  };
+}
+
+type ReviewerLegResultEvidenceCommon = Readonly<{
+  dispatchIdentity: string;
+  axis: "standards" | "spec";
+  prompt: ReviewerPromptText;
+  target: ReviewerPinnedTarget;
+  workspaceDisposition: ReviewerWorkspaceDisposition;
+}>;
+export type ReviewerLegResultEvidence = ReviewerLegResultEvidenceCommon & (
+  | Readonly<{ status: "successful"; report: string; usage: ReviewerUsage; failure?: never }>
+  | Readonly<{ status: "failed"; failure: ReviewerFailureClassification; diagnostic: string; report?: never; usage?: never }>
+);
+export type ReviewerEvidenceEvent =
+  | (Readonly<{ source: "reviewer-dispatch"; type: "rejected"; identity: string; violations: readonly ReviewerPreflightViolation[]; started: false }>)
+  | Readonly<{ source: "reviewer-dispatch"; type: "closed-attempt"; identity: string; reason: "acceptance-closed"; started: false }>
+  | (Readonly<{ source: "reviewer-dispatch"; type: "accepted" }> & ReviewerAcceptedEvidence)
+  | Readonly<{ source: "reviewer-agent"; type: "dispatch-started"; dispatchIdentity: string; cardinality: 1 | 2 }>
+  | (Readonly<{ source: "reviewer-agent"; type: "leg-settled" }> & ReviewerLegResultEvidence)
+  | Readonly<{ source: "reviewer-runtime"; type: "fatal"; diagnostics: string; cause: unknown; targetSnapshot?: ReviewerTargetSnapshot; workspaceDisposition?: ReviewerWorkspaceDisposition }>;
+
+export type ReviewerExecutionRecord = Readonly<{
+  rejections: readonly Readonly<{ identity: string; violations: readonly ReviewerPreflightViolation[]; started: false }>[];
+  closedAttempts?: readonly Readonly<{ identity: string; reason: "acceptance-closed"; started: false }>[];
+  accepted?: ReviewerAcceptedEvidence;
+  started?: Readonly<{ dispatchIdentity: string; cardinality: 1 | 2 }>;
+  results: Readonly<Partial<Record<"standards" | "spec", ReviewerLegResultEvidence>>>;
+}>;
+export type ReviewerExecutionLedger = Readonly<{
+  append(event: ReviewerEvidenceEvent): void;
+  recordInfrastructureFailure<T>(error: T): T;
+  recordForAudit(status: "completed" | "refused"): ReviewerExecutionRecord;
+}>;
+
+export function projectReviewerDispatchOutcome(
+  ledger: ReviewerExecutionLedger,
+  dispatch: AcceptedReviewerDispatch,
+  result: ReviewerDispatchRunResult,
+): void {
+  if (result.identity !== dispatch.identity) throw new Error("Reviewer runner identity does not match accepted dispatch");
+  if (!sameReviewerPinnedTarget(result.target, dispatch.targetSnapshot)) throw new Error("Reviewer runner target does not match accepted pinned target");
+  const expectedAxes = dispatch.legs.map(({ axis }) => axis).sort();
+  const actualAxes = Object.keys(result.legs).sort();
+  if (actualAxes.length !== expectedAxes.length || actualAxes.some((axis, index) => axis !== expectedAxes[index])) {
+    throw new Error(`Reviewer runner result axes do not match accepted dispatch: expected ${expectedAxes.join(",")}; received ${actualAxes.join(",")}`);
+  }
+  for (const leg of dispatch.legs) {
+    const actual = result.legs[leg.axis];
+    if (actual === undefined) throw new Error(`Reviewer runner omitted ${leg.axis} result`);
+    ledger.append(actual.status === "failed"
+      ? { source: "reviewer-agent", type: "leg-settled", dispatchIdentity: dispatch.identity, axis: leg.axis, status: "failed", prompt: actual.prompt, target: actual.target, failure: actual.failure, diagnostic: actual.diagnostic, workspaceDisposition: actual.workspaceDisposition }
+      : { source: "reviewer-agent", type: "leg-settled", dispatchIdentity: dispatch.identity, axis: leg.axis, status: "successful", prompt: actual.prompt, target: actual.target, report: actual.report, usage: actual.usage, workspaceDisposition: actual.workspaceDisposition });
+  }
+}
+
+type FatalEvidence = { diagnostics: string; cause: unknown; targetSnapshot?: ReviewerTargetSnapshot; workspaceDisposition?: ReviewerWorkspaceDisposition };
+
+function cloneFreeze<T>(value: T): T {
+  if (Array.isArray(value)) return Object.freeze(value.map(cloneFreeze)) as T;
+  if (typeof value === "object" && value !== null) {
+    const copy: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) copy[key] = cloneFreeze(item);
+    return Object.freeze(copy) as T;
+  }
+  return value;
+}
+function hasExactEventShape(event: object, keys: readonly string[]): boolean {
+  const actual = Object.keys(event);
+  return actual.length === keys.length && actual.every((key) => keys.includes(key));
+}
+
+function fatal(error: unknown): FatalEvidence {
+  const record = typeof error === "object" && error !== null ? error as Record<string, unknown> : undefined;
+  return cloneFreeze({
+    diagnostics: "infrastructure-failure",
+    cause: error,
+    ...(record?.targetSnapshot === undefined ? {} : { targetSnapshot: record.targetSnapshot as ReviewerTargetSnapshot }),
+    ...(record?.workspaceDisposition === undefined ? {} : { workspaceDisposition: record.workspaceDisposition as ReviewerWorkspaceDisposition }),
+  });
+}
+
+export function createReviewerExecutionLedger(): ReviewerExecutionLedger {
+  const rejections: Array<{ identity: string; violations: readonly ReviewerPreflightViolation[]; started: false }> = [];
+  const closedAttempts: Array<{ identity: string; reason: "acceptance-closed"; started: false }> = [];
+  let accepted: ReviewerAcceptedEvidence | undefined;
+  let started: { dispatchIdentity: string; cardinality: 1 | 2 } | undefined;
+  const results: Partial<Record<"standards" | "spec", ReviewerLegResultEvidence>> = {};
+  let infrastructureFailure: FatalEvidence | undefined;
+
+  function append(raw: ReviewerEvidenceEvent): void {
+    const event = cloneFreeze(raw);
+    if (event.source === "reviewer-dispatch" && event.type === "rejected") {
+      if (!hasExactEventShape(event, ["source", "type", "identity", "violations", "started"]) || event.started !== false ||
+          event.violations.length === 0 || event.violations.some((code) => !REVIEWER_PREFLIGHT_VIOLATIONS.includes(code)))
+        throw new Error("Rejected dispatch must contain only closed bounded non-start evidence");
+      if (accepted !== undefined || started !== undefined) throw new Error("Rejection cannot follow an accepted dispatch");
+      rejections.push(cloneFreeze({ identity: event.identity, violations: event.violations, started: false }));
+      return;
+    }
+    if (event.source === "reviewer-dispatch" && event.type === "closed-attempt") {
+      if (!hasExactEventShape(event, ["source", "type", "identity", "reason", "started"]) || event.reason !== "acceptance-closed" || event.started !== false)
+        throw new Error("Closed attempt must contain only immutable non-start outcome evidence");
+      if (accepted === undefined) throw new Error("Closed attempt requires a closed acceptance lifecycle");
+      closedAttempts.push(cloneFreeze({ identity: event.identity, reason: event.reason, started: false }));
+      return;
+    }
+    if (event.source === "reviewer-dispatch" && event.type === "accepted") {
+      if (accepted !== undefined) throw new Error("Projection permits exactly one accepted dispatch");
+      const axes = event.legs.map((leg) => leg.axis);
+      if (axes[0] !== "standards" || (axes.length !== 1 && (axes.length !== 2 || axes[1] !== "spec")))
+        throw new Error("Accepted dispatch sibling axes disagree");
+      if (!isReviewerPromptText(event.input.canonicalSkill))
+        throw new Error("Accepted canonical Skill must be plain text");
+      for (const leg of event.legs) {
+        if (!isReviewerPromptText(leg.prompt))
+          throw new Error("Accepted compiled prompt must be plain text");
+      }
+      accepted = event;
+      return;
+    }
+    if (event.source === "reviewer-runtime" && event.type === "fatal") {
+      if (infrastructureFailure === undefined) infrastructureFailure = cloneFreeze({
+        diagnostics: event.diagnostics,
+        cause: event.cause,
+        ...(event.targetSnapshot === undefined ? {} : { targetSnapshot: event.targetSnapshot }),
+        ...(event.workspaceDisposition === undefined ? {} : { workspaceDisposition: event.workspaceDisposition }),
+      });
+      return;
+    }
+    if (event.type === "dispatch-started") {
+      if (accepted === undefined || event.dispatchIdentity !== accepted.identity) throw new Error("Start requires its accepted dispatch");
+      if (started !== undefined) throw new Error("Accepted dispatch can start exactly once");
+      if (event.cardinality !== accepted.legs.length) throw new Error("Dispatch start cardinality disagrees with acceptance");
+      started = cloneFreeze({ dispatchIdentity: event.dispatchIdentity, cardinality: event.cardinality });
+      return;
+    }
+    if (accepted === undefined || started === undefined || event.dispatchIdentity !== accepted.identity)
+      throw new Error("Runner result requires its irreversible accepted dispatch start");
+    if (results[event.axis] !== undefined) throw new Error(`Reviewer ${event.axis} result can settle exactly once`);
+    const compiled = accepted.legs.find((leg) => leg.axis === event.axis);
+    if (compiled === undefined) throw new Error(`Reviewer ${event.axis} was not an accepted leg`);
+    if (!sameReviewerPromptText(event.prompt, compiled.prompt) || !isReviewerPromptText(event.prompt))
+      throw new Error("Actual runner prompt does not exactly match compiled prompt text");
+    if (!sameReviewerPinnedTarget(event.target, accepted.target)) throw new Error("Runner target does not match shared pinned target");
+    if (event.status === "successful") {
+      if (typeof event.report !== "string" || event.report.length === 0 || event.failure !== undefined) throw new Error("Successful settlement requires a report");
+    } else if (event.failure === undefined || event.report !== undefined) {
+      throw new Error("Failed settlement requires a bounded failure classification and no report");
+    }
+    results[event.axis] = event;
+  }
+
+  function recordInfrastructureFailure<T>(error: T): T {
+    if (infrastructureFailure === undefined) {
+      const evidence = fatal(error);
+      append({ source: "reviewer-runtime", type: "fatal", ...evidence });
+    }
+    return error;
+  }
+  function recordForAudit(status: "completed" | "refused"): ReviewerExecutionRecord {
+    if (infrastructureFailure !== undefined) throw Object.assign(new Error(`Reviewer infrastructure previously failed: ${infrastructureFailure.diagnostics}`), { fatalReviewerInfrastructure: true as const });
+    if (status === "completed") {
+      if (accepted === undefined || started === undefined) throw new Error("Reviewer completed requires exactly one accepted and started dispatch");
+      const expected = accepted.legs.map((leg) => leg.axis);
+      if (expected.some((axis) => results[axis]?.status !== "successful") || Object.keys(results).length !== expected.length)
+        throw new Error(expected.length === 2 ? "Reviewer completed requires both axes settled successfully" : "Reviewer completed requires Standards settled successfully and no Spec evidence");
+    } else if (accepted !== undefined) {
+      const expected = accepted.legs.map((leg) => leg.axis);
+      if (started === undefined || expected.some((axis) => results[axis] === undefined) || Object.keys(results).length !== expected.length)
+        throw new Error("Reviewer refused after acceptance requires every expected leg terminal outcome");
+    }
+    return cloneFreeze({ rejections, closedAttempts, ...(accepted === undefined ? {} : { accepted }), ...(started === undefined ? {} : { started }), results });
+  }
+  return Object.freeze({ append, recordInfrastructureFailure, recordForAudit });
+}

package/src/reviewer-failure-diagnostic.ts

@@ -0,0 +1,18 @@
+import type { ReviewerFailureClassification } from "./reviewer-execution-ledger.ts";
+
+export function normalizeReviewerFailureDiagnostic(error: unknown, failure: ReviewerFailureClassification): string {
+  const original = error instanceof Error && Object.hasOwn(error, "reviewerOriginal")
+    ? (error as Error & { reviewerOriginal: unknown }).reviewerOriginal
+    : error;
+  const message = original instanceof Error
+    ? original.message.trim()
+    : typeof original === "string"
+      ? original.trim()
+      : typeof original === "object" && original !== null && typeof (original as { errorMessage?: unknown }).errorMessage === "string"
+        ? (original as { errorMessage: string }).errorMessage.trim()
+        : "";
+  if (message !== "") return message;
+  return failure === "provider"
+    ? "Reviewer Agent provider supplied no diagnostic details"
+    : "Reviewer Agent failed without diagnostic details";
+}

package/src/reviewer-git-snapshot.ts

@@ -0,0 +1,53 @@
+export const REVIEW_REF_PREFIXES = ["refs/heads", "refs/tags", "refs/remotes"] as const;
+
+/** Closed identity for a ref: annotated tags retain both tag object and peeled commit. */
+export type ReviewerRefEntry = Readonly<{
+  objectId: string;
+  peeledCommitId: string | null;
+}>;
+export type ReviewerRefMap = Readonly<Record<string, ReviewerRefEntry>>;
+
+export function parseReviewerRefSnapshot(raw: string): Record<string, ReviewerRefEntry> {
+  const refs: Record<string, ReviewerRefEntry> = {};
+  for (const line of raw.split("\n")) {
+    if (!line) continue;
+    const fields = line.split("\0");
+    if (fields.length !== 5 || !fields[0] || !fields[1] || !fields[3]) {
+      throw new Error(`Malformed Git ref snapshot line: ${line}`);
+    }
+    const peeledCommitId = fields[3] === "commit"
+      ? fields[1]
+      : fields[4] === "commit" && fields[2] ? fields[2] : null;
+    refs[fields[0]] = Object.freeze({
+      objectId: fields[1],
+      peeledCommitId,
+    });
+  }
+  return refs;
+}
+
+export function reviewerRefSnapshotArgs(): string[] {
+  return ["for-each-ref", "--format=%(refname)%00%(objectname)%00%(*objectname)%00%(objecttype)%00%(*objecttype)", ...REVIEW_REF_PREFIXES];
+}
+
+export function immutableReviewerRefs(refs: ReviewerRefMap): ReviewerRefMap {
+  return Object.freeze(Object.fromEntries(Object.entries(refs)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, entry]) => [name, Object.freeze({ objectId: entry.objectId, peeledCommitId: entry.peeledCommitId })])));
+}
+
+export function sameReviewerPinnedTarget(
+  actual: Readonly<{ repositoryRoot: string; objectFormat: "sha1" | "sha256"; targetHead: string; refs: ReviewerRefMap }>,
+  expected: Readonly<{ repositoryRoot: string; objectFormat: "sha1" | "sha256"; targetHead: string; refs: ReviewerRefMap }>,
+): boolean {
+  return actual.repositoryRoot === expected.repositoryRoot && actual.objectFormat === expected.objectFormat &&
+    actual.targetHead === expected.targetHead && sameReviewerRefs(actual.refs, expected.refs);
+}
+
+export function sameReviewerRefs(actual: ReviewerRefMap, expected: ReviewerRefMap): boolean {
+  const actualEntries = Object.entries(actual).sort(([left], [right]) => left.localeCompare(right));
+  const expectedEntries = Object.entries(expected).sort(([left], [right]) => left.localeCompare(right));
+  return actualEntries.length === expectedEntries.length && actualEntries.every(([name, value], index) =>
+    name === expectedEntries[index]?.[0] && value.objectId === expectedEntries[index]?.[1].objectId &&
+    value.peeledCommitId === expectedEntries[index]?.[1].peeledCommitId);
+}

package/src/reviewer-pinned-git.ts

@@ -0,0 +1,144 @@
+import { execFile } from "node:child_process";
+import { access, realpath } from "node:fs/promises";
+import { promisify } from "node:util";
+
+import { immutableReviewerRefs, parseReviewerRefSnapshot, reviewerRefSnapshotArgs, type ReviewerRefMap } from "./reviewer-git-snapshot.ts";
+import { sha256Hex } from "./sha256.ts";
+import { ReviewerCorrectablePreflightError } from "./reviewer-preflight-error.ts";
+
+export type ReviewerObjectFormat = "sha1" | "sha256";
+export type ReviewerPinnedTarget = Readonly<{
+  repositoryRoot: string;
+  objectFormat: ReviewerObjectFormat;
+  targetHead: string;
+  refs: ReviewerRefMap;
+}>;
+export type ReviewerRange = Readonly<{
+  base: string;
+  target: string;
+  diffCommand: string;
+  diffSha256: string;
+  commits: readonly string[];
+}>;
+export type ReviewerPinnedGitReader = {
+  pin: ReviewerPinnedTarget;
+  snapshot(): Promise<ReviewerPinnedTarget>;
+  resolve(base: string): Promise<string>;
+  range(base: string): Promise<ReviewerRange>;
+};
+
+const execFileAsync = promisify(execFile);
+type GitProcessError = Error & Readonly<{ code: number | string | null; signal: NodeJS.Signals | null; timedOut: boolean; aborted: boolean; stderr: string; stdout: string }>;
+async function execGit<T extends "utf8" | "buffer">(args: readonly string[], options: { encoding: T; maxBuffer?: number }): Promise<{ stdout: T extends "buffer" ? Buffer : string; stderr: string }> {
+  try { return await execFileAsync("git", args, options) as unknown as { stdout: T extends "buffer" ? Buffer : string; stderr: string }; }
+  catch (error) {
+    const source = error as Partial<GitProcessError>;
+    const wrapped = new Error("git process failed", { cause: error }) as GitProcessError;
+    Object.assign(wrapped, { code: source.code ?? null, signal: source.signal ?? null, timedOut: (source as { killed?: unknown }).killed === true && source.signal === "SIGTERM", aborted: source.name === "AbortError", stderr: String(source.stderr ?? ""), stdout: String(source.stdout ?? "") });
+    throw wrapped;
+  }
+}
+function exitCode(error: unknown): number | undefined { const code = typeof error === "object" && error !== null ? (error as { code?: unknown }).code : undefined; return typeof code === "number" ? code : undefined; }
+async function repositoryIsAvailable(root: string): Promise<{ available: boolean; cause?: unknown }> { try { await access(`${root}/.git`); return { available: true }; } catch (cause) { return { available: false, cause }; } }
+export const immutableReviewerPin = (pin: ReviewerPinnedTarget): ReviewerPinnedTarget => Object.freeze({
+  repositoryRoot: pin.repositoryRoot, objectFormat: pin.objectFormat, targetHead: pin.targetHead, refs: immutableReviewerRefs(pin.refs),
+});
+async function gitText(root: string, args: readonly string[]): Promise<string> {
+  const { stdout } = await execGit(["-C", root, ...args], { encoding: "utf8" });
+  return stdout.trim();
+}
+
+/** Concrete fixed-point Git I/O; dispatch owns all policy applied to these reads. */
+export async function createReviewerPinnedGitReader(root = process.cwd()): Promise<ReviewerPinnedGitReader> {
+  const discoveredRoot = await gitText(root, ["rev-parse", "--show-toplevel"]);
+  const repositoryRoot = await realpath(discoveredRoot);
+  const objectFormat = await gitText(repositoryRoot, ["rev-parse", "--show-object-format"]);
+  if (objectFormat !== "sha1" && objectFormat !== "sha256") throw new Error("Unsupported Git object format");
+  const oidWidth = objectFormat === "sha1" ? 40 : 64;
+  const targetHead = await gitText(repositoryRoot, ["rev-parse", "HEAD^{commit}"]);
+  const reachableCommitIds = Object.freeze((await gitText(repositoryRoot, ["rev-list", targetHead])).split("\n").filter(Boolean));
+  const refs = parseReviewerRefSnapshot(await gitText(repositoryRoot, reviewerRefSnapshotArgs()));
+  const pin = immutableReviewerPin({ repositoryRoot, objectFormat, targetHead, refs });
+  const invalid = (
+    code: "base-invalid" | "range-invalid",
+    diagnostic: string,
+    cause?: unknown,
+  ): never => {
+    throw new ReviewerCorrectablePreflightError(code, diagnostic, cause === undefined ? undefined : { cause });
+  };
+  const symbolic = (base: string): string | undefined => {
+    const selected = Object.hasOwn(refs, base) ? base : (() => {
+      const candidates = [`refs/heads/${base}`, `refs/tags/${base}`, `refs/remotes/${base}`].filter((name) => Object.hasOwn(refs, name));
+      if (candidates.length > 1) invalid("base-invalid", "base revision is ambiguous across pinned refs");
+      return candidates[0];
+    })();
+    if (selected === undefined) return undefined;
+    const commit = refs[selected]?.peeledCommitId;
+    if (commit === null) invalid("base-invalid", "base revision ref must resolve to a commit");
+    return commit ?? undefined;
+  };
+  return Object.freeze({
+    pin,
+    async snapshot() {
+      const liveObjectFormat = await gitText(repositoryRoot, ["rev-parse", "--show-object-format"]);
+      if (liveObjectFormat !== "sha1" && liveObjectFormat !== "sha256") throw new Error("Unsupported Git object format");
+      return immutableReviewerPin({ repositoryRoot, objectFormat: liveObjectFormat, targetHead: await gitText(repositoryRoot, ["rev-parse", "HEAD^{commit}"]), refs: parseReviewerRefSnapshot(await gitText(repositoryRoot, reviewerRefSnapshotArgs())) });
+    },
+    async resolve(base: string) {
+      if (!/^[A-Za-z0-9._/~^+-]+$/.test(base) || base.startsWith("-") || base.includes("..") || base.includes("@{")) {
+        invalid("base-invalid", "base revision syntax is invalid or uses a forbidden revision form");
+      }
+      let commit: string | undefined;
+      const headExpression = /^HEAD((?:~[0-9]+|\^[0-9]+)*)$/.exec(base);
+      if (headExpression) {
+        try {
+          commit = await gitText(repositoryRoot, ["rev-parse", "--verify", `${targetHead}${headExpression[1]}^{commit}`]);
+        } catch (error) {
+          if (exitCode(error) === 128) {
+            const repository = await repositoryIsAvailable(repositoryRoot);
+            if (repository.available) invalid("base-invalid", "base revision HEAD ancestry expression must resolve to a reachable commit", error);
+          }
+          throw error;
+        }
+      } else if (new RegExp(`^[0-9a-f]{${oidWidth}}$`).test(base)) commit = base;
+      else if (new RegExp(`^[0-9a-f]{4,${oidWidth - 1}}$`).test(base) && !(objectFormat === "sha256" && base.length === 40)) {
+        const matches = reachableCommitIds.filter((candidate) => candidate.startsWith(base));
+        if (matches.length !== 1) invalid("base-invalid", "base revision abbreviation must identify exactly one reachable commit");
+        commit = matches[0];
+      } else commit = symbolic(base);
+      if (commit === undefined) invalid("base-invalid", "base revision must name an existing pinned ref or reachable commit");
+      try { commit = await gitText(repositoryRoot, ["rev-parse", "--verify", `${commit}^{commit}`]); } catch (error) {
+        if (exitCode(error) === 128) {
+          const repository = await repositoryIsAvailable(repositoryRoot);
+          if (repository.available) invalid("base-invalid", "base revision must resolve to an existing commit", error);
+        }
+        throw error;
+      }
+      try { await gitText(repositoryRoot, ["merge-base", "--is-ancestor", commit, targetHead]); } catch (error) {
+        if (exitCode(error) === 1) invalid("base-invalid", "base revision must be an ancestor of the pinned target", error);
+        throw error;
+      }
+      return commit;
+    },
+    async range(base: string) {
+      let mergeBase: string;
+      try {
+        mergeBase = await gitText(repositoryRoot, ["merge-base", base, targetHead]);
+      } catch (error) {
+        if (exitCode(error) === 1) {
+          invalid("range-invalid", "review range requires a common ancestor for base and pinned target", error);
+        }
+        throw error;
+      }
+      if (!mergeBase) invalid("range-invalid", "review range requires a common ancestor for base and pinned target");
+      const diffCommand = `git diff ${mergeBase}...${targetHead}`;
+      const [{ stdout: diff }, commitsText] = await Promise.all([
+        execGit(["-C", repositoryRoot, "diff", `${mergeBase}...${targetHead}`], { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 }),
+        gitText(repositoryRoot, ["rev-list", "--reverse", `${mergeBase}..${targetHead}`]),
+      ]);
+      if (diff.length === 0) invalid("range-invalid", "review range must contain a non-empty diff between base and pinned target");
+      return Object.freeze({ base: mergeBase, target: targetHead, diffCommand, diffSha256: sha256Hex(Uint8Array.from(diff)), commits: Object.freeze(commitsText ? commitsText.split("\n") : []) });
+    },
+
+  });
+}