@hanzlaa/rcode 2.5.1 → 2.6.1

package/package.json

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

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

@@ -136,10 +136,50 @@ 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. Print the routing banner with `Reason: explicit user verb — "{matched verb}" + "{matched noun}"`.
+4. Dispatch immediately.
+
+**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" → `/rihal:new-milestone` (parent = milestone). The dispatched command will handle the nested 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.
+
+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:
 

package/rihal/workflows/init.md

@@ -128,6 +128,16 @@ test -f .rihal/state.json || node .rihal/bin/rihal-tools.cjs state init --projec
 
 If the project has code (from Step 1 detection), produce `.rihal/RIHLA.md`. This is the journey baseline — a lightweight snapshot, not a full audit. Use `/rihal:map-codebase` or `/rihal:scan` later for deep analysis.
 
+**Memory-bank refresh on `--reset`.** When `--reset` is passed AND `.planning/codebase/` already contains docs from a previous scan, also chain to `/rihal:scan --refresh --focus tech+arch` immediately after writing RIHLA.md. The refresh path:
+
+- Captures pre-state (commits since last doc mtime, manifest hashes, top-level dirs).
+- Briefs the user on what changed since the last scan.
+- Overwrites the docs and appends an entry to `.planning/codebase/CHANGELOG.md`.
+
+Skip the chain if `--skip-scan` is set, no existing docs are present (nothing stale to refresh), or the user passes `--no-refresh`.
+
+This makes init+reset a true memory-bank refresh — RIHLA baseline updated, codebase docs reconciled with current code, CHANGELOG entry written.
+
 Gather (parallel reads, all bounded):
 
 ```bash

package/rihal/workflows/scan.md

@@ -20,7 +20,7 @@ If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 
 **Usage:**
 ```
-/rihal:scan [--focus tech|arch|quality|concerns|tech+arch]
+/rihal:scan [--focus tech|arch|quality|concerns|tech+arch] [--refresh] [--reset]
 ```
 
 **Examples:**
@@ -28,8 +28,20 @@ If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
 /rihal:scan --focus tech
 /rihal:scan --focus arch
 /rihal:scan --focus tech+arch
+/rihal:scan --refresh                 # auto-update stale docs, brief diff, log to CHANGELOG.md
+/rihal:scan --reset --focus tech+arch # silent overwrite (CI / autonomous)
 ```
 
+**Refresh flag — memory-bank pattern.** When `--refresh` is passed AND existing docs are present, the orchestrator:
+
+1. Captures a *pre-state snapshot* (top-level dirs, manifests, dep counts, file counts, git HEAD).
+2. Reads the oldest existing target doc's mtime — anchor for "changes since last scan".
+3. Runs git log + dir diff + manifest diff against that anchor.
+4. Spawns Dalil with the diff context, instructs him to overwrite docs AND prepend a "Changes since last scan" section to each.
+5. Appends a structured entry to `.planning/codebase/CHANGELOG.md` with the brief.
+
+This is the canonical way to keep the memory bank fresh without losing the audit trail of what changed and why.
+
 <process>
 
 ## Focus-to-Document Mapping
@@ -48,7 +60,11 @@ Parse the user's input for `--focus <area>`. Default to `tech+arch` if not speci
 
 Validate that the focus is one of: `tech`, `arch`, `quality`, `concerns`, `tech+arch`.
 
-If invalid:
+Also parse:
+- `--refresh` → auto-update mode (briefs the user on what changed, then overwrites)
+- `--reset` → silent overwrite (no prompt, no brief — for CI / autonomous chains)
+
+If invalid focus:
 ```
 Unknown focus area: "{input}". Valid options: tech, arch, quality, concerns, tech+arch
 ```
@@ -68,16 +84,83 @@ For each target document, check if it already exists in `.planning/codebase/`:
 ls -la .planning/codebase/{DOCUMENT}.md 2>/dev/null
 ```
 
-If any exist, show their modification dates and ask:
+**Three modes:**
+
+### 2a — Refresh mode (`--refresh` flag)
+
+Skip the [y/N] prompt. Instead, run the diff analysis in Step 2c and proceed to dispatch with refresh context.
+
+### 2b — Reset mode (`--reset` flag)
+
+Silent overwrite. No prompt, no brief, no CHANGELOG entry. Use only for CI or chained autonomous workflows.
+
+### 2c — Default mode (no flag)
+
+If any target doc exists, show their mod dates AND age in days, AND a one-line activity hint, then ask:
+
+```bash
+# For each existing doc, compute relative age:
+for DOC in {document_list}; do
+  if [ -f ".planning/codebase/$DOC" ]; then
+    MTIME=$(stat -c %Y ".planning/codebase/$DOC" 2>/dev/null || stat -f %m ".planning/codebase/$DOC" 2>/dev/null)
+    NOW=$(date +%s)
+    AGE_DAYS=$(( (NOW - MTIME) / 86400 ))
+    COMMITS_SINCE=$(git log --oneline --since="@$MTIME" 2>/dev/null | wc -l | tr -d ' ')
+    echo "  - $DOC ({date}, ${AGE_DAYS}d ago, ${COMMITS_SINCE} commits since)"
+  fi
+done
+```
+
 ```
 Existing documents found:
-  - STACK.md (modified 2026-04-03)
-  - INTEGRATIONS.md (modified 2026-04-01)
+  - STACK.md         (2026-03-22, 35d ago, 14 commits since)
+  - INTEGRATIONS.md  (2026-03-22, 35d ago, 14 commits since)
+
+These docs are stale. Three options:
+  [Y]   Refresh — analyze what changed, briefly explain, then overwrite + log to CHANGELOG.md
+  [o]   Overwrite blind — skip the diff brief, just rebuild
+  [n]   Keep as-is, exit
+```
 
-Overwrite with fresh scan? [y/N]
+Map the answer:
+- `Y` / `y` / empty → set internal mode to **refresh**, continue to Step 2d
+- `o` → set mode to **reset**, continue to Step 4
+- `n` / `no` → exit
+
+## Step 2d — Pre-state capture (refresh mode only)
+
+Before dispatching Dalil, capture a structured snapshot for diff comparison. Fire each command and save the output verbatim — it goes into the dispatch prompt and the CHANGELOG entry.
+
+```bash
+# Anchor mtime — oldest existing target doc
+ANCHOR_TS=$(for DOC in {document_list}; do
+  [ -f ".planning/codebase/$DOC" ] && stat -c %Y ".planning/codebase/$DOC" 2>/dev/null || stat -f %m ".planning/codebase/$DOC" 2>/dev/null
+done | sort -n | head -1)
+ANCHOR_DATE=$(date -d "@$ANCHOR_TS" -u +%Y-%m-%d 2>/dev/null || date -r "$ANCHOR_TS" -u +%Y-%m-%d 2>/dev/null)
+
+# Commits since anchor
+echo "=== COMMITS SINCE $ANCHOR_DATE ==="
+git log --oneline --since="@$ANCHOR_TS" 2>/dev/null | head -50
+
+# Top-level dir set
+echo "=== TOP-LEVEL DIRS ==="
+find . -maxdepth 1 -type d -not -name '.git' -not -name 'node_modules' -not -name '.next' -not -name 'dist' -not -name '.venv' -not -name '__pycache__' | sort
+
+# Manifest hashes (changed if deps shifted)
+echo "=== MANIFEST HASHES ==="
+for M in package.json pnpm-lock.yaml pyproject.toml requirements.txt Cargo.toml go.mod; do
+  [ -f "$M" ] && echo "$M  $(sha256sum "$M" 2>/dev/null | awk '{print $1}' || shasum -a 256 "$M" | awk '{print $1}')"
+done
+
+# Source file count by language
+echo "=== SOURCE FILE COUNTS ==="
+for EXT in py ts tsx js jsx go rs rb; do
+  COUNT=$(find . -name "*.$EXT" -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/dist/*' 2>/dev/null | wc -l | tr -d ' ')
+  [ "$COUNT" -gt 0 ] && echo "*.$EXT  $COUNT"
+done
 ```
 
-If user says no, exit.
+Store this entire output as `$PRE_STATE` for the dispatch prompt.
 
 ## Step 3: Create output directory
 
@@ -121,7 +204,9 @@ Always first-person. Always include the deliverable path. If a topic phrase isn'
 
 ## 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:
+Spawn a single `rihal-codebase-mapper` agent. Pass the persona instructions in the prompt so the agent's own response opens in-character.
+
+**Base prompt (always sent):**
 
 ```
 Task(
@@ -144,6 +229,35 @@ Task(
 )
 ```
 
+**Refresh-mode addendum (append to the prompt above when mode === "refresh"):**
+
+```
+  REFRESH MODE — this is NOT a first scan. Existing docs are present and stale.
+
+  Anchor date (last scan): {ANCHOR_DATE}
+  Pre-state snapshot (verbatim from orchestrator):
+  {PRE_STATE}
+
+  Additional requirements for refresh runs:
+  1. After the Scan Scope section in EACH document, insert a section titled
+     '## Changes since last scan ({ANCHOR_DATE} → today)' that lists, in bullets:
+     - new files / removed files relevant to this doc's focus
+     - new dependencies / removed dependencies (for STACK.md / INTEGRATIONS.md)
+     - new modules / removed modules (for ARCHITECTURE.md / STRUCTURE.md)
+     - new TODO/FIXME or eliminated ones (for CONCERNS.md)
+     - 3-7 most-important commit subjects from the pre-state COMMITS list
+       that materially shaped the current state
+  2. The body of each document must reflect CURRENT state — not a diff. The
+     'Changes since last scan' section is the ONLY place where pre-state and
+     diff narrative belongs.
+  3. Include a final line in your return summary:
+     'Brief: {one-paragraph plain-English summary of the most important changes
+     since last scan, suitable for posting to CHANGELOG.md}'
+     The orchestrator extracts this verbatim.
+```
+
+When refresh mode is active, also include `topic_keyword` (if any) and the resolved focus in the prompt as before.
+
 ## Step 6: Announce return (persona-driven)
 
 When the agent returns, print the RETURNED banner per `.rihal/references/dispatch-banner.md`. Filled-in template:
@@ -184,6 +298,44 @@ If the document is missing its Scan Scope section, do NOT print the success bann
 
 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 6.5: Append to CHANGELOG.md (refresh mode only)
+
+When mode === "refresh", extract Dalil's `Brief:` line from his RETURNED summary and append a structured entry to `.planning/codebase/CHANGELOG.md`. Create the file if missing. Use the Read tool first if updating, then Edit/Write — never blind-overwrite a file with prior entries.
+
+**Entry format:**
+
+```markdown
+## {today's ISO date} — refresh
+
+**Anchor:** {ANCHOR_DATE} ({age in days} days ago)
+**Focus:** {focus}
+**Commits since anchor:** {count}
+**Docs touched:** {comma-separated list}
+
+{Dalil's Brief: line, verbatim, formatted as a paragraph}
+
+**Top-level signals:**
+- Source roots: {comma-separated list of dirs from PRE_STATE}
+- Languages: {detected mix}
+- Manifest changes: {hash diff summary, e.g. "package.json: changed", "pyproject.toml: unchanged"}
+
+---
+```
+
+Insert at the TOP of the file body (newest-first), under any pre-existing `# Changelog — Codebase Memory Bank` H1. If the file doesn't exist, write it with this header:
+
+```markdown
+# Changelog — Codebase Memory Bank
+
+This file tracks structural changes between scans. Each entry is auto-written by `/rihal:scan --refresh`. Newest entries first.
+
+---
+
+{first entry here}
+```
+
+This file is **read by future `/rihal:scan --refresh` runs** as additional anchor context — the memory bank is self-improving across scans.
+
 ## 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: