docs(tiers): make Opus 5 the default top tier, Fable the peak reserve

CLAUDE.md

@@ -7,14 +7,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 1. **Understand before changing** — For non-trivial work in unfamiliar code, read `graphify-out/GRAPH_REPORT.md` and `wiki/index.md` first. If `graphify-out/` is missing, **create it first** before any non-trivial exploration (see §0 for the rebuild command). Don't edit code you haven't mapped.
 2. **Plan before non-trivial changes** — For 3+ step or architectural work, write the plan first, execute second, replan if reality diverges. Skip for mechanical one-liners.
 3. **Reuse before writing** — Before adding a new function, type, or helper, grep for existing functionality. Exact fit: reuse. Close fit (~80%): refactor existing code (flag the scope change in the plan). Never silently copy-paste. (§1a)
-4. **Delegate to subagents** — Offload research, parallel exploration, and focused subtasks to keep the main context clean. Match model tier (Haiku/Sonnet/Opus) to task complexity. Reuse a context-warm agent (`SendMessage`) before spawning a fresh one when the follow-up touches the same files. (§2)
+4. **Delegate to subagents** — Offload research, parallel exploration, and focused subtasks to keep the main context clean. Match model tier (Haiku/Sonnet/Opus/Fable) to task complexity. Reuse a context-warm agent (`SendMessage`) before spawning a fresh one when the follow-up touches the same files. (§2)
 5. **Capture every correction** — When the user corrects an approach, immediately save a memory entry that prevents the same mistake. Review relevant memories at session start. (§3)
 6. **No "done" without proof** — Run tests, check logs, exercise the UI. "Should work" is not a status. If verification isn't possible, say so explicitly. (§4)
 7. **Prefer elegance to hacks** — On non-trivial changes, pause and ask "is there a cleaner way?" before shipping. If a fix feels hacky, do it right. Skip for obvious one-liners. (§5)
 8. **Bugs: triage now, fix at root** — Symptom → root cause → fix → regression test. No temporary patches that hide the real issue. (§6)
 9. **Never delete data — including hidden/metadata files** — "Don't delete files" means ALL files: `.git` dirs, dotfiles, config caches, lockfiles, logs, build artifacts. Do NOT rationalize deletion as "just metadata," "can be regenerated," "not user data," or "the plan said so." Before `rm`, `rm -rf`, `git filter-repo`, `git branch -D`, `git reset --hard`, dropping tables, or any operation destroying on-disk or committed state you did not create this session, pause and get explicit per-item confirmation — even if a broader plan appeared to authorize it. For a "fresh" git repo use additive approaches (`git checkout --orphan`, or clone the working tree to a new path). If unsure whether a file matters, assume it does.
 
-This document may be used by OpenAI or Gemini tooling. When it names Anthropic tiers, use the corresponding tiers in the same role: Haiku -> gpt-5.4-mini -> Gemini 3.1 Flash-Lite; Sonnet -> gpt-5.4 -> Gemini 3.1 Flash; Opus -> gpt-5.5 -> Gemini 3.1 Pro. Keep cheapest/mid/top aligned if local model names change.
+This document may be used by OpenAI or Gemini tooling. When it names Anthropic tiers, use the corresponding tiers in the same role: Haiku -> gpt-5.4-mini -> Gemini 3.1 Flash-Lite; Sonnet -> gpt-5.4 -> Gemini 3.1 Flash; Opus (the default top tier — planning, review, iteration, debugging, non-trivial implementation, see §1c and §2) -> gpt-5.5 -> Gemini 3.1 Pro; Fable (peak reserve, ~2x Opus cost, only when the last-0.5% of max-effort intelligence decides it) -> the top tier at max effort (gpt-5.5 / Gemini 3.1 Pro). Keep cheapest/mid/top aligned if local model names change.
 
 > **If you're running on an Anthropic model**, **ignore this mapping** — the tier names below already correspond to your model family. The mapping is for OpenAI- or Gemini-backed tooling consuming this same file.
 
@@ -113,18 +113,18 @@ Non-trivial work happens in a dedicated git worktree branched off the current br
 - **Rebase, don't merge**, by default; clean up the worktree and delete the plan file after.
 - **Skip only for trivially mechanical edits** — typo, pure rename, comment tweak. When in doubt, create the worktree.
 
-### 1c. Local Review Loop — Opus Reviews Every Sonnet Change, Sonnet Fixes, Repeat
+### 1c. Local Review Loop — Opus Reviews Every Implementation Change, the Implementer Fixes, Repeat
 
-Every code change Sonnet produces during the implementation phase is reviewed locally by Opus before it counts as done. Local analog of the post-PR CodeRabbit loop (`git-workflow.md`): catch issues in the worktree before the diff is pushed. Does NOT replace the §1 post-implementation review or the §1b merge gate; it runs inside the implementation phase, upstream of both.
+Every code change the implementer (Sonnet for simpler changes, Opus for non-trivial code, per §2) produces during the implementation phase is reviewed locally by Opus before it counts as done. Local analog of the post-PR CodeRabbit loop (`git-workflow.md`): catch issues in the worktree before the diff is pushed. Does NOT replace the §1 post-implementation review or the §1b merge gate; it runs inside the implementation phase, upstream of both.
 
 The loop:
-1. **Sonnet implements** an atomic task (or one logically complete chunk) per the approved plan.
-2. **Opus reviews the diff locally** across the five review dimensions plus Reuse (§1a) and scope discipline. Review on the main session when it is Opus, or spawn a dedicated Opus reviewer subagent to keep the implementer's context clean. Emit a concrete findings list (`file:line` + what's wrong + suggested fix), or an explicit "no actionable findings".
-3. **Sonnet addresses** every finding. Mechanical, decided fixes stay on Sonnet; a finding needing a design call escalates that item to Opus (§2 carve-out), then the decided fix goes back to Sonnet.
+1. **The implementer (Sonnet or Opus per §2) implements** an atomic task (or one logically complete chunk) per the approved plan.
+2. **Opus reviews the diff locally** across the five review dimensions plus Reuse (§1a) and scope discipline. Spawn a dedicated Opus reviewer subagent (set via `model`) to keep the implementer's context clean; escalate the review to Fable only for the hardest money-path / architecture calls where peak intelligence matters. Emit a concrete findings list (`file:line` + what's wrong + suggested fix), or an explicit "no actionable findings".
+3. **The implementer addresses** every finding. Mechanical, decided fixes stay with the implementer; a finding needing a design call escalates that item to Opus (or Fable for a peak call, §2 carve-out), then the decided fix goes back to the implementer.
 4. **Opus re-reviews** the updated diff.
 5. Repeat 3-4 until a review pass returns no actionable findings. "Until everything is addressed" means a clean pass, not "the obvious ones are fixed".
 
-Rules: reviewer and implementer are distinct roles, ideally distinct agents (review the diff as if a stranger wrote it); implementer on Sonnet, reviewer on Opus (set via `model`); log per-round findings in the plan file for auditability; review per task as it lands, don't batch; skip only for the same trivially mechanical edits §1b lets you skip the worktree for. Across rounds, keep the SAME implementer and SAME reviewer agents alive and continue them via `SendMessage` (§2 agent reuse): the diff and files stay loaded in each agent's context, so round N+1 costs only the delta, not a full re-read. Reviewer/implementer separation is between the two roles, not between rounds of the same role.
+Rules: reviewer and implementer are distinct roles, ideally distinct agents (review the diff as if a stranger wrote it); implementer on Sonnet or Opus (per §2), reviewer on Opus (Fable for peak calls) (set via `model`); log per-round findings in the plan file for auditability; review per task as it lands, don't batch; skip only for the same trivially mechanical edits §1b lets you skip the worktree for. Across rounds, keep the SAME implementer and SAME reviewer agents alive and continue them via `SendMessage` (§2 agent reuse): the diff and files stay loaded in each agent's context, so round N+1 costs only the delta, not a full re-read. Reviewer/implementer separation is between the two roles, not between rounds of the same role.
 
 ### 2. Subagent Strategy
 
@@ -136,16 +136,17 @@ Full rubric, PR-shipping tier split, and rationale in `~/.claude/subagent-strate
 - **When NOT to use subagents**: tight debugging loops where each iteration informs the next, work needing multiple rounds of your own judgement, interactive refinement with the user.
 - **Background-first: don't block the main chat.** Default to running independent or long-running work in the background so the main session stays responsive instead of waiting on it: spawn subagents with `run_in_background: true` (builds, full test suites, CI/deploy/CR watchers, migrations, broad sweeps, research fan-outs, anything that takes more than ~30s or fans out), and use Bash `run_in_background: true` for long shell commands. Keep moving on other independent work or hand control back to the user while it runs, and collect results when the completion notification arrives - **never poll** (`TaskOutput`/status loops just re-block you). Run in the **foreground only** when the very next step truly needs that result, or for the 'When NOT to use subagents' carve-outs (tight debugging loops, interactive refinement). Fire independent calls together: multiple queries -> one message with parallel `Agent` calls. Lock patterns for concurrent agents in `multi-agent-comms.md`.
 - **Delegate to the cheapest sufficient tier — actively, not just when in doubt.** The main session is usually the most expensive option; reserving it for work that needs it is the biggest cost lever.
-- **Set the `model` parameter on EVERY `Agent` call — never rely on inheritance** (inheriting Opus is a 5-10x premium on work that rarely needs it).
-- **PR-shipping splits across tiers**: planning phase + iteration loops (incl. the §1c review loop, CR responses, fix-push, rebases) -> **Opus**; implementation phase (writing the diff, tests/lint/build, opening the PR, label-mirror, `gh`/`git` mechanics) -> **Sonnet**. Mechanical single steps within an iteration loop stay Haiku/Sonnet. Compact tier guide:
+- **Set the `model` parameter on EVERY `Agent` call — never rely on inheritance** (inheriting a top tier — Opus, or the ~2x-pricier Fable reserve — is a large premium on work that rarely needs it).
+- **PR-shipping splits across tiers**: planning phase + review loops (the §1c local review loop, the §1 pre-commit/post-impl reviews, adversarial/money-path reviews) + architecture/design decisions + iteration loops (CR responses, fix-push, rebases) + gnarly hypothesis-driven debugging + non-trivial implementation (complex multi-file features, intricate logic, unclear-shape refactors) -> **Opus** (the default top tier); simpler decided-shape implementation (writing the diff, tests/lint/build, opening the PR, label-mirror, `gh`/`git` mechanics) -> **Sonnet**. Mechanical single steps stay Haiku/Sonnet. Escalate to **Fable** only when the last ~0.5% of peak (max-effort) intelligence genuinely decides the outcome — the hardest money-path adversarial reviews and gnarliest architecture calls — since Opus 5 reaches ~Fable-5 frontier intelligence at roughly half the cost, so Fable's extra margin is worth its ~2x price only at the true frontier. Compact tier guide:
 
   | Tier | Use for |
   |------|---------|
   | Haiku | renames, typo/format fixes, mechanical edits with a clear spec, simple lookups, single-command runs, tightly-specified function/test, small single-file review, documented API migration, rubric classification, short summaries |
-  | Sonnet | PR implementation phase; focused multi-file changes with a decided shape; functions with 1-2 design choices; multi-file/non-trivial-logic review; refactors with a clear target |
-  | Opus | PR planning + iteration loops; architecture decisions; unclear-shape refactors; gnarly hypothesis-driven debugging; reading a large unfamiliar codebase from scratch; any work where understanding/weighing options is the hard part |
+  | Sonnet | PR implementation of simpler, decided-shape changes; focused multi-file changes with a decided shape; functions with 1-2 design choices; refactors with a clear target; small single-file/mechanical review |
+  | Opus | **the default top tier.** PR planning; all review loops (§1c local review, §1 pre-commit/post-impl, adversarial money-path review); architecture/design decisions; iteration loops (CR responses, fix-push, rebases); gnarly hypothesis-driven debugging; non-trivial implementation (complex features, intricate logic, unclear-shape refactors); reading a large unfamiliar codebase from scratch; any work where understanding/weighing options is the hard part |
+  | Fable | **peak reserve (~2x Opus cost).** Only when the last ~0.5% of max-effort intelligence decides the outcome — the hardest money-path adversarial reviews, the gnarliest architecture calls. Default to Opus; escalate to Fable only when Opus is genuinely not enough. |
 
-  When in doubt, go one tier cheaper and re-spawn stronger if it struggles — *except* planning/iteration loops, which default to Opus.
+  When in doubt, go one tier cheaper and re-spawn stronger if it struggles — *except* planning, review, iteration, debugging, and non-trivial implementation (default to Opus). Escalate to Fable only for peak-critical work.
 - **Every `gh pr create` MUST mirror the closing issue's triage labels onto the PR** (`priority/*`, `severity/*`, `urgency/*`, `impact/*`, `effort/*`, `type/*`, plus `triaged` only if the issue carries it). Part of the open-PR step, not a follow-up. Detail in `subagent-strategy.md`.
 
 ### 2a. Tool Selection
@@ -219,9 +220,10 @@ Key rules from the reference file: triage tags 5 dimensions plus a derived prior
 
 Full rules in `~/.claude/git-workflow.md` — **read before every commit, PR, or push**. Headline:
 
+- **Repo first — check at TASK START, not commit time**: if you're working in a PROJECT dir that isn't a git repo (`Is a git repository: false`, no `.git`), `git init` immediately, before the first non-trivial edit. You cannot make atomic commits — or recover intermediate states — without one, and multi-phase work in an unversioned tree loses its per-step history irreversibly. Creating a repo is safe and additive (the opposite of the never-destroy-`.git` rule §9); don't let that caution bleed into not creating one. Then commit per phase as you go, never one giant commit at the end. **Exceptions (do NOT init):** the home dir itself, system temp / scratchpad (`/tmp`, `$TMPDIR`), `~/Downloads`/`~/Desktop` and similar non-project scratch locations. Anything done in a project dir needs a repo. Detail in `git-workflow.md`.
 - **Conventional commits**: `type(scope): subject`, imperative, ≤72 chars. Never mention Anthropic/Claude. Never use heredoc-based `git commit -m` — `Write` a fresh uniquely-named file under `/tmp/claude/`, commit with `git commit -F`, delete it after.
 - **Small atomic commits**: one concern each, independently revertable.
-- **⚠️ Mandatory pre-commit review loop — 3 clean passes**: read `git diff --cached` and check the five review dimensions (§1). Fix in the same changeset, never via follow-up commits. **Run this review on Opus as comprehensively as possible — CodeRabbit's lens is the floor, not the ceiling** (architecture, type design, silent failures, test coverage, security, comment accuracy, performance, convention fit; fan out the `pr-review-toolkit:*` agents for substantial diffs). Goal: land clean for CR AND humans on the first pass. Catching a finding locally costs one pass; catching it after review costs a push + review wait + fix commit + another round. Shipping it well the first time is much faster.
+- **⚠️ Mandatory pre-commit review loop — 3 clean passes**: read `git diff --cached` and check the five review dimensions (§1). Fix in the same changeset, never via follow-up commits. **Run this review on Opus as comprehensively as possible (escalate to Fable only for the hardest / highest-stakes diffs) — CodeRabbit's lens is the floor, not the ceiling** (architecture, type design, silent failures, test coverage, security, comment accuracy, performance, convention fit; fan out the `pr-review-toolkit:*` agents for substantial diffs). Goal: land clean for CR AND humans on the first pass. Catching a finding locally costs one pass; catching it after review costs a push + review wait + fix commit + another round. Shipping it well the first time is much faster.
 - **Post-push CI watcher**: after every `git push`, enumerate all workflow runs for the pushed commit and launch one background `Agent` per run (`run_in_background: true`) named `ci-watch-<short-sha>-<workflow-slug>`. Each fetches failed logs and **fixes failures autonomously**. Coordinate via the `git-push` lock before pushing fixes. Escalate only for decisions.
 - **PRs**: ≤400 lines, one concern, conventional-commit title, feature branch `type/short-description`. Never `--no-verify`.
 - **Post-PR review loop**: after `gh pr create`, trigger CodeRabbit (`@coderabbitai review`) **and spawn `cr-watch-<pr-#>` as ONE atomic action — posting the trigger without arming the watcher is a defect identical in shape to `git push` without a CI watcher; safe ordering is spawn-watcher-then-trigger so a posted trigger always implies a live watcher** (re-request CR after every push to the PR branch and wait ~10 min before triaging so CR has time to post, then 60-120s polling, soft-handle 429s — but recover from any CR rate-limit with `@coderabbitai full review`, never the incremental `@coderabbitai review`, since a throttled pass silently skips the in-flight commits and yields a false-clean), triage suggestions (actionable / dismiss-with-justification / batch-nitpick), push fixes per the pre-commit loop, then re-ping `@coderabbitai review` and loop until a clean review (**never** `@coderabbitai resolve` or hand-resolving threads to silence the bot), then `merge-watch-<pr-#>` awaits **human merge** (no self-merge by default), then deploy + verify (Chrome MCP for UI, `curl` for API, `terraform plan` for IaC), then post a recommendation-to-close on the originating issue and **file new issues for out-of-scope follow-ups**. **Before declaring PR work done for a session (or any time you spot unaddressed CR comments), run the reconciliation sweep**: every open PR you authored must have a live `cr-watch`, a clean terminal CR state, or be closed — re-arm any that slipped. Full lifecycle in `git-workflow.md`.