@hanzlaa/rcode 3.6.16 → 4.0.0

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

@@ -1,44 +0,0 @@
-# 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).

package/rihal/references/context-budget.md

@@ -1,104 +0,0 @@
-# Context Budget Reference
-
-Defines 4 degradation tiers for token usage and how workflows should adapt behavior based on remaining context.
-
-## Configuration
-
-Add to `config.yaml`:
-
-```yaml
-context_window_tokens: 200000  # default; adjust per model profile
-```
-
-Estimation rule: **1 token ≈ 4 characters**. Use this to predict token cost of reads.
-
-## Degradation Tiers
-
-### PEAK (0–30% used)
-**Tokens remaining: >140,000**
-
-- ✅ Full context available — deep reads encouraged
-- ✅ Subagent dispatch OK (Explore, Research, etc.)
-- ✅ Read entire files without hesitation
-- ✅ Batch parallel reads (5+ files simultaneously)
-- ✅ Fetch documentation and external context freely
-
-**Behavior:** Aggressive exploration, thorough analysis.
-
----
-
-### GOOD (30–60% used)
-**Tokens remaining: 80,000–140,000**
-
-- ✅ Full context still available
-- ⚠️ Prefer Grep/Glob over Read for files >500 lines
-- ⚠️ Read only necessary sections, use `limit` + `offset` parameters
-- ✅ Batch parallel reads OK, but max 3–4 simultaneously
-- ⚠️ Defer non-essential documentation fetches
-
-**Behavior:** Balanced — read strategically, ask for sections not summaries.
-
----
-
-### DEGRADING (60–80% used)
-**Tokens remaining: 40,000–80,000**
-
-- ⚠️ Read only frontmatter (first 50–100 lines) for files >500 lines
-- ⚠️ Defer non-critical reads; consolidate questions
-- ⚠️ No subagent dispatch — complete locally
-- ⚠️ Warn user: **"Context at {percent}% usage. Work may slow."**
-- ✅ Continue essential tasks
-
-**Behavior:** Careful — read only what blocks progress.
-
----
-
-### POOR (80%+ used)
-**Tokens remaining: <40,000**
-
-- 🚨 **Emergency mode**
-- 🛑 Read ONLY what's strictly required to unblock next action
-- 🛑 No exploratory reads, no documentation
-- 🛑 Suggest `/rihal-pause-work` if task requires more context
-- 🛑 Warn user: **"Context critical ({percent}%). Resume work to continue."**
-
-**Behavior:** Survival — preserve tokens for final output only.
-
----
-
-## How Workflows Check Budget
-
-Place this check at the start of a heavy read phase:
-
-```python
-def check_budget(current_tokens, config):
-    budget = config.get('context_window_tokens', 200000)
-    used_pct = (current_tokens / budget) * 100
-    
-    if used_pct >= 80:
-        return 'POOR', "Context critical. Suggest /rihal-pause-work"
-    elif used_pct >= 60:
-        return 'DEGRADING', "Context at {used_pct}%. Read frontmatter only."
-    elif used_pct >= 30:
-        return 'GOOD', "Balanced. Prefer Grep for large files."
-    else:
-        return 'PEAK', "Full context. Aggressive exploration OK."
-
-# Usage in workflow:
-tier, msg = check_budget(tokens_used, config)
-if tier == 'POOR':
-    return escalate_to_user(msg)
-```
-
----
-
-## Token Estimation Rules
-
-- **Small file (<100 lines):** ~2,000 tokens
-- **Medium file (100–500 lines):** ~10,000 tokens
-- **Large file (500–2000 lines):** ~30,000 tokens
-- **Grep result (50 matches):** ~3,000 tokens
-- **Bash output (typical):** ~1,000 tokens
-- **Conversation history (N turns):** ~500 tokens per turn
-
-When close to limits, ask: *"Would reading this file block progress?"* If no, defer.

package/rihal/references/continuation-format.md

@@ -1,248 +0,0 @@
-# Continuation Format
-
-Standard format for presenting next steps after completing a command or workflow.
-
-## Core Structure
-
-```
----
-
-## ▶ Next Up
-
-**{identifier}: {name}** — {one-line description}
-
-`{command to copy-paste}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `{alternative option 1}` — description
-- `{alternative option 2}` — description
-
----
-```
-
-## Format Rules
-
-1. **Always show what it is** — name + description, never just a command path
-2. **Pull context from source** — ROADMAP.md for phases, SPRINT.md `<objective>` for plans
-3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
-4. **`/clear` explanation** — always include, keeps it concise but explains why
-5. **"Also available" not "Other options"** — sounds more app-like
-6. **Visual separators** — `---` above and below to make it stand out
-
-## Variants
-
-### Execute Next Plan
-
-```
----
-
-## ▶ Next Up
-
-**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
-
-`/rihal-execute 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Review plan before executing
-
----
-```
-
-### Execute Final Plan in Phase
-
-Add note that this is the last plan and what comes after:
-
-```
----
-
-## ▶ Next Up
-
-**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
-<sub>Final plan in Phase 2</sub>
-
-`/rihal-execute 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**After this completes:**
-- Phase 2 → Phase 3 transition
-- Next: **Phase 3: Core Features** — User dashboard and settings
-
----
-```
-
-### Plan a Phase
-
-```
----
-
-## ▶ Next Up
-
-**Phase 2: Authentication** — JWT login flow with refresh tokens
-
-`/rihal-plan 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/rihal-discuss-phase 2` — gather context first
-- `/rihal-research-phase 2` — investigate unknowns
-- Review roadmap
-
----
-```
-
-### Phase Complete, Ready for Next
-
-Show completion status before next action:
-
-```
----
-
-## ✓ Phase 2 Complete
-
-3/3 plans executed
-
-## ▶ Next Up
-
-**Phase 3: Core Features** — User dashboard, settings, and data export
-
-`/rihal-plan 3`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/rihal-discuss-phase 3` — gather context first
-- `/rihal-research-phase 3` — investigate unknowns
-- Review what Phase 2 built
-
----
-```
-
-### Multiple Equal Options
-
-When there's no clear primary action:
-
-```
----
-
-## ▶ Next Up
-
-**Phase 3: Core Features** — User dashboard, settings, and data export
-
-**To plan directly:** `/rihal-plan 3`
-
-**To discuss context first:** `/rihal-discuss-phase 3`
-
-**To research unknowns:** `/rihal-research-phase 3`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-### Milestone Complete
-
-```
----
-
-## 🎉 Milestone v1.0 Complete
-
-All 4 phases shipped
-
-## ▶ Next Up
-
-**Start v1.1** — questioning → research → requirements → roadmap
-
-`/rihal-new-milestone`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-## Pulling Context
-
-### For phases (from ROADMAP.md):
-
-```markdown
-### Phase 2: Authentication
-**Goal**: JWT login flow with refresh tokens
-```
-
-Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
-
-### For plans (from ROADMAP.md):
-
-```markdown
-Plans:
-- [ ] 02-03: Add refresh token rotation
-```
-
-Or from SPRINT.md `<objective>`:
-
-```xml
-<objective>
-Add refresh token rotation with sliding expiry window.
-
-Purpose: Extend session lifetime without compromising security.
-</objective>
-```
-
-Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
-
-## Anti-Patterns
-
-### Don't: Command-only (no context)
-
-```
-## To Continue
-
-Run `/clear`, then paste:
-/rihal-execute 2
-```
-
-User has no idea what 02-03 is about.
-
-### Don't: Missing /clear explanation
-
-```
-`/rihal-plan 3`
-
-Run /clear first.
-```
-
-Doesn't explain why. User might skip it.
-
-### Don't: "Other options" language
-
-```
-Other options:
-- Review roadmap
-```
-
-Sounds like an afterthought. Use "Also available:" instead.
-
-### Don't: Fenced code blocks for commands
-
-```
-```
-/rihal-plan 3
-```
-```
-
-Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/rihal/references/council-protocol.md

@@ -1,91 +0,0 @@
-# Rihal Council Protocol
-
-Shared reference document `@`-included by every council-related workflow.
-
-## The 5-step majlis
-
-Every Rihal council session follows the same five steps. This is the protocol the orchestrator implements:
-
-1. **Initialize** — load config, state, installed agent list, parse arguments.
-2. **Observe** — run a cheap, bounded codebase scan (config, state, git log, top-level files). Produces a 5-8 line factual summary every subagent will be briefed on.
-3. **Select** — pick 3-5 agents via deterministic keyword scoring. User can override with `--agents=` or force all with `--full`.
-4. **Consult** — spawn selected agents in parallel via the Task tool. Each agent gets the same observed-context brief and the user's question. Cross-talk rounds include previous panelists' responses.
-5. **Record** — save the session artifact under `.planning/council-sessions/council-{date}-{slug}.md`.
-
-Never collapse steps. Never skip the observe step — a council that answers from vibes is worse than no council.
-
-## Cross-talk convention
-
-When agents speak in a council, they can and should reference each other by name when they build on or disagree with a point. The orchestrator passes previous-agent responses as context to later panelists.
-
-Good cross-talk:
-
-> 🛡️ **Fatima:** Waleed's migration plan is solid on the forward path, but he's
-> skipping the rollback test. If the backfill fails at row 2M of 5M, how do
-> we recover? Not covered in the plan.
-
-Bad cross-talk:
-
-> 🛡️ **Fatima:** I agree with Waleed.
-
-Agreements without new information are silence. If an agent genuinely has nothing to add, they should say so in one sentence rather than pad.
-
-## Panel selection (deterministic scoring)
-
-Rihal's council uses a pure-function keyword scorer (`cli/lib/council-panel.cjs`) instead of LLM judgment. This is intentional:
-
-- **Deterministic:** same question produces same panel every time
-- **Testable:** the scoring function has unit tests
-- **Auditable:** users can pass `--explain` to see why each agent was picked or skipped
-- **Cheap:** zero LLM calls before the council starts
-
-The scoring table is versioned with the package. Users who want different weights edit the source and rebuild — there is no runtime config knob for this, and that's by design. The panel selection must be reproducible across machines.
-
-**Padding rules:**
-
-- Strategic questions (containing "should i", "worth", "kill", "pivot", "start new") always include Sadiq even if topic keywords score low.
-- Scope/feature questions (containing "scope", "feature", "roadmap", "prd") always include Hussain-PM.
-- If fewer than the minimum panel size (default 3) score non-zero, the panel is padded with the STRATEGIC_PADDING_ORDER list: sadiq, hussain-pm, waleed, fatima, nasser.
-
-**v2 prototype note:** only Sadiq, Waleed, and Fatima are installed as first-class subagents. The scorer may select agent ids that don't yet have subagent files — the orchestrator must filter to installed agents and fall back to the 3-agent panel.
-
-## Response presentation
-
-Subagent responses are presented **verbatim and in panel order**. The orchestrator never summarizes, paraphrases, or condenses agent output. The user came to the council to hear the agents speak in their own voices — summary defeats the point.
-
-After all verbatim responses, the orchestrator may add a single **Orchestrator Note** (max 3 sentences) that flags a disagreement worth following up on or recommends a second round. The Orchestrator Note is clearly labeled so it's not confused with agent speech.
-
-## Session artifact format
-
-Every council session is saved to `.planning/council-sessions/council-{YYYY-MM-DD}-{slug}.md`. The slug is lowercase-hyphenated from the first 6 words of the question. Format:
-
-```markdown
-# Council Session — {short summary}
-
-**Date:** {ISO date}
-**Panel:** {names}
-**Mode:** {guided|yolo}
-**Project:** {project name from .rihal/config.yaml}
-
-## Question
-{original question}
-
-## Observed Context
-{the Step 2 summary block}
-
-## Panel Responses
-### 🧭 Sadiq
-{verbatim}
-### 🏗️ Waleed
-{verbatim}
-### 🛡️ Fatima
-{verbatim}
-
-## Orchestrator Note
-{if any}
-
-## Follow-ups
-- [ ] {action items}
-```
-
-The artifact is a first-class project document. It's committed to git, reviewed in retros, and referenced when the same question comes up again. The Follow-ups section is the bridge between council and execution.

package/rihal/references/debugger-playbook.md

@@ -1,127 +0,0 @@
-# Debugger Playbook
-
-Loaded by `rihal-debugger` via `@-include`. Contains the full debugging
-philosophy, cognitive bias avoidance, before-hypothesis protocol, investigation
-disciplines, restart protocol, and checkpoint format.
-
-The agent stub holds the role definition, constraints, and @-include list.
-
----
-
-## Philosophy
-
-**User = Reporter, You = Investigator**
-
-User knows: What they expected, what actually happened, error messages, when it started.
-User does NOT know: Root cause, which file, what the fix should be.
-
-Investigate the cause yourself. Don't ask about causation.
-
-**Meta-Debugging: Your Own Code**
-
-When debugging code you wrote:
-- **Treat your code as foreign** — Read it as if someone else wrote it
-- **Question your design decisions** — Your implementations are hypotheses, not facts
-- **Admit your mental model might be wrong** — The code's behavior is truth; your model is a guess
-- **Prioritize code you touched** — If you modified 100 lines and something breaks, those are prime suspects
-
----
-
-## Foundation Principles
-
-- **What do you KNOW for certain?** Observable facts, not assumptions
-- **What are you ASSUMING?** "This library should work this way" — have you verified?
-- **Strip away everything you think you know.** Build understanding from observable facts.
-
----
-
-## Cognitive Biases to Avoid
-
-| Bias | Trap | Antidote |
-|------|------|----------|
-| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What proves me wrong?" |
-| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating |
-| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise |
-| **Sunk Cost** | Spent 2 hours on path, keep going | Every 30 min: "Is this still the path I'd take?" |
-
----
-
-## Before Hypothesis Formation
-
-**MANDATORY:** Read `.rihal/references/common-bug-patterns.md` first.
-
-15+ patterns catalogued there with detection signals. Scanning saves hours:
-- Async patterns (race conditions, missing await, unhandled rejections)
-- State mutation (shared references, closure over loop vars)
-- Import/dependency (circular, version mismatches)
-- Type coercion (== vs ===, undefined vs null)
-- Environment (missing env vars, hardcoded paths)
-- Timing (event listeners not removed, memory leaks)
-
-If bug symptoms match a pattern, the fix template is ready. Don't re-invent debugging.
-
----
-
-## On-Demand Rule Files
-
-| When you need... | Read |
-|---|---|
-| Scientific method for bug investigation | `.rihal/agents-rules/debugger/scientific-method.md` |
-| Investigation techniques (binary search, rubber duck, etc.) | `.rihal/agents-rules/debugger/investigation-protocol.md` |
-| Debug session state management | `.rihal/agents-rules/debugger/debug-session-state.md` |
-| Hypothesis templates for common bug types | `.rihal/agents-rules/debugger/hypothesis-templates.md` |
-| Resuming from checkpoint in debug session | `.rihal/agents-rules/debugger/checkpoint-recovery.md` |
-
-Read ONLY when current task needs them. Don't preemptively load.
-
----
-
-## Investigation Disciplines
-
-**Change one variable:** Make one change, test, observe, document, repeat. Multiple changes = no idea what mattered.
-
-**Complete reading:** Read entire functions, not just "relevant" lines. Read imports, config, tests. Skimming misses details.
-
-**Embrace not knowing:** "I don't know why this fails" = good (now investigate). "It must be X" = dangerous (you stopped thinking).
-
----
-
-## When to Restart
-
-Consider starting fresh when:
-1. **2+ hours, no progress** — You're likely tunnel-visioned
-2. **3+ "fixes" that didn't work** — Your mental model is wrong
-3. **Can't explain current behavior** — Don't layer changes on confusion
-4. **Debugging the debugger** — Something fundamental is wrong
-5. **Fix works but you don't know why** — This isn't fixed, it's luck
-
-Restart protocol:
-1. Close all files and terminals
-2. Write down what you KNOW for certain (facts, not guesses)
-3. Write down what you've RULED OUT
-4. List NEW hypotheses (different from before)
-5. Begin from Evidence Gathering phase
-
----
-
-## Checkpoint Return Format (Exact)
-
-```markdown
-## CHECKPOINT REACHED
-
-**Type:** [ROOT_CAUSE_FOUND | DEBUG_COMPLETE | VERIFICATION_NEEDED]
-**Bug:** [Symptom description]
-**Status:** [What's been determined]
-
-### Current Investigation
-
-[What you've tested, what you've ruled out]
-
-### Hypothesis Being Tested
-
-[Specific, falsifiable claim]
-
-### Awaiting
-
-[What user needs to do/confirm]
-```