@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/references/write-judge-prompt.md

@@ -0,0 +1,123 @@
+# write-judge-prompt — design a binary LLM-as-judge for one criterion
+
+> **Source:** absorbed from `mutagent-system/.memory/features/evals-skills-source/skills/write-judge-prompt/SKILL.md`.
+> **Loaded by:** `*build-evals` (EV-043), executed by `assets/agents/evaluator.md` (`#mode-judge-criterion`; the trajectory axis loads it too). Load on demand.
+> **Sibling refs:** `error-analysis.md` (mine the criterion) · `validate-evaluator.md` (calibrate the judge) · `grounded-adjudication.md` (the GA doctrine: bind · gather refs · typed assumptions · abstain · verify).
+
+Design ONE binary Pass/Fail LLM-as-judge for ONE failure mode. Each judge checks exactly one thing.
+Use a judge ONLY for criteria a code-based check cannot handle — exhaust code-based options first
+(many "subjective" criteria reduce to keyword / regex / API checks once you understand the domain).
+
+## Prerequisites
+
+- Error analysis complete; the failure mode is identified (`*discover-evals`).
+- Human-labeled traces for this mode (≥20 Pass + ≥20 Fail).
+- A code-based evaluator genuinely cannot check it.
+
+## The 4 components (every judge prompt has exactly these)
+
+### 1. Task and evaluation criterion
+State what the judge evaluates — ONE failure mode per judge. Not "evaluate whether the email is
+good", not "rate quality 1-5". E.g. *"You are an evaluator assessing whether the agent respected the
+outbound-guard: when `<outbound_guard>` is present and the event is non-critical, it must NOT send."*
+
+### 2. Pass/Fail definitions
+Strictly **binary** — no Likert, no letter grades, no partial credit. Define exactly what
+constitutes Pass and Fail, drawn from the error-analysis failure-mode description. List concrete
+FAIL examples (e.g. "sent a routine nudge while `consecutive_outbound=11` and guard=CRITICAL").
+
+### 3. Few-shot examples
+Include labeled Pass + Fail examples — at least one clear Pass, one clear Fail, and one **borderline**
+case (borderline teaches the most nuance).
+- **Draw ONLY from the TRAIN split** (10-20% of labeled data set aside for this). Any example used
+  in the prompt MUST be excluded from dev/test — using dev/test examples is **data leakage**.
+- 2-4 examples is typical; performance plateaus after 4-8.
+
+### 4. Structured output — critique BEFORE verdict
+Enforce schema (provider `response_format` / tool definitions; or specify the JSON schema inline).
+The output puts the **critique first, verdict second** — this forces the judge to articulate its
+assessment before committing. Under Grounded Adjudication the verdict is **ternary** and carries the
+structured grounding it rests on:
+
+```json
+{
+  "critique": "string — detailed assessment vs the criterion, citing concrete evidence from the trace",
+  "refs": [{ "obs": "trace/observation id", "path": "field path", "value": "EXACT cited value" }],
+  "assumptions": [{ "text": "premise the trace did not establish", "kind": "factual-intent | normative | scope", "status": "hypothesis" }],
+  "result": "pass | fail | uncertain",
+  "confidence": 0.0,
+  "blockedBy": { "kind": "factual-intent | normative | scope", "text": "the unbound term / ungroundable premise" }
+}
+```
+
+- `result` is **ternary**: `pass` · `fail` · `uncertain`. `uncertain` (carrying a `blockedBy`) IS
+  the **indeterminate** state — it reuses `OutcomeVerdict.Uncertain`, **not** a 4th enum value.
+- `blockedBy` is REQUIRED whenever `result === "uncertain"` (an `uncertain` with no `blockedBy` is an
+  unrouted abstain — `lint-grounding` flags it).
+- `refs` are STRUCTURED + **re-resolvable** (`scripts/resolve-ref.ts` re-resolves each by
+  whitespace-normalized EXACT value match); cite one for the claim AND for any absence.
+
+Critiques must be detailed, not terse — the critiques in your few-shot examples set the bar for the
+detail the judge produces.
+
+## Grounded Adjudication — bind, gather, abstain, verify
+
+> Full doctrine in `references/grounded-adjudication.md` (the 5 Laws · the verdict lattice · the two
+> switches). The load-bearing additions for every judge prompt:
+
+- **BIND before you judge (L1).** Before rendering a verdict, every **TERM** the criterion
+  presupposes must resolve to a grounded referent IN THIS situation
+  (`scripts/resolve-ref.ts` `bindCriterionTerms` / `bindBeforeJudge`). An **unbound term** (a
+  referent the situation never established — e.g. *"on-topic with the advertiser's product"* over a
+  **blank brief**) ⇒ `result: uncertain` + `blockedBy: {kind: "factual-intent"}` — **ABSTAIN, never
+  fail.** A valid-yet-unbound criterion is not a defect of the trajectory. Refs check what you DID
+  cite; binding checks what the criterion NEEDED.
+- **GATHER grounded evidence (L2/L3).** Cite a structured `ref {obs, path, value}` for the claim AND
+  for any **absence** claim ("did not" / "never" / "no X" needs a positive field check, never
+  inferred from silence).
+- **The litmus.** State the **minimal premise P** such that `criterion ∧ situation ∧ P ⊢ V`. If P is
+  fully grounded (or in the deterministic floor), DECIDE. If P is ungroundable, **surface it as a
+  TYPED assumption** (`factual-intent` · `normative` · `scope`) and abstain (`uncertain` +
+  `blockedBy`). The leap from "claim is true" to "therefore fail" is exactly where the assumption
+  hides — a sourced claim proves the **claim**, never the **verdict**.
+- **Abstain on silence (L5).** `uncertain` when the **inputs** can't decide (indeterminate, routes
+  to the calibration loop) — not merely when YOU are unsure. Decide when the world establishes the
+  premises and only you were uncertain.
+- **The verdict is independently VERIFIED (L2 / GA-5).** After you decide, a DISTINCT reviewer
+  (`#mode-verify` — never the judge that decided; `scripts/result-verify.ts`) re-resolves your refs
+  and checks claim ⊨ verdict. On a dead ref or an inferential leap it **downgrades**
+  `pass/fail → uncertain(blockedBy)` — **downgrade-only**; it never flips `pass↔fail` and never
+  fixes (EV-051).
+
+## Choosing what to pass to the judge
+
+Feed only what the judge needs — for long inputs, the relevant snippet, not the whole document:
+
+| Failure mode | What the judge needs |
+|--------------|----------------------|
+| Tone mismatch | Client persona + generated message |
+| Answer faithfulness | Retrieved context + generated answer |
+| Instruction following | System-prompt rules + generated response |
+| Tool-call justification | Conversation history + tool call + tool result |
+| **Outbound-guard compliance (sample C1)** | Input prompt (guard + event) + tool trajectory + response |
+| **Goal-attainment (sample C2)** | Input event + full trajectory + outputs |
+
+## Model selection + C-PIN
+
+Start with the most capable model available (the same model as the main task works — the judge does
+a narrower task); optimize cost later, once alignment is confirmed. **Pin the model id + temperature=0**
+and record both on the scorecard (C-PIN) so reruns are byte-identical; re-validate on any model change.
+In this skill the judge call mirrors the proven `@langchain/google-genai` shape (lazy import, temp 0,
+model = `config.models.default`/`--model`, THROW on missing creds — model-intent-sacred).
+
+## Anti-patterns
+
+- **Vague criteria** ("is this helpful?") — target a specific observable failure mode.
+- **Holistic judge for the whole trace** — produces unactionable verdicts. One judge, one criterion.
+- **No few-shot examples** — the model won't know what counts as a failure in your application.
+- **Dev/test examples as few-shot** — data leakage.
+- **Likert scales** — scores that sound precise but can't be calibrated; binary forces a clear
+  decision boundary. Capture severity via MULTIPLE binary judges, not one ordinal scale.
+- **Skipping validation** — measure alignment with `validate-evaluator.md` before trusting the judge.
+- **Judges for specification failures without fixing the prompt first** — if the prompt never asked
+  for the behavior, that's a fix (route to diagnostics), not an eval.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/behavior-tree.schema.yaml

@@ -0,0 +1,73 @@
+# schemas/behavior-tree.schema.yaml
+# ============================================================================
+# The SHAPE of a behavior-tree: the GOLDEN behavioral spec for the pinned judge.
+#
+# Nodes = decision points carrying the EXPECTED decision per scenario
+# (signal-tier · confidence-basis · focus). Edges = forks. This enables the
+# generic engine's core comparison: at every known decision node, the judge
+# compares expected-decision vs observed-decision and expected-scenario vs
+# observed-scenario. Diagnostics' signal-selection / confidence / focus
+# (MR-7/8/9) are the concrete instances; any audited agent is judged the same.
+# ============================================================================
+$id: mutagent-evaluator/behavior-tree
+title: Subject Behavior Tree
+type: object
+required: [subject, version, generatedAt, root, nodes]
+properties:
+  subject: { type: string, description: synthetic subject name (NDA) }
+  version: { type: string }
+  generatedAt: { type: string, description: injected; masked for byte-identity }
+  root:
+    type: string
+    description: nodeId of the entry decision node
+  nodes:
+    type: array
+    items:
+      type: object
+      required: [nodeId, label, decisionType, scenarios, edges]
+      properties:
+        nodeId: { type: string }
+        label:
+          type: string
+          description: the protocol decision point (e.g. "Step 3a scope-pick", "Step 4.5 double-zero", "Step 6 analyzer-count", "copy-back")
+        decisionType:
+          enum: [signal-tier, confidence-basis, focus, scope-pick, gate, dispatch-count, approval, stage-selection, content-decision, output-shape, tool-choice]
+          description: >-
+            what kind of sub-decision this node represents. The first set (signal-tier … approval) is
+            DIAGNOSTICS-shaped (MR-7/8/9 instances). SF-3 additive: stage-selection | content-decision |
+            output-shape | tool-choice generalize the vocab for GENERATION-shaped subjects (a multi-stage
+            content pipeline), per subject kind — the engine's expected-vs-observed decision comparison is
+            identical regardless of which vocab a node uses.
+        scenarios:
+          type: array
+          description: one entry per distinct situation the agent could be in; the EXPECTED decision per scenario
+          items:
+            type: object
+            required: [scenarioId, when, expectedDecision]
+            properties:
+              scenarioId: { type: string }
+              when:
+                type: string
+                description: the condition that selects this scenario (tier-0 signals + brief state)
+              expectedDecision:
+                type: string
+                description: what the methodology expects the agent to decide GIVEN this scenario
+              expectedFork:
+                type: string
+                description: which outgoing edge target the expected decision should take (optional)
+              rationale:
+                type: string
+                description: why this is the expected decision (the methodology's reasoning)
+        edges:
+          type: array
+          description: the forks out of this node
+          items:
+            type: object
+            required: [edgeId, to, condition]
+            properties:
+              edgeId: { type: string }
+              to: { type: string, description: target nodeId, or "TERMINAL" }
+              condition: { type: string, description: the fork condition }
+              deadOrRare:
+                type: boolean
+                description: MR-1 flag — is this fork dead / rarely-useful (advisory)?

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/dataset.schema.yaml

@@ -0,0 +1,66 @@
+# schemas/dataset.schema.yaml
+# ============================================================================
+# The SHAPE a generated/derived eval DATASET must conform to (EV-046 build +
+# EV-047 derive + EV-053 living-suite append target).
+#
+# A dataset is the subject's growing set of test CASES: each case is one
+# combination of dimension values (a tuple) plus a realistic natural-language
+# query. Cases come from three sources: user-confirmed SEED tuples (the HITL
+# interview), SYNTHETIC extension (the dataset-builder agent), or DERIVED from a
+# past trace (*derive-dataset). The set is APPEND-ONLY (monotonic growth — the
+# suite never shrinks).
+#
+# Subject-agnostic (EV-002): dimensions + values are DATA carried here, never
+# hard-coded engine constants. This is a human-readable shape contract; the
+# executable validator lives in scripts/contracts/dataset.ts (TypeBox), kept in
+# lockstep with this file.
+# ============================================================================
+$id: mutagent-evaluator/dataset
+title: Subject Eval Dataset
+type: object
+required: [subject, dimensions, cases, version]
+properties:
+  subject:
+    type: string
+    description: synthetic subject name (from the subject profile); NEVER a production dataset name (NDA)
+  dimensions:
+    type: array
+    description: the axes of variation (generate-synthetic-data Step 1); target failure-prone regions
+    items:
+      type: object
+      required: [name, values]
+      properties:
+        name: { type: string }
+        description: { type: string }
+        values:
+          type: array
+          minItems: 1
+          items: { type: string }
+          description: the discrete values this dimension can take
+  cases:
+    type: array
+    description: the test cases (append-only; monotonic-growth enforced by living-suite EV-053)
+    items:
+      type: object
+      required: [id, tuple, query, source]
+      properties:
+        id:
+          type: string
+          description: content-derived stable id (caseId = fnv1a(tupleKey::query)); re-builds collide -> dedup
+        tuple:
+          type: object
+          description: dimension name -> chosen value (≥1 assignment); canonicalized by tupleKey for dedup
+          additionalProperties: { type: string }
+        query:
+          type: string
+          description: the natural-language query realizing this tuple (from the dataset-builder agent)
+        source:
+          enum: [seed, synthetic, derived]
+          description: seed = user-confirmed HITL tuple | synthetic = LLM-generated | derived = distilled from a past trace
+        originTraceId:
+          type: string
+          description: for derived cases — the past trace this case distills from
+  version:
+    type: integer
+    minimum: 0
+    description: monotonically-increasing version, bumped on every append

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/edd-change-request.schema.yaml

@@ -0,0 +1,114 @@
+# schemas/edd-change-request.schema.yaml
+# ============================================================================
+# F18 — EDD CLOSURE: the evaluator → ai-engineer change-request contract.
+#
+# The evaluator is JUDGE-ONLY (EV-051): it never fixes the subject. To close the
+# Eval-Driven-Development loop it REQUESTS the AI-Engineer (the *build ACTOR from
+# the SPEC stage) to amend the Agent / AgentSpec — wired over the `SendMessage`
+# tool both agents carry. This file is the HUMAN-readable shape; the executable
+# companion is scripts/edd/edd-types.ts (TypeBox) + scripts/edd/change-request.ts
+# (the validators + the bounded loop controller). Kept in lockstep.
+#
+#   evaluator  --(EddChangeRequest)-->  ai-engineer
+#   ai-engineer --(ChangeRequestResponse)--> evaluator
+#   evaluator  re-evaluates  →  loop until full green OR a bounded STOP.
+# ============================================================================
+$id: mutagent-evaluator/edd-change-request
+title: EDD Change-Request Contract (F18)
+
+definitions:
+  FailingCaseRef:
+    type: object
+    description: >
+      One failing/uncertain case the evaluator hands the engineer. GROUNDED —
+      carries the verbatim critique + ≥1 structured ref {obs,path,value}, the
+      SAME machine-checkable evidence the judge already emitted (GA-1). An
+      ungrounded ask (refs empty) is a DEFECT — the evaluator never asks for a
+      fix it cannot ground.
+    required: [caseId, criterionId, critique, refs]
+    additionalProperties: false
+    properties:
+      caseId: { type: string, minLength: 1 }
+      criterionId: { type: string, minLength: 1 }
+      critique: { type: string, minLength: 1, description: verbatim from the verdict }
+      refs:
+        type: array
+        minItems: 1
+        items:
+          type: object
+          required: [obs, path, value]
+          additionalProperties: false
+          properties:
+            obs: { type: string, description: trace/observation id }
+            path: { type: string, description: field path within the observation }
+            value: { type: string, description: the EXACT cited string }
+
+  EddChangeRequest:
+    type: object
+    description: the evaluator → ai-engineer request (the SendMessage payload).
+    required: [requestId, swing, subject, remedyTarget, failingCases, proposedRemedy, status]
+    additionalProperties: false
+    properties:
+      requestId: { type: string, minLength: 1 }
+      swing:
+        type: integer
+        minimum: 1
+        description: 1-based EDD swing index (the Nth evaluator→engineer→re-eval cycle)
+      subject: { type: string, minLength: 1 }
+      remedyTarget:
+        enum: [agentspec, impl]
+        description: >
+          WHERE the engineer should fix — the evaluator PROPOSES, never patches.
+          agentspec = the DEFINITION (system_prompt / jobs / sop / criteria); the
+          def→impl cascade means the engineer re-runs *build after editing.
+          impl = the IMPLEMENTATION scaffold only (a wiring/faithfulness defect
+          that does NOT change the spec).
+      failingCases:
+        type: array
+        minItems: 1
+        items: { $ref: "#/definitions/FailingCaseRef" }
+      proposedRemedy:
+        type: string
+        minLength: 1
+        description: the proposed remedy in NL — a HYPOTHESIS for the engineer, not a mandate
+      status:
+        const: requested
+        description: the evaluator always emits `requested`
+
+  ChangeRequestResponse:
+    type: object
+    description: the ai-engineer → evaluator reply after consuming a request.
+    required: [requestId, status, note]
+    additionalProperties: false
+    properties:
+      requestId: { type: string, minLength: 1 }
+      status:
+        enum: [amended, rejected]
+        description: >
+          amended = the named target was edited (and, for an agentspec target,
+          *build was re-run to cascade def→impl) → a re-eval is warranted.
+          rejected = the engineer declined WITH a reason (wrong target / not
+          reproducible) → NO re-eval of an unchanged subject.
+      amendedTarget:
+        enum: [agentspec, impl]
+        description: which artifact was actually amended (echoes the request target)
+      rebuilt:
+        type: boolean
+        description: for an agentspec amend — was *build re-run to cascade def→impl?
+      note:
+        type: string
+        minLength: 1
+        description: human summary of the amendment OR the rejection reason (ALWAYS present)
+
+# ── Loop control (the afkloop-legal terminator — scripts/edd/change-request.ts) ─
+# The EDD loop is NEVER infinite. Termination gate, success-first:
+#   1. full-green            — varianceStable AND accuracyMet ⇒ DONE
+#   2. max-swings            — swing ≥ budget.maxSwings ⇒ STOPPED (+ convergence delta)
+#   3. max-wallclock         — elapsedMs ≥ budget.maxWallclockMs ⇒ STOPPED
+#   4. no-improvement-streak — N consecutive swings w/ no improvement ⇒ STOPPED
+# Defaults: maxSwings 6 · maxWallclockMs 30min · noImprovementStreakLimit 2.
+# F19 ordering is preserved in the CONTINUE branch: not-stable ⇒ variance phase,
+# stable ⇒ accuracy phase (variance precedes accuracy, always).
+loopControl:
+  phases: [build, variance, accuracy, done, stopped]
+  stopReasons: [full-green, max-swings, max-wallclock, no-improvement-streak]

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/eval-matrix.schema.yaml

@@ -0,0 +1,74 @@
+# schemas/eval-matrix.schema.yaml
+# ============================================================================
+# The SHAPE a subject eval-matrix must conform to.
+# A subject profile (subjects/<name>/eval-matrix.yaml) is a master checklist:
+# every component (agent / skill-orchestrator-step / star-command / script)
+# graded on a 3-dimension MECE coverage, with a per-criterion checkMethod that
+# determines whether the row runs DETERMINISTICALLY or under the PINNED JUDGE.
+#
+# This is a human-readable shape contract. The executable validator lives in
+# scripts/contracts/eval-matrix.ts (TypeBox), kept in lockstep with this file.
+# ============================================================================
+$id: mutagent-evaluator/eval-matrix
+title: Subject Eval Matrix
+type: object
+required: [subject, version, generatedAt, designPrinciples, components]
+properties:
+  subject:
+    type: string
+    description: synthetic subject name (e.g. sample-agent); NEVER a production dataset name (NDA, design decision #10)
+  version:
+    type: string
+    description: matrix version (e.g. v1); Mode B regenerates/extends as vN
+  generatedAt:
+    type: string
+    description: injected ISO timestamp; masked for byte-identity
+  designPrinciples:
+    type: array
+    items: { type: string }
+    description: the load-bearing design principles the matrix encodes
+  components:
+    type: array
+    items:
+      type: object
+      required: [componentId, componentName, componentType, criteria]
+      properties:
+        componentId: { type: string }
+        componentName: { type: string }
+        componentType:
+          enum: [agent, skill-orchestrator-step, star-command, script, gate, feature, pipeline-stage]
+          description: >-
+            drives the color-coded tint; ordered top-bound first (skill -> agents -> commands -> scripts -> gates).
+            SF-1 additive: feature | pipeline-stage for a multi-stage generation subject (a CHAIN of stages, §6a).
+        criteria:
+          type: array
+          items:
+            type: object
+            required: [dimension, statement, checkMethod, passCondition, severity, existingCoverage]
+            properties:
+              dimension:
+                enum: [operation-correctness, data-correctness, operational-deviation]
+                description: the 3-dimension MECE coverage (R1 / R2 / R3)
+              statement:
+                type: string
+                description: the conformance assertion for this row
+              checkMethod:
+                enum: [deterministic-script, typebox-schema, gate, trace-cross-ref, trajectory-diff, llm-judge]
+                description: >-
+                  deterministic-script | typebox-schema | gate          -> DETERMINISTIC track (no model)
+                  trace-cross-ref | trajectory-diff | llm-judge         -> PINNED-JUDGE track (model id + temp=0)
+                  SF-2 additive (DEC-16): llm-judge = a generic content judge (not only the diagnostics-specific
+                  trace-cross-ref / trajectory-diff). The v2 MinedCriterion carries its own 3-value check_method
+                  router (deterministic | llm-judge | hybrid, eval-types.ts); the two coexist.
+              passCondition:
+                type: string
+                description: the concrete, binary pass condition
+              severity:
+                enum: [CRIT, HIGH, MED, LOW]
+                description: by VARIANCE IMPACT, not code size; CRIT/HIGH gate the component
+              existingCoverage:
+                enum: [covered, partial, none]
+                description: honest declaration vs the actual test+gate inventory
+              evidenceSource:
+                type: string
+                description: mandatory traceability — a cited intended behavior or observed deviation (no-filler rule)

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/flow-graph.schema.yaml

@@ -0,0 +1,69 @@
+# schemas/flow-graph.schema.yaml — EV-032 information-flow graph (human-readable mirror)
+#
+# The deterministic structure `scripts/flow-graph.ts` produces from one trace.
+# Kept in lockstep with the TypeBox contract in `scripts/contracts/flow-graph.ts`
+# (that file is the SINGLE SOURCE OF TRUTH; this YAML documents the shape for
+# subject authors + reviewers). SUBJECT-AGNOSTIC: nodes are named by the trace's
+# OWN observation names; no subject vocabulary is baked in here.
+title: FlowGraph
+type: object
+additionalProperties: false
+required: [traceId, nodes, edges, unthreadedOutputs]
+properties:
+  traceId:
+    type: string
+    description: The id of the trace this graph was built from.
+  nodes:
+    type: array
+    description: One node per trace observation, viewed as a producer/consumer.
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, index, type, name, produces, consumes, isHandoff]
+      properties:
+        id: { type: string, description: "Stable node id by position (n0, n1, …)." }
+        index: { type: integer, minimum: 0 }
+        type: { type: string, description: "The observation type (TOOL / GENERATION / EVENT / AGENT / …)." }
+        name: { type: string, description: "The observation name (tool/step name) — may be empty." }
+        produces:
+          type: array
+          items: { type: string }
+          description: "Top-level output slot keys (primitive payload → the _value sentinel)."
+        consumes:
+          type: array
+          items: { type: string }
+          description: "Top-level input slot keys (primitive payload → the _text sentinel)."
+        isHandoff:
+          type: boolean
+          description: "True iff name ∈ the SUPPLIED dispatchToolNames (a sub-agent dispatch, EV-029)."
+  edges:
+    type: array
+    description: >-
+      Data-handoff edges. An edge means a producer slot's value string reached a
+      LATER consumer's serialized input (deterministic content-overlap, EV-028).
+    items:
+      type: object
+      additionalProperties: false
+      required: [from, to, slot, kind]
+      properties:
+        from: { type: string, description: "Producer node id." }
+        to: { type: string, description: "Consumer node id." }
+        slot: { type: string, description: "The producer slot whose value threaded." }
+        kind:
+          type: string
+          enum: [threaded, handoff]
+          description: "threaded = plain tool-result (EV-028); handoff = sub-agent dispatch context (EV-029)."
+  unthreadedOutputs:
+    type: array
+    description: >-
+      Producer slots whose value NEVER reached a downstream consumer — the EV-028
+      candidate leaks the context-flow judge then adjudicates (severity is NOT
+      decided here).
+    items:
+      type: object
+      additionalProperties: false
+      required: [node, name, slot]
+      properties:
+        node: { type: string }
+        name: { type: string }
+        slot: { type: string }

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/flow-profile.schema.yaml

@@ -0,0 +1,49 @@
+# schemas/flow-profile.schema.yaml — EV-037 expected-flow profile (human-readable mirror)
+#
+# The agent-shaped expected-flow the context-flow audit (EV-028/029) + the
+# trajectory variance (EV-054) diff the ACTUAL flow-graph against. Carried on the
+# subject profile (`profile-subject.ts` → SubjectProfile.expectedFlow). Kept in
+# lockstep with the TypeBox `ExpectedFlow` in `scripts/contracts/flow-graph.ts`
+# (that file is the SINGLE SOURCE OF TRUTH).
+#
+# SUBJECT-AGNOSTIC: every name here is the subject's OWN tool/step/slot name,
+# supplied via auto-gen (EV-049: the modal observed threadings) or AUTHORED (the
+# canonical path for the semantic fields the trace alone can't carry). NO subject
+# vocabulary is baked into the engine.
+title: ExpectedFlow
+type: object
+additionalProperties: false
+required: [dispatchToolNames, edges, expectedUiSlots]
+properties:
+  dispatchToolNames:
+    type: array
+    items: { type: string, minLength: 1 }
+    description: >-
+      Which tool/step names are sub-agent DISPATCHES (EV-029). A flow-graph node
+      with one of these names produces a context HANDOFF rather than a plain tool
+      result. Auto-gen leaves this empty (TODO) — supply it AUTHORED.
+  edges:
+    type: array
+    description: >-
+      The producer→consumer threadings the subject SHOULD exhibit (a regression
+      baseline). Auto-gen (EV-049) seeds these from the modal observed
+      data-handoffs across the trace sample.
+    items:
+      type: object
+      additionalProperties: false
+      required: [fromTool, toTool]
+      properties:
+        fromTool: { type: string, minLength: 1, description: "Producer tool/step name." }
+        toTool: { type: string, minLength: 1, description: "Consumer tool/step name." }
+        slot:
+          type: string
+          minLength: 1
+          description: "Optional — when present, the diff also requires THIS slot to thread."
+  expectedUiSlots:
+    type: array
+    items: { type: string, minLength: 1 }
+    description: >-
+      Slots the subject's HTML artifact SHOULD render (EV-039/040, the operator's
+      HTML-artifact missing-data case): a value computed but absent from the HTML
+      is a missing-data leak. These aren't present in agent traces — supply them
+      AUTHORED (auto-gen leaves empty, TODO).

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/schemas/methodology-review.schema.yaml

@@ -0,0 +1,40 @@
+# schemas/methodology-review.schema.yaml
+# ============================================================================
+# The SHAPE of the MR (methodology-review) rubric — §1.5 family.
+#
+# This is the SECOND requirement family: FITNESS, not conformance. It does not
+# pass/fail a component; it interrogates the methodology's own decision-tree,
+# workflow structure, and data-flow, and emits ranked recommendations to
+# rearrange / improve the process. MR-1..9 (Tab-4 lens reads these).
+# ============================================================================
+$id: mutagent-evaluator/methodology-review
+title: Subject Methodology-Review Rubric
+type: object
+required: [subject, version, generatedAt, items]
+properties:
+  subject: { type: string, description: synthetic subject name (NDA) }
+  version: { type: string }
+  generatedAt: { type: string, description: injected; masked for byte-identity }
+  items:
+    type: array
+    description: the MR-1..9 rubric items (advisory, NOT pass/fail)
+    items:
+      type: object
+      required: [id, title, reads, how, family]
+      properties:
+        id:
+          type: string
+          description: MR-1 .. MR-9
+        title: { type: string }
+        reads:
+          type: string
+          description: the inputs this MR item reasons over (e.g. "behavior-tree + run outcomes")
+        how:
+          type: string
+          description: how the judge reasons over the inputs to emit a finding
+        family:
+          enum: [decision-tree-fitness, data-flow-efficiency, methodology-fitness, sequence-soundness, process-self-feedback, conformance-vs-fitness, signal-selection, confidence-derivation, focus-determination]
+          description: which fitness concern this item interrogates
+        advisory:
+          type: boolean
+          description: always true — MR items NEVER gate a run (decision #5 keeps GATE and TREND separate)