@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/memory/append.ts

@@ -0,0 +1,215 @@
+/**
+ * scripts/memory/append.ts — project-level AutoMemory: APPEND (dated + classified).
+ * ---------------------------------------------------------------------------
+ * Append an operator-feedback entry to the project-level AutoMemory store
+ * (`.mutagent/memory/`) in the Claude-Code AutoMemory format
+ * (`references/memory-format.md`). The SUBJECT is the TOOL + operator preferences
+ * — NOT the evaluated agent (subject findings go to the living-suite, never here).
+ *
+ * The store: one FACT per `<slug>.md` file + an index `MEMORY.md`
+ * (`- [Title](<slug>.md) — <hook>` one line/entry). Every entry is DATED
+ * (`metadata.created`) + lifecycle-tagged. DEDUPE on append: an entry with the
+ * same slug is UPDATED (body + refreshed date), never duplicated.
+ *
+ * Determinism (coding-rules): the CORES are PURE — `now` (the date) is INJECTED,
+ * never read from a clock; fs is done only in the thin writer at the bottom. Tests
+ * exercise the pure cores with a fixed `now`. Standalone: no cross-skill import
+ * (mirrors the diagnostics library-store APPEND DISCIPLINE, not its per-entity
+ * keying — this store is flat + tool-scoped).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Categorical constants (no magic strings) ─────────────────────────────────
+
+/** Claude Code's four memory types (the classification target). */
+export const MemoryType = {
+  User: "user",
+  Feedback: "feedback",
+  Project: "project",
+  Reference: "reference",
+} as const;
+export type MemoryTypeValue = (typeof MemoryType)[keyof typeof MemoryType];
+
+/** The ADL lifecycle tag (the recall filter axis). */
+export const Lifecycle = {
+  Spec: "spec",
+  Build: "build",
+  Evaluate: "evaluate",
+  Diagnose: "diagnose",
+  Improve: "improve",
+  General: "general",
+} as const;
+export type LifecycleValue = (typeof Lifecycle)[keyof typeof Lifecycle];
+
+// ── Classification (the memory-format.md rubric — first match wins) ───────────
+
+/** The raw operator feedback to classify + persist. */
+export interface FeedbackInput {
+  /** the fact to store (verbatim operator text or a distilled summary). */
+  text: string;
+  /** optional caller hint (a URL / path) — strengthens the `reference` signal. */
+  resourceHint?: string;
+}
+
+/**
+ * Classify feedback into one of the four Claude-Code types by the memory-format.md
+ * decision order (FIRST match wins): reference → user → feedback → project. PURE,
+ * deterministic — regex + explicit hint, no I/O, no LLM. A caller may OVERRIDE the
+ * classification explicitly (an operator who knows the type); this is the default.
+ */
+export function classifyFeedback(fb: FeedbackInput): MemoryTypeValue {
+  const t = fb.text.trim();
+  // 1 — external resource (URL / dashboard / ticket / dataset path).
+  if (
+    fb.resourceHint !== undefined ||
+    /\bhttps?:\/\/\S+/i.test(t) ||
+    /\b(?:dashboard|ticket|dataset|\S+\.(?:ndjson|jsonl|csv|parquet)(?:\.gz)?)\b/i.test(t)
+  ) {
+    return MemoryType.Reference;
+  }
+  // 2 — who the operator is (identity / standing preference about themselves).
+  if (/\bI['’]?m\b|\bI am\b|\bmy (?:role|team|preference)\b|\bas the (?:lead|operator|owner)\b/i.test(t)) {
+    return MemoryType.User;
+  }
+  // 3 — how the TOOL should behave (behavioral steer).
+  if (/\b(?:stop|don['’]?t|do not|too verbose|next time|always|never|prefer)\b/i.test(t)) {
+    return MemoryType.Feedback;
+  }
+  // 4 — ongoing work / goals / constraints (default).
+  return MemoryType.Project;
+}
+
+// ── Slug + entry formatting ───────────────────────────────────────────────────
+
+/** Kebab-case a title into a stable slug (deterministic — no random). */
+export function slugify(title: string): string {
+  const s = title
+    .toLowerCase()
+    .replace(/['’"]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return s === "" ? "untitled" : s;
+}
+
+export interface MemoryEntry {
+  /** kebab-case slug (the file name stem + `name:` frontmatter). */
+  slug: string;
+  /** one-line description (recall relevance). */
+  description: string;
+  type: MemoryTypeValue;
+  lifecycle: LifecycleValue;
+  /** YYYY-MM-DD (INJECTED — never a live clock). */
+  created: string;
+  /** the fact body (feedback/project carry **Why:** + **How to apply:** lines). */
+  body: string;
+}
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Render a MemoryEntry to its `<slug>.md` file text (Claude-Code AutoMemory format). */
+export function renderEntryMarkdown(entry: MemoryEntry): string {
+  if (!DATE_RE.test(entry.created)) {
+    throw new Error(
+      `renderEntryMarkdown: created must be YYYY-MM-DD (got '${entry.created}'). Every memory is DATED — ` +
+        "inject `now`, never read a clock.",
+    );
+  }
+  return (
+    "---\n" +
+    `name: ${entry.slug}\n` +
+    `description: ${entry.description}\n` +
+    "metadata:\n" +
+    `  type: ${entry.type}\n` +
+    `  lifecycle: ${entry.lifecycle}\n` +
+    `  created: ${entry.created}\n` +
+    "---\n\n" +
+    entry.body.trimEnd() +
+    "\n"
+  );
+}
+
+/** The one index line for an entry (`- [Title](<slug>.md) — <hook>`). */
+export function indexLine(entry: MemoryEntry): string {
+  return `- [${entry.slug}](${entry.slug}.md) — ${entry.description}`;
+}
+
+/**
+ * Fold an entry's index line into an existing `MEMORY.md`, DEDUPED by slug (an
+ * existing line for the same slug is REPLACED in place; a new slug is appended).
+ * PURE — string in, string out. Preserves a leading title/header block.
+ */
+export function upsertIndex(existingIndex: string, entry: MemoryEntry): string {
+  const newLine = indexLine(entry);
+  const lineRe = new RegExp(`^- \\[${entry.slug}\\]\\(${entry.slug}\\.md\\).*$`);
+  const lines = existingIndex.split("\n");
+  let replaced = false;
+  const out = lines.map((l) => {
+    if (lineRe.test(l)) {
+      replaced = true;
+      return newLine;
+    }
+    return l;
+  });
+  if (replaced) return out.join("\n");
+  // Append (ensure a header exists + trailing newline hygiene).
+  const base =
+    existingIndex.trim() === ""
+      ? "# AutoMemory — index\n\n> Project-level operator-feedback + tool self-learning. One line per entry.\n"
+      : existingIndex.replace(/\n*$/, "\n");
+  return base + newLine + "\n";
+}
+
+// ── Filesystem writer (the ONLY impure edge) ──────────────────────────────────
+
+export interface AppendResult {
+  slug: string;
+  entryFile: string;
+  indexFile: string;
+  /** true when an existing entry was UPDATED (dedupe hit) rather than created. */
+  updated: boolean;
+}
+
+/**
+ * Append (or UPDATE) an AutoMemory entry under `<memoryDir>/`. Writes the
+ * `<slug>.md` file + upserts the `MEMORY.md` index line. DEDUPE: an existing
+ * `<slug>.md` is overwritten (not duplicated) and its index line replaced.
+ * `now` (YYYY-MM-DD) is INJECTED. The pure cores above do the formatting; this is
+ * the thin fs edge.
+ */
+export function appendMemory(
+  memoryDir: string,
+  input: { title: string; description: string; lifecycle: LifecycleValue; feedback: FeedbackInput; type?: MemoryTypeValue },
+  now: string,
+): AppendResult {
+  const slug = slugify(input.title);
+  const type = input.type ?? classifyFeedback(input.feedback);
+  const entry: MemoryEntry = {
+    slug,
+    description: input.description,
+    type,
+    lifecycle: input.lifecycle,
+    created: now,
+    body: input.feedback.text.trim(),
+  };
+
+  mkdirSync(memoryDir, { recursive: true });
+  const entryFile = join(memoryDir, `${slug}.md`);
+  const updated = existsSync(entryFile);
+  writeFileSync(entryFile, renderEntryMarkdown(entry));
+
+  const indexFile = join(memoryDir, "MEMORY.md");
+  const existingIndex = existsSync(indexFile) ? readFileSync(indexFile, "utf8") : "";
+  writeFileSync(indexFile, upsertIndex(existingIndex, entry));
+
+  return { slug, entryFile, indexFile, updated };
+}
+
+/** List the entry slugs currently in a memory dir (PURE-ish fs read; [] if absent). */
+export function listEntrySlugs(memoryDir: string): string[] {
+  if (!existsSync(memoryDir)) return [];
+  return readdirSync(memoryDir)
+    .filter((f) => f.endsWith(".md") && f !== "MEMORY.md")
+    .map((f) => f.replace(/\.md$/, ""))
+    .sort();
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/memory/read.ts

@@ -0,0 +1,168 @@
+/**
+ * scripts/memory/read.ts — project-level AutoMemory: READ (filter by lifecycle).
+ * ---------------------------------------------------------------------------
+ * Read the project-level AutoMemory store (`.mutagent/memory/`) at run START and
+ * return the entries relevant to THIS stage. The evaluator reads entries whose
+ * `lifecycle ∈ {evaluate, general}` (the run-start injection surface). The subject
+ * is the TOOL + operator preferences — NOT the evaluated agent.
+ *
+ * Determinism (coding-rules): the PARSE + FILTER cores are PURE (string in, data
+ * out); fs is confined to `readMemoryDir`. Tests exercise the pure cores against
+ * committed fixture text. Standalone — no cross-skill import.
+ *
+ * Format: one FACT per `<slug>.md`, Claude-Code AutoMemory frontmatter
+ * (`references/memory-format.md`). A malformed / partial entry is SKIPPED (never
+ * throws) so one bad file can't blind a run.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  Lifecycle,
+  MemoryType,
+  type LifecycleValue,
+  type MemoryTypeValue,
+} from "./append.ts";
+
+export interface ParsedMemoryEntry {
+  slug: string;
+  description: string;
+  type: MemoryTypeValue;
+  lifecycle: LifecycleValue;
+  created: string;
+  body: string;
+}
+
+const LIFECYCLE_VALUES = new Set<string>(Object.values(Lifecycle));
+const TYPE_VALUES = new Set<string>(Object.values(MemoryType));
+
+/**
+ * Parse ONE `<slug>.md` entry (frontmatter + body). Returns null on a malformed /
+ * partial entry (missing frontmatter, unknown type/lifecycle, absent date) — a bad
+ * file is SKIPPED, never fatal. PURE — string in, entry out. `fallbackSlug` is the
+ * file stem, used when the `name:` field is absent.
+ */
+export function parseMemoryEntry(text: string, fallbackSlug: string): ParsedMemoryEntry | null {
+  const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+  if (m === null) return null;
+  const front = m[1] ?? "";
+  const body = (m[2] ?? "").trim();
+
+  const scalar = (key: string): string | undefined => {
+    // top-level `key: value` OR nested `  key: value` (metadata block).
+    const re = new RegExp(`^\\s*${key}:\\s*(.+?)\\s*$`, "m");
+    const mm = re.exec(front);
+    return mm ? (mm[1] as string).trim() : undefined;
+  };
+
+  const slug = scalar("name") ?? fallbackSlug;
+  const description = scalar("description") ?? "";
+  const type = scalar("type");
+  const lifecycle = scalar("lifecycle");
+  const created = scalar("created");
+
+  if (type === undefined || !TYPE_VALUES.has(type)) return null;
+  if (lifecycle === undefined || !LIFECYCLE_VALUES.has(lifecycle)) return null;
+  if (created === undefined || !/^\d{4}-\d{2}-\d{2}$/.test(created)) return null;
+
+  return {
+    slug,
+    description,
+    type: type as MemoryTypeValue,
+    lifecycle: lifecycle as LifecycleValue,
+    created,
+    body,
+  };
+}
+
+/**
+ * Keep only entries whose `lifecycle` is in `stages` (the recall filter). PURE.
+ * For the evaluator run start: `stages = [Evaluate, General]`.
+ */
+export function filterByLifecycle(
+  entries: ParsedMemoryEntry[],
+  stages: LifecycleValue[],
+): ParsedMemoryEntry[] {
+  const want = new Set<string>(stages);
+  return entries.filter((e) => want.has(e.lifecycle));
+}
+
+/** The default recall filter for an EVALUATE run: {evaluate, general}. */
+export const EVALUATE_RECALL: LifecycleValue[] = [Lifecycle.Evaluate, Lifecycle.General];
+
+export interface ReadMemoryResult {
+  exists: boolean;
+  /** entries matching the lifecycle filter, sorted by slug (deterministic). */
+  entries: ParsedMemoryEntry[];
+  /** files that failed to parse (skipped) — surfaced for honesty, never fatal. */
+  skipped: string[];
+}
+
+/**
+ * Read `<memoryDir>/*.md` (excluding the `MEMORY.md` index), parse each, and
+ * return the entries matching `stages` (default = EVALUATE_RECALL). A missing dir
+ * → `{ exists:false, entries:[] }`. A malformed file is SKIPPED (listed in
+ * `skipped`). Deterministic: entries sorted by slug. The ONLY impure edge.
+ */
+export function readMemoryDir(
+  memoryDir: string,
+  stages: LifecycleValue[] = EVALUATE_RECALL,
+): ReadMemoryResult {
+  if (!existsSync(memoryDir)) return { exists: false, entries: [], skipped: [] };
+
+  const files = readdirSync(memoryDir)
+    .filter((f) => f.endsWith(".md") && f !== "MEMORY.md")
+    .sort();
+
+  const parsed: ParsedMemoryEntry[] = [];
+  const skipped: string[] = [];
+  for (const f of files) {
+    const stem = f.replace(/\.md$/, "");
+    let text: string;
+    try {
+      text = readFileSync(join(memoryDir, f), "utf8");
+    } catch {
+      skipped.push(f);
+      continue;
+    }
+    const entry = parseMemoryEntry(text, stem);
+    if (entry === null) {
+      skipped.push(f);
+      continue;
+    }
+    parsed.push(entry);
+  }
+
+  return { exists: true, entries: filterByLifecycle(parsed, stages), skipped };
+}
+
+/**
+ * Render the recalled entries as a compact operator-preference context block for
+ * injection at run start (one bullet per entry: type · slug · description). PURE.
+ * EMPTY string when nothing recalled (a run with no AutoMemory is byte-identical
+ * to the legacy no-memory path).
+ */
+export function renderRecallContext(entries: ParsedMemoryEntry[]): string {
+  if (entries.length === 0) return "";
+  const bullets = entries
+    .map((e) => `- [${e.type}] ${e.slug} — ${e.description}`)
+    .join("\n");
+  return `AutoMemory (operator preferences · evaluate + general):\n${bullets}`;
+}
+
+// ── CLI — thin wrapper (print the recalled entries for a project root) ─────────
+// bun scripts/memory/read.ts [project-root]
+
+function memoryDirFor(projectRoot: string): string {
+  return join(projectRoot, ".mutagent", "memory");
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv = typeof Bun !== "undefined" ? Bun.argv : process.argv;
+  const projectRoot = argv[2] ?? process.cwd();
+  const result = readMemoryDir(memoryDirFor(projectRoot));
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(0);
+}

package/mutagent-evaluator/.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 };
+}