@hanzlaa/rcode 2.2.0 → 2.3.2

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.2.0",
-  "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 44 agents, 93 slash commands, 58 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
+  "version": "2.3.2",
+  "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 44 agents, 98 slash commands, 56 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
   "main": "cli/index.js",
   "bin": {
-    "rcode": "cli/index.js",
-    "rihal-code": "cli/index.js"
+    "rcode": "dist/rcode.js",
+    "rihal-code": "dist/rcode.js"
   },
   "scripts": {
     "dashboard": "node server/dashboard.js",
     "test": "node --test",
     "test:ci": "node --test --test-reporter=spec",
-    "postinstall": "node cli/postinstall.js"
+    "postinstall": "node cli/postinstall.js",
+    "build:cli": "node scripts/build.cjs",
+    "build": "node scripts/build.cjs"
   },
   "files": [
     "cli/",
     "rihal/",
     "server/",
+    "dist/",
     ".rihal-template/",
     "README.md",
     "AGENTS.md",
@@ -54,6 +57,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "picocolors": "^1.1.1",
+    "nanospinner": "^1.2.2",
+    "fast-glob": "^3.3.3",
+    "zod": "^3.24.0",
+    "semver": "^7.7.1",
+    "diff": "^7.0.0",
+    "@clack/prompts": "^0.9.1"
+  },
   "publishConfig": {
     "access": "public"
   }

package/rihal/DOCS-AUDIT.md

@@ -0,0 +1,14 @@
+# DOCS-AUDIT.md (per-project artefact)
+
+This file is generated by `/rihal:document-project` into the project root
+as `DOCS-AUDIT.md`. The shipped reference here just defines the schema:
+
+- **Inventory:** every doc file (path, last-touched, owner, freshness).
+- **Gaps:** docs that should exist per the project's domain (e.g. README,
+  CONTRIBUTING, ADRs for major decisions) but don't.
+- **Stale:** docs that diverge from current code/state (links to dead
+  files, version mismatches, removed features still documented).
+- **Recommendations:** ordered remediation list.
+
+Workflows that @-include this file expect the live audit output, which
+the workflow itself writes to disk before reading.

package/rihal/agents/rihal-code-reviewer.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Code Reviewer

package/rihal/agents/rihal-codebase-mapper.md

@@ -7,7 +7,7 @@ color: cyan
 
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 
 <role>
 You are a rihal codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.rihal/codebase/`.

package/rihal/agents/rihal-docs-auditor.md

@@ -6,7 +6,7 @@ color: gold
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Documentation Auditor

package/rihal/agents/rihal-edge-case-hunter.md

@@ -6,7 +6,7 @@ color: maroon
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Edge Case Hunter

package/rihal/agents/rihal-executor.md

@@ -6,9 +6,10 @@ color: yellow
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
 @.rihal/references/no-unauthorized-git-ops.md
+@.rihal/brain/best-practices/no-theoretical-suggestions.md
 
 <role>
 Rihal sprint executor. Execute SPRINT.md files atomically, commit each story, handle deviations, pause at checkpoints, produce SUMMARY.md.

package/rihal/agents/rihal-hussain-pm.md

@@ -7,6 +7,7 @@ color: orange
 
 @.rihal/references/response-style.md
 @.rihal/references/codebase-grounding.md
+@.rihal/references/karpathy-guidelines.md
 
 # Hussain-PM — Product Manager
 

package/rihal/agents/rihal-nyquist-auditor.md

@@ -6,7 +6,7 @@ color: #8B5CF6
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 <role>

package/rihal/agents/rihal-phase-researcher.md

@@ -7,8 +7,8 @@ color: cyan
 
 
 @.rihal/references/response-style.md
-
-
+@.rihal/references/karpathy-guidelines.md
+@.rihal/brain/best-practices/no-theoretical-suggestions.md
 
 <role>
 You are a Rihal phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.

package/rihal/agents/rihal-planner.md

@@ -6,8 +6,9 @@ color: green
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
+@.rihal/brain/best-practices/no-theoretical-suggestions.md
 
 <role>
 Rihal sprint planner. Create executable SPRINT.md files with story breakdown, dependency analysis, and goal-backward verification.
@@ -129,7 +130,7 @@ Output: [Artifacts created]
 </objective>
 
 <execution_context>
-@.rihal/workflows/execute-plan.md
+@.rihal/workflows/execute.md
 @.rihal/templates/summary.md
 </execution_context>
 

package/rihal/agents/rihal-roadmapper.md

@@ -8,6 +8,7 @@ color: purple
 
 @.rihal/references/response-style.md
 @.rihal/references/output-realism.md
+@.rihal/references/karpathy-guidelines.md
 
 <role>
 You are a rihal roadmapper. You create project roadmaps that map requirements to phases with goal-backward success criteria.

package/rihal/agents/rihal-security-adversary.md

@@ -6,7 +6,7 @@ color: darkred
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Security Adversary

package/rihal/agents/rihal-security-auditor.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 # Rihal Security Auditor

package/rihal/agents/rihal-sprint-checker.md

@@ -7,7 +7,7 @@ color: green
 
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 
 <role>
 You are a Rihal sprint checker. Verify that sprints WILL achieve the phase goal, not just that they look complete.

package/rihal/agents/rihal-verifier.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rihal/references/response-style.md
-@.rihal/references/karpathy-guidelines.md
+@.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
 
 <role>

package/rihal/bin/lib/roadmap.cjs

@@ -1,9 +1,8 @@
 /**
  * Roadmap — Rihal ROADMAP.md parsing and mutation helpers.
  *
- * Self-contained (stdlib only). Matches GSD output shapes for the subset of
- * commands that Rihal workflows currently invoke: get-phase, list-phases,
- * update-plan-progress, and clear.
+ * Self-contained (stdlib only). Subcommands invoked by Rihal workflows:
+ * get-phase, list-phases, update-plan-progress, clear.
  */
 
 const fs = require('fs');

package/rihal/bin/rihal-tools.cjs

@@ -1950,7 +1950,7 @@ function cmdState(subArgs) {
   // --- promote-backlog <from> --to <target> ---
   // Promote a 999.x parking-lot phase to a real phase number.
   // Mutates state.phases[]; renames the on-disk directory if present.
-  // Tracks issue #159 (M2.5 — GSD-parity 999.x convention).
+  // Tracks issue #159 (M2.5 — 999.x parking-lot convention).
   if (sub === 'promote-backlog') {
     const from = subArgs[1];
     const flags = parseFlags(2);
@@ -2568,8 +2568,12 @@ function cmdResolveModel(agentId) {
 }
 
 /**
- * config set --key <k> --value <v> — update a key in .rihal/config.yaml
- * Writes YAML-style `key: value` (quotes strings with spaces).
+ * config set --key <k> --value <v> — DEPRECATED legacy form.
+ *
+ * Closes #233. The original implementation used a flat YAML parser that
+ * destroyed the nested `workflow:` and `git:` sections on every save.
+ * This shim now delegates to the nested-safe writer in lib/config.cjs and
+ * emits a one-line deprecation warning to stderr so callers migrate.
  */
 function cmdConfigSet(subArgs) {
   const flags = {};
@@ -2587,34 +2591,10 @@ function cmdConfigSet(subArgs) {
   if (!key) throw new Error('config set requires --key <key> --value <value>\n  e.g. config set --key language --value Arabic');
   if (!value) throw new Error('config set requires --key <key> --value <value>\n  e.g. config set --key language --value Arabic');
 
-  const configPath = path.join(RIHAL_DIR, 'config.yaml');
-  fs.mkdirSync(RIHAL_DIR, { recursive: true });
-
-  let content = '';
-  if (fs.existsSync(configPath)) {
-    content = fs.readFileSync(configPath, 'utf8');
-  }
-
-  // Parse current config
-  const config = parseSimpleYaml(content);
-
-  // Update the key
-  config[key] = value;
-
-  // Serialize back to YAML
-  const lines = [];
-  for (const [k, v] of Object.entries(config)) {
-    const needsQuotes = /\s/.test(v);
-    const yamlValue = needsQuotes ? `"${v.replace(/"/g, '\\"')}"` : v;
-    lines.push(`${k}: ${yamlValue}`);
-  }
-
-  const newContent = lines.join('\n') + '\n';
-  const tmp = configPath + '.tmp';
-  fs.writeFileSync(tmp, newContent, 'utf8');
-  fs.renameSync(tmp, configPath);
+  process.stderr.write(`[deprecated] 'config set --key X --value Y' — use 'config-set X Y' instead (preserves nested YAML).\n`);
 
-  return { ok: true, key, value, path: configPath };
+  const cfg = require(path.join(__dirname, 'lib', 'config.cjs'));
+  return cfg.cmdSet(PROJECT_ROOT, key, value);
 }
 
 /**
@@ -3033,7 +3013,7 @@ function cmdBrain(args) {
 }
 
 /**
- * cmdProgress — single pre-computed progress blob (GSD-parity, issue #159).
+ * cmdProgress — single pre-computed progress blob (issue #159).
  *
  * Subcommands:
  *   progress init          Full snapshot — everything /rihal:progress needs.

package/rihal/brain/best-practices/no-theoretical-suggestions.md

@@ -0,0 +1,56 @@
+# No Theoretical Suggestions Rule
+
+Referenced by all agents that propose plans, file changes, or implementation steps.
+
+## The Rule
+
+**Every suggestion, plan, or implementation step must be grounded in what actually exists in the codebase.** Never propose a change based on assumed structure, naming conventions, documentation, or what "probably" exists.
+
+## What This Means in Practice
+
+Before including any file path, function name, config key, or field in a plan:
+
+1. Confirm it exists — use `Read`, `grep`, `find`, or `glob`.
+2. If it doesn't exist, say so explicitly: "this doesn't exist yet."
+3. Only then decide whether to create it (if the user asked) or report the gap (if they didn't).
+
+## The Test
+
+Could every line of your plan be traced to a specific file and line number in the repo right now? If not, the plan contains theoretical content — do not ship it.
+
+## Failure Pattern to Avoid
+
+- Agent reads an investigation doc or workflow description.
+- Agent produces a plan based on what the doc *says* should exist.
+- Agent never verifies the described files/fields/functions actually exist.
+- Plan references symbols that are missing, misnamed, or not yet implemented.
+- Execution fails or produces wrong results.
+
+This pattern is forbidden. Investigation documents describe intent, not ground truth. Code is ground truth.
+
+## Correct Behavior
+
+```
+# WRONG — theoretical
+"Fix the force_web_search toggle in backend/config.py"
+(without checking if force_web_search actually exists in that file)
+
+# RIGHT — grounded
+grep -r "force_web_search" backend/
+→ no results
+→ "force_web_search doesn't exist in the codebase yet. The investigation doc was theoretical. Here's what actually exists: ..."
+```
+
+## When You Can't Find Something
+
+- Do NOT assume it's in a different file or under a different name.
+- Do NOT write a plan that assumes you'll find it later.
+- STOP and report: "I searched for X and found nothing. Either it doesn't exist yet or the investigation was theoretical."
+
+## Applies To
+
+- `rihal-planner` — every task in SPRINT.md must reference real files
+- `rihal-executor` — read the target file before writing any change
+- `rihal-phase-researcher` — cite actual code paths, not presumed ones
+- `rihal-sprint-checker` — flag plans that reference non-existent symbols
+- All council agents — proposals must name real constraints, not theoretical ones

package/rihal/commands/add-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:add-phase
-description: Execute add-phase workflow
-argument-hint: ""
+description: "Add a new integer phase to the end of the current milestone. Auto-calculates the next phase number, creates the phase directory, and updates ROADMAP.md. Use when scope expands mid-milestone."
+argument-hint: "<phase-name>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/audit.md

@@ -0,0 +1,8 @@
+---
+name: rihal:audit
+description: Single audit entry point — asks what to audit (phase, milestone, UAT, code, fix, work) and dispatches to the right subroute. Honours .rihal/config.yaml mode.
+argument-hint: "[phase | milestone | uat | code | fix | work] [...subroute args]"
+allowed-tools: Read, Write, Bash, AskUserQuestion
+---
+
+@.rihal/workflows/audit.md

package/rihal/commands/checkpoint-preview.md

@@ -0,0 +1,13 @@
+---
+name: rihal:checkpoint-preview
+description: Human-in-the-loop change review — makes sense of a diff, focuses attention where it matters, and walks through testing. Use when you say "checkpoint", "walk me through this", or "human review".
+argument-hint: "[<branch-or-diff>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+@.rihal/workflows/checkpoint-preview.md

package/rihal/commands/cleanup.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:cleanup
-description: Execute cleanup workflow
-argument-hint: ""
+description: "Archive completed milestone phase directories into .planning/milestones/. Run after /rihal:complete-milestone to keep .planning/ tidy. Shows a dry-run summary before moving anything."
+argument-hint: "[--dry-run]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

package/rihal/commands/config.md

@@ -1,8 +1,8 @@
 ---
 name: rihal:config
-description: View or edit Rihal configuration (language, mode, model profile, branching strategy)
-argument-hint: "[show | set <key> <value>]"
-allowed-tools: Read, Bash, AskUserQuestion
+description: Alias for /rihal:settings — view or edit Rihal config (language, mode, model profile, workflow gates, git strategy)
+argument-hint: "[show | get <key> | set <key> <value>]"
+allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 
-@.rihal/workflows/config.md
+@.rihal/workflows/settings.md

package/rihal/commands/pr-branch.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:pr-branch
-description: Execute pr-branch workflow
-argument-hint: ""
+description: "Create a clean PR branch that strips all Rihal planning artifacts (.planning/, SPRINT.md, SUMMARY.md, STATE.md). Reviewers see only code changes. Use before /rihal:ship when you want a clean git history in the PR."
+argument-hint: "[<base-branch>]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/prfaq.md

@@ -0,0 +1,15 @@
+---
+name: rihal:prfaq
+description: Working Backwards PRFAQ challenge — stress-test a product concept by writing the press release before building it. Produces a battle-hardened PRFAQ document + PRD distillate.
+argument-hint: "[<idea>] [--headless] [--customer=<persona>] [--problem=<problem>] [--stakes=<why>] [--solution=<concept>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Agent
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+---
+
+@.rihal/workflows/prfaq.md

package/rihal/commands/remove-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:remove-phase
-description: Execute remove-phase workflow
-argument-hint: ""
+description: "Remove an unstarted future phase from ROADMAP.md, delete its directory, and renumber all subsequent phases to maintain a clean sequence. Cannot remove a phase already in progress or completed."
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/research-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:research-phase
-description: Execute research-phase workflow
-argument-hint: ""
+description: "Research how to implement a phase before planning. Spawns rihal-phase-researcher with phase context. Standalone tool — /rihal:plan already runs this automatically. Use only when you want research without immediately creating a plan."
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/settings.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:settings
-description: Interactive configuration wizard for Rihal project settings. Update model profile, research strategy, execution gates, and branching strategy.
-argument-hint: ""
+description: View or edit Rihal project settings (mode, model_profile, workflow gates, git strategy). Supports show / get / set / interactive modes.
+argument-hint: "[show | get <key> | set <key> <value>]"
 allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 

package/rihal/commands/ship.md

@@ -1,12 +1,24 @@
 ---
 name: rihal:ship
-description: Execute ship workflow
-argument-hint: ""
+description: "After a phase is verified, create a PR: push branch, auto-generate PR body from planning artifacts (ROADMAP, VERIFICATION, SUMMARY), and optionally request review. Closes the plan→execute→verify→ship loop."
+argument-hint: "[<phase>] [--draft]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <objective>
-Execute ship workflow
+Ship a completed, verified phase by pushing its feature branch and opening a
+pull request with an auto-generated body drawn from planning artifacts.
+
+**When to use:**
+- You have finished `/rihal:execute <phase>` and `/rihal:verify-phase <phase>` passed
+- You want to open a PR from your feature branch into main/develop
+- You want the PR body auto-filled with phase goal, changes, requirements addressed, and verification status
+
+**When NOT to use:**
+- Publishing a package to npm → use `npm publish` directly
+- Tagging a release → use `git tag` + `git push --tags`
+- You are inside the rihal-code framework repo itself (no phases exist here)
+- Your project uses `git.branching_strategy: none` and you commit directly to main
 </objective>
 
 <execution_context>

package/rihal/commands/validate-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:validate-phase
 description: Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
-argument-hint: ""
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

package/rihal/commands/verify-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:verify-phase
-description: Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, 
-argument-hint: ""
+description: "Goal-backward audit — does the codebase actually deliver what the phase promised? Produces VERIFICATION.md with pass/fail. Required before /rihal:ship. Run after /rihal:execute completes."
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

package/rihal/references/agent-contracts.md

@@ -0,0 +1,12 @@
+# Agent Contracts
+
+Conventions Rihal sub-agents follow when invoked from a workflow.
+
+- **Input**: a single prompt string. The orchestrator passes structured data
+  inline (path lists, JSON blobs) — sub-agents do not stream args.
+- **Output**: one final message back to the orchestrator. No partial state
+  is visible mid-run.
+- **Side effects**: each agent's tool list is its full surface — any tool
+  not granted in the agent definition is unavailable.
+- **Failure**: agents that hit an obstacle return a structured "blocked"
+  message rather than fabricating output.

package/rihal/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 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-tech-writer, 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.