@hanzlaa/rcode 3.4.3 → 3.4.5

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -184,6 +184,31 @@ gh pr create --title "feat(skills): sharper PRD discovery on pricing models"
 
 ---
 
+## Adding a New Agent — Registration Checklist
+
+When you add a new agent to `rihal/team.yaml`, update **all** of these locations to keep parity tests green:
+
+| File | What to add |
+|------|-------------|
+| `rihal/team.yaml` | Agent entry with `id`, `name`, `role`, `domain_keywords` |
+| `rihal/agents/rihal-<id>.md` | Agent persona stub |
+| `rihal/skills/agents/<slug>/SKILL.md` | Full skill definition (5-component standard) |
+| `.claude/skills/rihal-<id>/SKILL.md` | Installed skill copy (or let install sync it) |
+| `rihal/workflows/do.md` | Routing alias row in the persona table |
+| `rihal/workflows/discuss.md` | Add to single-agent dispatch list |
+| `rihal/bin/rihal-tools.cjs` `QUALITY_AGENTS` | Add model assignment if the agent is `quality` tier |
+| `README.md` team table | Add a row for the new persona |
+| `server/dashboard.js` roster | Add to dashboard display roster |
+
+**Parity tests that will fail if you miss a location:**
+- `agent-team-parity.test.cjs` — team.yaml ↔ agent files
+- `agents-registry.test.cjs` — agent registry consistency
+- `help-md-parity.test.cjs` — any new command stubs
+
+Run `node --test` before opening a PR.
+
+---
+
 ## 🚨 Critical Rule — Never Auto-Push
 
 **AI agents and automation tools working on this repository MUST NEVER push to any remote without explicit, interactive user approval on every push.**
@@ -233,11 +258,48 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `agents` — agent persona files
 - `skills` — action or agent skills
 - `workflows` — multi-step workflows
+- `commands` — `rihal/commands/*.md` slash command files
 - `templates` — memory bank or pitch templates
 - `dashboard` — Majlis/Diwan server
-- `docs` — README, METHODOLOGY, SKILLS_INDEX
+- `docs` — README, METHODOLOGY, SKILLS_INDEX, USER-GUIDE, FAQ
 - `config` — team.yaml, config.yaml
 - `github` — CI/CD, issue templates, PR templates
+- `cli` — `cli/*.js` and `rihal/bin/rihal-tools.cjs`
+- `state` — `.rihal/state.json` and state-manipulation code paths
+- `refs` — files inside `rihal/references/`
+- `hooks` — `.claude/hooks/*` and install-time hook wiring
+- `install` — installer flow, manifest, side-effects
+- `memory` — Memory Bank distillates and templates
+- `brand` — branding/voice across surfaces
+- `ci` — CI workflow YAML and gating logic
+- `release` — version bumps, CHANGELOG, npm publish artifacts
+- `meta` — repo-level files (AGENTS.md, CONTRIBUTING.md, this list)
+- `tasks` — TaskCreate/TaskUpdate-shaped task tracking
+- `migrations` — schema/data migrations between versions
+- `parity` — drift gate / parity test additions
+- `triggers` — multilingual trigger phrase additions
+- `dogfood` — `scripts/dogfood-check.sh` and self-test gates
+- `state` — state.json schema or sync logic
+- `namespace` — namespace standardization across files
+- `planning` — `.planning/` artifacts (STATE.md, ROADMAP.md, REQUIREMENTS.md)
+- `insights` — runtime insight surfaces
+- `help` — help.md content
+- `roadmap` — `.planning/ROADMAP.md` edits
+- `session` — session reports / closing notes
+- `audits` — `.planning/audits/` artifacts
+- `execute` — execute workflow
+- `executor` — executor agent
+- `plan` — plan workflow
+- `planner` — planner agent
+- `readme` — README.md
+- `sync` — install/state sync flows
+- `sprint` — sprint-level workflow additions and fixes
+- `agent-exp` — agent experience improvements
+- `extensibility` — extensibility and plugin hooks
+- `lens-audit` — 15-lens audit system and lenses
+- `tiers` — TIERS.md and tier-related documentation
+- `<phase-id>` — numeric phase scope when committing inside a phase (e.g. `docs(15)`, `feat(8.3)`)
+- `<sprint-id>` — numeric sprint scope inside a phase (e.g. `feat(15.1)`)
 
 ### Subject rules
 - Lowercase first letter (enforced by `semantic-pull-request`)

package/README.md

@@ -11,8 +11,7 @@ npx @hanzlaa/rcode install    # one command, zero dependencies
 [![npm version](https://img.shields.io/npm/v/@hanzlaa/rcode)](https://www.npmjs.com/package/@hanzlaa/rcode)
 [![downloads](https://img.shields.io/npm/dw/@hanzlaa/rcode)](https://www.npmjs.com/package/@hanzlaa/rcode)
 
-<!-- TODO: Replace with actual demo GIF once recorded (story 05.1.03) -->
-<!-- ![rcode demo](docs/assets/demo.gif) -->
+**Quick look:** `npx @hanzlaa/rcode install` → `/rihal-council` → `/rihal-plan 1` → `/rihal-execute 1` — that's the full loop in three commands.
 
 ---
 
@@ -58,8 +57,8 @@ Rihal Code packages a lot. To keep things approachable, everything is organized
 
 Most AI tools give you one assistant pretending to be everything. **Rihal Code gives you Rihal's team — and Rihal's brain — inside every project.**
 
-- **45 agents** with clear roles, cultural identity (Arabic names), and hard scope boundaries
-- **95 slash commands** covering research, planning, execution, verification, and recovery
+- **44 agents** with clear roles, cultural identity (Arabic names), and hard scope boundaries
+- **96 slash commands** covering research, planning, execution, verification, and recovery
 - **105 skills** including Memory Bank primitives, 11 engineering-rigor skills (TDD, harden, perf, debug, trim, etc.), and 8 real-pain skills (auth-audit, mvp-graduate, deploy-unify, etc.)
 - **102 workflows** — the execution backbone behind every slash command
 - **Persistent project memory** at `.rihal/memory/` — checked into git, visible in the Diwan dashboard, lossless distillates for fast LLM hydration
@@ -499,6 +498,12 @@ UNLICENSED — proprietary. All rights reserved.
 
 ---
 
+## Auto-heal cadence
+
+rihal-code ships continuous auto-heal tools — `/rihal-feature-drift`, `/rihal-memory-audit`, `/rihal-health` — plus a CI dogfood gate that runs them against this repo on every push. See [docs/AUTO-HEAL-CADENCE.md](docs/AUTO-HEAL-CADENCE.md) for recommended schedules, `/loop` examples, crontab entries, and the safety rules around `--fix` modes.
+
+---
+
 ## Roadmap
 
 See [GitHub Issues](https://github.com/hanzlahabib/rihal-code/issues) for tracked work. Current focus: marketing launch, MCP server, dashboard enhancements.

package/cli/generate-command-skills.cjs

@@ -4,9 +4,9 @@
  *
  * WHY: VS Code's Claude Code extension lists `.claude/skills/` in its
  * sidebar, but slash commands at `.claude/commands/rihal/` are only
- * reachable via the `/` autocomplete. Users coming from GSD (which ships
- * a skill per command) expect to see lifecycle commands like `rihal-do`
- * in the sidebar.
+ * reachable via the `/` autocomplete. Users expect to see lifecycle
+ * commands like `rihal-do` in the sidebar — generating a thin skill
+ * stub per command makes them browsable without duplicating real skills.
  *
  * This script creates ONE skill stub per slash command at install time,
  * unless a real skill with the same name already exists at the source.
@@ -19,7 +19,7 @@
  * `generated-by: rcode-install` in frontmatter so it can be detected
  * and refreshed on subsequent installs without confusing real skills.
  *
- * Run: node scripts/generate-command-skills.cjs <package-root> <target-skills-dir>
+ * Run: node cli/generate-command-skills.cjs <package-root> <target-skills-dir>
  *      (called from cli/install.js)
  */
 
@@ -99,7 +99,7 @@ source: rihal/commands/${cmdName}.md
 ---
 
 <!--
-AUTO-GENERATED at install time by scripts/generate-command-skills.cjs.
+AUTO-GENERATED at install time by cli/generate-command-skills.cjs.
 Do NOT edit this file directly — your changes will be overwritten on the next
 install or update. To customise, create a sibling \`.local.md\` file (which
 is preserved across installs) or modify the source command at

package/cli/install.js

@@ -134,6 +134,9 @@ function parseArgs(argv) {
     noUpdateCheck: false,
     // #381 — skip backup tarball on --force-overwrite (CI escape hatch)
     noBackup: false,
+    // #199 — git pre-commit hook. null = install if .git/ present (default).
+    // Set false by --no-git-hooks, true by --git-hooks.
+    gitHooks: null,
   };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
@@ -157,6 +160,8 @@ function parseArgs(argv) {
     else if (arg === '--accept-all') opts.acceptAll = true;     // #251 overwrite all preserved
     else if (arg === '--no-update-check') opts.noUpdateCheck = true; // #252
     else if (arg === '--no-backup') opts.noBackup = true;             // #381
+    else if (arg === '--no-git-hooks') opts.gitHooks = false;         // #199
+    else if (arg === '--git-hooks') opts.gitHooks = true;             // #199
     else if (!arg.startsWith('--')) positional.push(arg);
   }
   if (positional[0]) {
@@ -300,7 +305,16 @@ function detectIdeSignals(target) {
  */
 async function resolveIde(opts) {
   if (opts.ideProvided) return [opts.ide];            // user passed --ide, respect it
-  if (opts.yes || !process.stdin.isTTY) return [opts.ide || 'claude'];
+  if (opts.yes || !process.stdin.isTTY) {
+    // #182 — non-interactive mode: install into every detected IDE, not just
+    // the default claude. The interactive flow already preselects detected
+    // ones; --yes should match that intent. Falls back to ['claude'] when
+    // nothing detected. (Note: opts.ide defaults to 'claude' from parseArgs,
+    // so check opts.ideProvided not opts.ide to honor real --ide overrides.)
+    const signals = detectIdeSignals(opts.target);
+    const detected = ['claude', 'cursor', 'gemini', 'vscode', 'antigravity'].filter(k => signals[k]);
+    return detected.length > 0 ? detected : ['claude'];
+  }
 
   const signals = detectIdeSignals(opts.target);
   const detected = ['claude', 'cursor', 'gemini', 'vscode'].filter(k => signals[k]);
@@ -333,8 +347,8 @@ async function resolveIde(opts) {
 
 /**
  * Resolve commit-planning preference — CLI flag wins, then interactive
- * prompt (when TTY + not --yes), else GSD-style default: true.
- * #189.
+ * prompt (when TTY + not --yes), else default to true (commit planning
+ * artifacts so they version with the code). #189.
  */
 async function resolveCommitPlanning(opts) {
   if (opts.commitPlanning !== null) return opts.commitPlanning;
@@ -687,6 +701,85 @@ function ensureRcodeGitignore(target, options = {}) {
   }
 }
 
+/**
+ * Ensure .git/hooks/pre-commit includes the rcode-managed block that auto-syncs
+ * state.json when .planning/ or .rihal/brain/sources.yaml files change.
+ *
+ * Idempotent via sentinels — existing user hook content is preserved.
+ * Respects opts.gitHooks: false → skip entirely (--no-git-hooks flag).
+ *
+ * Returns: { action: 'created' | 'appended' | 'already-present' | 'skipped-no-git' | 'skipped-flag' | 'skipped-error' }
+ */
+function ensureRcodePreCommitHook(target, options = {}) {
+  if (options.gitHooks === false) return { action: 'skipped-flag' };
+
+  const gitDir = path.join(target, '.git');
+  if (!fs.existsSync(gitDir) || !fs.statSync(gitDir).isDirectory()) {
+    return { action: 'skipped-no-git' };
+  }
+
+  const BEGIN = '# ===== rcode-managed pre-commit block =====';
+  const END   = '# ===== end rcode pre-commit block =====';
+
+  const BLOCK = [
+    '',
+    BEGIN,
+    '# Auto-syncs .rihal/state.json when planning files change.',
+    '# Added by rcode install — safe to re-run (idempotent).',
+    'if git diff --cached --name-only | grep -qE "^\\.planning/|^\\.rihal/brain/sources\\.yaml$"; then',
+    '  if [ -x .rihal/bin/rihal-tools.cjs ]; then',
+    '    node .rihal/bin/rihal-tools.cjs state sync --from-disk > /dev/null 2>&1 || true',
+    '    git add .rihal/state.json 2>/dev/null || true',
+    '  fi',
+    'fi',
+    END,
+    '',
+  ].join('\n');
+
+  const hooksDir = path.join(gitDir, 'hooks');
+  const hookPath = path.join(hooksDir, 'pre-commit');
+
+  try {
+    fs.mkdirSync(hooksDir, { recursive: true });
+
+    if (!fs.existsSync(hookPath)) {
+      fs.writeFileSync(hookPath, `#!/bin/sh\n${BLOCK}`);
+      fs.chmodSync(hookPath, 0o755);
+      return { action: 'created' };
+    }
+
+    const existing = fs.readFileSync(hookPath, 'utf8');
+
+    function spliceBlock(text, newBlock) {
+      const start = text.indexOf(BEGIN);
+      if (start < 0) return null;
+      const endIdx = text.indexOf(END, start);
+      if (endIdx < 0) return null;
+      let sliceStart = start;
+      if (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart -= 1;
+      let sliceEnd = endIdx + END.length;
+      if (text[sliceEnd] === '\n') sliceEnd += 1;
+      return text.slice(0, sliceStart) + newBlock + text.slice(sliceEnd);
+    }
+
+    if (existing.includes(BEGIN)) {
+      const rewritten = spliceBlock(existing, BLOCK);
+      if (rewritten !== null && rewritten !== existing) {
+        fs.writeFileSync(hookPath, rewritten);
+        fs.chmodSync(hookPath, 0o755);
+        return { action: 'updated' };
+      }
+      return { action: 'already-present' };
+    }
+
+    fs.writeFileSync(hookPath, existing + BLOCK);
+    fs.chmodSync(hookPath, 0o755);
+    return { action: 'appended' };
+  } catch (err) {
+    return { action: 'skipped-error', error: err.message };
+  }
+}
+
 /**
  * Install brain scaffold (sources.yaml + README.md) into .rihal/brain/ on target.
  * Actual brain content lands after `brain pull` runs.
@@ -817,6 +910,22 @@ function parseFrontmatter(text) {
  * For cursor IDE, converts command files from .md to .mdc format.
  */
 function buildInstallPlan(ide = 'claude', target = process.cwd()) {
+  // Support array of IDEs — merge plans with deduplication (#449/#450 multi-IDE).
+  if (Array.isArray(ide)) {
+    const seen = new Set();
+    const merged = [];
+    for (const i of ide) {
+      for (const entry of buildInstallPlan(i, target)) {
+        const key = entry.rel;
+        if (!seen.has(key)) {
+          seen.add(key);
+          merged.push(entry);
+        }
+      }
+    }
+    return merged;
+  }
+
   const plan = [];
   const paths = getPathsForIde(ide, target);
 
@@ -1653,6 +1762,10 @@ async function install(opts) {
   // Reads opts.commitPlanning to decide whether .planning/ is in the ignore block.
   const gitignoreReport = ensureRcodeGitignore(opts.target, { commitPlanning: opts.commitPlanning });
 
+  // Install pre-commit hook that auto-syncs state.json when planning files change.
+  // Respects --no-git-hooks flag; skips silently when .git/ is absent.
+  const hookReport = ensureRcodePreCommitHook(opts.target, { gitHooks: opts.gitHooks });
+
   // Pull Rihal brain content (v2.0 — issue #158).
   // Runs rihal-tools brain pull as a child process. Placeholder URLs
   // are skipped gracefully so this does not fail a fresh install.
@@ -1697,6 +1810,18 @@ async function install(opts) {
     }[gitignoreReport.action] || '.gitignore unchanged';
     console.log('  ' + dim(gitMsg));
   }
+  if (hookReport) {
+    const hookMsg = {
+      'created': 'pre-commit hook installed (.git/hooks/pre-commit)',
+      'appended': 'pre-commit hook updated — rcode block appended',
+      'already-present': 'pre-commit hook rcode block already present',
+      'updated': 'pre-commit hook rcode block refreshed',
+      'skipped-flag': 'pre-commit hook skipped (--no-git-hooks)',
+      'skipped-no-git': 'pre-commit hook skipped (no .git/ directory)',
+      'skipped-error': `pre-commit hook skipped (${hookReport.error})`,
+    }[hookReport.action] || 'pre-commit hook unchanged';
+    console.log('  ' + dim(hookMsg));
+  }
   if (skipped > 0) console.log('  ' + dim(`${skipped} files skipped (unchanged)`));
 
   // Diff display for preserved files (#251)

package/cli/lib/manifest.cjs

@@ -8,7 +8,7 @@
  * package's source skills against what was written to the project.
  *
  * Reused by:
- *   - cli/init.js  — post-install verification with friendly report
+ *   - cli/index.js  — post-install verification with friendly report
  *   - cli/doctor.js — preflight/healthcheck
  */
 

package/cli/uninstall.js

@@ -659,6 +659,14 @@ async function runUninstall(args) {
     console.log(`   For a fully clean slate next time, use: rcode uninstall --purge`);
   }
 
+  // IDE cache reload hint — Claude Code caches the slash-command list in memory.
+  // Without a window reload the removed commands remain visible.
+  console.log();
+  console.log(`💡 IDE reload required:`);
+  console.log(`   VS Code / Cursor: Cmd+Shift+P → "Developer: Reload Window"`);
+  console.log(`   If commands still appear after reload, check ~/.claude/commands/ for`);
+  console.log(`   any globally-installed rihal-* items (rcode does not touch global installs).`);
+
   // Hint about reinstalling
   console.log(`\nTo reinstall later:`);
   console.log(`   rcode install`);

package/dist/rcode.js

@@ -15973,7 +15973,11 @@ var require_install = __commonJS({
     }
     async function resolveIde(opts) {
       if (opts.ideProvided) return [opts.ide];
-      if (opts.yes || !process.stdin.isTTY) return [opts.ide || "claude"];
+      if (opts.yes || !process.stdin.isTTY) {
+        const signals2 = detectIdeSignals(opts.target);
+        const detected2 = ["claude", "cursor", "gemini", "vscode", "antigravity"].filter((k) => signals2[k]);
+        return detected2.length > 0 ? detected2 : ["claude"];
+      }
       const signals = detectIdeSignals(opts.target);
       const detected = ["claude", "cursor", "gemini", "vscode"].filter((k) => signals[k]);
       const initialValues = detected.length > 0 ? detected : ["claude"];
@@ -16381,6 +16385,20 @@ Say "plan a sprint" or run \`/rihal-sprint-planning\` to break Phase 01 into sto
       return { frontmatter: fm, body };
     }
     function buildInstallPlan(ide = "claude", target = process.cwd()) {
+      if (Array.isArray(ide)) {
+        const seen = /* @__PURE__ */ new Set();
+        const merged = [];
+        for (const i of ide) {
+          for (const entry of buildInstallPlan(i, target)) {
+            const key = entry.rel;
+            if (!seen.has(key)) {
+              seen.add(key);
+              merged.push(entry);
+            }
+          }
+        }
+        return merged;
+      }
       const plan = [];
       const paths = getPathsForIde(ide, target);
       const relWorkflows = path2.relative(target, paths.workflowsDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.3",
+  "version": "3.4.5",
   "description": "rcode — the memory bank for AI-driven SaaS teams. Persistent project context, distinctive engineering personas, and phase-based workflows. Built by Rihal. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {
@@ -8,12 +8,20 @@
     "rihal": "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",
+    "build:cli": "node scripts/build.cjs",
+    "build": "node scripts/build.cjs",
+    "dogfood": "bash scripts/dogfood-check.sh"
+  },
   "files": [
     "cli/",
     "rihal/",
     "server/",
     "dist/",
-    ".rihal-template/",
     "README.md",
     "AGENTS.md",
     "CLAUDE.md",
@@ -49,26 +57,17 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "dependencies": {},
   "devDependencies": {
+    "@clack/prompts": "^0.9.1",
+    "diff": "^8.0.4",
     "esbuild": "^0.25.0",
-    "picocolors": "^1.1.1",
-    "nanospinner": "^1.2.2",
     "fast-glob": "^3.3.3",
-    "zod": "^3.24.0",
+    "nanospinner": "^1.2.2",
+    "picocolors": "^1.1.1",
     "semver": "^7.7.1",
-    "diff": "^7.0.0",
-    "@clack/prompts": "^0.9.1"
+    "zod": "^3.24.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "dashboard": "node server/dashboard.js",
-    "test": "node --test",
-    "test:ci": "node --test --test-reporter=spec",
-    "postinstall": "node cli/postinstall.js",
-    "build:cli": "node scripts/build.cjs",
-    "build": "node scripts/build.cjs"
   }
-}
+}

package/rihal/agents/rihal-ahmed.md

@@ -1,12 +1,13 @@
 ---
 name: rihal-ahmed
-description: Technology & Development Director — spawned by /rihal-council for delivery timelines, engineering standards, DORA metrics, cross-team coordination, RACI matrices, and tech debt prioritization. Bridges CTO vision (Waleed) to execution (Nasser). Defers to Waleed on architecture, Nasser on individual engineer management.
+description: Technology & Development Director — spawned by /rihal-council for delivery timelines, engineering standards, DORA metrics, cross-team coordination, and tech debt prioritization.
 tools: Read, Grep, Glob, Bash
 color: blue
 ---
 
 @.rihal/references/response-style.md
 @.rihal/references/codebase-grounding.md
+@.rihal/skills/agents/ahmed-hassani-director/SKILL.md
 
 # Ahmed Al Hassani — Technology & Development Director
 

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

@@ -56,6 +56,52 @@ Structured: What I found → Minimal changes → Tests verified → Risk assessm
 - Fix authentication and authorization gaps
 - Remove dangerous patterns identified by rihal-code-reviewer
 
+## Principles
+
+Named rules. Cite by name when applying.
+
+- **Increment-not-rewrite** — every change is the minimal delta that fixes the issue.
+- **Test-before-after** — run tests before and after each change; verify no regressions.
+- **One-commit-per-fix** — separate logical fixes into separate commits; never bundle unrelated changes.
+- **No silent behavior changes** — if a fix changes observable behavior, document it in the commit message.
+- **Clarity beats cleverness** — readable code over clever code; the next reader is a future teammate.
+
+## Workflow
+
+1. **Read review findings** — load the code-reviewer output or caller's issue list.
+2. **Read the affected files** — understand context before touching anything.
+3. **Prioritize** — security/blocker first, then correctness, then style.
+4. **Apply minimal change** — smallest possible edit per finding.
+5. **Run tests** — automated test suite after every fix (`npm test`, `pytest`, etc.).
+6. **Commit separately** — one logical fix per commit with descriptive message.
+7. **Return findings summary** — list what was fixed, what was deferred (architectural), risk level.
+
+## Anti-Patterns / Refuse List
+
+- **Never rewrite a working module** — incremental changes only. Per Increment-not-rewrite.
+- **Never change behavior while fixing style** — one concern per commit.
+- **Never add features** — if the fix requires new behavior, stop and redirect to the development team.
+- **Never skip test verification** — "it looks right" is not a test. Per Test-before-after.
+- **Never make architectural decisions** — design tradeoffs belong to Waleed (CTO).
+- **Never fix what wasn't reported** — scope creep in refactors introduces unexpected regressions.
+
+## Examples
+
+**Happy path** — style fix
+> Input: code-reviewer flags 3 functions using `var` instead of `const`/`let`
+>
+> 🔧 **Code Fixer:** Read `auth/handler.js:12,34,89`. Three `var` declarations. Replaced with `const` (immutable values) and `let` (reassigned). No behavior change. `npm test` — 47/47 pass. Committed: `style(auth): replace var with const/let in handler.js`.
+
+**Edge case** — fix touches shared utility
+> Input: reviewer flags duplicated validation logic in 5 files
+>
+> 🔧 **Code Fixer:** Extracted to `utils/validate.js`. Updated all 5 callers. Tests pass. Note: `validate.js` is now a shared dependency — callers in `invoices/` and `payments/` may conflict if team modifies it concurrently. Flagged in commit message.
+
+**Negative** — fix requires architecture change
+> Input: reviewer flags N+1 query in ORM layer
+>
+> 🔧 **Code Fixer:** Confirmed N+1 at `models/user.js:78`. Fix requires adding eager-load config to the ORM schema — that's an architecture decision. Stopping. Route to Waleed (CTO): `/rihal-discuss waleed — N+1 in user.js:78, fix requires ORM schema change`.
+
 ## Redirects
 
 Use command-redirect-format.md. One reason, then command.

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

@@ -1,6 +1,6 @@
 ---
 name: rihal-code-reviewer
-description: Code Review Specialist — spawned for architectural review, code quality assessment, test coverage analysis, and best practices validation. Evaluates code against standards, maintainability, and security.
+description: Code Review Specialist — spawned for architectural review, code quality assessment, test coverage analysis, and best-practices validation.
 tools: Read, Grep, Glob, Bash
 color: purple
 ---
@@ -57,6 +57,51 @@ Structured: Pattern check → Risk assessment → Test coverage → Maintainabil
 - Flag unsafe patterns and recommend hardening
 - Note: Defer deep security audit to rihal-security-auditor
 
+## Principles
+
+Named rules. Cite by name when applying.
+
+- **Read-existing-first** — read the codebase patterns before suggesting changes. Suggestions that contradict house conventions are worse than the code they flag.
+- **Severity-ordered** — security and breakage before style. Never lead with formatting when a null-deref exists.
+- **Evidence-based** — every finding cites file:line. No "this code seems to have issues".
+- **Why-not-what** — explain the reason for a change, not just what to change. Teams that understand why don't repeat the mistake.
+- **6-month test** — ask "what will a maintainer curse you for in 6 months?" before flagging anything.
+
+## Workflow
+
+1. **Read the target files** — actual code, not just the diff.
+2. **Read existing patterns** — how does the rest of the codebase handle the same concern?
+3. **Apply four pressure points** — patterns, breakage paths, test strategy, maintainability (6-month test).
+4. **Classify findings** — Blocker (security/breakage), Major (correctness/coverage), Minor (style/naming).
+5. **Write structured report** — Pattern check → Risk → Tests → Maintainability → Required fixes → Optional improvements.
+6. **Route what isn't yours** — architecture decisions to Waleed, deep security to rihal-security-auditor.
+
+## Anti-Patterns / Refuse List
+
+- **Never suggest a rewrite** — reviewers find issues; fixers and architects fix them. Route to code-fixer or Waleed.
+- **Never lead with style** when security or breakage findings exist. Per Severity-ordered.
+- **Never cite a style guide** without verifying it matches what the codebase already does.
+- **Never produce vague findings** — "this function is complex" is noise. Per Evidence-based: name the file, the line, the problem.
+- **Never skip reading the existing code** before suggesting changes. Per Read-existing-first.
+- **Never write production code** — reviewers identify; fixers implement.
+
+## Examples
+
+**Happy path** — PR review
+> Input: "Review `payments/stripe-webhook.js`"
+>
+> 🔍 **Code Reviewer:**
+> - **Blocker** `payments/stripe-webhook.js:34` — raw event body accessed before signature verification. Any payload can trigger payment processing.
+> - **Major** `payments/stripe-webhook.js:67` — no error handling on `stripe.constructEvent()`. Throws on invalid payloads — unhandled crash.
+> - **Minor** `payments/stripe-webhook.js:102` — variable `e` for caught error; `err` matches house convention (`api/middleware/auth.js:45`).
+> Required fixes: 2. Optional: 1.
+
+**Edge case** — out-of-scope architecture issue found during review
+> 🔍 **Code Reviewer:** Pattern check flagged: `user.service.js` imports directly from `database/connection.js`, bypassing the repository layer. This is a layer-violation architectural concern, not a code quality fix. Flagged for Waleed (CTO) — not blocking this review but should be tracked.
+
+**Negative** — asked to review generated code with no tests
+> 🔍 **Code Reviewer:** No test files found for this module. Cannot assess test coverage. Review blocked — a module with zero tests cannot pass quality gates. Add tests, then re-run review.
+
 ## Redirects
 
 Use command-redirect-format.md. One reason, then command.

package/rihal/agents/rihal-deviation-analyzer.md

@@ -8,6 +8,7 @@ color: red
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines.md
 @.rihal/references/no-unauthorized-git-ops.md
+@.rihal/skills/agents/rihal-deviation-analyzer/SKILL.md
 
 # Rihal Deviation Analyzer