@hanzlaa/rcode 4.7.3 → 4.9.0

package/rcode/skills/actions/4-implementation/rcode-sprint-status/SKILL.md

@@ -15,6 +15,8 @@ triggers:
   - "where are we in the sprint"
 user-invocable: true
 ---
+
+<!-- Bridge status: not currently invoked by any rcode/workflows/*.md file (no delegate_to_skill cross-reference exists in either direction). Reachable only via direct phrase-trigger match or explicit @-inclusion. See AUDIT-redundant-work.md finding 3. -->
 @.rcode/references/karpathy-guidelines.md
 
 

package/rcode/skills/agents/haitham-frontend/SKILL.md

@@ -53,6 +53,12 @@ This skill embodies Haitham (هيثم), senior frontend engineer archetype. Hait
 
 rcode's frontend stack: **React 18+, Next.js 15 App Router, TypeScript strict, Tailwind v4, shadcn/ui, Framer Motion, next-intl for Arabic-English localization.** Haitham follows these conventions without needing to be told.
 
+## Dispatch Mode
+
+Invoking this skill directly (triggers like "talk to Haitham", "build this UI") loads Haitham's persona instructions **inline into the current session** — no isolated context, no `Task()` call. This is structured roleplay, not a spawned subagent.
+
+For genuine isolated Task-tool dispatch, Haitham is separately registered as a Task-dispatchable agent (`rcode-haitham`, see `rcode/agents/rcode-haitham.md`) and is spawned for real, isolated-context dispatch by `/rcode-council`. It is **not yet** wired into `/rcode-execute` — that workflow currently spawns only the generic `rcode-executor` subagent type; routing execution work to persona-specific agents like this one is pending issue #1003 (in progress in parallel on branch `fix-execute-routing`). Unlike Hanzla, there is currently no `@haitham` shortcut in `do.md`'s `@persona CODE` alias table.
+
 ## Identity
 
 Senior frontend engineer specializing in Next.js App Router, TypeScript, Tailwind, shadcn/ui, and bilingual (Arabic-English) web apps. Committed to pixel-perfect craft, accessibility, and performance.

package/rcode/skills/agents/hanzla-engineer/SKILL.md

@@ -49,6 +49,12 @@ user-invocable: true
 
 This skill embodies Hanzla (حنظلة), senior full-stack engineer archetype. It executes approved stories with strict adherence to story details, writes tests before marking work complete, and refactors only incrementally. Hanzla never rewrites code from scratch, never commits code he doesn't understand, and never lies about test status.
 
+## Dispatch Mode
+
+Invoking this skill directly (triggers like "talk to Hanzla", "implement this") loads Hanzla's persona instructions **inline into the current session** — no isolated context, no `Task()` call. This is structured roleplay, not a spawned subagent.
+
+For genuine isolated Task-tool dispatch, Hanzla is separately registered as a Task-dispatchable agent (`rcode-hanzla`, see `rcode/agents/rcode-hanzla.md`) and is spawned for real, isolated-context dispatch by `/rcode-council`. It is **not yet** wired into `/rcode-execute` — that workflow currently spawns only the generic `rcode-executor` subagent type; routing execution work to persona-specific agents like this one is pending issue #1003 (in progress in parallel on branch `fix-execute-routing`). `do.md`'s `@persona CODE` shortcut table already has an alias for this persona (`@hanzla`, aliases: hanzla/dev/engineer) as its deterministic API surface.
+
 ## Identity
 
 Senior software engineer who executes approved stories with strict adherence to story details and team standards. Pragmatic, test-driven, and allergic to premature abstractions.

package/rcode/skills/agents/hussain-pm/SKILL.md

@@ -142,7 +142,7 @@ State the rule by name when refusing.
    - What's explicitly out of scope?
    - Kill criteria: when would we stop this project?
 2. After answers, draft PRD with: Problem, User, Scope, Success Metrics, Kill Criteria, Out-of-Scope
-3. Save to `.rcode/phases/{current}/prd.md`
+3. Save to `.planning/prd.md`
 
 ### Edge Case: Vague Request
 **Input:** "We need a feature for notifications"

package/rcode/skills/agents/hussain-sm/SKILL.md

@@ -79,7 +79,7 @@ Crisp and checklist-driven. Every word has a purpose. Zero tolerance for ambigui
 | SP | Generate or update the sprint plan that sequences tasks for the dev agent | rcode-sprint-planning |
 | CS | Prepare a story with all required context for implementation | rcode-create-story |
 | SS | Generate sprint status report from current epics and stories | rcode-sprint-status |
-| ER | Multi-agent review of all work completed across an epic (retrospective) | rcode-retrospective |
+| ER | Structured single-session retrospective roleplay covering all work completed across an epic | rcode-retrospective |
 | CC | Determine how to proceed if major change is discovered mid-implementation | rcode-correct-course |
 
 ## Workflow
@@ -108,7 +108,7 @@ Crisp and checklist-driven. Every word has a purpose. Zero tolerance for ambigui
 **Input:** "Prepare the next story from the backlog"
 
 **Expected behavior:**
-1. Read `.rcode/phases/{current}/epics.md` and find next unstarted story
+1. Read `.planning/epics/EPIC-{NN}.md` and find next unstarted story
 2. Create story file with ALL sections populated:
    - Goal (one sentence)
    - Context (references to PRD, architecture, UX)
@@ -117,7 +117,7 @@ Crisp and checklist-driven. Every word has a purpose. Zero tolerance for ambigui
    - Dependencies (other stories, external systems)
    - File List (empty — for Hanzla to fill)
    - Dev Agent Record (empty — for Hanzla to fill)
-3. Save to `.rcode/phases/{current}/stories/story-{id}.md`
+3. Save to `.planning/epics/stories/{N}.{M}.md`
 4. Report: "Story {id} ready. Assign to Hanzla with `rcode-dev-story {path}`."
 
 ### Edge Case: Ambiguous Story from User

package/rcode/skills/agents/majlis-council/references.md

@@ -30,13 +30,23 @@ In Omani and Arab tradition, a Majlis is a gathering where voices are heard befo
 
 ## Dispatch modes
 
-Majlis has two execution modes:
-
-**Real mode (default).** Dispatches actual subagents via the `Task` tool. Each agent runs in isolated context, genuinely parallel, with uncontaminated reasoning. Use for high-stakes decisions and demos.
-
-**Fast mode.** Single-Claude structured roleplay following each agent's SKILL.md principles. Fallback for harnesses without subagent support, or for quick sanity checks. Faster but reasoning runs in shared context.
-
-When in doubt, use real mode.
+Within this skill, the CV/CVF/QC/DM/CM convene-mode sub-skills listed in SKILL.md's
+Capabilities table are **not yet implemented** — do not claim real Task-tool dispatch
+is available through this skill today.
+
+**For genuine parallel, isolated-context subagent dispatch, use the separate
+`/rcode-council` slash command** (`rcode/workflows/council.md`) — a different,
+already-working implementation: deterministic panel scoring, parallel Task-tool
+spawning (not sequential roleplay), and structured artifact output to
+`.planning/council-sessions/`.
+
+**Fast mode (the only mode this skill currently supports).** Single-Claude
+structured roleplay following each agent's SKILL.md principles, in shared context.
+Use this skill (phrase-triggered: "convene the majlis", "consult the team", etc.)
+only when a `/rcode-council` slash-command invocation isn't available or a quick
+sanity check is enough.
+
+When real, isolated-context dispatch matters, prefer `/rcode-council` over this skill.
 
 ---
 

package/rcode/skills/agents/raees-orchestrator/SKILL.md

@@ -45,7 +45,9 @@ user-invocable: true
 
 ## Overview
 
-Raees (رئيس) dispatches the right specialists for execution. Where Majlis convenes the full council for discussion, Raees runs the dispatch desk. He knows every agent's authority and dependencies, parallelises ruthlessly where possible, sequences strictly where necessary, and escalates to Majlis when a question crosses into strategy. The full dispatch matrix and rcode-specific context awareness live in [`references.md`](references.md).
+Raees (رئيس) produces a dispatch **plan** — text output for a human (or another workflow) to act on, not a dispatch action. Where Majlis convenes the full council for discussion, Raees works out who should own what: he reasons about every agent's authority and dependencies, identifies what can run in parallel vs. what must sequence strictly, and flags when a question should escalate to Majlis instead. The full dispatch matrix and rcode-specific context awareness live in [`references.md`](references.md).
+
+**No live routing mechanism exists yet.** The DP/SQ/PL/HO sub-skills in the Capabilities table below are planned, not implemented — there is no `Task()` call, no `rcode-raees*` subagent, and no automatic handoff. Raees writes the plan; a human or another command (e.g. `/rcode-execute`) is what actually carries it out today.
 
 ## Capabilities
 
@@ -76,10 +78,10 @@ Raees (رئيس) dispatches the right specialists for execution. Where Majlis co
 
 ## Output Format
 
-Dispatch plans use this exact structure:
+Dispatch plans use this exact structure — this is the deliverable, a document, not a log of actions taken:
 
 ```
-Dispatch: <request summary>
+Dispatch Plan: <request summary>
 
 Step 1 (BLOCKING):  <agent> → <skill> — delivers: <output>
 Step 2 (PARALLEL):  <agent A> → <task A> | <agent B> → <task B>
@@ -88,29 +90,29 @@ Step 3 (BLOCKING):  <agent> → <skill> — gate
 
 Always show: primary owner, dependencies (arrows or "blocked by"), parallel opportunities.
 
-Save dispatch plans to `.rcode/progress/dispatch-{date}.md`.
+Save the plan to `.rcode/progress/dispatch-{date}.md`. Raees does not invoke the agents named in the plan — no `Task()` call is made. Executing the plan is a separate, manual step for the user (or a workflow like `/rcode-execute`, once persona routing lands there).
 
-Do NOT include: diffuse responsibility, unowned tasks, or silent handoffs. Do NOT synthesise strategic decisions — that's Majlis's job. Do NOT override specialist authority.
+Do NOT include: diffuse responsibility, unowned tasks, or silent handoffs. Do NOT synthesise strategic decisions — that's Majlis's job. Do NOT override specialist authority. Do NOT phrase output as if dispatch already happened ("invoked", "dispatching X now") — phrase it as a recommendation ("plan calls for X", "recommended: assign to X").
 
 ## Examples
 
 **Happy path — feature request**
-"Add Arabic RTL support to our dashboard" → touches UX (Layla), FE (Haitham), BE (Yousef), QA (Fatima), localisation (Noor) → 5-step plan with Layla blocking, Haitham/Yousef/Noor in parallel, Fatima gate, Khalid ship → saved to `.rcode/progress/dispatch-{date}.md` → Layla invoked first.
+"Add Arabic RTL support to our dashboard" → touches UX (Layla), FE (Haitham), BE (Yousef), QA (Fatima), localisation (Noor) → produces a 5-step plan with Layla blocking, Haitham/Yousef/Noor in parallel, Fatima gate, Khalid ship → saved to `.rcode/progress/dispatch-{date}.md`. The plan lists Layla as step 1; nothing is actually invoked.
 
 **Happy path — government proposal**
-"Ministry of Housing wants a property management proposal" → context triggers compliance-first + Arabic-first + data residency → Sadiq (research) → Waleed (compliance) → parallel Mariam + Zayd → Noor (full document Arabic + English) → Sadiq final review.
+"Ministry of Housing wants a property management proposal" → context triggers compliance-first + Arabic-first + data residency → plan sequences: Sadiq (research) → Waleed (compliance) → parallel Mariam + Zayd → Noor (full document Arabic + English) → Sadiq final review.
 
 **Edge case — single-owner task**
-"Fix the typo in the footer" — don't build a plan. "Single-owner task. Dispatching Haitham directly. No coordination needed."
+"Fix the typo in the footer" — don't build a multi-step plan. Output: "Single-owner task. Recommended: assign to Haitham directly. No coordination needed." (a recommendation, not an action).
 
 **Edge case — strategic question**
-"Should we enter the Saudi market?" — don't dispatch. Escalate: "Cross-domain strategic question — handing to Majlis. I'll reconvene for execution once Majlis has a verdict."
+"Should we enter the Saudi market?" — don't produce a dispatch plan. Recommend escalation: "Cross-domain strategic question — recommend routing to Majlis. Re-run this once Majlis has a verdict."
 
 **Edge case — conflicting specialists**
-Waleed wants approach A, Yousef wants approach B. Do NOT pick. Escalate to Majlis with the conflict framed.
+Waleed wants approach A, Yousef wants approach B. Do NOT pick. Recommend escalation to Majlis with the conflict framed.
 
 **Negative — single-domain UX question**
-"What colour should the button be?" — Layla owns this directly. Redirect.
+"What colour should the button be?" — Layla owns this directly. Redirect, don't produce a plan.
 
 ## Memory Bank Hooks
 

package/rcode/skills/agents/yousef-backend/SKILL.md

@@ -50,6 +50,12 @@ user-invocable: true
 
 This skill embodies Yousef (يوسف), senior backend engineer archetype. Yousef builds APIs, databases, data pipelines, and integration services — with particular expertise in data management, RPA (Robotic Process Automation), and enterprise/government integrations.
 
+## Dispatch Mode
+
+Invoking this skill directly (triggers like "talk to Yousef", "build the backend") loads Yousef's persona instructions **inline into the current session** — no isolated context, no `Task()` call. This is structured roleplay, not a spawned subagent.
+
+For genuine isolated Task-tool dispatch, Yousef is separately registered as a Task-dispatchable agent (`rcode-yousef`, see `rcode/agents/rcode-yousef.md`) and is spawned for real, isolated-context dispatch by `/rcode-council`. It is **not yet** wired into `/rcode-execute` — that workflow currently spawns only the generic `rcode-executor` subagent type; routing execution work to persona-specific agents like this one is pending issue #1003 (in progress in parallel on branch `fix-execute-routing`). Unlike Hanzla, there is currently no `@yousef` shortcut in `do.md`'s `@persona CODE` alias table.
+
 ## Identity
 
 Senior backend engineer specializing in REST/GraphQL APIs, relational and time-series databases, data pipelines, and system integrations. Focused on correctness, reliability, and observability.

package/rcode/templates/github/epic-template.md

@@ -54,4 +54,4 @@
 
 ---
 
-<sub>Generated by rcode — `.rcode/phases/{{phase}}/tasks/{{source_file}}`</sub>
+<sub>Generated by rcode — `.planning/phases/{{phase}}/{{source_file}}`</sub>

package/rcode/templates/github/feature-template.md

@@ -52,4 +52,4 @@
 
 ---
 
-<sub>Generated by rcode — `.rcode/phases/{{phase}}/stories/{{source_file}}`</sub>
+<sub>Generated by rcode — `.planning/phases/{{phase}}/{{source_file}}`</sub>

package/rcode/templates/github/task-template.md

@@ -49,4 +49,4 @@
 
 ---
 
-<sub>Generated by rcode — `.rcode/phases/{{phase}}/tasks/{{source_file}}`</sub>
+<sub>Generated by rcode — `.planning/phases/{{phase}}/{{source_file}}`</sub>

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/add-phase.md

@@ -29,11 +29,21 @@ Exit.
 Load phase operation context:
 
 ```bash
-INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "0" 2>/dev/null)
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "1" 2>/dev/null)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-If `INIT` is empty or `INIT.ok` is false, print error and exit:
+`init phase-op` only populates the phase-aware fields (`roadmap_exists`,
+`planning_exists`, `phase_found`, ...) when its `question` argument's first
+token parses as an integer `> 0` (rcode-tools.cjs's `phase-op` handler gates
+on `phaseNum > 0`). add-phase has no target phase to pass — it's creating a
+new one — so a placeholder is required. `"0"` fails that guard, silently
+dropping `roadmap_exists` from every response (#1017); `"1"` satisfies it.
+The dummy value only affects unused fields like `phase_found`/`phase_name`
+(harmless here) — `roadmap_exists` itself is purely a file-existence check
+and doesn't depend on phase 1 actually existing.
+
+If `INIT` is empty, print error and exit:
 ```
 Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
 ```
@@ -92,7 +102,13 @@ The CLI handles:
 - Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
 - Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
 
-Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`,
+`milestone_health` (object: `open_phases`, `recommendation`, `threshold_should`,
+`threshold_consider`), `nudge` (present only when `recommendation` isn't
+`healthy` — a ready-to-print one-liner naming the milestone). `phase add`
+computes these via `milestoneCloseNudge()` (issue #942) as part of the same
+call, so `milestone_health_check` below reads them straight off `$RESULT`
+instead of re-deriving them.
 
 **If `BULK_MODE=true`:** after the CLI returns, write the bulk body to `${directory}/TASKS.md` per the structure defined in `detect_task_list`. This step is non-destructive — it only ADDs a TASKS.md file inside the new phase directory.
 </step>
@@ -110,26 +126,30 @@ If "Roadmap Evolution" section doesn't exist, create it.
 </step>
 
 <step name="milestone_health_check">
-After the phase is added, run the milestone-health gauge (issue #718):
+After the phase is added, read the milestone-health gauge (issue #718)
+straight off the `phase add` result captured in `add_phase` — no extra
+subprocess calls. Previously this step spawned a separate `milestone-health`
+call plus 3 `node -e` JSON field extractions to re-derive data that `phase
+add` already returns inline via `milestoneCloseNudge()` (#942); that was
+4 wasted calls per phase-add for data already sitting in `$RESULT` (#1018).
 
-```bash
-HEALTH=$(node ".rcode/bin/rcode-tools.cjs" milestone-health 2>/dev/null)
-RECOMMENDATION=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).recommendation||'unknown')}catch{console.log('unknown')}})")
-OPEN_COUNT=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).open_phases||0)}catch{console.log(0)}})")
-MILESTONE_NAME=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).milestone||'')}catch{console.log('')}})")
+```
+RECOMMENDATION="$RESULT.milestone_health.recommendation"   # e.g. healthy | consider-closing | should-close
+OPEN_COUNT="$RESULT.milestone_health.open_phases"
+NUDGE="$RESULT.nudge"                                       # ready-to-print, names the milestone; absent when healthy
 ```
 
 If `RECOMMENDATION` is `should-close` (≥12 open phases), surface a hard nudge:
 
 ```
-⚠ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases.
+⚠ {NUDGE}
 
 Phase {N} is now in this milestone, but the milestone is well past the
 12-phase threshold for considering closure. Phases are accumulating without
 a milestone boundary — historically this is where roadmaps lose structure.
 
 Recommended next step:
-  /rcode-complete-milestone    close {MILESTONE_NAME} cleanly + archive done phases
+  /rcode-complete-milestone    close the milestone cleanly + archive done phases
   /rcode-new-milestone         start a fresh milestone for ongoing work
 
 If you genuinely want a giant single-milestone roadmap, ignore this and
@@ -139,11 +159,10 @@ continue. The threshold is conservative on purpose.
 If `RECOMMENDATION` is `consider-closing` (8-11 open phases), softer nudge:
 
 ```
-ℹ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases — getting full.
-   Consider /rcode-complete-milestone before adding more.
+ℹ {NUDGE}
 ```
 
-If `RECOMMENDATION` is `healthy`, say nothing.
+If `RECOMMENDATION` is `healthy` or `milestone_health` is absent (no state.json / no milestone), say nothing.
 </step>
 
 <step name="completion">

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

@@ -198,11 +198,10 @@ Deviations are normal — handle via rules below.
    - `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.
+     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 `<done>` 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".
+     - If `<verify><automated>` is absent: fall back to `<done>` alone. `<evidence>` (grep hits, line ranges, or a creates-justification recorded by the planner per issue #649) is supporting grounding, not a completion signal to re-check here — the real plan schema (planner-playbook.md, sprint.md) has no such tag.
+   - **MANDATORY completion check:** After completing each task, confirm `<verify><automated>` passes (or, if absent, that the task's `<done>` sentence is observably true). Use grep, file reads, or CLI commands to confirm. If any check fails, fix the implementation before proceeding. Do not skip this or mark it as "will verify later".
 3. Run `<verification>` checks
 4. Confirm `<success_criteria>` met
 5. Document deviations in Summary
@@ -378,6 +377,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 +395,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).