@hanzlaa/rcode 3.4.21 → 3.4.22

package/cli/generate-command-skills.cjs

@@ -149,7 +149,7 @@ Identical to \`/rihal-${cmdName}\`. See the workflow file for the canonical outp
 `;
 }
 
-function main(packageRoot, targetSkillsDir, version) {
+function main(packageRoot, targetSkillsDir, version, options = {}) {
   if (!fs.existsSync(targetSkillsDir)) {
     fs.mkdirSync(targetSkillsDir, { recursive: true });
   }
@@ -158,11 +158,20 @@ function main(packageRoot, targetSkillsDir, version) {
   const commandsDir = path.join(packageRoot, 'rihal', 'commands');
   if (!fs.existsSync(commandsDir)) {
     console.warn(`[generate-command-skills] commands dir not found: ${commandsDir}`);
-    return { generated: 0, skipped: 0 };
+    return { generated: 0, skipped: 0, skippedGlobal: 0 };
   }
 
+  // Issue #679: skip stubs whose name already exists in ~/.claude/skills/.
+  // Otherwise the slash picker shows the same /rihal-* twice.
+  const os = require('os');
+  const globalSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  const globalSkills = (options.skipGlobalDuplicates && fs.existsSync(globalSkillsDir))
+    ? new Set(fs.readdirSync(globalSkillsDir).filter(n => n.startsWith('rihal-')))
+    : new Set();
+
   let generated = 0;
   let skipped = 0;
+  let skippedGlobal = 0;
 
   for (const file of fs.readdirSync(commandsDir)) {
     if (!file.endsWith('.md')) continue;
@@ -177,6 +186,28 @@ function main(packageRoot, targetSkillsDir, version) {
       continue;
     }
 
+    if (globalSkills.has(skillName)) {
+      // Global skill of same name exists — installing a sidebar stub here would
+      // duplicate the entry in Claude Code's slash picker. Also clean up any
+      // previously-generated stub with the same name.
+      const existingStub = path.join(targetSkillsDir, skillName);
+      if (fs.existsSync(existingStub)) {
+        try {
+          const existingFile = path.join(existingStub, 'SKILL.md');
+          if (fs.existsSync(existingFile)) {
+            const text = fs.readFileSync(existingFile, 'utf8');
+            // Only delete previously-generated stubs (marker present) — never
+            // user customizations.
+            if (/^generated:\s*true/m.test(text)) {
+              fs.rmSync(existingStub, { recursive: true, force: true });
+            }
+          }
+        } catch { /* non-fatal */ }
+      }
+      skippedGlobal++;
+      continue;
+    }
+
     const cmdPath = path.join(commandsDir, file);
     const cmdText = fs.readFileSync(cmdPath, 'utf8');
     const cmdFm = parseFrontmatter(cmdText);

package/cli/index.js

@@ -3,14 +3,14 @@
  * Rihal Code CLI
  *
  * Usage:
- *   npx @hanzlahabib/rihal-code init          → scaffold .rihal/ in current project
- *   npx @hanzlahabib/rihal-code dashboard     → start the Diwan view-only dashboard
- *   npx @hanzlahabib/rihal-code serve         → alias for dashboard
- *   npx @hanzlahabib/rihal-code digest        → print compact agent digests
- *   npx @hanzlahabib/rihal-code team          → list the team roster
- *   npx @hanzlahabib/rihal-code doctor        → compliance check
- *   npx @hanzlahabib/rihal-code version       → print version
- *   npx @hanzlahabib/rihal-code help          → this message
+ *   npx @hanzlaa/rcode init          → scaffold .rihal/ in current project
+ *   npx @hanzlaa/rcode dashboard     → start the Diwan view-only dashboard
+ *   npx @hanzlaa/rcode serve         → alias for dashboard
+ *   npx @hanzlaa/rcode digest        → print compact agent digests
+ *   npx @hanzlaa/rcode team          → list the team roster
+ *   npx @hanzlaa/rcode doctor        → compliance check
+ *   npx @hanzlaa/rcode version       → print version
+ *   npx @hanzlaa/rcode help          → this message
  */
 
 const path = require('path');

package/cli/install.js

@@ -370,11 +370,32 @@ async function resolveIde(opts) {
 async function resolveCommitPlanning(opts) {
   if (opts.commitPlanning !== null) return opts.commitPlanning;
   if (opts.noPrompt || opts.global) return false; // global install: no planning artifacts
-  if (opts.yes || !process.stdin.isTTY) return true; // non-interactive default
 
+  // Issue #685: on re-install, read the existing .rihal/config.yaml and use
+  // its commit_planning value as the default. Otherwise the new prompt
+  // answer overwrites .gitignore but NOT config.yaml, leaving two sources of
+  // truth that silently diverge. Users on re-install almost always want to
+  // KEEP their existing setting unless they explicitly pass --commit-planning.
+  let existingValue = null;
+  try {
+    const cfgPath = path.join(opts.target, '.rihal', 'config.yaml');
+    if (fs.existsSync(cfgPath)) {
+      const cfg = fs.readFileSync(cfgPath, 'utf8');
+      const m = cfg.match(/^commit_planning:\s*(true|false)\s*$/m);
+      if (m) existingValue = m[1] === 'true';
+    }
+  } catch { /* fall through to prompt */ }
+
+  if (opts.yes || !process.stdin.isTTY) {
+    return existingValue !== null ? existingValue : true; // honor existing on re-install
+  }
+
+  const initialValue = existingValue === false ? 'gitignore' : 'commit';
   const choice = await clack.select({
-    message: '📋 .planning/ holds PRDs, roadmaps, sprints, SUMMARY files. How should they be tracked?',
-    initialValue: 'commit',
+    message: existingValue !== null
+      ? '📋 .planning/ tracking — current setting preserved unless you change it.'
+      : '📋 .planning/ holds PRDs, roadmaps, sprints, SUMMARY files. How should they be tracked?',
+    initialValue,
     options: [
       { value: 'commit',    label: 'Commit',    hint: 'collaborators see the same plans (recommended)' },
       { value: 'gitignore', label: 'Gitignore', hint: 'planning stays local (good for sensitive PRDs)' },
@@ -873,16 +894,26 @@ function installBrainScaffold(packageRoot, target) {
  *
  * A skill is marked internal by adding `internal: true` to its SKILL.md frontmatter.
  */
-function installSkills(packageRoot, target) {
+function installSkills(packageRoot, target, options = {}) {
   const skillsSource = path.join(packageRoot, 'rihal/skills');
   const skillsDest = path.join(target, '.claude/skills');
   const internalDest = path.join(target, '.rihal/skills');
 
-  if (!fs.existsSync(skillsSource)) return 0;
+  if (!fs.existsSync(skillsSource)) return { count: 0, skippedGlobal: 0 };
   fs.mkdirSync(skillsDest, { recursive: true });
   fs.mkdirSync(internalDest, { recursive: true });
 
+  // Issue #679: when ~/.claude/skills/<name>/ already exists with the rihal-
+  // prefix, Claude Code reads from BOTH global and project, showing every
+  // /rihal-* twice in the slash picker. Skip the project copy for any rihal-*
+  // skill that already lives in the global skills dir.
+  const globalSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  const globalRihalSkills = (options.skipGlobalDuplicates && fs.existsSync(globalSkillsDir))
+    ? new Set(fs.readdirSync(globalSkillsDir).filter(n => n.startsWith('rihal-')))
+    : new Set();
+
   let count = 0;
+  let skippedGlobal = 0;
 
   function isInternalSkill(skillDir) {
     const skillMd = path.join(skillDir, 'SKILL.md');
@@ -891,6 +922,13 @@ function installSkills(packageRoot, target) {
     return /^internal:\s*true\s*$/m.test(text);
   }
 
+  function hasLocalOverride(destDir) {
+    if (!fs.existsSync(destDir)) return false;
+    try {
+      return fs.readdirSync(destDir).some(f => f.endsWith('.local.md'));
+    } catch { return false; }
+  }
+
   function walkForSkills(dir) {
     if (!fs.existsSync(dir)) return;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -901,9 +939,23 @@ function installSkills(packageRoot, target) {
         const destName = entry.name.startsWith('rihal-')
           ? entry.name
           : `rihal-${entry.name}`;
-        const dest = isInternalSkill(src)
+        const internal = isInternalSkill(src);
+        const dest = internal
           ? path.join(internalDest, destName)   // internal → .rihal/skills/
           : path.join(skillsDest, destName);     // user-facing → .claude/skills/
+
+        // Skip user-facing (non-internal) rihal-* skills when the same name
+        // exists globally — UNLESS the user has a *.local.md override on the
+        // project copy, in which case we always preserve their customization.
+        if (!internal && globalRihalSkills.has(destName) && !hasLocalOverride(dest)) {
+          // Also remove the existing project copy (left over from previous
+          // installs that didn't dedup) so it stops showing in the picker.
+          if (fs.existsSync(dest)) {
+            try { fs.rmSync(dest, { recursive: true, force: true }); } catch { /* non-fatal */ }
+          }
+          skippedGlobal++;
+          continue;
+        }
         copyDirRecursive(src, dest);
         count++;
       } else {
@@ -916,7 +968,7 @@ function installSkills(packageRoot, target) {
     walkForSkills(path.join(skillsSource, bucket));
   }
 
-  return count;
+  return { count, skippedGlobal };
 }
 
 /**
@@ -1425,6 +1477,18 @@ function convertToCursorMdc(sourceText) {
 async function install(opts) {
   if (opts.help) { printHelp(); return 0; }
 
+  // Issue #680: --reset alone is a footgun — silently does nothing. Fail
+  // fast with a clear message before any work happens.
+  if (opts.reset && !opts.force) {
+    console.log('');
+    console.log('  ' + warn('--reset has no effect without --force.'));
+    console.log('  ' + dim('  --reset wipes config.yaml and state.json. To prevent accidental data loss,'));
+    console.log('  ' + dim('  it must be paired with --force. Re-run as:'));
+    console.log('  ' + dim('    rcode install --reset --force'));
+    console.log('');
+    return 2;
+  }
+
   const pkgVersion = readPackageVersion();
 
   // Header banner — only shown for interactive runs to keep CI/non-TTY logs terse.
@@ -1754,8 +1818,10 @@ async function install(opts) {
     const configDir = path.join(opts.target, '.rihal', '_config');
     ensureDir(configDir);
     fs.writeFileSync(path.join(configDir, 'manifest.yaml'), generateInstallManifest(opts));
-    // Install skills + sidebar stubs globally
-    let skillsInstalled = installSkills(PACKAGE_ROOT, opts.target);
+    // Install skills + sidebar stubs globally — never dedup against globals,
+    // because in --global mode the target IS the global dir.
+    const skillsResult = installSkills(PACKAGE_ROOT, opts.target);
+    let skillsInstalled = skillsResult.count;
     try {
       const { main: generateCommandSkills } = require(path.join(PACKAGE_ROOT, 'cli', 'generate-command-skills.cjs'));
       const stubsDir = path.join(opts.target, '.claude', 'skills');
@@ -1831,6 +1897,7 @@ async function install(opts) {
         plan.length = 0;
         filtered.forEach(e => plan.push(e));
       }
+
     } catch { /* non-fatal — skip detection on permission errors */ }
   }
 
@@ -1855,11 +1922,34 @@ async function install(opts) {
   } else if (opts.force && (fs.existsSync(configPath) || fs.existsSync(stateDest))) {
     existedBefore = true;
   }
+  // Note: --reset without --force is rejected at the top of install() (#680).
 
   // Write .rihal/config.yaml (user_name, project_name, language, mode)
   // Note: config.yaml is user data and should NOT be overwritten on --force (unless --reset)
   if (!fs.existsSync(configPath)) {
     fs.writeFileSync(configPath, generateConfigYaml(opts));
+  } else {
+    // Issue #685: re-install path. config.yaml is preserved BUT if the user
+    // just changed commit_planning via the prompt/flag, .gitignore will be
+    // rewritten with the new value while config.yaml keeps the old one,
+    // creating a silent drift. Update only commit_planning in-place
+    // (preserve everything else the user may have customized).
+    try {
+      const before = fs.readFileSync(configPath, 'utf8');
+      const desired = opts.commitPlanning !== false;
+      const re = /^commit_planning:\s*(true|false)\s*$/m;
+      const match = before.match(re);
+      const currentInFile = match ? match[1] === 'true' : null;
+      if (match && currentInFile !== desired) {
+        const updated = before.replace(re, `commit_planning: ${desired}`);
+        fs.writeFileSync(configPath, updated);
+        console.log('  ' + dim(`Updated commit_planning in config.yaml (${currentInFile} → ${desired}) — closes #685.`));
+      } else if (!match) {
+        // Older config without the key — append it so the next read finds it.
+        const appended = before.replace(/\n*$/, '') + `\ncommit_planning: ${desired}\n`;
+        fs.writeFileSync(configPath, appended);
+      }
+    } catch { /* best-effort — never fail install on this */ }
   }
   // Validate config.yaml with zod schema (#250) — warn but never block install.
   try {
@@ -1917,7 +2007,16 @@ async function install(opts) {
 
   // Install v1-style phrase-activated skills (scaffold-project, create-prd,
   // retrospective, etc.) into .claude/skills/ alongside the v2 agents/commands.
-  let skillsInstalled = installSkills(PACKAGE_ROOT, opts.target);
+  // Issue #679: skip rihal-* skills that already exist in ~/.claude/skills/
+  // (global precedence) so the slash picker doesn't show every command twice.
+  // Reuse the isProjectInstall flag declared earlier in this scope.
+  const skillsResult = installSkills(PACKAGE_ROOT, opts.target, {
+    skipGlobalDuplicates: isProjectInstall,
+  });
+  let skillsInstalled = skillsResult.count;
+  if (skillsResult.skippedGlobal > 0) {
+    console.log('  ' + dim(`Skipped ${skillsResult.skippedGlobal} project-level rihal skills (global ones in ~/.claude/skills/ take precedence) — closes #679.`));
+  }
 
   // Generate install-time skill stubs that mirror sidebar-worthy slash commands.
   // Source codebase stays clean — these stubs only exist at the install
@@ -1926,11 +2025,16 @@ async function install(opts) {
   try {
     const { main: generateCommandSkills } = require(path.join(PACKAGE_ROOT, 'cli', 'generate-command-skills.cjs'));
     const stubsDir = path.join(opts.target, '.claude', 'skills');
-    const result = generateCommandSkills(PACKAGE_ROOT, stubsDir, readPackageVersion());
+    const result = generateCommandSkills(PACKAGE_ROOT, stubsDir, readPackageVersion(), {
+      skipGlobalDuplicates: isProjectInstall,
+    });
     if (result.generated > 0) {
       console.log('  ' + dim(`${result.generated} sidebar skill stub${result.generated === 1 ? '' : 's'} generated for command discoverability`));
       skillsInstalled += result.generated;
     }
+    if (result.skippedGlobal > 0) {
+      console.log('  ' + dim(`Skipped ${result.skippedGlobal} sidebar stub${result.skippedGlobal === 1 ? '' : 's'} that duplicate global ~/.claude/skills/ — closes #679.`));
+    }
   } catch (err) {
     // Non-fatal: install succeeds without sidebar stubs
     console.log('  ' + dim(`(sidebar stub generation skipped: ${err.message})`));

package/cli/set-profile.js

@@ -2,11 +2,11 @@
  * rihal-code set-profile — change the model profile for the current project
  *
  * Usage:
- *   npx @hanzlahabib/rihal-code set-profile balanced
- *   npx @hanzlahabib/rihal-code set-profile quality
- *   npx @hanzlahabib/rihal-code set-profile budget
- *   npx @hanzlahabib/rihal-code set-profile inherit
- *   npx @hanzlahabib/rihal-code set-profile                  # show current
+ *   npx @hanzlaa/rcode set-profile balanced
+ *   npx @hanzlaa/rcode set-profile quality
+ *   npx @hanzlaa/rcode set-profile budget
+ *   npx @hanzlaa/rcode set-profile inherit
+ *   npx @hanzlaa/rcode set-profile                  # show current
  *
  * This is a thin wrapper over `rihal-code config model_profile <name>`.
  * All config read/write goes through cli/lib/config.cjs, which handles

package/cli/show-model.js

@@ -2,9 +2,9 @@
  * rihal-code show-model — print the resolved model for an agent (or all agents)
  *
  * Usage:
- *   npx @hanzlahabib/rihal-code show-model              # all agents in current profile
- *   npx @hanzlahabib/rihal-code show-model waleed       # single agent
- *   npx @hanzlahabib/rihal-code show-model --profile=quality   # different profile
+ *   npx @hanzlaa/rcode show-model              # all agents in current profile
+ *   npx @hanzlaa/rcode show-model waleed       # single agent
+ *   npx @hanzlaa/rcode show-model --profile=quality   # different profile
  */
 
 const {

package/cli/uninstall.js

@@ -250,8 +250,15 @@ function isKnownSkillName(name) {
 /**
  * Build the list of files/dirs (relative to cwd) that the uninstall plan
  * will delete or mutate. Used to feed `tar --files-from=-`.
+ *
+ * @param {object} plan — uninstall plan
+ * @param {string} cwd — project root
+ * @param {object} [options]
+ * @param {boolean} [options.purge=false] — when true, also include .rihal/
+ *   and .planning/ in the backup so --purge users can recover state.json,
+ *   decisions, and planning artifacts. Issue #683.
  */
-function planToPathList(plan, cwd) {
+function planToPathList(plan, cwd, options = {}) {
   const paths = [];
 
   for (const name of plan.claude.skills) {
@@ -278,6 +285,26 @@ function planToPathList(plan, cwd) {
     paths.push('AGENTS.md');
   }
 
+  // Issue #683: --purge wipes .rihal/ AND .planning/ but the backup never
+  // included them. User loses state.json, decisions, planning artifacts with
+  // no recovery. Add them when purging — but EXCLUDE .rihal/backups/ itself
+  // (we'd be writing into the dir we're tar-ing).
+  if (options.purge) {
+    const rihalDir = path.join(cwd, '.rihal');
+    if (fs.existsSync(rihalDir)) {
+      // Walk one level deep and add everything except backups/
+      try {
+        for (const entry of fs.readdirSync(rihalDir)) {
+          if (entry === 'backups') continue;
+          paths.push(path.join('.rihal', entry));
+        }
+      } catch { /* fall through; ok=false from tar will warn */ }
+    }
+    if (fs.existsSync(path.join(cwd, '.planning'))) {
+      paths.push('.planning');
+    }
+  }
+
   return paths;
 }
 
@@ -288,8 +315,8 @@ function planToPathList(plan, cwd) {
  * (tar missing, no paths, etc.); the caller should warn the user but may
  * still proceed since the user already confirmed the destructive action.
  */
-function createBackup(cwd, plan) {
-  const paths = planToPathList(plan, cwd);
+function createBackup(cwd, plan, options = {}) {
+  const paths = planToPathList(plan, cwd, { purge: options.purge === true });
   if (paths.length === 0) {
     return { ok: false, warning: 'nothing to back up' };
   }
@@ -301,11 +328,17 @@ function createBackup(cwd, plan) {
     return { ok: false, warning: 'tar not available on this system' };
   }
 
-  const backupsDir = path.join(cwd, '.rihal/backups');
+  // Issue #683: when --purge wipes .rihal/, a backup written into
+  // .rihal/backups/ would be deleted moments later. Write to a sibling
+  // .rihal-backups/ at the project root instead so the backup survives.
+  // For non-purge runs, keep the historical .rihal/backups/ location.
+  const backupsDir = options.purge
+    ? path.join(cwd, '.rihal-backups')
+    : path.join(cwd, '.rihal/backups');
   try {
     fs.mkdirSync(backupsDir, { recursive: true });
   } catch (err) {
-    return { ok: false, warning: `could not create .rihal/backups/: ${err.message}` };
+    return { ok: false, warning: `could not create ${path.relative(cwd, backupsDir)}/: ${err.message}` };
   }
 
   const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
@@ -489,10 +522,15 @@ async function runUninstall(args) {
 
   // Create a timestamped backup before doing anything destructive.
   // Non-fatal on failure — the user already confirmed, we just warn.
+  // Issue #683: --purge backs up .rihal/ and .planning/ too so users can
+  // recover state.json, decisions log, and planning artifacts.
   console.log();
-  const backup = createBackup(cwd, plan);
+  const backup = createBackup(cwd, plan, { purge: opts.purge === true });
   if (backup.ok) {
     console.log(`   💾 backup created: ${backup.path}`);
+    if (opts.purge) {
+      console.log('      includes .rihal/ and .planning/ (state, decisions, planning artifacts)');
+    }
   } else {
     console.log(`   ⚠ no backup created (${backup.warning}) — continuing anyway`);
   }
@@ -649,15 +687,29 @@ async function runUninstall(args) {
 
     // Strip the rcode-managed block from .gitignore. The installer writes
     // a fenced block; we remove it cleanly without touching user lines.
+    //
+    // Issue #684: previous regex `/\n?# rcode[\s\S]*?(?=\n\n|\n$|$)/g` was a
+    // footgun — it matched ANY user line starting with "# rcode" (e.g.
+    // "# rcode notes", "# rcode is great") and greedily consumed everything
+    // up to the next blank line, silently nuking user content.
+    //
+    // Three shapes have ever shipped:
+    //   1. Current (install.js:653-654): "# ===== rcode-managed gitignore block ... =====" ... "# ===== end rcode-managed gitignore block ====="
+    //   2. Old fenced markers: "# >>> rihal-code >>>" ... "# <<< rihal-code <<<"
+    //   3. Hypothetical legacy single-line "# rcode" — never actually
+    //      committed by any installer version we can find. Removed.
+    //
+    // Both kept patterns require BOTH sentinel markers to be present —
+    // user content with "# rcode" prefix is now safe.
     const gitignorePath = path.join(cwd, '.gitignore');
     if (fs.existsSync(gitignorePath)) {
       try {
         const before = fs.readFileSync(gitignorePath, 'utf8');
-        // Match either fenced markers or the legacy "# rcode" header through to
-        // the next blank line — both shapes the installer has used historically.
         const stripped = before
+          // Current shape (install.js BEGIN/END markers — exact match).
+          .replace(/\n?# ===== rcode-managed gitignore block[\s\S]*?# ===== end rcode-managed gitignore block =====\n?/g, '\n')
+          // Legacy >>> / <<< fenced shape.
           .replace(/\n?# >>> rihal-code >>>[\s\S]*?# <<< rihal-code <<<\n?/g, '\n')
-          .replace(/\n?# rcode[\s\S]*?(?=\n\n|\n$|$)/g, '\n')
           .replace(/\n{3,}/g, '\n\n');
         if (stripped !== before) {
           fs.writeFileSync(gitignorePath, stripped);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.21",
+  "version": "3.4.22",
   "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": {

package/rihal/bin/rihal-tools.cjs

@@ -985,6 +985,26 @@ function cmdState(subArgs) {
       try { process.kill(pid, 0); return true; } catch { return false; }
     }
 
+    // Issue #681: auto-clear the install-time _seeded_stub marker once the
+    // state has graduated to a real project (project field set + at least one
+    // real phase OR REQUIREMENTS.md present). project-status (#675) reads
+    // _seeded_stub; if no writer ever clears it, every project stays "stub"
+    // forever and downstream workflows misroute.
+    if (state._seeded_stub === true) {
+      const phases = Array.isArray(state.phases) ? state.phases : [];
+      const firstPhaseName = phases[0]?.name || '';
+      const hasRealPhase = phases.length > 1 ||
+        (firstPhaseName && firstPhaseName !== 'Setup & Scaffolding');
+      const hasRequirements = (() => {
+        try {
+          return fs.existsSync(path.join(PROJECT_ROOT, '.planning', 'REQUIREMENTS.md'));
+        } catch { return false; }
+      })();
+      if ((state.project && hasRealPhase) || hasRequirements) {
+        delete state._seeded_stub;
+      }
+    }
+
     state.updated = new Date().toISOString();
     fs.mkdirSync(RIHAL_DIR, { recursive: true });
     const lockPath = statePath + '.lock';
@@ -1069,6 +1089,23 @@ function cmdState(subArgs) {
     return state;
   }
 
+  // --- clear-stub --- (issue #681)
+  // Explicit way to flip _seeded_stub off. Useful for /rihal-new-project once
+  // PROJECT.md / REQUIREMENTS.md / ROADMAP.md are committed. The auto-clear in
+  // writeState() also handles this, but having an explicit subcommand lets
+  // workflows be self-documenting and idempotent.
+  if (sub === 'clear-stub') {
+    if (!fs.existsSync(statePath)) {
+      return { ok: false, error: 'No state.json — nothing to clear.' };
+    }
+    const state = readState();
+    if (!state) return { ok: false, error: 'state.json unreadable' };
+    const wasStub = state._seeded_stub === true;
+    if (wasStub) delete state._seeded_stub;
+    writeState(state);
+    return { ok: true, was_stub: wasStub, project: state.project || null };
+  }
+
   // --- init ---
   if (sub === 'init') {
     let existing;