@mutagent/helix 0.1.0-alpha.14

package/mutagent-orchestrator/references/MONITORING.md

@@ -0,0 +1,209 @@
+# Monitoring — `*dogfood` (inward) + `*monitor` (outward) User Manual
+
+> Helix ships **two** monitors that share the low-level Slack transport but keep **separate voices**:
+>
+> | | **Dogfood Monitor** (`*dogfood`) | **External Monitor** (`*monitor`) |
+> |---|---|---|
+> | Direction | INWARD — self-observation of a live session | OUTWARD — watches system conditions |
+> | Watches | `config.dogfood.source_dir` (a live coding session) | `config.triggers` (evaluate/diagnose rules) |
+> | On tick / match | re-render report + post a Slack **thread** reply | route a `HandoverBundle` + post a Slack **notification** |
+> | Slack shape | a live THREAD (root + progress replies) | discrete one-shot NOTIFICATIONS |
+> | Ships | live (watch-by-default) | **DISABLED** (no auto-fire until enabled) |
+>
+> §1–4 below cover `*dogfood`; **§5 covers `*monitor`**. Both post only when Slack is configured;
+> unconfigured ⇒ no Slack, never an error.
+
+---
+
+## 1. What `*dogfood` is
+
+`*dogfood` is Helix's **inward self-observation** monitor. It live-tails a Helix coding session and,
+on every drift **and** at least every 3 minutes, reconstructs the ADL trajectory, extracts feedback +
+signals, and re-renders a live status report.
+
+- **Always live.** `*dogfood` is a monitor, not a one-shot: it watches by default (3-minute heartbeat
+  **+** on-drift re-render). There is no "just render once" operator mode (an internal `--once` exists
+  for tests only).
+- **Start:** `*dogfood <sessionId>` — or `*dogfood` with no id to watch the latest session in the
+  configured `source_dir`.
+- **Stop:** `*dogfood-stop` (it also stops on session inactivity).
+- **Where the report lands:** `.mutagent/dogfood/<runId>/status.html` — a self-contained HTML page that
+  **auto-reloads** in the browser (Helix auto-opens it once). Sections: timeline · command usage ·
+  subagents · feedback · Call-Stack DAG.
+
+> **Build project ≠ dogfood target.** `*dogfood` does NOT watch the project you're developing Helix in;
+> it watches the dogfood TARGET project's Claude-Code session dir, set in `config.dogfood.source_dir`.
+
+---
+
+## 2. Config reference — `config.dogfood`
+
+In `.mutagent/config.yaml`:
+
+```yaml
+dogfood:
+  # The dogfood TARGET project's Claude-Code session dir (NOT the build project).
+  # Absolute by design (Claude encodes the project cwd by replacing "/" with "-").
+  source_dir: "~/.claude/projects/-Users-you-Desktop-your-DOGFOOD-project"
+
+  # Forced re-render cadence in seconds. Default 180 (3 min). The watch loop ALSO
+  # re-renders on drift (a new *command / ADL stage / [feedback] / subagent).
+  cadence_seconds: 180
+
+  # Resolve + ingest dispatched subagent session JSONLs too. Default true.
+  include_subagents: true
+
+  # OPTIONAL live Slack thread (see §3). Omit or set enabled:false ⇒ HTML report
+  # only, never an error.
+  slack:
+    enabled: true
+    channel: "C0123ABC"              # a Slack channel id the bot is in
+    token_ref: "SLACK_BOT_TOKEN"     # the ENV-VAR NAME holding the xoxb-… token (never the secret itself)
+```
+
+| Key | Meaning | Default |
+|---|---|---|
+| `source_dir` | dogfood target's `~/.claude/projects/<enc(path)>/` dir | *(required)* |
+| `cadence_seconds` | forced re-render cadence (seconds) | `180` |
+| `include_subagents` | ingest dispatched subagent transcripts | `true` |
+| `slack.enabled` | post a live Slack thread | `false` |
+| `slack.channel` | Slack channel id | — |
+| `slack.token_ref` | **name** of the env var holding the bot token | — |
+
+---
+
+## 3. Slack setup — the operator flow {#slack-setup}
+
+The dogfood live thread posts a **root message on start** and **threaded replies** as the session moves
+(stage change · agent dispatch · feedback · signal · progress heartbeat · stop). Threading requires the
+Slack **Web API** (`chat.postMessage` + `thread_ts`) — a **bot token**, NOT an incoming webhook.
+
+**Step by step:**
+
+1. **Create a Slack App.** Go to <https://api.slack.com/apps> → **Create New App** → **From scratch**.
+   Name it (e.g. "Helix Dogfood") and pick your workspace.
+2. **Add the bot scope.** In the app: **OAuth & Permissions** → **Scopes** → **Bot Token Scopes** → add
+   **`chat:write`**. If you'll post to a channel the bot hasn't been invited to, also add
+   **`chat:write.public`**.
+3. **Install to workspace.** **OAuth & Permissions** → **Install to Workspace** → Allow. Copy the
+   **Bot User OAuth Token** — it starts with `xoxb-…`.
+4. **Export the token as an env var.** The **name** (not the value) goes in `token_ref`:
+   ```bash
+   export SLACK_BOT_TOKEN=xoxb-your-token-here
+   ```
+5. **Invite the bot + get the channel id.** In the target channel run `/invite @YourApp`. Get the
+   channel **ID** (`C0…`) from the channel's *View channel details* (bottom of the popover) or the URL.
+6. **Set the config:**
+   ```yaml
+   dogfood:
+     slack: { enabled: true, channel: "C0123ABC", token_ref: "SLACK_BOT_TOKEN" }
+   ```
+7. **Run it.** `*dogfood <sessionId>` → a live thread appears in the channel (root + replies). Verify the
+   root posts and replies thread underneath as the session moves.
+
+> **Unconfigured = no Slack.** With no token/channel, or `enabled:false`, `*dogfood` produces the HTML
+> report only and posts nothing — it is **never** an error. A misconfigured or unreachable Slack likewise
+> never breaks a render (the post silently no-ops).
+
+### Troubleshooting
+
+| Slack error | Cause | Fix |
+|---|---|---|
+| `not_in_channel` | the bot isn't a member of `channel` | `/invite @YourApp` in that channel (or add `chat:write.public`) |
+| `invalid_auth` | token missing/expired, or `token_ref` points at an unset/typo'd env var | re-check the exported env var name + value (`echo $SLACK_BOT_TOKEN`) |
+| `missing_scope` | the app lacks `chat:write` | add the **Bot Token Scope** `chat:write`, then **reinstall** the app |
+| *(nothing posts, no error)* | `slack.enabled:false` or `token_ref` env var unset | set `enabled:true` and export the token; disabled/unset ⇒ intentional no-op |
+
+---
+
+## 4. Quick reference
+
+```bash
+# start watching the latest session in source_dir
+*dogfood
+
+# start watching a specific session
+*dogfood d4e98196-926d-4602-965f-d5aed291a54c
+
+# stop
+*dogfood-stop
+
+# the live report (auto-reloads in the browser)
+.mutagent/dogfood/<runId>/status.html
+```
+
+---
+
+## 5. The External Monitor — `*monitor` (outward)
+
+`*monitor` is Helix's **outward** monitor. Where `*dogfood` looks INWARD at a live session,
+`*monitor` watches **conditions** in `config.triggers` (the dormant evaluate/diagnose trigger rules).
+When a trigger fires, it **routes** a `HandoverBundle` to the target ADL stage — the same dispatch
+model as `*discover` — and posts a discrete Slack **notification**. It never runs the stage itself
+and never edits a target; it hands off and notifies.
+
+- **Notification vs dogfood thread (the distinction).** `*dogfood` posts a live THREAD (a root
+  message + progress replies under it) so coworkers follow one session in real time. `*monitor` posts
+  a discrete NOTIFICATION — one standalone message per fired trigger. Shared Slack transport
+  (`scripts/slack/*`), **separate emitters**: `dogfood/slack-thread.ts` vs `monitor/slack-notify.ts`.
+- **Start / stop:** `*monitor` arms the watch; `*monitor-stop` disarms it. Both are internal
+  (maintainer/system) commands — invocable by name, hidden from the roster.
+
+### Ships DISABLED — how to enable
+
+The condition source is `config.triggers`, which **ships DISABLED** (`enabled:false`, empty rules).
+A disabled block fires **nothing**, so a fresh install never auto-fires. To enable a trigger, opt in
+per stage:
+
+```yaml
+# .mutagent/config.yaml
+triggers:
+  diagnose:
+    enabled: true                 # ← opt-in (ships false)
+    rules:
+      - on: "trace-count>=100"    # fire when ≥ 100 new traces arrive
+        run: "*diagnose"          # the stage/command to route to
+  evaluate:
+    enabled: true
+    rules:
+      - on: "schedule"            # fire on a scheduled wake
+        run: "*evaluate"
+```
+
+**Event kinds** a rule's `on` can name: `trace-count` (optionally `trace-count>=N` / `trace-count>N`),
+`schedule`, `ci`, `manual`. A rule fires only for its own event kind (and, for `trace-count` with a
+threshold, only when the count satisfies the comparator).
+
+### The external notification sink — `config.monitor.slack`
+
+`*monitor` uses its **own** Slack sink, separate from `dogfood.slack`:
+
+```yaml
+# .mutagent/config.yaml
+monitor:
+  slack:                          # OPTIONAL — omit / disable ⇒ no notifications, never an error
+    enabled: true
+    channel: "C0123ABC"           # a Slack channel id the bot is a member of
+    token_ref: "SLACK_BOT_TOKEN"  # the ENV-VAR NAME holding the xoxb-… bot token (never the secret)
+```
+
+The Slack app setup is identical to §3 (`chat:write` bot token; `token_ref` is the env-var **name**).
+Unconfigured / disabled `monitor.slack` ⇒ the monitor still **routes** the handover, it just posts no
+Slack (the post no-ops; a broken Slack never blocks a route).
+
+| Key | Meaning | Default |
+|---|---|---|
+| `triggers.<stage>.enabled` | arm this stage's rules | `false` (ships DISABLED) |
+| `triggers.<stage>.rules[].on` | the event condition (`trace-count[>=N]` · `schedule` · `ci` · `manual`) | — |
+| `triggers.<stage>.rules[].run` | the stage/command to route to on a match | — |
+| `monitor.slack.enabled` | post a notification per fired trigger | `false` |
+| `monitor.slack.channel` | Slack channel id | — |
+| `monitor.slack.token_ref` | **name** of the env var holding the bot token | — |
+
+```bash
+# arm the external watch on config.triggers
+*monitor
+
+# disarm it
+*monitor-stop
+```

package/mutagent-orchestrator/references/config-fields.md

@@ -0,0 +1,132 @@
+# `.mutagent/config.yaml` — Field Board (v0.2.0)
+
+> The durable field map for the MutagentConfig contract. Every field · its block ·
+> type · the consumer file(s) that READ it · its purpose · when it is required.
+> Source of truth: `scripts/config-schema.ts` (the doc-comments there mirror this
+> board). No field should read as "dead" — each row names a real consumer.
+>
+> **Consumer legend.** `onboarding-check.ts` / `gate.ts` / `resolve-credential.ts` /
+> `resolve-paths.ts` / `dispatch.ts` live in this package (`mutagent-orchestrator`).
+> `@mutagent/tools` is the shared trace layer (fetch + normalize). The SKILLS
+> (evaluator / diagnostics / agentspec / builder) each read their own
+> `lifecycle.<skill>` section + the shared `global` catalogs. RESERVED = shape is
+> frozen but no current code path reads it (future Build/Improve or the future
+> monitor).
+
+## Top level
+
+| Field | Block | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|---|
+| `config_version` | (root) | `"0.2.0"` literal | `config-schema.ts` (`validateConfig`, `detectLegacyConfig`) | The FROZEN contract version; wrong/absent ⇒ legacy or reject | ALWAYS |
+| `global` | (root) | object | `onboarding-check.ts`, `gate.ts`, `resolve-credential.ts`, skills | Framework-wide shared resources | Optional (partial config validates) |
+| `lifecycle` | (root) | object | `gate.ts`, `onboarding-check.ts`, each skill | Per-skill behavior, keyed by skill name | Optional |
+| `triggers` | (root) | object | RESERVED — future monitor | The future always-on monitor (disabled) | Optional (ships disabled) |
+| `dogfood` | (root) | object | `scripts/dogfood/*` (the `*dogfood` surface) | Watches a SEPARATE dogfood-target project's sessions | Optional |
+
+## `global` — framework-wide shared resources
+
+| Field | Block | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|---|
+| `providers[]` | `global` | `Provider[]` | `onboarding-check.ts` (provider floor), `resolve-credential.ts` | Provider credential REFS | evaluate + `judge_runtime: in-house` |
+| `providers[].name` | `global.providers` | string | `resolve-credential.ts`, in-house judge wiring | Provider id (`anthropic`/`google`) | when a provider entry exists |
+| `providers[].credentials_ref` | `global.providers` | `string \| {env,path}` | `onboarding-check.ts`, `resolve-credential.ts` | Env-var NAME (never a raw secret) | when a provider entry exists |
+| `workspace.repo` | `global.workspace` | string | `onboarding-check.ts` (target floor), build/apply worktree | The target repo slug | target-writing stage (build/improve/diagnose-apply) |
+| `workspace.path` | `global.workspace` | string (relative) | `resolve-paths.ts` | Locates the install/init dir | optional |
+| `models.default` | `global.models` | string | `onboarding-check.ts` (default-model floor), evaluator run | Default execution model + JUDGE FALLBACK. **ASYMMETRY: diagnostics IGNORES it** (host-runtime agent-dispatch) | evaluate or a target-writing stage |
+| `models.judge_model` | `global.models` | string | `onboarding-check.ts` (judge floor), evaluator scorecard stamp | C-PIN pinned judge (renamed from `pinned_judge`) | evaluate / audit (judging stages) |
+| `brand.theme` | `global.brand` | string | evaluator/diagnostics HTML report renderers | REPORT STYLING only (cosmetic; no gating effect) | optional |
+| `context[]` | `global` | `ContextLink[]` | the skills (loaded as stage context) | PROJECT-WIDE context links | optional |
+| `context[].path/what/why/when` | `global.context` | string ×4 | loading skill's context banner | The doc + its WHAT/WHY/WHEN rationale | all four required per link |
+| `sources[]` | `global` | `Source[]` | `onboarding-check.ts` (`resolveSourceByRole`), `@mutagent/tools` fetch | The SOURCES catalog (where traces come from) | diagnose (always) / evaluate (discover) |
+| `targets[]` | `global` | `Target[]` | `onboarding-check.ts` (`resolveTargetByRole`), builder/diagnose-apply | The TARGETS catalog (where fixes go) | build / improve(apply) / diagnose(apply, non-report-only) |
+
+### `global.sources[]` — one catalog entry
+
+| Field | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|
+| `name` | string | `onboarding-check.ts`, run-time confirm/pick prompt | Catalog key | ALWAYS (per entry) |
+| `platform` | enum `langfuse\|otel\|local-jsonl\|claude-code\|codex` | `@mutagent/tools` fetch (+ eval/diag ports) | Picks the per-platform reader | ALWAYS (per entry) |
+| `default` | boolean | `onboarding-check.ts` `resolveByRole`, run-time prompt | SELECTION selector: one default among many ⇒ `resolved-default` | optional (only meaningful with multiple entries) |
+| `project` | string | `@mutagent/tools` remote fetch | Remote project/workspace slug | remote platforms |
+| `endpoint` | string | `@mutagent/tools` remote fetch | Remote base URL (mut. exclusive with `paths`) | remote (otel/rest) |
+| `credential_ref` | `string \| {env,path}` | `resolve-credential.ts` → `@mutagent/tools` | Read token env-var NAME | remote platforms |
+| `paths` | string[] | `@mutagent/tools` local-jsonl / unitf reader | File-source glob(s) (mut. exclusive with `endpoint`) | file sources |
+| `format` | enum `langfuse-export\|claude-code\|codex\|raw\|unitf` | `@mutagent/tools` normalize path | How to parse records. **`unitf` (F1) ⇒ read jsonl direct, skip normalize** | optional (inferred otherwise) |
+| `agent_field` | string | eval/diag agent-variance grouping | Which record field carries the agent name | optional |
+| `latency_unit` | enum `auto\|ms\|s` | `@mutagent/tools` normalize (latency projection) | Latency-unit override (`auto` = infer) | optional |
+
+### `global.targets[]` — one catalog entry
+
+| Field | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|
+| `name` | string | `onboarding-check.ts`, run-time confirm/pick prompt | Catalog key | ALWAYS (per entry) |
+| `platform` | enum (local-claude/codex/cursor/opencode/mastra/cloud-agent-sdk, **local-skill**, cloud-rest, report-only) | `mutagent-cli apply` adapter (+ builder) | Picks the fix writer / adapter | ALWAYS (per entry) |
+| `subject` | enum `agent\|skill` | apply on-ramp (skill amends → skill-builder wave), `onboarding-check.ts` | D2 subject-kind: `skill` root = skill DIR, SSoT = `.meta/prd.yaml` (annexed skillspec), markdown transport | optional (absent ⇒ `agent`) |
+| `default` | boolean | `onboarding-check.ts` `resolveByRole`, run-time prompt | SELECTION selector: one default among many ⇒ `resolved-default` | optional (only with multiple entries) |
+| `mode` | enum `local\|remote` | diagnose-apply worker | Local-diff vs REST-PUT branch | ALWAYS (per entry) |
+| `root` | string | diagnose-apply worker (local mode) | Local root dir the fix writes under | local mode |
+| `rest_base_url` | string | diagnose-apply worker (remote mode) | Remote REST base URL | remote/cloud-rest |
+| `repo_url` | string | diagnose-apply worker (local-git-over-remote) | Remote git repo clone source | git-over-remote |
+| `code_refs[]` | `CodeRef[]` | **RESERVED — Build/Improve (future)** | Realized-implementation links a `*build`/`*improve` run records | never (reserved) |
+| `code_refs[].path/why` | string ×2 | **RESERVED — Build/Improve (future)** | The impl file + why it realizes the spec | never (reserved) |
+| `credential_ref` | `string \| {env,path}` | `resolve-credential.ts` → diagnose-apply | Target write token env-var NAME | remote mode |
+| `apply` | `Apply` | `onboarding-check.ts`, diagnose-apply worker | HOW a fix is applied | ALWAYS (per entry) |
+| `apply.kind` | enum `code-pr\|markdown\|cloud-deploy\|report-only` | `onboarding-check.ts` (`report-only` gates OUT the target floor), diagnose-apply | Apply strategy | ALWAYS (within `apply`) |
+| `apply.versioning` | boolean | **RESERVED — Build/Improve (future)** | Bump a version stamp on apply | never (reserved) |
+| `apply.pr` | boolean | **RESERVED — Build/Improve (future)** | Open a PR vs write in place | never (reserved) |
+
+## `lifecycle.<skill>` — per-skill sections (open objects; only typed fields shown)
+
+| Field | Block | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|---|
+| `agentspec.spec_dir` | `lifecycle.agentspec` | string | orchestrator + agentspec skill | Where `*spec` writes agentspec.yaml | optional |
+| `builder.*` | `lifecycle.builder` | open | builder skill (passthrough) | Config-light (writes by role to a target) | optional |
+| `evaluator.context[]` | `lifecycle.evaluator` | `ContextLink[]` | evaluator skill | Stage-specific context for evaluate | optional |
+| `evaluator.judge_runtime` | `lifecycle.evaluator` | string | `gate.ts`/`onboarding-check.ts` (provider floor), evaluator judge wiring | HOW judges run (renamed from `substrate`); `in-house` ⇒ provider floor | optional |
+| `evaluator.*` (other) | `lifecycle.evaluator` | open | evaluator skill (passthrough) | subject/datasets/etc. — the skill's opaque knobs | optional |
+| `diagnostics.apply` | `lifecycle.diagnostics` | string | `onboarding-check.ts` (`diagnosticsIsReportOnly`), `gate.ts` | Report-only gate: `report-only` ⇒ skip the target floor | optional |
+| `diagnostics.context[]` | `lifecycle.diagnostics` | `ContextLink[]` | diagnostics skill | Stage-specific context for diagnose | optional |
+| `diagnostics.*` (other) | `lifecycle.diagnostics` | open | diagnostics skill (passthrough) | ask_tool/run_tags/audience/etc. — opaque knobs | optional |
+
+## `triggers.<stage>` — the future monitor (ALL RESERVED, ship disabled)
+
+| Field | Block | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|---|
+| `<stage>.enabled` | `triggers.<stage>` | boolean (default false) | RESERVED — future monitor | Master on/off per stage | never (ships false) |
+| `<stage>.rules[]` | `triggers.<stage>` | `TriggerRule[]` (default []) | RESERVED — future monitor | The trigger rules | never (ships empty) |
+| `<stage>.rules[].on` | `triggers.<stage>.rules` | string | RESERVED — future monitor | The event that fires the rule | never |
+| `<stage>.rules[].run` | `triggers.<stage>.rules` | string | RESERVED — future monitor | Stage/command to run on fire | never |
+| `<stage>.schedule.mode/at/timezone` | `triggers.<stage>.schedule` | string ×3 | RESERVED — future monitor | When the monitor wakes | never |
+| `<stage>.heartbeat.notify_on_zero_matches` | `triggers.<stage>.heartbeat` | boolean | RESERVED — future monitor | Notify on empty scan | never |
+| `<stage>.heartbeat.notify_on_matches` | `triggers.<stage>.heartbeat` | boolean | RESERVED — future monitor | Notify on match | never |
+| `<stage>.heartbeat.max_diagnostics_per_day` | `triggers.<stage>.heartbeat` | integer ≥0 | RESERVED — future monitor | Per-day cost cap | never |
+
+Stages keyed by the routing `AdlStage` enum: `build \| evaluate \| diagnose \| improve \| audit`.
+
+## `dogfood` — the hidden `*dogfood` observe surface
+
+| Field | Block | Type | Consumer | Purpose | Required-when |
+|---|---|---|---|---|---|
+| `source_dir` | `dogfood` | string (ABSOLUTE by design) | `scripts/dogfood/*` | The DOGFOOD-target project's Claude-Code session dir (NOT the build project) | when `dogfood` block present |
+| `session_glob` | `dogfood` | string | `scripts/dogfood/*` | Session glob (default `*.jsonl`) | optional |
+| `include_subagents` | `dogfood` | boolean | `scripts/dogfood/*` | Also tail dispatched subagent JSONLs (default true) | optional |
+
+---
+
+## SELECTION contract — role binding (source + target)
+
+Binding is BY ROLE (no `source_ref`/`target_ref`) over the `global.sources[]` /
+`global.targets[]` catalog, under the `default` flag:
+
+| Catalog shape | `resolveByRole` status | Bindable? | Run-time behavior |
+|---|---|---|---|
+| 0 entries | `none` | no | floor UNMET (`source/target-required`) |
+| 1 entry | `resolved-single` | yes | auto-bind, NO prompt |
+| many, exactly one `default: true` | `resolved-default` | yes | bind the default; run-time CONFIRMS (preselected, overridable) |
+| many, no default | `needs-selection` | yes | operator PICKS at run time |
+| many, >1 `default: true` | `multiple-defaults` | no | CONFIG ERROR (`source/target-config-error`) |
+
+`resolved-single` and `resolved-default` (F2) are DISTINCT statuses but BOTH satisfy
+the onboarding floor — the split only drives the run-time prompt (confirm vs
+silent), never the gate. The confirm/pick prompts are a run-time skill concern, not
+a `gate.ts` blocker.

package/mutagent-orchestrator/references/config-migration.md

@@ -0,0 +1,132 @@
+# Config migration directive — `.mutagent/config.yaml` v0.1.0 → v0.2.0
+
+> **This is a DIRECTIVE, not a script.** There is no static migrate tool (Fork B:
+> hard-cut). When the orchestrator detects a legacy config it emits
+> `migration-required`; a coding agent (or the operator, under the `*onboard`
+> gate) then rewrites the file IN PLACE by following the steps below. The loader
+> NEVER parses the old shape at runtime.
+
+## When this fires
+
+`loadConfig` returns `{ ok: false, legacy: true }` — and `gateExecution` emits the
+`migration-required` blocker — when the parsed config carries ANY legacy marker:
+
+- `config_version` is absent or `"0.1.0"` (anything other than the frozen `"0.2.0"`), OR
+- a legacy top-level key is present: `shared`, `stages`, a top-level `diagnostics`
+  section, or a top-level `evaluator` section, OR
+- any `stages.<stage>.observability` block survives.
+
+## The v0.2.0 shape (target)
+
+Three top-level blocks: **`global`** (shared resources + the sources/targets
+catalogs) · **`lifecycle`** (per-skill, keyed by skill name) · **`triggers`**
+(future monitor, per stage, disabled). The old `stages` map is GONE — every skill
+IS a stage, so the config is keyed by skill, and "where traces come from" / "where
+fixes go" live in a global catalog bound BY ROLE (no `source_ref` / `target_ref`).
+
+## The transform (apply all, in order)
+
+1. **`shared` → `global`.** Rename the top-level `shared:` block to `global:`.
+   Every field under it keeps its meaning.
+
+2. **`models.pinned_judge` → `models.judge_model`.** Rename the key under
+   `global.models`. Semantics unchanged — it is the C-PIN pinned judge model
+   (`agent-dispatch` judge runtime ⇒ the host model, no provider key).
+
+3. **Hoist the observability source → `global.sources[]`.** For each
+   `stages.<stage>.observability` you had (typically evaluate + diagnose, usually
+   the SAME source named in multiple places), create ONE entry under
+   `global.sources[]`:
+   ```yaml
+   global:
+     sources:
+       - name: primary-langfuse           # a catalog id you choose
+         platform: langfuse               # was observability.platform
+         project: mutagent-evals          # was observability.project (optional)
+         # endpoint / credential_ref / paths / format / agent_field / latency_unit
+         # as applicable — endpoint_ref (env-var) becomes credential_ref
+   ```
+   De-duplicate: if evaluate + diagnose named the same source, emit it ONCE. A
+   source-consuming stage binds it BY ROLE under the SELECTION contract: one
+   entry ⇒ auto-bind; MANY entries ⇒ mark exactly ONE with `default: true` to
+   auto-select it (`resolved`), or leave all un-marked to pick at run time
+   (`needs-selection`). Setting `default: true` on MORE THAN ONE entry is a
+   config error (`multiple-defaults`) — the orchestrator surfaces it as a distinct
+   `source-config-error` blocker.
+
+   ```yaml
+   global:
+     sources:
+       - name: prod-langfuse            # auto-selected when multiple exist
+         platform: langfuse
+         default: true                  # SELECTION selector (optional, boolean)
+       - name: local-jsonl-dump
+         platform: local-jsonl
+         paths: [traces/*.jsonl]
+   ```
+
+4. **Hoist the apply target → `global.targets[]`.** If the legacy config expressed
+   a fix target (a `diagnostics.target` / a `report-only` marker), create ONE
+   entry under `global.targets[]`:
+   ```yaml
+   global:
+     targets:
+       - name: local-agents
+         platform: local-claude           # local-claude|…|cloud-rest|report-only
+         mode: local                       # local | remote
+         root: .claude/agents              # local targets
+         # rest_base_url / repo_url / code_refs / credential_ref as applicable
+         apply:
+           kind: code-pr                   # code-pr|markdown|cloud-deploy|report-only
+   ```
+   A `report-only` legacy target becomes `lifecycle.diagnostics.apply: report-only`
+   (see step 6) — a report-only run needs NO target at all. As with sources, a
+   MULTI-target catalog uses the SELECTION contract: mark exactly one entry
+   `default: true` to auto-select it, or leave all un-marked to pick at run time.
+   More than one `default: true` is a config error (`target-config-error`).
+
+5. **Drop `stages` entirely.** After steps 3-4, delete the whole `stages:` map. Its
+   only real content was `observability` (now a global source) — the rest was a
+   false phase/skill axis that v0.2.0 collapses.
+
+6. **Move skill sections under `lifecycle.<skill>`.** A top-level `diagnostics:` /
+   `evaluator:` section moves under `lifecycle:`, keyed by skill name:
+   ```yaml
+   lifecycle:
+     agentspec:  { spec_dir: .mutagent/specs }     # optional
+     builder:    {}                                # config-light
+     evaluator:  { judge_runtime: agent-dispatch, context: [...] }
+     diagnostics:{ apply: report-only, context: [...] }
+   ```
+   The orchestrator TYPES only the gate-relevant fields per skill
+   (`spec_dir` / `context` / `apply` / `judge_runtime`); every other knob is the
+   skill's own opaque passthrough — leave it as-is under its skill section.
+
+7. **`substrate` → `judge_runtime`.** Under the evaluator section, rename
+   `substrate` to `judge_runtime`. Enum VALUES are unchanged
+   (`agent-dispatch` | `in-house` | `code-based` | `user-framework`).
+
+8. **Move `diagnostics.{schedule, trigger_rules, heartbeat}` → `triggers.<stage>`.**
+   These three no longer live under the diagnostics skill section. Fold them into
+   the top-level `triggers` block, keyed per stage:
+   ```yaml
+   triggers:
+     diagnose:
+       enabled: false          # ships DISABLED (on-demand only)
+       rules: []               # was diagnostics.trigger_rules
+       schedule:  { mode: on-demand, at: ..., timezone: ... }   # was diagnostics.schedule
+       heartbeat: { notify_on_zero_matches: ..., max_diagnostics_per_day: ... }  # was diagnostics.heartbeat
+   ```
+
+9. **Widen credential refs.** Any `credentials_ref` / `credential_ref` /
+   `endpoint_ref` that named a bare env var stays a string; where you need to pin
+   an explicit file, use the widened `{ env: NAME, path: FILE }` object form. Refs
+   are ALWAYS env-var NAMES — never a raw secret value.
+
+10. **Bump the version.** Set `config_version: "0.2.0"`.
+
+## After migrating
+
+Re-run the orchestrator's onboarding check / `*onboard` gate. `loadConfig` now
+returns `{ ok: true, config }`; the `migration-required` blocker clears and the
+scoped source/target/provider floors take over.

package/mutagent-orchestrator/references/index-registry.md

@@ -0,0 +1,92 @@
+# `.mutagent/index.md` — the ADL spec ↔ implementation registry
+
+> Convention doc for the orchestrator-owned registry writer (`scripts/index/{build-index,render-index}.ts`).
+> This is the ONLY place the update-point convention is documented (F4, PLAN §"FEATURE 4").
+
+## What it is
+
+`.mutagent/index.md` is a **single markdown file that IS the record** — no sidecar JSON. It links
+each registered AgentSpec to everything that realizes it, versioned + dated, so the spec ↔
+implementation relationship stays traceable across the whole ADL loop.
+
+The markdown IS the machine surface: section headers + markdown links are what downstream reads.
+There is no parallel structured file to drift against.
+
+## HIGH-LEVEL ONLY (anti-drift — LOAD-BEARING)
+
+The index carries **identity + stage/verdict + version/date + LINKS ONLY**:
+
+- spec identity (`spec_id`, display name) + `spec_version`
+- ADL `loop_state.stage` + `last_verdict`
+- the build target (`target_framework` · `runtime`)
+- markdown LINKS to: agent code · tooling/integrations · harness/framework code · context/product docs
+- an injected `updated <YYYY-MM-DD>` stamp
+
+It **NEVER** carries eval criteria, scenarios, dataset detail, or any other volatile field. That
+lives in the evaluator's living-suite; duplicating it here is a drift + maintenance burden. **The
+index only links; it never restates.** The renderer is guarded by a test that asserts no
+`criteria` / `scenario` / `dataset` tokens ever appear.
+
+## Data sources
+
+| Field(s) | Source | Notes |
+|---|---|---|
+| `spec_id` · `spec_version` · `stage` · `last_verdict` | each `agentspec.yaml` under `.mutagent/specs/*` (`meta` + `meta.loop_state`) | `last_verdict` absent ⇒ rendered as `—` |
+| display name | `definition.identity.name` (falls back to the spec_id) | |
+| build target · runtime | `build.{target_framework, runtime}` | absent build block ⇒ Build bullet omitted |
+| implementation / code links | config `global.targets[].code_refs[]` (`{path, why}`) | flattened across targets, deduped + sorted by path |
+| context / product docs | config `global.context[]` (`{path, what, why, when}`) | sorted by path |
+| `updated <date>` | **INJECTED clock** (`nowIso.slice(0,10)`), NOT the spec's `updated_at` | see Determinism |
+
+**Why config-sourced impl links (not per-spec):** per agentspec PR-013 the spec is
+implementation-agnostic and never enumerates its own impls (backwards-only linking). So the config's
+`global.targets[].code_refs` are the impl-link source of truth. They are shared across the install and
+attached to each spec entry — exactly right for the dominant one-agent-per-install case; a multi-agent
+install shows them as shared implementation/context, which is the correct high-level view (per-spec
+target binding is a run-time role-binding concern, out of scope for the static index).
+
+**Link resolution:** the index lives at `<root>/.mutagent/index.md`.
+- Spec links are `.mutagent/`-relative: `specs/<id>/agentspec.yaml` (no prefix).
+- Code + context paths are project-root-relative (config determinism rule), so they are hopped out of
+  `.mutagent/` with a `../` prefix: `src/foo.ts` → `[src/foo.ts](../src/foo.ts)`.
+
+## Determinism (mirrors the diagnostics `store.ts` `regenerateIndex` pattern)
+
+`regenerateIndex(root, nowIso, io?)` regenerates the WHOLE file from on-disk state each call
+(append-then-regenerate — never hand-patched line edits):
+
+- entries sorted by `spec_id`; code + context links sorted (and deduped) by path
+- the ONLY non-determinism — the `updated` date — is **injected** by the caller (`nowIso`), so tests
+  are byte-stable and a re-run with the same clock produces byte-identical output
+- pure `buildIndexModel` (data → model, no I/O / no clock) + pure `renderIndex` (model → markdown)
+- the fs is an **injected `IndexIo` seam** (live binding = `node:fs`; tests inject an in-memory fake)
+- **fail-soft per entry:** a spec whose YAML fails to parse drops its own row rather than crashing the
+  whole regen
+
+## Owner + update points (orchestrator-owned — Fork C)
+
+The **orchestrator** owns `.mutagent/index.md` because it is the only layer that sees every ADL stage.
+It regenerates the file at each stage **finalize** — the per-stage skills emit the fields they own
+(into their `agentspec.yaml` / config), and the orchestrator re-runs `regenerateIndex` to re-link:
+
+| ADL stage | Finalize trigger | What the regen picks up |
+|---|---|---|
+| SPEC | `*spec` register | new `spec_id` · `spec_version` · `stage: spec` |
+| BUILD | `*build` finalize | `build.{target_framework, runtime}` · realized `code_refs` |
+| EVALUATE | `*evaluate` run-end | `loop_state.last_verdict` |
+| DIAGNOSE | `*diagnose` finalize | (findings link — future; still high-level, link only) |
+| IMPROVE | `*improve` finalize | re-linked impl paths after the fix |
+
+Because the writer is a full regenerate (not an incremental patch), each finalize simply calls
+`regenerateIndex` — the file always reflects the current on-disk truth. The orchestrator wires this
+step into `orchestrator.md` / the orchestrator-protocol (owned by the orchestrator lane — NOT edited
+from here).
+
+## CLI
+
+```bash
+# Regenerate the index for the resolved (or supplied) `.mutagent/` install root.
+bun run scripts/index/build-index.ts [root] [--now <ISO8601>]
+```
+
+`--now` pins the clock (deterministic scripting / reproducing a stamp); default is the wall clock.