pan-wizard 3.36.0 → 3.37.0

package/docs/specs/right-sized-ceremony.md

@@ -0,0 +1,74 @@
+# Right-sized ceremony: PAN's cost and time on well-specified work
+
+**Date:** `2026-10-24`, last amended `2026-10-25` · **Status:** Built; re-measurements below · **Owner decisions:** `2026-10-24` (right-sized by default; `quality` keeps the old behaviour; `--quality` per run)
+
+## The problem
+
+Three paired H10 runs (`docs/specs/product-excellence-superplan.md`, H10 row) compared PAN with Claude Code on its own, both on Opus 5.5, on precisely specified work. The bare host completed every rep. PAN completed the same work and cost much more:
+
+| Pair | Bare host | PAN | PAN ÷ bare |
+|---|---|---|---|
+| Single module, `/pan:quick --full` (discount codes) | $0.32, 72 s | $2.82, 748 s | about 9× cost, 10× time |
+| Two-phase roadmap, `autodev` | $0.62, 144 s | $19.19, 4,659 s (one rep; the next ran out of budget) | about 30× cost, 32× time |
+
+## Where it went (instrumented runs, `2026-10-24`)
+
+PAN's cost logger (`.planning/metrics/tokens.jsonl`) and autodev's ledger, on the same seeds, with PAN `3.36.0`:
+
+**`/pan:quick --full`, $2.67, 585 s.** Planner 214 s and 22k output tokens; plan-checker 111 s; executor 123 s (the work itself); verifier 48 s. The orchestrating session cost about $1.44, $1.10 of it cache writes (each new agent context re-caches its prompt and the project files).
+
+**One autodev phase pair, $10.00, 40 min.** plan-phase 1: $5.24 and 21 min. exec-phase 1: $2.86 and 9 min. plan-phase 2: $1.75 and 10 min. Per agent: the plan-checker ran four times (91k output tokens, about $2.06, 12 min) and the planner three times (68k, about $2.00, 12 min), because the checker sent the plans back for revision; the executor cost $0.63.
+
+**Reading.** About 70% of PAN's cost and time was planning ceremony on work whose requirements already said exactly what to build: research, then a planner and a plan-checker revising a plan, serially, every agent on the launch model at high effort. A cheaper model alone helps less than it seems: Sonnet 5.5 is half Opus 5.5's price, not a fifth.
+
+## What changed
+
+| Lever | `balanced` (default) and `budget` | `quality` |
+|---|---|---|
+| Ceremony | **Auto-sized** (`pan-wizard-core/bin/lib/sizing.cjs`): a phase whose requirements (at least one) each have an acceptance criterion or name the artifact to build is **lean** up to three times `workflow.lean_max_requirements` (15 requirements; one session holds a lean phase, and the planner designs anything larger): above `lean_max_requirements` (5) the engine splits it into plans of at most that many tasks: no research, one short plan, the engine's plan check instead of the plan-checker agent (`pan-tools size plan-check`, which records the plan check exec-phase needs), and execution without the test-generation agent (one reviewer pass and the verifier still run; autodev runs the phase in one session, `exec-lean`). A quick task whose description names an artifact and runs to 15 words or more is lean: the engine writes its one-task plan (`pan-tools size quick-plan`) and no planner runs. Anything else is **full** | Full everywhere |
+| Revision loop | One revision, then the user decides | Two revisions |
+| Checker output | Verdict and blocking issues only, a word budget | Unbudgeted |
+| Models | Plan-checker and researchers on the mid tier (Sonnet 5.5 on Claude) | Every agent on the reasoning tier |
+
+`--quality` on `/pan:quick`, `/pan:plan-phase`, `/pan:exec-phase` and `autodev run` (passed to every unit) gives one run the full ceremony; `--full` does the same for one command. `workflow.ceremony: full` keeps the full ceremony for a project without changing its models. `/pan:new-project` and `/pan:settings` describe the choice.
+
+**Not done: lower effort on checks.** Claude Code reads an agent's `effort:` from its file, and no workflow passes effort per run, so lowering it there would change `quality` too. It stays as it was.
+
+**Unchanged on purpose:** the executor's prompt (a tier-0 cassette records it, and re-recording needs an API key), the verifier on every phase (the phase gate needs its verdict), and every deterministic gate.
+
+## Re-measurement (`2026-10-24`, the same seeds, owner-approved $8 cap)
+
+Every run passed its project's tests and every case of the hidden acceptance check (`check-discounts.cjs`, `check-tasks.cjs`).
+
+| Task | PAN before | PAN after | Bare host | PAN ÷ bare, after |
+|---|---|---|---|---|
+| Discount codes | $2.67, 585 s (`/pan:quick --full`) | $0.44, 90 s (`/pan:quick`, lean: no planner, no checker) | $0.32, 76 s | 1.4× cost, 1.2× time |
+| Two-phase roadmap, `autodev` | $19.19, 4,659 s (H10 rep 1) | $4.52, 1,003 s (both phases built; stopped at the $4.50 cap before phase 2's separate verify unit) | $0.54, 121 s | 8× cost, 8× time |
+
+Autodev per unit after: plan-phase 1 $1.29 (256 s), exec-phase 1 $1.85 (466 s), plan-phase 2 $0.77 (143 s), exec-phase 2 $0.47 (109 s). No research and no plan-checker ran; one planner per phase and one executor per phase did.
+
+**Step 2 (built after this measurement).** A lean phase is planned by the engine: `pan-tools size phase-plan` writes one task per requirement from the requirements' own text, checks the plan in code, records the plan check and commits it, and `autodev` runs it for a lean phase's `plan` unit with no session, so a lean phase costs one exec-phase session. `/pan:plan-phase` uses it too.
+
+**Step 2 re-measured (`2026-10-24`, owner-approved $5 cap):** autodev on the same two-phase roadmap finished both phases (`done`) for **$3.09 in 691 s**, passing every hidden acceptance case: plan 1 by the engine ($0, 1 s), execute 1 $1.65 (353 s), plan 2 by the engine ($0, 1 s), execute 2 $1.44 (334 s). Against the bare host's $0.54 and 121 s that is **5.7× cost and 5.7× time, down from about 30×** ($19.19 and 4,659 s before right-sizing). What remains is the exec-phase session itself (the executor, the verifier and the orchestrating workflow), about $1.50 and six minutes a phase.
+
+**Bug found by the run, fixed:** when the cap was spent mid-unit, a retry started a session with `--max-budget-usd 0.00`, which Claude Code refuses; a retry now stops with `budget_usd` first.
+
+## Optimisation set 2 and the regression check (`2026-10-24`, owner-approved $10 cap)
+
+**Change:** autodev's unit prompt now starts with the command (`/pan:exec-phase 1 (PAN autodev unit, unattended: …)`). The earlier transcript showed each unit spending its first turns finding the command, because inside a sentence Claude Code did not expand it; now the host expands it and the session starts at `init`. **Effect on cost: within noise** ($2.89 against $3.09 for the two-phase roadmap; units ran engine plan $0, execute $1.87, engine plan $0, execute $1.02). The exploration turns were cheap; what each session pays is its fixed context: about 90k tokens of cache writes (Claude Code's system prompt and tools, the workflow, the agents' results), about $0.45 a session, and PAN's MCP tool list is only about 2,300 tokens of it.
+
+**Regression check, live:**
+
+| Check | Result |
+|---|---|
+| Lean autodev, two phases | `done`, $2.89, 745 s; hidden acceptance check passed |
+| `/pan:quick --full --quality` (the old path) | planner, plan-checker and verifier all ran; $2.00, 618 s; hidden check passed |
+| `/pan:plan-phase 1` on a vague phase (`clarify-export`) | sized `full` by itself: the planner wrote two plans, no engine plan; the plan-checker did not run before the session's $2.50 cap |
+
+Plus a fresh packed install on all five runtimes (no errors; `size` answers in each runtime's core; the engine plans a lean phase and exec-phase reads its plan check as `ok`) and the full local CI.
+
+**Where the rest of autodev's cost is:** per phase, an orchestrating session (about $0.85: mostly that fixed context), the executor (about $0.40) and the verifier (about $0.17). Plain Claude Code pays one session's fixed context for the whole job. The levers left are structural: run consecutive lean phases in one execute session, or let the engine's gates stand in for the verifier on a lean phase (a quality trade the H4 corpus cannot yet price, since its defects are too easy).
+
+**One session per lean phase (`2026-10-25`).** For a lean phase, autodev's execute unit no longer starts `/pan:exec-phase` (an orchestrating session with an 11k-token workflow that then spawns a separate executor). It hands the session `pan-wizard-core/workflows/exec-lean.md`, which does the executor's work in that session (the plan as specification, tests never weakened, `supersedes_tests` recorded as deviations, a commit per task, the summary and state updates) and then spawns the verifier and records its verdict (and, since the quality check below, one reviewer pass before it). The phase gate and `phase complete` stay in autodev. The verifier stays, so quality is unchanged; what goes is one session's fixed context and the orchestration turns. A full phase and `--quality` keep exec-phase.
+
+**Does the lean path drop quality? (`2026-10-25`, owner-approved $3).** The same `pan-reviewer`, same prompt, over the lean brief build and a bare host's brief build, both 33/33 on the hidden check: lean 1 high, 1 medium, 1 low (a save that overwrites the live file, so a crash mid-write loses the shop; `Number.isInteger` past the safe range; dates not normalised); bare 1 high, 2 medium, 1 low (restock past the safe range saves a file `load` then rejects; unchecked totals; an empty file read as an empty shop with no flush before rename; two instances on one file). Equivalent builds, the lean one at 193 lines and 46 tests against 336 and 21. Reading: no quality drop on this evidence, and one defect in each build that neither the tests nor the verifier could see. So the lean path now keeps **one reviewer pass** (`exec-lean` step 4, and exec-phase's `code_review` on a lean phase): about $0.40 a phase; a `NEEDS_FIXES` gets one fix round, and what stays open is recorded as deferred, never passed silently. $2.08 spent (two reviews at $0.38 and $0.42, a bare rebuild at $1.28 that the harness's $1-a-session floor stopped after two of four sessions, the product already complete).

package/docs/specs/roadmap_and_competition_2026_q4_featureai.md

@@ -0,0 +1,390 @@
+# /featureAI Spec: Q4 2026 Roadmap and Competitive Analysis
+
+**Date:** `2026-10-11`
+**Status:** Realigned `2026-10-12` — the owner set features first and exposure later. The program is now `product_excellence_program_2026_q4_featureai.md`; this spec's competitive analysis stands as background, its publication bet (F3) moves to that program's deferred Exposure phase, and F1 and F2 are absorbed there (R45 in W1; R46 by V9 and V1 in W1, with V2 in W2).
+**Tree:** `feat/memory-optimization-2026-10` @ `4994ed5` (`3.34.0`, released `2026-10-10`) plus the same-day doc audit's working tree
+**Supersedes:** `industry_comparison_and_feature_gaps_featureai.md` (`2026-02-28`) and `industry_analysis_strategic_additions_featureai.md` (`2026-03-03`) as the strategic read
+**Evidence base (all `2026-10-11`):** the market idea scan with a feature-level read of Superpowers (ledger rows MI-110 to MI-126), the doc audit, the reality check (§11 of `docs/ECOSYSTEM-REVIEW-2026-08.md`), and a feature-level landscape of Spec Kit, BMAD, gsd-core and OpenSpec read from their READMEs, docs, releases APIs and registries. Queue ids (M, R) refer to the Addendum of `docs/specs/market-ideas-2026-10.md`.
+
+---
+
+## Phase 0: Problem Framing
+
+### 0.1 Problem statement
+
+PAN Wizard is ahead of its category on rigour and nearly invisible in it. The reality check found a product that does what its docs say on all five runtimes. It has a behavioural harness that installs from a packed artifact, an MCP server with a forbidden-verb list and a human merge gate, a cost ledger priced from a dated rate table, and deterministic orchestration beside portable markdown workflows. No direct peer was found with all four. But `pan-wizard` drew 1,599 npm downloads from `2026-09-11` to `2026-10-10` (api.npmjs.org). OpenSpec drew about 2.9 million and BMAD about 77,500 in a comparable window. Superpowers is listed in three official plugin marketplaces; PAN is listed in none. Three things make this the quarter to act:
+- **The peers are moving onto PAN's ground.** gsd-core shares PAN's `.planning/` file vocabulary and loop. BMAD v7 adds an eval tool. Superpowers runs an eval lab against real CLIs.
+- **The distribution channels have opened.** Anthropic takes directory submissions through a developer portal, and Codex and Copilot ship default marketplaces.
+- **A host is changing under PAN.** OpenCode 2 is now pushed to users and does not load PAN's plugin.
+
+### 0.2 Scope
+
+| In scope | Out of scope |
+|---|---|
+| A sequenced roadmap for `2026-10` to `2026-12`: correctness, publication, measured behaviour, plan quality | A sixth runtime (MI-017), standardising `.planning/` (MI-018), skills-marketplace listings on quality grounds alone (MI-020) |
+| A competitive analysis of the direct peers and the host-tool natives | The IDE peers in `docs/COMPARISON.md`, whose rows did not change this quarter |
+| Implement-ready specs for the roadmap's first items (F1, F2) and design-level specs for the strategic ones (F3, F4, F5) | Building anything: this spec feeds `/execplan` |
+| The decisions only the owner can make, named and sized | Telemetry of any kind (MI-056) |
+
+### 0.3 Success criteria (roadmap level)
+
+```text
+SC-1: PAN's plugin is installable from at least one official marketplace (Anthropic's directory, Codex's or Copilot's default marketplaces) by 2026-12-31, from a tracked artifact a test validates.
+SC-2: Every capability claim in README.md and docs/COMPARISON.md is backed by code or a harness scenario; the claims audit of the next reality check finds no FALSE row and no WEAKENED row in PAN's own column.
+SC-3: The OpenCode plugin loads on OpenCode 1.x and 2.x, proven by a live check on each.
+SC-4: A failed test gate cannot complete a phase on any runtime, enforced by code that a test pins.
+SC-5: At least one portable behavioural chain (exec-phase) passes the harness on a second host CLI (MI-104).
+SC-6: UAT runs as a command on all five runtimes and feeds the diagnose loop (closes the COMPARISON "UAT only as a template" row).
+SC-7: No regression: the full suite, every release gate and harness tier 0 stay green at each step.
+```
+
+### 0.4 User stories
+
+```text
+As a developer choosing a planning framework, I want to find and install PAN from my host's marketplace,
+so that I can try it in one step, instead of discovering it on npm and reading an install guide.
+
+As an OpenCode user moved to OpenCode 2, I want PAN's compaction hand-off to keep working,
+so that a long session resumes where it stopped, instead of losing PAN's position silently.
+
+As a team lead relying on verification, I want a failing test suite to stop the phase in code,
+so that a verifier's mistaken "passed" cannot ship broken work, instead of trusting the prompt.
+
+As a product owner, I want to walk a phase's acceptance criteria with the agent and have gaps diagnosed,
+so that UAT is part of the loop, instead of a template nobody runs.
+
+As a maintainer, I want the portable chain proven on more than Claude Code,
+so that "works on five runtimes" means behaviour, not only installation.
+```
+
+---
+
+## Phase 1: Internal Reconnaissance (what the reality check established)
+
+### 1.1 Strengths, with evidence
+
+| Strength | Evidence |
+|---|---|
+| Installs and runs on all five runtimes | Packed-tarball install of all five in seconds; `validate deployment` clean on each; harness tier 0 all green except the Antigravity gate (no `agy`) |
+| Fresh context per plan | `workflows/exec-phase.md` spawns `pan-executor` with paths only; tier-2 chain scenarios count reads from each executor's own transcript |
+| Deterministic orchestration where control flow is knowable | Native Claude Code workflow scripts (`buildNativeWorkflowScripts` in `bin/install-lib.cjs`) beside portable markdown; the oracle measured parity (MI-002) |
+| Engine over MCP with guard rails | `pan-wizard-core/mcp/`: fixed registry, `FORBIDDEN_VERB`, no-shell spawn, a per-request merge token; every resource reads cleanly on a bare project |
+| Cost ledger correctness | Dated rate table re-read from the pricing page; long-prompt pricing (MI-107); per-agent transcript attribution; usage-window stop (MI-109) |
+| Behavioural harness against packed installs | `harness/` tiers 0–2 with a findings ledger (ADR-0047) |
+| Documentation trust | Counts live in one file; doc-lint and model-version lints gate the suite; the doc audit's prompt sweeps found real code bugs |
+
+### 1.2 Weaknesses, with evidence
+
+| Weakness | Evidence | Roadmap answer |
+|---|---|---|
+| Invisible | 1,599 npm downloads in the last month; no official marketplace listing; no GitHub stars recorded since the repository went public | F3 |
+| Some guarantees are prompt-only | The verifier's test gate (RC3); the `/pan:army` merge gate (README says so); the MCP caps use caller-supplied counts | F2, and honest wording (done) |
+| UAT does not run | No command writes a UAT file; `diagnose-issues.md` is loaded by no command; the native diagnose script exists on Claude Code only | F4 |
+| Behaviour proven on one host | The model tiers of the harness run on Claude Code only (MI-104 plumbing built, parsers missing) | H3 |
+| OpenCode 2 plugin break | v2's loader needs `setup` or `effect` (RC1) | F1 |
+| Plan quality depends on prose | No Review Focus, no executor concerns state, some spawns inherit the session model | M39, M41, M42 |
+
+### 1.3 Runtime matrix today
+
+| Runtime | Commands/skills | Agents | Hooks / observers | MCP | Native workflows | Behaviour proven |
+|---|---|---|---|---|---|---|
+| Claude Code | ✅ | ✅ | ✅ full set | ✅ `.mcp.json` (global: printed command) | ✅ | ✅ tier 2 |
+| Codex | ✅ `.agents/skills` | ✅ `.toml` | ✅ (async observers) | printed TOML snippet by design | — | install and MCP listing only |
+| Gemini CLI | ✅ `.toml` | ✅ | partial: no monitor or loggers (no matching event) | ✅ | — | install and MCP listing only; live model runs blocked on an API key |
+| OpenCode | ✅ | ✅ | plugin (compaction only; breaks on v2) | ✅ (v1 shape, which v2 normalises) | — | install, discovery and MCP listing |
+| Copilot CLI | ✅ | ✅ `.agent.md` | ✅ | ✅ `.github/mcp.json` | — | install, MCP, a live compaction check |
+
+---
+
+## Phase 2: Competitive Analysis
+
+### 2.1 Positioning
+
+| Project | Position in its own words (paraphrased) | Centre of gravity |
+|---|---|---|
+| **PAN Wizard** | A planning, state and verification layer installed into five host CLIs | Rigour and portability: durable state, gated loop, measured behaviour |
+| **Superpowers** (`obra/superpowers`, v7.0.0 `2026-10-10`) | A skills plugin that changes how the agent works: brainstorm, plan, subagent-driven development, TDD, review | Behavioural discipline through always-loaded skills; widest marketplace presence |
+| **gsd-core** (`open-gsd/gsd-core`, v1.16.0 `2026-10-05`) | Lightweight meta-prompting and context engineering; fresh-context subagents through discuss, plan, execute, verify, ship | The closest twin: same `.planning/` vocabulary, many gates, cross-AI reviewer lanes |
+| **Spec Kit** (`github/spec-kit`, v1.1.3 `2026-10-09`) | Structured processes and templates for any agent: spec-driven development, bug fixing, idea assessment | Breadth: widest agent coverage, extension catalog, workflow engine |
+| **BMAD** (`bmad-code-org/BMAD-METHOD`, v6.12.2 `2026-10-11`; v7 preview) | Agile AI-driven development with product, architecture, UX, dev and test perspectives | Planning depth through personas; v7 moves to skills-native distribution |
+| **OpenSpec** (`Fission-AI/OpenSpec`, v1.14.1 `2026-10-06`) | A lightweight spec layer so human and agent agree before code is written | Simplicity and reach: delta specs, a strict validator, the largest install base |
+
+### 2.2 Capability matrix
+
+Y = shipped · P = partial or weaker · N = not found on `2026-10-11` · B = beta or preview. PAN's column is from the code; the others are from each project's own README, docs and releases.
+
+| Capability | PAN | Superpowers | gsd-core | Spec Kit | BMAD | OpenSpec |
+|---|---|---|---|---|---|---|
+| Durable planning state | Y `.planning/` | P dated spec and plan files, ephemeral run ledger | Y `.planning/` + a JSON state contract with transactions | Y `.specify/` per feature | Y `_bmad-output/`; v7 initiatives | Y `openspec/specs` + delta changes |
+| Research before planning | Y researcher agents | P brainstorming with optional recon | Y researchers, claim provenance | Y plan Phase 0; `assess` extension | Y deep-recon packs | N (reads code first) |
+| Plan verification | Y plan-checker loop | Y self-review + user review of the plan | Y plan-checker and several gates; plans reviewed by other AIs | Y `analyze`, checklists | Y readiness gate | Y `validate --strict` |
+| Fresh context per unit of work | Y | Y per task (SDD) | Y per executor, parallel waves | N (agent's own session) | P (`bmad-build-auto`; bmad-loop) | N |
+| Parallel worktrees | P Claude-only army | N by design (one worktree per plan) | Y on by default, several runtimes | P community extension | P bmad-loop (beta), five CLIs | N |
+| Post-execution verification | Y verifier + test gate (prompt-enforced) | Y verification before completion, final review | Y goal-backward verify, invalidation on change, API coverage | Y `converge` loop | Y coverage audit, re-verification | Y `verify` (skipped ≠ passed) |
+| UAT that runs | N template only | N | Y in `verify-work`; live-DOM UAT (off by default) | P bug extension's verified/partial/failed | P walkthrough skill | N |
+| Review agents | Y reviewer, hardener, meta-reviewer | Y task + final reviewer | Y review pipeline, disposition ledger | P community | Y multi-layer parallel review | N |
+| Behavioural evals of the framework | Y harness vs packed installs, findings ledger | Y Quorum lab vs real CLIs (separate repo) | P mutation testing, conformance tiers | P `selftest` extension | B `bmad-eval` (v7) | N (QA smoke harness unshipped) |
+| Cost ledger / model routing | Y ledger, dated rates, profiles, usage-window stop | P per-role model guidance in prose | P profiles, failure escalation; no rate table | P per-step model | P handoff routing | N |
+| MCP server | Y read tools + gated merge | N | Y read and write state (no merge gate found) | B read-only, experimental | N | N |
+| Hooks | Y four runtimes + OpenCode plugin | Y session-start bootstrap | Y monitor and several guards | Y extension and native hooks | P customization hooks | N |
+| Deterministic orchestration | Y native scripts on Claude Code | N | B Workflow-tool capability, Claude-only | Y workflow engine (YAML) | P bmad-loop (Python) | N |
+| Runtimes targeted | 5 (+ Antigravity via `.agents/`) | ~15 harnesses | 16 (dropped Gemini CLI in v1.15.0) | 42 integration keys | 48 install targets (v6) | ~44 tools |
+| Official marketplace listings | none | Claude, Codex-curated, Grok | none (self-hosted) | none | none (own marketplace) | none |
+| Telemetry | none (MI-056) | opt-out logo ping in one tool | none (a recorded non-goal) | none found | none found | on by default, opt-out |
+
+### 2.3 Momentum (last 90 days, from `2026-07-13`)
+
+| Project | Releases (GitHub API) | Downloads per month (primary registry unless marked) | Stars (secondary) |
+|---|---|---|---|
+| PAN Wizard | 6 | npm 1,599 | none recorded |
+| Superpowers | 5 | (plugin installs: ~1.15M official-marketplace installs, a scrape of Anthropic's endpoint, secondary) | ~297k |
+| gsd-core | 11 | npm ~46.5k (+ ~60k on the legacy package) | ~10k |
+| Spec Kit | 44 | PyPI ~84k (pypistats, secondary) | ~141k |
+| BMAD | 4 on v6 (v7 unreleased) | npm ~77.5k | ~54k |
+| OpenSpec | 11 | npm ~2.9M; Homebrew ~1.7k | ~72k |
+
+### 2.4 Where PAN stands
+
+- **Ahead (protect):**
+  - The harness against packed installs.
+  - The MCP merge gate. gsd-core's MCP writes state with no merge gate found.
+  - The dated cost ledger.
+  - Deterministic plus portable orchestration with a measured parity oracle.
+  - **Threat to these:** Superpowers' Quorum and BMAD's `bmad-eval` make "we test the framework itself" a contested claim within a quarter.
+- **Parity:**
+  - Durable state (gsd-core matches it file for file).
+  - Plan verification.
+  - Fresh-context execution (Superpowers, gsd-core).
+  - Review agents (BMAD's layered review is richer on adversarial and intent layers).
+- **Behind:**
+  - Distribution and reach on every measure.
+  - Running UAT (gsd-core).
+  - Parallel worktrees beyond Claude Code (gsd-core, bmad-loop).
+  - Cross-AI review (gsd-core reviewer lanes; MI-044 is WATCH).
+  - Runtime breadth. This is by decision (MI-017); it is a positioning choice, not a gap to close.
+- **Converging signals:**
+  - Explicit model choice per dispatch (Superpowers).
+  - Verification invalidated by change (gsd-core; PAN has MI-067).
+  - Skipped is not passed (OpenSpec; PAN has MI-064).
+  - Evals of the framework (three peers).
+  - The read on `2026-09-10` holds: the market converged on PAN's thesis. The gap is publication, and now also proof of behaviour off Claude Code.
+
+### 2.5 Differentiation statement
+
+PAN is the planning, state and verification layer whose behaviour is measured against what users actually install, on every host it supports, with spend and merges under explicit control. The roadmap keeps every item inside that sentence. Anything that only widens reach (more runtimes, telemetry, marketplace spam) or only adds ceremony (personas, always-on bootstraps) is out.
+
+---
+
+## Phase 3: Design — the roadmap
+
+### 3.1 Three strategic bets
+
+1. **Get found (publication).** One official marketplace listing by year end, from a tracked artifact (F3). Every review since August names this gap. Two peers with smaller rigour have larger reach because of it.
+2. **Make every guarantee true in code (trust).** The test gate (F2), UAT that runs (F4), the OpenCode 2 plugin (F1), explicit models on every spawn (M39). The audit this quarter showed the docs had drifted ahead of the code in exactly these places.
+3. **Prove behaviour beyond one host (evidence).** The portable chain on a second host CLI (MI-104), a baseline arm before any prompt change (M43, MI-114), and live re-runs of the two open findings (R49). This keeps PAN's lead on evals while two peers build theirs.
+
+### 3.2 Horizons
+
+| Horizon | Window | Theme | Items | Exit |
+|---|---|---|---|---|
+| **H1** | `2026-10` | Correctness and trust | F1 (R45), F2 (R46), M39, R47, R48, the local-marketplace path (RC10) | SC-3, SC-4; no spawn inherits the session model |
+| **H2** | `2026-11` | Publication and plan quality | F3 (MI-025, after the owner's decision), M41 Review Focus, M42 executor concerns, the Antigravity variant once `agy` confirms the manifest (MI-026) | SC-1 submitted; plans carry Review Focus |
+| **H3** | `2026-12` | Measured behaviour | F4 UAT that runs, MI-104 second-host chain, M43 then M35, R49; F5 cross-AI review lane as a design spike | SC-5, SC-6; open harness findings resolved |
+
+### 3.3 Decisions only the owner can make
+
+| Decision | Blocks | Options | Recommendation |
+|---|---|---|---|
+| Plugin hosting | F3 | (a) a tracked plugin folder in this repo, committed by the release workflow, submitted through Anthropic's developer portal; (b) a second npm package with `source: npm` | (a): the portal tracks a public repo's folder or tag. It is the model the one listed peer uses (a pinned commit). It keeps a single package |
+| Harness spend cap | MI-104, M43, M35, R49 | a per-run `--max-usd` | A standing monthly cap, recorded in `harness/README.md` **Decided `2026-10-12`: none** — per-run `--max-usd` (program §3.4) |
+| Gemini API key | Gemini live checks (M33, MI-051) | a key in the environment for live gates only | Provide one, or accept "Gemini behaviour unproven" in COMPARISON |
+| ADR-0049 acceptance | none in code; doc truth | accept or amend | Accept: M11 and M12 shipped on it in `3.32.0` **Accepted `2026-10-12`** |
+
+### 3.4 What not to do (re-affirmed for the roadmap)
+
+All the entries carried in the reality check hold. The roadmap adds four:
+- **Do not chase runtime count.** Peers list 15 to 48 targets. PAN's answer is proven behaviour on its five (MI-017).
+- **Do not add personas or an always-on bootstrap skill.** Both trade progressive disclosure for ceremony (MI-119).
+- **Do not emit OpenCode v2 config shapes** while the published schema is v1.
+- **Do not ship telemetry to measure reach.** Registry download counts and marketplace install counts are enough (MI-056).
+
+---
+
+## Phase 4: Specifications
+
+### F1 — OpenCode plugin for v1 and v2 (R45, H1, P1, S)
+
+**Problem:** OpenCode 2's loader requires a default export with `id` and `setup` (or `effect`) and throws "Plugin must export a default definition with an id and an effect or setup function". PAN exports `{ id, server }`, so the compaction hand-off is lost on v2. The documented fix (`opencode.ai/v2/docs/build/plugins`, migrate-v1 page) is one object carrying both: v1 calls `server()`, v2 calls `setup()`. It needs OpenCode ≥1.18.29.
+
+**Files**
+- `pan-wizard-core/opencode/pan-wizard.js`: add `setup(ctx)`.
+- `tests/opencode-plugin.test.cjs`: the export-shape test changes from "`{ id, server }`, nothing else" to "`id`, `server`, `setup`", plus the cases below.
+- `docs/HOOKS.md`, `docs/TROUBLESHOOTING.md`: one line each on v2.
+
+**Implementation steps**
+1. Factor the existing compaction body into `pushBlock(directory, target)`. It is fail-open and inert outside work in flight.
+2. Add `function setup(ctx)`. It resolves the directory like `server` (`ctx.directory || ctx.worktree || process.cwd()`) and calls `ctx.session.hook('compaction', (e) => { … })`. The handler pushes the block onto `e.system` when that is an array. Otherwise it pushes onto `e.context` when that is an array, otherwise it does nothing. Wrap everything in try/catch.
+3. Export `module.exports = { id: 'pan-wizard', server, setup }`. Keep CommonJS: the installer writes `{"type":"commonjs"}` above `plugins/`.
+4. Live check on `@opencode/cli` 2.0.26 in a scratch home. Install PAN with `--opencode`, start a session with a phase in flight, and run `/compact`. The summary must carry PAN's block. Record the event's actual field names, because `system` was read from the binary, not the docs. If the field differs, change step 2 and its tests before shipping.
+
+**Tests (at least 10)**
+- Happy path:
+  - (1) `setup` registers exactly one `compaction` hook on a fake `ctx.session`.
+  - (2) Firing it with `{ system: [] }` pushes one block equal to the `server` path's block.
+  - (3) `server` behaviour is unchanged (the existing parity tests still pass).
+  - (4) `PAN_TRACK` routing works through `setup`.
+- Edge cases:
+  - (5) No `ctx.session` or no `hook` function: `setup` returns without throwing.
+  - (6) An event with neither `system` nor `context`: no throw, no write.
+  - (7) No phase in flight: nothing pushed.
+  - (8) The block is truncated at the same cap.
+- Error cases:
+  - (9) A throwing `hook` does not escape `setup`.
+  - (10) A `.planning/` read error inside the handler is swallowed.
+- Runtime-specific:
+  - (11) The installer still copies the file byte for byte for OpenCode only.
+  - (12) Uninstall still removes it and keeps the user's plugins.
+
+**Runtime matrix:** OpenCode 1.x (≥1.18.29) and 2.x ✅. The other four runtimes are unaffected (no plugin).
+
+### F2 — The test gate enforced in code (R46, H1, P1, M)
+
+**Problem:** The verifier's prompt says a failed or non-running suite means `gaps_found`. The recorder (`verdictFromVerificationFrontmatter` in `pan-wizard-core/bin/lib/verdict.cjs`) only warns `test_gate_failed_under_pass` and keeps `passed`. `workflows/exec-phase.md` routes on the word `findings record --raw` prints. A verifier that writes `status: passed` with `test_gate: failed` therefore completes the phase.
+
+**Files**
+- `pan-wizard-core/bin/lib/verdict.cjs`: the frontmatter adapter.
+- The `findings record` command module (read `cmdFindingsRecord` first).
+- `pan-wizard-core/bin/lib/verify-*.cjs`: the module behind `verify reconcile`.
+- Tests: `tests/verdict*.test.cjs` and the reconcile tests.
+- `README.md` (revert the interim wording to the stronger claim once true), `docs/CLI-REFERENCE.md`, `agents/pan-verifier.md` (unchanged rule, now backed).
+
+**Implementation steps**
+1. In the adapter, when `test_gate === 'failed'` and the outcome is pass, set the outcome to gaps. Add a finding of class `defect` ("the test gate failed under a passed status") and keep the warning text for the trace.
+2. In `findings record --raw`, print the adjusted word. exec-phase's routing table then sends the phase to gaps without any prompt change.
+3. In `verify reconcile`, treat the same case as a contradiction (exit 1). That covers the auto-advance gate in `transition.md`, which reads the file's own `status:`.
+4. Leave `test_gate: skipped` alone. Skipped already surfaces through `not_checked` (MI-064). A missing `test_gate` stays a warning.
+
+**Tests (at least 10)**
+- Happy path:
+  - (1) passed + gate passed → passed.
+  - (2) gaps + gate failed → gaps.
+  - (3) passed + gate skipped → passed with `not_checked` intact.
+- Edge cases:
+  - (4) passed + gate failed → gaps, plus one defect finding.
+  - (5) A missing `test_gate` → passed with the existing warning.
+  - (6) An unknown gate value → the existing warning, no downgrade.
+  - (7) CRLF frontmatter gives the same result.
+- Error cases:
+  - (8) `reconcile` exits 1 on passed + gate failed and prints why.
+  - (9) A verification file with no status → `no_verdict` as today.
+- Runtime-specific:
+  - (10) The exec-phase routing snippet, run in a sandbox, routes to gaps.
+  - (11) The native `pan-exec-waves` script's verification read takes the same path (check how it reads the status).
+
+**Runtime matrix:** all five ✅. The CLI is shared; the change is in the engine, not in host-specific text.
+
+### F3 — Publication pipeline (MI-025, H2, P5, L; needs the hosting decision)
+
+**Design (option a, recommended):**
+- A release-workflow job runs `npm run build:plugin`, then commits the result to a tracked `plugins/pan-wizard/` folder (or a `plugin` branch), tagged with the release.
+- A root `.claude-plugin/marketplace.json` lists it with a relative source, so `claude plugin marketplace add oharms/PanWizard` works from GitHub.
+- The Codex (`.agents/plugins/marketplace.json`) and Copilot (`.github/plugin/marketplace.json`) manifests point at the tracked Agent Plugins bundle, not the untracked `./dist/`.
+- Submission goes to Anthropic's developer portal, then the Codex and Copilot default-marketplace processes, and Grok's marketplace, which consumes the Claude format.
+
+**Gates:**
+- `claude plugin validate` on the tracked folder.
+- A harness live gate that adds the marketplace from the GitHub URL in a scratch home and lists PAN's commands.
+- Gate 8 extended: the tracked folder matches a fresh build.
+
+**Risks:**
+- A tracked build doubles the diff on each release: a dedicated folder plus a release-only job keeps it out of feature PRs.
+- Review latency at each marketplace: start with the one already shown to list peers.
+
+**Runtime matrix:**
+- Claude Code: plugin.
+- Codex and Copilot: Agent Plugins bundle.
+- Gemini and OpenCode: unchanged (npm installer).
+- Antigravity: after MI-026.
+
+### F4 — UAT that runs (H3, P4, L)
+
+**Problem:**
+- The UAT template (`templates/uat.md`) exists.
+- The diagnose workflow (`workflows/diagnose-issues.md`) reads a UAT file and spawns `pan-debugger` per gap.
+- The native `pan-diagnose-issues` script does the same on Claude Code.
+- But no command writes a UAT file, so the chain never starts. The COMPARISON row is "UAT only as a template no command runs". gsd-core runs UAT inside its verify step.
+
+**Design:**
+1. Add a `--uat` mode to `/pan:verify-phase`, as a markdown workflow so it works on all five runtimes.
+2. It reads the phase's success criteria from the roadmap slice and the verification report.
+3. It walks the user through them one at a time (one question per message, the user's verdict recorded verbatim).
+4. It writes `{phase}-uat.md` from the template, with `status: complete` or `status: gaps`, then hands any gaps to `diagnose-issues`: markdown everywhere, the native script on Claude Code.
+5. In auto mode it never runs: a human verdict is the point. It prints the command instead.
+
+**Gates:**
+- A template round-trip test with `extractFrontmatter`.
+- A workflow text test that the mode loads `diagnose-issues.md`.
+- A tier-2 harness scenario with a scripted user (the MI-049 driver pattern) that marks one criterion failed and asserts a diagnosed `uat.md` and a gaps plan.
+
+**Runtime matrix:** all five ✅ (markdown). The native diagnosis is Claude Code only, as today.
+
+### F5 — Cross-AI review lane (H3 spike, P5, M; MI-044 WATCH → design)
+
+**Problem:** gsd-core sends plans to other AIs through declared reviewer lanes, and BMAD lets an external model take a review layer. PAN's reviewers are all one model family.
+
+**Design (spike only this quarter):**
+- A `review.lanes` config entry names a host CLI already installed (for example `codex exec` or `gemini -p`).
+- `/pan:review-deep` runs that lane's prompt on the diff in a read-only mode, and its findings go through the same `findings record` path.
+
+**Spike exit:** one lane runs on this machine with a captured cost, and its findings parse into the ledger.
+
+**Hard constraints:**
+- No shell interpolation of the diff.
+- A foreign CLI's cost must be readable (the MI-104 parser rule) or the lane is refused.
+
+**Runtime matrix:** a reviewer lane runs from any host. Lanes are opt-in.
+
+---
+
+## Phase 5: Risk Assessment
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| The v2 compaction event's fields differ from what was read in the binary | F1 ships a no-op on v2 | Medium | The live check in F1 step 4 gates the release; the handler tolerates both `system` and `context` |
+| F2 turns a verifier's honest mistake into a stopped phase | Users see more `gaps_found` | Medium | That is the intended behaviour; the gap message names the failed gate and the fix path |
+| Publication review rejects or delays the listing | SC-1 slips | Medium | Submit to the channel where a peer is already listed; keep the npm path working throughout |
+| A tracked plugin build drifts from the source | Users install stale prompts | Low | Gate 8 extended to compare the tracked folder with a fresh build |
+| Cross-host harness runs cost more than planned | H3 slips | Medium | Per-run `--max-usd` approvals; tier 0 stays free and green; cassette replay (program H2) keeps reruns free; model tiers run per release, not per commit |
+| UAT mode stalls headless sessions | Auto runs hang | Low | `--uat` refuses auto mode and prints the command |
+| Peers' eval labs out-pace PAN's harness | The "measured behaviour" claim weakens | Medium | H3 widens the harness to a second host; COMPARISON states dated, sourced verdicts only |
+| OpenCode 1.x users break if PAN writes v2 shapes | Config rejected under the closed v1 schema | High if done | Recorded as a "What not to do" entry |
+
+---
+
+## Sources (read `2026-10-11`)
+
+- Peers:
+  - Each project's README, docs and GitHub releases API (`published_at`): `obra/superpowers`, `open-gsd/gsd-core` (default branch `next`), `github/spec-kit`, `bmad-code-org/BMAD-METHOD` (v6 on `V6.12`, v7 on `main`), `Fission-AI/OpenSpec`.
+  - Contributor counts from the GitHub API link header.
+- Registries:
+  - `api.npmjs.org/downloads/point/last-month/<package>` for `pan-wizard`, `bmad-method`, `@opengsd/gsd-core`, `get-shit-done-cc` and `@fission-ai/openspec`.
+  - `formulae.brew.sh` for OpenSpec.
+  - pypistats for Spec Kit (secondary).
+- Marketplaces, raw JSON parsed:
+  - `anthropics/claude-plugins-official`
+  - `openai/plugins`
+  - `github/awesome-copilot`
+  - `github/copilot-plugins`
+  - `xai-org/plugin-marketplace`
+  - `cursor/plugins`
+- OpenCode 2:
+  - `opencode.ai/v2/docs/{migrate-v1,build/plugins,permissions,config}`
+  - `opencode.ai/config.json`
+  - strings read (not run) from `@opencode/cli-linux-x64@2.0.26`
+- PAN:
+  - `docs/ECOSYSTEM-REVIEW-2026-08.md` §11
+  - `docs/specs/market-ideas-ledger.md`
+  - `docs/specs/market-ideas-2026-10.md` (Addendum)
+  - `docs/COMPARISON.md`
+  - the code paths cited above.
+- Secondary figures: stars, the Superpowers install count, and PyPI downloads. Each is marked where it appears.