@hanzlaa/rcode 2.1.0

package/rihal/references/execution-protocol.md

@@ -0,0 +1,155 @@
+# Rihal Execution Protocol
+
+Shared reference `@`-included by `execute.md` workflow and `rihal-executor` subagent.
+
+**Also see:** @.rihal/references/karpathy-guidelines.md for behavioral principles that apply during execution.
+
+## SPRINT.md schema
+
+Every plan file must have this frontmatter and structure:
+
+```markdown
+---
+id: "01.02"                 # full hierarchical ID
+phase: "01"                 # phase ID (2-digit, zero-padded)
+plan: "02"                  # plan ID within phase (2-digit, zero-padded)
+milestone: "M1"             # optional, if assigned to milestone
+type: auto | tdd
+depends_on: []              # list of other plan IDs like ["01.01"]
+wave: 1                     # auto-derived from depends_on
+---
+
+## Objective
+One sentence describing what this plan achieves.
+
+## Success criteria
+- [ ] Specific, verifiable outcome
+
+## Tasks
+
+### Task 01.02.01 — name
+type: auto
+**Steps:**
+1. ...
+**Done when:** specific, observable condition
+**Commit:** feat(scope): description
+
+### Task 01.02.02 — name
+type: checkpoint:human-verify
+**Verify:** what the human must confirm before continuing
+```
+
+**Hierarchical ID format:**
+- Milestone: `M{N}` (e.g., M1, M2)
+- Phase: `{NN}` 2-digit, zero-padded (e.g., 01, 02, 72)
+- Decimal phase (inserted): `{NN.M}` (e.g., 02.1, 72.3)
+- Plan within phase: `{NN.MM}` (e.g., 01.02)
+- Task within plan: `{NN.MM.TT}` (e.g., 01.02.03)
+
+**Task types:**
+- `auto` — executor runs without pausing
+- `checkpoint:human-verify` — executor stops, prints return format, waits for human
+- `checkpoint:decision` — executor stopped itself due to a deviation requiring architectural choice
+
+## Deviation rules
+
+When the executor encounters something unexpected:
+
+1. **Bug in the task itself** → fix it, continue, note in SUMMARY
+2. **Missing critical dependency** (file, package, env var) → add it, continue, note in SUMMARY
+3. **Blocking issue not in the plan** → fix the blocker, continue, note in SUMMARY
+4. **Architectural change required** (the plan's approach is fundamentally wrong) → STOP, return `checkpoint:decision` with the options
+
+Rules 1-3 are auto. Rule 4 always pauses for human decision.
+
+## Analysis paralysis guard
+
+If the executor has made 5+ Read/Grep/Glob calls without a Write, Edit, or Bash that changes state — STOP. Write what you have so far, commit, and continue from the next task. Do not read more before acting.
+
+## Checkpoint return format
+
+When an executor hits a checkpoint, it returns exactly this block and stops:
+
+```
+---CHECKPOINT REACHED---
+Plan: {plan file path}
+Task: {task name}
+Type: {human-verify | decision}
+
+{For human-verify:}
+Please verify: {what to check}
+URL/path: {where to look}
+Resume with: /rihal:execute {plan} --continue
+
+{For decision:}
+Problem: {what the plan assumed that isn't true}
+Option A: {approach} — {trade-off}
+Option B: {approach} — {trade-off}
+Recommendation: {which one and why}
+Resume with: /rihal:execute {plan} --continue --option=A
+---
+```
+
+## Commit protocol
+
+After every completed `auto` task:
+
+1. `git status --short` — confirm only expected files changed
+2. Stage specific files: `git add path/to/file` — never `git add -A`
+3. Commit: `type(scope): description` (Conventional Commits)
+4. Record the SHA in the SUMMARY
+
+**Never add:** `Co-Authored-By: Claude`, `Generated with Claude Code`, or any AI attribution.
+**Never use:** `--no-verify`.
+**Never run:** `git push` — pushing requires explicit human authorization outside the executor's scope. Commits only.
+
+## SUMMARY format
+
+Written to `{plan-dir}/{plan-name}-SUMMARY.md` after completion:
+
+```markdown
+# Plan Summary — {plan name}
+
+**Status:** complete | partial
+**Duration:** {start} → {end}
+**Commits:** {count}
+
+## Tasks
+- [x] Task 1 — {commit SHA}
+- [x] Task 2 — {commit SHA}
+- [ ] Task 3 — SKIPPED: {reason}
+
+## Deviations
+- {deviation description} → {rule applied} → {resolution}
+
+## Known Stubs
+(Optional section if stubs exist)
+- [file:line] stub pattern → reason → resolved in [plan name]
+
+## Self-Check
+**Status:** PASSED | FAILED
+- Task count: {count} completed vs {plan count} in plan
+- Commits: {count} recorded
+- Criteria: {verified count}/{total} verified
+```
+
+### Stub Detection
+
+Before writing SUMMARY.md, executor scans all modified files for stub patterns:
+- `TODO` / `FIXME` / `XXX` comments
+- `throw new Error('not implemented')` or `throw new Error('TODO')`
+- Placeholder values: `'YOUR_API_KEY'`, `'REPLACE_ME'`
+- `console.log` in non-test files
+- Empty function bodies: `return null` / `return undefined`
+
+If stubs exist, add `## Known Stubs` section listing each with file:line and resolution plan. Do NOT mark complete if stubs block success criteria.
+
+### Self-Check Loop
+
+After writing SUMMARY.md:
+1. **Count tasks:** SUMMARY task count must match plan task count
+2. **Count commits:** Commits listed must exist in git log
+3. **Verify criteria:** Each success criterion has evidence (diff line, test, or SUMMARY entry)
+4. **Report result:** Append `## Self-Check: PASSED/FAILED` with deltas if failed
+
+Stop before state updates if self-check fails.

package/rihal/references/gate-prompts.md

@@ -0,0 +1,212 @@
+# Gate Prompts
+
+Gate prompts enforce safety, reversibility, and clarity at critical decision points. They follow three canonical patterns: **Safety gates** (before risky actions), **Decision gates** (before irreversible commitments), and **Escalation gates** (when uncertainty exceeds tolerance).
+
+All gate prompts reference `.rihal/references/no-unauthorized-git-ops.md` — never allow unauthorized commits, pushes, or force operations.
+
+---
+
+## Template: Safety Gate
+
+Use before executing **irreversible or high-impact actions** (deletes, force-pushes, breaking changes).
+
+**Structure:**
+
+```markdown
+## Safety Gate: [Action Name]
+
+**You are about to:** [Specific action in plain English]
+
+**Impact:** [What user will see/lose if they proceed]
+
+**Approval Required**
+
+Confirm you want to:
+- [ ] [Specific irreversible consequence 1]
+- [ ] [Specific irreversible consequence 2]
+
+Type `yes, proceed` to confirm or `abort` to stop.
+```
+
+**Example: Delete Branch**
+
+```markdown
+## Safety Gate: Delete Feature Branch
+
+You are about to **permanently delete** the branch `feature/payment-redesign` and all uncommitted changes on that branch will be lost.
+
+**Consequences:**
+- 3 unpushed commits (1234abc–4567def) will be discarded
+- If you pushed this branch to origin, the remote copy will remain (must delete separately)
+- This cannot be undone
+
+Confirm:
+- [ ] I have reviewed all unpushed commits (above)
+- [ ] I understand this is permanent
+- [ ] I accept responsibility for any lost work
+
+Type `yes, proceed` to delete or `abort` to stop.
+```
+
+---
+
+## Template: Decision Gate
+
+Use before **high-stakes architectural or functional commitments** (framework choice, auth model, data migration strategy).
+
+**Structure:**
+
+```markdown
+## Decision Gate: [Decision Name]
+
+**You have chosen:** [Option selected]
+
+**Rationale you provided:** [Summary of reasoning]
+
+**We will commit to:**
+- [ ] [Consequence 1 — what must now be true]
+- [ ] [Consequence 2 — what becomes harder/impossible]
+- [ ] [Consequence 3 — reversibility or cost of changing later]
+
+**Alternative considered:**
+- [Alt 1]: Why not chosen? [Your reasoning]
+- [Alt 2]: Why not chosen? [Your reasoning]
+
+Confirm this is the right choice, or select a different option.
+```
+
+**Example: Framework Choice**
+
+```markdown
+## Decision Gate: Choose Backend Framework
+
+**You have chosen:** Express.js
+
+**Rationale:** "Lightweight, large ecosystem, familiar to team, handles routing + middleware out of the box"
+
+**We will commit to:**
+- [ ] Express patterns (routes, middleware, error handling) will structure all backend code
+- [ ] Team becomes responsible for architectural decisions Express doesn't provide (logging, caching, auth flow)
+- [ ] Switching later requires rewriting routing and middleware (medium cost, ~2-3 days)
+
+**Alternatives considered:**
+- Fastify: "Too low-level for our timeline, less middleware ecosystem"
+- NestJS: "Good, but opinionated — less flexibility for experiments"
+
+Confirm this is right, or choose differently.
+```
+
+---
+
+## Template: Irreversible-Action Gate
+
+Use before **operations with no undo button** (force-push, delete production data, merge to main without PR).
+
+**Structure:**
+
+```markdown
+## Gate: Irreversible Action
+
+**Action:** [What you're about to do]
+
+**Undo Difficulty:** [IMPOSSIBLE | HARD | MEDIUM | EASY]
+
+**Recovery Plan** (if action fails):
+[Specific steps to recover, or "Cannot be undone — be certain"]
+
+---
+
+**Type your confirmation:**
+- For IMPOSSIBLE/HARD: Type the exact phrase `I understand [consequence], proceed`
+- For MEDIUM: Type `yes, proceed`
+- For EASY: Proceed normally (standard confirmation)
+```
+
+**Example: Force-Push to Main**
+
+```markdown
+## Gate: Force-Push to Main
+
+**Action:** `git push --force-with-lease origin main`
+
+**Undo Difficulty:** IMPOSSIBLE (force-push rewrites history; commits are lost unless recovered via reflog within 30 days)
+
+**Recovery Plan:**
+If commits are lost, recovery requires:
+1. Accessing git reflog (only possible on local machine where push originated)
+2. Resetting to the lost commit
+3. Re-pushing to main (requires another force-push authorization)
+
+This is high-risk and should not be attempted in production workflows.
+
+---
+
+**Type your confirmation:**
+`I understand this cannot be easily undone and may cause data loss, proceed`
+```
+
+---
+
+## Approval / Revise / Abort Pattern
+
+For gates that offer a **choice** (not just yes/no):
+
+```markdown
+## Confirmation Gate: [Decision]
+
+[Summarize the planned action and its consequences]
+
+### Options
+
+1. **Approve** — Proceed with the plan as described
+2. **Revise** — Go back and modify [aspect 1], [aspect 2]
+3. **Abort** — Stop here; don't proceed
+
+Enter: `approve` | `revise <aspect>` | `abort`
+```
+
+**Example: Code Review Findings**
+
+```markdown
+## Confirmation Gate: Fix Code Review Issues
+
+Found 3 issues:
+1. Missing error handling in `/api/users.js`
+2. Hardcoded API key in `.env.local` (security risk)
+3. Type annotation missing on `fetchUser()` return type
+
+All are medium severity. Should we fix before merging?
+
+### Options
+
+1. **Approve** — Merge as-is (I accept these risks)
+2. **Revise** — Fix issues 1 and 2, skip 3
+3. **Abort** — Stop; I want to rethink this
+
+Enter: `approve` | `revise 1,2` | `abort`
+```
+
+---
+
+## Gate Placement Rules
+
+| Gate Type | Placement | User Decision? |
+|---|---|---|
+| Safety | Before destructive operation | Required (explicit yes) |
+| Decision | After exploring options, before implementation | Required (choose path) |
+| Escalation | After investigation, before proceeding with uncertainty | Required (accept or retry) |
+
+---
+
+## No Unauthorized Git Operations
+
+Reference `.rihal/references/no-unauthorized-git-ops.md` before any gate that involves:
+- `git push` (any flag)
+- `git reset --hard`
+- `git rebase`
+- `git checkout` to discard changes
+- `git clean -f`
+
+**Rule:** User types the command themselves, or explicitly authorizes it in chat (outside of gate prompts).
+
+Gates may **describe** an intended git operation, but the user must actively choose to proceed with full understanding of consequences.

package/rihal/references/gates.md

@@ -0,0 +1,127 @@
+# Gates Reference
+
+Defines 4 gate types used in rihal workflows to control execution flow, validate decisions, and escalate blockers.
+
+## Gate Types
+
+### 1. Pre-Flight (Validation Before Action)
+
+**Purpose:** Block invalid operations before they start.
+
+**Behavior:**
+- Check preconditions (file exists, user authorized, config valid)
+- Either block execution or warn with recovery suggestion
+- Non-blocking warnings permit continuation; blocking gates halt
+
+**Recovery:** Suggest specific fix and retry path
+
+**Example:** Phase execution gate
+```
+Gate: Check phase.md exists and has required sections
+Block: "Phase {N} has no SPRINT.md. Create with /rihal:help"
+Warn: "Phase overdue by {days}. Review roadmap?"
+```
+
+---
+
+### 2. Revision (Iteration Loop)
+
+**Purpose:** Catch defects within a task, permit retries.
+
+**Behavior:**
+- Max retries: 3 (configurable per workflow)
+- Detect stalls: if N consecutive attempts fail identically, escalate
+- Log each retry attempt with timestamp and error
+
+**Recovery:** After 3 failures, escalate to Escalation gate
+
+**Example:** Code compilation gate
+```
+Revision Loop: Test build
+Retry 1: "Build failed: missing import. Added import, retrying..."
+Retry 2: "Build failed: type error. Fixed type, retrying..."
+Retry 3: "Build succeeded."
+On 4th failure: escalate to user
+```
+
+---
+
+### 3. Escalation (Decision Needed)
+
+**Purpose:** Pause execution and ask user for direction.
+
+**Behavior:**
+- Preserve current state (save SPRINT.md, commit progress)
+- Pause execution with AskUserQuestion
+- Wait for user decision (proceed, abort, or retry with modified approach)
+- Log decision timestamp and rationale
+
+**Recovery:** User confirms direction; resume or return to Revision
+
+**Example:** Architecture decision gate
+```
+Gate: Design choice between Pattern A and Pattern B
+State: Saved current work, phase paused
+Ask: "Pattern A is faster but less flexible. Pattern B is extensible but slower.
+       Which should we implement? (A/B/defer)"
+```
+
+---
+
+### 4. Abort (Unrecoverable)
+
+**Purpose:** Exit gracefully when task cannot proceed.
+
+**Behavior:**
+- Preserve all state (don't delete files, commit progress, log cause)
+- Exit cleanly without recovery attempt
+- Suggest manual recovery path
+
+**Recovery:** Manual repair via `/rihal:health` or `/rihal:forensics`
+
+**Example:** Corrupted state gate
+```
+Gate: Validate state.json integrity
+Fail: "state.json corrupted (invalid JSON at line 42).
+       Aborting to prevent further damage.
+       Recovery: /rihal:health --repair"
+```
+
+---
+
+## State Preservation Rules
+
+**Revision gates:** Commit work-in-progress at each retry
+```bash
+git add -A
+git commit -m "wip: revision loop attempt {N} of {max}"
+```
+
+**Escalation gates:** Tag the commit with the question
+```bash
+git add -A
+git commit -m "session: escalation gate at {phase} — awaiting user input"
+```
+
+**Abort gates:** Preserve full state, no cleanup
+```bash
+git add -A
+git commit -m "session: abort gate — state preserved for manual repair"
+# Do NOT delete files, do NOT reset --hard
+```
+
+---
+
+## Iteration Cap Rule
+
+Revision gates must fail fast:
+- **Cap:** 3 retries maximum per gate
+- **Stall detection:** If retries 2 and 3 fail identically, escalate immediately
+- **Rationale:** Prevent infinite loops; protect token budget
+
+Example stall detection:
+```
+Retry 2 error: "Compilation failed: missing MockDB"
+Retry 3 error: "Compilation failed: missing MockDB"
+→ Detect stall (identical error) → Escalate to user
+```

package/rihal/references/git-integration.md

@@ -0,0 +1,159 @@
+# Git Integration Reference
+
+Defines 3 branching strategies for rihal workflows and when to use each.
+
+---
+
+## Configuration
+
+Add to `config.yaml`:
+
+```yaml
+git:
+  branching_strategy: "feature-branch"  # options: none, feature-branch, worktree-isolation
+```
+
+---
+
+## 3 Branching Strategies
+
+### 1. None (Commit to Current Branch)
+
+**Complexity:** ⭐ (minimal)  
+**Cleanliness:** ⭐ (messy history)  
+**Parallel Safety:** ⭐ (unsafe)
+
+**How it works:**
+- All commits go to current branch (typically main or v2-prototype)
+- No branch creation; no cleanup
+- Linear history but mixed concerns (planning, code, docs)
+
+**When to use:**
+- Solo development, local experimentation
+- Fast prototyping where history doesn't matter
+- Quick fixes, immediate merge to main
+
+**Trade-offs:**
+- ✅ Zero overhead
+- ❌ Pollutes main with wip/planning commits
+- ❌ Can't revert feature without reverting unrelated work
+- ❌ CI might fail on intermediate commits
+
+---
+
+### 2. Feature-Branch (Auto-Create Per Phase)
+
+**Complexity:** ⭐⭐⭐ (moderate)  
+**Cleanliness:** ⭐⭐⭐⭐ (clean history)  
+**Parallel Safety:** ⭐⭐ (limited)
+
+**How it works:**
+- Workflow auto-creates branch per phase: `phase/1-setup`, `phase/2-auth`, etc.
+- All commits in phase go to phase branch
+- PR to main when phase complete
+- Delete branch after merge
+
+**When to use:**
+- Standard team workflow, code review required
+- Multi-phase projects with clean phase boundaries
+- Need clear history of which commits belong to which phase
+- CI/CD integration with branch-based triggers
+
+**Trade-offs:**
+- ✅ Clean history, easy PR review
+- ✅ Can revert entire phase with one revert commit
+- ⚠️ Branch management overhead (create, delete, rebase)
+- ❌ Can't work on multiple phases in parallel
+
+---
+
+### 3. Worktree-Isolation (Each Phase in Worktree)
+
+**Complexity:** ⭐⭐⭐⭐⭐ (high)  
+**Cleanliness:** ⭐⭐⭐⭐⭐ (pristine)  
+**Parallel Safety:** ⭐⭐⭐⭐⭐ (safe)
+
+**How it works:**
+- Each phase runs in isolated `git worktree`
+- Phase branch created, checked out in worktree
+- Work in isolation; no interference with main or other phases
+- Each worktree has independent working directory and index
+- Switch between phases by exiting/entering worktrees
+
+**When to use:**
+- Parallel multi-phase execution
+- Complex features needing isolated testing
+- Multiple team members working different phases simultaneously
+- High-risk changes requiring clean rollback
+
+**Trade-offs:**
+- ✅ True isolation, zero branch interference
+- ✅ Parallel work on multiple phases
+- ✅ Easy rollback (delete worktree, delete branch)
+- ❌ Disk overhead (separate directory per phase)
+- ❌ More cognitive load (track multiple worktrees)
+- ⚠️ Requires git worktree knowledge
+
+---
+
+## Strategy Decision Tree
+
+```
+1. Solo development, quick fix?
+   → Strategy: none
+
+2. Team, need clean history, sequential phases?
+   → Strategy: feature-branch
+
+3. Parallel phases, isolated testing, or high risk?
+   → Strategy: worktree-isolation
+```
+
+---
+
+## Implementation Details
+
+### None Strategy
+```bash
+# Just commit to current branch
+git add <files>
+git commit -m "feat(...): description"
+```
+
+### Feature-Branch Strategy
+```bash
+# Auto-created by workflow
+git checkout -b phase/1-setup
+git add <files>
+git commit -m "feat(...): description"
+# On completion: create PR, merge, delete branch
+```
+
+### Worktree-Isolation Strategy
+```bash
+# Workflow commands
+/rihal:do --worktree phase/2-auth
+# Internally:
+git worktree add .claude/worktrees/phase-2-auth phase/2-auth
+cd .claude/worktrees/phase-2-auth
+# Work here, commit, test
+# Exit: cd ../.. ; git worktree remove .claude/worktrees/phase-2-auth
+```
+
+---
+
+## Config Example
+
+```yaml
+# Single-phase project: no branching needed
+git:
+  branching_strategy: "none"
+
+# Multi-phase, team project: feature branches
+git:
+  branching_strategy: "feature-branch"
+
+# High-risk, parallel work: worktrees
+git:
+  branching_strategy: "worktree-isolation"
+```