@hanzlaa/rcode 3.6.16 → 4.0.0

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

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

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

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

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