@hanzlaa/rcode 4.7.2 → 4.8.0

package/rcode/templates/sprint.md

@@ -13,9 +13,20 @@
 
 ## Stories
 
-| ID | Title | Points | Status | Done when |
-|----|-------|--------|--------|-----------|
-| {story_id} | {title} | {points} | {status} | {verifiable_ac} |
+<!-- One <task> block per story. id= and <title> are REQUIRED (scanner.js's primary parse path) -->
+<tasks>
+<task id="{sprint_id}.{NN}" type="auto">
+<title>{story title}</title>
+<read_first>{files + line ranges the executor must read before writing}</read_first>
+<files>{exact paths this task creates/modifies}</files>
+<action>{specific implementation instructions}</action>
+<verify>
+  <automated>{command < 60 sec}</automated>
+</verify>
+<done>{measurable acceptance criteria}</done>
+<evidence>{grep/lines/creates evidence per issue #649}</evidence>
+</task>
+</tasks>
 
 ## Capacity
 

package/rcode/templates/verification-report.md

@@ -10,11 +10,14 @@ phase: NN
 phase_name: <slug>
 verifier: <agent / human>
 verified_at: <ISO date>
-verdict: pass | fail | partial
+status: passed | gaps_found | human_needed
 goal_source: ROADMAP.md (commit-sha-at-phase-start)
 ---
 ```
 
+`status` is the ONLY key `execute.md`'s `uat_gate` step reads (`grep -qE "^status:[[:space:]]*passed"`). Do not
+substitute `result`, `verdict`, or `outcome` — a wrong key silently strands the phase at `status: executed` forever.
+
 ## Sections
 
 ### Phase goal (verbatim)
@@ -63,9 +66,9 @@ What the phase changed BEYOND the goal. Often these are silent:
 
 Each side effect should be intentional and documented.
 
-### Verdict reasoning
+### Status reasoning
 
-One paragraph explaining why the verdict (pass / fail / partial) was chosen. Include any judgment calls.
+One paragraph explaining why the status (passed / gaps_found / human_needed) was chosen. Include any judgment calls.
 
 ### Follow-ups
 
@@ -79,5 +82,5 @@ Issues filed (or to file) for gaps surfaced during verification:
 ```
 Verifier: <name or agent id>
 Date: <ISO>
-Verdict: <verdict from frontmatter>
+Status: <status from frontmatter>
 ```

package/rcode/workflows/code-review-fix.md

@@ -1,5 +1,5 @@
 <purpose>
-Auto-fix issues from REVIEW.md. Validates phase, checks config gate, verifies REVIEW.md exists and has fixable issues, spawns rcode-fixer agent, handles --auto iteration loop (capped at 3), commits REVIEW-FIX.md once at the end, and presents results.
+Auto-fix issues from REVIEW.md. Validates phase, checks config gate, verifies REVIEW.md exists and has fixable issues, spawns rcode-code-fixer agent, handles --auto iteration loop (capped at 3), commits REVIEW-FIX.md once at the end, and presents results.
 </purpose>
 
 <required_reading>
@@ -9,7 +9,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 </required_reading>
 
 <available_agent_types>
-- rcode-fixer: Applies fixes to code review findings
+- rcode-code-fixer: Applies fixes to code review findings
 - rcode-reviewer: Reviews source files for bugs and issues
 </available_agent_types>
 
@@ -202,7 +202,7 @@ If REVIEW.md contains a `files_reviewed_list` frontmatter field, use that as the
 </step>
 
 <step name="spawn_fixer">
-Spawn the rcode-fixer agent with config:
+Spawn the rcode-code-fixer agent with config:
 
 ```bash
 # Build config for agent
@@ -295,7 +295,7 @@ if [ "$AUTO_MODE" = "true" ]; then
     
     # Spawn rcode-reviewer agent to re-review
     # (This overwrites REVIEW_PATH with latest review state)
-    Task(subagent_type="rcode-code-reviewer",
+    Task(subagent_type="rcode-reviewer",
   model="{model}", prompt="
 <config>
 depth: ${REVIEW_DEPTH}
@@ -527,7 +527,7 @@ echo "════════════════════════
 
 - [ ] Config gate (`workflow.code_review`) verified before any agent is spawned
 - [ ] `REVIEW.md` confirmed present at `.planning/phases/<N>/REVIEW.md`; workflow exits with explicit error if missing
-- [ ] `rcode-fixer` agent spawned with correct `review_path`, `fix_scope`, and `fix_report_path`
+- [ ] `rcode-code-fixer` agent spawned with correct `review_path`, `fix_scope`, and `fix_report_path`
 - [ ] `--auto` iteration loop capped at 3 rounds; each round re-reviews only the original file scope
 - [ ] `REVIEW-FIX.md` committed exactly once at the end of all iterations (not per iteration)
 - [ ] Results presented inline with a concrete next-step suggestion (e.g., `git log --oneline`)

package/rcode/workflows/code-review.md

@@ -388,7 +388,7 @@ done
 Spawn the rcode-reviewer agent:
 
 ```
-Task(subagent_type="rcode-code-reviewer",
+Task(subagent_type="rcode-reviewer",
   model="{model}", prompt="
 <files_to_read>
 ${FILES_TO_READ}

package/rcode/workflows/council.md

@@ -157,6 +157,7 @@ Parse the JSON for:
 - `flags.explain` — boolean, show panel scoring
 - `panel` — string[], the pre-computed panel (respects `--full` and `--agents`)
 - `scores` — object, per-agent scoring for explain mode
+- `domain` — string, the detected question domain (`fe`/`be`/`ml`/`deploy`/`strategic`/`market`/`general`) — always populated, used for the `Domain:` banner field
 - `question_type` — `"codebase" | "discovery" | "market" | "greenfield"` — drives Step 1 branching
 - `question_signals` — string[], matched phrases that drove the classification
 - `config` — `{ user_name, project_name, language, mode }` from `.rcode/config.yaml`

package/rcode/workflows/create-epics-and-stories.md

@@ -4,6 +4,16 @@
 Parse a PRD, PROJECT.md, or project document to generate numbered epic files in `.planning/epics/`. Each epic file contains user stories with acceptance criteria, development notes, and effort estimates. Output is ready for `/rcode-sprint-planning`.
 </purpose>
 
+> **Note (experimental, no execution consumer):** the epics/stories/dev-story pipeline this
+> workflow is part of is not wired to `/rcode-execute` today — `rcode-executor` only reads
+> `*-SPRINT.md` files (see `rcode/agents/rcode-executor.md`). The only way to "run" a story
+> produced here is the manual `/rcode {dev-prompt-file}` invocation documented in
+> `rcode/workflows/dev-story.md`, which has none of `/rcode-execute`'s atomic-commit,
+> checkpoint, wave, or verification machinery. Treat this pipeline as experimental /
+> unsupported for production execution until a decision is made to either wire it to
+> `/rcode-execute` or deprecate it in favor of the SPRINT.md pipeline (see
+> `AUDIT-redundant-work.md` finding 2).
+
 
 <available_agent_types>
 - `rcode-roadmapper` — reads PRD/context and generates epic structure
@@ -378,11 +388,7 @@ If arguments are invalid, missing files, or subagent fails:
 
 ## ▶ Next Up
 
-- /rcode-sprint-planning
-- /rcode-dev-story {story-id}
-- /rcode-edit-prd
-
-## Next Up
-
 - `/rcode-sprint-planning` — plan the sprint from the generated epic files
+- `/rcode-dev-story {story-id}`
+- `/rcode-edit-prd`
 - `/rcode-create-story` — develop individual stories into self-contained STORY.md files

package/rcode/workflows/dev-story.md

@@ -336,11 +336,9 @@ This story is "Done" when all items in checklist-story-dod.md are checked:
 
 ## Running This Story
 
-To execute with an AI coder:
-
-```bash
-/rcode .planning/dev-sessions/{story-id}-dev-prompt.md
-```
+This file is the execution context for an AI coder — there is no standalone command that consumes it directly. Either:
+- Continue in the session that has this context loaded and say "let's build this," or
+- Fold the story into a phase (`/rcode-add-phase`) and run `/rcode-execute {phase-number}` for a full plan/build cycle with checkpoints.
 
 ---
 
@@ -388,7 +386,9 @@ Acceptance Criteria: {count}
 
 Context file: {path to dev-prompt.md}
 
-Next: /rcode {path to dev-prompt.md}
+Ready to code this story? Two real options:
+  1. Continue this session — I already have full story context loaded, just say "let's build this"
+  2. Fold it into a phase (/rcode-add-phase) and run /rcode-execute {phase-number} for a full plan/build cycle with checkpoints
 
 Or, continue the current session to:
   - Ask clarifying questions
@@ -396,24 +396,22 @@ Or, continue the current session to:
   - Review dependencies
 ```
 
-## Step 6 — Optional: Spawn AI Coder
+## Step 6 — Next Step: Continue or Fold Into a Phase
 
-If user says "start coding" or "let's build", spawn the code execution workflow:
+There is no standalone command that consumes a dev-prompt.md file directly (`/rcode`, no hyphen, does not exist — every rcode command is hyphenated). This step never spawns anything; it only tells the user how to proceed.
 
-```bash
-# User says "let's go" or "start", then:
-/rcode "$DEV_PROMPT_FILE"
-```
+If the user says "start coding" or "let's build", continue implementing directly in the current session — it already has the full story context loaded from Step 3-4.
 
 Otherwise, offer:
 
 ```
 Ready to code this story?
 
-/rcode {dev-prompt-file}
+1. Continue in this session — say "let's build this" and I'll implement it directly.
+2. Fold it into a phase (/rcode-add-phase) and run /rcode-execute {phase-number} for a full plan/build cycle with checkpoints.
 ```
 
-Stop and wait for user to proceed. Do NOT auto-spawn.
+Stop and wait for user to proceed. Do NOT auto-spawn — this workflow only wraps the story, it never executes it.
 
 ## Errors
 

package/rcode/workflows/do.md

@@ -6,10 +6,11 @@ Analyze freeform text from the user and route to the most appropriate rcode comm
 @.rcode/references/auto-init-guard.md
 @.rcode/references/output-format.md
 @.rcode/references/verb-dictionary.md
-@.rcode/references/dispatch-banner.md
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>
 
+`.rcode/references/dispatch-banner.md` is NOT required reading here — its banner format is scoped to real `Task(subagent_type=...)` spawns. `/rcode-do` never spawns a Task/subagent (see guardrails); it only dispatches via the `Skill` tool, so it uses the plain `ROUTING` banner defined in the `display` step below.
+
 <process>
 
 <step name="auto_init_check">
@@ -71,7 +72,7 @@ Match if `$QUESTION` starts with `@<persona> <CODE>` or `@<persona>:<CODE>` —
    {list from the persona's Capabilities table}
    ```
    And stop. Do not fall back to fuzzy intent matching — the user used the deterministic API, honour it.
-5. Dispatch directly via the routing banner. Skip greenfield_guard / external_data_guard / explicit_intent_check / route — the user already chose the persona AND the action. The persona itself can still refuse internally if its preconditions aren't met.
+5. Dispatch directly: show the plain `ROUTING` banner (the `display` step's format — "Routing to: {chosen command}") and call the `Skill` tool. Skip greenfield_guard / external_data_guard / explicit_intent_check / route — the user already chose the persona AND the action. This is a `Skill()` dispatch, not a `Task(subagent_type=...)` spawn, so it does NOT use the persona-voiced `dispatch-banner.md` format. The persona itself can still refuse internally if its preconditions aren't met.
 
 **This is the deterministic API surface.** Power users (and other agents in council follow-ups) can invoke specific capabilities without re-reading triggers or risking fuzzy match. It's the cheapest way to get repeatable behaviour out of the persona system.
 
@@ -423,15 +424,17 @@ If the chosen command expects a phase number and one wasn't provided in the text
 </process>
 
 <guardrails>
-**Hard prohibitions during /rcode-do execution (issue #458):**
+**Hard prohibitions during /rcode-do execution (issue #458, refined by #1007):**
+
+The steps above (`parse_args`, `check_project`, `auto_init_check`, `greenfield_guard`, `explicit_intent_check`, `persona_shortcut`) legitimately call Bash for structured state/config lookups (`rcode-tools.cjs state load`, `progress init`, `config-get mode`, `classify-question`, milestone/PRD/epic detection via `ls`/`grep`) and Read for the specific persona/capability-table lookup in `persona_shortcut` step 2. That is routing plumbing, not investigation, and is allowed. What's prohibited is using those same tools to figure out the route by inspecting application code, or to do the routed work itself:
 
-- 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 /rcode-do are: AskUserQuestion (for disambiguation), Skill (for dispatch), and the one Bash call to the classifier (`classify-question`). Nothing else.
+- MUST NOT use Bash/Read/Grep/Glob to explore or read application source code to guess what a vague request means. The state/config lookups named above are the only sanctioned uses — anything beyond them (grepping `src/`, reading a feature file to understand behavior, etc.) means the dispatcher contract has failed — STOP and use the no-route exit instead.
+- MUST NOT call Write or Edit. The dispatcher never modifies files.
+- MUST NOT spawn Task / Agent / subagents. Dispatch is a `Skill` tool call to a routed command — nothing else.
+- MUST NOT "do a quick check" of source code before routing. If you feel the urge to grep or read application code to "figure out the right route," the dispatcher contract has already failed — STOP and use the no-route exit.
 - 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.
+Why this is hard: do.md is a router. The moment it does the work itself (as opposed to looking up state to decide *where to route*), 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>
@@ -444,7 +447,7 @@ Why this is hard: do.md is a router. The moment it does work, two failure modes
 - [ ] 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)
+- [ ] No Write/Edit/Task tool calls, and no Bash/Read/Grep/Glob use beyond the sanctioned state/config lookups and persona/capability-table reads
 - [ ] On no-route, exit cleanly with the disambiguation menu — never silently fall through to inline work
 </success_criteria>
 </content>

package/rcode/workflows/execute-sprint.md

@@ -378,6 +378,8 @@ If new untracked files appeared after running scripts or tools, decide for each:
 <hook_revert_detection_gate>
 ## Post-Step Hook Revert Detection Gate
 
+<!-- See also <post_step_revert_gate> below — catches a different revert shape (shrunk, not identical) -->
+
 After each task that writes or edits files, run:
 ```bash
 git diff --name-only HEAD
@@ -394,6 +396,8 @@ Do not proceed to the next task until all expected file changes survive the git
 <post_step_revert_gate>
 ## Post-Step Revert Detection Gate
 
+<!-- See also <hook_revert_detection_gate> above — catches a different revert shape (identical, not shrunk) -->
+
 After committing each task, run a diff check to detect accidental reverts. This catches the class of bug where a task's implementation unknowingly undoes work from a previous task or wave.
 
 **When to run:** After every `git commit` that records a task completion (not after TDD RED commits or style-only commits).

package/rcode/workflows/execute-waves.md

@@ -71,6 +71,47 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    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.
 
+   **Classify plan and select subagent_type (BEFORE spawning, once per plan):**
+
+   Reuse the `files_modified` list already parsed in step 1's intra-wave overlap check for this
+   plan — do not re-read the plan file to get it again.
+
+   ```
+   FRONTEND_GLOBS = ["*.tsx", "*.jsx", "*.css"] + paths containing "client" or "ui"
+   BACKEND_GLOBS  = paths containing "api", "server", "db", or "service"
+
+   touches_frontend = any(file matches FRONTEND_GLOBS for file in files_modified)
+   touches_backend  = any(file matches BACKEND_GLOBS for file in files_modified)
+
+   if touches_frontend and touches_backend:
+     classification = "full-stack"
+   elif touches_frontend:
+     classification = "frontend"
+   elif touches_backend:
+     classification = "backend"
+   else:
+     classification = "other"   # files_modified empty/absent, or no glob matched
+   ```
+
+   **If `classification` is `"other"`** (ambiguous, or `files_modified` empty/absent), fall back
+   to keyword-matching the plan's `<objective>` text before giving up:
+   - Frontend keywords (React, component, UI, CSS, Tailwind, frontend, client-side, accessibility, a11y) → `classification = "frontend"`
+   - Backend keywords (API, endpoint, database, schema, service, queue, backend, server-side) → `classification = "backend"`
+   - Neither matches (pure docs/config/infra plan) → `classification` stays `"other"`
+
+   **Route to `subagent_type`:**
+
+   | classification | subagent_type |
+   |---|---|
+   | frontend | rcode-haitham |
+   | backend | rcode-yousef |
+   | full-stack | rcode-hanzla |
+   | other | rcode-executor |
+
+   This decision is computed once per plan, before that plan's Task() spawn(s) below, and the
+   resulting `subagent_type` value is used in the Task() call template (worktree and sequential
+   modes both reuse this same value — see "Sequential mode" further below).
+
    **Worktree mode** (`USE_WORKTREES` is not `false`):
 
    Before spawning, capture the current HEAD:
@@ -96,7 +137,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
    ```
    Task(
-     subagent_type="rcode-executor",
+     subagent_type="{subagent_type}",
      description="Execute plan {plan_number} of phase {phase_number}",
      model="{executor_model}",
      isolation="worktree",
@@ -105,6 +146,8 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
        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.
+
+       Routing note: this plan touches {classification} paths → dispatched to {subagent_type} (see step 3's classification logic in execute-waves.md).
        </objective>
 
        <!--

package/rcode/workflows/execute.md

@@ -178,12 +178,13 @@ via filesystem and git state.
 </runtime_compatibility>
 
 <required_reading>
-@.rcode/references/auto-init-guard.md
-@.rcode/references/output-format.md
+<!-- If chained from plan.md's --auto (Skill(), same context), these 3 are already loaded — see AUDIT-workflow-complexity.md finding 3. -->
+${AUTO_CHAINED_FROM_PLAN ? '' : '@.rcode/references/auto-init-guard.md'}
+${AUTO_CHAINED_FROM_PLAN ? '' : '@.rcode/references/output-format.md'}
 @.rcode/references/git-preflight.md
 Read STATE.md before any operation to load project context.
 
-@.rcode/references/karpathy-guidelines.md
+${AUTO_CHAINED_FROM_PLAN ? '' : '@.rcode/references/karpathy-guidelines.md'}
 @.rcode/references/execution-protocol.md
 <!-- Read .rcode/references/agent-contracts.md only if debugging agent contract violations -->
 <!-- Read .rcode/references/context-budget.md only if context degradation guidance is needed -->
@@ -204,8 +205,11 @@ Always use the exact name from this list — do not fall back to 'general-purpos
 - rcode-integration-checker — Checks cross-phase integration
 - rcode-nyquist-auditor — Validates verification coverage
 - rcode-ux-designer — Researches UI/UX approaches
-- rcode-ui-auditor — Reviews UI implementation quality
 - rcode-ui-auditor — Audits UI against design requirements
+- rcode-hanzla — Senior Full-Stack Engineer — full-stack plans spanning both frontend and backend
+- rcode-yousef — Senior Backend Engineer — backend-only plans (API, DB, services, queues)
+- rcode-haitham — Senior Frontend Engineer — frontend-only plans (React/Next.js/Tailwind/CSS/RTL/a11y)
+- rcode-omar — Software Engineer (generalist) — fallback for cross-stack or small ambiguous plans when Hanzla isn't the clear fit
 </available_agent_types>
 
 <process>
@@ -335,46 +339,10 @@ Write these answers inline before continuing. If a blocking anti-pattern cannot
 
 **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 `.rcode/workflows/execute-sprint.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.
-      **Overwrite guard:** If the SUMMARY.md file already exists from a previous run, delete it first with `rm -f <path>` before writing the new version. Never append to or skip an existing SUMMARY.md — always overwrite with the current sprint's completion data.
-
-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 rcode's planning/tracking structure
-- Best for: small phases, bug fixes, verification gaps, learning rcode
+```bash
+INTERACTIVE_MODE=$([[ "$ARGUMENTS" =~ (^|[[:space:]])--interactive($|[[:space:]]) ]] && echo true || echo false)
+```
+${INTERACTIVE_MODE === 'true' ? '@.rcode/references/execute-interactive-mode.md' : ''}
 
 **Skip to handle_branching step** (interactive plans execute inline after grouping).
 </step>
@@ -434,10 +402,8 @@ Report:
 ```
 </step>
 
-
 @rcode/workflows/execute-waves.md
 
-
 <step name="checkpoint_handling">
 Plans with `autonomous: false` require user interaction.
 
@@ -646,7 +612,7 @@ generated: <ISO timestamp>
 Group findings by severity. For each finding include: file path, line reference, description, recommended fix.
 
 ${REVIEWER_SKILLS}",
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="${REVIEWER_MODEL}"
 )
 ```
@@ -740,59 +706,16 @@ Only when the gate is clean or the user overrides do we proceed to close_parent_
 
 **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=$(node ".rcode/bin/rcode-tools.cjs" find-phase "${PARENT_PHASE}" --raw)
-# 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
-node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
+IS_GAP_CLOSURE_PHASE=$([[ "$PHASE_NUMBER" == *.* ]] && echo true || echo false)
 ```
+${IS_GAP_CLOSURE_PHASE === 'true' ? '@.rcode/references/execute-close-parent-artifacts.md' : ''}
 </step>
 
-
 @rcode/workflows/execute-regression-gates.md
 
-
-
 @rcode/workflows/execute-verify-phase-goal.md
 
-
 <step name="uat_gate" priority="blocker">
 **UAT gate:**
 
@@ -899,24 +822,13 @@ node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-{X}): complete phase execut
 <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 `.rcode/knowledge/`.
-
 **Check config gate:**
 ```bash
 GL_ENABLED=$(node ".rcode/bin/rcode-tools.cjs" config-get features.global_learnings --raw 2>/dev/null || echo "false")
 ```
 
 **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
-node ".rcode/bin/rcode-tools.cjs" learnings copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
-```
-Copy failure must NOT block phase completion.
+${GL_ENABLED === 'true' ? '@.rcode/references/execute-auto-copy-learnings.md' : ''}
 </step>
 
 <step name="update_project_md">
@@ -947,21 +859,10 @@ node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-{X}): evolve PROJECT.md aft
 Silent no-op if no webhook URLs are in `.rcode/config.yaml`. Failures are reported but never block the workflow.
 
 ```bash
-node ".rcode/bin/rcode-tools.cjs" notify send \
-  --title "Phase ${phase_number} complete — ${phase_name}" \
-  --body "$(basename "$PWD") · $(git rev-parse --short HEAD) · ${incomplete_count:-0} plan(s) remaining" \
-  --event "execute-done" 2>/dev/null || true
+WEBHOOK_CONFIGURED=$(node ".rcode/bin/rcode-tools.cjs" config-get slack_webhook_url 2>/dev/null; node ".rcode/bin/rcode-tools.cjs" config-get discord_webhook_url 2>/dev/null; node ".rcode/bin/rcode-tools.cjs" config-get teams_webhook_url 2>/dev/null)
+WEBHOOK_CONFIGURED=$([ -n "$WEBHOOK_CONFIGURED" ] && echo true || echo false)
 ```
-
-Users configure webhooks by editing `.rcode/config.yaml`:
-
-```yaml
-slack_webhook_url: "https://hooks.slack.com/services/..."
-discord_webhook_url: "https://discord.com/api/webhooks/..."
-teams_webhook_url: "https://outlook.office.com/webhook/..."
-```
-
-Then verify with `/rcode-notify-test`.
+${WEBHOOK_CONFIGURED === 'true' ? '@.rcode/references/execute-notify-webhooks.md' : ''}
 </step>
 
 <step name="generate_tests">
@@ -1075,7 +976,7 @@ For 1M+ context models, consider:
 </context_efficiency>
 
 <failure_handling>
-- **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not rcode. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
+- See the classifyHandoffIfNeeded workaround in execute-waves.md (already @-included above).
 - **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

package/rcode/workflows/lens-audit.md

@@ -196,7 +196,7 @@ FINDINGS[security] = merge(PRIMARY, SECONDARY)
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="Audit-only — do NOT optimize anything. {CONTEXT}
   
@@ -288,7 +288,7 @@ FINDINGS[extensibility] = RESULT
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-dep-auditor",
   model="{lens_model}",
   prompt="Audit-only — do NOT install or update packages. {CONTEXT}
   
@@ -419,7 +419,7 @@ FINDINGS[documentation] = RESULT
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-cross-platform-auditor",
   model="{lens_model}",
   prompt="Cross-platform audit — do NOT fix scripts. {CONTEXT}
   
@@ -446,7 +446,7 @@ FINDINGS[cross-platform] = RESULT
 
 ```
 PRIMARY = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="Karpathy 4-principle audit — do NOT fix code. {CONTEXT}
   
@@ -516,7 +516,7 @@ FINDINGS[sxo] = RESULT
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-observability-auditor",
   model="{lens_model}",
   prompt="Observability audit — do NOT add instrumentation. {CONTEXT}
   
@@ -559,7 +559,7 @@ PRIMARY = Task(
 )
 
 SECONDARY = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="Variable naming audit in recent code changes. {CONTEXT}
   
@@ -619,7 +619,7 @@ FINDINGS[coverage] = merge(PRIMARY, SECONDARY)
 
 ```
 PRIMARY = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="YAGNI / over-engineering audit — do NOT fix code. {CONTEXT}
 

package/rcode/workflows/plan-spawn-planner.md

@@ -351,7 +351,6 @@ Fix issues inline. No sub-agent needed — this is a quick self-check before the
 Task(
   prompt=filled_prompt,
   subagent_type="rcode-planner",
-  model="{model}",
   model="{planner_model}",
   description="Plan Phase {phase}"
 )