pan-wizard 3.22.0 → 3.25.0

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.

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

@@ -47,7 +47,7 @@ Exit.
 
 Read the phase artifacts (in order of priority):
 1. `${phase_dir}/*-summary.md` — what was implemented, files changed
-2. `${phase_dir}/context.md` — acceptance criteria, decisions
+2. `${phase_dir}/*-context.md` — acceptance criteria, decisions
 3. `${phase_dir}/*-verification.md` — user-verified scenarios (if UAT was done)
 
 If no summary.md exists:
@@ -341,7 +341,7 @@ If there are passing tests to commit:
 
 ```bash
 git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+git commit -m "test(phase-${phase_number}): add unit and E2E tests from phase-tests command"
 ```
 
 Present next steps:

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

@@ -542,6 +542,10 @@ Check for auto-advance trigger:
    ```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), so the rest of the chain and the P-1809 stop guard see the run as autonomous on disk (P-1810):
+   ```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:**
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Switch the model profile used by PAN agents. Controls which Claude model each agent uses, balancing quality vs token spend.
+Switch the model profile used by PAN agents. Controls which model tier each agent uses, balancing quality vs token spend.
 </purpose>
 
 <required_reading>
@@ -88,20 +88,23 @@ Agents will now use:
 
 [Show table from MODEL_PROFILES in pan-tools.cjs for selected profile]
 
-Example:
-| Agent | Model |
-|-------|-------|
-| pan-planner | opus |
-| pan-executor | sonnet |
-| pan-verifier | haiku |
+Example (`budget` — the only profile that steps agents below the reasoning
+tier; `quality` and `balanced` put every agent on `reasoning`):
+| Agent | Tier |
+|-------|------|
+| pan-planner | mid |
+| pan-executor | mid |
+| pan-verifier | fast |
 | ... | ... |
 
 Cost estimate:
 [Run: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs estimate-cost]
 Show the average cost multiplier for each profile (quality/balanced/budget)
-and highlight the selected profile. Example:
-  quality: 15.0× avg | balanced: 4.3× avg | budget: 2.2× avg
-                                              ^^^^^^^^^^^^^^^^ selected
+and highlight the selected profile — read the numbers from the command output,
+don't hardcode them (`quality` and `balanced` report the same multiplier).
+Example shape:
+  quality: <n>× avg | balanced: <n>× avg | budget: <n>× avg
+                                           ^^^^^^^^^^^^^^^^ selected
 
 Next spawned agents will use the new profile.
 ```

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

@@ -26,7 +26,7 @@ If `found` is false: Error and exit.
 ## Step 2: Check Existing Research
 
 ```bash
-ls .planning/phases/${PHASE}-*/research.md 2>/dev/null
+ls .planning/phases/*/*-research.md 2>/dev/null | grep -E "/0*${PHASE}-[^/]*/"
 ```
 
 If exists: Offer update/view/skip options.

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

@@ -67,7 +67,7 @@ ls .planning/phases/*/.continue-here*.md 2>/dev/null
 
 # Check for plans without summaries (incomplete execution)
 for plan in .planning/phases/*/*-plan.md; do
-  summary="${plan/PLAN/SUMMARY}"
+  summary="${plan%-plan.md}-summary.md"
   [ ! -f "$summary" ] && echo "Incomplete: $plan"
 done 2>/dev/null
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Interactive configuration of PAN workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.pan-wizard-core/defaults.json) for future projects.
+Interactive configuration of PAN workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.pan-wizard/defaults.json) for future projects.
 </purpose>
 
 <required_reading>
@@ -44,9 +44,9 @@ AskUserQuestion([
     header: "Model",
     multiSelect: false,
     options: [
-      { label: "Quality", description: "Opus everywhere except verification (highest cost)" },
-      { label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for execution/verification" },
-      { label: "Budget", description: "Sonnet for writing, Haiku for research/verification (lowest cost)" }
+      { label: "Quality", description: "reasoning tier for every agent — identical to balanced, so switching between the two changes nothing" },
+      { label: "Balanced (Recommended)", description: "reasoning tier for every agent (quality and balanced are identical post-COST-RESET); use budget to step down" },
+      { label: "Budget", description: "mid tier for writing, fast tier for research/verification (lowest cost)" }
     ]
   },
   {
@@ -153,20 +153,20 @@ AskUserQuestion([
     header: "Defaults",
     multiSelect: false,
     options: [
-      { label: "Yes", description: "New projects start with these settings (saved to ~/.pan-wizard-core/defaults.json)" },
+      { label: "Yes", description: "New projects start with these settings (saved to ~/.pan-wizard/defaults.json)" },
       { label: "No", description: "Only apply to this project" }
     ]
   }
 ])
 ```
 
-If "Yes": write the same config object (minus project-specific fields like `brave_search`) to `~/.pan-wizard-core/defaults.json`:
+If "Yes": write the same config object (minus project-specific fields like `brave_search`) to `~/.pan-wizard/defaults.json`:
 
 ```bash
-mkdir -p ~/.gsd
+mkdir -p ~/.pan-wizard
 ```
 
-Write `~/.pan-wizard-core/defaults.json` with:
+Write `~/.pan-wizard/defaults.json` with:
 ```json
 {
   "mode": <current>,
@@ -222,6 +222,6 @@ Quick commands:
 - [ ] Current config read
 - [ ] User presented with 7 settings (profile + 5 workflow toggles + git branching)
 - [ ] Config updated with model_profile, workflow, and git sections
-- [ ] User offered to save as global defaults (~/.pan-wizard-core/defaults.json)
+- [ ] User offered to save as global defaults (~/.pan-wizard/defaults.json)
 - [ ] Changes confirmed to user
 </success_criteria>

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

@@ -76,9 +76,20 @@ cat .planning/config.json 2>/dev/null
 
 </config-check>
 
+**Detect AUTO mode (P-1807 — gate parity with the rest of the chain):**
+
+```bash
+HAS_AUTO_FLAG=$(echo "$ARGUMENTS" | grep -c -- '--auto' || true)
+AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+```
+
+**AUTO is active** when `HAS_AUTO_FLAG` > 0 (the `--auto` flag exec-phase passes through), OR `AUTO_CFG` is `true`, OR config `mode` is `yolo`. Every `<if auto>` gate in this workflow keys on this condition — the same trigger `exec-phase.md` (offer_next), `plan-phase.md` (step 14) and `discuss-phase.md` (auto_advance) use.
+
+**P-1807 (2026-08, PanLoop finding 0):** these gates were previously `mode: yolo` alone. This file never read `--auto` or `workflow.auto_advance`, so on the template-default `mode: interactive`, exec-phase would announce "AUTO-ADVANCING → TRANSITION", this workflow would update state to the next phase, then route to the interactive "Next Up" menu and exit cleanly — the P-1801 Task spawn below was unreachable, and every autonomous run built exactly one phase while reporting success. Do not narrow these gates back to `mode` alone.
+
 **If all plans complete:**
 
-<if mode="yolo">
+<if auto (HAS_AUTO_FLAG > 0, or AUTO_CFG true, or mode yolo)>
 
 ```
 ⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
@@ -91,7 +102,7 @@ Proceed directly to cleanup_handoff step.
 
 </if>
 
-<if mode="interactive" OR="custom with gates.confirm_transition true">
+<if NOT auto — mode="interactive" OR="custom with gates.confirm_transition true">
 
 Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
 
@@ -157,8 +168,9 @@ Extract from result: `completed_phase`, `plans_executed`, `next_phase`, `next_ph
 
 <step name="archive_prompts">
 
-If prompts were generated for the phase, they stay in place.
-The `completed/` subfolder pattern from create-meta-prompts handles archival.
+If prompts were generated for the phase, they stay in place — plans and
+summaries remain in the phase directory as the durable record. No separate
+archival step is performed.
 
 </step>
 
@@ -361,6 +373,8 @@ Resume file: None
 
 <step name="offer_next_phase">
 
+**AUTO-mode terminal contract (P-1807):** when AUTO is active (the condition from `verify_completion`), this step has exactly two valid endings — **Route A ends with a `Task(...)` call actually issued** (not described, not deferred: issued), or **Route B reaches the milestone boundary**. Updating state.md and presenting a "Next Up" menu is NOT a valid AUTO ending — field runs (PanLoop, 2026-08-08) show that exact exit four times in five even with the gates fixed. If you notice you are composing a menu while AUTO is active, stop and execute the Route A spawn. Do not end your turn between the state update and the spawn.
+
 **MANDATORY: Verify milestone status before presenting next steps.**
 
 **Use the transition result from `pan-tools phase complete`:**
@@ -392,10 +406,12 @@ ls .planning/phases/*[X+1]*/*-context.md 2>/dev/null
 
 **If next phase exists:**
 
-<if mode="yolo">
+<if auto (HAS_AUTO_FLAG > 0, or AUTO_CFG true, or mode yolo — the P-1807 condition from verify_completion)>
 
 **P-1801 fix (v3.7.6):** In auto mode, **spawn the next phase as a Task subagent** — same pattern as `plan-phase.md`'s auto-advance to exec-phase. Prose-based "DO NOT exit. Read X" instructions (the v3.7.4 P-1701 attempt) were not behaviorally binding: the orchestrator returned from sub-agent calls and exited cleanly at the phase boundary. A `Task(...)` invocation is a tool call the orchestrator cannot ignore — control flow is forced into the next phase's workflow.
 
+**P-1807 (2026-08):** this gate was `mode: yolo` alone, which made the P-1801 spawn unreachable for `--auto` / `workflow.auto_advance` runs on interactive-mode projects — the exact symptom P-1801 fixed, reintroduced one gate higher. If exec-phase announced AUTO-ADVANCING, this branch MUST run and MUST end in the `Task(...)` call below; exiting after the state update is the regression.
+
 Cost trade-off: each Task spawn restarts context (loses the cumulative cache reads from the previous phase). Acceptable because: (1) cross-phase cache value is low — phase N's plan/research is mostly irrelevant to phase N+1's executor — and (2) reliability beats marginal cost optimization for autonomous runs.
 
 **If context.md exists for the next phase:**
@@ -489,7 +505,7 @@ Task(
 
 </if>
 
-<if mode="interactive" OR="custom with gates.confirm_transition true">
+<if NOT auto — mode="interactive" OR="custom with gates.confirm_transition true">
 
 **If context.md does NOT exist:**
 
@@ -551,7 +567,7 @@ Task(
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance false
 ```
 
-<if mode="yolo">
+<if auto (HAS_AUTO_FLAG > 0, or AUTO_CFG true, or mode yolo — the P-1807 condition from verify_completion)>
 
 ```
 Phase {X} marked complete.
@@ -565,7 +581,7 @@ Exit skill and invoke SlashCommand("/pan:milestone-done {version}")
 
 </if>
 
-<if mode="interactive" OR="custom with gates.confirm_transition true">
+<if NOT auto — mode="interactive" OR="custom with gates.confirm_transition true">
 
 ```
 ## ✓ Phase {X}: {Phase Name} Complete

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

@@ -12,28 +12,31 @@ Read all files referenced by the invoking prompt's execution_context before star
 Detect whether PAN is installed locally or globally by checking both locations and validating install integrity:
 
 ```bash
-# Check local first (takes priority only if valid)
-# Paths templated at install time for runtime compatibility
-LOCAL_VERSION_FILE="./.claude/pan-wizard-core/VERSION"
-LOCAL_MARKER_FILE="./.claude/pan-wizard-core/workflows/update.md"
-GLOBAL_VERSION_FILE="$HOME/.claude/pan-wizard-core/VERSION"
-GLOBAL_MARKER_FILE="$HOME/.claude/pan-wizard-core/workflows/update.md"
-
-if [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
-  cat "$LOCAL_VERSION_FILE"
-  echo "LOCAL"
-elif [ -f "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then
-  cat "$GLOBAL_VERSION_FILE"
-  echo "GLOBAL"
+# There is ONE install location per install. The installer templates the
+# canonical ~/.claude/ prefix to this install's real path, and the SHAPE of that
+# templated prefix reveals the scope: a --local install is cwd-relative ("./…"),
+# a --global install is an absolute path. Deriving scope from the single
+# templated path avoids the collapsed dual-path detection that mis-ran every
+# global update as --local (N2 regression fix, ADR audit 2026-08).
+VERSION_FILE="~/.claude/pan-wizard-core/VERSION"
+MARKER_FILE="~/.claude/pan-wizard-core/workflows/update.md"
+case "$VERSION_FILE" in
+  ./*) SCOPE="LOCAL" ;;
+  *)   SCOPE="GLOBAL" ;;
+esac
+
+if [ -f "$VERSION_FILE" ] && [ -f "$MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$VERSION_FILE"; then
+  cat "$VERSION_FILE"
+  echo "$SCOPE"
 else
   echo "UNKNOWN"
 fi
 ```
 
-Parse output:
-- If last line is "LOCAL": local install is valid; installed version is first line; use `--local`
-- If last line is "GLOBAL": local missing/invalid, global install is valid; installed version is first line; use `--global`
-- If "UNKNOWN": proceed to install step (treat as version 0.0.0)
+Parse output (there is ONE install; scope is derived from the shape of the single templated prefix):
+- If last line is "LOCAL": this install is local-scoped (templated prefix is `./`-relative); installed version is first line; use `--local`
+- If last line is "GLOBAL": this install is global-scoped (templated prefix is an absolute path); installed version is first line; use `--global`
+- If "UNKNOWN": the VERSION/marker files are missing or invalid; proceed to install step (treat as version 0.0.0)
 
 **If VERSION file missing:**
 ```
@@ -166,7 +169,7 @@ Clear the update cache so statusline indicator disappears:
 
 **If LOCAL install:**
 ```bash
-rm -f ./.claude/cache/pan-update-check.json
+rm -f ~/.claude/cache/pan-update-check.json
 ```
 
 **If GLOBAL install:**
@@ -184,9 +187,9 @@ Format completion message (changelog was already shown in confirmation step):
 ║  PAN Updated: v1.5.10 → v1.5.15                           ║
 ╚═══════════════════════════════════════════════════════════╝
 
-⚠️  Restart Claude Code to pick up the new commands.
+⚠️  Restart your AI coding tool to pick up the new commands.
 
-[View full changelog](https://github.com/pan-wizard-core/blob/main/CHANGELOG.md)
+[View full changelog](https://github.com/oharms/PanWizard/blob/main/CHANGELOG.md)
 ```
 </step>