pan-wizard 3.36.0 → 3.37.0

package/docs/decisions/ADR-0042-design-parity-both-flows.md

@@ -0,0 +1,45 @@
+# ADR-0042: Design-quality parity across the main and focus flows — shared design tiers + independent design verification
+
+## Status
+
+Accepted — 2026-08-05. Implemented incrementally (see `references/design-methodology.md`, `agents/pan-design-checker.md`, `agents/pan-designer.md`, `commands/pan/design-phase.md`, and the `focus-design`/`plan-phase` wiring).
+
+## Context
+
+PAN has two ways to reach implementation, and they were asymmetric on design quality:
+
+- **Main flow** (phase lifecycle: `discuss-phase → research-phase → plan-phase → exec-phase → verify-phase`) produces an *executable plan* and verifies it with an **independent** adversarial agent (`pan-plan-checker`, `effort: xhigh`, goal-backward, max-2 reflexion loop). But it has **no design step**: `discuss-phase` explicitly defers architecture ("Do NOT ask about architecture choices — Claude handles these"), so architecture, ADRs, and threat modeling are left implicit.
+- **Focus flow** (`focus-design`, the `/featureAI` pipeline) produces a **deep** design: a 10-phase strategic pipeline with architecture assessment, design synthesis, ADR, STRIDE-lite threat model, and a machine-checkable test plan. But its verification is **self-review only** — there is no independent checker for the spec/ADR the way `plan-phase` has `pan-plan-checker`.
+
+So each flow was strong on the axis the other was weak on: the main flow had independent verification but shallow design; the focus flow had deep design but only self-verification. The goal is parity — **both flows get deep design AND independent design verification** — without duplicating the ~1100-line focus-design methodology into the per-phase path, and without making the frequently-run main flow slow.
+
+## Decision
+
+Adopt four coupled decisions:
+
+1. **One methodology, four depth tiers.** Extract the design method into a single reference, `pan-wizard-core/references/design-methodology.md`, with tiers `spike` / `phase` / `feature` / `full`. Both entry points cite it — `focus-design` at `feature`/`full`, the main flow at `phase` — so the method can't drift between flows (consistent with the "single source of truth" rule in CLAUDE.md). The design artifact schema lives in `pan-wizard-core/templates/design.md`, with tier-gated mandatory sections.
+
+2. **A shared, independent design-checker.** Add `agents/pan-design-checker.md`, modeled exactly on `pan-plan-checker` (`effort: xhigh`; `tools: Read, Bash, Glob, Grep`; goal-backward; adversarial; max-2 reflexion loop). It verifies design artifacts against seven dimensions: requirement coverage, ≥2 machine-checkable success criteria, architecture conformance to *discovered* project conventions, ADR honesty (real alternatives, mitigated consequences), threat coverage, testability, and scope discipline. Both flows spawn it.
+
+3. **Ramp the main flow up with a dedicated `/pan:design-phase` command** (not folded into `plan-phase`). It runs `pan-designer` at the `phase` tier → `pan-design-checker` reflexion loop → writes `{phase}-design.md`. The lifecycle becomes `discuss → research → design → plan → verify`. `design.md` is an *optional upstream input* consumed by `pan-planner` exactly as `context.md` is, so existing projects without a design step still plan. Trivial phases auto-skip; `--skip-design` forces it. A dedicated command (vs a gate inside `plan-phase`) keeps the step optional, cacheable like `research.md`, and independently invocable.
+
+4. **Altitude split.** Product/strategic design (demand validation, competitive intelligence, market analysis) runs **once** at feature/milestone creation (`focus-design`, and a product-design pass wired into `milestone-new`), not per phase. Per-phase design (`design-phase`) covers only architecture, ADR, threat model, design synthesis, and machine-checkable criteria — the `phase` tier — so the per-phase path stays fast.
+
+`plan-phase` gains a `## Design` upstream input and passes it to `pan-planner`; `pan-plan-checker` gains a **Design Conformance** dimension (does the plan implement the approved design?). `focus-design` spawns `pan-design-checker` after its ADR phase and its final-artifact phase.
+
+## Consequences
+
+- **Parity achieved:** both flows produce deep design *and* pass it through an independent adversarial checker.
+- **No duplication:** the methodology is defined once and cited twice; the checker is one agent used by both flows.
+- **Bounded overhead:** the depth dial + altitude split + auto-skip + `design.md` caching keep the per-phase path cheap; the reflexion loop is capped at 2 iterations (same as `pan-plan-checker`) so verification can't stall.
+- **Backward compatible:** `design.md` is optional upstream input; projects and phases without it still plan and execute unchanged.
+- **Runtime-agnostic:** new agents/commands use no host-specific tools; any Workflow fan-out keeps its no-op fallback (ADR-0031), so all five runtimes are unaffected.
+- **Cost:** two new agents, one new command, one reference, one template, and wiring/tests. The main-flow lifecycle gains a step (optional), which is a real behavior change teams will see.
+
+## References
+
+- `pan-wizard-core/references/design-methodology.md`, `pan-wizard-core/templates/design.md`
+- `agents/pan-designer.md`, `agents/pan-design-checker.md`, `commands/pan/design-phase.md`
+- Existing pattern this mirrors: `agents/pan-plan-checker.md`, `agents/pan-planner.md`, `commands/pan/plan-phase.md`
+- Deep design source being tiered: `commands/pan/focus-design.md` (the `/featureAI` pipeline)
+- Related: ADR-0031 (Workflow fan-out with no-op fallback), ADR-0038 (skill-aligned decomposition).

package/docs/decisions/ADR-0043-addressable-planning-roots.md

@@ -0,0 +1,56 @@
+# ADR-0043: Addressable planning roots — a command must be able to name the tree it acted on
+
+## Status
+
+Accepted — 2026-08-21. Implemented in `pan-wizard-core/bin/lib/planning-root.cjs`, with `utils.planningPath()` / `utils.planningRel()` as the only path constructors. `hygiene` and `init milestone-op` (which backs `/pan:milestone-audit`) are the multi-root consumers.
+
+## Context
+
+Every planning path in PAN was built as `path.join(cwd, PLANNING_DIR, …)`, where `PLANNING_DIR` was the hard-coded constant `'.planning'`. That made exactly one planning tree per project addressable, and it was the only tree any command could see.
+
+The `--cwd` flag looked like an escape hatch but is not one: it moves the *project* root, and the planning tree is always `<project>/.planning`. A repo whose planning trees live at `.planning/tracks/{core,defense,verify}/` — several independently-planned products merged into one repository — had three of its four trees permanently unreachable.
+
+The damage was not that the other trees were awkward to reach. It was that **the commands did not fail.** They succeeded against the wrong tree:
+
+- `hygiene scan` reported `summary.total: 0` — "clean" — while `tracks/verify/optimization/traces` held 18 trace sessions against a retention of 5. Thirteen were prunable. The command exists to prune them and reported nothing to do.
+- `milestone-audit` resolved a different track than the one requested.
+- `milestone-done` would have archived the wrong milestone.
+
+A tool that errors is safe: the reader retries. A tool that reports "clean" teaches the reader to trust a result it never computed. That is the failure mode this ADR addresses, and it generalises past `hygiene` — any command that silently resolves an implicit target has it.
+
+## Decision
+
+**1. One resolver owns the question "which tree?".** `planning-root.cjs` is a leaf module (it requires only `fs` and `path`) that resolves a project-relative, POSIX-separated planning root, with precedence:
+
+| Rank | Source | Form |
+|---|---|---|
+| 1 | `--planning-dir <path>` / `--track <name>` | explicit flag |
+| 2 | `PAN_PLANNING_DIR` | project-relative path |
+| 3 | `PAN_TRACK` | track name |
+| 4 | default | `.planning` |
+
+**2. Every resolution carries its provenance.** The resolver returns `{rel, source, track}`, never a bare string, and `describePlanningRoot()` adds `planning_root_exists`. Commands surface all four fields. This is the half of the fix that matters most: it is what makes a wrong target *visible* rather than indistinguishable from a right one. A mistyped `--track ghost` now reports `planning_root_exists: false` next to its zero findings, instead of passing for a healthy project.
+
+**3. Two path constructors, no direct joins.** `utils.planningPath(cwd, …segments)` builds absolute paths; `utils.planningRel(…segments)` builds the project-relative display form used in output, findings, and `git add` arguments. They read the same root, so what a command *reports* is always the tree it *touched*. Roughly ninety direct `path.join(cwd, PLANNING_DIR, …)` sites were routed through them, and `PLANNING_DIR` is no longer imported for path building anywhere.
+
+**4. Tracks are discovered, not declared.** `discoverTracks()` walks `.planning/tracks/*/` and returns only directories carrying a planning spine (`state.md`, `roadmap.md`, `phases/`, `focus/`, …). An empty or incidental folder under `tracks/` is not a track — inventing one would reintroduce exactly the "acted on the wrong thing" failure being removed. No registry file, so a track cannot drift out of sync with the filesystem.
+
+**5. Sweeping several trees is scoped, not threaded.** `withPlanningRoot(rel, fn)` pins the root for a synchronous callback and restores it in a `finally`. `hygiene --all-tracks` uses it per tree. Threading a root parameter through each check would have stopped at the module boundary — the checks call into `memory.cjs` and `cost.cjs`, which resolve the root themselves — so the ambient scope is what makes downstream readers follow the sweep instead of all reporting on `.planning/`.
+
+**6. Project-level checks run once.** Version alignment is a property of the project (which runtimes are installed, at what version), not of any planning tree. Sweeping four trees must not report the same drift four times.
+
+## Consequences
+
+- **The reported defect is closed.** `--track verify` surfaces the 13 prunable sessions; `--all-tracks` sweeps the root tree and every track, attributing each finding to its track; `clean --apply` prunes the offending tree and leaves the others intact.
+- **Clean verdicts now name their scope.** Every `hygiene` scan prints the tree it read, and a single-tree scan on a project with tracks says so and points at `--all-tracks`.
+- **Traversal is bounded at the seam.** `--planning-dir` rejects absolute, drive-relative, and `..`-containing paths; `--track` is restricted to a slug alphabet. Both checks are inline literals rather than helper calls, because static analysis does not follow guards across function boundaries.
+- **Behaviour is unchanged when nothing is passed.** The default root stays `.planning`; the full suite passed before the new tests were added, which is the evidence that the ~90-site reroute is faithful.
+- **`withPlanningRoot` is synchronous-only.** Overlapping scopes would interleave and restore onto the wrong value. This is documented at the function and is the one sharp edge the design accepts in exchange for downstream readers following the sweep.
+- **Two commands sweep today.** `--track` / `--planning-dir` work for every command because they resolve at the seam. `--all-tracks` aggregation is implemented for `hygiene` and `init milestone-op`; extending it to the phase/state commands is follow-on work, not a gap in the seam.
+- **The audit gained a refusal.** `init milestone-op` now reports `milestone_basis` and `milestone_ambiguous`, and `/pan:milestone-audit` stops when the roadmap marks more than one milestone current. This is the same principle applied one level up: an audit that cannot resolve its subject must say so rather than produce a confident report about a silently-chosen one.
+
+## Alternatives considered
+
+- **A `--planning-dir` flag with no provenance reporting.** Cheaper, and it would have made the tracks reachable — but it fixes only the "unreachable" half. The costly half of the defect was that a wrong target looked like a right one, which no amount of reachability addresses.
+- **Resolving `PLANNING_DIR` from the environment at module load.** Nearly zero churn: every existing call site would have become track-aware for free. Rejected because the value freezes at first `require`, so any in-process caller that sets the root afterwards (every test, and the `--all-tracks` sweep) silently gets the stale tree — the same class of silent-wrong-target bug, relocated.
+- **A `tracks.json` registry.** Explicit, but a declared list drifts from the filesystem, and a track missing from the registry would be invisible in precisely the way this ADR exists to prevent.

package/docs/decisions/ADR-0044-bound-the-cached-context.md

@@ -0,0 +1,104 @@
+# ADR-0044: Bound the cached context — PAN's dominant cost is what it re-reads, not what it generates
+
+## Status
+
+Accepted — 2026-08-21. Implemented across `state-compact.cjs` (new), `hygiene.cjs`, `context-budget.cjs`, `core.cjs::buildCachedContext`, and the three planning-aware hooks.
+
+> **Amended 2026-10-04 (memory optimisation O1–O3).** The memory review measured the field installs and found three gaps in this decision's reach.
+>
+> 1. **The bound never ran on Windows.** `memory optimize` and the automatic reconcile matched `\n` only. Every Windows field project's planning files are CRLF, so state.md's append-only lists were never reconciled there. One client's Decisions list held 145 entries, and the file was 35 KB where it should have been 10 KB. Every planning-file parser now reads on LF and writes back in the file's own ending (O1).
+> 2. **The largest re-read was not state.md.** The planner and plan checker were handed the whole roadmap.md and requirements.md, and every plan's `<context>` named the whole roadmap for its executors. Phase agents now read `roadmap slice <phase>`, which is 75–98% smaller on the field projects (O2). So "the cached block is re-read on every agent call" now holds for state.md only.
+> 3. **The roadmap had no compaction path.** It is what grows in a long project: 476 KB at 54 phases. `roadmap compact` (`roadmap-compact.cjs`) moves shipped phases' sections to `roadmap-history.md` under the same rules as Decision 1 below: history first, a stub left behind, dry-run by default, declined when it would not shrink. hygiene offers it as the `compact-roadmap` fix (O3).
+
+## Context
+
+A field project reported that PAN had got slow. Its cost ledger explains why.
+
+Excluding the 24% of rows that PAN's own `isSuspectRecord` flags as pre-v3.12.4 oversum poison, 92 clean records show:
+
+| axis | tokens |
+|---|---:|
+| cache_read | 550.2M |
+| output | 8.7M |
+| input | 1.9M |
+
+**Cache reads are 98.1% of all token traffic** — roughly sixty times the generated output. `pan-executor` averaged 7.0M cache-read tokens per call across 47 calls.
+
+The block being re-read on every agent call was 109 KB ≈ 28k tokens:
+
+```
+project.md        14.1 KB
+requirements.md   21.5 KB
+roadmap.md        18.3 KB
+state.md          53.8 KB   ← half the block
+```
+
+And 56% of `state.md` was settled history: a 25.6 KB session log from ten weeks earlier, a resolved milestone audit, and three phase closures. Roughly 7k tokens of finished work re-read into every agent call for months.
+
+Two structural facts made this inevitable rather than accidental:
+
+1. **`state.md` can only grow.** Its section writers are append-only — `sectionBody.trimEnd() + '\n' + entry` in both `cmdStateAddDecision` and `cmdStateAddBlocker`. PAN bounds its other append-only store (`memory compact`, `DEFAULT_MAX_ENTRIES`) but never applied the same idea to the file that dominates every prompt.
+
+2. **Nothing watched the block.** `context-budget.cjs` computed `cache.total_tokens` and `eligible_pct` and reported them with no threshold attached. A measurement with no classification is not a signal — a 28k-token block looked exactly like a 3k-token one.
+
+Two adjacent failures shared the shape:
+
+- **The ledger poison gate counted rows, not tokens.** `checkCostLedger` fired at `suspect/records.length ≥ 0.5`. The field ledger sat at 24% by count — passing — while those rows carried 89% of the token mass. A ledger that is arithmetically useless reported clean.
+- **Phase attribution only worked under tracing.** The cost hook read the phase from `.planning/optimization/current-session`, which exists only while the optimizer runs. With tracing off — the default — 100% of rows carried `phase: null`, so "which phase got expensive" was unanswerable from PAN's own telemetry.
+
+## Decision
+
+**1. `state.md` gets a compaction path.** New `pan-tools state compact [--apply] [--keep-days N]` moves settled sections into `state-history.md`. Safety is ordered:
+
+- Nothing is deleted. History is appended to the archive **first**, then `state.md` is rewritten, so an interruption can only duplicate, never lose.
+- Only unambiguous history moves: a heading dated past the retention window, or one saying "closure"/"closed". Anything unrecognised stays.
+- A protected list guards the headings PAN reads and writes (`state get <section>` can read *any* heading by name).
+- A section carrying a field the frontmatter is rebuilt from (`**Status:**`, `**Current Phase:**`, …) is never moved: `syncStateFrontmatter` regenerates frontmatter from the **first** such match in the body, so relocating one could silently rewrite `state.md` metadata.
+- Compaction that would not shrink the file is declined. On a small file the pointers cost more than the sections they replace, and churning `state.md` to make it bigger helps nobody.
+- Dry-run by default, and the dry-run's byte count is produced by the same rebuild `--apply` uses — a dry-run that disagrees with the apply is not a dry-run.
+
+**2. The cached block is classified, not merely measured.** `CACHE_BLOCK_WARN_TOKENS` (15k) / `CACHE_BLOCK_CRIT_TOKENS` (25k) / `CACHE_FILE_WARN_TOKENS` (6k), mirroring the existing `MEMORY_LOAD_*` pattern. `context-budget` gains `cache.status` plus advice naming the largest file, and hygiene gains a `cache-context` check whose `state.md` finding carries the `compact-state` remedy.
+
+**3. Hygiene covers the rest of the growth surface.** `optimization/reports/` is now pruned on the same retention and keep-newest floor as `optimization/traces/` — previously traces aged out while the analysis JSON beside them (92 KB in the field) never did.
+
+**4. The ledger poison gate watches token mass.** `HYGIENE_LEDGER_SUSPECT_MASS_RATIO` fires when suspect rows carry ≥50% of the token mass, whatever their count. The finding names which gate tripped so a healthy-looking row count is not mistaken for a false positive. Mass is what `aggregate` sums, so mass is what the gate has to watch.
+
+**5. Phase attribution works without tracing.** The cost hook falls back to `state.md` — frontmatter `current_phase`, then the `**Current Phase:**` body field — when no trace session is active.
+
+**6. The cached list is extensible.** `config.json → cache.extra_files` lets a project add its own stable documents. The built-in list is the *phase-model* spine, so a focus-model project had an empty block and therefore no prompt caching at all. Entries are appended after the built-ins so the cache prefix stays byte-stable for projects that configure nothing.
+
+**7. All three planning-aware hooks resolve the same root.** `pan-cost-logger`, `pan-trace-logger`, and `pan-stop-guard` now honour `PAN_PLANNING_DIR` / `PAN_TRACK`. Without this the CLI could be pointed at a track (ADR-0043) while the hooks kept writing to `.planning/`, stranding that track's telemetry in the wrong tree.
+
+## Consequences
+
+- **The reported slowdown has a measured remedy.** On the field project, `state compact` archives four sections and cuts the per-call re-read by ~6,995 tokens — roughly halving `state.md` and taking the block from `critical` to below it.
+- **`cost_usd` stays null in the ledger, deliberately.** It is computed at read time from current rates (`appendRecord`, `aggregate`). Freezing a value at write time would bake in stale pricing. This was considered and rejected, not overlooked.
+- **A conservative compactor leaves things behind.** On the field file it correctly declined to archive a milestone audit marked "GAPS FOUND" — an open item that merely looked historical. Under-archiving is the right failure direction for a tool that edits the project's source of truth.
+- **`walkPlanning` no longer descends into `tracks/`.** Fixing this was forced by the new check: the root scan had been absorbing every track's files, which also meant `--all-tracks` double-counted `.tmp` orphans. A latent ADR-0043 defect, surfaced by giving the walker a second consumer.
+- **One existing test changed meaning.** `small or mostly-clean ledgers are not flagged` asserted that 5 poisoned rows among 25 were fine. Under the mass gate they are not — those rows held 99.99% of the tokens. The test was rewritten to be clean on both axes, and a new test pins the count-passes/mass-fails case.
+
+## Convergence — a clean must actually finish
+
+Applying the above surfaced a fourth failure, reported from the field as "hygiene doesn't properly fix a project". Running `hygiene clean --apply` twice on a real tree showed why:
+
+```
+PASS 2:  ✗ compact-state  .planning/state.md  nothing past the retention window
+         fixable: 1, executed: 0, failed: 1, manual: 1
+```
+
+Three defects, all of the same kind — the tool claiming more than it delivers:
+
+1. **A finding advertised a fix that could no longer do anything.** `fixable` was derived from the mere presence of a `fix` object, so once state.md's settled history was archived the `compact-state` remedy stayed attached to a file whose remaining bulk is LIVE content. Every subsequent `clean --apply` reported `failed: 1`, forever. `checkCachedContext` now consults `planStateCompaction` and offers the fix only when something is genuinely archivable; otherwise the finding is honestly manual and says so.
+
+2. **Quarantines accumulated without limit.** Each poisoned-ledger quarantine left a dated copy and nothing ever removed one — the field tree already held a July file alongside the new one. Quarantine now prunes superseded copies, keeping the newest so the evidence survives. The cure had become the disease it treats.
+
+3. **The cost cursor outlived the ledger it indexed.** `.cost-cursor.json` holds per-transcript high-water marks into `tokens.jsonl`; leaving it after a quarantine meant the "fresh" ledger inherited the old read position and undercounted its next slice. It is now cleared with the rename.
+
+After these, the same tree converges: `fixable: 0, executed: 0, failed: 0, manual: 2`, with the two remaining findings carrying honest manual advice. **`auto-fixable` now means "running clean will change this"** — which is the only reading that makes a repeat run meaningful.
+
+## Alternatives considered
+
+- **Cap `state.md` at a byte limit and truncate.** Simple, and unacceptable: the file is the project's source of truth, and a size-triggered truncation would drop live content as readily as settled content.
+- **Stop caching `state.md`.** Removes the growth cost but also the benefit — it is genuinely stable within a phase, which is exactly what prompt caching rewards. The problem was never that it was cached; it was that it was unbounded.
+- **Classify sections with an agent.** More flexible than pattern rules, and wrong for this job: compaction rewrites the project's source of truth and must be deterministic, reviewable in a dry-run, and identical on every run.
+- **Infer the phase from the transcript path or session id.** Cheaper than reading `state.md`, but it guesses. `state.md` is where the current phase actually lives.

package/docs/decisions/ADR-0045-agent-plugins-bundle.md

@@ -0,0 +1,76 @@
+# ADR-0045: Ship PAN as an Agent Plugins bundle — one portable package for the non-Claude runtimes
+
+## Status
+
+Accepted — 2026-09-10. Spike complete (this document, plus the two normative schemas pinned under `tests/fixtures/agent-plugins/`). Implementation tracked as items 4b–4g of `docs/specs/market-delta-2026-09-superplan.md`.
+
+## Context
+
+PAN reaches five runtimes with a loose-file installer and reaches Claude Code additionally as a plugin (`scripts/build-plugin.js`, ADR-0028 Phase 3). The June review planned bespoke packaging for the others — "Codex plugin + Gemini extension remain" — and the August review ranked plugin distribution as the unit that matters. Neither review saw the thing that changed the picture.
+
+**Agent Plugins 1.0** was published on 2026-08-06 by Vercel with Amazon, Cursor, GitHub, Microsoft and OpenAI; Google joined the same day. It is a vendor-neutral package format for exactly two component types: Agent Skills and MCP servers. It is loaded natively by Copilot CLI, VS Code and the Copilot app (GA 2026-08-12), by Codex (0.146–0.147, remote marketplaces from 0.153), by Cursor and Kiro, and Antigravity declares its plugin format a superset that discovers from the workspace `.agents/plugins/` tree. Anthropic is not a maintainer; Claude Code keeps its own format.
+
+PAN already has both component types the standard packages: a spec-conformant skills compiler (`convertClaudeCommandToUnifiedSkill`, ADR-0028) and a zero-dependency MCP server (`pan-wizard-core/mcp/`, ADR-0041). What it lacks is the wrapper.
+
+### What was verified, and from where (read 2026-09-10)
+
+| Fact | Source | Status |
+|---|---|---|
+| `plugin.json` is a **closed** schema: required `$schema` (const `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`) and `name` (1–64 chars, `^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$`); optional `version`, `description`, `author{name,email,url}`, `homepage`, `repository`, `license`, `keywords[]`, `extensions{reverse-domain: object}`; `additionalProperties: false` | `agent-plugins.org/schemas/1.0.0/plugin.schema.json`, pinned as a fixture | Verified |
+| Optional metadata fields are "validated only by their JSON types" — a client must not reject on semver/URL/SPDX format | `spec/1.0.0.md` §5 | Verified |
+| Unknown top-level manifest field or non-object `extensions` is **non-fatal**; any other schema violation is **fatal** to the whole plugin | `spec/1.0.0.md` conformance section | Verified |
+| Skills: fixed `skills/` directory; each immediate child holding a regular file named exactly `SKILL.md` is one skill; no recursion; a non-conforming skill is skipped, not fatal | `spec/1.0.0.md` | Verified |
+| MCP: fixed `mcp.json` at plugin root, never inline in the manifest; `$schema` const `…/1.0.0/mcp.schema.json` + `mcpServers`; stdio servers carry `type: "stdio"`, `command` (single executable token, bare name or `./`-prefixed, **no placeholder**), optional `args[]`, `env{}`, `cwd` | `mcp.schema.json`, pinned as a fixture; `spec/1.0.0.md` | Verified |
+| `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` are expanded by the client in `args` elements, `env` values and `cwd` — not in `command`, not in keys, not anywhere else. Single non-recursive textual replacement; unknown placeholder-like text stays literal | `spec/1.0.0.md` | Verified |
+| **When `cwd` is omitted, the client MUST use the plugin root as the subprocess working directory** | `spec/1.0.0.md` | Verified — and consequential, see D6 |
+| Client-specific files live in a top-level directory named for a reverse-domain namespace; matching manifest data goes under `extensions[namespace]`; a client ignores namespaces it does not implement without validating them. No registry of namespaces exists | `spec/1.0.0.md` | Verified |
+| Copilot: namespace `com.github.copilot/` with `agents/*.agent.md`, `hooks/hooks.json`, `commands/`, `rules/`; the older root-level layout (`agents/`, `hooks.json`, `.mcp.json`) is still read; plugin hooks accept the Claude matcher format and expand `${CLAUDE_PLUGIN_ROOT}` (also exported to the hook process) | `code.visualstudio.com/docs/agent-customization/agent-plugins`; `github.blog` changelog 2026-08-12 | Verified for VS Code; **Copilot CLI's own how-to shows only the root layout** — treat the namespace layout as VS Code-verified, CLI-unverified |
+| Codex: consumes the root `plugin.json` directly; OpenAI-specific data lives inline under `extensions["com.openai"]` (`hooks` path or inline, `apps`, `interface`), hooks at `hooks/hooks.json`; `.codex-plugin/plugin.json` remains a compatibility fallback; marketplaces at `.agents/plugins/marketplace.json` (repo) or `~/.agents/plugins/marketplace.json`; install via `codex plugin marketplace add` / `/plugin`; enable in `config.toml` as `[plugins."name@marketplace"] enabled = true` | `developers.openai.com/plugins/build/plugins` | Verified |
+| Antigravity: discovers `<workspace>/.agents/plugins/<name>/` and `~/.gemini/antigravity-cli/plugins/<name>/`; layout `plugin.json` (**own closed schema: `name`, `description`, `$schema` only**), `mcp_config.json`, `hooks.json`, `skills/`, `agents/`, `rules/`; install `agy plugin install <path>` | `antigravity.google/docs/cli/plugins/` | Verified layout; **mcp_config.json shape, hooks.json shape, agent/rule formats, and whether an Agent Plugins `$schema` is accepted are all UNSPECIFIED on the page** |
+| Spec 1.1.0 is a working draft that still scopes v1 to skills + MCP: "Other component types are outside the v1 format" | `spec/1.1.0.md` | Verified |
+
+Three facts that a changelog-level reading would have gotten wrong, recorded so they are not re-derived: the Antigravity manifest schema is **closed and different** from the Agent Plugins one, so a single `plugin.json` cannot satisfy both; `command` in `mcp.json` may **not** carry a placeholder, so the bundled server must be launched as `node` + `${PLUGIN_ROOT}/…` in `args`; and the stdio default working directory is the **plugin root**, which is the opposite of what PAN's server assumes.
+
+## Decision
+
+**D1 — One bundle, a separate builder.** Emit an Agent Plugins 1.0 package to `dist/pan-agent-plugin/` from a new `scripts/build-agent-plugin.js`. The Claude plugin builder is not extended with a format flag: the two layouts share almost no file paths, and the Claude plugin's output must stay byte-identical (a test pins that). Shared logic goes into pure functions in `bin/install-lib.cjs`, never into a second copy.
+
+**D2 — Skills come from the one compiler.** The bundle's `skills/pan-*/SKILL.md` is produced by `convertClaudeCommandToUnifiedSkill` with the same content rewrite the installer applies — extracted from `bin/install.js` into install-lib so the installer and the builder call one function. ADR-0028's rule stands: no second skills compiler, ever. The emitted skills already satisfy every hard rule the spec's skills discovery applies (name equals directory, closed key set, no angle brackets, single-line description).
+
+**D3 — A PAN placeholder, not a client one, for paths inside skill bodies.** Agent Plugins expands `${PLUGIN_ROOT}` only in `mcp.json`; Claude's `${CLAUDE_PLUGIN_ROOT}` textual substitution in content is Claude-specific (VS Code expands it in hooks and MCP config, not in skill bodies). Skill bodies in the bundle therefore reference the bundled core through PAN's own token, `{{PAN_PLUGIN_ROOT}}`, in the same style as the existing `{{PAN_ARGS}}`, and the skill adapter header defines it: the directory containing this plugin's `plugin.json`, two levels above the `SKILL.md`, which the runtime reports when it loads the skill. The header also says to prefer the `pan` MCP server's tools where the runtime has connected them. Whether models resolve the token reliably on each runtime is the live gate in 4c/4d; a conformance test can only assert that no `.claude/` or install-directory path survives in the bundle.
+
+**D4 — `mcp.json` declares the bundled bridge.** `{"$schema": …, "mcpServers": {"pan": {"type": "stdio", "command": "node", "args": ["${PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs"]}}}`. `node` is a bare executable token, which the spec permits; the placeholder sits in `args`, where expansion is defined. No `env` block: a plugin serves whatever project the session is in, the same rule the Claude plugin follows.
+
+**D5 — Vendor directories per runtime, each behind its own verification.** Copilot: `com.github.copilot/agents/*.agent.md` via the existing `convertClaudeToCopilotAgent`, and `com.github.copilot/hooks/hooks.json` in the Claude matcher format with `${CLAUDE_PLUGIN_ROOT}` paths, since that is the form VS Code documents as expanded. Codex: agents via `convertClaudeAgentToCodexToml`, location and hook variable **unverified** — emit only after reading the Codex plugin reference for agents, and register hooks under `extensions["com.openai"].hooks` only once its path form is known. Antigravity: **a separate variant, not this bundle**, because its manifest schema is closed with a different `$schema`; it is deferred until `mcp_config.json` and `hooks.json` shapes are read from a primary source. Emitting an unverified shape would repeat the dead-config-path class the June review caught twice.
+
+**D6 — The server must learn the project root from the call, not the process.** `pan-wizard-core/mcp/server.cjs` resolves its project as `opts.cwd || PAN_PROJECT_ROOT || process.cwd()`. Under Claude Code the process cwd is the project, so it works. Under Agent Plugins the client launches the server **in the plugin root**, so every tool would read `.planning/` from inside the plugin cache and report an empty project — cleanly, which is the worst kind of failure. The fix is additive and shared with the Claude plugin: every registry tool gains an optional `cwd` input (absolute project path), the server uses it per call when present and falls back to today's resolution otherwise, and the resource rule from ADR-0041 (`args` static, never a function of client input) is preserved by scoping the parameter to tools only. Tracked as new item 4g; it is a prerequisite for the live gates, not a follow-up to them.
+
+**D7 — Distribution.** A Codex marketplace file at `.agents/plugins/marketplace.json` in this repository (local `./dist/pan-agent-plugin` source for the test bed; a git source once published) and a Copilot marketplace file where its docs place it. Both gated on the same policy as the Claude plugin: ship the versioned bundle before listing anywhere that indexes without certifying.
+
+**D8 — Conformance suite before any live gate.** A zero-dependency structural validator, driven by the pinned schemas, asserts: the manifest validates against `plugin.schema.json` (required keys, `$schema` const, name pattern, closed key set, field types); `mcp.json` validates against `mcp.schema.json`; every skill directory name equals its `name`; skill frontmatter uses only the closed key set with no angle brackets; every `{{PAN_PLUGIN_ROOT}}` reference resolves to a file inside the bundle; no `.claude/` or `.agents/pan-wizard-core/` path survives; a non-vacuity guard runs first. The Claude plugin build is asserted byte-identical before and after the compiler extraction.
+
+**D9 — A skill longer than Codex loads ships as a pointer page (added 2026-10-03, market-ideas S8).** Codex injects at most the first 8,000 bytes of a skill that came from an Agent Plugin (`codex-rs/ext/skills/src/render.rs`, `MAX_SKILL_PROMPT_BYTES`). Measured on Codex CLI 0.157.1 with a capture-only mock provider, so no model was involved: a 56,540-byte PAN skill reached the model cut mid-sentence, with a "was truncated" warning. The same skill from an install's `.agents/skills/` arrived whole, so the cut applies to plugins only. The builder now keeps every bundle `SKILL.md` within the limit. A skill over it keeps its frontmatter and adapter block, says where the full instructions are, and carries a short summary. The body moves to `skills/<name>/references/instructions.md`, the Agent Skills directory for files a skill loads on demand. The split is `splitOversizedSkill()` in install-lib, applied after the one compiler (D2 stands). A test rebuilds every skill and asserts each one is either the compiler's output unchanged or exactly its split. Re-probed live the same day: the 3,116-byte pointer page arrived whole and the reference file was installed beside it. Untested without a model: that a model follows the pointer.
+
+## Consequences
+
+- One emitted bundle serves Copilot and Codex today and Cursor/Kiro incidentally; Antigravity needs a thin variant later. This replaces the June plan's two bespoke packagings and closes ADR-0028 Phase 3's remaining half for those runtimes.
+- The skills compiler extraction touches the installer's unified-skills path. Its output is pinned by `tests/unified-skills-install.test.cjs`; the extraction must leave that suite untouched and green.
+- D6 changes the MCP bridge's tool schemas (additive optional field). Every runtime that registers the bridge sees the new parameter; the tool descriptions must make clear it is optional.
+- The `{{PAN_PLUGIN_ROOT}}` convention is a bet on runtimes exposing the skill's file location at activation. If a runtime does not, its skills cannot reach `pan-tools` by path and must rely on the `pan` MCP tools — which is why D4 and D6 are not optional.
+- PAN takes on a second `dist/` artefact and a second manifest that mirrors `package.json`; the manifest-mirror test pattern from the Claude plugin applies.
+
+## Alternatives considered
+
+- **Extend `build-plugin.js` with `--format agent-plugins`.** Rejected: different manifest location and schema, different MCP file name and schema, different placeholder, different vendor layout — a flag would be two builders in one function, and the Claude plugin's byte-identity guarantee would be harder to hold.
+- **Fork the skills compiler for the bundle.** Rejected outright; it recreates the drift class ADR-0028 removed.
+- **Use `${PLUGIN_ROOT}` inside skill bodies.** Rejected: the spec defines expansion only for `mcp.json` fields; the token would reach the model literally and unexplained.
+- **Set `PAN_PROJECT_ROOT` in `mcp.json` `env`.** Rejected: the project path is unknown at build time, and `env` cannot name `PLUGIN_ROOT` or `PLUGIN_DATA`.
+- **Wait for Agent Plugins 1.1 to add agents and hooks natively.** Rejected: the draft explicitly keeps them out of v1 scope; vendor namespaces are the standard's answer and are stable.
+
+## Verification caveats
+
+Copilot CLI's namespace layout is verified through VS Code's documentation and GitHub's changelog, not through the CLI's own how-to; Codex agent placement and hook path variables, and every Antigravity file shape, are unverified. Each is gated in the plan. Re-read the spec repository before implementing 4c/4d — the 1.1.0 draft is live.
+
+## Amendment — `2026-10-19`: Codex loads no hooks from the bundle
+
+Codex decides a plugin's format from its manifest. A root `plugin.json` carrying the agent-plugins.org schema is an Agent Plugin, and for an Agent Plugin the loader returns no hook sources at all (`codex-rs/core-plugins/src/loader.rs`; introduced by "Enforce Agent Plugin runtime boundaries", openai/codex#37027, `2026-08-05`; identical at `rust-v0.163.0`). A `.codex-plugin/plugin.json` beside it is read only as an overlay and does not change the format. The `hooks/hooks.json` this bundle emits for Codex (D5), and the stop guard added to it (MI-037), therefore never fire on Codex. The `plugin_hooks` feature flag Codex now lists as removed is a compatibility flag for the other manifest format. Nothing changes in the build: the file is harmless and other consumers may read it. Codex users get PAN's hooks from a `--codex` install, which writes `.codex/hooks.json`. Found by the reality check (R55).

package/docs/decisions/ADR-0046-subagent-frontmatter-decisions.md

@@ -0,0 +1,39 @@
+# ADR-0046: Newer Claude Code subagent frontmatter — what PAN adopts, and what it declines
+
+## Status
+
+Accepted — 2026-09-10. A decision record, not a feature: four fields are declined with reasons, and the one capability PAN does want (a longer prompt-cache lifetime for subagents) is delivered as a **recommendation from measured data** rather than as emitted frontmatter. Plan items 7a/7b of `docs/specs/market-delta-2026-09-superplan.md`.
+
+## Context
+
+Claude Code's subagent frontmatter grew a set of fields PAN's agents do not use: `maxTurns` (now yielding partial, resumable output — 2.1.246/2.1.259), `memory` (`user` / `project` / `local` scopes), `isolation: worktree`, `skills:` preload, `experimental.cacheTtl` (2.1.248), and the `fork` spawn mode that inherits the parent's context and cache. The August review listed them as "unadopted"; this record decides each on its merits. Two constraints frame every decision:
+
+- **PAN's quality guarantee is that every agent starts from zero context and reads its inputs from disk.** Anything that trades that for convenience changes the thing PAN sells.
+- **ADR-0028's frontmatter rule:** a field is emitted only where a runtime has been seen to read it, and PAN ships the same agents to five runtimes. A Claude-only field must be stripped for the other four and must earn its place on Claude.
+
+## Decisions
+
+**D1 — `maxTurns`: declined as a shipped default.** PAN agents run whole protocols — a planner writes a complete plan set, a verifier walks every success criterion. A turn cap mid-protocol leaves a half-written artifact on disk that the next hop will read as finished; the "partial + resume" contract only helps when the *orchestrator* notices the partial flag and resumes, and PAN's orchestrators are markdown prose — exactly the layer PanLoop finding 0 showed drops steps at its lowest-context moment. Revisit when a native workflow owns the orchestration, where honouring a partial result and re-issuing the agent is a mechanical step the script cannot skim past. Budgeting remains the `budget` profile's job (cheaper tiers, not fewer turns).
+
+**D2 — `memory`: declined.** PAN already has two memory surfaces with explicit curation rules: `.planning/memory/*.md` (project rules injected into executor prompts, verified by the reviewer) and the learnings store with its `learn promote` gate. A third, agent-private memory that Claude Code curates by its own rules — and that only exists on one runtime — would diverge from those two and be invisible to PAN's hygiene and drift checks. If per-agent recall is wanted, it belongs in `.planning/memory/` where every runtime and every check can see it.
+
+**D3 — `isolation: worktree`: declined for the shipped agents.** The execution protocol requires the executor to commit to the project's branch and to update `state.md`, `roadmap.md` and `summary.md` where the orchestrator and the verifier will read them; an executor in a private worktree would leave those on a branch the main checkout cannot see. Where PAN wants isolation it already has it, with explicit naming and teardown: `worktree.cjs` and the `army/<task>` branches (ADR-0033, P-1815). Two isolation mechanisms with different cleanup rules is the class of defect P-1815 closed.
+
+**D4 — `skills:` preload: declined.** The field injects each listed skill's *full body* into the agent at startup. PAN's agents already instruct the model to read project skills from `.agents/skills/` when they exist, which loads only what a task needs. Preloading would put every listed body into every agent call — the opposite of the cached-context discipline ADR-0044 imposed.
+
+**D5 — `experimental.cacheTtl` and `subagentPromptCacheTtl`: recommend, do not emit.** The one-hour lifetime is worth having for a phase whose agents are spaced more than five minutes apart, and worthless for a burst that never idles; one-hour writes bill at 2× base input against 1.25×. PAN cannot know which pattern a project has — but its cost ledger can. `context-budget` now reports `cache.ttl` (cache writes that followed an idle gap of five to sixty minutes, the misses a one-hour lifetime would have avoided) and hygiene raises an `info` finding naming the setting when the pattern recurs. The user makes the trade with the numbers in front of them. Emitting `experimental.cacheTtl: 1h` on selected agents was considered and rejected: it is marked experimental, it would need stripping on four runtimes, and it hard-codes a cost decision that varies per project.
+
+**D6 — `fork` spawn mode: declined for the planning chain, allowed nowhere by default.** Forking inherits the parent's full conversation and cache. That is the inverse of PAN's fresh-context guarantee for the planner, executor, verifier and reviewer. It suits a cheap same-context follow-up and nothing in PAN's chain is that.
+
+## Consequences
+
+- Nothing is emitted; ADR-0028's rule is untouched. The plan's item 7b ("adopt whatever 7a accepts") closes with no adoption, by decision rather than omission.
+- The cache-lifetime capability arrives as data (`cache.ttl`) plus a documented setting, so the recommendation improves as the ledger grows and is wrong for nobody.
+- D1 names its own revisit trigger: native workflows owning orchestration. When `pan-exec-waves` or a successor runs executors, a `maxTurns` on those spawns with a scripted re-issue is the right shape, and this record should be superseded for that path.
+- **`2026-09-26` — the trigger fired, and D1 still stands.** `pan-exec-waves` (3.28.0) owns the executor spawns, so market-ideas queue item M9 took the revisit up. The Workflow tool's `agent()` takes `label`, `phase`, `schema`, `model`, `effort`, `isolation` and `agentType` — no turn cap per spawn (the workflow-authoring reference, read that day). The only other place for `maxTurns` is `pan-executor`'s frontmatter, and a cap there binds every executor spawn, the markdown `exec-phase` path included — exactly what D1 declined. So nothing ships; revisit when the engine offers a per-spawn cap, or if PAN ever emits a wave-only executor agent for the native path.
+
+## Alternatives considered
+
+- Emit `maxTurns` only on read-only agents (researcher, verifier). Rejected: a verifier cut off mid-criteria writes a verification file that reads as complete.
+- Emit `memory: project` on `pan-reviewer` to accumulate recurring findings. Rejected in favour of `.planning/memory/` — same benefit, visible to hygiene and to all five runtimes.
+- Emit `experimental.cacheTtl: 1h` on `pan-executor` and `pan-verifier`. Rejected per D5.

package/docs/decisions/ADR-0047-pan-harness.md

@@ -0,0 +1,76 @@
+# ADR-0047: PAN Harness — a behavioural test harness that lives with the code it tests
+
+## Status
+
+**Amended `2026-10-12` (D2):** a step backed by the harness's local model double — capture, scripted or replayed answers, with no request reaching a real model — spends nothing and counts as tier 0, so it needs no `--max-usd` and may run in CI. Record mode (which proxies to a real model) stays tier ≥1, needs `--max-usd`, and uses API-key auth only (decided by the maintainer, `docs/specs/product_excellence_program_2026_q4_featureai.md` §3.4).
+
+**Amended `2026-10-10` (D4, MI-104):** a `model` step may name a `runtime` — `claude` (the default and the only host with an output parser) or `codex`, `copilot`, `gemini`, `opencode`, whose argv follows each CLI's own help. A host without a parser is refused before anything runs, because D2's cap needs the step's cost; each host gets its parser from one captured run.
+
+Accepted — 2026-09-10. Replaces the PanLoop harness (`D:\panwiz_recursiontest`), which no longer exists on disk; only its Claude transcript folder survives, and this record was written from what that transcript and its recovered files show worked. Implementation under `harness/`; the model-free tier ran green against a packed artifact the day this was accepted.
+
+## Context
+
+PAN had one thing almost nothing in its category has: a behavioural eval harness that drove *deployed* installs and measured what the model actually did. PanLoop found the auto-advance chain drop (0/3 → 16/16 across the fix chain), two dead MCP resources, a dead reconcile gate, and its own over-claiming checks. Then it disappeared with the directory it lived in. The market-delta plan (`docs/specs/market-delta-2026-09-superplan.md`) closed every item except the ones that needed it: the behavioural gate for the new native workflows (5c), the agent-scope probe (3b), and the live installs for the Agent Plugins vendor directories.
+
+What the recovered material establishes about the old harness, and what this design keeps or changes:
+
+| PanLoop practice | Verdict | Why |
+|---|---|---|
+| Scenario = JSON with `tier`, `description`, a `why` per step, `expect` assertions, a `budget` | **Keep** | The `why` is what made findings legible months later |
+| Steps of three kinds: `panSteps` (pan-tools argv), `mcpSteps` (JSON-RPC to the installed bridge), `steps` (a prompt to `claude -p`) | **Keep, unify** | One `steps` array with a `kind` field; the old split hid that a scenario could mix them |
+| Install from a **packed artifact**, never the source tree; identify the build by content | **Keep** | The released and branch builds shared a version string once; `npx <tgz>` silently no-ops on Windows |
+| Model steps run under `--mcp-config <ws>/.mcp.json --strict-mcp-config` | **Keep** | Measured: without it an agent saw two `pan` servers (workspace + plugin cache) with near-identical tool names |
+| Findings ledger with signatures, promotion rule (deterministic, or seen in ≥2 runs), recheck sweep | **Keep** | It stopped single flaky runs from becoming filed defects |
+| Every check must be proven able to **fail** (mutation fixture) — PanLoop withdrew four of its own claims for lacking this | **Keep, enforce in tests** | A check that cannot fail is a false pass waiting to be believed |
+| Lived in its own directory with its own git history | **Change** | It vanished. Scenarios assert PAN's contracts; they version with PAN |
+| Run scenarios five times | **Keep for model tiers** | One green run proves nothing at a 4/5 failure rate |
+
+## Decision
+
+**D1 — Location: source in the repo, state outside it.** `harness/` in this repository holds the runner, the scenario definitions and the seeds; it is absent from `package.json` `files`, so nothing ships. Run state — workspaces, extracted artifacts, per-run reports — goes under `d:\pantesting\harness-runs\<run-id>\` by default (`--state-dir`, or `PAN_HARNESS_STATE`), honouring the rule that installs never touch the source checkout. The findings ledger, `harness/ledger.jsonl`, is tracked: it is the finding history the promotion rule depends on.
+
+**D2 — Three tiers, model spend is opt-in and capped.** Tier 0 is model-free (pan-tools, filesystem, the bridge over stdio) and is the default run. Tier 1 is one model turn per step; tier 2 is a chain run. A tier ≥1 step is refused unless the run carries `--max-usd`; the runner stops when the cap is reached and records the stop as a finding of the run, not of PAN. Costs come from `claude -p --output-format json` (`total_cost_usd`), so the cap is enforced from measured spend, not estimates.
+
+**D3 — Artifact-first.** A run begins with `npm pack` of the repository into the run directory, extraction with `tar` (never `npx`), and an install from the extracted package into each workspace. The run records the package version, the repository HEAD, and the tarball's SHA-256; a report that names only a version is not a report.
+
+**D4 — Scenario schema.** One JSON file per scenario:
+
+```
+{ id, tier, description, why,
+  seed: "<name under harness/seeds>" | "empty",
+  install: ["--claude", "--codex", …] | null,      // installer flags; null = no install
+  requires: { cli: "copilot" } | null,             // absent CLI → the scenario is SKIPPED with the reason, never green
+  budget: { maxUsd, maxMinutes, maxStepMinutes },
+  steps: [ { kind: "pan" | "sh" | "mcp" | "model" | "fs", …, expect: [ … ], why } ] }
+```
+
+Step kinds: `pan` runs the **installed** `pan-tools` with an argv; `sh` runs a whitelisted node script (never a shell string); `mcp` sends a JSON-RPC batch to the **installed** bridge over stdio; `model` runs `claude -p` in the workspace; `fs` asserts without running anything. Assertion kinds: `exit:<n>`, `file:<rel>`, `absent:<rel>`, `glob:<pattern>`, `count:<glob>=<n>`, `json:<path>` (key present) and `json:<path>=<value>` (on stdout JSON), `stdout~<regex>`, `stderr~<regex>`, and for `mcp` steps `rpc:<id>.<path>=<value>`. Every kind has a unit test that shows it failing on a mutated input.
+
+**D5 — Findings.** A failed assertion is a finding with a signature (`sha1(scenario, step, kind, normalised detail)`). The ledger records first/last seen, the runs and builds it appeared in, and `resolved_at` when a later run passes the same step. Promotion rule as before: a tier-0 finding is promotable at once; a model-tier finding after two runs. A skipped scenario is recorded as `skipped` with its reason in the report and is never counted as passed.
+
+**D6 — What it covers first.** The coverage matrix the plan left open:
+
+| Plan item | Scenario | Tier |
+|---|---|---|
+| Deployed install of every runtime; Codex hooks async; native workflows shipped; MCP registrations written | `install-matrix` | 0 |
+| 4g — the installed bridge answers for another project when `cwd` says so | `mcp-bridge-cwd` | 0 |
+| Native workflow scripts as deployed: parse, meta first, phases agree | `native-workflows-deployed` | 0 |
+| Agent Plugins bundle builds from the artifact's sibling repo and validates; Copilot/Codex/Antigravity live installs | `agent-plugin-bundle`, `live-gate-copilot`, `live-gate-codex`, `live-gate-antigravity` | 0 (skips with reason when the CLI is absent) |
+| 5c — `/pan-exec-waves` chain completion vs the markdown path on a seeded two-plan phase | `native-exec-waves-chain` | 2 |
+| 3b — agent scope inside the Claude plugin (`AGENT_SCOPE: scoped\|bare`) | `plugin-agent-scope` | 1 |
+
+**D7 — Seeds are PAN-shaped.** A seed is a `.planning/` tree written the way PAN's own templates write it (roadmap, state, plan files with the frontmatter `phase-plan-index` parses), because the reconcile-gate lesson stands: a fixture hand-written in a format PAN never emits verifies nothing.
+
+## Consequences
+
+- The harness can no longer be lost separately from the code; a change to a PAN contract and the scenario that asserts it land in the same commit.
+- Tier 0 runs in CI-like conditions with no spend and no credentials; it is the release gate's natural ninth step once it has run green for a while.
+- Model tiers spend the maintainer's Claude usage. They never run by accident: no `--max-usd`, no model step.
+- The live gates for Copilot, Codex and Antigravity are encoded now and will report `skipped: <cli> not installed` on this machine until the CLIs exist; on a machine that has them, the same run turns them into real results.
+- Every assertion kind carries a both-direction test, so the harness cannot accumulate checks that pass vacuously — the failure mode PanLoop found in itself.
+
+## Alternatives considered
+
+- **Rebuild PanLoop as a sibling repository.** Rejected: it is how the last one was lost, and its scenarios asserted contracts that live here.
+- **Reuse `tests/scenarios/` for behavioural runs.** Rejected: those are unit-shaped, model-free and run from the source tree; the harness's value is the deployed artifact and the model.
+- **Drive Claude Code through the Agent SDK instead of `claude -p`.** Deferred: `claude -p --output-format json` already yields cost and result; the SDK adds a dependency to a zero-dependency project for no measured gain.

package/docs/decisions/ADR-0048-one-core-per-project.md

@@ -0,0 +1,43 @@
+# ADR-0048: One core per project — collapse the per-runtime `pan-wizard-core` copies for local installs
+
+## Status
+
+Accepted — option A (status quo) — 2026-09-10, by the maintainer, after the reality check framed the choice (plan item R16a). The per-runtime duplication is recorded here as an accepted cost; R16b is closed without implementation. Revisit trigger: a second runtime-neutral consumer that needs the shared core, or a measured version-drift incident that `hygiene scan` did not catch.
+
+## Context
+
+A local install selects one or more of the five runtimes, and each selected runtime directory receives its own complete copy of `pan-wizard-core/` — the engine, the workflows, the templates, the references, the MCP bridge. Measured on a packed `3.27.0` install into all five runtimes on 2026-09-10 (reality check RC18, reproduce with Phase 4.2 of `.claude/commands/reality-check.md`): five identical core trees, one per runtime directory, and a sixth under `.agents/pan-wizard-core/` when `--unified-skills` is on. Each copy is a few megabytes and a few hundred files. The duplication is a design consequence, not an accident:
+
+- **Per-runtime self-containment.** Every runtime's commands embed a path into *its own* core (`~/.claude/pan-wizard-core/…`, `.opencode/pan-wizard-core/…`), so a runtime keeps working when another is uninstalled, and a global install of one runtime never depends on another's home.
+- **Manifest ownership.** Each runtime's `pan-file-manifest.json` tracks the files it installed; uninstall removes exactly those.
+- **The shared tree already exists for one case.** ADR-0028 Phase 2 introduced `.agents/pan-wizard-core/` as the runtime-neutral home for unified skills, with path rewriting (`rewriteSharedCoreMarkdown`) and a ref-counted uninstall (the last tracker removes and prunes). The per-runtime copies remained for the proprietary command trees.
+
+What the duplication costs: disk and file count per project; five drift surfaces where one would do (a partial upgrade leaves two runtimes on two engine versions, which `hygiene scan`'s version-alignment check exists to catch); and five MCP server locations registered per project when one would serve every client.
+
+## Options
+
+**A — Status quo.** Keep one core per runtime directory. Cost: the duplication above. Benefit: no migration, no cross-runtime coupling, global installs and local installs share one code path.
+
+**B — One core per project for local installs.** Local installs place the core once at `.agents/pan-wizard-core/` (the ADR-0028 location) and every runtime's commands, agents, hooks and MCP registration point there. Global installs are unchanged: their homes differ per runtime (`~/.claude`, `~/.config/opencode`, `~/.gemini`, `~/.codex`, `~/.copilot`) and cannot share a tree.
+
+- Converters: the path rewriting exists (`rewriteSharedCoreMarkdown`, `rewriteUnifiedSkillCommandContent`); the proprietary command converters would take the same target.
+- Manifests and uninstall: the shared tree's ref-counted uninstall exists; every runtime's manifest would record the shared core with a shared-owner marker, as unified skills do today.
+- Hooks: the hook scripts resolve the engine relative to their runtime directory today; they would resolve the shared path instead, with a fallback to the per-runtime copy for older installs.
+- MCP registration: one server path in every runtime's registration file.
+- `--config-dir`: a custom runtime directory still points at the project's shared core.
+- Migration: an upgrade over an existing five-copy install must either migrate (remove the per-runtime cores after re-pointing) or keep serving the old layout; `hygiene` would report the leftover copies.
+- Failure domain: the shared tree is a single point of failure for every runtime in the project — the same trade ADR-0028 accepted for unified skills, mitigated by the same scenario matrix.
+
+**C — Links.** Symlink or hardlink the per-runtime paths to one tree. Rejected: Windows symlinks need a privilege or Developer Mode, hardlinks do not cross volumes, and a link is invisible to the manifest.
+
+## Decision
+
+**A — status quo — accepted 2026-09-10.** The reality check recommended B scoped to local installs; the maintainer chose A: `hygiene scan`'s version-alignment check already catches the drift class, the footprint cost is disk only, and B would carry two install layouts indefinitely because global installs cannot share. If the revisit trigger in Status fires, B re-opens under the gates below.
+
+Gates for accepting B: the `install-matrix` and `runtime-roundtrip` scenarios green on the new layout; the packed-install footprint measured before and after with the Phase 4.2 command; an upgrade from a five-copy install verified in `d:\pantesting`; `hygiene scan` recognising and offering to remove the orphaned per-runtime copies.
+
+## Consequences
+
+If A: nothing changes; RC18 stays an accepted cost and is recorded here so the next review does not rediscover it.
+
+If B: one engine version per project, one MCP server per project, a smaller footprint, and a migration path that every existing local install will walk once. Global installs keep the per-runtime layout, so the installer carries both layouts indefinitely — the documentation must say which layout a given install has and why.