pan-wizard 3.31.0 → 3.33.0

package/pan-wizard-core/mcp/server.cjs

@@ -50,6 +50,15 @@ const META_SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
 // claim to speak a version we don't. Newest first (the `server/discover` order).
 const SUPPORTED_VERSIONS_LIST = [MODERN_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05'];
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(SUPPORTED_VERSIONS_LIST);
+// The `CacheableResult` fields a modern result MUST carry where its type extends
+// that interface: DiscoverResult, ListToolsResult, ListResourcesResult and
+// ReadResourceResult (schema/2026-07-28/schema.ts). Claude Code 2.1.288 drops a
+// list without them, so the server showed as connected with no tools and no
+// resources (live check H2, 2026-10-03). The registry is fixed for the life of the
+// process, so its lists are public and long-lived; a resource is the project's
+// state at the moment it is read, so a read is private and stale at once.
+const REGISTRY_CACHE = Object.freeze({ ttlMs: 3600000, cacheScope: 'public' });
+const READ_CACHE = Object.freeze({ ttlMs: 0, cacheScope: 'private' });
 /**
  * The version the server reports in `initialize` / `server/discover`. Read from the
  * package.json two levels up: the repository root in the source tree, the runtime
@@ -320,12 +329,13 @@ function createServer(opts = {}) {
         { supported: SUPPORTED_VERSIONS_LIST, requested: requestedVersion });
     }
 
-    // Modern results MUST carry a `resultType`; legacy results MUST NOT change
-    // shape (clients treat an absent resultType as "complete"). Stamp it only on
+    // Modern results MUST carry a `resultType`, a cacheable one its caching fields,
+    // and each SHOULD name the server in `_meta`; legacy results MUST NOT change
+    // shape (clients treat an absent resultType as "complete"). Stamp them only on
     // the modern path.
-    const reply = (result) => rpcResult(id,
+    const reply = (result, cache) => rpcResult(id,
       isModern && result && typeof result === 'object' && result.resultType === undefined
-        ? { resultType: 'complete', ...result }
+        ? { resultType: 'complete', ...cache, ...result, _meta: { ...result._meta, [META_SERVER_INFO_KEY]: SERVER_INFO } }
         : result);
 
     switch (method) {
@@ -339,8 +349,7 @@ function createServer(opts = {}) {
           supportedVersions: SUPPORTED_VERSIONS_LIST,
           capabilities: { tools: {}, resources: {} },
           instructions: 'PAN Wizard engine bridge: planning, verification, and orchestration tools backed by the pan-tools CLI. All tools are read-only except the gated pan_confirm_merge.',
-          ttlMs: 3600000,
-          cacheScope: 'public',
+          ...REGISTRY_CACHE,
           _meta: { [META_SERVER_INFO_KEY]: SERVER_INFO },
         });
       case 'initialize': {
@@ -354,9 +363,9 @@ function createServer(opts = {}) {
       case 'ping':
         return reply({});
       case 'tools/list':
-        return reply({ tools: reg.TOOLS.map(toMcpTool) });
+        return reply({ tools: reg.TOOLS.map(toMcpTool) }, REGISTRY_CACHE);
       case 'resources/list':
-        return reply({ resources: reg.RESOURCES.map(toMcpResource) });
+        return reply({ resources: reg.RESOURCES.map(toMcpResource) }, REGISTRY_CACHE);
       case 'tools/call': {
         const out = callTool(params && params.name, params && params.arguments);
         return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
@@ -364,7 +373,7 @@ function createServer(opts = {}) {
       case 'resources/read': {
         const out = readResource(params && params.uri);
         if (out.unknown) return rpcError(id, -32602, `Unknown resource: ${params && params.uri}`);
-        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result, READ_CACHE);
       }
       default:
         return rpcError(id, -32601, `Method not found: ${method}`);

package/pan-wizard-core/mcp/tool-registry.cjs

@@ -69,6 +69,8 @@ const RESOURCES = [
     description: 'Doc↔code link graph verdict: forward links, backlink contracts, and anchor targets, with finding codes.' },
   { uri: 'pan://cost',     name: 'Token cost',     verb: 'cost',    args: ['report'],
     description: 'Aggregated token spend from the .planning/metrics ledger. Reads as zeros on a project with no recorded calls.' },
+  { uri: 'pan://findings', name: 'Findings',       verb: 'findings', args: ['list'],
+    description: 'Every finding PAN\'s judges recorded (verifier, plan checker, reviewer, design checker), with its folded status — open, fixed, deferred, dismissed or decision — and the reason given. Reads as an empty list on a project with no recorded verdicts.' },
 ];
 
 /** Actionable pan-tools verbs → MCP tools (each spawns `node pan-tools.cjs <verb>`). */

package/pan-wizard-core/references/checkpoints.md

@@ -8,7 +8,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 2. **Claude sets up the verification environment** - Start dev servers, seed databases, configure env vars
 3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
 4. **Secrets come from user, automation comes from Claude** - Ask for API keys, then Claude uses them via CLI
-5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
+5. **Auto-mode bypasses verification checkpoints, and decisions only where the planner named a default** — When `workflow.auto_advance` is true in config: human-verify auto-approves; a decision with `auto_select="<option id>"` takes that option, and a decision without it stops for a human (auto mode never takes an option because it is listed first); human-action still stops (auth gates cannot be automated)
 </overview>
 
 <checkpoint_types>
@@ -105,7 +105,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 
 **Structure:**
 ```xml
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
   <decision>[What's being decided]</decision>
   <context>[Why this decision matters]</context>
   <options>
@@ -124,6 +124,8 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 </task>
 ```
 
+**`auto_select` (optional)** names the option auto mode takes. Set it only when the choice is safe to make without the user: reversible, no new paid service, no credential, no data-model lock-in. It must name an `id` from this checkpoint's options; `verify plan-structure` fails one that names no option. Leave it out when a human must choose, and auto mode stops at this checkpoint. The examples below omit it: picking a vendor or a database is the user's call.
+
 **Example: Auth Provider Selection**
 ```xml
 <task type="checkpoint:decision" gate="blocking">

package/pan-wizard-core/references/verdict-contract.md

@@ -0,0 +1,102 @@
+# The `pan-verdict` block
+
+A judging agent ends its report with one fenced `pan-verdict` block. The block is the machine-readable form of the verdict the report already gives in prose. The orchestrator records it with `pan-tools findings record`, and that record is what the workflow branches on. It also feeds the findings ledger that milestone audits read for tech debt. The prose stays for people, and the block states the same verdict for code.
+
+## Rules
+
+1. **Place it last.** The block is the final element of your return. When a report holds more than one block, the recorder reads the last one.
+2. **Valid JSON only.** No comments and no trailing commas. One line or pretty-printed are both fine.
+3. **Same verdict as the prose.** `verdict` is the word your report already uses, and `outcome` is what that word means (see the table below). The block never disagrees with the report.
+4. **One finding per issue.** List the findings the report lists, each as its own entry, most severe first. A clean pass has `"findings": []`.
+5. **Plain summaries.** State each finding in one sentence of 300 characters or fewer. Put the location in `where`, not in `summary`.
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-reviewer","phase":"03","verdict":"NEEDS_FIXES","outcome":"fail","findings":[{"class":"defect","severity":"high","where":"src/utils/parser.ts:42","summary":"parse() drops the final token of every line"}]}
+```
+````
+
+## Fields
+
+| Field | Required | Value |
+|---|---|---|
+| `contract` | yes | `"1.0"` |
+| `agent` | yes | your agent name, e.g. `pan-reviewer` |
+| `phase` | when you know it | the phase number you were asked about, e.g. `"03"` |
+| `verdict` | yes | your own verdict word (table below) |
+| `outcome` | yes | `pass`, `fail` or `needs_human` |
+| `findings` | yes (may be empty) | a list of `{class, severity, where, summary}` |
+| `not_checked` | when a check could not run | a list of `{check, reason}`: a check you were asked to make and could not run, and why (no test script, no browser, a file you could not read). Never fold it into `pass`: a verdict with entries here says what it did not see |
+
+| Agent | `verdict` → `outcome` |
+|---|---|
+| pan-plan-checker | `passed` → `pass` · `issues_found` → `fail` |
+| pan-reviewer | `PASS` → `pass` · `PASS_WITH_WARNINGS` → `pass` · `NEEDS_FIXES` → `fail` |
+| pan-design-checker | `PASS` → `pass` · `GAPS` → `fail` |
+
+The verifier does not emit this block. Its verification.md frontmatter (`status`, `gaps`, `human_verification`, `unrequested`, `test_gate`, `not_checked`) is its machine contract, and the recorder reads that directly. `test_gate` is `passed`, `failed` or `skipped`. A skipped gate is recorded as a `tests` entry in `not_checked` even when the list leaves it out, and a verification that does not record `test_gate` at all is recorded with a `test_gate_unrecorded` warning.
+
+## `class`: what kind of finding
+
+| Class | Use when |
+|---|---|
+| `missing` | Something required is absent: a requirement with no task, a must-have not built, an unplanned key link |
+| `partial` | Present but incomplete: a task missing its verify/done fields, a stub, a half-derived criterion |
+| `contradicts` | It conflicts with a requirement, a locked decision (context.md) or the codebase's established architecture |
+| `unrequested` | Work, a file or a behaviour that no plan or requirement asked for (scope creep) |
+| `defect` | Incorrect behaviour or a code error; a broken dependency order in a plan |
+| `risk` | A security, reliability or scale exposure; a plan whose scope will not fit its budget |
+| `quality` | Convention, naming, style or maintainability, with no correctness impact |
+| `human` | Cannot be settled by a check, so a person must look |
+
+## `severity`: how much it matters
+
+`critical` · `high` · `medium` · `low` · `info`. This is the same ladder `/pan:review-deep` uses.
+
+## Mapping for each judge
+
+**pan-plan-checker.**
+- Classes by dimension:
+  - Requirement coverage, key links, test coverage, Nyquist → `missing`
+  - Task completeness, verification derivation, spec sufficiency, decision trace → `partial`
+  - Dependency correctness → `defect`
+  - Scope sanity → `risk`
+  - Context compliance → `contradicts`
+  - Standards → `quality`
+- Severity: blocker → `high`, warning → `medium`, info → `info`.
+- `where`: `NN-MM-plan.md` or `NN-MM-plan.md#task-N`.
+
+**pan-reviewer.**
+- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, work no plan asked for → `unrequested`.
+- Severity: ERROR → `high`, WARNING → `medium`, INFO → `info`.
+- `where`: `path:line`.
+
+**pan-design-checker.**
+- Classes by dimension:
+  - Requirement coverage → `missing`
+  - Architecture conformance → `contradicts`
+  - Threat coverage → `risk`
+  - Scope discipline → `unrequested`
+  - Every other dimension → `partial`
+- Severity: each gap is `high`. A gap you report as a caveat on the final iteration is `medium`.
+- `where`: the design section, e.g. `03-design.md#interfaces`.
+
+## Examples
+
+A plan check that passes:
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-plan-checker","phase":"05","verdict":"passed","outcome":"pass","findings":[]}
+```
+````
+
+A design check with two gaps:
+
+````markdown
+```pan-verdict
+{"contract":"1.0","agent":"pan-design-checker","phase":"05","verdict":"GAPS","outcome":"fail","findings":[
+  {"class":"missing","severity":"high","where":"05-design.md#requirements","summary":"REQ-12 (export to CSV) maps to no design element"},
+  {"class":"risk","severity":"high","where":"05-design.md#threats","summary":"the upload endpoint accepts any file type and no threat entry covers it"}]}
+```
+````

package/pan-wizard-core/templates/discovery.md

@@ -30,7 +30,7 @@ Discover [topic] to inform [phase name] implementation.
 
 Purpose: [What decision/implementation this enables]
 Scope: [Boundaries]
-Output: DISCOVERY.md with recommendation
+Output: discovery.md with recommendation
 </discovery_objective>
 
 <discovery_scope>

package/pan-wizard-core/templates/phase-prompt.md

@@ -79,7 +79,8 @@ Output: [What artifacts will be created]
 <!-- For checkpoint task examples and patterns, see @~/.claude/pan-wizard-core/references/checkpoints.md -->
 <!-- Key rule: Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
 
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
+  <!-- auto_select: the option auto mode takes. Omit it when a human must choose. -->
   <decision>[What needs deciding]</decision>
   <context>[Why this decision matters]</context>
   <options>

package/pan-wizard-core/templates/verification-report.md

@@ -10,8 +10,16 @@ Template for `.planning/phases/XX-name/{phase_num}-verification.md` — phase go
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
+verified_commit: <sha> # git rev-parse HEAD before writing this file; `pan-tools verify stale` compares against it
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+test_gate: passed | failed | skipped
+not_checked: # Only for checks that could not run, with why — a skipped test gate is one
+  - check: "tests"
+    reason: "no test script in package.json"
+unrequested: # Only when the scope check (`pan-tools verify scope <phase>`) found work no plan asked for
+  - path: "src/admin/panel.tsx"
+    what: "An admin panel no plan or requirement asked for"
 ---
 
 # Phase {X}: {Name} Verification Report
@@ -89,6 +97,19 @@ None — all verifiable items checked programmatically.
 **Expected:** {What should happen}
 **Why human:** {Why can't verify programmatically}
 
+## Unrequested Work
+
+{If the scope check found none:}
+None: every change traces to a plan.
+
+{Otherwise, one row per `unrequested:` entry:}
+
+| File | What it adds | Why no plan covers it |
+|------|--------------|-----------------------|
+| src/admin/panel.tsx | An admin panel | No requirement mentions admin tooling |
+
+Unrequested work is recorded, not blocking: the status does not change because of it.
+
 ## Gaps Summary
 
 {If no gaps:}

package/pan-wizard-core/workflows/exec-phase.md

@@ -256,7 +256,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a PAN or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (summary.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
 
-   For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
+   For real failures: report which plan failed → ask "Continue?" or "Stop?". If stop, partial completion report. If continue, never run a plan that depends on a failed one; ask the engine which plans are blocked:
+   ```bash
+   BLOCKED=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase-plan-index "${PHASE_NUMBER}" --failed "${FAILED_PLAN_IDS}")
+   ```
+   `${FAILED_PLAN_IDS}` is the comma-separated ids of every plan that failed so far. `blocked` lists each unfinished plan whose `depends_on` reaches a failed plan, directly or through another blocked plan, with the failed plans behind it. Do not spawn those plans in this or any later wave. Name them in the wave report and the final summary ("Skipped 03-03 and 03-04: they depend on 03-01, which failed"), and run every other plan as planned. The same applies after "Continue with remaining waves?" in step 4.
 
 6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
@@ -275,7 +279,7 @@ AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.
 
 When executor returns a checkpoint AND `AUTO_CFG` is `"true"`:
 - **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
-- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
+- **decision** → The executor already took the plan's `auto_select` option when the task had one, so a decision that comes back has none: present it to the user (standard flow below). If a returned decision's task does carry `auto_select` in the plan file, auto-spawn the continuation agent with `{user_response}` = that option id and log `⚡ Auto-selected: [option] (auto_select)`. Never answer with an option because it is listed first.
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
 
 **Standard flow (not auto-mode, or human-action type):**
@@ -425,13 +429,21 @@ Task(
 )
 ```
 
-3. Handle review results:
+3. **Save the report.** Use the Write tool to write the reviewer's returned text, verbatim and in full (including its closing `pan-verdict` block), to `{phase_dir}/{phase_number}-review.md`. The reviewer is read-only by design, so the orchestrator saves the report. `/pan:review-deep` and the findings ledger read this file.
+
+4. **Record the verdict, then act on it.** The record is what this step branches on. It also adds the findings to the ledger (`.planning/findings.jsonl`) and logs the verdict to the trace, so no separate trace call is needed:
+```bash
+REVIEW_FILE="{phase_dir}/{phase_number}-review.md"
+REVIEW_VERDICT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --agent pan-reviewer --file "$REVIEW_FILE" --raw 2>/dev/null) \
+  || REVIEW_VERDICT=$(grep -A1 '^### Verdict' "$REVIEW_FILE" | tail -1 | tr -d ' ')
+```
+The fallback reads the word under `### Verdict` when the report carries no valid `pan-verdict` block.
 
 | Verdict | Action |
 |---------|--------|
 | `PASS` | Continue to verification |
-| `PASS_WITH_WARNINGS` | Report warnings, continue to verification |
-| `NEEDS_FIXES` | Present ERROR findings to user: "Fix before verification?" or "Continue anyway?" |
+| `PASS_WITH_WARNINGS` | Report the warnings, then record that the phase continues past them (below), and continue to verification |
+| `NEEDS_FIXES` | Present the ERROR findings to the user: "Fix before verification?" or "Continue anyway?" |
 
 ```
 ## Code Review Results
@@ -442,34 +454,60 @@ Task(
 {If errors: list top 5 with file:line}
 ```
 
-**If user chooses "Continue anyway":** Proceed to verification. Review findings are informational, not blocking.
+**Never continue past findings silently.** Whenever the phase moves on with review findings still open, record why. The reason is what a milestone audit later reports as tech debt:
+- `PASS_WITH_WARNINGS`:
+  ```bash
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-reviewer --open --as deferred --reason "accepted at review: PASS_WITH_WARNINGS"
+  ```
+- **The user chooses "Continue anyway"** at `NEEDS_FIXES`: the same command with `--reason "continued past NEEDS_FIXES at the user's choice"`, then proceed to verification.
+- **The user chooses "Fix before verification"**: apply the fixes, then run the review once more (steps 2–4). The new record closes the findings it no longer reports.
 
-4. **Circular optimization — log reviewer corrections to trace bus (W1 fix):**
+5. **No separate trace logging.** The record logs `verdict_passed` or `verdict_failed` for the reviewer on every runtime. The `reviewer_correction` and `reviewer_warnings` trace calls that used to sit here read the error count from a shell variable nothing ever set.
 
-   When verdict is `NEEDS_FIXES`, write a `reviewer_correction` event so the optimizer can see the primary quality signal:
-   ```bash
-   # Extract error count from review output (parse "Errors: N" line)
-   REVIEW_ERROR_COUNT=$(echo "$REVIEW_OUTPUT" | grep -E "^- Errors: [0-9]+" | grep -oE "[0-9]+" | head -1)
-   REVIEW_ERROR_COUNT=${REVIEW_ERROR_COUNT:-1}
-   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-     --type error --category reviewer_correction \
-     --description "Phase ${PHASE_NUMBER} reviewer: NEEDS_FIXES — ${REVIEW_ERROR_COUNT} error(s) found" \
-     --agent pan-reviewer --impact major \
-     --context "{\"phase\":\"${PHASE_NUMBER}\",\"verdict\":\"NEEDS_FIXES\",\"error_count\":${REVIEW_ERROR_COUNT}}" \
-     2>/dev/null || true
+6. **Deep review — only when `--deep-review` is in $ARGUMENTS.** The security pass and cross-check that `/pan:review-deep` runs, done inline right after the normal review. If the normal review was skipped (`--skip-review` or `--fast`), say that `--deep-review` needs the review it builds on, and continue without it.
+
+   a. Spawn the hardener. Its output path is `.planning/reviews/${PHASE_NUMBER}/hardener.md`:
+   ```
+   Task(
+     subagent_type="pan-hardener",
+     model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-hardener --raw)",
+     prompt="
+       <files_to_read>
+       - {phase_dir}/{phase_number}-review.md (the first-pass review)
+       - the phase plans: {phase_dir}/*-plan.md
+       Changed files to audit:
+       ${CHANGED_FILES_LIST}
+       </files_to_read>
+       <output_path>.planning/reviews/${PHASE_NUMBER}/hardener.md</output_path>
+       <framework_scope>OWASP Top 10 (2025) and STRIDE, across every changed file.</framework_scope>
+     "
+   )
    ```
 
-   When verdict is `PASS_WITH_WARNINGS`, log a softer signal:
-   ```bash
-   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-     --type decision --category reviewer_warnings \
-     --description "Phase ${PHASE_NUMBER} reviewer: PASS_WITH_WARNINGS — warnings present" \
-     --agent pan-reviewer --impact trivial \
-     --context "{\"phase\":\"${PHASE_NUMBER}\",\"verdict\":\"PASS_WITH_WARNINGS\"}" \
-     2>/dev/null || true
+   b. Spawn the meta-reviewer on both first-pass reports. Its output path is `.planning/reviews/${PHASE_NUMBER}/meta.md`:
    ```
+   Task(
+     subagent_type="pan-meta-reviewer",
+     model="$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-meta-reviewer --raw)",
+     prompt="
+       <files_to_read>
+       - {phase_dir}/{phase_number}-review.md
+       - .planning/reviews/${PHASE_NUMBER}/hardener.md
+       </files_to_read>
+       <output_path>.planning/reviews/${PHASE_NUMBER}/meta.md</output_path>
+     "
+   )
+   ```
+   If either agent returns its report instead of writing the output path, save the returned text there with the Write tool before the merge.
 
-   When verdict is `PASS`, no trace event needed — clean passes are the expected baseline.
+   c. Merge the three reports:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs review-deep merge "${PHASE_NUMBER}" \
+     --reviewer-file "{phase_dir}/{phase_number}-review.md" \
+     --hardener-file ".planning/reviews/${PHASE_NUMBER}/hardener.md" \
+     --meta-file ".planning/reviews/${PHASE_NUMBER}/meta.md"
+   ```
+   This writes `.planning/reviews/${PHASE_NUMBER}/deep-review.md` and prints its verdict (`ok` · `ok_with_minor` · `fix_before_merge` · `review_required` · `block`). Report the verdict and the finding count. On `review_required` or `block`, stop before verification and present the high and critical findings to the user, as with `NEEDS_FIXES`.
 </step>
 
 <step name="close_parent_artifacts">
@@ -533,41 +571,26 @@ Phase goal: {goal from roadmap.md}
 Phase requirement IDs: {phase_req_ids}
 Check must_haves against actual codebase.
 Cross-reference requirement IDs from PLAN frontmatter against requirements.md — every ID MUST be accounted for.
+Run the project's test suite as the test gate (the run_test_suite step of @~/.claude/pan-wizard-core/workflows/verify-phase.md) and record test_gate in the frontmatter.
 Create verification.md.",
   subagent_type="pan-verifier",
   model="{verifier_model}"
 )
 ```
 
-Read status:
+Record the verification and read its status:
 ```bash
-VERIF_STATUS=$(grep "^status:" "$PHASE_DIR"/*-verification.md | cut -d: -f2 | tr -d ' ')
+VERIF_FILE=$(ls "$PHASE_DIR"/*-verification.md 2>/dev/null | head -1)
+VERIF_STATUS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --file "$VERIF_FILE" --raw 2>/dev/null) \
+  || VERIF_STATUS=$(grep "^status:" "$VERIF_FILE" | cut -d: -f2 | tr -d ' ')
 ```
+`findings record` reads the verdict from the verification frontmatter (`status`, `gaps`, `human_verification`, `unrequested`) and adds its findings to the ledger. A re-verification after a fix round is the next attempt: the gaps it no longer reports are closed, and the retry is logged. Recording the same file twice is a no-op, so verify-phase recording it too is safe. The grep fallback keeps the old reading when the record cannot parse the file.
 
-**P-1806 fix (v3.7.8):** the trace event for verify-phase outcome is logged HERE (in exec-phase.md after the verifier returns) rather than only at the end of verify-phase.md. When verification runs inline (orchestrator-as-verifier in auto mode, no separate Task spawn), the trace.log block at the bottom of verify-phase.md never executes — the orchestrator just writes verification.md and continues. By logging here, the event fires regardless of the verification path taken. Surfaced by the wookie autonomous build (v3.7.5–v3.7.7): all 5 phases used inline verification, no `verification_passed` events appeared in the trace despite v3.7.5 adding the trace block to verify-phase.md.
-
-```bash
-if [ "$VERIF_STATUS" = "passed" ]; then
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type decision --category verification_passed \
-    --description "Phase ${PHASE_NUMBER} verification passed (logged from exec-phase, P-1806)" \
-    --agent pan-verifier --impact minor 2>/dev/null || true
-elif [ "$VERIF_STATUS" = "gaps_found" ]; then
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type error --category verification_gaps \
-    --description "Phase ${PHASE_NUMBER} verification found gaps" \
-    --agent pan-verifier --impact major 2>/dev/null || true
-elif [ "$VERIF_STATUS" = "human_needed" ]; then
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type decision --category verification_human_needed \
-    --description "Phase ${PHASE_NUMBER} verification awaiting human review" \
-    --agent pan-verifier --impact minor 2>/dev/null || true
-fi
-```
+**Trace logging happens in the record.** The record above logs the verification outcome (`verdict_passed`, `verdict_failed` or `verdict_needs_human`) here, after the verifier returns. That covers inline verification too, which is the reason P-1806 moved the trace call here (v3.7.8). No separate `optimize trace log` call is needed.
 
 | Status | Action |
 |--------|--------|
-| `passed` | → update_roadmap |
+| `passed` | → update_roadmap. If the verification frontmatter has `test_gate: skipped` or a `not_checked` list, say so when you report the phase: "passed — not checked: tests (no test script)". A pass never hides what it did not check |
 | `human_needed` | Present items for human testing, get approval or feedback |
 | `gaps_found` | Present gap summary, offer `/pan:plan-phase {phase} --gaps` |
 

package/pan-wizard-core/workflows/health.md

@@ -163,6 +163,9 @@ Report final status.
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
 | I002 | info | Phase in ROADMAP ahead of current phase, not planned yet | No |
 | I003 | info | Focus-model or campaign tree — the phase-model checks do not apply | No |
+| I004 | info | planning-with-files shares the tree — PAN leaves its files alone | No |
+| I005 | info | The planning tree is gitignored while commit_docs is true — planning commits commit nothing | No |
+| I006 | info | config.json holds keys PAN does not read (usually a typo); the fix names the nearest known key | No |
 | STATE_REQ_DRIFT | warning | state.md complete but REQUIREMENTS.md has unchecked boxes | Yes |
 | STATE_ROADMAP_DRIFT | warning | state.md complete but roadmap.md has unchecked plan boxes | Yes |
 | VERIFICATION_GATE_MISSING | warning | Phase has completed plans but no verification record | No |

package/pan-wizard-core/workflows/learn.md

@@ -31,10 +31,10 @@ If `--session <id>` was specified, use that session ID.
 
 Run:
 ```
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id>]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize learn [--session <id> | --sessions <n>]
 ```
 
-This produces `.planning/optimization/reports/{session}-analysis.json`.
+This produces `.planning/optimization/reports/{session}-analysis.json`. With `--sessions <n>` it pools the last n sessions into `pooled-<n>-{session}-analysis.json`: a recommendation should explain failures that recur across runs, not one run's accident.
 
 Read the output and note:
 - `summary.errors` — how many error events
@@ -42,6 +42,8 @@ Read the output and note:
 - `summary.memory_misses` — how many memory miss events
 - `summary.wasted_tokens` — tokens wasted on redundancies
 - `top_error_patterns` — most frequent error categories
+- `top_tool_error_patterns` — failed tool calls captured from the subagents' own transcripts, ranked by how many spawns hit them
+- `verdict_stats` — each judge's pass/fail counts, retries, and the retries that resolved a failure
 - `top_memory_misses` — most frequent memory miss topics
 
 ## Step 3 — Invoke pan-optimizer agent

package/pan-wizard-core/workflows/milestone-audit.md

@@ -82,6 +82,18 @@ From each verification.md, extract:
 
 If a phase is missing verification.md, flag it as "unverified phase" — this is a blocker.
 
+### 2b. Read the Recorded Findings
+
+What the judges found in this milestone, and what was decided about each finding, is on record. Read it rather than reconstructing it from prose:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings debt --milestone "{version}"
+```
+
+- **`deferred`** findings were continued past on purpose, and each carries the reason recorded at the time. They are the milestone's tech debt: put every one in `tech_debt`, with its id and reason.
+- **`open`** findings were never disposed (no fix, deferral, dismissal or decision). List them under "Undisposed findings" in the report. They are not blockers by themselves: the verification gate handles blockers. They do mean the milestone cannot be `passed`, so the status is at least `tech_debt`.
+- A dismissal or decision is settled and not debt. `findings list --milestone "{version}" --status dismissed` shows the dismissals and their reasons when the report needs them.
+
 ## 3. Spawn Integration Checker
 
 With phase context collected:
@@ -181,11 +193,11 @@ gaps:  # Critical blockers
       evidence: "{specific evidence or lack thereof}"
   integration: [...]
   flows: [...]
-tech_debt:  # Non-critical, deferred
+tech_debt:  # Non-critical, deferred — from `findings debt` (step 2b) plus anything the verifications list
   - phase: 01-auth
     items:
+      - "[f_81ab3c9d20] no password strength validation — deferred: accepted at review: PASS_WITH_WARNINGS"
       - "TODO: add rate limiting"
-      - "Warning: no password strength validation"
   - phase: 03-dashboard
     items:
       - "Deferred: mobile responsive layout"
@@ -197,7 +209,7 @@ Plus full markdown report with tables for requirements, phases, integration, tec
 **Status values:**
 - `passed` — all requirements met, no critical gaps, minimal tech debt
 - `gaps_found` — critical blockers exist
-- `tech_debt` — no blockers but accumulated deferred items need review
+- `tech_debt` — no blockers but accumulated deferred items need review, or recorded findings were never disposed
 
 ## 7. Present Results
 

package/pan-wizard-core/workflows/new-project.md

@@ -985,7 +985,7 @@ Use AskUserQuestion:
   - .planning/roadmap.md (Current roadmap to revise)
   </files_to_read>
 
-  Update the roadmap based on feedback. Edit files in place.
+  Update the roadmap based on feedback: rewrite each changed file with one Write.
   Return ROADMAP REVISED with changes made.
   </revision>
   ", subagent_type="pan-roadmapper", model="{roadmapper_model}", description="Revise roadmap")

package/pan-wizard-core/workflows/optimize.md

@@ -8,6 +8,7 @@ Manage the circular optimization loop — apply reports, check stats, control tr
 |------------|--------|
 | `apply` | Apply safe recommendations from most recent report |
 | `apply --report <file>` | Apply from a specific report |
+| `revert <apply_id>` / `revert --last` | Undo one apply exactly |
 | `list` | List all reports |
 | `stats` | Show cumulative stats |
 | `trace init` | Start a new trace session |
@@ -40,8 +41,9 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize apply [--report <path>
 
 Show the user:
 - **Applied** — each item that was written (memory entries, notes)
-- **Skipped** — items that already exist or had unknown types
+- **Skipped** — items that already exist, that an earlier apply already wrote, or that had unknown types
 - **Still needs review** — prompt/workflow suggestions in `suggestions.md`
+- **The `apply_id`**, and how to undo the apply: `/pan:optimize revert <apply_id>`
 
 If memory entries were written, tell the user:
 > Memory entries have been added to `.planning/memory/`. They will be loaded on the next agent run, reducing future memory misses for these topics.
@@ -54,6 +56,17 @@ If `.planning/optimization/suggestions.md` exists, tell the user to review it fo
 
 ---
 
+## revert
+
+```
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize revert <apply_id>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize revert --last
+```
+
+Show the user each reverted action and each refused one, with its reason. A refusal means someone edited the file after the apply, or a later apply also wrote it. Revert that later apply first; never force it. The status is `reverted`, `partial`, `refused` or `nothing_to_revert`.
+
+---
+
 ## trace init
 
 ### Step 1 — Extract description