npm - @mutagent/helix - Versions diffs - 0.1.0-alpha.14 - Mend

@mutagent/helix 0.1.0-alpha.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (357) hide show

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/assets/brand/theme.css ADDED Viewed

@@ -0,0 +1,213 @@
+/* ============================================================================
+ * Mutagent brand — SELF-CONTAINED copy, ALIGNED to the unified design-system.
+ *
+ * Source of truth: @mutagent/templates/design-system/tokens.css (the ONE canonical
+ * style). This file mirrors those tokens + re-skins the evaluator report's own
+ * component classes onto them, so all three evaluator HTML renderers
+ * (render-report.ts · render-eval-report.ts · build-review-ui.ts) share the
+ * unified brand WITHOUT a cross-skill runtime reference (the self-containment
+ * rule: copied here, read from the evaluator's own assets/brand/ at runtime).
+ *
+ * Brand (2026-06-23 design session):
+ *   · SHARP corners (radius 0) — the UI "sharp-corners brand"
+ *   · SUBTLE non-black card surfaces (cards lift off the void, never pure black,
+ *     never "overly purple") — purple is an ACCENT only, never a card fill
+ *   · TONED status (vibrant, not neon) + MUTED heatmap fills
+ *   · RESTRAINED cyberpunk — minimal glow, NO heavy gradients (the wordmark
+ *     gradient is the only one)
+ * Fonts: Space Grotesk (display) + IBM Plex Mono (mono) — loaded via the <head>
+ * <link> the renderer emits.
+ * ========================================================================== */
+:root {
+  /* ── canonical design-system tokens (mirror tokens.css) ── */
+  --bg: #0a0a12;            /* near-black void (dominant surface) */
+  --surf: #14141d;          /* CARD — subtle lift, non-black, barely-tinted */
+  --surf-2: #1a1a25;        /* raised (nested cards, headers) */
+  --surf-3: #22222f;        /* elevated / hover */
+  --border: rgba(255, 255, 255, 0.09);
+  --border-strong: rgba(255, 255, 255, 0.16);
+  --fg: #d6dbe6;
+  --fg-strong: #eef1f6;
+  --muted: #8a8698;
+  --dim: #5a5667;
+  --primary: #7E47D7;       /* purple — ACCENT only (never a card fill) */
+  --primary-soft: #b794f4;
+  --cyan: #45b8cc;          /* secondary accent, used sparingly */
+  --pass: #43c39a;          /* TONED status (vibrant, not neon) */
+  --fail: #e06666;
+  --warn: #e8a64d;
+  /* STATUS COLOR-ACUITY — tints raised ~.08→.16 so pass/fail/indeterminate POP at a
+   * glance (still toned, not neon). Paired with a status LEFT-BORDER on verdict
+   * cards/rows so the eye catches the outcome instantly. */
+  --pass-bg: rgba(67, 195, 154, 0.16);
+  --fail-bg: rgba(224, 102, 102, 0.16);
+  --warn-bg: rgba(232, 166, 77, 0.16);
+  /* §9.4.5 E7 — RECOMMENDED highlight toned DOWN ~50% (cyan #45b8cc desaturated →
+   * #67a0aa; bg alpha .10→.05) so the "★ recommended" treatment reads calm, not glare.
+   * Mirrors the shared @mutagent/templates token. */
+  --recommend: #67a0aa;     /* RECOMMENDED highlight (remedies / picks) — calm cyan */
+  --recommend-bg: rgba(103, 160, 170, 0.05);
+  --radius: 0px;            /* SHARP corners */
+  --font: 'Space Grotesk', system-ui, -apple-system, sans-serif;
+  --mono: 'IBM Plex Mono', ui-monospace, monospace;
+  /* ── R7 (§9.4.4) NORMALIZED TYPE SCALE — one scale, applied everywhere ──
+   * The single source of font sizing for every evaluator artifact. The FLOOR is
+   * --fs-2xs = 11px: raised from 10.5 so even the smallest mono chip is comfortably
+   * legible at normal zoom. Every size steps off this scale — NO ad-hoc px in the
+   * report components, and NO sub-1em (em/%-relative) shrink anywhere (the `code`
+   * 0.88em bug let nested mono dip below floor — now pinned to the absolute token).
+   * Map of legacy → token:
+   *   8 / 8.5 / 9 / 9.5  → --fs-2xs (11)     micro labels · mono chips · code
+   *   10 / 10.5 / 11 / 11.5 → --fs-xs (12)   small mono · secondary
+   *   12 / 12.5 / 13     → --fs-sm (13)       table cells · body-small
+   *   14                 → --fs-md (14)       base body
+   *   15 / 16            → --fs-lg (16)       h3 / section emphasis
+   *   18                 → --fs-xl (19)       large emphasis
+   *   22                 → --fs-2xl (22)      h2 / big-stat values
+   */
+  --fs-2xs: 11px;
+  --fs-xs:  12px;
+  --fs-sm:  13px;
+  --fs-md:  14px;
+  --fs-lg:  16px;
+  --fs-xl:  19px;
+  --fs-2xl: 22px;
+  /* ── legacy aliases — the renderers reference these names; map onto canonical ── */
+  --bg2: #14141d;           /* tabs strip — subtle, non-black */
+  --bg3: #1a1a25;           /* table even-row — subtle */
+  --surf-r: var(--surf-2);
+  --surf-e: var(--surf-3);
+  --surf-h: var(--surf-3);
+  --text: var(--fg-strong);
+  --bstr: var(--border-strong);
+  --p: var(--primary);
+  --c: var(--cyan);
+  --g: var(--pass);
+  --y: var(--warn);
+  --r: var(--fail);
+  --m: var(--primary-soft);  /* inline code — soft purple, not magenta */
+  --glow: transparent;       /* RESTRAINED — no glow */
+  --gglow: transparent;
+  --fs: var(--font);
+  --fm: var(--mono);
+}
+/* SHARP everywhere — the global radius reset is the sharp-corners brand. */
+* { box-sizing: border-box; border-radius: var(--radius); }
+body {
+  margin: 0;
+  font-family: var(--font);
+  color: var(--fg);
+  background: var(--bg);
+  font-size: var(--fs-md);
+  line-height: 1.55;
+}
+/* ── Banner + MUTAGENT wordmark (flat subtle surface; wordmark is the ONLY gradient) ── */
+header.banner {
+  background: var(--surf);
+  border-bottom: 1px solid var(--border-strong);
+  padding: 20px 32px;
+  position: relative;
+}
+.brand { display: flex; align-items: baseline; gap: 14px; margin-bottom: 6px; }
+.logo {
+  font-family: var(--font);
+  font-weight: 700;
+  font-size: var(--fs-2xl);
+  letter-spacing: 0.18em;
+  background: linear-gradient(90deg, var(--primary-soft), var(--cyan));
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+.product { font-size: var(--fs-md); font-weight: 500; color: var(--muted); letter-spacing: 0.04em; }
+.meta { font-size: var(--fs-xs); font-family: var(--mono); color: var(--muted); letter-spacing: 0.02em; }
+.meta .mk { color: var(--cyan); font-weight: 600; }
+.meta .mv { color: var(--fg-strong); font-weight: 600; }
+.meta .sep { color: var(--dim); margin: 0 6px; }
+/* ── Tabs (functional; no glow/shadow) ────────────────────────────────────── */
+nav.tabs {
+  background: var(--bg);
+  border-bottom: 1px solid var(--border);
+  padding: 0 12px;
+  position: sticky; top: 0; z-index: 100;
+  overflow-x: auto; white-space: nowrap;
+}
+nav.tabs button {
+  background: none; border: none;
+  padding: 10px 12px;
+  font-size: var(--fs-xs); font-weight: 500;
+  color: var(--muted); cursor: pointer;
+  border-bottom: 3px solid transparent;
+  transition: all 0.15s; font-family: inherit; letter-spacing: 0.01em;
+}
+nav.tabs button:hover { color: var(--fg-strong); background: var(--surf); }
+nav.tabs button.active { color: var(--primary-soft); border-bottom-color: var(--primary); font-weight: 600; }
+nav.tabs button.internal { color: var(--cyan); }
+nav.tabs button.internal.active { border-bottom-color: var(--cyan); }
+/* ── Layout + panels ─────────────────────────────────────────────────────── */
+main { max-width: 1200px; margin: 0 auto; padding: 28px 32px 140px 32px; }
+.panel { display: none; }
+.panel.active { display: block; animation: fade 0.2s ease-out; }
+@keyframes fade { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: translateY(0); } }
+h2 { font-size: var(--fs-2xl); font-weight: 600; margin: 0 0 8px 0; padding-bottom: 10px; border-bottom: 1px solid var(--border-strong); color: var(--fg-strong); }
+.sub { color: var(--muted); font-size: var(--fs-sm); margin-bottom: 24px; }
+/* §9.4.5 E4 — tighter section rhythm (24→18) toward diagnostics density. */
+h3 { font-size: var(--fs-lg); font-weight: 600; margin-top: 18px; margin-bottom: 6px; color: var(--primary-soft); }
+h4 { font-size: var(--fs-sm); font-weight: 600; margin-top: 14px; color: var(--fg-strong); text-transform: uppercase; letter-spacing: 0.04em; font-family: var(--mono); }
+p { line-height: 1.6; color: var(--muted); }
+strong { color: var(--fg-strong); }
+/* ── Tables (sharp; subtle) ───────────────────────────────────────────────── */
+table { border-collapse: collapse; margin: 12px 0; font-size: var(--fs-sm); width: 100%; border: 1px solid var(--border); }
+th, td { border: 1px solid var(--border); padding: 8px 12px; text-align: left; vertical-align: top; color: var(--muted); }
+th { background: var(--surf-2); font-weight: 600; color: var(--fg-strong); }
+tr:nth-child(even) td { background: var(--surf); }
+code { background: var(--bg); color: var(--primary-soft); padding: 2px 6px; font-size: var(--fs-2xs); font-family: var(--mono); border: 1px solid var(--border); }
+/* ── Callouts (flat tinted surface + accent border; NO gradient/glow) ─────── */
+.crit { background: var(--fail-bg); border-left: 3px solid var(--fail); padding: 14px 18px; margin: 14px 0; }
+.crit strong { color: var(--fail); }
+.warn { background: var(--warn-bg); border-left: 3px solid var(--warn); padding: 14px 18px; margin: 14px 0; }
+.warn strong { color: var(--warn); }
+.alert { background: var(--pass-bg); border-left: 3px solid var(--pass); padding: 14px 18px; margin: 14px 0; }
+.alert strong { color: var(--pass); }
+.internal-banner { background: var(--recommend-bg); border: 1px dashed var(--cyan); padding: 10px 16px; margin: 0 0 18px 0; font-family: var(--mono); font-size: var(--fs-xs); color: var(--cyan); letter-spacing: 0.03em; }
+/* ── RECOMMENDED highlight (remedies / recommended picks) ─────────────────── */
+.recommend { border-left: 3px solid var(--recommend); background: var(--recommend-bg); padding: 7px 11px; }
+.recommend .tag { font-family: var(--mono); font-size: var(--fs-2xs); font-weight: 700; color: var(--recommend); }
+/* ── Badges + pills (sharp; toned) ────────────────────────────────────────── */
+.badge { display: inline-block; padding: 2px 6px; font-size: var(--fs-xs); font-weight: 600; letter-spacing: 0.04em; font-family: var(--mono); margin-right: 4px; }
+.b-crit { background: var(--fail-bg); color: var(--fail); border: 1px solid var(--fail); }
+.b-high { background: var(--warn-bg); color: var(--warn); border: 1px solid var(--warn); }
+.b-med { background: rgba(69, 184, 204, 0.10); color: var(--cyan); border: 1px solid var(--cyan); }
+.b-low { background: var(--surf-3); color: var(--muted); border: 1px solid var(--border); }
+.b-pass { background: var(--pass-bg); color: var(--pass); border: 1px solid var(--pass); }
+.b-fail { background: var(--fail-bg); color: var(--fail); border: 1px solid var(--fail); }
+.b-skip { background: var(--surf-3); color: var(--muted); border: 1px solid var(--border); }
+/* ── Big-stat tiles (subtle non-black cards) ──────────────────────────────── */
+.big-stat { display: flex; gap: 18px; flex-wrap: wrap; margin: 16px 0; }
+.big-stat .s { background: var(--surf-2); border: 1px solid var(--border); padding: 12px 16px; min-width: 96px; }
+.big-stat .v { font-size: var(--fs-2xl); font-weight: 700; font-family: var(--mono); }
+.big-stat .l { font-size: var(--fs-xs); color: var(--dim); text-transform: uppercase; letter-spacing: 0.06em; margin-top: 2px; }
+/* ── Verdict card (subtle; toned accent border; NO glow) ──────────────────── */
+.verdict { background: var(--surf-2); border: 1px solid var(--border-strong); border-left-width: 5px; padding: 18px 20px; margin: 16px 0; }
+.verdict.pass { border-color: var(--pass); border-left-color: var(--pass); background: var(--pass-bg); }
+.verdict.fail { border-color: var(--fail); border-left-color: var(--fail); background: var(--fail-bg); }
+.verdict.skip { border-color: var(--warn); border-left-color: var(--warn); background: var(--warn-bg); }

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/assets/brand/wordmark.html ADDED Viewed

@@ -0,0 +1,9 @@
+<!-- Mutagent banner + MUTAGENT wordmark — SELF-CONTAINED copy, extracted from
+     the diagnostics report.html.tpl header treatment so the two products are
+     visually consistent. The HEADER title + meta are stamped by render-report.ts.
+     The renderer reads this partial from its own package; it never references
+     the diagnostics package at runtime. -->
+<header class="banner">
+  <div class="brand"><div class="logo">MUTAGENT</div><div class="product">{{HEADER_TITLE}}</div></div>
+  <div class="meta">{{HEADER_META}}</div>
+</header>

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/lenses/context-flow-lens.md ADDED Viewed

@@ -0,0 +1,85 @@
+# Context-Flow Lens — generic pinned-judge prompt (EV-028 / EV-029)
+> **Track:** Data-Leak Tab — the **context-flow** dimension (agent context-flow,
+> not data-pipeline). Scores over the deterministic **flow-graph** (EV-032) +
+> **expected-flow** (EV-037), never the raw trace.
+> **Pinning (R10):** PINNED model id + **temperature = 0**, recorded. **Mask the
+> output.** Two audits on one flow-graph ⇒ byte-identical verdict.
+> **Parameterized by the loaded subject profile** — flow/slot/tool names come
+> from the flow-graph + expected-flow, NOT from any subject constant in the lens.
+## Purpose
+Judge an AGENT's context-flow for two leak families — the same `LEAK_SCHEMA`
+SHAPE the data-pipeline dimensions use (`locus` C2C/UI · `cls` A/B ·
+`formalStructure`), new producers:
+- **EV-028 — tool-result threading.** A tool result produced at step N that is
+  NEVER threaded into a later consumer's context (an `unthreadedOutput` in the
+  flow-graph). Is the dropped result one the downstream step NEEDED? → leak
+  (`locus: C2C`, `cls: B` producer-not-threaded). Or was it legitimately unused
+  (a side-effect / log) → NOT a leak.
+- **EV-029 — sub-agent handoff completeness.** A `lossyHandoff` (an expected-flow
+  edge ABSENT from the actual graph): the dispatch brief did not carry the
+  context the expected-flow says the child sub-agent needs. A child that runs
+  without the context it required → leak (`locus: C2C`, `cls: B`). The
+  expected-flow is the source of truth for "what the child NEEDED".
+> This lens generalizes the v1 data-pipeline SHAPE to agent context-flow — it
+> does NOT rebuild the engine. `flow-graph.ts` makes producers/consumers/edges
+> EXPLICIT; `expected-flow` supplies the diff target; THIS lens adjudicates.
+## Inputs (supplied by the harness, deterministic)
+- `flowGraph` — the EV-032 graph for the trace under audit (`nodes` with
+  produces/consumes slots · `edges` threaded handoffs · `unthreadedOutputs`).
+- `expectedFlow` — the EV-037 spec (`dispatchToolNames` · expected `edges` ·
+  `expectedUiSlots`).
+- `candidates` — the deterministic `contextFlowCandidates` bundle
+  (`unthreadedOutputs` = EV-028 candidates · `lossyHandoffs` = EV-029 candidates).
+  These are CANDIDATES — the lens decides which are TRUE leaks + their severity.
+## Method
+1. **Threading (EV-028).** For EACH `candidates.unthreadedOutputs[]`
+   `{node, name, slot}`: read the producing observation's output slot + the
+   downstream steps. Decide: was this slot's value REQUIRED by a later step that
+   silently re-derived it, guessed, or proceeded without it? → leak. Or a
+   legitimate side-effect with no consumer → not a leak. Ground the verdict in
+   the specific producer/consumer node names — never speculate.
+2. **Handoff completeness (EV-029).** For EACH `candidates.lossyHandoffs[]`
+   `{fromTool, toTool, slot?}`: confirm the expected producer→consumer threading
+   is genuinely absent in `flowGraph.edges` (not merely renamed). A dispatch that
+   handed a child an INCOMPLETE brief (the expected context never threaded) →
+   leak. Cite the dispatch node + the missing slot.
+3. **Severity.** HIGH when the dropped/incomplete context changes the agent's
+   action (a wrong send, a hallucinated value, a child that acts on stale
+   context). MED/LOW when cosmetic or recoverable. `formalStructure`: `exists`
+   when a schema/contract for the handoff is defined but unenforced; `partial`
+   when fields are optional; `none` when no handoff contract exists.
+4. **No candidates → no leaks.** A fully-threaded, expectation-meeting graph
+   returns an empty `leaks` array (the audit is allowed to find nothing).
+## Output contract (masked, schema-validated → `LEAK_SCHEMA`, dimension="context-flow")
+Emit ONE `LEAK_SCHEMA` leak per CONFIRMED context-flow leak:
+```yaml
+dimension: context-flow
+summary: <one-line verdict on the headline context-flow leaks>
+leaks:
+  - id: CF-1                      # CF-n
+    title: <unthreaded result | lossy handoff — named>
+    locus: C2C                    # context lost between steps/components
+    cls: B                        # producer not run / not threaded
+    producer: <the node name that should have threaded it>
+    whyNotProduced: <dropped result | incomplete dispatch brief>
+    formalStructure: none|partial|exists
+    severity: HIGH|MED|LOW
+    whatsLost: <the slot/context + the downstream step that needed it>
+    evidence: <flow-graph node ids + slot, e.g. "n3.draft unthreaded; n7 sendMessage proceeded without it">
+```
+**Never fabricate.** If a candidate turns out to be legitimately unused
+(side-effect, log, terminal output), DO NOT emit a leak for it — say so in
+`summary`. The flow-graph is the ground truth; cite node ids + slot names from it.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/lenses/data-lens.md ADDED Viewed

@@ -0,0 +1,47 @@
+# Data Lens — generic pinned-judge prompt
+> **Track:** Tab-1 judge rows (checkMethod `trace-cross-ref` on data rows).
+> **Pinning (R10):** PINNED model id + **temperature = 0**, recorded. **Mask the
+> output.** Two audits on one bundle ⇒ byte-identical verdict.
+> **Parameterized by the loaded subject profile** — no subject-specific logic.
+## Purpose
+Judges **data correctness** rows that cannot be settled by schema-presence alone:
+faithfulness of a produced artifact to its evidence source, threading of a
+producer's output to its consumer, and the C2C/UI loci where data is produced
+but not drawn. (Schema-shape rows are handled deterministically; this lens is
+only for the `trace-cross-ref` rows the deterministic engine defers.)
+## Inputs (supplied by the harness)
+- `criterion` — the single data criterion under judgment (statement +
+  passCondition + severity).
+- `runBundle` — the produced artifacts (runMeta / render-input / evidence /
+  traces-metadata) to cross-reference.
+## Method
+1. Identify the **producer** artifact and the **consumer** surface named in the
+   criterion's `passCondition`.
+2. Cross-reference: does the value the producer emitted reach the consumer
+   **unaltered and non-empty**? Spot-check 2 concrete values
+   (producer-side vs consumer-side) and compare verbatim.
+3. A value that is silently dropped, altered, or re-derived ad hoc (instead of
+   threaded from the script-of-record) **FAILS**. An identical, faithfully
+   threaded value **PASSES**.
+## Output contract (masked, schema-validated)
+```yaml
+criterion: <statement>
+producer: <artifact/field>
+consumer: <surface/field>
+result: pass | fail
+evidence: <the two compared values + their file:locations>
+rationale: <faithful & threaded → pass; dropped/altered/re-derived → fail>
+```
+**Never fabricate.** If the producer or consumer artifact is absent from the
+bundle, return `result: fail` (a missing producer is a leak, not a pass) with an
+evidence note naming the absent artifact.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/lenses/decision-lens.md ADDED Viewed

@@ -0,0 +1,48 @@
+# Decision Lens — generic pinned-judge prompt
+> **Track:** Tab-1 judge rows (checkMethod `trajectory-diff` on decision nodes).
+> **Pinning (decision #10 / R10):** run at a PINNED model id + **temperature = 0**.
+> Record the resolved model id + temperature into the scorecard. **Mask the
+> output** (runId / timestamps / abs-paths) so two audits on one bundle produce a
+> byte-identical verdict.
+> **Parameterized by the loaded subject profile** — this lens ships ZERO subject-
+> specific logic; the behavior-tree supplies the expected decisions.
+## Inputs (supplied by the harness)
+- `behaviorTree` — the subject's `behavior-tree.yaml` (the golden behavioral spec).
+- `runTrajectory` — the run-bundle's transcript / runMeta / evidence.
+- `node` — the single decision node under judgment (one row per node-scenario).
+## The generic comparison (specific ↔ generic)
+At the given behavior-tree node, determine **which scenario the agent was
+actually in** (match the run's tier-0 signals + brief state against each
+scenario's `when`). Then compare:
+1. **expected-scenario vs observed-scenario** — did the agent correctly identify
+   the situation it was in?
+2. **expected-decision vs observed-decision** — given the scenario it was
+   actually in, did the agent make the decision the methodology expected
+   (`expectedDecision`) and take the expected fork (`expectedFork`)?
+A decision that reaches the goal via an out-of-order-but-valid path **PASSES**
+(trajectory judging rewards goal-reaching, not rote path-matching). A decision
+that takes a fork the scenario did not warrant **FAILS**.
+## Output contract (masked, schema-validated)
+```yaml
+nodeId: <string>
+observedScenario: <scenarioId | "unmatched">
+expectedDecision: <verbatim from the node>
+observedDecision: <what the agent actually did, quoted from the transcript>
+result: pass | fail
+evidence: <transcript quote / runMeta field proving the observed decision>
+rationale: <why pass/fail — cite the scenario's rationale>
+```
+**Never fabricate a verdict.** If the transcript does not contain enough to
+identify the observed decision, return `result: fail` with
+`observedScenario: unmatched` and an evidence note — an unobservable decision is
+a determinism defect, not a pass.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/lenses/methodology-critic-lens.md ADDED Viewed

@@ -0,0 +1,53 @@
+# Methodology-Critic Lens — Tab-4 (FITNESS, not conformance)
+> **Track:** Tab-4 — the §1.5 family. **Advisory, NOT pass/fail** (decision #5
+> keeps GATE and TREND/fitness separate). A methodology can score 100%
+> conformance (Tab-1) and still be the wrong/inefficient choice; this lens
+> answers that second question independently.
+> **Pinning (R10):** PINNED model id + **temperature = 0**, recorded. **Mask the
+> output.**
+> **Parameterized by the loaded subject profile** — the subject's behavior-tree +
+> MR rubric drive the critique; no subject-specific logic in the lens.
+## Inputs (supplied by the harness / methodology-review.ts)
+- `behaviorTree` — the subject's decision-tree.
+- `methodologyRubric` — the subject's `methodology-review.yaml` (MR-1..9).
+- `runTrajectory` — the run's trajectory + findings + data-pipeline trace.
+## The rubric (run each item; emit a finding, ranked)
+| MR | Concern | What to interrogate |
+|----|---------|---------------------|
+| MR-1 | Decision-tree fitness | Does each fork earn its place? Flag **dead / rarely-useful / mis-placed** forks vs what the run needed. |
+| MR-2 | Data-flow efficiency | Redundant/recomputed transforms; stages that could collapse/parallelize; artifacts produced-and-never-consumed. |
+| MR-3 | Methodology fitness given findings | Was depth/breadth (deep-read tier · analyzer count · sampling) over- or under-scaled for what the findings turned out to be? |
+| MR-4 | Sequence soundness | Reactive one-at-a-time crash patching, re-dispatch loops, redo-after-failure = the order/contract is wrong, not just the code. |
+| MR-5 | Process self-feedback | Concrete, **impact-ranked** proposals: collapse a stage, drop a fork, re-order, pin a choice. |
+| MR-6 | Followed ≠ Right | Explicitly separate conformance (Tab-1) from fitness (here). |
+| MR-7 | Signal/failure-mode selection | Was the primary signal grounded in the RIGHT evidence tier (deep-read-evidenced WHAT, not a frequency artifact)? Highest-leverage. |
+| MR-8 | Confidence derivation | Does the confidence number FOLLOW from the LLM-trace evidence + sample representativeness? Catch asserted-not-earned confidence on imbalanced samples. |
+| MR-9 | Focus determination → search-shaping | Expected-focus vs observed-focus; a wrong/early focus mis-steers every downstream trace selection. |
+## The generic engine (MR-7/8/9 generalized)
+At every behavior-tree node, compare **expected-decision vs observed-decision**
+and **expected-scenario vs observed-scenario**. Diagnostics' signal-selection /
+confidence / focus are the concrete instances; for ANY audited agent, judge its
+sub-decisions the same way: *given the scenario it was actually in, did the agent
+make the decision the methodology expected?*
+## Output contract (masked)
+```yaml
+findings:
+  - mr: MR-7
+    verdict: <fit | mis-fit | inefficient>
+    observation: <what the run actually did at this methodology decision>
+    recommendation: <concrete rearrange/improve proposal>
+    impactRank: <1=highest>          # ranked self-feedback (MR-5)
+    advisory: true                    # NEVER gates the run
+```
+This lens **never** emits a pass/fail that feeds the GATE. It is process
+self-feedback only.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/lenses/trajectory-lens.md ADDED Viewed

@@ -0,0 +1,44 @@
+# Trajectory Lens — generic pinned-judge prompt
+> **Track:** Tab-1 judge rows (checkMethod `trajectory-diff` on operational-
+> deviation rows — R3).
+> **Pinning (R10):** PINNED model id + **temperature = 0**, recorded. **Mask the
+> output.** Two audits on one bundle ⇒ byte-identical verdict.
+> **Parameterized by the loaded subject profile** — no subject-specific logic.
+## Purpose
+Judges **operational deviation** (expected-vs-observed trajectory): which input →
+which path → which fork at known decision points. This is the R3/R9 family — the
+judge is the only thing in the loop for these rows, reading the transcript
+against the behavior-tree.
+## Inputs (supplied by the harness)
+- `behaviorTree` — the golden state-transition spec.
+- `runTrajectory` — the transcript + runMeta stamps.
+- `criterion` — the operational-deviation row under judgment.
+## Method
+1. Reconstruct the **observed path** through the behavior-tree from the
+   transcript (node → fork → node …).
+2. Compare against the **expected path** for the scenario the run was in.
+3. **Out-of-order tool sequences that still reach the goal PASS** — trajectory
+   judging is about goal-reaching and decision-point correctness, not literal
+   ordering. Skipping a *mandatory* step, taking an unwarranted fork, or a
+   reactive re-dispatch loop (the same failure patched one-at-a-time) **FAILS**.
+## Output contract (masked, schema-validated)
+```yaml
+criterion: <statement>
+observedPath: [<nodeId>, <fork>, ...]
+expectedPath: [<nodeId>, <fork>, ...]
+result: pass | fail
+deviation: <the first divergence point, or "none">
+evidence: <transcript quotes proving the observed path>
+rationale: <goal reached via valid path → pass; mandatory-skip / unwarranted-fork → fail>
+```
+**Never fabricate.** An unobservable trajectory is a determinism defect → `fail`.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/references/build-review-interface.md ADDED Viewed

@@ -0,0 +1,83 @@
+# build-review-interface — a browser annotation UI to collect human labels
+> **Source:** absorbed from `mutagent-system/.memory/features/evals-skills-source/skills/build-review-interface/SKILL.md`.
+> **Loaded by:** `*review` (EV-045), rendered by `scripts/build-review-ui.ts`. Load on demand.
+> **Sibling refs:** `error-analysis.md` (what to look for) · `validate-evaluator.md` (the labels feed TPR/TNR).
+Build an HTML page that loads traces from a data source, shows ONE trace at a time with Pass/Fail
+buttons, a notes field, and Next/Previous navigation, and persists labels to a local file. The
+human labels it collects are the ground truth `*validate` calibrates the judge against
+(`HumanLabel`, `scripts/contracts/validation.ts`).
+## How this maps onto the evaluator (the Hybrid, EV-045)
+| Piece | Type | Who |
+|-------|------|-----|
+| **Render the annotation HTML + labels persistence** | Code-only (deterministic template, like `render-report.ts`) | `scripts/build-review-ui.ts` |
+| **A human labels traces in the browser** | HITL gate | a domain expert |
+**Autonomy caveat (afkloop):** in the autonomous loop NO human labels in-browser. The UI is BUILT +
+deterministically smoke-tested (DOM structure asserted) and surfaced as an artifact; `*validate`
+proceeds on whatever labels exist and marks criteria with < ~60 labels `unvalidated` (bias-corrected,
+never blocking on a human — see `validate-evaluator.md`).
+## Data display (render in the most human-readable form for the domain)
+- **Native format**: emails look like emails, markdown rendered, code highlighted, JSON
+  pretty-printed + collapsible, tables as tables, URLs clickable.
+- **Collapse repetitive elements** (a shared system prompt → a `<details>` toggle).
+- **Extract + surface key metadata** (subject id, channel, session id) as a prominent header/badge.
+- **Color-code by role/status** (left-border colors for user / assistant / tool / system).
+- **Group related elements** (a tool call + its response visually linked).
+- **Highlight what matters** (bold prices/dates/names; hierarchy via size + spacing).
+- **Show the full trace** — all intermediate steps accessible, collapsed by default.
+- **Sanitize rendered content** — strip raw HTML from LLM outputs before rendering; disable images
+  in rendered markdown (tracking-pixel risk).
+## Feedback collection (trace-level, not span-level)
+- Binary **Pass / Fail** buttons as the primary action (visually distinct: color + size).
+- Free-text **notes** field.
+- **Defer** button for uncertain cases.
+- **Auto-save on every action** — labels persist without an explicit save.
+- (Later, once failure categories exist, predefined failure-mode tags can be added as checkboxes —
+  NOT in the initial build.)
+## Navigation & status
+Next/Previous (buttons + arrow keys) · trace counter ("12 of 87 remaining") · jump-to-id · labeled
+vs unlabeled counts.
+## Keyboard shortcuts
+```
+Arrow keys = Navigate     1 = Pass     2 = Fail
+D = Defer     U = Undo     Cmd+S = Save     Cmd+Enter = Save and next
+```
+## Selecting traces to load
+The app accepts traces from any source; keep sampling OUTSIDE the app in `scripts/sample-traces.ts`
+(start with the balanced ✓/✗ mix). The app is a pure renderer + label collector.
+## Testing
+After building, verify with Playwright (the human-run path):
+- **Visual review** — screenshots with representative data: visual hierarchy clear? all data in
+  native format (no raw JSON blobs / unrendered markdown)? professional + clean? responsive?
+- **Functional test** — load app → click Pass (label saved) → click Fail + note (both saved) →
+  Defer (recorded) → navigate (buttons + keyboard) → counter updates → reload → labels persist →
+  expand collapsed sections → every keyboard shortcut fires its action.
+In this skill the **deterministic DOM-structure smoke test** (`tests/build-review-ui.test.ts`)
+asserts the controls + handlers + persistence shape exist without a browser dep, so the gate stays
+austere; the Playwright workflow above is the human-run visual/functional verification.
+## Design checklist
+- [ ] Same layout, controls, terminology on every trace
+- [ ] Pass/Fail buttons visually distinct
+- [ ] Keyboard shortcuts work for all primary actions
+- [ ] Full trace accessible even when sections are collapsed
+- [ ] Labels persist automatically (no explicit save)
+- [ ] Trace-level annotation as the default
+- [ ] All data rendered in its native format
+## Anti-patterns
+- **Span-level annotation by default** — judge the whole trace.
+- **Explicit-save-only** — auto-save or labels get lost.
+- **Raw unrendered data** (JSON blobs, unescaped LLM HTML) — render native + sanitize.
+- **Sampling logic inside the app** — keep it in `sample-traces.ts` (separable, testable).