pan-wizard 3.21.1 → 3.24.0

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

@@ -27,13 +27,13 @@
  *   config-get <key>                   Get a config.json value
  *   history-digest                     Aggregate all summary.md data
  *   summary-extract <path> [--fields]  Extract structured data from summary.md
- *   state-snapshot                     Structured parse of state.md
+ *   state-snapshot                     Structured parse of state.md (alias: state snapshot)
  *   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]
  *
  * Phase Listing:
- *   phases list [--type plan|summary]  List phases with optional type filter
+ *   phases list [--type plans|summaries]  List phases with optional type filter
  *     [--phase N] [--include-archived]
  *
  * Phase Operations:
@@ -282,8 +282,20 @@ async function main() {
 
   const command = args[0];
 
+  const USAGE = 'Usage: pan-tools <command> [args] [--raw] [--cwd <path>]\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';
+
   if (!command) {
-    error('Usage: pan-tools <command> [args] [--raw] [--cwd <path>]\nCommands: state, state-snapshot, resolve-model, find-phase, commit, verify-summary, verify, frontmatter, template, 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, summary-extract, rollback-snapshot, websearch, focus, preflight, dashboard, learnings, deps, standards');
+    error(USAGE);
+  }
+
+  // P-1814 (PanLoop finding 11): `--help` was the single most frequent failed
+  // probe in field transcripts — 26 sightings across 10 command docs. It is
+  // the most predictable thing any agent or human tries, so it works: print
+  // the usage and exit 0. A missing command stays exit 1 (the error contract);
+  // an explicit request for help is a success.
+  if (command === '--help' || command === '-h' || command === 'help') {
+    console.log(USAGE);
+    process.exit(0);
   }
 
   switch (command) {
@@ -337,10 +349,16 @@ async function main() {
           stopped_at: getArgValue(args, '--stopped-at'),
           resume_file: getArgValue(args, '--resume-file', 'None'),
         }, raw);
+      } else if (subcommand === 'snapshot') {
+        // Alias for the top-level `state-snapshot` (P-1813). The hyphenated
+        // command reads exactly like a `state` subcommand, and a field agent
+        // guessed the spaced form by analogy (PanLoop finding 10). The guess
+        // is semantically right, so it lands on the real handler.
+        state.cmdStateSnapshot(cwd, raw);
       } 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`);
+        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`);
       }
       break;
     }
@@ -530,7 +548,7 @@ async function main() {
       } else if (subcommand === 'stubs') {
         verify.cmdVerifyStubs(cwd, { gate: args.includes('--gate') }, raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs');
       }
       break;
     }
@@ -786,8 +804,12 @@ async function main() {
 
     case 'batch-commit': {
       const itemsJson = args[1];
-      let items = [];
-      try { items = JSON.parse(itemsJson); } catch { /* empty */ }
+      // Report a malformed payload rather than silently reporting 'no_items':
+      // a caller whose JSON was garbled (e.g. shell-stripped quotes) must not be
+      // told there was nothing to commit. Absent arg → genuine empty batch.
+      const items = itemsJson === undefined || itemsJson === ''
+        ? []
+        : parseJsonOrError(itemsJson, 'batch-commit');
       commands.cmdBatchCommit(cwd, items, raw);
       break;
     }
@@ -1295,6 +1317,7 @@ async function main() {
       const subcommand = args[1];
       if (subcommand === 'trace') {
         const traceSub = args[2];
+        const tokensWasted = getArgValue(args, '--tokens-wasted');
         optimize.cmdOptimizeTrace(cwd, traceSub, {
           sessionId: getArgValue(args, '--session'),
           all: args.includes('--all'),
@@ -1306,9 +1329,8 @@ async function main() {
           type: getArgValue(args, '--type'),
           category: getArgValue(args, '--category'),
           impact: getArgValue(args, '--impact'),
-          description: getArgValue(args, '--description'),
           correction: getArgValue(args, '--correction'),
-          tokens_wasted: getArgValue(args, '--tokens-wasted') ? Number(getArgValue(args, '--tokens-wasted')) : null,
+          tokens_wasted: tokensWasted ? Number(tokensWasted) : null,
           context: (() => { const v = getArgValue(args, '--context'); if (!v) return null; try { return JSON.parse(v); } catch { return null; } })(),
         }, raw);
       } else if (subcommand === 'learn') {
@@ -1382,7 +1404,7 @@ async function main() {
         const sourceExperiments = sourceExpsCsv
           ? sourceExpsCsv.split(',').map(s => s.trim()).filter(Boolean)
           : [];
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
 
         const result = optimize.promotePattern(
           { id: patternId, summary, evidence, rule, applies_in: appliesIn, source_experiments: sourceExperiments },
@@ -1396,7 +1418,7 @@ async function main() {
         const patternId = getArgValue(args, '--pattern');
         const scope = getArgValue(args, '--scope');
         const topic = getArgValue(args, '--topic');
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         if (!patternId || !scope || !topic) {
           error('learn unpromote requires --pattern <id> --scope <s> --topic <t>');
         }
@@ -1406,14 +1428,14 @@ async function main() {
       }
 
       if (subcommand === 'list-promoted') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const result = optimize.listPromotedPatterns({ sourceRoot });
         output(result, raw);
         break;
       }
 
       if (subcommand === 'build-index') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const result = learnIndex.cmdBuildIndex(sourceRoot);
         if (raw) {
           output(result, true,
@@ -1428,7 +1450,7 @@ async function main() {
       }
 
       if (subcommand === 'topics-for') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const agent = getArgValue(args, '--agent');
         if (!agent) { error('learn topics-for requires --agent <name>'); }
         const minRelevance = getArgValue(args, '--min-relevance', 'medium');
@@ -1451,7 +1473,7 @@ async function main() {
       }
 
       if (subcommand === 'lint') {
-        const sourceRoot = getArgValue(args, '--source-root') || cwd;
+        const sourceRoot = getArgValue(args, '--source-root') || learnLint.resolveLearningsRoot();
         const scope = getArgValue(args, '--scope');
         const strict = args.includes('--strict');
         const result = learnLint.cmdLearnLint(sourceRoot, { scope, strict });
@@ -1466,11 +1488,12 @@ async function main() {
           for (const v of result.violations) {
             lines.push(`[${v.severity.toUpperCase()}] ${v.code} ${v.pattern_id}: ${v.message}`);
           }
-          output(result, true, lines.join('\n'));
+          output(result, true, lines.join('\n'), result.summary.status === 'fail' ? 1 : 0);
         } else {
-          output(result, false);
+          output(result, false, undefined, result.summary.status === 'fail' ? 1 : 0);
         }
-        if (result.summary.status === 'fail') process.exit(1);
+        // exit code carried through output() above (it used to hard-exit 0
+        // before this check, so `learn lint` never gated — M32, ADR audit 2026-08).
         break;
       }
 
@@ -1504,7 +1527,7 @@ async function main() {
     }
 
     default:
-      error(`Unknown command: ${command}. Run pan-tools without arguments to see available commands.`);
+      error(`Unknown command: ${command}. Run pan-tools --help to see available commands.`);
   }
 }
 

package/pan-wizard-core/learnings/index.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "generated_at": "2026-07-09T15:40:55.203Z",
+  "generated_at": "2026-08-07T13:36:47.532Z",
   "topics": [
     {
       "name": "experiment-runner",
@@ -152,8 +152,8 @@
         "P-350",
         "P-360"
       ],
-      "size_bytes": 10667,
-      "size_tokens_est": 2667,
+      "size_bytes": 11837,
+      "size_tokens_est": 2960,
       "agent_relevance": {
         "planner": "low",
         "executor": "medium",
@@ -218,8 +218,8 @@
         "P-1204",
         "P-NPRS-003"
       ],
-      "size_bytes": 3400,
-      "size_tokens_est": 850,
+      "size_bytes": 3402,
+      "size_tokens_est": 851,
       "agent_relevance": {
         "planner": "medium",
         "executor": "high",
@@ -804,7 +804,7 @@
   "totals": {
     "topics": 47,
     "patterns": 93,
-    "size_bytes": 148954,
-    "size_tokens_est": 37255
+    "size_bytes": 150126,
+    "size_tokens_est": 37549
   }
 }

package/pan-wizard-core/learnings/universal/autonomous-loop.md

@@ -37,12 +37,14 @@ patterns:
 
 ## P-330 — Scale agents into a coordinated army with squads, worktree isolation, and a human-gated ship
 
-**Evidence:** The bot-army model (ADR-0032/0033) showed the durable shape for running a whole-project goal across many agents: a delegation-only coordinator (never codes) fans work to role-scoped *squads* (architecture/build/quality/release), the build squad parallelizes by giving each agent its own branch + git worktree (so concurrent builders never touch the same file), quality is adversarial and read-only, and the path to a protected branch is a human-approved gate, not a bot merge.
+**Evidence:** The bot-army model (ADR-0032/0033) showed the durable shape for running a whole-project goal across many agents: a coordinator that routes rather than implements fans work to role-scoped *squads* (architecture/build/quality/release), the build squad parallelizes by giving each agent its own branch + git worktree (which is why concurrent builders cannot land in the same working file), quality is adversarial and reads more than it writes, and the path to a protected branch is a human-approved gate, not a bot merge.
+
+**Where the enforcement actually lives, and where it does not.** Worktree isolation is real isolation — separate directories, separate branches, enforced by git. The *role* labels are not: a coordinator that can spawn agents generally also holds file and shell tools, and a squad's `read-only` label is a contract its prompt is told to honour rather than a sandbox the runtime imposes. Both were written as absolutes here ("delegation-only", "never codes") and both were wrong; the guidance below survived the correction unchanged, because instructing the split is still right — claiming it is enforced is what was not.
 
 **Rule:** When scaling beyond a single agent:
 
-1. **Coordinator delegates, never codes** — its tools are delegation-only; it plans, decomposes, and routes to squads, then aggregates tight summaries.
-2. **Group agents into role-scoped squads with least-privilege tools** — design read-only, build read/write, quality read-only/adversarial, release always-ask. Resolve the roster from data, not hardcoded prompt lists.
+1. **Instruct the coordinator to delegate rather than implement** — it plans, decomposes, and routes to squads, then aggregates tight summaries. Treat that as prompt discipline and verify the grant instead of assuming it: read the coordinator's own `tools:` frontmatter, and if it holds write or shell tools, the split is instructed, not enforced. Say which of the two your prompt is relying on wherever you describe the design to a user.
+2. **Group agents into role-scoped squads with a declared least-privilege contract** — design read-only, build read/write, quality read-only/adversarial, release always-ask. Resolve the roster from data, not hardcoded prompt lists. A label is a contract until a per-agent grant matches it; a registry that maps agents to role labels changes no execution path on its own, so publish those labels as advisory rather than as guarantees.
 3. **Parallelize by isolation, not by hope** — one branch + worktree per concurrent builder; never two agents in one tree. Serialize builds only where the build tree corrupts under concurrency (a per-project opt-in).
 4. **The mutating boundary is human-gated** — merging to a protected branch is `always-ask`; recovery is revert / previous tag, never force-push or history rewrite.
 5. **The harness scales with the army, not after it** — depth caps, spawn/budget ceilings, and an abort kill-switch checked before every spawn are mandatory; a longer loop must not relax a single cap. Power and safety are the same investment.

package/pan-wizard-core/learnings/universal/concurrency.md

@@ -18,7 +18,7 @@ patterns:
 
 ## P-1204 — O_EXCL lockfile + retry with bounded backoff is enough for multi-process file writes in Node — no flock needed
 
-**Evidence:** whoocache lock.js + atomic-write.js: parallel-process tests with two child processes each calling set() 1000 times completed with consistent index, zero lost writes. P-1402 (whoocache 02-02 summary): 'O_EXCL lockfile + Windows rename retry' shipped Phase 2.
+**Evidence:** whoocache lock.js + atomic-write.js: parallel-process tests with two child processes each calling set() 1000 times completed with consistent index, zero lost writes. The whoocache 02-02 summary records 'O_EXCL lockfile + Windows rename retry' shipped Phase 2.
 
 **Rule:** For multi-process safe writes (parallel CLI invocations sharing one cache/index/state file), use fs.openSync(lockPath, 'wx') as a 'try-acquire' (EEXIST means held). On failure, retry with random backoff 5-50ms, capped at ~10 attempts. Always wrap acquired work in try/finally and unlink the lockfile in finally. Cross-platform safe (no flock dependency). Combine with the atomic write-tmp-then-rename pattern (P-1201) so even if the lock holder is killed mid-write, recovery is automatic.
 

package/pan-wizard-core/references/design-methodology.md

@@ -0,0 +1,94 @@
+# Design Methodology (shared)
+
+Single source of truth for how PAN designs a change **before** it is planned or
+executed. Cited by `pan-designer` (main flow, via `/pan:design-phase`) and by
+`focus-design` (the `/featureAI` feature pipeline). Both flows use the *same*
+method at different **depth tiers** so design quality can't drift between them.
+
+This reference defines: the depth tiers, what each tier must produce, and the
+quality bar every design artifact is held to (the same bar `pan-design-checker`
+verifies against). It does not prescribe a runtime — agents apply it with
+whatever tools they have.
+
+---
+
+## Depth tiers
+
+A tier selects which sections of the design artifact (`templates/design.md`) are
+**mandatory**. Deeper tiers are supersets of shallower ones. Pick the shallowest
+tier that fits the altitude of the work.
+
+| Tier | Altitude | Mandatory sections | Skips | Typical entry point |
+|------|----------|--------------------|-------|---------------------|
+| `spike` | Throwaway PoC / trivial change | Problem · Scope · Minimal architecture | Everything else — flag as speculative | `/pan:design-phase --spike`, `focus-design --spike` |
+| `phase` | One roadmap phase | Problem · Success criteria (≥2 machine-checkable) · Architecture assessment · Design synthesis · Phase-scoped ADR · Threat-lite · Test hooks | Demand validation, competitive intel, market/strategy | **`/pan:design-phase` (main-flow default)** |
+| `feature` | A whole feature (internal) | `phase` + Demand validation · Error-handling design · Full STRIDE-lite threat model · Test plan · Feature ladder | Competitive intel, strategic (Blue Ocean/Wardley) | `focus-design --internal` |
+| `full` | A market-facing feature | `feature` + Competitive intelligence · Strategic analysis (ERRC) · Adoption analysis | — (nothing) | `focus-design --full` (DEFAULT) |
+
+**Altitude rule (why the tiers exist):** product/strategic design — *whether*
+and *what* to build, with demand and competitive evidence — is decided **once**
+at feature/milestone creation (`focus-design`, or the product-design pass in
+`milestone-new`). Per-phase design (`phase` tier) covers only *how* to build an
+already-scoped phase: architecture, ADR, threat, synthesis. This keeps the
+frequently-run per-phase path cheap and stops the main flow re-litigating product
+questions on every phase.
+
+---
+
+## What every tier produces
+
+The artifact is `{scope}-design.md` from `templates/design.md`. Sections below are
+ordered; a tier makes a contiguous prefix (plus its named additions) mandatory.
+
+### 1. Problem & scope (all tiers)
+- **Problem statement** — what problem exists, why it matters, cost of inaction. Concrete, not a vague generality.
+- **Scope** — in-scope / out-of-scope, and the fixed boundary this design must not exceed (a phase boundary from `roadmap.md`, or a feature boundary).
+
+### 2. Success criteria (`phase`+)
+- 3–7 criteria, **at least 2 machine-checkable** (verifiable by an automated test, not manual inspection). State the check for each machine-checkable one.
+
+### 3. Architecture assessment & synthesis (`phase`+)
+- **Conventions** — extract the project's actual conventions (module layout, error style, boundaries) from the codebase; do not assume.
+- **Components & boundaries** — what modules are added/touched; confirm the design honors the discovered boundaries (no layer violations).
+- **Interface contract** — exact invocation + input/output schema + status/exit codes, per project convention.
+- **State & filesystem scope** — reads from / writes to (must stay within project root / `.planning/`), state mutations, side effects.
+- **Design decisions** — each significant decision: what was decided, why, alternatives rejected.
+
+### 4. ADR (`phase`+)
+- A right-sized Architecture Decision Record: Status · Date · Context (problem, forces, current state, requirements traceability) · Decision (summary + numbered sub-decisions with rationale + integration) · Consequences (positive **and** negative, every negative with a mitigation or explicit acceptance).
+- `phase` tier: phase-scoped ADR (may be a section in `design.md`). `feature`/`full`: a standalone `docs/decisions/ADR-NNNN-*.md`.
+
+### 5. Threat model (`phase` = lite, `feature`+ = full)
+- STRIDE-lite: for each realistic threat, its vector and its mitigation (or explicit acceptance). `phase` tier covers the change's own surface; `feature`+ covers the full feature.
+
+### 6. Error handling & diagnostics (`feature`+)
+- Every error condition → output shape + handling style (validate args before side effects; safe reads return null; actionable messages).
+
+### 7. Test plan (`phase` = hooks, `feature`+ = full)
+- How each success criterion is verified; which are unit vs scenario; the seed inputs for the machine-checkable ones.
+
+### 8. Demand & strategy (`feature`+ / `full`)
+- `feature`: demand evidence (or an explicit "speculative" flag), feature ladder (v0 MVP → v1 → v2).
+- `full`: competitive intelligence, strategic analysis (ERRC: eliminate/reduce/raise/create), adoption analysis.
+
+---
+
+## Quality bar (what `pan-design-checker` enforces)
+
+A design artifact **passes** only when all of these hold at its tier. This is the
+same checklist the independent checker verifies — designers should self-check
+against it before handing off, but passing is decided by the checker, not the
+author.
+
+1. **Requirement coverage** — every stated requirement maps to a design element; nothing is silently dropped.
+2. **Machine-checkable criteria** — ≥2 success criteria are automatable, and each names its check (`phase`+).
+3. **Architecture conformance** — the design matches conventions *discovered* from the codebase, and introduces no layer/boundary violation.
+4. **ADR honesty** — alternatives are real (not strawmen); every negative consequence has a mitigation or is explicitly accepted; no placeholder/skeleton sections (`phase`+).
+5. **Threat coverage** — each identified threat is mitigated or explicitly accepted; none is left open (`phase` lite / `feature`+ full).
+6. **Testability** — the test plan/hooks map to the success criteria (`phase`+).
+7. **Scope discipline** — the design stays within the fixed boundary; scope-expanding ideas are captured as "deferred", never designed in.
+
+If any dimension fails, the checker returns structured gaps and the designer
+revises. The reflexion loop is capped at **2 revision iterations** (design →
+check → revise → check → final) to prevent over-revision — the same guardrail
+`plan-phase` uses with `pan-plan-checker`.

package/pan-wizard-core/references/git-integration.md

@@ -14,9 +14,9 @@ The git log should read like a changelog of what shipped, not a diary of plannin
 | Event                   | Commit? | Why                                              |
 | ----------------------- | ------- | ------------------------------------------------ |
 | BRIEF + ROADMAP created | YES     | Project initialization                           |
-| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
-| RESEARCH.md created     | NO      | Intermediate                                     |
-| DISCOVERY.md created    | NO      | Intermediate                                     |
+| plan.md created         | NO      | Intermediate - commit with plan completion       |
+| research.md created     | NO      | Intermediate                                     |
+| discovery.md created    | NO      | Intermediate                                     |
 | **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
 | **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
 | Handoff created         | YES     | WIP state preserved                              |
@@ -123,13 +123,13 @@ Tasks completed: [N]/[N]
 - [Task 2 name]
 - [Task 3 name]
 
-SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-summary.md
 ```
 
 What to commit:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/state.md .planning/roadmap.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-plan.md .planning/phases/XX-name/{phase}-{plan}-summary.md .planning/state.md .planning/roadmap.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -205,9 +205,9 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 <anti_patterns>
 
 **Still don't commit (intermediate artifacts):**
-- PLAN.md creation (commit with plan completion)
-- RESEARCH.md (intermediate)
-- DISCOVERY.md (intermediate)
+- plan.md creation (commit with plan completion)
+- research.md (intermediate)
+- discovery.md (intermediate)
 - Minor planning tweaks
 - "Fixed typo in roadmap"
 
@@ -228,7 +228,7 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 - Git history becomes primary context source for future Claude sessions
 - `git log --grep="{phase}-{plan}"` shows all work for a plan
 - `git diff <hash>^..<hash>` shows exact changes per task
-- Less reliance on parsing SUMMARY.md = more context for actual work
+- Less reliance on parsing summary.md = more context for actual work
 
 **Failure recovery:**
 - Task 1 committed ✅, Task 2 failed ❌

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

@@ -13,7 +13,10 @@ phase — context compaction may have dropped earlier sections.
 | "Phase tests passed locally, /pan:verify-phase isn't needed" | One run isn't validation. verify-phase checks state consistency, doc sync, blockers, and the full suite — not just the phase's own tests. | Always run `/pan:verify-phase` before marking a phase complete. |
 | "I'll skip /pan:focus-scan and pick the next item myself" | Manual selection ignores priority/budget logic in `focus.cjs`. You'll bias toward easy items and miss higher-priority work. | Use `/pan:focus-scan` → `/pan:focus-plan` → `/pan:focus-exec`. |
 | "I'll bump the model / add a flag / refactor while I'm here" | Scope creep. The user asked for one change; surrounding cleanup belongs in a separate item. | Do only the requested change. Note unrelated cleanup as a TODO for a future focus-scan. |
-| "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run `/pan:sync` (or the equivalent doc-sync step) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |
+| "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run the doc-sync step (update CHANGELOG/state and commit via `pan-tools commit`) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |
+| "The tests pass, so the code is portable" | Tests run on one Node version on one OS. Modern Node auto-detects ESM syntax, so `import`/`export` in a project with no `package.json` passes locally and fails under `"type": "commonjs"` or older Node. | Declare the module type explicitly whenever you emit `import`/`export` or `require` — `"type"` in `package.json`, or `.mjs`/`.cjs` extensions. Never rely on syntax detection. |
+| "It rejects bad input — I wrapped the parser in try/catch" | That only rejects *unparseable* input. Valid JSON of the wrong shape passes through and surfaces as `undefined` in an unrelated caller. | Validate shape after parsing, not just parseability. Assert the expected type/keys and fall back or throw. See `references/verification-patterns.md` → Baseline Checks. |
+| "I'll write the doc now and refine it as I go" | Skeleton-then-refine never converges: field transcripts show planning files rewritten 12-19× and re-read 6-16× in a single step, and every in-flight version of state.md is one a later step can read (P-1808). | Compose the complete document in memory, then issue exactly ONE Write per file per step. Don't re-read a file you wrote this step. Post-write corrections are targeted Edits for a verified defect, never a rewrite. |
 
 ## Code Preservation Principle
 

package/pan-wizard-core/references/model-profile-resolution.md

@@ -24,7 +24,7 @@ Task(
 )
 ```
 
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+**Note:** Reasoning-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific model versions.
 
 ## Usage
 

package/pan-wizard-core/references/model-profiles.md

@@ -10,7 +10,7 @@ PAN uses three abstract tiers instead of hardcoded model names:
 
 | Tier | Purpose | Anthropic | OpenAI | Google |
 |------|---------|-----------|--------|--------|
-| `reasoning` | Architecture, planning, complex decisions | inherit (Fable/Opus) | inherit | inherit |
+| `reasoning` | Architecture, planning, complex decisions | inherit (your session's top-tier model) | inherit | inherit |
 | `mid` | Execution, research, verification | Sonnet | mid | mid |
 | `fast` | Read-only extraction, budget tasks | Haiku | fast | fast |
 
@@ -28,55 +28,63 @@ For backward compatibility, legacy Anthropic model names still work:
 
 ---
 
-## Recommended Models (Claude)
+## Choosing a Reasoning-Tier Model (Claude)
 
-PAN never selects your host model — it recommends one. Because the `reasoning` tier is `inherit`, whichever top-tier model you configure in your runtime (Claude Code, etc.) runs every reasoning-tier agent (planner, conductor, executor, hardener…). `mid` and `fast` agents stay on Sonnet/Haiku regardless, so the whole fleet is never on one expensive model.
+PAN never selects your host model — it recommends a *class*. Because the `reasoning` tier is `inherit`, whichever top-tier model you configure in your runtime (Claude Code, etc.) runs the reasoning-tier agents (planner, conductor, executor…). Since the 2026-07 COST RESET that means *every* agent under `quality` and `balanced` (the default), except the ones that pin a model in their own frontmatter — `grep -l '^model: opus' agents/*.md` lists those, and the pin wins on Claude Code. Only the opt-in `budget` profile drops agents to `mid`/`fast`, which on Anthropic map to Sonnet/Haiku.
 
-| Model | Role in PAN | Context | Relative cost | Notes |
-|-------|-------------|---------|---------------|-------|
-| `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
-| `claude-opus-4-8` | **Cost-conscious default** — same 1M context + thinking, half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
+The IDs below are *examples* of what you can configure in each class — not an exhaustive or only-valid list. A newer release in the same class behaves the same way here.
 
-**Why Fable is the recommended flagship.** It is Anthropic's most capable widely released model for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select it in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
+At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits Haiku's, which is not a 1M-context/thinking profile. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
 
-**Fable caveat — the cyber-classifier refusal, and how PAN handles it.** Fable is the only current Claude model that runs input safety classifiers targeting cybersecurity and biology content, and benign *defensive* security tooling can trigger false positives — a successful response with `stop_reason: "refusal"` and `stop_details.category: "cyber"`. In PAN this hits every security path: `/pan:review-deep`, `exec-phase --deep-review`, **and the `focus-auto`/army `security` category** (which was observed refusing in a real project). Two mitigations, in order of reliability:
+| Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
+|-------|-------------------|-------------|---------|---------------|-------|
+| Fable / Mythos | `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
+| Opus | `claude-opus-5`, `claude-opus-4-8` | **Cost-conscious pick** — same 1M context + thinking, about half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
 
-1. **Opus pin (the durable fix).** `pan-hardener`, `pan-reviewer`, and `pan-meta-reviewer` carry `model: opus` in their frontmatter, so on **Claude Code** they run on Opus 4.8 regardless of your session model and never reach Fable's classifier. The `focus-auto` security category routes its vulnerability *assessment* through the Opus-pinned `pan-hardener` for the same reason. This pin is **Claude-Code-only** — it is stripped from the Gemini/OpenCode/Codex/Copilot outputs by the installer, so on the other runtimes run security campaigns on a non-Fable model.
+**Why the Fable class is the recommended flagship.** It is Anthropic's deepest class for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select the current release in that class in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
+
+**Fable caveat — the cyber-classifier refusal, and how PAN handles it.** Fable-class models run input safety classifiers targeting cybersecurity and biology content, and benign *defensive* security tooling can trigger false positives — a successful response with `stop_reason: "refusal"` and `stop_details.category: "cyber"`. In PAN this hits every security path: `/pan:review-deep`, `exec-phase --deep-review`, **and the `focus-auto`/army `security` category** (which was observed refusing in a real project). Two mitigations, in order of reliability:
+
+1. **Opus pin (the durable fix).** PAN's security-review agents carry `model: opus` in their frontmatter — `grep -l '^model: opus' agents/*.md` lists the current set — so on **Claude Code** they run on the default Opus model regardless of your session model and never reach Fable's classifier. The `focus-auto` security category routes its vulnerability *assessment* through the Opus-pinned `pan-hardener` for the same reason. This pin is **Claude-Code-only** — it is stripped from the Gemini/OpenCode/Codex/Copilot outputs by the installer, so on the other runtimes run security campaigns on a non-Fable model.
 2. **Defensive framing.** Those agents and the `focus-auto` security prose are written as *authorized, defensive review* (no exploit-path narration), which lowers the trigger rate but cannot eliminate it — a security scanner must name injection, auth bypass, and RCE by definition. Framing is the backstop; the Opus pin is the fix.
 
 **Fable data-retention requirement.** Fable is not available under zero data retention; an org whose retention is below 30 days gets a hard `400` on every request. If Fable 400s on every call with an otherwise-valid request, check the org's retention setting before debugging anything else.
 
-**Prompting note for Fable.** Fable prefers *less-prescriptive* prompts than earlier models and runs longer per turn. PAN's autonomous-loop guidance (anti-overplanning, grounded progress claims, act-when-you-have-enough) already aligns with this; avoid piling on `CRITICAL: YOU MUST` scaffolding, which can reduce Fable's output quality.
+**Prompting note for Fable.** Fable-class models prefer *less-prescriptive* prompts than earlier generations and run longer per turn. PAN's autonomous-loop guidance (anti-overplanning, grounded progress claims, act-when-you-have-enough) already aligns with this; avoid piling on `CRITICAL: YOU MUST` scaffolding, which can reduce Fable's output quality.
 
 ---
 
 ## Profile Definitions
 
+Since the 2026-07 **COST RESET**, `quality` and `balanced` are identical — both route every agent to the `reasoning` tier. Only the opt-in `budget` profile steps agents below reasoning (to `mid`/`fast` per the last column). The table below is illustrative; `core.cjs` `MODEL_PROFILES` is the source of truth and covers the full agent roster.
+
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
 | pan-planner | reasoning | reasoning | mid |
-| pan-roadmapper | reasoning | mid | mid |
-| pan-executor | reasoning | mid | mid |
-| pan-phase-researcher | reasoning | mid | fast |
-| pan-project-researcher | reasoning | mid | fast |
-| pan-research-synthesizer | reasoning | mid | fast |
-| pan-debugger | reasoning | mid | mid |
-| pan-document_code | reasoning | fast | fast |
-| pan-verifier | reasoning | mid | fast |
-| pan-plan-checker | reasoning | mid | fast |
-| pan-integration-checker | reasoning | mid | fast |
-| pan-reviewer | reasoning | fast | fast |
+| pan-roadmapper | reasoning | reasoning | mid |
+| pan-executor | reasoning | reasoning | mid |
+| pan-phase-researcher | reasoning | reasoning | fast |
+| pan-project-researcher | reasoning | reasoning | fast |
+| pan-research-synthesizer | reasoning | reasoning | fast |
+| pan-debugger | reasoning | reasoning | mid |
+| pan-document_code | reasoning | reasoning | fast |
+| pan-verifier | reasoning | reasoning | fast |
+| pan-plan-checker | reasoning | reasoning | fast |
+| pan-integration-checker | reasoning | reasoning | fast |
+| pan-reviewer | reasoning | reasoning | fast |
 
 ### Profile Philosophy
 
+Post-COST-RESET, `quality` and `balanced` are the same profile in practice — both give every agent the `reasoning` tier. Cost savings come only from opting into `budget`.
+
 **quality** — Maximum reasoning power
 - Reasoning tier for ALL agents. Use when quota is available, critical architecture work, or maximum quality is desired.
 
-**balanced** (default) — Smart allocation
-- Reasoning only for planning (where architecture decisions happen). Mid for execution. Fast for read-only tasks. Good balance of quality and cost.
+**balanced** (default) — Reasoning everywhere
+- Identical to `quality` since the COST RESET: reasoning tier for every agent. It remains the default so new projects get full reasoning power out of the box. Switch to `budget` when you need to cut token spend.
 
 **budget** — Minimal token spend
-- Mid for anything that writes code. Fast for research and verification. Use for high-volume work or less critical phases.
+- The only profile that steps agents below reasoning: mid for anything that writes code, fast for research and verification (see the `budget` column). Use for high-volume work or less critical phases.
 
 ### Cost Multipliers
 
@@ -246,17 +254,19 @@ Runtime: `/pan:profile <profile>`
 
 ## Design Rationale
 
-**Why reasoning for pan-planner?**
-Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+Since the 2026-07 COST RESET, `quality` and `balanced` put every agent on the `reasoning` tier — so the notes below explain the tier each agent *steps down to* under `budget`, the only profile that now drops below reasoning.
+
+**Why reasoning for pan-planner (and every agent under quality/balanced)?**
+Planning involves architecture decisions, goal decomposition, and task design — where model quality has the highest impact. Post-COST-RESET the reasoning tier is inexpensive enough that every agent stays on it unless you opt into budget.
 
-**Why mid for pan-executor?**
-Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
+**Why mid for pan-executor under budget?**
+Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation, so `budget` can safely step them to mid.
 
-**Why mid (not fast) for verifiers in balanced?**
-Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching.
+**Why fast for verifiers under budget?**
+Verification ideally uses goal-backward reasoning, but under `budget` the check degrades gracefully to fast pattern-matching to save tokens.
 
-**Why fast for pan-document_code?**
+**Why fast for pan-document_code under budget?**
 Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
 
-**Why fast for pan-reviewer in balanced?**
-Code review is pattern-matching against known conventions and security rules. Fast handles checklist-style verification efficiently.
+**Why fast for pan-reviewer under budget?**
+Code review is pattern-matching against known conventions and security rules. Fast handles checklist-style verification efficiently when budget is engaged.

package/pan-wizard-core/references/planning-config.md

@@ -101,7 +101,7 @@ To use uncommitted mode:
    git commit -m "chore: stop tracking planning docs"
    ```
 
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `milestone-done` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
 
 </setup_uncommitted_mode>
 
@@ -113,7 +113,7 @@ To use uncommitted mode:
 |----------|---------------------|--------------|-------------|
 | `none` | Never | N/A | N/A |
 | `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `milestone-done` |
 
 **When `git.branching_strategy: "none"` (default):**
 - All work commits to current branch
@@ -124,13 +124,13 @@ To use uncommitted mode:
 - Branch name from `phase_branch_template` (e.g., `pan/phase-03-authentication`)
 - All plan commits go to that branch
 - User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
+- `milestone-done` offers to merge all phase branches
 
 **When `git.branching_strategy: "milestone"`:**
 - First `execute-phase` of milestone creates the milestone branch
 - Branch name from `milestone_branch_template` (e.g., `pan/v1.0-mvp`)
 - All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
+- `milestone-done` offers to merge milestone branch to main
 
 **Template variables:**
 
@@ -172,7 +172,7 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
-**Merge options at complete-milestone:**
+**Merge options at milestone-done:**
 
 | Option | Git command | Result |
 |--------|-------------|--------|