@hanzlaa/rcode 4.4.3 → 4.5.0

package/AGENTS.md

@@ -68,8 +68,8 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 ## Dashboard Server Rules
 
-- Keep `server/dashboard.js` dependency-free (pure Node stdlib)
-- Single-file — do not introduce a framework
+- `server/dashboard.js` is the entry point; server-side logic lives in `server/lib/` (`api.js`, `scanner.js`, `html/`) and `server/orchestrator.js` — split across files, not single-file
+- No external framework dependency on the server or client — the client is a Preact SPA built on a vendored copy (`server/lib/html/client/vendor/preact.js`), not an npm package; keep it that way
 - View-only — NEVER add write endpoints, POST handlers, or database code
 - Test after every change: `node server/dashboard.js` must start cleanly
 
@@ -84,9 +84,16 @@ If a user says "just keep going" or "don't stop until done", that authorization
   node cli/doctor.js                       # full preflight + compliance
   node --test test/artifact-schema.test.cjs   # schema validators only
   ```
-- Run grep checks before committing renames or refactors:
+- Run grep checks before committing renames or refactors. Scope to `TODO:`
+  and code files only — `rcode/`, `docs/`, and skill/workflow markdown
+  legitimately discuss the concept of TODOs (stub-detection guides, the
+  `add-todo`/`check-todos` commands, checklists); an unscoped `-i "TODO"`
+  grep will always be red on this repo:
   ```bash
-  grep -rn -i "TODO" rcode docs examples README.md server   # should be empty
+  grep -rn "TODO:" rcode docs examples README.md server \
+    --include="*.js" --include="*.cjs" --include="*.mjs" --include="*.ts"
+  # should be empty, or only match deliberate string/regex literals
+  # (e.g. rcode/bin/rcode-hooks.cjs's hedging-language detector)
   ```
 - Test the dashboard server boots without errors before committing dashboard changes
 

package/CLAUDE.md

@@ -58,8 +58,8 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 ## Dashboard Server Rules
 
-- Keep `server/dashboard.js` dependency-free (pure Node stdlib)
-- Single-file — do not introduce a framework
+- `server/dashboard.js` is the entry point; server-side logic lives in `server/lib/` (`api.js`, `scanner.js`, `html/`) and `server/orchestrator.js` — split across files, not single-file
+- No external framework dependency on the server or client — the client is a Preact SPA built on a vendored copy (`server/lib/html/client/vendor/preact.js`), not an npm package; keep it that way
 - View-only — NEVER add write endpoints, POST handlers, or database code
 - Test after every change: `node server/dashboard.js` must start cleanly
 
@@ -74,9 +74,16 @@ If a user says "just keep going" or "don't stop until done", that authorization
     grep -q "^## Examples" "$f" || echo "MISSING: $f"
   done
   ```
-- Run grep checks before committing renames or refactors:
+- Run grep checks before committing renames or refactors. Scope to `TODO:`
+  and code files only — `rcode/`, `docs/`, and skill/workflow markdown
+  legitimately discuss the concept of TODOs (stub-detection guides, the
+  `add-todo`/`check-todos` commands, checklists); an unscoped `-i "TODO"`
+  grep will always be red on this repo:
   ```bash
-  grep -rn -i "TODO" rcode docs examples README.md server   # should be empty
+  grep -rn "TODO:" rcode docs examples README.md server \
+    --include="*.js" --include="*.cjs" --include="*.mjs" --include="*.ts"
+  # should be empty, or only match deliberate string/regex literals
+  # (e.g. rcode/bin/rcode-hooks.cjs's hedging-language detector)
   ```
 - Test the dashboard server boots without errors before committing dashboard changes
 

package/CONTRIBUTING.md

@@ -399,7 +399,12 @@ chore(github): import Siraaj commit and PR rules
    ```
 4. **Grep for regressions:**
    ```bash
-   grep -rn -i "TODO" rcode docs examples README.md server   # should be empty
+   # Scope to "TODO:" and code files — rcode/, docs/, and skill/workflow
+   # markdown legitimately discuss TODOs (stub-detection guides, the
+   # add-todo/check-todos commands); an unscoped -i "TODO" grep is always red.
+   grep -rn "TODO:" rcode docs examples README.md server \
+     --include="*.js" --include="*.cjs" --include="*.mjs" --include="*.ts"
+   # should be empty, or only match deliberate string/regex literals
    grep -rn "ahmed" rcode docs README.md server | grep -v "ahmed-hassani\|Ahmed Al Hassani"   # should be empty
    ```
 

package/README.md

@@ -23,7 +23,7 @@ pnpm dlx @hanzlaa/rcode install
 [![CI](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml/badge.svg)](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Status: `@hanzlaa/rcode` v4.4.3 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
+Status: `@hanzlaa/rcode` v4.4.4 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
 
 ---
 

package/cli/doctor.js

@@ -17,6 +17,8 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { verifyInstall, formatReport } = require('./lib/manifest.cjs');
 const { checkStaleness } = require('./lib/memory-bank.cjs');
+const { homedir } = require('./lib/homedir.cjs');
+const { scanNamespaceDuplication } = require('./lib/namespace-migrate.cjs');
 const {
   parseFrontmatter,
   validateSkillFrontmatter,
@@ -102,6 +104,29 @@ function commandAvailable(cmd) {
   return result.status === 0;
 }
 
+/**
+ * Detect phases stuck at status 'executing' while a numerically later phase
+ * has already reached 'complete'. That combination only happens when an
+ * executor crashed/was killed without updating state.json — a real phase
+ * would never be marked complete while an earlier one is still mid-run.
+ * Read-only; used by `rcode doctor` to flag stale state for manual repair.
+ */
+function findStuckExecutingPhases(state) {
+  const phases = Array.isArray(state?.phases) ? state.phases : [];
+  const executing = phases.filter((p) => p && p.status === 'executing');
+  if (executing.length === 0) return [];
+  const maxCompleteNumber = phases
+    .filter((p) => p && p.status === 'complete')
+    .map((p) => parseFloat(p.number))
+    .filter((n) => !Number.isNaN(n))
+    .reduce((max, n) => Math.max(max, n), -Infinity);
+  if (maxCompleteNumber === -Infinity) return [];
+  return executing.filter((p) => {
+    const n = parseFloat(p.number);
+    return !Number.isNaN(n) && n < maxCompleteNumber;
+  });
+}
+
 // ---------- Preflight checks ----------
 
 /**
@@ -192,6 +217,36 @@ function runPreflight(cwd, packageRoot) {
       : 'not found (github-sync unavailable)',
   });
 
+  // 5b. Namespace duplication (#954) — legacy rihal-* entries whose rcode-*
+  // twin already exists, plus unprefixed/cross-scope command dupes. Doesn't
+  // require .rcode/ init since it inspects .claude/ directly. Read-only —
+  // fix path is `rcode update` or `rcode migrate-namespace --yes`.
+  try {
+    const nsDup = scanNamespaceDuplication(cwd, homedir());
+    if (nsDup.totalCount > 0) {
+      checks.push({
+        label: 'Namespace duplication',
+        status: 'warn',
+        message:
+          `${nsDup.totalCount} duplicate registration(s) — legacy skills: ${nsDup.legacySkillCount}, ` +
+          `legacy commands: ${nsDup.legacyCommandCount}, unprefixed: ${nsDup.unprefixedCount}, ` +
+          `cross-scope: ${nsDup.crossScopeCount} (run \`rcode migrate-namespace --yes\` or \`rcode update\`)`,
+      });
+    } else {
+      checks.push({
+        label: 'Namespace duplication',
+        status: 'ok',
+        message: 'no duplicate rihal-*/rcode-* registrations found',
+      });
+    }
+  } catch (e) {
+    checks.push({
+      label: 'Namespace duplication',
+      status: 'warn',
+      message: `could not scan: ${e.message}`,
+    });
+  }
+
   // 6. Agent manifest drift (only if .rcode/ is initialized — indicates installed editors)
   if (fs.existsSync(rcodeDir)) {
     const editors = [];
@@ -254,6 +309,69 @@ function runPreflight(cwd, packageRoot) {
         message: `STALE — ${staleness.reasons[0]}${staleness.reasons.length > 1 ? ` (+${staleness.reasons.length - 1} more)` : ''}`,
       });
     }
+
+    // 8. .rcode/data/intent-table.json presence (#952/#954). Installer ships
+    // rcode/data/ into consumer projects as of #952; if it's missing, the
+    // prompt-router degrades to a no-op with no visible error. Warn-only —
+    // the fail-open behavior in rcode-hooks.cjs keeps hooks working either way.
+    const intentTablePath = path.join(rcodeDir, 'data', 'intent-table.json');
+    checks.push({
+      label: 'intent-table.json',
+      status: fs.existsSync(intentTablePath) ? 'ok' : 'warn',
+      message: fs.existsSync(intentTablePath)
+        ? path.relative(cwd, intentTablePath)
+        : 'missing — run `npx @hanzlaa/rcode update` to sync .rcode/data/',
+    });
+
+    // 9. Stale phase state — a phase stuck 'executing' while a numerically
+    // later phase has already reached 'complete' means an executor died
+    // without updating state.json. Warn-only; fix is manual state repair.
+    const statePath = path.join(rcodeDir, 'state.json');
+    if (fs.existsSync(statePath)) {
+      try {
+        const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        const stuck = findStuckExecutingPhases(state);
+        checks.push({
+          label: 'Phase state',
+          status: stuck.length > 0 ? 'warn' : 'ok',
+          message:
+            stuck.length > 0
+              ? `${stuck.length} phase(s) stuck 'executing' while a later phase is complete: ${stuck.map((p) => p.number).join(', ')}`
+              : 'no stuck phases',
+        });
+      } catch (e) {
+        checks.push({
+          label: 'Phase state',
+          status: 'warn',
+          message: `state.json unreadable: ${e.message}`,
+        });
+      }
+    }
+
+    // 10. Memory INDEX.md staleness — separate from the fingerprint-based
+    // "Memory bank" check above (#7), which tracks .rcode/context/. This is
+    // a simple wall-clock check on .rcode/memory/INDEX.md, the distilled
+    // memory index every workflow reads.
+    const memoryIndexPath = path.join(rcodeDir, 'memory', 'INDEX.md');
+    if (fs.existsSync(memoryIndexPath)) {
+      const ageDays = Math.floor(
+        (Date.now() - fs.statSync(memoryIndexPath).mtimeMs) / (24 * 60 * 60 * 1000),
+      );
+      checks.push({
+        label: 'Memory INDEX.md',
+        status: ageDays > 30 ? 'warn' : 'ok',
+        message:
+          ageDays > 30
+            ? `STALE — last updated ${ageDays}d ago (run /rcode-memory-update)`
+            : `fresh — updated ${ageDays}d ago`,
+      });
+    } else {
+      checks.push({
+        label: 'Memory INDEX.md',
+        status: 'warn',
+        message: 'missing (run /rcode-memory-init)',
+      });
+    }
   }
 
   return checks;
@@ -479,3 +597,7 @@ module.exports = function doctor(args, { packageRoot }) {
   console.log();
   process.exit(totalFailures > 0 ? 1 : 0);
 };
+
+// Re-exports for unit tests.
+module.exports.findStuckExecutingPhases = findStuckExecutingPhases;
+module.exports.runPreflight = runPreflight;

package/cli/index.js

@@ -27,6 +27,7 @@ const COMMANDS = {
   uninstall: require('./uninstall'),
   remove: require('./uninstall'),  // alias
   nuke: require('./nuke'),         // full cleanup across all package managers + global state
+  'migrate-namespace': require('./migrate-namespace'), // clean up legacy rihal-* dupes (#954)
   dashboard: require('./dashboard'),
   serve: require('./dashboard'),
   digest: require('./digest'),
@@ -73,6 +74,9 @@ Usage:
                  binaries, ~/.claude/* rcode artifacts, ~/.rcode/, project artifacts)
                  Default = dry-run. Pass --yes to remove. Pass --include-planning
                  to also remove .planning/ in CWD.
+  migrate-namespace  Back up + remove legacy rihal-* skills/commands whose
+                 rcode-* twin exists, plus unprefixed/cross-scope command dupes.
+                 Default = dry-run. Pass --yes to remove. Idempotent.
   config         Get/set project configuration (project_name, user_name, etc.)
   context        Memory bank freshness (--check | --refresh | --install-hook)
   github-sync    Sync .rcode/ phases/epics/stories to GitHub (dry-run default)

package/cli/install.js

@@ -888,6 +888,7 @@ function ensureRcodeGitignore(target, options = {}) {
     '# Installed methodology files (regenerate with: npx @hanzlaa/rcode install)',
     '.claude/',
     '.rcode/bin/',
+    '.rcode/data/',
     '.rcode/workflows/',
     '.rcode/references/',
     '.rcode/commands/',
@@ -1310,6 +1311,12 @@ function buildInstallPlan(ide = 'claude', target = process.cwd()) {
     plan.push({ src: f, rel: path.join(relBin, rel), executable: f.endsWith('.cjs') });
   }
 
+  // .rcode/data/
+  for (const f of walkFiles(path.join(SOURCE_ROOT, 'data'))) {
+    const rel = path.relative(path.join(SOURCE_ROOT, 'data'), f);
+    plan.push({ src: f, rel: path.join('.rcode', 'data', rel) });
+  }
+
   // .rcode/templates/projects/  — starter templates consumed by /rcode-from-template
   const projectTemplatesSrc = path.join(SOURCE_ROOT, 'templates', 'projects');
   const relProjectTemplates = path.relative(target, path.join(target, '.rcode', 'templates', 'projects'));
@@ -1418,6 +1425,7 @@ function filterPlanByModules(plan, moduleNames) {
   // Always include bin/ (shared infrastructure, not module-specific)
   return plan.filter((entry) => {
     if (entry.rel.startsWith(path.join('.rcode', 'bin'))) return true;
+    if (entry.rel.startsWith(path.join('.rcode', 'data'))) return true;
     return allowed.has(entry.rel);
   });
 }

package/cli/lib/namespace-migrate.cjs

@@ -0,0 +1,216 @@
+'use strict';
+/**
+ * Legacy rihal-* → rcode-* namespace cleanup (#954).
+ *
+ * The rcode↔rihal rename left rihal-* skills/commands installed alongside
+ * their rcode-* twins everywhere — every session loaded each command 2-4x.
+ * This module scans for safe-to-remove legacy artifacts (a rihal-* entry is
+ * only ever flagged when its rcode-* twin already exists — never delete
+ * something with no replacement) and, on request, backs them up under
+ * ~/.claude/.rcode-backup/<timestamp>/ before deleting.
+ *
+ * Read-only scan functions (findLegacyRihalArtifacts, findUnprefixedTwinDupes,
+ * findCrossScopeDupes, scanNamespaceDuplication) are reused by `rcode doctor`
+ * for report-only checks. The destructive migrateNamespace() is reused by
+ * `rcode update` and `rcode migrate-namespace`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function listDirSafe(dir) {
+  if (!fs.existsSync(dir)) return [];
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Legacy rihal-* skill dirs / command files whose rcode-* twin exists in
+ * the SAME .claude dir. Read-only.
+ */
+function findLegacyRihalArtifacts(claudeDir) {
+  const skills = [];
+  const skillsDir = path.join(claudeDir, 'skills');
+  for (const entry of listDirSafe(skillsDir)) {
+    if (!entry.isDirectory() || !entry.name.startsWith('rihal-')) continue;
+    const twinName = 'rcode-' + entry.name.slice('rihal-'.length);
+    if (fs.existsSync(path.join(skillsDir, twinName))) {
+      skills.push({
+        name: entry.name,
+        twin: twinName,
+        srcPath: path.join(skillsDir, entry.name),
+        kind: 'skill',
+      });
+    }
+  }
+
+  const commands = [];
+  const commandsDir = path.join(claudeDir, 'commands');
+  for (const entry of listDirSafe(commandsDir)) {
+    if (!entry.isFile() || !entry.name.startsWith('rihal-') || !entry.name.endsWith('.md')) continue;
+    const twinName = 'rcode-' + entry.name.slice('rihal-'.length);
+    if (fs.existsSync(path.join(commandsDir, twinName))) {
+      commands.push({
+        name: entry.name,
+        twin: twinName,
+        srcPath: path.join(commandsDir, entry.name),
+        kind: 'command',
+      });
+    }
+  }
+
+  return { skills, commands };
+}
+
+/**
+ * Unprefixed command files (e.g. `do.md`) that duplicate an already-installed
+ * `rcode-do.md` twin in the SAME .claude/commands dir. Read-only.
+ */
+function findUnprefixedTwinDupes(claudeDir) {
+  const dupes = [];
+  const commandsDir = path.join(claudeDir, 'commands');
+  for (const entry of listDirSafe(commandsDir)) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    if (entry.name.startsWith('rcode-') || entry.name.startsWith('rihal-')) continue;
+    const twinName = 'rcode-' + entry.name;
+    if (fs.existsSync(path.join(commandsDir, twinName))) {
+      dupes.push({
+        name: entry.name,
+        twin: twinName,
+        srcPath: path.join(commandsDir, entry.name),
+        kind: 'command',
+      });
+    }
+  }
+  return dupes;
+}
+
+/**
+ * Unprefixed command basenames registered in BOTH project and global scope.
+ * Project always wins — the returned entries point at the GLOBAL copy,
+ * which is the one safe to remove (the project copy stays canonical).
+ */
+function findCrossScopeDupes(projectClaudeDir, globalClaudeDir) {
+  const dupes = [];
+  if (path.resolve(projectClaudeDir) === path.resolve(globalClaudeDir)) return dupes;
+  const projectCommandsDir = path.join(projectClaudeDir, 'commands');
+  const globalCommandsDir = path.join(globalClaudeDir, 'commands');
+  const projectNames = new Set(
+    listDirSafe(projectCommandsDir)
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => e.name),
+  );
+  for (const entry of listDirSafe(globalCommandsDir)) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    if (projectNames.has(entry.name)) {
+      dupes.push({
+        name: entry.name,
+        srcPath: path.join(globalCommandsDir, entry.name),
+        keptPath: path.join(projectCommandsDir, entry.name),
+        kind: 'command',
+      });
+    }
+  }
+  return dupes;
+}
+
+/**
+ * Full duplication report across project + global scopes. Pure read — safe
+ * to call from `rcode doctor` on every run.
+ */
+function scanNamespaceDuplication(projectDir, homeDir) {
+  const projectClaudeDir = path.join(projectDir, '.claude');
+  const globalClaudeDir = path.join(homeDir, '.claude');
+
+  const projectLegacy = findLegacyRihalArtifacts(projectClaudeDir);
+  const globalLegacy = findLegacyRihalArtifacts(globalClaudeDir);
+  const projectUnprefixed = findUnprefixedTwinDupes(projectClaudeDir);
+  const globalUnprefixed = findUnprefixedTwinDupes(globalClaudeDir);
+  const crossScope = findCrossScopeDupes(projectClaudeDir, globalClaudeDir);
+
+  const legacySkillCount = projectLegacy.skills.length + globalLegacy.skills.length;
+  const legacyCommandCount = projectLegacy.commands.length + globalLegacy.commands.length;
+  const unprefixedCount = projectUnprefixed.length + globalUnprefixed.length;
+  const crossScopeCount = crossScope.length;
+
+  return {
+    legacySkillCount,
+    legacyCommandCount,
+    unprefixedCount,
+    crossScopeCount,
+    totalCount: legacySkillCount + legacyCommandCount + unprefixedCount + crossScopeCount,
+    detail: { projectLegacy, globalLegacy, projectUnprefixed, globalUnprefixed, crossScope },
+  };
+}
+
+/**
+ * Move `srcPath` under `backupRoot/<scope>/<skills|commands>/`, then delete
+ * the original. Idempotent: if srcPath no longer exists (already migrated
+ * in an earlier pass, or removed by an earlier step in this same pass),
+ * this is a no-op that returns false.
+ */
+function backupAndRemove(srcPath, backupRoot, scope, kind) {
+  if (!fs.existsSync(srcPath)) return false;
+  const destDir = path.join(backupRoot, scope, kind === 'skill' ? 'skills' : 'commands');
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, path.basename(srcPath));
+  fs.cpSync(srcPath, dest, { recursive: true });
+  fs.rmSync(srcPath, { recursive: true, force: true });
+  return true;
+}
+
+/**
+ * Execute the cleanup: back up + remove every legacy rihal-* artifact and
+ * unprefixed/cross-scope duplicate found by scanNamespaceDuplication(), for
+ * real. Idempotent — running twice in a row removes 0 the second time
+ * because the scan re-runs fresh each call and finds nothing left to flag.
+ *
+ * Backups always land under ~/.claude/.rcode-backup/<timestamp>/ regardless
+ * of whether the artifact came from the project or global scope, so a
+ * single rollback location covers everything from one migrate run.
+ */
+function migrateNamespace(projectDir, homeDir) {
+  const scan = scanNamespaceDuplication(projectDir, homeDir);
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const backupRoot = path.join(homeDir, '.claude', '.rcode-backup', ts);
+
+  const summary = {
+    backupDir: null,
+    removed: { legacySkills: 0, legacyCommands: 0, unprefixedDupes: 0, crossScopeDupes: 0 },
+  };
+
+  const removeAll = (items, scope, kind) => {
+    let count = 0;
+    for (const item of items) {
+      if (backupAndRemove(item.srcPath, backupRoot, scope, kind)) count++;
+    }
+    return count;
+  };
+
+  summary.removed.legacySkills =
+    removeAll(scan.detail.projectLegacy.skills, 'project', 'skill') +
+    removeAll(scan.detail.globalLegacy.skills, 'global', 'skill');
+  summary.removed.legacyCommands =
+    removeAll(scan.detail.projectLegacy.commands, 'project', 'command') +
+    removeAll(scan.detail.globalLegacy.commands, 'global', 'command');
+  summary.removed.unprefixedDupes =
+    removeAll(scan.detail.projectUnprefixed, 'project', 'command') +
+    removeAll(scan.detail.globalUnprefixed, 'global', 'command');
+  summary.removed.crossScopeDupes = removeAll(scan.detail.crossScope, 'global', 'command');
+
+  const totalRemoved = Object.values(summary.removed).reduce((a, b) => a + b, 0);
+  if (totalRemoved > 0) summary.backupDir = backupRoot;
+
+  return summary;
+}
+
+module.exports = {
+  findLegacyRihalArtifacts,
+  findUnprefixedTwinDupes,
+  findCrossScopeDupes,
+  scanNamespaceDuplication,
+  migrateNamespace,
+};

package/cli/migrate-namespace.js

@@ -0,0 +1,61 @@
+/**
+ * rcode migrate-namespace — clean up legacy rihal-* skills/commands whose
+ * rcode-* twin already exists (#954), plus unprefixed/cross-scope command
+ * duplicates. Backs everything up under ~/.claude/.rcode-backup/<ts>/
+ * before removing. Idempotent — running twice removes nothing the second
+ * time.
+ *
+ * Default is dry-run (prints what WOULD be removed). Pass --yes to execute.
+ * `rcode update` also runs this automatically after refreshing files.
+ */
+
+const path = require('path');
+const { homedir } = require('./lib/homedir.cjs');
+const { scanNamespaceDuplication, migrateNamespace } = require('./lib/namespace-migrate.cjs');
+
+function parseArgs(args) {
+  return { yes: args.includes('--yes') || args.includes('-y') };
+}
+
+function printScanSummary(scan) {
+  console.log(`\n🕌 rcode — Namespace Migration\n`);
+  if (scan.totalCount === 0) {
+    console.log(`   ✓ No legacy rihal-* or duplicate command registrations found.\n`);
+    return;
+  }
+  console.log(`   Found ${scan.totalCount} artifact(s) to migrate:`);
+  console.log(`     legacy rihal-* skills:   ${scan.legacySkillCount}`);
+  console.log(`     legacy rihal-* commands: ${scan.legacyCommandCount}`);
+  console.log(`     unprefixed dupes:        ${scan.unprefixedCount}`);
+  console.log(`     cross-scope dupes:       ${scan.crossScopeCount}  (global copy shadowed by project)`);
+  console.log();
+}
+
+module.exports = function migrateNamespaceCommand(args = []) {
+  const opts = parseArgs(args);
+  const cwd = process.cwd();
+  const home = homedir();
+
+  const scan = scanNamespaceDuplication(cwd, home);
+  printScanSummary(scan);
+  if (scan.totalCount === 0) return;
+
+  if (!opts.yes) {
+    console.log(`   [DRY RUN] Nothing removed. Pass --yes to back up and remove these files.\n`);
+    return;
+  }
+
+  const summary = migrateNamespace(cwd, home);
+  const total = Object.values(summary.removed).reduce((a, b) => a + b, 0);
+  console.log(`   ✓ Removed ${total} artifact(s):`);
+  console.log(`     legacy skills:   ${summary.removed.legacySkills}`);
+  console.log(`     legacy commands: ${summary.removed.legacyCommands}`);
+  console.log(`     unprefixed:      ${summary.removed.unprefixedDupes}`);
+  console.log(`     cross-scope:     ${summary.removed.crossScopeDupes}`);
+  if (summary.backupDir) {
+    console.log(`   💾 backup: ${path.relative(home, summary.backupDir)} (under ~/.claude/.rcode-backup/)`);
+  }
+  console.log();
+};
+
+module.exports.parseArgs = parseArgs;

package/cli/update.js

@@ -446,6 +446,25 @@ async function runUpdate(args, { packageRoot, packageJson }) {
   }
   console.log(`   ✓ ${path.relative(cwd, configPath)} → installed_version: ${packageVersion}`);
 
+  // ------ Legacy namespace cleanup (#954) ------
+  // Backs up + removes legacy rihal-* skills/commands whose rcode-* twin
+  // already exists, plus unprefixed/cross-scope command dupes. Idempotent —
+  // safe to run on every update even when there's nothing to migrate.
+  try {
+    const { migrateNamespace } = require('./lib/namespace-migrate.cjs');
+    const { homedir: getHomedir } = require('./lib/homedir.cjs');
+    const nsResult = migrateNamespace(cwd, getHomedir());
+    const nsTotal = Object.values(nsResult.removed).reduce((a, b) => a + b, 0);
+    if (nsTotal > 0) {
+      console.log(`   🧹 migrated ${nsTotal} legacy rihal-*/duplicate command registration(s)`);
+      if (nsResult.backupDir) {
+        console.log(`      backup: ${nsResult.backupDir}`);
+      }
+    }
+  } catch (err) {
+    console.log(`   ⚠ namespace migration skipped: ${err.message}`);
+  }
+
   // ------ Verify manifest ------
   console.log();
   const { reports, hasDrift } = verifyInstall(cwd, packageRoot, editors);