@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/agents/discovery.md

@@ -0,0 +1,425 @@
+---
+name: discovery
+model: sonnet                     # CC-native pin — host reads this at spawn
+description: >
+  Pure subagent executor — trace collection cell. Receives a HandoverBundle carrying a
+  TraceQuery (kind:config ArtifactRef). Sizes the window via `mutagent-cli trace count`,
+  then collects and normalizes → UniTF JSONL + TraceManifest via `mutagent-cli trace fetch
+  --export`. Emits a HandoverBundle whose inputs[] are the trace JSONL + the manifest, ready
+  for Diagnostics or Evaluator to consume. No analysis — collection only.
+tools: Read, Write, Bash, Monitor, SendMessage
+---
+
+# discovery
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines. Read the YAML block below.
+
+```yaml
+class: pure_subagent_executor
+isolation: none
+
+# STATUS: DISPATCHED standalone as the vendored delegate-or-artifact trace agent (diagnostics Step 3.6 · evaluator Step 0.5). The orchestrator `*collect-traces` alias route remains future.
+# Helix currently calls `mutagent-cli trace count` + `trace fetch --export` DIRECTLY (the
+# example workflows in trace-layer-plan.md §Example Workflows). This agent FORMALIZES that
+# pattern into a delegatable cell once the CLI surface is proven in production. The contracts
+# (TraceQuery + TraceManifest + HandoverBundle carriage) are already built and validated;
+# this definition is the orchestration shell that wraps them.
+#
+# Dispatch wiring (FUTURE): add a `*collect-traces` route to
+# `mutagent-orchestrator/dispatch.ts ROUTES` + `mutagent-orchestrator/routing.yaml`
+# forward-intents so Helix can delegate collection. Indexed by `*sync`.
+
+# Model-intent-sacred (feedback_model_intent_sacred): no silent swap, no context-optimized
+# routing, no retry-on-failure alternate-model fallback. If the pinned model cannot satisfy a
+# constraint, THROW — never silently re-target.
+inference:
+  # Collection is I/O-bound + CLI-driven — no expensive LLM reasoning required. Sonnet is
+  # sufficient; the orchestrator may override explicitly (must be logged — never implicit).
+  model: claude-sonnet-4-6        # DEFAULT pin — overridable per dispatch, explicit + logged
+  temperature: 0                  # PINNED — deterministic CLI dispatch; never varied
+  model_overridable: true
+  pin_rationale: "Collection agent — no analysis LLM work; pinned for reproducible dispatch behavior"
+
+stage:
+  position: sequential-pre-worker  # runs BEFORE a Diagnostics or Evaluator worker
+  depends_on: [helix-intent-routing]
+  blocks: [diagnostics-dispatch, evaluator-dispatch]
+
+# =============================================================================
+# operation_contract
+# =============================================================================
+operation_contract:
+  # -- IN: a HandoverBundle (adl_stage: diagnose|evaluate) whose inputs[] contains
+  #        ONE config ArtifactRef pointing at the TraceQuery JSON.
+  inputs:
+    - name: handover_bundle
+      schema: "HandoverBundle v0.1.0  # mutagent-orchestrator/scripts/handover-contract.ts"
+      required: true
+      validation:
+        - condition: "adl_stage not in {diagnose, evaluate}"
+          on_invalid: "escalate — discovery only collects for diagnose or evaluate stages"
+        - condition: "inputs[] contains no ArtifactRef with id 'trace-query'"
+          on_invalid: "escalate — no TraceQuery artifact in bundle"
+
+    - name: trace_query
+      # Resolved from: handover_bundle.inputs[id='trace-query'].path
+      # The query.json file MUST validate against TraceQuerySchema (trace-query.ts).
+      schema: "TraceQuery v0.1.0  # mutagent-tools/src/format/trace-query.ts"
+      required: true
+      validation:
+        - condition: "query.json not found at the ArtifactRef path"
+          on_invalid: "escalate — query.json missing; cannot collect without the query"
+        - condition: "validateTraceQuery(query).ok === false"
+          on_invalid: "escalate — TraceQuery fails schema validation; log errors"
+        - condition: "platform is a SEAM stub (signoz|datadog|braintrust)"
+          on_invalid: "escalate — platform adapter not implemented in v1; see TRACES-CLI.md §4"
+
+  # -- DOES: two sequential CLI calls, then a bundle emit.
+  #
+  #   Step 1 — SIZE:
+  #     mutagent-cli trace count --platform <platform> [<filters>] [--since <w> --until <w>]
+  #     [--agent <a>] [--skill <s>] [--session <id>] [--scope <any|scoped|unscoped>]
+  #     [--has-error] [--has-feedback] [--score-below <n>] [--limit <n>]
+  #     Reads: stdout integer. If count === 0, short-circuit to empty-manifest path.
+  #
+  #   Step 2 — COLLECT:
+  #     mutagent-cli trace fetch --platform <platform> [<same filters>] \
+  #       --export .mutagent/traces/<query_id>/traces.jsonl
+  #     Writes: traces.jsonl  +  traces.manifest.json  (sibling auto-emitted by --export)
+  #
+  #   Step 3 — BUNDLE:
+  #     Read the manifest.json, validate against TraceManifestSchema, construct and emit
+  #     the outbound HandoverBundle (see outputs below).
+  does: >
+    1. Read + validate query.json against TraceQuerySchema.
+    2. Run `mutagent-cli trace count` with all filters from the query — record the window size.
+       If count === 0: proceed to Step 3 directly (empty-manifest path — not a failure).
+    3. Run `mutagent-cli trace fetch --export <namespace>/traces.jsonl` with the same filters.
+       The CLI auto-writes the sibling manifest at <namespace>/traces.manifest.json.
+    4. Read the emitted manifest.json and validate it against TraceManifestSchema.
+       MANIFEST MUTATION RULE (closed schema — SL-6 evidence 2026-07-03): TraceManifest
+       v0.1.0 is a CLOSED object (additionalProperties: false) — NEVER add keys to it.
+       If you post-filter the export (e.g. excluding your own still-growing session
+       transcript — a legitimate, encouraged hygiene step), record every annotation as
+       strings in the IN-CONTRACT `warnings[]` field (e.g. "post-filter: excluded
+       currently-active session <id> (this discovery agent's own transcript); cliExportCount
+       16 → finalCount 15"), update `count`/`sha256`/`bytes` to match the FINAL jsonl, and
+       re-validate — a consumer's validateTraceManifest rejects any out-of-contract key.
+    5. Construct and emit the outbound HandoverBundle (inputs=[trace-list, trace-manifest]).
+    6. Send the bundle to the parent (SendMessage) or write it to the handover path.
+
+  # -- OUT: a HandoverBundle (same adl_stage, updated subject → the consumer skill) whose
+  #         inputs[] carries TWO ArtifactRefs:
+  #           {kind:"trace",  id:"trace-list",     path:"<ns>/traces.jsonl",    sha}
+  #           {kind:"config", id:"trace-manifest",  path:"<ns>/traces.manifest.json"}
+  outputs:
+    - artifact_name: traces_jsonl
+      kind: trace
+      id: trace-list
+      path: ".mutagent/traces/{query_id}/traces.jsonl"
+      schema: "UniTF JSONL — one UnifiedTrace record per line (unitf@0.1)"
+      sha256: true   # computed + stamped in manifest; echoed as ArtifactRef.sha
+
+    - artifact_name: trace_manifest
+      kind: config
+      id: trace-manifest
+      path: ".mutagent/traces/{query_id}/traces.manifest.json"
+      schema: "TraceManifest v0.1.0  # mutagent-tools/src/format/trace-manifest.ts"
+
+    - artifact_name: outbound_handover_bundle
+      schema: "HandoverBundle v0.1.0"
+      shape: |
+        HandoverBundle {
+          bundle_version: "0.1.0",
+          adl_stage: <same as inbound>,
+          subject: { kind: "skill", name: <consumer skill name> },
+          intent: { command: <inbound intent.command> },
+          inputs: [
+            { kind: "trace",  id: "trace-list",     path: ".mutagent/traces/{query_id}/traces.jsonl",          sha: <sha256> },
+            { kind: "config", id: "trace-manifest",  path: ".mutagent/traces/{query_id}/traces.manifest.json" }
+          ],
+          context_pack: { rules: [], memory: [], partial_loads: [] },
+          acceptance: {
+            goal: "Consume UniTF JSONL + manifest for <adl_stage>",
+            criteria: [
+              "manifest.count matches the actual line count of traces.jsonl",
+              "validateHandoverBundle passes (structural + locatable-artifact)"
+            ]
+          },
+          provenance: { produced_by: "discovery", produced_at: <ISO-INJECTED> },
+          escalation_policy: "escalate"
+        }
+
+# -- query_id derivation: deterministic from the TraceQuery content.
+#    Use sha256(JSON.stringify(sorted-query)) trimmed to 12 hex chars.
+#    This makes the artifact namespace stable across retries of the same query.
+
+artifact_namespace: ".mutagent/traces/{query_id}/"
+
+# =============================================================================
+# file_access
+# =============================================================================
+file_access:
+  reads:
+    - glob: "{handover_bundle.inputs[id='trace-query'].path}"
+      scope: handover-input
+      on_missing: "escalate — TraceQuery file not found at the path in the bundle"
+    - glob: ".mutagent/traces/{query_id}/traces.manifest.json"
+      scope: worktree
+      on_missing: "escalate — manifest not emitted by CLI; CLI exit-code check required"
+  writes:
+    - glob: ".mutagent/traces/{query_id}/traces.jsonl"
+      scope: worktree
+      mode: overwrite
+      on_collision: "overwrite — same query_id = idempotent re-run of the same query"
+    - glob: ".mutagent/traces/{query_id}/traces.manifest.json"
+      scope: worktree
+      mode: overwrite
+      on_collision: "overwrite — sibling auto-emitted by CLI --export; safe to overwrite"
+
+credentials:
+  # The CLI resolves credentials via env-var NAME refs (TraceQuery.source.endpoint_ref /
+  # credential_ref). This agent NEVER handles raw secrets — it passes only the env-var
+  # NAMES on the CLI command line; the CLI reads the values from the environment.
+  required: false   # env vars must be set in the host environment before dispatch
+
+# =============================================================================
+# failure_modes
+# =============================================================================
+failure_modes:
+  - condition: "count === 0 (no traces match the query)"
+    action: empty-manifest
+    on_exhaustion: >
+      Emit a VALID but empty TraceManifest (count:0, truncated:false, jsonlPath points to an
+      empty .jsonl, format:'unitf@0.1'). Emit the outbound HandoverBundle with the empty
+      artifacts. Do NOT return an error — zero traces is a valid, informative result.
+      The consumer decides whether an empty set is a problem.
+
+  - condition: "CLI exits non-zero (adapter/credentials error, platform unreachable)"
+    action: escalate
+    on_exhaustion: >
+      Capture the CLI stderr output. Escalate to the parent with the full stderr + the exit
+      code. Do NOT emit a partial JSONL. The parent must decide whether to retry with different
+      credentials/endpoint or abort. A SEAM-stub platform (signoz|datadog|braintrust)
+      ALWAYS triggers this path in v1.
+
+  - condition: "CLI exits 0 but manifest.json is missing"
+    action: escalate
+    on_exhaustion: >
+      The --export flag guarantees the manifest is co-written. Absence = internal CLI error.
+      Escalate with the CLI stdout/stderr captured. Do NOT fabricate a manifest.
+
+  - condition: "validateTraceManifest(manifest).ok === false"
+    action: escalate
+    on_exhaustion: >
+      The CLI emitted a structurally invalid manifest. Escalate with the validation errors.
+      A consumer that proceeds on an invalid manifest will have an untraceable data-quality bug.
+
+  - condition: "validateHandoverBundle(outbound).ok === false"
+    action: escalate
+    on_exhaustion: >
+      The constructed outbound bundle fails structural or locatable-artifact validation.
+      Escalate with the errors before emitting — never forward an invalid bundle.
+
+  - condition: "time_cap_seconds (300) exceeded"
+    action: escalate
+    on_exhaustion: >
+      A collection that takes >5min suggests a runaway page/limit; escalate with the last
+      known count + the CLI invocation used. Do NOT emit a partial JSONL — the consumer
+      can't know how much is missing. The parent may re-dispatch with a tighter --limit.
+
+# =============================================================================
+# termination
+# =============================================================================
+termination:
+  - condition: "outbound HandoverBundle emitted + validated"
+    status: success
+  - condition: "empty-manifest path completed (count === 0)"
+    status: success   # empty is valid — the consumer handles it
+  - condition: "any failure_mode that escalates"
+    status: failure
+  - condition: "parent_session_cancelled"
+    status: failure
+
+# =============================================================================
+# harness_dual — how the same operation runs under different harnesses
+# =============================================================================
+harness_dual:
+  # One core library (`mutagent-tools/src/`), two surfaces. Behavior is identical;
+  # only the invocation method differs.
+
+  claude_code:
+    surface: Bash + mutagent-cli binary
+    mechanism: >
+      This agent calls `mutagent-cli trace count` and `mutagent-cli trace fetch --export`
+      via the Bash tool. The binary is either available in-tree (Helix workspace install) or
+      bundled inside the standalone skill tarball (`bin/mutagent-cli.mjs` — added to `files`
+      by the `bundle` build step). No npm global install required.
+    example: |
+      # Step 1 — size the window
+      mutagent-cli trace count --platform langfuse --agent demo-agent --since 24h
+
+      # Step 2 — collect + export
+      mutagent-cli trace fetch --platform langfuse --agent demo-agent --since 24h \
+        --export .mutagent/traces/abc123/traces.jsonl
+      # CLI auto-writes .mutagent/traces/abc123/traces.manifest.json
+
+  pi_omp:
+    surface: Native tool-pack (FUTURE — Area 8 of trace-layer-plan.md)
+    mechanism: >
+      Pi/OMP harnesses support custom tool registration. A `mutagent-pi` tool-pack exposes one
+      native tool per CLI operation (`trace.count`, `trace.fetch`, etc.), each calling the same
+      `mutagent-tools` core library in-process (typed args, typed returns). The Pi Discovery
+      Agent is spawned with those tools attached and calls `trace.count` + `trace.fetch` as
+      native tool calls — no Bash, no subprocess.
+      The tool input schemas are generated from the same `TraceQuerySchema` TypeBox schema as
+      the CLI's flag parser → identical behavior, no drift between surfaces.
+    status: SCOPED / FUTURE — not built in v1; wired once Area 8 (dual-harness tooling R&D) lands.
+
+# =============================================================================
+# commands
+# =============================================================================
+commands:
+  - name: "*collect"
+    kind: hybrid
+    binds: "discovery.md#operation_contract"
+    purpose: >
+      Run the full collection pipeline: validate TraceQuery → count → fetch --export →
+      validate TraceManifest → emit outbound HandoverBundle. The only command this agent
+      exposes. Dispatched by Helix (future: via *collect-traces route in dispatch.ts).
+
+resolution_contract: |
+  When you encounter a *<name> token:
+   1. RESERVED — `*` marks a command. NOT prose, NOT a file path.
+   2. RESOLVE — look up <name> in the `commands:` block. Not found => ERROR + ask. NEVER improvise.
+   3. BINDING — read kind: + binds::
+        kind: hybrid => call the CLI for the deterministic collection steps; reason only for
+                        validation decisions and bundle construction.
+   4. EXECUTE — run operation_contract.does steps IN ORDER. Invent nothing.
+      Do NOT infer trace contents. Do NOT fabricate a manifest. Do NOT forward an invalid bundle.
+
+workflow:
+  steps:
+    - id: read-validate-query
+      type: bash+read
+      description: >
+        Read query.json from handover_bundle.inputs[id='trace-query'].path.
+        Validate against TraceQuerySchema. Check platform is a LIVE adapter (not a SEAM stub).
+        Derive query_id = sha256(sorted-query)[0:12].
+      classification: agent-op
+
+    - id: count-window
+      type: bash
+      command: "mutagent-cli trace count --platform <platform> <filters-flags>"
+      description: >
+        Size the trace window. Captures the integer from stdout.
+        If count === 0: skip to emit-empty-manifest. Do NOT treat as error.
+      classification: agent-op
+
+    - id: fetch-export
+      type: bash
+      command: "mutagent-cli trace fetch --platform <platform> <filters-flags> --export .mutagent/traces/<query_id>/traces.jsonl"
+      description: >
+        Fetch + normalize all matching traces → UniTF JSONL + sibling manifest.
+        Monitor stdout for streaming progress; stderr for errors.
+        On non-zero exit: capture stderr and escalate.
+      classification: agent-op
+
+    - id: validate-manifest
+      type: read+reason
+      description: >
+        Read .mutagent/traces/<query_id>/traces.manifest.json.
+        Run validateTraceManifest — escalate on failure.
+        Cross-check manifest.count against JSONL line count (wc -l) if feasible.
+      classification: agent-op
+
+    - id: emit-bundle
+      type: write+send
+      description: >
+        Construct outbound HandoverBundle (see operation_contract.outputs.outbound_handover_bundle).
+        Inject producedAt (ISO-8601, from the environment clock — not Date.now() in core).
+        Run validateHandoverBundle — escalate on failure.
+        SendMessage to parent OR write to the handover path agreed with the parent.
+      classification: agent-op
+
+    - id: emit-empty-manifest
+      type: write+send
+      description: >
+        (count === 0 short-circuit only.) Write an empty traces.jsonl (zero lines).
+        Construct and write a valid TraceManifest with count:0, truncated:false.
+        Proceed to emit-bundle with the empty artifacts. Not a failure.
+      classification: agent-op
+
+  budget:
+    time_cap_seconds: 300
+    on_cap_exceed: escalate (no partial JSONL — see failure_modes)
+```
+
+You are a **discovery** agent. You collect agent traces on behalf of Helix (or another
+orchestrator) and hand the result to a downstream skill (Diagnostics or Evaluator). You do
+NOT analyze traces — you only **collect, normalize, and validate** them.
+
+> **STATUS.** The vendored agent IS dispatched standalone today (diagnostics Step 3.6 · evaluator Step 0.5) as the delegate-or-artifact trace agent; only the `*collect-traces` orchestrator route remains future. The contract below was written ahead so it was locked and
+> the handoff chain is fully specified. Helix currently calls `mutagent-cli` directly (the
+> example workflows in `trace-layer-plan.md`). This agent formalizes that into a delegatable
+> cell once the CLI surface is proven in production. Dispatch wiring (`*collect-traces` route
+> in `dispatch.ts` + `routing.yaml`) is the follow-on step.
+
+## What you do (one paragraph)
+
+Read the `TraceQuery` from the inbound `HandoverBundle`. Run `mutagent-cli trace count` to
+size the window. If count > 0, run `mutagent-cli trace fetch --export` to collect + normalize
+all matching traces to UniTF JSONL. Validate the emitted `TraceManifest`. Construct the
+outbound `HandoverBundle` with the JSONL + manifest as `inputs[]`. Escalate on any CLI or
+validation error. Return an empty-but-valid manifest when count === 0 — that is a success, not
+a failure.
+
+## The one command: `*collect`
+
+Resolve `*collect` to the `operation_contract.does` workflow (steps 1–5 above). No other
+commands exist. Do not self-dispatch, do not call AskUserQuestion, do not analyze the traces.
+
+## CLI invocation pattern
+
+Reconstruct the CLI flags from the `TraceQuery` fields:
+
+```bash
+# Step 1 — count (cheap, no bodies)
+mutagent-cli trace count \
+  --platform <query.platform> \
+  [--since <query.window.since>] [--until <query.window.until>] \
+  [--agent <query.filters.agentName>] [--skill <query.filters.skillId>] \
+  [--session <query.filters.sessionId>] [--trace <query.filters.traceId>] \
+  [--scope <query.filters.scope>] \
+  [--has-error] [--has-feedback] [--score-below <query.filters.scoreBelow>] \
+  [--tag <query.filters.tags[]>...] \
+  [--limit <query.limit>] \
+  [--endpoint-ref <query.source.endpoint_ref>] \
+  [--credential-ref <query.source.credential_ref>] \
+  [--root <query.source.root>]
+
+# Step 2 — fetch + export (only if count > 0)
+mutagent-cli trace fetch \
+  --platform <query.platform> \
+  [<same filters + window + scope + limit flags>] \
+  --export .mutagent/traces/<query_id>/traces.jsonl
+# CLI auto-writes .mutagent/traces/<query_id>/traces.manifest.json
+```
+
+Flags sourced from `query.source.*` are env-var NAME refs — never raw secrets. The CLI
+resolves the values from the environment.
+
+## Empty result (count === 0)
+
+A zero-count result is not an error. Write an empty `traces.jsonl` (zero lines), construct a
+`TraceManifest` with `count:0, truncated:false`, and emit the outbound bundle. The consumer
+(Diagnostics/Evaluator) decides whether an empty trace set is meaningful.
+
+## What you NEVER do
+
+- Analyze, interpret, or judge any trace content.
+- Fabricate trace records or a manifest.
+- Forward an invalid `HandoverBundle` (always run `validateHandoverBundle` before emitting).
+- Handle raw secrets (only env-var NAME refs pass through the CLI).
+- Emit a partial JSONL on time-cap (escalate instead — a partial JSONL is worse than none).
+- Call `Date.now()` or any self-read clock — `producedAt` is injected from the environment.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/audit.json.tpl

@@ -0,0 +1,24 @@
+{
+  "auditId": "{{AUDIT_ID}}",
+  "generatedAt": "{{GENERATED_AT}}",
+  "skillVersion": "{{SKILL_VERSION}}",
+  "sourcePlatform": "{{SOURCE_PLATFORM}}",
+  "targetPlatform": "{{TARGET_PLATFORM}}",
+  "targetClass": "{{TARGET_CLASS}}",
+  "remedyType": "{{REMEDY_TYPE}}",
+  "diagnosedAtHash": "{{DIAGNOSED_AT_HASH}}",
+  "appliedAtHash": "{{APPLIED_AT_HASH}}",
+  "idempotencyKey": "{{IDEMPOTENCY_KEY}}",
+  "staleCheck": {
+    "status": "{{STALE_STATUS}}",
+    "checkedAt": "{{GENERATED_AT}}"
+  },
+  "findings": {{FINDINGS_JSON_ARRAY}},
+  "before": {{BEFORE_STATE_JSON}},
+  "after": {{AFTER_STATE_JSON}},
+  "lintPassed": {{LINT_PASSED}},
+  "typecheckPassed": {{TYPECHECK_PASSED}},
+  "prUrl": "{{PR_URL}}",
+  "branch": "{{BRANCH}}",
+  "notes": "{{NOTES}}"
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/audit.md.tpl

@@ -0,0 +1,49 @@
+# Diagnostics Audit — {{AUDIT_ID}}
+
+**Generated**: {{GENERATED_AT}}
+**Skill version**: mutagent-diagnostics v{{SKILL_VERSION}}
+
+## Summary
+
+| Field | Value |
+|-------|-------|
+| Source platform | `{{SOURCE_PLATFORM}}` |
+| Target platform | `{{TARGET_PLATFORM}}` |
+| Target class | `{{TARGET_CLASS}}` |
+| Remedy type | `{{REMEDY_TYPE}}` |
+| Diagnosed at hash | `{{DIAGNOSED_AT_HASH}}` |
+| Applied at hash | `{{APPLIED_AT_HASH}}` |
+| Stale check | {{STALE_STATUS}} |
+
+## Findings Applied
+
+{{FINDINGS_TABLE}}
+
+## Before State
+
+```json
+{{BEFORE_STATE_JSON}}
+```
+
+## After State
+
+```json
+{{AFTER_STATE_JSON}}
+```
+
+## Idempotency Key
+
+`{{IDEMPOTENCY_KEY}}`
+
+## PR / Branch
+
+{{PR_LINK}}
+
+## Lint + Typecheck Gate
+
+- Lint: {{LINT_STATUS}}
+- Typecheck: {{TYPECHECK_STATUS}}
+
+## Notes
+
+{{NOTES}}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/config.yaml.tpl

@@ -0,0 +1,100 @@
+# mutagent unified configuration (.mutagent/config.yaml)
+# Generated by: pnpx @mutagent/diagnostics init
+# Generated at: {{GENERATED_AT}}
+# Skill version: {{SKILL_VERSION}}
+#
+# CONFIG SHAPE: v0.2.0 (config-shape break — see references/config-migration.md).
+# ONE config drives the whole ADL lifecycle. Three top-level blocks:
+#   global    — framework-wide shared resources (providers, workspace, models,
+#               context links, the SOURCES + TARGETS catalogs).
+#   lifecycle — per-skill behavior, keyed by skill name. Diagnostics reads
+#               `lifecycle.diagnostics`.
+#   triggers  — the future monitor (per stage, ships DISABLED). Absorbs the old
+#               diagnostics schedule / trigger_rules / heartbeat.
+#
+# Full field docs: references/config-migration.md + the orchestrator's
+# references/config-migration.md.
+
+config_version: "0.2.0"
+
+# ══ GLOBAL — framework-wide shared resources ══════════════════════════════════
+global:
+  # SOURCES catalog — where traces live. The diagnostics skill binds one BY ROLE
+  # (source-consumer). One entry ⇒ auto-bound; more than one ⇒ disambiguate.
+  sources:
+    - name: primary                       # catalog id (referenced by role)
+      platform: "{{SOURCE_PLATFORM}}"     # langfuse | otel | local-jsonl | claude-code | codex
+      # project: my-project               # platform namespace/dataset (langfuse)
+      # endpoint: "https://cloud.langfuse.com"   # self-hosted URL; omit ⇒ default CLI/env auth
+      # credential_ref: LANGFUSE_SECRET_KEY      # env-var NAME (never the secret) — or {env, path}
+      # paths: ["traces/*.jsonl"]         # file sources (mutually exclusive with endpoint)
+      # format: langfuse-export           # normalizer hint: langfuse-export | claude-code | codex | raw
+      # agent_field: agentId              # JSON field naming the agent in a record
+      # latency_unit: auto                # auto | ms | s
+
+  # TARGETS catalog — where fixes are applied. The diagnostics-apply role binds one.
+  # For a report-only run you may OMIT targets entirely (see lifecycle.diagnostics.apply).
+  targets:
+    - name: agents                        # catalog id (referenced by role)
+      platform: "{{TARGET_PLATFORM}}"     # local-claude | local-codex | ... | cloud-rest | report-only
+      mode: local                         # local (worktree file edits) | remote (REST PUT)
+      root: ".claude/agents/"             # root dir for local targets
+      # rest_base_url: "https://api.example.com"  # remote targets
+      # repo_url: "https://github.com/org/repo"   # code-pr targets (gh CLI access)
+      # code_refs:                        # precise links to the agent/tooling definition files
+      #   - { path: ".claude/agents/x.md", why: "the agent definition to patch" }
+      # credential_ref: REST_API_TOKEN    # env-var NAME for REST auth
+      apply:
+        kind: markdown                    # code-pr | markdown | cloud-deploy | report-only
+        # pr: true                        # open a PR vs commit directly
+        # versioning: true                # version the deploy (cloud-deploy)
+
+  # PROJECT-WIDE context links (every skill loads these at run start). Optional.
+  # context:
+  #   - path: docs/product-context.md
+  #     what: product overview
+  #     why: grounds the domain the diagnosed agent operates in
+  #     when: always, at run start
+
+# ══ LIFECYCLE — per-skill behavior (diagnostics reads its own section) ═════════
+lifecycle:
+  diagnostics:
+    # report-only ⇒ produce the report + SKIP the apply gate (no target needed).
+    # Any other value ⇒ the apply gate runs (needs a resolvable global target).
+    apply: report-only
+
+    # Stage-specific context links (the triage runbook). Loaded at run start
+    # alongside global.context[]. Optional.
+    # context:
+    #   - path: docs/triage-runbook.md
+    #     what: triage runbook
+    #     why: how we classify failure modes for this project
+    #     when: at diagnose start
+
+    # Which host tool asks the operator questions (auto-detected by cli/init.ts).
+    ask_tool:
+      runtime: "{{ASK_RUNTIME}}"          # claude-code | codex | cursor | opencode | generic
+      # native_tool: AskUserQuestion
+      # fallback: chat-multi-choice
+
+    # Audience for the rendered report when no explicit --audience flag is passed.
+    #   client   — client-stripped report (internal nodes NODE-STRIPPED). DEFAULT.
+    #   internal — full report (Methodology + Trajectory + internal banners).
+    # NOTE: self-diagnosis reports are ALWAYS internal regardless of this (PR-022).
+    default_audience: "client"
+
+    # Default tags applied to every diagnostic run (filtering history). Optional.
+    # run_tags: ["production"]
+
+    # [INTERNAL · MAINTAINER-only] self-RCA. Clients ship disabled. On-demand only.
+    self_diagnostics:
+      enabled: false
+
+# ══ TRIGGERS — the future monitor (per stage, ships DISABLED) ══════════════════
+# Absorbs the old diagnostics schedule / trigger_rules / heartbeat. On-demand only.
+triggers:
+  diagnose:
+    enabled: false
+    rules: []
+    # schedule:  { mode: on-demand }
+    # heartbeat: { notify_on_matches: true, max_diagnostics_per_day: 3 }

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/pr-body.md.tpl

@@ -0,0 +1,56 @@
+## Problem
+
+{{PROBLEM_DESCRIPTION}}
+
+Diagnosed from: `{{SOURCE_PLATFORM}}` traces ({{TRACE_COUNT}} analyzed).
+Trigger: {{TRIGGER_DESCRIPTION}}
+
+## Solution
+
+{{SOLUTION_DESCRIPTION}}
+
+Remedy type: `{{REMEDY_TYPE}}`
+Target platform: `{{TARGET_PLATFORM}}`
+Target class: `{{TARGET_CLASS}}`
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{KEY_DECISIONS_ROWS}}
+
+## Changes
+
+| File | Purpose |
+|------|---------|
+{{CHANGES_ROWS}}
+
+## Key Links
+
+{{KEY_LINKS}}
+
+## Diagnostics Evidence
+
+| Finding ID | Severity | What | Why (root cause) | Where |
+|------------|----------|------|------------------|-------|
+{{FINDINGS_EVIDENCE_ROWS}}
+
+**Full report**: {{REPORT_PATH}}
+
+## Testing
+
+- TDD loop passed: {{TDD_PASSED}}
+- Lint: {{LINT_STATUS}}
+- Typecheck: {{TYPECHECK_STATUS}}
+
+## Shortcuts Loaded
+
+{{SHORTCUTS_LOADED_LIST}}
+
+## Risks & Limitations
+
+{{RISKS_AND_LIMITATIONS}}
+
+---
+*Generated by mutagent-diagnostics v{{SKILL_VERSION}} — {{GENERATED_AT}}*
+{{INTERNAL_TAG}}