@hanzlaa/rcode 3.4.3 → 3.4.5

package/rihal/workflows/do.md

@@ -5,6 +5,7 @@ Analyze freeform text from the user and route to the most appropriate Rihal comm
 <required_reading>
 @.rihal/references/output-format.md
 @.rihal/references/verb-dictionary.md
+@.rihal/references/dispatch-banner.md
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>
 
@@ -137,7 +138,7 @@ Apply this guard BEFORE the routing table below:
 | Intent contains... | AND state shows... | Then re-route to... | Why |
 |--------------------|---------------------|----------------------|-----|
 | "draft phases", "all phases", "build all phases", "groom phases", "auto mode" + "phases" | `HAS_PRD=false` | `/rihal-create-prd` first | Phases need a PRD foundation. Without one, the autonomous flow hallucinates requirements. |
-| "execute phase", "build phase N", "run phase N" | `HAS_PHASES=false` OR PLAN.md missing for phase N | `/rihal-plan N` first (or `/rihal-create-prd` if no PRD) | Can't execute what hasn't been planned. |
+| "execute phase", "build phase N", "run phase N" | `HAS_PHASES=false` OR SPRINT.md missing for phase N | `/rihal-plan N` first (or `/rihal-create-prd` if no PRD) | Can't execute what hasn't been planned. |
 | "sprint planning", "plan the sprint" | `HAS_EPICS=false` | `/rihal-create-epics-and-stories` first | Sprints draw stories from epics. No epics = no stories to schedule. |
 | "create stories", "epics" | `HAS_PRD=false` | `/rihal-create-prd` first | Epics decompose a milestone. Milestone needs PRD. |
 | "create milestones", "roadmap" | `HAS_PRD=false` | `/rihal-create-prd` first | Roadmap is derived from PRD success metrics. |
@@ -298,6 +299,8 @@ Evaluate `$QUESTION` against these routing rules. Apply the **first matching** r
 | A note, idea, or "remember to..." | `/rihal-note` | Capture for later |
 | Adding tests, "write tests", "test coverage" | `/rihal-add-tests` | Test generation |
 | Completing a milestone, shipping, releasing | `/rihal-complete-milestone` | Milestone lifecycle |
+| Drift / out-of-date / "verify docs vs code" / "audit feature docs" / "fill out existing PRD/epics/stories" | `/rihal-feature-drift` | Detects PRD↔epics↔stories↔code drift; --fix patches trivial items |
+| General audit / re-audit / extend / fill out / expand an existing artifact | `/rihal-audit` | Unified audit entry — picks artifact type and re-runs |
 | A specific, actionable, small task (add feature, fix typo, update config) | `/rihal-quick` | Self-contained, single executor |
 | Market/discovery/greenfield question (from classify) | `/rihal-council` | Needs multi-perspective discovery |
 
@@ -307,7 +310,20 @@ If no rule matches, fall back to the classifier:
 CLASSIFY=$(node ".rihal/bin/rihal-tools.cjs" classify-question "$QUESTION")
 ```
 
-Parse `type` from JSON — map codebase/team/release → `/rihal-discuss`; market/discovery/greenfield → `/rihal-council`. Default: `/rihal-discuss`.
+Parse `type` from JSON — map codebase/team/release → `/rihal-discuss`; market/discovery/greenfield → `/rihal-council`; drift → `/rihal-feature-drift`. Default: `/rihal-discuss`.
+
+**No-route exit (issue #458):** If neither the routing table nor the classifier yields a confident match, you MUST STOP. Print this disambiguation menu via AskUserQuestion and wait:
+
+```
+I can't route this cleanly. Pick one:
+  1. /rihal-add-phase — if it's a new phase
+  2. /rihal-plan — if scope is clear, jump to plan
+  3. /rihal-discuss-phase — if you want to think through it first
+  4. /rihal-audit — if you want to extend an existing audit/plan
+  5. Describe more specifically what you want
+```
+
+Do NOT execute the work yourself. Do NOT run grep, find, Read, Bash, or Write to "investigate before routing." If you feel the urge to investigate, the dispatcher contract has already failed — STOP and ask.
 
 **Requires `.planning/` directory:** All routes except `/rihal-new-project`, `/rihal-map-codebase`, `/rihal-help`, `/rihal-discuss`, `/rihal-council`. If the project doesn't exist and the route requires it, suggest `/rihal-new-project` first.
 
@@ -341,15 +357,23 @@ Reason: {one-line why}
 </step>
 
 <step name="dispatch">
-**Invoke the chosen command.**
+**Invoke the chosen command via the Skill tool — do NOT just print it as text.**
 
-If `AUTO_MODE` is true OR routing is unambiguous, invoke immediately:
+CRITICAL: The dispatch step is an *action*, not a *display*. You must call the `Skill` tool with `skill: "rihal-{command}"` (and `args:` for any arguments). Printing the slash-command in a code block, in a banner, or in a "Dispatching..." message is NOT dispatch — it is just text rendering, and the routed command will never run. Past failure: model emitted the dispatch banner three times in a row without ever invoking the Skill tool, then stalled.
 
-```
-/rihal-{command} {arguments}
-```
+Canonical form: skills are namespaced with a hyphen, e.g. `rihal-discuss-phase`, `rihal-plan`, `rihal-status`. The colon form `rihal:discuss-phase` is NOT used in this project (avoided for cross-IDE compatibility) — do not display it to users or pass it to the Skill tool.
+
+Rules:
+- One Skill tool call per `/rihal-do` invocation. Never emit the same dispatch banner twice.
+- Do NOT print `/rihal-{command}` inside a fenced code block as your "action" — that is display-only.
+- The routing banner from the `display` step is the ONLY user-facing summary of the dispatch. After it, the very next thing you do is the Skill tool call.
+
+If `AUTO_MODE` is true OR routing is unambiguous:
+1. Confirm the routing banner has been shown once (from the `display` step).
+2. Immediately call the Skill tool: `Skill(skill: "rihal-{command}", args: "{arguments}")`.
+3. Stop. The dispatched command handles everything from here.
 
-Otherwise show suggestion and ask via AskUserQuestion:
+Otherwise (ambiguous, non-auto), use AskUserQuestion to confirm:
 
 ```
 Based on your request, I'd use: /rihal-{command} {arguments}
@@ -359,22 +383,37 @@ Based on your request, I'd use: /rihal-{command} {arguments}
 3. Cancel
 ```
 
-If the chosen command expects a phase number and one wasn't provided in the text, extract it from context or ask via AskUserQuestion.
+On "Yes" → call Skill tool as above. On "Pick a different route" → restart routing. On "Cancel" → stop.
 
-After invoking the command, stop. The dispatched command handles everything from here.
+If the chosen command expects a phase number and one wasn't provided in the text, extract it from context or ask via AskUserQuestion BEFORE the Skill call.
 </step>
 
 </process>
 
+<guardrails>
+**Hard prohibitions during /rihal-do execution (issue #458):**
+
+- MUST NOT call Bash, Read, Grep, Glob, Write, or Edit tools. The dispatcher does not investigate, read code, or write files. Period.
+- MUST NOT spawn Task / Agent / subagents. Dispatch is a Skill tool call to a routed command — nothing else.
+- MUST NOT "do a quick check" before routing. If you feel the urge to grep or read a file to "figure out the right route," the dispatcher contract has already failed — STOP and use the no-route exit.
+- The ONLY tools allowed inside /rihal-do are: AskUserQuestion (for disambiguation), Skill (for dispatch), and the one Bash call to the classifier (`classify-question`). Nothing else.
+- If the user's input doesn't match any route and the classifier is ambiguous: invoke the no-route exit menu. Do not "be helpful" by executing the work yourself.
+
+Why this is hard: do.md is a router. The moment it does work, two failure modes appear: (a) the work is duplicated when the user re-invokes the proper command, or (b) the work happens in the wrong context with the wrong subagent and produces inferior output. Both are worse than a 1-second routing prompt.
+</guardrails>
+
 <success_criteria>
 - [ ] Input validated (not empty)
 - [ ] Intent matched to exactly one Rihal command
 - [ ] Ambiguity resolved via user question (if needed)
 - [ ] Scope-uncertainty signals steer to `/rihal-discuss-phase` over planning routes
 - [ ] Project existence checked for routes that require it
-- [ ] Routing decision displayed before dispatch
-- [ ] Command invoked with appropriate arguments
+- [ ] Routing decision displayed before dispatch (exactly once)
+- [ ] Command invoked via the Skill tool — NOT printed as text
+- [ ] Dispatch banner not repeated (single emission only)
 - [ ] No work done directly — dispatcher only
+- [ ] No Bash/Read/Grep/Write/Edit/Task tool calls during execution (only AskUserQuestion + Skill + classifier Bash)
+- [ ] On no-route, exit cleanly with the disambiguation menu — never silently fall through to inline work
 </success_criteria>
 </content>
 </invoke>

package/rihal/workflows/docs-update.md

@@ -49,6 +49,7 @@ fi
 Extract from project analysis:
 - `doc_writer_model` — model string from agent manifest (never hardcode a model name)
 - `commit_docs` — whether to commit generated files when done (read from `.planning/config.json` if exists)
+- `response_language` — output language from `.rihal/config.yaml` (null = English); if set, include `Respond in {value}.` in all spawned subagent prompts
 - `existing_docs` — find all existing Markdown files with `find docs -name "*.md" 2>/dev/null`
 - `project_type` — detect from: `package.json`, `src/pages/api` or `pages/api`, `bin/` or `cli/`, `LICENSE`, `vercel.json` or `netlify.toml`, `lerna.json` or `pnpm-workspace.yaml`, `test/` or `__tests__/`
 - `doc_tooling` — detect from: `docusaurus.config.js`, `vitepress.config.js`, `mkdocs.yml`, `storybook.js`
@@ -156,6 +157,7 @@ For each doc in the queue, spawn a `rihal-noor` agent in parallel waves (up to 3
 ```
 Task(
   subagent_type="rihal-noor",
+  model="sonnet",
   prompt="
 Generate documentation for {doc_type}.
 Output path: {resolved_path}
@@ -178,6 +180,7 @@ For each generated doc:
 ```
 Task(
   subagent_type="rihal-docs-auditor",
+  model="sonnet",
   prompt="
 Verify this documentation file against the live codebase:
 Path: {resolved_path}

package/rihal/workflows/document-project.md

@@ -72,7 +72,7 @@ For each row in CSV, check if document exists and assess staleness:
 ```bash
 for doc in $(cut -d',' -f1 .rihal/documentation-requirements.csv | tail -n +2); do
   if [ -f "$doc" ]; then
-    MTIME=$(stat -c %Y "$doc")
+    MTIME=$(stat -c %Y "$doc" 2>/dev/null || stat -f %m "$doc" 2>/dev/null)
     NOW=$(date +%s)
     AGE_DAYS=$(( ($NOW - $MTIME) / 86400 ))
     if [ $AGE_DAYS -gt 90 ]; then echo "STALE"; fi
@@ -178,3 +178,9 @@ If .rihal/DOCS-AUDIT.md exists, check for missing/stale docs:
 - If CSV malformed: use template
 - If audit agent fails: provide manual audit template
 - If state write fails: skip task filing, report audit only
+
+## ▶ Next Up
+
+- **Documentation updated:** `/rihal-progress` — see current project state
+- **Proceed to planning:** `/rihal-plan {phase}` — create executable plans
+- **Review with council:** `/rihal-council {question}` — debate approach

package/rihal/workflows/edit-prd.md

@@ -0,0 +1,31 @@
+# Workflow: rihal-edit-prd
+
+<purpose>
+Update an existing PRD with revisions or clarifications. Delegates to the rihal-edit-prd skill.
+</purpose>
+
+## Execution
+
+Locate and follow the installed skill:
+
+```bash
+find .rihal/skills/actions -path "*rihal-edit-prd/workflow.md" 2>/dev/null | head -1
+```
+
+Read and follow the workflow at that path. If the path is empty:
+
+```
+Skill not installed — run: npx @hanzlaa/rcode install
+```
+
+## On Completion
+
+/rihal-validate-prd — validate after edits
+/rihal-plan — re-plan phases from the updated PRD
+/rihal-create-prd — start fresh if edits are too extensive
+
+## ▶ Next Up
+
+- **PRD updated:** `/rihal-validate-prd` — check completeness after changes
+- **Ready to plan:** `/rihal-create-milestone` — build milestone roadmap from PRD
+- **Review epics:** `/rihal-create-epics-and-stories` — update stories if scope changed

package/rihal/workflows/enable-hooks.md

@@ -62,7 +62,7 @@ Verify that the hook binary exists and is executable:
 ```bash
 if [ ! -f .rihal/bin/rihal-hooks.cjs ]; then
   echo "⚠ Hook binary missing at .rihal/bin/rihal-hooks.cjs"
-  echo "  Run: node /tmp/rihal-src/cli/install-v2.js . --force --yes"
+  echo "  Run: npx @hanzlaa/rcode install --force --yes"
   exit 1
 fi
 node .rihal/bin/rihal-hooks.cjs --help 2>&1 || true

package/rihal/workflows/execute-regression-gates.md

@@ -0,0 +1,131 @@
+<purpose>
+Sub-steps of execute.md — regression_gate and schema_drift_gate. Runs post-execution regression checks and schema drift detection before advancing to verification.
+</purpose>
+
+<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 | sort | tail -5)
+```
+
+**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 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>
+

package/rihal/workflows/execute-sprint.md

@@ -21,7 +21,7 @@ Valid Rihal subagent types (use exact names — do not fall back to 'general-pur
 Load execution context (paths only to minimize orchestrator context):
 
 ```bash
-INIT=$(node ".rihal/bin/rihal-tools.cjs" init execute-phase "${PHASE}")
+INIT=$(node ".rihal/bin/rihal-tools.cjs" init execute "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
@@ -60,6 +60,23 @@ PLAN_START_EPOCH=$(date +%s)
 ```
 </step>
 
+<step name="create_phase_snapshot">
+Create a pre-execution git tag so `/rihal-undo --phase NN --to-snapshot` can restore to this exact state.
+Only runs when inside a git repository (skip silently otherwise).
+
+```bash
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+  SNAPSHOT_TAG="rihal/snapshot/phase-${PHASE_NUMBER}"
+  if git rev-parse --verify "refs/tags/${SNAPSHOT_TAG}" >/dev/null 2>&1; then
+    git tag -d "${SNAPSHOT_TAG}" >/dev/null 2>&1
+  fi
+  git tag -a "${SNAPSHOT_TAG}" -m "Pre-execution snapshot for phase ${PHASE_NUMBER}" HEAD 2>/dev/null \
+    && echo "✓ Snapshot: ${SNAPSHOT_TAG} @ $(git rev-parse --short HEAD)" \
+    || echo "⚠ Could not create snapshot tag (non-fatal)"
+fi
+```
+</step>
+
 <step name="parse_segments">
 ```bash
 grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-SPRINT.md
@@ -146,6 +163,11 @@ Deviations are normal — handle via rules below.
    - **MANDATORY read_first gate:** If the task has a `<read_first>` field, you MUST read every listed file BEFORE making any edits. This is not optional. Do not skip files because you "already know" what's in them — read them. The read_first files establish ground truth for the task.
    - `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary.
    - `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation.
+   - **Task completion precedence (when signals conflict):**
+     1. `<verify><automated>` — machine-executable shell commands. **Highest authority.** If these pass, the task is done. If these fail, the task is NOT done — regardless of what `<acceptance_criteria>` says.
+     2. `<done>` — single observable sentence. Use as the human-readable confirmation once automated checks pass.
+     3. `<acceptance_criteria>` — prose checklist. **Lowest authority.** Use as a guide during implementation, but automated results override prose judgments.
+     - If `<verify><automated>` is absent: fall back to `<done>`, then `<acceptance_criteria>`.
    - **MANDATORY acceptance_criteria check:** After completing each task, if it has `<acceptance_criteria>`, verify EVERY criterion before moving to the next task. Use grep, file reads, or CLI commands to confirm each criterion. If any criterion fails, fix the implementation before proceeding. Do not skip criteria or mark them as "will verify later".
 3. Run `<verification>` checks
 4. Confirm `<success_criteria>` met
@@ -400,6 +422,13 @@ One-liner SUBSTANTIVE: "JWT auth with refresh rotation using jose library" not "
 
 Include: duration, start/end times, task count, file count.
 
+**Fill the knowledge-transfer sections (omit any with nothing substantive to say):**
+
+- **Patterns Established** — Any new architectural/coding patterns introduced. Future plans should follow these. Example: "All service errors now wrap in ServiceError(code, message)". If none, omit.
+- **Provides** — Specific functions, APIs, models, config keys, or contracts this plan exposes for future plans to build on. Be concrete: function names and file paths.
+- **Requires** — What this plan consumed from prior phases. Helps trace dependency chains.
+- **Affects** — Later phases or components that may need re-verification because of what changed here.
+
 Next: more plans → "Ready for {next-plan}" | last → "Phase complete, ready for next step".
 </step>
 
@@ -500,7 +529,7 @@ If `USER_SETUP_CREATED=true`: display `⚠️ USER SETUP REQUIRED` with path + e
 
 | Condition | Route | Action |
 |-----------|-------|--------|
-| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/rihal-execute-phase {phase}` + `/rihal-verify-work`. STOP here. |
+| summaries < plans | **A: More plans** | Find next PLAN without SUMMARY. Yolo: auto-continue. Interactive: show next plan, suggest `/rihal-execute {phase}` + `/rihal-verify-work`. STOP here. |
 | summaries = plans, current < highest phase | **B: Phase done** | Show completion, suggest `/rihal-plan-phase {Z+1}` + `/rihal-verify-work {Z}` + `/rihal-discuss-phase {Z+1}` |
 | summaries = plans, current = highest phase | **C: Milestone done** | Show banner, suggest `/rihal-complete-milestone` + `/rihal-verify-work` + `/rihal-add-phase` |
 

package/rihal/workflows/execute-verify-phase-goal.md

@@ -0,0 +1,136 @@
+<purpose>
+Sub-step of execute.md — verify_phase_goal. Spawns rihal-verifier to confirm the phase achieved its GOAL, not just completed tasks. Creates VERIFICATION.md.
+</purpose>
+
+<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 — most recent 5 phases only (regression check)
+` : ''}
+</files_to_read>
+
+${VERIFIER_SKILLS}",
+  subagent_type="rihal-verifier",
+  model="sonnet",
+  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>