@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.6-config-review.md

@@ -0,0 +1,57 @@
+# WF-1.6 — Config Review + Write
+
+> Phase 6 of onboarding: review generated config and confirm write.
+> Prev: WF-1.5 | Next: WF-1.7 (or WF-1.8 on first run)
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 5 of 7 — Review Configuration                         │
+│                                                             │
+│  Here's what will be written to config.yaml:               │
+│                                                             │
+│  source:                                                    │
+│    platform: "langfuse"                                     │
+│    config: {}                                               │
+│                                                             │
+│  target:                                                    │
+│    platform: "local-claude"                                 │
+│    config: {}                                               │
+│                                                             │
+│  filters:                                                   │
+│    time_window:                                             │
+│      from: "7daysAgo"                                       │
+│      to: "now"                                              │
+│    limit: 100                                               │
+│                                                             │
+│  ask_tool:                                                  │
+│    runtime: "claude-code"                                   │
+│                                                             │
+│  schedule:                                                  │
+│    mode: "on-demand"                                        │
+│                                                             │
+│  self_diagnostics:                                          │
+│    enabled: false                                           │
+│                                                             │
+│  [1] Write config and continue                              │
+│  [2] Go back to change a setting                            │
+│  [3] Exit without saving                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## On Confirm
+
+1. Write `config.yaml` from template (using `assets/templates/config.yaml.tpl`)
+2. Run `scripts/config/validate.ts` on written file
+3. If validation fails → show error + offer fix
+4. If validation passes → advance to WF-1.7
+
+## Validation Display
+
+```
+  Writing config.yaml... ✓
+  Validating... ✓ Config is valid
+
+  [1] Continue to next step
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.7-filter-defaults.md

@@ -0,0 +1,52 @@
+# WF-1.7 — Filter Defaults + Scope
+
+> Phase 7 of onboarding: set default filter scope for diagnostics runs.
+> Prev: WF-1.6 | Next: WF-1.8
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 6 of 7 — Default Scope                                │
+│                                                             │
+│  How many traces should diagnostics analyze per run?        │
+│                                                             │
+│  [1] Last 7 days, up to 100 traces    (recommended)         │
+│  [2] Last 24 hours, up to 50 traces   (fast)                │
+│  [3] Last 30 days, up to 500 traces   (thorough)            │
+│  [4] Custom                                                 │
+│                                                             │
+│  Errors-only mode:                                          │
+│  [Y] Include errors only (faster, higher signal)            │
+│  [N] Include all traces                    (default)        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Custom Path
+
+```
+  Custom filter configuration:
+  
+  Time window from ("7daysAgo", "24h", ISO date): > 7daysAgo
+  Time window to ("now", ISO date):               > now
+  Max traces:                                     > 100
+  Filter to errors only? (y/n):                   > n
+  Filter by agent ID (leave empty for all):        > 
+```
+
+## On Confirm
+
+Updates `filters` section in `config.yaml`:
+```yaml
+filters:
+  time_window:
+    from: "7daysAgo"
+    to: "now"
+  has_error: null   # null = all
+  limit: 100
+```
+
+## Note on Score Filters
+
+Score-based filters are NOT set here — they require score-scale auto-discovery at runtime (iter-8). Thresholds are never hardcoded in config.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.8-first-run.md

@@ -0,0 +1,59 @@
+# WF-1.8 — First Run Prompt
+
+> Phase 8 of onboarding: offer to run diagnostics immediately after setup.
+> Prev: WF-1.7 (or WF-1.1 if setup already complete)
+
+## Display (After Fresh Setup)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 7 of 7 — Setup Complete                               │
+│                                                             │
+│  ✓ config.yaml written                                      │
+│  ✓ Connection validated                                     │
+│  ✓ .mutagent/diagnostics/ initialized                       │
+│                                                             │
+│  Run diagnostics now?                                       │
+│                                                             │
+│  [1] Yes, run diagnostics now                               │
+│  [2] No, I'll run it manually later                         │
+│                                                             │
+│  To run manually: say "run diagnostics" or "diagnose my     │
+│  agents" in your AI coding session, or:                     │
+│  pnpx @mutagent/diagnostics run                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Display (Already Set Up)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  mutagent-diagnostics — Ready                               │
+│                                                             │
+│  Config: ✓ valid                                            │
+│  Source: langfuse (connected)                               │
+│  Target: local-claude                                       │
+│                                                             │
+│  [1] Run diagnostics now                                    │
+│  [2] Reconfigure                                            │
+│  [3] Exit                                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## On "Run Now"
+
+→ Trigger diagnostics orchestrator (equivalent to `pnpx @mutagent/diagnostics run`)
+→ Jump to WF-2.1 (diagnostics entry point)
+
+## On "Run Later"
+
+```
+  To run diagnostics:
+  
+  • In your AI coding session: say "run diagnostics on my agents"
+  • From CLI: pnpx @mutagent/diagnostics run
+  
+  Config saved at: ./config.yaml
+  
+  Done!
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/examples/sample-findings.json

@@ -0,0 +1,92 @@
+{
+  "sessionId": "sample-session-001",
+  "diagnosedAt": "2026-05-28T12:00:00.000Z",
+  "sourcePlatform": "local-jsonl",
+  "targetPlatform": "local-claude",
+  "totalTraces": 12,
+  "findings": [
+    {
+      "findingId": "F-001",
+      "actionable": "Tool call to 'search' returns empty results 60% of the time — agent retries in a loop without a fallback",
+      "assumptions": [
+        "Tool timeout is the primary cause of empty results (hypothesis-pending-source: search.ts timeout config not yet read)",
+        "No existing retry-cap exists in the tool definition"
+      ],
+      "failureOrigin": {
+        "what": "loop",
+        "why": "tool-missing",
+        "where": "tool-definition",
+        "evidence": "session-abc123 → message[14]: tool_result empty string, repeated 4×",
+        "confidence": "high"
+      },
+      "whyChain": [
+        {
+          "why": "Agent repeatedly calls search tool",
+          "evidence": "Trace messages 10-18: tool_use 'search' 4× in 90s",
+          "isOrigin": false
+        },
+        {
+          "why": "Search tool returns empty body on API timeout",
+          "evidence": "Tool result content: '' on 4/6 calls in session-abc123",
+          "isOrigin": false
+        },
+        {
+          "why": "No fallback path defined when search returns empty — agent loops",
+          "evidence": "tool-definition: search.ts missing timeout guard + empty-result branch",
+          "isOrigin": true
+        }
+      ],
+      "remedies": [
+        {
+          "remedyId": "R-001-a",
+          "title": "Add empty-result guard + max-retry cap to search tool definition",
+          "applyTarget": "scripts/tools/search.ts",
+          "failureOrigin": {
+            "what": "loop",
+            "why": "tool-missing",
+            "where": "tool-definition",
+            "evidence": "tool-definition: search.ts:42",
+            "confidence": "high"
+          },
+          "diff": {
+            "before": "if (!result) { return searchTool(query); }",
+            "after": "if (!result || retries >= MAX_RETRIES) { return { found: false, fallback: true }; }"
+          },
+          "cost": "low",
+          "correctness": "high",
+          "rank": 1,
+          "targetClass": "local-code-construct"
+        },
+        {
+          "remedyId": "R-001-b",
+          "title": "Add system-prompt instruction: 'If search returns empty after 2 attempts, summarize what you know and halt'",
+          "failureOrigin": {
+            "what": "loop",
+            "why": "prompt-underspec",
+            "where": "system-prompt",
+            "evidence": "system-prompt: no loop-break instruction present",
+            "confidence": "medium"
+          },
+          "cost": "low",
+          "correctness": "medium",
+          "rank": 2,
+          "targetClass": "local-agent"
+        }
+      ],
+      "sourceTraceIds": ["session-abc123"],
+      "referenceIds": {
+        "traceId": "session-abc123",
+        "sessionId": "session-abc123",
+        "findingId": "F-001"
+      }
+    }
+  ],
+  "discoveredChecks": [
+    {
+      "checkId": "DC-001",
+      "name": "Retry-loop detector",
+      "description": "Detects consecutive identical tool calls without intervening reasoning",
+      "affectedTraceIds": ["session-abc123"]
+    }
+  ]
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/examples/sample-meta.json

@@ -0,0 +1,47 @@
+[
+  {
+    "traceId": "trace-meta-001",
+    "sessionId": "session-meta-001",
+    "hasError": false,
+    "hasFeedback": true,
+    "rawScore": 1.5,
+    "latencyMs": 3200,
+    "sourcePlatform": "local-jsonl",
+    "skillBehaviorDeviationCount": 2,
+    "agentId": "diagnostics-orchestrator",
+    "startTime": "2026-05-28T10:00:00.000Z",
+    "endTime": "2026-05-28T10:00:03.200Z",
+    "totalTokens": 8420,
+    "tags": ["self-diagnostics", "phase-3-c"]
+  },
+  {
+    "traceId": "trace-meta-002",
+    "sessionId": "session-meta-001",
+    "hasError": false,
+    "hasFeedback": false,
+    "rawScore": 4,
+    "latencyMs": 1100,
+    "sourcePlatform": "local-jsonl",
+    "skillBehaviorDeviationCount": 0,
+    "agentId": "diagnostics-analyzer",
+    "startTime": "2026-05-28T10:00:03.500Z",
+    "endTime": "2026-05-28T10:00:04.600Z",
+    "totalTokens": 3210,
+    "tags": ["self-diagnostics"]
+  },
+  {
+    "traceId": "trace-meta-003",
+    "sessionId": "session-meta-002",
+    "hasError": true,
+    "hasFeedback": false,
+    "sourcePlatform": "local-jsonl",
+    "skillBehaviorDeviationCount": 1,
+    "agentId": "diagnostics-orchestrator",
+    "startTime": "2026-05-28T11:00:00.000Z",
+    "endTime": "2026-05-28T11:00:02.100Z",
+    "totalTokens": 5640,
+    "apiErrors": [
+      { "retryAttempt": 1, "maxRetries": 3, "timestamp": "2026-05-28T11:00:01.000Z" }
+    ]
+  }
+]

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/adapter-strategy.md

@@ -0,0 +1,75 @@
+# Adapter Strategy — Q1-Q6 Locked Decisions
+
+> All Q1-Q6 → Option A. Locked iter-5. See decisions-log.md for operator verbatim answers.
+
+## Q1 — Per-platform reference docs
+
+**Decision**: Per-platform reference doc + ONE normalization script per source.
+
+Each source platform has:
+- `references/source-platforms/<name>.md` — CLI operation manual + filter examples + credential setup + hyperlinks
+- `scripts/normalize/platforms/<name>.ts` — Platform JSON → canonical TraceBody shape
+
+Custom platforms: drop a new reference doc + normalize.ts. The orchestrator discovers it from config.yaml `source.platform`.
+
+## Q2 — Normalization in script
+
+**Decision**: Normalization is deterministic mapping in a TypeScript script.
+
+The normalize scripts are Type A (pure, no LLM, no I/O). They receive raw platform JSON and emit canonical `TraceBody`. This makes normalization testable, reproducible, and cost-free.
+
+The agent NEVER interprets raw platform JSON directly — it always reads via the normalized shape.
+
+## Q3 — CLI install detection at onboarding
+
+**Decision**: CLI install detection at onboarding via `Bash(which <cli>)` + AskUserQuestion install prompt if missing.
+
+Trigger: operator picks a source/target platform during onboarding. Agent immediately checks:
+```bash
+Bash("which langfuse") # or equivalent
+```
+If missing, prompt with the install command from the per-platform reference doc.
+Do NOT proceed with that platform until CLI is confirmed present.
+
+## Q4 — Target apply: the shared `mutagent-cli apply` transport (SUPERSEDED — M9/DC-5)
+
+**Original decision**: target applies were pure agent operations run by the bespoke
+`diagnostics-apply-worker` (Bash git/gh + Bash curl).
+
+**Superseded (M9/DC-5)**: the apply-worker is RETIRED. Its three branches (local worktree-PR ·
+remote REST · vendor) are now the shared `mutagent-cli apply` target adapters
+(`@mutagent/tools` src/apply — one `TargetAdapter` contract: read → dryRun → apply → rollback →
+emitAudit). At the Step-11 gate, ai-engineer (the WRITE actor) produces the amended artifact and
+shells `mutagent-cli apply --kind <k> --target <root> --dry-run` → `--commit`. Apply is
+non-destructive (REST create-rev+activate; git-revert never force-push) + always audited. The
+skill layer gates BEFORE the CLI (DC-1); the CLI holds no approval logic.
+
+## Q5 — Idempotency via uuidgen
+
+**Decision**: `Bash(uuidgen)` generates the idempotency key for REST writes.
+
+Every remote PUT includes `Idempotency-Key: {uuid}`. Same key on retry → server ignores duplicate. Retry on 5xx (max 2 attempts). Escalate to operator on persistent failure.
+
+## Q6 — Custom platform extensibility
+
+**Decision**: Custom platform onboarding = drop new reference doc + normalize.ts.
+
+No plugin registry or config DSL. To add a new source platform:
+1. Add `references/source-platforms/<new-platform>.md` with CLI operation manual + hyperlinks
+2. Add `scripts/normalize/platforms/<new-platform>.ts` implementing `normalize<Platform>File(content: string): TraceBody`
+3. Update `scripts/config/schema.ts` to include the new platform literal
+
+The orchestrator reads `source.platform` from config and looks up the reference doc by convention.
+
+---
+
+## Filter vs Search distinction
+
+| Term | What it is | Maps to |
+|------|-----------|---------|
+| **Filter** | Narrowing on trace metadata (agent ID, time, score, error flag, tags) | Native CLI `--flag` arguments |
+| **Search** | Additional categorization on top of filter (full-text, semantic, by content match) | Additional API call OR client-side post-filter |
+
+Master Filter/Search Coverage Matrix: `filter-search-matrix.md`
+
+For unknown platforms: agent does runtime CLI docs lookup — `Bash(<cli> --help)` + WebFetch upstream docs — and reasons over the help text to map dimensions.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/config-migration.md

@@ -0,0 +1,84 @@
+# Config Migration — v0.1.0 → v0.2.0 (Diagnostics)
+
+> **Skill-local mirror** of the framework migration directive (canonical copy:
+> `mutagent-orchestrator/references/config-migration.md`). Load this when
+> `scripts/config/load.ts` returns `migrationRequired: true` (a legacy shape was
+> detected) or when `scripts/setup/detect.ts` reports `migrationRequired`.
+
+## Why a migration is needed
+
+The unified `.mutagent/config.yaml` changed shape in **v0.2.0**. The old per-skill
+`diagnostics:` section named its own `source` / `target` / `schedule` /
+`trigger_rules` / `heartbeat`. In v0.2.0 those move to shared, framework-owned
+places so the whole ADL lifecycle shares one catalog. **Fork B — HARD-CUT:** the
+loader NEVER parses the old shape at runtime. It detects a legacy config and emits
+`migration-required`; you rewrite the config in place (this directive), then re-run.
+
+There is **no static migration script** — this is a directive an agent applies
+under the `*onboard` gate.
+
+## Legacy detection (what trips `migration-required`)
+
+Any ONE of these fires (see `detectLegacyShape` in `scripts/config/load.ts`):
+
+- `config_version` is absent or not the frozen `"0.2.0"`.
+- A legacy top-level key is present: `shared` · `stages` · a top-level
+  `diagnostics` · a top-level `evaluator`.
+
+## The rewrite (apply in place)
+
+| # | v0.1.0 (old) | v0.2.0 (new) |
+|---|---|---|
+| 1 | `shared:` | **`global:`** (rename) |
+| 2 | `diagnostics.source: { platform, endpoint, credential_ref, paths, format, agent_field, latency_unit }` | **`global.sources: [ { name, platform, project?, endpoint?, credential_ref?, paths?, format?, agent_field?, latency_unit? } ]`** — give it a `name`; bound BY ROLE (source-consumer), no `source_ref`. |
+| 3 | `diagnostics.target: { platform, mode, root, rest_base_url, credential_ref }` | **`global.targets: [ { name, platform, mode, root?, rest_base_url?, repo_url?, code_refs?, credential_ref?, apply: { kind } } ]`** — give it a `name` + an `apply.kind`; bound BY ROLE (target-writer). A `platform: report-only` target becomes `apply.kind: report-only` (or set `lifecycle.diagnostics.apply: report-only` and omit the target). |
+| 4 | top-level `diagnostics:` section | **`lifecycle.diagnostics:`** (nest under `lifecycle`) |
+| 5 | `diagnostics.schedule` · `diagnostics.trigger_rules` · `diagnostics.heartbeat` | **`triggers.diagnose: { enabled, rules, schedule?, heartbeat? }`** (top-level `triggers`, ships disabled) |
+| 6 | `credential_ref: SOME_ENV` | unchanged, but WIDENED — may now be `credential_ref: { env: SOME_ENV, path: ../secrets/.env }` |
+| 7 | any `*.observability` block | **REMOVED** — source binds by role via `global.sources` |
+| 8 | `config_version: "0.1.0"` (or absent) | **`config_version: "0.2.0"`** (frozen literal) |
+
+Fields the diagnostics section KEEPS (now under `lifecycle.diagnostics`):
+`apply` (new — the report-only gate), `context[]` (new — stage context links),
+`ask_tool`, `default_audience`, `run_tags`, `self_diagnostics`, `feedback_sources`,
+`agents[]`.
+
+## Before → after (minimal example)
+
+**Before (v0.1.0):**
+```yaml
+config_version: "0.1.0"
+shared:
+  models: { default: sonnet, pinned_judge: sonnet }
+diagnostics:
+  source: { platform: langfuse, credential_ref: LANGFUSE_SECRET_KEY }
+  target: { platform: report-only, mode: local }
+  ask_tool: { runtime: claude-code }
+  schedule: { mode: on-demand }
+  heartbeat: { max_diagnostics_per_day: 3 }
+```
+
+**After (v0.2.0):**
+```yaml
+config_version: "0.2.0"
+global:
+  models: { default: sonnet, judge_model: sonnet }   # pinned_judge → judge_model
+  sources:
+    - name: primary
+      platform: langfuse
+      credential_ref: LANGFUSE_SECRET_KEY
+lifecycle:
+  diagnostics:
+    apply: report-only            # was target.platform=report-only
+    ask_tool: { runtime: claude-code }
+triggers:
+  diagnose:
+    enabled: false
+    rules: []
+    schedule: { mode: on-demand }
+    heartbeat: { max_diagnostics_per_day: 3 }
+```
+
+After rewriting, re-run `scripts/setup/detect.ts <project-root>` — it should now
+report `state: complete` (or a normal `partial` for genuinely-missing fields, NOT
+`migrationRequired`).

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

@@ -0,0 +1,159 @@
+# Config Reference — config.yaml Schema with Doc Strings
+
+> Config location: `<host>/.mutagent/config.yaml`
+> Secrets location: `<host>/.mutagentrc` (gitignored — never commit)
+> Schema source of truth: `scripts/config/schema.ts` (TypeBox)
+
+## Full annotated config.yaml
+
+```yaml
+# ──── SOURCE ─────────────────────────────────────────────────────────────────
+# Where agent traces come from.
+source:
+  # Source platform identifier. Required.
+  # Supported in v0.1: langfuse | otel | local-jsonl | claude-code | codex
+  platform: langfuse
+
+  # Endpoint URL for the source platform.
+  # Empty = use default CLI auth / env vars.
+  # Set for self-hosted platforms (e.g., self-hosted Langfuse).
+  endpoint: ""
+
+  # Key name in .mutagentrc for the source API secret.
+  # NEVER store the value here — only the key name.
+  # Example: LANGFUSE_SECRET_KEY → .mutagentrc has LANGFUSE_SECRET_KEY=sk-...
+  credential_ref: LANGFUSE_SECRET_KEY
+
+# ──── TARGET ─────────────────────────────────────────────────────────────────
+# Where agent definitions live (apply remedies back here).
+target:
+  # Target platform identifier. Required.
+  # local-agent: .claude/agents/*.md, .codex/agents/*.md, etc.
+  # local-code-construct: Mastra Agent, Cloud Agent SDK, LangGraph, etc.
+  # cloud-rest: REST API with GET/PUT for agent definition CRUD
+  platform: local-claude
+
+  # Apply mode. Required.
+  # local = markdown file edits via BG worktree + PR
+  # remote = REST PUT with idempotency-key
+  mode: local
+
+  # Root directory for local targets (relative to project root).
+  # Default: .claude/agents/
+  root: .claude/agents/
+
+  # REST base URL for remote targets.
+  # rest_base_url: https://api.example.com/v1
+
+  # Key name in .mutagentrc for REST auth token.
+  # credential_ref: REST_API_TOKEN
+
+# ──── ASK TOOL ───────────────────────────────────────────────────────────────
+# Platform-native ASK mechanism. Auto-detected by cli/init.ts at first run.
+# Override here if auto-detection is wrong.
+ask_tool:
+  # Host coding-agent runtime. Required.
+  # claude-code | codex | cursor | opencode | generic
+  runtime: claude-code
+
+  # Platform tool name for structured multi-select.
+  # AskUserQuestion on Claude Code; varies on other runtimes.
+  native_tool: AskUserQuestion
+
+  # Fallback when native tool is unavailable.
+  # chat-multi-choice: numbered list in chat message
+  fallback: chat-multi-choice
+
+# ──── SCHEDULE ───────────────────────────────────────────────────────────────
+# When the orchestrator wakes to check trigger rules.
+# v0.1 ships on-demand ONLY. Schedule structure prepared for post-v0.1 wiring.
+# See references/workflows/schedule-prep.md for adding scheduling post-v0.1.
+schedule:
+  # on-demand = operator manually invokes (v0.1 supported)
+  # daily-batch = native /loop or cron wake (post-v0.1)
+  mode: on-demand
+
+  # For daily-batch: local time (HH:MM format)
+  at: "09:00"
+
+  # Timezone. Defaults to system timezone.
+  # timezone: "America/New_York"
+
+# ──── TRIGGER RULES ──────────────────────────────────────────────────────────
+# Which traces qualify for a diagnostic run when schedule fires or operator invokes.
+# Each rule's match is a TraceFilter; traces matching ANY rule are diagnosed.
+trigger_rules:
+  - name: high-latency-errors
+    match:
+      latency_p99_ms_above: 5000
+      has_error: true
+    action: diagnose
+
+  - name: feedback-bearing
+    match:
+      has_feedback: true
+      # score_below is computed via score-scale auto-discovery (iter-8)
+      # Do NOT hardcode here — let the orchestrator probe and compute threshold
+    action: diagnose
+
+  # Example: specific agent filter
+  # - name: search-agent-failures
+  #   match:
+  #     agent_id: search-agent
+  #     has_error: true
+  #   action: diagnose
+
+# ──── HEARTBEAT ──────────────────────────────────────────────────────────────
+# Controls notifications for scheduled (non-interactive) runs.
+heartbeat:
+  # Whether to log when no triggers fire (no operator ping)
+  notify_on_zero_matches: false
+
+  # Whether to notify operator when triggers fire and report is ready
+  notify_on_matches: true
+
+  # Cost guardrail: max full diagnostic runs per day
+  max_diagnostics_per_day: 3
+
+# ──── SELF DIAGNOSTICS [INTERNAL] ────────────────────────────────────────────
+# Skill diagnoses itself after usage session (PR-022).
+# OFF by default for end users. ON for skill maintainers + dogfood mode.
+self_diagnostics:
+  # Enable/disable self-diagnostics. Default: false.
+  enabled: false
+
+  # Cadence: per-session | daily | manual
+  cadence: per-session
+
+  # Source: auto-detect host (claude-code | codex)
+  source: host-coding-agent
+
+  # Branch for self-remedy PRs (use {date} placeholder)
+  remedy_branch: mutagent/self-diagnostics/{date}
+
+  # [INTERNAL] prefix added to all self-remedy PR titles
+  marker: "[INTERNAL]"
+```
+
+## TraceFilter fields (for trigger_rules.match)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agent_id` | string | Filter by agent identifier |
+| `session_id` | string | Filter by specific session/trace ID |
+| `start_time` | ISO8601 string | Start of time window |
+| `end_time` | ISO8601 string | End of time window |
+| `has_error` | boolean | Only traces with error events |
+| `has_feedback` | boolean | Only traces with attached feedback |
+| `score_below` | number | Traces with score below threshold (computed by orchestrator from scale probe) |
+| `latency_p99_ms_above` | number | Traces with P99 latency above threshold (ms) |
+| `by_skill` | string | Traces where a specific skill was triggered |
+| `by_route` | string | Traces with a specific operation name |
+| `by_tag` | string[] | Traces with specific tags |
+
+## Security notes
+
+- `config.yaml` is committed to the project repository (non-secrets only)
+- `.mutagentrc` is gitignored and holds actual secret values
+- The `credential_ref` field in config.yaml is a KEY NAME pointing to `.mutagentrc`, never the value
+- Three-layer protection: `.gitignore` pattern + `git check-ignore` before any write + PR-time `git status` check