@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/reference.md

@@ -0,0 +1,119 @@
+# mutagent-diagnostics — Reference Entry Point
+
+> Load this first. It provides the full architecture diagram, dependency graph, and TOC for all reference docs.
+
+## Architecture DAG
+
+> The Orchestrator is **NOT a sub-agent** — it is the parent coding-agent session following
+> `references/workflows/orchestrator-protocol.md` inline (PR-024; the retired
+> `diagnostics-orchestrator.md` is archived). The sub-agents are the analyzer (RCA) + the
+> vendored apply actors (ai-engineer WRITE · ai-architect VERIFY) that drive the shared
+> `mutagent-cli apply` — the bespoke apply-worker is retired (M9).
+
+```mermaid
+flowchart TD
+  USER[Operator in coding agent] -->|invoke| SKILL[mutagent-diagnostics SKILL.md]
+  SKILL -->|§0 setup detect| DETECT{config present?}
+  DETECT -->|NO| ONB[Onboarding — references/workflows/onboarding.md]
+  DETECT -->|YES| ORCH[Orchestrator — parent session\nreferences/workflows/orchestrator-protocol.md]
+  ONB --> CFG[config.yaml + .mutagentrc]
+  CFG --> SKILL
+  ORCH -->|Bash CLI / file read| SRC[Source Platform — references/source-platforms/]
+  ORCH -->|bun tier0-scan.ts| TIER0[Tier 0 SCRIPT — scripts/tier0-scan.ts]
+  ORCH -->|normalize + extract EntityContext| NORM[Normalizers — scripts/normalize/platforms/*.ts\n+ entity-context.ts R1.7]
+  TIER0 -->|bun slicer.ts| SLICE[Slicer SCRIPT — scripts/slicer.ts]
+  ORCH -->|Agent dispatch| ANL[N Analyzers ≤5 — assets/agents/diagnostics-analyzer.md]
+  ANL --> ORCH
+  ORCH -->|LLM RCA reasoning| TL[RCA Layer — references/workflows/rca.md]
+  TL -->|Step 8.5: bun build-render-input.ts| ENRICH[Enricher — scripts/enrich/build-render-input.ts\ndeterministic · fail-loud]
+  NORM -->|EntityContext| ENRICH
+  ENRICH -->|bun render.ts| REPORT[report.html — assets/templates/report.html.tpl\ngold-standard multi-tab]
+  REPORT --> COPY{Operator pastes copy-back markdown}
+  COPY -->|approved, gated| APPLY[Shared apply — assets/agents/ai-engineer.md then mutagent-cli apply @mutagent/tools]
+  APPLY -->|worktree-PR| LOCAL[Local Target — references/target-platforms/]
+  APPLY -->|REST create-rev| REMOTE[Remote Target — references/target-platforms/cloud-rest.md]
+```
+
+## Dependency Graph
+
+```mermaid
+flowchart LR
+  SKILL[SKILL.md] --> RF[reference.md]
+  SKILL --> RW0[workflows/orchestrator-protocol.md\nStep 8.5 = build render input]
+  SKILL --> RW1[workflows/onboarding.md]
+  SKILL --> RW2[workflows/diagnostics.md]
+  SKILL --> RW4[workflows/rca.md]
+  SKILL --> RP[principles.md]
+  SKILL --> RFL[operator-feedback-log.md]
+  SKILL --> ROP[operation-inventory.md]
+  SKILL --> RAS[adapter-strategy.md]
+  SKILL --> RFS[filter-search-matrix.md]
+  SKILL --> RHK[harness-knowledge.md]
+  SKILL --> RC[config.md]
+  SKILL --> ROQ[open-questions.md]
+  SKILL --> AG2[agents/diagnostics-analyzer.md]
+  SKILL --> AG3[agents/ai-engineer.md]
+  SKILL --> AG4[agents/ai-architect.md]
+
+  RW1 --> RS[source-platforms/*.md]
+  RW1 --> RT[target-platforms/*.md]
+  RW0 --> RW2
+  RW0 --> RW4
+  RW2 --> RW4
+  RW2 --> RS
+  RW3 --> RT
+
+  RS -.->|hyperlinks| EXT1[Upstream platform docs]
+  RT -.->|hyperlinks| EXT2[Upstream platform docs]
+
+  AG2 --> RW2
+  AG3 --> RW3
+
+  T0[scripts/tier0-scan.ts] --> NT[scripts/normalize/trace.ts]
+  SL[scripts/slicer.ts] --> NT
+  EC[scripts/normalize/platforms/entity-context.ts] --> NT
+  EN[scripts/enrich/build-render-input.ts] --> NT
+  EN --> RR
+  RR[scripts/report/render.ts] --> RHT[assets/templates/report.html.tpl]
+  CT[scripts/contract/types.ts] --> RR
+  CL[scripts/config/load.ts] --> CS[scripts/config/schema.ts]
+  CV[scripts/config/validate.ts] --> CS
+  SD[scripts/setup/detect.ts] --> CL
+  SD --> CV
+  NPL[scripts/normalize/platforms/*.ts] --> NT
+  NPL --> EC
+```
+
+## Table of Contents
+
+| Reference | Purpose |
+|-----------|---------|
+| `overview.md` | **Entry point for new users** — What/when/quick-start/glossary (PRD-SO-01) |
+| `principles.md` | 53 Design Principles — PR-001 to PR-053 |
+| `operator-feedback-log.md` | Append-only operator feedback on the report shape (Wave-5 R1.6) — the durable WHY behind the gold-standard renderer |
+| `operation-inventory.md` | Type A/B/C operation classification |
+| `adapter-strategy.md` | Adapter Q1-Q6 locked decisions |
+| `filter-search-matrix.md` | Per-platform Filter/Search coverage matrix |
+| `harness-knowledge.md` | Platform Knowledge Table (expandable) |
+| `config.md` | Config schema with doc strings |
+| `open-questions.md` | OQ-1..OQ-10 all resolved |
+| `workflows/onboarding.md` | 8-phase onboarding procedure |
+| `workflows/orchestrator-protocol.md` | Inline orchestrator protocol (parent session); Step 8.5 builds the render input via the enricher |
+| `workflows/diagnostics.md` | Full diagnostic procedure + NL→filter |
+| `workflows/rca.md` | RCA layer procedure + 3-dim taxonomy |
+| `workflows/verification-methodology.md` | Background Investigator finding false-positive audit (5 tiers + AuditVerdict + per-source cache-detection); on-demand, improvable |
+| `workflows/rendering-anatomy.md` | Canonical per-finding + per-remedy panel anatomy (PRD-CC-12) |
+| `workflows/schedule-prep.md` | How to wire scheduling post-v0.1 |
+| `source-platforms/langfuse.md` | Langfuse CLI fetch + filter examples |
+| `source-platforms/otel.md` | OpenTelemetry OTLP pull + queries |
+| `source-platforms/local-jsonl.md` | Local JSONL file read patterns |
+| `source-platforms/claude-code-transcripts.md` | Claude Code session transcript format |
+| `source-platforms/codex-transcripts.md` | Codex session transcript format |
+| `target-platforms/local-claude.md` | .claude/agents/*.md apply recipe |
+| `target-platforms/local-codex.md` | .codex/agents/*.md apply recipe |
+| `target-platforms/local-cursor.md` | Cursor agent dir apply |
+| `target-platforms/local-opencode.md` | OpenCode agent dir apply |
+| `target-platforms/local-mastra.md` | Mastra code-construct apply |
+| `target-platforms/local-cloud-agent-sdk.md` | Cloud Agent SDK apply |
+| `target-platforms/cloud-rest.md` | REST PUT with idempotency |
+| `internal/self-diagnostics.md` | [INTERNAL] PR-022 self-diagnostics playbook |

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/script-index.md

@@ -0,0 +1,101 @@
+# Script Index — the data-flow navigation map
+
+> **Why this file exists (W13).** Most recurring report bugs are *forgotten data*: a
+> producer runs but its output is never threaded into `runMeta`, or the renderer
+> dereferences a field no producer guaranteed → `undefined` in the HTML. This index is
+> the single place the orchestrator (and any maintainer) reads to know **what every
+> script consumes, produces, and which `runMeta`/render field depends on it.** If you
+> add a step, add its row here. The **gates** column is what FAILS LOUD if the data is
+> forgotten — never rely on memory; the gate is the enforcement.
+>
+> Quick listing at runtime: `bash scripts/cli/run.sh --list` (or read this file).
+
+## Run sequence → script → I/O → the field it feeds → the gate that enforces it
+
+> **Form column (REQ-051).** Every operation is exactly one of ①**script /
+> code-workflow** · ②**agent-workflow** · ③**hybrid** (legend + integrity rule in
+> "Operation forms (REQ-051)" below). ②-form steps (e.g. Step 2, Step 3) produce
+> TYPED outputs and are legitimate — a "no script" cell is NOT a coverage gap.
+
+| Step | Form | Script | Consumes | Produces | Threads into `runMeta` / render | Enforced by |
+|------|------|--------|----------|----------|----------------------------------|-------------|
+| 2 | ②agent-workflow | *(no script)* — `Bash(<cli> scores list)` + LLM classify | platform score samples | **scale type** (`boolean`\|`discrete-1-5`\|…) — TYPED | informs Step 3 `scoreBelow` threshold | AskUserQuestion on ambiguity |
+| 3 | ②agent-workflow | *(no script)* — LLM NL→filter reasoning | operator NL query + scale type | **`TraceFilter`** (agentId/time/hasFeedback/scoreBelow) — TYPED | parameterizes the UPSTREAM `mutagent-cli trace fetch --export` query (Helix pre-stage) | filter-search-matrix per-platform flags |
+| 3a | ①script | `scripts/invocation/parse-brief.ts` | operator brief (string) | `{agent,timeWindow,focus,residual,scopeType,entity}` | `runMeta.operatorInvocation` (verbatim, D2) | parse-brief.test |
+| 3.5 | ③hybrid | `scripts/awareness/llm-sample.ts` + `blind-spots.ts` | 5 representative traces | `AwarenessSample`, `BlindSpots` | `runMeta.awarenessSample` · `runMeta.blindSpots` (F2) | completeness-check · wave6-checklist |
+| 3.7 | ①script | `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`) — reads the handed-over UniTF JSONL (+ manifest) from `HandoverBundle.inputs[]`; fetch+normalize now upstream in `@mutagent/tools` | UniTF JSONL (one `UnifiedTrace`/line) + optional `manifest.json` | `TraceMetadata[]`, `EntityContext` (deterministic, no LLM) — projected from `ut.*` + `ut.ext.agent` | `diagnosedEntity` · `billedTokens` · trace latency (span-authoritative, W13-D2) · **GROUNDED cache fields** (W18-cache: `cachedInputTokens` · `cacheCreationTokens` · `cacheStatus` `hit`\|`miss`\|`unknown` · `cacheHitRate`) — carried in `ut.tokens`/`ut.ext.cache`; absent ⇒ `unknown`, NEVER inferred from flat `promptTokens` | findings-contract (entity) · render-contract pass |
+| 4 | ①script | `scripts/tier0-scan.ts` | `TraceMetadata[]` | `Tier0Report` (errorSpike/latencySpike/feedbackCluster/estimatedSlots) | signal census candidates | tier0 tests |
+| 4.5 | ①script | `scripts/library/match.ts` | Tier0Report + entity | `libraryMatches[]` (3× weight) · double-zero gate | `runMeta.decisions` (if empty) | double-zero fail-loud |
+| 5 | ①script | `scripts/slicer.ts` · `scripts/sample/representative.ts` | Tier0Report + metadata | slices · `sample` + `CoverageProof` (worst-weighted, W13-D9) | per-finding `coverageProof` (W12-13) | representative.test |
+| 5c | ①script | `scripts/scan/objection.ts` | trace bodies (user-authored text) | `ObjectionScanResult` (`byTrace`, `objectionRate`) — deterministic, NO LLM | **sampling-priority hint only** — NOT a census signal (advisory pre-filter; may corroborate a deep-read finding) | objection.test |
+| 5.7 | ①script | `scripts/context/build-diagnosis-context.ts` (CLI: `--entity-context <f> --traces <f> --output <f> [--purpose <text>] [--doc <label>:<path> …]`) | `EntityContext` (Step 3.7) + normalized traces (+ optional source docs) | `diagnosis-context.md` — GROUNDED LENS (Identity · Purpose · FULL system prompt · Tool Inventory · Source Code; provenance-badged), Type A pure (no LLM/clock/random) — EXTRACTED FACT only | analyzer brief `artifacts_in.diagnosis_context` (W18-context, MANDATORY-PRE-READ before fan-out) | build-diagnosis-context.test |
+| 6 | ②agent-workflow | analyzer dispatch (`assets/agents/diagnostics-analyzer.md`) | slice + **handover-contract schema** (W13-D7) + `diagnosis-context.md` (W18-context pre-read) | `Finding[]` (`problem` + rank/cost/correctness REQUIRED, W18-problem/W13-D1) | findings | **findings-contract.ts** RESEND if missing (incl. `problem(task-phrased)`) |
+| 6.5 | ①script | `scripts/scan/trajectory.ts` (CLI: `--bodies <f> [--out <f>]`) | sampled deep-read trace bodies | `TrajectoryCorroboration[]` (`{signal, evidenceRef}`) — mechanical, deterministic, NO LLM | `SignalCensusContext.corroborations` (R1 evidence floor → PRIMARY eligibility) | trajectory.test |
+| 6.5 | ①script | `scripts/library/store.ts` (`foldValidDigests`) over `deep-read-ledger.json` | per-entity cross-run ledger + (analyzerVersion · entityFingerprint · nowMs · ttlMs) | `DeepReadLedgerEntry[]` (still-VALID folded digests) | `SignalCensusContext.foldedDigests` (R2 — re-floored by Block C, never trusted blindly) | ledger.test · store via library.test |
+| 7 | ③hybrid | aggregate (LLM dedup) + `scripts/aggregate/sort-findings.ts` (W13) | analyzer Finding[] | deduped + **deterministically sorted** findings | `runMeta.findings` | findings-contract |
+| 8.5b | ③hybrid | `scripts/library/store.ts` (`foldValidDismissals`, NO TTL) + PINNED host-runtime reasoning (`scripts/enrich/dismissal-match.ts` `buildSemanticMatchRequest`, temp-0 · C-PIN) | produced findings + folded DISMISSED verdicts (`verdict-ledger.json`) + `entityFingerprint` | `dismissalContext` (`{ entitySlug, dismissedEntries, VerdictLookup }`) → enricher | (suppressed findings REMOVED from `renderInput.findings`; NO Suppressed section) | dismissal-match.test · dismissal-enrich.test |
+| 8.5 | ①script | `scripts/enrich/build-render-input.ts` (+ `rank-remedies.ts`, `signal-census`, heatmap, selectionRules; **`--dismissalContext`** OPTIONAL — semantic-dismissal partition, severity-escalation guard FIRST, absent ⇒ no-op) | findings + EntityContext + wave6 stamps + **`--signal-ctx <f>`** (`SignalCensusContext`, Step 6.5; OPTIONAL — absent ⇒ safe-by-default Tier-0-only census) | `RenderInput` (rank BACKFILLED, signals reconciled; discovered signals evidence-floored, `suspectedPrimaryUnconfirmed` on R7; ACTIVE findings only) | the whole render contract + `primarySignal` | **completeness-check render-contract pass (W13-D6)** |
+| 8.9 | ①script | `scripts/validate/render-js-syntax.ts` (PR-050) | rendered HTML | parse verdict | — | Step-8.9 gate |
+| 9 | ①script | `scripts/report/render.ts` → `assets/templates/report.html.tpl` | `RenderInput` | `report.html` | — | render-js-syntax · escapeHtml/badge guards (W12/W13-A) |
+| 9.9 | ①script | `scripts/validate/finalize-gate.ts` + `report-checklist.yaml` (W14) | rendered `report.html` + audience | `{ pass, gaps[] }` (per-gap `section·tier·what·sourceStep·healAction`) | — | **Step 9.9 OUTPUT gate** — CRIT blocks "report done"; backtrace each gap's `sourceStep` (this table) → re-run producer → re-render → re-check (bounded 2 rounds, then escalate loud) |
+| 11.5 | ①script | `scripts/library/store.ts` (`recordVerdict` · `writeApprovedFinding` mirror) | parsed copy-back (`## Invalid findings` + `## Approved Remedies` blocks) + run-context (`runId·ts·operatorInvocation·entityFingerprint`) | unified `verdict-ledger.json` (both polarities — feeds Step 8.5b next run) | — | verdict-ledger.test |
+
+## Operation forms (REQ-051) — and why "no script" is not a gap
+
+Every pipeline operation is exactly ONE of three forms. The `Form` column above
+tags each step; this section is the legend + the integrity rule.
+
+| Form | What it is | Type (PR-019) | Boundary artifact |
+|------|-----------|---------------|-------------------|
+| ①**script / code-workflow** | 1:1 command→script; deterministic, structured I/O; zero LLM; unit-testable in isolation. | Type A | the script's typed output (e.g. `Tier0Report`, `RenderInput`) |
+| ②**agent-workflow** | a command drives the agent through one-or-more steps (LLM reasoning); may point into another workflow. Not unit-testable in isolation. | Type B | the TYPED structure the agent is required to emit (e.g. scale type, `TraceFilter`, `Finding[]`) |
+| ③**hybrid** | the agent invokes ①-scripts AND runs LLM loops/calls around them; the script gives deterministic shape, the agent decides when/how + reasons over the result. | Type C | the script's typed output, consumed/reconciled by the agent |
+
+> **Integrity rule — TYPED ARTIFACTS at boundaries, not script-coverage.**
+> The skill's correctness invariant is **NOT** "every operation must be a script."
+> It is: **every step hands the next step a TYPED artifact**, and a gate
+> (`findings-contract` · `completeness-check` render-contract · `finalize-gate`)
+> asserts that artifact's shape. A ②agent-workflow op is a first-class, legitimate
+> form — it is a gap ONLY if it emits an UNTYPED / unvalidated blob, never merely
+> because it has "no script." Do not "fix" a ②-form step by forcing it into a
+> script; fix it (if broken) by tightening the typed contract on its output.
+
+**Step 2 (score-scale inference)** and **Step 3 (NL→TraceFilter)** are ②agent-workflow
+ops by design — both require LLM judgment (classify an arbitrary platform's scoring
+convention; translate operator natural language into a structured filter). Each
+produces a **TYPED output** (Step 2 → a scale-type enum; Step 3 → a `TraceFilter`)
+that the downstream code-workflow consumes. They are **legitimate, not coverage
+gaps** — the absence of a `scripts/*.ts` for them is correct, not a defect.
+
+## Trace intake — single read path (post UniTF flip / Step 3.7)
+
+The skill no longer owns any per-platform fetch/normalize entrypoints. Those five
+adapters (langfuse · local-ndjson · claude-code · codex · otel) now live + are
+tested in `@mutagent/tools` and run UPSTREAM via `mutagent-cli trace fetch`, which
+emits a UniTF JSONL + `manifest.json`. Inside the skill there is ONE
+platform-agnostic reader, exposed via the same INTERNAL `--out-entity` /
+`--out-metadata` transport through `scripts/cli/run.sh` (run.sh only — NOT the
+product `mutagent` CLI). `--out-entity` is the AUTHORIZED producer of
+`entity-context.json` (consumed at Step 8.5a via the enricher's `--entity-context`
+flag). ≥1 `--out-*` required; deterministic — no clock/random/network/LLM.
+
+| Reader | `--in` shape | Projects | CLI flags |
+|--------|--------------|----------|-----------|
+| `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`) | UniTF JSONL — one `UnifiedTrace`/line; blank lines skipped, non-UniTF lines tolerated-but-visible | `TraceMetadata[]` (from `ut.*`) + `EntityContext` (from `ut.ext.agent`) via `unitf-adapter.ts` | `--in <traces.jsonl> [--manifest <manifest.json>] --out-metadata --out-entity` |
+
+The **self-diagnosis** skill-typed entity (report-only path, orchestrator-protocol
+Step 12.2) is NOT a platform read — it is produced by `buildSkillSelfEntityContext`
+in `scripts/normalize/platforms/entity-context.ts` (kept) from the skill's own
+SKILL.md + session. All UniTF-projected rows produce an agent-typed entity for
+diagnosing an external agent run.
+
+## The five gates (the durable "never forgotten" enforcement)
+
+1. **`findings-contract.ts`** (Step 7) — TypeBox over Finding/Remedy/Assumption; the required apply-readiness fields (incl. cost/correctness; `rank` is enricher-derived) must be present or the analyzer is RESENT. **W18-problem CONTENT gate:** `problem` is REQUIRED (presence), AND `isTaskPhrasedProblem` RESENDS `problem(task-phrased)` when a present `problem` reads as a task/remedy (leading bare imperative verb from `BANNED_LEADING_IMPERATIVE_VERBS`, or a `should`/`must`/`needs to` modal in its main clause). The fix must live in `remedies`, not the `problem` description. *Producer ↔ contract agreement.*
+2. **`completeness-check.ts` render-contract pass** (W13-D6) — asserts the **exact** fields `render.ts` dereferences (sessionId, actionable, failureOrigin.evidence/confidence, remedy fields, the methodology widgets). *Gate ↔ renderer agreement.* "Gate passes but render garbles" is structurally closed. *INPUT side (RenderInput JSON).*
+3. **`render-js-syntax.ts`** (PR-050) — every emitted `<script>` must parse. *OUTPUT side (rendered HTML).*
+4. **`wave6-checklist.ts`** — the Wave-6 methodology widgets are present/threaded.
+5. **`finalize-gate.ts` + `report-checklist.yaml`** (W14, Step 9.9) — per-section completeness of the RENDERED `report.html`: no soft fallback shipped (`RANK n/a`/`cost:n/a`), no `undefined`/`null`/`NaN` in visible prose, no `class="internal"` leak on client, prose (not raw-JSON) entity prompt. CRIT blocks "report done"; gaps backtrace via this table → bounded self-heal. *OUTPUT side (rendered HTML) — the complement to gate 2.*
+
+## The three sources of truth (keep them in agreement)
+For any field the report shows: **canonical type** (`scripts/normalize/trace.ts`) ↔ **producer contract** (`references/workflows/handover-contract.md` + `diagnostics-analyzer.md`) ↔ **gate** (above). A field present in only two of the three is the bug class this index + the gates exist to kill. A static audit agent validates exactly this (conformance matrix + data-leak tab) on every run.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-adapter-contract.md

@@ -0,0 +1,93 @@
+# Source-Adapter Contract — adding a trace source
+
+> Authority: `scripts/source/` (the read-side transport layer). This is the
+> symmetric twin of the write-side `TargetAdapter` contract in
+> `@mutagent/tools` `src/apply/` (see `adapter-strategy.md` Q4/DC-5).
+
+## Why this exists
+
+Before Item #7 the per-platform read path was **ad-hoc**: `scripts/tier0-scan.ts`
+held a hard-coded `if (platform === "langfuse") … if (platform === "claude-code") …`
+dispatch with inline dynamic imports. Adding a source meant editing that switch.
+
+Now sources register **declaratively** through a registry that mirrors the apply
+layer exactly:
+
+| apply (write side, `@mutagent/tools/src/apply`) | source (read side, `scripts/source`) |
+| --- | --- |
+| `AdapterId` (const) | `SourceAdapterId` (const) |
+| `TargetAdapter` (interface) | `SourceAdapter` (interface) |
+| `registerTargetAdapter` / `getTargetAdapter` (throws) / `listTargetAdapters` / `clearTargetAdapters` | `registerSourceAdapter` / `getSourceAdapter` (throws) / `listSourceAdapters` / `clearSourceAdapters` |
+| `registerBuiltinAdapters()` | `registerBuiltinSourceAdapters()` |
+| `apply.kind` → `adapterIdForKind()` (binding.ts, **N:1**) | `source.platform` → adapter id (**1:1, identity — no binding module**) |
+
+**The one intentional asymmetry**: the apply layer needs a `binding.ts` because
+`apply.kind` (4 config values) maps *non-1:1* onto adapter ids (`code-pr` **and**
+`markdown` → `worktree-pr`; `cloud-deploy` → `rest` **or** `vendor-cli`). On the
+read side `source.platform` → adapter id is **1:1** — the registry key *is* the
+platform literal — so there is no binding module (it would be an identity
+function). Everything else is a direct mirror.
+
+## The interface
+
+```ts
+// scripts/source/types.ts
+export interface SourceAdapter {
+  id: SourceAdapterIdValue;   // === a SourcePlatform literal; binds to config source.platform
+  label: string;              // human label (onboarding pickers)
+  live: boolean;              // false = declared SEAM stub, true = shipped
+  tier0Scan?: Tier0ScanFn;    // OPTIONAL per-platform Tier-0 enrichment
+}
+```
+
+`tier0Scan` is **optional and behavior-defining by its absence**:
+
+- **present** (langfuse, claude-code) → `runTier0ScanPlatformAware` dispatches a
+  homogeneous batch to it for signal extraction tuned to that source
+  (e.g. Langfuse `LF-001` low-score-concentration, Claude-Code compaction clusters).
+- **absent** (otel, local-jsonl, codex) → the generic `runTier0Scan` runs. This is
+  identical to the pre-registry fallback where only langfuse/claude-code had a branch.
+
+Implementations should **lazily `import()`** their heavy scan module (as the
+pre-registry dispatch did) so registering the adapter set stays cheap and there is
+no eval-time import cycle with `tier0-scan.ts`.
+
+## How to add a NEW source
+
+1. **Extend the platform literal** in both:
+   - `scripts/normalize/trace.ts` → `SourcePlatform` union
+   - `scripts/config/schema.ts` → `SourcePlatformSchema`
+2. **Add the adapter id** to `SourceAdapterId` in `scripts/source/types.ts`.
+3. **Drop an adapter file** at `scripts/source/adapters/<platform>.ts`:
+   ```ts
+   import { SourceAdapterId } from "../types.ts";
+   import type { SourceAdapter } from "../types.ts";
+   export const myPlatformSourceAdapter: SourceAdapter = {
+     id: SourceAdapterId.MyPlatform,
+     label: "My Platform",
+     live: true,
+     // OPTIONAL — only if the platform warrants a bespoke Tier-0 scanner:
+     // async tier0Scan(traces, config) {
+     //   const mod = await import("../../tier0/my-platform.ts");
+     //   return mod.runMyPlatformTier0(traces, config);
+     // },
+   };
+   ```
+4. **Register it** — add one line to `registerBuiltinSourceAdapters()` in
+   `scripts/source/index.ts`. **No consumer switch to edit.**
+5. **(Read side)** add `references/source-platforms/<platform>.md` (CLI manual +
+   filters + credential setup) and, if you fetch+normalize rather than read a
+   UniTF handover, `scripts/normalize/platforms/<platform>.ts` — per
+   `adapter-strategy.md` Q1/Q6.
+6. **(Optional)** add `scripts/tier0/<platform>.ts` with a
+   `run<Platform>Tier0(traces, config)` scanner, wired via `tier0Scan` above.
+
+## Resolution semantics
+
+- `getSourceAdapter(id)` — **throws** a clear error (naming the registered set)
+  when the source is unknown. Use on the strict binding path.
+- `tryGetSourceAdapter(id)` — returns `undefined` (never throws). Used by
+  `tier0-scan.ts` so a mixed-platform / unregistered batch **falls back to the
+  generic scan** instead of throwing.
+- `ensureBuiltinSourceAdapters()` — registers the shipped set exactly once and
+  never clobbers a caller-registered custom/fake adapter (library-safe).

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/claude-code-transcripts.md

@@ -0,0 +1,66 @@
+# Claude Code Transcripts — Source Platform Reference
+
+> Claude Code stores all sessions as JSONL files at a known path.
+> No CLI needed — pure file reads.
+> Upstream docs: https://code.claude.com/docs/en/data-usage
+
+## Session path
+
+```
+~/.claude/projects/<encoded-project-path>/<session-id>.jsonl
+```
+
+- `<encoded-project-path>`: absolute project path encoded by Claude Code (path separators → hyphens, URL-encoded special chars)
+- `<session-id>`: UUID format
+- Default retention: `cleanupPeriodDays` setting (30 days by default)
+- Format: plaintext JSONL, one event per line
+
+## Discover sessions for this project
+
+```bash
+# List all session files for current project
+find ~/.claude/projects -name "*.jsonl" -newer /tmp/ref-date -ls
+
+# Find by project path (approximate — encoding varies)
+ls ~/.claude/projects/ | grep "$(pwd | sed 's|/|-|g')"
+```
+
+`scripts/self-diagnostics/probe.ts` handles the encoding automatically.
+
+## CLI install check
+
+No CLI required. Pure file reads via `Read` or `Bash(cat ...)`.
+
+> Official docs: https://code.claude.com/docs/en/data-usage
+>
+> The ensure-cli gate (PR-021 — `references/workflows/onboarding.md` Phase 2)
+> reports `status: not-required` for this source: there is nothing to install,
+> so onboarding links these docs and proceeds directly to file reads.
+
+## Filter/Search Support
+
+See `references/filter-search-matrix.md`. All filtering is file-level or content-grep:
+- by session ID: filename matches session UUID
+- by time: file `mtime`
+- has error: `grep '"isError":true'`
+- by skill: `grep '"toolName":"Skill"'`
+- full-text: grep over JSONL content
+
+## Normalization (moved upstream — UniTF flip)
+
+Claude Code session JSONL → UniTF normalization now lives in the `@mutagent/tools`
+claude-code adapter and runs UPSTREAM via `mutagent-cli trace fetch --platform
+claude-code --export <traces.jsonl>` (one session `.jsonl`, many event lines → one
+UnifiedTrace). The skill READS the resulting UniTF via the single reader:
+
+```bash
+bun scripts/cli/run.sh scripts/normalize/read-unitf.ts \
+  --in <traces.jsonl> --manifest <manifest.json> \
+  --out-metadata /tmp/traces-metadata.json --out-entity /tmp/entity-context.json
+```
+
+Reader: `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`). The
+report-only **self-diagnosis** skill entity is a separate path — built by
+`buildSkillSelfEntityContext` in `scripts/normalize/platforms/entity-context.ts`
+(kept) from the skill's own SKILL.md + session, NOT from a platform export.
+Run `mutagent-cli trace --help` for the fetch surface.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/codex-transcripts.md

@@ -0,0 +1,78 @@
+# Codex Transcripts — Source Platform Reference
+
+> Codex CLI session path CONFIRMED iter-8.
+> Source: codex-rs/rollout/src/lib.rs constants.
+> Upstream docs: https://developers.openai.com/codex/cli · https://github.com/openai/codex
+
+## Session paths (confirmed iter-8)
+
+```
+Active sessions:   ~/.codex/sessions/<session>.jsonl
+Archived sessions: ~/.codex/archived_sessions/<session>.jsonl
+Config:            ~/.codex/config.toml
+
+Constants (codex-rs/rollout/src/lib.rs):
+  SESSIONS_SUBDIR = "sessions"
+  ARCHIVED_SESSIONS_SUBDIR = "archived_sessions"
+```
+
+- Default: session recording is ON
+- Suppress: `codex exec --ephemeral`
+- Config: `~/.codex/config.toml`
+
+## Discover sessions
+
+```bash
+# List all active sessions
+ls ~/.codex/sessions/
+
+# Most recent session
+ls -lt ~/.codex/sessions/ | head -5
+
+# Find by approximate date (file mtime)
+find ~/.codex/sessions -newer /tmp/ref-date -name "*.jsonl"
+```
+
+## CLI install check
+
+> Official Codex CLI docs: https://developers.openai.com/codex/cli
+>
+> Reading Codex transcripts needs **no CLI** (they are local JSONL files under
+> `~/.codex/sessions/`) — the `codex` CLI only PRODUCES them. During onboarding the
+> ensure-cli gate (PR-021 — `references/workflows/onboarding.md` Phase 2) probes for
+> the `codex` binary; if missing it shows the docs link + the install command below
+> and **asks for explicit approval before installing** (never auto-installs). On
+> decline, the skill still reads any existing session files directly.
+
+Codex CLI install:
+```bash
+which codex
+# Install: npm install -g @openai/codex
+# or: curl https://install.codex.openai.com | sh
+```
+
+## Filter/Search Support
+
+See `references/filter-search-matrix.md`. Pure file reads:
+- by session ID: filename = session UUID
+- by time: file `mtime`
+- has error: `grep '"error":'`
+- by skill: `grep '"skill":'`
+- by agent type: `grep '"agent_type":'`
+- full-text: grep over JSONL content
+
+## Normalization (moved upstream — UniTF flip)
+
+Codex rollout session JSONL → UniTF normalization now lives in the `@mutagent/tools`
+codex adapter and runs UPSTREAM via `mutagent-cli trace fetch --platform codex
+--export <traces.jsonl>` (one rollout session `.jsonl`, many lines → one
+UnifiedTrace). The skill READS the resulting UniTF via the single reader:
+
+```bash
+bun scripts/cli/run.sh scripts/normalize/read-unitf.ts \
+  --in <traces.jsonl> --manifest <manifest.json> \
+  --out-metadata /tmp/traces-metadata.json --out-entity /tmp/entity-context.json
+```
+
+Reader: `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`). Run
+`mutagent-cli trace --help` for the fetch surface.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/codex.md

@@ -0,0 +1,145 @@
+# Codex — Skill + Agent Install Format Reference
+
+> This file covers **skill binding and agent install format** for the Codex platform.
+> For transcript/session fetch (session paths, normalization), see
+> `references/source-platforms/codex-transcripts.md`.
+
+## Status
+
+| Topic | Status |
+|---|---|
+| Session paths | **Confirmed** (iter-8) — see `codex-transcripts.md` |
+| Skill install format | **Best-effort** — OQ-3 docs lookup pending; verify before publishing |
+| Agent install format (TOML) | **Best-effort** — per dashboard line 625 + OQ-3 |
+
+> ⚠️ Verify skill + agent paths against Codex docs before publishing. These are best-effort
+> based on the confirmed `~/.codex/` home dir and general agent platform conventions.
+
+## Skill install path
+
+```
+~/.codex/skills/mutagent-diagnostics/
+```
+
+Codex uses `~/.codex/` as its home directory (confirmed from `config.toml` path in
+`codex-rs/rollout/src/lib.rs`). Skill binding: copy the full skill directory to
+`~/.codex/skills/<skill-name>/`.
+
+```bash
+# Install skill to Codex
+cp -r /path/to/mutagent-diagnostics ~/.codex/skills/mutagent-diagnostics
+```
+
+## Agent install path
+
+```
+~/.codex/agents/
+```
+
+Agent files are stored as `.toml` files (not Markdown) in `~/.codex/agents/`.
+
+```bash
+# Install an agent (after MD→TOML transcode)
+bun scripts/cli/run.sh scripts/cli/install-agents.ts \
+  --transcode-only --to codex \
+  assets/agents/diagnostics-analyzer.md \
+  ~/.codex/agents/diagnostics-analyzer.toml
+```
+
+## Agent format: MD → TOML transcode
+
+Codex uses **TOML** for agent configuration. Claude Code `.md` agent files must be transcoded
+to TOML format via `scripts/cli/install-agents.ts --transcode-only --to codex`.
+
+### Input (`.md` / Claude Code format)
+
+```markdown
+---
+name: diagnostics-analyzer
+description: Parallel analyzer agent for mutagent-diagnostics
+tools: Bash, Read, Write, SendMessage
+---
+
+Agent body content here.
+```
+
+### Output (`.toml` / Codex format)
+
+```toml
+[agent]
+name = "diagnostics-analyzer"
+description = "Parallel analyzer agent for mutagent-diagnostics"
+tools = ["Bash", "Read", "Write"]
+
+[agent.body]
+content = """
+Agent body content here.
+"""
+```
+
+### TOML key mapping
+
+| Markdown frontmatter key | TOML key | Type | Notes |
+|---|---|---|---|
+| `name:` | `[agent] name` | string | Required |
+| `description:` | `[agent] description` | string | Required |
+| `tools:` | `[agent] tools` | array | Comma-separated → TOML string array |
+| Other frontmatter keys | `[agent] <key>` | string | Passed through verbatim |
+| Body (after `---`) | `[agent.body] content` | multi-line string | Trimmed |
+
+### Transcode CLI
+
+```bash
+bun scripts/cli/run.sh scripts/cli/install-agents.ts \
+  --transcode-only --to codex <input.md> <output.toml>
+```
+
+`--transcode-only` skips symlink/copy logic and only writes the transcoded file.
+`--to codex` selects the TOML output format.
+
+> ⚠️ Verify TOML key names (`[agent]`, `[agent.body]`) against Codex docs before publishing.
+> agentskills.io format compatibility is assumed per operator OQ-3 answer — lookup pending.
+
+## Config reference
+
+```
+~/.codex/config.toml          # Codex config (confirmed — codex-rs source)
+~/.codex/sessions/            # Active sessions (confirmed — codex-rs source)
+~/.codex/archived_sessions/   # Archived sessions (confirmed — codex-rs source)
+~/.codex/skills/              # Skill install directory (best-effort)
+~/.codex/agents/              # Agent install directory (best-effort)
+```
+
+## Activation
+
+Codex agents are activated by agent name from within a Codex session:
+- Sub-agent dispatch: invoke the agent by its `name` field
+- No slash-command equivalent (Codex uses TOML `name` as the identifier)
+
+## CLI install check
+
+> Official Codex CLI docs: https://developers.openai.com/codex/cli
+>
+> When Codex is the **source** platform, onboarding's ensure-cli gate (PR-021 —
+> `references/workflows/onboarding.md` Phase 2) probes for the `codex` binary and,
+> if missing, shows these docs + the install command below and **asks for explicit
+> approval before installing** (never auto-installs). See also
+> `references/source-platforms/codex-transcripts.md`.
+
+```bash
+which codex
+# Install: npm install -g @openai/codex
+# or: curl https://install.codex.openai.com | sh
+```
+
+## Upstream docs
+
+- https://developers.openai.com/codex/cli
+- https://github.com/openai/codex
+
+## Cross-references
+
+- `references/source-platforms/codex-transcripts.md` — session transcript paths + fetch
+- `references/source-platforms/install-paths.md` — install path table (all platforms)
+- `references/oq-answers.md` OQ-3 — operator answer + lookup-pending status
+- `scripts/cli/install-agents.ts` — transcode CLI implementation