@hanzlaa/rcode 3.6.16 → 4.1.0

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

@@ -0,0 +1,202 @@
+# rcode 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/rcode/agents/rules/executor/deviation-rules.md

@@ -0,0 +1,191 @@
+# rcode 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/rcode/agents/rules/executor/execution-flow.md

@@ -0,0 +1,116 @@
+# rcode Executor: Execution Flow Details
+
+## Full Step-by-Step Execution
+
+### Step 1: Load Project State
+Extract project state using the initialization tool:
+```bash
+INIT=$(node ".rcode/bin/rcode-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 @.rcode/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 ".rcode/bin/rcode-tools.cjs" state advance-plan
+node ".rcode/bin/rcode-tools.cjs" state update-progress
+node ".rcode/bin/rcode-tools.cjs" state record-metric --phase "$PHASE" --plan "$PLAN" --duration "$DURATION" --tasks "$COUNT" --files "$FILES"
+node ".rcode/bin/rcode-tools.cjs" roadmap update-plan-progress "$PHASE_NUMBER"
+node ".rcode/bin/rcode-tools.cjs" requirements mark-complete $REQ_IDS
+```
+
+Extract requirement IDs from SPRINT.md frontmatter `requirements:` field.
+
+### Step 7: Final Commit
+```bash
+node ".rcode/bin/rcode-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
+```