@hanzlaa/rcode 3.4.4 → 3.4.6

package/rihal/workflows/execute.md

@@ -7,8 +7,8 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s
 findings BEFORE any subagents are spawned. If any check fails, stop and
 route back to the user.
 
-1. **Init state**: `node .rihal/bin/rihal-tools.cjs init execute-phase {N}`
-2. **Phase index**: list all plans via `state phase-plan-index {N}` — extract
+1. **Init state**: `node .rihal/bin/rihal-tools.cjs init execute {N}`
+2. **Phase index**: list all plans via `phase-plan-index {N}` — extract
    plan count, wave count, autonomy flag per plan, files_modified overlaps
 3. **Anti-patterns**: check for `.continue-here.md` (paused state), STATE.md
    error flag, existing VERIFICATION.md with FAIL items without overrides
@@ -126,7 +126,8 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-spr
 
 <runtime_compatibility>
 **Subagent spawning is runtime-specific:**
-- **Claude Code:** Uses `Task(subagent_type="rihal-executor", ...)` — blocks until complete, returns result
+- **Claude Code:** Uses `Task(subagent_type="rihal-executor",
+  model="sonnet", ...)` — blocks until complete, returns result
 - **Copilot:** Subagent spawning does not reliably return completion signals. **Default to
   sequential inline execution**: read and follow execute-sprint.md directly for each plan
   instead of spawning parallel agents. Only attempt parallel spawning if the user
@@ -149,6 +150,7 @@ Read STATE.md before any operation to load project context.
 @.rihal/references/context-budget.md
 @.rihal/references/gates.md
 @.rihal/references/karpathy-guidelines.md
+@.rihal/references/execution-protocol.md
 </required_reading>
 
 <available_agent_types>
@@ -206,6 +208,10 @@ Read context window size for adaptive prompt enrichment:
 
 ```bash
 CONTEXT_WINDOW=$(node ".rihal/bin/rihal-tools.cjs" config-get context_window 2>/dev/null || echo "200000")
+
+# Detect if any SPRINT.md in this phase references a checkpoint — used to lazy-load checkpoints.md
+SPRINT_HAS_CHECKPOINT=$(grep -rl "checkpoint" "${phase_dir}"/*-SPRINT.md 2>/dev/null | head -1)
+PRIOR_WAVE_FAILED=false  # set to true by wave failure handler if a prior wave errored
 ```
 
 When `CONTEXT_WINDOW >= 500000` (1M-class models), subagent prompts include richer context:
@@ -385,389 +391,9 @@ Report:
 ```
 </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(
-     subagent_type="rihal-executor",
-     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. To avoid pre-commit hook
-       contention with other agents, acquire a file-based lock before each
-       commit and release it immediately after:
-
-         while ! mkdir .rihal/.commit-lock 2>/dev/null; do sleep 0.5; done
-         git commit -m "..."           # hooks run normally
-         rmdir .rihal/.commit-lock
-
-       Hooks run as designed for every commit. AGENTS.md forbids --no-verify;
-       hook failures must be fixed at the source, not bypassed. The orchestrator
-       still validates state once after all agents complete.
-       </parallel_execution>
-
-       <execution_context>
-       @.rihal/workflows/execute-sprint.md
-       @.rihal/templates/summary.md
-       @.rihal/references/checkpoints.md
-       @.rihal/references/tdd.md
-       </execution_context>
-
-       <files_to_read>
-       Read these files at execution start using the Read tool:
-       - {phase_dir}/{plan_file} (Plan)
-       - .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)
-       ` : ''}
-       - ./CLAUDE.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)
-       - .claude/skills/ or .agents/skills/ (Project skills, if either exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
-       </files_to_read>
-
-       ${AGENT_SKILLS}
-
-       <mcp_tools>
-       If CLAUDE.md or 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 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 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 signal fallback (Copilot and runtimes where Task() may not return):**
-
-   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.
-
-   **This fallback applies automatically to all runtimes.** Claude Code's Task() normally
-   returns synchronously, but the fallback ensures resilience if it doesn't.
-
-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=$(node ".rihal/bin/rihal-tools.cjs" config-get commit_docs 2>/dev/null || echo "true")
-         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 the 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
-     node ".rihal/bin/rihal-tools.cjs" roadmap update-plan-progress "${PHASE_NUMBER}" "${PLAN_ID}" completed
-   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
-
-   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:**
-
-   **Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a Rihal or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 5 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
-
-   For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
-
-7b. **Pre-wave dependency check (waves 2+ only):**
-
-    Before spawning wave N+1, for each plan in the upcoming wave:
-    ```bash
-    node ".rihal/bin/rihal-tools.cjs" verify key-links {phase_dir}/{plan}-SPRINT.md
-    ```
-
-    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.
+@rihal/workflows/execute-waves.md
 
-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.
@@ -889,6 +515,48 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
 - this means the selected wave happened to be the last remaining work in the phase
 </step>
 
+<step name="run_verify_commands">
+**Run per-task `<verify>` shell commands from all completed SPRINT.md plans.**
+
+After all executor agents finish, extract and run any `<verify>` blocks defined in plan tasks. These are the machine-executable counterpart to `<acceptance_criteria>` prose.
+
+```bash
+# Extract all <verify> blocks from all SPRINT.md files for this phase
+for plan in "${PHASE_DIR}"/*-SPRINT.md; do
+  python3 -c "
+import re, sys
+content = open('$plan').read()
+verifies = re.findall(r'<verify>(.*?)</verify>', content, re.DOTALL)
+for v in verifies:
+    for line in v.strip().splitlines():
+        line = line.strip()
+        if line:
+            print(line)
+" 2>/dev/null
+done
+```
+
+Run each extracted command. Collect results:
+- Exit 0 → `✓ PASS`
+- Non-zero → `❌ FAIL: {command}`
+
+**If any verify command fails:**
+```
+⚠ Task verify commands failed:
+
+  ❌ {command}
+  Output: {stderr/stdout}
+
+These are task-level acceptance checks. Fix before proceeding to code review.
+/rihal-debug "verify command failed: {command}" — diagnose the failure
+```
+STOP — do not proceed to `code_review_gate` until all verify commands pass or the user explicitly overrides.
+
+**If all pass (or no `<verify>` blocks exist):** proceed to `code_review_gate` silently.
+
+**Skip if:** `--skip-verify` flag is set.
+</step>
+
 <step name="code_review_gate" required="true">
 **This step is REQUIRED and must not be skipped.** Spawn `rihal-code-reviewer` to review the phase's source changes. Acts as a BLOCKING gate before the verifier when critical or high findings are present.
 
@@ -901,7 +569,8 @@ If `CODE_REVIEW_ENABLED` is `"false"`: display "Code review skipped (workflow.co
 
 **Resolve reviewer model:**
 ```bash
-REVIEWER_MODEL=$(node ".rihal/bin/rihal-tools.cjs" resolve-model code-reviewer 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{console.log(JSON.parse(d).model)}catch{console.log('')}})" || echo "")
+REVIEWER_MODEL=$(node ".rihal/bin/rihal-tools.cjs" resolve-model code-reviewer 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{console.log(JSON.parse(d).model)}catch{console.log('')}})" || echo "sonnet")
+REVIEWER_MODEL=${REVIEWER_MODEL:-sonnet}
 REVIEWER_SKILLS=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-code-reviewer 2>/dev/null || echo "")
 PADDED=$(printf "%02d" "${PHASE_NUMBER}")
 REVIEW_FILE="${PHASE_DIR}/${PADDED}-REVIEW.md"
@@ -1039,264 +708,13 @@ node ".rihal/bin/rihal-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve U
 ```
 </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.*`
+@rihal/workflows/execute-regression-gates.md
 
-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
-```
+@rihal/workflows/execute-verify-phase-goal.md
 
-**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 AskUserQuestion 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=$(node ".rihal/bin/rihal-tools.cjs" verify schema-drift "${PHASE_NUMBER}" 2>/dev/null)
-```
-
-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 "${Rihal_SKIP_SCHEMA_CHECK:-false}")
-```
-
-**If `SKIP_SCHEMA` is `true`:**
-
-Display:
-```
-⚠ Schema drift detected but Rihal_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 (Rihal_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 AskUserQuestion.
-
-**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=$(node ".rihal/bin/rihal-tools.cjs" agent-skills rihal-verifier 2>/dev/null)
-```
-
-```
-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}/*-SPRINT.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_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>
-
-${VERIFIER_SKILLS}",
-  subagent_type="rihal-verifier",
-  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 `/rihal-plan {phase} --gaps ${Rihal_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
-node ".rihal/bin/rihal-tools.cjs" commit "test({phase_num}): persist human verification items as UAT" --files "{phase_dir}/{phase_num}-HUMAN-UAT.md"
-```
-
-**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 `/rihal-progress` and `/rihal-audit-uat`.
-
-"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 `/rihal-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:
-
-`/rihal-plan {X} --gaps ${Rihal_WS}`
-
-Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
-Also: `/rihal-verify-work {X} ${Rihal_WS}` — manual testing first
-```
-
-Gap closure cycle: `/rihal-plan {X} --gaps ${Rihal_WS}` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/rihal-execute {X} --gaps-only ${Rihal_WS}` → verifier re-runs.
-</step>
 
 <step name="uat_gate" priority="blocker">
 **UAT gate (added in v3.1.0 after #443 / #448):**
@@ -1308,9 +726,9 @@ VERIFICATION_FILE=$(ls "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1)
 
 if [ -z "$VERIFICATION_FILE" ]; then
   VERIFICATION_STATUS="missing"
-elif grep -q "^status:\s*pass\b" "$VERIFICATION_FILE" 2>/dev/null; then
+elif grep -qE "^status:[[:space:]]*passed" "$VERIFICATION_FILE" 2>/dev/null; then
   VERIFICATION_STATUS="pass"
-elif grep -q "^status:\s*fail\b" "$VERIFICATION_FILE" 2>/dev/null; then
+elif grep -qE "^status:[[:space:]]*(gaps_found|fail)" "$VERIFICATION_FILE" 2>/dev/null; then
   VERIFICATION_STATUS="fail"
 else
   VERIFICATION_STATUS="indeterminate"
@@ -1332,8 +750,11 @@ fi
 
    {list AC items from SPRINT.md}
 
-   Run /rihal-verify-work {X} to perform UAT and produce VERIFICATION.md.
-   /rihal-next will refuse to advance until this gate passes.
+   Recommended next steps:
+   /rihal-add-tests {X} — generate unit + E2E tests before UAT
+   /rihal-verify-work {X} — perform UAT and produce VERIFICATION.md
+
+   /rihal-next will refuse to advance until the UAT gate passes.
    ```
 3. STOP the workflow. Do NOT proceed to `update_roadmap`. Do NOT call `phase complete`.
 
@@ -1355,6 +776,16 @@ The previous behaviour (printing "Next Up: /rihal-verify-work" without state-gat
 COMPLETION=$(node ".rihal/bin/rihal-tools.cjs" phase complete "${PHASE_NUMBER}")
 ```
 
+Record execution telemetry (plan count + latest commit hash):
+```bash
+EXEC_HASH=$(git rev-parse --short HEAD 2>/dev/null || echo "")
+node ".rihal/bin/rihal-tools.cjs" state record-execution \
+  --plan "${PHASE_NUMBER}" \
+  --tasks "${PLAN_COUNT}" \
+  --hash "${EXEC_HASH}" \
+  2>/dev/null || true
+```
+
 The CLI handles:
 - Marking phase checkbox `[x]` with completion date
 - Updating Progress table (Status → Complete, date)
@@ -1447,6 +878,33 @@ teams_webhook_url: "https://outlook.office.com/webhook/..."
 Then verify with `/rihal-notify-test`.
 </step>
 
+<step name="generate_tests">
+**Offer test generation for the completed phase.**
+
+After verification passes and the roadmap is updated, check whether tests were already written as part of the phase plans:
+
+```bash
+TEST_FILES=$(find "${PHASE_DIR}" -name "*test*" -o -name "*spec*" 2>/dev/null | wc -l)
+```
+
+If `TEST_FILES` is 0 — no test artifacts were produced during execution. Present the test generation offer:
+
+```
+## ✓ Phase {X}: {Name} — Add Tests?
+
+No test files were generated during this phase.
+Run /rihal-add-tests to generate unit + E2E tests from the SUMMARY:
+
+/rihal-add-tests {X} ${Rihal_WS}
+
+Skip if tests are out of scope for this phase (infra, config, docs-only).
+```
+
+If `TEST_FILES` is > 0 — tests were written inline. Skip this step silently.
+
+**This step is advisory only — it never blocks phase completion.**
+</step>
+
 <step name="offer_next">
 
 **Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/rihal-plan {X} --gaps`). No additional routing needed — skip auto-advance.
@@ -1505,6 +963,7 @@ Read and follow `.rihal/workflows/transition.md`, passing through the `--auto` f
 ```
 ## ✓ Phase {X}: {Name} Complete
 
+/rihal-add-tests {X} ${Rihal_WS} — generate unit + E2E tests for this phase
 /rihal-progress ${Rihal_WS} — see updated roadmap
 /rihal-discuss-phase {next} ${Rihal_WS} — discuss next phase before planning
 /rihal-plan {next} ${Rihal_WS} — plan next phase