@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/references/git-preflight.md

@@ -0,0 +1,117 @@
+# Git Preflight Contract
+
+Shared reference `@`-included by every code-touching workflow. Designed by Khalid (DevOps) to close #659.
+
+## When this runs
+
+Before ANY workflow step that will modify files in the working tree — i.e. before `/rcode-execute`, `/rcode-quick`, `/rcode-dev-story`, `/rcode-review-fix`, and any other workflow that writes outside `.planning/`.
+
+## The 4 checks
+
+Run these read-only commands in order. Any failure halts the workflow with the failure banner below.
+
+```bash
+# Check 1: working tree clean
+DIRTY=$(git status --porcelain 2>/dev/null)
+
+# Check 2: not on a protected branch
+BRANCH=$(git branch --show-current 2>/dev/null)
+PROTECTED="main master develop v2-prototype"
+
+# Check 3: branch follows naming convention
+# Allowed: feat/foo-bar, fix/123-baz, issue-123-name, task-123-slug
+BRANCH_OK=$(echo "$BRANCH" | grep -qE '^((feat|fix|docs|chore|refactor|test|perf|style|build|ci)/[a-z0-9][a-z0-9-]*|(issue|task)-[0-9]+-[a-z0-9-]+)$' && echo yes || echo no)
+
+# Check 4: scope drift — files touched that don't belong to the active task
+# The workflow MUST pass $TASK_SCOPE_GLOB (e.g. ".planning/phases/8-*/" or "src/auth/")
+# If the workflow can't compute scope, skip this check rather than fail closed.
+if [ -n "$TASK_SCOPE_GLOB" ]; then
+  OUT_OF_SCOPE=$(git diff --name-only HEAD 2>/dev/null | grep -vE "$TASK_SCOPE_GLOB" | head -10)
+fi
+```
+
+## Failure conditions
+
+The workflow MUST stop and print the banner below if ANY of:
+
+- `DIRTY` is non-empty AND user did not pass `--allow-dirty`
+- `BRANCH` is in `$PROTECTED` AND user did not pass `--on-main`
+- `BRANCH_OK` is `no` AND user did not pass `--allow-dirty` (branch-name lint is advisory if working tree is dirty AND user accepted the dirty override)
+- `OUT_OF_SCOPE` is non-empty AND user did not pass `--allow-scope-drift`
+
+## Failure UX (banner)
+
+```
+Khalid (خالد) — DevOps preflight
+
+Cannot start {workflow_name}. Git state is unsafe.
+
+  Branch:        {BRANCH}              {protected? "(protected)" : ""}
+  Working tree:  {dirty/clean}         {N modified, M untracked if dirty}
+  Branch name:   {BRANCH_OK ? "ok" : "doesn't match convention"}
+  Scope drift:   {N files outside task scope}
+
+  {if dirty: list up to 5 modified files}
+  {if scope drift: list up to 5 out-of-scope files}
+
+Fix path:
+  1. git checkout -b fix/<issue-num>-<short-slug>
+  2. git add <files> ; git commit -m "fix(scope): subject (#<issue>)"
+  3. Re-run /{workflow_name}
+
+Override (last resort, only if you understand the trade-off):
+  /{workflow_name} {args} --allow-dirty       # skip working-tree check
+  /{workflow_name} {args} --on-main           # skip protected-branch check
+  /{workflow_name} {args} --allow-scope-drift # skip scope-drift check
+
+▶ Next Up
+  Clean the tree or branch, then resume. Khalid does not gate hotfixes —
+  if this is a true emergency, --on-main is the right answer.
+```
+
+## Post-task commit prompt
+
+After the workflow's code-modifying work completes, BEFORE returning control to the user, prompt for a commit:
+
+```
+Khalid — commit checkpoint
+
+Modified files (staged or unstaged):
+  [list git status --short output, grouped by logical unit if possible]
+
+A commit is required before this workflow can be considered done.
+
+GH issue link required per AGENTS.md. What issue does this work close?
+  Issue # (digits only, or "none" if this is exploratory): ___
+
+Suggested commit (Conventional Commits):
+  {type}({scope}): {subject} (#{issue})
+
+  {body — optional, explain WHY}
+
+Run `git add <files> && git commit` with the message above, or edit before
+running. AGENTS.md forbids --no-verify; if a hook fails, fix the underlying
+cause.
+```
+
+The hook only stages and commits. **It does NOT push.** Push always requires fresh user consent per `.rcode/references/no-unauthorized-git-ops.md`.
+
+## Override flag semantics
+
+| Flag | Skips | When valid |
+|------|-------|------------|
+| `--allow-dirty` | working-tree clean check | resuming a partial in-progress task, or amending a WIP commit |
+| `--on-main` | protected-branch check | true hotfix where the user accepts the risk; CI / release flows |
+| `--allow-scope-drift` | scope drift check | refactor that legitimately spans phases; cross-cutting cleanup |
+
+Each flag is independent. The user must pass exactly the override they need; the workflow MUST NOT auto-promote one override into another.
+
+## What this does NOT do
+
+- Does not run `git fetch` / `git pull` — those are remote operations and need explicit consent (see `no-unauthorized-git-ops.md`).
+- Does not create branches automatically. The failure banner *suggests* the branch name; the user runs the command.
+- Does not block read-only workflows (`/rcode-status`, `/rcode-discuss`, `/rcode-council`, etc.).
+
+## Why a shared reference
+
+Same shape as `no-unauthorized-git-ops.md`: a pre-condition contract that every workflow includes by `@`-reference. Single source of truth — when the policy changes, exactly one file changes and every code-touching workflow inherits the update.

package/rcode/references/integration-verification-playbook.md

@@ -0,0 +1,392 @@
+# Integration Verification Playbook
+
+Loaded by `rcode-integration-checker` via `@-include`. Contains the full
+six-step verification process, structured output template, critical rules,
+and success criteria.
+
+---
+
+## Step 1: Build Export/Import Map
+
+For each phase, extract what it provides and what it should consume.
+
+**From SUMMARYs, extract:**
+
+```bash
+# Key exports from each phase
+for summary in .planning/phases/*/*-SUMMARY.md; do
+  echo "=== $summary ==="
+  grep -A 10 "Key Files\|Exports\|Provides" "$summary" 2>/dev/null
+done
+```
+
+**Build provides/consumes map:**
+
+```
+Phase 1 (Auth):
+  provides: getCurrentUser, AuthProvider, useAuth, /api/auth/*
+  consumes: nothing (foundation)
+
+Phase 2 (API):
+  provides: /api/users/*, /api/data/*, UserType, DataType
+  consumes: getCurrentUser (for protected routes)
+
+Phase 3 (Dashboard):
+  provides: Dashboard, UserCard, DataList
+  consumes: /api/users/*, /api/data/*, useAuth
+```
+
+## Step 2: Verify Export Usage
+
+For each phase's exports, verify they're imported and used.
+
+**Check imports:**
+
+```bash
+check_export_used() {
+  local export_name="$1"
+  local source_phase="$2"
+  local search_path="${3:-src/}"
+
+  # Find imports
+  local imports=$(grep -r "import.*$export_name" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | \
+    grep -v "$source_phase" | wc -l)
+
+  # Find usage (not just import)
+  local uses=$(grep -r "$export_name" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | \
+    grep -v "import" | grep -v "$source_phase" | wc -l)
+
+  if [ "$imports" -gt 0 ] && [ "$uses" -gt 0 ]; then
+    echo "CONNECTED ($imports imports, $uses uses)"
+  elif [ "$imports" -gt 0 ]; then
+    echo "IMPORTED_NOT_USED ($imports imports, 0 uses)"
+  else
+    echo "ORPHANED (0 imports)"
+  fi
+}
+```
+
+**Run for key exports:**
+
+- Auth exports (getCurrentUser, useAuth, AuthProvider)
+- Type exports (UserType, etc.)
+- Utility exports (formatDate, etc.)
+- Component exports (shared components)
+
+## Step 3: Verify API Coverage
+
+Check that API routes have consumers.
+
+**Find all API routes:**
+
+```bash
+# Next.js App Router
+find src/app/api -name "route.ts" 2>/dev/null | while read route; do
+  # Extract route path from file path
+  path=$(echo "$route" | sed 's|src/app/api||' | sed 's|/route.ts||')
+  echo "/api$path"
+done
+
+# Next.js Pages Router
+find src/pages/api -name "*.ts" 2>/dev/null | while read route; do
+  path=$(echo "$route" | sed 's|src/pages/api||' | sed 's|\.ts||')
+  echo "/api$path"
+done
+```
+
+**Check each route has consumers:**
+
+```bash
+check_api_consumed() {
+  local route="$1"
+  local search_path="${2:-src/}"
+
+  # Search for fetch/axios calls to this route
+  local fetches=$(grep -r "fetch.*['\"]$route\|axios.*['\"]$route" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l)
+
+  # Also check for dynamic routes (replace [id] with pattern)
+  local dynamic_route=$(echo "$route" | sed 's/\[.*\]/.*/g')
+  local dynamic_fetches=$(grep -r "fetch.*['\"]$dynamic_route\|axios.*['\"]$dynamic_route" "$search_path" \
+    --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l)
+
+  local total=$((fetches + dynamic_fetches))
+
+  if [ "$total" -gt 0 ]; then
+    echo "CONSUMED ($total calls)"
+  else
+    echo "ORPHANED (no calls found)"
+  fi
+}
+```
+
+## Step 4: Verify Auth Protection
+
+Check that routes requiring auth actually check auth.
+
+**Find protected route indicators:**
+
+```bash
+# Routes that should be protected (dashboard, settings, user data)
+protected_patterns="dashboard|settings|profile|account|user"
+
+# Find components/pages matching these patterns
+grep -r -l "$protected_patterns" src/ --include="*.tsx" 2>/dev/null
+```
+
+**Check auth usage in protected areas:**
+
+```bash
+check_auth_protection() {
+  local file="$1"
+
+  # Check for auth hooks/context usage
+  local has_auth=$(grep -E "useAuth|useSession|getCurrentUser|isAuthenticated" "$file" 2>/dev/null)
+
+  # Check for redirect on no auth
+  local has_redirect=$(grep -E "redirect.*login|router.push.*login|navigate.*login" "$file" 2>/dev/null)
+
+  if [ -n "$has_auth" ] || [ -n "$has_redirect" ]; then
+    echo "PROTECTED"
+  else
+    echo "UNPROTECTED"
+  fi
+}
+```
+
+## Step 5: Verify E2E Flows
+
+Derive flows from milestone goals and trace through codebase.
+
+**Common flow patterns:**
+
+### Flow: User Authentication
+
+```bash
+verify_auth_flow() {
+  echo "=== Auth Flow ==="
+
+  # Step 1: Login form exists
+  local login_form=$(grep -r -l "login\|Login" src/ --include="*.tsx" 2>/dev/null | head -1)
+  [ -n "$login_form" ] && echo "✓ Login form: $login_form" || echo "✗ Login form: MISSING"
+
+  # Step 2: Form submits to API
+  if [ -n "$login_form" ]; then
+    local submits=$(grep -E "fetch.*auth|axios.*auth|/api/auth" "$login_form" 2>/dev/null)
+    [ -n "$submits" ] && echo "✓ Submits to API" || echo "✗ Form doesn't submit to API"
+  fi
+
+  # Step 3: API route exists
+  local api_route=$(find src -path "*api/auth*" -name "*.ts" 2>/dev/null | head -1)
+  [ -n "$api_route" ] && echo "✓ API route: $api_route" || echo "✗ API route: MISSING"
+
+  # Step 4: Redirect after success
+  if [ -n "$login_form" ]; then
+    local redirect=$(grep -E "redirect|router.push|navigate" "$login_form" 2>/dev/null)
+    [ -n "$redirect" ] && echo "✓ Redirects after login" || echo "✗ No redirect after login"
+  fi
+}
+```
+
+### Flow: Data Display
+
+```bash
+verify_data_flow() {
+  local component="$1"
+  local api_route="$2"
+  local data_var="$3"
+
+  echo "=== Data Flow: $component → $api_route ==="
+
+  # Step 1: Component exists
+  local comp_file=$(find src -name "*$component*" -name "*.tsx" 2>/dev/null | head -1)
+  [ -n "$comp_file" ] && echo "✓ Component: $comp_file" || echo "✗ Component: MISSING"
+
+  if [ -n "$comp_file" ]; then
+    # Step 2: Fetches data
+    local fetches=$(grep -E "fetch|axios|useSWR|useQuery" "$comp_file" 2>/dev/null)
+    [ -n "$fetches" ] && echo "✓ Has fetch call" || echo "✗ No fetch call"
+
+    # Step 3: Has state for data
+    local has_state=$(grep -E "useState|useQuery|useSWR" "$comp_file" 2>/dev/null)
+    [ -n "$has_state" ] && echo "✓ Has state" || echo "✗ No state for data"
+
+    # Step 4: Renders data
+    local renders=$(grep -E "\{.*$data_var.*\}|\{$data_var\." "$comp_file" 2>/dev/null)
+    [ -n "$renders" ] && echo "✓ Renders data" || echo "✗ Doesn't render data"
+  fi
+
+  # Step 5: API route exists and returns data
+  local route_file=$(find src -path "*$api_route*" -name "*.ts" 2>/dev/null | head -1)
+  [ -n "$route_file" ] && echo "✓ API route: $route_file" || echo "✗ API route: MISSING"
+
+  if [ -n "$route_file" ]; then
+    local returns_data=$(grep -E "return.*json|res.json" "$route_file" 2>/dev/null)
+    [ -n "$returns_data" ] && echo "✓ API returns data" || echo "✗ API doesn't return data"
+  fi
+}
+```
+
+### Flow: Form Submission
+
+```bash
+verify_form_flow() {
+  local form_component="$1"
+  local api_route="$2"
+
+  echo "=== Form Flow: $form_component → $api_route ==="
+
+  local form_file=$(find src -name "*$form_component*" -name "*.tsx" 2>/dev/null | head -1)
+
+  if [ -n "$form_file" ]; then
+    # Step 1: Has form element
+    local has_form=$(grep -E "<form|onSubmit" "$form_file" 2>/dev/null)
+    [ -n "$has_form" ] && echo "✓ Has form" || echo "✗ No form element"
+
+    # Step 2: Handler calls API
+    local calls_api=$(grep -E "fetch.*$api_route|axios.*$api_route" "$form_file" 2>/dev/null)
+    [ -n "$calls_api" ] && echo "✓ Calls API" || echo "✗ Doesn't call API"
+
+    # Step 3: Handles response
+    local handles_response=$(grep -E "\.then|await.*fetch|setError|setSuccess" "$form_file" 2>/dev/null)
+    [ -n "$handles_response" ] && echo "✓ Handles response" || echo "✗ Doesn't handle response"
+
+    # Step 4: Shows feedback
+    local shows_feedback=$(grep -E "error|success|loading|isLoading" "$form_file" 2>/dev/null)
+    [ -n "$shows_feedback" ] && echo "✓ Shows feedback" || echo "✗ No user feedback"
+  fi
+}
+```
+
+## Step 6: Compile Integration Report
+
+Structure findings for milestone auditor.
+
+**Wiring status:**
+
+```yaml
+wiring:
+  connected:
+    - export: "getCurrentUser"
+      from: "Phase 1 (Auth)"
+      used_by: ["Phase 3 (Dashboard)", "Phase 4 (Settings)"]
+
+  orphaned:
+    - export: "formatUserData"
+      from: "Phase 2 (Utils)"
+      reason: "Exported but never imported"
+
+  missing:
+    - expected: "Auth check in Dashboard"
+      from: "Phase 1"
+      to: "Phase 3"
+      reason: "Dashboard doesn't call useAuth or check session"
+```
+
+**Flow status:**
+
+```yaml
+flows:
+  complete:
+    - name: "User signup"
+      steps: ["Form", "API", "DB", "Redirect"]
+
+  broken:
+    - name: "View dashboard"
+      broken_at: "Data fetch"
+      reason: "Dashboard component doesn't fetch user data"
+      steps_complete: ["Route", "Component render"]
+      steps_missing: ["Fetch", "State", "Display"]
+```
+
+---
+
+Return structured report to milestone auditor:
+
+```markdown
+## Integration Check Complete
+
+### Wiring Summary
+
+**Connected:** {N} exports properly used
+**Orphaned:** {N} exports created but unused
+**Missing:** {N} expected connections not found
+
+### API Coverage
+
+**Consumed:** {N} routes have callers
+**Orphaned:** {N} routes with no callers
+
+### Auth Protection
+
+**Protected:** {N} sensitive areas check auth
+**Unprotected:** {N} sensitive areas missing auth
+
+### E2E Flows
+
+**Complete:** {N} flows work end-to-end
+**Broken:** {N} flows have breaks
+
+### Detailed Findings
+
+#### Orphaned Exports
+
+{List each with from/reason}
+
+#### Missing Connections
+
+{List each with from/to/expected/reason}
+
+#### Broken Flows
+
+{List each with name/broken_at/reason/missing_steps}
+
+#### Unprotected Routes
+
+{List each with path/reason}
+
+#### Requirements Integration Map
+
+| Requirement | Integration Path | Status | Issue |
+|-------------|-----------------|--------|-------|
+| {REQ-ID} | {Phase X export → Phase Y import → consumer} | WIRED / PARTIAL / UNWIRED | {specific issue or "—"} |
+
+**Requirements with no cross-phase wiring:**
+{List REQ-IDs that exist in a single phase with no integration touchpoints — these may be self-contained or may indicate missing connections}
+```
+
+---
+
+**Check connections, not existence.** Files existing is phase-level. Files connecting is integration-level.
+
+**Trace full paths.** Component → API → DB → Response → Display. Break at any point = broken flow.
+
+**Check both directions.** Export exists AND import exists AND import is used AND used correctly.
+
+**Be specific about breaks.** "Dashboard doesn't work" is useless. "Dashboard.tsx line 45 fetches /api/users but doesn't await response" is actionable.
+
+**Return structured data.** The milestone auditor aggregates your findings. Use consistent format.
+
+---
+
+- [ ] Export/import map built from SUMMARYs
+- [ ] All key exports checked for usage
+- [ ] All API routes checked for consumers
+- [ ] Auth protection verified on sensitive routes
+- [ ] E2E flows traced and status determined
+- [ ] Orphaned code identified
+- [ ] Missing connections identified
+- [ ] Broken flows identified with specific break points
+- [ ] Requirements Integration Map produced with per-requirement wiring status
+- [ ] Requirements with no cross-phase wiring identified
+- [ ] Structured report returned to auditor
+
+---
+
+- verify external service connectivity
+- check environment variables are properly set
+- validate API integrations and database connections
+- document all integration failures with remediation steps
+- return structured PASS/FAIL report

package/rcode/references/iterative-retrieval.md

@@ -0,0 +1,85 @@
+# Iterative Retrieval — Bounded Research Loop
+
+The contract a research-spawning workflow follows when dispatching a research
+subagent and handling its return. Designed to be `@`-included by any workflow
+that spawns a research subagent (`rcode-phase-researcher`,
+`rcode-project-researcher`, `rcode-research-synthesizer`,
+`rcode-codebase-mapper`).
+
+Goal: research subagents get a follow-up gate, the same way executors get a
+verifier gate. A single research dispatch may return a shallow or partial
+result; this loop re-queries it — bounded — until the result is sufficient
+against the original objective.
+
+---
+
+## 1. Initial dispatch — pass the broader objective
+
+The orchestrator MUST pass the broader **objective** into the subagent prompt,
+not just the literal query. The subagent needs to know *why* the research
+matters and *what its output must enable downstream* — otherwise it optimizes
+for the narrow question and misses what the consumer actually needs.
+
+Include an `<objective>` block of this shape in the dispatch prompt:
+
+```
+<objective>
+{literal research query — the specific thing to find out}
+
+Why this matters: {the broader phase/project goal this research serves}
+Downstream consumer: {what planning/requirements/roadmap step uses this
+  result, and what a sufficient result must let that step do}
+</objective>
+```
+
+The literal query stays; the objective frames it.
+
+---
+
+## 2. Sufficiency evaluation — on return
+
+After the subagent returns its `## RESEARCH COMPLETE` summary, the orchestrator
+evaluates the result against the Step-1 objective **before** routing onward.
+The result is **insufficient** if any of these hold:
+
+- **Coverage gap** — the result does not address every dimension the objective
+  asked for (a missing dimension, an unanswered sub-question).
+- **Vague recommendations** — recommendations lack specifics: no versions, no
+  rationale, "consider X or Y" menus instead of "use X because Y".
+- **Blocked signal** — the subagent returned `## RESEARCH INCONCLUSIVE`, a
+  structured blocked message, or flagged a dimension it could not resolve.
+
+If none hold, the result is sufficient — proceed with normal routing.
+
+---
+
+## 3. Re-dispatch — same subagent, named gaps
+
+If insufficient, re-spawn the **SAME** `subagent_type` with a follow-up prompt
+that:
+
+- names the **specific gaps** found in Section 2 (which dimension, which
+  vague recommendation, which blocked signal),
+- includes the **prior result** so the subagent does not redo finished work,
+- asks **only for the missing pieces** — not a full re-research.
+
+The follow-up dispatch carries the same `<objective>` block from Step 1.
+
+---
+
+## 4. Hard cap — maximum 3 cycles
+
+The loop is hard-capped at **3 cycles**: the initial dispatch plus at most 2
+follow-up re-dispatches. After cycle 3, the orchestrator accepts the best
+result obtained, records the residual gaps in the research artifact (a
+`## Residual Gaps` note or equivalent), and proceeds. **Never loop unbounded** —
+3 cycles is the ceiling regardless of remaining gaps.
+
+---
+
+## 5. Out of scope — executors
+
+This loop applies to **research subagents only**. It does **not** apply to
+executor subagents — the executor checkpoint/verifier flow is unchanged. Do
+not re-dispatch an executor based on a sufficiency evaluation; executors have
+their own checkpoint and verifier gates.

package/rcode/references/karpathy-guidelines-full.md

@@ -0,0 +1,79 @@
+# Karpathy Coding Guidelines
+
+Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rcode agent that writes, reviews, or refactors code must internalize these four principles.
+
+**Tradeoff:** These bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+**rcode application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rcode-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rcode-executor must stop on Rule 4 deviations and return a checkpoint, not silently guess.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Test: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+**rcode application:** rcode-planner tasks must be single-purpose. rcode-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rcode-review explicitly flags overengineering.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+**rcode application:** rcode-executor commits must only include files its tasks touched. The deviation scope boundary (out-of-scope warnings logged to deferred-items.md, not fixed) enforces this. rcode-review-fix must not change style in files it's auditing.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**rcode application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rcode-executor self-check loop verifies Done-when conditions were met. rcode-sprint-checker rejects plans where tasks have vague success criteria.
+
+## Enforcement
+
+Agents that write or modify code (rcode-executor, rcode-planner, rcode-noor, rcode-codebase-mapper when producing code docs) must:
+1. @-include this file
+2. Apply the 4 principles as hard constraints, not suggestions
+3. Reference the specific principle when refusing to make a change (e.g., "Declining per Karpathy #3: that's adjacent to the requested change but not part of it")
+
+## Credit
+
+Original principles by Andrej Karpathy. Reference implementation by Forrest Chang at github.com/forrestchang/andrej-karpathy-skills. Adapted and extended for rcode's multi-agent architecture.

package/rcode/references/karpathy-guidelines.md

@@ -0,0 +1,11 @@
+# Karpathy Guidelines — Quick Reference
+
+Four hard constraints for every agent that writes, reviews, or modifies code or artifacts.
+Full text with rcode-specific application notes: `@.rcode/references/karpathy-guidelines-full.md`
+
+1. **Think first (P1)** — State assumptions explicitly before acting. If scope is ambiguous, ask. Never guess silently.
+2. **Simplicity (P2)** — Minimum code/scope that solves the problem. No speculative features, abstractions, or error handling for impossible cases.
+3. **Surgical (P3)** — Touch only what the task requires. Don't improve adjacent code, don't refactor what isn't broken.
+4. **Goal-driven (P4)** — Define a verifiable success criterion before starting. "Done when: X can be verified externally."
+
+When refusing a change, cite the principle: `"Declining per Karpathy P3 — that's adjacent to the requested change."`