@hanzlaa/rcode 2.1.0

package/rihal/references/codebase-grounding.md

@@ -0,0 +1,76 @@
+<codebase_grounding>
+
+**Mandatory for any agent answering a technical question about an existing codebase.**
+
+Before producing your response, you MUST use Read/Grep/Glob/Bash to inspect
+the actual codebase. Your recommendations must cite specific evidence from
+the repo, not general knowledge.
+
+## The Rule
+
+- **Zero tool uses = zero credibility.** If you produce a response without
+  calling Read, Grep, Glob, or Bash at least once on a codebase question,
+  your output is considered ungrounded and will be flagged.
+- **Cite file:line.** Every specific claim about the codebase must reference
+  a concrete `path/to/file.ext:42` location. Claims without citations are
+  treated as speculation.
+- **Base recommendations on observed evidence.** Do not say "you should
+  probably have caching" — say "I see `src/api/search.ts:88` makes a DB call
+  on every request with no cache; add an in-memory LRU here."
+
+## What to inspect (minimum)
+
+For performance/latency questions:
+- Relevant service entry points (handlers, routes)
+- Existing metrics/observability (baseline-metrics.md, instrumentation files)
+- Recent commits touching the area (`git log --oneline -20 -- path/`)
+- Any profiling artifacts already captured
+
+For code quality / bug questions:
+- The specific files mentioned
+- Test files for those paths
+- Recent changes to those paths
+
+For architecture questions:
+- Directory structure of the affected subsystem
+- Interface boundaries (types, protocols, APIs)
+- Dependency graph (imports, cross-module calls)
+
+## Acceptable citation formats
+
+Good:
+- "`src/api/search.ts:88` — no cache on retrieval path"
+- "Per `baseline-metrics.md` line 12, internal search P50=21s"
+- "Commit `a1b2c3d` shows OCR was moved to separate service"
+
+Unacceptable (ungrounded):
+- "The backend probably needs caching"
+- "You might want to profile this"
+- "Consider checking the logs"
+
+## When you genuinely have no evidence
+
+If the codebase doesn't contain information needed to answer, state it explicitly:
+"I searched `src/` for `{keyword}` via Grep — zero matches. The evidence for
+{claim} isn't in this repo. Either it lives elsewhere (e.g. separate service,
+external docs) or needs to be created."
+
+Then propose what to inspect next, or defer with a clear signal.
+
+## Tools, in order of preference
+
+1. **Read** — when you know the file path
+2. **Grep** — when you know a pattern
+3. **Glob** — when you know a pattern but not the path
+4. **Bash** (git log, find, wc) — for history, stats, or multi-step queries
+5. **Web search** — last resort, only when question references external tech
+
+## Anti-patterns
+
+- ❌ Producing a recommendation list without a single tool call
+- ❌ Speculating about code you haven't read
+- ❌ Citing generic best practices as if they're project-specific
+- ❌ Saying "the codebase likely has X" instead of checking
+- ❌ Copying boilerplate advice that would apply to any project
+
+</codebase_grounding>

package/rihal/references/command-redirect-format.md

@@ -0,0 +1,62 @@
+# Rihal Command Redirect Format
+
+Shared reference for all agents and workflows when they suggest the user run a different command.
+
+## The rule
+
+**When suggesting a `/rihal:*` command, print it on a single line for copy-paste.**
+
+The user's terminal-style interface benefits from one-line commands they can select and paste without touching line-wrap issues. Never split a suggested command across multiple lines, never bullet it, never break arguments onto separate rows.
+
+## Good format
+
+```
+Run: /rihal:council I'm in Pakistan, USD 1000 budget, want to dropship Gaming + Creator accessories to UAE. Should I build a Next.js custom app or use Shopify?
+```
+
+One line. User selects the whole line, pastes, presses enter.
+
+## Bad format — do NOT do this
+
+```
+Run /rihal:council with the new question:
+"I'm in Pakistan, USD 1000 budget, want to dropship Gaming + Creator accessories to UAE. Should I build a Next.js custom app or use Shopify?"
+```
+
+Two lines, with quotes, with a lead-in sentence. The user has to reconstruct the command mentally.
+
+## When to redirect
+
+Agents and workflows redirect when:
+- An agent receives a question outside its domain (Sadiq gets a technical question → Waleed)
+- A workflow gets an input type it doesn't handle (`/rihal:plan` gets a decision question → `/rihal:council`)
+- The user's intent would be better served by a different command
+
+## Template
+
+```
+<reason for redirect in one sentence>
+
+Copy-paste this instead:
+
+/rihal:<command> <exact arguments from user's original input>
+```
+
+The third line — the full command — is a single physical line, regardless of length. No wrapping. No quotes around the arguments unless the command itself requires them.
+
+## For argument substitution
+
+Pass `$ARGUMENTS` verbatim when redirecting plan → council or discuss → council. Do not modify punctuation, do not add quotes, do not summarize. The user said what they meant — preserve it.
+
+## Multi-option redirects
+
+If multiple commands could fit, list each on its own line as a complete single-line command:
+
+```
+Could be either — pick one:
+
+/rihal:discuss waleed <your question>
+/rihal:council <your question>
+```
+
+Not with lead-in prose for each option.

package/rihal/references/commit-conventions.md

@@ -0,0 +1,125 @@
+# Rihal Commit Conventions
+
+Shared reference `@`-included by every workflow that creates or modifies git artifacts.
+
+## Detect project-local conventions FIRST (mandatory)
+
+Before writing any commit, scan the project for local commit standards and let them **override** the defaults in this file. Check in this priority order — stop at the first one that yields a concrete allowed-types + allowed-scopes list:
+
+1. **`commitlint.config.{js,cjs,ts,mjs,json}`** — most authoritative. Parse `rules['type-enum']` and `rules['scope-enum']`.
+2. **`.github/workflows/semantic*.{yaml,yml}`** — GitHub Semantic PR action. Parse `types:` and `scopes:` blocks under `amannn/action-semantic-pull-request`.
+3. **`.github/COMMIT_CONVENTIONS.md`, `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`** — look for sections naming allowed types/scopes.
+4. **`git log --oneline -50`** — infer from past 50 commits: extract `type(scope):` prefixes, take the set that appears ≥2 times.
+
+Run this cheaply before composing the commit:
+
+```bash
+# Priority 2 example — semantic PR action scopes
+if [ -f .github/workflows/semantic.yaml ] || [ -f .github/workflows/semantic.yml ]; then
+  echo "--- project semantic PR config ---"
+  cat .github/workflows/semantic*.y*ml 2>/dev/null | sed -n '/types:/,/scopes:/{p}; /scopes:/,/[A-Za-z]*:/{p}'
+fi
+# Priority 4 fallback — infer from history
+git log --oneline -50 | grep -oE '^[a-f0-9]+ [a-z]+\([a-z0-9-]+\):' | awk '{print $2}' | sort -u
+```
+
+**If the project defines scopes, you MUST pick from that list.** Do not invent new scopes (e.g., `branding` when only `web, server, docker, k8s, e2e, docs, ci, deps, ml, strapi` are allowed). A commit that fails the project's semantic PR check wastes the user's CI run and signals the workflow didn't read the repo.
+
+If no project list exists, fall back to the generic rihal scopes in the "Format" section below.
+
+## Format
+
+All commits follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): subject
+```
+
+- **type**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
+- **scope** (optional): a short noun describing the affected area — `council`, `install`, `agents`, `workflows`, `references`, `cli`, `docs`, `test`
+- **subject**: lowercase first letter, imperative mood, no trailing period, under 72 characters
+
+Example:
+```
+feat(council): parallel subagent dispatch via Task tool
+fix(install): hash-check skipped symlinked files
+docs(agents): add Fatima's default moves
+```
+
+## The subject line is load-bearing
+
+The subject is read by:
+
+- Other engineers browsing `git log --oneline`
+- `git blame` users hunting for context
+- CI semantic-release parsers (which auto-bump versions)
+- Future-you in 6 months
+
+Every word counts. "fix bug" is never acceptable. "fix(council): panel scoring ignored --agents flag" is.
+
+## Body
+
+If the commit needs more than a subject, leave one blank line and write a body. The body explains **why**, not **what** — the diff already shows what changed.
+
+```
+feat(council): parallel subagent dispatch via Task tool
+
+The v1 council fired 13 personas sequentially in one Claude context,
+producing one voice with 13 hats. The v2 council spawns each selected
+agent as a first-class subagent via the Task tool, running in parallel.
+
+Benefits:
+- Real independence — each subagent has its own context and cannot
+  be biased by what the previous agent said
+- Parallel latency — 3 agents respond in ~max(each) instead of sum
+- Smaller orchestrator context — each subagent's output is summarized
+  back rather than accumulated in the parent
+
+Replaces cli/lib/council-panel.cjs caller paths in the slash command
+template.
+```
+
+## What NOT to put in commits
+
+Per `/home/hanzla/development/rihal-code/CLAUDE.md` and `AGENTS.md`:
+
+- **Never** add `Generated with Claude Code` or `Co-Authored-By: Claude` trailers
+- **Never** add `🤖 Generated` markers
+- **Never** use `--no-verify` to bypass hooks
+- **Never** use `git add -A` or `git add .` without reading what would be staged
+
+The project explicitly rejects AI attribution in commit messages. Human authorship is the default and the only acceptable form.
+
+## Staging
+
+Always stage specific files:
+
+```bash
+git add rihal/agents/rihal-sadiq.md rihal/agents/rihal-waleed.md
+```
+
+Not:
+
+```bash
+git add .
+```
+
+The `.` form stages untracked config files, secrets, and scratch directories that shouldn't be in the commit. Specific staging forces you to see what you're committing.
+
+## Push authorization
+
+**Never run `git push` without explicit human approval on that specific push.** Prior authorization for one push does not transfer to the next. This is a hard rule in `AGENTS.md` and it applies to every workflow that touches git.
+
+Workflows that produce commits must hand back to the user at the end and wait for an explicit "push" before running `git push`. If the user has not typed the word "push", the workflow stops at the commit step.
+
+## Commit from a workflow
+
+When a Rihal workflow creates a commit on the user's behalf:
+
+1. **Run the "Detect project-local conventions" scan** above. Pick scope from the project's allowed list if one exists.
+2. Stage only the files the workflow actually modified (never `-A`)
+3. Write the subject as `type(scope): subject` using project-local types/scopes when defined, generic rihal scopes only as fallback
+4. If the body adds real value (the why isn't obvious from the diff), include it
+5. Do not sign with AI attribution
+6. Print the commit SHA and one-line summary to the user
+7. **Stop.** Do not push. Wait for explicit authorization.

package/rihal/references/common-bug-patterns-index.md

@@ -0,0 +1,44 @@
+# Common Bug Patterns — Quick Index
+
+A reference of 15+ patterns that appear repeatedly across codebases. Each pattern shows the manifestation, how to detect it, and a fix template. Use this before forming debugging hypotheses.
+
+## Pattern Categories
+
+### Async Patterns
+- **Race Condition in Concurrent Operations** — Two async operations modify shared state without synchronization → "flaky" tests, data loss
+- **Missing await in Async Chain** — Forgot `await` keyword → using Promise instead of value → "Cannot read property X of undefined"
+- **Unhandled Promise Rejection** — Promise rejects with no `.catch()` or `try-catch` → silent failure
+
+### State Mutation Patterns
+- **Shared Reference Bug** — Multiple parts reference same object, one mutates it → "I didn't change this but it changed"
+- **Mutation in Array/Map Iteration** — Modifying collection while iterating → skipped items, out-of-order processing
+- **Stale Closure** — Function captures old variable state → wrong value after variable changes
+
+### Type/Schema Patterns
+- **Implicit Type Coercion** — `"5" == 5` behavior, Array operations behaving unexpectedly
+- **Null/Undefined Confusion** — Treating null and undefined as same → access undefined property → crash
+- **Schema Drift** — Code expects field that doesn't exist → "Cannot read property X of undefined"
+
+### API & I/O Patterns
+- **Retry Loop Without Backoff** — Same request loops rapidly → hammers server → blocks execution
+- **Resource Leak** — DB connections, file handles never closed → "too many connections" error
+- **Timeout Without Fallback** — Request hangs indefinitely → process blocks forever
+
+### Logic Patterns
+- **Off-by-One Error** — Loop boundary wrong → skips first/last item or crashes
+- **Lost Update in Distributed Systems** — Two processes update same record → one write lost
+- **Cascading Failures** — One service down takes out dependent services
+
+### Configuration Patterns
+- **Env Variable Not Loaded** — Code checks `process.env.FOO` but it's not set → silent default (often wrong)
+- **Hardcoded Paths in Code** — Path works locally, breaks in CI/deployment → "file not found"
+
+## How to Use
+
+1. **Check Manifestation** — Does it match what you're seeing?
+2. **Use Detection Signal** — Grep for the pattern in your codebase
+3. **Apply Fix Template** — Copy pattern and adapt to your code
+
+## Full Details
+
+For complete examples with 30+ patterns, code snippets, and debugging strategies, see `/rihal/references/common-bug-patterns.md` (detailed reference).