pan-wizard 3.22.0 → 3.24.0

package/pan-wizard-core/workflows/diagnose-issues.md

@@ -64,7 +64,7 @@ Spawning parallel debug agents to investigate root causes:
 | Delete removes comment | blocker |
 
 Each agent will:
-1. Create DEBUG-{slug}.md with symptoms pre-filled
+1. Create ${DEBUG_DIR}/{slug}.md with symptoms pre-filled
 2. Investigate autonomously (read code, form hypotheses, test)
 3. Return root cause
 
@@ -80,22 +80,24 @@ For each gap, fill the debug-subagent-prompt template and spawn:
 ```
 Task(
   prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-uat.md\n- .planning/state.md\n</files_to_read>",
-  subagent_type="general-purpose",
-  description="Debug: {truth_short}"
+  subagent_type="pan-debugger",
+  description="Debug: {issue_summary_short}"
 )
 ```
 
 **All agents spawn in single message** (parallel execution).
 
-Template placeholders:
-- `{truth}`: The expected behavior that failed
+Template placeholders (see `debug-subagent-prompt.md`):
+- `{issue_id}`: Stable id for the gap, e.g. `UAT-{test_num}`
+- `{issue_summary}`: The expected behavior that failed
 - `{expected}`: From UAT test
 - `{actual}`: Verbatim user description from reason field
 - `{errors}`: Any error messages from UAT (or "None reported")
 - `{reproduction}`: "Test {test_num} in UAT"
 - `{timeline}`: "Discovered during UAT"
+- `{true_or_false}`: `true` (symptoms are prefilled from the UAT gap)
 - `{goal}`: `find_root_cause_only` (UAT flow - plan-phase --gaps handles fixes)
-- `{slug}`: Generated from truth
+- `{slug}`: Generated from the issue summary
 </step>
 
 <step name="collect_results">
@@ -200,7 +202,7 @@ Agents only diagnose—plan-phase --gaps handles fixes (no fix application).
 - Report incomplete diagnosis
 
 **Agent times out:**
-- Check DEBUG-{slug}.md for partial progress
+- Check ${DEBUG_DIR}/{slug}.md for partial progress
 - Can resume with /pan:debug
 
 **All agents fail:**

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

@@ -160,7 +160,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
 2. **Spawn executor agents:**
 
-   Pass paths only — executors read files themselves with their fresh 200k context.
+   Pass paths only — executors read files themselves in their own fresh context window.
    This keeps orchestrator context lean (~10-15%).
 
    ```
@@ -286,11 +286,23 @@ When executor returns a checkpoint AND `AUTO_CFG` is `"true"`:
    [Awaiting section from agent return]
    ```
 5. User responds: "approved"/"done" | issue description | decision selection
-6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
-   - `{completed_tasks_table}`: From checkpoint return
-   - `{resume_task_number}` + `{resume_task_name}`: Current task
-   - `{user_response}`: What user provided
-   - `{resume_instructions}`: Based on checkpoint type
+6. **Spawn continuation agent (NOT resume)** with a prompt built inline from this structure:
+   ```
+   Continue executing plan {plan_id}. A previous agent paused at a checkpoint.
+
+   ## Already completed
+   {completed_tasks_table}    ← the completed-tasks table from the checkpoint return
+
+   ## Resume point
+   Task {resume_task_number}: {resume_task_name}    ← the current (paused) task
+   User response to checkpoint: {user_response}      ← "approved"/"done", the chosen decision option, or the issue description the user typed
+
+   ## Instructions
+   {resume_instructions}      ← derived from the checkpoint type: human-verify → "resume the paused task";
+                                decision → "apply the selected option, then continue"; issue → "address the
+                                described issue first, then continue". Verify the previous commits before proceeding.
+   ```
+   All five placeholders are defined here — there is no separate template file to load.
 7. Continuation agent verifies previous commits, continues from resume point
 8. Repeat until plan completes or user stops
 
@@ -602,7 +614,7 @@ The CLI handles:
 
 Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 
-**Phase reports (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the self-contained per-phase HTML report — and, when `workflow.phase_reports.index` is `true`, the project timeline index — at this verify→complete gate so they ship with the phase and ride the commit below. Disabled by default; phase-less projects are skipped automatically by `report`. Never opens a browser here (that's reserved for a manual `pan-tools report --open`).
+**Phase reports (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the self-contained per-phase HTML report — and, when `workflow.phase_reports.index` is `true`, the project timeline index — at this verify→complete gate so they ship with the phase and ride the commit below. Disabled by default; phase-less projects are skipped automatically by `report`. Never opens a browser here (that's reserved for a manual `pan-tools report index --open`).
 
 ```bash
 REPORT_FILES=""
@@ -704,6 +716,10 @@ STOP — do not auto-advance. Return to user.
    ```bash
    AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
    ```
+3. **If `--auto` flag present AND `AUTO_CFG` is not true — persist it** (same as discuss-phase's auto_advance step). The flag lives only in this invocation's arguments; the rest of the chain, and the P-1809 stop guard, can only see the run as autonomous if the disk says so (P-1810 — the guard missed a real boundary drop because a flag-driven run left config unarmed):
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance true
+   ```
 
 **If `--auto` flag present OR `AUTO_CFG` is true (AND verification passed with no gaps):**
 
@@ -718,6 +734,10 @@ Execute the transition workflow inline (do NOT use Task — orchestrator context
 
 Read and follow `~/.claude/pan-wizard-core/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
 
+**Contract (P-1807):** transition.md's continuation gates key on the same trigger you just evaluated (`--auto` flag, `workflow.auto_advance`, or `mode: yolo`) — NOT on `mode` alone. Having announced AUTO-ADVANCING, the transition must end in a `Task(...)` spawn of the next phase (Route A) or reach the milestone boundary (Route B). If you find yourself printing a "Next Up" menu and stopping after the banner above, that is the P-1801/P-1807 regression, not a valid outcome.
+
+**Post-transition self-check (MANDATORY final action in auto mode):** after transition.md finishes, confirm one of its two valid terminal states actually happened: (a) a `Task(...)` spawn for the next phase was issued (Route A), or (b) the milestone boundary was reached (Route B). If neither — state was updated but no spawn went out — you are inside the P-1801/P-1807 failure right now: return to transition.md `offer_next_phase` Route A and issue the Task spawn before ending your turn.
+
 **If neither `--auto` nor `AUTO_CFG` is true:**
 
 The workflow ends. The user runs `/pan:progress` or invokes the transition workflow manually.
@@ -726,7 +746,7 @@ The workflow ends. The user runs `/pan:progress` or invokes the transition workf
 </process>
 
 <context_efficiency>
-Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task blocks). No context bleed.
+Orchestrator: ~10-15% context. Subagents: a fresh window each. No polling (Task blocks). No context bleed.
 </context_efficiency>
 
 <failure_handling>

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

@@ -94,14 +94,13 @@ Fresh context per subagent preserves peak quality. Main context stays lean.
 if [ ! -f .planning/agent-history.json ]; then
   echo '{"version":"1.0","max_entries":50,"entries":[]}' > .planning/agent-history.json
 fi
-rm -f .planning/current-agent-id.txt
 if [ -f .planning/current-agent-id.txt ]; then
   INTERRUPTED_ID=$(cat .planning/current-agent-id.txt)
   echo "Found interrupted agent: $INTERRUPTED_ID"
 fi
 ```
 
-If interrupted: ask user to resume (Task `resume` parameter) or start fresh.
+If interrupted: ask user to resume (Task `resume` parameter) or start fresh. Only AFTER that decision (per the tracking protocol below — resume detection must see the stale id first) clear the marker with `rm -f .planning/current-agent-id.txt`.
 
 **Tracking protocol:** On spawn: write agent_id to `current-agent-id.txt`, append to agent-history.json: `{"agent_id":"[id]","task_description":"[desc]","phase":"[phase]","plan":"[plan]","segment":[num|null],"timestamp":"[ISO]","status":"spawned","completion_timestamp":null}`. On completion: status → "completed", set completion_timestamp, delete current-agent-id.txt. Prune: if entries > max_entries, remove oldest "completed" (never "spawned").
 
@@ -423,7 +422,7 @@ FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase
 git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
 ```
 
-Update only structural changes: new src/ dir → STRUCTURE.md | deps → STACK.md | file pattern → CONVENTIONS.md | API client → INTEGRATIONS.md | config → STACK.md | renamed → update paths. Skip code-only/bugfix/content changes.
+Update only structural changes: new src/ dir → structure.md | deps → stack.md | file pattern → conventions.md | API client → integrations.md | config → stack.md | renamed → update paths. Skip code-only/bugfix/content changes.
 
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "" --files .planning/codebase/*.md --amend

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

@@ -157,9 +157,32 @@ Report final status.
 | W003 | warning | config.json not found | Yes |
 | W004 | warning | config.json invalid field value | No |
 | W005 | warning | Phase directory naming mismatch | No |
-| W006 | warning | Phase in ROADMAP but no directory | No |
+| W006 | warning | Phase in ROADMAP at or behind current phase, but no directory | No |
 | W007 | warning | Phase on disk but not in ROADMAP | No |
 | I001 | info | Plan without SUMMARY (may be in progress) | No |
+| I002 | info | Phase in ROADMAP ahead of current phase, not planned yet | 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 |
+
+Flag-gated codes:
+
+| Code | Severity | Flag | Description | Repairable |
+|------|----------|------|-------------|------------|
+| TESTS_FAIL | error | --full | Test run exited non-zero | No |
+| BUILD_FAIL | error | --full | Build exited non-zero | No |
+| MEM_BUDGET | warning / info | --full | Memory injection over budget | No |
+| DRIFT_HIGH | warning | --drift | Drift verdict is high | No |
+| DRIFT_MEDIUM | info | --drift | Drift verdict is medium | No |
+| LINKS_ERR | warning | --links | Link graph has errors | No |
+| STD-000 | info | --standards | No standards.md found | No |
+| STD-001 | info | --standards | standards.md has no recognized standards | No |
+| STD-*id* | warning / info | --standards | Per-standard coverage (warning at 0%) | No |
+| STD-SUMMARY | info | --standards | Overall coverage across standards | No |
+
+**I002 vs W006:** a roadmap phase the project has not reached yet is normal progress,
+not a defect — it reports as info and does not degrade health. Only a missing phase at
+or behind the current position warns.
 
 </error_codes>
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Display the complete PAN command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+Display the PAN command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
 </purpose>
 
 <reference>
@@ -148,7 +148,6 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 **Flags:**
 - `--mode <mode>` — select execution mode (default: balanced)
 - `--budget N` — override point budget (5-100)
-- `--dry-run` — show what would be selected without writing
 - `--lean` — exclude items with RS < 1.5
 
 ### Step 3: `/pan:focus-exec`
@@ -208,7 +207,9 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 ---
 
-## All Commands (42)
+## All Commands
+
+> This table is a **curated subset** of the most-used commands, not an exhaustive list. For the full, always-current command set, browse the `commands/pan/*.md` files in your install (each `.md` is one `/pan:<name>` command).
 
 ### Getting Started
 | Command | Description |
@@ -389,7 +390,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:settings`** — Toggle researcher, plan checker, verifier agents. Select model profile.
 
-**`/pan:profile <name>`** — Quick profile switch: `quality` (Opus everywhere), `balanced` (Opus plan + Sonnet exec, default), `budget` (Sonnet + Haiku).
+**`/pan:profile <name>`** — Quick profile switch: `quality` and `balanced` (reasoning tier for every agent; `balanced` is the default), `budget` (mid tier for writing, fast tier for research/verification).
 
 **Planning config** (`.planning/config.json`):
 - `commit_docs: true` — commit planning artifacts to git (set `false` + add `.planning/` to `.gitignore` for private planning)

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

@@ -16,12 +16,12 @@ Analyze the most recent trace session and generate a circular optimization repor
 
 Run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
 ```
 
 If no active session, run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace list
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace list
 ```
 Use the most recent session unless `--session <id>` was specified.
 
@@ -31,7 +31,7 @@ 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>]
 ```
 
 This produces `.planning/optimization/reports/{session}-analysis.json`.
@@ -67,7 +67,7 @@ Present to the user:
 
 If the `--apply` flag was passed, immediately run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize apply
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize apply
 ```
 
 Show what was applied and what still needs review.
@@ -82,7 +82,7 @@ After applying, tell the user what to watch in the next run:
 ## Edge cases
 
 **No events in trace:**
-- Tell the user the trace session is empty. They may need to ensure the `pan-trace-logger` hook is registered in `.claude/settings.json`.
+- Tell the user the trace session is empty. They may need to ensure the `pan-trace-logger` hook is registered in `~/.claude/settings.json`.
 
 **Too few events (< 5):**
 - The optimizer can still run but note the small sample size.

package/pan-wizard-core/workflows/map-codebase.md

@@ -315,7 +315,7 @@ This would expose credentials if committed.
 **Action required:**
 1. Review the flagged content above
 2. If these are real secrets, they must be removed before committing
-3. Consider adding sensitive files to Claude Code "Deny" permissions
+3. Consider adding sensitive files to your AI coding tool's deny/ignore list
 
 Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
 ```

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

@@ -129,7 +129,7 @@ For each REQ-ID, determine status using all three sources:
 
 ## 6. Aggregate into v{version}-milestone-audit.md
 
-Create `.planning/v{version}-v{version}-milestone-audit.md` with:
+Create `.planning/v{version}-milestone-audit.md` with:
 
 ```yaml
 ---

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

@@ -17,12 +17,12 @@ Read all files referenced by the invoking prompt's execution_context before star
 - Read project.md (existing project, validated requirements, decisions)
 - Read milestones.md (what shipped previously)
 - Read state.md (pending todos, blockers)
-- Check for MILESTONE-context.md (from /pan:discuss-milestone)
+- Check for MILESTONE-context.md (optional pre-seeded context, if the user prepared one)
 
 ## 2. Gather Milestone Goals
 
 **If MILESTONE-context.md exists:**
-- Use features and scope from discuss-milestone
+- Use features and scope from MILESTONE-context.md
 - Present summary for confirmation
 
 **If no context file:**
@@ -151,7 +151,7 @@ Use template: ~/.claude/pan-wizard-core/templates/research-project/{FILE}
 | QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
 | CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
 | GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
-| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
+| FILE | stack.md | features.md | architecture.md | pitfalls.md |
 
 After all 4 complete, spawn synthesizer:
 
@@ -195,7 +195,7 @@ Display key findings from summary.md:
 
 Read project.md: core value, current milestone goals, validated requirements (what exists).
 
-**If research exists:** Read FEATURES.md, extract feature categories.
+**If research exists:** Read features.md, extract feature categories.
 
 Present features by category:
 ```

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

@@ -8,6 +8,21 @@ Read all files referenced by the invoking prompt's execution_context before star
 @~/.claude/pan-wizard-core/references/guardrails.md
 </required_reading>
 
+<planning_write_policy>
+
+**P-1808 — compose once, write once.** Every planning document this workflow produces (`project.md`, `requirements.md`, `roadmap.md`, `state.md`) is composed **in full, in memory, then written exactly once**. Field transcripts (PanLoop, 2026-08-08) counted `state.md` rewritten up to **12 times inside a single step**, `roadmap.md` and `project.md` 3× each, the same files re-read up to 6× — an agent failing to converge on a document it authored moments earlier. Every in-flight version of `state.md` is a chance for a later step to read a partial write, and the rewrite churn is why this workflow's duration varied 7× on similar briefs.
+
+Rules, for this orchestrator and every subagent it spawns:
+
+1. **Gather everything, then emit.** Do not write a skeleton and refine it in place. Not ready to write the final document = still in the gathering step.
+2. **One Write per file per step.** Preparing a second Write to the same file in the same step means the first was premature — stop, finish composing, write once.
+3. **Do not re-read a file you wrote this step.** You know what it says; re-reading your own output to "check" it is the non-convergence loop starting.
+4. **Post-write corrections are targeted Edits for a verified defect** (wrong value, broken parse) — never a rewrite for restructuring you should have composed the first time.
+
+"Write files first, then return" — the persistence rule — is unchanged: it orders writes **before the return**; it does not license early drafts.
+
+</planning_write_policy>
+
 ## Phase 0 — Clarify (MANDATORY, do not skip)
 
 Before scaffolding or coding anything, confirm with the user:
@@ -63,7 +78,7 @@ The document should describe what you want to build.
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
 
 ```bash
-INIT=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs init new-project)
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init new-project)
 ```
 
 Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
@@ -154,13 +169,13 @@ Create `.planning/config.json` with mode set to "yolo":
 
 ```bash
 mkdir -p .planning
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: add project config" --files .planning/config.json
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: add project config" --files .planning/config.json
 ```
 
 **Persist auto-advance to config (survives context compaction):**
 
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance true
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance true
 ```
 
 Proceed to Step 4 (skip Steps 3 and 5).
@@ -304,19 +319,19 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: initialize project" --files .planning/project.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: initialize project" --files .planning/project.md
 ```
 
 ## 5. Workflow Preferences
 
 **If auto mode:** Skip — config was collected in Step 2a. Proceed to Step 5.5.
 
-**Check for global defaults** at `~/.pan-wizard-core/defaults.json`. If the file exists, offer to use saved defaults:
+**Check for global defaults** at `~/.pan-wizard/defaults.json`. If the file exists, offer to use saved defaults:
 
 ```
 AskUserQuestion([
   {
-    question: "Use your saved default settings? (from ~/.pan-wizard-core/defaults.json)",
+    question: "Use your saved default settings? (from ~/.pan-wizard/defaults.json)",
     header: "Defaults",
     multiSelect: false,
     options: [
@@ -327,9 +342,9 @@ AskUserQuestion([
 ])
 ```
 
-If "Yes": read `~/.pan-wizard-core/defaults.json`, use those values for config.json, and skip directly to **Commit config.json** below.
+If "Yes": read `~/.pan-wizard/defaults.json`, use those values for config.json, and skip directly to **Commit config.json** below.
 
-If "No" or `~/.pan-wizard-core/defaults.json` doesn't exist: proceed with the questions below.
+If "No" or `~/.pan-wizard/defaults.json` doesn't exist: proceed with the questions below.
 
 **Round 1 — Core workflow settings (4 questions):**
 
@@ -421,9 +436,9 @@ questions: [
     question: "Which AI models for planning agents?",
     multiSelect: false,
     options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
+      { label: "Balanced (Recommended)", description: "reasoning tier for every agent — the default (identical to quality post-COST-RESET)" },
+      { label: "Quality", description: "reasoning tier for every agent — identical to balanced, so switching between the two changes nothing" },
+      { label: "Budget", description: "mid tier for writing, fast tier for research/verification — fastest, lowest cost" }
     ]
   }
 ]
@@ -456,7 +471,7 @@ Create `.planning/config.json` with all settings:
 **Commit config.json:**
 
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: add project config" --files .planning/config.json
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: add project config" --files .planning/config.json
 ```
 
 **Note:** Run `/pan:settings` anytime to update these preferences.
@@ -510,7 +525,7 @@ Display spawning indicator:
 Spawn 4 parallel pan-project-researcher agents with path references:
 
 ```
-Task(prompt="First, read ./.claude/agents/pan-project-researcher.md for your role and instructions.
+Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
 
 <research_type>
 Project Research — Stack dimension for [domain].
@@ -546,11 +561,11 @@ Your stack.md feeds into roadmap creation. Be prescriptive:
 
 <output>
 Write to: .planning/research/stack.md
-Use template: ./.claude/pan-wizard-core/templates/research-project/stack.md
+Use template: ~/.claude/pan-wizard-core/templates/research-project/stack.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
 
-Task(prompt="First, read ./.claude/agents/pan-project-researcher.md for your role and instructions.
+Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
 
 <research_type>
 Project Research — Features dimension for [domain].
@@ -586,11 +601,11 @@ Your features.md feeds into requirements definition. Categorize clearly:
 
 <output>
 Write to: .planning/research/features.md
-Use template: ./.claude/pan-wizard-core/templates/research-project/features.md
+Use template: ~/.claude/pan-wizard-core/templates/research-project/features.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
 
-Task(prompt="First, read ./.claude/agents/pan-project-researcher.md for your role and instructions.
+Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
 
 <research_type>
 Project Research — Architecture dimension for [domain].
@@ -626,11 +641,11 @@ Your architecture.md informs phase structure in roadmap. Include:
 
 <output>
 Write to: .planning/research/architecture.md
-Use template: ./.claude/pan-wizard-core/templates/research-project/architecture.md
+Use template: ~/.claude/pan-wizard-core/templates/research-project/architecture.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
 
-Task(prompt="First, read ./.claude/agents/pan-project-researcher.md for your role and instructions.
+Task(prompt="First, read ~/.claude/agents/pan-project-researcher.md for your role and instructions.
 
 <research_type>
 Project Research — Pitfalls dimension for [domain].
@@ -666,7 +681,7 @@ Your pitfalls.md prevents mistakes in roadmap/planning. For each pitfall:
 
 <output>
 Write to: .planning/research/pitfalls.md
-Use template: ./.claude/pan-wizard-core/templates/research-project/pitfalls.md
+Use template: ~/.claude/pan-wizard-core/templates/research-project/pitfalls.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
 ```
@@ -688,7 +703,7 @@ Synthesize research outputs into summary.md.
 
 <output>
 Write to: .planning/research/summary.md
-Use template: ./.claude/pan-wizard-core/templates/research-project/summary.md
+Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
 Commit after writing.
 </output>
 ", subagent_type="pan-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
@@ -727,7 +742,7 @@ Read project.md and extract:
 - Stated constraints (budget, timeline, tech limitations)
 - Any explicit scope boundaries
 
-**If research exists:** Read research/FEATURES.md and extract feature categories.
+**If research exists:** Read research/features.md and extract feature categories.
 
 **If auto mode:**
 - Auto-include all table stakes features (users expect these)
@@ -853,7 +868,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: define v1 requirements" --files .planning/requirements.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: define v1 requirements" --files .planning/requirements.md
 ```
 
 ## 8. Create Roadmap
@@ -888,10 +903,10 @@ Create roadmap:
 2. Map every v1 requirement to exactly one phase
 3. Derive 2-5 success criteria per phase (observable user behaviors)
 4. Validate 100% coverage
-5. Write files immediately (roadmap.md, state.md, update requirements.md traceability)
+5. Compose each file in full, then write each exactly once — one Write per file, no draft-then-refine (P-1808): roadmap.md, state.md, update requirements.md traceability
 6. Return ROADMAP CREATED with summary
 
-Write files first, then return. This ensures artifacts persist even if context is lost.
+Write files first, then return — before the return, not early and often. One complete Write per file persists the artifacts without the rewrite churn (P-1808).
 </instructions>
 ", subagent_type="pan-roadmapper", model="{roadmapper_model}", description="Create roadmap")
 ```
@@ -983,7 +998,7 @@ Use AskUserQuestion:
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: create roadmap ([N] phases)" --files .planning/roadmap.md .planning/state.md .planning/requirements.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: create roadmap ([N] phases)" --files .planning/roadmap.md .planning/state.md .planning/requirements.md
 ```
 
 ## 8.5. Standards Recommendation
@@ -991,7 +1006,7 @@ node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: create roadmap ([
 **After roadmap is committed, offer standards selection based on project type.**
 
 ```bash
-RECOMMEND=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards recommend)
+RECOMMEND=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards recommend)
 ```
 
 If the command succeeds (project.md exists and project types detected):
@@ -1004,9 +1019,9 @@ Parse JSON for `project_types` and `recommendations` arrays.
 HIGH_IDS=$(echo "$RECOMMEND" | jq -r '.recommendations[] | select(.priority=="high") | .id')
 if [ -n "$HIGH_IDS" ]; then
   for id in $HIGH_IDS; do
-    node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards select "$id"
+    node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards select "$id"
   done
-  node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: add recommended standards" --files .planning/standards.md
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: add recommended standards" --files .planning/standards.md
 fi
 ```
 
@@ -1036,12 +1051,12 @@ Use AskUserQuestion:
 
 For each selected standard:
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards select [id]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards select [id]
 ```
 
 If any selected, commit:
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: add project standards" --files .planning/standards.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: add project standards" --files .planning/standards.md
 ```
 
 Display:
@@ -1058,7 +1073,7 @@ Run /pan:health --standards to check compliance anytime.
 
 ```bash
 if [ "$(git status --porcelain .planning/ 2>/dev/null)" ]; then
-  node ./.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: bundle remaining .planning artifacts (safety-net)" --files .planning/
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: bundle remaining .planning artifacts (safety-net)" --files .planning/
 fi
 ```
 

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

@@ -12,7 +12,7 @@ Manage the circular optimization loop — apply reports, check stats, control tr
 | `stats` | Show cumulative stats |
 | `trace init` | Start a new trace session |
 | `trace end` | Finalize current session |
-| `trace status` | Show active session |
+| `trace current` | Show active session |
 | `trace list` | List all sessions |
 
 ---
@@ -23,7 +23,7 @@ Manage the circular optimization loop — apply reports, check stats, control tr
 
 Run:
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize list
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize list
 ```
 
 Use the most recent `.md` report (the full opt-report, not the `-analysis.json`).
@@ -33,7 +33,7 @@ If `--report <filename>` was specified, use that file from `.planning/optimizati
 ### Step 2 — Run apply
 
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize apply [--report <path>]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize apply [--report <path>]
 ```
 
 ### Step 3 — Present results
@@ -63,7 +63,7 @@ If `--description "..."` was provided, extract it from the args.
 ### Step 2 — Initialize session
 
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init [--description "..."]
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace init [--description "..."]
 ```
 
 Show the user the session ID and confirm that:
@@ -76,17 +76,17 @@ Show the user the session ID and confirm that:
 ## trace end
 
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace end
 ```
 
 Show: session ID, event count, agent count, type breakdown.
 
 ---
 
-## trace status
+## trace current
 
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace current
 ```
 
 If active: show session ID and instruct how to view events.
@@ -97,7 +97,7 @@ If none: tell user to run `/pan:optimize trace init` before their next build.
 ## stats
 
 ```
-node .claude/pan-wizard-core/bin/pan-tools.cjs optimize stats
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize stats
 ```
 
 Present as a summary table:

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

@@ -13,7 +13,7 @@ Find current phase directory from most recently modified files:
 
 ```bash
 # Find most recent phase directory with work
-ls -lt .planning/phases/*/plan.md 2>/dev/null | head -1 | grep -oP 'phases/\K[^/]+'
+ls -lt .planning/phases/*/*-plan.md 2>/dev/null | head -1 | sed -n 's#.*phases/\([^/]*\)/.*#\1#p'
 ```
 
 If no active phase detected, ask user which phase they're pausing work on.