pan-wizard 3.31.0 → 3.32.0

package/pan-wizard-core/bin/pan-tools.cjs

@@ -28,6 +28,7 @@
  *   history-digest                     Aggregate all summary.md data
  *   summary-extract <path> [--fields]  Extract structured data from summary.md
  *   state-snapshot                     Structured parse of state.md (alias: state snapshot)
+ *   findings record|list|dispose|debt  Judges' verdicts and their findings ledger (evidence loop)
  *   phase-plan-index <phase>           Index plans with waves and status
  *   websearch <query>                  Search web via Brave API (if configured)
  *     [--limit N] [--freshness day|week|month]
@@ -206,6 +207,7 @@ const cost = require('./lib/cost.cjs');
 const costRebuild = require('./lib/cost-rebuild.cjs');
 const preview = require('./lib/preview.cjs');
 const reviewDeep = require('./lib/review-deep.cjs');
+const findings = require('./lib/findings.cjs');
 const knowledge = require('./lib/knowledge.cjs');
 const skillAlign = require('./lib/skill-align.cjs');
 const hygiene = require('./lib/hygiene.cjs');
@@ -331,7 +333,7 @@ async function main() {
     + '  --planning-dir <path>  act on an arbitrary project-relative planning tree\n'
     + '  --all-tracks           (hygiene) act on the root tree AND every discovered track\n'
     + '  env: PAN_TRACK, PAN_PLANNING_DIR (flags win)\n'
-    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
+    + '\nCommands: state, resolve-model, estimate-cost, find-phase, git, distill, experiment, commit, verify-summary, template, frontmatter, verify, generate-slug, current-timestamp, list-todos, verify-path-exists, config-ensure-section, config-set, config-get, history-digest, phases, roadmap, requirements, phase, milestone, validate, progress, context-budget, todo, scaffold, init, phase-plan-index, state-snapshot, summary-extract, rollback-snapshot, batch-commit, websearch, focus, preflight, dashboard, hud, report, learnings, deps, drift-check, memory, bridge, whatif, knowledge, skills, hygiene, review-deep, findings, preview, cost, models, squad, worktree, campaign, bus, cache, retro, codebase, standards, optimize, doc-lint, learn, links';
 
   if (!command) {
     error(USAGE);
@@ -412,7 +414,7 @@ async function main() {
       } else if (subcommand === 'load' || !subcommand) {
         state.cmdStateLoad(cwd, raw);
       } else {
-        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
+        error(`Unknown state subcommand: ${subcommand}. Available: json, update, get, patch, compact, advance-plan, record-metric, update-progress, add-decision, add-blocker, resolve-blocker, record-session, load, snapshot`);
       }
       break;
     }
@@ -607,8 +609,10 @@ async function main() {
         verify.cmdVerifyReconcile(cwd, args[2], raw);
       } else if (subcommand === 'stubs') {
         verify.cmdVerifyStubs(cwd, { gate: args.includes('--gate') }, raw);
+      } else if (subcommand === 'scope') {
+        verify.cmdVerifyScope(cwd, args[2], raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope');
       }
       break;
     }
@@ -914,7 +918,13 @@ async function main() {
             output({ error: 'No batch file found. Run focus plan first.' }, raw);
             break;
           }
-          items = batch.batch || [];
+          if (batch.error) {
+            // The newest batch is the one /pan:focus-exec runs; classifying another would
+            // hand it waves for the wrong items, so an unusable newest batch is an error.
+            output({ error: batch.error }, raw);
+            break;
+          }
+          items = batch.batch;
         }
         output(focus.classifyStageDependencies(items), raw);
       } else if (subcommand === 'reflection') {
@@ -1177,6 +1187,44 @@ async function main() {
       break;
     }
 
+    case 'findings': {
+      // Evidence loop (ADR-0049): judges' verdicts recorded from their reports, and
+      // the dispositions workflows give the findings they continue past.
+      const subcommand = args[1];
+      const filters = {
+        phase: getArgValue(args, '--phase'),
+        agent: getArgValue(args, '--agent'),
+        status: getArgValue(args, '--status'),
+        class: getArgValue(args, '--class'),
+        milestone: getArgValue(args, '--milestone'),
+      };
+      if (subcommand === 'record') {
+        findings.cmdFindingsRecord(cwd, {
+          phase: filters.phase,
+          agent: filters.agent,
+          file: getArgValue(args, '--file'),
+          text: getArgValue(args, '--text'),
+          stdin: args.includes('--stdin'),
+        }, raw);
+      } else if (subcommand === 'list') {
+        findings.cmdFindingsList(cwd, filters, raw);
+      } else if (subcommand === 'dispose') {
+        findings.cmdFindingsDispose(cwd, {
+          ids: findings.findingIdsIn(args.slice(2)),
+          phase: filters.phase,
+          agent: filters.agent,
+          open: args.includes('--open'),
+          as: getArgValue(args, '--as'),
+          reason: getArgValue(args, '--reason'),
+        }, raw);
+      } else if (subcommand === 'debt') {
+        findings.cmdFindingsDebt(cwd, { milestone: filters.milestone }, raw);
+      } else {
+        error('Unknown findings subcommand. Available: record, list, dispose, debt');
+      }
+      break;
+    }
+
     case 'preview': {
       const subcommand = args[1];
       if (subcommand === 'phase') {
@@ -1408,17 +1456,23 @@ async function main() {
       } else if (subcommand === 'learn') {
         optimize.cmdOptimizeLearn(cwd, {
           sessionId: getArgValue(args, '--session'),
+          sessions: getArgValue(args, '--sessions'),
         }, raw);
       } else if (subcommand === 'apply') {
         optimize.cmdOptimizeApply(cwd, {
           reportPath: getArgValue(args, '--report'),
         }, raw);
+      } else if (subcommand === 'revert') {
+        optimize.cmdOptimizeRevert(cwd, {
+          applyId: args[2] && !args[2].startsWith('--') ? args[2] : null,
+          last: args.includes('--last'),
+        }, raw);
       } else if (subcommand === 'list') {
         optimize.cmdOptimizeList(cwd, raw);
       } else if (subcommand === 'stats') {
         optimize.cmdOptimizeStats(cwd, raw);
       } else {
-        error('Unknown optimize subcommand. Available: trace, learn, apply, list, stats');
+        error('Unknown optimize subcommand. Available: trace, learn, apply, revert, list, stats');
       }
       break;
     }

package/pan-wizard-core/learnings/README.md

@@ -4,7 +4,7 @@ This directory holds AI-derived behavioral patterns extracted from real PAN
 Wizard sessions via the **self-improvement loop** (v3.7.0+, see
 [ADR-0026](../../docs/decisions/ADR-0026-self-improvement-loop.md)).
 
-Patterns are produced by running `pan-tools learn promote --pattern <id>` over
+Patterns are promoted by hand with `pan-tools learn promote` (see Lifecycle) from
 harvested experiment data. They are **advisory** — orchestrators weight them
 against current context, not as hard rules.
 
@@ -46,9 +46,10 @@ patterns:
 
 ## Lifecycle
 
-1. **Promote** — `pan-tools learn promote --pattern <id> --scope universal --topic <name>` appends a pattern to the topic file (creates the file if absent).
-2. **Unpromote** — `pan-tools learn unpromote --pattern <id> --topic <name>` removes a pattern (for rollback).
+1. **Promote** — `pan-tools learn promote --pattern <id> --scope universal --topic <name> --summary <text> --rule <text>` appends a pattern to the topic file (creates the file if absent); `--evidence`, `--applies-in` and `--source-experiments` fill in the rest of the entry.
+2. **Unpromote** — `pan-tools learn unpromote --pattern <id> --scope <universal|internal> --topic <name>` removes a pattern (for rollback) and deletes the topic file once it holds none.
 3. **List** — `pan-tools learn list-promoted` shows the inventory across both tiers.
+4. **Index** — `pan-tools learn build-index` regenerates `index.json`, the topic index `pan-tools learn topics-for --agent <name>` reads; promote and unpromote do not update it.
 
 ## Why two tiers
 
@@ -58,13 +59,15 @@ apply when the project *is* PAN. Examples:
 - **PAN-internal**: "Always commit individually, never `git add -A`" (because of source repo's pre-commit hooks)
 - **Universal**: "Run the full test suite before marking a phase complete"
 
-The promote step uses a heuristic filter on file paths in the pattern's
-evidence. References to `pan-wizard-core/`, `bin/install.js`, `commands/pan/*`
-suggest `internal` scope. The human running `promote` makes the final call.
+The promote step warns when a universal-scope pattern reads like a prompt
+fragment rather than a structural pattern (P-RES-007), and `pan-tools learn lint`
+warns when a universal pattern's heading or Rule names PAN-internal terms such as
+`pan-wizard-core` or `pan-tools`, a candidate for `internal` scope. The human
+running `promote` makes the final call.
 
 ## Maintenance
 
 These files are **AI-managed**. Direct human edits create drift between
-the frontmatter `pattern_ids` list and the body content. For human-authored
+the frontmatter `patterns` list and the body content. For human-authored
 behavioral content, use `references/` instead — that's the canonical
 hand-authored channel (e.g., `references/guardrails.md` shipped in v3.6.0).

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/verdict-contract.md

@@ -0,0 +1,101 @@
+# 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}` |
+
+| 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`) is its machine contract, and the recorder reads that directly.
+
+## `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/verification-report.md

@@ -12,6 +12,9 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+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 +92,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

@@ -425,13 +425,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 +450,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">
@@ -539,31 +573,15 @@ Create verification.md.",
 )
 ```
 
-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 |
 |--------|--------|

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

@@ -163,6 +163,8 @@ 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 |
 | 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/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

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

@@ -222,7 +222,7 @@ In that case, log a `decision` trace event (`type: "decision", category: "skip-r
 
 This is a workflow-level optimization — the planner still produces a plan, just without per-phase research.md. Phase 2+ phases with substantive build work still go through full research.
 
-**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${PHASE_NUM}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces 4-file phase output (context, research, plan, summary) to a 2-file output (record, plan) for trivial phases. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (>1 plan or non-trivial change_class) still produce full per-phase artifacts regardless of this flag.
+**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${PHASE_NUM}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces the planning output (context, research, plan) to a record and a plan for trivial phases; execution still writes the plan's summary. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (>1 plan or non-trivial change_class) still produce full per-phase artifacts regardless of this flag.
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
@@ -448,20 +448,20 @@ Task(
 
 ## 11. Handle Checker Return
 
-- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
-  ```bash
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type decision --category plan_verified \
-    --description "Plan-checker passed for phase ${PHASE_NUMBER}" \
-    --agent pan-plan-checker --impact trivial 2>/dev/null || true
-  ```
-- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
-  ```bash
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type error --category plan_checker_issues \
-    --description "Plan-checker found issues in phase ${PHASE_NUMBER} plans" \
-    --agent pan-plan-checker --impact minor 2>/dev/null || true
-  ```
+Save the checker's returned text, verbatim and in full (including its closing `pan-verdict` block), to `{phase_dir}/{padded_phase}-plan-check.md` with the Write tool. Then record it, and branch on the record. The record also adds the issues to the findings ledger and logs the check to the trace; there is no separate trace call:
+
+```bash
+CHECK_FILE="{phase_dir}/{padded_phase}-plan-check.md"
+CHECK_VERDICT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --agent pan-plan-checker --file "$CHECK_FILE" --raw 2>/dev/null) \
+  || CHECK_VERDICT=$(grep -q '^## VERIFICATION PASSED' "$CHECK_FILE" && echo passed || echo issues_found)
+```
+
+The fallback reads the heading when the report carries no valid `pan-verdict` block.
+
+- **`passed`:** Display confirmation, proceed to step 13.
+- **`issues_found`:** Display issues, check iteration count, proceed to step 12.
+
+Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The issues a revision resolved are closed by that record.
 
 ## 12. Revision Loop (Max 3 Iterations)
 
@@ -510,6 +510,11 @@ Display: `Max iterations reached. {N} issues remain:` + issue list
 
 Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
+**On "Force proceed":** record that planning continues past the remaining issues. Execution and the milestone audit will see them as deferred, with this reason:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-plan-checker --open --as deferred --reason "force proceed after 3 plan revision iterations"
+```
+
 ## 13. Present Final Status
 
 **Sync state.md first** — without this, state.md says "Ready to plan" until the