@mutagent/evaluator 0.1.0-alpha.3 → 0.1.0-alpha.5

package/.claude/skills/mutagent-evaluator/scripts/config/load.ts

@@ -93,16 +93,29 @@ export function detectLegacyConfig(obj: unknown): string[] {
 
 /**
  * How the evaluator's source was bound (or why it couldn't be). The SELECTION
- * contract (v0.2.1 — parity with orchestrator + diagnostics):
- *   bound            — exactly one source resolved (single entry · `default:true` · `--source` hit).
+ * contract (v0.2.2 — parity with orchestrator + diagnostics; F2 disambiguation UX):
+ *   bound            — exactly one source resolved with NO ambiguity (single entry ·
+ *                      `--source` hit). No prompt.
+ *   confirm-default  — >1 source with exactly one `default:true` (F2). The default is
+ *                      PRESELECTED (`source`) but the caller ISSUES A CONFIRM ASK before
+ *                      using it (distinct from a silent bind — be explicit around ambiguity).
+ *                      NON-fatal + bindable: `source` is usable as-is if the operator accepts
+ *                      or the run is non-interactive (`--source` / CI). Carries the full
+ *                      candidate list so the confirm can offer an override.
  *   none             — zero sources (DISCOVER needs a pick; code/dataset runs don't need a source).
  *   needs-selection  — >1 source, none `default:true`, no `--source` ⇒ the caller must PROMPT the
- *                      operator to pick (NON-fatal — the source EXISTS, only the pick is missing).
+ *                      operator to pick with NO preselection (NON-fatal — the source EXISTS,
+ *                      only the pick is missing).
  *   multiple-defaults— >1 source with `default:true` — an AMBIGUOUS config the operator must fix.
  *   unknown-name     — an explicit `--source <name>` that matched no catalog entry.
+ *
+ * confirm-default vs needs-selection: BOTH defer a run-time ASK, but confirm-default
+ * carries a PRESELECTED default (a yes/no confirm) whereas needs-selection has none (an
+ * open pick). Both are bindable-in-principle; the distinction drives the ASK shape.
  */
 export type SourceBinding =
   | { kind: "bound"; source: GlobalSource }
+  | { kind: "confirm-default"; source: GlobalSource; sources: GlobalSource[] }
   | { kind: "none" }
   | { kind: "needs-selection"; sources: GlobalSource[] }
   | { kind: "multiple-defaults"; sources: GlobalSource[] }
@@ -128,6 +141,17 @@ export interface EvaluatorConfigResolved {
   evaluatorContext: ContextLink[];
   /** present targets (evaluator is judge-only — carried for completeness only). */
   targets: GlobalTarget[];
+  /** PRD R-4 — the admin default render audience for the evaluation report. Client-by-default
+   *  (leak-safe); an admin sets `internal` in config.yaml to show the §5 Self-Eval tab. */
+  defaultAudience: "client" | "internal";
+}
+
+/** PRD R-4 — resolve the effective render audience: explicit flag → config → "client". */
+export function resolveEvalAudience(
+  explicit: "client" | "internal" | undefined,
+  config?: { defaultAudience?: "client" | "internal" } | undefined,
+): "client" | "internal" {
+  return explicit ?? config?.defaultAudience ?? "client";
 }
 
 export type LoadEvaluatorConfigResult =
@@ -142,14 +166,16 @@ export type LoadEvaluatorConfigResult =
  *
  *   1. explicit `selectName` (`--source`) WINS — find by name; miss ⇒ `unknown-name`.
  *   2. 0 sources                  ⇒ `none`.
- *   3. 1 source                   ⇒ `bound` (auto-bind).
+ *   3. 1 source                   ⇒ `bound` (auto-bind — no ambiguity, no prompt).
  *   4. >1 sources:
- *        exactly one `default:true` ⇒ `bound` (silent default).
+ *        exactly one `default:true` ⇒ `confirm-default` (F2 — preselected default; caller
+ *                                     CONFIRMS before use, not a silent bind).
  *        >1 `default:true`          ⇒ `multiple-defaults` (ambiguous — operator fixes config).
- *        0  `default:true`          ⇒ `needs-selection` (caller PROMPTS the operator).
+ *        0  `default:true`          ⇒ `needs-selection` (caller PROMPTS the operator — open pick).
  *
- * Pure; no clock/random/network. NON-fatal on `needs-selection` — the source
- * exists, only the disambiguation pick is deferred to the run-start ASK.
+ * Pure; no clock/random/network. NON-fatal on `confirm-default`/`needs-selection` —
+ * the source exists; only the disambiguation confirm/pick is deferred to the run-start ASK.
+ * `--source` (explicit) always short-circuits both, satisfying the non-interactive/CI escape.
  */
 function bindSourceByRole(
   sources: GlobalSource[],
@@ -167,7 +193,11 @@ function bindSourceByRole(
   if (sources.length === 1) return { kind: "bound", source: sources[0] as GlobalSource };
   // (4) — multiple entries; disambiguate by `default:true`.
   const defaults = sources.filter((s) => s.default === true);
-  if (defaults.length === 1) return { kind: "bound", source: defaults[0] as GlobalSource };
+  // F2: a lone default is PRESELECTED but CONFIRMED (be explicit around ambiguity) —
+  // it is NOT silently bound. The caller (parent session) issues a yes/no confirm ask.
+  if (defaults.length === 1) {
+    return { kind: "confirm-default", source: defaults[0] as GlobalSource, sources };
+  }
   if (defaults.length > 1) return { kind: "multiple-defaults", sources };
   return { kind: "needs-selection", sources };
 }
@@ -266,6 +296,11 @@ export function loadEvaluatorConfig(
     typeof evaluatorSection.judge_runtime === "string" && evaluatorSection.judge_runtime !== ""
       ? evaluatorSection.judge_runtime
       : undefined;
+  // PRD R-4 — admin audience override. Precedence: lifecycle.evaluator.default_audience >
+  // global.default_audience > "client". Only "internal" flips it; anything else stays client.
+  const rawAudience =
+    evaluatorSection.default_audience ?? globalBlock.default_audience;
+  const defaultAudience: "client" | "internal" = rawAudience === "internal" ? "internal" : "client";
 
   return {
     status: "ok",
@@ -278,6 +313,7 @@ export function loadEvaluatorConfig(
       globalContext,
       evaluatorContext,
       targets,
+      defaultAudience,
     },
   };
 }

package/.claude/skills/mutagent-evaluator/scripts/config/schema.ts

@@ -45,7 +45,12 @@ export const LEGACY_CONFIG_VERSIONS = ["0.1.0"] as const;
 
 // ── Categorical constants (no magic strings — coding-rules) ──────────────────
 
-/** Source platforms a `global.sources[]` entry can pull traces from. */
+/**
+ * Source platforms a `global.sources[]` entry can pull traces from.
+ * CONSUMER: the trace-fetch layer (`mutagent-cli trace fetch`, run by Helix BEFORE
+ * dispatch — the evaluator never fetches) selects the adapter by this value.
+ * PURPOSE: names WHERE the subject's traces live so they can be normalized to UniTF.
+ */
 export const SourcePlatform = {
   Langfuse: "langfuse",
   Otel: "otel",
@@ -56,12 +61,21 @@ export const SourcePlatform = {
 export type SourcePlatformValue =
   (typeof SourcePlatform)[keyof typeof SourcePlatform];
 
-/** Normalizer format hint for a source (how to parse the records). */
+/**
+ * Normalizer format hint for a source (how to parse the records).
+ * CONSUMER: the trace-fetch/normalize layer (`@mutagent/tools` adapters) — picks the
+ * parser for a source's records. PURPOSE: disambiguates record shape within a platform.
+ *   `unitf` (F1) — the records are ALREADY conformant UniTF jsonl (e.g. emitted by the
+ *   code-run capture WRAP, `captureUniTF` in `@mutagent/tools`). The fetch layer then
+ *   SKIPS per-platform normalization and reads the jsonl DIRECTLY. Pairs with
+ *   `platform: local-jsonl` + `paths:[…]`. PARITY PORT of the orchestrator's SourceFormat.
+ */
 export const SourceFormat = {
   LangfuseExport: "langfuse-export",
   ClaudeCode: "claude-code",
   Codex: "codex",
   Raw: "raw",
+  Unitf: "unitf",
 } as const;
 export type SourceFormatValue = (typeof SourceFormat)[keyof typeof SourceFormat];
 
@@ -137,7 +151,16 @@ export const ContextLinkSchema = Type.Object(
 );
 export type ContextLink = Static<typeof ContextLinkSchema>;
 
-/** The default model + the pinned judge model (`judge_model` — was `pinned_judge`). */
+/**
+ * The default model + the pinned judge model (`judge_model` — was `pinned_judge`).
+ * CONSUMER: config/load.ts `resolveJudgeModel` → prep.ts `--model` gap-fill.
+ *   default     — the project-wide fallback judge model. PURPOSE: used ONLY when
+ *                 `judge_model` is absent (`from: "default"`). ASYMMETRY: diagnostics
+ *                 IGNORES `models.default` for its judge (it pins its own) — the field
+ *                 is a shared config key that the two skills consume differently.
+ *   judge_model — the C-PIN pinned judge (model-intent-sacred; temp pinned 0). PURPOSE:
+ *                 the authoritative judge model; wins over `default` (`from: "judge_model"`).
+ */
 export const ModelsSchema = Type.Object(
   {
     default: Type.Optional(Type.String({ minLength: 1 })),
@@ -154,7 +177,10 @@ export type Models = Static<typeof ModelsSchema>;
  */
 export const GlobalSourceSchema = Type.Object(
   {
+    // name — the catalog key. CONSUMER: config/load.ts `bindSourceByRole` (matched by
+    // `--source <name>`) + prep.ts surface messages. PURPOSE: stable id for selection.
     name: Type.String({ minLength: 1 }),
+    // platform — see SourcePlatform. CONSUMER: the fetch/normalize adapter selector.
     platform: Type.Union([
       Type.Literal(SourcePlatform.Langfuse),
       Type.Literal(SourcePlatform.Otel),
@@ -162,19 +188,34 @@ export const GlobalSourceSchema = Type.Object(
       Type.Literal(SourcePlatform.ClaudeCode),
       Type.Literal(SourcePlatform.Codex),
     ]),
+    // project — remote-source project/scope id. CONSUMER: the remote fetch adapter
+    // (e.g. Langfuse project). PURPOSE: scopes a pull on a multi-project backend.
     project: Type.Optional(Type.String({ minLength: 1 })),
+    // endpoint — remote base URL. CONSUMER: the remote fetch adapter. PURPOSE: where to
+    // pull from (mutually exclusive with `paths`; onboarding enforces, schema tolerates).
     endpoint: Type.Optional(Type.String({ minLength: 1 })),
+    // credential_ref — env-var NAME / {env,path} (NEVER a secret). CONSUMER: resolve-
+    // credential.ts at fetch-time. PURPOSE: names the key for a remote pull.
     credential_ref: Type.Optional(CredentialRefSchema),
+    // paths — file-source globs. CONSUMER: the local-jsonl fetch adapter. PURPOSE: the
+    // on-disk jsonl location (pairs with `platform: local-jsonl`; see `format: unitf`).
     paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    // format — see SourceFormat. CONSUMER: the normalize step (`unitf` ⇒ skip normalize,
+    // read jsonl direct). PURPOSE: record-shape hint within a platform.
     format: Type.Optional(
       Type.Union([
         Type.Literal(SourceFormat.LangfuseExport),
         Type.Literal(SourceFormat.ClaudeCode),
         Type.Literal(SourceFormat.Codex),
         Type.Literal(SourceFormat.Raw),
+        Type.Literal(SourceFormat.Unitf),
       ]),
     ),
+    // agent_field — record path naming the agent/subject. CONSUMER: the normalizer's
+    // subject-grouping. PURPOSE: which field identifies the agent when a trace is multi-agent.
     agent_field: Type.Optional(Type.String({ minLength: 1 })),
+    // latency_unit — see LatencyUnit (`auto` = infer). CONSUMER: the normalizer's
+    // latency projection. PURPOSE: overrides ambiguous ms-vs-s latency records.
     latency_unit: Type.Optional(
       Type.Union([
         Type.Literal(LatencyUnit.Auto),
@@ -182,16 +223,23 @@ export const GlobalSourceSchema = Type.Object(
         Type.Literal(LatencyUnit.S),
       ]),
     ),
-    // PARITY (orchestrator SourceSchema): the catalog's DEFAULT pick when >1 entry
-    // exists — the selection contract's silent-bind marker (exactly one `default:true`
-    // ⇒ auto-bind, skipping the disambiguation prompt). Optional: absent ⇒ no default.
+    // default — PARITY (orchestrator SourceSchema): the catalog's DEFAULT pick when >1
+    // entry exists. CONSUMER: config/load.ts `bindSourceByRole` — exactly one `default:true`
+    // ⇒ `confirm-default` (F2: preselected, operator confirms), not a silent bind. PURPOSE:
+    // marks the preferred source among many. Optional: absent ⇒ no default.
     default: Type.Optional(Type.Boolean()),
   },
   { additionalProperties: false },
 );
 export type GlobalSource = Static<typeof GlobalSourceSchema>;
 
-/** A precise link to an Agent / Tooling definition file in a code target. */
+/**
+ * A precise link to an Agent / Tooling definition file in a code target.
+ * RESERVED — consumed by Build/Improve (future). The evaluator is JUDGE-ONLY (EV-051)
+ * and never writes a target; `targets[].code_refs` is ported for shape parity only and
+ * has NO evaluator consumer today. PURPOSE (future): tells BUILD/IMPROVE which files
+ * realize the agent so a fix lands on the right def.
+ */
 export const CodeRefSchema = Type.Object(
   {
     path: Type.String({ minLength: 1 }),
@@ -201,7 +249,14 @@ export const CodeRefSchema = Type.Object(
 );
 export type CodeRef = Static<typeof CodeRefSchema>;
 
-/** HOW a fix is applied for a target. `kind` gates the report-only branch. */
+/**
+ * HOW a fix is applied for a target. `kind` gates the report-only branch.
+ * CONSUMER: the diagnostics APPLY path (not the evaluator — judge-only). PURPOSE:
+ * selects the write mechanism for a fix.
+ *   versioning / pr — RESERVED, consumed by Build/Improve (future). No evaluator
+ *                     consumer; ported for parity. PURPOSE (future): toggle spec-bump /
+ *                     open-a-PR on apply.
+ */
 export const ApplySchema = Type.Object(
   {
     kind: Type.Union([

package/.claude/skills/mutagent-evaluator/scripts/load-bundle.ts

@@ -31,7 +31,7 @@ export const WELL_KNOWN_ARTIFACTS: Readonly<Record<string, string>> = {
   tracesMetadata: "traces-metadata.json",
   entityContext: "entity-context.json",
   renderInput: "render-input.json",
-  report: "report.html",
+  report: "evaluation-report.html",
 };
 
 /** Logical names whose VALUE is a sub-directory of evidence files. */

package/.claude/skills/mutagent-evaluator/scripts/persist-eval-criteria.ts

@@ -0,0 +1,232 @@
+/**
+ * scripts/persist-eval-criteria.ts — the EVAL-LEG on-disk WRITER (Wave-2 FU57 · KP-003).
+ * ---------------------------------------------------------------------------
+ * The IO half of the eval-leg reconcile. `sync-eval-criteria.ts` COMPUTES the grown
+ * criteria set as DATA (`reconcileEvalCriteria` — pure upsert-by-id, monotonic, never
+ * drops); it never touches disk. This module is the deterministic WRITER the evaluator
+ * SESSION calls to PERSIST that computed set back to the located eval-suite criteria
+ * artifact — the write that bumps the artifact's freshness and thereby returns the eval
+ * leg of `#sync-spec` to `in-sync` (the builder freshness probe reads the artifact's
+ * mtime / `updatedAt`; a fresh write makes the eval criteria as new as the amended impl).
+ *
+ * SEPARATION OF CONCERNS (mirrors `artifact-paths.ts` + `aggregate-discover.ts` doing IO
+ * while `living-suite.ts` stays pure): the reconcile COMPUTE is pure/C-PIN; this WRITE is
+ * the IO layer. The SERIALIZATION here is still deterministic (stable key order, no clock
+ * embedded unless the caller passes an explicit `updatedAt`), so a persisted artifact
+ * round-trips byte-faithful.
+ *
+ * JUDGE-ONLY PRESERVED (EV-051): this file writes CRITERIA (the evaluator maintaining its
+ * own eval-suite / code-quality criteria set) — it NEVER scores a subject, NEVER decides a
+ * pass/fail, and NEVER dispatches an agent (Model-B: code is a deterministic writer; the
+ * reconcile REASONING is the ai-architect's, session-dispatched).
+ *
+ * LOCATION + FORMAT (mirror the living-suite persistence; FLAGGED-for-operator, see
+ * `EVAL_CRITERIA_ARTIFACT_FILENAMES`): the artifact lands under the evaluator's namespaced
+ * `.mutagent/evaluator/living-suite/` root (`artifact-paths.ts` `livingSuiteDir`, auto-
+ * gitignored, no-spillover-guarded) as one JSON file per LEG — the same dir + extension the
+ * builder `check-sync-spec.ts` `locateEvalCriteria` auto-discovers.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type Static, Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+
+import { assertUnderRoot, livingSuiteDir } from "./artifact-paths.ts";
+import {
+  EvalCriterionSchema,
+  EvalLegKind,
+  reconcileEvalCriteria,
+  type EvalCriteriaReconcileRequest,
+  type EvalCriteriaReconcileResult,
+  type EvalCriterion,
+  type EvalLegKindValue,
+} from "./sync-eval-criteria.ts";
+
+// ── the on-disk artifact shape (mirror LivingSuite `{ …, provenance }`) ───────
+
+/**
+ * The persisted eval-criteria artifact — one per LEG. Mirrors the living-suite shape
+ * (a keyed collection + provenance), specialized to the reconcile result: the maintained
+ * `criteria` set, the reconcile `provenance` counters, and an OPTIONAL `updatedAt`
+ * freshness marker. `updatedAt` is the ONE clock-bearing field and it is NEVER generated
+ * here — the caller (the session, Model-B) passes it when it wants a content-level
+ * freshness stamp the builder probe's `parseEvalUpdatedAt` can read; omitted, freshness
+ * rides on the file's mtime alone (write bumps it). `additionalProperties: false` keeps the
+ * header tight while each criterion stays forward-parsing (EvalCriterionSchema is open).
+ */
+export const EvalCriteriaArtifactSchema = Type.Object(
+  {
+    subjectId: Type.String({ minLength: 1 }),
+    leg: Type.Union([
+      Type.Literal(EvalLegKind.EvalSuite),
+      Type.Literal(EvalLegKind.CodeQuality),
+    ]),
+    criteria: Type.Array(EvalCriterionSchema),
+    provenance: Type.Object(
+      { added: Type.Number(), updated: Type.Number(), total: Type.Number() },
+      { additionalProperties: false },
+    ),
+    updatedAt: Type.Optional(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+export type EvalCriteriaArtifact = Static<typeof EvalCriteriaArtifactSchema>;
+
+/**
+ * FLAGGED-for-operator: the per-leg artifact FILENAME under `.mutagent/evaluator/living-suite/`.
+ * The sensible default that mirrors the living-suite location AND the builder probe's
+ * conventional fallback names (`eval-criteria` / `code-quality-criteria`), one file per leg
+ * so the two legs never collide. Both are `.json` under the dir `check-sync-spec.ts`
+ * `locateEvalCriteria` walks (`*.{yaml,yml,json}`), so a written artifact is auto-discovered
+ * as the eval-leg freshness anchor with no extra wiring. (A workspace evaluates ONE subject,
+ * so only its leg's file exists; multi-subject-per-workspace would want a `<subjectId>/`
+ * sub-dir — deferred, flagged.)
+ */
+export const EVAL_CRITERIA_ARTIFACT_FILENAMES: Readonly<Record<EvalLegKindValue, string>> = {
+  [EvalLegKind.EvalSuite]: "eval-suite.criteria.json",
+  [EvalLegKind.CodeQuality]: "code-quality.criteria.json",
+};
+
+/**
+ * Resolve the located eval-criteria artifact path for a leg:
+ * `<cwd>/.mutagent/evaluator/living-suite/<leg>.criteria.json`. Routes through the
+ * `artifact-paths.ts` no-spillover guard (`assertUnderRoot`), so the writer can NEVER
+ * escape the evaluator's namespaced root. `cwd` passed in (pure path construction).
+ */
+export function evalCriteriaArtifactPath(leg: EvalLegKindValue, cwd?: string): string {
+  return assertUnderRoot(join(livingSuiteDir(cwd), EVAL_CRITERIA_ARTIFACT_FILENAMES[leg]), cwd);
+}
+
+// ── serialize / build (pure, deterministic — no clock) ───────────────────────
+
+/** Build the on-disk artifact from a reconcile RESULT. Pure. `updatedAt` passed in. */
+export function evalCriteriaArtifactFromResult(
+  result: EvalCriteriaReconcileResult,
+  updatedAt?: string,
+): EvalCriteriaArtifact {
+  return {
+    subjectId: result.subjectId,
+    leg: result.leg,
+    criteria: result.criteria,
+    provenance: result.provenance,
+    ...(updatedAt !== undefined ? { updatedAt } : {}),
+  };
+}
+
+/**
+ * Serialize an artifact to its on-disk JSON — DETERMINISTIC: explicit key order, 2-space
+ * indent, trailing newline. Same artifact → byte-identical string (round-trip faithful);
+ * no clock unless the artifact already carries a caller-supplied `updatedAt`.
+ */
+export function serializeEvalCriteriaArtifact(artifact: EvalCriteriaArtifact): string {
+  const ordered: EvalCriteriaArtifact = {
+    subjectId: artifact.subjectId,
+    leg: artifact.leg,
+    criteria: artifact.criteria,
+    provenance: artifact.provenance,
+    ...(artifact.updatedAt !== undefined ? { updatedAt: artifact.updatedAt } : {}),
+  };
+  return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+
+/** Guarded parse of a persisted artifact. THROWS with the first schema error. PURE. */
+export function parseEvalCriteriaArtifact(value: unknown): EvalCriteriaArtifact {
+  if (!Value.Check(EvalCriteriaArtifactSchema, value)) {
+    const first = [...Value.Errors(EvalCriteriaArtifactSchema, value)][0];
+    throw new Error(
+      `parseEvalCriteriaArtifact: schema violation at '${first?.path ?? "(root)"}': ` +
+        `${first?.message ?? "invalid eval-criteria artifact"}`,
+    );
+  }
+  return value;
+}
+
+// ── the WRITER + reader (the IO layer) ───────────────────────────────────────
+
+/** The result of a persist: WHERE it landed + WHAT was written (artifact + bytes). */
+export interface PersistEvalCriteriaResult {
+  /** the located artifact path the criteria were written to. */
+  path: string;
+  /** the artifact that was serialized. */
+  artifact: EvalCriteriaArtifact;
+  /** the exact bytes written (for a byte-faithful round-trip assertion). */
+  json: string;
+}
+
+/**
+ * PERSIST a reconcile result's `criteria` back to the located eval-suite criteria artifact
+ * — the WRITE that returns the eval leg to `in-sync`. Resolves the per-leg path under
+ * `.mutagent/evaluator/living-suite/` (no-spillover-guarded via `artifact-paths.ts`),
+ * ensures the dir, and writes the deterministic JSON. Handles BOTH legs by `result.leg`:
+ * the eval-suite leg (agent/skill/composite subject) and the code-quality leg (a code
+ * subject, incl. an operator-overridden code-quality set). The freshness bump is the file
+ * write itself (mtime advances → the builder probe reads the eval leg as fresh); pass
+ * `options.updatedAt` (ISO 8601) to ALSO stamp a content-level freshness marker the probe's
+ * `parseEvalUpdatedAt` reads. IO — NOT pure (that is its job); serialization is deterministic.
+ */
+export function persistEvalCriteria(
+  result: EvalCriteriaReconcileResult,
+  options: { cwd?: string; updatedAt?: string } = {},
+): PersistEvalCriteriaResult {
+  const artifact = evalCriteriaArtifactFromResult(result, options.updatedAt);
+  const path = evalCriteriaArtifactPath(result.leg, options.cwd);
+  const json = serializeEvalCriteriaArtifact(artifact);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, json);
+  return { path, artifact, json };
+}
+
+/** Read + validate a persisted artifact (round-trip). THROWS on a schema violation. */
+export function readEvalCriteriaArtifact(path: string): EvalCriteriaArtifact {
+  return parseEvalCriteriaArtifact(JSON.parse(readFileSync(path, "utf8")) as unknown);
+}
+
+/**
+ * Load the CURRENTLY-persisted criteria for a leg (the `existing` set the next reconcile
+ * grows). Returns `[]` when no artifact exists yet (the cold / first-reconcile case) so a
+ * caller can feed it straight into an `EvalCriteriaReconcileRequest.existing`. Reads only.
+ */
+export function loadExistingEvalCriteria(leg: EvalLegKindValue, cwd?: string): EvalCriterion[] {
+  const path = evalCriteriaArtifactPath(leg, cwd);
+  if (!existsSync(path)) return [];
+  return readEvalCriteriaArtifact(path).criteria;
+}
+
+/**
+ * The eval-criteria artifact's effective freshness epoch (seconds) — the evaluator-side
+ * MIRROR of the builder `check-sync-spec.ts` eval-leg compare: `max(updatedAt, mtime)`
+ * (git omitted — kept in-package + git-independent). `null` when the artifact is absent.
+ * Feed this as `evalCriteriaEpoch` to `flagEvalLegDrift` to confirm a fresh write closed
+ * the loop (`in-sync`). Reads mtime (IO).
+ */
+export function evalCriteriaEffectiveEpoch(path: string): number | null {
+  if (!existsSync(path)) return null;
+  const epochs: number[] = [];
+  try {
+    const parsed = readEvalCriteriaArtifact(path);
+    if (parsed.updatedAt !== undefined) {
+      const ms = Date.parse(parsed.updatedAt);
+      if (Number.isFinite(ms)) epochs.push(Math.floor(ms / 1000));
+    }
+  } catch {
+    // a corrupt artifact still has an mtime — fall back to it for freshness.
+  }
+  epochs.push(Math.floor(statSync(path).mtimeMs / 1000));
+  return Math.max(...epochs);
+}
+
+/**
+ * Convenience for the session: COMPUTE the reconcile (pure) THEN PERSIST it (IO) in one
+ * call — the exact "reconcile → write → in-sync" step the `#sync-spec` eval leg performs.
+ * Still Model-B: the criteria DELTA (`request.proposed`) is the ai-architect's reasoning;
+ * this only applies it deterministically and writes it. Returns the compute result + the
+ * persist result together.
+ */
+export function reconcileAndPersistEvalCriteria(
+  request: EvalCriteriaReconcileRequest,
+  options: { cwd?: string; updatedAt?: string } = {},
+): { result: EvalCriteriaReconcileResult; persisted: PersistEvalCriteriaResult } {
+  const result = reconcileEvalCriteria(request);
+  const persisted = persistEvalCriteria(result, options);
+  return { result, persisted };
+}

package/.claude/skills/mutagent-evaluator/scripts/render-discover-report.ts

@@ -1566,7 +1566,7 @@ export function writeDiscoverRunReport(
   return writeDiscoverReportFromFiles(
     {
       criteriaPath: join(dir, "criteria.json"),
-      outPath: join(dir, "report.html"),
+      outPath: join(dir, "discovery-report.html"),
       groundingPath: join(dir, "grounding-check.json"),
       triagePath: triageSummaryPath,
       verdictsDir: join(dir, "verdicts"),

package/.claude/skills/mutagent-evaluator/scripts/render-eval-report.ts

@@ -358,6 +358,9 @@ export interface CriterionResolution {
 
 export interface EvalReportInput {
   subject: { name: string; org?: string; source?: string; models?: string[] };
+  /** PRD R-4 — render audience. Default "client" (leak-safe): the §5 Self-Eval [INTERNAL]
+   *  tab + nav button are NOT emitted. "internal" (admin opt-in) shows them. */
+  audience?: "client" | "internal";
   /** the v2 *evaluate Scorecard (GATE + variance). */
   scorecard: Scorecard;
   /** the folded per-criterion verdicts. */
@@ -3479,6 +3482,16 @@ export function renderEvalReport(input: EvalReportInput): string {
   const theme = readFileSync(join(BRAND_DIR, "theme.css"), "utf8");
   const wordmark = readFileSync(join(BRAND_DIR, "wordmark.html"), "utf8");
 
+  // PRD R-4 — audience gate. CLIENT is the DEFAULT (leak-safe): the §5 Self-Eval [INTERNAL]
+  // tab + nav button are NOT emitted into the HTML at all (NODE-STRIP, not CSS-hidden).
+  const internal = (input.audience ?? "client") === "internal";
+  const selfEvalNav = internal
+    ? `  <button class="tab-btn internal" data-tab="t5">⑤ Self-Eval [INTERNAL]</button>\n`
+    : "";
+  const selfEvalPanel = internal
+    ? `  <section class="panel" id="t5">${selfEvalTab(input)}</section>\n`
+    : "";
+
   const headerTitle = "evaluator · Eval Report";
   const headerMeta =
     `<span class="mk">subject</span> <span class="mv">${esc(input.subject.name)}</span>` +
@@ -3564,15 +3577,13 @@ ${header}
   <button class="tab-btn" data-tab="t2">② Trajectory · Judge Behaviour</button>
   <button class="tab-btn" data-tab="t3">③ Eval Scorecard</button>
   <button class="tab-btn" data-tab="t4">④ Findings</button>
-  <button class="tab-btn internal" data-tab="t5">⑤ Self-Eval [INTERNAL]</button>
-</nav>
+${selfEvalNav}</nav>
 <main>
   <section class="panel active" id="t1">${overviewTab(input)}</section>
   <section class="panel" id="t2">${trajectoryTab(input)}</section>
   <section class="panel" id="t3">${scorecardTab(input)}</section>
   <section class="panel" id="t4">${findingsTab(input)}</section>
-  <section class="panel" id="t5">${selfEvalTab(input)}</section>
-</main>
+${selfEvalPanel}</main>
 <script data-pii="ledger">
 ${clientScript(ledgerJson, critJson, walksJson, resMetaJson)}
 </script>
@@ -3635,6 +3646,8 @@ export function writeEvalReportFromFiles(
      *  one trace off the raw ndjson and passes it here; the system prompt is identical
      *  across the batch so one trace suffices. ABSENT ⇒ system prompt stays UNAVAILABLE. */
     traces?: EvalTrace[];
+    /** PRD R-4 — render audience (default "client", leak-safe). "internal" shows §5. */
+    audience?: "client" | "internal";
   },
   io: EvalReportFilesIO,
 ): { report: string; completeness: EvalReportCompleteness } {
@@ -3746,6 +3759,8 @@ export function writeEvalReportFromFiles(
     // WS-6 — forward the trace(s) so the system prompt is reconstructed for the hero.
     ...(params.traces !== undefined ? { traces: params.traces } : {}),
   });
+  // PRD R-4 — set audience on the built input (buildEvalReportInput does not forward it).
+  if (params.audience !== undefined) input.audience = params.audience;
   io.writeFile(params.outPath, renderEvalReport(input));
 
   // 5) the data-completeness probe over the BOUND ledger (what the UI will render).
@@ -3803,9 +3818,9 @@ async function main(): Promise<void> {
   const { join: pjoin } = await import("node:path");
   const input = JSON.parse(rf(inputPath, "utf8")) as EvalReportInput;
   // P8: a bare run DEFAULTS the report under the localized dot-root
-  // `.mutagent/evaluator/reports/<runId>/report.html` (never /tmp or .memory).
+  // `.mutagent/evaluator/reports/<runId>/evaluation-report.html` (never /tmp or .memory).
   const runId = runIdArg ?? input.subject.name;
-  const outPath = outArg ?? pjoin(reportDir(runId), "report.html");
+  const outPath = outArg ?? pjoin(reportDir(runId), "evaluation-report.html");
   mkdirSync(pjoin(outPath, ".."), { recursive: true });
   console.info(renderEvalCards(input));
   writeFileSync(outPath, renderEvalReport(input));

package/.claude/skills/mutagent-evaluator/scripts/route-failures.ts

@@ -40,7 +40,13 @@ export const AdlStage = {
 } as const;
 export type AdlStageValue = (typeof AdlStage)[keyof typeof AdlStage];
 
-export const SubjectKind = { Skill: "skill", Agent: "agent" } as const;
+// Mirrors the orchestrator handover-contract SubjectKind. The CANONICAL inter-stage
+// subject vocabulary is `agent | skill | code` (matches config-schema TargetSubject).
+// `code` (Wave-2 follow-up) is ADDITIVE — every existing skill/agent handoff still
+// validates; it only lets a `code` subject route through *evaluate's failure handoff
+// the SAME way it flows through the orchestrator handover-contract (the two are kept
+// in lock-step by design; the evaluator re-implements the shape, never imports it).
+export const SubjectKind = { Skill: "skill", Agent: "agent", Code: "code" } as const;
 export type SubjectKindValue = (typeof SubjectKind)[keyof typeof SubjectKind];
 
 export const ArtifactKind = {
@@ -67,7 +73,11 @@ export type EscalationPolicyValue =
 // ── TypeBox schemas (closed objects — auditable boundary) ───────────────────
 const SubjectSchema = Type.Object(
   {
-    kind: Type.Union([Type.Literal(SubjectKind.Skill), Type.Literal(SubjectKind.Agent)]),
+    kind: Type.Union([
+      Type.Literal(SubjectKind.Skill),
+      Type.Literal(SubjectKind.Agent),
+      Type.Literal(SubjectKind.Code),
+    ]),
     name: Type.String({ minLength: 1 }),
     path: Type.String({ minLength: 1 }),
   },