session-orchestrator 3.22.0 → 3.24.0

package/skills/journey-audit/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: journey-audit
+description: >
+  Use this skill when the user wants the PRODUCT audited from the outside in — what the website
+  promises vs what the code does vs what a real user experiences vs what actually arrives by mail
+  vs what the data says is used. Runs a 7-role read-only wave (R5 writes only under an explicit
+  SAFETY block) against a per-repo `.orchestrator/journey-manifest.md` and writes a dossier to
+  docs/audits/. Distinct from /discovery, which checks code quality inside-out — this checks
+  product truth outside-in; they complement, neither replaces the other. Triggers "journey audit",
+  "Nutzersicht-Audit", "audit the product from the user's side", "/journey-audit".
+model: inherit
+color: purple
+tools: Read, Grep, Glob, Bash, Write, Task
+---
+
+# Journey Audit
+
+> Outside-in product audit as a repeatable deep session. Code review checks code against code;
+> this checks the product against the user's experience. Quarterly, never a CI component.
+
+## Purpose
+
+The most expensive defects of a consumer product's first run (session id redacted) — a core
+feature with no entry point anywhere in the UI, burned free quota, a plan gate that could be
+bypassed, a claim-vs-code contradiction, EUR copy in a USD context — are **invisible to every
+code-centric check**. They are not bugs in a function; they are gaps between five surfaces —
+marketing copy, code constants, live UI, outbound mail, real usage data — that no single
+surface can reveal.
+
+This skill dispatches seven roles that each own one surface, then makes the coordinator personally
+re-verify every P0 before it is written down. The re-verification is the value, not the fan-out:
+the first run caught 2 agent errors that way and confirmed 3 real P0s.
+
+## Phase 0: Gates
+
+### 0.1 Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. GATE_CLOSED → invoke
+`skills/bootstrap/SKILL.md` first. GATE_OPEN → continue.
+
+### 0.2 Manifest HARD-GATE
+
+<HARD-GATE>
+Read `.orchestrator/journey-manifest.md` in the target repo (or the path passed as `$ARGUMENTS`).
+
+**A — File missing or empty → REFUSE the whole run.** Say exactly this, then stop:
+
+> `/journey-audit` needs `.orchestrator/journey-manifest.md` in this repo and it is not there.
+> The audit is repo-specific: without personas, entry points, truth-SSOTs, the chat-interview key
+> and the SAFETY block, seven agents would invent their own definition of "correct" and every
+> finding would be unfalsifiable.
+> Copy the template — `templates/_shared/journey-manifest.md` in the session-orchestrator plugin —
+> to `.orchestrator/journey-manifest.md`, fill it in, then re-run `/journey-audit`.
+
+**B — Manifest present, `## SAFETY` heading absent or its body empty → REFUSE R5 ONLY.** R5 is the
+only role that touches production with a real account. Say:
+
+> The manifest has no filled `## SAFETY` block, so R5 (real end-to-end run against production) is
+> NOT dispatched. Running as dry-run: R1–R4 + R7 (R6 additionally needs the read-only DB
+> credentials named in the manifest). Fill in allowed accounts/events, no-go actions, the checkout
+> limit and the cleanup rule to enable R5.
+
+Do NOT infer a SAFETY block from other sections, do NOT ask the operator to dictate one into chat,
+do NOT dispatch R5 "read-only, just this once". A production write without a written, committed
+safety envelope is the one thing this skill never does.
+</HARD-GATE>
+
+Both gates are cheap and mechanical:
+
+```bash
+MANIFEST="${1:-.orchestrator/journey-manifest.md}"
+[ -s "$MANIFEST" ] || { echo "GATE-A: no manifest"; exit 1; }
+awk '/^## SAFETY/{f=1;next} /^## /{f=0} f&&NF{c++} END{exit c>0?0:1}' "$MANIFEST" \
+  || echo "GATE-B: SAFETY block absent or empty → R5 disabled"
+```
+
+### 0.3 Peer-session check (before dispatch, not after)
+
+Run `ListAgents` / read `.orchestrator/` session locks and check for peer sessions in this working
+copy per `.claude/rules/parallel-sessions.md`. A journey audit reads wide and R5 writes to
+production — a peer holding the same files must know before the wave starts, not from the diff.
+Announce the audit and the file scope you will touch; the audit itself claims almost no write
+scope, which is exactly why it is easy to forget.
+
+## Phase 1: Read the manifest
+
+Parse the manifest into `$MANIFEST` and derive per-role inputs. Every role prompt below is filled
+from these fields — an empty field is reported to the operator, never guessed:
+
+`personas` · `entry_points` · `truth_ssots` · `touchpoints` (template dir, send path, cron sources,
+render idiom) · `chat_interview` (question → expected answer → SSOT) · `safety` · `credentials`
+(env-var NAMES) · `realdata_queries` · `platform_expectation` · `known_exceptions`.
+
+## Phase 2: The wave — R1–R7
+
+All roles are **read-only** except R5. All run in parallel in one wave; none depends on another's
+output (the coordinator, not an agent, joins their findings).
+
+| R | Rolle | Generisch | Aus dem Manifest |
+|---|-------|-----------|------------------|
+| R1 | Flow-Zensus | Trigger→Empfänger→Zeitpunkt→Dedupe map of every outbound touchpoint (mail/push/webhook) | Template dir, send path, cron sources |
+| R2 | Artefakt-Rendering | Render templates to HTML, screenshots desktop/mobile/dark, consistency matrix | Render idiom, example props |
+| R3 | Claim-vs-Code-Matrix | Every marketing/FAQ/chat claim against the SSOT constants; feature inventory × surfaces | SSOT files, i18n namespaces, chat fact source |
+| R4 | Anonymer Live-Rundgang | agent-browser desktop+mobile, chat interview against the truth key, dead links, console | Route list, chat questions + expected answers |
+| R5 | Echter E2E-Durchstich | Prod, real account, actually execute each core flow, DB counter-check, mail-log reconciliation | **SAFETY block (mandatory)** |
+| R6 | Realdaten-Funnel | Usage funnel, never-fired flows, delivery defects, name what is not measurable | Read-only DB access, identity rules, mail-provider API |
+| R7 | Plattform-Ausnutzung | Self-built vs platform matrix (hosting/DB/realtime/queues/CDN/WAF), limits at 10× | CLI logins, expected plan, open perf issues |
+
+### Shared prompt preamble (prepend to every role)
+
+> You are role `<R#>` of a journey audit of `<repo>`. Manifest: `.orchestrator/journey-manifest.md`
+> — read it first; it is your only definition of "correct". You are **read-only**: no `Edit`, no
+> `Write` outside your own report, no git write operations (PSA-007), no production writes.
+> Every distributional claim ("all N routes", "no template does X") carries the executed command
+> and its output (PSA-006). A finding you cannot reproduce with a quoted command is a suspicion —
+> label it as one. Findings listed under `Bekannte Ausnahmen` in the manifest are reported as
+> `known-exception`, never as new. Severity: **P0** = money, data loss, or a core flow unreachable ·
+> **P1** = a broken flow or a UX dead end · **P2** = content/platform. Return the FULL report as
+> your last message.
+
+### Role prompt skeletons
+
+Each is self-contained; fill the `<…>` from `$MANIFEST`.
+
+**R1 — Flow-Zensus.** Inputs: template dir `<…>`, send path `<…>`, cron sources `<…>`.
+Task: enumerate every outbound touchpoint and produce one row per flow: trigger (code location) →
+recipient (which persona) → timing → dedupe/idempotency → is it reachable at all. Grep the send
+path for callers; a template with zero callers is a P1 finding, a caller with no dedupe on a
+money-relevant flow is P0. Output: Markdown table + a list of `never-fired` candidates with the
+grep that proves zero callers.
+
+**R2 — Artefakt-Rendering.** Inputs: render idiom `<…>`, example props `<…>`.
+Task: render every template found by R1's directory to HTML, screenshot desktop + mobile + dark,
+and build a consistency matrix (logo, sender, footer, legal block, CTA, language, currency).
+Output: matrix table + the artifact paths under `.orchestrator/journey-audit/<date>/`, plus every
+divergence as a finding. Do not fix a template; report it.
+
+**R3 — Claim-vs-Code-Matrix.** Inputs: SSOT files `<…>`, i18n namespaces `<…>`, chat fact source `<…>`.
+Task: extract every quantitative or capability claim from marketing pages, FAQ, pricing, chat facts
+and mail copy; compare each against the SSOT constant. One row: claim · where it is said · SSOT
+value · verdict (`match` / `drift` / `unbacked`). Then a feature inventory × surfaces grid: a
+feature that exists in code but appears on no surface is a P0 candidate ("no entry point").
+**i18n files are owned by R3 alone** — no other role opens them.
+Output: two tables + findings.
+
+**R4 — Anonymer Live-Rundgang.** Inputs: route list `<…>`, chat questions + expected answers `<…>`.
+Task: `agent-browser`, logged OUT, desktop and mobile viewport. Walk every route: dead links,
+console errors, layout breaks, CTA that goes nowhere. Then run the chat interview verbatim and
+score each answer against the expected answer from the manifest (`match` / `drift` / `refused` /
+`hallucinated`). Output: route table (status, console, findings), interview table, screenshots.
+Read-only: never submit a form that creates data, never sign up.
+
+**R5 — Echter E2E-Durchstich.** Inputs: SAFETY block `<…>`, credentials by env-var NAME `<…>`.
+Task: with the allowed account only, actually execute each core flow end to end in production;
+counter-check in the DB read-only that the expected records exist; reconcile against the mail log.
+**Before every step, re-read the SAFETY block and state which rule permits this step.** Stop at the
+first no-go, do not improvise around a block, honour the checkout limit exactly, and run the
+cleanup rule at the end and prove it ran. Output: per-flow trace (step → observed → expected →
+verdict), the DB counter-check output, the cleanup proof.
+
+**R6 — Realdaten-Funnel.** Inputs: read-only queries `<…>`, identity rules `<…>`, mail-provider API `<…>`.
+Task: run the manifest's `SELECT`s only. Build the funnel per persona, list flows that never fired
+in production, and pull delivery defects from the mail provider (bounces, suppressions, a
+permanently silenced owner address). Then name explicitly what the data CANNOT answer — an unnamed
+blind spot reads as a zero. Output: funnel table, never-fired list, delivery-defect list,
+`not-measurable` list. No writes, no schema changes, no query outside the manifest.
+
+**R7 — Plattform-Ausnutzung.** Inputs: CLI logins `<…>`, expected plan/tier `<…>`, open perf issues `<…>`.
+Task: self-built vs platform matrix across hosting, DB, realtime, queues, CDN, WAF, cron, mail:
+what does the repo hand-roll that the paid platform already provides, and what breaks at 10× today's
+load (quote the actual limit from the provider CLI/API, not from memory). Output: matrix
+(capability · self-built? · platform feature · effort to switch · limit at 10×) + findings.
+
+## Phase 3: Koordinator-Disziplin
+
+Numbered MUSTs. This phase is the skill; the wave is only its input.
+
+1. **Every P0 claim is re-verified by the coordinator, individually, with its OWN grep/curl/DB read,
+   before it enters the dossier.** Not "the agent quoted a command" — you run one yourself, and the
+   dossier carries YOUR command and output. An unreproduced P0 is downgraded to P1 with the note
+   `agent claim, not reproduced`, or dropped. First run: 2 of 5 P0 claims were agent errors
+   ("instantly unreachable" — it was selectable in the UI; "USD on prod" — a session artifact).
+2. **A finding is attributed.** Every dossier row names the role that found it and the command that
+   proves it — the reader must be able to re-run it without asking anyone.
+3. **i18n files are owned by exactly ONE agent (R3).** They were the known contention point in the
+   first run: many roles want to quote them, and a second reader turns into a second writer the
+   moment a fix is suggested. Same rule for any other file two roles both want.
+4. **Peer-session check before the wave starts** (Phase 0.3), not after the diff.
+5. **The coordinator never lets an agent write the dossier.** Agents return reports; the joining,
+   de-duplication and severity decision are the coordinator's, because contradictions between two
+   agents are only visible in one place.
+6. **Contradictions are reported as contradictions.** Two roles disagreeing is a finding about the
+   product, not a merge conflict to smooth over.
+7. **No fixes during the audit.** Findings only. The fix wave is Phase 5 and is a separate decision.
+
+## Phase 4: Dossier
+
+Write `docs/audits/YYYY-MM-DD-user-journey-audit.md` with this fixed section order:
+
+1. `## P0 — Geld & Kern-Flows` (each: symptom · evidence (coordinator's own command + output) ·
+   impact · suggested fix · role)
+2. `## P1 — Flows`
+3. `## P1 — UX`
+4. `## P2 — Inhalt`
+5. `## P2 — Plattform`
+6. `## Realdaten` (funnel, never-fired flows, delivery defects, explicitly not-measurable)
+7. `## Marketing-Hebel` (what the product does well and says nowhere)
+
+Header carries: date, repo, HEAD SHA, roles dispatched (and which were skipped, with the reason —
+"R5 skipped: no SAFETY block" is a result, not a gap), manifest path, artifact directory.
+
+## Phase 5: Closing AskUserQuestion
+
+One `AskUserQuestion` call, per `.claude/rules/ask-via-tool.md` (option 1 `(Recommended)`, every
+description carries reason + cost + consequence, `header` ≤ 12 codepoints):
+
+```
+AskUserQuestion({ questions: [
+  { question: "Which fix packages should the follow-up wave carry?",
+    header: "Fix-Wellen", multiSelect: true,
+    options: [
+      { label: "P0 money+core (Recommended)", description: "The <N> P0s I re-verified myself. Blocks revenue/core flow today; ~<X>h; freezes nothing else." },
+      { label: "P1 flows",  description: "<N> broken/undedupliced flows. ~<X>h; needs the R1 map as input." },
+      { label: "P1 UX",     description: "<N> dead ends. Cheap individually, touches i18n — one owner." },
+      { label: "P2 content+platform", description: "<N> items. No user impact today; do in cooldown." } ] },
+  { question: "Create issues for the selected packages?",
+    header: "Issues", multiSelect: false,
+    options: [
+      { label: "Yes, batch now (Recommended)", description: "One issue per finding via gitlab-ops; labels priority::critical|high|medium + area:* + type:bug/feature. ~<N> issues; respects issue-budget." },
+      { label: "Dossier only", description: "No issues; the dossier stays the record. Choose when the backlog is already over budget." } ] } ] })
+```
+
+Issue creation follows `skills/gitlab-ops/SKILL.md` § Label Taxonomy: `priority::critical` for P0,
+`priority::high` for P1, `priority::medium` for P2, plus the repo's `area:` and `type:` axes. Each
+issue links back to the dossier section that produced it.
+
+## Offload note (R6/R7)
+
+R6 and R7 are pure CLI/API roles — no browser, no repo writes — so they can run headless on a
+second machine (`claude -p "<prompt>"`, see the `m5-offload` skill). Two rules from the first run,
+both learned the hard way:
+
+- **`claude -p` prints only the LAST message.** The prompt MUST end with: *"Return the complete
+  report in your last message — not a summary, not a pointer to a file. Nothing you say before the
+  last message will be read."*
+- **No background processes.** The prompt MUST forbid `&`, `run_in_background`, and any "I'll keep
+  it running" pattern: the process is killed when `-p` returns, and a half-finished role looks
+  identical to a clean one.
+
+## Cadence & Abgrenzung
+
+- **Quarterly, or after a large feature drop.** Deliberately **not a CI component** — it is
+  expensive and judgment-heavy, and a judgment-heavy gate that runs on every pipeline becomes a
+  rubber stamp.
+- **Optional monthly light variant:** R3 + R4 only, as a scheduled cloud session.
+- **vs `/discovery`:** discovery checks code quality inside-out (probes over the tree);
+  journey-audit checks product truth outside-in (five user-facing surfaces against each other).
+  Neither replaces the other; a repo needs both.
+- **Follow-through:** after each run, freeze the mechanizable parts per repo — a `report:*` script,
+  a claim-drift test pinned to the SSOT constant — so the next run is cheaper. The audit's job is
+  to find what no test knows how to look for yet.
+
+## Anti-Patterns
+
+- Dispatching R5 without a SAFETY block "because the operator said it's fine in chat" — the block
+  is a committed artifact for a reason.
+- Copying an agent's P0 into the dossier because its command looked convincing (Phase 3.1).
+- Two roles both editing/owning the i18n files (Phase 3.3).
+- Running the audit as a CI job to "keep it honest" — it turns into a stamp nobody reads.
+- Fixing findings mid-audit, so the later roles measure a moving product.

package/skills/peekaboo-driver/SKILL.md

@@ -156,11 +156,15 @@ For SwiftUI 26+ targets (projects with `Package.swift` declaring `.iOS("26")` or
 ```bash
 # Gate: glass-modifiers emit is opt-in per the active profile's rubric_features flag (v1 rubric does not consume).
 PROFILES_FILE=".orchestrator/policy/test-profiles.json"
-HAS_GLASS_V2="false"
+HAS_GLASS_V2="false"   # preconditions unmet (no PROFILE / no file / no jq) = feature not requested
 if [ -n "${PROFILE:-}" ] && [ -f "$PROFILES_FILE" ] && command -v jq >/dev/null 2>&1; then
-  HAS_GLASS_V2=$(jq -r --arg p "$PROFILE" '(.[$p].rubric_features // []) | contains(["glass-v2"])' "$PROFILES_FILE" 2>/dev/null || echo false)
+  # Fallback is `unknown`, NOT `false`: false is jq's legitimate "feature off" answer,
+  # so a jq crash on a malformed profiles file would read as a deliberate opt-out.
+  HAS_GLASS_V2=$(jq -r --arg p "$PROFILE" '(.[$p].rubric_features // []) | contains(["glass-v2"])' "$PROFILES_FILE" 2>/dev/null || echo unknown)
 fi
-if [ "$HAS_GLASS_V2" = "true" ]; then
+if [ "$HAS_GLASS_V2" = "unknown" ]; then
+  echo "WARN: glass-v2 probe failed (jq could not read $PROFILES_FILE) — no conformance artifact emitted" >&2
+elif [ "$HAS_GLASS_V2" = "true" ]; then
   cat > "${RUN_DIR}/ax-snapshots/glass-modifiers-$(date +%s%3N).json" <<EOF
 {
   "schema_version": "v1",
@@ -175,6 +179,14 @@ EOF
 fi
 ```
 
+`HAS_GLASS_V2` has **three** states, and the third is the reason the fallback is not `false`:
+
+| Value | Meaning | Driver action |
+|---|---|---|
+| `true` | The active profile lists `glass-v2` in `rubric_features` | Emit the conformance artifact |
+| `false` | The profile does not list it — a real answer from a readable file, or preconditions unmet (no `PROFILE`, no profiles file, no `jq`) | Skip the artifact silently |
+| `unknown` | The probe itself failed — `jq` could not read/parse `$PROFILES_FILE` | WARN on stderr, skip the artifact. **Never** collapsed into `false`: a crashed probe is not an opt-out, and ux-evaluator Check 4 would otherwise report screenshot-only fallback as if the profile had chosen it |
+
 The ux-evaluator Check 4 reads this file. `glassEffect_frames` = compliant (uses `.glassEffect()`). `legacy_material_frames` = non-compliant (uses `.background(.thinMaterial)` etc.). `blur_modifier_frames` = non-compliant (uses `.blur(radius:)` as background). In v1 the arrays are always empty — the evaluator falls back to screenshot-only analysis. Do NOT emit a bare `{}` — use the full schema structure with empty arrays.
 
 ## Composability Contract

package/skills/persona-panel/SKILL.md

@@ -334,7 +334,7 @@ result. If `final_verdict == "warn"`: exit 0 with a warning line on stderr. If
 - **NEVER** dispatch more than 20 personas per panel (security M2 cap).
 - **NEVER** write a sidecar that fails schema validation — validate BEFORE write (security M3).
 - **NEVER** skip `validatePathInsideProject` for the target path OR the sidecar output path (H1).
-- **NEVER** use `run_in_background: true` for persona agents — lose coordination ability.
+- **NEVER** use `run_in_background: true` for persona agents — the panel synthesis needs every reviewer's findings before Phase 4; background dispatch would add turn-juggling with no consumer for early results.
 - **ALWAYS** validate `model:` fields from the catalog against `MODEL_ID_RE` + aliases (H2).
 - **ALWAYS** run `output_contract` structural pre-check before `ajv.compile()` (H3).
 - **ALWAYS** emit the `aggregator_warning` to BOTH stderr and sidecar when using

package/skills/reconcile/SKILL.md

@@ -122,12 +122,43 @@ fi
 Resolve `$PLUGIN_ROOT` per `skills/_shared/config-reading.md` (the standard resolution chain:
 `$CLAUDE_PLUGIN_ROOT` → `$CODEX_PLUGIN_ROOT` → `$CURSOR_RULES_DIR` → common install locations).
 
-### 2.2 Invoke `runReconcile`
+### 2.2 Resolve the Effective Write-Targets
+
+`reconcile.targets` says WHERE approved rules land. Resolve it BEFORE surfacing
+the approval AUQ — the operator must never be asked to approve a write to a
+destination that cannot exist:
 
 ```javascript
-import { runReconcile } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
+import { resolveEffectiveTargets } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
+
+const { targets, baselineRoot, dropped, reason } = resolveEffectiveTargets({
+  targets: CONFIG.reconcile?.targets,        // ['repo-local'] | ['baseline'] | both
+  baselineRoot: CONFIG['plan-baseline-path'], // already 3-tier-resolved by config.mjs
+});
+```
+
+| Target | Writes to | Root |
+|---|---|---|
+| `repo-local` (default) | `<repoRoot>/.claude/rules/<slug>.md` | `repoRoot` |
+| `baseline` (#1099) | `<baselineRoot>/proposals/<slug>.md` | `plan-baseline-path`, resolved `SO_BASELINE_PATH` env > `owner.yaml` `paths.baseline-path` > committed |
+
+`baseline` is DROPPED (with one stderr WARN, and `dropped: ['baseline']` in the
+return) when the root is unresolvable on all three tiers, is still the committed
+`OVERRIDE-IN-…` placeholder, or is not absolute. A dropped target means: do not
+surface its proposals in the AUQ at all. If `targets` comes back EMPTY, stop
+here and report the `reason` — there is nowhere to write.
 
-const { proposals, rejected, summary, error } = await runReconcile({
+Writing to `baseline` is still advisory and AUQ-gated exactly like `repo-local`:
+files land under `proposals/` in the baseline checkout, nothing is committed
+there, and no branch is touched. The operator reviews and commits in that repo
+himself.
+
+### 2.3 Invoke `runReconcile`
+
+```javascript
+import { runReconcileFromSkill } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
+
+const { proposals, rejected, summary, error } = await runReconcileFromSkill({
   repoRoot,             // absolute path from git rev-parse --show-toplevel
   ruleExpiryDays: RULE_EXPIRY_DAYS,   // empty → undefined → engine per-type TTL
   minRuleDays: MIN_RULE_DAYS,         // default 7 — floors a near-dead expires-at
@@ -135,6 +166,9 @@ const { proposals, rejected, summary, error } = await runReconcile({
   maxProposalsPerRun: MAX_PROPOSALS_PER_RUN, // default 10 — volume brake (issue #900 D)
   now: new Date(),
   dryRun: DRY_RUN,     // true → engine touches no disk (no idempotency sidecar write)
+  // trigger is pinned to 'skill' IN CODE by runReconcileFromSkill (#1201 Part A) —
+  // this prose block no longer sets it.
+  targets,             // from resolveEffectiveTargets above; recorded when non-empty, omitted otherwise
 });
 
 // The engine does NOT apply a confidence floor — it proposes every eligible
@@ -282,12 +316,21 @@ const { written, archived, errors } = await writeApprovedRules({
   approved: approved,             // proposals the operator approved
   rejected: rejected_by_operator, // proposals the operator declined
   repoRoot,
+  baselineRoot,                   // from Phase 2.2; omit/undefined ⇒ baseline is a no-op
+  targets,                        // from Phase 2.2; omitted ⇒ ['repo-local']
   sessionId: currentSessionId,    // informational; from STATE.md or 'manual'
 });
 ```
 
 `writeApprovedRules` NEVER throws — per-item failures are collected in `errors[]`.
 
+`written` is a FILE count, not a proposal count: one proposal approved with both
+targets in effect writes two files and counts 2, while stamping the idempotency
+sidecar exactly once. A baseline root that does not exist on disk (the
+fresh-clone / CI case) skips that target with an `errors[]` entry — it is NEVER
+created, because a typo'd path that silently mints a directory tree looks
+exactly like a successful write.
+
 ### 6.2 Handle Errors
 
 If `errors.length > 0`, surface each error to the operator:

package/skills/remote-offload/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: remote-offload
+user-invocable: false
+tags: [reference, remote, offload, wave-executor, resource-gate]
+model: haiku
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+description: Use when local resource pressure would shrink or coordinator-direct a wave, a wave plan carries heavy build/test/audit roles (test, ui, perf), or the operator says offload, remote host, or auslagern — reference for routing that wave role to a declared SSH-reachable host instead of reducing agent count
+---
+
+# Remote Offload — routing a wave role to a declared host instead of shrinking it
+
+Repo-side half of #1160: `remote-hosts:` declares hosts, `wave-resource-gate.mjs` places work on them, `remote-dispatch.mjs` runs it. The host-side `offload` CLI (a separate baseline repo owns its SSOT) is invoked as a subprocess; this skill covers what the repo itself knows about it.
+
+## Quick reference
+
+| Task | Command |
+|---|---|
+| Host readiness | `offload doctor -H <alias> --brief` |
+| Gate (typecheck/lint/test) | `offload gate <repo> -H <alias>` |
+| Run a command | `offload run <repo> -H <alias> -- <cmd...>` |
+| Read-only analysis | `offload claude <repo> -H <alias> --model <name> < prompt.txt` |
+| Implementation + patch | `offload claude <repo> -H <alias> --write --patch <path> < prompt.txt` |
+| Remove finished jobs | `offload clean -H <alias> --older-than <hours>` |
+
+Exit codes (`offload --help`, measured 2026-09-02): `0` ok · `1` usage/config · `2` host unreachable/not ready · `3` remote command failed · `4` sync failed · `5` timeout · `6` empty diff on a `--write` run · `7` account quota exhausted (429) · `8` write lock held. Same map as `OFFLOAD_EXIT_REASONS` in `scripts/lib/wave-executor/remote-dispatch.mjs`.
+
+## 1. Decision rule — offload vs reduce
+
+The gate decides, not the coordinator. `applyOffloadDecision()` in `scripts/lib/wave-resource-gate.mjs` only fires when the resource verdict is already `reduce` or `coordinator-direct`, and only AFTER the HR-004 heavy-repo cap — a capped wave that offloads still respects the cap. It never probes the network; the coordinator supplies a readiness WITNESS:
+
+- `opts.remoteReady` — `{ [alias]: boolean }`, built from the SessionStart banner line `Offload <alias>: ready=yes …`, or
+- `opts.probeFn` — an async `(alias) => boolean` fallback, consulted only for aliases `remoteReady` doesn't answer for (backed by `remoteDoctor()`, i.e. `offload doctor -H <alias> --brief` parsed by `parseDoctorLine()`).
+
+With neither supplied, no host counts as ready and the wave stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/foreign-dispatch.mjs`: `impl-core`, `security-review`, `migration`, `release`, `secrets`) is never offloaded regardless of readiness.
+
+## 2. What is declared where
+
+`remote-hosts:` in Session Config (`docs/session-config-reference.md` § Remote Hosts) declares the hosts, in preference order — the gate takes the FIRST host whose `roles-allowed` accepts the wave role and is witnessed ready:
+
+```yaml
+remote-hosts:
+  - alias: <ssh-alias>                 # required, SAFE slug; reaches argv as `-H <alias>`
+    roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
+    repo-path: ~/path/on/host          # optional; SAFE path; default null
+    claude-path: ~/.local/bin/claude   # optional; SAFE path; default null
+```
+
+Two enums meet here and must not be conflated: `roles-allowed` holds `agent-mapping` roles (`test`/`ui`/`perf`), not wave roles (`Impl-Core`/`Quality`/…). The translation table is `OFFLOADABLE_WAVE_ROLES` in `wave-resource-gate.mjs` (`quality`→`test`, `test`→`test`, `ui`→`ui`, `perf`→`perf`; a wave role absent from that map stays local by default).
+
+An `agent-mapping` entry of the form `<role>: ssh:<alias>` routes that wave role to Claude running ON the declared host instead of shrinking the wave; the alias must already exist under `remote-hosts`, or the config parse throws.
+
+## 3. Three channels of work
+
+| Channel | Command | Verdict rule |
+|---|---|---|
+| Gate / arbitrary command | `offload gate` / `offload run` | Exit code decides — use the table above, never the prose in the run's own output |
+| Implementation, patch back | `offload claude --write --patch <file>` via `dispatchRemote()` | Empty patch (exit `6`) is a FAILURE regardless of what the run reports; the coordinator READS the patch, then applies it with its own `git apply` — the remote job never touches the repo the coordinator commits from |
+| Read-only analysis | `offload claude` (no `--write`) | No patch is produced; treat the transcript as advisory input, same skepticism as any reviewer output (`receiving-review.md`) |
+
+`dispatchRemote()` (`scripts/lib/wave-executor/remote-dispatch.mjs`) is the wave-executor caller for the second and third channels; it emits `orchestrator.remote_dispatch.completed` once per call (`docs/events-schema.md`) — the only ledger record a remote dispatch produces, since a Bash-spawned `offload` child fires no `SubagentStop` hook. Payload: `host`, `role`, `run_id`, `ok`, `exit_code`, `duration_ms`, `patch_files`, `patch_bytes`, `reason` (present on every refusal and every failure class — absence means success). Deliberately excluded from the payload: prompt text, patch body, `patch_path`.
+
+## 4. Rules
+
+- **Supervised, not blind.** Read the gate log or the patch before treating it as a result — completed and correct are not the same claim.
+- **Prompt travels on stdin, never argv** (`offload --help`: "prompts travel by file (mode 600), never argv"; argv is visible to every process on the host).
+- **The patch is READ, then applied by the coordinator** — never inside the offloaded job.
+- **`never_foreign` roles are never offloaded** — checked first in `dispatchRemote()`, before any spawn or side effect.
+- **One `--job` per concurrent run.** A job holds ONE set of run artefacts; two parallel runs sharing a job collided until per-run ids were introduced.
+- **Rate-limit (exit `7`) carries the reset time in the message** — do not retry blind.
+- **Secrets never in output** (SEC-008) — `offload` does not print credentials, and the module deliberately excludes prompt text and patch body from telemetry.
+- **Never "clean up" another checkout on the host.** `offload clean` only removes the offload tool's OWN finished job worktrees, never a host's other active checkouts.
+
+## 5. Host readiness checklist
+
+- SSH alias configured with key auth (no password/interactive prompt on connect).
+- `tmux` available on the host (for an interactive `offload session`).
+- Claude authenticated ON the host — never copy OAuth credentials between machines (refresh-token rotation invalidates the source copy); log in fresh with `/login` there instead.
+- Repo cloned on the host with headless git credentials configured (no interactive auth prompt on push/pull).
+- Node version matching this repo's `.nvmrc`.
+- Toolchain parity with the local checkout (same package manager, same lockfile).
+
+## 6. Pitfalls measured in this repo
+
+- **The pre-push quality gate used to fire on the sync push.** `.husky/pre-push` (#C10) detects a SCRATCH push — an unconfigured remote URL, e.g. the offload tool's own SSH sync target — and skips the gate for it; publish remotes (`origin`, `github`) stay gated regardless. The offload tool has since been fixed upstream to push with `--no-verify` itself, so this repo-side detection is defense-in-depth, not the primary fix.
+- **The host installer must follow this repo's committed lockfile.** `package-lock.json` is tracked here (npm-canonical — `.claude/rules/development.md` § Package Management); install with `npm ci`, never a different package manager's install command, or the host checkout's `node_modules` layout diverges from CI's.
+- **A linked worktree makes `.git` a file, not a directory.** 13 tracked files used to be flagged as "not in repository" in an unmodified worktree at the same layout, because the file form of `.git` was read as an untracked candidate rather than the repository marker — wave 3 fixed `scripts/lib/validate/check-untracked-test-deps.mjs` to treat a `.git` FILE as the repository marker in a linked worktree; the remote gate then ran 15,829/0.
+- **Keychain-route auth shares the host account's usage window with that account's other interactive sessions**, not a dedicated quota — a token-slot profile (`--via slot`) avoids the sharing where a fixed quota matters.

package/skills/session-end/SKILL.md

@@ -843,7 +843,12 @@ Auto-promoted sibling worktrees are created by `enterWorktree()` during the Phas
 
 > **Authoritative impl:** `scripts/lib/session-end/worktree-cleanup.mjs` — `detectAutoPromotedWorktree(repoRoot, sessionId, opts)`. Import and call; do NOT re-implement from this doc.
 >
-> Algorithm: parse `sessionId` via `parseSessionId()`; return `null` immediately for UUID-format sessions (never auto-promoted). Derive the MAIN checkout root from the first `worktree ` entry of `git worktree list --porcelain` (NOT `path.basename(repoRoot)` — the promoted worktree's basename IS the comparison target). If `repoRoot` resolves to the main checkout, return `null`. Otherwise compare `path.basename(repoRoot)` against `<main-repo-name>-<sessionId>`; on match return `{ wtPath, sessionId, branch }`, else `null`. All git invocation is via the injection-safe `opts.execFileFn` (default `execFileSync` with an args array — #577 HARDEN-001).
+> Two keys, tried in this order:
+>
+> 1. **Marker (primary).** Reads `<repoRoot>/.orchestrator/promoted-from.json` (`PROMOTION_MARKER_RELPATH`), written by `enterWorktree()` at creation time with `branch`, `source_session_id`, `source_root_hash`, `source_root_basename`, `promoted_at`. Accepted when the file parses, carries a non-empty `branch` + `source_session_id`, and the worktree's current branch (`git branch --show-current`) either matches the recorded one or cannot be read at all — an unverifiable branch never triggers auto-removal by itself, since that is gated separately by `isWorktreeClean()`, which fails closed on any git error. On match returns `{ wtPath, sessionId: marker.source_session_id, branch: marker.branch, source: 'marker' }`. This is the only key that survives the #1069 process boundary: since #1069 the session that RUNS in the promoted worktree is a brand-new session with its own id (see ADR-0013), so the current session's id appears in neither the worktree's directory name nor its branch — key 2 below can never match a #1069-promoted worktree.
+> 2. **Basename (legacy fallback).** Parse `sessionId` via `parseSessionId()`; return `null` immediately for UUID-format sessions (never auto-promoted). Derive the MAIN checkout root from the first `worktree ` entry of `git worktree list --porcelain` (NOT `path.basename(repoRoot)` — the promoted worktree's basename IS the comparison target). If `repoRoot` resolves to the main checkout, return `null`. Otherwise compare `path.basename(repoRoot)` against `<main-repo-name>-<sessionId>` (the CURRENT session id); on match return `{ wtPath, sessionId, branch: parsed.branch, source: 'basename' }` — still correct for worktrees created before the marker existed. Returns `null` on no match.
+>
+> All git invocation is via the injection-safe `opts.execFileFn` (default `execFileSync` with an args array — #577 HARDEN-001).
 
 ### Clean-check
 
@@ -855,7 +860,7 @@ A worktree is clean iff ALL three conditions hold:
 
 > **Authoritative impl:** `scripts/lib/session-end/worktree-cleanup.mjs` — `isWorktreeClean(wtPath, opts)`. Import and call; do NOT re-implement from this doc.
 >
-> Algorithm: run `git status --porcelain`; if non-empty → dirty (`false`). Else run `git status --short --branch`; if it matches `/\bahead\b/` → unpushed (`false`). Otherwise `true`. On ANY git error → `false` (conservative PSA-003 default: never auto-remove a worktree we could not verify). Git invocation is via the injection-safe `opts.execFileFn` (default `execFileSync` with an args array — #577 HARDEN-001).
+> Algorithm: run `git status --porcelain`; filter blank lines, then discount EXACTLY the one untracked line the promotion marker itself produces (`?? .orchestrator/promoted-from.json` — in a repo where `.orchestrator/` is only partly gitignored, or on a worktree whose branch predates the ignore line, the marker `enterWorktree()` writes would otherwise make every promoted worktree read "dirty"; a modified/staged/renamed/conflicted marker still counts as dirty). If any lines remain → dirty (`false`). Else run `git status --short --branch`; if it matches `/\bahead\b/` → unpushed (`false`). Otherwise `true`. On ANY git error → `false` (conservative PSA-003 default: never auto-remove a worktree we could not verify). Git invocation is via the injection-safe `opts.execFileFn` (default `execFileSync` with an args array — #577 HARDEN-001).
 
 ### Clean path: auto-remove + WARN (PRD §3 P3 Gherkin row 2)
 
@@ -1032,7 +1037,7 @@ if (sweep) {
 
      Fail-open: a `markOpenQuestionAnsweredOnDisk` failure is non-fatal — log a WARN and proceed with the close; the question simply stays `- [ ]` and roundtrips to the next session.
 
-3b. **Drain the issue-budget overflow — exactly ONE collector artefact (issue-budget):** when `.orchestrator/runtime/issue-budget.json` has a non-empty `overflow[]`, the session hit its `issue-budget.max-per-session` cap and every over-cap creation was PARKED rather than filed. Fold the whole list into a single artefact so nothing is silently dropped.
+3b. **Drain the issue-budget overflow — exactly ONE collector artefact (issue-budget):** when this session's budget file (`budgetStatePath(repoRoot, accountingSessionId)` → `.orchestrator/runtime/issue-budget/<hash>.json`, #1141) has a non-empty `overflow[]`, the session hit its `issue-budget.max-per-session` cap and every over-cap creation was PARKED rather than filed. Fold the whole list into a single artefact so nothing is silently dropped.
 
     **Ordering (load-bearing):** run this as the LAST issue-creating action of Phase 5 — after step 3, after "Discovery Issue Creation", after step 4 — and re-read the counter file at that moment. Those steps can themselves push new entries into `overflow[]`; draining early would leave them unfiled.
 
@@ -1072,6 +1077,14 @@ if (sweep) {
     - After the artefact exists, reset `overflow` to `[]` in the counter file and record the collector issue ID / note path in the Phase 6 Final Report under `### Zurückgestellt (issue-budget)`.
     - **Never exempt-by-accident:** the cap never applied to `priority::critical`, the carryover class (`[Carryover]`, SPIRAL/FAILED, `type::carryover`), or `broken-window` closure issues, so nothing on the Phase 1.65 carry-list can ever appear in `overflow[]`. The promises at Phase 1.8 ("SPIRAL / FAILED agent carryover … non-deselectable") and the Critical Rule "ALWAYS create issues for unfinished PLANNED work" stay intact by construction.
     - Fail-open: a missing or malformed counter file means "no overflow" — log a WARN and continue the close.
+    - **Then reap stale counter files (#1151):** the per-session split (#1141) writes one file per accounting session and nothing ever deleted them, so `.orchestrator/runtime/issue-budget/` grew without bound in every working copy. After the drain, sweep files older than 14 days; THIS session's file is exempt regardless of age, and the call is best-effort (it never throws, so it can never abort the close).
+
+      ```js
+      import { reapStaleBudgetFiles } from '${PLUGIN_ROOT}/scripts/lib/issue-budget.mjs';
+
+      const { removed } = reapStaleBudgetFiles({ repoRoot, sessionId: accountingSessionId });
+      if (removed.length) console.log(`issue-budget: reaped ${removed.length} stale counter file(s) (> 14 d)`);
+      ```
 
 #### Discovery Issue Creation (if discovery ran in Phase 1.5)
 
@@ -1161,7 +1174,7 @@ Present to the user:
 | `learning-patterns.md` | Phases 3.5a + 3.6 extraction heuristics, confidence updates, passive decay, and JSONL write procedure |
 | `phase-3-6-tail.md` | Phase 3.6.x tail — full unabridged detail procedures for all six tail phases: 3.6.3 Memory-Proposals Collection (`collectProposals` + AUQ multiSelect + `promoteAndClear`, composing `writeApproved` + `clearProposalsJsonl` behind a mechanical write-before-clear guard, #828), 3.6.4 Expired-Learnings Sweep (Epic #723 B4), 3.6.5 Auto-Dream nudge (`shouldDispatchAutoDream`, #614), 3.6.6 Skill-Applied Judge (#645 L3 — `runSkillJudge`, coordinator-writes), 3.6.7 Auto-Dialectic nudge (`shouldDispatchAutoDialectic`, #614), 3.6.8 Reconciliation Rule Proposals (#696 FA3 — `runReconcile` + AUQ + `writeApprovedRules`). Loaded on demand by the SKILL.md skip-plan dispatcher (#724) — only phases with `run: true` in the `planTailPhases()` plan execute |
 | `scripts/lib/session-end/phase-skip.mjs` | Phase 3.6.x tail skip-plan aggregator (#724) — `planTailPhases({repoRoot, config, sessionId, platform})` → `{plan, skippedReport}`; side-effect-free (reconcile/sweep via dry-run — no writes), never-throws (per-phase probe error fail-opens to `run: true`); wraps the six existing signal helpers with config gates first, then input detection |
-| (inline) Phase 3.45 | Telemetry Flush (advisory, #844) — `flush()` from `scripts/lib/telemetry/sync.mjs` drains the host-local send-queue fire-and-forget; no config key (send-gate is `resolveConsent()` inside the module, fail-closed); skip when `persistence: false`; never-throw + ~3s-bounded, offline → bounded oldest-dropped queue, optional `Telemetry: sent/queued/gated` close-summary line, NEVER an error banner; runs late in the close after Phase 3.7 |
+| (inline) Phase 3.45 | Telemetry Flush (advisory, #844; MECHANICAL since #1138 — `hooks/on-session-end.mjs` calls `flush()` itself at the end of every teardown and emits an `orchestrator.telemetry.flush` breadcrumb, so this phase is the DESCRIPTION and the fallback, never the trigger; a coordinator that skips it changes nothing) — `flush()` from `scripts/lib/telemetry/sync.mjs` drains the host-local send-queue fire-and-forget; no config key (send-gate is `resolveConsent()` inside the module, fail-closed); skip when `persistence: false`; never-throw + ~3s-bounded, offline → bounded oldest-dropped queue, optional `Telemetry: sent/queued/gated` close-summary line, NEVER an error banner; runs late in the close after Phase 3.7 |
 | `session-metrics-write.md` | Phase 3.7 JSONL append, vault-mirror invocation, durable narrative mirror (`mirrorNarrative`, #675), and behavior matrix |
 | `phase-3-7a-recommendations.md` | Phase 3.7a full procedural body — computeV0Recommendation call, STATE.md field write, data source guarantee, error mode |
 | `phase-3-7a-recommendations.md` § 3.7b | Phase 3.7b full procedural body — `withDurableCommit` invocation for `sessions.jsonl` + `STATE.md` (#490 AC2), `enabled:false` local no-op, autopilot.jsonl exclusion note |

package/skills/session-end/metrics-collection.md

@@ -36,7 +36,8 @@ Finalize session metrics by reading the wave data accumulated during execution:
    From the `stagnation` array, aggregate into `stagnation_events`:
    - `total`: count of entries in the array
    - `by_pattern`: count by `pattern` value (omit zero-valued keys)
-   - `by_error_class`: count by `error_class` value (omit zero-valued keys; omit entire sub-object if all entries lack `error_class`)
+   - `by_error_class`: count by `error_class` value (omit zero-valued keys; omit entire sub-object if all entries lack `error_class` — only `error-echo` records carry one)
+   - `by_source`: count by `source` value — `coordinator` (post-wave review) vs `tail` (the `wave-transcript-tail` monitor, #1114). Same rule: omit zero-valued keys; omit the entire sub-object when no entry carries `source` (pre-#1114 records do not).
    - `files`: unique list of non-null `file` values (deduplicated)
    - **Omit the entire `stagnation_events` field if `total == 0`** (keeps historical entries clean).
 
@@ -67,7 +68,7 @@ Finalize session metrics by reading the wave data accumulated during execution:
      total_agents: <N>,
      total_files_changed: <N>,
      agent_summary: {complete: <N>, partial: <N>, failed: <N>, spiral: <N>},
-     waves: [/* {wave, role, agent_count, files_changed, quality, planned_files_count?, over_delivery_ratio?} */],
+     waves: [/* {wave, role, agent_count, files_changed, quality, agent_count_planned?, agent_count_started?, agent_count_completed?, planned_files_count?, over_delivery_ratio?} */],
      // effectiveness is CONSTRUCTED EXPLICITLY (#773) — NOT left as an optional
      // field for the coordinator to remember. Leaving it optional is exactly how
      // the carryover=0 blind spot recurred (41/41 records read carryover:0).
@@ -110,7 +111,7 @@ Finalize session metrics by reading the wave data accumulated during execution:
      "total_files_changed": N,
      "agent_summary": {"complete": N, "partial": N, "failed": N, "spiral": N},
      "waves": [
-       {"wave": 1, "role": "Discovery", "agent_count": N, "files_changed": N, "quality": "pass|fail|skip", "planned_files_count": N, "over_delivery_ratio": 0.0},
+       {"wave": 1, "role": "Discovery", "agent_count": N, "files_changed": N, "quality": "pass|fail|skip", "agent_count_planned": N, "agent_count_started": N, "agent_count_completed": N, "planned_files_count": N, "over_delivery_ratio": 0.0},
        ...
      ],
      "discovery_stats": {
@@ -152,7 +153,8 @@ Finalize session metrics by reading the wave data accumulated during execution:
      },
      "stagnation_events": {
        "total": N,
-       "by_pattern": {"error-echo": N, "turn-key-repetition": N, "pagination-spiral": N},
+       "by_pattern": {"error-echo": N, "turn-key-repetition": N, "pagination-spiral": N, "psa007-git-write": N, "status-partial": N},
+       "by_source": {"coordinator": N, "tail": N},
        "by_error_class": {"edit-format-friction": N, "scope-denied": N, "command-blocked": N, "other": N},
        "files": ["<relative path>", "..."]
      }
@@ -168,6 +170,7 @@ Finalize session metrics by reading the wave data accumulated during execution:
 > - `review_stats`: populated ONLY when Phase 1.8 dispatched the session-reviewer agent AND it returned findings. Source: the session-reviewer's output summary.
 > - `effectiveness`: ALWAYS populated from Phase 1 plan verification results, and CONSTRUCTED EXPLICITLY in the METRICS_ENTRY snippet (#773) — never deferred to a "remember to add" optional step (that omission is how `carryover: 0` slipped past 41 records). `completion_rate` = `completed / planned_issues` (0.0-1.0, where 0.0 means nothing was completed). **`carryover` counting rule (#773):** `carryover` is the **length of the Phase 1.65 gate carry-list** — `autoCarry` ∪ the middle-band `ask` items the operator LEFT SELECTED ∪ the answered-question `impliesWork: true` candidates — NOT the raw Phase 1.2+1.3 candidate count. On the fail-open skip (gate disabled / headless / AUQ unavailable), EVERY candidate carries, so `carryover` = the full candidate-list length. Count the gate's OUTPUT (what reaches Phase 5 Step 3 filing), not its INPUT.
 > - `effectiveness.override_ratio` (#730/H5): OPTIONAL nested field = `overridden_findings / max(total_findings_surfaced, 1)` (float 0.0-1.0). Populate ONLY when Phase 2.6 (Broken-Window Budget) ran this session (`broken-window-budget.enabled: true`). OMIT (do NOT write null/0) otherwise — **absent = "not measured"**, `0.0` = "measured, nothing overridden". `overridden_findings` = the summed `count` of the `orchestrator.finding.overridden` events emitted this session; `total_findings_surfaced` = every MED/LOW+ finding surfaced across Phase 1.8 + wave reviewers.
+> - `waves[].agent_count_planned` / `waves[].agent_count_started` / `waves[].agent_count_completed` (#724/#1115): OPTIONAL per-wave fields, sourced from `wave-loop.md` § Capture wave metrics step 7 — mirror its definitions exactly, do not re-derive them here. `agent_count_planned` = agents named in the session plan for this wave. `agent_count_started` = distinct agents whose `agent-<id>.meta.json` sidecar is present, after any silent-drop re-dispatch — NOT "produced a tool-result" (under background dispatch the launch ack is a result and would count an agent that never ran). `agent_count_completed` = distinct agents whose task-notification (`<status>completed</status>`) arrived. Omit each field when the wave did not measure it — **absent = "not measured"**, never zero-fill; `0` would read as "measured, no agent started", which is the opposite of an unmeasured wave. The two gaps carry the diagnosis: `agent_count_planned > agent_count_started` after re-dispatch is a persistent silent drop, `agent_count_started > agent_count_completed` at wave end is an agent that started and never returned. Both are also logged to STATE.md `## Deviations` by wave-loop.md, so a record and a deviation entry should agree.
 > - `waves[].planned_files_count` / `waves[].over_delivery_ratio` (#730/H4): OPTIONAL per-wave fields, populated from STATE.md Wave History headers of the form `(planned <P> files → actual <A>, over-delivery <R>)` (written by wave-executor §3a since #730/H4); omit when absent (pre-#730 sessions / grounding-check: false).
 > - `waves[].suite_passed` / `waves[].suite_failed` / `waves[].suite_platform` (#944): OPTIONAL per-wave fields. Omit all three when absent — absent = "not measured", `suite_failed: 0` = "measured, zero failures".
 >   **`suite_passed` / `suite_failed`: read the event FIRST, the STATE.md header only as fallback (#966 step 3).** Since #954/#967 the between-waves gate wrapper `scripts/run-quality-gate.mjs` emits `orchestrator.quality_gate.{passed,failed}` with a machine-measured `counts: {passed, failed, total}` AND the `wave_number` it resolved from the `wave-scope.json` sidecar, so per-wave attribution needs no wall-clock window join. Payload fields are flat at the record's top level; for each wave `N` of this session: