@hanzlaa/rcode 4.9.0 → 4.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "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/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);

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

package/rcode/workflows/execute.md

@@ -98,7 +98,41 @@ CONFIG_MODE=$(node .rcode/bin/rcode-tools.cjs config-get mode 2>/dev/null || ech
 
 **If `CONFIG_MODE == "yolo"` or `$ARGUMENTS` contains `--auto`:** Skip the menu. Auto-select **A) Autonomous run** and print one line: `▶ Auto-selecting Autonomous run (yolo mode). /rcode-settings set mode guided to change.`
 
-Otherwise, offer three modes via AskUserQuestion. Each option names the tradeoff explicitly:
+**herdr availability check (cached).** Before offering options, determine whether a 4th
+option (**D) herdr multi-agent orchestration**) should be shown. This uses the same
+cached-boolean idiom as `workflow._auto_chain_active` above — read with a safe default,
+write back once resolved, and skip the live check on subsequent runs:
+
+```bash
+HERDR_NAMED_EXPLICITLY=$([[ "$ARGUMENTS" =~ herdr ]] && echo true || echo false)
+
+HERDR_CHECKED=$(node .rcode/bin/rcode-tools.cjs config-get workflow._herdr_checked 2>/dev/null || echo "false")
+HERDR_CHECKED=${HERDR_CHECKED:-false}  # config-get exits 0 with empty output when key absent
+
+if [[ "$HERDR_CHECKED" != "true" || "$HERDR_NAMED_EXPLICITLY" == "true" ]]; then
+  # Live re-check: first time ever, OR user named herdr explicitly this run
+  # (herdr may have been installed since the last negative cache hit).
+  if command -v herdr >/dev/null 2>&1; then
+    HERDR_AVAILABLE=true
+  else
+    HERDR_AVAILABLE=false
+  fi
+  node .rcode/bin/rcode-tools.cjs config-set workflow._herdr_available "$HERDR_AVAILABLE" 2>/dev/null
+  node .rcode/bin/rcode-tools.cjs config-set workflow._herdr_checked true 2>/dev/null
+else
+  # Cached negative (or positive) result from a prior run — skip the check entirely.
+  HERDR_AVAILABLE=$(node .rcode/bin/rcode-tools.cjs config-get workflow._herdr_available 2>/dev/null || echo "false")
+  HERDR_AVAILABLE=${HERDR_AVAILABLE:-false}
+fi
+```
+
+Do **not** re-run `command -v herdr` on every invocation once `_herdr_checked` is `true` —
+that defeats the point of caching. The only exception is `HERDR_NAMED_EXPLICITLY`: if the
+user's request names herdr by name (e.g. "use herdr for this", "orchestrate via herdr"),
+always re-check live regardless of the cached value, since herdr may have been installed
+since the negative result was cached.
+
+Otherwise, offer modes via AskUserQuestion. Each option names the tradeoff explicitly:
 
 **A) Autonomous run** — Spawn subagent per plan in sequence/parallel per
     wave rules. Checkpoints still pause for user. Fastest wall-clock.
@@ -112,9 +146,31 @@ Otherwise, offer three modes via AskUserQuestion. Each option names the tradeoff
     later waves in a separate session. Good for staged rollout / review
     gates.
 
+**D) herdr multi-agent orchestration** (only shown if `HERDR_AVAILABLE == "true"`) —
+    Fan this phase's plans out to parallel `herdr` panes/tabs, each running its own
+    Claude agent in an isolated git worktree, then merge their work back. Be specific
+    about the tradeoff, not a one-liner: separate terminal panes you can watch
+    independently, genuinely parallel wall-clock (not wave-sequenced), noticeably
+    higher token cost than A/B/C since each pane runs a full agent session, and a
+    merge step at the end. Best fit is plans that are truly independent (no shared
+    `files_modified`, no cross-plan sequencing) — for plans with overlaps or a single
+    linear wave, herdr adds coordination overhead for no benefit; prefer A or C instead.
+    Selecting this option invokes the `rcode-herdr-orchestration` skill — it does not
+    replace this workflow's execution, it's a different way to run the same plans.
+
+    **Never auto-select D, even in yolo/`--auto` mode.** Orchestrating via herdr requires
+    explicit user confirmation on this turn — if `CONFIG_MODE == "yolo"` skipped the menu
+    above, herdr is simply not offered this run; the autonomous-run auto-selection must
+    never silently switch into herdr mode.
+
 Include a recommendation line: "My recommendation: {letter} because {reason
 in one clause}." Then ask which option to proceed with — do NOT silently
-pick one.
+pick one. If the user selects D, confirm once more in plain language what
+will happen (parallel panes, worktrees, higher cost) before invoking
+`Skill(skill="rcode-herdr-orchestration", ...)` — do not invoke it on the same
+turn as the AskUserQuestion answer without that confirmation being part of
+the answer itself (i.e. selecting the option IS the confirmation only if its
+label made the tradeoff explicit, which it does above).
 </three_options>
 
 <output_format>

package/rcode/workflows/init.md

@@ -42,6 +42,12 @@ Run detection in parallel:
 test -f .rcode/config.yaml && echo "rcode-configured: yes" || echo "rcode-configured: no"
 test -f .rcode/state.json && echo "state-present: yes" || echo "state-present: no"
 test -f .rcode/JOURNEY.md && echo "rihla-present: yes" || echo "rihla-present: no"
+# #1028: config.yaml is written by the installer itself, so it exists on the
+# very first /rcode-init run after a fresh install — not just on a genuine
+# "returning" session. state.json's installer-seeded _seeded_stub marker
+# (cleared once a real init/new-project run completes) is what actually
+# distinguishes "normal first brownfield run" from "prior init was interrupted".
+grep -q '"_seeded_stub"[[:space:]]*:[[:space:]]*true' .rcode/state.json 2>/dev/null && echo "seeded-stub: yes" || echo "seeded-stub: no"
 
 # Project presence
 # Use git rev-parse instead of test -d .git — in git worktrees .git is a FILE not a dir
@@ -83,12 +89,20 @@ If `state === "returning"` and `--reset` not passed:
   Or run with --reset to reconfigure.
   ```
 
-- If `rihla-present: no` — JOURNEY.md is missing from a partial prior init. Do NOT stop. Print a recovery notice and continue to Steps 4 and 4b to write the missing baseline:
+- If `rihla-present: no` and `seeded-stub: yes` — this is the normal, expected first `/rcode-init` run on a brownfield project: `config.yaml` was seeded by the installer, but no real init has happened yet. Nothing was broken; do NOT use "recovery" language. Print a plain first-run notice and continue to Steps 4 and 4b to write the baseline:
+
+  ```
+  ✓ rcode is configured. Writing the JOURNEY.md baseline now...
+  ```
+
+  Skip Steps 2 and 3 (config already exists). Jump directly to Step 4.
+
+- If `rihla-present: no` and `seeded-stub: no` — a genuine prior init/new-project run completed (the stub marker was cleared) but JOURNEY.md is missing, meaning that prior run was interrupted before writing it. This is an actual recovery case. Print a recovery notice and continue to Steps 4 and 4b to write the missing baseline:
 
   ```
   ✓ rcode is already configured here.
 
-  JOURNEY.md baseline is missing — completing the scan step now...
+  JOURNEY.md baseline is missing from a prior interrupted init — completing it now...
   ```
 
   Skip Steps 2 and 3 (config already exists). Jump directly to Step 4.
@@ -290,12 +304,12 @@ test -f .rcode/sources.yaml && node .rcode/bin/rcode-tools.cjs context refresh >
 `generate-claude-md` (the command routing rule + project rules block every agent needs at session start) previously only ran via the `/rcode-new-project` roadmap flow — a project set up with `/rcode-init` alone (the common "add rcode to an existing codebase" path) never got it, so agents had no ambient instruction to check `do.md` before acting ad-hoc. Close that gap here, unconditionally (not just on `fresh`):
 
 ```bash
-if [ ! -f CLAUDE.md ]; then
+if [ ! -f CLAUDE.md ] || [ ! -f AGENTS.md ]; then
   node .rcode/bin/rcode-tools.cjs generate-claude-md
 fi
 ```
 
-Never pass `--force` here — an existing `CLAUDE.md` is the user's own file (or was already generated by a prior init/new-project run) and must not be overwritten. Silent no-op when `CLAUDE.md` already exists.
+Never pass `--force` here — an existing `CLAUDE.md` or `AGENTS.md` is the user's own file (or was already generated by a prior init/new-project run) and must not be overwritten. `cmdGenerateClaudeMd` gates each file's write on that file's own existence, so this backfills whichever one is missing (#1025). Silent no-op when both files already exist.
 
 ## Step 5 — Suggest the next step
 

package/rcode/workflows/scan.md

@@ -14,10 +14,12 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 ## Step 0 — Usage check
 
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+If `$ARGUMENTS` contains `--help` or `-h`:
 - Print the usage block below
 - STOP — do not proceed
 
+If `$ARGUMENTS` is empty, do NOT stop — proceed to Step 1, which defaults focus to `tech+arch`.
+
 **Usage:**
 ```
 /rcode-scan [--focus tech|arch|quality|concerns|tech+arch] [--refresh] [--reset]
@@ -339,6 +341,25 @@ This file tracks structural changes between scans. Each entry is auto-written by
 
 This file is **read by future `/rcode-scan --refresh` runs** as additional anchor context — the memory bank is self-improving across scans.
 
+## Step 6.6: Propagate scan findings into PROJECT.md / STATE.md stubs
+
+After the RETURNED banner, check whether `.planning/PROJECT.md` and `.planning/STATE.md` are still install stubs (contain the `<!-- INSTALL STUB` banner). If real, non-stub content already exists, skip this step entirely — never overwrite user-authored planning docs.
+
+```bash
+grep -q '<!-- INSTALL STUB' .planning/PROJECT.md 2>/dev/null && echo "PROJECT_IS_STUB"
+grep -q '<!-- INSTALL STUB' .planning/STATE.md 2>/dev/null && echo "STATE_IS_STUB"
+```
+
+If `PROJECT.md` is a stub: replace its `**One-line:**` sentence with a brief, grounded one-line summary derived from the scan output just written (e.g. from STACK.md/ARCHITECTURE.md's opening lines — language, framework, primary purpose). Keep the rest of the stub structure (Vision/Stack sections) intact; do not attempt a full rewrite. Use Read then Edit — never blind-overwrite.
+
+If `STATE.md` is a stub: update `**Current phase:**` line to read:
+```
+**Current phase:** none — existing project scanned, see .planning/codebase/ — no phases planned yet
+```
+and add one line under `## Next Action` noting the scan already ran: `Codebase scanned via /rcode-scan — run /rcode-new-project or /rcode-add-phase to plan phases.`
+
+This is a minimal, targeted edit — not a full PROJECT.md content-generation system. The goal is closing the "user opens STATE.md and sees zero acknowledgment a scan already ran" gap.
+
 ## Step 7: Final cue (orchestrator-level, after RETURNED banner)
 
 The RETURNED banner above is Dalil's voice. After it, the orchestrator may add ONE neutral cue line if the user might want a deeper scan:

package/server/lib/html/client/components/Sidebar.js

@@ -63,11 +63,14 @@ export function Sidebar({ activeView, projectName }) {
   const name = project.name || projectName || 'No project';
   const user = (project.user && project.user.name) ? project.user : null;
 
-  // Full store subscription for live health badge counts.
+  // Full store subscription for live health badge counts. Derived from
+  // activeSessions (the /api/sessions poll) — same source of truth as the
+  // OrchPanel footer and NotifyCenter — not the static store.blockers list
+  // (PROJECT.md-backed, unrelated to live orchestrator state; see #965).
   // Re-renders on every setState (sessions poll every 4 s, state refresh every 30 s).
-  const { activeSessions, blockers } = useStore();
-  const sessionCount = (activeSessions || []).filter(s => s.status === 'running').length;
-  const blockerCount = (blockers || []).length;
+  const { activeSessions } = useStore();
+  const sessionCount = (activeSessions || []).filter(s => s.status === 'running' && !s.waiting).length;
+  const blockerCount = (activeSessions || []).filter(s => s.status === 'blocked' || s.waiting).length;
 
   return html`
     <aside class="sidebar" id="sidebar">
@@ -93,7 +96,7 @@ export function Sidebar({ activeView, projectName }) {
         </span>
         <span
           class=${'health-badge' + (blockerCount > 0 ? ' health-badge--alert' : ' health-badge--zero')}
-          title=${blockerCount + ' blocker' + (blockerCount === 1 ? '' : 's')}
+          title=${blockerCount + ' blocked orchestration session' + (blockerCount === 1 ? '' : 's')}
         >
           <${Icon} name="alert-triangle" size=${12} />
           ${blockerCount} blocked

package/server/lib/html/client/components/shared.js

@@ -332,18 +332,37 @@ export function TaskCard({ task: t }) {
   const done = t.status === 'done' || t.status === 'completed';
   const running = isSessionRunning(t.id);
 
-  // Build cmd hints for this task
+  // Build cmd hints for this task. rcode has two separate tracking pipelines
+  // that both use "sprint" terminology: phase -> SPRINT.md plan -> task
+  // (t.phaseId set; this is the real, execution-backed pipeline) vs.
+  // epic -> story (no t.phaseId; dev-story/create-story/verify-work). Using
+  // dev-story/create-story commands against a phase-pipeline task id (e.g.
+  // "1.1.2") doesn't parse — those commands only accept 2-part epic.story
+  // ids. Branch on t.phaseId so the hints (and the RunBtn below) actually
+  // resolve to a real command for whichever pipeline this task is from.
+  const isPhaseTask = !!t.phaseId;
+  const runCmd = isPhaseTask ? '/rcode-execute ' + t.phaseId : '/rcode-dev-story ' + t.id;
   const taskCmds = [];
   if (t.id) {
-    if (!done) {
-      taskCmds.push(['/rcode-dev-story ' + t.id, 'Implement this story']);
-      taskCmds.push(['/rcode-create-story ' + (t.sprintId || ''), 'Add related story']);
+    if (isPhaseTask) {
+      if (!done) {
+        taskCmds.push(['/rcode-execute ' + t.phaseId, 'Execute phase ' + t.phaseId]);
+      } else {
+        taskCmds.push(['/rcode-verify-phase ' + t.phaseId, 'Verify phase ' + t.phaseId]);
+        taskCmds.push(['/rcode-review --phase ' + t.phaseId + ' --all', 'Review code for this phase']);
+      }
+      taskCmds.push(['/rcode-progress', 'Overall project status']);
     } else {
-      taskCmds.push(['/rcode-verify-work ' + t.id, 'Verify this story']);
-      taskCmds.push(['/rcode-review ' + t.id, 'Review code for this story']);
-    }
-    if (t.sprintId) {
-      taskCmds.push(['/rcode-sprint-status ' + t.sprintId, 'Sprint ' + t.sprintId + ' status']);
+      if (!done) {
+        taskCmds.push(['/rcode-dev-story ' + t.id, 'Implement this story']);
+        taskCmds.push(['/rcode-create-story ' + (t.sprintId || ''), 'Add related story']);
+      } else {
+        taskCmds.push(['/rcode-verify-work ' + t.id, 'Verify this story']);
+        taskCmds.push(['/rcode-review ' + t.id, 'Review code for this story']);
+      }
+      if (t.sprintId) {
+        taskCmds.push(['/rcode-sprint-status ' + t.sprintId, 'Sprint ' + t.sprintId + ' status']);
+      }
     }
   }
 
@@ -357,7 +376,7 @@ export function TaskCard({ task: t }) {
       aria-expanded=${expanded}
       ...${pressable(() => setExpanded(e => !e))}>
       <div class="item-title" style=${done ? 'text-decoration:line-through' : ''}>
-        ${t.id && !done ? html`<${RunBtn} storyId=${t.id} cmd=${'/rcode-dev-story ' + t.id} label=${'Story ' + t.id}/>` : null}
+        ${t.id && !done ? html`<${RunBtn} storyId=${t.id} cmd=${runCmd} label=${isPhaseTask ? 'Phase ' + t.phaseId : 'Story ' + t.id}/>` : null}
         ${t.file ? html`
           <button class="card-file-btn" title=${'View ' + t.file} onClick=${handleViewFile}>
             <${Icon} name="file-text" size=${11}/> File

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

@@ -91,7 +91,7 @@ function PhaseDetail({ phase: p, S }) {
         <div class="attr-grid">
           <${AttrItem} label="Status" value=${html`<${Chip} status=${p.status}/>`}/>
           <${AttrItem} label="Sprints" value=${sps.length}/>
-          <${AttrItem} label="Tasks Done" value=${done + '/' + stories.length}/>
+          <${AttrItem} label="Tasks Done" value=${stories.length ? (done + '/' + stories.length) : 'no tasks tracked'}/>
           <${AttrItem} label="Progress" value=${pct(done, stories.length)}/>
           ${p.completed_at ? html`<${AttrItem} label="Completed" value=${humanDate(p.completed_at)}/>` : null}
         </div>

package/server/lib/html/css.js

@@ -2651,6 +2651,8 @@ footer {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+  min-width: 0;
+  flex-shrink: 1;
 }
 .orch-term-dock-live {
   display: inline-flex;
@@ -2661,6 +2663,7 @@ footer {
   color: var(--green);
   font-family: var(--font-mono);
   white-space: nowrap;
+  flex-shrink: 0;
 }
 .orch-term-dock-live-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--green); }
 .orch-term-dock-stop {
@@ -2675,6 +2678,7 @@ footer {
   cursor: pointer;
   font-family: var(--font-sans);
   margin-left: var(--space-2);
+  flex-shrink: 0;
 }
 .orch-term-dock-stop:hover { opacity: 0.85; }
 .orch-term-dock-body {

package/server/lib/scanner.js

@@ -195,7 +195,7 @@ function buildPhaseTree(projectDir, rawPhases, listCached, overrides) {
       // Status: a *-SUMMARY.md sibling means the sprint shipped.
       const hasSummary = files.includes(f.replace(/-SPRINT\.md$/i, '-SUMMARY.md'));
       const status = hasSummary ? 'complete'
-        : (p.status === 'active' || p.status === 'in_progress') ? 'in_progress'
+        : toState(p.status) === 'active' ? 'in_progress'
         : 'planned';
 
       // Project-relative path to this sprint's SPRINT.md — same shape as the
@@ -269,6 +269,9 @@ function buildDashboard(state) {
              : (Array.isArray(raw.phases) ? raw.phases : []);
 
   // ---- phases (superset: rich phaseTree + contract range/state) ----
+  // Sorted numerically by phase number — state.json array order reflects
+  // insertion order (when a phase entry was appended), not phase sequence,
+  // so an inserted-late phase like 13 would otherwise render after 38/39/42/43.
   const phases = tree.map(p => {
     const started   = p.started || p.created || null;
     const completed = p.completed || p.completed_at || null;
@@ -276,7 +279,7 @@ function buildDashboard(state) {
       ? [fmtShort(started), fmtShort(completed)].filter(Boolean).join(' – ')
       : '';
     return { ...p, name: p.name || p.slug || String(p.id || ''), range, state: toState(p.status) };
-  });
+  }).sort((a, b) => (parseFloat(a.id ?? a.number) || 0) - (parseFloat(b.id ?? b.number) || 0));
 
   // ---- progress (prefer story counts; fall back to phase-level counts) ----
   let completed = 0, total = 0, inProg = 0;
@@ -380,7 +383,7 @@ function buildDashboard(state) {
             date: fmtISODate(p.completed || s.completed_at || p.created),
             file: s.file || null,
           });
-        } else if (p.state === 'active') {
+        } else if (toState(p.status) === 'active') {
           // No per-task progress tracking exists — pct stays null and the UI
           // omits the percent pill rather than inventing a number.
           inProgressTasks.push({ title: st.title || st.id, pct: null, file: s.file || null });
@@ -390,10 +393,10 @@ function buildDashboard(state) {
   }
   // Fallbacks so the cards are never empty when stories are unregistered in state.json.
   if (!completedTasks.length) {
-    phases.filter(p => p.state === 'done').slice(-6).forEach(p =>
+    phases.filter(p => toState(p.status) === 'done').slice(-6).forEach(p =>
       completedTasks.push({ title: p.name, date: fmtISODate(p.completed || p.created), file: null }));
   }
-  if (!inProgressTasks.length && activePhase && activePhase.state === 'active') {
+  if (!inProgressTasks.length && activePhase && toState(activePhase.status) === 'active') {
     inProgressTasks.push({ title: activePhase.name, pct: null, file: null });
   }
   const tasks = {