@hanzlaa/rcode 3.6.16 → 4.1.0

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

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

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

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