pan-wizard 3.30.0 → 3.32.0

package/pan-wizard-core/bin/lib/verify.cjs

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, EXIT_OK, error, escapeRegex } = require('./core.cjs');
+const { safeReadFile, normalizePhaseName, comparePhaseNum, execGit, findPhaseInternal, getMilestoneInfo, toPosix, output, EXIT_OK, error, escapeRegex, loadConfig, isGitIgnored, isGitRepo } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const {
@@ -22,6 +22,7 @@ const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDrif
 const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
 const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
+const { scopePhase, cmdVerifyScope } = require('./verify-scope.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
 
 /**
@@ -821,6 +822,23 @@ function checkStateFile(cwd, addIssue, repairs) {
  * @param {Function} addIssue - Issue recording callback
  * @param {string[]} repairs - Mutable array of repair actions to schedule
  */
+/**
+ * I005: the planning tree is ignored by git while `commit_docs` is on, so every
+ * `pan-tools commit` of planning docs commits nothing, silently. planning-with-files
+ * adds `.planning/` to .gitignore by default (its README, read 2026-09-28), which is
+ * how a PAN project ends up like this (market item M3). Info, not a warning: keeping
+ * the docs out of git is a legitimate choice, and it is one config key away.
+ */
+function checkPlanningIgnored(cwd, addIssue) {
+  try {
+    if (loadConfig(cwd).commit_docs === false || !isGitRepo(cwd)) return;
+    const rel = planningRootRel();
+    if (!isGitIgnored(cwd, `${rel}/`)) return;
+    addIssue('info', 'I005', `${rel}/ is ignored by git while commit_docs is true, so PAN's planning commits commit nothing`,
+      `Remove ${rel}/ from .gitignore (planning-with-files adds it by default), or keep the docs out of git on purpose: pan-tools config-set commit_docs false`);
+  } catch { /* best effort: a git failure is not a finding */ }
+}
+
 function checkConfigFile(cwd, addIssue, repairs) {
   const configFullPath = path.join(planningPath(cwd), CONFIG_FILE);
   let rawContent;
@@ -1314,7 +1332,9 @@ function cmdValidateHealth(cwd, options, raw) {
   // error and stop: E002-E005 would describe a foreign layout as a broken PAN one,
   // and --repair must never write into it. Reality check R15.
   const foreign = detectForeignPlanningTree(planningPath(cwd));
-  if (foreign) {
+  if (foreign && foreign.coexists) {
+    addIssue('info', 'I004', `${foreign.tool} also writes into this planning tree: ${foreign.evidence.join(', ')}`, 'None needed: PAN leaves its files alone. Give PAN its own tree with --planning-dir if you prefer them apart (ADR-0043)');
+  } else if (foreign) {
     addIssue('error', 'E006', `planning tree belongs to ${foreign.tool}: ${foreign.evidence.join(', ')}`, 'Run PAN with --planning-dir <dir> to use a separate tree (ADR-0043)');
     output({ status: HEALTH_STATUS.BROKEN, errors, warnings, info, repairable_count: 0 }, raw, undefined, 1);
     return;
@@ -1337,6 +1357,7 @@ function cmdValidateHealth(cwd, options, raw) {
     addIssue('info', 'I003', `${shape.model}-model project (${shape.evidence.join(', ')}) — the phase-model checks (project.md, roadmap.md, state.md, phases/) do not apply`, null);
   }
   checkConfigFile(cwd, addIssue, repairs);
+  checkPlanningIgnored(cwd, addIssue);
   if (phaseModel) {
     checkPhaseDirectories(cwd, addIssue);
     checkPhaseContents(cwd, addIssue);
@@ -1535,6 +1556,8 @@ module.exports = {
   cmdVerifyReconcile,
   scanStubs,
   cmdVerifyStubs,
+  scopePhase,
+  cmdVerifyScope,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,

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;
     }
@@ -420,7 +422,13 @@ async function main() {
     case 'resolve-model': {
       const metadataIdx = args.indexOf('--metadata');
       const metadataJson = metadataIdx !== -1 ? args[metadataIdx + 1] : undefined;
-      commands.cmdResolveModel(cwd, args[1], raw, metadataJson);
+      const attemptRaw = getArgValue(args, '--attempt');
+      let attempt;
+      if (attemptRaw !== null && attemptRaw !== undefined) {
+        if (!/^[1-9]\d*$/.test(String(attemptRaw))) error('--attempt must be a positive integer (1 for a first try)');
+        attempt = parseInt(attemptRaw, 10);
+      }
+      commands.cmdResolveModel(cwd, args[1], raw, metadataJson, attempt);
       break;
     }
 
@@ -601,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;
     }
@@ -908,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') {
@@ -1171,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') {
@@ -1272,6 +1326,9 @@ async function main() {
           daily_budget: budget != null ? Number(budget) : undefined,
           enabled: args.includes('--disable') ? false : undefined,
           paused: args.includes('--pause') ? true : (args.includes('--resume') ? false : undefined),
+          // campaign.cjs has always honoured enforce_budget; no flag reached it, so
+          // making the daily budget a hard stop meant editing schedule.json by hand.
+          enforce_budget: args.includes('--enforce-budget') ? true : (args.includes('--advisory-budget') ? false : undefined),
         }, raw);
       } else if (subcommand === 'status' || !subcommand) {
         campaign.cmdCampaignStatus(cwd, raw);
@@ -1399,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,19 +69,31 @@ 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>`). */
 const SPAWN_TOOLS = [
   {
     name: 'pan_resolve_model', title: 'Resolve model for an agent', verb: 'resolve-model',
-    description: 'Resolve the model tier/id PAN would use for an agent under the active profile.',
+    description: 'Resolve the model tier/id PAN would use for an agent under the active profile. Pass attempt > 1 for a retry after a failure: the tier climbs toward the agent\'s quality tier (routing.max_escalations caps it).',
     readOnly: true, destructive: false,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['agent'],
-      properties: { agent: { type: 'string', description: 'Agent type, e.g. pan-planner' } },
+      properties: {
+        agent: { type: 'string', description: 'Agent type, e.g. pan-planner' },
+        attempt: { type: 'integer', minimum: 1, maximum: 99, description: '1 for a first try; 2 for the first retry after a failure' },
+      },
+    },
+    args: (i) => {
+      const out = [str('agent', i && i.agent, AGENT_RE, 64)];
+      if (i && i.attempt !== undefined) {
+        if (!Number.isInteger(i.attempt) || i.attempt < 1 || i.attempt > 99) throw new Error('Invalid "attempt": must be an integer from 1 to 99');
+        out.push('--attempt', String(i.attempt));
+      }
+      return out;
     },
-    args: (i) => [str('agent', i && i.agent, AGENT_RE, 64)],
   },
   {
     name: 'pan_find_phase', title: 'Find a phase', verb: 'find-phase',
@@ -155,7 +167,7 @@ const { NATIVE_TOOLS } = require('./native-tools.cjs');
 // safety argument of ADR-0041 is that no client input reaches it.
 const PROJECT_CWD_PROPERTY = Object.freeze({
   type: 'string',
-  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project.',
+  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project. The server acts on any existing directory named here with the permissions of the user who runs it — it trusts its caller as it trusts the session that started it.',
 });
 
 const PROJECT_CWD_MAX = 1024;

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

@@ -117,6 +117,14 @@ Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objec
 
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
 
+**If `--gaps-only`:** this run is the fix round after a verification found gaps — a second attempt at work that failed once. Resolve the executor for that attempt and use it in place of `executor_model` for every spawn in this run:
+
+```bash
+EXECUTOR_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-executor --attempt 2 --raw)
+```
+
+It equals `executor_model` unless the `budget` profile runs the executor below its quality tier; then it is one tier higher (capped by `routing.max_escalations`), so the gaps are not retried on the tier that left them.
+
 Report:
 ```
 ## Execution Plan
@@ -417,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
@@ -434,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">
@@ -531,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/help.md

@@ -224,7 +224,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 | `/pan:plan-phase <N>` | Research + plan a phase with verification |
 | `/pan:exec-phase <N>` | Execute plans with wave-based parallelization |
 | `/pan:research-phase <N>` | Deep ecosystem research for specialized domains |
-| `/pan:verify-phase <N>` | Validate built features through UAT |
+| `/pan:verify-phase <N>` | Re-run goal-backward verification with a test-suite gate |
 
 ### Phase Management
 | Command | Description |
@@ -348,7 +348,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:exec-phase <N>`** — Execute all plans in a phase. Groups by wave, runs waves sequentially, plans within each wave in parallel.
 
-**`/pan:verify-phase <N>`** — Conversational UAT. Presents tests one at a time, diagnoses failures, creates fix plans.
+**`/pan:verify-phase <N>`** — Re-run goal-backward verification behind a test-suite gate. Writes the phase's verification report (passed, gaps_found or human_needed); fix gaps with `/pan:plan-phase <N> --gaps`.
 
 **`/pan:quick <desc>`** — Small tasks with PAN guarantees but shorter path. Skips researcher, checker, verifier. Lives in `.planning/quick/`.