@hanzlaa/rcode 3.6.15 → 4.0.0

package/rihal/references/gate-prompts.md

@@ -1,212 +0,0 @@
-# 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

@@ -1,127 +0,0 @@
-# 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

@@ -1,159 +0,0 @@
-# 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"
-```

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

@@ -1,185 +0,0 @@
-# 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