@hanzlaa/rcode 4.10.0 → 4.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.10.0",
+  "version": "4.10.2",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/agents/rcode-haitham.md

@@ -19,6 +19,7 @@ color: cyan
 @.rcode/references/response-style.md
 @.rcode/references/codebase-grounding.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/persona-executor-mode.md
 @.rcode/references/persona-engineer-shared.md
 @.rcode/skills/agents/haitham-frontend/SKILL.md
 

package/rcode/agents/rcode-hanzla.md

@@ -15,4 +15,5 @@ color: green
 @.rcode/references/agent-shared-rules.md
 @.rcode/references/codebase-grounding.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/persona-executor-mode.md
 @.rcode/skills/agents/hanzla-engineer/SKILL.md

package/rcode/agents/rcode-omar.md

@@ -17,6 +17,7 @@ color: green
 @.rcode/references/response-style.md
 @.rcode/references/codebase-grounding.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/persona-executor-mode.md
 @.rcode/references/persona-engineer-shared.md
 
 # Omar (عمر) — Software Engineer (generalist)

package/rcode/agents/rcode-waleed.md

@@ -17,6 +17,7 @@ color: green
 @.rcode/references/agent-shared-rules.md
 @.rcode/references/codebase-grounding.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/persona-executor-mode.md
 @.rcode/skills/agents/waleed-architect/SKILL.md
 
 ## Grounding rule (mandatory)

package/rcode/agents/rcode-yousef.md

@@ -18,6 +18,7 @@ color: blue
 @.rcode/references/response-style.md
 @.rcode/references/codebase-grounding.md
 @.rcode/references/karpathy-guidelines.md
+@.rcode/references/persona-executor-mode.md
 @.rcode/references/persona-engineer-shared.md
 @.rcode/skills/agents/yousef-backend/SKILL.md
 

package/rcode/bin/lib/council-panel.cjs

@@ -404,11 +404,21 @@ function normalize(question) {
     .trim();
 }
 
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function matchesKeyword(text, word) {
+  // Word-boundary match, not substring — avoids collisions like
+  // "storage" containing "rag" (#1034 follow-up).
+  return new RegExp('\\b' + escapeRegExp(word) + '\\b').test(text);
+}
+
 function scoreAgent(agentId, normalizedQuestion) {
   const keywords = KEYWORDS[agentId] || [];
   let score = 0;
   for (const { word, weight } of keywords) {
-    if (normalizedQuestion.includes(word)) score += weight;
+    if (matchesKeyword(normalizedQuestion, word)) score += weight;
   }
   const names = AGENT_NAMES[agentId] || [];
   for (const name of names) {
@@ -419,30 +429,30 @@ function scoreAgent(agentId, normalizedQuestion) {
 }
 
 function applyPriorityBoosts(scores, normalizedQuestion) {
-  if (SADIQ_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (SADIQ_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.sadiq = (scores.sadiq || 0) + 5;
   }
-  if (PM_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (PM_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores['hussain-pm'] = (scores['hussain-pm'] || 0) + 3;
   }
-  if (MARKET_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (MARKET_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.mariam = (scores.mariam || 0) + 6; // Mariam leads market questions
     scores['hussain-pm'] = (scores['hussain-pm'] || 0) + 3; // PM follows for scoping
   }
   // Domain boosts — lift the right technical expert when signal is clear
-  if (FE_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (FE_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.haitham = (scores.haitham || 0) + 4;
   }
-  if (BE_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (BE_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.yousef = (scores.yousef || 0) + 4;
   }
-  if (ML_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (ML_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.zayd = (scores.zayd || 0) + 4;
   }
-  if (DEPLOY_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (DEPLOY_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.khalid = (scores.khalid || 0) + 4;
   }
-  if (QUALITY_TRIGGERS.some((t) => normalizedQuestion.includes(t))) {
+  if (QUALITY_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t))) {
     scores.fatima = (scores.fatima || 0) + 4;
   }
   return scores;
@@ -453,16 +463,16 @@ function applyPriorityBoosts(scores, normalizedQuestion) {
  * Returns: 'fe' | 'be' | 'ml' | 'deploy' | 'quality' | 'market' | 'strategic' | 'general'
  */
 function detectDomain(normalizedQuestion, scores) {
-  const isMarket = MARKET_TRIGGERS.some((t) => normalizedQuestion.includes(t));
+  const isMarket = MARKET_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
   if (isMarket) return 'market';
 
-  const isStrategic = SADIQ_TRIGGERS.some((t) => normalizedQuestion.includes(t));
+  const isStrategic = SADIQ_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
 
-  const feTrigger = FE_TRIGGERS.some((t) => normalizedQuestion.includes(t));
-  const beTrigger = BE_TRIGGERS.some((t) => normalizedQuestion.includes(t));
-  const mlTrigger = ML_TRIGGERS.some((t) => normalizedQuestion.includes(t));
-  const deployTrigger = DEPLOY_TRIGGERS.some((t) => normalizedQuestion.includes(t));
-  const qualityTrigger = QUALITY_TRIGGERS.some((t) => normalizedQuestion.includes(t));
+  const feTrigger = FE_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
+  const beTrigger = BE_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
+  const mlTrigger = ML_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
+  const deployTrigger = DEPLOY_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
+  const qualityTrigger = QUALITY_TRIGGERS.some((t) => matchesKeyword(normalizedQuestion, t));
 
   // Multiple technical domains present — fall back to top-scoring agent
   const technicalCount = [feTrigger, beTrigger, mlTrigger, deployTrigger, qualityTrigger].filter(Boolean).length;
@@ -566,12 +576,12 @@ function explainSelection(question, opts = {}) {
   const panel = selectPanel(question, opts);
   return {
     question, normalized, scores, panel, domain,
-    sadiq_triggered: SADIQ_TRIGGERS.some((t) => normalized.includes(t)),
-    pm_triggered: PM_TRIGGERS.some((t) => normalized.includes(t)),
-    fe_triggered: FE_TRIGGERS.some((t) => normalized.includes(t)),
-    be_triggered: BE_TRIGGERS.some((t) => normalized.includes(t)),
-    ml_triggered: ML_TRIGGERS.some((t) => normalized.includes(t)),
-    deploy_triggered: DEPLOY_TRIGGERS.some((t) => normalized.includes(t)),
+    sadiq_triggered: SADIQ_TRIGGERS.some((t) => matchesKeyword(normalized, t)),
+    pm_triggered: PM_TRIGGERS.some((t) => matchesKeyword(normalized, t)),
+    fe_triggered: FE_TRIGGERS.some((t) => matchesKeyword(normalized, t)),
+    be_triggered: BE_TRIGGERS.some((t) => matchesKeyword(normalized, t)),
+    ml_triggered: ML_TRIGGERS.some((t) => matchesKeyword(normalized, t)),
+    deploy_triggered: DEPLOY_TRIGGERS.some((t) => matchesKeyword(normalized, t)),
   };
 }
 

package/rcode/references/planner-playbook.md

@@ -74,6 +74,7 @@ depends_on: [sprint-id, ...]
 files_modified: [paths...]
 autonomous: true | false             # false if has checkpoints
 requirements: [REQ-01, REQ-02]        # MUST NOT be empty
+owner: yousef                        # OPTIONAL — see below
 
 must_haves:
   truths: [...]                       # Observable outcomes from user perspective
@@ -82,6 +83,8 @@ must_haves:
 ---
 ```
 
+**`owner:` field.** If this plan is grounded in a council session (a `.planning/council-sessions/council-*.md` file is referenced in `<context>` as the authoritative decision), set `owner:` to the id of that session's lead/highest-consensus technical persona for THIS sprint's dominant work — one of `haitham`, `hanzla`, `omar`, `waleed`, `yousef` (the engineer personas with execute permission; `sadiq`/`fatima`/others are advisory-only and never valid here). Pick by domain match: a sprint whose `files_modified` is mostly `src/routes|services|models` → `yousef` (backend); mostly `src/components|pages` → `haitham` (frontend); architecture-level, cross-cutting → `waleed`; general/full-stack with no clear split → `hanzla`. If there was no council session, or the domain split is genuinely ambiguous, omit `owner:` entirely — `execute-sprint.md` defaults to the generic `rcode-executor` when the field is absent. Do not guess an owner just to fill the field; an absent `owner:` is the correct, safe default.
+
 ## Dependency Graph Rules
 
 **For each story:**
@@ -170,6 +173,19 @@ requirements: [...]
 must_haves: {truths, artifacts, key_links}
 ---
 
+## Sprint {phase}.{plan}: {one-line sprint goal, plain English, no jargon}
+
+{2-4 sentence plain-English recap: what this sprint builds and why, written for someone who will never open the XML tags below}
+
+**Tasks:**
+1. {task 1 title, plain English — copy the <title> text verbatim, no XML}
+2. {task 2 title}
+3. {task N title}
+
+_Below this line is the execution prompt the agent reads — task bodies, read-first file lists, verification commands. Not meant for skimming._
+
+---
+
 <objective>...</objective>
 <execution_context>
 @.rcode/workflows/execute-sprint.md
@@ -192,6 +208,8 @@ must_haves: {truths, artifacts, key_links}
 <output>Create `.planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md`</output>
 ```
 
+**Summary block cost/rule:** the plain-English recap above the `---` divider is 1 title line + 2-4 sentences + a numbered list of task titles you're already writing for each `<title>` tag — copy, don't re-derive. Do not summarize `<action>` bodies, do not restate `<verify>` commands, do not add anything not already stated elsewhere in the file. If a sprint has more than ~10 tasks, list only the first 8 titles plus `...and N more (see tasks below)` rather than growing the summary unboundedly.
+
 ## Common Planning Mistakes to Avoid
 
 1. **Empty requirements:** Every plan MUST list requirement IDs from ROADMAP. No empty requirements field.

package/rcode/workflows/council.md

@@ -274,7 +274,18 @@ Selected: {panel agents}
 Excluded (0 score): {agents with score=0, comma-separated}
 ```
 
-**If `config.mode === 'guided'`:** confirm with the user:
+**Inline yolo override (checked before `config.mode`):** council can be invoked directly by a user OR dispatched by `/rcode-do` after it already detected yolo intent (literal `--auto` flag, persisted `config.mode: yolo`, or natural-language phrasing like "yolo mode" / "autonomous mode" / "without pausing" — see `do.md`'s `parse_args` step). Check `$ARGUMENTS` for the same signal here, since council can run standalone and never pass through `do.md`:
+
+```bash
+INLINE_YOLO=false
+if echo "$ARGUMENTS" | grep -qiE '(--auto\b|\byolo\b|\bautonomous(ly)? mode\b|\bno pauses?\b|\bwithout (asking|stopping|pausing)\b)'; then
+  INLINE_YOLO=true
+fi
+```
+
+**If `INLINE_YOLO=true` OR `config.mode === 'yolo'`:** print the panel one-liner and proceed without confirmation.
+
+**Else (`config.mode === 'guided'` and no inline signal):** confirm with the user:
 
 ```
 Panel for this question: <comma-separated display names>
@@ -283,8 +294,6 @@ Proceed? [Y/n]
 
 Use the AskUserQuestion tool (not raw stdin) for the confirmation.
 
-**If `config.mode === 'yolo'`:** print the panel one-liner and proceed without confirmation.
-
 ## Step 4 — Spawn the panel in parallel (two rounds)
 
 ### Round 1 — Independent perspectives
@@ -619,5 +628,12 @@ node .rcode/bin/rcode-tools.cjs state record-session
 
 ## Next Up
 
-- `/rcode-plan` — plan implementation based on the council's recommendation
+Check `project-status` before suggesting `/rcode-plan`:
+
+```bash
+PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
+```
+
+- If `PROJECT_STATUS` is `real` (a phase already exists): `/rcode-plan {phase-number}` — plan implementation based on the council's recommendation
+- Otherwise (`uninstalled`/`uninitialized`/`stub`, no phase exists yet): `/rcode-add-phase` — create a phase for this work first, then `/rcode-plan` will work
 - `/rcode-decisions` — review decisions the council produced

package/rcode/workflows/do.md

@@ -28,6 +28,12 @@ if [[ "$ARGUMENTS" == *"--auto"* ]]; then
   AUTO_MODE=true
   QUESTION=$(echo "$ARGUMENTS" | sed 's/--auto[[:space:]]*//' | xargs)
 fi
+# Natural-language yolo intent — users say "on yolo mode" / "yolo mode" /
+# "in autonomous mode" in free text far more often than they type --auto.
+# Detect it the same way as the literal flag (#1034/#1035 follow-up).
+if echo "$ARGUMENTS" | grep -qiE '(\byolo\b|\bautonomous(ly)? mode\b|\bno pauses?\b|\bwithout (asking|stopping|pausing)\b)'; then
+  AUTO_MODE=true
+fi
 # Also auto-dispatch in yolo mode
 CONFIG_MODE=$(node .rcode/bin/rcode-tools.cjs config-get mode 2>/dev/null || echo "guided")
 if [[ "$CONFIG_MODE" == "yolo" ]]; then
@@ -143,6 +149,45 @@ LAST_SHIPPED_VERSION=$(grep -m1 -oE 'v[0-9]+\.[0-9]+' .planning/MILESTONES.md 2>
 These flags drive the greenfield guard AND the explicit_intent_check below. `.planning/` existing alone is not enough — we need to know whether the methodology chain has actually run (PRD → milestone → epics → phases) AND which milestone is currently open.
 </step>
 
+<step name="compound_chain_preflight" priority="first-match">
+**Detect compound/chained requests and preflight the whole chain before dispatching step one.**
+
+`/rcode-do` is a single-dispatch router by design — it normally picks ONE command and hands off. But real input often chains several actions in one sentence (e.g. "scan and init my project & get council decision on X and plan and execute on yolo mode"). If the router just dispatches to the first-matched command and lets each downstream skill discover its own missing prerequisites, the user sees red errors scattered mid-flight instead of one clear picture up front (issue #1034/#1035).
+
+**Detection:** `$QUESTION` matches this step if it contains 2+ pipeline-stage signals joined by `and`/`&`/`then`/`,`. Pipeline-stage signals: `scan`/`map`, `init`, `council`/`decide`/`architect`, `plan`, `execute`/`build`/`implement`/`yolo`.
+
+**If detected, run one consolidated readiness check before dispatching anything:**
+
+```bash
+PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
+```
+
+Using `$PROJECT_STATUS`, `$HAS_PRD`, `$HAS_PHASES` (already computed in `check_project`), and any `--agents=` list the user named, build the ordered stage list implied by the request and check each stage's precondition against state already on hand — do not re-derive it per stage, and do not spawn anything yet:
+
+| Stage (if requested) | Precondition | If unmet |
+|---|---|---|
+| scan/map | none | always runnable |
+| init | none — auto-init guard already ran | always runnable |
+| council | none, BUT if the user passed an explicit `--agents=` list, validate every id against the roster now: `sadiq, hussain-pm, waleed, ahmed-hassani, nasser, layla, zahra, haitham, yousef, zayd, fatima, khalid, mariam, noor` | flag unknown ids and show the valid list in the preflight report — do not let council fail on this mid-run |
+| plan | a phase must exist (`$PROJECT_STATUS == real` OR `$HAS_PHASES == true`) after council — since council alone does not create a phase | note that `/rcode-add-phase` will run between council and plan to create one |
+| execute | a plan (SPRINT.md) must exist for the phase — this is always true after a successful plan stage in the same chain | n/a within a single chain |
+
+Print one consolidated block before touching any subagent:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► CHAIN PREFLIGHT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Detected stages: {ordered list, e.g. scan → init → council → add-phase → plan → execute}
+{✓ or ⚠ per stage, with the one-line reason for any ⚠}
+{if --agents had unknown ids: "⚠ Unknown agent id(s): {ids}. Valid: {roster list}. Continuing with the corrected/auto-selected panel."}
+```
+
+Then dispatch the stages in order via the `Skill` tool, one at a time, re-using this preflight's state instead of letting each stage rediscover it. If a stage's precondition is genuinely unmet and nothing in the chain fixes it (e.g. user asked to `plan` but not `council`/`add-phase` and no phase exists), stop before dispatching that stage and tell the user which single command to run first — do not let it fail loudly mid-chain.
+
+This step does not replace `greenfield_guard` or `explicit_intent_check` below — it only applies when a *chain* is detected. Single-verb requests fall through to those steps as before.
+</step>
+
 <step name="greenfield_guard" priority="first-match">
 **Block methodology inversion.**
 

package/rcode/workflows/execute-sprint.md

@@ -12,9 +12,28 @@ Read config.yaml for planning behavior settings.
 
 <available_agent_types>
 Valid rcode subagent types (use exact names — do not fall back to 'general-purpose'):
-- rcode-executor — Executes plan tasks, commits, creates SUMMARY.md
+- rcode-executor — Executes plan tasks, commits, creates SUMMARY.md (default)
+- rcode-haitham / rcode-hanzla / rcode-omar / rcode-waleed / rcode-yousef — same execution contract as rcode-executor (via `@.rcode/references/persona-executor-mode.md`), used ONLY when `owner:` in SPRINT.md frontmatter names one of them (see `owner_agent_resolution` below)
 </available_agent_types>
 
+<step name="owner_agent_resolution">
+**Resolve which agent actually executes this plan.**
+
+Read the `owner:` field from the SPRINT.md frontmatter (set by `/rcode-plan` from the council decision's lead persona, when one exists — see `plan.md`'s `owner_field` step). This is a plain frontmatter read, not a new tool call.
+
+```bash
+SPRINT_OWNER=$(grep -m1 '^owner:' .planning/phases/XX-name/{phase}-{plan}-SPRINT.md 2>/dev/null | sed 's/^owner:[[:space:]]*//' | tr -d '"' | xargs)
+VALID_OWNERS="haitham hanzla omar waleed yousef"
+if [[ -n "$SPRINT_OWNER" ]] && echo "$VALID_OWNERS" | grep -qw "$SPRINT_OWNER"; then
+  EXEC_AGENT="rcode-${SPRINT_OWNER}"
+else
+  EXEC_AGENT="rcode-executor"
+fi
+```
+
+Use `$EXEC_AGENT` as the `subagent_type` in every Task spawn below (Pattern A, Pattern B subagent route). No other change to the spawn prompt is needed — the persona file's own conditional clause tells it to load the full executor playbook when it sees `subagent_type` = itself and a SPRINT.md path in the prompt. If `$EXEC_AGENT` is a persona and that persona is not installed (agent file missing), fall back to `rcode-executor` and note the fallback in SUMMARY.md's Deviations section — do not fail the sprint over this.
+</step>
+
 <process>
 
 <preflight name="dependency_check">
@@ -122,9 +141,9 @@ grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-SPRINT.md
 | Verify-only | B (segmented) | Segments between checkpoints. After none/human-verify → SUBAGENT. After decision/human-action → MAIN |
 | Decision | C (main) | Execute entirely in main context |
 
-**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → spawn Task(subagent_type="rcode-executor", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
+**Pattern A:** init_agent_tracking → capture `EXPECTED_BASE=$(git rev-parse HEAD)` → run `owner_agent_resolution` to get `$EXEC_AGENT` → spawn Task(subagent_type="$EXEC_AGENT", model=executor_model) with prompt: execute plan at [path], autonomous, all tasks + SUMMARY + commit, follow deviation/auth rules, report: plan name, tasks, SUMMARY path, commit hash → track agent_id → wait → update tracking → report. **Include `isolation="worktree"` only if `workflow.use_worktrees` is not `false`** (read via `config-get workflow.use_worktrees`). **When using `isolation="worktree"`, include a `<worktree_branch_check>` block in the prompt** instructing the executor to run `git merge-base HEAD {EXPECTED_BASE}` and, if the result differs from `{EXPECTED_BASE}`, reset the branch base with `git reset --soft {EXPECTED_BASE}` before starting work. This corrects a known issue on Windows where `EnterWorktree` creates branches from `main` instead of the feature branch HEAD.
 
-**Post-install namespace fallback:** If `Task(subagent_type="rcode-executor")` fails with "Agent type not found", the runtime has not yet registered the agent (requires IDE reload after install). Retry with `subagent_type="rihal-executor"`. If that also fails, fall back to Pattern C (execute in main context) and log `[execute-sprint] rcode-executor not available — reload IDE or executing in main context`.
+**Post-install namespace fallback:** If `Task(subagent_type="$EXEC_AGENT")` fails with "Agent type not found": if `$EXEC_AGENT` was a persona (not `rcode-executor`), retry once with `subagent_type="rcode-executor"` (the persona may not be installed in this project) and note the fallback in SUMMARY.md. If `rcode-executor` itself fails "Agent type not found", the runtime has not yet registered the agent (requires IDE reload after install) — retry with `subagent_type="rihal-executor"`. If that also fails, fall back to Pattern C (execute in main context) and log `[execute-sprint] ${EXEC_AGENT} not available — reload IDE or executing in main context`.
 
 **Pattern B:** Execute segment-by-segment. Autonomous segments: spawn subagent for assigned tasks only (no SUMMARY/commit). Checkpoints: main context. After all segments: aggregate, create SUMMARY, commit. See segment_execution.
 
@@ -363,6 +382,35 @@ TASK_COMMIT=$(git rev-parse --short HEAD)
 TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
 ```
 
+**5.5. Sync dashboard state (closes the manual/`--wave N` state-sync gap):**
+
+The dashboard reads task status from `.rcode/state.json`'s `phases[].sprints[].stories[]`, not from SUMMARY.md or git. `state story move` only works on a story that's already registered — and the planner does not register stories into state.json when it writes SPRINT.md (see `#590` fallback in `scanner.js`). Without this step, a task that is fully committed and tested still shows "todo" on the dashboard until the ENTIRE phase's status flips to complete, which is silently wrong for any partial/single-wave run (`--wave N`, a manually re-run single plan, a checkpoint-interrupted resume).
+
+Run this after every task's commit, not just at the end of the plan:
+
+```bash
+# Ensure the parent sprint is marked active (idempotent — no-op if already started)
+node ".rcode/bin/rcode-tools.cjs" state sprint start --sprint "${SPRINT_ID}" >/dev/null 2>&1
+
+# Try to move the story directly by its SPRINT.md task id first
+MOVE_RESULT=$(node ".rcode/bin/rcode-tools.cjs" state story move --id "${TASK_ID}" --status done 2>&1)
+if echo "$MOVE_RESULT" | grep -qi "not found"; then
+  # Story was never registered (planner doesn't pre-register) — register it now.
+  # state story add assigns ids in {sprint}.{N} sequence matching the order
+  # tasks are added, which matches SPRINT.md's own <task id> numbering as
+  # long as tasks are committed in the order they appear in the file.
+  node ".rcode/bin/rcode-tools.cjs" state story add --sprint "${SPRINT_ID}" --title "${TASK_TITLE}" >/dev/null 2>&1
+  node ".rcode/bin/rcode-tools.cjs" state story move --id "${TASK_ID}" --status done >/dev/null 2>&1
+fi
+```
+
+Non-fatal: if either `rcode-tools.cjs` call fails for a reason other than "not found" (e.g. state.json corrupted), log a one-line warning and continue — dashboard staleness is not a reason to fail a task that verified and committed successfully.
+
+When the whole plan finishes (all tasks done), mark the sprint complete too:
+```bash
+node ".rcode/bin/rcode-tools.cjs" state sprint complete --sprint "${SPRINT_ID}" >/dev/null 2>&1
+```
+
 **6. Check for untracked generated files:**
 ```bash
 git status --short | grep '^??'

package/rcode/workflows/map-codebase.md

@@ -52,13 +52,20 @@ End with closure banner + top findings summary:
 If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 
 ```
-/rcode-map-codebase <argument-here>
+/rcode-map-codebase <a short description of the codebase or why you're mapping it>
 ```
 
-**Examples:**
+The description isn't used to scope or filter what gets mapped — all 4 mapper
+agents (tech, architecture, conventions, concerns) always cover the whole
+codebase regardless of what you write here. It exists as an intentional
+non-empty confirmation, not a topic filter — `/rcode-scan --focus <topic>` is
+the command for a narrower, single-topic pass.
+
+**Examples (any of these work identically — the text just needs to be non-empty):**
 ```
-/rcode-map-codebase example 1
-/rcode-map-codebase example 2
+/rcode-map-codebase full codebase
+/rcode-map-codebase onboarding a new engineer, need the full picture
+/rcode-map-codebase before a major refactor
 ```
 
 STOP — do not proceed.

package/rcode/workflows/plan.md

@@ -81,7 +81,7 @@ PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || e
 If `PROJECT_STATUS` is `uninstalled`, `uninitialized`, or `stub`:
 
 ```
-Project not initialized. Run /rcode-init first (or /rcode-new-project for a greenfield project), then return here.
+Project not initialized for planning. Run /rcode-new-project (full roadmap) or /rcode-add-phase (if you just want to add one phase), then return here.
 ```
 
 Stop. Do not proceed until `project-status` returns `real`.

package/server/lib/html/client/views/DecisionsView.js

@@ -28,7 +28,7 @@ export function DecisionsView() {
   if (!decisions.length) {
     return html`
       <div id="view-decisions" class="view active">
-        <div class="view-title">Decisions (ADRs)</div>
+        <div class="view-title">Decisions (Architecture Decision Records — ADRs)</div>
         <div class="empty">
           No decisions recorded yet.
           <div class="empty-action">Decisions made during /rcode-council appear here</div>
@@ -47,7 +47,7 @@ export function DecisionsView() {
 
   return html`
     <div id="view-decisions" class="view active">
-      <div class="view-title">Decisions (ADRs)</div>
+      <div class="view-title">Decisions (Architecture Decision Records — ADRs)</div>
       <div class="filter-bar">
         <input
           class="filter-input"