@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/workflows/schedule-prep.md

@@ -0,0 +1,100 @@
+# Schedule Prep — How to Wire Scheduling Post-v0.1
+
+> v0.1 ships `schedule.mode: on-demand` ONLY.
+> This document prepares the operator to add scheduling via their host runtime after v0.1.
+
+## Why no schedules in v0.1
+
+Scheduling is host-runtime-specific. v0.1 ships the structure (config fields, trigger_rules, heartbeat config) but no schedule wiring. The operator can ask their coding agent to wire scheduling at any time using the playbook below.
+
+---
+
+## How to ask your coding agent to set up scheduling
+
+Tell your coding agent:
+```
+Set up daily diagnostics at 09:00 using mutagent-diagnostics.
+Source: langfuse. Trigger rule: has_feedback + score_below threshold.
+```
+
+The coding agent will follow the appropriate procedure for your host runtime:
+
+---
+
+## Claude Code — native /loop + CronCreate
+
+```bash
+# Claude Code has native scheduling primitives (confirmed in docs)
+# 1. Update config.yaml: schedule.mode = daily-batch, at = "09:00"
+# 2. Register with Claude Code's scheduler:
+#    CronCreate({ cron: "0 9 * * *", command: "invoke mutagent-diagnostics" })
+# OR use /loop for interactive polling:
+#    /loop 24h <diagnose my agents>
+```
+
+Reference: [code.claude.com/docs](https://code.claude.com/docs/en/)
+
+---
+
+## Codex CLI — external cron + codex exec
+
+```bash
+# Codex has no native scheduler — use OS cron
+# 1. Update config.yaml: schedule.mode = daily-batch, at = "09:00"
+# 2. Add crontab entry:
+crontab -e
+# Add line:
+# 0 9 * * * codex exec --ephemeral "invoke mutagent-diagnostics for daily batch"
+```
+
+Reference: [developers.openai.com/codex](https://developers.openai.com/codex/cli)
+
+---
+
+## Cursor — Background Agents (2025+)
+
+```bash
+# Verify Background Agents support scheduling in your Cursor version
+# If supported: register a recurring task via Background Agents UI
+# If not: fall back to OS cron (see Codex pattern above)
+```
+
+Reference: [cursor.com/docs](https://cursor.com/docs)
+
+---
+
+## Headless / CI (GitHub Actions)
+
+```yaml
+# .github/workflows/mutagent-diagnostics-daily.yml
+name: Daily Diagnostics
+on:
+  schedule:
+    - cron: '0 9 * * *'
+jobs:
+  diagnose:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run diagnostics
+        run: pnpx @mutagent/diagnostics run --non-interactive
+        env:
+          LANGFUSE_SECRET_KEY: ${{ secrets.LANGFUSE_SECRET_KEY }}
+```
+
+---
+
+## config.yaml schedule fields
+
+```yaml
+schedule:
+  mode: daily-batch        # Change from on-demand → daily-batch
+  at: "09:00"             # Local time
+  timezone: "America/New_York"
+
+heartbeat:
+  notify_on_matches: true   # Notify operator when triggers fire
+  max_diagnostics_per_day: 3  # Cost guardrail
+```
+
+**Important**: scheduled runs produce a report + notification. HITL apply gate still fires — operator must confirm apply on next interactive session.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/workflows/scope-model.md

@@ -0,0 +1,128 @@
+# Scope Model — Skill vs Agent + Agent-ID Identity
+
+> **W11-07** — documents the scope-picker decision model and the agent-identity
+> resolution system introduced in Wave-11.
+>
+> **Authority**: orchestrator-protocol.md Step 3a (runtime procedure) references
+> this file for the full model.
+
+---
+
+## Scope Types
+
+The diagnostic run has three scope modes:
+
+| Scope | When to use | Config resolution |
+|---|---|---|
+| `skill` | Diagnosing a skill's operational traces (e.g. `mutagent-diagnostics`) | Looks up `config.agents[name=<entity>]` |
+| `agent` | Diagnosing a named runtime agent (e.g. `search-agent`, `orchestrator`) | Looks up `config.agents[name=<entity>]` |
+| `all-traces` | No named entity — run across all available traces | No identity lookup; name-based filter only |
+
+---
+
+## Invocation-Aware Scope Resolution
+
+The orchestrator determines scope using this **decision tree** at Step 3a:
+
+```
+parse-brief result
+    │
+    ├── scopeType = "skill"  → use scope: skill directly (no AskUserQuestion)
+    │
+    ├── scopeType = "agent"  → use scope: agent directly (no AskUserQuestion)
+    │
+    └── scopeType = null     → AskUserQuestion: skill | agent | all-traces
+                               (see orchestrator-protocol.md Step 3a for template)
+```
+
+**Named → direct**: when parse-brief extracts a `scopeType`, use it immediately.
+No AskUserQuestion for scopes that are already resolvable from the brief.
+
+**Null → ask**: when scope cannot be inferred, present the three-option picker
+with concrete preview blocks (per `feedback_ask_user_question_with_previews`).
+
+---
+
+## Agent-ID Identity Map
+
+The `config.agents[]` field (added W11-07) is an optional cross-platform identity
+map that tells the skill HOW to find a named entity's traces on each observability
+platform.
+
+### Why this is needed
+
+A single code-level agent may appear as:
+- `"search-agent"` in application code
+- `"search-v2"` as `trace.name` in Langfuse (due to versioned naming)
+- `"search-svc"` as `service.name` in OpenTelemetry (due to service naming conventions)
+
+Without an identity map, the skill falls back to name-based matching which may
+miss traces or return traces from a different agent.
+
+### Config shape
+
+```yaml
+# .mutagent/config.yaml
+agents:
+  - name: search-agent          # canonical code-level name (matches parse-brief.entity)
+    langfuse:
+      traceName: "search-v2"   # Langfuse trace.name override
+      tags: ["production"]     # additional tag filter
+      agentIdField: "metadata.agent_id"  # custom field override
+    otel:
+      serviceName: "search-svc"          # OTEL service.name
+      resourceAttrs:
+        deployment.env: "prod"           # additional resource attr filter
+```
+
+See `scripts/config/schema.ts` → `AgentIdentitySchema` for the TypeBox definition.
+
+### Resolution Step (Step 3.7)
+
+```typescript
+import { resolveEntityIdentity } from "scripts/normalize/platforms/entity-context.ts";
+
+// After parse-brief and scope picker (Step 3a):
+const identity = resolveEntityIdentity(parsedInvocation.entity, config.agents);
+if (identity) {
+  entityContext.identity = identity;
+}
+```
+
+`resolveEntityIdentity` performs a case-insensitive name lookup. When the entity is
+not declared in `config.agents`, it returns `undefined` and the run proceeds with
+name-based matching (no behavioral change from pre-W11-07).
+
+### How identity pointers are used
+
+After `EntityContext.identity` is populated:
+
+| Platform | How identity is used |
+|---|---|
+| Langfuse | `identity.langfuse.traceName` overrides the trace name filter; `identity.langfuse.tags` added to query; `identity.langfuse.agentIdField` overrides the JSON field used for `agentId` extraction |
+| OTel | `identity.otel.serviceName` filters by `service.name` resource attr; `identity.otel.resourceAttrs` added to span query |
+
+When `identity` is absent: existing name-based matching behavior (backward-compatible).
+
+---
+
+## Escape Hatch: all-traces
+
+When the operator selects `all-traces` (or explicitly passes `--scope all`):
+- No entity identity lookup.
+- No `skillAgentScope` filter applied.
+- TraceFilter.skill_agent_scope remains empty.
+- The run is an unfocused exploratory sweep.
+
+Use this for initial investigations before a named entity is known.
+
+---
+
+## Backward Compatibility
+
+- `config.agents` is OPTIONAL. Configs without it continue to work unchanged.
+- `EntityContext.identity` is OPTIONAL. All downstream consumers that read
+  `EntityContext` but do not use `identity` are unaffected.
+- `ParsedInvocation.scopeType` + `entity` are new fields with TypeScript default
+  `scopeType: null` — existing callers that deconstruct only the original fields
+  continue to compile without changes.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/workflows/verification-methodology.md

@@ -0,0 +1,174 @@
+# Verification Methodology — Background Investigator (finding false-positive audit)
+
+> Audience: CORE. Sits beside [`rca.md`](rca.md) and [`handover-contract.md`](handover-contract.md).
+> Status: **documentation, on-demand**. This wave it is invoked manually for a one-shot audit of a
+> finished report. It is written to be **repeatable and improvable** — a future orchestrator step can
+> consume it verbatim (see "Future wiring" at the end). It does NOT edit `references/principles.md`
+> (operator-LOCKED); it only PROPOSES.
+
+## 0. Why this exists
+
+The producer-side gates enforce **shape, not truth**: `findings-contract.ts` checks fields are
+present and well-formed, the problem-statement format gate rejects task-phrasing, and the Wave-18
+analyzer rule "[Never infer cache/cost — read the field](../../assets/agents/diagnostics-analyzer.md)"
+forces cache *detection* to come from real token fields. None of those re-validate that a finding's
+**asserted mechanism** is consistent with the grounded evidence. A finding can be perfectly shaped,
+honestly hedged in its assumptions, and still ship a **false positive** because its `failureOrigin`
+or `whyChain` states — *as fact* — a mechanism that the trace data does not confirm.
+
+The Background Investigator is the **independent, evidence-first audit pass** that closes that gap. It
+re-derives each finding's claims from the raw trace evidence and the run's `diagnosis-context.md`,
+and assigns a verdict. It is fed **raw data, never the orchestrator's conclusions** (peer-verification
+discipline): seeding it with the hypothesis it is meant to test would make it corroborate the error.
+
+## 1. Equipment (what the investigator must read FIRST)
+
+Before auditing a single finding, the investigator reads, in order:
+
+1. **`diagnosis-context.md`** — the run's grounded lens (entity identity · operator-stated purpose ·
+   FULL untruncated system prompt · tool inventory · source code when accessible). This is the same
+   Step-5.7 artifact the analyzers pre-read; it is how the investigator gets "full skill knowledge"
+   of *what the entity was supposed to do*, so it can tell intended behavior from a real deviation.
+2. **This methodology** — the five tiers + the verdict rubric.
+3. **The per-source cache-detection reference** (§5) + the relevant
+   [`references/source-platforms/<platform>.md`](../source-platforms/) — so it knows *where cache
+   tokens live for this platform* and where a *false* `cacheStatus="unknown"` can arise.
+4. **The raw evidence** — the sampled trace bodies and per-slice evidence files the findings cite,
+   plus the run's mechanical artifacts (trajectory corroborations, the `wave6/*.json` methodology
+   stamps, tier-0 output). These are the ground truth a citation is checked against.
+
+If a required pointer's raw source is **not retained** (e.g. trace bodies were not persisted), the
+investigator marks the affected citation **"unresolvable — needs raw-trace re-fetch"**. It never
+guesses, and never upgrades an unresolvable citation to "confirmed".
+
+## 2. The verdict — `AuditVerdict`
+
+Each finding (and, where relevant, each remedy) gets one or more verdict rows:
+
+```
+AuditVerdict = {
+  findingId: string
+  remedyId?: string
+  verdict: "CONFIRMED" | "DOWNGRADE" | "RETRACT"
+  tier: "citation-truth" | "mechanism-consistency" | "corroboration-alignment"
+       | "assumption-integrity" | "prevalence-honesty"
+  reason: string              // plain-words why, ≤2 sentences
+  contradictingEvidence: string  // the exact field/pointer that contradicts (e.g. "tr_7c1 cacheStatus=unknown")
+  caveat?: string             // REQUIRED when verdict=DOWNGRADE — the SECONDARY caveat to render
+}
+```
+
+A finding's overall disposition is the **most severe** verdict across its rows
+(`RETRACT` > `DOWNGRADE` > `CONFIRMED`).
+
+## 3. Handling rubric (operator-chosen: retract fabricated, downgrade unconfirmed)
+
+| Condition | Verdict | Report effect |
+|---|---|---|
+| A **load-bearing** citation is fabricated or unresolvable, OR the origin claim is contradicted outright by the grounded evidence | **RETRACT** | Finding removed from the active set **with a visible ledger note** (Methodology tab) — never silent-dropped. |
+| Finding is **plausible** but a load-bearing claim rests on an **unverified / unknown** mechanism (e.g. cache state unknown), or the WHAT/WHY is LLM-asserted-only with no mechanical corroboration, or a prevalence figure is inflated | **DOWNGRADE** | Severity capped to **SECONDARY**; the `caveat` is rendered; any "RECOMMENDED / RANK-1" emphasis on the dependent remedy is removed. |
+| Claims dereference cleanly and are consistent with grounded fields | **CONFIRMED** | No change. |
+
+**Visible, never silent** (Wave-17 discipline): a RETRACT writes a ledger note; a DOWNGRADE writes a
+caveat. The operator can always see *what the audit changed and why*.
+
+## 4. The five audit tiers
+
+Run cheapest-first; a single finding may collect verdicts from several tiers.
+
+### (i) Citation-truth resolution
+For every `failureOrigin.evidence` and every `whyChain[].evidence` pointer (`trace-id#msg[range]`,
+`file:line`, or a named run artifact), dereference it against the real trace body / source in
+`diagnosis-context.md`. The dereferenced content must **support** the paired `whatHappened`.
+- Unresolvable **load-bearing** pointer → **RETRACT** (or "unresolvable — needs raw-trace re-fetch"
+  when the raw source simply was not retained; flag, do not retract on absence alone).
+- Resolves but **does not support** the narration → **DOWNGRADE**.
+
+### (ii) Mechanism-consistency — *priority tier: the caching class*
+Flag any `failureOrigin` / `whyChain` step that asserts a **mechanism contradicted by a grounded
+field**. The caching specialization (the motivating class):
+
+> A **cache-dependent mechanism** asserted as fact — "the static prefix is re-sent / re-processed
+> every step", "uncached", "no caching benefit", "per-step token re-pay" — while the grounded
+> `cacheStatus` for the finding's `sourceTraceIds` is **`unknown`** or **`miss`-claimed-as-`off`**,
+> **OR** while an `assumptions[]` entry about caching is **`unverified` / `hypothesis-pending`**.
+
+→ **DOWNGRADE** to SECONDARY with caveat: *"cache state UNKNOWN — mechanism unverified; the rising
+per-step latency may be the growing transcript, not the static prefix."* If the **entire** finding
+rests on the uncached premise, escalate toward RETRACT.
+
+This is the consistency check the analyzer's detection rule cannot make about itself: detection says
+*"read the field, don't infer"*; the investigator says *"and don't ASSERT a mechanism the field
+leaves unknown."*
+
+### (iii) Corroboration alignment
+A **PRIMARY** finding's `failureOrigin.what` / `why` must resolve against the run's mechanical
+trajectory corroborations (retry-loop → loop/latency · tool-error → tool-misuse · abandoned-call →
+handoff-loss · oscillation → prompt-underspec). LLM-asserted-only, with no mechanical corroboration
+→ **DOWNGRADE** to SECONDARY (surface the same evidence-floor reason the enricher would).
+
+### (iv) Assumption-status integrity
+A load-bearing claim in `problem` / `failureOrigin` / `whyChain` cannot rest on an assumption marked
+`unverified` / `hypothesis-pending` while being stated **declaratively as fact**. The contradiction
+between a confident origin and its own hedged assumption → **DOWNGRADE**. (The caching FP is the
+common instance of this general rule.)
+
+### (v) Prevalence honesty
+Any `k/n`, "N traces", or "X% of the population" claim is checked against `sourceTraceIds.length` and
+the sampled denominator (`sampledCount`). A figure larger than the evidence supports → **DOWNGRADE**
+with the corrected `seen in k/n sampled` in the caveat.
+
+## 5. Per-source cache-detection reference
+
+"Different ways depending on the trace source." Where cache tokens live, and where a **false**
+`cacheStatus="unknown"` (which then licenses a caching FP under tier ii) can arise:
+
+| Source | Where the cache signal lives | Easy-to-miss / false-`unknown` risk |
+|---|---|---|
+| **Langfuse** | per-GENERATION `usageDetails.input_cached_tokens` (cache read), `cache_creation_input_tokens` (cache write); Anthropic-shape `usage.cache_read_input_tokens` / `cache_creation_input_tokens`; flattened top-level aliases | Cache tokens on a **non-doGenerate** GENERATION span, or at **trace-level** `usageDetails`, are not seen if only leaf `doGenerate` spans are scanned. A flat export that omitted `usageDetails` ⇒ genuine `unknown` (do not read it as "uncached"). |
+| **OTel** | span attrs `gen_ai.usage.cache_read_input_tokens` / `input_cached_tokens`, `gen_ai.usage.cache_creation_input_tokens`, `llm.usage.*` variants | Vendor-specific attribute names (`anthropic.*`, `bedrock.*`) and **baggage**-propagated usage are not in the standard key set ⇒ `unknown`. |
+| **Claude-Code / Codex / local-JSONL** | no native cache-token reporting in the transcript format | `cacheStatus` is **always `unknown` / absent**. *Every* cache or per-step-cost claim on these sources is a hypothesis — tier (ii) downgrades any that are asserted as fact. |
+
+Cross-reference: the analyzer's "Never infer cache/cost — read the field (W18-cache)" section is the
+**detection** rule; this table tells the investigator where detection can legitimately fail to a
+`unknown`, so it can tell *"unknown because the field was absent"* (a real hypothesis) from
+*"unknown because the normalizer didn't look in the right place"* (flag for a normalizer follow-up).
+
+## 6. Worked example (synthetic)
+
+> **Finding F-syn-lat-2** (PRIMARY, RANK-1 RECOMMENDED remedy).
+> `problem`: *"The agent runs ~6 serial reasoning calls per trace; per-step latency climbs from 2.2s
+> to 5.6s because the 18k-token system prompt is re-sent and re-processed on every step."*
+> `failureOrigin.whyChain[origin]`: *"system prompt re-sent every step inflates per-step cost."*
+> `assumptions[]`: *"Rising per-step latency reflects growing input, not throttling — UNVERIFIED;
+> `input_cached_tokens` not present in the export so caching state could not be confirmed."*
+> Source platform: Langfuse export; `cacheStatus = "unknown"` for all source traces.
+
+**Audit:**
+- Tier (ii) mechanism-consistency: origin asserts "re-sent **and re-processed** every step" *as fact*
+  → but re-*processing* only holds if the prefix is **uncached**, and `cacheStatus="unknown"`.
+  `contradictingEvidence: "all sourceTraceIds cacheStatus=unknown; caching assumption UNVERIFIED"`.
+- Tier (iv) assumption-integrity: the same assumption block marks caching unverified while the origin
+  states it declaratively.
+
+**Verdict:** `DOWNGRADE`, tier `mechanism-consistency`,
+`caveat: "cache state UNKNOWN — the prefix may already be cached (~typical for static system
+prompts); rising per-step latency may be the growing transcript, not prefix re-processing. Confirm
+input_cached_tokens on live traces before prioritizing a prefix-caching fix."` → severity SECONDARY,
+RANK-1/RECOMMENDED emphasis removed from the "enforce prompt caching" remedy. The *other* legitimate
+driver (serial-chain depth) is unaffected and stays.
+
+## 7. Future wiring (improve-loop)
+
+This methodology is built to be promoted from on-demand to in-pipeline without rewrite:
+- A `diagnostics-investigator` agent (sibling of `diagnostics-analyzer`) would take the inputs in §1
+  and emit `AuditVerdict[]`.
+- An orchestrator **Step 7.5** (post-`findings-contract`, pre-RCA) would run it and apply §3:
+  DOWNGRADE → SECONDARY + caveat (reuse the enricher's existing SECONDARY caveat surface);
+  RETRACT → remove + `RunMeta.decisions[]` ledger note.
+- A deterministic backstop (`cache-consistency.ts`) could front-run tier (ii) for free.
+
+To **improve** the methodology: when a new false-positive class is observed, add a tier (or a cue to
+an existing tier) here with a synthetic worked example, the same way §4(ii) was seeded from the
+prompt-caching class. Keep cues conservative — match explicit mechanism tokens, never any bare
+mention of the topic — so the audit never manufactures its own false positives.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/awareness/blind-spots.ts

@@ -0,0 +1,167 @@
+/**
+ * scripts/awareness/blind-spots.ts
+ * R2.2 — blind-spots derivation for the Methodology Step 1.5 widget.
+ * Type A — Pure Script (deterministic; NO clock/random/LLM/I-O).
+ *
+ * A "blind spot" is a signal that Tier-0 CANNOT measure (so it would never become
+ * the auto-picked primary signal) but which the awareness LLM mini-sample (R2.2)
+ * CAN surface. The blind-spots table makes the measurement gap HONEST (design
+ * philosophy §2.3): for each candidate signal we state whether Tier-0 can measure
+ * it, who checked it, and what was found.
+ *
+ * The canonical Tier-0-MEASURABLE set is derived from what tier0-scan.ts actually
+ * computes: error spike, latency spike, feedback cluster, low score, api exhaustion,
+ * skill-behavior deviation. EVERYTHING ELSE in the WHAT taxonomy is a Tier-0
+ * blind spot — only the LLM awareness layer can see it.
+ */
+
+import type { WhatCategory } from "../normalize/trace.ts";
+
+/** WHAT-categories Tier-0 can MEASURE deterministically (from tier0-scan.ts). */
+export const TIER0_MEASURABLE: ReadonlySet<WhatCategory> = new Set<WhatCategory>([
+  "latency-spike",
+  "low-score",
+  "user-complaint", // feedback cluster
+  "cost-overshoot", // token totals are countable
+]);
+
+/**
+ * WHAT-categories that are Tier-0 BLIND SPOTS — only the LLM awareness layer
+ * (or a deep-read) can surface them. The complement of TIER0_MEASURABLE over the
+ * full WhatCategory union.
+ */
+export const TIER0_BLIND_SPOTS: ReadonlyArray<WhatCategory> = [
+  "wrong-output",
+  "missing-output",
+  "loop",
+  "format-violation",
+  "hallucination",
+  "missing-context",
+];
+
+export interface BlindSpotRow {
+  /** Signal / failure-mode name. */
+  signal: string;
+  /** Whether Tier-0 can MEASURE this signal. */
+  measurable: "Tier-0" | "No";
+  /** Who checked it ("tier-0 scan" | "awareness LLM sample" | "—"). */
+  checkedBy: string;
+  /** What the check found. */
+  result: string;
+}
+
+export interface BlindSpotsInput {
+  /**
+   * Signals the awareness LLM mini-sample DISCOVERED (free-form labels from the
+   * analyzer). Used to fill the "result" column for blind-spot signals.
+   */
+  awarenessFindings: string[];
+  /**
+   * Whether the awareness layer actually fired. When false (library priors), the
+   * blind-spots table renders a single placeholder row.
+   */
+  awarenessFired: boolean;
+}
+
+/**
+ * Build the blind-spots table rows. Deterministic: iterates the canonical
+ * Tier-0-measurable list (marked measurable) then the blind-spot list (marked No),
+ * attributing the awareness LLM as the checker for blind spots when it fired.
+ *
+ * A blind-spot signal whose name appears (case-insensitive substring) in the
+ * awarenessFindings is marked "DISCOVERED"; otherwise "not observed".
+ */
+export function buildBlindSpots(input: BlindSpotsInput): BlindSpotRow[] {
+  if (!input.awarenessFired) {
+    return [
+      {
+        signal: "(all)",
+        measurable: "No",
+        checkedBy: "—",
+        result: "Awareness layer skipped (library priors exist) — see Step 1.5 placeholder.",
+      },
+    ];
+  }
+
+  const rows: BlindSpotRow[] = [];
+
+  // Tier-0-measurable signals first (these are NOT blind spots).
+  for (const sig of TIER0_MEASURABLE) {
+    rows.push({
+      signal: sig,
+      measurable: "Tier-0",
+      checkedBy: "tier-0 scan",
+      result: "Measured deterministically (no LLM needed).",
+    });
+  }
+
+  // Blind spots — only the awareness LLM can see these.
+  const lowered = input.awarenessFindings.map((f) => f.toLowerCase());
+  for (const sig of TIER0_BLIND_SPOTS) {
+    const discovered = lowered.some((f) => f.includes(sig.toLowerCase()));
+    rows.push({
+      signal: sig,
+      measurable: "No",
+      checkedBy: "awareness LLM sample",
+      result: discovered ? "DISCOVERED by awareness sample" : "not observed in awareness sample",
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * True when the awareness sample surfaced at least one Tier-0 blind spot — i.e.
+ * the measurement layer caught something Tier-0 would have missed. Used to mark
+ * "discovered" badges on the R2.4 selection-rule cards.
+ */
+export function awarenessDiscoveredBlindSpot(rows: BlindSpotRow[]): boolean {
+  return rows.some((r) => r.measurable === "No" && r.result.startsWith("DISCOVERED"));
+}
+
+// ── SO-05 CLI entrypoint ──────────────────────────────────────────────────────
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const get = (flag: string): string | undefined => {
+    const idx = args.indexOf(flag);
+    return idx !== -1 ? args[idx + 1] : undefined;
+  };
+
+  // Accept awareness findings as a JSON array string or a file path
+  const findingsArg = get("--findings");
+  const firedStr = get("--awareness-fired");
+  const outputPath = get("--output");
+
+  if (!findingsArg) {
+    process.stderr.write(
+      "Usage: bun scripts/awareness/blind-spots.ts --findings '[\"signal1\",\"signal2\"]' [--awareness-fired true|false] [--output <file>]\n"
+    );
+    process.exit(1);
+  }
+
+  const { writeFileSync } = await import("fs");
+
+  let awarenessFindings: string[];
+  try {
+    awarenessFindings = JSON.parse(findingsArg) as string[];
+  } catch {
+    process.stderr.write(`--findings must be a JSON array string\n`);
+    process.exit(1);
+  }
+
+  const awarenessFired = firedStr !== "false";
+  const rows = buildBlindSpots({ awarenessFindings, awarenessFired });
+  const discovered = awarenessDiscoveredBlindSpot(rows);
+
+  const result = { rows, discoveredBlindSpot: discovered };
+  const out = JSON.stringify(result, null, 2);
+
+  if (outputPath) {
+    writeFileSync(outputPath, out, "utf8");
+    process.stderr.write(`Blind-spots table written to ${outputPath}\n`);
+  } else {
+    process.stdout.write(out + "\n");
+  }
+  process.exit(0);
+}