@hanzlaa/rcode 2.1.0

package/rihal/references/git-planning-commit.md

@@ -0,0 +1,185 @@
+# Git Planning Commit Reference
+
+Defines commit prefixes for planning artifacts, separate from code commits.
+
+---
+
+## Overview
+
+Planning commits are **metadata about work**, not code changes. They use special prefixes to distinguish from feature/fix commits.
+
+---
+
+## Commit Prefixes
+
+### 1. `plan:` — Planning Artifacts
+
+**Purpose:** Capture or update SPRINT.md, roadmap files, phase structure
+
+**Format:**
+```
+plan: <action> <artifact> for <scope>
+```
+
+**Examples:**
+```
+plan: add execute-phase 02 for Rihal authentication module
+plan: update roadmap with Q3 milestones
+plan: split phase 3 into 3a (API) and 3b (database)
+plan: revise Phase 1 scope — reduce by 2 tasks
+```
+
+**When to use:**
+- Create new SPRINT.md after phase design
+- Update SPRINT.md during refinement (before execution)
+- Record major scope decisions
+- Capture planning worksheets or pre-mortems
+
+---
+
+### 2. `wip:` — Work In Progress
+
+**Purpose:** Commit progress during phase execution, before completion
+
+**Format:**
+```
+wip: <description> (<progress>)
+```
+
+**Examples:**
+```
+wip: implement auth endpoints (2 of 3 routes)
+wip: add unit tests for cart service (50% coverage)
+wip: refactor database layer (schema + models, queries next)
+wip: revision loop attempt 2 of 3 for build failure
+```
+
+**When to use:**
+- Save work checkpoint mid-phase
+- Document partial completion
+- Record state before escalation
+- Mark iteration/retry attempts in gates
+
+**Note:** `wip:` commits are NOT final; phase completion creates code commits.
+
+---
+
+### 3. `session:` — Session Markers
+
+**Purpose:** Record session start/pause/end, escalation gates, state decisions
+
+**Format:**
+```
+session: <event> at <phase> — <detail>
+```
+
+**Examples:**
+```
+session: pause work at phase 2 task 4 of 7
+session: resume work from phase 2
+session: escalation gate at phase 3 — awaiting user input on architecture
+session: abort gate — state preserved for manual repair
+session: context critical (92% usage) — pausing to avoid token exhaustion
+```
+
+**When to use:**
+- Start/pause/resume session
+- Hit escalation/abort gates
+- Context budget exceeded
+- Decision point needing human input
+
+---
+
+### 4. `roadmap:` — Long-Term Planning
+
+**Purpose:** Capture roadmap decisions, milestone plans, future phases
+
+**Format:**
+```
+roadmap: <action> for <timescale>
+```
+
+**Examples:**
+```
+roadmap: define Q2 2026 milestones for Rihal dashboard
+roadmap: plan Phase 6–8 for mobile app redesign
+roadmap: identify technical debt and refactoring priorities
+roadmap: schedule team capacity planning for H2 2026
+```
+
+**When to use:**
+- Create or update roadmap files
+- Plan future milestones
+- Document strategic decisions
+- Record capacity constraints
+
+---
+
+## Separation from Code Commits
+
+**Code commits** follow Conventional Commits:
+```
+feat(auth): add JWT token refresh endpoint
+fix(cart): resolve race condition on checkout
+refactor(database): normalize user schema
+```
+
+**Planning commits** use special prefixes:
+```
+plan: add execute-phase 02 SPRINT.md
+wip: implementation attempt 1 of 2
+session: pause work at task 4
+roadmap: plan Q3 milestones
+```
+
+**In git log, they're clearly distinct:**
+```
+abc123 feat(auth): add JWT refresh          ← code
+def456 wip: implement refresh logic (75%)   ← session artifact
+ghi789 plan: update Phase 2 scope           ← planning artifact
+jkl012 session: pause work at task 5 of 8   ← session marker
+mno345 fix(auth): close XSS in token        ← code
+```
+
+---
+
+## Hook Integration
+
+Add to `.git/hooks/post-commit`:
+
+```bash
+#!/bin/bash
+# Validate planning commit prefix matches changed files
+
+msg=$(git log -1 --format=%B)
+files=$(git diff-tree --no-commit-id --name-only -r HEAD)
+
+if [[ "$msg" =~ ^plan: ]]; then
+  # Expect *.md files (SPRINT.md, roadmap, etc.)
+  if [[ ! "$files" =~ \.md$ ]]; then
+    echo "Warning: 'plan:' commit but no .md files changed"
+  fi
+fi
+
+if [[ "$msg" =~ ^wip: ]]; then
+  # Expect source code, tests, or config
+  if [[ ! "$files" =~ \.(js|ts|py|json|yaml|md)$ ]]; then
+    echo "Warning: 'wip:' commit but no source files changed"
+  fi
+fi
+
+if [[ "$msg" =~ ^session: ]] || [[ "$msg" =~ ^roadmap: ]]; then
+  # These typically commit SPRINT.md or metadata
+  true  # No validation needed
+fi
+```
+
+---
+
+## Best Practices
+
+1. **One prefix per commit** — Don't mix `plan:` and `feat:` in same commit
+2. **Descriptive detail** — "update SPRINT.md" is vague; "add execute-phase 02 for auth module" is clear
+3. **Session markers** — Always mark session start/pause to enable resume
+4. **Escalation tracking** — Use `session: escalation gate` to mark decision points
+5. **Preserve state** — Never delete planning commits; history aids context recovery

package/rihal/references/karpathy-guidelines.md

@@ -0,0 +1,79 @@
+# Karpathy Coding Guidelines
+
+Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rihal agent that writes, reviews, or refactors code must internalize these four principles.
+
+**Tradeoff:** These bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+**Rihal application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rihal-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rihal-executor must stop on Rule 4 deviations and return a checkpoint, not silently guess.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Test: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+**Rihal application:** rihal-planner tasks must be single-purpose. rihal-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rihal-code-review explicitly flags overengineering.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+**Rihal application:** rihal-executor commits must only include files its tasks touched. The deviation scope boundary (out-of-scope warnings logged to deferred-items.md, not fixed) enforces this. rihal-code-review-fix must not change style in files it's auditing.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**Rihal application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rihal-executor self-check loop verifies Done-when conditions were met. rihal-sprint-checker rejects plans where tasks have vague success criteria.
+
+## Enforcement
+
+Agents that write or modify code (rihal-executor, rihal-planner, rihal-tech-writer, rihal-codebase-mapper when producing code docs) must:
+1. @-include this file
+2. Apply the 4 principles as hard constraints, not suggestions
+3. Reference the specific principle when refusing to make a change (e.g., "Declining per Karpathy #3: that's adjacent to the requested change but not part of it")
+
+## Credit
+
+Original principles by Andrej Karpathy. Reference implementation by Forrest Chang at github.com/forrestchang/andrej-karpathy-skills. Adapted and extended for rihal's multi-agent architecture.

package/rihal/references/model-profiles.md

@@ -0,0 +1,90 @@
+# Model Profiles
+
+Rihal v2 supports four model profile configurations that control which Claude model variant is assigned to each agent. Use the `resolve-model` subcommand to look up the model for a specific agent under the active profile.
+
+## Profile definitions
+
+### quality
+
+Optimized for reasoning-heavy agents that make strategic decisions or verify work. Uses Claude 3.5 Opus for maximum capability on complex analysis; Haiku for lightweight utilities.
+
+| Agent | Model | Role |
+|-------|-------|------|
+| rihal-sadiq | claude-3-5-opus-20241022 | Strategic priority, decision framing |
+| rihal-waleed | claude-3-5-opus-20241022 | Architecture, technical feasibility |
+| rihal-planner | claude-3-5-opus-20241022 | Plan generation and task breakdown |
+| rihal-sprint-checker | claude-3-5-opus-20241022 | Plan verification and quality gates |
+| rihal-fatima | claude-3-5-sonnet-20241022 | QA strategy and release readiness |
+| rihal-executor | claude-3-5-sonnet-20241022 | Task execution and implementation |
+| rihal-verifier | claude-3-5-sonnet-20241022 | Post-execution verification |
+| All others | claude-3-5-haiku-20241022 | Utility agents, research, synthesis |
+
+### balanced
+
+Standard configuration. Uses Claude 3.5 Sonnet for all agents, balancing speed and capability.
+
+| Agent | Model |
+|-------|-------|
+| All agents | claude-3-5-sonnet-20241022 |
+
+### budget
+
+Cost-optimized. Uses Claude 3.5 Haiku for all agents, prioritizing latency and cost over maximum reasoning capability.
+
+| Agent | Model |
+|-------|-------|
+| All agents | claude-3-5-haiku-20241022 |
+
+### inherit
+
+No model override. Agents use the model specified by the parent session context (e.g., Claude Code's current model selection). Useful for keeping subagent model aligned with the user's environment.
+
+| Agent | Model |
+|-------|-------|
+| All agents | (inherited from parent) |
+
+## Configuration
+
+The active profile is set in `.rihal/config.yaml` under the key `model_profile`:
+
+```yaml
+user_name: User
+project_name: my-project
+communication_language: English
+mode: guided
+model_profile: balanced
+```
+
+If `model_profile` is absent or unrecognized, the default is `balanced`.
+
+## Usage
+
+To query the model for an agent under the current profile:
+
+```bash
+node .rihal/bin/rihal-tools.cjs resolve-model <agent-id>
+```
+
+Example:
+
+```bash
+$ node .rihal/bin/rihal-tools.cjs resolve-model rihal-sadiq
+claude-3-5-opus-20241022
+
+$ node .rihal/bin/rihal-tools.cjs resolve-model rihal-executor
+claude-3-5-sonnet-20241022
+```
+
+When spawning a subagent in a workflow, use the resolved model:
+
+```bash
+MODEL=$(node .rihal/bin/rihal-tools.cjs resolve-model <agent-id>)
+# Pass $MODEL to the Task spawn instruction
+```
+
+## Design rationale
+
+- **quality** is recommended for council (advisor agents) and plan/execute gatekeepers where reasoning depth matters.
+- **balanced** is the default and suitable for most projects.
+- **budget** is for rapid iteration cycles or cost-constrained environments where latency is acceptable.
+- **inherit** allows parent context (Claude Code, IDE harness) to fully control model selection, useful when testing or when the user has explicit model preferences in their session.

package/rihal/references/no-unauthorized-git-ops.md

@@ -0,0 +1,73 @@
+# No Unauthorized Git Operations
+
+Shared reference `@`-included by every workflow and agent. This is a hard safety contract, not a suggestion.
+
+## The rule
+
+**Never perform these git operations without explicit, current, per-invocation user consent:**
+
+- `git push` / `git push --force` / `git push --force-with-lease`
+- `git worktree add` / `git worktree remove`
+- `git branch <new-name>` (creating a new branch)
+- `git checkout -b <new-name>` (creating and switching to a new branch)
+- `git checkout --` / `git restore` / `git reset --hard` / `git clean -f` (destructive)
+- `git rebase` / `git merge` (touching history)
+- `git stash drop` / `git stash clear`
+- `git tag` (creating tags)
+- `git config --global` / `git config --system`
+
+**Never pass `isolation="worktree"` to the Task tool without explicit user consent.** Worktree isolation silently creates a new git worktree under `.worktrees/` — that is a write operation the user may not want. If you believe isolation is genuinely needed, ask first via AskUserQuestion with explicit trade-offs.
+
+## Why
+
+These operations have one or more of:
+
+- **Destructive** — can lose work (reset --hard, checkout --, clean -f)
+- **Visible beyond local** — publishes state to remotes or affects other collaborators (push)
+- **Creates state that requires cleanup** — worktrees, branches, tags
+- **Hard to reverse** — rebase, merge, force-push
+
+The user's trust surface is "I asked for X, I got X — nothing more." Silently adding branch/worktree/push operations violates that contract. One unauthorized worktree is irritating. One unauthorized force-push is lost work.
+
+## What IS allowed without explicit consent
+
+- `git status`, `git log`, `git diff`, `git show`, `git branch --show-current` (read-only)
+- `git add <specific-files>` (stage specific files you're about to commit — never `-A` or `.`)
+- `git commit -m "..."` (commit staged changes — subject + conventional format)
+- `git stash push` (stash uncommitted changes before a read operation that might be destabilized)
+- `git worktree list` (read-only inspection)
+
+## Confirmation pattern
+
+When a workflow genuinely needs a gated operation, use AskUserQuestion with:
+
+1. **What the operation will do** (in plain English)
+2. **Why it's needed for this task** (not abstract — specific)
+3. **What the reversal path is** (how the user undoes it if they regret)
+4. **Default = no** (the safe option must be the default)
+
+Example:
+
+```
+Spawn the debug agent with git worktree isolation?
+
+  • Creates a new worktree at .worktrees/debug-ttft-1959/
+  • Agent edits stay isolated until you review + merge
+  • Undo: git worktree remove .worktrees/debug-ttft-1959
+
+[yes / no — default no]
+```
+
+## Agent enforcement
+
+Every Rihal agent that can execute shell commands (rihal-executor, rihal-debugger, rihal-planner, rihal-tech-writer, etc.) must:
+
+1. Reject any prompt asking them to perform a banned operation without a prior user-confirmed authorization in their input
+2. Surface a warning if a parent workflow or user prompt tries to include a banned flag
+3. Prefer read-only alternatives when the task can be accomplished without state mutation
+
+## Escalation
+
+If an operation seems necessary but falls in the banned list, STOP and ask. The cost of asking is 5 seconds. The cost of an unauthorized worktree, branch, or push can be lost work, confused collaborators, or broken trust.
+
+The user typed "do X" — do exactly X. Never more.