@hanzlaa/rcode 2.1.0

package/rihal/agents/rules/debugger/scientific-method.md

@@ -0,0 +1,317 @@
+# Rihal Debugger: Scientific Method for Bug Investigation
+
+## The Scientific Method in Debugging
+
+Debugging is empirical investigation, not guessing. Follow the scientific method:
+
+1. **Observation** — Describe precisely what happens
+2. **Question** — What could cause this?
+3. **Hypothesis** — Make a specific, testable claim
+4. **Experiment** — Test the hypothesis
+5. **Analysis** — What does the result tell us?
+6. **Conclusion** — Is the hypothesis supported?
+
+---
+
+## Phase 1: Observation (Precise Description)
+
+**Bad observation:** "It's broken"
+**Good observation:** "Login button click does nothing, no error message, form stays visible"
+
+### Documenting Observations
+
+```
+Symptom: User login fails intermittently
+Expected: Form submits, shows loading state, redirects to dashboard
+Actual: Form doesn't submit, button click has no effect
+Frequency: Happens ~30% of the time, not consistent
+When started: Today after deployment, worked yesterday
+Environment: Chrome, macOS, localhost:3000
+Error message: None visible (checked console too)
+```
+
+### Complete Reading Protocol
+
+Read ENTIRE functions, not just "relevant" lines:
+- Read the full function body (not just the error line)
+- Read all imports (missing dependency?)
+- Read function signature (wrong params?)
+- Read calling code (are you using it right?)
+- Read error handler (is it catching too broadly?)
+
+Skimming misses crucial details like:
+```javascript
+// You spot the error here:
+const user = getUserById(userId);  // userId might be undefined
+
+// But you missed this earlier in the function:
+if (someCondition) {
+  userId = null;  // Aha! This sets it to null
+}
+```
+
+---
+
+## Phase 2: Question (What Could Cause This?)
+
+For each observation, list EVERY possible cause (don't judge yet):
+
+**Observation:** Form doesn't submit when clicking button
+
+**Possible causes:**
+1. Click handler never fires (listener not attached)
+2. Click handler fires but form validation fails silently
+3. API call doesn't happen (async issue)
+4. API call fails (network error)
+5. API response causes error (bad data)
+6. Button is disabled (CSS display: none?)
+7. Async/await missing (call doesn't wait)
+8. Event prevention (stopPropagation?)
+9. Race condition (another handler removes button)
+10. Browser issue (console errors hidden)
+
+Write them all down. You'll test them later.
+
+---
+
+## Phase 3: Hypothesis Formation
+
+Transform each possibility into a testable, specific claim:
+
+**Bad (unfalsifiable):**
+- "Something is wrong with the form"
+- "The timing is off"
+- "There's a race condition"
+
+**Good (falsifiable):**
+- "Click handler doesn't fire because addEventListener() wasn't called"
+- "Form validation fails silently because error handler catches all exceptions"
+- "API call completes after unmount, causing state update on unmounted component"
+
+**The difference:** Specificity. Good hypotheses make claims you can test.
+
+### Hypothesis Template
+```
+Hypothesis: [Specific, testable claim]
+
+If TRUE, I should observe:
+  - [Observable evidence 1]
+  - [Observable evidence 2]
+
+If FALSE, I should observe:
+  - [Contradicting evidence]
+
+How to test:
+  - [Specific test steps]
+```
+
+### Example:
+```
+Hypothesis: Click handler doesn't fire because addEventListener() was never called
+
+If TRUE, I should observe:
+  - console.log() inside click handler never executes
+  - Breakpoint in handler never hits
+
+If FALSE, I should observe:
+  - Handler runs but something else prevents submission
+
+How to test:
+  1. Add console.log('Button clicked') at start of handler
+  2. Click button
+  3. Check browser console for log message
+```
+
+---
+
+## Phase 4: Experiment (Design and Run Test)
+
+For each hypothesis, design ONE experiment that tests it:
+
+### Experimental Design Template
+
+```
+Hypothesis: [Claim]
+
+Prediction: If H is true, I will observe [X]
+
+Test Setup:
+  1. [Precondition]
+  2. [Precondition]
+
+Action:
+  1. [Do this]
+  2. [Do that]
+
+Measurement:
+  - What exactly am I measuring?
+  - How do I know if X occurred?
+
+Success Criteria:
+  - Result supports hypothesis: [What would prove it true?]
+  - Result contradicts hypothesis: [What would prove it false?]
+
+Expected Outcome:
+  [What I think will happen]
+
+Actual Outcome:
+  [What actually happened]
+
+Conclusion:
+  [Does this support or refute the hypothesis?]
+```
+
+### Example Test
+
+```
+Hypothesis: Click handler doesn't execute because addEventListener wasn't called
+
+Prediction: console.log inside handler never runs
+
+Test Setup:
+  1. Open browser DevTools Console
+  2. Navigate to login page
+
+Action:
+  1. Click the Login button
+
+Measurement:
+  I'm looking for a console message "Button clicked"
+
+Success if:
+  - No message appears → Handler didn't run → Hypothesis TRUE
+  - Message appears → Handler ran → Hypothesis FALSE
+
+Expected: No message (I think the handler isn't attached)
+
+Actual: Message DOES appear "Button clicked"
+
+Conclusion: Hypothesis is FALSE. Handler DOES execute. Problem is elsewhere.
+```
+
+---
+
+## Phase 5: Analysis (What Does Evidence Tell Us?)
+
+After each experiment:
+
+1. **Record the result** — Exactly what happened, not what you expected
+2. **Compare to prediction** — Did reality match expectation?
+3. **Assess evidence quality** — Strong or weak?
+4. **Extract learning** — What did this rule out? What's new?
+5. **Update mental model** — Based on evidence, what's likely now?
+
+### Evidence Quality
+
+**Strong evidence:**
+- Directly observable (I see X in logs)
+- Repeatable (X happens every time)
+- Unambiguous (Definitely X, not Y)
+- Independent (X happens even without Y)
+
+**Weak evidence:**
+- Hearsay (I think I saw X once)
+- Non-repeatable (X failed once, can't replicate)
+- Ambiguous (Maybe X, could be Y)
+- Confounded (X happened after A AND B AND C)
+
+---
+
+## Phase 6: Hypothesis Refinement
+
+When a hypothesis is **refuted:**
+
+```
+Hypothesis: Click handler doesn't run
+Result: Handler DOES run (console.log proved it)
+
+What this rules out:
+  - addEventListener() missing ✓ (handler runs, so it exists)
+  - Event listener detached ✓
+
+What this reveals:
+  - Handler executes successfully
+  - Problem is AFTER handler, not in handler
+  - Next place: form submission or API call
+
+New hypothesis to test:
+  Form.submit() doesn't actually submit (event default prevented? form validation fail?)
+```
+
+When a hypothesis is **supported:**
+
+```
+Hypothesis: API call fails with 401 error
+Result: Network tab shows POST /api/login returns 401
+
+What this confirms:
+  - Authentication failing (could be: token expired, wrong creds, header missing)
+
+What to test next:
+  - Is Authorization header present?
+  - Is token valid/non-expired?
+  - Are credentials correct?
+```
+
+---
+
+## The Debugging Loop
+
+```
+┌─ Observation (What's broken?)
+│
+├─ Questions (What could cause this?)
+│
+├─ Hypothesis (Specific testable claim)
+│
+├─ Experiment (Test the claim)
+│
+├─ Analysis (What does evidence show?)
+│
+├─ Refine Hypothesis (Based on analysis)
+│
+└─ Repeat until root cause found
+```
+
+---
+
+## Common Mistakes in Scientific Method
+
+### Mistake 1: Falling in Love with First Hypothesis
+**Problem:** You form one hypothesis and spend hours defending it.
+**Fix:** Generate 3+ independent hypotheses before investigating any.
+
+### Mistake 2: Confirmation Bias
+**Problem:** You only look for evidence supporting your hypothesis.
+**Fix:** Actively seek disconfirming evidence. "What would prove me wrong?"
+
+### Mistake 3: Testing Multiple Variables at Once
+**Problem:** You change three things and it works. Which one fixed it?
+**Fix:** Test ONE hypothesis at a time. Change one variable per experiment.
+
+### Mistake 4: Acting on Weak Evidence
+**Problem:** "It seems like maybe this could be..." → You change code.
+**Fix:** Wait for strong, unambiguous evidence before acting.
+
+### Mistake 5: Abandoning Rigor Under Pressure
+**Problem:** "Just let me try this..." without hypothesis/experiment.
+**Fix:** Double down on method when pressure increases. Speed comes from efficiency, not skipping steps.
+
+---
+
+## When to Restart
+
+Consider starting fresh when:
+
+1. **2+ hours, no progress** — You're likely tunnel-visioned
+2. **3+ "fixes" that didn't work** — Your mental model is wrong
+3. **Can't explain current behavior** — Don't layer changes on confusion
+4. **Debugging the debugger** — Something fundamental is wrong
+5. **Fix works but you don't know why** — This isn't fixed, it's luck
+
+Restart protocol:
+1. Close all files and terminals
+2. Write down what you KNOW for certain (not guesses)
+3. Write down what you've RULED OUT
+4. List NEW hypotheses (different from before)
+5. Begin again from Observation phase

package/rihal/agents/rules/executor/authentication-gates.md

@@ -0,0 +1,202 @@
+# Rihal Executor: Authentication Gates
+
+## Defining Authentication Gates
+
+Authentication errors ("Not authenticated", "401", "403", "Set ENV_VAR") are gates, not failures.
+
+A gate is:
+- A checkpoint that requires human action (visiting a URL, clicking a button, entering credentials)
+- Unavoidable (code alone cannot pass)
+- **NOT** a task failure or bug
+
+Examples:
+- "Please visit OAuth provider and authorize app" → gate
+- "Set STRIPE_API_KEY environment variable" → gate
+- "Click email verification link" → gate
+- "Enter 2FA code" → gate
+- "Set missing database credentials" → gate
+
+Non-examples:
+- "Database connection failed" → Try to debug (wrong password? wrong host? down?)
+- "API request timeout" → Retry logic
+- "Missing npm dependency" → Install it
+
+---
+
+## When to Stop at Gate
+
+Recognize gate patterns:
+
+```javascript
+// Pattern 1: Explicit authentication message
+Error: Not authenticated
+401 Unauthorized
+403 Forbidden
+Set ENV_VAR_NAME=<value>
+
+// Pattern 2: Missing credentials
+Missing API key
+No auth token
+Credentials required
+
+// Pattern 3: OAuth/session flow
+Authorization required
+User consent needed
+Session expired
+```
+
+---
+
+## Gate Handling Protocol
+
+When you hit a gate:
+
+### 1. Identify Gate Type
+- **Env variable:** Missing secret key
+- **OAuth:** Authorization flow needed
+- **Session:** Re-authentication required
+- **Email:** Verification link click
+- **MFA:** Code entry
+- **Manual setup:** Dashboard configuration
+
+### 2. Document Exact Steps
+Write down EXACTLY what the user needs to do:
+```
+Gate: Missing STRIPE_API_KEY
+Steps:
+1. Visit https://dashboard.stripe.com
+2. Go to Developers → API Keys
+3. Copy the Secret Key (not publishable key)
+4. Set in your shell: export STRIPE_API_KEY=<key>
+5. Re-run plan execution
+```
+
+### 3. Return Checkpoint
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** human-action
+**Plan:** {phase}-{plan}
+**Task {N}:** [task name]
+**Blocked by:** {gate type}
+
+### What's Needed
+[Exact steps from above]
+
+### Why It's Needed
+[Brief explanation of what this enables]
+
+### Awaiting
+User to complete steps and confirm.
+```
+
+### 4. Never Guess Credentials
+- NEVER invent placeholder values like `api_key_123`
+- NEVER hardcode fake credentials to unblock testing
+- NEVER store secrets in code
+- User provides real secrets during checkpoint
+
+---
+
+## Special Cases
+
+### Multiple Gates in One Task
+If a single task requires multiple gates (OAuth + env var + email):
+1. Return ONE checkpoint with all required steps
+2. Ask user to complete ALL before resuming
+3. Resume and continue task execution
+
+### Gate in Middle of Plan
+If gate appears mid-plan:
+1. Complete all tasks before gate
+2. Return checkpoint
+3. User completes gate steps
+4. Resume remaining tasks
+
+### Forgotten Gate from Previous Checkpoint
+If user re-runs plan and forgot gate step:
+1. Detect same gate error
+2. Return same checkpoint message
+3. Remind user of previous steps
+
+---
+
+## Never Confuse with Failure
+
+| Situation | Is Gate? | Action |
+|-----------|----------|--------|
+| "401 Unauthorized" with no creds set | YES | Checkpoint, ask for credentials |
+| "401 Unauthorized" with creds set but expired | NO | Retry or refresh token |
+| "Missing API_KEY env var" | YES | Checkpoint, ask user to set it |
+| "Database connection refused" | NO | Debug (wrong host? port? down?) |
+| "OAuth authorization required" | YES | Checkpoint with OAuth flow steps |
+| "Session expired" | MAYBE | Try to refresh, if no mechanism, checkpoint |
+
+---
+
+## Automation Preference
+
+Always try to automate BEFORE stopping at gate:
+
+```javascript
+// BEFORE stopping, try:
+1. Check if creds can be read from ~/.env or ~/.config
+2. Check if refresh tokens exist
+3. Check if session can be re-established
+4. Try to programmatically authorize if library supports it
+
+// ONLY AFTER automation attempts fail:
+Return checkpoint with human-action type
+```
+
+Example:
+```bash
+# Before gate checkpoint, check:
+if [ -f "$HOME/.stripe-creds" ]; then
+  source "$HOME/.stripe-creds"
+fi
+
+# If still missing:
+# Return checkpoint asking user to provide
+```
+
+---
+
+## Gate Completion Verification
+
+After user completes gate steps:
+
+1. **Ask confirmation:** "Have you completed steps 1-3 above?"
+2. **Test gate:** Try the operation that failed before
+3. **If still fails:** Return checkpoint again with debugging steps
+4. **If passes:** Resume execution, commit current task
+
+Example:
+```
+User completes OAuth, returns to prompt saying "Done"
+
+Verification: Run API call that previously failed
+Result: Still 401
+
+Action: Return checkpoint with debugging steps
+- "Check if token is in your Authorization header"
+- "Verify OAuth provider shows app as authorized"
+- "Check token hasn't expired (token valid for 1 hour)"
+```
+
+---
+
+## Documentation
+
+When creating SUMMARY.md, list gates encountered:
+
+```markdown
+### Authentication Gates
+
+| Gate | Type | Resolution |
+|------|------|-----------|
+| STRIPE_API_KEY missing | Env var | User provided key during checkpoint 1 |
+| OAuth authorization | OAuth | User authorized app via Stripe dashboard |
+
+If this plan is re-run, gates may reappear. Complete steps above to resume.
+```

package/rihal/agents/rules/executor/deviation-rules.md

@@ -0,0 +1,191 @@
+# Rihal Executor: Deviation Rules
+
+## The Four Deviation Rules
+
+When implementation diverges from plan, follow this priority:
+
+### RULE 1: Auto-fix bugs
+**Trigger:** Code doesn't work as intended
+
+Examples:
+- Logic errors (wrong condition, bad algorithm)
+- Null/undefined checks missing
+- Validation skipped
+- Security issues (SQL injection, XSS exposure)
+
+**Action:** Fix immediately. Commit with `fix()` scope. No checkpoint needed.
+
+**Example:** Plan says "validate email with regex" but implementation skips validation → fix the validation logic and commit.
+
+---
+
+### RULE 2: Auto-add critical functionality
+**Trigger:** Missing error handling, validation, security, or reliability
+
+Examples:
+- API endpoint missing try/catch → add it
+- Input validation missing → add validators
+- Auth checks missing → add authentication guards
+- Rate limiting missing → add rate limiter
+- Database indexes missing → add indexes
+- Unhandled promise rejections → add error handlers
+
+**Action:** Add the missing critical piece. Commit with `feat()` scope if new, `fix()` if completing incomplete code.
+
+**Example:** Plan implements payment endpoint but forgets error handling → add comprehensive error handling, commit `fix(payment): add error handling`.
+
+---
+
+### RULE 3: Auto-fix blocking issues
+**Trigger:** Something prevents task from completing
+
+Examples:
+- Missing dependency (not in package.json)
+- Broken import (file path wrong)
+- Missing environment variable (required but not set)
+- Database connection error (can't reach DB)
+- Build configuration error (TypeScript won't compile)
+
+**Action:** Fix the blocker. This is a prerequisite, not a deviation.
+
+**Example:** Plan imports from `lib/utils` but file doesn't exist → create the file or fix the import path.
+
+---
+
+### RULE 4: Ask about architectural changes
+**Trigger:** Changes that affect future plans or system design
+
+Examples requiring human decision:
+- New database table or schema change
+- Major schema restructuring (many fields affected)
+- New external service (Stripe, SendGrid, etc.)
+- Library switch (React Router → TanStack Router)
+- Authentication approach change (JWT → OAuth, etc.)
+- Breaking API changes (endpoint restructuring)
+- Data model redesign
+
+**Action:** STOP execution. Return checkpoint with `type="decision"`. Explain the architectural choice and ask for user approval.
+
+**Example:** Plan assumes User has email field, but field doesn't exist. User needs to decide: add field to schema, or change plan approach.
+
+---
+
+## Priority and Scoping
+
+**Priority:** Rule 4 → STOP. Rules 1-3 → Fix. Unsure → Apply Rule 4 (ask, don't assume).
+
+**Scope:** Only auto-fix issues DIRECTLY caused by this task's changes.
+- If task A creates a bug in task A's code → auto-fix
+- If task A exposes a pre-existing bug in unrelated code → log to `deferred-items.md`
+
+**Retry Limit:** After 3 attempts per task (3 bug fixes, 3 missing features, 3 blockers), STOP execution. Document in SUMMARY.md and return checkpoint.
+
+---
+
+## Decision Flowchart
+
+```
+Issue detected during task execution
+│
+├─ Is it a logic bug in this task's code?
+│  └─ YES → Rule 1: Auto-fix bug, continue
+│
+├─ Is it missing error/validation/security in this task?
+│  └─ YES → Rule 2: Auto-add critical feature, continue
+│
+├─ Is it blocking this task from completing?
+│  └─ YES → Rule 3: Auto-fix blocker, continue
+│
+└─ Does it require architectural decision?
+   └─ YES → Rule 4: STOP, checkpoint, ask user
+```
+
+---
+
+## Examples by Rule
+
+### Rule 1 Example: Logic Bug
+```javascript
+// Plan says: Create endpoint that validates even request IDs
+// Implementation:
+app.get('/item/:id', (req, res) => {
+  const id = parseInt(req.params.id);
+  if (id % 2 !== 0) {  // BUG: checks ODD, not EVEN
+    return res.status(400).send('ID must be even');
+  }
+  res.json({ id });
+});
+
+// Deviation fix:
+if (id % 2 === 0) {  // FIXED: now checks EVEN
+```
+
+### Rule 2 Example: Missing Validation
+```javascript
+// Plan says: Create POST endpoint for user creation
+// Implementation (missing validation):
+app.post('/users', (req, res) => {
+  db.createUser(req.body);  // No validation!
+  res.json({ ok: true });
+});
+
+// Deviation fix:
+app.post('/users', (req, res) => {
+  if (!req.body.email || !req.body.password) {
+    return res.status(400).json({ error: 'Missing required fields' });
+  }
+  if (!isValidEmail(req.body.email)) {
+    return res.status(400).json({ error: 'Invalid email' });
+  }
+  db.createUser(req.body);
+  res.json({ ok: true });
+});
+```
+
+### Rule 3 Example: Broken Import
+```javascript
+// Plan references src/lib/utils.ts
+// File doesn't exist → Auto-fix
+// Solution: Create the file with required exports
+
+// src/lib/utils.ts (created to unblock)
+export function formatDate(d) {
+  return d.toLocaleDateString();
+}
+```
+
+### Rule 4 Example: Architectural Decision
+```
+Plan assumes: "User model has 'role' field"
+Implementation: User model doesn't have role field
+Question: Should we add 'role' to User, or use a separate Roles table?
+
+Action: STOP execution
+Checkpoint: "User model needs role field. Add to User, or use separate table?"
+Wait: User decision
+Resume: Implement based on user's chosen approach
+```
+
+---
+
+## Special Cases
+
+### Cascade of Bugs
+If fixing one bug reveals another:
+1. Fix the first bug, commit
+2. Test fix (does primary issue resolve?)
+3. If secondary issue appears, evaluate: Rule 1-3 → fix, Rule 4 → checkpoint
+4. Continue normally
+
+### Ambiguous Issues
+If unsure which rule applies:
+- Err toward Rule 4 (asking)
+- Asking for confirmation costs 5 seconds
+- Fixing the wrong thing can waste hours
+
+### Cross-Task Bugs
+If task A's code breaks task B's code during execution:
+1. Identify root cause in task A
+2. Apply appropriate rule (usually Rule 1 or 2)
+3. Fix and re-test both tasks
+4. Continue execution