@hanzlaa/rcode 3.6.16 → 4.1.0

package/rihal/references/git-preflight.md

@@ -1,117 +0,0 @@
-# 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 `/rihal-execute`, `/rihal-quick`, `/rihal-dev-story`, `/rihal-code-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 `.rihal/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 (`/rihal-status`, `/rihal-discuss`, `/rihal-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/rihal/references/integration-verification-playbook.md

@@ -1,392 +0,0 @@
-# Integration Verification Playbook
-
-Loaded by `rihal-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/rihal/references/iterative-retrieval.md

@@ -1,85 +0,0 @@
-# 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 (`rihal-phase-researcher`,
-`rihal-project-researcher`, `rihal-research-synthesizer`,
-`rihal-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/rihal/references/karpathy-guidelines-full.md

@@ -1,79 +0,0 @@
-# Karpathy Coding Guidelines
-
-Behavioral guidelines derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. Every rihal 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.
-
-**Rihal application:** In Round 1 of council/chain, every agent's response must include an `## Assumptions` block listing load-bearing assumptions. rihal-planner must ask via AskUserQuestion before writing a plan when scope is ambiguous. rihal-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.
-
-**Rihal application:** rihal-planner tasks must be single-purpose. rihal-executor must not add abstractions during task execution (deviation Rule 2 applies only to missing critical functionality, not speculative flexibility). rihal-code-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.
-
-**Rihal application:** rihal-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. rihal-code-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.
-
-**Rihal application:** Every task in a SPRINT.md must have a "Done when:" clause that's externally verifiable. rihal-executor self-check loop verifies Done-when conditions were met. rihal-sprint-checker rejects plans where tasks have vague success criteria.
-
-## Enforcement
-
-Agents that write or modify code (rihal-executor, rihal-planner, rihal-noor, rihal-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 rihal's multi-agent architecture.

package/rihal/references/karpathy-guidelines.md

@@ -1,11 +0,0 @@
-# Karpathy Guidelines — Quick Reference
-
-Four hard constraints for every agent that writes, reviews, or modifies code or artifacts.
-Full text with Rihal-specific application notes: `@.rihal/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."`