@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/enrich/corpus-severity.ts

@@ -0,0 +1,172 @@
+/**
+ * scripts/enrich/corpus-severity.ts
+ * ② Corpus-relative severity calibration — the G-2 over-alarming fix (SL-8 / DS-02).
+ * Type A — Pure Script (deterministic numeric scoring, no LLM calls, no I/O).
+ *
+ * PROBLEM (SL-8, run SL-8-diag-dual-…14-34-32): on the all-clean control dataset DS-02,
+ * `*diagnose` raised 2 CRIT + 3 HIGH on 50 certified-clean traces because a numeric
+ * anomaly's SEVERITY was assigned by ABSOLUTE thresholds, not corpus-relative norms — a
+ * latency that IS the corpus baseline got escalated to CRIT.
+ *
+ * FIX — reuse the proven FI-LAT rubric recipe (do NOT invent a model): a numeric anomaly's
+ * SEVERITY is scored against the corpus's OWN distribution. Concretely:
+ *   • compare each span ONLY against spans of the SAME name;
+ *   • band(name) = BAND_MULTIPLIER (3) × that name's p90, with an absolute FLOOR;
+ *   • a value is a SPIKE (→ high/crit severity) ONLY if it exceeds BOTH its name-band AND
+ *     the floor. Below either bound it is corpus-normal → med/info, never crit/high.
+ *
+ * The floor guards a FAST corpus: a 50ms value that is 5× a 10ms p90 is a relative outlier
+ * but not a real latency problem, so the absolute floor keeps it out of crit/high.
+ *
+ * PROPOSED principle (operator-locked constitution): see
+ *   .meta/prd.yaml key_problems → KP-023 (proposed PR-056).
+ * `.meta/design-principles.md` is operator-LOCKED and is NOT edited here.
+ */
+
+/** Severity grades a numeric anomaly can resolve to (subset of Finding.severity). */
+export type NumericSeverity = "crit" | "high" | "med" | "info";
+
+/** band(name) = BAND_MULTIPLIER × p90(name). FI-LAT rubric = 3×. */
+export const BAND_MULTIPLIER = 3;
+
+/**
+ * Absolute latency floor (ms). Nothing below this is ever a spike, regardless of how far
+ * it sits above its name-band. Mirrors tier0-scan.ts HIGH_LATENCY_MS (10_000) for parity.
+ */
+export const DEFAULT_LATENCY_FLOOR_MS = 10_000;
+
+/** A (name, value) sample — the numeric metric grouped by its span/agent name. */
+export interface NameValue {
+  /** Span / agent / operation name the value is compared WITHIN. */
+  name: string;
+  /** The numeric metric (e.g. latency in ms). */
+  value: number;
+}
+
+/** The corpus's own distribution, computed once per run and reused per finding. */
+export interface CorpusBaseline {
+  /** p90 of the metric per span name. */
+  p90ByName: Map<string, number>;
+  /** p90 across ALL values — fallback when a finding's name is unseen in the corpus. */
+  overallP90: number;
+  /** Absolute floor below which nothing is a spike. */
+  floor: number;
+  /** Multiplier applied to a name's p90 to get its spike band. */
+  bandMultiplier: number;
+  /** How many samples fed the baseline (0 = no corpus data → callers should skip). */
+  sampleCount: number;
+}
+
+/** The verdict for a single value scored against the corpus. */
+export interface SpikeVerdict {
+  /** True iff value > name-band AND value > floor. */
+  isSpike: boolean;
+  /** Corpus-relative severity grade. */
+  severity: NumericSeverity;
+  /** The evaluated value. */
+  value: number;
+  /** bandMultiplier × p90(name) — the relative spike threshold. */
+  nameBand: number;
+  /** The absolute floor applied. */
+  floor: number;
+}
+
+/**
+ * Nearest-rank percentile over a numeric array (deterministic). Identical semantics to
+ * build-render-input.ts `percentile` — kept local so this module stays dependency-light
+ * (build-render-input imports THIS file, so importing back would create a cycle).
+ */
+export function percentile(values: number[], p: number): number {
+  if (values.length === 0) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const rank = Math.max(0, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[rank];
+}
+
+/** Rank a severity for MAX-severity aggregation across a finding's source spans. */
+const SEVERITY_RANK: Record<NumericSeverity, number> = { info: 0, med: 1, high: 2, crit: 3 };
+
+/**
+ * Compute the corpus baseline (per-name p90 + overall p90) from a batch of (name, value)
+ * samples. Deterministic. sampleCount === 0 signals "no corpus data" so callers can skip
+ * calibration rather than fabricate a baseline from nothing.
+ */
+export function computeCorpusBaseline(
+  samples: NameValue[],
+  opts?: { floor?: number; bandMultiplier?: number }
+): CorpusBaseline {
+  const floor = opts?.floor ?? DEFAULT_LATENCY_FLOOR_MS;
+  const bandMultiplier = opts?.bandMultiplier ?? BAND_MULTIPLIER;
+
+  const byName = new Map<string, number[]>();
+  const all: number[] = [];
+  for (const s of samples) {
+    if (!Number.isFinite(s.value)) continue;
+    all.push(s.value);
+    const arr = byName.get(s.name);
+    if (arr) arr.push(s.value);
+    else byName.set(s.name, [s.value]);
+  }
+
+  const p90ByName = new Map<string, number>();
+  for (const [name, vals] of byName) p90ByName.set(name, percentile(vals, 90));
+
+  return {
+    p90ByName,
+    overallP90: percentile(all, 90),
+    floor,
+    bandMultiplier,
+    sampleCount: all.length,
+  };
+}
+
+/**
+ * Score ONE (name, value) against the corpus. A value is a spike ONLY if it clears BOTH
+ * its name-band (3× the name's p90) AND the absolute floor. Spikes grade high, or crit
+ * when extreme (≥ 2× the name-band); non-spikes are med (absolutely slow but corpus-normal)
+ * or info (below the floor). A baseline-normal value therefore never grades crit/high.
+ */
+export function corpusRelativeSeverity(
+  name: string,
+  value: number,
+  baseline: CorpusBaseline
+): SpikeVerdict {
+  const p90 = baseline.p90ByName.get(name) ?? baseline.overallP90;
+  const nameBand = baseline.bandMultiplier * p90;
+  const floor = baseline.floor;
+  const isSpike = value > nameBand && value > floor;
+
+  let severity: NumericSeverity;
+  if (isSpike) {
+    severity = value >= 2 * nameBand ? "crit" : "high";
+  } else if (value > floor) {
+    // above the absolute floor but within its cohort's norms → notable, not alarming.
+    severity = "med";
+  } else {
+    severity = "info";
+  }
+  return { isSpike, severity, value, nameBand, floor };
+}
+
+/**
+ * Calibrate a finding's numeric-anomaly severity from its source spans. Evaluates EACH
+ * (name, value) against the corpus and returns the MAX-severity verdict (a single genuine
+ * spike dominates; if none of the finding's spans spike, the finding is corpus-normal).
+ * Returns null when there are no scorable spans, so the caller leaves severity untouched.
+ */
+export function calibrateFromSpans(
+  spans: NameValue[],
+  baseline: CorpusBaseline
+): SpikeVerdict | null {
+  const scorable = spans.filter((s) => Number.isFinite(s.value));
+  if (scorable.length === 0 || baseline.sampleCount === 0) return null;
+
+  let worst: SpikeVerdict | null = null;
+  for (const s of scorable) {
+    const v = corpusRelativeSeverity(s.name, s.value, baseline);
+    if (worst === null || SEVERITY_RANK[v.severity] > SEVERITY_RANK[worst.severity]) {
+      worst = v;
+    }
+  }
+  return worst;
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/enrich/dismissal-match.ts

@@ -0,0 +1,270 @@
+/**
+ * scripts/enrich/dismissal-match.ts
+ * DISMISSAL FINAL-CHECK — semantic suppression of previously-dismissed findings.
+ * Type A — Pure Script (deterministic; the reasoning VERDICT is INJECTED, not computed here).
+ *
+ * THE MATCH (operator decision): a new finding is the SAME failure mode as a dismissed
+ * one when BOTH hold:
+ *   1. entitySlug EXACT match (same diagnosed entity), AND
+ *   2. SEMANTIC OVERLAP of the (what, why, where) failure-mode triple.
+ *
+ * The (what, why, where) prose is LLM-generated and will NEVER string-match run-to-run,
+ * so it is NOT exact-matched. Instead a PINNED host-runtime reasoning check (temperature 0,
+ * C-PIN) compares the triples and returns { overlap, confidence }. That reasoning runs
+ * OUTSIDE this module (the orchestrator dispatches it at the enrich final-check step — see
+ * references/workflows/orchestrator-protocol.md), keeping build-render-input's "no LLM, no
+ * network, no random" contract intact. This module owns the DETERMINISTIC half:
+ *   - buildSemanticMatchRequest() — the pinned, reproducible request the orchestrator sends;
+ *   - decideSuppress()            — the ONE deterministic decision fed by the reasoning verdict;
+ *   - partitionByDismissal()      — splits findings into active / suppressed, applying the
+ *                                   severity-escalation HARD GUARD *before* the semantic match.
+ *
+ * CONSERVATIVE / FAIL-SAFE: suppress ONLY on high-confidence overlap. When the reasoning
+ * check is unsure (missing verdict, low/medium confidence, or overlap:false) the finding is
+ * NOT suppressed — it shows. A dismissed finding is hidden only when we are confident it is
+ * the same not-an-issue; otherwise the operator sees it.
+ */
+
+import type { Finding } from "../normalize/trace.ts";
+import type { VerdictLedgerEntry, VerdictSeverity } from "../library/types.ts";
+
+// ── Pinned reasoning envelope (RC-LLM-PIN parity) ────────────────────────────
+//
+// Mirrors the analyzer/orchestrator inference pin (orchestrator-protocol.md §W13-C):
+// model claude-sonnet-4-6 default, temperature 0 unconditional. The C-PIN string binds
+// {promptVersion, model, temperature} so the request is byte-identical run-to-run →
+// reproducible verdicts. Honors feedback_model_intent_sacred — declared intent, no swap.
+
+/** Default pinned model for the semantic-match reasoning check. */
+export const SEMANTIC_MATCH_MODEL = "claude-sonnet-4-6";
+/** Temperature is PINNED to 0 (deterministic sampling) — never overridden. */
+export const SEMANTIC_MATCH_TEMPERATURE = 0;
+/** Prompt version — bump to invalidate cached verdicts when the prompt changes. */
+export const SEMANTIC_MATCH_PROMPT_VERSION = "v1";
+
+/**
+ * C-PIN — the reproducibility tag binding the pinned inference envelope. A stable,
+ * human-readable string so two runs with the same inputs produce byte-identical requests.
+ */
+export function semanticMatchCPin(model: string = SEMANTIC_MATCH_MODEL): string {
+  return `dismissal-semantic-match@${SEMANTIC_MATCH_PROMPT_VERSION}|${model}|t${SEMANTIC_MATCH_TEMPERATURE}`;
+}
+
+/** A single failure-mode triple (what / why / where) + optional narration. */
+export interface FailureTriple {
+  what: string;
+  why: string;
+  where: string;
+  whatHappened?: string;
+}
+
+/** The pinned, reproducible request the orchestrator sends to the host-runtime reasoning check. */
+export interface SemanticMatchRequest {
+  /** Pinned model (RC-LLM-PIN). */
+  model: string;
+  /** PINNED to 0. */
+  temperature: number;
+  /** Reproducibility tag (binds prompt-version + model + temperature). */
+  cPin: string;
+  /** The new finding's failure-mode triple. */
+  candidate: FailureTriple;
+  /** The dismissed ledger entry's failure-mode triple. */
+  dismissed: FailureTriple;
+  /** The entity slug both must share (EXACT-match half of the check). */
+  entitySlug: string;
+  /** The critique-before-verdict instruction (deterministic given the triples). */
+  prompt: string;
+}
+
+/** The verdict the reasoning check returns — overlap yes/no + confidence. */
+export interface SemanticMatchVerdict {
+  /** True when the reasoning check judges the two failure modes the SAME. */
+  overlap: boolean;
+  /** How confident that judgment is. Only "high" + overlap suppresses. */
+  confidence: "high" | "medium" | "low";
+  /** Optional critique/rationale (audit — not used by the deterministic decision). */
+  rationale?: string;
+}
+
+/** Build the deterministic critique-before-verdict prompt for one triple pair. */
+function buildPrompt(candidate: FailureTriple, dismissed: FailureTriple, entitySlug: string): string {
+  const fmt = (t: FailureTriple): string =>
+    `  what:  ${t.what}\n  why:   ${t.why}\n  where: ${t.where}` +
+    (t.whatHappened ? `\n  whatHappened: ${t.whatHappened}` : "");
+  return [
+    `You are comparing two agent-diagnostics findings for the SAME entity (${entitySlug}).`,
+    `A prior finding was DISMISSED by the operator as "not an issue". A new finding was just produced.`,
+    `Decide whether the NEW finding describes the SAME underlying failure mode as the DISMISSED one.`,
+    ``,
+    `DISMISSED finding (failure-mode triple):`,
+    fmt(dismissed),
+    ``,
+    `NEW finding (failure-mode triple):`,
+    fmt(candidate),
+    ``,
+    `First CRITIQUE the comparison (what matches, what differs — surface wording differs run-to-run,`,
+    `so judge the MEANING, not the phrasing). Then return a verdict:`,
+    `- overlap: true ONLY if it is the same failure mode (same what happening for the same reason at the same place).`,
+    `- confidence: "high" | "medium" | "low".`,
+    `Be CONSERVATIVE: reserve "high" for an unambiguous same-failure-mode match. When unsure, do NOT claim high.`,
+  ].join("\n");
+}
+
+/**
+ * Build the pinned, reproducible semantic-match request for one (candidate, dismissed) pair.
+ * Deterministic — same inputs ⇒ byte-identical request (the reproducibility guarantee).
+ */
+export function buildSemanticMatchRequest(
+  candidate: FailureTriple,
+  dismissed: FailureTriple,
+  entitySlug: string,
+  model: string = SEMANTIC_MATCH_MODEL
+): SemanticMatchRequest {
+  return {
+    model,
+    temperature: SEMANTIC_MATCH_TEMPERATURE,
+    cPin: semanticMatchCPin(model),
+    candidate,
+    dismissed,
+    entitySlug,
+    prompt: buildPrompt(candidate, dismissed, entitySlug),
+  };
+}
+
+/**
+ * THE ONE deterministic decision fed by the reasoning verdict. CONSERVATIVE / fail-safe:
+ * suppress ONLY on high-confidence overlap. Anything else (no verdict, overlap:false,
+ * medium/low confidence) → do NOT suppress (the finding shows).
+ */
+export function decideSuppress(verdict: SemanticMatchVerdict | undefined): boolean {
+  if (!verdict) return false;
+  return verdict.overlap === true && verdict.confidence === "high";
+}
+
+// ── Severity-escalation HARD GUARD ───────────────────────────────────────────
+
+/** Severity rank (crit > high > med > info) — same order the renderer's badges use. */
+const SEVERITY_RANK: Readonly<Record<VerdictSeverity, number>> = {
+  crit: 3,
+  high: 2,
+  med: 1,
+  info: 0,
+};
+
+/** Rank a severity; an unknown/undefined severity ranks lowest (info). */
+export function severityRank(sev: VerdictSeverity | undefined): number {
+  return sev ? (SEVERITY_RANK[sev] ?? 0) : 0;
+}
+
+/**
+ * True when a finding's CURRENT severity materially EXCEEDS the severity it was dismissed
+ * at — a dismissed-but-now-worse finding. When escalated, the finding is NEVER suppressed
+ * (it re-surfaces) regardless of any semantic overlap. This is the HARD GUARD and it runs
+ * BEFORE the semantic match.
+ */
+export function isSeverityEscalated(
+  current: VerdictSeverity | undefined,
+  atDismissal: VerdictSeverity
+): boolean {
+  return severityRank(current) > severityRank(atDismissal);
+}
+
+// ── VerdictLookup — the injected reasoning-verdict map ────────────────────────
+
+/** Stable key identifying one dismissed ledger entry (matches store.ts verdictKey). */
+export function dismissalEntryKey(entry: VerdictLedgerEntry): string {
+  return `${entry.verdict}:${entry.runId}:${entry.findingId}`;
+}
+
+/** Lookup key for the verdict of (this new finding × this dismissed entry). */
+export function verdictLookupKey(findingId: string, entry: VerdictLedgerEntry): string {
+  return `${findingId}::${dismissalEntryKey(entry)}`;
+}
+
+/** The injected map of reasoning verdicts, keyed by verdictLookupKey(). */
+export type VerdictLookup = Readonly<Record<string, SemanticMatchVerdict>>;
+
+// ── The partition (pure, deterministic) ──────────────────────────────────────
+
+/** One suppressed finding + the dismissed entry + verdict that suppressed it (audit). */
+export interface SuppressionRecord {
+  finding: Finding;
+  matchedEntry: VerdictLedgerEntry;
+  verdict: SemanticMatchVerdict;
+}
+
+export interface DismissalPartitionResult {
+  /** Findings that SHOW in the report (not suppressed). */
+  active: Finding[];
+  /** Findings REMOVED from the report (matched a valid dismissal at high confidence). */
+  suppressed: SuppressionRecord[];
+}
+
+export interface PartitionOptions {
+  /** The diagnosed entity's slug — the EXACT-match gate for the final-check. */
+  entitySlug: string;
+}
+
+/**
+ * Split findings into active (shown) vs suppressed (removed from the report), applying the
+ * dismissal final-check DETERMINISTICALLY given the injected reasoning verdicts.
+ *
+ * Per finding, for each dismissed entry of the SAME entity (entitySlug EXACT):
+ *   1. HARD GUARD FIRST — if the finding's current severity escalated beyond the entry's
+ *      severityAtDismissal, this entry can NEVER suppress it (skip the entry). A
+ *      dismissed-but-now-worse finding always re-surfaces, regardless of overlap.
+ *   2. else consult the injected reasoning verdict; suppress iff decideSuppress() (high-
+ *      confidence overlap). The FIRST qualifying entry suppresses the finding.
+ *
+ * Fail-safe: `dismissedEntries` empty (no library / no dismissals) ⇒ every finding is
+ * active (a no-op). Deterministic: input order is preserved; no clock, no random.
+ */
+export function partitionByDismissal(
+  findings: Finding[],
+  dismissedEntries: VerdictLedgerEntry[],
+  verdicts: VerdictLookup,
+  opts: PartitionOptions
+): DismissalPartitionResult {
+  const candidates = dismissedEntries.filter((e) => e.entitySlug === opts.entitySlug);
+  const active: Finding[] = [];
+  const suppressed: SuppressionRecord[] = [];
+
+  for (const finding of findings) {
+    let hit: SuppressionRecord | undefined;
+    for (const entry of candidates) {
+      // 1. Severity-escalation HARD GUARD — runs BEFORE the semantic match.
+      if (isSeverityEscalated(finding.severity, entry.severityAtDismissal)) continue;
+      // 2. Semantic overlap (injected reasoning verdict), conservative decision.
+      const verdict = verdicts[verdictLookupKey(finding.findingId, entry)];
+      if (decideSuppress(verdict)) {
+        // decideSuppress guarantees verdict is defined here.
+        hit = { finding, matchedEntry: entry, verdict: verdict as SemanticMatchVerdict };
+        break;
+      }
+    }
+    if (hit) suppressed.push(hit);
+    else active.push(finding);
+  }
+
+  return { active, suppressed };
+}
+
+/** Extract a finding's failure-mode triple (for building a match request). */
+export function findingTriple(finding: Finding): FailureTriple {
+  return {
+    what: finding.failureOrigin.what,
+    why: finding.failureOrigin.why,
+    where: finding.failureOrigin.where,
+    whatHappened: finding.failureOrigin.whatHappened,
+  };
+}
+
+/** Extract a dismissed ledger entry's failure-mode triple. */
+export function entryTriple(entry: VerdictLedgerEntry): FailureTriple {
+  return {
+    what: entry.what,
+    why: entry.why,
+    where: entry.where,
+    whatHappened: entry.whatHappened,
+  };
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/enrich/rank-remedies.ts

@@ -0,0 +1,75 @@
+/**
+ * scripts/enrich/rank-remedies.ts
+ * W13-C (D-1): deterministic remedy-rank derivation.
+ *
+ * The orchestrator protocol (§8) states "Remedies: ranked by cost × correctness",
+ * but no code implemented it — so `remedy.rank` reached the renderer as `undefined`
+ * (one leg of the D-1 contract-triad desync). This module finally implements that
+ * rule in code: `rank` is DERIVED here from the analyzer's `cost` + `correctness`
+ * categoricals, never analyzer-supplied. That:
+ *   1. guarantees every remedy carries a `rank` before render (no `RANK undefined`);
+ *   2. removes an agent-discretion variance source — ranking is now reproducible
+ *      (honors the variance program: deterministic, no LLM judgment on rank).
+ *
+ * `cost`/`correctness` themselves are analyzer-emitted and contract-required
+ * (findings-contract.ts REQUIRED_REMEDY_FIELDS) — so they are guaranteed present
+ * by the time this runs (Step 8.5 enricher, post Step-7.1 gate).
+ *
+ * Type A — Pure Script (deterministic, no I/O, no clock, no random).
+ */
+
+import type { Remedy } from "../normalize/trace.ts";
+
+/** Categorical → ordinal weight. Higher correctness and LOWER cost are better. */
+const CORRECTNESS_WEIGHT: Record<Remedy["correctness"], number> = {
+  high: 3,
+  medium: 2,
+  low: 1,
+};
+
+const COST_WEIGHT: Record<Remedy["cost"], number> = {
+  // Lower cost is better, so it contributes MORE priority when cheaper.
+  low: 3,
+  medium: 2,
+  high: 1,
+};
+
+/**
+ * Priority score for a remedy — HIGHER means a better (higher-priority) remedy.
+ *
+ * Correctness is weighted to dominate cost: a correct-but-pricey fix outranks a
+ * cheap-but-weak one. We achieve strict dominance by scaling correctness above the
+ * cost range (cost ∈ [1..3] can never overturn a correctness step):
+ *
+ *   score = correctnessWeight * 10 + costWeight
+ *
+ * Deterministic: same inputs → same score, every run.
+ */
+export function remedyPriorityScore(remedy: Pick<Remedy, "cost" | "correctness">): number {
+  return CORRECTNESS_WEIGHT[remedy.correctness] * 10 + COST_WEIGHT[remedy.cost];
+}
+
+/**
+ * Assign a 1-based `rank` to every remedy by descending priority score
+ * (lower rank = higher priority, per the canonical Remedy.rank contract).
+ *
+ * Pure: returns a new array of new remedy objects; the input is not mutated.
+ * Stable + reproducible: score ties are broken deterministically by `remedyId`
+ * ascending, so parallel-analyzer output ranks identically on every run.
+ */
+export function rankRemedies(remedies: readonly Remedy[]): Remedy[] {
+  // Index-tag first so the sort is fully deterministic even on duplicate ids.
+  const ordered = remedies
+    .map((remedy, index) => ({ remedy, index }))
+    .sort((a, b) => {
+      const scoreDelta = remedyPriorityScore(b.remedy) - remedyPriorityScore(a.remedy);
+      if (scoreDelta !== 0) return scoreDelta;
+      // Tie-break 1: remedyId ascending (stable, content-addressed).
+      const idDelta = a.remedy.remedyId.localeCompare(b.remedy.remedyId);
+      if (idDelta !== 0) return idDelta;
+      // Tie-break 2: original input order (never relies on Array.sort stability).
+      return a.index - b.index;
+    });
+
+  return ordered.map(({ remedy }, i) => ({ ...remedy, rank: i + 1 }));
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/hooks/install-hooks.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# =============================================================================
+# install-hooks.sh — mutagent-diagnostics skill-local git hook installer
+# =============================================================================
+# Installs the skill's pre-push hook into the shared .git/hooks (works from a
+# worktree via --git-common-dir). Idempotent. Standalone usage from the skill
+# package root:  bun run setup:hooks
+#
+# Scope discipline: this installer belongs to the mutagent-diagnostics package
+# and ONLY installs the diagnostics pre-push hook. It does NOT touch the
+# monorepo-root scripts/install-hooks.sh (which manages pre-commit/post-commit/
+# post-checkout). If a root pre-push hook is later added, this installer should
+# be folded into it; until then it is self-contained per feedback_infra_changes_last.
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+GIT_COMMON="$(git rev-parse --git-common-dir 2>/dev/null || true)"
+if [ -z "$GIT_COMMON" ]; then
+  echo "[mdiag install-hooks] not inside a git repo — skipping" >&2
+  exit 0
+fi
+HOOKS_DIR="$GIT_COMMON/hooks"
+mkdir -p "$HOOKS_DIR"
+
+SRC="$SCRIPT_DIR/pre-push.sh"
+DST="$HOOKS_DIR/pre-push"
+
+if [ ! -f "$SRC" ]; then
+  echo "[mdiag install-hooks] source hook missing: $SRC" >&2
+  exit 1
+fi
+
+# Guard: if a DIFFERENT pre-push hook already exists (not ours), do not clobber.
+if [ -f "$DST" ] && ! grep -q "mdiag pre-push" "$DST" 2>/dev/null; then
+  echo "[mdiag install-hooks] a non-diagnostics pre-push hook already exists at $DST" >&2
+  echo "[mdiag install-hooks] NOT overwriting — integrate the diagnostics T2 manually:" >&2
+  echo "[mdiag install-hooks]   bash $SRC" >&2
+  exit 0
+fi
+
+cp "$SRC" "$DST"
+chmod +x "$DST"
+echo "[mdiag install-hooks] pre-push hook installed → $DST"

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/hooks/pre-push.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# =============================================================================
+# pre-push.sh — mutagent-diagnostics on-demand Langfuse integration gate (T2)
+# =============================================================================
+# Runs the T2 LIVE Langfuse integration (verify:langfuse) before a push, ONLY
+# for contributors who have a local Langfuse stack + creds. It SKIPS LOUDLY and
+# exits 0 when the stack/creds are absent (CI + keyless contributors stay green).
+# This mirrors the repo's "on-demand local verification" pattern (see the
+# Wave-5.1 coverage matrix spec).
+#
+# This hook is INTENTIONALLY skill-local (installed by `bun run setup:hooks`
+# from THIS package) — it does NOT modify the monorepo-root install-hooks.sh.
+# It is heavier than pre-commit, so it runs at push time, not on every commit.
+#
+# To enable for this clone:
+#   cd mutagent-system/mutagent-diagnostics && bun run setup:hooks
+# To bypass intentionally (e.g. offline): the hook self-skips when no stack —
+# you should NOT need --no-verify. Never use --no-verify to hide a real failure.
+# =============================================================================
+
+set -euo pipefail
+
+# This hook runs as the INSTALLED copy at .git/hooks/pre-push, so it cannot use
+# its own location to find the package — it discovers the package via the git
+# worktree toplevel. Works from the root checkout AND from any worktree.
+TOP="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$TOP" ]; then
+  echo "[mdiag pre-push] not inside a git worktree — skipping" >&2
+  exit 0
+fi
+PKG_DIR="$TOP/mutagent-system/mutagent-diagnostics"
+
+if [ ! -f "$PKG_DIR/package.json" ]; then
+  # The diagnostics package is not present in this worktree (e.g. a checkout that
+  # predates the skill). Nothing to verify — skip cleanly.
+  echo "[mdiag pre-push] diagnostics package not found at $PKG_DIR — skipping" >&2
+  exit 0
+fi
+
+# Source local Langfuse creds if present. The hook never prints or commits keys.
+# Absence is fine — verify:langfuse self-skips loudly. Prefer creds already in
+# the environment; otherwise try the worktree's mutagent/.env (post-checkout hook
+# copies it) then the root checkout's mutagent/.env.
+if [ -z "${LANGFUSE_HOST:-}" ] || [ -z "${LANGFUSE_PUBLIC_KEY:-}" ] || [ -z "${LANGFUSE_SECRET_KEY:-}" ]; then
+  GIT_COMMON="$(git rev-parse --git-common-dir 2>/dev/null || true)"
+  ROOT_CHECKOUT="$(cd "$GIT_COMMON/.." 2>/dev/null && pwd || true)"
+  for envf in "$TOP/mutagent/.env" "$ROOT_CHECKOUT/mutagent/.env"; do
+    if [ -f "$envf" ]; then
+      set -a
+      # shellcheck disable=SC1090
+      source "$envf"
+      set +a
+      break
+    fi
+  done
+fi
+
+echo "[mdiag pre-push] running T2 Langfuse integration (verify:langfuse) …" >&2
+if ! command -v bun >/dev/null 2>&1; then
+  echo "[mdiag pre-push] bun not found — skipping T2 (install bun to enable)" >&2
+  exit 0
+fi
+
+# Enter the package dir defensively. If the dir is inaccessible (e.g. a sandboxed
+# / restricted worktree path), skip loudly rather than fail the push — an
+# unreachable package is an ENVIRONMENT problem, not a test failure. This keeps
+# the hook aligned with its "skip when you can't actually run" philosophy and
+# never forces a --no-verify bypass.
+if ! cd "$PKG_DIR" 2>/dev/null; then
+  echo "[mdiag pre-push] cannot enter $PKG_DIR — skipping T2 (restricted/unavailable path)" >&2
+  exit 0
+fi
+# Verify the package script exists before invoking (guards against partial checkouts).
+if ! grep -q '"verify:langfuse"' package.json 2>/dev/null; then
+  echo "[mdiag pre-push] verify:langfuse script not present here — skipping T2" >&2
+  exit 0
+fi
+bun run verify:langfuse