@gethmy/harness 1.0.0

package/src/exec-types.ts

@@ -0,0 +1,109 @@
+/**
+ * Execution-only types. The daemon's types.ts keeps its config, claim and queue
+ * types; this file holds what the motor's build, metric and git modules need.
+ *
+ * The two config interfaces are deliberately NARROW: they name only the LEAF
+ * fields the motor actually reads, not the whole `claude` / `worktree` /
+ * `verification` sub-shape. The daemon's AgentConfig satisfies them structurally,
+ * so its call sites are unchanged — and the motor never learns the daemon's config
+ * shape beyond the handful of fields it touches. If a new field is needed here,
+ * add that one field, never the whole config object or a whole sub-shape.
+ */
+
+/**
+ * One operator-declared, allowlisted measurement a `custom` gate can run (#690).
+ *
+ * Executed in argv form (`command` + `args`) — never through a shell — so nothing
+ * in the value is ever word-split, glob-expanded, or interpolated. Both fields are
+ * fixed by the operator; a gate contributes only the *choice* of which metric runs.
+ */
+export interface PlaybookMetricDef {
+  /** Executable to run, resolved on PATH. Never a shell string. */
+  command: string;
+  /** Fixed arguments. Operator-declared; a gate can never append to these. */
+  args?: string[];
+  /**
+   * How to read the measured value out of the command's stdout:
+   *   - `"number"`        — the whole trimmed stdout parsed as a number.
+   *   - `"json:<path>"`   — stdout parsed as JSON, then the dot-path resolved
+   *                         (e.g. `"json:categories.performance.score"`), reusing
+   *                         the evaluator's own prototype-safe `resolvePath`.
+   * Anything else is refused at collection time (fail closed), never guessed.
+   */
+  parse: string;
+  /**
+   * Per-metric timeout in ms. Defaults to {@link DEFAULT_METRIC_TIMEOUT_MS} and
+   * is CLAMPED to a 15-minute ceiling — the run is synchronous and the daemon is
+   * a single process, so a larger value would stall the watcher, the health
+   * endpoint and every other worker rather than just this measurement. A timeout
+   * is `blocked` (no measurement was produced), never a silent pass.
+   */
+  timeoutMs?: number;
+}
+
+/** Default wall-clock cap for one metric command (#690). Real measurement tools
+ * (a Lighthouse run, a benchmark) outrun a build, so this is deliberately generous
+ * — but never unbounded. */
+export const DEFAULT_METRIC_TIMEOUT_MS = 300_000; // 5 minutes
+
+/**
+ * The slice of the daemon's config that verification actually reads — leaf
+ * fields only, not the whole `claude` / `worktree` / `verification` sub-shape.
+ */
+export interface VerificationConfig {
+  claude: {
+    /**
+     * Base model for implement runs — the default tier every card lands on
+     * unless it escalates per below. (#354 will let a card pick its own model;
+     * until then this is the fallback for all cards.)
+     */
+    model: string;
+    /**
+     * `--setting-sources` value for lean spawns (review, auto-fix, deep-review)
+     * that don't need the project CLAUDE.md / @-imports (~23KB). `"local,user"`
+     * keeps the local-scoped harmony MCP server + user settings while dropping
+     * the project docs. Empty string omits the flag (full default behaviour).
+     */
+    leanSettingSources: string;
+  };
+  worktree: {
+    baseBranch: string;
+  };
+  verification: {
+    build: boolean;
+    lint: boolean;
+    /**
+     * Run the repo's test suite before a branch reaches Review (#688). Unlike
+     * lint, a failing suite BLOCKS completion — a run that breaks tests is a
+     * failed attempt, not a Review-ready branch. Repos with no resolvable test
+     * command (see `project-type.ts`) skip-and-warn regardless of this flag.
+     * Default on; set `false` to opt out per repo (e.g. a suite too slow to run
+     * on every attempt).
+     */
+    test: boolean;
+    deepReview: boolean;
+    /**
+     * Block a branch that deletes a test/spec file relative to current main
+     * before it reaches Review — a deleted regression test is the signature of
+     * an accidental revert of already-merged work (#408). Default on.
+     */
+    revertGuard: boolean;
+    devServerBasePort: number;
+    /** Timeout for the build / lint / auto-fix steps. */
+    timeout: number;
+    /**
+     * Timeout for the test step (#688). Separate from `timeout` because a real
+     * suite routinely outruns a build: a 2-minute cap would kill it mid-run and
+     * report a timeout as a test failure.
+     */
+    testTimeout: number;
+  };
+}
+
+/** The slice of the daemon's config that the git helpers actually read. */
+export interface WorktreeConfig {
+  worktree: VerificationConfig["worktree"];
+}
+
+/** How a PR is integrated. Re-declared here so the motor needs no daemon import. */
+export type MergeStrategy = "squash" | "merge" | "rebase";

package/src/gate-collectors.ts

@@ -0,0 +1,431 @@
+/**
+ * Gate evidence collectors + dispatcher (Playbooks P1 #3, card #516).
+ *
+ * This is the daemon half of the #515 gate runner. Each collector turns the live
+ * world into a `GateEvidence`:
+ *   - build_green   → ran the worktree build/lint (verification.ts) + dev-server probe
+ *   - review_passed → the parsed review verdict + #478 gated-acceptance checks
+ *   - checklist/dod → the card's subtasks / done state
+ *   - artifact      → #517's LLM rubric judge over the produced artifact
+ *   - custom        → #690's allowlisted command metric (a number to gate on)
+ *   - oracle_passed → the held test authored by the stage's `author` role, run
+ *                     against the implementer's worktree (Playbooks P2, Task 12)
+ *
+ * The flow per gate, run daemon-side after a stage's work completes:
+ *   collector.collect(ctx) → GateEvidence
+ *     → gateEvaluate(gate, evidence)        // shared, pure — the single verdict
+ *     → toStageGateEvidenceInsert(ctx, evid) // shared, pure — the row shape
+ *     → client.recordStageGateEvidence(insert) // service-role write via the API
+ *
+ * The daemon has NO service-role Supabase client (it only holds an anon Realtime
+ * client + the API-key REST client). So evidence is persisted by POSTing to a new
+ * harmony-api endpoint that writes with the edge's service-role client — one write
+ * path, RLS-honest. See `recordStageGateEvidence` on the API client.
+ *
+ * Registry: {@link buildGateCollectorRegistry} maps `GateKind → GateEvidenceCollector`.
+ * #517's artifact collector is added by registering one more entry — the dispatcher
+ * (`collectGateEvidence`) is closed for modification, open for extension.
+ */
+
+import type { Card, Subtask } from "@harmony/shared";
+import {
+  type GateEvidence,
+  type GateEvidenceCollector,
+  type GateEvidenceContext,
+  type GateKind,
+  type GateResult,
+  type GateSpec,
+  isGateKind,
+  type PlaybookStageDef,
+  resolveStageDef,
+} from "@harmony/shared";
+import { ArtifactCollector, type ArtifactJudgeDeps } from "./artifact-judge.js";
+import {
+  CommandMetricCollector,
+  type CommandMetricDeps,
+} from "./command-metric.js";
+import { log } from "./log.js";
+import type { OracleDeps } from "./oracle.js";
+import { OracleCollector } from "./oracle-collector.js";
+import type { ReviewResult } from "./review-types.js";
+import { runBuild, runLint } from "./verification.js";
+
+const TAG = "gate-collectors";
+
+/** The minimal client request seam the gate helpers need. */
+type GateRequestFn = (
+  method: string,
+  path: string,
+) => Promise<{ version: { steps: unknown; steps_version: number } }>;
+
+/**
+ * Resolve a card's bound stage and its normalized gate from the PINNED
+ * `playbook_versions` snapshot (never live `playbooks.steps` — editing a playbook
+ * must not retroactively change an in-flight card; same rule as the #514 stage
+ * executor). Returns `null` when playbooks are off, the card isn't staged, the pin
+ * is missing, or the stage / its gate can't be resolved.
+ *
+ * FAIL-CLOSED + total — never throws. Shared by the implement worker (build_green)
+ * and the review worker (review_passed) so both read the gate the same way.
+ */
+export async function resolveStageGate(
+  client: { request: GateRequestFn },
+  card: Pick<Card, "current_stage" | "playbook_id" | "playbook_version">,
+): Promise<{ stage: PlaybookStageDef; gate: GateSpec } | null> {
+  const currentStage = card.current_stage;
+  const playbookId = card.playbook_id;
+  const version = card.playbook_version;
+  if (!currentStage || !playbookId || version == null) return null;
+  try {
+    const res = await client.request(
+      "GET",
+      `/playbooks/${encodeURIComponent(playbookId)}/versions/${version}`,
+    );
+    const def = res.version;
+    const resolution = resolveStageDef(def, currentStage);
+    if (resolution.kind !== "found") return null;
+    const gate = normalizeGateSpec(resolution.stage.gate);
+    if (!gate) return null;
+    return { stage: resolution.stage, gate };
+  } catch (err) {
+    log.warn(
+      TAG,
+      `resolveStageGate failed for stage "${currentStage}": ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Gate spec normalization (stage.gate Record → GateSpec)
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a stage's stored `gate` (`PlaybookStageDef.gate`, a
+ * `Record<string, unknown> | null`) into a typed {@link GateSpec}, or `null` when
+ * the stage declares no gate / the record is malformed.
+ *
+ * Fail-closed on `kind`: an unknown/missing kind yields `null` so the caller treats
+ * the stage as ungated rather than inventing a gate. (The evaluator also fails
+ * closed on a bad spec — this just gives the collector layer a typed handle and a
+ * clean "no gate here" signal.) `conditions`/`mode`/`pendingEngine` pass through
+ * untouched; the evaluator owns their validation.
+ *
+ * `metric` (#690) also passes through as an opaque string — it is the name of an
+ * operator-allowlisted measurement the `custom` collector looks up. Validating it
+ * here would be wrong: whether a name is permitted depends on the *daemon's* own
+ * config, which this pure normalizer has no view of, and the collector reports an
+ * undeclared name as a legible `blocked` rather than a silently dropped field.
+ */
+export function normalizeGateSpec(
+  gate: Record<string, unknown> | null | undefined,
+): GateSpec | null {
+  if (!gate || typeof gate !== "object") return null;
+  const kind = (gate as { kind?: unknown }).kind;
+  if (!isGateKind(kind)) return null;
+  const spec: GateSpec = { kind: kind as GateKind };
+  const pendingEngine = (gate as { pendingEngine?: unknown }).pendingEngine;
+  if (typeof pendingEngine === "boolean") spec.pendingEngine = pendingEngine;
+  const conditions = (gate as { conditions?: unknown }).conditions;
+  if (Array.isArray(conditions))
+    spec.conditions = conditions as GateSpec["conditions"];
+  const mode = (gate as { mode?: unknown }).mode;
+  if (mode === "all" || mode === "any") spec.mode = mode;
+  const metric = (gate as { metric?: unknown }).metric;
+  if (typeof metric === "string" && metric.length > 0) spec.metric = metric;
+  return spec;
+}
+
+// ---------------------------------------------------------------------------
+// build_green collector
+// ---------------------------------------------------------------------------
+
+/**
+ * Dependencies the build-green collector needs to inspect the live worktree. The
+ * daemon injects them at construction time; `collect(ctx)` is then a thin call into
+ * the existing verification primitives. Injecting (rather than reaching for module
+ * globals) keeps the collector unit-testable with a fake build/lint.
+ */
+export interface BuildGreenDeps {
+  worktreePath: string;
+  buildTimeout: number;
+  lintTimeout: number;
+  /** Inject for tests; defaults to verification.ts `runBuild`. Returns error lines. */
+  runBuild?: (worktreePath: string, timeout: number) => string[];
+  /** Inject for tests; defaults to verification.ts `runLint`. Returns warning lines. */
+  runLint?: (worktreePath: string, timeout: number) => string[];
+}
+
+/**
+ * build_green — Slice-1 gate. Runs the worktree's build + lint and reports
+ * structured pass/fail. The dev-server probe is review-pipeline state, so the
+ * implement-side collector reports build + lint only.
+ *
+ * The coarse `result` MIRRORS `verification.ts`: a build is "green" when the
+ * **build** passes (exit 0). Lint findings are **non-fatal warnings** — exactly
+ * as `runVerification` treats them (it logs lint issues but only `buildErrors`
+ * flip `passed`). This keeps the gate from being *stricter* than the daemon's own
+ * verification: a repo with a pre-existing, repo-wide lint baseline (e.g. the
+ * known `harmony-api/index.ts` issues) would otherwise make EVERY card's
+ * build_green gate `failed` even when the card's own change is clean and the
+ * daemon already advanced it to Review (#552, surfaced by the #523 dogfood).
+ *
+ * The full lint detail is still carried in `structured.lint` (`passed`,
+ * `warnings`), so a playbook author who wants a lint-clean bar can OPT IN with a
+ * gate condition `{ path: "lint.passed", op: "eq", value: true }` (#515's
+ * predicate mechanism). The default for a bare `{ kind: "build_green" }` gate is
+ * the verification-matching "build passes" semantics; strict-lint is a choice,
+ * not the floor.
+ *
+ * structured shape (predicate paths address into this):
+ *   {
+ *     build: { passed: boolean, errors: string[] },
+ *     lint:  { passed: boolean, warnings: string[] }
+ *   }
+ */
+export class BuildGreenCollector implements GateEvidenceCollector {
+  readonly kind: GateKind = "build_green";
+  constructor(private readonly deps: BuildGreenDeps) {}
+
+  async collect(_context: GateEvidenceContext): Promise<GateEvidence> {
+    const doBuild = this.deps.runBuild ?? runBuild;
+    const doLint = this.deps.runLint ?? runLint;
+    const buildErrors = doBuild(this.deps.worktreePath, this.deps.buildTimeout);
+    const lintWarnings = doLint(this.deps.worktreePath, this.deps.lintTimeout);
+    const buildPassed = buildErrors.length === 0;
+    const lintPassed = lintWarnings.length === 0;
+    // Match verification.ts: only a failing BUILD makes the gate red. Lint
+    // warnings are non-fatal (kept in `structured.lint` for an opt-in condition).
+    const result: GateResult = buildPassed ? "passed" : "failed";
+    return {
+      result,
+      structured: {
+        build: { passed: buildPassed, errors: buildErrors },
+        lint: { passed: lintPassed, warnings: lintWarnings },
+      },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// review_passed collector
+// ---------------------------------------------------------------------------
+
+export interface ReviewPassedDeps {
+  /** The parsed review verdict from review-completion's `parseReviewOutput`. */
+  review: ReviewResult;
+}
+
+/**
+ * review_passed — reads the Playbook DoD contract via the #478 gated-acceptance
+ * review output. The verdict is the coarse signal; the per-criterion acceptance
+ * checks are the structured detail a predicate can gate on.
+ *
+ * `parseReviewOutput` already folds any failed/partial acceptance criterion into a
+ * `rejected` verdict (#478), so `verdict === "approved"` already implies every
+ * criterion passed. We surface both so a gate can predicate on either the coarse
+ * verdict or a specific criterion.
+ *
+ * structured shape:
+ *   {
+ *     verdict: "approved" | "rejected" | "error",
+ *     acceptanceChecks: [{ criterion, status }],
+ *     unmetCount: number
+ *   }
+ */
+export class ReviewPassedCollector implements GateEvidenceCollector {
+  readonly kind: GateKind = "review_passed";
+  constructor(private readonly deps: ReviewPassedDeps) {}
+
+  async collect(_context: GateEvidenceContext): Promise<GateEvidence> {
+    const { review } = this.deps;
+    const checks = review.acceptanceChecks ?? [];
+    const unmetCount = checks.filter(
+      (c) => c.status === "fail" || c.status === "partial",
+    ).length;
+    // An "error" verdict means the reviewer produced no parseable judgement — the
+    // collector can't assert pass/fail, so it's `blocked` (the gate can't be met
+    // on an unparseable review).
+    const result: GateResult =
+      review.verdict === "approved"
+        ? "passed"
+        : review.verdict === "rejected"
+          ? "failed"
+          : "blocked";
+    return {
+      result,
+      structured: {
+        verdict: review.verdict,
+        acceptanceChecks: checks.map((c) => ({
+          criterion: c.criterion,
+          status: c.status,
+        })),
+        unmetCount,
+      },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// checklist / dod collector
+// ---------------------------------------------------------------------------
+
+export interface ChecklistDodDeps {
+  subtasks: Subtask[];
+  /** Whether the card itself is marked done (the DoD coarse signal). */
+  cardDone: boolean;
+}
+
+/**
+ * checklist + dod — reads the card's subtasks (the checklist) and `done` state (the
+ * definition-of-done signal). Both kinds share one collector body; the gate `kind`
+ * picks which the dispatcher routes here. A gate with no explicit conditions passes
+ * iff `result === "passed"`, which for this collector means: every subtask complete
+ * AND (for `dod`) the card marked done.
+ *
+ * structured shape:
+ *   {
+ *     total: number, completed: number, allComplete: boolean,
+ *     cardDone: boolean,
+ *     items: [{ id, title, completed }]
+ *   }
+ */
+export class ChecklistDodCollector implements GateEvidenceCollector {
+  constructor(
+    readonly kind: GateKind,
+    private readonly deps: ChecklistDodDeps,
+  ) {}
+
+  async collect(_context: GateEvidenceContext): Promise<GateEvidence> {
+    const { subtasks, cardDone } = this.deps;
+    const total = subtasks.length;
+    const completed = subtasks.filter((s) => s.completed).length;
+    const allComplete = total === 0 ? cardDone : completed === total;
+    // `dod` additionally requires the card itself to be marked done; `checklist`
+    // only cares about the subtasks.
+    const passed = this.kind === "dod" ? allComplete && cardDone : allComplete;
+    const result: GateResult = passed ? "passed" : "failed";
+    return {
+      result,
+      structured: {
+        total,
+        completed,
+        allComplete,
+        cardDone,
+        items: subtasks.map((s) => ({
+          id: s.id,
+          title: s.title,
+          completed: s.completed,
+        })),
+      },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registry + dispatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * The dependencies the daemon has on hand at the gate-collection point, from which
+ * the registry constructs each kind's collector. A field may be absent if the
+ * pipeline that produces it hasn't run for this gate (e.g. no `review` on the
+ * implement side) — the dispatcher only instantiates a collector when the gate's
+ * kind has what it needs, else it reports the gate as `blocked`.
+ */
+export interface GateCollectorDeps {
+  build?: BuildGreenDeps;
+  review?: ReviewResult;
+  checklist?: ChecklistDodDeps;
+  /** #517 artifact gate — deps for the LLM-judge collector (worktree + rubric judge). */
+  artifact?: ArtifactJudgeDeps;
+  /**
+   * #690 `custom` command gate — the worktree to measure in plus the operator's
+   * metric allowlist. Supply it whenever a worktree exists, even with an EMPTY
+   * allowlist: the collector then reports "metric X is not declared" and names the
+   * config key to edit, which is a far better hold reason than the dispatcher's
+   * generic "no collector for kind custom". Both are `blocked` — only one tells
+   * the operator what to do about it.
+   */
+  command?: CommandMetricDeps;
+  /**
+   * The oracle_passed gate: the held test fetched from Harmony, placed in the
+   * worktree, run, removed. Supply it whenever a worktree exists.
+   */
+  oracle?: OracleDeps;
+}
+
+/**
+ * Build the `GateKind → GateEvidenceCollector` registry for the available deps.
+ * Only kinds whose deps are present get a collector; the rest are absent (the
+ * dispatcher treats an absent collector as `blocked`).
+ *
+ * Open for extension (#517): register an `artifact` collector here once its deps
+ * are wired. The dispatcher below never changes.
+ */
+export function buildGateCollectorRegistry(
+  deps: GateCollectorDeps,
+): Partial<Record<GateKind, GateEvidenceCollector>> {
+  const registry: Partial<Record<GateKind, GateEvidenceCollector>> = {};
+  if (deps.build) {
+    registry.build_green = new BuildGreenCollector(deps.build);
+  }
+  if (deps.review) {
+    registry.review_passed = new ReviewPassedCollector({ review: deps.review });
+  }
+  if (deps.checklist) {
+    registry.checklist = new ChecklistDodCollector("checklist", deps.checklist);
+    registry.dod = new ChecklistDodCollector("dod", deps.checklist);
+  }
+  if (deps.artifact) {
+    registry.artifact = new ArtifactCollector(deps.artifact);
+  }
+  if (deps.command) {
+    registry.custom = new CommandMetricCollector(deps.command);
+  }
+  if (deps.oracle) {
+    registry.oracle_passed = new OracleCollector(deps.oracle);
+  }
+  return registry;
+}
+
+/**
+ * Run the collector for `context.gate.kind`, or report `blocked` when no collector
+ * is registered for that kind (its producing pipeline didn't run, or the kind has
+ * no daemon collector yet — `label` is the last such kind; `custom` gained one in
+ * #690 and is registered wherever a worktree exists).
+ *
+ * `blocked` evidence is honest: the evaluator can't pass a gate it has no signal
+ * for, and the human-advance edge renders a "blocked" gate distinctly from a
+ * "failed" one. Never throws — a collector that throws is caught and downgraded to
+ * `blocked` with the error noted in `structured.error`, so a flaky collector can't
+ * crash the worker.
+ */
+export async function collectGateEvidence(
+  registry: Partial<Record<GateKind, GateEvidenceCollector>>,
+  context: GateEvidenceContext,
+): Promise<GateEvidence> {
+  const collector = registry[context.gate.kind];
+  if (!collector) {
+    log.info(
+      TAG,
+      `No collector for gate kind "${context.gate.kind}" — reporting blocked`,
+    );
+    return {
+      result: "blocked",
+      structured: {
+        reason: `No daemon collector for gate kind "${context.gate.kind}".`,
+      },
+    };
+  }
+  try {
+    return await collector.collect(context);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.warn(
+      TAG,
+      `Collector for "${context.gate.kind}" threw: ${msg} — reporting blocked`,
+    );
+    return { result: "blocked", structured: { error: msg } };
+  }
+}

package/src/gate-config-error.ts

@@ -0,0 +1,73 @@
+/**
+ * The "this gate cannot be measured as configured" marker (card #823).
+ *
+ * A gate that reports `blocked` says only that no measurement exists. Two very
+ * different situations produce it, and the advancement engine must not treat them
+ * alike:
+ *
+ *   - **The measurement failed.** The command exited non-zero, timed out, or
+ *     printed something unparsable. A re-run can genuinely change the outcome —
+ *     the tool may be flaky, the branch may be fixed by the next attempt — so this
+ *     keeps the existing retry path (`handleGateUnmet`).
+ *   - **The gate is misconfigured.** The metric name is undeclared, the
+ *     declaration carries no `command`, or its `parse` mode is unknown. Nothing
+ *     ran and nothing ever will: the inputs are static config, so attempt N+1
+ *     computes exactly the same answer as attempt 1. Re-running costs a full
+ *     Claude implementation run each time and cannot help.
+ *
+ * Before this marker existed, both routed into the generic "gate unmet → re-run
+ * this stage" path, so a typo'd metric name burned the card's whole `maxAttempts`
+ * budget (and a converge loop's whole iteration budget) before holding. The
+ * collector now tags the config-defect blocks, and `stage-advance.ts` holds on
+ * them immediately with the attempt rolled back.
+ *
+ * The marker is a plain own key on the evidence's `structured` doc, so it survives
+ * the round-trip every other field takes: `gateEvaluate` echoes `structured` into
+ * its `GateEvaluation` verbatim, and `stage_gate_evidence.structured` persists it
+ * for the board/edge to read later. It is deliberately NOT part of the gate
+ * predicate surface — `blockedDetail` composes the human-facing finding from
+ * `structured.reason` alone, so adding this key changes no verdict text.
+ *
+ * Fail-safe by omission: evidence without the key reads as retryable, which is the
+ * pre-#823 behavior. A collector opts a block IN to the hold-immediately path; it
+ * can never opt one out by accident.
+ */
+
+/** Own key on `GateEvidence.structured` marking a block as a configuration defect. */
+export const GATE_CONFIG_ERROR_KEY = "configError";
+
+/** The structured fragment a collector spreads into config-defect `blocked` evidence. */
+export const GATE_CONFIG_ERROR_MARK: Readonly<Record<string, unknown>> =
+  Object.freeze({ [GATE_CONFIG_ERROR_KEY]: true });
+
+/** The minimal evaluation shape this predicate reads — structurally a `GateEvaluation`. */
+interface EvaluationLike {
+  passed: boolean;
+  structured: Record<string, unknown>;
+}
+
+/**
+ * The reason a gate cannot be measured as configured, or `null` when this is a
+ * normal (retryable) verdict. PURE + TOTAL — never throws, so a malformed
+ * structured doc degrades to "retryable" rather than crashing the engine.
+ *
+ * A *passing* evaluation is never a config error: `gateEvaluate` cannot pass
+ * blocked evidence, so a marked-and-passed evaluation would mean the marker was
+ * forged into a passing doc. Reading `passed` first makes that unreachable instead
+ * of merely unlikely.
+ */
+export function gateConfigErrorReason(
+  evaluation: EvaluationLike | null | undefined,
+): string | null {
+  if (!evaluation || evaluation.passed) return null;
+  const structured = evaluation.structured;
+  if (!structured || typeof structured !== "object") return null;
+  if (!Object.hasOwn(structured, GATE_CONFIG_ERROR_KEY)) return null;
+  if ((structured as Record<string, unknown>)[GATE_CONFIG_ERROR_KEY] !== true) {
+    return null;
+  }
+  const reason = (structured as Record<string, unknown>).reason;
+  return typeof reason === "string" && reason.trim().length > 0
+    ? reason.trim()
+    : "the gate cannot be measured as configured";
+}