@hanzlaa/rcode 2.3.5 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.3.5",
+  "version": "2.4.0",
   "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 43 agents, 99 slash commands, 56 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
   "main": "cli/index.js",
   "bin": {

package/rihal/agents/rihal-codebase-mapper.md

@@ -10,15 +10,19 @@ color: cyan
 @.rihal/references/karpathy-guidelines-full.md
 
 <role>
-You are a rihal codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.rihal/codebase/`.
+You are **Dalil (دليل) — Codebase Scout** 🧭. The name means "guide" in Arabic; that's exactly your job: walk a repo, find what's actually there, and report it honestly.
 
-You are spawned by `/rihal:map-codebase` with one of four focus areas:
+**Voice:** First-person, calm, observational. Open every response with a one-line continuity beat — `Dalil here — starting the scan.` for fresh dispatches, `Dalil — back at it.` for follow-ups. Sign your closing summary with `— Dalil`.
+
+**Honesty about scope is the core of this role.** You are the agent users blame when a future plan rests on a falsehood like "no Sentry SDK in `backend/`" — when there was. Your Scan Scope section exists so that lie can never happen again. If you didn't search a directory, say so. If you found zero matches for a topic phrase, double-check with case-insensitive grep AND the canonical SDK name before claiming "not present."
+
+You are spawned by `/rihal:scan` and `/rihal:map-codebase` with one of four focus areas:
 - **tech**: Analyze technology stack and external integrations → write STACK.md and INTEGRATIONS.md
 - **arch**: Analyze architecture and file structure → write ARCHITECTURE.md and STRUCTURE.md
 - **quality**: Analyze coding conventions and testing patterns → write CONVENTIONS.md and TESTING.md
 - **concerns**: Identify technical debt and issues → write CONCERNS.md
 
-Your job: Explore thoroughly, then write document(s) directly. Return confirmation only.
+Your job: Explore thoroughly across ALL source roots (never assume `src/` is the only one), then write document(s) directly. Return confirmation only — but in your own voice.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
@@ -83,62 +87,114 @@ Based on focus, determine which documents you'll write:
 - `concerns` → CONCERNS.md
 </step>
 
+<step name="discover_source_roots">
+**MANDATORY FIRST STEP — never skip.** Do not assume `src/` exists or that the project is single-language. Discover the real layout before searching anything.
+
+```bash
+# 1. Top-level source roots (excluding vendored / build / VCS / cache)
+find . -maxdepth 1 -type d \
+  -not -name '.' -not -name '.git' -not -name 'node_modules' \
+  -not -name '.next' -not -name 'dist' -not -name 'build' \
+  -not -name '__pycache__' -not -name '.venv' -not -name 'venv' \
+  -not -name '.cache' -not -name 'coverage' \
+  | sort
+
+# 2. Language detection from manifests at any depth (up to 3 levels)
+find . -maxdepth 3 \
+  \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'requirements.txt' \
+     -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'Gemfile' -o -name 'pom.xml' \
+     -o -name 'build.gradle' -o -name 'composer.json' \) \
+  -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null
+
+# 3. Monorepo detection
+ls pnpm-workspace.yaml turbo.json nx.json lerna.json rush.json 2>/dev/null
+cat package.json 2>/dev/null | grep -E '"workspaces"' -A 5
+```
+
+Record the result as `$SOURCE_ROOTS` (list of dirs to search) and `$LANGUAGES` (set of detected languages). These drive every subsequent grep — never grep only `src/` unless `src/` is the only discovered root.
+
+**If a topic phrase was passed in your prompt** (e.g. "Sentry instrumentation", "GraphQL resolvers", "Redis caching"), run a literal sweep across ALL discovered roots BEFORE focus-specific exploration:
+
+```bash
+TOPIC="<phrase from prompt>"
+for ROOT in $SOURCE_ROOTS; do
+  echo "=== $ROOT ==="
+  grep -rli "$TOPIC" "$ROOT" \
+    --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' \
+    --include='*.jsx' --include='*.go' --include='*.rs' --include='*.rb' \
+    2>/dev/null | head -50
+done
+```
+
+The file list this returns becomes your PRIMARY analysis target. Do not narrow it to one subdirectory based on assumed conventions.
+</step>
+
 <step name="explore_codebase">
-Explore the codebase thoroughly for your focus area.
+Explore the codebase thoroughly for your focus area, iterating across ALL `$SOURCE_ROOTS` discovered above. Adapt globs to `$LANGUAGES` — if Python is in the language set, search `*.py`; if TypeScript, `*.ts`/`*.tsx`; etc.
 
 **For tech focus:**
 ```bash
-# Package manifests
-ls package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null
-cat package.json 2>/dev/null | head -100
-
+# Package manifests across ALL roots (already gathered in discover_source_roots)
 # Config files (list only - DO NOT read .env contents)
 ls -la *.config.* tsconfig.json .nvmrc .python-version 2>/dev/null
 ls .env* 2>/dev/null  # Note existence only, never read contents
 
-# Find SDK/API imports
-grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*@" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
+# SDK/API imports — iterate over every source root
+for ROOT in $SOURCE_ROOTS; do
+  grep -rE "^(import|from) (.*stripe|.*supabase|.*aws|.*sentry|.*@)" "$ROOT" \
+    --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' 2>/dev/null | head -30
+done
 ```
 
 **For arch focus:**
 ```bash
-# Directory structure
-find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | head -50
-
-# Entry points
+# Directory tree of each source root
+for ROOT in $SOURCE_ROOTS; do
+  find "$ROOT" -type d \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/__pycache__/*' \
+    | head -40
+done
+
+# Entry points across languages
 ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
-
-# Import patterns to understand layers
-grep -r "^import" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -100
+find . -maxdepth 4 -name 'main.py' -o -name '__main__.py' -o -name 'manage.py' \
+  -o -name 'app.py' -o -name 'wsgi.py' -o -name 'asgi.py' \
+  -not -path '*/.venv/*' -not -path '*/node_modules/*' 2>/dev/null
 ```
 
 **For quality focus:**
 ```bash
-# Linting/formatting config
-ls .eslintrc* .prettierrc* eslint.config.* biome.json 2>/dev/null
-cat .prettierrc 2>/dev/null
+ls .eslintrc* .prettierrc* eslint.config.* biome.json ruff.toml .flake8 mypy.ini pyrightconfig.json 2>/dev/null
 
-# Test files and config
-ls jest.config.* vitest.config.* 2>/dev/null
-find . -name "*.test.*" -o -name "*.spec.*" | head -30
-
-# Sample source files for convention analysis
-ls src/**/*.ts 2>/dev/null | head -10
+# Tests across all roots and languages
+for ROOT in $SOURCE_ROOTS; do
+  find "$ROOT" \( -name '*.test.*' -o -name '*.spec.*' -o -name 'test_*.py' -o -name '*_test.py' \) \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' 2>/dev/null | head -20
+done
 ```
 
 **For concerns focus:**
 ```bash
-# TODO/FIXME comments
-grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
-
-# Large files (potential complexity)
-find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -rn | head -20
-
-# Empty returns/stubs
-grep -rn "return null\|return \[\]\|return {}" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -30
+# TODO/FIXME comments — search every root, every primary language
+for ROOT in $SOURCE_ROOTS; do
+  grep -rnE "TODO|FIXME|HACK|XXX" "$ROOT" \
+    --include='*.py' --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+    --include='*.go' --include='*.rs' \
+    -not -path '*/node_modules/*' 2>/dev/null | head -50
+done
+
+# Large files (potential complexity) — language-aware
+for ROOT in $SOURCE_ROOTS; do
+  find "$ROOT" \( -name '*.py' -o -name '*.ts' -o -name '*.tsx' -o -name '*.go' \) \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' \
+    | xargs wc -l 2>/dev/null | sort -rn | head -10
+done
+
+# If the orchestrator passed a topic phrase, the file list from discover_source_roots
+# is your primary input — analyze each of those files directly.
 ```
 
-Read key files identified during exploration. Use Glob and Grep liberally.
+Read key files identified during exploration. Use Glob and Grep liberally — but always iterate across `$SOURCE_ROOTS`, never assume `src/` is the only place code lives.
 </step>
 
 <step name="write_documents">
@@ -153,6 +209,23 @@ Write document(s) to `.rihal/codebase/` using the templates below.
 4. Always include file paths with backticks
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+**MANDATORY — Scan Scope section.** Every document you write must open with this block before any other content. The orchestrator will reject documents missing it.
+
+```markdown
+## Scan Scope
+
+**Source roots discovered:** `<list from discover_source_roots step 1>`
+**Source roots searched:** `<subset actually iterated by greps>`
+**Source roots NOT searched:** `<any discovered root not searched>` — Reason: `<vendored / out-of-scope / time / etc.>`
+**Languages detected:** `<from manifests, e.g. Python 3.11, TypeScript 5.x>`
+**Topic phrase (if any):** `<literal phrase from orchestrator prompt, or "none">`
+**Topic-phrase sweep result:** `<file count + 5-10 sample paths from grep -rl, or "n/a">`
+
+**Blind-spot acknowledgment:** If you searched only a subset (e.g. only `src/` while `backend/` and `services/` exist), state it explicitly here. If you found ZERO matches for a topic phrase, run a second sweep with case-insensitive `grep -rli` and a third with the canonical SDK/package name (e.g. `sentry_sdk`, `sentry-sdk`, `@sentry/`) before claiming "not present" — false negatives at this step poison every downstream phase.
+```
+
+If the topic-phrase sweep returns matches in a directory you did not analyze in depth, you MUST either (a) extend the analysis to cover it, or (b) explicitly note in the document body which findings might exist there but were not investigated. Never silently exclude a directory that contains topic-phrase hits.
 </step>
 
 <step name="return_confirmation">

package/rihal/bin/rihal-tools.cjs

@@ -3043,6 +3043,9 @@ function cmdProgress(args) {
     if (!fs.existsSync(roadmapPath)) return [];
     const text = fs.readFileSync(roadmapPath, 'utf8');
     const phases = [];
+    const seen = new Set();
+
+    // Format A — markdown pipe tables: | 07 | Name | Goal |
     const rowRe = /^\|\s*(\d{1,3}(?:\.\d+)?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|/gm;
     let m;
     while ((m = rowRe.exec(text)) !== null) {
@@ -3051,16 +3054,54 @@ function cmdProgress(args) {
       const goal = m[3].trim();
       if (!/^\d/.test(num)) continue;
       if (name.toLowerCase() === 'phase') continue;
+      if (seen.has(num)) continue;
+      seen.add(num);
       phases.push({ number: num, name, goal });
     }
+
+    // Format B — heading style: ## Phase 07 — Name  /  ### Phase 07: Name  /  ## Phase 07 - Name
+    const headRe = /^#{2,4}\s*Phase\s+(\d{1,3}(?:\.\d+)?)\s*[—\-:]\s*([^\n]+)$/gm;
+    while ((m = headRe.exec(text)) !== null) {
+      const num = m[1].trim();
+      const name = m[2].trim();
+      if (seen.has(num)) continue;
+      seen.add(num);
+      // Goal: pull the first non-empty line after the heading that starts with **Goal:** or is plain text
+      const after = text.slice(headRe.lastIndex).split(/\n/).slice(0, 8).join('\n');
+      const goalMatch = after.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+      phases.push({ number: num, name, goal: goalMatch ? goalMatch[1].trim() : '' });
+    }
+
+    // Sort numerically (handles "07" vs "10" string ordering correctly)
+    phases.sort((a, b) => parseFloat(a.number) - parseFloat(b.number));
     return phases;
   }
 
   function extractMilestoneName() {
-    if (!fs.existsSync(roadmapPath)) return null;
-    const text = fs.readFileSync(roadmapPath, 'utf8');
-    const m = text.match(/^##\s+Milestone\s+(M\d+\S*)\s*[—\-:]?\s*(.*)$/m);
-    return m ? `${m[1]} ${m[2]}`.trim() : null;
+    // 1. Try ROADMAP.md headings — match any milestone header form
+    if (fs.existsSync(roadmapPath)) {
+      const text = fs.readFileSync(roadmapPath, 'utf8');
+      // Bold form: **Milestone: v1.0 — Name** or **Milestone v1.0 — Name**
+      let m = text.match(/\*\*\s*Milestone\s*:?\s*([^\n*]+?)\s*\*\*/i);
+      if (m) return m[1].trim();
+      // Header form: ## Milestone v1.0 — Name  /  ## Milestone: v1.0 — Name
+      m = text.match(/^#{1,4}\s+Milestone\s*:?\s*([^\n]+)$/m);
+      if (m) return m[1].trim();
+    }
+    // 2. Fall back to state.json milestone field
+    try {
+      if (fs.existsSync(statePath)) {
+        const s = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        if (s && s.milestone) return String(s.milestone).trim();
+      }
+    } catch { /* ignore */ }
+    return null;
+  }
+
+  // Treat any of `number`, `id`, or `name` as the phase identifier.
+  // Different commands historically write different field names — accept all.
+  function phaseKey(p) {
+    return String(p?.number ?? p?.id ?? p?.name ?? '').trim();
   }
 
   function walkPhaseDirs() {
@@ -3099,10 +3140,13 @@ function cmdProgress(args) {
       });
     }
 
-    // Undercount: phases that exist on disk but not in state
-    const statePhaseNums = new Set(statePhases.map(p => String(p.number)));
+    // Undercount: phases that exist on disk but not in state.
+    // Accept any of `number`, `id`, or `name` as the phase identifier — the codebase historically writes different fields.
+    // Also normalize "07" / "7" / 7 to a comparable form.
+    const norm = (k) => String(k ?? '').replace(/^0+(\d)/, '$1');
+    const statePhaseNums = new Set(statePhases.map(p => norm(phaseKey(p))));
     const diskPhaseNums = Object.keys(diskByNum);
-    const missingFromState = diskPhaseNums.filter(n => !statePhaseNums.has(n));
+    const missingFromState = diskPhaseNums.filter(n => !statePhaseNums.has(norm(n)));
     if (missingFromState.length > 0) {
       insights.push({
         kind: 'undercount',
@@ -3132,14 +3176,15 @@ function cmdProgress(args) {
 
     // Route A — phases with pending plans (ready to execute)
     const pendingExec = statePhases.filter(p => {
-      const disk = diskByNum[String(p.number)];
+      const disk = diskByNum[phaseKey(p)];
       return disk && disk.plan_count > disk.summary_count;
     }).slice(0, 3);
     for (const p of pendingExec) {
+      const k = phaseKey(p);
       routes.push({
         letter: 'A',
-        label: `Execute phase ${p.number} — unfinished plans`,
-        command: `/rihal:execute-phase ${p.number}`,
+        label: `Execute phase ${k} — unfinished plans`,
+        command: `/rihal:execute-phase ${k}`,
       });
     }
 
@@ -3155,6 +3200,23 @@ function cmdProgress(args) {
       });
     }
 
+    // Route B' — in-progress phases without plans (the user is actively working but no SPRINT.md exists yet)
+    const inProgressNoPlan = statePhases
+      .filter(p => (p.status === 'in_progress' || p.status === 'in-progress'))
+      .filter(p => {
+        const disk = diskByNum[phaseKey(p)];
+        return !disk || disk.plan_count === 0;
+      })
+      .slice(0, 2);
+    for (const p of inProgressNoPlan) {
+      const k = phaseKey(p);
+      routes.push({
+        letter: 'B',
+        label: `Plan phase ${k} — in progress without SPRINT.md`,
+        command: `/rihal:plan ${k}`,
+      });
+    }
+
     // Route C — close out milestone if everything seems done
     const allDone = statePhases.length > 0 && statePhases.every(p => p.status === 'complete' || p.completed);
     if (allDone) {
@@ -3215,11 +3277,28 @@ function cmdProgress(args) {
     phase_count: phaseCount,
     completed_count: completedCount,
     bar: buildBar(completedCount, phaseCount),
-    phases: roadmapPhases.map(p => ({
-      ...p,
-      disk: diskByNum[p.number] || null,
-      in_state: statePhases.some(sp => String(sp.number) === p.number),
-    })),
+    phases: (() => {
+      // Prefer ROADMAP-parsed phases when available; fall back to state.phases
+      // when the roadmap doesn't use a parseable format. Normalize "07" / "7" / 7.
+      const norm = (k) => String(k ?? '').replace(/^0+(\d)/, '$1');
+      const source = roadmapPhases.length > 0 ? roadmapPhases : statePhases.map(p => ({
+        number: phaseKey(p),
+        name: p.name || '',
+        goal: p.goal || '',
+        status: p.status,
+      }));
+      return source.map(p => {
+        const k = phaseKey(p);
+        const sp = statePhases.find(x => norm(phaseKey(x)) === norm(k));
+        return {
+          ...p,
+          number: k,
+          status: p.status || (sp && sp.status) || null,
+          disk: diskByNum[k] || null,
+          in_state: !!sp,
+        };
+      });
+    })(),
     decisions: state ? (state.decisions || []).slice(-3) : [],
     blockers: state ? (state.blockers || []).filter(b => !b.resolved).slice(0, 5) : [],
     insights,

package/rihal/commands/progress.md

@@ -1,12 +1,12 @@
 ---
 name: rihal:progress
-description: Check project progress and suggest next steps
+description: Alias of /rihal:status --verbose — full project state dashboard with decisions, blockers, and next-step routes
 argument-hint: ""
 allowed-tools: bash, read, grep
 ---
 
 <objective>
-Check project progress narrative — what was done, what is next, and route to the best next action.
+Alias of `/rihal:status --verbose`. Produces the verbose project state dashboard — phase, sprint progress, recent decisions, blockers, last council session, and a Next Up route tree.
 </objective>
 
 <execution_context>
@@ -14,6 +14,5 @@ Check project progress narrative — what was done, what is next, and route to t
 </execution_context>
 
 <process>
-Execute the progress workflow from @.rihal/workflows/progress.md end-to-end.
-Load state, summarize recent work, suggest next command to run.
+Execute the progress workflow from @.rihal/workflows/progress.md end-to-end. That workflow delegates to `.rihal/workflows/status.md` in verbose mode — single source of truth via `rihal-tools progress init`.
 </process>

package/rihal/references/dispatch-banner.md

@@ -0,0 +1,157 @@
+# Dispatch Banner — Persona-driven hand-off format
+
+**Purpose:** every time a Rihal workflow spawns a sub-agent (mapper, planner, executor, council member, etc.), the user must see WHO is taking over, in their voice, with what scope. Inspired by BMAD's PM-introduces-itself pattern. No silent dispatches.
+
+This banner format is mandatory for every `Task(subagent_type=...)` invocation in any Rihal workflow.
+
+---
+
+## Persona registry
+
+Each agent has a persona name and a one-line role tag used in the banner. Pull from `rihal/team.yaml` (`name` + `role` fields). For utility agents not in team.yaml, use the fallback table below.
+
+| Agent ID | Persona name | Role tag | Glyph |
+|---|---|---|---|
+| `rihal-sadiq` | Sadiq (صادق) | Director of Strategy | 🧭 |
+| `rihal-waleed` | Waleed (وليد) | CTO / Architect | 🏛️ |
+| `rihal-hussain-pm` | Hussain (حسين) | Product Manager | 📋 |
+| `rihal-mariam` | Mariam (مريم) | Marketing & Growth | 📣 |
+| `rihal-fatima` | Fatima (فاطمة) | QA Lead | 🔍 |
+| `rihal-yousef` | Yousef (يوسف) | Senior Backend Engineer | 🛠️ |
+| `rihal-haitham` | Haitham (هيثم) | Senior Frontend Engineer | 🎨 |
+| `rihal-layla` | Layla (ليلى) | UX Designer | ✏️ |
+| `rihal-zahra` | Zahra (زهراء) | Branding & Creative | 🎭 |
+| `rihal-zayd` | Zayd (زيد) | Senior ML Engineer | 🧠 |
+| `rihal-khalid` | Khalid (خالد) | DevOps & Infrastructure | 🚢 |
+| `rihal-nasser` | Nasser (ناصر) | Engineering Manager | 🤝 |
+| `rihal-ahmed-hassani-director` | Ahmed (أحمد) | Tech & Delivery Director | 🧩 |
+| `rihal-noor` | Noor (نور) | Technical Writer | ✒️ |
+| `rihal-omar` | Omar (عمر) | Software Engineer | ⚙️ |
+| `rihal-hanzla` | Hanzla | Senior Full-Stack Engineer | ⚡ |
+| `rihal-codebase-mapper` | Dalil (دليل) | Codebase Scout | 🧭 |
+| `rihal-planner` | Khattat (خطّاط) | Sprint Planner | 📐 |
+| `rihal-executor` | Munaffidh (منفّذ) | Plan Executor | 🔨 |
+| `rihal-phase-researcher` | Bahith (باحث) | Phase Researcher | 🔬 |
+| `rihal-verifier` | Muhaqqiq (محقّق) | Goal Verifier | ✅ |
+| `rihal-security-auditor` | Hamid (حامد) | Security Auditor | 🛡️ |
+| `rihal-debugger` | Mufattish (مفتّش) | Debug Investigator | 🐛 |
+
+If an agent is not in this table, derive: `Persona = Title-cased role from team.yaml`, glyph `🤖`.
+
+---
+
+## Banner format — DISPATCH (before spawn)
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  {glyph}  {Persona name} — {Role tag}                    │
+╰─────────────────────────────────────────────────────────╯
+
+السلام عليكم — I'm {Persona-first-name}, your {short role}.
+
+{One-sentence first-person statement of what this agent will do,
+ referencing the user's request directly. No abstract jargon.}
+
+Scope:
+  • {bullet — what's in scope}
+  • {bullet — what's in scope}
+
+Output:
+  → {file path or deliverable}
+
+{Optional: any caveat the user should know up-front, e.g. "I'll
+ only read code — no edits, no commits." }
+
+Working now — I'll surface anything I'm unsure about before
+returning.
+```
+
+**Rules:**
+- Always first-person (`I'm`, `I'll`, `I have`). Never "the agent will…"
+- Always include `السلام عليكم` for the first dispatch in a session; for subsequent dispatches in the same conversation, replace with `Back at it —` or similar continuity phrase.
+- Always state the deliverable path so the user can grep / open the file later.
+- Keep total banner ≤ 14 lines. If scope needs more bullets, that's a sign the spawn is too broad — narrow it first.
+
+---
+
+## Banner format — RETURNED (after spawn)
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  ✓  {Persona name} — back                                │
+╰─────────────────────────────────────────────────────────╯
+
+{One-sentence first-person summary of what got done.}
+
+Covered:
+  • {bullet — concrete coverage, e.g. "Searched: web/, backend/, ml/"}
+  • {bullet}
+
+Skipped / blind spots:
+  • {bullet — explicit acknowledgment of what was NOT done}
+
+Wrote:
+  → {file path} ({N} lines)
+
+{Optional: 1-2 follow-up questions the persona surfaces, in their
+ own voice, e.g. "I noticed X — want me to dig deeper?"}
+
+I'm still here for follow-up questions about this work until the
+next dispatch.
+```
+
+**Rules:**
+- Always declare blind spots, even if "none". An empty `Skipped` section is a code smell — it usually means the agent didn't honestly account for what it skipped.
+- Follow-up questions stay in the persona's voice; the orchestrator does not strip them.
+- The "still here for follow-up" line tells the user that subsequent questions in this conversation will be answered by THIS persona until a new dispatch fires.
+
+---
+
+## Follow-up framing
+
+When the user asks a follow-up question after a RETURNED banner and BEFORE the next dispatch, the orchestrator answers AS the persona that just returned — first person, persona name in any signature line. Example:
+
+> User: "kya tumne backend/onyx/ check kiya tha?"
+>
+> Orchestrator response (as Dalil):
+>
+> > Yes — I swept it. Found 47 files importing `sentry_sdk`. Want me to drill into the LoggingIntegration init points specifically? — Dalil
+
+When the topic shifts to something OUTSIDE the persona's scope, hand off explicitly:
+
+```
+This is outside my scope as Dalil (codebase mapping). Handing off to
+{next persona} for {topic}…
+```
+
+Then print a fresh DISPATCH banner.
+
+---
+
+## Concurrency: parallel dispatches
+
+If a workflow spawns multiple agents in parallel (e.g. `/rihal:council` summons 4 specialists), print ONE combined banner:
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  Majlis (مجلس) — convening 4 voices                      │
+╰─────────────────────────────────────────────────────────╯
+
+I'm convening: Sadiq · Waleed · Hussain · Fatima
+Topic: {one-line topic}
+Each will weigh in independently — I'll compile their answers
+and surface where they agree, disagree, or push back.
+```
+
+Each individual agent's response is then prefixed with their persona glyph + name, e.g.:
+
+```
+🏛️  Waleed: …
+🔍  Fatima: …
+```
+
+---
+
+## When to skip the banner
+
+Never. If a workflow chooses to skip, it must justify in code review — the only legitimate reason is a sub-millisecond pure-data-shaping helper that produces no user-facing output. Anything that does real work gets a banner.

package/rihal/workflows/dashboard.md

@@ -23,18 +23,49 @@ STOP — do not proceed.
 
 ## Step 1 — Resolve dashboard script
 
-Check for the dashboard server in priority order:
+Check for the dashboard server in priority order. Use a single bash block so all fallbacks run before failing:
 
-1. `./server/dashboard.js` (when inside the rihal-code source repo)
-2. `./.rihal/lib/server/dashboard.js` (installed package copy)
-3. `$(npm root -g)/@hanzlaa/rcode/server/dashboard.js` (global install)
+```bash
+DASHBOARD=""
+# 1. Source repo
+if [ -f ./server/dashboard.js ]; then
+  DASHBOARD="./server/dashboard.js"
+# 2. Installed package copy inside project
+elif [ -f ./.rihal/lib/server/dashboard.js ]; then
+  DASHBOARD="./.rihal/lib/server/dashboard.js"
+else
+  # 3. Global installs — check npm, pnpm, and yarn roots
+  for ROOT in "$(npm root -g 2>/dev/null)" "$(pnpm root -g 2>/dev/null)" "$(yarn global dir 2>/dev/null)/node_modules"; do
+    [ -z "$ROOT" ] && continue
+    if [ -f "$ROOT/@hanzlaa/rcode/server/dashboard.js" ]; then
+      DASHBOARD="$ROOT/@hanzlaa/rcode/server/dashboard.js"
+      break
+    fi
+  done
+  # 4. Last resort — resolve via the rcode/rihal binary symlink
+  if [ -z "$DASHBOARD" ]; then
+    for BIN in rcode rihal rihal-code; do
+      BIN_PATH="$(command -v $BIN 2>/dev/null)" || continue
+      REAL_BIN="$(readlink -f "$BIN_PATH" 2>/dev/null)"
+      [ -z "$REAL_BIN" ] && continue
+      # Walk up from dist/rcode.js → package root → server/dashboard.js
+      PKG_ROOT="$(dirname "$(dirname "$REAL_BIN")")"
+      if [ -f "$PKG_ROOT/server/dashboard.js" ]; then
+        DASHBOARD="$PKG_ROOT/server/dashboard.js"
+        break
+      fi
+    done
+  fi
+fi
+echo "DASHBOARD=$DASHBOARD"
+```
 
 Store the resolved path as `$DASHBOARD`.
 
 If none found, print:
 ```
 ❌ Dashboard script not found.
-Run `npx @hanzlaa/rcode install` to install the package, or check you're inside a project with .rihal/.
+Run `npx @hanzlaa/rcode install` (or `pnpm add -g @hanzlaa/rcode`) to install the package, or check you're inside a project with .rihal/.
 ```
 Exit.
 

package/rihal/workflows/do.md

@@ -99,10 +99,47 @@ Then dispatch to the prerequisite command instead of the originally-matched rout
 The guard never silently rejects intent — it always either dispatches to a sensible alternative OR explicitly tells the user what flag overrides it (e.g. `--skip-prerequisites` for the rare legitimate use case).
 </step>
 
+<step name="external_data_guard" priority="first-match">
+**Block code-only routing when the actionable signal lives in an external system.**
+
+Some tasks reference systems whose data is NOT in the repo — observability platforms, issue trackers, analytics, and product dashboards. A pure codebase scan can map *instrumentation* but cannot classify *what is actually firing*. Routing such requests to `/rihal:scan` or `/rihal:map-codebase` without first establishing a data source produces theoretical output (violates the codebase-first rule).
+
+**External-data signals** — match if `$QUESTION` contains any of:
+
+- Observability: `sentry`, `datadog`, `new relic`, `newrelic`, `bugsnag`, `rollbar`, `honeycomb`, `grafana`, `prometheus`, `splunk`, `cloudwatch`
+- Analytics: `google analytics`, ` GA4`, `mixpanel`, `amplitude`, `posthog`, `heap`
+- Issue/support: `linear`, `jira`, `zendesk`, `intercom`, `freshdesk`, `pagerduty`
+- Product/CRM: `stripe dashboard`, `hubspot`, `salesforce`
+
+**Action verbs** — match if `$QUESTION` contains any of: `audit`, `clean up`, `cleanup`, `classify`, `triage`, `review errors`, `noisy`, `top errors`, `which errors`, `production errors`, `dashboard`.
+
+If BOTH a system signal AND an action verb match, fire the guard. Ask via AskUserQuestion BEFORE choosing a route:
+
+```
+The task involves {detected system} — the actionable data lives there, not in the repo.
+A codebase scan alone will only show instrumentation, not which errors are firing.
+
+How should we access the external data?
+
+1. MCP/API access available — pull the data and analyze it
+2. I'll paste the top errors / dashboard export manually
+3. Codebase-only scan is fine — I just want the instrumentation map
+4. Cancel — let me reformulate
+```
+
+Then route accordingly:
+- **Option 1:** Continue to `route` step but tag the chosen command with a note to use the external data source. If no Rihal command natively reads the external system, route to `/rihal:discuss` and have the agent guide MCP/API setup.
+- **Option 2:** Route to `/rihal:discuss` so the user can paste data into a focused conversation, OR `/rihal:note` to capture, then re-run.
+- **Option 3:** Continue to `route` step normally (likely `/rihal:scan` or `/rihal:map-codebase`) but display a clear caveat: *"Output will be an instrumentation map only — it cannot classify which errors are noisy vs critical."*
+- **Option 4:** Stop. Print the original input back so the user can rephrase.
+
+Skip this guard when `AUTO_MODE=true` AND the input explicitly contains `--codebase-only` or `instrumentation map` — those signal the user already accepted the limitation.
+</step>
+
 <step name="route">
 **Match intent to command.**
 
-(Run only after greenfield_guard has cleared.)
+(Run only after greenfield_guard AND external_data_guard have cleared.)
 
 Evaluate `$QUESTION` against these routing rules. Apply the **first matching** rule: