@hanzlaa/rcode 2.3.6 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.3.6",
+  "version": "2.4.1",
   "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": {
@@ -8,6 +8,14 @@
     "rihal": "dist/rcode.js",
     "rihal-code": "dist/rcode.js"
   },
+  "scripts": {
+    "dashboard": "node server/dashboard.js",
+    "test": "node --test",
+    "test:ci": "node --test --test-reporter=spec",
+    "postinstall": "node cli/postinstall.js",
+    "build:cli": "node scripts/build.cjs",
+    "build": "node scripts/build.cjs"
+  },
   "files": [
     "cli/",
     "rihal/",
@@ -62,13 +70,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "dashboard": "node server/dashboard.js",
-    "test": "node --test",
-    "test:ci": "node --test --test-reporter=spec",
-    "postinstall": "node cli/postinstall.js",
-    "build:cli": "node scripts/build.cjs",
-    "build": "node scripts/build.cjs"
   }
-}
+}

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:
 

package/rihal/workflows/init.md

@@ -142,9 +142,12 @@ git remote -v 2>/dev/null | head -2
 find . -maxdepth 3 -type d ! -path "./node_modules*" ! -path "./.git*" ! -path "./.rihal*" ! -path "./.claude*" ! -path "./.planning*" 2>/dev/null | head -20
 ```
 
-Write `.rihal/RIHLA.md` following this template (don't over-interpret — just record what's seen):
+Write `.rihal/RIHLA.md` following this template (don't over-interpret — just record what's seen).
+
+**Naming note (do NOT remove from the template):** the file is `RIHLA.md`, not `RIHAL.md`. This is intentional — same Arabic root, different word. **Rihal (رحّال)** = the traveler/tool. **Rihla (رحلة)** = the journey/voyage. The product is *Rihal* (the tool you use); the per-project artifact is *Rihla* (your project's journey). The HTML comment in the template below preserves this reminder for anyone who later wonders if it's a typo.
 
 ```markdown
+<!-- RIHLA (رحلة) = "the journey". Not a typo of RIHAL (رحّال) = "the traveler" / the tool itself. Same root, different word. This file documents your project's journey; Rihal is the tool that walks it with you. -->
 # RIHLA — Project journey baseline
 
 **Written by:** /rihal:init

package/rihal/workflows/progress.md

@@ -1,184 +1,46 @@
+# Workflow: rihal:progress
+
 <purpose>
-Render project progress: what was accomplished, where you are, what's pending, what's next. All data comes from a single `rihal-tools progress init` call. This workflow is a pure renderer — no direct markdown parsing, no state.json grep, no phase-directory walk.
+**`/rihal:progress` is an alias of `/rihal:status --verbose`.**
 
-**SSOT:** `.rihal/state.json`, surfaced through `rihal-tools progress init`. `/rihal:progress` and `/rihal:status` call the same CLI and cannot disagree (issue #131 closed).
+Historically this was a separate workflow with overlapping data and a heavier render. They both read the same source of truth (`rihal-tools progress init`), so we collapsed them: `/rihal:status` is the canonical renderer with built-in slim/verbose modes, and `/rihal:progress` is a thin alias that always runs in verbose mode.
 
-For a sprint-board view, use `/rihal:sprint-status`. For a concise dashboard, use `/rihal:status`. This workflow gives the full narrative view with recent-work excerpts and an intent-tree Next Up menu.
+Use whichever name you prefer — they produce the same output.
 </purpose>
 
 <required_reading>
-@.rihal/references/output-format.md
-Read all files referenced by the invoking prompt's execution_context before starting.
+@.rihal/workflows/status.md
 </required_reading>
 
-<output_format>
-Banner from output-format.md:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► PROGRESS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Use ✓ complete / ◆ in_progress / ○ planned / 🅿 parking-lot throughout.
-End with a Next Up block rendered from the CLI's `routes[]` array.
-</output_format>
-
 <process>
 
-<step name="init_context">
-
-## 1. Init context
-
-Fetch the full progress snapshot in a single call:
-
-```bash
-SNAPSHOT=$(node .rihal/bin/rihal-tools.cjs progress init)
-```
-
-Parse as JSON.
-
-If `SNAPSHOT.project` is null AND `SNAPSHOT.phases[]` is empty:
-
-```
-No planning structure found.
-
-Run /rihal:new-project to start a new project.
-```
-
-Exit.
+## Step 1 — Delegate to /rihal:status in verbose mode
 
-Read `DISCUSS_MODE` from config (separate cheap call):
-
-```bash
-DISCUSS_MODE=$(node .rihal/bin/rihal-tools.cjs config 2>/dev/null | grep -oE '"discuss_mode"\s*:\s*"[^"]*"' | cut -d'"' -f4 || echo "discuss")
-```
+Execute the workflow defined in `.rihal/workflows/status.md` end-to-end, with one override:
 
-</step>
+- Always render in **verbose mode** (full Steps 2–6 output: banner + phases + insights + decisions + blockers + Next Up route tree).
+- Treat `$ARGUMENTS` exactly as `/rihal:status --verbose $ARGUMENTS` would.
 
-<step name="recent_work">
+Do not parse ROADMAP.md, walk SUMMARY.md files, or grep state.json directly. If the underlying CLI reports a drift insight, surface it — do not silently compensate.
 
-## 2. Recent work excerpts
+## Step 2 — Footer note (one-time alias hint)
 
-For the last 2-3 phase directories with SUMMARY.md, pull the one-liner field surgically:
+After the verbose status output, append a single grey line:
 
-```bash
-# find the 3 most recent SUMMARY.md files
-(find .planning/phases -name "SUMMARY.md" -o -name "*-SUMMARY.md" 2>/dev/null) | xargs -r ls -t 2>/dev/null | head -3 | while read f; do
-  node .rihal/bin/rihal-tools.cjs summary-extract "$f" --fields one_liner,status
-done
 ```
-
-Each call returns `{ ok: true, one_liner: "...", status: "..." }`. Collect into an in-memory list for rendering. This avoids loading full SUMMARY.md bodies — context-expensive and unnecessary.
-
-</step>
-
-<step name="insights">
-
-## 3. Insights — surface what the CLI noticed
-
-`SNAPSHOT.insights[]` contains drift warnings, between-milestone detection, phase-dir undercount. Render above the progress bar so the user sees divergences immediately:
-
-```
-⚠ {insight.message}     (severity: warn)
-ℹ {insight.message}     (severity: info)
-```
-
-Each insight that mentions a fix command should have it surfaced exactly as-is — e.g. "Run: node .rihal/bin/rihal-tools.cjs state sync --from-disk".
-
-</step>
-
-<step name="report">
-
-## 4. Render the progress view
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► PROGRESS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-# {SNAPSHOT.project}
-
-{insights block — printed FIRST if present}
-
-**Progress:** {SNAPSHOT.bar}
-**Milestone:** {SNAPSHOT.milestone or "—"}
-**Discuss mode:** {DISCUSS_MODE}
-
-## Recent Work
-- [Phase {N}]: {one_liner extracted in step 2}
-- [Phase {N}]: {one_liner}
-
-## Current Position
-Phase [{SNAPSHOT.current_phase}] of [{SNAPSHOT.phase_count}]
-Plan progress: {completed_count}/{phase_count}
-
-## Key Decisions
-- {SNAPSHOT.decisions[].summary} — [{phase}.{plan}], {date}
-
-## Blockers
-- ⚠ {SNAPSHOT.blockers[].description} — [{phase}.{plan}]
-
-## Pending Todos
-- {todo count} pending — /rihal:check-todos to review
-(Skip if count = 0)
-
-## Active Debug Sessions
-- {count} active — /rihal:debug to continue
-(Skip if count = 0)
-```
-
-Omit any section whose underlying array is empty — don't print "Key Decisions" with zero entries.
-
-</step>
-
-<step name="next_up">
-
-## 5. Next Up — intent tree
-
-Render `SNAPSHOT.routes[]` as a grouped menu. Group by `letter` field (A / B / C). Multiple routes per letter print indented under that letter's heading:
-
-```
-▶ Next Up
-
-  [A] Execute unfinished work
-      → /rihal:execute-phase 999.5
-      → /rihal:execute-phase 66
-
-  [B] Plan researched-but-unplanned phases
-      → /rihal:plan-phase 68
-
-  [C] Close out current milestone
-      → /rihal:audit-milestone
-      → /rihal:complete-milestone
-```
-
-The CLI derives routes from current disk state (researched-not-planned phases, phases with pending plans, all-complete detection for milestone closure). Do NOT second-guess by walking disk yourself.
-
-If `SNAPSHOT.routes[]` is empty or only has fallback entries, print:
-
-```
-▶ Nothing obvious on deck.
-
-  [A] /rihal:progress          — refresh
-  [B] /rihal:council            — start a conversation on what next
-  [C] /rihal:new-milestone     — if the current cycle is done
+(/rihal:progress is an alias of /rihal:status --verbose — same data, same source.)
 ```
 
-</step>
+Skip this footer if `$ARGUMENTS` already contains `--no-alias-hint`.
 
 </process>
 
 ## Success Criteria
 
-- [ ] `progress init` called once — not repeatedly per section
-- [ ] No direct parsing of ROADMAP.md, epics.md, or SUMMARY.md in the workflow body
-- [ ] Recent work uses `summary-extract --fields one_liner` (surgical read)
-- [ ] Insights section rendered when non-empty
-- [ ] Next Up is a grouped route tree, not a single suggestion
+- [ ] Calls the status workflow with verbose mode forced
+- [ ] No independent CLI parsing — single source of truth via `progress init`
+- [ ] Optional alias hint footer printed unless suppressed
 
 ## On Error
 
-- **CLI missing:** "Rihal Code install missing or stale. Run: npx @hanzlaa/rcode install"
-- **CLI returns `ok: false`:** surface the CLI's error verbatim. Do not attempt to compensate — the CLI's failures are the source of truth on what's wrong.
-- **Network-dependent insights:** there should be none. Insights are computed from local state + disk only.
+Defer to `.rihal/workflows/status.md` error handling. This workflow adds nothing on top.

package/rihal/workflows/scan.md

@@ -85,30 +85,115 @@ If user says no, exit.
 mkdir -p .planning/codebase
 ```
 
-## Step 4: Spawn mapper agent
+## Step 4: Announce dispatch (persona-driven)
 
-Spawn a single `rihal-codebase-mapper` agent with the selected focus area:
+Use the canonical dispatch-banner spec at `.rihal/references/dispatch-banner.md`. Read it now if you have not already — it defines the BMAD-style first-person hand-off the user expects.
+
+For this workflow, the dispatched agent is `rihal-codebase-mapper` → persona **Dalil (دليل) — Codebase Scout** 🧭.
+
+Print the DISPATCH banner per the spec. Filled-in template for this workflow:
+
+```
+╭─────────────────────────────────────────────────────────╮
+│  🧭  Dalil (دليل) — Codebase Scout                       │
+╰─────────────────────────────────────────────────────────╯
+
+السلام عليكم — I'm Dalil, your codebase scout.
+
+I'll map this repo for you with focus: {focus}{ — topic: "{topic}" if topic else ""}.
+Before I start I'll discover every source root (not just `src/`),
+detect the language mix from manifests, and — if you gave me a
+topic phrase — sweep for it across all roots before narrowing.
+
+Scope:
+  • Focus: {focus}
+  • Topic phrase: {topic-keyword or "none — broad scan"}
+  • Read-only: I never edit code.
+
+Output:
+  → .planning/codebase/{document_list}
+
+Working now — I'll come back with a Scan Scope declaration
+so you see exactly what I covered (and what I skipped).
+```
+
+Always first-person. Always include the deliverable path. If a topic phrase isn't provided, drop the topic-related lines rather than printing "none".
+
+## Step 5: Spawn mapper agent
+
+Spawn a single `rihal-codebase-mapper` agent. Pass the persona instructions in the prompt so the agent's own response opens in-character:
 
 ```
 Task(
-  prompt="Scan this codebase with focus: {focus}. Write results to .planning/codebase/. Produce only: {document_list}",
+  prompt="You are spawned as **Dalil (دليل) — Codebase Scout**. Open your response with a one-line in-character continuity beat (e.g. 'Dalil here — starting the scan.') and sign your closing summary with your persona name. Use first-person.
+
+  Scan this codebase with focus: {focus}.
+  Topic phrase (literal search target, may be empty): {topic-keyword}
+  Write results to .planning/codebase/. Produce only: {document_list}.
+
+  REQUIRED — every document must open with a 'Scan Scope' section per `.rihal/agents-rules/codebase-mapper/detailed-guide.md` that declares:
+  - Source roots discovered (top-level non-vendored directories)
+  - Source roots searched (grep/glob targets)
+  - Source roots NOT searched and why
+  - Languages detected (from package manifests)
+  - If a topic phrase was provided: a literal `grep -rl '<phrase>' <discovered-roots>` run across ALL source roots, with the file count and an excerpt of matches
+
+  This scope section is non-negotiable — the orchestrator will reject documents missing it.",
   subagent_type="rihal-codebase-mapper",
   model="{resolved_model}"
 )
 ```
 
-## Step 5: Report
+## Step 6: Announce return (persona-driven)
+
+When the agent returns, print the RETURNED banner per `.rihal/references/dispatch-banner.md`. Filled-in template:
 
 ```
-## Scan Complete
+╭─────────────────────────────────────────────────────────╮
+│  ✓  Dalil — back from scout                              │
+╰─────────────────────────────────────────────────────────╯
 
-**Focus:** {focus}
-**Documents produced:**
-{list of documents written with line counts}
+Done — here's what I covered for you.
 
-Use `/rihal:map-codebase` for a comprehensive 4-area parallel scan.
+Covered:
+  • Searched: {roots actually iterated}
+  • Languages: {detected language mix}
+  • Topic sweep: {file count + sample paths, or "n/a"}
+
+Skipped / blind spots:
+  • {explicit list — never leave empty without justification}
+
+Wrote:
+  → .planning/codebase/{doc} ({N} lines)
+
+{Optional: 1-2 follow-up questions Dalil surfaces in his own voice,
+ e.g. "I noticed X — want me to dig deeper?"}
+
+I'm still here if you want to follow up on what I found,
+until the next dispatch. — Dalil
+```
+
+If the document is missing its Scan Scope section, do NOT print the success banner. Instead print:
+
+```
+⚠  Dalil returned without a Scan Scope declaration.
+    Treating this run as incomplete — re-spawn with stricter instructions?
 ```
 
+## Follow-up framing
+
+Until the next `Task()` dispatch, answer follow-up questions about the scan AS Dalil — first-person, sign with `— Dalil`. If the user asks something outside Dalil's scope (e.g. strategy, planning, code editing), hand off explicitly per the dispatch-banner spec and print a fresh DISPATCH banner for the new persona.
+
+## 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:
+
+```
+Tip: `/rihal:map-codebase` runs a 4-area parallel scan if you want broader coverage.
+```
+
+Skip this cue if the user already asked for a focused scan — don't push an upsell.
+
 </process>
 
 <success_criteria>