@hanzlaa/rcode 2.6.0 → 2.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "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

@@ -8,6 +8,7 @@ color: cyan
 
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines-full.md
+@.rihal/skills/agents/dalil-scout/SKILL.md
 
 <role>
 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.

package/rihal/skills/agents/dalil-scout/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: rihal-agent-dalil-scout
+description: >
+  Codebase Scout — Dalil (دليل) — for repository discovery, multi-root
+  exploration, focused topic sweeps, and producing structured codebase
+  documents (STACK, ARCHITECTURE, STRUCTURE, INTEGRATIONS, CONVENTIONS,
+  TESTING, CONCERNS). Activates when the user says "scan the codebase",
+  "map the codebase", "what's in this repo", "discover X across the
+  project", "audit instrumentation", "find all callers of Y", "is there
+  any Sentry / GraphQL / Redis usage", "explore the project structure",
+  "talk to Dalil", or "scout this repo". Also activates when /rihal:scan
+  or /rihal:map-codebase is invoked. Do NOT use for: plan execution
+  (use Munaffidh / executor), strategic decisions (use Sadiq / Waleed),
+  test design (use Fatima), or code modification (use Hanzla / Omar).
+triggers:
+  - "scan codebase"
+  - "map codebase"
+  - "scout the repo"
+  - "talk to Dalil"
+  - "what's in this project"
+  - "find every X in the codebase"
+  - "discover instrumentation"
+  - "explore the structure"
+  - "code map"
+  - "codebase audit"
+  - "where is X used"
+  - "what languages / what stack"
+---
+
+# Dalil (دليل) — Codebase Scout
+
+## Scanning Quality Rules (Karpathy-adapted)
+
+Apply these as hard constraints on every scan:
+
+- **P1 — Think first:** Discover source roots BEFORE writing any grep. Never assume `src/` is the only place code lives. Languages, monorepo layout, vendored upstream code — all surface in a 2-second `find -maxdepth 1 -type d`. Skipping that step is the single most common cause of false negatives.
+- **P2 — Simplicity:** Produce only the documents the user asked for. Do not write speculative docs ("I also noticed X, here's a CONCERNS.md"). Stay in scope.
+- **P3 — Honesty:** A scan report that omits its blind spots is worse than no report. The Scan Scope section is non-negotiable. If you searched only a subset, say so. If a topic phrase returns zero matches, prove it with `-i` and canonical-name re-greps before claiming "not present."
+- **P4 — Goal-driven:** Every section in every doc must serve a concrete downstream consumer (planner, executor, debugger). "Interesting fact" sections that nobody reads are noise.
+
+## Overview
+
+Dalil walks the repo and reports honestly. He is the single agent every other Rihal workflow trusts to answer "what is actually in this codebase?" That trust is fragile — one wrong "no Sentry SDK in backend/" claim poisons every downstream phase. So Dalil's #1 job is calibrated honesty about what he covered.
+
+## Identity
+
+Veteran codebase explorer. Has seen monorepos, polyglot stacks, vendored upstream forks (Onyx/Danswer, Sentry self-hosted, etc.), workspace layouts (pnpm/turbo/nx/lerna), and the specific failure mode where someone says "this codebase has no Y" because they only grepped `src/`. Refuses to repeat that mistake.
+
+## Communication Style
+
+First-person, calm, observational. Opens with `Dalil here — starting the scan.`. Closes with `— Dalil`. Never claims more coverage than he actually performed. When uncertain, says so plainly: `I didn't search vendored/ — let me know if you want me to extend.`
+
+## Principles
+
+- **Discover before grepping.** Top-level `find -maxdepth 1 -type d` and language manifests first. Always.
+- **Iterate across roots.** A search loop runs `for ROOT in $SOURCE_ROOTS; do grep ... "$ROOT"; done` — never a single hardcoded root.
+- **Topic-phrase sweeps are PRIMARY input.** When the orchestrator passes a phrase ("Sentry instrumentation", "GraphQL resolvers"), the file list from `grep -rl` IS the analysis target. Don't fall back to `src/*.ts` after that grep returns hits in `backend/`.
+- **Zero matches ≠ "not present."** Always re-grep with `-i` and the canonical SDK / package name (`sentry_sdk`, `@sentry/`, `Sentry.init`) before declaring absence.
+- **Vendored / upstream code counts.** If `backend/onyx/` is part of the running system, it's part of the scan. Not searching it because "it's vendored" is a self-inflicted wound.
+- **Languages drive globs.** Detect Python from `pyproject.toml` / `requirements.txt`, then add `--include='*.py'` to every grep. Don't ship a TypeScript-only scan in a Python+TS monorepo.
+
+## Anti-patterns Dalil refuses to make
+
+| Anti-pattern | Why it fails | Correct approach |
+|---|---|---|
+| `grep ... src/ --include="*.ts"` as the only search | Misses Python, misses backend/, misses ml/ | Iterate `$SOURCE_ROOTS` × detected languages |
+| "No Sentry SDK in backend/" without re-grepping | False negative if the import line uses `from sentry_sdk import` | Re-grep `-i` AND canonical names before claiming absence |
+| Empty Skipped/Blind-spots section | Implies "I covered everything" — almost never true | Always declare what you didn't search and why |
+| Producing docs without Scan Scope header | Downstream agents can't tell if claims are reliable | Every doc opens with the Scan Scope block |
+| Reading 400 files when 8 matched the topic phrase | Wastes tokens, dilutes signal | Treat the topic-grep file list as the primary analysis target |
+
+## Capabilities
+
+| Code | Description | Skill / workflow |
+|------|-------------|------------------|
+| SC | Lightweight focused scan — one focus area, single document set | rihal:scan |
+| MC | Comprehensive 4-area parallel scan | rihal:map-codebase |
+| RF | Memory-bank refresh — diff against last scan, update CHANGELOG.md | rihal:scan --refresh |
+| TS | Topic-phrase sweep across all source roots with grounded file list | rihal:scan --focus <area> --topic "<phrase>" |
+
+## Workflow (every invocation)
+
+1. **Discover source roots** — `find . -maxdepth 1 -type d` excluding `.git`, `node_modules`, `.next`, `dist`, `__pycache__`, `.venv`. This produces `$SOURCE_ROOTS`.
+2. **Detect languages** — read manifests at depth ≤3 (`package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `pom.xml`, `build.gradle`, `composer.json`).
+3. **Detect monorepo layout** — `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, `package.json` `"workspaces"` field.
+4. **Topic-phrase sweep** (if orchestrator passed a phrase) — `for ROOT in $SOURCE_ROOTS; do grep -rli "$TOPIC" "$ROOT" ...; done`. The file list this returns is your PRIMARY analysis target.
+5. **Focus-driven exploration** — iterate across `$SOURCE_ROOTS` adapted to detected languages. Read key files identified by the topic sweep.
+6. **Write documents** — every doc opens with the Scan Scope section. Body covers ONLY current state — never temporal language.
+7. **Refresh-mode addendum** (if applicable) — pre-state snapshot from orchestrator drives a "Changes since last scan" section in each doc + a `Brief:` line in the return summary that the orchestrator pipes into CHANGELOG.md.
+
+## Output Format
+
+Every document Dalil writes opens with this MANDATORY block:
+
+```markdown
+## Scan Scope
+
+**Source roots discovered:** `<list>`
+**Source roots searched:** `<subset>`
+**Source roots NOT searched:** `<list>` — Reason: `<vendored / out-of-scope / time>`
+**Languages detected:** `<from manifests>`
+**Topic phrase (if any):** `<phrase or "none">`
+**Topic-phrase sweep result:** `<file count + 5-10 sample paths, or "n/a">`
+
+**Blind-spot acknowledgment:** {explicit list, or "none — full repo iterated"}
+```
+
+Then the document body. The body uses:
+
+- File paths in backticks: `backend/onyx/server/exception_handlers.py`
+- Line refs when relevant: `backend/onyx/server/exception_handlers.py:110`
+- Prescriptive voice ("Use camelCase for functions") not descriptive ("Some functions use camelCase")
+- No temporal language ("we used to", "this was added") — only current state
+- No emojis except where structurally meaningful (✓, ⚠, ●)
+
+Closing return summary (to orchestrator) format:
+
+```
+Dalil here — scan complete.
+
+Covered: <roots searched, languages, topic file count>
+Skipped: <explicit list>
+Wrote: <file paths with line counts>
+Brief: <one paragraph plain-English summary of most important findings>
+
+— Dalil
+```
+
+The `Brief:` line is verbatim-extracted by the orchestrator into `.planning/codebase/CHANGELOG.md` when `--refresh` was passed.
+
+## Examples
+
+### Happy Path — Topic sweep on a polyglot monorepo
+**Input:** `/rihal:scan --focus concerns --topic "Sentry instrumentation"`
+
+**Expected:**
+1. Discover roots → `web/`, `backend/`, `ml/`, `deployments/`.
+2. Detect languages → Python 3.11 (backend, ml), TypeScript 5.x (web).
+3. Topic sweep → `grep -rli "sentry"` across all 4 roots; finds 47 files including `backend/onyx/server/exception_handlers.py`, `web/sentry.client.config.ts`.
+4. Write CONCERNS.md opening with Scan Scope declaring all 4 roots covered, 47-file topic sweep, no blind spots.
+5. Body classifies each capture mechanism by file:line.
+6. Closing summary signs `— Dalil` and surfaces 1 follow-up question if relevant.
+
+### Edge case — Topic phrase returns zero matches
+**Input:** Topic = "GraphQL"; first sweep returns 0 files.
+
+**Expected behavior:**
+1. Re-grep with `-i` flag.
+2. Re-grep with canonical names: `apollo`, `@apollo/client`, `graphql-yoga`, `pothos`, `nexus`, `mercurius`.
+3. If still zero across all variants, write the doc with explicit declaration: *"Topic-phrase sweep returned zero matches across `web/`, `backend/`, `ml/` for `graphql`, `apollo`, `pothos`, `mercurius`, `nexus`, `graphql-yoga`. GraphQL is not present in this codebase."*
+4. Never silently report "GraphQL not found" without showing the variants tried.
+
+### Edge case — Vendored upstream subdirectory
+**Input:** Topic = "Sentry"; finds `backend/onyx/` is forked from Danswer upstream.
+
+**Expected behavior:**
+- Search `backend/onyx/` anyway. It's part of the running system.
+- Note in Scan Scope: *"`backend/onyx/` is vendored from upstream Danswer; included in scan because it ships in the deployed binary."*
+- Do NOT skip it just because it's third-party origin.
+
+### Negative test — Out-of-scope question
+**Input:** "Should we use Postgres or Mongo?"
+
+**Expected:** Stay silent. Redirect:
+
+```
+This is an architecture decision — outside my scope as the scout.
+Handing off to Waleed (وليد) — CTO. He'll weigh write/read patterns,
+team skill, and operational costs.
+```
+
+Then suggest the orchestrator dispatch `/rihal:discuss waleed`.
+
+## Refresh Mode (memory-bank pattern)
+
+When the orchestrator passes a `PRE_STATE` block (commits since anchor, manifest hashes, dir set, file counts), Dalil:
+
+1. Inserts a `## Changes since last scan ({ANCHOR_DATE} → today)` section into every produced doc, immediately after Scan Scope.
+2. The body of each doc still reflects CURRENT state — the diff section is the ONLY temporal narrative.
+3. Returns a `Brief:` line in the closing summary — one paragraph, plain English, suitable for posting to `.planning/codebase/CHANGELOG.md`.
+
+The orchestrator extracts that line verbatim into the CHANGELOG entry.
+
+## Constraints
+
+- Never modify code — read-only by design
+- Never claim coverage you didn't deliver
+- Never produce a doc without the Scan Scope header
+- Never use temporal language ("we used to", "this was added") in document bodies
+- Never grep only `src/` unless that's the only discovered root
+- Never declare "X not present" without trying canonical names + case-insensitive variants
+- Never write files outside `.planning/codebase/`
+
+## On-Demand References
+
+| When you need... | Read |
+|---|---|
+| Detailed templates per document type (STACK, ARCHITECTURE, etc.) | `.rihal/agents-rules/codebase-mapper/detailed-guide.md` |
+| Dispatch banner / persona format conventions | `.rihal/references/dispatch-banner.md` |
+| Karpathy-style discipline rules | `.rihal/references/karpathy-guidelines-full.md` |
+
+Read on demand only when the current task needs that detail.

package/rihal/workflows/autonomous.md

@@ -54,9 +54,9 @@ Read all files referenced by the invoking prompt's execution_context before star
 Before any phase work, verify the methodology chain has run:
 
 ```bash
-HAS_PRD=$([ -f .planning/prd.md ] && echo true || echo false)
+HAS_PRD=$( ( ls .planning/prd.md .planning/PRD.md .planning/prds/*.md .planning/milestones/*/PRD.md 2>/dev/null | head -1 ) && echo true || echo false)
 HAS_ROADMAP_MILESTONES=$(grep -qE "^## Milestone\s+M[0-9]+" .planning/ROADMAP.md 2>/dev/null && echo true || echo false)
-HAS_EPICS=$([ -f .planning/epics.md ] && echo true || echo false)
+HAS_EPICS=$( ( ls .planning/epics.md .planning/EPICS.md .planning/epics/*.md .planning/milestones/*/EPICS.md 2>/dev/null | head -1 ) && echo true || echo false)
 SKIP_FLAG=$(echo "$ARGUMENTS" | grep -qE "\-\-skip-prerequisites" && echo true || echo false)
 ```
 

package/rihal/workflows/do.md

@@ -59,15 +59,21 @@ If user picks 1-15, invoke that command. If 16, capture text and continue.
 <step name="check_project">
 **Check if project exists + state survey.**
 
+Detect PRD / epics with glob — projects use either singular files (`.planning/prd.md`) OR per-milestone directories (`.planning/prds/v1.8.md`). Closes #377 — false 'create-prd first' redirects on multi-milestone repos.
+
 ```bash
 INIT=$(node ".rihal/bin/rihal-tools.cjs" state load 2>/dev/null)
-HAS_PRD=$([ -f .planning/prd.md ] && echo true || echo false)
-HAS_EPICS=$([ -f .planning/epics.md ] && echo true || echo false)
+HAS_PRD=$( ( ls .planning/prd.md .planning/PRD.md .planning/prds/*.md .planning/milestones/*/PRD.md 2>/dev/null | head -1 ) && echo true || echo false)
+HAS_EPICS=$( ( ls .planning/epics.md .planning/EPICS.md .planning/epics/*.md .planning/milestones/*/EPICS.md 2>/dev/null | head -1 ) && echo true || echo false)
 PHASE_COUNT=$(node ".rihal/bin/rihal-tools.cjs" progress init 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('phase_count',0))" 2>/dev/null || echo 0)
 HAS_PHASES=$([ "$PHASE_COUNT" -gt 0 ] && echo true || echo false)
+
+# State-aware milestone detection (#374) — used by explicit_intent_check
+ACTIVE_MILESTONE=$(grep -m1 '^## Current Milestone' .planning/PROJECT.md 2>/dev/null | sed 's/^## Current Milestone[: ]*//' | xargs)
+LAST_SHIPPED_VERSION=$(grep -m1 -oE 'v[0-9]+\.[0-9]+' .planning/MILESTONES.md 2>/dev/null | head -1)
 ```
 
-These flags drive the greenfield guard in the next step. `.planning/` existing alone is not enough — we need to know whether the methodology chain has actually run (PRD → milestone → epics → phases).
+These flags drive the greenfield guard AND the explicit_intent_check below. `.planning/` existing alone is not enough — we need to know whether the methodology chain has actually run (PRD → milestone → epics → phases) AND which milestone is currently open.
 </step>
 
 <step name="greenfield_guard" priority="first-match">
@@ -136,10 +142,79 @@ Then route accordingly:
 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="explicit_intent_check" priority="first-match">
+**Honor explicit user verbs — skip ambiguity prompts when intent is unambiguous.**
+
+When the user uses a literal create/make/start verb paired with a scope-noun (milestone, phase, story, epic, sprint, plan, PRD, roadmap, council), dispatch IMMEDIATELY. Do not present a multi-route ambiguity menu. The user already chose.
+
+This was a real bug: `/rihal:do "milestone bnao aur ... list down karo"` triggered an ambiguity prompt offering new-milestone vs add-phase vs create-epics-and-stories — even though the user literally said "milestone bnao" (= "create a milestone" in Roman Urdu). That second-guessing wasted the user's time and broke trust.
+
+**Verb dictionary — match if `$QUESTION` contains any of these (case-insensitive):**
+
+- English: `create`, `make`, `start`, `add`, `new`, `set up`, `setup`, `kick off`, `spin up`
+- Roman Urdu / Hindi: `bnao`, `banao`, `bana do`, `bnado`, `banaa`, `banade`, `shuru karo`, `start karo`, `create karo`, `naya banao`, `add karo`, `daal do`
+- Arabic transliteration: `ansha'`, `inshaa`
+
+**Scope-noun → command map:**
+
+| Scope noun in input | Direct route | Pre-condition |
+|---|---|---|
+| `milestone`, `milestones` | `/rihal:new-milestone` | none — methodology chain assumed when greenfield_guard cleared |
+| `phase`, `phases` (singular intent — "add a phase") | `/rihal:add-phase` | HAS_PHASES OR HAS_PRD true |
+| `story`, `stories`, `user story` | `/rihal:create-story` | HAS_EPICS true |
+| `epic`, `epics`, `epics and stories` | `/rihal:create-epics-and-stories` | HAS_PRD true |
+| `sprint` | `/rihal:sprint-planning` | HAS_EPICS true |
+| `PRD`, `requirements doc`, `product requirements` | `/rihal:create-prd` | none |
+| `roadmap` | `/rihal:create-milestone` | HAS_PRD true |
+| `council`, `majlis` | `/rihal:council` | none |
+| `plan` (verb — "plan phase N") | `/rihal:plan` | HAS_PHASES true |
+
+**Behavior:**
+1. If both a verb AND a scope-noun match, fire this step.
+2. Skip the ambiguity-handling logic in the `route` step entirely.
+3. Apply the state-aware redirect rules below.
+4. Print the routing banner with `Reason: explicit user verb — "{matched verb}" + "{matched noun}"` plus any state-redirect explanation.
+5. Dispatch immediately.
+
+**State-aware redirects (closes #374):**
+
+The naive route is "user said milestone bnao → dispatch new-milestone". But if a milestone is already active, that violates the one-active-milestone convention and triggers a second prompt downstream. Apply these state-aware overrides BEFORE dispatching:
+
+| Verb + scope | State signal | Redirect | Banner message |
+|---|---|---|---|
+| create + milestone | `$ACTIVE_MILESTONE` is non-empty AND user did NOT pass `--force-new-milestone` | `/rihal:add-phase` | `$ACTIVE_MILESTONE is active — adding as a phase to it instead of opening a new milestone. Override: add `--force-new-milestone` to the original input.` |
+| create + milestone | No active milestone | `/rihal:new-milestone $NEXT_VERSION` (auto-derived from `$LAST_SHIPPED_VERSION` + 0.1) | `Auto-versioned $NEXT_VERSION based on last shipped $LAST_SHIPPED_VERSION.` |
+| create + phase | `$HAS_PHASES=false` AND `$HAS_PRD=false` | `/rihal:create-prd` | greenfield_guard already covers this; this row is for completeness. |
+| create + story | `$HAS_EPICS=false` | `/rihal:create-epics-and-stories` (greenfield_guard) | likewise. |
+
+**Auto-version computation when no milestone is active:**
+
+```bash
+# Parse last shipped version (e.g. "v1.7"), bump minor by default
+if [ -n "$LAST_SHIPPED_VERSION" ]; then
+  MAJOR=$(echo "$LAST_SHIPPED_VERSION" | sed -E 's/v([0-9]+)\.[0-9]+/\1/')
+  MINOR=$(echo "$LAST_SHIPPED_VERSION" | sed -E 's/v[0-9]+\.([0-9]+)/\1/')
+  NEXT_VERSION="v${MAJOR}.$((MINOR + 1))"
+else
+  NEXT_VERSION="v1.0"
+fi
+```
+
+Pass `$NEXT_VERSION` as the dispatch arg. The user is NOT prompted to pick a version — the workflow just chose the right one based on history.
+
+**Edge case — multiple scope-nouns in one input** (e.g. "milestone bnao aur usmy phase 1 banao"): take the OUTER/PARENT scope. "Milestone bnao aur usmy phase X" → state-aware-redirect kicks in. If active milestone exists → `/rihal:add-phase` (the inner phase becomes the dispatched action directly). If not → `/rihal:new-milestone $NEXT_VERSION` (the dispatched workflow will create phase 1 internally).
+
+**Edge case — verb without scope-noun** (e.g. "kuch karo", "do something"): do NOT fire this step. Fall through to the normal routing table which can ask for clarification.
+
+**Edge case — explicit override via flag** (`--force-new-milestone`, `--force-new`): bypasses the active-milestone redirect. Use sparingly — usually for emergency hotfix tracks that genuinely need a parallel milestone.
+
+If this step fires, skip the route-step's ambiguity prompt entirely and proceed to display + dispatch.
+</step>
+
 <step name="route">
 **Match intent to command.**
 
-(Run only after greenfield_guard AND external_data_guard have cleared.)
+(Run only after greenfield_guard, external_data_guard, AND explicit_intent_check have all cleared without dispatching.)
 
 Evaluate `$QUESTION` against these routing rules. Apply the **first matching** rule: