@hanzlaa/rcode 4.8.0 → 4.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.8.0",
+  "version": "4.9.1",
   "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-code-reviewer.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/code-reviewer-playbook.md
 

package/rcode/agents/rcode-docs-auditor.md

@@ -6,7 +6,7 @@ color: yellow
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 @.rcode/references/docs-auditor-playbook.md

package/rcode/agents/rcode-edge-case-hunter.md

@@ -6,7 +6,7 @@ color: red
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 

package/rcode/agents/rcode-security-adversary.md

@@ -6,7 +6,7 @@ color: red
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 

package/rcode/agents/rcode-security-auditor.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 

package/rcode/agents/rcode-sprint-checker.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/sprint-checker-playbook.md
 
 <role>

package/rcode/agents/rcode-verifier.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/verifier-playbook.md
 

package/rcode/bin/lib/brain.cjs

@@ -243,7 +243,22 @@ function cmdBrain(args, { PROJECT_ROOT, RCODE_DIR }) {
     const os = require('os');
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rcode-brain-'));
     const branch = s.branch || cfg.defaults?.branch || 'main';
-    const sparsePaths = Array.isArray(s.paths) ? s.paths : [];
+    // #1029 — `sparse-checkout set --no-cone` treats each path as a
+    // .gitignore-style pattern, not a literal path pin. A bare filename
+    // (no '/', no wildcard) matches that filename at any depth in the repo
+    // tree, over-fetching every same-named file repo-wide. Anchor bare
+    // filenames to the repo root with a leading '/' so they pin the
+    // root-level file only. Patterns that already start with '/', contain a
+    // '/', or use wildcards (already scoped or intentionally recursive) are
+    // left untouched.
+    function anchorBareFilename(p) {
+      const str = String(p || '');
+      if (str.startsWith('/')) return str;
+      if (/[*?[]/.test(str)) return str;
+      if (str.includes('/')) return str;
+      return `/${str}`;
+    }
+    const sparsePaths = (Array.isArray(s.paths) ? s.paths : []).map(anchorBareFilename);
 
     // Cache key = sha1(repo + branch + sparsePaths joined). Changing any of
     // those gets a fresh cache slot. Different projects pulling the same

package/rcode/bin/lib/gitignore.cjs

@@ -1,7 +1,5 @@
 /**
- * Gitignore — extracted from rcode-tools.cjs (issue #204). Pure mechanical
- * move, no behavior change (including the pre-existing `slice_end` typo in
- * spliceBlock, left untouched — out of scope for this extraction).
+ * Gitignore — extracted from rcode-tools.cjs (issue #204).
  */
 
 const fs = require('fs');
@@ -102,8 +100,8 @@ function cmdGitignore(args, { PROJECT_ROOT, RCODE_DIR }) {
     let sliceStart = start;
     if (sliceStart > 0 && existing[sliceStart - 1] === '\n') sliceStart -= 1;
     let sliceEnd = endIdx + END.length;
-    if (existing[slice_end] === '\n') slice_end += 1;
-    return existing.slice(0, sliceStart) + newBlock + existing.slice(slice_end);
+    if (existing[sliceEnd] === '\n') sliceEnd += 1;
+    return existing.slice(0, sliceStart) + newBlock + existing.slice(sliceEnd);
   }
 
   if (!fs.existsSync(gitignorePath)) {

package/rcode/bin/rcode-hooks.cjs

@@ -743,7 +743,10 @@ function parseSimpleYamlInline(text) {
 /**
  * Read prompt_nudge from .rcode/config.yaml.
  * Returns 'every' | 'once-per-intent' | 'when-stale' | 'off'.
- * Defaults to 'every' when key is absent, file is missing, or value is unknown.
+ * Defaults to 'once-per-intent' when key is absent, file is missing, or value
+ * is unknown — #953: 'every' re-nudged on every matching prompt during an
+ * active session, which read as noise once the keyword matcher's false
+ * positives compounded it. 'every' is still available as an opt-in.
  */
 function readPromptNudgeToggle(cwd) {
   const VALID = new Set(['every', 'once-per-intent', 'when-stale', 'off']);
@@ -752,9 +755,9 @@ function readPromptNudgeToggle(cwd) {
     const text = fs.readFileSync(cfgPath, 'utf8');
     const parsed = parseSimpleYamlInline(text);
     const val = (parsed.prompt_nudge || '').trim().toLowerCase();
-    return VALID.has(val) ? val : 'every';
+    return VALID.has(val) ? val : 'once-per-intent';
   } catch {
-    return 'every';
+    return 'once-per-intent';
   }
 }
 
@@ -791,6 +794,20 @@ function isStateStaleFallbackTrue(cwd) {
   }
 }
 
+/**
+ * Word-boundary keyword match — #953: plain `lower.includes(kw)` matched
+ * generic keywords like "bug" and "crash" inside unrelated words ("debugger",
+ * "crashing"), over-firing the debug nudge. Boundaries are checked against
+ * Unicode letters/numbers (not just ASCII \w) so Arabic/Urdu keyword phrases
+ * still match correctly.
+ */
+function keywordMatches(lower, kw) {
+  const kwLower = kw.toLowerCase();
+  const escaped = kwLower.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, 'u');
+  return re.test(lower);
+}
+
 /**
  * prompt-router: Nudge toward rcode commands for memory consistency (#892).
  * Reads stdin synchronously (NOT async — rejects bad JSON). Keyword-matches INTENT_TABLE,
@@ -868,12 +885,12 @@ function promptRouter() {
       process.exit(0);
     }
 
-    // ── Keyword match (first-match-wins, case-insensitive) ───────────────
+    // ── Keyword match (first-match-wins, case-insensitive, word-boundary) ─
     const lower = prompt.toLowerCase();
     let matched = null;
     for (const entry of INTENT_TABLE) {
       for (const kw of entry.keywords) {
-        if (lower.includes(kw.toLowerCase())) {
+        if (keywordMatches(lower, kw)) {
           matched = entry;
           break;
         }

package/rcode/bin/rcode-tools.cjs

@@ -4547,9 +4547,11 @@ function cmdGenerateClaudeMd(rawArgs) {
   const force = args.includes('--force');
   const claudeMdPath = path.join(PROJECT_ROOT, 'CLAUDE.md');
   const agentsMdPath = path.join(PROJECT_ROOT, 'AGENTS.md');
+  const claudeExisted = fs.existsSync(claudeMdPath);
+  const agentsExisted = fs.existsSync(agentsMdPath);
 
-  if (fs.existsSync(claudeMdPath) && !force) {
-    throw new Error(`CLAUDE.md already exists at ${claudeMdPath}. Use --force to overwrite.`);
+  if (claudeExisted && agentsExisted && !force) {
+    throw new Error(`CLAUDE.md and AGENTS.md already exist at ${PROJECT_ROOT}. Use --force to overwrite.`);
   }
 
   // Resolve project name from package.json or directory.
@@ -4647,26 +4649,33 @@ Before handling planning, exploration, auditing, refactoring, or multi-step buil
 **This file is part of the project. Treat it as load-bearing.**
 `;
 
-  const claudeExisted = fs.existsSync(claudeMdPath);
-  fs.writeFileSync(claudeMdPath, content);
+  // Each file's own existence gates only its own write — a project with an
+  // existing CLAUDE.md must still get a missing AGENTS.md backfilled, and
+  // vice versa (#1025).
+  const wroteClaude = !claudeExisted || force;
+  if (wroteClaude) {
+    fs.writeFileSync(claudeMdPath, content);
+  }
 
   // Mirror the same rules to AGENTS.md (the cross-tool standard Codex, Cursor,
   // Windsurf, Antigravity, and Gemini read). Skip when it already exists without
   // --force so an install-appended "## rcode Agents (installed)" roster survives.
-  const agentsExisted = fs.existsSync(agentsMdPath);
   const wroteAgents = !agentsExisted || force;
   if (wroteAgents) {
     fs.writeFileSync(agentsMdPath, content);
   }
 
+  const writtenPaths = [];
+  if (wroteClaude) writtenPaths.push(path.relative(PROJECT_ROOT, claudeMdPath));
+  if (wroteAgents) writtenPaths.push(path.relative(PROJECT_ROOT, agentsMdPath));
+
   return {
     ok: true,
     path: path.relative(PROJECT_ROOT, claudeMdPath),
-    paths: wroteAgents
-      ? [path.relative(PROJECT_ROOT, claudeMdPath), path.relative(PROJECT_ROOT, agentsMdPath)]
-      : [path.relative(PROJECT_ROOT, claudeMdPath)],
+    paths: writtenPaths,
     project_name: projectName,
-    overwritten: force && claudeExisted,
+    overwritten: force && (claudeExisted || agentsExisted),
+    claude_md_skipped: !wroteClaude,
     agents_md_skipped: !wroteAgents,
   };
 }
@@ -5283,18 +5292,55 @@ function cmdPhasePlanIndex(rawArgs) {
     const stem = file.replace(/-SPRINT\.md$/i, '');
     const text = fs.readFileSync(path.join(phaseDir, file), 'utf8');
     const { frontmatter, body } = parseFrontmatter(text);
+    let block = '';
+    if (text.startsWith('---\n')) {
+      const end = text.indexOf('\n---\n', 4);
+      if (end !== -1) block = text.slice(4, end);
+    }
     const id = frontmatter.sprint || frontmatter.plan || stem;
-    const wave = parseInt(frontmatter.wave || '1', 10) || 1;
-    const autonomous = String(frontmatter.autonomous || '').toLowerCase() === 'true';
+    // `wave:` may be an explicit scalar key, or absent — in which case it's
+    // derived from `depends_on` below (block-list or inline form, issue #951).
+    const hasExplicitWave = /^wave\s*:\s*\d+/m.test(block);
+    const wave = hasExplicitWave ? (parseInt(frontmatter.wave, 10) || 1) : null;
+    const dependsOn = fmListField(block, 'depends_on');
+    const hasAutonomousKey = /^autonomous\s*:/m.test(block);
+    const autonomous = hasAutonomousKey
+      ? String(frontmatter.autonomous || '').toLowerCase() === 'true'
+      : /<automated>/i.test(body);
     const gapClosure = String(frontmatter.gap_closure || frontmatter.type || '').toLowerCase() === 'gap_closure';
     const objMatch = body.match(/^##\s+(?:Objective|Goal)\s*\n+([^\n]+)/mi);
     const objective = objMatch ? objMatch[1].trim() : (frontmatter.goal || '').replace(/^["']|["']$/g, '');
-    const taskCount = (body.match(/^[-*]\s+\[[ xX]\]/gm) || []).length;
-    const filesModified = (body.match(/^\s*-\s*path:\s*["']?([^"'\n]+)/gm) || []).length;
+    const checkboxCount = (body.match(/^[-*]\s+\[[ xX]\]/gm) || []).length;
+    const storyHeaderCount = (body.match(/^###\s+Story\s+\S+/gm) || []).length;
+    const taskCount = checkboxCount > 0 ? checkboxCount : storyHeaderCount;
+    const filesModifiedList = fmListField(block, 'files_modified');
+    const filesModified = filesModifiedList.length > 0
+      ? filesModifiedList.length
+      : (body.match(/^\s*-\s*path:\s*["']?([^"'\n]+)/gm) || []).length;
     const hasSummary = summarySet.has(stem);
     if (/checkpoint/i.test(body)) hasCheckpoints = true;
-    return { id, wave, autonomous, gap_closure: gapClosure, objective, task_count: taskCount, files_modified: filesModified, has_summary: hasSummary, file: path.relative(PROJECT_ROOT, path.join(phaseDir, file)) };
+    return { id, wave, dependsOn, autonomous, gap_closure: gapClosure, objective, task_count: taskCount, files_modified: filesModified, has_summary: hasSummary, file: path.relative(PROJECT_ROOT, path.join(phaseDir, file)) };
   });
+
+  // Resolve waves left undetermined (no explicit `wave:` key) from depends_on:
+  // wave(p) = 1 + max(wave of each same-phase dependency), or 1 if none.
+  const idToPlan = new Map(plans.map((p) => [p.id, p]));
+  function resolveWave(p, seen) {
+    if (p.wave !== null) return p.wave;
+    if (seen.has(p.id)) { p.wave = 1; return 1; }
+    seen.add(p.id);
+    let maxDepWave = 0;
+    for (const depId of p.dependsOn) {
+      const dep = idToPlan.get(depId);
+      if (!dep) continue;
+      maxDepWave = Math.max(maxDepWave, resolveWave(dep, seen));
+    }
+    p.wave = maxDepWave > 0 ? maxDepWave + 1 : 1;
+    return p.wave;
+  }
+  for (const p of plans) resolveWave(p, new Set());
+  for (const p of plans) delete p.dependsOn;
+
   const waves = {};
   for (const p of plans) {
     const k = String(p.wave);
@@ -5402,6 +5448,109 @@ function cmdPlanCheckWaveOverlaps(rawArgs) {
   return { phase: phaseArg, phase_dir: path.relative(PROJECT_ROOT, phaseDir), plans_checked: plans.length, conflicts };
 }
 
+/**
+ * Deterministic frontend/backend glob check for classify-plan (issue #1021).
+ * Mirrors the FRONTEND_GLOBS / BACKEND_GLOBS rules formerly hand-applied by
+ * the orchestrating LLM in execute-waves.md — kept here as the single source
+ * of truth so both the CLI and the workflow doc describe the same behavior.
+ */
+function matchesFrontendGlob(file) {
+  const f = String(file || '').toLowerCase();
+  if (/\.(tsx|jsx|css)$/.test(f)) return true;
+  return f.includes('client') || f.includes('ui');
+}
+function matchesBackendGlob(file) {
+  const f = String(file || '').toLowerCase();
+  return f.includes('api') || f.includes('server') || f.includes('db') || f.includes('service');
+}
+
+const CLASSIFY_PLAN_ROUTE = { frontend: 'rcode-haitham', backend: 'rcode-yousef', 'full-stack': 'rcode-hanzla', other: 'rcode-executor' };
+
+function classifyPlanFiles(files, objective) {
+  const touchesFrontend = files.some(matchesFrontendGlob);
+  const touchesBackend = files.some(matchesBackendGlob);
+  let classification;
+  if (touchesFrontend && touchesBackend) classification = 'full-stack';
+  else if (touchesFrontend) classification = 'frontend';
+  else if (touchesBackend) classification = 'backend';
+  else classification = 'other';
+
+  if (classification === 'other') {
+    const obj = String(objective || '').toLowerCase();
+    const frontendKeywords = ['react', 'component', 'ui', 'css', 'tailwind', 'frontend', 'client-side', 'accessibility', 'a11y'];
+    const backendKeywords = ['api', 'endpoint', 'database', 'schema', 'service', 'queue', 'backend', 'server-side'];
+    if (frontendKeywords.some((k) => obj.includes(k))) classification = 'frontend';
+    else if (backendKeywords.some((k) => obj.includes(k))) classification = 'backend';
+  }
+  return classification;
+}
+
+/**
+ * classify-plan — deterministic replacement for execute-waves.md's
+ * hand-computed FRONTEND_GLOBS/BACKEND_GLOBS classification (issue #1021).
+ * A live execution run showed the orchestrating LLM never actually carried
+ * out the prose pseudocode, so a plan with a "db"-containing path still fell
+ * back to rcode-executor instead of rcode-yousef.
+ *
+ * Two call shapes:
+ *   classify-plan <phase> <plan-id>              — reads files_modified/objective from the plan's SPRINT.md
+ *   classify-plan --files=a,b,c --objective="..."  — classify an already-parsed list directly
+ */
+function cmdClassifyPlan(args) {
+  const flags = {};
+  const positional = [];
+  for (const t of args) {
+    if (t.startsWith('--files=')) flags.files = t.slice('--files='.length);
+    else if (t.startsWith('--objective=')) flags.objective = t.slice('--objective='.length);
+    else positional.push(t);
+  }
+
+  let files = [];
+  let objective = '';
+
+  if (flags.files !== undefined || flags.objective !== undefined) {
+    files = flags.files ? flags.files.split(',').map((s) => s.trim()).filter(Boolean) : [];
+    objective = flags.objective || '';
+  } else {
+    const [phaseArg, planArg] = positional;
+    if (!phaseArg || !planArg) {
+      throw new Error('Usage: classify-plan <phase> <plan-id>  OR  classify-plan --files=a,b,c --objective="text"');
+    }
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const norm = phaseArg.replace(/^0+/, '') || '0';
+    let phaseDir = null;
+    if (fs.existsSync(phasesDir)) {
+      for (const d of fs.readdirSync(phasesDir)) {
+        const m = d.match(/^(\d+)(?:[-.])/);
+        if (m && (m[1].replace(/^0+/, '') || '0') === norm) { phaseDir = path.join(phasesDir, d); break; }
+      }
+    }
+    if (!phaseDir) throw new Error(`Phase not found: ${phaseArg}`);
+    let planFile = null;
+    for (const file of fs.readdirSync(phaseDir).filter((f) => /-SPRINT\.md$/i.test(f)).sort()) {
+      const stem = file.replace(/-SPRINT\.md$/i, '');
+      if (stem === planArg || stem.endsWith(`-${planArg}`)) { planFile = file; break; }
+      const text = fs.readFileSync(path.join(phaseDir, file), 'utf8');
+      const { frontmatter } = parseFrontmatter(text);
+      if ((frontmatter.sprint || frontmatter.plan) === planArg) { planFile = file; break; }
+    }
+    if (!planFile) throw new Error(`Plan not found: ${planArg} in phase ${phaseArg}`);
+    const text = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+    const { frontmatter, body } = parseFrontmatter(text);
+    let block = '';
+    if (text.startsWith('---\n')) {
+      const end = text.indexOf('\n---\n', 4);
+      if (end !== -1) block = text.slice(4, end);
+    }
+    files = fmListField(block, 'files_modified');
+    const objMatch = body.match(/^##\s+(?:Objective|Goal)\s*\n+([^\n]+)/mi);
+    objective = objMatch ? objMatch[1].trim() : (frontmatter.goal || '').replace(/^["']|["']$/g, '');
+  }
+
+  const classification = classifyPlanFiles(files, objective);
+  return { classification, subagent_type: CLASSIFY_PLAN_ROUTE[classification], files_checked: files.length };
+}
+
 /** phases list — directory inventory under .planning/phases with optional --type filter and --pick path. */
 function cmdPhasesList(args) {
   const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
@@ -6658,6 +6807,9 @@ async function main() {
       case 'phase-plan-index':
         result = cmdPhasePlanIndex(args.join(' '));
         break;
+      case 'classify-plan':
+        result = cmdClassifyPlan(args);
+        break;
       case 'phases':
         if (args[0] === 'list') { result = cmdPhasesList(args.slice(1)); if (result === undefined) return; }
         else { console.error('Unknown phases subcommand. Valid: list'); process.exit(1); }

package/rcode/data/intent-table.json

@@ -11,7 +11,7 @@
   },
   {
     "intent": "debug",
-    "keywords": ["bug", "getting an error", "throwing an error", "error in the", "fix the error", "debug this", "crash", "failure", "broken", "not working", "fails", "exception", "traceback", "kharab", "masla", "ye kaam nahi kar raha", "yeh kaam nahi kar raha", "error a raha hai", "theek karo", "khud se crash", "خطأ", "مشكلة", "لا يعمل", "أصلح الخطأ", "تعطل البرنامج"],
+    "keywords": ["getting an error", "throwing an error", "error in the", "fix the error", "debug this", "crash", "not working", "exception", "traceback", "kharab", "masla", "ye kaam nahi kar raha", "yeh kaam nahi kar raha", "error a raha hai", "theek karo", "khud se crash", "خطأ", "مشكلة", "لا يعمل", "أصلح الخطأ", "تعطل البرنامج"],
     "command": "/rcode-debug"
   },
   {

package/rcode/references/git-preflight.md

@@ -14,8 +14,11 @@ Run these read-only commands in order. Any failure halts the workflow with the f
 # Check 1: working tree clean
 DIRTY=$(git status --porcelain 2>/dev/null)
 
-# Check 2: not on a protected branch
+# Check 2: not on a protected branch (skipped entirely when `git.branching_strategy`
+# config is `none` — committing directly to main/master is the deliberately configured
+# workflow in that case)
 BRANCH=$(git branch --show-current 2>/dev/null)
+BRANCHING_STRATEGY=$(node .rcode/bin/rcode-tools.cjs config-get git.branching_strategy 2>/dev/null)
 PROTECTED="main master develop v2-prototype"
 
 # Check 3: branch follows naming convention
@@ -35,7 +38,7 @@ fi
 The workflow MUST stop and print the banner below if ANY of:
 
 - `DIRTY` is non-empty AND user did not pass `--allow-dirty`
-- `BRANCH` is in `$PROTECTED` AND user did not pass `--on-main`
+- `BRANCH` is in `$PROTECTED` AND `BRANCHING_STRATEGY` is not `none` AND user did not pass `--on-main`
 - `BRANCH_OK` is `no` AND user did not pass `--allow-dirty` (branch-name lint is advisory if working tree is dirty AND user accepted the dirty override)
 - `OUT_OF_SCOPE` is non-empty AND user did not pass `--allow-scope-drift`
 

package/rcode/references/output-format.md

@@ -42,7 +42,7 @@ Use for major workflow transitions.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► {STAGE NAME}
+ rcode ► {STAGE NAME}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -69,7 +69,7 @@ Use this when a router command dispatches to another command:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► ROUTING
+ rcode ► ROUTING
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Input: {user's question or intent}
@@ -328,7 +328,7 @@ Use standard markdown pipe tables with status symbols:
 **Majlis banner** (multi-agent council):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► MAJLIS CONVENING
+ rcode ► MAJLIS CONVENING
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -354,7 +354,7 @@ the banner, not inside it.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► PLANNING SPRINT 01.1
+ rcode ► PLANNING SPRINT 01.1
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 التخطيط للسباق 01.1 — يرجى الانتظار
 ```
@@ -389,7 +389,7 @@ translated prose goes outside the art, on its own line(s).
 
 - Varying box/banner widths within same output
 - Mixing banner styles (`===`, `---`, `***`)
-- Skipping `RCODE ►` prefix in stage banners
+- Skipping `rcode ►` prefix in stage banners
 - Random emoji (`🚀`, `✨`, `💫`) outside the approved set
 - Missing Next Up block after workflow completions
 - Hardcoding references to other methodologies in rcode's UX

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/do.md

@@ -387,6 +387,38 @@ Scope: {one-line scope summary}
 Routing to: {chosen command}
 Reason: {one-line why}
 ```
+
+**herdr hint (cached read only — no live check from here).** When the chosen command is
+`/rcode-execute` or `/rcode-add-phase` (routes that fan out substantial multi-file
+execution work), read the cached availability flag left by `/rcode-execute`'s own
+availability check:
+
+```bash
+HERDR_AVAILABLE=$(node .rcode/bin/rcode-tools.cjs config-get workflow._herdr_available 2>/dev/null || echo "false")
+HERDR_AVAILABLE=${HERDR_AVAILABLE:-false}
+```
+
+This is a plain `config-get` read — the same sanctioned category as `config-get mode`
+used elsewhere in this workflow (see `<guardrails>`). It reuses the exact cache
+`/rcode-execute` writes to (`workflow._herdr_checked` / `workflow._herdr_available`) —
+do NOT duplicate the `command -v herdr` probe or call `config-set` here. `/rcode-do`
+has no sanctioned way to run that shell probe or persist a value itself, so if the
+cache hasn't been populated yet (`_herdr_checked` still false), say nothing — the
+first `/rcode-execute` run downstream will perform and cache the check itself.
+
+If `HERDR_AVAILABLE == "true"`, append one extra line to the banner above:
+
+```
+Note: herdr is available on this machine — {chosen command} will offer a
+      multi-agent orchestration option if the work fans out into independent
+      plans; you'll be asked to confirm before anything runs via herdr.
+```
+
+Do NOT turn this into an `AskUserQuestion` prompt and do NOT ask the user to
+decide here — `/rcode-do` only routes, it never presents execution-mode choices.
+The actual offer (with the full tradeoff explanation and required confirmation)
+is `/rcode-execute`'s `three_options` step, which fires after dispatch regardless
+of whether this hint line was shown.
 </step>
 
 <step name="dispatch">
@@ -426,7 +458,7 @@ If the chosen command expects a phase number and one wasn't provided in the text
 <guardrails>
 **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:
+The steps above (`parse_args`, `check_project`, `auto_init_check`, `greenfield_guard`, `explicit_intent_check`, `persona_shortcut`, `display`) legitimately call Bash for structured state/config lookups (`rcode-tools.cjs state load`, `progress init`, `config-get mode`, `config-get workflow._herdr_available`, `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. `config-get workflow._herdr_available` is a read of a cache another workflow (`/rcode-execute`) already populated — `/rcode-do` MUST NOT run `command -v herdr` itself or call `config-set` to populate that cache; it only reads whatever is already there. 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 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.