@hanzlaa/rcode 2.1.0

package/rihal/agents/rules/executor/execution-flow.md

@@ -0,0 +1,116 @@
+# Rihal Executor: Execution Flow Details
+
+## Full Step-by-Step Execution
+
+### Step 1: Load Project State
+Extract project state using the initialization tool:
+```bash
+INIT=$(node ".rihal/bin/rihal-tools.cjs" init execute "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+From the response, extract:
+- `executor_model`: Model/agent name to use for execution
+- `commit_docs`: Documentation style for commits
+- `sub_repos`: Any sub-repositories to manage
+- `phase_dir`: Phase directory path
+- `plans`: Available plans for execution
+- `incomplete_plans`: Plans that need continuation
+
+Read `.planning/STATE.md` to determine:
+- Current position in plan execution
+- Any previous decisions made
+- Known blockers or issues
+
+### Step 2: Load Plan Metadata
+Parse the SPRINT.md frontmatter to extract:
+- `phase`: Phase identifier
+- `plan`: Plan number
+- `type`: Execution type (execute, tdd)
+- `autonomous`: Whether plan has checkpoints
+- `wave`: Execution wave number
+- `depends_on`: Plan dependencies
+- `requirements`: Requirement IDs being addressed
+
+If CONTEXT.md is referenced in the plan, read it to understand the broader vision and any special instructions.
+
+### Step 3: Determine Execution Pattern
+
+**Pattern A: No Checkpoints**
+- Tasks are all `type="auto"`
+- Execute all tasks sequentially
+- Create SUMMARY.md at end
+- Update STATE.md with completion
+- No human pauses
+
+**Pattern B: Has Checkpoints**
+- One or more tasks are `type="checkpoint:*"`
+- Execute until first checkpoint
+- STOP and return structured checkpoint message
+- Wait for user response
+- Resume from checkpoint (continuation handling)
+
+**Pattern C: Continuation**
+- Prompt contains `<completed_tasks>` with task hashes
+- Verify those commits exist in git history
+- DO NOT redo completed tasks
+- Start from next incomplete task
+- Handle based on checkpoint type (verify, decision, action)
+
+### Step 4: Execute Tasks
+For each task in sequence:
+
+1. **If type="auto":**
+   - Read task `<files>`, `<action>`, `<verify>`, `<done>`
+   - Implement exactly as specified
+   - If TDD mode: Follow RED→GREEN→REFACTOR
+   - Commit individually with task name
+   - Record commit hash
+   - Move to next task
+
+2. **If type="checkpoint:*":**
+   - Complete all tasks up to this one
+   - Prepare checkpoint response
+   - STOP execution
+   - Return checkpoint message
+   - Wait for user input
+
+3. **After each task completion:**
+   - Verify criteria met
+   - Check git status clean
+   - Record state for recovery
+   - **Append execution log:** Append to `.planning/{plan-dir}/EXECUTION-LOG.md`:
+     ```
+     {ISO timestamp} | {task-id} | completed | {commit-sha}
+     ```
+     This enables resume-work to see progress if executor crashes
+   - Continue to next
+
+### Step 5: Summary Creation (Pattern A only)
+After all auto tasks complete:
+1. Create SUMMARY.md at `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+2. Use @.rihal/templates/summary.md as template
+3. List completed tasks with commit hashes
+4. Document any deviations from plan
+5. Record metrics (task count, file count, duration)
+6. Self-check: verify counts match
+7. **After every 3 tasks completed**, write a checkpoint:
+   - Create `.planning/{plan-dir}/SUMMARY-PARTIAL.md` with tasks 1-3, 4-6, etc.
+   - This allows safe recovery if executor crashes mid-plan
+   - Final SUMMARY.md integrates all partials
+
+### Step 6: State Updates
+```bash
+node ".rihal/bin/rihal-tools.cjs" state advance-plan
+node ".rihal/bin/rihal-tools.cjs" state update-progress
+node ".rihal/bin/rihal-tools.cjs" state record-metric --phase "$PHASE" --plan "$PLAN" --duration "$DURATION" --tasks "$COUNT" --files "$FILES"
+node ".rihal/bin/rihal-tools.cjs" roadmap update-plan-progress "$PHASE_NUMBER"
+node ".rihal/bin/rihal-tools.cjs" requirements mark-complete $REQ_IDS
+```
+
+Extract requirement IDs from SPRINT.md frontmatter `requirements:` field.
+
+### Step 7: Final Commit
+```bash
+node ".rihal/bin/rihal-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+```

package/rihal/agents/rules/executor/self-check.md

@@ -0,0 +1,241 @@
+# Rihal Executor: Self-Check Verification
+
+## Pre-SUMMARY Self-Check
+
+Before finalizing SUMMARY.md, verify plan execution was complete and correct.
+
+---
+
+## Verification Checklist
+
+### Task Completion
+- [ ] All `type="auto"` tasks executed
+- [ ] No `type="checkpoint:*"` tasks remain (or documented in prompt)
+- [ ] Task count in SUMMARY matches plan's `<tasks>` count
+- [ ] Each completed task has git commit hash
+
+### Git Commits
+- [ ] One commit per task (or multiple for TDD)
+- [ ] Commit messages follow Conventional Commits format
+- [ ] No commits contain `git add .` or `git add -A`
+- [ ] Each commit references specific task
+- [ ] Final commit includes SUMMARY.md
+
+### Deviations Documented
+- [ ] All Rule 1 fixes (bugs) listed in deviations
+- [ ] All Rule 2 additions (critical features) listed
+- [ ] All Rule 3 fixes (blockers) listed
+- [ ] No unlisted auto-fixes in commit messages
+- [ ] Deviations list is complete or empty
+
+### Code Quality
+- [ ] No TODO/FIXME/XXX remaining (or documented as stubs)
+- [ ] No console.log() in non-test code
+- [ ] No hardcoded test values
+- [ ] All imports resolve (no broken paths)
+- [ ] All tests passing (if tests were modified)
+
+### Success Criteria
+- [ ] Original plan `<success_criteria>` met
+- [ ] All `<verify>` checks pass
+- [ ] All `<done>` acceptance criteria satisfied
+
+---
+
+## Verification Commands
+
+Run these before finalizing:
+
+### 1. Verify All Tasks Completed
+```bash
+# Count tasks in plan
+PLAN_TASKS=$(grep -c "^<task" .planning/phases/XX-name/PLAN.md)
+echo "Plan declares: $PLAN_TASKS tasks"
+
+# Count commits in SUMMARY
+SUMMARY_TASKS=$(grep -c "^| [0-9]" .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md)
+echo "SUMMARY lists: $SUMMARY_TASKS tasks"
+
+# Should match
+if [ "$PLAN_TASKS" = "$SUMMARY_TASKS" ]; then
+  echo "✓ Task counts match"
+else
+  echo "✗ Task count mismatch!"
+fi
+```
+
+### 2. Verify Git Status
+```bash
+# Should be clean (no uncommitted changes)
+git status
+# Output should be: "On branch ... nothing to commit"
+
+# If dirty, list changes:
+git status --short
+```
+
+### 3. Verify Commits Exist
+```bash
+# List commits from this plan
+git log --oneline | head -20
+
+# Count commits (should match task count)
+COMMIT_COUNT=$(git log --oneline | wc -l)
+echo "Commits in current branch: $COMMIT_COUNT"
+```
+
+### 4. Verify No Stubs
+```bash
+# Search for stubs
+grep -rn "TODO\|FIXME\|XXX" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
+
+# Search for console.log
+grep -rn "console\." src/ --include="*.ts" --include="*.tsx" | grep -v "\.test\." | grep -v "\.spec\." | head -10
+
+# If any found, decide: document in SUMMARY or implement
+```
+
+### 5. Run Plan's Verify Commands
+```bash
+# From plan's <verify> section, run specified commands
+# Example:
+npm test -- --filter=auth
+npm run build
+curl -X POST http://localhost:3000/api/auth/login
+```
+
+### 6. Verify Success Criteria
+From plan `<success_criteria>`, manually verify:
+```
+Example success criteria:
+- "All tasks executed or paused at checkpoint" → ✓ (all auto tasks done)
+- "Each task committed individually" → ✓ (git log confirms)
+- "Deviations documented" → ✓ (SUMMARY deviations section populated)
+- "Auth gates handled" → ✓ (no 401 errors in final test)
+```
+
+---
+
+## Self-Check Failure Scenarios
+
+### Scenario 1: Missing Tasks
+**Problem:** SUMMARY shows 2 tasks but plan has 3.
+
+**Debug:**
+1. Re-read plan `<tasks>` section
+2. Check git log: which task is missing commits?
+3. Execute missing task
+4. Update SUMMARY
+5. Create final commit with updated SUMMARY
+
+### Scenario 2: Unverified Tests
+**Problem:** Tests were modified but you didn't run them.
+
+**Fix:**
+```bash
+npm test -- --filter=task_name
+# Verify all pass
+
+# If failing:
+# - Fix code
+# - Re-run test
+# - Commit
+# - Update SUMMARY
+```
+
+### Scenario 3: Uncommitted Changes
+**Problem:** `git status` shows modified files.
+
+**Fix:**
+```bash
+# Option 1: These belong to this plan
+git add src/file.ts
+git commit -m "fix(scope): fix issue found during verification"
+
+# Option 2: These are unrelated changes
+# Stash them and commit later
+git stash
+# Complete plan execution and SUMMARY
+# Later: git stash pop
+```
+
+### Scenario 4: Leftover Stubs
+**Problem:** Search finds `// TODO: add validation` in your code.
+
+**Fix:**
+- If critical: Implement it, commit, re-run tests
+- If non-critical: Document in SUMMARY.md Known Stubs section
+
+### Scenario 5: Success Criteria Not Met
+**Problem:** Plan says "endpoint returns 200" but it returns 500.
+
+**Fix:**
+1. Debug the issue
+2. Apply appropriate Deviation Rule (likely Rule 1 or 2)
+3. Fix the code
+4. Re-run success criteria verification
+5. Create fix commit
+6. Update SUMMARY deviations section
+
+---
+
+## Red Flags (Stop and Review)
+
+**STOP before finalizing SUMMARY if:**
+
+- [ ] Tests are failing
+- [ ] `git status` shows uncommitted changes
+- [ ] Success criteria verification fails
+- [ ] More stubs exist than documented
+- [ ] Commit count doesn't match task count
+- [ ] Task names in SUMMARY don't match plan
+- [ ] Deviations list is incomplete
+- [ ] You're unsure whether code works
+
+**If any flag raised:**
+1. Don't create SUMMARY yet
+2. Go back and fix the issue
+3. Re-run verification
+4. Only after ALL checks pass: create SUMMARY
+
+---
+
+## SUMMARY Self-Check Block
+
+In the SUMMARY.md, before submitting, include:
+
+```markdown
+## Self-Check
+
+**Status:** [PASSED | FAILED]
+
+Verification performed:
+- [ ] Task count matches (plan: X, SUMMARY: X)
+- [ ] All commits present in git log
+- [ ] No uncommitted changes
+- [ ] No failing tests
+- [ ] Success criteria verified
+- [ ] Stubs documented or resolved
+- [ ] Deviations documented
+
+**Issues encountered and resolved:**
+[List any red flags caught and how you fixed them]
+
+**Ready for state update:** [YES | NO]
+```
+
+If any checkbox is unchecked, status is FAILED. Fix issues before moving forward.
+
+---
+
+## Post-SUMMARY Actions
+
+After SUMMARY.md is finalized and verified:
+
+1. Create final commit
+2. Update STATE.md
+3. Record metrics
+4. Update ROADMAP
+5. Mark requirements complete
+
+Only proceed to next plan after SUMMARY is verified and all state updates complete.

package/rihal/agents/rules/executor/stub-detection.md

@@ -0,0 +1,267 @@
+# Rihal Executor: Stub Detection
+
+## What Are Stubs?
+
+Stubs are placeholders, incomplete code, or temporary implementations that remain in the codebase.
+
+Examples:
+- `TODO` comments
+- `FIXME` markers
+- `XXX` comments
+- `console.log()` in non-test files
+- Empty function bodies
+- Hardcoded test values left in production
+- Comments like "implement later"
+
+---
+
+## Stub Detection Strategy
+
+### Automated Search
+
+Before creating SUMMARY.md, scan for stubs:
+
+```bash
+# Find TODO/FIXME/XXX
+grep -rn "TODO\|FIXME\|XXX" src/ --include="*.ts" --include="*.tsx" --include="*.js" --exclude-dir=node_modules
+
+# Find console.log in non-test files
+grep -rn "console\." src/ --include="*.ts" --include="*.tsx" --include="*.js" | grep -v "\.test\." | grep -v "\.spec\."
+
+# Find empty functions
+grep -rn "{ *}" src/ --include="*.ts" --include="*.tsx"
+
+# Find placeholder values
+grep -rn "TODO\|FIXME\|XXX\|placeholder\|stub\|mock\|temp" src/ --include="*.ts" --include="*.tsx"
+```
+
+### Manual Code Review
+
+While executing task, watch for:
+
+```typescript
+// BAD: Comment indicating incomplete work
+export function fetchUser(id: string) {
+  // TODO: Add error handling
+  return api.get(`/users/${id}`);
+}
+
+// BAD: Empty body waiting for implementation
+export function validatePayment(payment: any) {
+  // XXX implement validation
+}
+
+// BAD: Console statement left behind
+function processOrder(order: Order) {
+  console.log('DEBUG: order =', order);  // forgot to remove
+  return calculateTotal(order);
+}
+
+// BAD: Hardcoded test values
+export function getAdminUser() {
+  return {
+    id: '123',  // hardcoded for testing
+    email: 'admin@test.com',  // test email
+    role: 'admin'
+  };
+}
+
+// BAD: Mock implementation left in
+export function sendEmail(to: string, body: string) {
+  console.log('Email sent (mock)', to, body);  // forgot to implement real email
+  return Promise.resolve();
+}
+```
+
+---
+
+## When Stubs Are Acceptable
+
+Stubs are OK ONLY if:
+
+1. **Documented in SUMMARY.md** — List all stubs with resolution plan
+2. **Tagged with issue/plan reference** — Example: `// TODO: Implement in plan 03-email`
+3. **Not blocking functionality** — Feature works with stub in place
+4. **Has clear next step** — `// XXX: Add real Stripe payment (stub returns mock)`
+
+Example of acceptable stub:
+
+```typescript
+// Acceptable: Tagged with future work
+async function sendConfirmationEmail(email: string) {
+  // TODO: Implement in plan 03-email-service
+  // For now, mock response so registration flow works
+  console.log('[STUB] Email sent to:', email);
+  return { success: true, messageId: 'mock-123' };
+}
+```
+
+In SUMMARY.md:
+```markdown
+### Known Stubs
+
+| File | Line | Type | Reason | Resolution |
+|------|------|------|--------|-----------|
+| src/email.ts | 45 | Mock function | Email service not yet integrated | Implement real SendGrid integration in plan 03 |
+```
+
+---
+
+## Unacceptable Stubs
+
+DO NOT leave these in SUMMARY:
+
+1. **Broken functionality** — Feature doesn't work, marked as TODO
+2. **Untagged stubs** — No reference to what needs implementing
+3. **Multiple stubs blocking one feature** — Sign of incomplete plan
+4. **Dead code** — Functions that do nothing
+5. **Placeholder values in constants** — `API_KEY = "TODO_SET_THIS"`
+
+---
+
+## Stub Handling Workflow
+
+During task execution:
+
+### Encounter a Stub Situation
+```
+Situation: Need to send email, but email service not ready
+Decision tree:
+  ├─ Is email required for THIS task to pass? 
+  │  └─ NO → Create stub, tag with future plan number
+  │  └─ YES → This should have been in plan discovery, raise checkpoint
+  └─ Can you mock it temporarily?
+     └─ YES → Implement mock, tag for real implementation later
+     └─ NO → STOP, return checkpoint (architectural issue)
+```
+
+### Create Stub with Proper Tagging
+```typescript
+/**
+ * STUB: Email sending
+ * 
+ * Implemented as mock for plan 01-authentication.
+ * Real implementation requires: SendGrid API key, email templates, rate limiting.
+ * 
+ * Tracked in: .planning/DEFERRED-ITEMS.md
+ * Resolution plan: plan 03-email-service (when email infrastructure ready)
+ */
+export async function sendConfirmationEmail(email: string): Promise<EmailResult> {
+  // Mock implementation - returns success without sending
+  console.log('[STUB sendConfirmationEmail]', email);
+  
+  return {
+    success: true,
+    messageId: `mock-${Date.now()}`,
+    timestamp: new Date().toISOString()
+  };
+}
+```
+
+### Log Stub in Deferred Items
+Create `.planning/DEFERRED-ITEMS.md` (if not exists):
+```markdown
+# Deferred Implementation Items
+
+## Email Service (plan 03-email-service)
+- **File:** src/email.ts
+- **Function:** sendConfirmationEmail()
+- **Current:** Mock returns success, doesn't send
+- **To Do:** Implement with SendGrid, handle bounces, add retries
+- **Estimate:** 3 tasks
+```
+
+---
+
+## Before Finalizing SUMMARY
+
+Scan for stubs one final time:
+
+```bash
+# Comprehensive stub search
+for pattern in "TODO" "FIXME" "XXX" "stub" "mock" "placeholder"; do
+  echo "=== Searching for: $pattern ==="
+  grep -rn "$pattern" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | head -20
+done
+```
+
+For each match found:
+1. Is it in code I wrote? (If no, skip)
+2. Is it acceptable per criteria above? (If no, implement or return checkpoint)
+3. If acceptable, ensure it's in SUMMARY.md stubs list
+
+---
+
+## SUMMARY.md Stub Section
+
+If stubs present:
+
+```markdown
+## Known Stubs
+
+| File | Line | Type | Reason | Resolution Plan |
+|------|------|------|--------|-----------------|
+| src/email.ts | 45 | Mock function | Email service integration deferred | Implement with SendGrid in plan 03-email |
+| src/payments.ts | 120 | TODO comment | Rate limiting not critical for MVP | Add in plan 04-security |
+
+**Note:** These stubs do not block functionality. All critical paths work. Stub functions return valid mock responses.
+```
+
+If NO stubs:
+
+```markdown
+## Known Stubs
+
+**No stubs found.** Plan executed with complete implementations.
+```
+
+---
+
+## Stub vs Incomplete Task
+
+| Situation | Classification | Action |
+|-----------|---|---------|
+| Function body is `{ console.log('stub'); return null; }` | Stub | Tag and document |
+| Function throws `NotImplementedError` | Incomplete | STOP execution, return checkpoint |
+| Function has TODO comment but works | Stub | Tag and document |
+| Tests marked with `.skip()` | Incomplete | Implement test or remove |
+| Feature works but has hardcoded test values | Stub | Document in SUMMARY |
+
+---
+
+## Common Stub Patterns to Catch
+
+```typescript
+// Pattern 1: Empty or minimal implementation
+function validate(data: unknown): boolean {
+  // TODO: actually validate
+  return true;
+}
+
+// Pattern 2: Console debugging left behind
+function process(item: Item) {
+  console.log('DEBUG:', item);  // left from debugging
+  return item.value * 2;
+}
+
+// Pattern 3: Placeholder values
+const API_KEY = 'set_this_later';
+const DATABASE_URL = 'TODO_configure';
+
+// Pattern 4: Mock still in code
+function fetchUser(id: string) {
+  // Mock for testing
+  if (id === 'test-123') return { id, name: 'Test User' };
+  
+  // Real implementation missing
+  throw new Error('Not implemented');
+}
+
+// Pattern 5: Commented-out code (dead code)
+// function legacyAuth(user) {
+//   // old approach, don't use
+//   return jwt.sign(user);
+// }
+```
+
+Catch these before SUMMARY. If found: implement, delete, or document with tag.

package/rihal/agents/rules/executor/summary-creation.md

@@ -0,0 +1,76 @@
+# Rihal Executor: Summary Creation
+
+## Creating SUMMARY.md After Plan Execution
+
+After all auto tasks complete, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+
+## Structure
+
+```markdown
+# {phase}-{plan} Summary
+
+**Plan:** {phase}-{plan}
+**Duration:** {time taken}
+**Tasks:** {completed}/{total}
+
+## Overview
+
+One-liner: "JWT auth with refresh rotation using jose library, 15-min access / 7-day refresh"
+
+Purpose: Why this plan matters (context in roadmap)
+Output: Artifacts created (files, endpoints, tables)
+
+## Tasks Completed
+
+| # | Task | Commit | Files |
+|---|------|--------|-------|
+| 1 | Task 1 name | a1b2c3d | src/auth.ts, src/types/user.ts |
+
+## Deviations from Plan
+
+### Auto-Fixed Issues
+
+| Issue | Rule | Location | Fix | Commit |
+|-------|------|----------|-----|--------|
+| Null check missing | Rule 2 | src/auth.ts:45 | Added email validation | a1b2c3d |
+
+Or if none: **None - plan executed exactly as written.**
+
+## Known Stubs
+
+Scan for TODO/FIXME/XXX before writing:
+
+```bash
+grep -rn "TODO\|FIXME\|XXX\|console\.log" src/ --include="*.ts" --include="*.tsx" | grep -v "\.test\."
+```
+
+If found:
+
+| File | Line | Type | Reason | Resolution |
+|------|------|------|--------|-----------|
+| src/email.ts | 45 | TODO | Email service deferred | Implement in plan 03 |
+
+Or if clean: **No stubs found.**
+
+## Self-Check
+
+- [ ] Task count matches (plan: X, SUMMARY: X)
+- [ ] All commits present in git
+- [ ] No uncommitted changes
+- [ ] No failing tests
+- [ ] Success criteria verified
+- [ ] Stubs documented or resolved
+
+**Status:** PASSED or FAILED
+
+## State Updates After SUMMARY
+
+```bash
+node ".rihal/bin/rihal-tools.cjs" state advance-plan
+node ".rihal/bin/rihal-tools.cjs" state update-progress
+node ".rihal/bin/rihal-tools.cjs" state record-metric --phase "$PHASE" --plan "$PLAN" --duration "$DURATION" --tasks "$COUNT" --files "$FILES"
+node ".rihal/bin/rihal-tools.cjs" roadmap update-plan-progress "$PHASE_NUMBER"
+node ".rihal/bin/rihal-tools.cjs" requirements mark-complete $REQ_IDS
+```
+
+Then final commit with SUMMARY.md + STATE.md + ROADMAP.md + REQUIREMENTS.md