@hanzlaa/rcode 3.4.21 → 3.4.23

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/dist/rcode.js

@@ -15188,10 +15188,23 @@ var require_install = __commonJS({
     async function resolveCommitPlanning(opts) {
       if (opts.commitPlanning !== null) return opts.commitPlanning;
       if (opts.noPrompt || opts.global) return false;
-      if (opts.yes || !process.stdin.isTTY) return true;
+      let existingValue = null;
+      try {
+        const cfgPath = path2.join(opts.target, ".rihal", "config.yaml");
+        if (fs2.existsSync(cfgPath)) {
+          const cfg = fs2.readFileSync(cfgPath, "utf8");
+          const m = cfg.match(/^commit_planning:\s*(true|false)\s*$/m);
+          if (m) existingValue = m[1] === "true";
+        }
+      } catch {
+      }
+      if (opts.yes || !process.stdin.isTTY) {
+        return existingValue !== null ? existingValue : true;
+      }
+      const initialValue = existingValue === false ? "gitignore" : "commit";
       const choice = await clack.select({
-        message: "\u{1F4CB} .planning/ holds PRDs, roadmaps, sprints, SUMMARY files. How should they be tracked?",
-        initialValue: "commit",
+        message: existingValue !== null ? "\u{1F4CB} .planning/ tracking \u2014 current setting preserved unless you change it." : "\u{1F4CB} .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)" }
@@ -15312,9 +15325,13 @@ Installs (IDE-specific):
       fs2.mkdirSync(planningDir, { recursive: true });
       const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
       const name = projectName || path2.basename(target);
+      const STUB_BANNER = `<!-- INSTALL STUB \u2014 overwritten by /rihal-new-project. Delete this file or run
+     /rihal-new-project before committing. See https://github.com/hanzlahabib/rihal-code/issues/670 -->
+
+`;
       fs2.writeFileSync(
         projectPath,
-        `# ${name}
+        STUB_BANNER + `# ${name}
 
 **One-line:** Describe what this project is in one sentence.
 
@@ -15331,7 +15348,7 @@ What this project delivers and who it serves.
       );
       fs2.writeFileSync(
         roadmapPath,
-        `# ${name} \u2014 Roadmap
+        STUB_BANNER + `# ${name} \u2014 Roadmap
 
 **Milestone: M1 \u2014 Initial Delivery** (v1.0)
 Started: ${today} \xB7 Current
@@ -15355,7 +15372,7 @@ Ideas and future phases go here.
       );
       fs2.writeFileSync(
         statePath,
-        `# ${name} \u2014 State
+        STUB_BANNER + `# ${name} \u2014 State
 
 **Last updated:** ${today}
 **Milestone:** M1 \u2014 Initial Delivery
@@ -15374,7 +15391,7 @@ _None._
 
 ## Next Action
 
-Say "plan a sprint" or run \`/rihal-sprint-planning\` to break Phase 01 into stories.
+Run \`/rihal-new-project <description>\` to bootstrap, or \`/rihal-sprint-planning\` once a real phase exists.
 `
       );
       const rihalStateJson = path2.join(target, ".rihal", "state.json");
@@ -15382,16 +15399,15 @@ Say "plan a sprint" or run \`/rihal-sprint-planning\` to break Phase 01 into sto
         const now = (/* @__PURE__ */ new Date()).toISOString();
         const state = {
           version: "1",
-          project: name,
+          project: null,
+          _seeded_stub: true,
           created: now,
           updated: now,
-          current_phase: "01",
+          current_phase: null,
           current_plan: 0,
           current_sprint: null,
-          milestone: "M1 \u2014 Initial Delivery",
-          phases: [
-            { id: "01", name: "Setup & Scaffolding", status: "planned" }
-          ],
+          milestone: null,
+          phases: [],
           executions: [],
           decisions: [],
           blockers: [],
@@ -15584,20 +15600,31 @@ ${BLOCK}`);
       }
       return copied;
     }
-    function installSkills(packageRoot, target) {
+    function installSkills(packageRoot, target, options = {}) {
       const skillsSource = path2.join(packageRoot, "rihal/skills");
       const skillsDest = path2.join(target, ".claude/skills");
       const internalDest = path2.join(target, ".rihal/skills");
-      if (!fs2.existsSync(skillsSource)) return 0;
+      if (!fs2.existsSync(skillsSource)) return { count: 0, skippedGlobal: 0 };
       fs2.mkdirSync(skillsDest, { recursive: true });
       fs2.mkdirSync(internalDest, { recursive: true });
+      const globalSkillsDir = path2.join(os.homedir(), ".claude", "skills");
+      const globalRihalSkills = options.skipGlobalDuplicates && fs2.existsSync(globalSkillsDir) ? new Set(fs2.readdirSync(globalSkillsDir).filter((n) => n.startsWith("rihal-"))) : /* @__PURE__ */ new Set();
       let count = 0;
+      let skippedGlobal = 0;
       function isInternalSkill(skillDir) {
         const skillMd = path2.join(skillDir, "SKILL.md");
         if (!fs2.existsSync(skillMd)) return false;
         const text = fs2.readFileSync(skillMd, "utf8");
         return /^internal:\s*true\s*$/m.test(text);
       }
+      function hasLocalOverride(destDir) {
+        if (!fs2.existsSync(destDir)) return false;
+        try {
+          return fs2.readdirSync(destDir).some((f) => f.endsWith(".local.md"));
+        } catch {
+          return false;
+        }
+      }
       function walkForSkills(dir) {
         if (!fs2.existsSync(dir)) return;
         for (const entry of fs2.readdirSync(dir, { withFileTypes: true })) {
@@ -15606,7 +15633,18 @@ ${BLOCK}`);
           const hasSkillMd = fs2.existsSync(path2.join(src, "SKILL.md"));
           if (hasSkillMd) {
             const destName = entry.name.startsWith("rihal-") ? entry.name : `rihal-${entry.name}`;
-            const dest = isInternalSkill(src) ? path2.join(internalDest, destName) : path2.join(skillsDest, destName);
+            const internal = isInternalSkill(src);
+            const dest = internal ? path2.join(internalDest, destName) : path2.join(skillsDest, destName);
+            if (!internal && globalRihalSkills.has(destName) && !hasLocalOverride(dest)) {
+              if (fs2.existsSync(dest)) {
+                try {
+                  fs2.rmSync(dest, { recursive: true, force: true });
+                } catch {
+                }
+              }
+              skippedGlobal++;
+              continue;
+            }
             copyDirRecursive(src, dest);
             count++;
           } else {
@@ -15617,7 +15655,7 @@ ${BLOCK}`);
       for (const bucket of ["agents", "actions", "core"]) {
         walkForSkills(path2.join(skillsSource, bucket));
       }
-      return count;
+      return { count, skippedGlobal };
     }
     function parseFrontmatter(text) {
       if (!text.startsWith("---\n")) return { frontmatter: {}, body: text };
@@ -16001,6 +16039,15 @@ ${BLOCK}`);
         printHelp2();
         return 0;
       }
+      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();
       const isInteractive = process.stdin.isTTY && !opts.yes;
       if (isInteractive) printInstallHeader(pkgVersion);
@@ -16273,7 +16320,8 @@ ${BLOCK}`);
         const configDir2 = path2.join(opts.target, ".rihal", "_config");
         ensureDir(configDir2);
         fs2.writeFileSync(path2.join(configDir2, "manifest.yaml"), generateInstallManifest(opts));
-        let skillsInstalled2 = installSkills(PACKAGE_ROOT2, opts.target);
+        const skillsResult2 = installSkills(PACKAGE_ROOT2, opts.target);
+        let skillsInstalled2 = skillsResult2.count;
         try {
           const { main: generateCommandSkills } = require(path2.join(PACKAGE_ROOT2, "cli", "generate-command-skills.cjs"));
           const stubsDir = path2.join(opts.target, ".claude", "skills");
@@ -16353,6 +16401,25 @@ ${BLOCK}`);
       }
       if (!fs2.existsSync(configPath)) {
         fs2.writeFileSync(configPath, generateConfigYaml(opts));
+      } else {
+        try {
+          const before = fs2.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}`);
+            fs2.writeFileSync(configPath, updated);
+            console.log("  " + dim(`Updated commit_planning in config.yaml (${currentInFile} \u2192 ${desired}) \u2014 closes #685.`));
+          } else if (!match) {
+            const appended = before.replace(/\n*$/, "") + `
+commit_planning: ${desired}
+`;
+            fs2.writeFileSync(configPath, appended);
+          }
+        } catch {
+        }
       }
       try {
         const configText = fs2.readFileSync(configPath, "utf8");
@@ -16392,15 +16459,26 @@ ${BLOCK}`);
         path2.join(configDir, "files-manifest.csv"),
         generateFilesManifest(plan, opts.target, { mergeExistingManifest: !opts.force })
       );
-      let skillsInstalled = installSkills(PACKAGE_ROOT2, opts.target);
+      const skillsResult = installSkills(PACKAGE_ROOT2, 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) \u2014 closes #679.`));
+      }
       try {
         const { main: generateCommandSkills } = require(path2.join(PACKAGE_ROOT2, "cli", "generate-command-skills.cjs"));
         const stubsDir = path2.join(opts.target, ".claude", "skills");
-        const result = generateCommandSkills(PACKAGE_ROOT2, stubsDir, readPackageVersion());
+        const result = generateCommandSkills(PACKAGE_ROOT2, 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/ \u2014 closes #679.`));
+        }
       } catch (err) {
         console.log("  " + dim(`(sidebar stub generation skipped: ${err.message})`));
       }
@@ -17666,7 +17744,7 @@ var require_uninstall = __commonJS({
     function isKnownSkillName(name) {
       return KNOWN_ACTION_SKILLS.includes(name);
     }
-    function planToPathList(plan, cwd) {
+    function planToPathList(plan, cwd, options = {}) {
       const paths = [];
       for (const name of plan.claude.skills) {
         paths.push(path2.join(".claude/skills", name));
@@ -17689,10 +17767,25 @@ var require_uninstall = __commonJS({
       if (plan.agentsMd && fs2.existsSync(path2.join(cwd, "AGENTS.md"))) {
         paths.push("AGENTS.md");
       }
+      if (options.purge) {
+        const rihalDir = path2.join(cwd, ".rihal");
+        if (fs2.existsSync(rihalDir)) {
+          try {
+            for (const entry of fs2.readdirSync(rihalDir)) {
+              if (entry === "backups") continue;
+              paths.push(path2.join(".rihal", entry));
+            }
+          } catch {
+          }
+        }
+        if (fs2.existsSync(path2.join(cwd, ".planning"))) {
+          paths.push(".planning");
+        }
+      }
       return paths;
     }
-    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" };
       }
@@ -17700,11 +17793,11 @@ var require_uninstall = __commonJS({
       if (tarCheck.status !== 0) {
         return { ok: false, warning: "tar not available on this system" };
       }
-      const backupsDir = path2.join(cwd, ".rihal/backups");
+      const backupsDir = options.purge ? path2.join(cwd, ".rihal-backups") : path2.join(cwd, ".rihal/backups");
       try {
         fs2.mkdirSync(backupsDir, { recursive: true });
       } catch (err) {
-        return { ok: false, warning: `could not create .rihal/backups/: ${err.message}` };
+        return { ok: false, warning: `could not create ${path2.relative(cwd, backupsDir)}/: ${err.message}` };
       }
       const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
       const backupFile = path2.join(backupsDir, `uninstall-${ts}.tgz`);
@@ -17845,9 +17938,12 @@ var require_uninstall = __commonJS({
         }
       }
       console.log();
-      const backup = createBackup(cwd, plan);
+      const backup = createBackup(cwd, plan, { purge: opts.purge === true });
       if (backup.ok) {
         console.log(`   \u{1F4BE} backup created: ${backup.path}`);
+        if (opts.purge) {
+          console.log("      includes .rihal/ and .planning/ (state, decisions, planning artifacts)");
+        }
       } else {
         console.log(`   \u26A0 no backup created (${backup.warning}) \u2014 continuing anyway`);
       }
@@ -17977,7 +18073,7 @@ var require_uninstall = __commonJS({
         if (fs2.existsSync(gitignorePath)) {
           try {
             const before = fs2.readFileSync(gitignorePath, "utf8");
-            const stripped = before.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");
+            const stripped = before.replace(/\n?# ===== rcode-managed gitignore block[\s\S]*?# ===== end rcode-managed gitignore block =====\n?/g, "\n").replace(/\n?# >>> rihal-code >>>[\s\S]*?# <<< rihal-code <<<\n?/g, "\n").replace(/\n{3,}/g, "\n\n");
             if (stripped !== before) {
               fs2.writeFileSync(gitignorePath, stripped);
               console.log(`   \u2713 stripped rcode block from .gitignore (--purge)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.21",
+  "version": "3.4.23",
   "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": {
@@ -15,6 +15,7 @@
     "postinstall": "node cli/postinstall.js",
     "build:cli": "node scripts/build.cjs",
     "build": "node scripts/build.cjs",
+    "prepack": "node scripts/build.cjs",
     "dogfood": "bash scripts/dogfood-check.sh"
   },
   "files": [

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;