pan-wizard 3.36.0 → 3.37.0

package/docs/specs/multi_model_routing_superplan.md

@@ -0,0 +1,197 @@
+# PAN Wizard Work Plan — Multi-Model Routing
+
+**Generated:** 2026-03-21 · **Source:** `docs/specs/multi_model_routing_featureai.md`
+
+---
+
+## Baseline
+
+| Metric | Value |
+|--------|-------|
+| Version | 2.8.1 |
+| Tests passing | 1658/1658 |
+| Test files | 71 (46 unit + 25 scenario) |
+| Commands shipped | 42 |
+| Agents shipped | 12 |
+| Core modules | 16 |
+| Open TODOs | 64 |
+| Hooks | 3 |
+
+---
+
+## Items
+
+| ID | Priority | Size | Pts | Title | Files | Status |
+|----|----------|------|-----|-------|-------|--------|
+| 1 | P5 | S | 2 | Add PROVIDER_MODELS constant | core.cjs | Done |
+| 2 | P5 | XS | 1 | Add LEGACY_ALIASES constant (opus→reasoning, sonnet→mid, haiku→fast) | core.cjs | Done |
+| 3 | P5 | M | 4 | Update MODEL_PROFILES to use tier aliases (reasoning/mid/fast) | core.cjs | Done |
+| 4 | P5 | S | 2 | Add detectProvider(cwd, config) function | core.cjs | Done |
+| 5 | P5 | S | 2 | Add resolveTierToModel(tier, provider) function | core.cjs | Done |
+| 6 | P5 | M | 4 | Add resolveComplexityTier(baseTier, taskMetadata) function | core.cjs | Done |
+| 7 | P5 | M | 4 | Update resolveModelInternal() — add provider detection, tier resolution, routing strategy support, optional taskMetadata param | core.cjs | Done |
+| 8 | P5 | S | 2 | Add estimateCostMultiplier(profile) function + COST_MULTIPLIERS constant | core.cjs | Done |
+| 9 | P5 | XS | 1 | Export new functions and constants from core.cjs module.exports | core.cjs | Done |
+| 10 | P5 | S | 2 | Update buildConfigDefaults() — add routing section (strategy, provider, cascade_quality_gate, complexity_thresholds) | config.cjs | Done |
+| 11 | P5 | S | 2 | Update config merge to deep-merge routing section | config.cjs | Done |
+| 12 | P5 | M | 4 | Update cmdResolveModel() — accept optional metadataJson param, pass to resolveModelInternal, include strategy in output | commands.cjs | Done |
+| 13 | P5 | S | 2 | Add cmdEstimateCost(cwd, raw) command | commands.cjs | Done |
+| 14 | P5 | S | 2 | Wire estimate-cost case in pan-tools.cjs dispatcher | pan-tools.cjs | Done |
+| 15 | P5 | XS | 1 | Update resolve-model case in pan-tools.cjs to pass metadata arg | pan-tools.cjs | Done |
+| 16 | P3 | M | 4 | Tests: PROVIDER_MODELS structure, tier alias resolution (6 tests) | tests/core.test.cjs | Done |
+| 17 | P3 | M | 4 | Tests: Legacy backward compat — opus/sonnet/haiku still resolve (3 tests) | tests/core.test.cjs | Done |
+| 18 | P3 | M | 4 | Tests: detectProvider() — config, env var, directory, fallback (4 tests) | tests/core.test.cjs | Done |
+| 19 | P3 | M | 4 | Tests: resolveComplexityTier — downgrade, maintain, upgrade, edge cases (6 tests) | tests/core.test.cjs | Done |
+| 20 | P3 | S | 2 | Tests: resolveModelInternal with strategy=static (backward compat) | tests/core.test.cjs | Done |
+| 21 | P3 | S | 2 | Tests: resolveModelInternal with strategy=complexity + metadata | tests/core.test.cjs | Done |
+| 22 | P3 | S | 2 | Tests: Per-agent override precedence over routing strategy | tests/core.test.cjs | Done |
+| 23 | P3 | S | 2 | Tests: estimateCostMultiplier returns valid numbers for all profiles | tests/core.test.cjs | Done |
+| 24 | P3 | S | 2 | Tests: Config — routing defaults present, user override merging (3 tests) | tests/config.test.cjs | Done |
+| 25 | P3 | S | 2 | Tests: Commands — resolve-model with/without metadata, estimate-cost output (4 tests) | tests/commands.test.cjs | Done |
+| 26 | P6 | L | 10 | Rewrite model-profiles.md reference — tier aliases, provider mapping, routing strategies, config examples | references/model-profiles.md | Done |
+| 27 | P6 | S | 2 | Update profile.md command — add cost estimation display after profile switch | commands/pan/profile.md | Done |
+| 28 | P6 | S | 2 | Update profile.md workflow — add cost multiplier output step | workflows/profile.md | Done |
+| 29 | P6 | S | 2 | Update settings.md workflow — add routing strategy question | workflows/settings.md | Done |
+| 30 | P6 | M | 4 | Update USER-GUIDE.md — Model Profiles section with routing, cost estimation, per-phase override | docs/USER-GUIDE.md | Done |
+| 31 | P6 | S | 2 | Update AGENTS.md — Model Profiles section with tier aliases | docs/AGENTS.md | Done |
+| 32 | P6 | S | 2 | Update COMPARISON.md — Model Flexibility row, Where PAN Leads section | docs/COMPARISON.md | Done |
+| 33 | P6 | S | 2 | Update INTERNALS.md — document routing pipeline | docs/INTERNALS.md | Done |
+| 34 | P5 | M | 4 | Per-phase model override — parse `<!-- model_tier: X -->` from roadmap phase sections in resolveModelInternal | core.cjs | Done |
+| 35 | P3 | S | 2 | Tests: Per-phase model override precedence | tests/core.test.cjs | Done |
+| 36 | P3 | S | 2 | Tests: Installer deploys updated model-profiles.md to all 5 runtimes | tests/e2e-install.test.cjs | Done |
+
+**Total: 36 items · 96 points**
+
+---
+
+## Dependency Graph
+
+```
+Items 1-2 (constants) ← Item 3 (profiles update) ← Item 7 (resolveModelInternal update)
+Items 4-5 (detect/resolve functions) ← Item 7
+Item 6 (complexity fn) ← Item 7
+Item 8 (cost fn) ← Item 13 (cmdEstimateCost)
+Items 7,9 (core exports) ← Items 12-15 (CLI wiring)
+Items 1-9 (all core) ← Items 16-23 (core tests)
+Items 10-11 (config) ← Item 24 (config tests)
+Items 12-15 (commands) ← Item 25 (command tests)
+Item 34 (per-phase override) ← Item 35 (per-phase tests)
+All code ← Items 26-33 (documentation)
+```
+
+---
+
+## Session Plan
+
+### Session 1: Core Routing Engine + Backward Compat (38 pts)
+
+**Goal:** All core functions working, existing tests still pass, new core tests green.
+
+| Order | IDs | Title | Pts |
+|-------|-----|-------|-----|
+| 1 | 1, 2 | PROVIDER_MODELS + LEGACY_ALIASES constants | 3 |
+| 2 | 3 | Update MODEL_PROFILES to tier aliases | 4 |
+| 3 | 4, 5 | detectProvider() + resolveTierToModel() | 4 |
+| 4 | 6 | resolveComplexityTier() | 4 |
+| 5 | 7 | Update resolveModelInternal() with provider + strategy | 4 |
+| 6 | 8 | estimateCostMultiplier() + COST_MULTIPLIERS | 2 |
+| 7 | 9 | Export new functions from module.exports | 1 |
+| 8 | 16, 17 | Tests: tier alias resolution + backward compat (9 tests) | 8 |
+| 9 | 18 | Tests: detectProvider() (4 tests) | 4 |
+| 10 | 20 | Tests: resolveModelInternal static backward compat | 2 |
+| 11 | 22 | Tests: Per-agent override precedence | 2 |
+
+**Verification gate:** `npm run test:all` — 1658 existing + ~15 new tests all pass. No regression in resolve-model output. Legacy opus/sonnet/haiku still work.
+
+**Risk:** Item 3 (MODEL_PROFILES change) touches the constant that ~6 existing test files assert against. Must update test expectations atomically with the constant change. Run tests after each sub-step.
+
+---
+
+### Session 2: Config + CLI Integration (16 pts)
+
+**Goal:** CLI commands wired, config defaults updated, full pipeline testable end-to-end.
+
+| Order | IDs | Title | Pts |
+|-------|-----|-------|-----|
+| 1 | 10, 11 | Config defaults — routing section + deep-merge | 4 |
+| 2 | 12 | Update cmdResolveModel() with metadata support | 4 |
+| 3 | 13 | Add cmdEstimateCost() command | 2 |
+| 4 | 14, 15 | Wire pan-tools.cjs — estimate-cost + resolve-model metadata | 3 |
+| 5 | 24 | Tests: config routing defaults (3 tests) | 2 |
+| 6 | 25 | Tests: commands — resolve-model metadata + estimate-cost (4 tests) | 2 |
+
+**Verification gate:** `npm run test:all` all pass. `pan-tools.cjs resolve-model pan-executor` returns expected value. `pan-tools.cjs estimate-cost` returns JSON with all 3 profiles.
+
+---
+
+### Session 3: Complexity Routing + Per-Phase Override (16 pts)
+
+**Goal:** Complexity routing adjusts tiers based on task metadata. Per-phase override works from roadmap frontmatter.
+
+| Order | IDs | Title | Pts |
+|-------|-----|-------|-----|
+| 1 | 19 | Tests: resolveComplexityTier — all 6 edge cases | 4 |
+| 2 | 21 | Tests: resolveModelInternal complexity strategy | 2 |
+| 3 | 23 | Tests: estimateCostMultiplier valid output | 2 |
+| 4 | 34 | Per-phase model override (parse `<!-- model_tier -->`) | 4 |
+| 5 | 35 | Tests: per-phase override precedence | 2 |
+| 6 | 36 | Tests: installer deploys updated reference | 2 |
+
+**Verification gate:** `npm run test:all` all pass. Complexity routing demonstrably up/downgrades based on fileCount, waveCount, requirementCount, isArchitectural metadata.
+
+---
+
+### Session 4: Documentation (26 pts)
+
+**Goal:** All documentation updated to reflect new routing capabilities. Reference doc rewritten.
+
+| Order | IDs | Title | Pts |
+|-------|-----|-------|-----|
+| 1 | 26 | Rewrite model-profiles.md reference (major) | 10 |
+| 2 | 27, 28 | profile.md command + workflow — cost display | 4 |
+| 3 | 29 | settings.md workflow — routing strategy question | 2 |
+| 4 | 30 | USER-GUIDE.md — Model Profiles + routing section | 4 |
+| 5 | 31, 32 | AGENTS.md + COMPARISON.md updates | 4 |
+| 6 | 33 | INTERNALS.md — routing pipeline docs | 2 |
+
+**Verification gate:** `npm run test:all` all pass (doc changes don't affect code). Spot-check that model-profiles.md is picked up by installer manifest.
+
+---
+
+## Session Summary
+
+| Session | Focus | Items | Points | Cumulative |
+|---------|-------|-------|--------|------------|
+| 1 | Core routing engine + backward compat | 1-9, 16-18, 20, 22 | 38 | 38 |
+| 2 | Config + CLI integration | 10-15, 24-25 | 16 | 54 |
+| 3 | Complexity routing + per-phase override + remaining tests | 19, 21, 23, 34-36 | 16 | 70 |
+| 4 | Documentation | 26-33 | 26 | 96 |
+
+**Total: 4 sessions · 36 items · 96 points**
+
+---
+
+## Risk Register
+
+| # | Risk | Impact | Mitigation |
+|---|------|--------|------------|
+| R1 | MODEL_PROFILES change breaks existing tests | High | Update test expectations atomically; run tests after each file |
+| R2 | resolveModelInternal signature change breaks callers | High | New param is optional; zero-arg path identical to current behavior |
+| R3 | detectProvider() filesystem checks slow on network drives | Low | Cached per-session; only called once per resolve |
+| R4 | Legacy model_overrides with "opus" stop working | High | LEGACY_ALIASES maps opus→reasoning→inherit; explicit test coverage |
+| R5 | Config deep-merge drops existing user routing overrides | Medium | Follow existing pattern (spread hardcoded + user); test merge behavior |
+| R6 | Per-phase override parsing fragile with HTML comments | Medium | Strict regex; fallback to profile default on parse failure |
+| R7 | Cost estimation numbers misleading (no real token counts) | Low | Label as "relative multiplier", not dollar amounts; document limitations |
+
+---
+
+## Cut Line
+
+**Recommended MVP:** Sessions 1-3 (70 pts) — full working routing engine with tests.
+
+**Recommended full:** Sessions 1-4 (96 pts) — including all documentation.
+
+**Deferred (not in this plan):**
+- **Cascade routing** (try cheaper → escalate on failure) — XL complexity, requires quality gate heuristics, double-execution latency. Spec designed but implementation deferred until routing engine proves value in static + complexity modes.
+- **Real-time cost tracking** — out of scope per spec; PAN delegates execution to host runtimes.
+- **Non-Anthropic runtime testing** — only Claude Code currently consumes resolve-model output; other runtimes need integration work first.

package/docs/specs/opus_47_existing_enhancements_featureai.md

@@ -0,0 +1,247 @@
+---
+name: Opus 4.7 Existing Feature Enhancements
+type: feature-spec
+status: draft
+created: 2026-04-18
+owner: oharms
+related: [multi_model_routing_featureai.md, focus_auto_runner_featureai.md, lifecycle_completeness_featureai.md]
+---
+
+# Spec A — Opus 4.7 Enhancements to Existing PAN Features
+
+**Scope:** Fix and enhance what already exists. No new commands, no new agents. Every change maps to an existing file in `commands/pan/`, `agents/`, `pan-wizard-core/bin/lib/`, or `bin/`.
+
+**Guiding principle:** the installed surface stays identical (same commands, same agents, same CLI). Behavior gets faster, cheaper, and smarter by leveraging Opus 4.7 primitives (1M context, prompt caching, extended thinking, skills discovery, tool-use-first orchestration, memory).
+
+---
+
+## E-1. Prompt Caching Layer (Cross-Agent Cost Reduction)
+
+**Problem.** Every agent spawn re-sends project.md + requirements.md + roadmap.md + CLAUDE.md (~15-50K input tokens) per call. In a single `/pan:exec-phase` wave that spawns 6 executors + 1 reviewer + 1 verifier, that's ~300K repeated input tokens. Opus 4.7 supports `cache_control` blocks with a 5-minute TTL.
+
+**Change surface.**
+- `pan-wizard-core/bin/lib/core.cjs` — add `buildCachedContext(cwd)` helper returning an ordered list of `{path, content, cache: true}` blocks for project.md, requirements.md, roadmap.md, state.md, standards.md (stable across agent calls in a phase).
+- `pan-wizard-core/bin/lib/constants.cjs` — `CACHEABLE_CONTEXT_FILES` array.
+- `agents/*.md` — each agent's preamble changes from inlined "## Project Context" dumps to a system-level cache-controlled block the host runtime injects.
+- `commands/pan/exec-phase.md`, `plan-phase.md`, `verify-phase.md`, `focus-exec.md` — add a `## Cache Priming` stage that runs once per command invocation to warm the cache, then all sub-agent calls within 5 minutes read from cache.
+
+**Runtime compatibility.**
+- Claude runtime: uses `cache_control` natively.
+- Codex/Gemini/OpenCode/Copilot: each host has its own cache semantics or none. Shipped agent/command files declare cacheable blocks via a `<!-- cache:stable -->` marker the installer strips/translates per runtime.
+
+**Expected impact.** 40-60% input-token reduction across exec-phase. Measured via new `pan-tools stats cache-savings --phase N`.
+
+**Test additions.**
+- `tests/cache-priming.test.cjs` — verify buildCachedContext returns stable SHA of all context files.
+- `tests/scenarios/cache-warm-cold.test.cjs` — simulate two agent calls within TTL, assert second call's input-token counter is lower.
+
+---
+
+## E-2. Whole-Project Ingest in `map-codebase`
+
+**Problem.** `/pan:map-codebase` today spawns 6 parallel `pan-document_code` agents each with a 200K budget, each covering a slice of the repo. Outputs are stitched post-hoc and often contradict each other (one says "React 18", another says "React 19" because they read different lockfiles). With Opus 4.7's 1M context, medium codebases (≤800K tokens) fit in a single agent.
+
+**Change surface.**
+- `pan-wizard-core/bin/lib/codebase.cjs` — add `estimateRepoTokenSize(cwd, opts)` using the existing CHARS_PER_TOKEN constant + gitignore-aware walk.
+- `agents/pan-document_code.md` — add a `## Mode` section: `single-shot` (repo fits in 1M) vs `sharded` (current 6-way parallel). Threshold at 700K tokens (leaves headroom).
+- `commands/pan/map-codebase.md` — new Stage 0 that calls `pan-tools codebase estimate-size` and picks mode.
+
+**Runtime compatibility.** Opus 4.7 only for single-shot. Sonnet/Haiku and non-Claude runtimes always take the sharded path.
+
+**Expected impact.** On the typical PAN-sized project (~400K tokens), replaces 6 agent calls with 1 — 6× cost reduction and zero stitching artifacts. For large monorepos, falls back to current behavior.
+
+**Test additions.**
+- `tests/codebase.test.cjs` — `estimateRepoTokenSize()` returns under-estimate within 20% of actual.
+- `tests/scenarios/map-codebase-single-shot.test.cjs` — small temp repo, assert mode=single-shot.
+- `tests/scenarios/map-codebase-sharded-fallback.test.cjs` — simulated large repo, mode=sharded.
+
+---
+
+## E-3. Extended Thinking for Verification-Heavy Agents
+
+**Problem.** `pan-plan-checker`, `pan-verifier`, `pan-integration-checker`, `pan-reviewer` all do *judgment* work. They benefit most from Opus 4.7's interleaved thinking (reasoning before tool calls). Today they answer inline without reflection, leading to rubber-stamp verifications (the v2.8.0 retrospective flagged this as a recurring pattern).
+
+**Change surface.**
+- `agents/pan-plan-checker.md`, `pan-verifier.md`, `pan-integration-checker.md`, `pan-reviewer.md` — add `thinking: enabled` and a `thinking_budget: 8000` field in frontmatter. Each agent's opening instruction changes from "Analyze this plan" to "Think step-by-step, then report".
+- `pan-wizard-core/bin/lib/constants.cjs` — `THINKING_BUDGETS` map per agent type.
+- `bin/install-lib.cjs` — add `translateThinkingDirective(runtime, budget)` converting the frontmatter field into runtime-specific syntax (Claude: native; Codex: `<thinking>` block prompt; Gemini: system prompt prefix).
+
+**Runtime compatibility.** Claude native; others use prompt-level "think step by step" fallback.
+
+**Expected impact.** Targeted: plan-checker catches ≥30% more logic gaps pre-execution (measured by comparing pre-exec vs post-exec rework rates). Verifier false-positives drop.
+
+**Test additions.**
+- `tests/frontmatter.test.cjs` — `thinking` field round-trips.
+- `tests/install-lib.test.cjs` — translateThinkingDirective() per runtime.
+
+---
+
+## E-4. Agent Memory Layer (Cross-Phase Learning)
+
+**Problem.** PAN's only cross-agent memory today is state.md + phase summaries. Every planner starts from zero. Opus 4.7 has native memory; PAN should register persistent memory per agent scope.
+
+**Change surface.**
+- New module: `pan-wizard-core/bin/lib/memory.cjs` (sibling to state.cjs). Exports: `readMemory(cwd, agent)`, `appendMemory(cwd, agent, entry)`, `compactMemory(cwd, agent, maxEntries)`.
+- New directory: `.planning/memory/<agent-name>.md` — one file per agent, append-only log of "learned patterns" with timestamps.
+- Each agent's prompt reads `.planning/memory/<self>.md` at start and is instructed to append a single-line "lesson" at end (via a new `pan-tools memory append <agent> <text>` CLI path).
+- `commands/pan/retro.md` — after milestone, extract top-N lessons per agent and write to memory.
+
+**Runtime compatibility.** All 5 runtimes — this is a file-based mechanism, not an API-level memory.
+
+**Expected impact.** Planner references "we decided on pattern X in phase 4" in phase 9's plan without a human restating it.
+
+**Test additions.**
+- `tests/memory.test.cjs` — 10 test cases covering append/read/compact + schema validation.
+- `tests/scenarios/memory-across-phases.test.cjs` — E2E: run 2 phases, verify second phase's planner reads first phase's memory.
+
+---
+
+## E-5. Native Skills Registration (Claude Code Host Integration)
+
+**Problem.** Claude Code 1.x now loads skills from `.claude/skills/` (per the in-conversation skill list we observe at session start). PAN installs commands to `.claude/commands/pan/`, which Claude Code treats as slash commands — but doesn't expose them as skills-with-descriptions to other agents or to the user's available-skills list.
+
+**Change surface.**
+- `bin/install.js` — when target is `--claude`, also write a shim `.claude/skills/pan-<cmd>.md` for each command with the `name:`, `description:`, `trigger:` frontmatter matching Claude Code's skill schema. The shim body delegates to the existing `commands/pan/<cmd>.md`.
+- `bin/install-lib.cjs` — new exported function `buildClaudeSkillShim(commandFrontmatter)`.
+- For Copilot runtime: already uses `.github/skills/` — re-use identical shim generator.
+
+**Runtime compatibility.** Claude + Copilot only (both use skills dir). Codex/Gemini/OpenCode use their own command model — unchanged.
+
+**Expected impact.** PAN commands appear in Claude Code's skill list with descriptions, making auto-invocation possible ("when the user asks X, invoke pan:focus-scan").
+
+**Test additions.**
+- `tests/install-lib.test.cjs` — buildClaudeSkillShim() produces valid YAML frontmatter with name/description/trigger.
+- `tests/scenarios/claude-skills-installed.test.cjs` — after install, `.claude/skills/pan-*.md` count equals `commands/pan/*.md` count.
+
+---
+
+## E-6. Parallel-Tool Plan Execution in `focus-exec`
+
+**Problem.** `focus-exec`'s 6-stage pipeline runs stages sequentially even when stages are independent (Stage 3 prep + Stage 4 wave-1 planning can overlap). Opus 4.7 is markedly better at emitting parallel tool calls in a single assistant turn.
+
+**Change surface.**
+- `commands/pan/focus-exec.md` — rewrite Stage 3-4 section to explicitly instruct "emit all independent read/analyze tools in one turn".
+- `pan-wizard-core/bin/lib/focus.cjs` — new helper `classifyStageDependencies(items)` returns a DAG so the command template can generate the right instructions.
+- `agents/pan-executor.md` — add explicit parallel-tool-use encouragement block.
+
+**Runtime compatibility.** Claude Code + Opus: full benefit. Others: instructions are harmless prose.
+
+**Expected impact.** `focus-exec` wall-clock latency drops ~25% on multi-item batches.
+
+**Test additions.**
+- `tests/focus.test.cjs` — `classifyStageDependencies()` returns correct DAG for mixed-tier batches.
+
+---
+
+## E-7. Model Routing Extension — Cache & Think Tiers
+
+**Problem.** The v2.9.0 multi-model router has tiers (reasoning/mid/fast) but doesn't factor in *cache warmth* or *thinking-required*. A planner call with warm cache + thinking is a different cost/quality profile than a cold mid-tier call.
+
+**Change surface.**
+- `pan-wizard-core/bin/lib/core.cjs` — extend `resolveModel(task, opts)` with new opts: `cache_warm: bool`, `needs_thinking: bool`, `context_estimate: number`.
+- Logic:
+  - `context_estimate > 700K` → Opus 4.7 (only model with 1M).
+  - `needs_thinking` → Opus 4.7 or Sonnet 4.6 with extended-thinking.
+  - `cache_warm && !needs_thinking && context_estimate < 50K` → Haiku 4.5.
+- `.planning/config.json` — new `model_routing.tiers` section with defaults.
+- `commands/pan/profile.md` — extend to show tier decision tree.
+
+**Runtime compatibility.** Routing happens in core.cjs — runtime-agnostic. Non-Claude runtimes use their own tier aliases (already plumbed in v2.9.0).
+
+**Test additions.**
+- `tests/core.test.cjs` — `resolveModel()` truth table: 12 combinations of (ctx, thinking, cache).
+
+---
+
+## E-8. `pan-statusline` — Cache & Thinking Indicators
+
+**Problem.** The statusline shows `model | task | dir | context %` today. Opus 4.7 workflows have two new signals users should see: cache-hit rate and whether an agent is currently thinking.
+
+**Change surface.**
+- `hooks/pan-statusline.js` — read two new fields from stdin JSON: `cache_hit_rate_pct`, `thinking_active`. Render as `🧠` when thinking, `⚡N%` for cache hits.
+- `pan-wizard-core/bin/lib/context-budget.cjs` — extend health report to include cache metrics.
+
+**Runtime compatibility.** Claude only (other runtimes don't run hooks).
+
+**Test additions.**
+- `tests/statusline.test.cjs` — 4 new test cases for the new fields.
+
+---
+
+## E-9. Installer — Opus 4.7 Detection & Warnings
+
+**Problem.** Features E-1, E-2, E-3, E-6 give materially better results on Opus 4.7 vs older models. The installer should detect the user's default model and warn if they're on an older one for features that require it.
+
+**Change surface.**
+- `bin/install.js` — after settings.json is written, detect current `model` field. If set to an older Opus/Sonnet and user didn't pass `--skip-warnings`, print a yellow notice: "PAN 2.10+ is tuned for Opus 4.7. You're on X. Features E-1,E-2,E-3,E-6 degrade gracefully but benefit from upgrade."
+- `bin/install-lib.cjs` — new `detectModelCapabilities(modelName)` pure function returning `{has_1m_ctx, has_thinking, has_cache}`.
+
+**Test additions.**
+- `tests/install-lib.test.cjs` — 6 cases across model strings.
+
+---
+
+## E-10. Focus-Auto — Interleaved Thinking Between Cycles
+
+**Problem.** `focus-auto` loops scan→plan→exec. Between cycles it consults hardcoded stop-reason rules (max_cycles, zero_completed, regression). Opus 4.7's thinking mode can evaluate *whether the next cycle will be productive* before committing to it.
+
+**Change surface.**
+- `pan-wizard-core/bin/lib/focus.cjs` — new `determineContinuation(run, cycle, proposedNextBatch)` that emits a reasoning prompt consumed by the orchestrator agent before it calls `focus-plan` again.
+- `commands/pan/focus-auto.md` — new Stage between cycle-N-complete and cycle-N+1-start: "Reflection gate" with thinking.
+- `pan-wizard-core/bin/lib/constants.cjs` — `REFLECTION_THRESHOLD` (default: enabled on Opus, disabled otherwise).
+
+**Test additions.**
+- `tests/focus.test.cjs` — `determineContinuation()` emits valid prompt, respects threshold.
+
+---
+
+## E-11. `pan-debugger` — Chain-of-Thought Hypothesis Trees
+
+**Problem.** The debugger agent today uses the scientific method but emits hypotheses linearly. With thinking mode, it can explore a hypothesis tree in a single turn (generate 3, rank, test top).
+
+**Change surface.**
+- `agents/pan-debugger.md` — restructure the `## Investigation Protocol` section: replace "form hypothesis → test → refine" linear flow with "think through 3 hypotheses → rank by Bayesian prior → attack top 2 in parallel (parallel tool calls)".
+
+**Test additions.** Behavioral test via scenario: `tests/scenarios/debugger-parallel-hypotheses.test.cjs`.
+
+---
+
+## E-12. Fix: Oldest-Batch-First in `focus-exec` (shipped in this branch)
+
+Already applied: `readLatestBatch()` now sorts ascending. Kept here for completeness — this is a bugfix that fits Spec A's "fix existing features" mandate.
+
+---
+
+## Files to Create/Modify Summary (Spec A)
+
+| Category | Files | Count |
+|----------|-------|-------|
+| Core modules modified | core.cjs, codebase.cjs, focus.cjs, context-budget.cjs, constants.cjs | 5 |
+| Core modules new | memory.cjs | 1 |
+| Agents modified | all 12 | 12 |
+| Commands modified | exec-phase, plan-phase, verify-phase, focus-exec, focus-auto, map-codebase, retro, profile | 8 |
+| Hooks modified | pan-statusline.js | 1 |
+| Installer | install.js, install-lib.cjs | 2 |
+| Tests new | 11 new test files | 11 |
+| Docs | ARCHITECTURE.md, USER-GUIDE.md, new ADR-0023 (Opus 4.7 adoption) | 3 |
+
+**Estimated test count delta:** +90 to +110 tests.
+
+**Estimated LOC impact:** ~800 LOC added (core + tests), ~200 LOC deleted (redundant context-dumping in agents).
+
+---
+
+## Implementation Order (Recommended)
+
+1. E-1 (caching — foundation, biggest cost win)
+2. E-4 (memory — foundation, unlocks learning)
+3. E-3 (thinking — highest quality impact per LOC)
+4. E-7 (routing extension — glues E-1+E-3 into model choice)
+5. E-2 (single-shot map-codebase)
+6. E-5 (skills registration — Claude Code integration)
+7. E-10, E-11 (focus-auto reflection, debugger hypotheses)
+8. E-6 (parallel-tool execution)
+9. E-8, E-9 (UX polish)
+10. E-12 (already shipped)
+
+Each item is 1-3 days of focused work. Full Spec A ~6 weeks calendar.