pan-wizard 3.34.0 → 3.35.0

package/README.md

@@ -101,7 +101,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 - **A human merges.** The Release squad prepares a squash-merge and surfaces an `always-ask` approval instead of merging; pair it with branch protection on your repo, which is what makes that unbypassable rather than merely instructed. Recovery is `git revert` or the previous tag, never a force-push.
 - **Isolated builders.** Each Build agent forks its own `army/<task>` branch + git worktree, so parallel agents never share a file.
-- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn by Mission Control's protocol (prompt-enforced; the MCP `pan_next_action` path enforces the cycle cap, the budget cap when `caps.enforceBudget` is set, an `aborted` flag the caller sets (it does not read the abort file) and the human gate in code — delegation depth is bounded by which agents hold the `Task` tool) — the same harness as hierarchical exec, at campaign scale.
+- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn by Mission Control's protocol (prompt-enforced; the MCP `pan_next_action` path applies the cycle cap, the budget cap (when `caps.enforceBudget` is set) and an `aborted` flag to the counts and caps the caller passes in — it tracks none of them and does not read the abort file; only the merge is gated independently of the caller, by `pan_confirm_merge`'s human approval token — delegation depth is bounded by which agents hold the `Task` tool) — the same harness as hierarchical exec, at campaign scale.
 
 **Run it over days.** `--schedule` arms a resumable campaign with a per-day budget that burns the backlog down across sessions (the per-day budget is advisory unless the schedule is armed with `--enforce-budget`, which pauses the day's run once spent — `campaign status` shows the day's spend — and an external scheduler triggers each `--continue`) — and *still* waits for you at every merge. **Autonomy runs up to the irreversible step; a human is at the step.**
 
@@ -415,7 +415,7 @@ Automated verification checks that code exists and tests pass. `/pan:verify-phas
 
 The system:
 
-1. **Gates on the test suite** — a failing (or non-running) suite forces the verdict to `gaps_found`; the must-have checks still run so the report is complete
+1. **Gates on the test suite** — the verifier's protocol sets the verdict to `gaps_found` when the suite fails or cannot run, and the must-have checks still run so the report is complete; the recorder flags a failed gate filed under `passed` (`test_gate_failed_under_pass`) but does not overwrite the status
 2. **Checks every must-have** — each phase promise is verified against the code, not the task list
 3. **Reports the gaps** — a verification report with a per-truth status and the recommended fix plans
 4. **Hands the gaps to the planner** — `/pan:plan-phase N --gaps` writes the fix plans (`gap_closure: true`); `/pan:exec-phase N --gaps-only` runs just those
@@ -528,7 +528,7 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 
 The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
 
-**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
+**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays small, because the work happens in fresh subagent contexts. Your session stays fast and responsive.
 
 ### Reasoning-Trace Handoff
 
@@ -582,7 +582,7 @@ You're never locked in. The system adapts.
 | **Context rot prevention** | Phase-scoped fresh context windows (native sub-agents on Claude Code) | No — context degrades over time | No (Cline: condensing) | No |
 | **Multi-agent** | Specialized agents, parallel waves | Parallel agents in worktrees (Cursor) | Single agent (Cline: subagents) | Custom agents as subagents |
 | **Plan → Verify loop** | Research → plan → verify with iteration | Agent generates plan | Plan mode (Cline) | Plan step |
-| **Post-execution verification** | Auto verifier + human UAT | Iterative error-fix | Manual test runs | Auto-fix loop |
+| **Post-execution verification** | Auto verifier with a test-suite gate (UAT is a template no command runs) | Iterative error-fix | Manual test runs | Auto-fix loop |
 | **Session persistence** | state.md + pause/resume + handoff | Memory tool / transcripts | None / checkpoints (Cline) | Copilot Memory, CLI session recovery |
 | **Runtime support** | Claude Code, OpenCode, Gemini CLI, Codex, Copilot CLI | IDE-locked | Terminal / VS Code | VS Code + CLI |
 | **Zero dependencies** | Yes (Node builtins only) | No (Electron) | No (Python / Node) | No |
@@ -630,7 +630,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:army "<goal>"` | Campaign-scale delivery: Mission Control delegates a whole-project goal to architecture/build/quality/release squads with branch-per-agent worktrees, behind CI + a human merge gate; `--schedule`/`--continue` run it over time |
+| `/pan:army "<goal>"` | Campaign-scale delivery: Mission Control delegates a whole-project goal to architecture/build/quality/release squads with branch-per-agent worktrees, behind CI + a human merge gate (prompt-enforced on `/pan:army`; enforced in code on the MCP path); `--schedule`/`--continue` run it over time |
 
 ### Phase Management
 
@@ -662,7 +662,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` fixes the issues it marks repairable |
 | `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat and stale or expired memory entries, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs) and Claude Code's own memory index (reported, never edited); `--apply` executes the safe fixes — poisoned ledgers are quarantined by rename (only the newest quarantine copy is kept), and settled `state.md` history, shipped roadmap phases and stale memory entries are archived rather than dropped |
 | `/pan:links [--strict] [--doc-root <dir>] [--source-root <dir>]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027). The default roots are PAN's own source layout, so pass your project's roots |
-| `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase based on UAT criteria |
+| `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase from its summaries, context decisions and verification report |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:retro` | Milestone retrospective — estimation accuracy, verification patterns, gap analysis |
 | `/pan:patches` | Restore local modifications after a PAN update |

package/agents/pan-conductor.md

@@ -51,7 +51,7 @@ Given a phase plan, decompose into **sub-tasks** that correspond to sub-agents:
    - **Executor sub-agents (up to 6):** one per `-plan.md` file that's marked `autonomous: true` in frontmatter. Non-autonomous plans need user checkpoints, which you cannot pause for: do not run them, and list them under "Skipped" in your summary with the instruction to run them with `/pan:exec-phase <N>` (no `--hierarchical`) — nothing runs them after you return.
    - **Reviewer (1):** spawn a `pan-reviewer` after all executors complete, unless `--skip-review` or `--fast` was passed.
    - **Verifier (1):** spawn a `pan-verifier` after the reviewer, unless `workflow.verifier` is false.
-   - Optional hardener + meta-reviewer (2): only if `--deep-review` was also passed.
+   - Optional hardener + meta-reviewer (2): only if `--deep-review` was also passed and the reviewer ran — like exec-phase, skip the deep review under `--skip-review` or `--fast`, since its merge needs the reviewer's report.
 
 3. **Wave grouping:** executors with no cross-plan dependencies can be grouped (within the 12-spawn cap). Sequential executors when `depends_on:` frontmatter indicates.
 
@@ -108,7 +108,7 @@ For each phase execution:
      a. Spawn pan-reviewer (always, unless --skip-review or --fast)
      b. Save its returned report verbatim to {phase_dir}/{phase_number}-review.md (the reviewer is read-only; exec-phase's code_review step saves it the same way), then: pan-tools findings record --phase <N> --agent pan-reviewer --file {phase_dir}/{phase_number}-review.md
 5. After reviewer:
-     a. If --deep-review: spawn pan-hardener (<output_path> .planning/reviews/<N>/hardener.md), then pan-meta-reviewer (<output_path> .planning/reviews/<N>/meta.md)
+     a. If --deep-review and the reviewer ran (not --skip-review/--fast): spawn pan-hardener (<output_path> .planning/reviews/<N>/hardener.md), then pan-meta-reviewer (<output_path> .planning/reviews/<N>/meta.md)
      b. Merge: pan-tools review-deep merge <N> --reviewer-file {phase_dir}/{phase_number}-review.md --hardener-file .planning/reviews/<N>/hardener.md --meta-file .planning/reviews/<N>/meta.md
 6. Spawn pan-verifier — unless `workflow.verifier` is false: then report "verification skipped (workflow.verifier is off)", as exec-phase does
 7. Emit final orchestration summary

package/agents/pan-debugger.md

@@ -830,6 +830,8 @@ gathering -> investigating -> fixing -> verifying -> awaiting_human_verify -> re
                   ^            |           |                 |
                   |____________|___________|_________________|
                   (if verification fails or user reports issue)
+
+goal: find_root_cause_only → gathering -> investigating -> diagnosed (stops there)
 ```
 
 ## Resume Behavior
@@ -1060,7 +1062,7 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# commit_docs is in the JSON output
+# commit_docs is at .config.commit_docs in the JSON output
 ```
 
 **Commit the fix:**

package/agents/pan-design-checker.md

@@ -90,6 +90,7 @@ contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How t
   `unrequested`, every other dimension → `partial`.
 - Each gap is `high`. A gap you report as a caveat on the final iteration is `medium`.
 - `where` is the design section.
+- **On a re-check you are given `<open_findings>`:** your earlier open findings on this phase, each with its `id`. Answer every one in a `resolutions` list in the block: `{"id":"f_…","status":"resolved","evidence":"what you checked and saw"}` when it is fixed, `still_present` when it is not, `cannot_tell` when you could not check it. A finding you leave out stays open: silence never closes a finding, and `resolved` without evidence closes nothing.
 
 The orchestrator records the block, so it must say what your verdict says.
 

package/agents/pan-executor.md

@@ -183,6 +183,23 @@ Only auto-fix issues DIRECTLY caused by the current task's changes. Pre-existing
 - Do NOT fix them
 - Do NOT re-run builds hoping they resolve themselves
 
+**TESTS ARE THE SPEC, NOT AN OBSTACLE:**
+Test files your plan does not list in `files_modified` are read-only. In any test file, never delete or rename a test, add a skip or only marker (`.skip`, `.only`, `xit`, `{ skip: true }`, `@pytest.mark.skip`, `t.Skip`, `#[ignore]`, `@Disabled`), remove an assertion, rewrite an expectation or a snapshot to match what the code now does, or add an assertion that cannot fail. `pan-tools verify test-integrity <phase>` checks the phase's commits for these, and a violation fails the phase gate: exec-phase will not auto-advance, and under `workflow.phase_gate: enforce` the phase cannot be completed without an override.
+
+When a test and your task cannot both be satisfied (the test asserts behaviour the plan changes, or the task is impossible as specified), stop. Do not edit the test. Return:
+
+```markdown
+## BLOCKED_SPEC_CONFLICT
+
+**Plan:** {phase}-{plan}
+**Test:** {file}:{line} — what it asserts
+**Requirement:** the task or requirement it conflicts with
+**Why both cannot hold:** one or two sentences
+**Options:** change the test (needs a plan that declares it) · change the requirement · something else
+```
+
+A person rules on it. Commit the work you finished before stopping.
+
 **FIX ATTEMPT LIMIT:**
 Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 - STOP fixing — document remaining issues in summary.md under "Deferred Issues"
@@ -453,7 +470,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs requirements mark-complete ${RE
 **State command behaviors:**
 - `state advance-plan`: Increments Current Plan, detects last-plan edge case, sets status
 - `state update-progress`: Recalculates progress bar from summary.md counts on disk
-- `state record-metric`: Appends to Performance Metrics table
+- `state record-metric`: Appends a per-plan row to the Performance Metrics table
 - `state add-decision`: Adds to Decisions section, removes placeholders
 - `state record-session`: Updates Last session timestamp and Stopped At fields
 - `roadmap update-plan-progress`: Updates roadmap.md progress table row with PLAN vs SUMMARY counts

package/agents/pan-experiment-runner.md

@@ -105,7 +105,7 @@ After the run completes, produce a concise structured summary:
 - <e.g., "External session ran a tight 14-cycle focus-auto loop">
 
 ### Recommendation for /pan:learn
-- Run `/pan:learn --experiment <slug>` to extract patterns from the trace.
+- Run `/pan:experiment harvest <slug>`, then `/pan:learn --experiment <slug>` to extract patterns from the trace (learn reads the harvest folder, not the experiment folder).
 - Especially check: <areas of high event density / repeated failures>
 ```
 

package/agents/pan-hardener.md

@@ -12,7 +12,7 @@ You are the PAN hardener. You perform focused security review on files changed d
 
 This is **authorized, defensive** secure-coding review of the user's own codebase — the goal is to find and fix weaknesses before shipping. You report findings for the user to remediate; you never write exploit code, attack tooling, or step-by-step intrusion instructions.
 
-You are spawned by `/pan:review-deep <phase>` or `/pan:exec-phase --deep-review`. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
+You are spawned by `/pan:review-deep <phase>`, `/pan:exec-phase --deep-review`, `/pan:focus-exec --deep-review` (per item, output under `.planning/reviews/<item-id>/`) or `/pan:focus-auto` Pass 3. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
 
 **You NEVER modify source files.** Your one write is the report at the output path your prompt gives. You report findings; the user fixes them.
 

package/agents/pan-meta-reviewer.md

@@ -15,7 +15,7 @@ You are the PAN meta-reviewer. Your job is to check the first-pass reviewers (`p
 3. **Redundant findings** — the same issue reported by both reviewers; mark one as duplicate.
 4. **Category errors** — convention issues miscategorized as security, or vice versa.
 
-You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports. Your output is merged with theirs by `review-deep.cjs`.
+You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports, or by `/pan:focus-exec --deep-review` with the hardener's report alone (an item has no first-pass review: check the hardener against the diff, and skip the reviewer-side coverage and duplicate checks). Your output is merged with theirs by `review-deep.cjs`.
 
 **You NEVER modify source code.** You produce one findings file. This is authorized, defensive review of the user's own codebase — you adjudicate security findings for remediation; never produce exploit code.
 

package/agents/pan-phase-researcher.md

@@ -142,7 +142,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit
 
 **Options:**
 - `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+- `--freshness day|week|month|year` — Restrict to recent content
 
 If `brave_search: false` (or not set), use built-in WebSearch tool instead.
 
@@ -411,7 +411,7 @@ Also read `.planning/config.json` — if `workflow.nyquist_validation` is `true`
 
 Then read context.md if exists:
 ```bash
-cat "$phase_dir"/*-context.md 2>/dev/null
+cat "$PHASE_DIR"/*-context.md 2>/dev/null
 ```
 
 **If context.md exists**, it constrains research:

package/agents/pan-plan-checker.md

@@ -246,8 +246,8 @@ issue:
 ```yaml
 issue:
   dimension: scope_sanity
-  severity: warning
-  description: "Plan 01 has 5 tasks - split recommended"
+  severity: blocker
+  description: "Plan 01 has 5 tasks - split required"
   plan: "01"
   metrics:
     tasks: 5
@@ -541,11 +541,11 @@ Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
 Orchestrator provides context.md content in the verification prompt. If provided, parse for locked decisions, discretion areas, deferred ideas.
 
 ```bash
-ls "$phase_dir"/*-plan.md 2>/dev/null
+ls "$PHASE_DIR"/*-plan.md 2>/dev/null
 # Read research for Nyquist validation data
-cat "$phase_dir"/*-research.md 2>/dev/null
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$phase_number"
-cat "$phase_dir"/*-design.md 2>/dev/null   # approved design from /pan:design-phase (Design Conformance)
+cat "$PHASE_DIR"/*-research.md 2>/dev/null
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE"
+cat "$PHASE_DIR"/*-design.md 2>/dev/null   # approved design from /pan:design-phase (Design Conformance)
 ```
 
 **Extract:** Phase goal, requirements (decompose goal), locked decisions, deferred ideas.
@@ -660,7 +660,7 @@ Missing: No mention of fetch/API call → Issue: Key link not planned
 ## Step 8: Assess Scope
 
 ```bash
-for plan in "$phase_dir"/*-plan.md; do
+for plan in "$PHASE_DIR"/*-plan.md; do
   grep -cE "<task[ >]" "$plan"   # "<task" alone also counts the <tasks> wrapper; Step 2's task_count is the same number
   grep "files_modified:" "$plan"
 done
@@ -766,6 +766,7 @@ Return all issues as a structured `issues:` YAML list (see dimension examples fo
 - `verdict` is `passed` or `issues_found` (the status from Step 10), and `outcome` is `pass` or `fail`.
 - Add one finding per issue you list. Blocker → `high`, warning → `medium`, info → `info`. The class follows the dimension, as mapped in the reference.
 - `where` is the plan file, plus `#task-N` when the issue is about one task.
+- **On a re-check you are given `<open_findings>`:** your earlier open findings on this phase, each with its `id`. Answer every one in a `resolutions` list in the block: `{"id":"f_…","status":"resolved","evidence":"what you checked and saw"}` when it is fixed, `still_present` when it is not, `cannot_tell` when you could not check it. A finding you leave out stays open: silence never closes a finding, and `resolved` without evidence closes nothing.
 
 The orchestrator records the block, and the record is what it branches on. The block must say the same thing as your heading.
 
@@ -838,7 +839,7 @@ End it with one finding per listed issue:
 
 ````markdown
 ```pan-verdict
-{"contract":"1.0","agent":"pan-plan-checker","phase":"{phase}","verdict":"issues_found","outcome":"fail","findings":[{"class":"missing","severity":"high","where":"{phase}-01-plan.md","summary":"requirement AUTH-02 (password reset) has no covering task"},{"class":"risk","severity":"medium","where":"{phase}-02-plan.md","summary":"plan 02 modifies 12 files across 5 tasks; split it"}]}
+{"contract":"1.0","agent":"pan-plan-checker","phase":"{phase}","verdict":"issues_found","outcome":"fail","findings":[{"class":"missing","severity":"high","where":"{phase}-01-plan.md","summary":"requirement AUTH-02 (password reset) has no covering task"},{"class":"risk","severity":"high","where":"{phase}-02-plan.md","summary":"plan 02 modifies 12 files across 5 tasks; split it"}]}
 ```
 ````
 

package/agents/pan-planner.md

@@ -422,6 +422,7 @@ files_modified: []
 autonomous: true
 requirements: []
 user_setup: []
+planned_commit: <sha>
 
 # Goal-backward verification; the Frontmatter Fields table below explains each field
 must_haves:
@@ -505,10 +506,11 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-summary.md`
 | `files_modified` | Yes | Files this plan touches |
 | `autonomous` | Yes | `true` if no checkpoints |
 | `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement ID MUST appear in at least one plan. |
+| `planned_commit` | Yes | The output of `git rev-parse HEAD` when you write the plan (omit it outside a git repository) |
 | `user_setup` | No | Human-required setup items |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
-Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.
+Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter. `pan-tools verify plan-set <phase>` checks the arithmetic before the plan checker runs: every roadmap requirement covered, no two plans in one wave modifying the same file, every `depends_on` naming a plan of this phase in an earlier wave, and no cycles.
 
 ## Interface Context for Executors
 

package/agents/pan-project-researcher.md

@@ -111,7 +111,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs websearch "your query" --limit
 
 **Options:**
 - `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+- `--freshness day|week|month|year` — Restrict to recent content
 
 If `brave_search: false` (or not set), use built-in WebSearch tool instead.
 

package/agents/pan-research-synthesizer.md

@@ -59,7 +59,7 @@ cat .planning/research/features.md
 cat .planning/research/architecture.md
 cat .planning/research/pitfalls.md
 
-# Planning config loaded via pan-tools.cjs in commit step
+# The commit step loads the planning config through pan-tools
 ```
 
 Parse each file to extract:

package/agents/pan-reviewer.md

@@ -72,7 +72,7 @@ If a changed file path starts with any of these prefixes, **skip it silently**.
 ## Design smells (baseline)
 
 A fixed baseline that applies even when the project documents no standards (Fowler, *Refactoring*, ch. 3). Rules:
-- Each is a judgement call: always **INFO**, written as "possible <smell>", never a reason for a non-PASS verdict on its own.
+- Each is a judgement call: always **INFO**, written as "possible <smell>", never a reason for a non-PASS verdict on its own; its Category is `Design smell`.
 - **The project wins.** Where a documented project standard, or an established pattern in the code, endorses what a smell would flag, do not report it. Skip anything a linter or formatter already enforces.
 - Only for code this phase changed, and only with a file:line and the hunk that shows it.
 
@@ -136,9 +136,10 @@ Return a structured review report:
 **Machine verdict (required).** End the report with a `pan-verdict` block. The contract is in `~/.claude/pan-wizard-core/references/verdict-contract.md`. How to fill it:
 - `verdict` is the word under `### Verdict`; `outcome` is `fail` for NEEDS_FIXES and `pass` otherwise.
 - Add one finding per table row. ERROR → `high`, WARNING → `medium`, INFO → `info`.
-- Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Unrequested → `unrequested`.
+- Category maps to class: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, Unrequested → `unrequested`.
 - `where` is `file:line`.
 - A clean review has `"findings": []`.
+- **On a re-check you are given `<open_findings>`:** your earlier open findings on this phase, each with its `id`. Answer every one in a `resolutions` list in the block: `{"id":"f_…","status":"resolved","evidence":"what you checked and saw"}` when it is fixed, `still_present` when it is not, `cannot_tell` when you could not check it. A finding you leave out stays open: silence never closes a finding, and `resolved` without evidence closes nothing.
 
 The orchestrator records this block. It is how your findings reach the phase's findings ledger and `/pan:review-deep`.
 

package/agents/pan-verifier.md

@@ -59,7 +59,7 @@ cat "$PHASE_DIR"/*-verification.md 2>/dev/null
 1. Parse previous verification.md frontmatter
 2. Take `must_haves` (truths, artifacts, key_links) from the plans' frontmatter (Step 2, Option A): the verification frontmatter does not store them
 3. Extract `gaps` (items that failed)
-4. Set `is_re_verification = true`
+4. Set `is_re_verification = true`. In the frontmatter's `re_verification` block, list every earlier gap you re-checked and found closed under `gaps_closed`, by its truth (add `evidence:` under a truth when one line says what you saw), and every gap still failing under `gaps_remaining`. A gap you leave out of both stays open in the findings ledger: silence never closes a gap
 5. **Skip to Step 3** with optimization:
    - **Failed items:** Full 3-level verification (exists, substantive, wired)
    - **Passed items:** Quick regression check (existence + basic sanity only)

package/bin/install-lib.cjs

@@ -1160,11 +1160,16 @@ function stripThinkingFrontmatter(content, runtime) {
  */
 function buildCopilotHooksConfig(commands) {
   const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand,
-    stateReinjectMarkCommand, stateReinjectInjectCommand } = commands || {};
+    stateReinjectMarkCommand, stateReinjectInjectCommand, guardCommand } = commands || {};
   const config = { version: 1, hooks: {} };
   if (updateCheckCommand) {
     config.hooks.sessionStart = [{ type: 'command', command: updateCheckCommand }];
   }
+  // preToolUse: the PAN guard (A7). Copilot denies a call on the JSON
+  // `permissionDecision: "deny"` output, which pan-guard.js prints under `--host copilot`.
+  if (guardCommand) {
+    config.hooks.preToolUse = [{ type: 'command', command: guardCommand }];
+  }
   const postToolUse = [];
   if (contextMonitorCommand) postToolUse.push({ type: 'command', command: contextMonitorCommand });
   // State re-injection after a compaction (M33): preCompact leaves the marker, the
@@ -1238,10 +1243,10 @@ function buildCopilotHooksConfig(commands) {
  * 2026-10-03, and live on Copilot CLI 1.0.88 the same day).
  */
 const HOOK_EVENT_MAP = Object.freeze({
-  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
-  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null, compactMark: 'PreCompress', compactInject: 'AfterTool' },
-  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
-  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
+  claude: { surface: 'settings.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', preToolUse: 'BeforeTool', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null, compactMark: 'PreCompress', compactInject: 'AfterTool' },
+  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', preToolUse: 'preToolUse', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
   opencode: null,
 });
 
@@ -1253,7 +1258,7 @@ const HOOK_EVENT_MAP = Object.freeze({
 const HOOK_SLOT_MATCHERS = Object.freeze({ compact: 'compact' });
 
 /** The hook scripts PAN registers in a Claude-shaped settings.json `hooks` block. */
-const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-context-monitor', 'pan-cost-logger', 'pan-trace-logger', 'pan-stop-guard', 'pan-state-reinject']);
+const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-guard', 'pan-context-monitor', 'pan-cost-logger', 'pan-trace-logger', 'pan-stop-guard', 'pan-state-reinject']);
 
 /**
  * Remove, from every event array of a Claude-shaped `hooks` object except
@@ -1384,10 +1389,78 @@ function mergeMcpRegistration(existing, runtime, entry, serverName = 'pan') {
   const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
   const key = spec.key;
   if (!config[key] || typeof config[key] !== 'object' || Array.isArray(config[key])) config[key] = {};
+  // OpenCode 2 nests servers under `mcp.servers` (R47). PAN keeps writing the v1
+  // shape, but in a file the user already converted it updates the native entry and
+  // never leaves a legacy `mcp.pan` beside it: the native one would win, stale.
+  if (runtime === 'opencode' && isOpencodeV2Servers(config[key].servers)) {
+    config[key].servers[serverName] = entry;
+    delete config[key][serverName];
+    return config;
+  }
   config[key][serverName] = entry;
   return config;
 }
 
+/** OpenCode 2's `mcp.servers` container: an object of server entries, not a v1 server named "servers". */
+function isOpencodeV2Servers(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v) && !('type' in v) && !('command' in v);
+}
+
+/**
+ * Add PAN's OpenCode read and external_directory allowances for `panPath`.
+ * v1 (or a new file): the `permission` object PAN has always written. v2 (the file
+ * already has an ordered `permissions[]` of {action, resource, effect}): PAN's rules
+ * go into that array, and no legacy `permission` object is added beside it (R47).
+ * @returns {{config: object, modified: boolean, shape: 'v1'|'v2'}}
+ */
+function addOpencodePermissions(existing, panPath) {
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  let modified = false;
+  if (Array.isArray(config.permissions)) {
+    for (const action of ['read', 'external_directory']) {
+      const has = config.permissions.some((r) => r && r.action === action && r.resource === panPath && r.effect === 'allow');
+      if (!has) { config.permissions.push({ action, resource: panPath, effect: 'allow' }); modified = true; }
+    }
+    return { config, modified, shape: 'v2' };
+  }
+  if (!config.permission || typeof config.permission !== 'object' || Array.isArray(config.permission)) config.permission = {};
+  for (const type of ['read', 'external_directory']) {
+    if (!config.permission[type] || typeof config.permission[type] !== 'object') config.permission[type] = {};
+    if (config.permission[type][panPath] !== 'allow') { config.permission[type][panPath] = 'allow'; modified = true; }
+  }
+  return { config, modified, shape: 'v1' };
+}
+
+/**
+ * Remove every PAN allowance from an OpenCode config, in either shape: keys of the
+ * v1 `permission.read` / `permission.external_directory` objects and v2
+ * `permissions[]` rules whose path names `pan-wizard` (which also catches the
+ * malformed `~/.config/opencode/pan-wizard/*` key early versions wrote). Containers
+ * PAN emptied are removed.
+ * @returns {{config: object, modified: boolean}}
+ */
+function stripOpencodePermissions(existing) {
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  let modified = false;
+  if (config.permission && typeof config.permission === 'object' && !Array.isArray(config.permission)) {
+    for (const type of ['read', 'external_directory']) {
+      const bag = config.permission[type];
+      if (!bag || typeof bag !== 'object') continue;
+      for (const key of Object.keys(bag)) if (key.includes('pan-wizard')) { delete bag[key]; modified = true; }
+      if (Object.keys(bag).length === 0) delete config.permission[type];
+    }
+    if (Object.keys(config.permission).length === 0) delete config.permission;
+  }
+  if (Array.isArray(config.permissions)) {
+    const kept = config.permissions.filter((r) => !(r && typeof r.resource === 'string' && r.resource.includes('pan-wizard')));
+    if (kept.length !== config.permissions.length) {
+      modified = true;
+      if (kept.length) config.permissions = kept; else delete config.permissions;
+    }
+  }
+  return { config, modified };
+}
+
 /**
  * Remove PAN's MCP server from a config object, preserving foreign entries.
  * Empties the container key when PAN was its only member, so uninstall does not
@@ -1400,10 +1473,17 @@ function stripMcpRegistration(existing, runtime, serverName = 'pan') {
   if (!spec) throw new Error(`stripMcpRegistration: unknown runtime "${runtime}"`);
   const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
   const bag = config[spec.key];
-  if (!bag || typeof bag !== 'object' || !(serverName in bag)) return { config, removed: false };
-  delete bag[serverName];
-  if (Object.keys(bag).length === 0) delete config[spec.key];
-  return { config, removed: true };
+  if (!bag || typeof bag !== 'object') return { config, removed: false };
+  let removed = false;
+  // OpenCode 2's `mcp.servers.pan` as well as the v1 `mcp.pan` (R47).
+  if (runtime === 'opencode' && isOpencodeV2Servers(bag.servers) && serverName in bag.servers) {
+    delete bag.servers[serverName];
+    if (Object.keys(bag.servers).length === 0) delete bag.servers;
+    removed = true;
+  }
+  if (serverName in bag) { delete bag[serverName]; removed = true; }
+  if (removed && Object.keys(bag).length === 0) delete config[spec.key];
+  return { config, removed };
 }
 
 /**
@@ -1439,7 +1519,7 @@ function buildCodexMcpSnippet(serverPath, panToolsPath, projectRoot, serverName
  * @returns {object} Merged config object to serialize back to hooks.json
  */
 function mergeCodexHooksConfig(existing, commands) {
-  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand } = commands || {};
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand, guardCommand } = commands || {};
   const config = (existing && typeof existing === 'object') ? existing : {};
   if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
 
@@ -1461,6 +1541,8 @@ function mergeCodexHooksConfig(existing, commands) {
   // builders without reading their docs first.
   const wanted = [
     ['SessionStart', updateCheckCommand, 'pan-check-update', true],
+    // The guard decides whether a call may run, which an async handler cannot (A7).
+    ['PreToolUse', guardCommand, 'pan-guard', false],
     ['PostToolUse', contextMonitorCommand, 'pan-context-monitor', false],
     ['SubagentStop', costLoggerCommand, 'pan-cost-logger', true],
     ['SubagentStop', traceLoggerCommand, 'pan-trace-logger', true],
@@ -1504,7 +1586,7 @@ function removeCodexPanHooks(existing) {
   for (const event of Object.keys(existing.hooks)) {
     if (!Array.isArray(existing.hooks[event])) continue;
     existing.hooks[event] = existing.hooks[event].filter(group =>
-      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|context-monitor|cost-logger|trace-logger|stop-guard|state-reinject)/.test(h.command))));
+      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|guard|context-monitor|cost-logger|trace-logger|stop-guard|state-reinject)/.test(h.command))));
     if (existing.hooks[event].length === 0) delete existing.hooks[event];
   }
   if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
@@ -1929,15 +2011,16 @@ function buildPluginManifest(pkg) {
  * @returns {object} hooks.json object
  */
 function buildPluginHooksConfig() {
-  const hook = (script, matcher) => ({
+  const hook = (script, matcher, args = '') => ({
     ...(matcher ? { matcher } : {}),
-    hooks: [{ type: 'command', command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"` }],
+    hooks: [{ type: 'command', command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"${args}` }],
   });
   const events = HOOK_EVENT_MAP.claude;
   return {
     hooks: {
       // compact shares SessionStart with the update check, narrowed by its matcher (M10).
       [events.sessionStart]: [hook('pan-check-update.js'), hook('pan-state-reinject.js', HOOK_SLOT_MATCHERS.compact)],
+      [events.preToolUse]: [hook('pan-guard.js', null, ' --host claude')],
       [events.postToolUse]: [hook('pan-context-monitor.js')],
       [events.subagentStop]: [hook('pan-cost-logger.js'), hook('pan-trace-logger.js')],
       [events.stop]: [hook('pan-stop-guard.js')],
@@ -2147,7 +2230,7 @@ const FINDINGS = {
         properties: {
           title: { type: 'string' },
           file: { type: 'string' },
-          severity: { type: 'string', enum: ['critical', 'major', 'minor', 'info'] },
+          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] }, // PAN's one ladder (verdict.cjs, review-deep.cjs)
           detail: { type: 'string' },
         },
         required: ['title', 'severity', 'detail'],
@@ -2256,6 +2339,7 @@ return { areas_mapped: maps.filter(Boolean).length, synthesis }
     { title: 'Index', detail: 'plan inventory with wave grouping, from the PAN engine' },
     { title: 'Execute', detail: 'one executor per plan; waves in order, plans within a wave in parallel' },
     { title: 'Verify', detail: 'the phase verifier over the completed plans' },
+    { title: 'Gate', detail: 'the PAN phase gate: stops when the phase may not be completed' },
   ],
 }
 // twin: pan-wizard-core/workflows/exec-phase.md
@@ -2377,7 +2461,24 @@ const verdict = await agent(
   'Verify phase ' + phaseArg + ' following the PAN verify-phase protocol (PAN core: workflows/verify-phase.md — ' + PAN_TOOLS + '). Check the phase goals against what the plans delivered, write the verification file the protocol prescribes, and report status (passed | gaps_found | human_needed | failed), the verification file path, any gaps, and a summary. Do not mark the phase complete or advance state — that decision stays with the user.',
   { agentType: 'pan-verifier', label: 'verify', phase: 'Verify', schema: VERIFY })
 
-return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, next: 'Review the verification, then continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
+phase('Gate')
+const GATE = {
+  type: 'object',
+  properties: {
+    ok: { type: 'boolean' },
+    mode: { type: 'string' },
+    reasons: { type: 'array', items: { type: 'object', properties: { code: { type: 'string' }, detail: { type: 'string' } }, required: ['code'] } },
+  },
+  required: ['ok', 'reasons'],
+}
+const gate = await agent(
+  'Run the PAN phase gate for phase ' + phaseArg + ' with the ' + PAN_TOOLS + ' Run exactly: phase gate ' + phaseArg + ' (it exits 1 when it refuses; that is a result, not an error). Return its JSON fields ok, mode and reasons (each code and detail) unchanged. Do not fix anything and do not mark the phase complete.',
+  { label: 'gate', phase: 'Gate', schema: GATE })
+const gateReasons = gate && Array.isArray(gate.reasons) ? gate.reasons : []
+if (!gate || gate.ok !== true) {
+  return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, gate, halted: 'phase_gate', next: 'The phase gate refused: ' + (gateReasons.map((r) => r.code).join(', ') || 'the gate step returned no verdict') + '. Fix each reason (or close the gaps with /pan:plan-phase ' + phaseArg + ' --gaps), then re-run /pan:exec-phase ' + phaseArg + '. Do not mark the phase complete until the gate passes.' }
+}
+return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, gate, next: 'The phase gate passes. Continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
 `;
 
   const diagnoseIssues = `export const meta = {
@@ -2559,6 +2660,8 @@ module.exports = {
   buildMcpServerEntry,
   mergeMcpRegistration,
   stripMcpRegistration,
+  addOpencodePermissions,
+  stripOpencodePermissions,
   buildCodexMcpSnippet,
   removeCodexPanHooks,
   buildNativeWorkflowScripts,