@hanzlaa/rcode 3.4.4 → 3.4.6

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)
  */
 
@@ -32,11 +32,23 @@ const path = require('path');
  * lifecycle verbs. Internal sub-commands stay slash-only.
  */
 const SIDEBAR_COMMANDS = new Set([
-  'do', 'status', 'progress', 'next', 'plan', 'execute',
-  'council', 'discuss', 'ship', 'audit', 'autonomous',
-  'session-report', 'forensics', 'health', 'debug',
-  'verify-phase', 'verify-work', 'review', 'code-review',
+  // Navigation & status
+  'do', 'status', 'progress', 'next', 'health',
+  // Core planning & execution
+  'plan', 'execute', 'add-phase', 'discuss-phase', 'complete-milestone',
+  'plan-milestone-gaps', 'autonomous',
+  // Project setup
   'new-project', 'new-milestone', 'milestone-summary',
+  // Sprint workflow
+  'sprint-planning', 'sprint-status', 'execute-sprint', 'dev-story',
+  'create-story', 'create-epics-and-stories',
+  // Discussion & council
+  'council', 'discuss', 'prfaq',
+  // Quality & review
+  'ship', 'audit', 'verify-phase', 'verify-work', 'review', 'code-review',
+  'feature-drift', 'ui-phase', 'ui-review',
+  // Utility
+  'debug', 'session-report', 'forensics', 'map-codebase', 'quick',
   'note', 'add-todo', 'check-todos', 'pause-work', 'resume-work',
 ]);
 
@@ -99,7 +111,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;
@@ -394,7 +408,7 @@ function getPathsForIde(ide, target) {
     case 'claude':
       return {
         agentsDir: path.join(target, '.claude', 'agents'),
-        commandsDir: path.join(target, '.claude', 'commands', 'rihal'),
+        commandsDir: path.join(target, '.claude', 'commands'),
         workflowsDir: path.join(target, '.rihal', 'workflows'),
         referencesDir: path.join(target, '.rihal', 'references'),
         binDir: path.join(target, '.rihal', 'bin'),
@@ -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.
@@ -878,10 +971,15 @@ function buildInstallPlan(ide = 'claude', target = process.cwd()) {
   }
 
   // Commands — IDE-specific
+  // Claude: output as .claude/commands/rihal-{name}.md (hyphen namespace → /rihal-name)
+  // Cursor/Gemini: keep original flat name inside their rihal/ subdirectory
   for (const f of walkFiles(path.join(SOURCE_ROOT, 'commands'))) {
     const rel = path.relative(path.join(SOURCE_ROOT, 'commands'), f);
     const ext = ide === 'cursor' ? '.mdc' : '.md';
-    const outName = path.basename(f, '.md') + ext;
+    const baseName = path.basename(f, '.md');
+    const outName = ide === 'claude'
+      ? `rihal-${baseName}${ext}`
+      : baseName + ext;
     plan.push({ src: f, rel: path.join(relCommands, path.dirname(rel), outName), ide, cursor: ide === 'cursor' });
   }
 
@@ -957,7 +1055,7 @@ function filterPlanByModules(plan, moduleNames) {
     if (!mod) { console.warn(`  ⚠ Unknown module: ${modName}`); continue; }
     for (const a of mod.agents) allowed.add(path.join('.claude', 'agents', a));
     for (const w of mod.workflows) allowed.add(path.join('.rihal', 'workflows', w));
-    for (const c of mod.commands) allowed.add(path.join('.claude', 'commands', 'rihal', c));
+    for (const c of mod.commands) allowed.add(path.join('.claude', 'commands', `rihal-${c}`));
     for (const r of mod.references) allowed.add(path.join('.rihal', 'references', r));
   }
   // Always include bin/ (shared infrastructure, not module-specific)
@@ -1669,6 +1767,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.
@@ -1713,6 +1815,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)
@@ -1749,7 +1863,12 @@ async function install(opts) {
       agentCount = fs.readdirSync(agentsDir).filter(f => (f.startsWith('rihal-') || f.startsWith('rcode-')) && (f.endsWith('.md') || f.endsWith('.mdc'))).length;
     }
     if (fs.existsSync(commandsDir)) {
-      commandCount = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md') || f.endsWith('.mdc')).length;
+      commandCount = fs.readdirSync(commandsDir).filter(f => f.startsWith('rihal-') && (f.endsWith('.md') || f.endsWith('.mdc'))).length;
+    }
+    // Clean up legacy .claude/commands/rihal/ colon-namespace directory if it exists
+    const legacyColonDir = path.join(opts.target, '.claude', 'commands', 'rihal');
+    if (primaryIde === 'claude' && fs.existsSync(legacyColonDir)) {
+      fs.rmSync(legacyColonDir, { recursive: true, force: true });
     }
   } catch {}
 

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`);