@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/references/grounded-adjudication.md

@@ -0,0 +1,221 @@
+# grounded-adjudication — how a verdict stays bound to its evidence
+
+> **Source:** the GA design review (`mutagent-system/.memory/features/mutagent-evaluator/grounded-adjudication-review.html`, Option 3 · final sign-off).
+> **Loaded by:** every judging path — `*discover-evals` (mine), `*build-evals` (judge), `*evaluate` (the headline trajectory judge + gate). Load on demand.
+> **Sibling refs:** `error-analysis.md` (mine the criterion) · `write-judge-prompt.md` (build the judge) · `validate-evaluator.md` (calibrate it).
+> **PR-locked principles:** `bind-before-judge` · `evidence-proves-claim-not-verdict` · `ground-absence` (`.meta/principles.md`).
+
+A judge is only a judge (EV-051). Grounded Adjudication (GA) is the discipline that keeps that
+judge HONEST: it forbids a verdict from resting on a premise that is neither bound to the situation
+nor surfaced as an assumption, and it makes the judge ABSTAIN when the inputs cannot decide. GA does
+not add a fourth verdict enum and does not change the command surface — it reuses
+`OutcomeVerdict.Uncertain` (carrying a typed `blockedBy`) as the indeterminate state and rides the
+existing 8-command / 3-subagent roster.
+
+---
+
+## The doctrine line
+
+> **A verdict may never outrun its grounding — every premise it rests on is bound to the situation
+> or surfaced as an assumption; when the world is silent, the judge abstains.**
+
+Sourcing secures the **premises**; it never secures the **inference**. Two edges carry the entire
+system: the **binding** of the criterion's terms to this situation (BIND), and the **entailment**
+from the claim to the verdict (VERIFY). Every other step is hygiene around those two.
+
+---
+
+## The 5 Laws → their guards
+
+Five laws, each enforced by exactly one guard. L1 and L2 carry the system.
+
+| Law | Statement | Enforcing guard |
+|-----|-----------|-----------------|
+| **L1 Bind** | Every criterion TERM resolves to a grounded referent here. A valid-yet-unbound term ⇒ **indeterminate, not fail**. (Refs check what you *did* cite — not what the criterion *needed*.) | `resolve-ref` on criterion terms |
+| **L2 Entail** | Evidence proves the **claim**, never the **verdict**. The claim must *entail* the verdict, not merely relate to it. | `result-verifier` (a MODE of `evaluator`, ≠ judge) |
+| **L3 Ground absence** | "X didn't happen" needs a POSITIVE check of the field where X would appear — absence is a finding, not a default. | `lint-grounding` |
+| **L4 Grounded ≠ confident** | Groundedness sets the verdict TYPE (pass / fail / indeterminate); confidence is a scalar ON an already-decided verdict. The two are orthogonal. | verdict **schema** (`OutcomeVerdict` + `confidence` + `blockedBy`) |
+| **L5 Abstain on silence** | Abstain when the INPUTS cannot decide (underdetermined); decide when only YOU are unsure. | the **ternary** (pass / fail / indeterminate) + the litmus |
+
+### The two switches (where you lose to assumptions)
+
+Each input can be flawless; soundness lives in the edges.
+
+1. **criterion → situation (the binding edge).** The criterion is valid in the abstract, but a term
+   it presupposes has no referent here. *Example:* criterion "copy is on-topic with **the
+   advertiser's product**"; situation = blank brief ⇒ "the advertiser's product" has NO referent ⇒
+   **indeterminate (factual · unbound)**, not a fail.
+2. **claim → verdict (the entailment edge · the master switch).** A sourced, verifiable claim proves
+   the **claim** — never the **verdict**. *Example:* ref ✓ sourced; claim ✓ "the copy is about tax
+   software" (true); verdict ✗ "therefore off-topic" ← the leap. The hidden premise ("tax software ≠
+   advertiser's product") is unsourced. The verifier downgrades this to indeterminate.
+
+---
+
+## The verdict lattice
+
+Three verdict types. Indeterminate is `OutcomeVerdict.Uncertain` **REUSED** (not a 4th enum), plus
+an optional `blockedBy:{kind,text}`.
+
+| Verdict | When | Routes |
+|---------|------|--------|
+| **pass** | Entailed by criterion ∧ grounded evidence — every premise stated or sourced. | → CRYSTALLIZE / suite |
+| **fail** | Entailed the other way — a grounded defect, no inferential leap. | → LOCALIZE → diagnostics (EV-051) |
+| **indeterminate(`blockedBy`)** | Underdetermined by the inputs. Never gates; routes to the calibration loop. | by `blockedBy.kind` (below) |
+
+`blockedBy.kind` decides where the calibration loop routes the block:
+
+| `kind` | Meaning | Routes to |
+|--------|---------|-----------|
+| `factual-intent` | a fact / intent missing from the trace | **calibrate** — re-ground from the trace |
+| `normative` | a value judgment the operator owns | **operator** — ratify the norm |
+| `scope` | the criterion does not apply to this route | **re-scope** — narrow / retire / human-verify |
+
+---
+
+## The procedure (the axiom floor)
+
+One criterion × one situation (trace). Run the stages IN ORDER — nothing advances implicitly.
+
+```
+BIND → GATHER → lint → CRITIQUE-before-verdict → DECIDE / ABSTAIN → VERIFY
+```
+
+1. **BIND** *(L1)* — resolve every criterion TERM to a grounded referent in this situation. Any
+   unbound term ⇒ stop here: **indeterminate (factual · unbound referent)**. Do not fail; do not
+   improvise a referent.
+2. **GATHER** — cite RESOLVABLE refs for the claim AND for any absence claim. A ref is structured
+   `{obs, path, value}`: the observation/trace id, the field path, and the EXACT cited value — it
+   must re-resolve by whitespace-normalized exact match.
+3. **lint (deterministic floor)** — `lint-grounding` checks the cheap, mechanical floor BEFORE any
+   judgement: tokens present, every cited ref resolves, code-class rows carry no free-text leap,
+   absence claims carry a positive field check *(L3)*. Lint is **fail-new, warn-old** (strictness
+   applies to newly minted artifacts; pre-existing ones warn).
+4. **CRITIQUE-before-verdict** — write the critique FIRST, then run the **litmus**: name the
+   *minimal* premise `P` such that `(criterion ∧ situation ∧ P) ⊢ V`. If every such `P` is grounded
+   or inside the deterministic floor → proceed to DECIDE. If some `P` is ungroundable → surface it as
+   a TYPED assumption (`factual-intent` / `normative` / `scope`) and emit **indeterminate
+   (`blockedBy{kind}`)**.
+5. **DECIDE / ABSTAIN** *(L5)* — pass or fail (+ a confidence scalar, L4) when the litmus premises
+   hold; ABSTAIN (indeterminate) when the inputs cannot decide.
+6. **VERIFY** *(L2)* — an INDEPENDENT pass (`result-verifier`, ≠ the judge, **downgrade-only**) asks
+   the single question: *does the claim entail the verdict?* If it finds an inferential leap, it
+   downgrades the verdict to **indeterminate (residual assumption)**. It can never upgrade.
+
+Every indeterminate exit (unbound term · ungroundable premise · residual leap) feeds the
+**calibration loop**, not the gate.
+
+---
+
+## Observed-eligibility (GA-11 — the diff-discriminate cut)
+
+A criterion is **OBSERVED** only when it actually discriminates: it must fire on a BROKEN trace ∧
+NOT fire on a HEALTHY one (`diff-discriminate`). This is the honesty cut that stops a good-practice
+guard from being laundered into an "observed" failure.
+
+| Situation | Result |
+|-----------|--------|
+| fires on broken ∧ not on healthy | **observed** — gate-eligible (cites refs + honest k/n prevalence) |
+| no healthy trace available | **graceful single-trace fallback** — diff SKIPPED, honest prevalence, TAGGED; never a hard fail |
+| no discriminating diff | **inferred** — kept in the suite as a guard, NOT gate-eligible |
+
+`grounding` is the three-tier honesty ladder: `observed` (a failure was actually seen, with refs +
+k/n) · `inferred` (a guard with no observed failure yet) · `hypothesis-pending` (a hypothesis
+awaiting evidence, the weakest tier). OBSERVED ⇒ non-empty `refs` ∧ `k > 0` (the evidence-first
+gate `parseMinedCriterion` enforces).
+
+---
+
+## The elimination / calibration loop
+
+Indeterminate is not a dead end — it is the on-ramp to calibration, which re-enters ADJUDICATE once
+the blocking assumption is grounded, ratified, or verified, or RETIRES the criterion.
+
+```
+indeterminate → CALIBRATE → re-enter ADJUDICATE   (or RETIRE)
+```
+
+| From CALIBRATE | Guard | To |
+|----------------|-------|-----|
+| re-ground | the missing fact is found in the trace | → ADJUDICATE (re-enter) |
+| operator-ratify | a `normative` assumption is ratified by the operator | → ADJUDICATE (re-enter) |
+| re-scope | the criterion is narrowed / scoped out | → ADJUDICATE (re-enter) |
+| human-verify | a human verifies the assumption directly | → SUITE (the criterion graduates) |
+| retire | persistent human disagreement (assumption-poisoned) | → RETIRE the criterion |
+
+Assumption lifecycle: `hypothesis → unverified → verified` (graduate) **or** `→ eliminated` (the
+calibration-loop terminal state: disproven / retired, not merely verified). A criterion whose
+blocking assumption is eliminated is re-adjudicable.
+
+---
+
+## The gate (run level) — `fail ▸ incomplete ▸ pass`
+
+The gate is the one intentional behavior delta GA introduces — it kills the latent **false-green**.
+
+- A component is **incomplete** iff a CRIT/HIGH criterion adjudicated **uncertain / indeterminate**
+  and no positive path re-grounded it.
+- A component **fails** iff a CRIT/HIGH criterion **failed**.
+- Otherwise the component **passes**.
+- `runVerdict = fail ▸ incomplete ▸ pass` (the run takes the worst component state).
+
+```
+component fail        iff ≥1 CRIT/HIGH criterion FAILED
+component incomplete  iff (no CRIT/HIGH fail) ∧ ≥1 CRIT/HIGH INDETERMINATE
+component pass        otherwise
+runVerdict            = fail ▸ incomplete ▸ pass
+```
+
+`RunVerdict.Incomplete` is a RUN-level rollup state distinct from the per-criterion
+`OutcomeVerdict`. Before GA, a CRIT/HIGH `uncertain` silently PASSED; after GA it surfaces as
+`incomplete` — the gate refuses to certify what it could not adjudicate. `*evaluate` may now return
+`incomplete`; this is the single caller-visible delta of GA (the 8-command / 3-subagent surface is
+otherwise frozen).
+
+### Grandfather rules (won't break existing evals)
+
+1. **missing `grounding` ⇒ inferred** — legacy lightweight criteria default to `inferred`, never
+   rejected; the hard gate fires only on `observed`. Coexist, upgrade lazily.
+2. **no healthy trace ⇒ graceful** — `*discover-evals` falls back to single-trace + honest prevalence
+   (diff skipped, tagged), never a hard fail.
+3. **lint: fail-new, warn-old** — strictness applies to newly minted artifacts; pre-existing ones
+   warn. No retroactive voiding.
+
+Reusing `uncertain` (not a 4th enum) means the ~17 verdict consumers compile unchanged; the only
+intentional behavior delta is **false-green → incomplete** (a fix).
+
+---
+
+## The two invariant corrections
+
+1. **`first_thing_wrong_only` → root-not-symptom (judged).** The old rule conflated DETECTION with
+   LOCALIZATION: the first *visible* wrong is often downstream of the real root, and a single-cascade
+   assumption drops independent causes. **KEEP** one criterion per ROOT (dedup the cascade). **FIX:**
+   trace to the root with JUDGEMENT, not the first symptom — multiple INDEPENDENT roots ⇒ multiple
+   criteria; a causal-link claim must be GROUNDED (cite the edge) or SURFACED as an assumption
+   (= indeterminate localization); deep recursive-why routes to diagnostics.
+2. **code/agent hybrid at the COMMAND level (mirrors diagnostics).** Code-before-judge applies not
+   just per-criterion but per-WORKFLOW: a deterministic skeleton, with the LLM only at the leaf where
+   judgement is irreducible.
+
+| Side | Steps |
+|------|-------|
+| **CODE** (deterministic) | sample · `resolve-ref` · `diff-discriminate` · `lint-grounding` · aggregate · gate · code-class criteria |
+| **JUDGE** (LLM leaf) | determine · critique · adjudicate · verify · localize · judge-class criteria |
+
+Mirrors diagnostics: slicer / tier0 (code) + analyzers (LLM).
+
+---
+
+## Law → guard quick reference
+
+| Law | Guard | Kind |
+|-----|-------|------|
+| L1 Bind | `resolve-ref` (criterion terms) | new script (code) |
+| L2 Entail | `result-verify` — a MODE of `evaluator`, downgrade-only | new script + judge mode |
+| L3 Ground absence | `lint-grounding` | new script (code) |
+| L4 Grounded ≠ confident | verdict schema (`OutcomeVerdict` + `confidence` + `blockedBy`) | contract |
+| L5 Abstain on silence | the ternary (pass / fail / indeterminate) + litmus | contract + judge |
+
+> GA changes INTERNALS only. The command surface, the subagent roster, and the v1 `*audit` world are
+> untouched; `result-verify` is a MODE of the existing `evaluator` cell, not a new registered agent.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/references/memory-format.md

@@ -0,0 +1,65 @@
+# AutoMemory — project-level operator-feedback + system self-learning
+
+> **Mirror (parity).** This is the SHARED AutoMemory standard for the ADL lifecycle
+> skills. The diagnostics + evaluator skills carry a BYTE-PARITY copy (a parity test
+> asserts they don't drift). The subject is **the TOOL + operator preferences — NOT
+> the diagnosed/evaluated agent.** ONE project-level store for the whole lifecycle.
+
+## Location + shape — Claude-Code AutoMemory format (verbatim)
+
+```
+.mutagent/memory/                    ← project-level, COMMITTED
+  MEMORY.md                          ← index: `- [Title](<slug>.md) — <hook>` one line/entry
+  <slug>.md                          ← one FACT per file
+```
+
+Each `<slug>.md` entry:
+
+```markdown
+---
+name: <short-kebab-case-slug>
+description: <one-line summary — used to decide relevance during recall>
+metadata:
+  type: user | feedback | project | reference    # Claude Code's four types
+  lifecycle: spec|build|evaluate|diagnose|improve|general   # ADL extension
+  created: YYYY-MM-DD                             # REQUIRED · every memory is DATED (stale-pruning)
+---
+
+<the fact. For feedback/project: **Why:** + **How to apply:** lines. Link with [[their-name]].>
+```
+
+- **Every entry DATED** (`metadata.created`). `MEMORY.md` = index only.
+- **Dedupe on append** (update the existing entry + refresh its date; never a second file for the same slug).
+- **Lifecycle-tagged.** A run READS entries whose `lifecycle ∈ {this-stage, general}`. For the
+  evaluator, `this-stage = evaluate` → read `lifecycle ∈ {evaluate, general}`.
+
+## Feedback → type CLASSIFICATION rubric (at append)
+
+Decision order — **first match wins**:
+
+| # | Feedback about… | → type | Signals | Body |
+|---|---|---|---|---|
+| 1 | external resource | `reference` | URL · dashboard · ticket · dataset path | pointer + what it's for |
+| 2 | who the operator is | `user` | "I'm the lead" · standing preference | the trait |
+| 3 | how the tool should behave | `feedback` | "stop surfacing X" · "too verbose" · "next time…" | fact + **Why:** + **How to apply:** |
+| 4 | ongoing work/goals/constraints | `project` | "migrating to…" · "don't touch Z until…" | fact + **Why:** + **How to apply:** |
+
+**Do NOT save:** already-in-code/config/git · ephemeral-to-one-run · subject findings (those go to the
+living-suite / class-memory library, NOT here).
+
+## Why AutoMemory is separate from the other memory subsystems
+
+These do NOT compete — they have different SUBJECTS:
+
+| Subsystem | Subject | Content | Write trigger | Location |
+|---|---|---|---|---|
+| **Living suite** (eval) | the evaluated subject | accumulated eval criteria | per discover run | `.mutagent/evaluator/living-suite/` |
+| **Class-memory library** (diag) | the diagnosed entity | journal + patterns + ledger | operator-APPROVED findings | `.mutagent/diagnostics/library/…` · gitignored |
+| **AutoMemory** (this) | the tool + operator | usage-feedback + lessons (dated, classified) | operator feedback | `.mutagent/memory/` · committed |
+
+## Evaluator wiring
+
+- **READ at run START** (`cli/prep.ts` + the run start): load `.mutagent/memory/` filtered by
+  `lifecycle ∈ {evaluate, general}` and inject as operator-preference context.
+- **APPEND at run END** on operator feedback: classify → dated + lifecycle-tagged entry → dedupe → index line.
+- **COMMITTED** — no subject-private data ever lands here.

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/references/methodology.md

@@ -0,0 +1,201 @@
+# Evaluator Methodology — distilled determinism-control reference
+
+> **Taken IN (distilled), not referenced on disk.** This is the generic
+> methodology + determinism-control vocabulary the evaluator operates by,
+> distilled from the Variance & Operational Behavioral Deviance Reduction
+> Operational Manual + the mdiag-master-audit lens. The evaluator does NOT read
+> any file under `.mutagent/diagnostics/audits/` at runtime — everything it needs
+> is here.
+>
+> **NDA:** synthetic identifiers only. No production dataset is named.
+
+---
+
+## 0. The 6-stage Agent-Outcome Evaluation backbone
+
+> The human evaluation flow as the **backbone**; Grounded Adjudication as the
+> Adjudicate core; the binary code/judge suite-construction kept; the calibration
+> loop wrapping it. Each stage declares whether it is **code** (deterministic) or
+> **judge** (LLM leaf) — the same code/agent-hybrid split Diagnostics uses
+> (slicer/tier-0 = code · analyzers = LLM). See `grounded-adjudication.md` for the
+> full doctrine (the 5 Laws, the verdict lattice, the two switches).
+
+A **scenario = an intent ROUTE** the agent handles on its decision tree (system
+prompt + skills). A human judges *per route*: establish the frame, read the
+trajectory, detect the three failure kinds, adjudicate, root-cause, crystallize.
+
+| # | Stage | code/judge | What it does |
+|---|-------|-----------|--------------|
+| ① | **CONTEXT** | judge | Establish the frame: the harness model (sysprompt · tools · skills · decision tree) + the INPUT's intent ROUTE → its intended success condition. The BIND target. |
+| ② | **TRAJECTORY** | code | Parse the tool / decision sequence the agent actually took (deterministic). |
+| ③ | **DETECT** | mixed | The 3 lenses — **drift/off-path** (judge) · **tool-output failure** (code/fixable) · **missing-context** (BIND / code). Emit candidate signals (≥0). |
+| ④ | **ADJUDICATE** | judge (guard) | Grounded Adjudication: **BIND · GATHER · CRITIQUE · DECIDE/ABSTAIN · VERIFY** → `pass · fail · indeterminate`. The core. |
+| ⑤ | **LOCALIZE** | judge | On a fail: **root-not-symptom** (§3a) — causal chain + locus (prompt · tool · context · skill). Deep RCA → diagnostics. |
+| ⑥ | **CRYSTALLIZE** | judge→code | Turn each root into a binary, actionable **CODE | JUDGE** criterion → the expanding eval suite + dataset. |
+
+### Transition conditions (every edge has a guard — nothing advances implicitly)
+
+| From | Transition condition (guard) | To |
+|------|------------------------------|----|
+| CONTEXT | route resolved ∧ route-intent bound | TRAJECTORY |
+| CONTEXT | route unresolvable / no intent | → CALIBRATE (indeterminate · scope) |
+| TRAJECTORY | parsed (deterministic) | DETECT |
+| DETECT | candidate signals emitted (≥0) | ADJUDICATE |
+| ADJUDICATE | **pass** ∧ verifier confirms claim ⊨ verdict | CRYSTALLIZE |
+| ADJUDICATE | **fail** ∧ verifier confirms claim ⊨ verdict | LOCALIZE |
+| ADJUDICATE | unbound term ∨ ungroundable premise ∨ residual leap | → CALIBRATE (indeterminate) |
+| LOCALIZE | root found ∧ causal edge grounded | CRYSTALLIZE |
+| LOCALIZE | causal edge ungroundable | → CALIBRATE (indeterminate localization) |
+| LOCALIZE | deep recursive-why required | ⤳ diagnostics (handoff) + continue |
+| CRYSTALLIZE | binary ∧ actionable ∧ observed (broken∧¬healthy diff ✓) | SUITE (gate-eligible) |
+| CRYSTALLIZE | no diff discriminate / single-trace | SUITE as **inferred** (guard, not gate) |
+| CALIBRATE | re-ground (fact found) ∨ normative ratified by operator | → ADJUDICATE (re-enter) |
+| CALIBRATE | human verifies the assumption | SUITE (criterion graduates) |
+| CALIBRATE | persistent human disagreement | RETIRE (assumption-poisoned) |
+| SUITE | all criteria adjudicated | GATE → **fail ▸ incomplete ▸ pass** |
+
+**Indeterminate is not a dead end** — it is the on-ramp to the calibration loop,
+which re-enters ADJUDICATE once the blocking assumption is grounded, ratified, or
+verified, or retires the criterion. Reusing `OutcomeVerdict.Uncertain` (+ a typed
+`blockedBy`) IS the indeterminate state — **not** a 4th enum value.
+
+---
+
+## 1. MECE scope model (root-cause locus, not symptom site)
+
+Every defect/criterion is assigned to **exactly one** scope by the **locus of the
+root cause**, not where the symptom appears:
+
+- **COMMAND** — a code bug or a missing runnable code deliverable. Fix = a code
+  change (guard, reorder, new script, schema loader). Locus = a `.ts` file (or a
+  script that should exist). Owner = engineer.
+- **SKILL** — a missing, ambiguous, or under-specified **specification**:
+  protocol prose, a contract document, a schema description, or a mandate that a
+  script be called. Fix = author/tighten the spec.
+- **AGENT** — runtime **behavior**: a discretionary judgment, improvisation,
+  hand-shaping, protocol deviation, or reactive fix. Fix via **cure-the-twin** —
+  an AGENT deviance is cured by landing its SKILL/COMMAND twin (removing the
+  ambiguity/bug that forced the improvisation).
+
+**three-locus spawn:** a single root cause spawns **at most one** COMMAND + one
+SKILL + one AGENT defect.
+
+---
+
+## 2. Three-dimension MECE coverage per component
+
+Every component is graded on three dimensions (omit a dimension only when it has
+no checkable surface there — never to pad):
+
+- **operation-correctness** — sequence right + each op did its job (R1).
+- **data-correctness** — input AND output contracts per component (R2).
+- **operational-deviation** — expected-vs-observed trajectory (R3).
+
+---
+
+## 3. Severity by variance-impact (not code size)
+
+- **CRIT** — flips a headline/primary signal, crashes render, blocks the
+  deliverable, OR is a dominant inter-run variance driver (missing model/temp
+  pin, cwd/config-root unpinned, latency short-circuit, OOM ingest).
+- **HIGH** — materially changes sample composition / finding count / coverage
+  honesty.
+- **MED / LOW** — interpretation / capability / escalation gaps.
+
+---
+
+## 3a. root-not-symptom (the LOCALIZE invariant · GA)
+
+The localization stage (⑤) obeys **root-not-symptom**, which REPLACES the prior
+`first_thing_wrong_only` rule (it conflated detection with localization — the first
+*visible* wrong is usually downstream of the real root, and its single-cascade
+assumption silently drops independent causes):
+
+- **KEEP** one criterion per **ROOT** — dedup the cascade (matches §1's "locus of
+  the root cause, not where the symptom appears").
+- **FIX** — trace to the root with **judgement**, not the first symptom.
+- **Multiple INDEPENDENT roots ⇒ multiple criteria** (the cascade assumption is
+  dropped).
+- A **causal-link claim** (root → symptom) must be **GROUNDED** (cite the edge via a
+  ref) OR surfaced as a **typed assumption** → an **INDETERMINATE localization** (not
+  a fail).
+- **Deep recursive-why → `mutagent-diagnostics`.** The evaluator localizes (locus:
+  prompt · tool · context · skill); it does not run full RCA.
+
+See `references/error-analysis.md` (the 3 detection lenses + root-not-symptom) and
+`grounded-adjudication.md` (the doctrine).
+
+---
+
+## 4. Determinism-control vocabulary
+
+Every remedy is framed as the specific **Determinism Control** that converts an
+improvised/stochastic path into a reproducible one:
+
+| Control | Converts |
+|---------|----------|
+| **C-SCRIPT** | improvisation → a MANDATED runnable script (streaming ingest, assemble-runmeta, …). |
+| **C-SCHEMA** | guessing → FULL types/enums/examples embedded in the contract. |
+| **C-GATE** | a partial gate → one that covers the FULL dereference surface and fails-loud ONCE with all gaps. |
+| **C-GUARD** | a throw-on-absence → an undefined/shape guard in code. |
+| **C-PIN** | a stochastic/environmental variable → pinned AND recorded into runMeta (model id, temperature = 0, seed, runId-namespace, configRoot, injected `--generated-at`). Honors **model-intent-sacred**: no silent swaps. |
+
+**Class taxonomy** (8): `code-bug` · `missing-determinism` · `schema-contract-gap`
+· `gate-coverage-gap` · `capability-gap` · `skill-forced-improvisation` ·
+`agent-discretion` · `reactive-improvisation`.
+
+**Named root causes (RC-\*):** RC-INGEST · RC-ENV · RC-LLM-PIN · RC-RUNMETA ·
+RC-LATENCY · RC-SCHEMA · RC-SAMPLE · RC-GATE · RC-CONFIG. The **dominant triads**
+twin-coupling enforces are RC-INGEST / RC-ENV / RC-LLM-PIN / RC-RUNMETA.
+
+**Variance Mechanism** — the per-defect statement of HOW the gap causes two runs
+to diverge (the causal chain from gap → divergence). Mandatory per criterion.
+
+---
+
+## 5. Byte-identity masking contract
+
+"Byte-identical across runs" is only testable **AFTER masking** the declared
+injected fields. Run the pipeline twice on byte-identical source (back-to-back,
+then a second machine), mask `runId` / timestamps / abs-paths (the **versioned
+masking set**, `scripts/mask.ts`), then diff each artifact. The **variance
+score** = count of differing scorecard dimensions — that number (not vibes) is
+the determinism signal.
+
+---
+
+## 6. The re-audit + 15-dimension determinism scorecard
+
+Re-auditing measures variance reduction over time against a **fixed** scorecard.
+Two layers:
+
+- **Per-defect verification** — every tracked defect carries an explicit,
+  executable pass condition ("run 3× → byte-identical artifact"; "the gate fails
+  listing all gaps in one pass, fixed input passes"; "two runs → same findingId
+  set"). A fix is verified only when its stated criterion passes against HEAD.
+- **Whole-run scorecard** — the fixed 15 dimensions (headline latency p50,
+  render crashes, gate fail-loud completeness, (n, analyzerCount), primary
+  signal, finding-id set, remedy ranking, slice plan, sampling buckets, coverage
+  confidence, tier-0 signals, entity identity, caps firstToTrip, awareness-fire,
+  heatmap cells). Each has a Measure + a per-Phase Target; a run-pair is scored
+  by masked diff per dimension. See `scripts/variance-compare.ts`.
+
+---
+
+## 7. Two-track rollup + twin-coupling
+
+- **Track-1 GATE** — binary, severity-gated. Component PASS iff 0 CRIT/HIGH
+  fail. Run PASS iff all components pass. Advisory.
+- **Track-2 TREND** — the 15-dim variance score, SEPARATE, never merged.
+- **Twin-coupling (inner → outer)** — the agent is graded on its OWN behavior
+  first; inner-OK ⇒ functional even if the skill-link is defective (defect →
+  SKILL scope). Coupling enforced only on the dominant triads (RC-INGEST / ENV /
+  LLM-PIN / RUNMETA).
+
+---
+
+## 8. Reviewer ≠ executor; coordinator ≠ executor
+
+The audit never grades a run it produced. The variance **coordinator** (who
+compares the two variants) is a role distinct from the audit **executors**. The
+audit itself obeys C-PIN so it is as deterministic as the thing it audits.