projecta-rrr 1.21.9 → 1.22.0

package/CHANGELOG.md

@@ -4,6 +4,113 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.22.0] - 2026-04-19
+
+**Webhook Live Reindex + Dynamic Routing + Token Diet v2.**
+
+23 of 24 Active requirements shipped across 6 phases (80, 82–86); 1 deferred to v1.23 (TOK-04).
+
+### Added — Phase 80 (Webhook & Push Policy)
+
+- **App-level GitHub webhook** `POST /webhooks/github-app` — single URL fans out to all repos via `installation.id` lookup. Reuses HMAC + 3-layer dedup from v1.21 (both routes coexist).
+- **Migration `014-installations.sql`** — `installations(installation_id, team_id)` + `repos.github_repo_id` (PF-WEBH-01 rename-resilient routing).
+- **PUSH-POLICY in 10 RRR command lifecycle skills** (plan-phase, execute-plan, execute-phase, verify-work-on-pass, complete-milestone, new-milestone, add-phase, insert-phase, remove-phase, ship) — every commit auto-pushes.
+- **`rrr/lib/auto-push.js`** with `settings.rrr.auto_push` opt-out + non-fatal failure surfacing.
+- **`rrr/lib/hud/freshness-segment.js`** + `rrr/hosted-mcp/docs/freshness.md` onboarding.
+
+### Added — Phase 82 (Framework Hygiene)
+
+- **SUMMARY.md backfill** across 184 legacy plans (`scripts/backfill-summaries.js`); 175 appended canonical sections, 10 marked `legacy_exempt`.
+- **LINT-BLOCK-01** — `prepublish-check.js` §12/§13 WARN→BLOCK with 7-day grace.
+- **TEST-UNIFY-01** — consolidated on `node --test` (D-v1.22-04); jest-compat shim retained for legacy `__tests__/`.
+
+### Added — Phase 83 (Dynamic Routing Core)
+
+- **`hooks/model-router.js`** — PreToolUse hook rewrites `Task.model` per canonical tier map (Pattern A confirmed). Fail-OPEN; logs every dispatch to `~/.rrr/telemetry/escalations.jsonl`.
+- **`rrr/lib/router/{tier-map,detect-stage,load-settings}.js`** — composer + stage-aware (planning/execution/verification per-stage).
+- **`settings.rrr.model_router: "dynamic"`** opt-in (default `static` preserves v1.21 bit-for-bit; 13 fixture-replay regressions).
+- Installer wiring via `wireModelRouter()`.
+
+### Added — Phase 84 (Model Escalation)
+
+- **`rrr-debugger` iter-3+ → opus** + **`rrr-executor` 2nd-retry → opus** layered on `decideTier()`.
+- **`rrr/lib/state/{debug-session,executor-retry}.js`** atomic per-plan counters.
+- **`escalations.jsonl` schema v2** (`retry_count`, `prior_tier`); `docs/escalations-schema.md`.
+
+### Added — Phase 85 (Token Diet v2)
+
+- **`hooks/tool-disallow.js`** — PreToolUse BLOCK for stock Read/Grep/Glob on main thread (opt-in `settings.rrr.tok_disallow`; installer/subagent/env exemptions).
+- **`hooks/edit-batching-nudge.js`** — PostToolUse advisory on ≥2 same-file edits within 60s.
+- **`/rrr:savings`** + `scripts/rrr-savings.js` + `rrr/lib/savings/{index,hud-segment}.js` — session/lifetime token-reduction + tier distribution + Opus-rate dashboard.
+- **TOK-04 deferred to v1.23** (measurement gate: 0 observation JSONLs in-repo).
+
+### Added — Phase 86 (SHIP GATE)
+
+- **SHIP-01 PASS** — `boot-e2e-first-time-index.test.js` (closes v1.21.6–8 root cause) + folds dropped Phase 81 SRCH-01 cross-repo contamination assertion.
+- `scripts/bnch-02-redo.js` + 2 per-repo `queries.json` — Haiku hit-rate@5 measurement (deferred-operator).
+- `scripts/measure-token-delta.js` — three-number falsifiable comparator (`actual ≤ 0.80 × static_all_sonnet`).
+- `scripts/measure-opus-rate.js` — strict <15% gate.
+- `scripts/k6-cross-user-isolation.js` + `scripts/run-k6-isolation.sh` + `docs/v1.22-load-test.md` — multi-tenant RLS load test (deferred-operator).
+- 48 Phase 86 tests + 239 root suite + 30 hosted-mcp targeted, all green.
+
+### Added — Infrastructure
+
+- **`.planning/INFRA-STATE.md`** — authoritative deployed-infra snapshot. `CLAUDE.md` + `PROJECT.md` mandate reading it before flagging "operator-step".
+- **`scripts/snapshot-infra.js`** — Fly + Neon verification runner.
+
+### Changed
+
+- Phase 81 (Search Hardening) **dropped** — SRCH-01 already shipped in v1.21 76-03. Verification folded into Phase 86 SHIP-01.
+
+### Deferred to v1.23
+
+TOK-04 (terse Read MCP); BROW-01/02 (gsd-browser eval); AUTH-U-01/02; RERK-01 (Voyage rerank, conditional on SHIP-02); CTXP-01..04; LRNG-01..04; XREP-01..02. Full list in `.planning/REQUIREMENTS.md`.
+
+## [1.21.10] - 2026-04-18
+
+**semantic_search injection waves 2 + 3.**
+
+Completes the token-saving rollout started in v1.21.9. Waves 2 and 3 target
+commands that auditor identified as MED priority but still carry significant
+token cost in practice — milestone audits, gap planning, roadmap creation,
+project research, and the planner agent itself.
+
+### Added
+
+- **semantic_search in `rrr-planner` agent.** Planner previously grepped
+  CONTEXT.md and ROADMAP sections during task breakdown — now prefers
+  ~500-token semantic_search for "existing implementations", "similar
+  patterns", "existing code shape" queries.
+
+- **semantic_search reference in 4 more commands:** `/rrr:audit-milestone`,
+  `/rrr:plan-milestone-gaps`, `/rrr:create-roadmap`, `/rrr:research-project`.
+  These don't run every session but they dominate milestone boundaries —
+  typical burn 12-22K each before this change.
+
+- **`semantic-search-preference.md` domain-query patterns (wave 3).**
+  10-row table: tech stack, architecture, similar implementation, error
+  root-cause, requirement coverage, auth/security, data model, test
+  coverage, API surface, config. With suggested k per query. Purpose:
+  stop Claude from grepping for "middleware" when a better-phrased
+  semantic_search would nail it in one call.
+
+### Status after waves 1-3
+
+Commands using semantic_search: **13 of 23** (was 5). The 10 remaining
+untouched commands do minimal code exploration (<5K tokens each) —
+diminishing returns beyond here.
+
+Agents using semantic_search: **5 of ~15** — the five highest-burn ones
+(rrr-codebase-mapper, rrr-phase-researcher, rrr-executor, rrr-debugger,
+rrr-planner). These carry ~80% of agent-side exploration cost.
+
+### Next (v1.22.0)
+
+Webhook-driven re-index infrastructure (GitHub App single-URL webhook +
+local post-commit hook → local MCP). Closes the "stale index" gap — today
+reindex only runs on cron or manual sync_repo. Needs a phase plan; not a
+patch.
+
 ## [1.21.9] - 2026-04-18
 
 **Token-efficient RRR: semantic_search injection wave 1 + hosted worker hardening.**

package/agents/rrr-planner.md

@@ -2,7 +2,7 @@
 name: rrr-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /rrr:plan-phase orchestrator.
 model: sonnet
-tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
+tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*, mcp__rrr-search-hosted__semantic_search, mcp__rrr-search__semantic_search
 color: green
 ---
 

package/bin/install.js

@@ -383,7 +383,8 @@ function runHostedInstallOrchestrator() {
     writePendingMerge
   } = require('../rrr/lib/install-merge-agents');
   const {
-    wireToolRedirect
+    wireToolRedirect,
+    wireModelRouter
   } = require('../rrr/lib/install-hooks-wiring');
 
   const repoRoot = path.join(__dirname, '..');
@@ -533,6 +534,28 @@ function runHostedInstallOrchestrator() {
     audit.hooks_wired = { error: err.message };
   }
 
+  // 6b) Wire the Phase 83 model-router hook (MDLR-03).
+  // Seeds `rrr.model_router: "static"` if not present — default v1.21 behavior.
+  let routerResult = null;
+  try {
+    routerResult = wireModelRouter({
+      repoRoot,
+      userHooksDir,
+      userClaudeDir,
+      userSettingsPath,
+      dryRun: hasDryRun
+    });
+    audit.model_router_wired = {
+      copied: routerResult.copied,
+      settings_updated: routerResult.settingsUpdated,
+      hook_command: routerResult.hookCommand,
+      libs_copied: routerResult.libsCopied
+    };
+  } catch (err) {
+    console.error(`  ${yellow}⚠ model-router wiring failed (non-fatal): ${err.message}${reset}`);
+    audit.model_router_wired = { error: err.message };
+  }
+
   // 7) Write (or preview) the merged registry.
   if (hasDryRun) {
     console.log(`  ${cyan}[dry-run]${reset} Planned actions:`);

package/commands/rrr/add-phase.md

@@ -411,3 +411,20 @@ Phase addition is complete when:
 - [ ] Next phase number calculated correctly (ignoring decimals)
 - [ ] User informed of next steps
       </success_criteria>
+
+<post_command_auto_push>
+**When the user commits the new phase entry (PUSH-01 — paired with Phase 80 webhook):**
+
+This command intentionally does NOT commit (see anti_patterns). After the
+user commits the new ROADMAP.md / STATE.md / phase-dir changes, prompt
+them to push so the hosted MCP reindexes within ~60s:
+
+```bash
+# After `git commit -m "docs: add phase {NN}"`:
+node rrr/lib/auto-push.js --source=add-phase || true
+```
+
+Honors `settings.rrr.auto_push` (default `true`); on failure prints
+non-fatal warning. To opt out: `{"rrr": {"auto_push": false}}` in
+`~/.claude/settings.json`.
+</post_command_auto_push>

package/commands/rrr/audit-milestone.md

@@ -19,6 +19,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 
 <execution_context>
 @~/.claude/rrr/references/principles.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/complete-milestone.md

@@ -148,6 +148,16 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
    - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
    - Ask about pushing tag
 
+8.5. **Auto-push** (PUSH-01 — paired with Phase 80 webhook for <60s reindex):
+
+   ```bash
+   node rrr/lib/auto-push.js --source=complete-milestone || true
+   ```
+
+   Honors `settings.rrr.auto_push` (default `true`); on failure prints
+   non-fatal warning and continues. To opt out:
+   `{"rrr": {"auto_push": false}}` in `~/.claude/settings.json`.
+
 9. **Offer next steps:**
    - `/rrr:discuss-milestone` — thinking partner, creates context file
    - Then `/rrr:new-milestone` — update PROJECT.md with new goals

package/commands/rrr/create-roadmap.md

@@ -40,6 +40,7 @@ Roadmaps define what work happens in what order. Phases map to requirements.
 @~/.claude/rrr/templates/roadmap.md
 @~/.claude/rrr/templates/state.md
 @~/.claude/rrr/references/goal-backward.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/execute-phase.md

@@ -598,3 +598,18 @@ After all plans in phase complete (step 7):
 - [ ] REQUIREMENTS.md updated (phase requirements marked Complete)
 - [ ] User informed of next steps
 </success_criteria>
+
+<post_command_auto_push>
+**Final step (PUSH-01 — paired with Phase 80 webhook for <60s reindex):**
+
+After all wave plans complete and the phase-level rollup commit lands,
+nudge the hosted MCP reindex:
+
+```bash
+node rrr/lib/auto-push.js --source=execute-phase || true
+```
+
+Honors `settings.rrr.auto_push` (default `true`); on failure prints
+non-fatal warning and continues. To opt out:
+`{"rrr": {"auto_push": false}}` in `~/.claude/settings.json`.
+</post_command_auto_push>

package/commands/rrr/execute-plan.md

@@ -882,3 +882,18 @@ Continue handling returns until "## PLAN COMPLETE" or user stops.
 - [ ] If phase complete: REQUIREMENTS.md updated (phase requirements marked Complete)
 - [ ] User informed of completion and next steps
 </success_criteria>
+
+<post_command_auto_push>
+**Final step (PUSH-01 — paired with Phase 80 webhook for <60s reindex):**
+
+After plan completes (executor's per-task commits + SUMMARY.md commit have
+landed locally), nudge the hosted MCP reindex:
+
+```bash
+node rrr/lib/auto-push.js --source=execute-plan || true
+```
+
+Honors `settings.rrr.auto_push` (default `true`); on failure prints
+non-fatal warning and continues. To opt out:
+`{"rrr": {"auto_push": false}}` in `~/.claude/settings.json`.
+</post_command_auto_push>

package/commands/rrr/insert-phase.md

@@ -414,3 +414,20 @@ Phase insertion is complete when:
 - [ ] Decimal number calculated correctly (based on existing decimals)
 - [ ] User informed of next steps and dependency implications
       </success_criteria>
+
+<post_command_auto_push>
+**When the user commits the inserted phase entry (PUSH-01 — paired with Phase 80 webhook):**
+
+This command intentionally does NOT commit (see anti_patterns). After the
+user commits the new ROADMAP.md / STATE.md / phase-dir changes, prompt
+them to push so the hosted MCP reindexes within ~60s:
+
+```bash
+# After `git commit -m "docs: insert phase {N.M}"`:
+node rrr/lib/auto-push.js --source=insert-phase || true
+```
+
+Honors `settings.rrr.auto_push` (default `true`); on failure prints
+non-fatal warning. To opt out: `{"rrr": {"auto_push": false}}` in
+`~/.claude/settings.json`.
+</post_command_auto_push>

package/commands/rrr/new-milestone.md

@@ -103,6 +103,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    ```bash
    git add "$PATCHES_FILE"
    git commit -m "docs: close v${PREV_MILESTONE} patches (starting v{NEW_VERSION})"
+   node rrr/lib/auto-push.js --source=new-milestone-patches || true   # PUSH-01
    ```
 
    **If no patches (PATCH_COUNT = 0 or file doesn't exist):**
@@ -217,6 +218,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    ```bash
    git add .planning/PROJECT.md .planning/STATE.md
    git commit -m "docs: start milestone v[X.Y] [Name]"
+   node rrr/lib/auto-push.js --source=new-milestone || true   # PUSH-01 (auto-push for hosted MCP reindex)
    ```
 
 8. **Milestone research decision:**
@@ -321,6 +323,7 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    ```bash
    git add ".planning/milestones/v${NEW_VERSION}/research/"
    git commit -m "docs: research milestone v${NEW_VERSION} features"
+   node rrr/lib/auto-push.js --source=new-milestone-research || true   # PUSH-01
    ```
 
    **If "No, define requirements directly":** Skip research, continue to step 9.

package/commands/rrr/plan-milestone-gaps.md

@@ -22,6 +22,7 @@ One command creates all fix phases — no manual `/rrr:add-phase` per gap.
 @~/.claude/rrr/references/principles.md
 @~/.claude/rrr/workflows/plan-phase.md
 @~/.claude/rrr/lib/phase-paths.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/plan-phase.md

@@ -941,3 +941,19 @@ Verification: {Passed | Passed with override | Skipped}
 - [ ] User sees status between agent spawns
 - [ ] User knows next steps (execute or review)
 </success_criteria>
+
+<post_command_auto_push>
+**Final step (PUSH-01 — paired with Phase 80 webhook for <60s reindex):**
+
+After plans are created and any planning commits have landed, nudge the
+hosted MCP reindex so subsequent `semantic_search` calls see the new
+PLAN.md files:
+
+```bash
+node rrr/lib/auto-push.js --source=plan-phase || true
+```
+
+Honors `settings.rrr.auto_push` (default `true`); on failure prints
+non-fatal warning and continues. To opt out:
+`{"rrr": {"auto_push": false}}` in `~/.claude/settings.json`.
+</post_command_auto_push>

package/commands/rrr/remove-phase.md

@@ -261,6 +261,7 @@ Stage and commit the removal:
 ```bash
 git add .planning/
 git commit -m "chore: remove phase {target} ({original-phase-name})"
+node rrr/lib/auto-push.js --source=remove-phase || true   # PUSH-01 (auto-push for hosted MCP reindex)
 ```
 
 The commit message preserves the historical record of what was removed.

package/commands/rrr/research-project.md

@@ -23,6 +23,10 @@ For new projects, use /rrr:new-project instead.
 Deprecated: 2026-01-16
 -->
 
+<execution_context>
+@rrr/references/semantic-search-preference.md
+</execution_context>
+
 <objective>
 Research domain ecosystem. Spawns 4 parallel rrr-project-researcher agents for comprehensive coverage.
 

package/commands/rrr/savings.md

@@ -0,0 +1,68 @@
+---
+name: rrr:savings
+description: Show token-savings report (session + lifetime) with tier distribution and Opus-rate dashboard
+---
+
+<objective>
+Display the RRR token-savings report computed from observation JSONL files,
+the optional escalations log, and the optional tier map. Defaults to lifetime
+aggregation; pass `--session <id>` to scope to one session.
+</objective>
+
+<behavior>
+
+## Step 1: Run the savings script
+
+```bash
+node scripts/rrr-savings.js
+```
+
+This produces a human-readable report with:
+
+- **Tool calls** and edits batched
+- **Tier distribution** (Haiku / Sonnet / Opus call counts + percentages)
+- **Opus rate** with status badge: OK (≤10%), WARN (10–15%), CRITICAL (>15%)
+- **Cost (USD)** measured vs all-Opus counterfactual baseline (PF-TOK-03 two-number reporting)
+- **v1.21 baseline** reduction (99.74%) for context
+- **Methodology footer** — token counts are heuristic estimates; for billing-grade numbers run Tier 1 telemetry (`countTokens`) on a representative session
+
+## Step 2: Optional filters
+
+| Flag | Meaning |
+|------|---------|
+| `--session <id>` | Filter to a specific session id (from observation `session` field) |
+| `--lifetime` | (default) Aggregate across all observation files under `.planning/` |
+| `--json` | Machine-readable output for tooling |
+| `--hud` | Print only the HUD segment string (`H45% S40% O15% \| Opus:15%`) |
+
+## Step 3: Watch the Opus rate
+
+If the **Opus rate** crosses 15% in lifetime mode, that's the SHIP-GATE-relevant threshold for Phase 86. Investigate via:
+
+- `.planning/escalations.jsonl` — every escalation event (Phase 84)
+- `~/.claude/rrr/tier-map.json` — per-command/per-agent tier defaults (Phase 83)
+
+## Step 4: Recommended cadence
+
+- **Per session:** `/rrr:savings --session <id>` after a long task to spot-check.
+- **Monthly:** `/rrr:savings` (lifetime) — operator step, captures milestone-scale trend.
+- **HUD:** the `--hud` segment is intended to live alongside the Phase 80 freshness segment in the OhMyPosh / JSON-state pipeline.
+
+</behavior>
+
+<inputs_consumed>
+
+| File | Phase shipped | Tolerated if missing? |
+|------|---------------|-----------------------|
+| `.planning/observations-*.jsonl` | v1.19 | Yes — returns zeros |
+| `.planning/escalations.jsonl` | v1.22 Phase 84 | Yes — falls back to tier-map / all-sonnet default |
+| `.rrr/tier-map.json` or `~/.claude/rrr/tier-map.json` | v1.22 Phase 83 | Yes — falls back to all-sonnet |
+
+</inputs_consumed>
+
+<constraints>
+- Pure read-only: never modifies observation/escalation files.
+- Never blocks: always exits 0 even if all inputs are missing.
+- Methodology is explicit: report header labels token counts as "estimated" to
+  avoid PF-TOK-03 (speculative savings calc) trap.
+</constraints>

package/commands/rrr/ship.md

@@ -246,6 +246,13 @@ On success, display:
 The PR description includes planning context from {N} SUMMARY.md files.
 ```
 
+After successful PR creation, also nudge the hosted MCP reindex on the
+base branch (PUSH-01 — paired with Phase 80 webhook):
+
+```bash
+node rrr/lib/auto-push.js --source=ship || true
+```
+
 On failure (gh pr create returns error), fall through to Step 4.
 
 **If ANY check fails, go to Step 4 (fallback).**
@@ -283,6 +290,11 @@ Generate `.planning/SHIP-READY.md`:
 2. Create PR at: https://github.com/{remote-owner/repo}/compare/{BASE_BRANCH}...{CURRENT_BRANCH}
 3. Copy the PR Body above into the PR description
 
+> Note: after merging the PR, run `node rrr/lib/auto-push.js --source=ship-postmerge`
+> on `main` to nudge the hosted MCP reindex (PUSH-01 — paired with Phase 80
+> webhook). Or set `rrr.auto_push: true` (default) and run `/rrr:next` —
+> downstream commands auto-push.
+
 ## Why Manual?
 
 {Reason from above}

package/commands/rrr/verify-work.md

@@ -436,4 +436,24 @@ All Glob/Grep/Read operations must exclude these paths.
 - [ ] Manual: presents tests one at a time for user verification
 - [ ] Creates/resumes UAT.md with tests
 - [ ] Tracks progress across context resets
-</success_criteria>
+</success_criteria>
+
+<post_command_auto_push>
+**Final step ON PASS only (PUSH-01 — paired with Phase 80 webhook):**
+
+When verification result is "Clean" (all SUMMARY.md present + commit
+hashes), nudge the hosted MCP reindex so the verified state is
+queryable within ~60s:
+
+```bash
+# Only run when verification PASSED (not on gaps_found / human_needed)
+node rrr/lib/auto-push.js --source=verify-work-pass || true
+```
+
+If verification reported gaps, do NOT auto-push — let the operator fix
+gaps first, then re-verify, then push on the next clean pass.
+
+Honors `settings.rrr.auto_push` (default `true`); on failure prints
+non-fatal warning and continues. To opt out:
+`{"rrr": {"auto_push": false}}` in `~/.claude/settings.json`.
+</post_command_auto_push>

package/docs/escalations-schema.md

@@ -0,0 +1,112 @@
+# `escalations.jsonl` schema (Phase 84, v2)
+
+The `~/.rrr/telemetry/escalations.jsonl` file is the single audit log for
+RRR's dynamic model router (Phase 83) and the difficulty-triggered
+escalation layer (Phase 84). One JSON object per line; appended atomically.
+
+This doc is the canonical reference. Phase 85 `/rrr:savings` consumes it.
+Phase 86 SHIP-04 (`<15%` Opus rate) is computed from it.
+
+## Schema v2
+
+```jsonc
+{
+  // Always present
+  "ts": "2026-04-18T22:33:00.000Z",      // ISO-8601 UTC timestamp
+  "event": "dispatch",                    // see Event enum below
+
+  // Dispatch-context fields (present when event=dispatch)
+  "tool_name": "Task",                    // matcher scope (always Task in v1.22)
+  "agent_name": "rrr-debugger",           // subagent_type from tool_input, or null
+  "command": "debug",                     // detected /rrr:<command>, or null
+  "stage": "execution",                   // "planning" | "execution" | "verification"
+  "tier": "opus",                         // "haiku" | "sonnet" | "opus" | "inherit"
+  "reason": "debugger_iter_escalate",     // see Reason enum below
+
+  // Phase 84 escalation extension (present when reason ∈ escalation set)
+  "retry_count": 3,                       // iter (debugger) or retry_count (executor)
+  "prior_tier": "sonnet",                 // tier the base decideTier() returned
+
+  // Free-form
+  "details": null,                        // optional object — never required to read
+
+  // Hook-error context (present when event=hook_error)
+  "error": "...",                         // truncated message
+  "stack": "..."                          // truncated stack (unhandled_exception only)
+}
+```
+
+### Event enum
+
+| `event`       | Meaning                                                   |
+|---------------|-----------------------------------------------------------|
+| `dispatch`    | Hook routed the Task tool. `tier` + `reason` describe the decision. |
+| `hook_error`  | Hook caught an exception or invariant violation. Fail-OPEN — Claude Code still gets an `allow` response. |
+
+### Reason enum (event=dispatch)
+
+| `reason`                       | Trigger                                                                                  |
+|--------------------------------|------------------------------------------------------------------------------------------|
+| `dispatch`                     | Plain Phase-83 routing — base `decideTier()` decision applied, no escalation.            |
+| `debugger_iter_escalate`       | Phase 84 ESCL-01 — `agent=rrr-debugger` AND iteration ≥ 3 forced tier to `opus`.          |
+| `executor_retry_escalate`      | Phase 84 ESCL-02 — `agent=rrr-executor` AND `retry_count` ≥ 2 forced tier to `opus`.      |
+| `manual`                       | Operator-emitted row (e.g. `/rrr:savings --tag` or external script). Reserved for v1.23+. |
+
+### Reason enum (event=hook_error)
+
+| `reason`               | Trigger                                                            |
+|------------------------|--------------------------------------------------------------------|
+| `router_lib_missing`   | One of the router libs failed to require — likely install drift.   |
+| `settings_load_failed` | `loadRouterConfig()` threw — corrupt JSON in settings.json.        |
+| `decide_tier_threw`    | `tier-map.decideTier()` threw — bug in escalation rules.           |
+| `escalation_threw`     | `escalation.applyEscalation()` threw — fail-OPEN, base passes.     |
+| `unhandled_exception`  | Top-level catch — anything else.                                    |
+
+## Per-plan vs per-task retry (PF-RETRY-02)
+
+`retry_count` for `executor_retry_escalate` is **per-plan**: it lives in
+`<project>/.rrr/state/executor-retry.json` keyed by `plan_id`. Querying
+the helper with a different `plan_id` returns 0 (retries don't carry
+across plans). Documented to prevent the silent "monotonic-vs-resetting"
+ambiguity the v1.22 PITFALLS research flagged.
+
+For `debugger_iter_escalate`, `retry_count` is the debug-session
+iteration count (also per-session, in `.rrr/state/debug-session.json`).
+
+## Backwards compatibility
+
+Phase 83 wrote rows with these fields only:
+`ts`, `event`, optional `tool_name`/`agent`/`command`/`stage`/`tier`/`reason`/`error`.
+
+Phase 84 adds `retry_count` and `prior_tier`. Existing readers (e.g.
+`rrr/lib/savings/index.js`, which uses `e.to_tier || e.tier`) tolerate the
+addition: unknown fields are simply ignored.
+
+## Append protocol
+
+The hook calls `logEscalation(entry)` which:
+
+1. Ensures `~/.rrr/telemetry/` exists.
+2. Prepends `ts: new Date().toISOString()`.
+3. Appends `JSON.stringify(entry) + '\n'` synchronously.
+4. **Swallows write errors** — telemetry must never crash the hook
+   (Phase 83 fail-OPEN contract).
+
+## Reading the file
+
+```bash
+# Last 20 escalations
+tail -n 20 ~/.rrr/telemetry/escalations.jsonl | jq .
+
+# Opus-rate over last 100 dispatches
+tail -n 100 ~/.rrr/telemetry/escalations.jsonl \
+  | jq -s 'map(select(.event=="dispatch")) | (map(select(.tier=="opus")) | length) / length'
+```
+
+`/rrr:savings` (Phase 85 TOK-03) aggregates this file and prints
+session + lifetime tier distribution. See `rrr/lib/savings/index.js`.
+
+## Rotation
+
+Not implemented in v1.22. The file grows ~100 bytes/event; ~10 MB/year
+for active dogfood usage. Track for v1.23 via a small cron rotator.