@kontextmind/kxm 0.7.92 → 0.7.93

package/plugins/kxm/src/improve.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
-import type { RoutingRecord, RoutingRecordV2 } from "./routing.ts";
+import { computeDecayedWeight, type RoutingRecord, type RoutingRecordV2 } from "./routing.ts";
 import { nowIso } from "./protocol.ts";
+import { compareCodeUnitIds } from "./relevance.ts";
 
 export const CANDIDATE_SCHEMA = "kxm.candidate.v1" as const;
 export const IMPROVEMENT_REPORT_SCHEMA = "kxm.improvement-report.v2" as const;
@@ -32,22 +33,43 @@ export interface ImprovementCandidate {
   createdAt: string;
 }
 
+/** Why a group that recurs is still not a coded-repeat candidate. */
+export type ImprovementExcludedReason = "writes-repository" | "ask-not-repeated";
+
 export interface ImprovementGroupRow {
   workflowHash: string;
+  /** The engine's workflow id when the records carry one. */
+  workflowId?: string;
   stepId: string;
   agentRole: string;
   promptHash: string;
   recurrence: number;
+  /** Distinct runs among decided records. */
+  distinctRuns: number;
+  /** Most distinct decided runs that shared one objective (the same ask). */
+  askRecurrence: number;
+  undecidedRecords: number;
   meanCost: number;
   meanLatency: number;
+  /** Accepted share of decided records; a superseded retry never passes. */
   verifyPassRate: number;
   rework: number;
+  /** Recency-weighted recurrence. Orders rows; never decides candidacy. */
+  weightedRecurrence: number;
+  undatedRecords: number;
+  costSamples: number;
+  writesRepository: boolean;
   evidenceRefs: string[];
   isCandidate: boolean;
+  excludedReason?: ImprovementExcludedReason;
   candidateKind?: CandidateKind;
   candidateId?: string;
 }
 
+export interface ImprovementPromotionEntry extends PromotionReadiness {
+  candidateId: string;
+}
+
 export interface ImprovementReport {
   schema: typeof IMPROVEMENT_REPORT_SCHEMA;
   createdAt: string;
@@ -55,6 +77,8 @@ export interface ImprovementReport {
   recordsCount: number;
   groups: ImprovementGroupRow[];
   candidates: ImprovementCandidate[];
+  promotionPolicy: string;
+  promotion: ImprovementPromotionEntry[];
 }
 
 export function classifyCandidateKind(stepId: string, agentRole: string): CandidateKind {
@@ -69,8 +93,17 @@ export function classifyCandidateKind(stepId: string, agentRole: string): Candid
   return "workflow-step";
 }
 
-function generateCandidateDiff(kind: CandidateKind, stepId: string, agentRole: string, workflowHash: string): { diff: string; declaredOutcome: string; measure: string; summary: string } {
-  const safeSlug = stepId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "step";
+function candidateSlug(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "step";
+}
+
+function generateCandidateDiff(
+  kind: CandidateKind,
+  stepId: string,
+  agentRole: string,
+  workflowId?: string | undefined,
+): { diff: string; declaredOutcome: string; measure: string; summary: string } {
+  const safeSlug = candidateSlug(stepId);
   if (kind === "gate") {
     const diff = [
       "diff --git a/.kxm/gates.yaml b/.kxm/gates.yaml",
@@ -118,80 +151,159 @@ function generateCandidateDiff(kind: CandidateKind, stepId: string, agentRole: s
       diff,
       declaredOutcome: `Governed reusable skill for ${stepId}`,
       measure: `Reduced prompt drift and consistent model guidance for ${stepId}`,
-      summary: `Promote repeated instructions for '${stepId}' (${agentRole}) to governed skill`,
+      summary: `Consolidate repeated instructions for '${stepId}' (${agentRole}) into a governed skill (consolidation, not a coded step)`,
     };
   }
-  const rel = `.kxm/workflows/${safeSlug}.yaml`;
+  // A workflow-step candidate proposes the coded step itself: the agent turn
+  // becomes a command gate the operator writes and reviews.
+  const rel = `.kxm/workflows/${workflowId !== undefined ? candidateSlug(workflowId) : safeSlug}.yaml`;
   const diff = [
     `diff --git a/${rel} b/${rel}`,
     `--- a/${rel}`,
     `+++ b/${rel}`,
-    "@@ -1,3 +1,6 @@",
-    " steps:",
-    `+  - id: ${stepId}`,
-    `+    kind: agent`,
-    `+    agent: ${agentRole}`,
+    "@@ -1,3 +1,3 @@",
+    `   - id: ${stepId}`,
+    "-    kind: agent",
+    `-    agent: ${agentRole}`,
+    "+    kind: gate",
+    `+    gate: ${safeSlug}`,
+    "diff --git a/.kxm/gates.yaml b/.kxm/gates.yaml",
+    "--- a/.kxm/gates.yaml",
+    "+++ b/.kxm/gates.yaml",
+    "@@ -1,2 +1,6 @@",
+    " schema: kxm.gate-registry.v1",
+    " gates:",
+    `+  ${safeSlug}:`,
+    "+    kind: command",
+    `+    argv: [node, scripts/${safeSlug}.mjs]`,
+    "+    timeoutMs: 600000",
     "",
   ].join("\n");
   return {
     diff,
-    declaredOutcome: `Dedicated workflow step with typed inputs and transitions for ${stepId}`,
-    measure: `Reduced manual coordination and faster stage transitions for ${stepId}`,
-    summary: `Automate repetitive step '${stepId}' (${agentRole}) in workflow`,
+    declaredOutcome: `Coded gate replaces the model turn for ${stepId}; the operator writes scripts/${safeSlug}.mjs`,
+    measure: `Model cost and latency for ${stepId} drop to zero while its accepted rate holds`,
+    summary: `Replace the model turn for '${stepId}' (${agentRole}) with a coded gate step`,
   };
 }
 
+/** A trimmed, non-empty string, or undefined. */
+function nonEmptyText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function roundThree(value: number): number {
+  return Number(value.toFixed(3));
+}
+
+interface GroupAccumulator {
+  key: string;
+  workflowHash: string;
+  workflowId?: string;
+  stepId: string;
+  agentRole: string;
+  promptHash: string;
+  costs: number[];
+  latencies: number[];
+  total: number;
+  decided: number;
+  passed: number;
+  undecided: number;
+  reworkCount: number;
+  weight: number;
+  undated: number;
+  writes: boolean;
+  decidedRuns: Set<string>;
+  /** Decided runs per objective digest; one '(unkeyed)' bucket for records without one. */
+  askRuns: Map<string, Set<string>>;
+  evidenceRefs: Set<string>;
+}
+
+export interface GroupRoutingOptions {
+  minRecurrence?: number | undefined;
+  minPassRate?: number | undefined;
+  /** improvement.telemetryHalfLifeDays; weights order rows and never decide candidacy. */
+  halfLifeDays?: number | undefined;
+  /** Epoch milliseconds the recency weights are measured against. */
+  now?: number | undefined;
+}
+
+/**
+ * Group routing records by (workflowHash, step, role, promptHash) across runs.
+ *
+ * Identity: workflowHash is the engine's workflowId when present, then a
+ * workflow definition digest, then the run; promptHash is the engine's
+ * askSha256 (stable across runs, independent of the objective), then a v1
+ * rolePromptSha256. A group is a coded-repeat candidate only when the same
+ * objective was decided in at least minRecurrence runs, the accepted rate over
+ * decided records reaches minPassRate, and the step writes no repository.
+ */
 export function groupRoutingRecords(
   records: Array<RoutingRecord | RoutingRecordV2>,
-  options: { minRecurrence?: number; minPassRate?: number } = {},
+  options: GroupRoutingOptions = {},
 ): ImprovementGroupRow[] {
   const minRecurrence = options.minRecurrence ?? 2;
   const minPassRate = options.minPassRate ?? 0.75;
+  const halfLifeDays = options.halfLifeDays ?? 14;
+  const now = options.now ?? Date.now();
+
+  const raws = records.map((record) => record as unknown as Record<string, unknown>);
+  const runKeys = raws.map((raw, index) => nonEmptyText(raw.runId) ?? nonEmptyText(raw.workflowRunId) ?? `record:${index}`);
+  const stepIds = raws.map((raw) => nonEmptyText(raw.stepId) ?? nonEmptyText(raw.stageId) ?? "unknown");
+  const retriesOf = (raw: Record<string, unknown>): number =>
+    typeof raw.retries === "number" && Number.isFinite(raw.retries) ? raw.retries : 0;
+  // A retry of the same step in the same run supersedes every earlier attempt.
+  const maxRetries = new Map<string, number>();
+  raws.forEach((raw, index) => {
+    const attemptKey = `${runKeys[index]}\u0000${stepIds[index]}`;
+    maxRetries.set(attemptKey, Math.max(maxRetries.get(attemptKey) ?? 0, retriesOf(raw)));
+  });
 
-  const map = new Map<string, {
-    workflowHash: string;
-    stepId: string;
-    agentRole: string;
-    promptHash: string;
-    costs: number[];
-    latencies: number[];
-    passedCount: number;
-    reworkCount: number;
-    evidenceRefs: Set<string>;
-    total: number;
-  }>();
-
-  for (const r of records) {
-    const raw = r as unknown as Record<string, unknown>;
-    const providerMeta = (raw.providerMetadata && typeof raw.providerMetadata === "object") ? raw.providerMetadata as Record<string, unknown> : {};
-    const workflowHash = (raw.workflowDefinitionSha256 as string)
-      || (providerMeta.workflowDefinitionSha256 as string)
-      || (raw.workflowRunId as string)
-      || (raw.runId as string)
-      || "standalone";
-    const stepId = (raw.stepId as string) || (raw.stageId as string) || "unknown";
-    const agentRole = (raw.agentRole as string)?.trim() || "agent";
-    const promptHash = (raw.rolePromptSha256 as string)?.trim()
-      || (providerMeta.rolePromptSha256 as string)?.trim()
-      || "none";
+  const map = new Map<string, GroupAccumulator>();
+  raws.forEach((raw, index) => {
+    const providerMeta = raw.providerMetadata && typeof raw.providerMetadata === "object" && !Array.isArray(raw.providerMetadata)
+      ? raw.providerMetadata as Record<string, unknown>
+      : {};
+    const workflowId = nonEmptyText(providerMeta.workflowId);
+    const workflowHash = workflowId
+      ?? nonEmptyText(raw.workflowDefinitionSha256)
+      ?? nonEmptyText(providerMeta.workflowDefinitionSha256)
+      ?? nonEmptyText(raw.workflowRunId)
+      ?? nonEmptyText(raw.runId)
+      ?? "standalone";
+    const stepId = stepIds[index]!;
+    const agentRole = nonEmptyText(raw.agentRole) ?? "agent";
+    const promptHash = nonEmptyText(providerMeta.askSha256) ?? nonEmptyText(raw.rolePromptSha256) ?? "none";
+    const runKey = runKeys[index]!;
 
     const key = `${workflowHash}:${stepId}:${agentRole}:${promptHash}`;
     let group = map.get(key);
     if (!group) {
       group = {
+        key,
         workflowHash,
         stepId,
         agentRole,
         promptHash,
         costs: [],
         latencies: [],
-        passedCount: 0,
+        total: 0,
+        decided: 0,
+        passed: 0,
+        undecided: 0,
         reworkCount: 0,
+        weight: 0,
+        undated: 0,
+        writes: false,
+        decidedRuns: new Set<string>(),
+        askRuns: new Map<string, Set<string>>(),
         evidenceRefs: new Set<string>(),
-        total: 0,
       };
       map.set(key, group);
     }
+    if (group.workflowId === undefined && workflowId !== undefined) group.workflowId = workflowId;
 
     group.total += 1;
     const cost = raw.costUsd;
@@ -205,8 +317,24 @@ export function groupRoutingRecords(
 
     const verifierOutcome = raw.verifierOutcome;
     const finalOutcome = raw.finalOutcome;
-    if (verifierOutcome === "passed" || finalOutcome === "accepted" || finalOutcome === "completed") {
-      group.passedCount += 1;
+    const decided = (verifierOutcome !== undefined && verifierOutcome !== null)
+      || (finalOutcome !== undefined && finalOutcome !== null && finalOutcome !== "pending");
+    if (decided) {
+      group.decided += 1;
+      group.decidedRuns.add(runKey);
+      const ask = nonEmptyText(providerMeta.objectiveSha256) ?? "(unkeyed)";
+      let askRuns = group.askRuns.get(ask);
+      if (!askRuns) {
+        askRuns = new Set<string>();
+        group.askRuns.set(ask, askRuns);
+      }
+      askRuns.add(runKey);
+      const superseded = (maxRetries.get(`${runKey}\u0000${stepId}`) ?? 0) > retriesOf(raw);
+      if (!superseded && (verifierOutcome === "passed" || finalOutcome === "accepted" || finalOutcome === "completed")) {
+        group.passed += 1;
+      }
+    } else {
+      group.undecided += 1;
     }
 
     const retries = raw.retries;
@@ -214,13 +342,18 @@ export function groupRoutingRecords(
       group.reworkCount += retries;
     }
 
+    const recordedAt = nonEmptyText(raw.recordedAt);
+    if (recordedAt === undefined || !Number.isFinite(Date.parse(recordedAt))) group.undated += 1;
+    group.weight += computeDecayedWeight(recordedAt ?? "", halfLifeDays, now);
+    if (providerMeta.stepWrites === true) group.writes = true;
+
     const ref = (raw.attemptId as string) || (raw.runId as string) || (raw.workflowRunId as string) || (raw.behavioralSha256 as string);
     if (ref && group.evidenceRefs.size < 16) {
       group.evidenceRefs.add(ref);
     }
-  }
+  });
 
-  const rows: ImprovementGroupRow[] = [];
+  const keyed: Array<{ key: string; row: ImprovementGroupRow }> = [];
   for (const group of map.values()) {
     const recurrence = group.total;
     const meanCost = group.costs.length > 0
@@ -229,56 +362,83 @@ export function groupRoutingRecords(
     const meanLatency = group.latencies.length > 0
       ? Math.round(group.latencies.reduce((a, b) => a + b, 0) / group.latencies.length)
       : 0;
-    const verifyPassRate = recurrence > 0
-      ? Number((group.passedCount / recurrence).toFixed(3))
-      : 0;
-    const rework = group.reworkCount;
-
-    const isCandidate = recurrence >= minRecurrence && verifyPassRate >= minPassRate;
+    const verifyPassRate = group.decided > 0 ? roundThree(group.passed / group.decided) : 0;
+    const distinctRuns = group.decidedRuns.size;
+    const askRecurrence = Math.max(0, ...[...group.askRuns.values()].map((runs) => runs.size));
+    const passes = verifyPassRate >= minPassRate;
+
+    const isCandidate = askRecurrence >= minRecurrence && passes && !group.writes;
+    let excludedReason: ImprovementExcludedReason | undefined;
+    if (!isCandidate && passes) {
+      if (askRecurrence >= minRecurrence && group.writes) excludedReason = "writes-repository";
+      else if (distinctRuns >= minRecurrence && askRecurrence < minRecurrence) excludedReason = "ask-not-repeated";
+    }
     const candidateKind = isCandidate ? classifyCandidateKind(group.stepId, group.agentRole) : undefined;
     const safeSlug = group.stepId.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 16) || "step";
     const keyHash = createHash("sha256").update(`${group.workflowHash}:${group.stepId}:${group.agentRole}:${group.promptHash}`).digest("hex").slice(0, 10);
     const candidateId = isCandidate && candidateKind ? `cand_${candidateKind.replace(/-/g, "_")}_${safeSlug}_${keyHash}` : undefined;
 
-    rows.push({
-      workflowHash: group.workflowHash,
-      stepId: group.stepId,
-      agentRole: group.agentRole,
-      promptHash: group.promptHash,
-      recurrence,
-      meanCost,
-      meanLatency,
-      verifyPassRate,
-      rework,
-      evidenceRefs: [...group.evidenceRefs],
-      isCandidate,
-      ...(candidateKind !== undefined ? { candidateKind } : {}),
-      ...(candidateId !== undefined ? { candidateId } : {}),
+    keyed.push({
+      key: group.key,
+      row: {
+        workflowHash: group.workflowHash,
+        ...(group.workflowId !== undefined ? { workflowId: group.workflowId } : {}),
+        stepId: group.stepId,
+        agentRole: group.agentRole,
+        promptHash: group.promptHash,
+        recurrence,
+        distinctRuns,
+        askRecurrence,
+        undecidedRecords: group.undecided,
+        meanCost,
+        meanLatency,
+        verifyPassRate,
+        rework: group.reworkCount,
+        weightedRecurrence: roundThree(group.weight),
+        undatedRecords: group.undated,
+        costSamples: group.costs.length,
+        writesRepository: group.writes,
+        evidenceRefs: [...group.evidenceRefs],
+        isCandidate,
+        ...(excludedReason !== undefined ? { excludedReason } : {}),
+        ...(candidateKind !== undefined ? { candidateKind } : {}),
+        ...(candidateId !== undefined ? { candidateId } : {}),
+      },
     });
   }
 
-  return rows.sort((a, b) => {
-    if (a.isCandidate !== b.isCandidate) return a.isCandidate ? -1 : 1;
-    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;
-    return a.stepId.localeCompare(b.stepId);
-  });
+  return keyed
+    .sort((left, right) => {
+      const a = left.row;
+      const b = right.row;
+      if (a.isCandidate !== b.isCandidate) return a.isCandidate ? -1 : 1;
+      if (b.weightedRecurrence !== a.weightedRecurrence) return b.weightedRecurrence - a.weightedRecurrence;
+      if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;
+      return compareCodeUnitIds(a.stepId, b.stepId) || compareCodeUnitIds(left.key, right.key);
+    })
+    .map((entry) => entry.row);
+}
+
+export interface BuildImprovementReportOptions extends GroupRoutingOptions {
+  candidatesDir?: string | undefined;
+  projectRoot?: string | undefined;
+  dryRun?: boolean | undefined;
+  /** improvement.promotionPolicy; reported as readiness only. */
+  promotionPolicy?: string | undefined;
+  autoThreshold?: PromotionAutoThreshold | undefined;
 }
 
 export function buildImprovementReport(
   records: Array<RoutingRecord | RoutingRecordV2>,
-  options: {
-    minRecurrence?: number;
-    minPassRate?: number;
-    candidatesDir?: string;
-    projectRoot?: string;
-    dryRun?: boolean;
-  } = {},
+  options: BuildImprovementReportOptions = {},
 ): ImprovementReport {
   const projectRoot = options.projectRoot ? resolve(options.projectRoot) : process.cwd();
   const candidatesDir = options.candidatesDir ? resolve(options.candidatesDir) : join(projectRoot, ".kxm", "candidates");
+  const promotionPolicy = options.promotionPolicy ?? "manual_pr";
 
   const groups = groupRoutingRecords(records, options);
   const candidates: ImprovementCandidate[] = [];
+  const promotion: ImprovementPromotionEntry[] = [];
 
   for (const group of groups) {
     if (!group.isCandidate || !group.candidateKind || !group.candidateId) continue;
@@ -287,7 +447,7 @@ export function buildImprovementReport(
       group.candidateKind,
       group.stepId,
       group.agentRole,
-      group.workflowHash,
+      group.workflowId,
     );
 
     const diffFileName = `${group.candidateId}.diff`;
@@ -326,6 +486,18 @@ export function buildImprovementReport(
     candidates.push(candidate);
   }
 
+  const rowsByCandidate = new Map(groups.flatMap((row) => row.candidateId !== undefined ? [[row.candidateId, row] as const] : []));
+  for (const candidate of candidates) {
+    const row = rowsByCandidate.get(candidate.id);
+    promotion.push({
+      candidateId: candidate.id,
+      ...evaluatePromotionPolicy(candidate, promotionPolicy, {
+        autoThreshold: options.autoThreshold,
+        ...(row ? { costSamples: row.costSamples, distinctRuns: row.distinctRuns } : {}),
+      }),
+    });
+  }
+
   return {
     schema: IMPROVEMENT_REPORT_SCHEMA,
     createdAt: nowIso(),
@@ -333,6 +505,8 @@ export function buildImprovementReport(
     recordsCount: records.length,
     groups,
     candidates,
+    promotionPolicy,
+    promotion,
   };
 }
 
@@ -348,27 +522,33 @@ export function writeImprovementReport(improvementsDir: string, report: Improvem
 
 export function formatImprovementReport(report: ImprovementReport): string {
   const lines: string[] = [
-    `Improvement Report (${report.recordsCount} record(s), ${report.groups.length} group(s), ${report.candidates.length} candidate(s))`,
+    `Improvement Report (${report.recordsCount} record(s), ${report.groups.length} group(s), ${report.candidates.length} candidate(s); promotion policy ${report.promotionPolicy})`,
     "",
-    "Workflow       Step         Role         Prompt       Recurrence  Cost ($)  Latency (ms)  Pass Rate  Rework  Candidate",
-    "-------------------------------------------------------------------------------------------------------------------------",
+    "Workflow       Step         Role         Prompt       Records  Runs  Asks  Weighted  Cost ($)  Latency (ms)  Accepted  Rework  Candidate",
+    "------------------------------------------------------------------------------------------------------------------------------------------",
   ];
 
   for (const g of report.groups) {
     const wf = g.workflowHash.slice(0, 12).padEnd(14);
     const step = g.stepId.slice(0, 11).padEnd(12);
     const role = g.agentRole.slice(0, 11).padEnd(12);
-    const prompt = g.promptHash.slice(0, 10).padEnd(12);
-    const rec = String(g.recurrence).padStart(10);
+    const prompt = g.promptHash.replace(/^sha256:/, "").slice(0, 10).padEnd(12);
+    const rec = String(g.recurrence).padStart(7);
+    const runs = String(g.distinctRuns).padStart(5);
+    const asks = String(g.askRecurrence).padStart(5);
+    const weighted = g.weightedRecurrence.toFixed(3).padStart(9);
     const cost = g.meanCost.toFixed(3).padStart(9);
     const lat = String(g.meanLatency).padStart(13);
-    const pass = `${(g.verifyPassRate * 100).toFixed(0)}%`.padStart(10);
+    const accepted = `${(g.verifyPassRate * 100).toFixed(0)}%`.padStart(9);
     const rework = String(g.rework).padStart(7);
-    const cand = g.isCandidate ? `yes (${g.candidateKind})` : "no";
-    lines.push(`${wf} ${step} ${role} ${prompt} ${rec} ${cost} ${lat} ${pass} ${rework}  ${cand}`);
+    const cand = g.isCandidate
+      ? `yes (${g.candidateKind})`
+      : g.excludedReason !== undefined ? `no (${g.excludedReason})` : "no";
+    lines.push(`${wf} ${step} ${role} ${prompt} ${rec} ${runs} ${asks} ${weighted} ${cost} ${lat} ${accepted} ${rework}  ${cand}`);
   }
 
   if (report.candidates.length > 0) {
+    const readiness = new Map(report.promotion.map((entry) => [entry.candidateId, entry]));
     lines.push("");
     lines.push("Emitted Coded-Repeat Candidates:");
     for (const c of report.candidates) {
@@ -376,80 +556,85 @@ export function formatImprovementReport(report: ImprovementReport): string {
       lines.push(`    Outcome: ${c.declaredOutcome}`);
       lines.push(`    Measure: ${c.measure}`);
       lines.push(`    Proposed diff: ${c.proposedDiffPath}`);
+      const entry = readiness.get(c.id);
+      if (entry) {
+        lines.push(`    Promotion (${entry.policy}): ${entry.readyForReview ? "ready for review" : "not ready for review"}; ${entry.reason}`);
+      }
     }
+    lines.push("");
+    lines.push("Candidates are proposals: readiness never authorizes, and activation is a reviewed Git change.");
   }
 
   return lines.join("\n");
 }
 
-export interface PromotionDecision {
-  eligible: boolean;
-  policy: "manual_pr" | "critic_quorum" | "auto_threshold";
-  authorized: boolean;
+/** Review readiness of one candidate under improvement.promotionPolicy. */
+export interface PromotionReadiness {
+  policy: string;
+  readyForReview: boolean;
   reason: string;
 }
 
+export interface PromotionAutoThreshold {
+  minRuns?: number | undefined;
+  minPassRate?: number | undefined;
+  minCostSavings?: number | undefined;
+}
+
 /**
- * Evaluates candidate promotion policy (Decision Q11).
- * Supports:
- * - manual_pr: strict operator signoff via Git PR / CLI (fail-closed anti-privilege-escalation)
- * - critic_quorum: requires dual critic approval before auto-promotion
- * - auto_threshold: requires candidate to exceed recurrence and verifyPassRate thresholds
+ * Report whether a candidate is ready for operator review (Decision Q11).
+ *
+ * No policy authorizes anything. AGENTS.md:141 forbids auto-promoting skills
+ * or gates from telemetry, and ADR-001 (docs/contracts/architecture.md:177-180)
+ * rejects automatic learned-policy activation: activation is a reviewed Git
+ * change. Every policy therefore ends at an operator PR:
+ * - manual_pr: always ready; the operator reviews the proposed diff.
+ * - critic_quorum: ready once two distinct critic receipts are cited.
+ * - auto_threshold: ready once the candidate's distinct runs and accepted rate
+ *   reach the thresholds and, when minCostSavings is set, recorded cost samples
+ *   show at least that mean cost; a group without cost samples is never ready.
+ * Any other policy is not ready.
  */
 export function evaluatePromotionPolicy(
   candidate: ImprovementCandidate,
-  policy: "manual_pr" | "critic_quorum" | "auto_threshold" = "manual_pr",
-  options?: {
-    criticApprovals?: string[] | undefined;
-    autoThreshold?: {
-      minRuns: number;
-      minPassRate: number;
-      minCostSavings?: number | undefined;
-    } | undefined;
-  },
-): PromotionDecision {
+  policy: string = "manual_pr",
+  options: {
+    criticReceipts?: string[] | undefined;
+    autoThreshold?: PromotionAutoThreshold | undefined;
+    costSamples?: number | undefined;
+    distinctRuns?: number | undefined;
+  } = {},
+): PromotionReadiness {
   if (policy === "manual_pr") {
-    return {
-      eligible: true,
-      policy,
-      authorized: false,
-      reason: "Manual PR review and signoff required by policy (fail-closed anti-privilege-escalation)",
-    };
+    return { policy, readyForReview: true, reason: `operator PR applying ${candidate.proposedDiffPath} required` };
   }
 
   if (policy === "critic_quorum") {
-    const approvals = options?.criticApprovals ?? [];
-    const hasQuorum = approvals.length >= 2;
-    return {
-      eligible: true,
-      policy,
-      authorized: hasQuorum,
-      reason: hasQuorum
-        ? `Authorized by critic quorum (${approvals.join(", ")})`
-        : `Requires dual critic quorum; current approvals: ${approvals.length}/2`,
-    };
+    const receipts = new Set((options.criticReceipts ?? []).map((receipt) => receipt.trim()).filter((receipt) => receipt.length > 0));
+    return receipts.size >= 2
+      ? { policy, readyForReview: true, reason: "two critic receipts cited; operator PR still required" }
+      : { policy, readyForReview: false, reason: `awaiting 2 distinct critic receipts (have ${receipts.size})` };
   }
 
   if (policy === "auto_threshold") {
-    const threshold = options?.autoThreshold ?? { minRuns: 10, minPassRate: 0.95 };
-    const recurrence = candidate.baselineMetrics.recurrence;
+    const minRuns = options.autoThreshold?.minRuns ?? 10;
+    const minPassRate = options.autoThreshold?.minPassRate ?? 0.95;
+    const minCostSavings = options.autoThreshold?.minCostSavings;
+    const runs = options.distinctRuns ?? candidate.baselineMetrics.recurrence;
     const passRate = candidate.baselineMetrics.verifyPassRate;
-    const meetsThreshold = recurrence >= threshold.minRuns && passRate >= threshold.minPassRate;
-
-    return {
-      eligible: true,
-      policy,
-      authorized: meetsThreshold,
-      reason: meetsThreshold
-        ? `Authorized by auto-threshold (runs=${recurrence}>=${threshold.minRuns}, passRate=${passRate}>=${threshold.minPassRate})`
-        : `Auto-threshold not met: runs=${recurrence}/${threshold.minRuns}, passRate=${passRate}/${threshold.minPassRate}`,
-    };
+    const costSamples = options.costSamples ?? 0;
+    const meanCost = candidate.baselineMetrics.meanCost;
+    const costMet = minCostSavings === undefined || (costSamples > 0 && meanCost >= minCostSavings);
+    const ready = runs >= minRuns && passRate >= minPassRate && costMet;
+    const detail = [
+      `runs=${runs}/${minRuns}`,
+      `passRate=${passRate}/${minPassRate}`,
+      ...(minCostSavings === undefined ? [] : [`meanCost=${meanCost}/${minCostSavings} over ${costSamples} cost sample(s)`]),
+    ].join(", ");
+    return ready
+      ? { policy, readyForReview: true, reason: `auto-threshold met (${detail}); operator PR still required` }
+      : { policy, readyForReview: false, reason: `auto-threshold not met (${detail})` };
   }
 
-  return {
-    eligible: false,
-    policy,
-    authorized: false,
-    reason: `Unknown promotion policy: ${String(policy)}`,
-  };
+  return { policy, readyForReview: false, reason: "unknown promotion policy" };
 }