@hanzlaa/rcode 3.4.8 → 3.4.10

package/cli/doctor.js

@@ -54,7 +54,9 @@ function isWritable(dir) {
 }
 
 function commandAvailable(cmd) {
-  const result = spawnSync('which', [cmd], { stdio: 'ignore' });
+  // 'which' is POSIX-only; 'where' is Windows. Try both so this works cross-platform.
+  const checker = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(checker, [cmd], { stdio: 'ignore' });
   return result.status === 0;
 }
 

package/cli/github-sync.js

@@ -649,6 +649,7 @@ async function main(args) {
         results.errors.push(`label ${label.name}: ${result.error}`);
       } else if (!result.dryRun) {
         if (!syncMap.labels.includes(label.name)) syncMap.labels.push(label.name);
+        if (opts.execute) saveSyncMap(cwd, syncMap);
         console.log(`   ✓ ${result.existed ? 'exists' : 'created'}: ${label.name}`);
       }
     }
@@ -670,6 +671,7 @@ async function main(args) {
           url: result.url,
           synced_at: new Date().toISOString(),
         };
+        if (opts.execute) saveSyncMap(cwd, syncMap);
         console.log(`   ✓ created: ${phase.id} → milestone #${result.number}`);
       }
     }
@@ -686,7 +688,7 @@ async function main(args) {
         ``,
         `## 📋 Source Content`,
         ``,
-        epic.content.slice(0, 3000),
+        epic.content.slice(0, 60000),
         ``,
         `---`,
         ``,
@@ -727,6 +729,7 @@ async function main(args) {
           content_hash: contentHash(epic.content),
           child_story_issues: [],
         };
+        if (opts.execute) saveSyncMap(cwd, syncMap);
         console.log(`   ✓ created: ${epic.id} → #${result.number}`);
       }
     }
@@ -766,7 +769,7 @@ async function main(args) {
         ``,
         `## 📋 Source Content`,
         ``,
-        story.content.slice(0, 3000),
+        story.content.slice(0, 60000),
         ``,
         `---`,
         ``,
@@ -807,6 +810,7 @@ async function main(args) {
           synced_at: new Date().toISOString(),
           content_hash: contentHash(story.content),
         };
+        if (opts.execute) saveSyncMap(cwd, syncMap);
         // Remember this child on the parent epic so we can update the
         // epic body with a task list after all stories have been created.
         if (parentEpicEntry) {
@@ -885,7 +889,7 @@ async function main(args) {
         ``,
         `## 📋 Source Content`,
         ``,
-        epic.content.slice(0, 3000),
+        epic.content.slice(0, 60000),
         ``,
         `---`,
         ``,
@@ -930,7 +934,7 @@ async function main(args) {
         ``,
         `## 📋 Source Content`,
         ``,
-        story.content.slice(0, 3000),
+        story.content.slice(0, 60000),
         ``,
         `---`,
         ``,

package/cli/install.js

@@ -690,7 +690,13 @@ function ensureRcodeGitignore(target, options = {}) {
       const start = text.indexOf(BEGIN);
       if (start < 0) return null;
       const endIdx = text.indexOf(END, start);
-      if (endIdx < 0) return null;
+      // If BEGIN exists but END is missing (manual edit removed it), strip
+      // everything from BEGIN to EOF and rewrite — avoids duplicate blocks.
+      if (endIdx < 0) {
+        let sliceStart = start;
+        if (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart -= 1;
+        return text.slice(0, sliceStart) + newBlock;
+      }
       let sliceStart = start;
       if (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart -= 1;
       let sliceEnd = endIdx + END.length;
@@ -765,7 +771,12 @@ function ensureRcodePreCommitHook(target, options = {}) {
       const start = text.indexOf(BEGIN);
       if (start < 0) return null;
       const endIdx = text.indexOf(END, start);
-      if (endIdx < 0) return null;
+      // If BEGIN exists but END is missing, strip from BEGIN to EOF and rewrite.
+      if (endIdx < 0) {
+        let sliceStart = start;
+        if (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart -= 1;
+        return text.slice(0, sliceStart) + newBlock;
+      }
       let sliceStart = start;
       if (sliceStart > 0 && text[sliceStart - 1] === '\n') sliceStart -= 1;
       let sliceEnd = endIdx + END.length;
@@ -1131,14 +1142,41 @@ function generateAgentManifest(plan, target) {
  * Generate files-manifest.csv with SHA256 per installed file. Used by
  * update/doctor to detect drift. Columns: rel, sha256, size.
  */
-function generateFilesManifest(plan, target) {
+function generateFilesManifest(plan, target, { mergeExistingManifest = false } = {}) {
   const rows = [['rel', 'sha256', 'size']];
+  const newRels = new Set();
+
   for (const entry of plan) {
     const filePath = path.join(target, entry.rel);
     if (!fs.existsSync(filePath)) continue;
     const buf = fs.readFileSync(filePath);
-    rows.push([entry.rel.split(path.sep).join('/'), sha256(buf), String(buf.length)]);
+    const rel = entry.rel.split(path.sep).join('/');
+    rows.push([rel, sha256(buf), String(buf.length)]);
+    newRels.add(rel);
+  }
+
+  // Merge old manifest entries that are still on disk but not in the current
+  // plan — this keeps orphaned files traceable by doctor/uninstall even when
+  // --force sweep was not run. Without this, a re-install without --force
+  // silently drops stale files from the manifest, making them invisible.
+  if (mergeExistingManifest) {
+    const manifestPath = path.join(target, '.rihal', '_config', 'files-manifest.csv');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const oldRows = fs.readFileSync(manifestPath, 'utf8').split('\n').slice(1).filter(Boolean);
+        for (const row of oldRows) {
+          const [rel] = row.split(',');
+          if (!rel || newRels.has(rel)) continue;
+          const full = path.join(target, rel);
+          if (!fs.existsSync(full)) continue; // already gone — don't re-add
+          const buf = fs.readFileSync(full);
+          rows.push([rel, sha256(buf), String(buf.length)]);
+          newRels.add(rel);
+        }
+      } catch { /* best-effort */ }
+    }
   }
+
   return rows.map((r) => r.join(',')).join('\n') + '\n';
 }
 
@@ -1764,7 +1802,7 @@ async function install(opts) {
   // self-referential nonsense).
   fs.writeFileSync(
     path.join(configDir, 'files-manifest.csv'),
-    generateFilesManifest(plan, opts.target),
+    generateFilesManifest(plan, opts.target, { mergeExistingManifest: !opts.force }),
   );
 
   // Install v1-style phrase-activated skills (scaffold-project, create-prd,

package/cli/lib/config.cjs

@@ -109,6 +109,10 @@ function projectLevelPath(cwd) {
   return path.join(cwd, '.rihal', 'config.json');
 }
 
+function projectYamlPath(cwd) {
+  return path.join(cwd, '.rihal', 'config.yaml');
+}
+
 // ---------- Loaders ----------
 
 function readJsonSafe(filePath) {
@@ -126,8 +130,33 @@ function loadUserDefaults() {
   return readJsonSafe(userLevelPath()) || {};
 }
 
+// YAML key → JSON key remapping (install.js writes YAML with some different names)
+const YAML_KEY_MAP = {
+  mode: 'communication_mode',
+};
+
+function readYamlFlat(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const result = {};
+    for (const raw of fs.readFileSync(filePath, 'utf8').split('\n')) {
+      const m = raw.match(/^([a-zA-Z_]+):\s*["']?([^"'\n#]+?)["']?\s*(?:#.*)?$/);
+      if (!m) continue;
+      const key = YAML_KEY_MAP[m[1].trim()] || m[1].trim();
+      const val = m[2].trim();
+      result[key] = val === 'true' ? true : val === 'false' ? false : val;
+    }
+    return Object.keys(result).length ? result : null;
+  } catch {
+    return null;
+  }
+}
+
 function loadProjectConfig(cwd) {
-  return readJsonSafe(projectLevelPath(cwd)) || {};
+  const json = readJsonSafe(projectLevelPath(cwd));
+  if (json) return json;
+  // Fall back to config.yaml written by installer — migrate keys on the fly
+  return readYamlFlat(projectYamlPath(cwd)) || {};
 }
 
 /**
@@ -330,5 +359,6 @@ module.exports = {
   loadProjectConfig,
   userLevelPath,
   projectLevelPath,
+  projectYamlPath,
   suggestClosest,
 };

package/cli/lib/fsutil.cjs

@@ -9,6 +9,7 @@
  * a partial truncation.
  */
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
@@ -34,10 +35,10 @@ function writeFileAtomic(filePath, content, opts = {}) {
   const dir = path.dirname(filePath);
   fs.mkdirSync(dir, { recursive: true });
 
-  // Include pid + rand so concurrent processes don't stomp each other's tmp.
+  // Include pid + crypto random so concurrent processes don't collide on tmp.
   const tmpPath = path.join(
     dir,
-    `.${path.basename(filePath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+    `.${path.basename(filePath)}.tmp-${process.pid}-${crypto.randomBytes(8).toString('hex')}`
   );
 
   let fd;

package/cli/lib/manifest.cjs

@@ -108,24 +108,22 @@ function verifyClaudeInstall(cwd, packageRoot) {
   const pkg = readPackageManifest(packageRoot);
   const skillsDir = path.join(cwd, '.claude/skills');
 
-  // Agents are installed as rihal-{name}
+  // Agents are installed as rihal-{name} — strip prefix to match pkg.agents keys
   const installedAgents = readInstalledDirs(skillsDir, 'rihal-');
-  // Agents come back with the 'rihal-' stripped; filter out action skills that
-  // happen to also start with 'rihal-' (they end up in the agents set too).
-  // We resolve this by intersecting: an entry is an agent only if the package
-  // manifest has it as an agent.
-  const agentsInstalled = new Set(
-    [...installedAgents].filter((n) => pkg.agents.has(n))
-  );
+  // Do NOT pre-filter against pkg.agents: we want stale entries (installed but
+  // not in current package) to appear in the `extra` list of diffSet so that
+  // `rcode doctor` can flag them as stale and `rcode uninstall` can remove them.
+  // The old intersection filter was hiding orphaned agent dirs after version bumps.
 
-  // Action skills: installed with their bare name (no rihal- prefix)
+  // Action skills: installed with their bare name (no rihal- prefix).
+  // Exclude known agent dirs (rihal-prefixed) so actions and agents don't bleed.
   const allInstalled = readInstalledDirs(skillsDir);
   const actionsInstalled = new Set(
-    [...allInstalled].filter((n) => pkg.actions.has(n))
+    [...allInstalled].filter((n) => !n.startsWith('rihal-'))
   );
 
   return [
-    diffSet('claude', 'agents', pkg.agents, agentsInstalled),
+    diffSet('claude', 'agents', pkg.agents, installedAgents),
     diffSet('claude', 'actions', pkg.actions, actionsInstalled),
   ];
 }

package/cli/postinstall.js

@@ -24,10 +24,22 @@ const isGlobalInstall = (() => {
   try {
     // npm sets npm_config_global=true for global installs
     if (process.env.npm_config_global === 'true') return true;
-    // Fallback: check if the install prefix is a global npm prefix
-    const prefix = process.env.npm_config_prefix || '';
-    const home = os.homedir();
-    if (prefix && !prefix.startsWith(home) && !prefix.includes('node_modules')) return true;
+    // pnpm sets npm_config_global too, but check PNPM_HOME as a fallback
+    if (process.env.PNPM_HOME && __dirname.startsWith(process.env.PNPM_HOME)) return true;
+    // Check if __dirname is inside a known global node_modules path.
+    // Covers: /usr/local/lib, /usr/lib, ~/.nvm/.../lib, ~/.pnpm/..., ~/.yarn/...
+    const globalPatterns = [
+      /\/node_modules\/@hanzlaa\/rcode/,  // any global node_modules
+      /[/\\]lib[/\\]node_modules[/\\]/,   // /usr/local/lib/node_modules
+      /\.nvm[/\\]versions[/\\]/,           // nvm
+      /\.pnpm[/\\]/,                       // pnpm global store
+      /\.yarn[/\\]global/,                 // yarn global
+    ];
+    if (globalPatterns.some((re) => re.test(__dirname))) return true;
+    // Last resort: package is NOT inside a project's local node_modules
+    // (local installs have .../project/node_modules/@hanzlaa/rcode/cli)
+    const localNodeModules = path.join(process.cwd(), 'node_modules');
+    if (!__dirname.startsWith(localNodeModules)) return true;
     return false;
   } catch {
     return false;

package/dist/rcode.js

@@ -15456,7 +15456,11 @@ Say "plan a sprint" or run \`/rihal-sprint-planning\` to break Phase 01 into sto
           const start = text.indexOf(BEGIN);
           if (start < 0) return null;
           const endIdx = text.indexOf(END, start);
-          if (endIdx < 0) return null;
+          if (endIdx < 0) {
+            let sliceStart2 = start;
+            if (sliceStart2 > 0 && text[sliceStart2 - 1] === "\n") sliceStart2 -= 1;
+            return text.slice(0, sliceStart2) + newBlock;
+          }
           let sliceStart = start;
           if (sliceStart > 0 && text[sliceStart - 1] === "\n") sliceStart -= 1;
           let sliceEnd = endIdx + END.length;
@@ -15512,7 +15516,11 @@ Say "plan a sprint" or run \`/rihal-sprint-planning\` to break Phase 01 into sto
           const start = text.indexOf(BEGIN);
           if (start < 0) return null;
           const endIdx = text.indexOf(END, start);
-          if (endIdx < 0) return null;
+          if (endIdx < 0) {
+            let sliceStart2 = start;
+            if (sliceStart2 > 0 && text[sliceStart2 - 1] === "\n") sliceStart2 -= 1;
+            return text.slice(0, sliceStart2) + newBlock;
+          }
           let sliceStart = start;
           if (sliceStart > 0 && text[sliceStart - 1] === "\n") sliceStart -= 1;
           let sliceEnd = endIdx + END.length;
@@ -15785,13 +15793,34 @@ ${BLOCK}`);
       }
       return rows.map((r) => r.join(",")).join("\n") + "\n";
     }
-    function generateFilesManifest(plan, target) {
+    function generateFilesManifest(plan, target, { mergeExistingManifest = false } = {}) {
       const rows = [["rel", "sha256", "size"]];
+      const newRels = /* @__PURE__ */ new Set();
       for (const entry of plan) {
         const filePath = path2.join(target, entry.rel);
         if (!fs2.existsSync(filePath)) continue;
         const buf = fs2.readFileSync(filePath);
-        rows.push([entry.rel.split(path2.sep).join("/"), sha256(buf), String(buf.length)]);
+        const rel = entry.rel.split(path2.sep).join("/");
+        rows.push([rel, sha256(buf), String(buf.length)]);
+        newRels.add(rel);
+      }
+      if (mergeExistingManifest) {
+        const manifestPath = path2.join(target, ".rihal", "_config", "files-manifest.csv");
+        if (fs2.existsSync(manifestPath)) {
+          try {
+            const oldRows = fs2.readFileSync(manifestPath, "utf8").split("\n").slice(1).filter(Boolean);
+            for (const row of oldRows) {
+              const [rel] = row.split(",");
+              if (!rel || newRels.has(rel)) continue;
+              const full = path2.join(target, rel);
+              if (!fs2.existsSync(full)) continue;
+              const buf = fs2.readFileSync(full);
+              rows.push([rel, sha256(buf), String(buf.length)]);
+              newRels.add(rel);
+            }
+          } catch {
+          }
+        }
       }
       return rows.map((r) => r.join(",")).join("\n") + "\n";
     }
@@ -16296,7 +16325,7 @@ ${BLOCK}`);
       ensureDir(globalAgentsDir);
       fs2.writeFileSync(
         path2.join(configDir, "files-manifest.csv"),
-        generateFilesManifest(plan, opts.target)
+        generateFilesManifest(plan, opts.target, { mergeExistingManifest: !opts.force })
       );
       let skillsInstalled = installSkills(PACKAGE_ROOT2, opts.target);
       try {
@@ -16867,6 +16896,7 @@ var require_prompts = __commonJS({
 // cli/lib/fsutil.cjs
 var require_fsutil = __commonJS({
   "cli/lib/fsutil.cjs"(exports2, module2) {
+    var crypto = require("crypto");
     var fs2 = require("fs");
     var path2 = require("path");
     function writeFileAtomic(filePath, content, opts = {}) {
@@ -16875,7 +16905,7 @@ var require_fsutil = __commonJS({
       fs2.mkdirSync(dir, { recursive: true });
       const tmpPath = path2.join(
         dir,
-        `.${path2.basename(filePath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+        `.${path2.basename(filePath)}.tmp-${process.pid}-${crypto.randomBytes(8).toString("hex")}`
       );
       let fd;
       try {
@@ -16966,15 +16996,12 @@ var require_manifest = __commonJS({
       const pkg = readPackageManifest(packageRoot);
       const skillsDir = path2.join(cwd, ".claude/skills");
       const installedAgents = readInstalledDirs(skillsDir, "rihal-");
-      const agentsInstalled = new Set(
-        [...installedAgents].filter((n) => pkg.agents.has(n))
-      );
       const allInstalled = readInstalledDirs(skillsDir);
       const actionsInstalled = new Set(
-        [...allInstalled].filter((n) => pkg.actions.has(n))
+        [...allInstalled].filter((n) => !n.startsWith("rihal-"))
       );
       return [
-        diffSet("claude", "agents", pkg.agents, agentsInstalled),
+        diffSet("claude", "agents", pkg.agents, installedAgents),
         diffSet("claude", "actions", pkg.actions, actionsInstalled)
       ];
     }
@@ -18242,7 +18269,8 @@ var require_doctor = __commonJS({
       }
     }
     function commandAvailable(cmd) {
-      const result = spawnSync("which", [cmd], { stdio: "ignore" });
+      const checker = process.platform === "win32" ? "where" : "which";
+      const result = spawnSync(checker, [cmd], { stdio: "ignore" });
       return result.status === 0;
     }
     function runPreflight(cwd, packageRoot) {
@@ -18606,6 +18634,9 @@ var require_config = __commonJS({
     function projectLevelPath(cwd) {
       return path2.join(cwd, ".rihal", "config.json");
     }
+    function projectYamlPath(cwd) {
+      return path2.join(cwd, ".rihal", "config.yaml");
+    }
     function readJsonSafe(filePath) {
       if (!fs2.existsSync(filePath)) return null;
       try {
@@ -18617,8 +18648,29 @@ var require_config = __commonJS({
     function loadUserDefaults() {
       return readJsonSafe(userLevelPath()) || {};
     }
+    var YAML_KEY_MAP = {
+      mode: "communication_mode"
+    };
+    function readYamlFlat(filePath) {
+      if (!fs2.existsSync(filePath)) return null;
+      try {
+        const result = {};
+        for (const raw of fs2.readFileSync(filePath, "utf8").split("\n")) {
+          const m = raw.match(/^([a-zA-Z_]+):\s*["']?([^"'\n#]+?)["']?\s*(?:#.*)?$/);
+          if (!m) continue;
+          const key = YAML_KEY_MAP[m[1].trim()] || m[1].trim();
+          const val = m[2].trim();
+          result[key] = val === "true" ? true : val === "false" ? false : val;
+        }
+        return Object.keys(result).length ? result : null;
+      } catch {
+        return null;
+      }
+    }
     function loadProjectConfig(cwd) {
-      return readJsonSafe(projectLevelPath(cwd)) || {};
+      const json = readJsonSafe(projectLevelPath(cwd));
+      if (json) return json;
+      return readYamlFlat(projectYamlPath(cwd)) || {};
     }
     function loadConfig(cwd) {
       const defaults = { ...HARDCODED_DEFAULTS };
@@ -18749,6 +18801,7 @@ var require_config = __commonJS({
       loadProjectConfig,
       userLevelPath,
       projectLevelPath,
+      projectYamlPath,
       suggestClosest
     };
   }
@@ -19936,6 +19989,7 @@ var require_github_sync = __commonJS({
             results.errors.push(`label ${label.name}: ${result.error}`);
           } else if (!result.dryRun) {
             if (!syncMap.labels.includes(label.name)) syncMap.labels.push(label.name);
+            if (opts.execute) saveSyncMap(cwd, syncMap);
             console.log(`   \u2713 ${result.existed ? "exists" : "created"}: ${label.name}`);
           }
         }
@@ -19956,6 +20010,7 @@ var require_github_sync = __commonJS({
               url: result.url,
               synced_at: (/* @__PURE__ */ new Date()).toISOString()
             };
+            if (opts.execute) saveSyncMap(cwd, syncMap);
             console.log(`   \u2713 created: ${phase.id} \u2192 milestone #${result.number}`);
           }
         }
@@ -19971,7 +20026,7 @@ var require_github_sync = __commonJS({
             ``,
             `## \u{1F4CB} Source Content`,
             ``,
-            epic.content.slice(0, 3e3),
+            epic.content.slice(0, 6e4),
             ``,
             `---`,
             ``,
@@ -20009,6 +20064,7 @@ var require_github_sync = __commonJS({
               content_hash: contentHash(epic.content),
               child_story_issues: []
             };
+            if (opts.execute) saveSyncMap(cwd, syncMap);
             console.log(`   \u2713 created: ${epic.id} \u2192 #${result.number}`);
           }
         }
@@ -20033,7 +20089,7 @@ var require_github_sync = __commonJS({
             ``,
             `## \u{1F4CB} Source Content`,
             ``,
-            story.content.slice(0, 3e3),
+            story.content.slice(0, 6e4),
             ``,
             `---`,
             ``,
@@ -20071,6 +20127,7 @@ var require_github_sync = __commonJS({
               synced_at: (/* @__PURE__ */ new Date()).toISOString(),
               content_hash: contentHash(story.content)
             };
+            if (opts.execute) saveSyncMap(cwd, syncMap);
             if (parentEpicEntry) {
               parentEpicEntry.child_story_issues = parentEpicEntry.child_story_issues || [];
               if (!parentEpicEntry.child_story_issues.includes(result.number)) {
@@ -20137,7 +20194,7 @@ ${taskList}
             ``,
             `## \u{1F4CB} Source Content`,
             ``,
-            epic.content.slice(0, 3e3),
+            epic.content.slice(0, 6e4),
             ``,
             `---`,
             ``,
@@ -20179,7 +20236,7 @@ ${taskList}
             ``,
             `## \u{1F4CB} Source Content`,
             ``,
-            story.content.slice(0, 3e3),
+            story.content.slice(0, 6e4),
             ``,
             `---`,
             ``,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.8",
+  "version": "3.4.10",
   "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/agents/rules/executor/task-commit-protocol.md

@@ -10,13 +10,15 @@ After completing a task's implementation, follow this protocol to atomically com
 
 Before writing any commit messages, read the project's commit standard from source — do NOT invent one or ask the user unless nothing is found.
 
-**Check in this order (stop at first hit):**
-
-1. `.github/COMMIT_CONVENTION.md` — explicit commit format doc
-2. `CONTRIBUTING.md` — look for a "Commit" or "Git" section
-3. `.commitlintrc`, `.commitlintrc.json`, `.commitlintrc.yaml`, `commitlint.config.js`, `commitlint.config.cjs` — commitlint config
-4. `package.json` → `"commitlint"` key
-5. `.github/pull_request_template.md` — PR template reveals expected format (e.g., ticket prefix, changelog format)
+**Check in this order — enforcement configs first, docs last (stop at first hit):**
+
+1. `.git/hooks/commit-msg` — the active enforcement hook (if exists and non-empty, read it to detect the validator)
+2. `.husky/commit-msg` — husky-managed commit hook
+3. `.commitlintrc`, `.commitlintrc.json`, `.commitlintrc.yaml`, `.commitlintrc.js`, `commitlint.config.js`, `commitlint.config.cjs` — commitlint config
+4. `package.json` → `"commitlint"` or `"config.commitizen"` key — commitizen config
+5. `.czrc` — commitizen standalone config
+6. `.github/COMMIT_CONVENTION.md` — explicit doc (lower priority than machine configs)
+7. `CONTRIBUTING.md` — look for a "Commit" or "Git" section (lowest priority)
 
 **If a standard is found:** Use it silently for all commits in this sprint. No need to confirm with user.
 

package/rihal/references/auto-init-guard.md

@@ -22,17 +22,30 @@ Tell the user:
 Rihal isn't configured for this project yet. Let me set it up — takes 30 seconds.
 ```
 
-**1. Bootstrap local tooling** — copy bin and workflows from the global install:
+**1. Bootstrap local tooling** — copy bin from the global install:
 
 ```bash
 GLOBAL_RIHAL="$HOME/.rihal"
-if [ -d "$GLOBAL_RIHAL/bin" ]; then
-  mkdir -p .rihal/bin .rihal/workflows .rihal/references
-  cp "$GLOBAL_RIHAL/bin/rihal-tools.cjs" .rihal/bin/ 2>/dev/null || true
-  # workflows and references are read from ~/.rihal at runtime via @.rihal/ resolution
+TOOLS_SRC="$GLOBAL_RIHAL/bin/rihal-tools.cjs"
+
+if [ ! -f "$TOOLS_SRC" ]; then
+  echo "ERROR: Global rihal tools not found at $TOOLS_SRC"
+  echo "Run: npm install -g @hanzlaa/rcode"
+  echo "Then retry this command."
+  # STOP — do not continue without tools; writing config.yaml alone is not enough
+  exit 1
+fi
+
+mkdir -p .rihal/bin
+cp "$TOOLS_SRC" .rihal/bin/rihal-tools.cjs
+if [ $? -ne 0 ]; then
+  echo "ERROR: Could not copy rihal-tools.cjs to .rihal/bin/ (permission denied?)"
+  exit 1
 fi
 ```
 
+Note: workflows and references are resolved from `~/.rihal/` at runtime — only the bin needs to be local.
+
 **2. Ask the 5 config questions** using AskUserQuestion:
 
 | # | Question | Options | Default |
@@ -99,6 +112,6 @@ Continuing with your original request...
 ## Notes
 
 - This guard is **non-blocking** — it asks questions but does not stop the session; once config is written it resumes the original request automatically.
-- If `AskUserQuestion` is unavailable (non-interactive mode), use all defaults and skip the questions.
+- If `AskUserQuestion` is unavailable (non-interactive mode), use all defaults and skip the questions. Always derive `project_name` from `basename $(pwd)` — never leave it as a placeholder.
 - If the bootstrap `cp` fails (global rihal not found), print a warning and attempt to continue — some workflows work without local rihal-tools if they only need config.
 - On **subsequent runs**, the guard exits immediately (config exists) with zero overhead.

package/rihal/workflows/do.md

@@ -296,6 +296,7 @@ Evaluate `$QUESTION` against these routing rules. Apply the **first matching** r
 | Implement a story, "work on story", "dev story", "build story" | `/rihal-dev-story` | Story-level implementation |
 | Find gaps in milestone plans, "gaps in plans", "missing plan", "unplanned phases" | `/rihal-plan-milestone-gaps` | Identify and fill planning gaps |
 | Executing a phase, "build phase N", "run phase N", "implement phase" | `/rihal-execute` | Direct phase execution request |
+| `/rihal-phase <number>` where number matches an existing phase dir | `/rihal-execute <N>` | User mistyped phase instead of execute — detect bare integer + existing dir, route to execute |
 | Running all remaining phases automatically | `/rihal-autonomous` | Full autonomous execution |
 | A review or quality concern about existing work | `/rihal-verify-work` | Needs verification |
 | "Council", "discuss strategy", "should we" | `/rihal-council` | Multi-agent strategic discussion |

package/rihal/workflows/phase.md

@@ -14,7 +14,42 @@ If `$ARGUMENTS` is empty AND no flag is set:
 
 STOP — do not proceed.
 
-## Step 1 — Parse mode flags
+## Step 1 — Disambiguate numeric arguments BEFORE routing
+
+If `$ARGUMENTS` is a bare integer (e.g. `116`, `20`, `7`) with no other words or flags:
+
+```bash
+# Check if a phase directory matching this number already exists
+PHASE_NUM="$ARGUMENTS"
+EXISTING=$(find .planning/phases -maxdepth 1 -type d -name "${PHASE_NUM}-*" 2>/dev/null | head -1)
+```
+
+If `$EXISTING` is non-empty, the user typed a phase number that already exists — they almost certainly meant to operate on it, not create a new one. Stop and ask:
+
+```
+Phase {N} already exists: {directory name}
+
+What did you mean to do?
+
+  /rihal-execute {N}   — execute the sprint plan for this phase
+  /rihal-plan {N}      — re-plan or view the plan for this phase
+  /rihal-status        — see overall project status
+
+  /rihal-phase "{description}"   — add a NEW phase (put the description in quotes)
+```
+
+Do NOT proceed to add/insert/remove. Wait for the user to clarify.
+
+If `$ARGUMENTS` is a bare integer and `$EXISTING` is empty, it's an ambiguous but plausible new-phase name. Proceed to Step 2 but warn:
+
+```
+Note: "{N}" looks like a number. If you meant to execute/plan phase {N}, use /rihal-execute {N} or /rihal-plan {N}.
+Adding a new phase named "{N}" — press Ctrl+C to cancel, or continue.
+```
+
+Then proceed to Step 2.
+
+## Step 1b — Parse mode flags
 
 Inspect `$ARGUMENTS`:
 
@@ -24,7 +59,7 @@ Inspect `$ARGUMENTS`:
 
 Strip the mode flag and pass remaining args to the underlying workflow.
 
-## Step 2 — Dispatch to underlying workflow
+## Step 2 — Dispatch to underlying workflow (after disambiguation)
 
 Each mode is implemented by an existing workflow: