pan-wizard 3.30.0 → 3.32.0

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/phase-tests.md

@@ -364,7 +364,7 @@ Present next steps:
 
 **Also available:**
 - `/pan:phase-tests {next_phase}` — test another phase
-- `/pan:verify-phase {phase_number}` — run UAT verification
+- `/pan:verify-phase {phase_number}` — re-run goal-backward verification
 
 ---
 ```

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

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

@@ -252,7 +252,7 @@ uat.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **Also available:**
 - `/pan:exec-phase {phase}` — execute phase plans
-- `/pan:verify-phase {phase}` — run more UAT testing
+- `/pan:verify-phase {phase}` — re-run goal-backward verification
 
 ---
 ```

package/pan-wizard-core/workflows/todo-add.md

@@ -19,7 +19,7 @@ Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos
 
 Ensure directories exist:
 ```bash
-mkdir -p .planning/todos/pending .planning/todos/done
+mkdir -p .planning/todos/pending .planning/todos/completed
 ```
 
 Note existing areas from the todos array for consistency in infer_area step.

package/pan-wizard-core/workflows/todo-check.md

@@ -105,7 +105,7 @@ Use AskUserQuestion:
 - header: "Action"
 - question: "This todo relates to Phase [N]: [name]. What would you like to do?"
 - options:
-  - "Work on it now" — move to done, start working
+  - "Work on it now" — mark it completed, start working
   - "Add to phase plan" — include when planning Phase [N]
   - "Brainstorm approach" — think through before deciding
   - "Put it back" — return to list
@@ -116,7 +116,7 @@ Use AskUserQuestion:
 - header: "Action"
 - question: "What would you like to do with this todo?"
 - options:
-  - "Work on it now" — move to done, start working
+  - "Work on it now" — mark it completed, start working
   - "Create a phase" — /pan:add-phase with this scope
   - "Brainstorm approach" — think through before deciding
   - "Put it back" — return to list
@@ -125,8 +125,9 @@ Use AskUserQuestion:
 <step name="execute_action">
 **Work on it now:**
 ```bash
-mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs todo complete "[filename]"
 ```
+This moves it to `.planning/todos/completed/` with a `completed:` date — the directory `init todos` and `/pan:progress` count.
 Update state.md todo count. Present problem/solution context. Begin work or ask how to proceed.
 
 **Add to phase plan:**
@@ -150,11 +151,11 @@ Re-run `init todos` to get updated count, then update state.md "### Pending Todo
 </step>
 
 <step name="git_commit">
-If todo was moved to done/, commit the change:
+If the todo was completed, commit the change:
 
 ```bash
 git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start work on todo - [title]" --files .planning/todos/done/[filename] .planning/state.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start work on todo - [title]" --files .planning/todos/completed/[filename] .planning/state.md
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.
@@ -172,5 +173,5 @@ Confirm: "Committed: docs: start work on todo - [title]"
 - [ ] Appropriate actions offered
 - [ ] Selected action executed
 - [ ] state.md updated if todo count changed
-- [ ] Changes committed to git (if todo moved to done/)
+- [ ] Changes committed to git (if the todo was completed)
 </success_criteria>

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

@@ -321,21 +321,11 @@ If human_needed: list items requiring human testing.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
 
-**Circular optimization — log verification outcome:**
+**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt, and it closes the gaps it no longer reports:
 ```bash
-# Map status to impact and event type
-if [ "${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 (score: ${SCORE})" \
-    --agent pan-verifier --impact minor 2>/dev/null || true
-elif [ "${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 (score: ${SCORE})" \
-    --agent pan-verifier --impact major 2>/dev/null || true
-fi
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --file "$REPORT_PATH" 2>/dev/null || true
 ```
+Recording the same report twice is a no-op, so exec-phase recording it again after this workflow returns is safe.
 </step>
 
 </process>

package/pan-zcode/README.md

@@ -50,7 +50,7 @@ before ADR-0028.
   preserves the body; plus a command → skill wrapper.
 - **M4 — bundle + install.** `bin/install-zcode.js` — assembles `agents/` + `pan-mcp.json` +
   manifest + `INSTALL-ZCODE.md` into a `--target` dir; refuses to write inside the source repo;
-  drives ZCode's own Import to finish.
+  leaves the finish to the human in ZCode's own Settings and Import, following `INSTALL-ZCODE.md`.
 - **M5 — hardening + docs.** Full test matrix + [`KNOWN-BETA-RISKS.md`](KNOWN-BETA-RISKS.md)
   (the beta-churn ledger + the M0 go/no-go questions).
 
@@ -59,11 +59,11 @@ Tests: `tests/pan-zcode-mcp.test.cjs`, `tests/pan-zcode-orchestration.test.cjs`,
 
 ## Still pending — M0 (needs a real ZCode install)
 
-Two go/no-go facts can only be settled empirically: **can a subagent call MCP tools?** and **are
+Among the go/no-go facts only a real install can settle (the M0 table in `KNOWN-BETA-RISKS.md`) are **can a subagent call MCP tools?** and **are
 local stdio MCP calls metered?** Both have folded-in fallbacks (see `KNOWN-BETA-RISKS.md`), so the
 design holds either way — but confirm them before relying on the richer paths.
 
-A third M0 checkpoint (added 2026-08): **which protocol era does the real ZCode client speak?**
+Another M0 checkpoint (added 2026-08, not yet in `KNOWN-BETA-RISKS.md`): **which protocol era does the real ZCode client speak?**
 The bridge is now dual-era (ADR-0041), so it answers both a legacy `initialize` handshake and a
 modern `server/discover` probe. Confirm on a real install which path ZCode takes and that the
 version it declares is in our supported list; if ZCode ever declares a revision newer than

package/scripts/build-agent-plugin.js

@@ -150,6 +150,8 @@ function hookCommands(rootVar) {
     contextMonitorCommand: cmd('pan-context-monitor.js'),
     costLoggerCommand: cmd('pan-cost-logger.js'),
     traceLoggerCommand: cmd('pan-trace-logger.js'),
+    stopGuardCommand: cmd('pan-stop-guard.js'),
+    stateReinjectCommand: cmd('pan-state-reinject.js'),
   };
 }
 
@@ -166,6 +168,8 @@ function emitCopilotNamespace(agentsSrc, nsDir) {
     content = lib.rewriteAgentReferenceCopy(content, TOKEN_PREFIX);
     content = lib.stripThinkingFrontmatter(content, 'copilot');
     content = lib.convertClaudeToCopilotAgent(content);
+    // The agent carries the root token, so it carries what the token means.
+    if (content.includes(TOKEN_PREFIX)) content = content.replace(/\s*$/, '\n\n' + lib.agentPluginSkillAdapterNote('agent') + '\n');
     fs.writeFileSync(path.join(agentsDest, f.replace(/\.md$/, '.agent.md')), content);
     agents++;
   }

package/scripts/build-hooks.js

@@ -22,7 +22,8 @@ const HOOKS_TO_COPY = [
   'pan-statusline.js',
   'pan-cost-logger.js',
   'pan-trace-logger.js',
-  'pan-stop-guard.js'
+  'pan-stop-guard.js',
+  'pan-state-reinject.js'
 ];
 
 function build() {

package/scripts/build-plugin.js

@@ -169,6 +169,15 @@ function main() {
     );
   }
 
+  // 7. Eval suite (market-ideas M4). `claude plugin eval` reads `evals/` at the
+  // plugin root; the cases live in harness/plugin-evals/ beside the harness
+  // scenarios they come from. harness/ is not in the npm package, so a build from
+  // an installed copy has no suite to copy and the plugin ships without one.
+  const evalsSrc = path.join(ROOT, 'harness', 'plugin-evals');
+  if (fs.existsSync(evalsSrc)) {
+    fs.cpSync(evalsSrc, path.join(OUT, 'evals'), { recursive: true });
+  }
+
   // Sanity report
   const count = (p) => { try { return fs.readdirSync(p).length; } catch { return 0; } };
   console.log('PAN plugin built at', path.relative(ROOT, OUT));
@@ -176,6 +185,7 @@ function main() {
   console.log('  agents:', count(path.join(OUT, 'agents')));
   console.log('  hooks:', count(path.join(OUT, 'hooks')));
   console.log('  workflows:', workflowScripts.length);
+  console.log('  eval cases:', count(path.join(OUT, 'evals')) ? fs.readdirSync(path.join(OUT, 'evals'), { withFileTypes: true }).filter(e => e.isDirectory()).length : 0);
   console.log('  version:', pkg.version);
 }
 

package/scripts/git-hooks/pre-commit

@@ -10,7 +10,8 @@
 # Or with a symlink (Unix / Git Bash):
 #   ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit
 #
-# Bypass for an emergency (creates a paper trail in the commit log):
+# Bypass for an emergency (the hook only prints that the scan was skipped;
+# nothing is recorded in the commit):
 #   SKIP_GITLEAKS=1 git commit -m "..."
 #
 # Exit codes:

package/scripts/npm-dist-tag.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Print the npm dist-tag a version publishes under: `next` for a prerelease
+ * (`3.31.0-rc.1`), `latest` otherwise.
+ *
+ * WHY. The release workflow ran `npm publish` with no `--tag`, and npm's default
+ * tag is `latest` — so a release candidate would have become what
+ * `npm install pan-wizard` resolves to for every user (market-ideas queue M1,
+ * 2026-09-21). Publishing a candidate under `next` keeps it installable by name
+ * (`pan-wizard@next`, `pan-wizard@3.31.0-rc.1`) without moving anyone onto it.
+ *
+ * A version that is not `major.minor.patch[-prerelease]` exits 1 rather than
+ * guessing a tag: publishing junk under `latest` is the failure this prevents.
+ *
+ * Usage:
+ *   node scripts/npm-dist-tag.js            # the tag for package.json's version
+ *   node scripts/npm-dist-tag.js 3.31.0-rc.1
+ */
+
+'use strict';
+
+const path = require('path');
+const { parse } = require('./deprecate-old-versions.js');
+
+/**
+ * @param {string} version
+ * @returns {'latest'|'next'|null} null when the version does not parse
+ */
+function distTagFor(version) {
+  const v = parse(version);
+  if (!v) return null;
+  return v.pre === null ? 'latest' : 'next';
+}
+
+function main() {
+  const version = process.argv[2] || require(path.join(__dirname, '..', 'package.json')).version;
+  const tag = distTagFor(version);
+  if (!tag) {
+    process.stderr.write(`npm-dist-tag: '${version}' is not a semver version — refusing to pick a tag\n`);
+    process.exit(1);
+  }
+  process.stdout.write(tag + '\n');
+}
+
+module.exports = { distTagFor };
+
+if (require.main === module) main();

package/scripts/plugin-path.js

@@ -49,8 +49,13 @@ function fail(message) {
 function build() {
   try {
     // Relay the builder's stdout to stderr so stdout stays single-line.
+    // PAN_PLUGIN_OUT redirects the builder; this script prints PLUGIN_DIR, so a value
+    // inherited from the caller's environment would build one place and point the
+    // marketplace at another (3.28.0 review, LOW). Build where the path says.
+    const env = { ...process.env };
+    delete env.PAN_PLUGIN_OUT;
     const out = execFileSync(process.execPath, [path.join(ROOT, 'scripts', 'build-plugin.js')], {
-      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env,
     });
     if (out) process.stderr.write(out);
   } catch (err) {

package/scripts/test-surface.cjs

@@ -68,6 +68,7 @@ const EVENT_HOOKS = Object.freeze({
   postToolUse: ['pan-context-monitor.js'],
   subagentStop: ['pan-cost-logger.js', 'pan-trace-logger.js'],
   stop: ['pan-stop-guard.js'],
+  compact: ['pan-state-reinject.js'],
 });
 
 // ─── Parsers (pure) ─────────────────────────────────────────────────────────