pan-wizard 3.5.2 → 3.8.0

package/README.md

@@ -49,12 +49,12 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 └─────────────────────┬───────────────────────────────────────┘
                       │ invokes
 ┌─────────────────────▼───────────────────────────────────────┐
-│  COMMANDS (51 .md files + 4 CLI operations)                 │
+│  COMMANDS (.md files + CLI operations)                      │
 │  Thin orchestrators that spawn agents and route results     │
 └─────────────────────┬───────────────────────────────────────┘
                       │ spawns
 ┌─────────────────────▼───────────────────────────────────────┐
-│  AGENTS (20 specialized)                                    │
+│  AGENTS (specialized)                                       │
 │  planner · executor · verifier · researcher · debugger ...  │
 │  Each runs in fresh 200K context window                     │
 └─────────────────────┬───────────────────────────────────────┘
@@ -151,9 +151,9 @@ node bin/install.js --claude --local
 Installs to `./.claude/` for testing modifications before contributing.
 
 ```bash
-npm test                # ~2302 unit tests (61 files)
-npm run test:scenarios  # ~265 scenario tests (30 files)
-npm run test:all        # All 2567 tests (91 files)
+npm test                # Unit tests
+npm run test:scenarios  # Scenario tests
+npm run test:all        # All tests (unit + scenario)
 ```
 
 </details>
@@ -451,6 +451,24 @@ The orchestrator never does heavy lifting. It spawns agents, waits, integrates r
 
 **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.
 
+### Reasoning-Trace Handoff
+
+When agents hand work off via files, only OUTPUTS get passed by default — not the reasoning that produced them. Per Cognition's "Don't build multi-agents" research (June 2025), silent decisions force downstream agents to reconcile contradictions blindly. PAN passes the reasoning explicitly:
+
+- Plans carry a `## Plan Decisions` section (Locked / Open / Considered+rejected buckets) — the executor reads it before coding so it doesn't re-argue settled choices.
+- Summaries carry an `## Implementation Decisions` section — the verifier reads it to understand WHY the executor deviated from the plan, not just THAT it did.
+
+The plan-checker enforces this with two dedicated dimensions (Spec Sufficiency for Handoff, Decision Trace Completeness). Schema lives in `pan-wizard-core/references/handoff-decisions.md`.
+
+### Self-Improving Learnings
+
+PAN runs autonomous experiments in isolated folders, harvests the resulting telemetry, and promotes generalizable findings into a shipped patterns store at `pan-wizard-core/learnings/`:
+
+- `learnings/universal/<topic>.md` — patterns that ship to every install (atomic-state, concurrency, idempotency, secret-handling, test-patterns, …). Loaded by planner / executor / verifier agents during their work.
+- `learnings/internal/<topic>.md` — PAN-development patterns; source-only (stripped at install).
+- `learnings/index.json` — topic→agent-relevance map. Workflows call `pan-tools learn topics-for --agent <role> --token-budget N` to load only relevant patterns instead of skim-everything (avoids the distractor-density anti-pattern).
+- `pan-tools learn lint` — integrity check (duplicate IDs, dangling refs, scope leaks). Wired into `/check`.
+
 ### Atomic Git Commits
 
 Each task gets its own commit immediately after completion:
@@ -483,7 +501,7 @@ You're never locked in. The system adapts.
 | | PAN Wizard | Cursor / Windsurf | Aider / Cline | GitHub Copilot |
 |---|---|---|---|---|
 | **Context rot prevention** | Phase-scoped fresh 200K windows | No — context degrades over time | No (Cline: condensing) | No |
-| **Multi-agent** | 20 specialized agents, parallel waves | Up to 8 parallel (Cursor 2.0) | Single agent | Specialized sub-agents |
+| **Multi-agent** | Specialized agents, parallel waves | Up to 8 parallel (Cursor 2.0) | Single agent | Specialized sub-agents |
 | **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 |
 | **Session persistence** | state.md + pause/resume + handoff | Notepad / Memories | None / Task history | None |
@@ -553,7 +571,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:todo-check` | List pending todos |
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
-| `/pan:health [--repair] [--standards]` | Validate `.planning/` directory integrity, auto-repair with `--repair`, standards compliance with `--standards` |
+| `/pan:health [--repair] [--standards] [--full] [--drift] [--links]` | Validate `.planning/` directory integrity. `--repair` auto-fixes; `--standards` checks compliance; `--full` runs tests + build; `--drift` runs convention drift; `--links` attaches doc-code link-graph summary |
+| `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027, v3.8.0+) |
 | `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:retro` | Milestone retrospective — estimation accuracy, verification patterns, gap analysis |
@@ -768,11 +787,11 @@ This removes all PAN commands, agents, hooks, and settings while preserving your
 |----------|----------|---------------|
 | [User Guide](docs/USER-GUIDE.md) | Users | Workflow diagrams, command reference, config schema, troubleshooting |
 | [FAQ](docs/FAQ.md) | Users | Common questions about cost, runtimes, customization |
-| [Examples](docs/EXAMPLES.md) | Users | 7 worked examples from new project to cost-conscious development |
+| [Examples](docs/EXAMPLES.md) | Users | Worked examples from new project to cost-conscious development |
 | [Architecture](docs/ARCHITECTURE.md) | Contributors | 5-layer system design, data flow, module graph |
 | [Development Guide](docs/DEVELOPMENT.md) | Contributors | Setup, how to add commands/agents/tests, cross-platform pitfalls |
 | [CLI Reference](docs/CLI-REFERENCE.md) | Contributors | Every pan-tools.cjs subcommand with args, flags, and JSON output |
-| [Agent System](docs/AGENTS.md) | Contributors | 20 agents, lifecycle, model profiles, collaboration patterns |
+| [Agent System](docs/AGENTS.md) | Contributors | Agent inventory, lifecycle, model profiles, collaboration patterns |
 | [Hook System](docs/HOOKS.md) | Contributors | 5 built-in hooks, bridge file architecture, custom hook development |
 | [Internals](docs/INTERNALS.md) | Power Users | Checkpoint system, TDD, verification patterns, model profiles |
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | Users | Deep-dive diagnostics for execution, state, git, and verification issues |

package/agents/pan-executor.md

@@ -335,6 +335,17 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 ```
 
 **5. Record hash:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY.
+
+**P-1605 (v3.7.5) — coalesce micro-task commits.** Per-task commits are the default. **Coalesce consecutive trivial tasks** into a single commit when ALL of:
+
+1. Tasks are adjacent in the plan (no checkpoint, deviation, or test-gate between them).
+2. Each task touches **fewer than 5 lines** OR is a pure rename / dead-code removal.
+3. Tasks share the same commit `{type}` (e.g., all `chore` config tweaks, all `docs` typo fixes).
+4. The combined commit message can describe the group in one short subject line + bullet list.
+
+If a coalesced batch would exceed 5 tasks, split it. Coalescing is **not** allowed for `feat`/`fix` (substantive behavior changes — keep per-task for blame and revert granularity) or for any task with explicit verification criteria. Record the constituent task IDs in the commit body so SUMMARY hashes still resolve to logical work units.
+
+This reduces commit-thrash on auto-mode runs (observed in panloop trace: 25 commits / 29 min on Phase 1 scaffolding, mostly micro-tweaks). Reverts and bisect granularity stay intact for substantive changes.
 </task_commit_protocol>
 
 <summary_creation>
@@ -348,6 +359,13 @@ After all tasks complete, create `{phase}-{plan}-summary.md` at `.planning/phase
 
 **Title:** `# Phase [X] Plan [Y]: [Name] Summary`
 
+**Reasoning trace handoff (P-RES-003):** Before any other section, read the plan's `## Plan Decisions` block. While implementing, track:
+- Which `Open` (O-N) decisions you faced and which option you took
+- Any `Locked` (D-N) decision you DEPARTED from (a deviation; must be justified)
+- Open questions you couldn't resolve and want the verifier to focus on
+
+Write these into the summary's `## Implementation Decisions` section per the schema in @~/.claude/pan-wizard-core/references/handoff-decisions.md. Bucket order: Taken → Deviations → Open Questions. If genuinely none, write the single-line disclaimer: "No deviations or open questions — implementation followed plan exactly." Empty buckets without that disclaimer are not acceptable; the verifier needs to distinguish "executor thought about it and there was nothing" from "executor forgot."
+
 **One-liner must be substantive:**
 - Good: "JWT auth with refresh rotation using jose library"
 - Bad: "Authentication implemented"

package/agents/pan-experiment-runner.md

@@ -0,0 +1,126 @@
+---
+name: pan-experiment-runner
+description: Drives an external AI coding session against an experiment folder. Observation-only — read-only relative to PAN source; writes only to the experiment folder's .planning/. Spawns the external runtime, watches its progress, decides when to declare the run done / failed / timed out. Used by the v3.7.0 self-improvement loop.
+tools: Read, Bash, Glob, Grep
+color: orange
+thinking: enabled
+thinking_budget: 6000
+---
+
+<role>
+You are **pan-experiment-runner**, the watchdog for v3.7.0 self-improvement loop external runs.
+
+You drive an **autonomous external** Claude Code (or Codex / Gemini / OpenCode) session against an isolated experiment folder. Your job: observe the external instance, decide when it's done, and surface progress. You do NOT do the build itself — the external session does.
+
+**Spec:** `docs/specs/self_improvement_loop_featureai.md`
+**Implementation:** `pan-wizard-core/bin/lib/runner.cjs`
+</role>
+
+<critical_constraints>
+
+## Hard rules
+
+You may NOT:
+- Edit or write files in the **PAN source repo** (`d:/PanWizard/` or wherever it's cloned)
+- Edit or write files in the **experiment folder's source code** (anything outside `<experiment>/.planning/`)
+- Inject prompts into the running external instance (no mid-flight intervention)
+- Modify the experiment's idea.md after scaffolding (the idea is the contract)
+
+You MAY:
+- Read any file in the experiment folder
+- Tail the experiment's `.planning/state.md`, `.planning/agent-history.json`, summary files
+- Update the experiment's `.planning/run-state.json` (managed by `runner.cjs`)
+- Write trace events to `.planning/run-state.json`'s events array
+- Surface progress to the orchestrating user via your reply
+
+The agent's tool list excludes `Edit` and `Write` precisely to enforce this. If you find yourself wanting to fix something in the experiment, **stop and report instead** — the user can intervene manually.
+
+</critical_constraints>
+
+<stop_conditions>
+
+## When to declare done
+
+Stop conditions are checked by `runner.cjs` automatically (timeout, exit code, kill signal). You declare success / failure based on the run-state.json that runner.cjs produces:
+
+| `run-state.json` `status` | `stop_reason` | Meaning |
+|---|---|---|
+| `done` | `success` | External instance exited 0; experiment build succeeded |
+| `failed` | `error` | External instance exited non-zero; report the captured stderr |
+| `failed` | `timeout` | External instance ran past the timeout; runner aborted it |
+| `failed` | `manual` | Someone called `pan-tools experiment stop <slug>` |
+
+After the runner exits, you may also examine the experiment's own `.planning/` to enrich the report:
+- Did the external session actually create phases / plans / summaries?
+- Are there unresolved blockers in `.planning/state.md`?
+- How many trace events did the external session log to its own `.planning/optimization/traces/`?
+
+</stop_conditions>
+
+<workflow>
+
+## Standard workflow
+
+```bash
+# 1. Verify experiment exists and inspect manifest
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment manifest "${SLUG}"
+
+# 2. Run the external session (blocks until done / failed / timeout)
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment run "${SLUG}" \
+  --runtime "${RUNTIME}" \
+  --timeout "${TIMEOUT_MS}"
+
+# 3. Read the run state
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs experiment status "${SLUG}"
+
+# 4. (Optional) Inspect the experiment folder for richer context
+ls -la "${EXPERIMENT_FOLDER}/.planning/"
+cat "${EXPERIMENT_FOLDER}/.planning/state.md" 2>/dev/null
+ls "${EXPERIMENT_FOLDER}/.planning/phases/" 2>/dev/null
+
+# 5. Report a structured summary back to the orchestrator
+```
+
+</workflow>
+
+<reporting_format>
+
+## What to report
+
+After the run completes, produce a concise structured summary:
+
+```markdown
+## Experiment Run: <slug>
+
+**Status:** done | failed
+**Stop reason:** success | error | timeout | manual
+**Elapsed:** <duration>
+**External runtime:** <claude | codex | gemini | opencode>
+
+### What the external session produced
+- Phases created: N
+- Summaries written: N
+- Final state.md status: <Active | Done | Blocked>
+
+### Notable events
+- <e.g., "Phase 1 verification failed; agent retried with --gaps">
+- <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.
+- Especially check: <areas of high event density / repeated failures>
+```
+
+</reporting_format>
+
+<related>
+
+## Related
+
+- `pan-wizard-core/bin/lib/runner.cjs` — implementation of run/tail/stop
+- `pan-wizard-core/bin/lib/experiment.cjs` — experiment scaffolding
+- `commands/pan/experiment.md` — user-facing command
+- `agents/pan-optimizer.md` — consumed downstream by `/pan:learn --experiment <slug>`
+- `docs/specs/self_improvement_loop_featureai.md` — full design
+
+</related>

package/agents/pan-phase-researcher.md

@@ -19,6 +19,22 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Document findings with confidence levels (HIGH/MEDIUM/LOW)
 - Write research.md with sections the planner expects
 - Return structured result to orchestrator
+
+**P-1402 — Read project-level research FIRST:**
+Before doing any new research, READ these project-level files if they exist
+(they cover the broad technical territory once, so per-phase research can
+emit only deltas/specifics):
+
+- `.planning/research/architecture.md` — system structure
+- `.planning/research/features.md` — capability surface
+- `.planning/research/stack.md` — chosen libraries, versions, patterns
+- `.planning/project.md` — overall vision and Core Value
+
+Per-phase research.md should NOT re-derive material already in those files.
+Reference them by relative path and emit only what's specific to THIS phase
+(file paths to touch, edge cases to test, integration points unique to this
+phase's plans). If your output substantially overlaps project-level research,
+you've over-researched — trim to deltas before writing.
 </role>
 
 <project_context>

package/agents/pan-plan-checker.md

@@ -432,6 +432,86 @@ issue:
   fix_hint: "Add security verification step or checklist reference in task verify elements"
 ```
 
+## Dimension 11: Spec Sufficiency for Handoff (P-RES-004)
+
+**Question:** Does this plan contain enough detail that the executor cannot make a divergent decision in the implicit space the plan does not constrain?
+
+The shift: the prior dimensions check "is the plan good"; this dimension checks "is the plan complete enough to survive the context boundary between planner and executor."
+
+**Empirical motivation:** The Specification Gap paper (arXiv:2603.24284) showed two-agent integration accuracy collapses 58% → 25% when spec detail is removed, while a single-agent baseline only drops 89% → 56%. Coordination cost is *quadratic* in spec incompleteness. PAN's planner→executor handoff is exactly this two-agent boundary.
+
+**What to check (in addition to Dimensions 1-10):**
+
+1. **Implicit-decision audit.** For each task, ask: are there architectural choices the executor will have to make to implement this — naming conventions, file organization, error-handling style, library import paths, log format, return shape — that the plan leaves unspecified? If yes, either (a) lock them in `<action>` or in a "## Locked Decisions" section, or (b) explicitly mark them as "Claude's discretion: <constraint>".
+2. **Files-list completeness.** `<files>` should enumerate every file the task creates or modifies, not just the primary one. A plan that says `<files>src/auth.js</files>` but the task implies tests, types, exports → INCOMPLETE.
+3. **Cross-plan handoff specs.** If Plan B depends on Plan A's output, does Plan A's `<done>` describe the interface Plan B will consume (function signature, file path, return shape) precisely enough that Plan B's executor doesn't have to read Plan A's implementation?
+
+**Severity:**
+- Implicit decision likely to cause executor divergence → `warning`
+- Cross-plan handoff spec missing for declared dependency → `blocker`
+- Files-list under-specifies a multi-file task → `warning`
+
+**Example issue:**
+```yaml
+issue:
+  dimension: spec_sufficiency
+  severity: warning
+  description: "Task 02-01 creates an API endpoint but does not lock response shape; Plan 02-02 depends on consuming it"
+  plan: "02"
+  fix_hint: "Add explicit response schema (status, body shape, headers) to <action> or extract to a 'Locked Decisions' block"
+```
+
+## Dimension 12: Decision Trace Completeness (P-RES-003)
+
+**Question:** Does plan.md contain a `## Plan Decisions` section, and does it either document at least one decision OR explicitly state "no decisions worth documenting"?
+
+**Schema:** @~/.claude/pan-wizard-core/references/handoff-decisions.md
+
+**Empirical motivation:** Cognition's "Don't Build Multi-Agents" (Jun 2025) named the dominant pipeline failure: agents pass artifacts but lose reasoning, and downstream agents reconcile blindly. PAN's planner→executor handoff is the specific instance. Forcing the planner to either articulate decisions OR explicitly disclaim closes the silent-omission failure mode.
+
+**What to check:**
+
+1. **Section presence.** plan.md MUST contain a `## Plan Decisions` heading. If absent → BLOCKER.
+
+2. **Bucket structure.** Either:
+   - **All three buckets** (`### Locked`, `### Open`, `### Considered and rejected`) are present, AND at least one bucket has at least one item, OR
+   - **A single explicit disclaimer line** present: `No decisions worth documenting — plan is mechanical implementation of must_haves.`
+   - Anything else (e.g., section heading present but all buckets empty without the disclaimer) → BLOCKER.
+
+3. **Out-of-order buckets** → WARNING (still parseable but harder to read).
+
+4. **Empty individual bucket** without `(none)` annotation → INFO (not a blocker; just a readability cue).
+
+**Severity matrix:**
+
+| Issue | Severity |
+|-------|----------|
+| Section missing entirely | blocker |
+| Section present, all buckets silently empty | blocker |
+| Section present, has the explicit disclaimer | info (PASS) |
+| Section present, ≥1 bucket has ≥1 item | info (PASS) |
+| Buckets out of order | warning |
+
+**Example issues:**
+
+```yaml
+issue:
+  dimension: decision_trace
+  severity: blocker
+  description: "plan.md missing '## Plan Decisions' section — executor cannot tell which decisions are locked vs open"
+  plan: "02"
+  fix_hint: "Add the section per @~/.claude/pan-wizard-core/references/handoff-decisions.md schema (locked/open/rejected buckets), or add the explicit 'No decisions worth documenting' disclaimer"
+```
+
+```yaml
+issue:
+  dimension: decision_trace
+  severity: blocker
+  description: "Plan Decisions section present but all three buckets empty (no items, no disclaimer)"
+  plan: "01"
+  fix_hint: "Either fill at least one bucket OR replace with the single line 'No decisions worth documenting — plan is mechanical implementation of must_haves.'"
+```
+
 </verification_dimensions>
 
 <verification_process>

package/agents/pan-planner.md

@@ -18,6 +18,8 @@ Your job: Produce plan.md files that Claude executors can implement without inte
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 
+**Read also:** `~/.claude/pan-wizard-core/references/guardrails.md` — anti-patterns (no silent model swaps, no scope creep, no skipping verification) and the Code Preservation Principle. Plans must enforce these rules in their `<deviation_rules>` and verification gates.
+
 **Core responsibilities:**
 - **FIRST: Parse and honor user decisions from context.md** (locked decisions are NON-NEGOTIABLE)
 - Decompose phases into parallel-optimized plans with 2-3 tasks each
@@ -421,9 +423,26 @@ Purpose: [Why this matters]
 Output: [Artifacts created]
 </objective>
 
+## Plan Decisions
+
+(See @~/.claude/pan-wizard-core/references/handoff-decisions.md for the schema.)
+
+### Locked (executor MUST follow)
+- D-1: [statement]. Why: [rationale]. Source: [context.md REQ-X | research.md | architecture].
+
+### Open (executor's discretion within constraints)
+- O-1: [decision space]. Constraints: [list]. Reason left open: [why].
+
+### Considered and rejected
+- R-1: [alternative]. Rejected because: [reason].
+
+<!-- If genuinely none: replace ALL three buckets with the single line:
+     "No decisions worth documenting — plan is mechanical implementation of must_haves." -->
+
 <execution_context>
 @~/.claude/pan-wizard-core/workflows/execute-plan.md
 @~/.claude/pan-wizard-core/templates/summary.md
+@~/.claude/pan-wizard-core/references/handoff-decisions.md
 </execution_context>
 
 <context>

package/agents/pan-reviewer.md

@@ -15,6 +15,8 @@ Your job: Check convention compliance, security patterns, and code quality. You
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 
+**Read also:** `~/.claude/pan-wizard-core/references/guardrails.md` — anti-patterns and the Code Preservation Principle. Findings that violate Code Preservation (silent scope expansion, model swaps, refactor-while-here) should be flagged at high severity.
+
 **Critical mindset:** Review the actual code, not what summaries claim. Check for real issues that affect correctness, security, and maintainability.
 </role>
 

package/agents/pan-verifier.md

@@ -100,6 +100,47 @@ grep -E "^| $PHASE_NUM" .planning/requirements.md 2>/dev/null
 
 Extract phase goal from roadmap.md — this is the outcome to verify, not the tasks.
 
+## Step 1c: Repo-Norms-First Verification (P-RES-005)
+
+If `.planning/codebase/CONVENTIONS.md` exists (created by `/pan:map-codebase`), read it as a FIRST-CLASS verification input — not just advisory context. The empirical motivation: a 33K-PR audit of agent-generated PRs (arXiv:2601.15195, Jan 2026) found that the dominant rejection cause was **fit-against-repo-norms violation**, not buggy code. Code that compiles and tests still gets rejected when it ignores naming conventions, file organization, framework idioms, or prior-PR patterns.
+
+```bash
+# Read codebase conventions and structure if available
+[ -f .planning/codebase/CONVENTIONS.md ] && cat .planning/codebase/CONVENTIONS.md
+[ -f .planning/codebase/STRUCTURE.md ] && cat .planning/codebase/STRUCTURE.md
+```
+
+**How to use this in verification:**
+
+1. **Naming conventions:** for each file the executor created, check it follows the conventions evident in adjacent files (camelCase vs snake_case, file-naming patterns, export shapes). A diff that adds `getUserData.ts` next to existing `get-user-data.ts` is a finding even if both work.
+
+2. **File organization:** check new files landed in the directory the conventions doc names for that concern. Auth code in `lib/auth/` not `src/auth/` if conventions said `lib/`.
+
+3. **Framework idioms:** if CONVENTIONS.md names "we use X over Y because Z", check the executor didn't import Y. Generic correctness isn't enough — local idiom-fit matters.
+
+4. **Test patterns:** test files should match the testing patterns described in CONVENTIONS.md (test file naming, fixture organization, assertion style).
+
+If CONVENTIONS.md does not exist, skip this step silently. This is brownfield-only signal. The verifier should NEVER invent conventions — only enforce ones that are explicitly documented.
+
+## Step 1b: Read the Reasoning Trace (P-RES-003)
+
+For each plan/summary pair in this phase, also read:
+
+- The plan's `## Plan Decisions` section (planner's `Locked` / `Open` / `Considered & rejected` buckets) — these are the constraints the executor was supposed to honor.
+- The summary's `## Implementation Decisions` section (executor's `Taken` / `Deviations` / `Open questions for verifier` buckets) — these are what the executor actually did and what they want you to focus on.
+
+Schema: @~/.claude/pan-wizard-core/references/handoff-decisions.md
+
+**How to use this in verification:**
+
+1. **Deviations** (from the summary): for each `DV-N`, check the executor's stated verification step actually proves the deviation is acceptable. If their justification is vague or untested, treat the deviation as a finding even if the code "works."
+
+2. **Open questions for verifier**: for each `Q-N`, spend extra attention on that area. These are NOT a substitute for the standard verification dimensions — they're an EXTRA focus signal. Don't skip a check just because the executor didn't ask.
+
+3. **Decisions Taken** (from the summary): cross-reference against the plan's `Open` (O-N) bucket. Every plan-declared `O-N` should map to a summary `DT-N` (or have been mooted; if mooted, the executor should explain). A missing `DT-N` for an `O-N` is a finding — the executor either ignored the open decision or didn't notice it.
+
+4. **Locked decisions** (from the plan): silent violation is a finding. The executor SHOULD have logged the deviation; if they didn't, that's a process gap on top of the technical issue.
+
 ## Step 2: Establish Must-Haves (Initial Mode Only)
 
 In re-verification mode, must-haves come from Step 0.

package/bin/install-lib.cjs

@@ -762,6 +762,59 @@ function detectModelCapabilities(modelName) {
   return result;
 }
 
+// ─── Install verification ────────────────────────────────────────────────────
+//
+// IMPROVEMENT-TODO P0 (v3.7.10): post-install verification pass that catches
+// silent copy/write failures from earlier stages. The installer has many
+// `catch {}` blocks in copy paths (around copyWithPathReplacement, the codex/
+// copilot skill builders, and the agent file writers); a final manifest-level
+// sanity check is belt-and-braces. This function reads the just-written
+// manifest and verifies every recorded file actually exists.
+
+const fs_v = require('fs');
+const path_v = require('path');
+
+/**
+ * Verify installed files against the manifest.
+ *
+ * For each entry in manifest.files, check the file is present on disk at
+ * the expected location. We do NOT re-hash (the manifest was just written
+ * from these files, so re-hashing would only catch corruption-after-write
+ * which is a different concern). We DO catch the much more common case of
+ * "file silently failed to land in the first place."
+ *
+ * Also verifies critical anchor files that, if missing, mean the install is
+ * unusable: pan-tools.cjs, the dispatcher.
+ *
+ * @param {string} configDir - install root (e.g., ~/.claude or ./.codex)
+ * @param {object} manifest - the manifest object returned by writeManifest()
+ * @returns {object} { ok: bool, missing: string[], warnings: string[] }
+ */
+function verifyInstall(configDir, manifest) {
+  const missing = [];
+  const warnings = [];
+
+  // Critical anchor: pan-tools.cjs MUST exist; without it, no command works.
+  const dispatcherPath = path_v.join(configDir, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  if (!fs_v.existsSync(dispatcherPath)) {
+    missing.push('pan-wizard-core/bin/pan-tools.cjs (dispatcher — install is unusable without it)');
+  }
+
+  // Manifest-level: every tracked file must exist.
+  if (manifest && manifest.files) {
+    for (const rel of Object.keys(manifest.files)) {
+      const abs = path_v.join(configDir, rel);
+      if (!fs_v.existsSync(abs)) {
+        missing.push(rel);
+      }
+    }
+  } else {
+    warnings.push('manifest is missing or has no files entry — verification is degraded');
+  }
+
+  return { ok: missing.length === 0, missing, warnings };
+}
+
 // ─── Exports ────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -810,4 +863,6 @@ module.exports = {
   buildClaudeSkillShim,
   translateThinkingDirective,
   stripThinkingFrontmatter,
+  // Install verification (v3.7.10)
+  verifyInstall,
 };