@guanlin4924/devflow-pi 0.1.20 → 0.1.22

package/plugins/devflow-implementation/skills/workflow-execute-phase/references/execute-phase.md

@@ -1,1251 +1,82 @@
-<purpose>
-Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
-</purpose>
+# Devflow 执行阶段参考
 
-<core_principle>
-Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
-</core_principle>
+## 目的
 
-<runtime_compatibility>
-Use OMP's `task` tool and the project agents discovered from `.omp/agents/`. Project
-configuration controls isolation and recursion; do not override those limits in prompts.
-If the `task` tool is unavailable, execute plans sequentially inline. After every task,
-verify filesystem, test, summary, and git evidence before advancing the control plane.
-</runtime_compatibility>
+本参考定义 Devflow 在变更清单冻结后如何执行代码任务。它只描述 Devflow 的受控执行链，不创建独立的人工验收账本，也不依赖外部流程模板。
 
-<required_reading>
-Read STATE.md before any operation to load project context.
+## 执行前提
 
-# agent contracts (see .planning/execution-contract.md)
-# context budget guidelines
-# workflow gates
-</required_reading>
+执行器必须读取并校验：
 
+- 已确认的需求基线、技术方案和架构约束；
+- 已冻结的变更清单；
+- 与任务绑定的 `TC-*`、`UT-*`、`IT-*` 和测试命令；
+- 项目初始化生成的工具链、代码索引和运行上下文。
 
+若任务缺少实现测试、验收用例绑定或执行契约，必须停止并回到变更清单阶段，不得由执行器临时补造范围。
 
-<process>
+## 任务执行顺序
 
-<step name="parse_args" priority="first">
-Parse `$ARGUMENTS` before loading any context:
+对每个代码任务按以下顺序处理：
 
-- First positional token → `PHASE_ARG`
-- Optional `--wave N` → `WAVE_FILTER`
-- Optional `--gaps-only` keeps its current meaning
+1. 建立任务快照，记录任务 ID、需求图谱 revision、代码索引 revision 和源文件哈希。
+2. 对 `tdd_required` 任务先运行 RED 命令，确认失败原因是目标行为尚未实现，而不是环境错误。
+3. 编写最小实现；只修改任务声明的文件和必要的测试文件。
+4. 运行同一测试目标的 GREEN 命令。
+5. 运行任务声明的回归命令，并记录 Core-owned machine evidence。
+6. 刷新代码索引；若索引失败或发现边界漂移，任务保持未完成。
+7. 将结果写入任务证据记录。执行器不得以自然语言自述替代命令、退出码、输出摘要哈希和源码快照。
 
-If `--wave` is absent, preserve the current behavior of executing all incomplete waves in the phase.
-</step>
+## TDD 证据要求
 
-<step name="initialize" priority="first">
-Load all context in one call:
+`tdd_required` 任务必须存在三段证据：
 
-```bash
-INIT=$(# (local impl)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS=$(# (local impl)
-```
-
-Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
-
-**If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
-
-Read worktree config:
-
-```bash
-USE_WORKTREES=$(# (local impl)
-```
+- `RED`：测试先运行且按预期失败；
+- `GREEN`：同一测试目标在实现后通过；
+- `REGRESSION`：任务完成前约定回归命令通过。
 
-When `USE_WORKTREES` is `false`, all executor agents run without `isolation="worktree"` — they execute sequentially on the main working tree instead of in parallel worktrees.
+缺任一段、命令目标不一致、失败属于环境问题，或 RED 前已经存在本任务生产代码变更，都不能把任务标记为完成。非 TDD 任务也必须说明测试模式和豁免理由。
 
-Read context window size for adaptive prompt enrichment:
+## 执行阶段的失败处理
 
-```bash
-CONTEXT_WINDOW=$(# (local impl)
-```
+失败分为三类：
 
-When `CONTEXT_WINDOW >= 500000` (1M-class models), subagent prompts include richer context:
-- Executor agents receive prior wave SUMMARY.md files and the phase CONTEXT.md/RESEARCH.md
-- Verifier agents receive all PLAN.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md
-- This enables cross-phase awareness and history-aware verification
+- **代码失败**：测试断言失败、类型错误或静态检查失败；保持任务未完成，修复后重复证据链。
+- **索引失败**：代码索引无法刷新或项目边界发生变化；先修复索引，再继续测试。
+- **环境阻塞**：依赖服务、浏览器、数据库或测试设备不可用；结果记录为 `blocked`，不能伪装为通过。
 
-**If `phase_found` is false:** Error — phase directory not found.
-**If `plan_count` is 0:** Error — no plans found in phase.
-**If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
+验收失败不在本步骤创建临时报告。编排器应转入 `acceptance-remediation`，依次执行诊断、修复、代码索引刷新和冻结验收测试重跑。
 
-When `parallelization` is false, plans within a wave execute sequentially.
+## 阶段完成条件
 
-**OMP task availability:**
-Confirm the `task` tool and the required project agent are available before starting a wave.
-If either is unavailable, force sequential inline execution regardless of the
-`parallelization` setting.
+执行阶段只负责完成变更清单和实现证据，不负责发布或归档。满足以下条件后才能交给后续质量链：
 
-**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
-# REQUIRED: prevents stale auto-chain from previous --auto runs
-if [[ ! "$ARGUMENTS" =~ --auto ]]; then
-  # (local impl)
-fi
-```
-</step>
+- 所有代码任务均有完成证据；
+- 所有 TDD 任务 RED/GREEN/REGRESSION 齐全；
+- 代码索引刷新成功；
+- 没有未处理的需求、架构或安全阻塞。
 
-<step name="check_blocking_antipatterns" priority="first">
-**MANDATORY — Check for blocking anti-patterns before any other work.**
+## 后续质量链
 
-Look for a `.continue-here.md` in the current phase directory:
+执行完成后由编排器按固定顺序推进：
 
-```bash
-ls ${phase_dir}/.continue-here.md 2>/dev/null || true
+```text
+execute-phase
+  → code-review
+  → workflow-generate-mainflow-cases（如适用）
+  → workflow-run-acceptance-tests
+  → CP-4 验收结果确认
+  → workflow-release-closeout
 ```
 
-If `.continue-here.md` exists, parse its "Critical Anti-Patterns" table for rows with `severity` = `blocking`.
-
-**If one or more `blocking` anti-patterns are found:**
-
-This step cannot be skipped. Before proceeding to `check_interactive_mode` or any other step, the agent must demonstrate understanding of each blocking anti-pattern by answering all three questions for each one:
-
-1. **What is this anti-pattern?** — Describe it in your own words, not by quoting the handoff.
-2. **How did it manifest?** — Explain the specific failure that caused it to be recorded.
-3. **What structural mechanism (not acknowledgment) prevents it?** — Name the concrete step, checklist item, or enforcement mechanism that stops recurrence.
-
-Write these answers inline before continuing. If a blocking anti-pattern cannot be answered from the context in `.continue-here.md`, stop and ask the user for clarification.
-
-**If no `.continue-here.md` exists, or no `blocking` rows are found:** Proceed directly to `check_interactive_mode`.
-</step>
-
-<step name="check_interactive_mode">
-**Parse `--interactive` flag from $ARGUMENTS.**
-
-**If `--interactive` flag present:** Switch to interactive execution mode.
-
-Interactive mode executes plans sequentially **inline** (no subagent spawning) with user
-checkpoints between tasks. The user can review, modify, or redirect work at any point.
-
-**Interactive execution flow:**
-
-1. Load plan inventory as normal (discover_and_group_plans)
-2. For each plan (sequentially, ignoring wave grouping):
-
-   a. **Present the plan to the user:**
-      ```
-      ## Plan {plan_id}: {plan_name}
-
-      Objective: {from plan file}
-      Tasks: {task_count}
-
-      Options:
-      - Execute (proceed with all tasks)
-      - Review first (show task breakdown before starting)
-      - Skip (move to next plan)
-      - Stop (end execution, save progress)
-      ```
-
-   b. **If "Review first":** Read and display the full plan file. Ask again: Execute, Modify, Skip.
-
-   c. **If "Execute":** Read and follow `references/execute-phase.md` **inline**
-      (do NOT spawn a subagent). Execute tasks one at a time.
-
-   d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address
-      their feedback before continuing. Otherwise proceed to next task.
-
-   e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan.
-
-3. After all plans: proceed to verification (same as normal mode).
-
-**Benefits of interactive mode:**
-- No subagent overhead — dramatically lower token usage
-- User catches mistakes early — saves costly verification cycles
-- Maintains the project's planning/tracking structure
-- Best for: small phases, bug fixes, verification gaps, and learning the workflow
-
-**Skip to handle_branching step** (interactive plans execute inline after grouping).
-</step>
-
-<step name="handle_branching">
-Check `branching_strategy` from init:
-
-**"none":** Skip, continue on current branch.
-
-**"phase" or "milestone":** Use pre-computed `branch_name` from init:
-```bash
-git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-```
-
-All subsequent commits go to this branch. User handles merging.
-</step>
-
-<step name="validate_phase">
-From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
-
-Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
-
-**Update STATE.md for phase start:**
-```bash
-# (local impl)
-```
-This updates Status, Last Activity, Current focus, Current Position, and plan counts in STATE.md so frontmatter and body text reflect the active phase immediately.
-</step>
-
-<step name="discover_and_group_plans">
-Load plan inventory with wave grouping in one call:
-
-```bash
-PLAN_INDEX=$(# (local impl)
-```
-
-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`.
-
-**Wave safety check:** If `WAVE_FILTER` is set and there are still incomplete plans in any lower wave that match the current execution mode, STOP and tell the user to finish earlier waves first. Do not let Wave 2+ execute while prerequisite earlier-wave plans remain incomplete.
-
-If all filtered: "No matching incomplete plans" → exit.
-
-Report:
-```
-## Execution Plan
-
-**Phase {X}: {Name}** — {total_plans} matching plans across {wave_count} wave(s)
-
-{If WAVE_FILTER is set: `Wave filter active: executing only Wave {WAVE_FILTER}`.}
-
-| Wave | Plans | What it builds |
-|------|-------|----------------|
-| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
-| 2 | 01-03 | ... |
-```
-</step>
-
-<step name="execute_waves">
-Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
-
-**For each wave:**
-
-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 overlap is detected:**
-   - Warn the user:
-     ```
-     ⚠ Intra-wave files_modified overlap detected in Wave {N}:
-       Plan {A} and Plan {B} both modify {file}
-       Running these plans sequentially to avoid parallel worktree conflicts.
-     ```
-   - 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):**
-
-   Read each plan's `<objective>`. Extract what's being built and why.
-
-   ```
-   ---
-   ## Wave {N}
-
-   **{Plan ID}: {Plan Name}**
-   {2-3 sentences: what this builds, technical approach, why it matters}
-
-   Spawning {count} agent(s)...
-   ---
-   ```
-
-   - 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."
-
-3. **Spawn executor agents:**
-
-   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.
-
-   **Worktree mode** (`USE_WORKTREES` is not `false`):
-
-   Before spawning, capture the current HEAD:
-   ```bash
-   EXPECTED_BASE=$(git rev-parse HEAD)
-   ```
-
-   **Sequential dispatch for parallel execution (waves with 2+ agents):**
-   When spawning multiple agents in a wave, dispatch each `Task()` call **one at a time
-   with `run_in_background: true`** — do NOT send all Task calls in a single message.
-   `git worktree add` acquires an exclusive lock on `.git/config.lock`, so simultaneous
-   calls race for this lock and fail. Sequential dispatch ensures each worktree finishes
-   creation before the next begins (the round-trip latency of each tool call provides
-   natural spacing), while all agents still **run in parallel** once created.
-
-   ```
-   # CORRECT: dispatch one Task() per message, each with run_in_background: true
-   # → worktrees created sequentially, agents execute in parallel
-   #
-   # WRONG: multiple Task() calls in a single message
-   # → simultaneous git worktree add → .git/config.lock contention → failures
-   ```
-
-   ```
-   Task(
-     ,
-     description="Execute plan {plan_number} of phase {phase_number}",
-     model="{executor_model}",
-     isolation="worktree",
-     prompt="
-       <objective>
-       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>
-
-       <worktree_branch_check>
-       FIRST ACTION before any other work: verify this worktree's branch is based on the correct commit.
-
-       Run:
-       ```bash
-       ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
-       CURRENT_HEAD=$(git rev-parse HEAD)
-       ```
-
-       If `ACTUAL_BASE` != `{EXPECTED_BASE}` (i.e. the worktree branch was created from an older
-       base such as `main` instead of the feature branch HEAD), rebase onto the correct base:
-       ```bash
-       git rebase --onto {EXPECTED_BASE} $(git rev-parse --abbrev-ref HEAD~1 2>/dev/null || git rev-parse HEAD^) HEAD 2>/dev/null || true
-       # If rebase fails or is a no-op, reset the branch to start from the correct base:
-       git reset --soft {EXPECTED_BASE}
-       ```
-
-       If `ACTUAL_BASE` == `{EXPECTED_BASE}`: the branch base is correct, proceed immediately.
-
-       This check fixes a known issue on Windows where `EnterWorktree` creates branches from
-       `main` instead of the current feature branch HEAD.
-       </worktree_branch_check>
-
-       <parallel_execution>
-       You are running as a PARALLEL executor agent. Use --no-verify on all git
-       commits to avoid pre-commit hook contention with other agents. The
-       orchestrator validates hooks once after all agents complete.
-       For git adds: add --no-verify flag.
-       For direct git commits: use git commit --no-verify -m "..."
-       </parallel_execution>
-
-       <execution_context>
-       @references/execute-phase.md
-       # SUMMARY.md template
-       # checkpoint handling
-       # task-level testing gate
-       </execution_context>
-
-       <task_testing_gate>
-       Before editing each code task, read its test strategy from the change list or plan.
-       Required fields: planned test command(s), execution test command placeholder, test files to add/update, and automation skip classification.
-       If any required testing field is missing, STOP and report the task blocked for change-list backfill.
-
-       Tests may be written before code (TDD) or incrementally with the implementation.
-       Do not defer task-level unit/integration/component/API tests to a final standalone test wave.
-       Before a task is committed or marked done:
-       - add/update the tests required by the task strategy, unless skip classification is acceptable or reviewed
-       - refine planning-level commands into execution-level commands precise enough to rerun changed tests
-       - run execution-level test commands and required build/codegen/mock/DI checks
-       - record test files, commands, results, and any skip classification in SUMMARY.md
-
-       Reject skip reasons such as "too busy", "later", "QA will test", or "manual check is enough" for logic/API/data/state/permission/compatibility/migration/job/external integration changes.
-       </task_testing_gate>
-
-       <files_to_read>
-       Read these files at execution start using the Read tool:
-       - {phase_dir}/{plan_file} (Plan — task descriptions, must_haves, file paths)
-       - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
-       - .planning/STATE.md (State)
-       - .planning/config.json (Config, if exists)
-       ${CONTEXT_WINDOW >= 500000 ? `
-       - ${phase_dir}/*-CONTEXT.md (User decisions from discuss-phase — honors locked choices)
-       - ${phase_dir}/*-RESEARCH.md (Technical research — pitfalls and patterns to follow)
-       - ${prior_wave_summaries} (SUMMARY.md files from earlier waves in this phase — what was already built)
-       ` : ''}
-       - ./AGENTS.md (Portable project instructions, if present)
-       - ./.omp/AGENTS.md (OMP-specific execution contract)
-       - OMP-discovered project skills (list relevant `skill://<name>` resources and follow only those needed for implementation)
-
-       ### Spec Resolution (MANDATORY — follow the index chain, do not hardcode paths)
-
-       Spec file locations are discovered through `.context/spec/index.md`, not guessed.
-       The index is the project's registry of where specs live; paths vary per project.
-
-       1. Read `.context/spec/index.md` — this is the SINGLE entry point:
-          - "Read Order" section → tells you the resolution priority
-          - "Stack Specs" table → maps each codebase (BACKEND, FRONTEND, etc.) to its stack spec path
-          - "Codebase Specs" table → maps each codebase to its codebase spec and navigation path
-          - "Detailed Spec Packages" table → maps each domain to its index and detailed spec files
-
-       2. For the files you are about to modify, identify which codebase they belong to (e.g., FRONTEND or BACKEND).
-
-       3. Resolve through the index:
-          - Stack spec → from "Stack Specs" table, column "Spec"
-          - Codebase spec → from "Codebase Specs" table, column "Spec"
-          - Domain index → from "Detailed Spec Packages" table (e.g., `.context/spec/backend/index.md`)
-          - Then read the relevant detailed specs listed in the domain index (e.g., service.md, router.md, model.md)
-
-       4. At minimum, read the stack spec and codebase spec. If the change list specifies "适用规范" per task, read those specific files too.
-
-       Example: modifying a Python backend service file →
-         1. `.context/spec/index.md` → BACKEND uses stack `python-fastapi-pydantic2-sqlalchemy-playwright` and codebase spec `.context/spec/backend/BACKEND.md`
-         2. `.context/spec/stacks/python-fastapi-pydantic2-sqlalchemy-playwright.md` — stack conventions
-         3. `.context/spec/backend/BACKEND.md` — project-specific conventions
-         4. `.context/spec/backend/index.md` → lists service.md, errors.md, etc.
-         5. `.context/spec/backend/service.md` + `.context/spec/backend/errors.md` — layer-specific MUST/SHOULD rules
-       </files_to_read>
-
-       
-
-       <mcp_tools>
-       If project instructions reference MCP tools (e.g. jCodeMunch, context7,
-       or other MCP servers), prefer those tools over Grep/Glob for code navigation when available.
-       MCP tools often save significant tokens by providing structured code indexes.
-       Check tool availability first — if MCP tools are not accessible, fall back to Grep/Glob.
-       </mcp_tools>
-
-       <success_criteria>
-       - [ ] All tasks executed
-       - [ ] Each code task has task-level test evidence or an accepted/reviewed skip classification
-       - [ ] Execution-level test commands were recorded and passed
-       - [ ] Each task committed individually
-       - [ ] SUMMARY.md created in plan directory
-       </success_criteria>
-     "
-   )
-   ```
-
-   **Sequential mode** (`USE_WORKTREES` is `false`):
-
-   Omit `isolation="worktree"` from the Task call. Replace the `<parallel_execution>` block with:
-
-   ```
-       <sequential_execution>
-       You are running as a SEQUENTIAL executor agent on the main working tree.
-       Use normal git commits (with hooks). Do NOT use --no-verify.
-       </sequential_execution>
-   ```
-
-   The sequential mode Task 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 code task has task-level test evidence or an accepted/reviewed skip classification
-       - [ ] Execution-level test commands were recorded and passed
-       - [ ] Each task committed individually
-       - [ ] SUMMARY.md created in plan directory
-       - [ ] STATE.md updated with position and decisions
-       - [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
-       </success_criteria>
-   ```
-
-   When worktrees are disabled, execute plans **one at a time within each wave** (sequential) regardless of the `PARALLELIZATION` setting — multiple agents writing to the same working tree concurrently would cause conflicts.
-
-4. **Wait for all agents in wave to complete.**
-
-   **Completion evidence fallback:**
-
-   If a spawned agent does not return a completion signal but appears to have finished
-   its work, do NOT block indefinitely. Instead, verify completion via spot-checks:
-
-   ```bash
-   # For each plan in this wave, check if the executor finished:
-   SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md" && echo "true" || echo "false")
-   COMMITS_FOUND=$(git log --oneline --all --grep="{phase_number}-{plan_padded}" --since="1 hour ago" | head -1)
-   ```
-
-   **If SUMMARY.md exists AND commits are found:** The agent completed successfully —
-   treat as done and proceed to step 5. Log: `"✓ {Plan ID} completed (verified via spot-check — completion signal not received)"`
-
-   **If SUMMARY.md does NOT exist after a reasonable wait:** The agent may still be
-   running or may have failed silently. Check `git log --oneline -5` for recent
-   activity. If commits are still appearing, wait longer. If no activity, report
-   the plan as failed and route to the failure handler in step 6.
-
-   Apply this fallback whenever an OMP task result is interrupted or ambiguous.
-
-5. **Post-wave hook validation (parallel mode only):**
-
-   When agents committed with `--no-verify`, run pre-commit hooks once after the wave:
-   ```bash
-   # Run project's pre-commit hooks on the current state
-   git diff --cached --quiet || git stash  # stash any unstaged changes
-   git hook run pre-commit 2>&1 || echo "⚠ Pre-commit hooks failed — review before continuing"
-   ```
-   If hooks fail: report the failure and ask "Fix hook issues now?" or "Continue to next wave?"
-
-5.5. **Worktree cleanup (when `isolation="worktree"` was used):**
-
-   When executor agents ran in worktree isolation, their commits land on temporary branches in separate working trees. After the wave completes, merge these changes back and clean up:
-
-   ```bash
-   # List worktrees created by this wave's agents
-   WORKTREES=$(git worktree list --porcelain | grep "^worktree " | grep -v "$(pwd)$" | sed 's/^worktree //')
-
-   for WT in $WORKTREES; do
-     # Get the branch name for this worktree
-     WT_BRANCH=$(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null)
-     if [ -n "$WT_BRANCH" ] && [ "$WT_BRANCH" != "HEAD" ]; then
-       CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-       # --- Orchestrator file protection (#1756) ---
-       # Snapshot orchestrator-owned files BEFORE merge. If the worktree
-       # branch outlived a milestone transition, its versions of STATE.md
-       # and ROADMAP.md are stale. Main always wins for these files.
-       STATE_BACKUP=$(mktemp)
-       ROADMAP_BACKUP=$(mktemp)
-       git show HEAD:.planning/STATE.md > "$STATE_BACKUP" 2>/dev/null || true
-       git show HEAD:.planning/ROADMAP.md > "$ROADMAP_BACKUP" 2>/dev/null || true
-
-       # Snapshot list of files on main BEFORE merge to detect resurrections
-       PRE_MERGE_FILES=$(git ls-files .planning/)
-
-       # Merge the worktree branch into the current branch
-       git merge "$WT_BRANCH" --no-edit -m "chore: merge executor worktree ($WT_BRANCH)" 2>&1 || {
-         echo "⚠ Merge conflict from worktree $WT_BRANCH — resolve manually"
-         rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
-         continue
-       }
-
-       # Restore orchestrator-owned files (main always wins)
-       if [ -s "$STATE_BACKUP" ]; then
-         cp "$STATE_BACKUP" .planning/STATE.md
-       fi
-       if [ -s "$ROADMAP_BACKUP" ]; then
-         cp "$ROADMAP_BACKUP" .planning/ROADMAP.md
-       fi
-       rm -f "$STATE_BACKUP" "$ROADMAP_BACKUP"
-
-       # Detect files deleted on main but re-added by worktree merge
-       # (e.g., archived phase directories that were intentionally removed)
-       DELETED_FILES=$(git diff --diff-filter=A --name-only HEAD~1 -- .planning/ 2>/dev/null || true)
-       for RESURRECTED in $DELETED_FILES; do
-         # Check if this file was NOT in main's pre-merge tree
-         if ! echo "$PRE_MERGE_FILES" | grep -qxF "$RESURRECTED"; then
-           git rm -f "$RESURRECTED" 2>/dev/null || true
-         fi
-       done
-
-       # Amend merge commit with restored files if any changed
-       if ! git diff --quiet .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || \
-          [ -n "$DELETED_FILES" ]; then
-         # Only amend the commit with .planning/ files if commit_docs is enabled (#1783)
-         COMMIT_DOCS=$(# (local impl)
-         if [ "$COMMIT_DOCS" != "false" ]; then
-           git add .planning/STATE.md .planning/ROADMAP.md 2>/dev/null || true
-           git commit --amend --no-edit 2>/dev/null || true
-         fi
-       fi
-
-       # Remove the worktree
-       git worktree remove "$WT" --force 2>/dev/null || true
-
-       # Delete the temporary branch
-       git branch -D "$WT_BRANCH" 2>/dev/null || true
-     fi
-   done
-   ```
-
-   **If `workflow.use_worktrees` is `false`:** Agents ran on main working tree — skip this step entirely.
-
-   **If no worktrees found:** Skip silently — agents may have been spawned without worktree isolation.
-
-5.6. **Post-wave shared artifact update (worktree mode only):**
-
-   When executor agents ran with `isolation="worktree"`, they 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:
-
-   ```bash
-   # Update ROADMAP.md for each completed plan in this wave
-   for PLAN_ID in ${WAVE_PLAN_IDS}; do
-     # (local impl)
-   done
-
-   ```
-
-   Where `WAVE_PLAN_IDS` is the space-separated list of plan IDs that completed in this wave.
-
-   **If `workflow.use_worktrees` is `false`:** Sequential agents already updated STATE.md and ROADMAP.md themselves — skip this step.
-
-6. **Report completion — spot-check claims first:**
-
-   For each SUMMARY.md:
-   - Verify first 2 files from `key-files.created` exist on disk
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
-   - Check for `## Self-Check: FAILED` marker
-   - Check for task-level test evidence: execution-level command(s), result(s), and test files changed, or an accepted/reviewed automation skip classification
-
-   If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
-
-   If pass:
-   ```
-   ---
-   ## Wave {N} Complete
-
-   **{Plan ID}: {Plan Name}**
-   {What was built — from SUMMARY.md}
-   {Notable deviations, if any}
-
-   {If more waves: what this enables for next wave}
-   ---
-   ```
-
-   - Bad: "Wave 2 complete. Proceeding to Wave 3."
-   - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
-
-7. **Handle failures:**
-
-   Report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, provide a partial completion report.
-
-7b. **Pre-wave dependency check (waves 2+ only):**
-
-    Before spawning wave N+1, for each plan in the upcoming wave:
-    ```bash
-    # (local impl)
-    ```
-
-    If any key-link from a PRIOR wave's artifact fails verification:
-
-    ## Cross-Plan Wiring Gap
-
-    | Plan | Link | From | Expected Pattern | Status |
-    |------|------|------|-----------------|--------|
-    | {plan} | {via} | {from} | {pattern} | NOT FOUND |
-
-    Wave {N} artifacts may not be properly wired. Options:
-    1. Investigate and fix before continuing
-    2. Continue (may cause cascading failures in wave {N+1})
-
-    Key-links referencing files in the CURRENT (upcoming) wave are skipped.
-
-8. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
-
-9. **Proceed to next wave.**
-</step>
-
-<step name="checkpoint_handling">
-Plans with `autonomous: false` require user interaction.
-
-**Auto-mode checkpoint handling:**
-
-Read auto-advance config (chain flag + user preference):
-```bash
-AUTO_CHAIN=$(# (local impl)
-AUTO_CFG=$(# (local impl)
-```
-
-When executor returns a checkpoint AND (`AUTO_CHAIN` is `"true"` OR `AUTO_CFG` is `"true"`):
-- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
-- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
-- **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
-
-**Standard flow (not auto-mode, or human-action type):**
-
-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
-
-**Why fresh agent, not resume:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
-
-**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">
-After all waves:
-
-```markdown
-## Phase {X}: {Name} Execution Complete
-
-**Waves:** {N} | **Plans:** {M}/{total} complete
-
-| Wave | Plans | Status |
-|------|-------|--------|
-| 1 | plan-01, plan-02 | ✓ Complete |
-| CP | plan-03 | ✓ Verified |
-| 2 | plan-04 | ✓ Complete |
-
-### Plan Details
-1. **03-01**: [one-liner from SUMMARY.md]
-2. **03-02**: [one-liner from SUMMARY.md]
-
-### Issues Encountered
-[Aggregate from SUMMARYs, or "None"]
-```
-
-**Security gate check:**
-```bash
-SECURITY_CFG=$(# (local impl)
-SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
-```
-
-If `SECURITY_CFG` is `false`: skip.
-
-If `SECURITY_CFG` is `true` AND `SECURITY_FILE` is empty (no SECURITY.md yet):
-Include in the next-steps routing output:
-```
-⚠ Security enforcement enabled — run before advancing:
-  
-```
-
-If `SECURITY_CFG` is `true` AND SECURITY.md exists: check frontmatter `threats_open`. If > 0:
-```
-⚠ Security gate: {threats_open} threats open
-  
-```
-</step>
-
-<step name="handle_partial_wave_execution">
-If `WAVE_FILTER` was used, re-run plan discovery after execution:
-
-```bash
-POST_PLAN_INDEX=$(# (local impl)
-```
-
-Apply the same "incomplete" filtering rules as earlier:
-- ignore plans with `has_summary: true`
-- if `--gaps-only`, only consider `gap_closure: true` plans
-
-**If incomplete plans still remain anywhere in the phase:**
-- STOP here
-- Do NOT run phase verification
-- Do NOT mark the phase complete in ROADMAP/STATE
-- Present:
-
-```markdown
-## Wave {WAVE_FILTER} Complete
-
-Selected wave finished successfully. This phase still has incomplete plans, so phase-level verification and completion were intentionally skipped.
-
-/workflow-execute-phase {phase} ${GSD_WS}                # Continue remaining waves
-/workflow-execute-phase {phase} --wave {next} ${GSD_WS}  # Run the next wave explicitly
-```
-
-**If no incomplete plans remain after the selected wave finishes:**
-- continue with the normal phase-level verification and completion flow below
-- this means the selected wave happened to be the last remaining work in the phase
-</step>
-
-<step name="code_review_gate" required="true">
-Code review is a separate workflow step in `feature-development.yaml`.
-
-Do not invoke `code-review` from inside `workflow-execute-phase`; doing so duplicates the post-execute review gate and can produce conflicting `REVIEW.md` results.
-
-Before returning from execute, ensure the execution outputs required by the downstream `code-review` step exist:
-
-- `.planning/features/{feature}/PROGRESS.md`
-- `.planning/phases/{phase}/SUMMARY.md`
-
-The orchestrator will run `code-review` after `execute` and before `verify`.
-</step>
-
-<step name="close_parent_artifacts">
-**For decimal/polish phases only (X.Y pattern):** Close the feedback loop by resolving parent UAT and debug artifacts.
-
-**Skip if** phase number has no decimal (e.g., `3`, `04`) — only applies to gap-closure phases like `4.1`, `03.1`.
-
-**1. Detect decimal phase and derive parent:**
-```bash
-# Check if phase_number contains a decimal
-if [[ "$PHASE_NUMBER" == *.* ]]; then
-  PARENT_PHASE="${PHASE_NUMBER%%.*}"
-fi
-```
-
-**2. Find parent UAT file:**
-```bash
-PARENT_INFO=$(# (local impl)
-# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
-```
-
-**If no parent UAT found:** Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).
-
-**3. Update UAT gap statuses:**
-
-Read the parent UAT file's `## Gaps` section. For each gap entry with `status: failed`:
-- Update to `status: resolved`
-
-**4. Update UAT frontmatter:**
-
-If all gaps now have `status: resolved`:
-- Update frontmatter `status: diagnosed` → `status: resolved`
-- Update frontmatter `updated:` timestamp
-
-**5. Resolve referenced debug sessions:**
-
-For each gap that has a `debug_session:` field:
-- Read the debug session file
-- Update frontmatter `status:` → `resolved`
-- Update frontmatter `updated:` timestamp
-- Move to resolved directory:
-```bash
-mkdir -p .planning/debug/resolved
-mv .planning/debug/{slug}.md .planning/debug/resolved/
-```
-
-**6. Commit updated artifacts:**
-```bash
-# (local impl)
-```
-</step>
-
-<step name="regression_gate">
-Run prior phases' test suites to catch cross-phase regressions BEFORE verification.
-
-**Skip if:** This is the first phase (no prior phases), or no prior VERIFICATION.md files exist.
-
-**Step 1: Discover prior phases' test files**
-```bash
-# Find all VERIFICATION.md files from prior phases in current milestone
-PRIOR_VERIFICATIONS=$(find .planning/phases/ -name "*-VERIFICATION.md" ! -path "*${PHASE_NUMBER}*" 2>/dev/null)
-```
-
-**Step 2: Extract test file lists from prior verifications**
-
-For each VERIFICATION.md found, look for test file references:
-- Lines containing `test`, `spec`, or `__tests__` paths
-- The "Test Suite" or "Automated Checks" section
-- File patterns from `key-files.created` in corresponding SUMMARY.md files that match `*.test.*` or `*.spec.*`
-
-Collect all unique test file paths into `REGRESSION_FILES`.
-
-**Step 3: Run regression tests (if any found)**
-
-```bash
-# Detect test runner and run prior phase tests
-if [ -f "package.json" ]; then
-  # Node.js — use project's test runner
-  npx jest ${REGRESSION_FILES} --passWithNoTests --no-coverage -q 2>&1 || npx vitest run ${REGRESSION_FILES} 2>&1
-elif [ -f "Cargo.toml" ]; then
-  cargo test 2>&1
-elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
-  python -m pytest ${REGRESSION_FILES} -q --tb=short 2>&1
-fi
-```
-
-**Step 4: Report results**
-
-If all tests pass:
-```
-✓ Regression gate: {N} prior-phase test files passed — no regressions detected
-```
-→ Proceed to verify_phase_goal
-
-If any tests fail:
-```
-## ⚠ Cross-Phase Regression Detected
-
-Phase {X} execution may have broken functionality from prior phases.
-
-| Test File | Phase | Status | Detail |
-|-----------|-------|--------|--------|
-| {file} | {origin_phase} | FAILED | {first_failure_line} |
-
-Options:
-1. Fix regressions before verification (recommended)
-2. Continue to verification anyway (regressions will compound)
-3. Abort phase — roll back and re-plan
-```
-
-Use ask to present the options.
-</step>
-
-<step name="schema_drift_gate">
-Post-execution schema drift detection. Catches false-positive verification where
-build/types pass because TypeScript types come from config, not the live database.
-
-**Run after execution completes but BEFORE verification marks success.**
-
-```bash
-SCHEMA_DRIFT=$(# (local impl)
-```
-
-Parse JSON result for: `drift_detected`, `blocking`, `schema_files`, `orms`, `unpushed_orms`, `message`.
-
-**If `drift_detected` is false:** Skip to verify_phase_goal.
-
-**If `drift_detected` is true AND `blocking` is true:**
-
-Check for override:
-```bash
-SKIP_SCHEMA=$(echo "${GSD_SKIP_SCHEMA_CHECK:-false}")
-```
-
-**If `SKIP_SCHEMA` is `true`:**
-
-Display:
-```
-⚠ Schema drift detected but GSD_SKIP_SCHEMA_CHECK=true — bypassing gate.
-
-Schema files changed: {schema_files}
-ORMs requiring push: {unpushed_orms}
-
-Proceeding to verification (database may be out of sync).
-```
-→ Continue to verify_phase_goal.
-
-**If `SKIP_SCHEMA` is not `true`:**
-
-BLOCK verification. Display:
-
-```
-## BLOCKED: Schema Drift Detected
-
-Schema-relevant files changed during this phase but no database push command
-was executed. Build and type checks pass because TypeScript types come from
-config, not the live database — verification would produce a false positive.
-
-Schema files changed: {schema_files}
-ORMs requiring push: {unpushed_orms}
-
-Required push commands:
-{For each unpushed ORM, show the push command from the message}
-
-Options:
-1. Run push command now (recommended) — execute the push, then re-verify
-2. Skip schema check (GSD_SKIP_SCHEMA_CHECK=true) — bypass this gate
-3. Abort — stop execution and investigate
-```
-
-If `TEXT_MODE` is true, present as a plain-text numbered list. Otherwise use ask.
-
-**If user selects option 1:** Present the specific push command(s) to run. After user confirms execution, re-run the schema drift check. If it passes, continue to verify_phase_goal.
-
-**If user selects option 2:** Set override and continue to verify_phase_goal.
-
-**If user selects option 3:** Stop execution. Report partial completion.
-</step>
-
-<step name="verify_phase_goal">
-Verify phase achieved its GOAL, not just completed tasks.
-
-```bash
-VERIFIER_SKILLS=$(# (local impl)
-```
-
-```
-Task(
-  description="Verify phase {phase_number} goal achievement",
-  prompt="Verify phase {phase_number} goal achievement.
-Phase directory: {phase_dir}
-Phase goal: {goal from ROADMAP.md}
-Phase requirement IDs: {phase_req_ids}
-Check must_haves against actual codebase.
-Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
-Create VERIFICATION.md.
-
-<files_to_read>
-Read these files before verification:
-- {phase_dir}/*-PLAN.md (All plans — understand intent, check must_haves)
-- {phase_dir}/*-SUMMARY.md (All summaries — cross-reference claimed vs actual)
-- .planning/REQUIREMENTS.md (Requirement traceability)
-- .context/spec/index.md (Spec registry — resolve stack spec, codebase spec, and domain specs through the index chain)
-${CONTEXT_WINDOW >= 500000 ? `- {phase_dir}/*-CONTEXT.md (User decisions — verify they were honored)
-- {phase_dir}/*-RESEARCH.md (Known pitfalls — check for traps)
-- Prior VERIFICATION.md files from earlier phases (regression check)
-` : ''}
-</files_to_read>
-
-",
-  ,
-  model="{verifier_model}"
-)
-```
-
-Read status:
-```bash
-grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
-```
-
-| Status | Action |
-|--------|--------|
-| `passed` | → update_roadmap |
-| `human_needed` | Present items for human testing, get approval or feedback |
-| `gaps_found` | Present gap summary, offer `/workflow-pipeline {phase} --gaps ${GSD_WS}` |
-
-**If human_needed:**
-
-**Step A: Persist human verification items as UAT file.**
-
-Create `{phase_dir}/{phase_num}-HUMAN-UAT.md` using UAT template format:
-
-```markdown
----
-status: partial
-phase: {phase_num}-{phase_name}
-source: [{phase_num}-VERIFICATION.md]
-started: [now ISO]
-updated: [now ISO]
----
-
-## Current Test
-
-[awaiting human testing]
-
-## Tests
-
-{For each human_verification item from VERIFICATION.md:}
-
-### {N}. {item description}
-expected: {expected behavior from VERIFICATION.md}
-result: [pending]
-
-## Summary
-
-total: {count}
-passed: 0
-issues: 0
-pending: {count}
-skipped: 0
-blocked: 0
-
-## Gaps
-```
-
-Commit the file:
-```bash
-# (local impl)
-```
-
-**Step B: Present to user:**
-
-```
-## ✓ Phase {X}: {Name} — Human Verification Required
-
-All automated checks passed. {N} items need human testing:
-
-{From VERIFICATION.md human_verification section}
-
-Items saved to `{phase_num}-HUMAN-UAT.md` — they will appear in `/workflow-pipeline` and `/workflow-verify-work`.
-
-"approved" → continue | Report issues → gap closure
-```
-
-**If user says "approved":** Proceed to `update_roadmap`. The HUMAN-UAT.md file persists with `status: partial` and will surface in future progress checks until the user runs `/workflow-verify-work` on it.
-
-**If user reports issues:** Proceed to gap closure as currently implemented.
-
-**If gaps_found:**
-```
-## ⚠ Phase {X}: {Name} — Gaps Found
-
-**Score:** {N}/{M} must-haves verified
-**Report:** {phase_dir}/{phase_num}-VERIFICATION.md
-
-### What's Missing
-{Gap summaries from VERIFICATION.md}
-
----
-## ▶ Next Up
-
-`/clear` then:
-
-`/workflow-pipeline {X} --gaps ${GSD_WS}`
-
-Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
-Also: `/workflow-verify-work {X} ${GSD_WS}` — manual testing first
-```
-
-Gap closure cycle: `/workflow-pipeline {X} --gaps ${GSD_WS}` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/workflow-execute-phase {X} --gaps-only ${GSD_WS}` → verifier re-runs.
-</step>
-
-<step name="update_roadmap">
-**Mark phase complete and update all tracking files:**
-
-```bash
-COMPLETION=$(# (local impl)
-```
-
-The CLI handles:
-- Marking phase checkbox `[x]` with completion date
-- Updating Progress table (Status → Complete, date)
-- Updating plan count to final
-- Advancing STATE.md to next phase
-- Updating REQUIREMENTS.md traceability
-- Scanning for verification debt (returns `warnings` array)
-
-Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `warnings`, `has_warnings`.
-
-**If has_warnings is true:**
-```
-## Phase {X} marked complete with {N} warnings:
-
-{list each warning}
-
-These items are tracked and will appear in `/workflow-pipeline` and `/workflow-verify-work`.
-```
-
-```bash
-# (local impl)
-```
-</step>
-
-<step name="auto_copy_learnings">
-**Auto-copy phase learnings to global store (when enabled).**
-
-This step runs AFTER phase completion and SUMMARY.md is written. It copies any LEARNINGS.md
-entries from the completed phase to the global learnings store at `.planning/lessons/`.
-
-**Check config gate:**
-```bash
-GL_ENABLED=$(# (local impl)
-```
-
-**If `GL_ENABLED` is not `true`:** Skip this step entirely (feature disabled by default).
-
-**If enabled:**
-
-1. Check if LEARNINGS.md exists in the phase directory (use the `phase_dir` value from init context)
-2. If found, copy to global store:
-```bash
-# (local impl)
-```
-Copy failure must NOT block phase completion.
-</step>
-
-<step name="update_project_md">
-**Evolve PROJECT.md to reflect phase completion (prevents planning document drift — #956):**
-
-PROJECT.md tracks validated requirements, decisions, and current state. Without this step,
-PROJECT.md falls behind silently over multiple phases.
-
-1. Read `.planning/PROJECT.md`
-2. If the file exists and has a `## Validated Requirements` or `## Requirements` section:
-   - Move any requirements validated by this phase from Active → Validated
-   - Add a brief note: `Validated in Phase {X}: {Name}`
-3. If the file has a `## Current State` or similar section:
-   - Update it to reflect this phase's completion (e.g., "Phase {X} complete — {one-liner}")
-4. Update the `Last updated:` footer to today's date
-5. Commit the change:
-
-```bash
-# (local impl)
-```
-
-**Skip this step if** `.planning/PROJECT.md` does not exist.
-</step>
-
-<step name="offer_next">
-
-**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/workflow-pipeline {X} --gaps`). No additional routing needed — skip auto-advance.
-
-**No-transition check (spawned by auto-advance chain):**
-
-Parse `--no-transition` flag from $ARGUMENTS.
-
-**If `--no-transition` flag present:**
-
-Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
-After verification passes and roadmap is updated, return completion status to parent:
-
-```
-## PHASE COMPLETE
-
-Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
-Plans: ${completed_count}/${total_count}
-Verification: {Passed | Gaps Found}
-
-[Include aggregate_results output]
-```
-
-STOP. Do not proceed to auto-advance or transition.
-
-**If `--no-transition` flag is NOT present:**
-
-**Auto-advance detection:**
-
-1. Parse `--auto` flag from $ARGUMENTS
-2. Read both the chain flag and user preference (chain flag already synced in init step):
-   ```bash
-   AUTO_CHAIN=$(# (local impl)
-   AUTO_CFG=$(# (local impl)
-   ```
-
-**If `--auto` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true (AND verification passed with no gaps):**
-
-```
-╔══════════════════════════════════════════╗
-║  AUTO-ADVANCING → TRANSITION             ║
-║  Phase {X} verified, continuing chain    ║
-╚══════════════════════════════════════════╝
-```
-
-Execute the transition workflow inline (do NOT use Task — orchestrator context is ~10-15%, transition needs phase completion data already in context):
-
-Read and follow `the transition process`, passing through the `--auto` flag so it propagates to the next phase invocation.
-
-**If none of `--auto`, `AUTO_CHAIN`, or `AUTO_CFG` is true:**
-
-**STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
-
-**IMPORTANT: There is NO `` command. Never suggest it. The transition workflow is internal only.**
-
-```
-## ✓ Phase {X}: {Name} Complete
-
-/workflow-pipeline ${GSD_WS} — see updated roadmap
-/workflow-pipeline {next} ${GSD_WS} — discuss next phase before planning
-/workflow-pipeline {next} ${GSD_WS} — plan next phase
-/workflow-execute-phase {next} ${GSD_WS} — execute next phase
-```
-
-Only suggest the commands listed above. Do not invent or hallucinate command names.
-</step>
-
-</process>
+`workflow-run-acceptance-tests` 只消费冻结的 `TC-*`。每个已确认验收条件都必须覆盖；异常、边界、权限、兼容和架构风险用例不能被主流程用例替代。验收结果保存在 `.planning/test-runs/{feature}/acceptance-results.json`。
 
-<context_efficiency>
-Orchestrator: ~10-15% context for 200k windows, can use more for 1M+ windows.
-Subagents: fresh context each (200k-1M depending on model). No polling (Task blocks). No context bleed.
+只有当所有冻结 `TC-*` 已执行且通过、无 `failed`/`blocked`，且代码索引审计通过时，才允许进入 `workflow-release-closeout`。版本收口负责生成项目自己的里程碑收口记录并更新项目状态；它不生成旧式人工验收或独立验证报告。
 
-For 1M+ context models, consider:
-- Passing richer context (code snippets, dependency outputs) directly to executors instead of just file paths
-- Running small phases (≤3 plans, no dependencies) inline without subagent spawning overhead
-- Relaxing /clear recommendations — context rot onset is much further out with 5x window
-</context_efficiency>
+## 波次执行
 
-<failure_handling>
-- **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
-- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
-- **All agents in wave fail:** Systemic issue → stop, report for investigation
-- **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
-</failure_handling>
+若只执行某个 wave，执行器只报告该 wave 的结果，不得提前标记阶段完成。剩余任务完成后，仍必须经过完整的代码审查、冻结验收测试和 CP-4；任何未执行或环境阻塞的 `TC-*` 都会阻止版本收口。
 
-<resumption>
-Re-run `/workflow-execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
+## 证据与可追溯性
 
-STATE.md tracks: last completed plan, current wave, pending checkpoints.
-</resumption>
+每次执行记录至少包含：任务 ID、关联需求/架构/测试 ID、命令及哈希、开始结束时间、退出码、输出摘要哈希、代码索引 revision 和源码快照。Markdown 说明仅作为人类视图，不能成为状态真相源。