Unify harness decision arbitration

Author: chenbo

docs/concepts/loop-engineering.md

@@ -183,7 +183,9 @@ Each loop writes a durable iteration directory:
   decision.json
 ```
 
-`iteration.json` is the stable directory index. `executor.result.json` records the executor command, exit code, hashes, changed files, and normalized event summary. `trace.json` is a schema wrapper around the normalized execution trace and trusted evidence summary. `guard.findings.json` normalizes policy, hallucination, and regression findings into one `GuardFinding` schema. `guard.gates.json` turns Guard findings into blocking conditions and required actions. `decision.json` records the selected action with priority, confidence, blocking status, input signals, and convergence state.
+`iteration.json` is the stable directory index. `executor.result.json` records the executor command, exit code, hashes, changed files, and normalized event summary. `trace.json` is a schema wrapper around the normalized execution trace and trusted evidence summary. `guard.findings.json` normalizes policy, hallucination, and regression findings into one `GuardFinding` schema. `guard.gates.json` turns Guard findings into blocking conditions and required actions. `decision.json` records the selected action with priority, confidence, blocking status, input signals, convergence state, and decision arbitration details.
+
+Decision arbitration converts executor failures, forbidden policy findings, every blocking Guard Gate, blocking Loop decisions, missing required policy evidence, and risk signals into normalized candidates. Candidates are sorted by the shared action priority (`rollback`, `block`, `repack`, `repair`, `run-tests`, `human-review`, `finalize`), then confidence and stable candidate ID. The highest-priority candidate supplies the action; all remaining candidates stay visible as supporting blockers and contribute deduplicated commands and artifacts. Reordering Guard Gates therefore cannot change the selected decision.
 
 `executor.events.jsonl` stores normalized `AgentEvent` records. OpenCode currently supports `opencode run --format json` stdout, optional transcript files, and generic stdout/stderr fallback; later executor adapters can produce the same event model for MiMoCode, Codex, Claude Code, and Cursor.
 

docs/developer/guard-gate-schema.md

@@ -37,4 +37,10 @@ interface GuardGate {
 }
 ```
 
-Gates feed the orchestrator decision router, which writes a decision report such as `finalize`, `repair`, `repack`, `block`, `rollback`, or `require-human-review`.
+Gates, executor failures, policy findings, Loop decisions, and risk signals are normalized into `HarnessDecisionCandidate` records before arbitration. Candidate ordering is deterministic and uses the shared action priority:
+
+```txt
+rollback > block > repack > repair > run-tests > human-review > finalize
+```
+
+The highest-priority candidate becomes the selected action. Remaining candidates are retained as supporting candidates; their reasons, required commands, and artifacts are merged into the final decision with stable deduplication. `decision.json` and the orchestrator Markdown report record the selected candidate, selected priority, and supporting candidates, so the result does not depend on Guard Gate array order.

src/harness/control-plane/decision-engine.ts

@@ -1,5 +1,5 @@
 import type { GuardGateAction, GuardGateReport } from "../../outputs/guard-gates.js";
-import type { ArtifactRef, HarnessDecision, HarnessDecisionAction } from "../types.js";
+import type { ArtifactRef, HarnessDecision, HarnessDecisionAction, HarnessDecisionCandidate } from "../types.js";
 import { createHarnessDecision } from "../types.js";
 import type { LoopControllerReport } from "./loop-controller.js";
 import type { PolicyEngineReport } from "../verification-plane/policy-engine.js";
@@ -28,116 +28,148 @@ export interface DecisionEngineInput {
 }
 
 export function decideHarnessAction(input: DecisionEngineInput): HarnessDecision {
+  return arbitrateDecisionCandidates(collectDecisionCandidates(input));
+}
+
+export function collectDecisionCandidates(input: DecisionEngineInput): HarnessDecisionCandidate[] {
+  const artifacts = input.artifacts ?? [];
+  const candidates: HarnessDecisionCandidate[] = [];
+
   if (input.executorResult.exitCode !== 0) {
-    return decision({
-      action: "block",
-      blocking: true,
-      confidence: 0.94,
-      reasons: [
-        "The selected executor failed before the harness could trust the result.",
-        `executor exit code: ${input.executorResult.exitCode ?? "unknown"}`,
-        input.executorResult.stderr ? "executor stderr captured" : "executor stderr empty"
-      ],
-      artifacts: input.artifacts ?? []
-    });
+    candidates.push(
+      candidate({
+        id: "executor.failure",
+        source: "executor",
+        action: "block",
+        confidence: 0.94,
+        reasons: [
+          "The selected executor failed before the harness could trust the result.",
+          `executor exit code: ${input.executorResult.exitCode ?? "unknown"}`,
+          input.executorResult.stderr ? "executor stderr captured" : "executor stderr empty"
+        ],
+        artifacts
+      })
+    );
   }
 
   if (input.policy.summary.forbidden > 0) {
-    return decision({
-      action: input.checkpointMode === "git-worktree" ? "rollback" : "block",
-      blocking: true,
-      confidence: 0.96,
-      reasons: [
-        "Forbidden policy findings were detected in the diff.",
-        `forbidden findings: ${input.policy.summary.forbidden}`,
-        `policy fail-on: ${input.policy.failOn}`
-      ],
-      artifacts: input.artifacts ?? []
-    });
+    candidates.push(
+      candidate({
+        id: "policy.forbidden",
+        source: "policy",
+        action: input.checkpointMode === "git-worktree" ? "rollback" : "block",
+        confidence: 0.96,
+        reasons: [
+          "Forbidden policy findings were detected in the diff.",
+          `forbidden findings: ${input.policy.summary.forbidden}`,
+          `policy fail-on: ${input.policy.failOn}`
+        ],
+        artifacts
+      })
+    );
   }
 
-  const blockingGate = input.guardGates.gates.find((gate) => gate.status === "blocked");
-  if (blockingGate) {
-    return decision({
-      action: decisionForGate(blockingGate.action, input.checkpointMode),
-      blocking: true,
-      confidence: 0.93,
-      reasons: [
-        `${blockingGate.guard} guard blocked: ${blockingGate.condition}.`,
-        `guard: ${blockingGate.guard}`,
-        `condition: ${blockingGate.condition}`,
-        ...blockingGate.evidence.slice(0, 5)
-      ],
-      requiredCommands: commandForGate(blockingGate.action),
-      artifacts: input.artifacts ?? []
-    });
+  for (const gate of input.guardGates.gates.filter((item) => item.status === "blocked")) {
+    candidates.push(
+      candidate({
+        id: `guard-gate.${gate.id}`,
+        source: "guard-gate",
+        action: decisionForGate(gate.action, input.checkpointMode),
+        confidence: 0.93,
+        reasons: [`${gate.guard} guard blocked: ${gate.condition}.`, `guard: ${gate.guard}`, `condition: ${gate.condition}`, ...gate.evidence.slice(0, 5)],
+        requiredCommands: commandForGate(gate.action),
+        artifacts
+      })
+    );
   }
 
-  const needsContext = input.loop.decisions.find((item) => item.action === "rebuild-context" || item.action === "replan" || item.action === "expand-context");
-  if (needsContext) {
-    return decision({
-      action: "repack",
-      blocking: true,
-      confidence: needsContext.confidence,
-      reasons: ["The next loop needs refreshed or expanded context before continuing.", needsContext.reason, ...needsContext.signals],
-      requiredCommands: needsContext.command ? [needsContext.command] : [],
-      artifacts: input.artifacts ?? []
-    });
+  for (const loopDecision of input.loop.decisions.filter((item) => item.blocking)) {
+    const action = actionForLoopDecision(loopDecision.action);
+    if (!action) continue;
+    candidates.push(
+      candidate({
+        id: `loop.${loopDecision.action}`,
+        source: "loop",
+        action,
+        confidence: loopDecision.confidence,
+        reasons: [loopReasonPrefix(action), loopDecision.reason, ...loopDecision.signals],
+        requiredCommands: loopDecision.command ? [loopDecision.command] : [],
+        artifacts
+      })
+    );
   }
 
-  const needsRepair = input.loop.decisions.find((item) => item.action === "repair-contracts" || item.action === "add-or-update-tests");
-  const needsTests = input.loop.decisions.find((item) => item.action === "run-tests");
-  if (needsTests) {
-    return decision({
-      action: "run-tests",
-      blocking: true,
-      confidence: needsTests.confidence,
-      reasons: [needsTests.reason, ...needsTests.signals],
-      requiredCommands: needsTests.command ? [needsTests.command] : [],
-      artifacts: input.artifacts ?? []
-    });
+  if (input.policy.summary.requiredMissing > 0) {
+    candidates.push(
+      candidate({
+        id: "policy.required-missing",
+        source: "policy",
+        action: "repair",
+        confidence: 0.88,
+        reasons: ["Required policy evidence is missing.", `required missing: ${input.policy.summary.requiredMissing}`],
+        requiredCommands: requiredCommandsFromPolicy(input.policy),
+        artifacts
+      })
+    );
   }
 
-  if (needsRepair || input.policy.summary.requiredMissing > 0) {
-    return decision({
-      action: "repair",
-      blocking: true,
-      confidence: needsRepair?.confidence ?? 0.88,
-      reasons: [
-        needsRepair?.reason ?? "Required policy evidence is missing.",
-        ...(needsRepair?.signals ?? [`required missing: ${input.policy.summary.requiredMissing}`])
-      ],
-      requiredCommands: needsRepair?.command ? [needsRepair.command] : requiredCommandsFromPolicy(input.policy),
-      artifacts: input.artifacts ?? []
-    });
+  if (input.loop.risk === "High" || input.policy.summary.risks > 0) {
+    candidates.push(
+      candidate({
+        id: "risk.human-review",
+        source: "risk",
+        action: "human-review",
+        confidence: 0.82,
+        reasons: [
+          "The diff has high-impact or risk policy signals even though hard gates passed.",
+          `impact risk: ${input.loop.risk}`,
+          `policy risks: ${input.policy.summary.risks}`
+        ],
+        artifacts
+      })
+    );
   }
 
-  if (input.loop.risk === "High" || input.policy.summary.risks > 0) {
-    return decision({
-      action: "human-review",
-      blocking: true,
-      confidence: 0.82,
-      reasons: [
-        "The diff has high-impact or risk policy signals even though hard gates passed.",
-        `impact risk: ${input.loop.risk}`,
-        `policy risks: ${input.policy.summary.risks}`
-      ],
-      requiredCommands: [],
-      artifacts: input.artifacts ?? []
-    });
+  if (!candidates.length) {
+    candidates.push(
+      candidate({
+        id: "fallback.finalize",
+        source: "fallback",
+        action: "finalize",
+        blocking: false,
+        confidence: input.changedFiles.length ? 0.8 : 0.72,
+        reasons: [
+          "No blocking policy, context, impact, or verification signals remain.",
+          `changed files: ${input.changedFiles.length}`,
+          `loop status: ${input.loop.status}`,
+          "policy: passed"
+        ],
+        artifacts
+      })
+    );
   }
 
+  return candidates.map(normalizeCandidate).sort(compareCandidates);
+}
+
+export function arbitrateDecisionCandidates(candidates: HarnessDecisionCandidate[]): HarnessDecision {
+  if (!candidates.length) throw new Error("Decision arbitration requires at least one candidate.");
+  const sorted = candidates.map(normalizeCandidate).sort(compareCandidates);
+  const selected = sorted[0];
+  if (!selected) throw new Error("Decision arbitration did not select a candidate.");
+  const supporting = sorted.slice(1);
   return decision({
-    action: "finalize",
-    blocking: false,
-    confidence: input.changedFiles.length ? 0.8 : 0.72,
-    reasons: [
-      "No blocking policy, context, impact, or verification signals remain.",
-      `changed files: ${input.changedFiles.length}`,
-      `loop status: ${input.loop.status}`,
-      "policy: passed"
-    ],
-    artifacts: input.artifacts ?? []
+    action: selected.action,
+    blocking: selected.blocking,
+    confidence: selected.confidence,
+    reasons: [...selected.reasons, ...supporting.map(supportingReason)],
+    requiredCommands: sorted.flatMap((item) => item.requiredCommands),
+    artifacts: sorted.flatMap((item) => item.artifacts),
+    arbitration: {
+      selectedCandidate: selected,
+      selectedPriority: selected.priority,
+      supportingCandidates: supporting
+    }
   });
 }
 
@@ -153,7 +185,8 @@ export function maxLoopHarnessDecision(maxLoops: number, lastDecision: HarnessDe
       ...lastDecision.reasons
     ],
     requiredCommands: lastDecision.requiredCommands,
-    artifacts: lastDecision.artifacts
+    artifacts: lastDecision.artifacts,
+    arbitration: lastDecision.arbitration
   });
 }
 
@@ -170,7 +203,8 @@ export function noProgressHarnessDecision(fingerprint: string, lastDecision: Har
       ...lastDecision.reasons
     ],
     requiredCommands: lastDecision.requiredCommands,
-    artifacts: lastDecision.artifacts
+    artifacts: lastDecision.artifacts,
+    arbitration: lastDecision.arbitration
   });
 }
 
@@ -183,7 +217,86 @@ function decision(
     confidence: input.confidence,
     reasons: input.reasons,
     requiredCommands: input.requiredCommands ?? [],
+    artifacts: input.artifacts ?? [],
+    ...(input.arbitration ? { arbitration: input.arbitration } : {})
+  });
+}
+
+function candidate(
+  input: Omit<HarnessDecisionCandidate, "priority" | "blocking" | "requiredCommands" | "artifacts"> & {
+    blocking?: boolean;
+    requiredCommands?: string[];
+    artifacts?: ArtifactRef[];
+  }
+): HarnessDecisionCandidate {
+  return {
+    id: input.id,
+    source: input.source,
+    action: input.action,
+    priority: HARNESS_DECISION_PRIORITY[input.action],
+    blocking: input.blocking ?? input.action !== "finalize",
+    confidence: input.confidence,
+    reasons: input.reasons,
+    requiredCommands: input.requiredCommands ?? [],
     artifacts: input.artifacts ?? []
+  };
+}
+
+function normalizeCandidate(input: HarnessDecisionCandidate): HarnessDecisionCandidate {
+  return {
+    ...input,
+    priority: HARNESS_DECISION_PRIORITY[input.action],
+    confidence: Math.round(Math.max(0, Math.min(1, input.confidence)) * 100) / 100,
+    reasons: dedupeStrings(input.reasons),
+    requiredCommands: dedupeStrings(input.requiredCommands).sort((a, b) => a.localeCompare(b)),
+    artifacts: dedupeArtifacts(input.artifacts)
+  };
+}
+
+function compareCandidates(a: HarnessDecisionCandidate, b: HarnessDecisionCandidate): number {
+  return (
+    b.priority - a.priority ||
+    Number(b.blocking) - Number(a.blocking) ||
+    b.confidence - a.confidence ||
+    a.id.localeCompare(b.id) ||
+    candidateSignature(a).localeCompare(candidateSignature(b))
+  );
+}
+
+function supportingReason(candidate: HarnessDecisionCandidate): string {
+  return `Supporting blocker [${candidate.id}] action=${candidate.action} priority=${candidate.priority}: ${candidate.reasons[0] ?? "no reason provided"}`;
+}
+
+function actionForLoopDecision(action: LoopControllerReport["decisions"][number]["action"]): HarnessDecisionAction | null {
+  if (action === "rebuild-context" || action === "replan" || action === "expand-context") return "repack";
+  if (action === "repair-contracts" || action === "add-or-update-tests") return "repair";
+  if (action === "run-tests") return "run-tests";
+  return null;
+}
+
+function loopReasonPrefix(action: HarnessDecisionAction): string {
+  if (action === "repack") return "The next loop needs refreshed or expanded context before continuing.";
+  if (action === "repair") return "The next loop must repair code, contracts, or tests before continuing.";
+  return "The next loop must run required verification commands before continuing.";
+}
+
+function dedupeStrings(items: string[]): string[] {
+  return [...new Set(items.filter(Boolean))];
+}
+
+function dedupeArtifacts(items: ArtifactRef[]): ArtifactRef[] {
+  const byKey = new Map<string, ArtifactRef>();
+  for (const item of items) byKey.set(`${item.kind ?? "other"}:${item.path}`, item);
+  return [...byKey.values()].sort((a, b) => `${a.kind ?? "other"}:${a.path}`.localeCompare(`${b.kind ?? "other"}:${b.path}`));
+}
+
+function candidateSignature(candidate: HarnessDecisionCandidate): string {
+  return JSON.stringify({
+    action: candidate.action,
+    artifacts: candidate.artifacts,
+    reasons: candidate.reasons,
+    requiredCommands: candidate.requiredCommands,
+    source: candidate.source
   });
 }