@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/tier0/langfuse.ts

@@ -0,0 +1,143 @@
+/**
+ * scripts/tier0/langfuse.ts
+ * R-SELF-11-a: Per-platform Tier 0 module for langfuse source.
+ *
+ * Langfuse traces carry explicit score + feedback + latency signals
+ * as first-class fields — this module produces a Tier 0 report tuned
+ * to Langfuse's signal density.
+ *
+ * Invoked by tier0-scan.ts when `sourcePlatform === "langfuse"`.
+ * Type A — Pure Script (deterministic pattern matching, no LLM calls)
+ */
+
+import type { TraceMetadata } from "../normalize/trace.ts";
+// I-020/PR-033 drift fix (SL-5): reuse the generic scanner's IQR fence rather than
+// reimplementing it, so Langfuse-source runs honor thresholdMode identically to the
+// generic path. `iqrUpperFence` is a runtime value import; tier0-scan.ts only DYNAMICALLY
+// imports this module (via dispatchPlatformTier0), so there is no eval-time import cycle.
+import { iqrUpperFence } from "../tier0-scan.ts";
+import type { Tier0Report, PatternMatch, Tier0ScanConfig } from "../tier0-scan.ts";
+
+const HIGH_LATENCY_MS = 10_000; // absolute gate; also the <4-sample fallback in relative mode
+const LOW_SCORE_RAW_MAX = 0.4;
+const MAX_ESTIMATED_SLOTS = 5;
+
+// I-020: default to "relative" — identical to the generic scanner's DEFAULT_TIER0_CONFIG.
+// Before this fix runLangfuseTier0 IGNORED the config entirely and hardcoded the absolute
+// HIGH_LATENCY_MS gate, so a `thresholdMode:"relative"` request silently used the absolute
+// threshold on Langfuse-source runs (PR-033 drift found by SimuLatte SL-5).
+const DEFAULT_LANGFUSE_TIER0_CONFIG: Tier0ScanConfig = { thresholdMode: "relative" };
+
+export function runLangfuseTier0(
+  traces: TraceMetadata[],
+  config: Tier0ScanConfig = DEFAULT_LANGFUSE_TIER0_CONFIG
+): Tier0Report {
+  const withError = traces.filter((t) => t.hasError);
+  const withFeedback = traces.filter((t) => t.hasFeedback);
+  const withLowScore = traces.filter((t) => {
+    if (t.normalizedScore !== undefined) return t.normalizedScore <= LOW_SCORE_RAW_MAX;
+    return typeof t.rawScore === "number" && t.rawScore < 3;
+  });
+
+  // I-020/PR-033: high-latency threshold follows thresholdMode, mirroring the generic
+  // runTier0Scan semantics EXACTLY — "relative" derives a per-batch Tukey IQR upper fence
+  // (Q3 + 1.5·IQR), falling back to the absolute constant when <4 latency samples exist;
+  // "absolute" uses the fixed HIGH_LATENCY_MS constant.
+  let highLatencyThreshold: number;
+  if (config.thresholdMode === "relative") {
+    const latencySamples = traces
+      .filter((t) => t.latencyMs !== undefined)
+      .map((t) => t.latencyMs as number);
+    highLatencyThreshold = iqrUpperFence(latencySamples) ?? HIGH_LATENCY_MS;
+  } else {
+    highLatencyThreshold = HIGH_LATENCY_MS;
+  }
+
+  const withHighLatency = traces.filter(
+    (t) => t.latencyMs !== undefined && t.latencyMs > highLatencyThreshold
+  );
+
+  // Langfuse-specific: check API exhaustion (v0.3 apiErrors — may be populated
+  // if the Langfuse normalizer captures SDK retry events)
+  const withApiExhaustion = traces.filter(
+    (t) =>
+      Array.isArray(t.apiErrors) &&
+      t.apiErrors.some((e) => e.retryAttempt >= e.maxRetries)
+  );
+  const hasApiExhaustion = withApiExhaustion.length > 0;
+
+  const hasPrimarySignal =
+    withFeedback.length > 0 || withLowScore.length > 0 || hasApiExhaustion;
+
+  const patterns: PatternMatch[] = [];
+
+  // P-001: error spike (>20% error rate)
+  const errorRate = withError.length / Math.max(traces.length, 1);
+  if (errorRate > 0.2) {
+    patterns.push({
+      patternId: "P-001",
+      name: "error-spike",
+      matchCount: withError.length,
+      traceIds: withError.map((t) => t.traceId),
+    });
+  }
+
+  // P-002: latency spike (>10% high latency)
+  const latencyRate = withHighLatency.length / Math.max(traces.length, 1);
+  if (latencyRate > 0.1) {
+    patterns.push({
+      patternId: "P-002",
+      name: "latency-spike",
+      matchCount: withHighLatency.length,
+      traceIds: withHighLatency.map((t) => t.traceId),
+    });
+  }
+
+  // P-003: feedback cluster (>5% feedback bearing)
+  const feedbackRate = withFeedback.length / Math.max(traces.length, 1);
+  if (feedbackRate > 0.05) {
+    patterns.push({
+      patternId: "P-003",
+      name: "feedback-cluster",
+      matchCount: withFeedback.length,
+      traceIds: withFeedback.map((t) => t.traceId),
+    });
+  }
+
+  // LF-001: score concentration in low tier (>30% below threshold — strong signal density)
+  const lowScoreRate = withLowScore.length / Math.max(traces.length, 1);
+  if (lowScoreRate > 0.3 && withLowScore.length > 2) {
+    patterns.push({
+      patternId: "LF-001",
+      name: "low-score-concentration",
+      matchCount: withLowScore.length,
+      traceIds: withLowScore.map((t) => t.traceId),
+    });
+  }
+
+  // NOTE: a former LF-002 "low-tagging-rate" pattern (>80% untagged) was REMOVED
+  // (W12-05 / PR-051 propose). Empty `tags[]` is Langfuse dashboard hygiene, NOT
+  // agent behavior — it is not a failure WHAT and must never surface as a signal,
+  // census row, or finding. The Tier-0 census admits only mechanical signals that
+  // map to a user-visible failure (loop / latency / cost / error / feedback / score);
+  // observability hygiene is out of scope by construction.
+  // See references/principles.md PR-049 step-2 + feedback_signal_discipline_evidence_first.
+
+  const slots = Math.min(
+    Math.max(1, patterns.length + (hasPrimarySignal ? 1 : 0)),
+    MAX_ESTIMATED_SLOTS
+  );
+
+  return {
+    totalTraces: traces.length,
+    withError: withError.length,
+    withFeedback: withFeedback.length,
+    withLowScore: withLowScore.length,
+    withHighLatency: withHighLatency.length,
+    hasApiExhaustion,
+    hasPrimarySignal,
+    recommendedSlicing: hasPrimarySignal ? "dynamic-cluster" : "window-based",
+    estimatedSlots: slots,
+    patterns,
+  };
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/tier0-scan.ts

@@ -0,0 +1,423 @@
+/**
+ * scripts/tier0-scan.ts
+ * Tier 0 static pattern scan — runs BEFORE any LLM call (PR-001)
+ * Type A — Pure Script (deterministic pattern matching + counts)
+ *
+ * Reads a JSON array of TraceMetadata, computes signal counts, emits a structured
+ * route-guess that tells the orchestrator whether to use dynamic-cluster or window-based slicing.
+ *
+ * R-SELF-11-a: When all traces share a single sourcePlatform, dispatches to the
+ * per-platform Tier 0 module for richer signal extraction. Falls back to generic
+ * path for mixed-platform or unknown batches.
+ *
+ * I-020: Relative threshold mode (PR-033). Anomaly detection uses per-session
+ * p95/IQR comparisons instead of hardcoded numeric thresholds. Default: "relative".
+ *
+ * Usage: bun scripts/tier0-scan.ts <traces-metadata.json>
+ */
+
+import { readFileSync } from "fs";
+import type { TraceMetadata, SourcePlatform } from "./normalize/trace.ts";
+import { ensureBuiltinSourceAdapters, tryGetSourceAdapter } from "./source/index.ts";
+
+/**
+ * I-020: Scan configuration for anomaly threshold mode (PR-033).
+ */
+export interface Tier0ScanConfig {
+  /**
+   * Threshold mode for latency anomaly detection.
+   * "relative" (default): IQR-based per-session outlier detection — no hardcoded ms values.
+   *   A trace is "high latency" if its latencyMs is above Q3 + 1.5 * IQR of the batch.
+   *   Falls back to absolute when fewer than 4 latency samples are available.
+   * "absolute" (legacy): fixed HIGH_LATENCY_MS = 10_000 ms threshold (backward-compat).
+   */
+  thresholdMode: "absolute" | "relative";
+}
+
+const DEFAULT_TIER0_CONFIG: Tier0ScanConfig = {
+  thresholdMode: "relative",
+};
+
+export interface Tier0Report {
+  totalTraces: number;
+  withError: number;
+  withFeedback: number;
+  withLowScore: number;
+  withHighLatency: number;
+  /**
+   * R-SELF-06-b: true when ANY trace has retryAttempt === maxRetries
+   * (provider exhausted all retries — a primary failure signal regardless of score).
+   */
+  hasApiExhaustion: boolean;
+  /**
+   * I-012: true when ANY trace has skill workflow deviations detected
+   * (TraceMetadata.skillBehaviorDeviationCount > 0).
+   * Covers: skipped signal census, omitted assumption enumeration, bypassed scope construct.
+   * Optional for backward-compat with platform-specific tier0 modules (claude-code, langfuse).
+   */
+  hasSkillBehaviorDeviation?: boolean;
+  /** Whether score/feedback signal is present (determines slicing strategy) */
+  hasPrimarySignal: boolean;
+  /** Recommended slicing: dynamic-cluster (scored) or window-based (naive) */
+  recommendedSlicing: "dynamic-cluster" | "window-based";
+  /** Estimated number of analyzer slots needed (capped at 5) */
+  estimatedSlots: number;
+  /** Known failure patterns matched */
+  patterns: PatternMatch[];
+  /**
+   * I-012: Typed Axis-1 signals — includes skill-behavior-deviation and future signal types.
+   * Separate from `patterns` (which are structural patterns P-001/P-002/P-003).
+   * Each entry has a `type` field for jq-queryable enumeration.
+   * Optional for backward-compat with platform-specific tier0 modules (claude-code, langfuse).
+   */
+  signals?: SignalMatch[];
+  /**
+   * I-020: Scan configuration applied for this report.
+   * Present when using runTier0Scan or runTier0ScanPlatformAware directly.
+   * Optional to avoid breaking per-platform modules (claude-code, langfuse) that return
+   * Tier0Report without config — runTier0ScanPlatformAware merges config in after dispatch.
+   */
+  config?: Tier0ScanConfig;
+  /**
+   * Wave-6 R2.3: class-memory library matches, MATCHED FIRST (before generic
+   * heuristics). Each entry carries the 3× prior weight. Present only when the scan
+   * was run via runTier0ScanWithLibrary against an entity with library priors.
+   * Optional (backward-compat — absent on every pre-R2.3 path).
+   */
+  libraryMatches?: LibraryMatchSummary[];
+}
+
+/**
+ * Wave-6 R2.3: a single library-prior match surfaced in a Tier-0 report.
+ * Mirrors scripts/library/match.ts LibraryMatch (kept structural here so
+ * tier0-scan.ts does not hard-depend on the library on the generic path).
+ */
+export interface LibraryMatchSummary {
+  patternId: string;
+  signal: string;
+  matchCount: number;
+  traceIds: string[];
+  /** 3× prior weight (library priors outrank fresh Tier-0 signals). */
+  weight: number;
+}
+
+
+/**
+ * I-012: Typed signal match — one entry per detected signal category.
+ * Used to surface skill workflow deviations and other Axis-1 signals.
+ */
+export interface SignalMatch {
+  /** Signal category type (e.g. "skill-behavior-deviation") */
+  type: string;
+  /** Number of traces where this signal was detected */
+  matchCount: number;
+  /** Trace IDs that exhibited this signal */
+  traceIds: string[];
+}
+
+export interface PatternMatch {
+  patternId: string;
+  name: string;
+  matchCount: number;
+  traceIds: string[];
+}
+
+const HIGH_LATENCY_MS = 10_000; // used only when thresholdMode === "absolute"
+const LOW_SCORE_RAW_MAX = 0.4; // used when normalizedScore present
+
+// ── I-020: Per-session relative threshold helpers (PR-033) ────────────────────
+
+/**
+ * Compute the p95 (95th percentile) of a numeric array using linear interpolation.
+ * Returns null for empty arrays.
+ */
+export function computeP95(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = 0.95 * (sorted.length - 1);
+  const lower = Math.floor(idx);
+  const upper = Math.ceil(idx);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (idx - lower) * (sorted[upper] - sorted[lower]);
+}
+
+/**
+ * Compute the Tukey IQR upper fence (Q3 + 1.5 × IQR) for outlier detection.
+ * A value above this fence is considered an anomaly relative to the batch.
+ *
+ * Uses linear interpolation for Q1/Q3 (same as computeP95).
+ * Returns null when fewer than 4 values are available (insufficient for IQR).
+ * Falls back to HIGH_LATENCY_MS (absolute) in the caller when null.
+ */
+export function iqrUpperFence(values: number[]): number | null {
+  if (values.length < 4) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const n = sorted.length - 1;
+  const q1Idx = 0.25 * n;
+  const q3Idx = 0.75 * n;
+  const q1 =
+    sorted[Math.floor(q1Idx)] +
+    (q1Idx - Math.floor(q1Idx)) * (sorted[Math.ceil(q1Idx)] - sorted[Math.floor(q1Idx)]);
+  const q3 =
+    sorted[Math.floor(q3Idx)] +
+    (q3Idx - Math.floor(q3Idx)) * (sorted[Math.ceil(q3Idx)] - sorted[Math.floor(q3Idx)]);
+  const iqr = q3 - q1;
+  return q3 + 1.5 * iqr;
+}
+
+/**
+ * R-SELF-11-a: Detect the dominant platform in a batch of traces.
+ * Returns the platform if ALL traces share the same sourcePlatform, else null.
+ */
+function detectSinglePlatform(traces: TraceMetadata[]): SourcePlatform | null {
+  if (traces.length === 0) return null;
+  const first = traces[0].sourcePlatform;
+  if (!first) return null;
+  return traces.every((t) => t.sourcePlatform === first) ? first : null;
+}
+
+/**
+ * R-SELF-11-a: Dispatch to per-platform Tier 0 module when batch is homogeneous.
+ * Falls back to generic path for mixed-platform or unknown-platform batches.
+ *
+ * Item #7: resolution is now REGISTRY-driven (scripts/source) instead of a
+ * hard-coded `if (platform === …)` switch — a new source registers declaratively
+ * and its optional `tier0Scan` is picked up here with ZERO edits to this file.
+ * Behavior is byte-identical to the prior switch:
+ *   - langfuse   → runLangfuseTier0(traces, config)   (config-honoring, I-020/PR-033)
+ *   - claude-code→ runClaudeCodeTier0(traces)
+ *   - otel / local-jsonl / codex / unknown → null (adapter has no tier0Scan) → generic scan
+ * Any adapter/module load or scan failure falls through to the generic path.
+ */
+async function dispatchPlatformTier0(
+  traces: TraceMetadata[],
+  platform: SourcePlatform,
+  config: Tier0ScanConfig = DEFAULT_TIER0_CONFIG
+): Promise<Tier0Report | null> {
+  ensureBuiltinSourceAdapters();
+  const adapter = tryGetSourceAdapter(platform);
+  // No adapter, or an adapter WITHOUT a bespoke scanner (otel/local-jsonl/codex),
+  // takes the generic path — exactly as the pre-registry fallback did.
+  if (!adapter || !adapter.tier0Scan) return null;
+  try {
+    return await adapter.tier0Scan(traces, config);
+  } catch {
+    // Module load / scan failure — fall through to generic path
+    return null;
+  }
+}
+
+/**
+ * Generic (platform-agnostic) Tier 0 scan.
+ * Used as the fallback when platform dispatch is unavailable or not applicable.
+ * Also exported for use by per-platform modules that want to extend the base result.
+ *
+ * @param traces  Batch of TraceMetadata to scan.
+ * @param config  I-020: Scan configuration. Defaults to { thresholdMode: "relative" }.
+ */
+export function runTier0Scan(traces: TraceMetadata[], config: Tier0ScanConfig = DEFAULT_TIER0_CONFIG): Tier0Report {
+  const withError = traces.filter((t) => t.hasError);
+  const withFeedback = traces.filter((t) => t.hasFeedback);
+  // R-SELF-04-a: treat null rawScore correctly — only count traces where
+  // rawScore is an actual number below threshold, not null/undefined.
+  const withLowScore = traces.filter((t) => {
+    if (t.normalizedScore !== undefined) {
+      return t.normalizedScore <= LOW_SCORE_RAW_MAX;
+    }
+    // rawScore must be a non-null number strictly below 3
+    return typeof t.rawScore === "number" && t.rawScore < 3;
+  });
+
+  // I-020: High-latency detection — relative (IQR) or absolute (hardcoded ms).
+  // In "relative" mode, the threshold is derived per-session from the batch's own
+  // latency distribution using the Tukey IQR upper fence (Q3 + 1.5 × IQR).
+  // This means no hardcoded ms values drive the anomaly gate (PR-033).
+  let highLatencyThreshold: number;
+  if (config.thresholdMode === "relative") {
+    const latencySamples = traces
+      .filter((t) => t.latencyMs !== undefined)
+      .map((t) => t.latencyMs as number);
+    // iqrUpperFence returns null when <4 samples — fall back to absolute threshold.
+    highLatencyThreshold = iqrUpperFence(latencySamples) ?? HIGH_LATENCY_MS;
+  } else {
+    highLatencyThreshold = HIGH_LATENCY_MS;
+  }
+
+  const withHighLatency = traces.filter(
+    (t) => t.latencyMs !== undefined && t.latencyMs > highLatencyThreshold
+  );
+
+  // R-SELF-06-b: API exhaustion = retryAttempt reached maxRetries on any trace
+  const hasApiExhaustion = traces.some(
+    (t) =>
+      Array.isArray(t.apiErrors) &&
+      t.apiErrors.some((e) => e.retryAttempt >= e.maxRetries)
+  );
+
+  // I-012: skill-behavior-deviation — skill deviated from documented workflow
+  // (e.g., skipped signal census, omitted assumption enumeration, bypassed scope construct)
+  const withSkillDeviation = traces.filter(
+    (t) => typeof t.skillBehaviorDeviationCount === "number" && t.skillBehaviorDeviationCount > 0
+  );
+  const hasSkillBehaviorDeviation = withSkillDeviation.length > 0;
+
+  const hasPrimarySignal = withFeedback.length > 0 || withLowScore.length > 0 || hasApiExhaustion;
+
+  // Pattern: error spike (>20% error rate)
+  const patterns: PatternMatch[] = [];
+  const errorRate = withError.length / Math.max(traces.length, 1);
+  if (errorRate > 0.2) {
+    patterns.push({
+      patternId: "P-001",
+      name: "error-spike",
+      matchCount: withError.length,
+      traceIds: withError.map((t) => t.traceId),
+    });
+  }
+
+  // Pattern: latency spike (>10% high latency)
+  const latencyRate = withHighLatency.length / Math.max(traces.length, 1);
+  if (latencyRate > 0.1) {
+    patterns.push({
+      patternId: "P-002",
+      name: "latency-spike",
+      matchCount: withHighLatency.length,
+      traceIds: withHighLatency.map((t) => t.traceId),
+    });
+  }
+
+  // Pattern: feedback cluster (>5% feedback bearing)
+  const feedbackRate = withFeedback.length / Math.max(traces.length, 1);
+  if (feedbackRate > 0.05) {
+    patterns.push({
+      patternId: "P-003",
+      name: "feedback-cluster",
+      matchCount: withFeedback.length,
+      traceIds: withFeedback.map((t) => t.traceId),
+    });
+  }
+
+  // I-012: Build Axis-1 signals array (typed signal categories, separate from patterns)
+  const signals: SignalMatch[] = [];
+  if (hasSkillBehaviorDeviation) {
+    signals.push({
+      type: "skill-behavior-deviation",
+      matchCount: withSkillDeviation.length,
+      traceIds: withSkillDeviation.map((t) => t.traceId),
+    });
+  }
+
+  // Estimate slots: one slot per distinct signal cluster, capped at 5 (PR-005)
+  const slots = Math.min(
+    Math.max(1, patterns.length + (hasPrimarySignal ? 1 : 0)),
+    5
+  );
+
+  return {
+    totalTraces: traces.length,
+    withError: withError.length,
+    withFeedback: withFeedback.length,
+    withLowScore: withLowScore.length,
+    withHighLatency: withHighLatency.length,
+    hasApiExhaustion,
+    hasSkillBehaviorDeviation,
+    hasPrimarySignal,
+    recommendedSlicing: hasPrimarySignal ? "dynamic-cluster" : "window-based",
+    estimatedSlots: slots,
+    patterns,
+    signals,
+    // I-020: record the config used so callers / jq queries can inspect thresholdMode
+    config,
+  };
+}
+
+/**
+ * R-SELF-11-a: Platform-aware entry point.
+ * Detects dominant sourcePlatform and dispatches to the appropriate per-platform
+ * module. Falls back to generic runTier0Scan for mixed or unknown batches.
+ *
+ * I-020: config is merged into the result regardless of path so that
+ * `.config.thresholdMode` is always present in CLI output (PR-033 audit surface).
+ *
+ * This is the preferred entrypoint for the orchestrator. The synchronous
+ * runTier0Scan export is kept for testing and for per-platform modules that
+ * call it internally.
+ */
+export async function runTier0ScanPlatformAware(
+  traces: TraceMetadata[],
+  config: Tier0ScanConfig = DEFAULT_TIER0_CONFIG
+): Promise<Tier0Report> {
+  const platform = detectSinglePlatform(traces);
+  if (platform) {
+    // I-020/PR-033: thread config INTO the per-platform module (not just merged into the
+    // result afterward) so the platform scanner actually COMPUTES with the requested
+    // thresholdMode — the langfuse module previously ignored it and hardcoded absolute.
+    const result = await dispatchPlatformTier0(traces, platform, config);
+    // Merge config into platform-specific result so .config.thresholdMode is always present
+    if (result) return { ...result, config };
+  }
+  // Generic fallback
+  return runTier0Scan(traces, config);
+}
+
+/**
+ * Wave-6 R2.3 / PRD-MP-07 (PR-037): library-FIRST Tier-0 entry point.
+ * Takes PRE-COMPUTED library matches (the caller runs scripts/library/match.ts
+ * FIRST, before this scan) and attaches them to the report's `libraryMatches`
+ * so the promoted patterns are surfaced ahead of the generic heuristics.
+ * The generic scan is unchanged — library matches are ADDITIVE prior signals
+ * carrying the 3× weight.
+ *
+ * PRD-MP-07 ENFORCEMENT: This function is now the PREFERRED entry point for
+ * the orchestrator at Step 4 (Tier-0). The orchestrator MUST:
+ *   1. Call matchLibraryPatterns() from scripts/library/match.ts FIRST.
+ *   2. Call this function with the resulting matches (empty array = no-op).
+ *   3. When matches.length > 0: skip Step 3.5 awareness mini-sample (buildPriorSignalsRef
+ *      provides the ref to pass to shouldFireAwareness({ priorSignalsRef })).
+ *   4. Record the skip in runMeta.exemptions: [{ stepId: 'awareness-sample',
+ *      reason: 'library-priors:' + ref, declaredBy: 'orchestrator' }].
+ *
+ * Library writes are approved-only — never auto-promoted without operator gate.
+ * Keeping the matcher OUT of this function keeps it dependency-light (pure wrapper).
+ *
+ * When there are no library matches, this behaves identically to
+ * runTier0ScanPlatformAware.
+ */
+export async function runTier0ScanWithLibrary(
+  traces: TraceMetadata[],
+  libraryMatches: LibraryMatchSummary[],
+  config: Tier0ScanConfig = DEFAULT_TIER0_CONFIG
+): Promise<Tier0Report> {
+  const base = await runTier0ScanPlatformAware(traces, config);
+  if (libraryMatches.length === 0) return base;
+  // LIBRARY FIRST: promoted patterns are surfaced ahead of generic heuristics.
+  // PRD-MP-07: hasPrimarySignal is re-evaluated to include library hits.
+  const hasPrimarySignalWithLib = base.hasPrimarySignal || libraryMatches.length > 0;
+  return {
+    ...base,
+    libraryMatches,
+    hasPrimarySignal: hasPrimarySignalWithLib,
+    recommendedSlicing: hasPrimarySignalWithLib ? "dynamic-cluster" : base.recommendedSlicing,
+  };
+}
+
+// CLI entrypoint
+if (import.meta.main) {
+  const inputPath = process.argv[2];
+  if (!inputPath) {
+    process.stderr.write("Usage: bun scripts/tier0-scan.ts <traces-metadata.json>\n");
+    process.exit(1);
+  }
+
+  try {
+    const raw = readFileSync(inputPath, "utf8");
+    const traces: TraceMetadata[] = JSON.parse(raw);
+    // R-SELF-11-a: use platform-aware entry for CLI execution
+    const report = await runTier0ScanPlatformAware(traces);
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Error: ${err}\n`);
+    process.exit(1);
+  }
+}