@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/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 `.rcode/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 `.rcode/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/rcode/references/gates.md

@@ -0,0 +1,127 @@
+# Gates Reference
+
+Defines 4 gate types used in rcode 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 /rcode-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 `/rcode-health` or `/rcode-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: /rcode-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/rcode/references/git-integration.md

@@ -0,0 +1,159 @@
+# Git Integration Reference
+
+Defines 3 branching strategies for rcode 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
+/rcode-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/rcode/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 rcode 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 rcode 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