@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/workflows/execute-phase.md

@@ -29,7 +29,7 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
   Claude Code agent per #853, or a non-Claude runtime), use sequential inline execution as
   the fallback for executor parallelization only. If `Agent` IS available (top-level Claude
   Code), you MUST spawn pp-executor agents — inline execution is not authorized. Check for
-  actual tool availability, not runtime name.
+  actual tool availability, not runtime name. Every inline path follows `EXECUTOR_HOOK_FRAGMENTS` as in `check_interactive_mode`.
 
 **Fallback rule:** If a spawned agent completes its work (commits visible, SUMMARY.md exists) but
 the orchestrator never receives the completion signal, treat it as successful based on spot-checks
@@ -69,8 +69,7 @@ Parse `$ARGUMENTS` before loading any context:
 
 - First positional token → `PHASE_ARG`
 - Optional `--wave N` → `WAVE_FILTER`
-- Optional `--gaps-only` → `GAPS_ONLY=true` (only `gap_closure: true` plans)
-- Optional `--tier light|standard|heavy` → `TIER_FLAG="--tier=<value>"` (one word, so zsh passes it as one argument; the phase's ceremony tier for this run; passed to init, dispatch plan and render-hooks)
+- Optional `--gaps-only` keeps its current meaning
 - Optional `--cross-ai` → `CROSS_AI_FORCE=true` (force all plans through cross-AI execution)
 - Optional `--no-cross-ai` → `CROSS_AI_DISABLED=true` (disable cross-AI for this run, overrides config and frontmatter)
 - Optional `--unattended` → `UNATTENDED=true` — set by `/pp:autonomous`; prompt sites marked `U-En` apply the rules in `pp-core/references/autonomous-best-effort.md` (Read it at the first such site)
@@ -83,7 +82,7 @@ Load all context in one call:
 
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
-INIT=$(pp_run query init.execute-phase "${PHASE_ARG}" ${TIER_FLAG})
+INIT=$(pp_run query init.execute-phase "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS=$(pp_run query agent-skills pp-executor)
 ```
@@ -168,7 +167,7 @@ or absence of the `Agent()` subagent API. If running under Copilot, force sequen
 execution regardless of the `parallelization` setting — Copilot's subagent completion
 signals are unreliable (see `<runtime_compatibility>`). Set `COPILOT_SEQUENTIAL=true`
 internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s
-inline path for each plan.
+inline path for each plan. That inline path carries `EXECUTOR_HOOK_FRAGMENTS` as in `check_interactive_mode`.
 
 **REQUIRED — Sync chain flag with intent.** If user invoked manually (no `--auto`), clear the ephemeral chain flag from any previous interrupted `--auto` chain. This prevents stale `_auto_chain_active: true` from causing unwanted auto-advance. This does NOT touch `workflow.auto_advance` (the user's persistent settings preference). You MUST execute this bash block before any config reads:
 ```bash
@@ -183,10 +182,21 @@ Resolve `MVP_MODE` once via the centralized `phase.mvp-mode` query verb (precede
 MVP_FLAG_ARG=""
 if [[ "$ARGUMENTS" =~ (^|[[:space:]])--mvp([[:space:]]|$) ]]; then MVP_FLAG_ARG="--cli-flag"; fi
 MVP_MODE=$(pp_run query phase.mvp-mode "${PHASE_NUMBER}" $MVP_FLAG_ARG --pick active)
-EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG}) || exit 1
-TDD_MODE=$(pp_run loop render-hooks execute:post --active-cap tdd) || exit 1
+EXECUTE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:post --raw)
+TDD_MODE=$(pp_run loop render-hooks execute:post --active-cap tdd)
+EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw)
+EXECUTOR_HOOK_FRAGMENTS=$(pp_run loop render-hooks execute:pre --into executor)
+printf '%s' "$EXECUTE_PRE_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('EXECUTE_PRE_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
 
+<step name="execute_pre_dispatch">
+**`execute:pre` capability dispatch — fetch, then decide (GATE-03).**
+
+Runs before `safe_resume_gate` — the first step that can spawn an executor — so the gate decides
+before any code is written. Read and execute
+`pp-core/workflows/execute-phase/steps/execute-pre-dispatch.md`.
+</step>
+
 <step name="safe_resume_gate">
 Before trusting `STATE.md` or dispatching any executor, derive `CURRENT_PLAN_ID`
 from the active incomplete plan in `INIT`, then search recent history:
@@ -275,6 +285,9 @@ checkpoints between tasks. The user can review, modify, or redirect work at any
 
    c. **If "Execute":** Read and follow `~/.claude/pp-core/workflows/execute-plan.md` **inline**
       (do NOT spawn a subagent). Execute tasks one at a time.
+      The inline executor follows `EXECUTOR_HOOK_FRAGMENTS` (computed in the hooks fence above) as
+      its contract exactly as a spawned executor would: in standards mode it is the vault's
+      execute:pre executor fragment; in practices mode it is empty.
 
    d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address
       their feedback before continuing. Otherwise proceed to next task.
@@ -346,10 +359,6 @@ This updates Status, Last Activity, Current focus, Current Position, and plan co
 Read and execute `pp-core/workflows/execute-phase/steps/client-context-gate.md` — Pareto client-context gate (inert without `.platform-bindings.json`; confirms the Phase 9 CLAUDE.md block first).
 </step>
 
-<step name="execute_pre_vault">
-Before any executor: `EXECUTE_PRE_HOOKS_JSON=$(pp_run loop render-hooks execute:pre --raw) || exit 1`. For an active `capId == "vault"` step, Read and execute `pp-core/workflows/execute-phase/steps/vault-fetch.md`; then, for an active `vault.status` gate, set `VAULT_GATE_POINT=execute` and Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md`. None active → skip.
-</step>
-
 <step name="discover_and_group_plans">
 Load plan inventory with wave grouping in one call:
 
@@ -357,7 +366,7 @@ Load plan inventory with wave grouping in one call:
 PLAN_INDEX=$(pp_run query phase-plan-index "${PHASE_NUMBER}")
 ```
 
-Parse JSON for: `phase`, `plans[]` (each with `id`, `title`, `wave`, `serial_group`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `serial_groups`, `incomplete`, `has_checkpoints`. A plan's `{plan_title}` is its `title` (legacy plans without one: its objective, 3-8 words).
+Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
 
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If `WAVE_FILTER` is set: also skip plans whose `wave` does not equal `WAVE_FILTER`.
 
@@ -375,7 +384,7 @@ Report:
 
 | Wave | Plans | What it builds |
 |------|-------|----------------|
-| 1 | 01-01, 01-02 | 01-01 {plan_title}; 01-02 {plan_title} |
+| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
 | 2 | 01-03 | ... |
 ```
 </step>
@@ -387,7 +396,7 @@ Read and execute `pp-core/workflows/execute-phase/steps/cross-ai-delegation.md`.
 </step>
 
 <step name="execute_waves">
-Execute each selected wave in sequence. Within a wave, follow its `run`: `parallel` — worktree spawns run alongside each other, main-checkout spawns one at a time; `sequential` — one spawn at a time.
+Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
 
 **Orchestrator cwd-drift guard (FIRST ACTION at execute_waves entry — #48):**
 
@@ -418,14 +427,6 @@ export ORCHESTRATOR_WT
 cd "$ORCHESTRATOR_WT" || { echo "FATAL: cannot cd to orchestrator worktree '$ORCHESTRATOR_WT' (#48)." >&2; exit 1; }
 ```
 
-**Dispatch plan (load once, after the cwd guard and cross-AI delegation):** what this run spawns, builds, tests and commits, computed by `phase.dispatch-plan`. Spawn exactly its spawns; never re-derive waves, serial groups, isolation or builds.
-
-```bash
-DISPATCH_PLAN=$(pp_run query phase.dispatch-plan "${PHASE_NUMBER}" --use-worktrees "${USE_WORKTREES:-true}" ${WAVE_FILTER:+--wave "$WAVE_FILTER"} ${GAPS_ONLY:+--gaps-only} ${TIER_FLAG})
-```
-
-`stages.execute.waves[]` in order, each with `spawns[]` (`kind` `serial-group`|`plan`, `plans[]` in run order with `id`, `title`, `build`, `touched_tests`; `isolation` `main-checkout`|`worktree`; `build`; `checkpoint`), `run`, `merge`, `build`, `suite_runs` (1), `tracking_commits` (1), `tracking.requirements`, `defects[]`. Report `totals` (spawns, suite runs, tracking commits). Non-empty `filters.lower_wave_incomplete` → STOP: finish the earlier waves first.
-
 **Stream-idle-timeout prevention — checkpoint heartbeats (#2410):**
 
 Multi-plan phases can accumulate enough subagent context that the Claude API
@@ -448,14 +449,39 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
 **For each wave:**
 
-1. **Intra-wave files_modified overlap check (BEFORE spawning — computed):** the wave's `defects[]` lists any two plans in it that share a source file, and any two plans in different spawns that share any file. Plans of one serial group share non-source files by design — not a defect; their one spawn runs them one after another.
+1. **Intra-wave files_modified overlap check (BEFORE spawning):**
+
+   Before spawning any agents for this wave, inspect the `files_modified` list of all plans
+   in the wave. Check every pair of plans in the wave — if any two plans share even one file
+   in their `files_modified` lists, those plans have an implicit dependency and MUST NOT run
+   in parallel.
+
+   **Detection algorithm (pseudocode):**
+   ```
+   seen_files = {}
+   overlapping_plans = []
+   for each plan in wave_plans:
+     for each file in plan.files_modified:
+       if file in seen_files:
+         overlapping_plans.add(plan, seen_files[file])  # both plans overlap on this file
+       else:
+         seen_files[file] = plan
+   ```
 
-   **If `defects` is non-empty:** warn the user with each defect's `message`:
+   **If overlap is detected:**
+   - Warn the user:
      ```
      ⚠ Intra-wave files_modified overlap detected in Wave {N}:
-       {defect.message}
+       Plan {A} and Plan {B} both modify {file}
+       Running these plans sequentially to avoid parallel worktree conflicts.
      ```
-   The wave's `run` is then `sequential` — run its spawns one at a time — and the overlap is a planning defect the user may replan.
+   - Override `PARALLELIZATION` to `false` for this wave only — run all plans in the wave
+     sequentially regardless of the global parallelization setting.
+   - This is a safety net for plans that were incorrectly assigned to the same wave.
+     The planner should have caught this; flag it as a planning defect so the user can
+     replan the phase if desired.
+
+   **If no overlap:** proceed normally (parallel if `PARALLELIZATION=true`).
 
 2. **Describe what's being built (BEFORE spawning):**
 
@@ -481,19 +507,21 @@ increases monotonically across waves. `{status}` is `complete` (success),
    ---
    ## Wave {N}
 
-   **{Plan ID}: {plan_title}**
+   **{Plan ID}: {Plan Name}**
    {2-3 sentences: what this builds, technical approach, why it matters}
 
-   Spawning {count} agent(s) — one per spawn in this wave... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
+   Spawning {count} agent(s)... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
    ---
    ```
 
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2.5. **Per-plan worktree decision (from the dispatch plan):** a spawn's `isolation` is the decision. `phase.dispatch-plan` makes it from `USE_WORKTREES` and `.gitmodules`: a serial group, a plan touching a submodule path, or a submodule-project plan with no `files_modified` gets `main-checkout`. For a `main-checkout` spawn set `USE_WORKTREES_FOR_PLAN=false`; for a `worktree` spawn leave it unset and append its plan ids to `WAVE_WORKTREE_PLANS`.
+2.5. **Per-plan worktree decision (run for each plan in this wave BEFORE its dispatch):**
 
-   The dispatch branches in step 3 below MUST gate on `USE_WORKTREES_FOR_PLAN` for the current spawn, not on the project-level `USE_WORKTREES`.
+   Read and execute `pp-core/workflows/execute-phase/steps/per-plan-worktree-gate.md` for each plan. It extracts `PLAN_FILES` from the plan's JSON, intersects against `SUBMODULE_PATHS` (with normalization, bidirectional matching, and glob-prefix handling), and sets `USE_WORKTREES_FOR_PLAN` to `false` when the plan touches a submodule path. Append `plan_id` to a `WAVE_WORKTREE_PLANS` accumulator when `USE_WORKTREES_FOR_PLAN != false`.
+
+   The dispatch branches in step 3 below MUST gate on `USE_WORKTREES_FOR_PLAN` for the current plan, not on the project-level `USE_WORKTREES`.
 
 3. **Spawn executor agents:**
 
@@ -502,8 +530,6 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
    `[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)`
 
-   **Serial-group spawn** (`kind: serial-group`): Read and execute `pp-core/workflows/execute-phase/steps/serial-group-dispatch.md` — ONE executor on the main checkout for the whole group. The rest of step 3 covers `kind: plan` spawns.
-
    Pass paths only — executors read files themselves with their fresh context window.
    For 200k models, this keeps orchestrator context lean (~10-15%).
    For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.
@@ -540,7 +566,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    ```text
    Agent(
      subagent_type="pp-executor",
-     description="Execute plan {plan_number} of phase {phase_number}: {plan_title}",
+     description="Execute plan {plan_number} of phase {phase_number}",
      # Only include model= when executor_model is an explicit model name.
      # When executor_model is "inherit", omit this parameter entirely so
      # Claude Code inherits the orchestrator model automatically.
@@ -548,13 +574,11 @@ increases monotonically across waves. `{status}` is `complete` (success),
      isolation="worktree",
      prompt="
        <objective>
-       Execute plan {plan_number} ({plan_title}) of phase {phase_number}-{phase_name}.
+       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
        Commit each task atomically. Create SUMMARY.md.
        Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
        </objective>
 
-       <dispatch tracking="orchestrator" suite="orchestrator" build="{spawn.build}" />
-
        <worktree_branch_check>
        ORCHESTRATOR build-time embed (NOT a sub-agent runtime step): before this dispatch, read `pp-core/references/worktree-branch-check.md`, substitute `{EXPECTED_BASE}` with the base SHA captured above ({EXPECTED_BASE}), and replace this note with that fragment's `<worktree_branch_check>` block so the dispatched prompt carries the runnable guard verbatim — do not pass this instruction through in its place.
        Per-commit HEAD/cwd-drift/path-guard: `agents/pp-executor.md` steps 0/0a/0b + `references/worktree-path-safety.md` (in <execution_context>).
@@ -607,6 +631,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
        </files_to_read>
 
        ${AGENT_SKILLS}
+       ${EXECUTOR_HOOK_FRAGMENTS}
 
        <mcp_tools>
        If CLAUDE.md or project instructions reference MCP tools (e.g. jCodeMunch, context7,
@@ -643,14 +668,15 @@ increases monotonically across waves. `{status}` is `complete` (success),
        </sequential_execution>
    ```
 
-   Everything else is the worktree-mode prompt, `<dispatch>` tag included — the orchestrator owns tracking for every spawn:
+   The sequential mode Agent prompt uses the same structure as worktree mode but with these differences in success_criteria — since there is only one agent writing at a time, there are no shared-file conflicts:
 
    ```
        <success_criteria>
        - [ ] All tasks executed
        - [ ] Each task committed individually
        - [ ] SUMMARY.md created in plan directory
-       - [ ] No tracking-file writes (the orchestrator advances them once per wave)
+       - [ ] STATE.md updated with position and decisions
+       - [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
        </success_criteria>
    ```
 
@@ -693,7 +719,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    for activity. If no completion signal, no SUMMARY.md, and no expected-branch
    commits appear for `${EXECUTOR_STALL_THRESHOLD_MINUTES}` minutes, pause and
    ask for one recovery path: `continue waiting`, `kill and retry`, or
-   `kill and switch to inline execution` (U-E7).
+   `kill and switch to inline execution` (U-E7). The inline switch follows `EXECUTOR_HOOK_FRAGMENTS` too.
 
    If the stalled executor ran in an isolated worktree, `kill and switch to inline execution` edits the primary checkout — see worktree recovery policy (`execute-phase/steps/worktree-recovery-policy.md`). Prefer `kill and retry` in a fresh worktree; inline execution requires explicit confirmation, never the default.
 
@@ -791,7 +817,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
    **When to skip step 5.5:**
 
-   **If no spawn in this wave used worktree isolation** (the wave's `merge.cleanup` is false — `WAVE_WORKTREE_PLANS` from step 2.5 is empty): all agents ran on the main working tree — skip this step entirely.
+   **If no plan in this wave used worktree isolation** (project-level `USE_WORKTREES=false` OR every plan in the wave had `USE_WORKTREES_FOR_PLAN=false` — i.e. `WAVE_WORKTREE_PLANS` from step 2.5 is empty): all agents ran on the main working tree — skip this step entirely.
 
    **If the orchestrator merged via custom messages (cross-wave-dependency deviation):** the templated cleanup loop above was not triggered for those merges. Run the cleanup-tail snippet above instead. After the snippet completes, proceed to step 5.6.
 
@@ -803,12 +829,10 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
 5.6. **Post-merge build & test gate:**
 
-   Once per wave, after the merge step (whatever ran: worktrees, a serial group, main-checkout
-   plans), run a build and then the project's full test suite — exactly once per wave
-   (`suite_runs: 1`), by the orchestrator, never per plan. Skip the build (Step A) when the
-   wave's `build` is false (no plan in it touches source). This catches cross-plan integration
-   issues that per-plan checks cannot detect (e.g., conflicting type definitions, removed
-   exports, import changes, link errors).
+   After merging all worktrees in a wave (parallel mode), or after the last plan completes
+   (serial mode), run a build and then the project's test suite to catch cross-plan
+   integration issues that individual worktree self-checks cannot detect (e.g., conflicting
+   type definitions, removed exports, import changes, link errors).
 
    This addresses the Generator self-evaluation blind spot identified in Anthropic's
    harness engineering research: agents reliably report Self-Check: PASSED even when
@@ -816,28 +840,25 @@ increases monotonically across waves. `{status}` is `complete` (success),
 
    Read and execute `pp-core/workflows/execute-phase/steps/post-merge-gate.md`.
 
-5.7. **Post-wave tracking (every wave, once, by the orchestrator; skip if tests failed):**
+5.7. **Post-wave shared artifact update (when at least one plan used worktrees, skip if tests failed):**
 
-   No executor writes tracking files under execute-phase (each prompt carries `<dispatch tracking="orchestrator">`), worktree or main checkout alike. After the merge and the suite, the orchestrator alone:
-   refreshes the plan rows and the Built state with `roadmap update-plan-progress`;
-   advances STATE, records the wave's `tracking.requirements` (`requirements.mark-complete`) and the `key-decisions` of its SUMMARY.md files (`state.add-decision`);
-   makes the wave's ONE tracking commit (`tracking_commits: 1`).
+   When **any** executor agent in this wave ran with `isolation="worktree"`, that agent skipped STATE.md and ROADMAP.md updates to avoid last-merge-wins overwrites. The orchestrator is the single writer for these files. After worktrees are merged back, update shared artifacts once for every completed plan in the wave (worktree-mode plans **and** sequential plans that ran on the main tree but deferred to the orchestrator for tracking writes).
 
    **Only update tracking when tests passed (TEST_EXIT=0).**
    If tests failed or timed out, skip the tracking update — plans should
    not be marked as complete when integration tests are failing or inconclusive.
 
    ```bash
-   # Timeout (124) is inconclusive — do NOT mark plans complete
+   # Guard: only update tracking if post-merge tests passed
+   # Timeout (124) is treated as inconclusive — do NOT mark plans complete
    if [ "${TEST_EXIT}" -eq 0 ]; then
-     # Plan rows and the Built state (D-08-12); phase completion is phase.complete's, in update_roadmap.
+     # Refresh plan rows and the Built state from disk (D-08-12). Phase completion is NOT
+     # written here — phase.complete does that in update_roadmap, after the execute:post gate.
      pp_run query roadmap.update-plan-progress "${PHASE_NUMBER}"
-     pp_run query state.update-progress
-     # WAVE_REQ_IDS: this wave's tracking.requirements from DISPATCH_PLAN, space-separated
-     [ -n "${WAVE_REQ_IDS:-}" ] && pp_run query requirements.mark-complete ${WAVE_REQ_IDS}
-     pp_run query state.record-session --stopped-at "Phase ${PHASE_NUMBER} wave ${N} complete" --resume-file "None"
-     if ! git diff --quiet .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md 2>/dev/null; then
-       pp_run query commit "docs(phase-${PHASE_NUMBER}): update tracking after wave ${N}" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+
+     # Only commit tracking files if they actually changed
+     if ! git diff --quiet .planning/ROADMAP.md .planning/STATE.md 2>/dev/null; then
+       pp_run query commit "docs(phase-${PHASE_NUMBER}): update tracking after wave ${N}" --files .planning/ROADMAP.md .planning/STATE.md
      fi
    elif [ "${TEST_EXIT}" -eq 124 ]; then
      echo "⚠ Skipping tracking update — test suite timed out. Plans remain in-progress. Run tests manually to confirm."
@@ -846,48 +867,35 @@ increases monotonically across waves. `{status}` is `complete` (success),
    fi
    ```
 
+   **If no plan in this wave used worktrees** (project-level `USE_WORKTREES=false` OR `WAVE_WORKTREE_PLANS` is empty): sequential agents already updated STATE.md and ROADMAP.md themselves — skip this step.
+
 5.75. **Execute:wave:post capability dispatch:**
 
    After worktree merge, post-merge tests, and tracking updates, dispatch capability hooks registered at `execute:wave:post`. The primary hook is the `ui.safety-gate` gate from the UI capability — it verifies that any frontend files changed in this wave conform to the UI-SPEC contract.
 
    ```bash
-   WAVE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:wave:post --raw) || exit 1
+   WAVE_POST_HOOKS_JSON=$(pp_run loop render-hooks execute:wave:post --raw)
+   printf '%s' "$WAVE_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('WAVE_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
    ```
 
-   Read the `activeHooks` array from `WAVE_POST_HOOKS_JSON` in-context (do NOT pipe through a shell parser).
+   Read the `activeHooks` array from the printed `WAVE_POST_HOOKS_JSON=` line, in-context (do NOT pipe through a shell parser).
 
    **If `activeHooks` is empty or absent:** Skip silently to step 5.8.
 
-   **For each active entry where `kind == "gate"`** (process in array order), run the gate check:
-
-   ```bash
-   GATE_RESULT=$(pp_run check ${hook.check.query} "${PHASE_NUMBER}" --raw)
-   CHECK_EXIT=$?
-   ```
-
-   **Step 1 — did the CHECK COMMAND itself succeed?**
-
-   If the check command failed (non-zero `CHECK_EXIT`, empty output, or unparseable JSON):
-   - `onError == "halt"` → treat as a fatal error: stop wave completion, do NOT proceed to step 5.8, and surface: `⚠ Gate check command failed ({hook.capId}): command error. Resolve before continuing.`
-   - `onError == "skip"` → log a warning and continue to the next hook. Do NOT read `GATE_RESULT.block`.
-
-   **Step 2 — read `GATE_RESULT.block` (boolean).** This step is only reached when the command succeeded.
-
-   - **Blocking gate (`hook.blocking == true`) AND `GATE_RESULT.block == true`:** HALT — stop wave completion, do NOT proceed to step 5.8, and present:
-
-     ```
-     ⚠ Wave {N} blocked by capability gate ({hook.capId}): {GATE_RESULT.message}
-     Resolve before continuing to next wave.
-     ```
-
-     This halt is **not** bypassed by `onError` — `onError` only covers command errors (step 1 above), not the gate's block decision.
-
-   - **Non-blocking gate (`hook.blocking == false`):** never halts. If `GATE_RESULT.block` is `true` (or non-empty `message`), print `⚠ {hook.capId} advisory (wave {N}): {GATE_RESULT.message}`, then:
-     - If `GATE_RESULT.spawn_mapper == true` OR `GATE_RESULT.directive == "auto-remap"`: spawn `pp-codebase-mapper` per `execute-phase/steps/codebase-drift-gate.md`; pass `--paths {GATE_RESULT.affected_paths}`. Continue regardless (wave NOT failed by remap failure).
-     - Otherwise: continue after advisory.
-     - If block `false` and no `message`: continue silently.
-
-   - **Blocking gate (`hook.blocking == true`) AND `GATE_RESULT.block == false`:** continue silently.
+   **Otherwise**, set `GATE_POINT=execute:wave:post`, `GATE_HOOKS_JSON=$WAVE_POST_HOOKS_JSON`,
+   `GATE_POSITIONAL_ARG="${PHASE_NUMBER}"` — preserving the positional phase-number argument this
+   call site has always passed — and `GATE_WS` to the active workstream name (empty in flat mode),
+   without which a phase-number positional cannot resolve on a partitioned project, then Read and follow
+   `pp-core/workflows/execute-phase/steps/check-query-gate.md`. That file is the single generic
+   `check.query` gate enforcer (GATE-02, D-VH-7): it owns the two-step contract (did the command
+   succeed? → then read the boolean `block`) and the halt. Do not restate its loop here.
+
+   **After the enforcer returns without halting**, perform this call site's own advisory follow-up
+   for each non-blocking entry it reported: if the verdict carried `spawn_mapper == true` OR
+   `directive == "auto-remap"`, spawn `pp-codebase-mapper` per
+   `execute-phase/steps/codebase-drift-gate.md`, passing `--paths {affected_paths}`. Continue
+   regardless — a remap failure never fails the wave. The enforcer owns the halt decision; this
+   directive handling is the host's, not the enforcer's.
 
    **When all active gates are processed without a blocking halt:** continue to step 5.8.
 
@@ -943,7 +951,7 @@ increases monotonically across waves. `{status}` is `complete` (success),
    ---
    ## Wave {N} Complete
 
-   **{Plan ID}: {plan_title}**
+   **{Plan ID}: {Plan Name}**
    {What was built — from SUMMARY.md}
    {Notable deviations, if any}
 
@@ -989,7 +997,45 @@ increases monotonically across waves. `{status}` is `complete` (success),
 9. **Proceed to next wave.**
 </step>
 <step name="checkpoint_handling">
-Plans with `autonomous: false` require user interaction. When an executor returns a checkpoint, Read and execute `pp-core/workflows/execute-phase/steps/checkpoint-handling.md` (auto-mode rules, continuation-agent flow).
+Plans with `autonomous: false` require user interaction.
+**Auto-mode checkpoint handling:**
+Read auto-advance config (chain flag OR user preference — same boolean as `check.auto-mode`):
+```bash
+AUTO_MODE=$(pp_run query check auto-mode --pick active 2>/dev/null || echo "false")
+```
+
+When executor returns a checkpoint AND (`UNATTENDED` or `AUTO_MODE`) is true (U-E1):
+- **human-action**, or package legitimacy — ANY of `**Gate:** blocking-human` in the return (the executor copies the task's `gate` attribute there), `gate="blocking-human"`, or `what-built` begins `Package`; the last two are the fallback for a return that predates the `Gate:` line → hard stop: present to user (below).
+- **human-verify** (other) → continuation with `{user_response}` = `"DEFERRED — not verified by a human (unattended run); record this checkpoint as not done in the SUMMARY and continue"`; log `⏭ Checkpoint deferred (recorded, not approved)`.
+- **decision** → continuation with the option marked recommended, else the first; log `⚡ Auto-selected: [option]`.
+
+**Standard flow (neither flag, human-action, or blocking-human):**
+
+1. Spawn agent for checkpoint plan
+2. Agent runs until checkpoint task or auth gate → returns structured state
+3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
+4. **Present to user:**
+   ```
+   ## Checkpoint: [Type]
+
+   **Plan:** 03-03 Dashboard Layout
+   **Progress:** 2/3 tasks complete
+
+   [Checkpoint Details from agent return]
+   [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
+7. Continuation agent verifies previous commits, continues from resume point
+8. Repeat until plan completes or user stops
+
+**Fresh agent, not resume:** resume breaks with parallel tool calls.
+
+**Checkpoints in parallel waves:** Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.
 </step>
 
 <step name="aggregate_results">
@@ -1016,10 +1062,13 @@ After all waves:
 
 **Security gate check:**
 ```bash
-VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG}) || exit 1
+VERIFY_POST_HOOKS_JSON=$(pp_run loop render-hooks verify:post --raw)
+printf '%s' "$VERIFY_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('VERIFY_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
+**Trace gate.** Read `pp-core/workflows/execute-phase/steps/verify-post-gate.md`.
+
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "secure-phase"`.
 
 If no active secure-phase step hook exists: skip.
@@ -1074,7 +1123,8 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
 
 **Capability gate:**
 ```bash
-EXECUTE_POST_HOOKS_JSON=${EXECUTE_POST_HOOKS_JSON:-$(pp_run loop render-hooks execute:post --raw --phase "${PHASE_NUMBER}" ${TIER_FLAG})} || exit 1
+EXECUTE_POST_HOOKS_JSON=${EXECUTE_POST_HOOKS_JSON:-$(pp_run loop render-hooks execute:post --raw)}
+printf '%s' "$EXECUTE_POST_HOOKS_JSON" | node -e "let h=[];try{h=JSON.parse(require('fs').readFileSync(0,'utf-8')).activeHooks||[]}catch{}console.log('EXECUTE_POST_HOOKS_JSON='+JSON.stringify({activeHooks:h}))"
 ```
 
 Resolve active step hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "code-review"`.
@@ -1101,17 +1151,11 @@ Code review found issues. Consider running:
 
 **Error handling:** If the Skill invocation fails or throws, catch the error, display "Code review encountered an error (non-blocking): {error}" and proceed to gate dispatch. Review failures must never block execution.
 
-**Execute:post gate hook dispatch.** After code review, dispatch all active gate hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "gate"`:
-
-For each active gate hook:
-```bash
-GATE_RESULT=$(pp_run check ${hook.check.query} "${PHASE_NUMBER}" --raw)
-CHECK_EXIT=$?
-```
+**Execute:post gate hook dispatch.** After code review, dispatch all active gate hooks from `EXECUTE_POST_HOOKS_JSON` where `kind == "gate"`. If none are active, skip silently.
 
-**Gate evaluation** uses the same two-step contract as `execute:wave:post` above: **Step 1** — if the check command failed (non-zero `CHECK_EXIT`, empty/unparseable output), `onError == "halt"` stops and surfaces the error, `onError == "skip"` warns and continues to the next hook (do not read `block`). **Step 2** (command succeeded) — a blocking gate (`hook.blocking == true`) halts on `GATE_RESULT.block == true` with its message/table (never bypassed by `onError`); an advisory gate (`hook.blocking == false`) shows its `table`/summary when `block == true` or `message` is non-empty, then continues; a blocking gate with `block == false` continues silently.
+Set `GATE_POINT=execute:post`, `GATE_HOOKS_JSON=$EXECUTE_POST_HOOKS_JSON`, `GATE_POSITIONAL_ARG="${PHASE_NUMBER}"` and `GATE_WS` to the active workstream name (empty in flat mode) — without it the phase-number positional cannot resolve on a partitioned project, and this is the point where the blocking `vault.trace` gate is declared — then Read and follow `pp-core/workflows/execute-phase/steps/check-query-gate.md` — the same single generic `check.query` gate enforcer used at `execute:pre` and `execute:wave:post` (GATE-02, D-VH-7). It owns the two-step contract (did the command succeed? → then read the boolean `block`) and the halt. Do not restate its loop here.
 
-**TDD review escalation (overrides the advisory default for the `tdd.review-checkpoint` gate only).** The tdd `execute:post` gate is declared `blocking: false`, so by the generic contract above it displays its `message`/table and continues. There is ONE documented exception (see `~/.claude/pp-core/references/execute-mvp-tdd.md`): when `MVP_MODE=true` AND `TDD_MODE=true` AND `GATE_RESULT.block == true` (one or more TDD plans miss a RED or GREEN gate commit), the end-of-phase TDD review escalates from advisory to **blocking under MVP+TDD** — refuse to mark the phase complete and present:
+**TDD review escalation (overrides the advisory default for the `tdd.review-checkpoint` gate only).** The tdd `execute:post` gate is declared `blocking: false`, so the enforcer displays its `message`/table and continues. There is ONE documented exception (see `~/.claude/pp-core/references/execute-mvp-tdd.md`), applied by this host workflow *after* the enforcer returns: when `MVP_MODE=true` AND `TDD_MODE=true` AND the enforcer reported a `true` block verdict for `tdd.review-checkpoint` (one or more TDD plans miss a RED or GREEN gate commit), the end-of-phase TDD review escalates from advisory to **blocking under MVP+TDD** — refuse to mark the phase complete and present:
 
 ```
 Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under MVP+TDD.
@@ -1120,7 +1164,7 @@ Resolve and re-run /pp:execute-phase, or override with /pp:execute-phase {phase}
 
 (`--force-mvp-gate` is the documented, not-yet-implemented escape hatch.) Outside MVP+TDD, TDD-review violations remain advisory (table shown, execution continues).
 
-**Proceed rule:** If `MVP_MODE && TDD_MODE && GATE_RESULT.block == true` for `tdd.review-checkpoint`: STOP — do NOT proceed to `close_parent_artifacts`, `regression_gate`, `verify_phase_goal`, or `phase.complete`. Otherwise proceed normally.
+**Proceed rule:** If `MVP_MODE && TDD_MODE` and the enforcer's reported block verdict for `tdd.review-checkpoint` is `true`: STOP — do NOT proceed to `close_parent_artifacts`, `regression_gate`, `verify_phase_goal`, or `phase.complete`. Otherwise proceed normally.
 </step>
 
 <step name="close_parent_artifacts">
@@ -1243,12 +1287,12 @@ If `TEXT_MODE` is true, present as a plain-text numbered list and ask the user t
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
-**Tier gate:** spawn the verifier only when `DISPATCH_PLAN.stages.verify` lists `pp-verifier` (= `verifier_enabled`). Otherwise print `Verifier skipped (tier {phase_tier.tier})`, treat the phase as `passed` and go to `update_roadmap`. When it lists `verify-install` (heavy tier), first Read and execute `pp-core/workflows/execute-phase/steps/install-run.md`: the installed-product run the verifier judges on.
-
 ```bash
 VERIFIER_SKILLS=$(pp_run query agent-skills pp-verifier)
 ```
 
+Read and execute `execute-phase/steps/verifier-practice-payload.md` (sets `PRACTICE_VERDICT_INPUT`).
+
 ```
 Agent(
   description="Verify phase {phase_number} goal achievement",
@@ -1267,11 +1311,11 @@ MANDATORY: load every file listed here with the Read tool before you start the w
 - .planning/REQUIREMENTS.md (Requirement traceability)
 - {phase_dir}/*-CONTEXT.md (User decisions — verify they were honored)
 - {phase_dir}/*-RESEARCH.md (Known pitfalls — check for traps)
-${INSTALL_RUN_FILE ? `- ${INSTALL_RUN_FILE} (installed-product run — judge user-facing behaviour on it, not on the repo)
-` : ''}${CONTEXT_WINDOW >= 500000 ? `- Prior VERIFICATION.md files from earlier phases (regression check)
+${CONTEXT_WINDOW >= 500000 ? `- Prior VERIFICATION.md files from earlier phases (regression check)
 ` : ''}
 </files_to_read>
 
+${PRACTICE_VERDICT_INPUT}
 ${VERIFIER_SKILLS}",
   subagent_type="pp-verifier",
   model="{verifier_model}"
@@ -1389,7 +1433,7 @@ Gap closure cycle: `/pp:plan-phase {X} --gaps ${GSD_WS}` reads VERIFICATION.md
 <step name="update_roadmap">
 **Mark phase complete and update all tracking files:**
 
-First, Read and execute `pp-core/workflows/execute-phase/steps/phase-close-rebaseline.md` (the phase's one size re-baseline; inert where no `size:baseline` script exists).
+Reached only after the `execute:post` gate dispatch above returned without halting and `verify_phase_goal` reported `passed` — completion follows that outcome, never a plan or SUMMARY count (D-08-13). `phase.complete` writes ROADMAP.md, REQUIREMENTS.md and STATE.md in one transaction with rollback: both move or neither does (D-08-14). Until here the phase reads `Built` (D-08-15).
 
 ```bash
 COMPLETION=$(pp_run query phase.complete "${PHASE_NUMBER}")