@hanzlaa/rcode 3.4.7 → 3.4.9

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.7",
+  "version": "3.4.9",
   "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

@@ -0,0 +1,117 @@
+# Auto-Init Guard
+
+Run this check at the very start of any workflow that needs project state.
+
+## Step: Detect project initialization
+
+```bash
+test -f .rihal/config.yaml && echo "rihal-ready" || echo "rihal-not-initialized"
+```
+
+**If `rihal-ready`:** continue with the workflow normally.
+
+**If `rihal-not-initialized`:** the user has never set up Rihal for this project. Do NOT fail or continue blindly. Run the project init flow inline before proceeding:
+
+---
+
+### Inline init flow (when config.yaml is missing)
+
+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 from the global install:
+
+```bash
+GLOBAL_RIHAL="$HOME/.rihal"
+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 |
+|---|----------|---------|---------|
+| 1 | Your name (what Rihal calls you) | free text | `$USER` |
+| 2 | Language for agent responses | English / Arabic / Urdu / Roman Urdu | English |
+| 3 | Mode (how Rihal handles decision gates) | `guided` / `yolo` | guided |
+| 4 | Model profile (cost vs quality) | `quality` / `balanced` / `budget` | balanced |
+| 5 | Commit planning artifacts to git? | yes / no | yes |
+
+**3. Write `.rihal/config.yaml` directly** (no rihal-tools needed — plain Bash):
+
+```bash
+mkdir -p .rihal
+cat > .rihal/config.yaml << 'YAML'
+# Rihal project config — edit any time
+user_name: "{name}"
+project_name: "{basename_of_cwd}"
+communication_language: "{lang}"
+mode: "{mode}"
+model_profile: "{profile}"
+commit_planning: {commit_planning_bool}
+rihal_source_path: ""
+workflow:
+  research_by_default: false
+  plan_checker: true
+  post_execute_gates: true
+  ui_safety_gate: true
+git:
+  branching_strategy: "none"
+YAML
+```
+
+**4. Seed `.rihal/state.json` and `.planning/` structure**:
+
+```bash
+mkdir -p .planning/phases .planning/council-sessions .rihal/context
+
+# state.json
+cat > .rihal/state.json << 'JSON'
+{"project":"{project_name}","phase":null,"sprint":null,"sessions":[],"initialized":"now"}
+JSON
+
+# context stubs
+echo "# Active Context\n\n_Run /rihal-init for full setup._" > .rihal/context/active.md
+echo "# Project Brief\n\n_Run /rihal-init for full setup._" > .rihal/context/project-brief.md
+```
+
+**5. Tell the user:**
+
+```
+✓ Rihal configured for this project.
+
+Config saved to .rihal/config.yaml — edit any time.
+Run /rihal-init for a full project scan and context setup.
+
+Continuing with your original request...
+```
+
+**6. Continue** with the original workflow as if it had been initialized from the start.
+
+---
+
+## 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. 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/council.md

@@ -28,6 +28,7 @@ Closure: `RIHAL ► COUNCIL COMPLETE ✓` + Next Up with decision options.
 </output_format>
 
 <required_reading>
+@.rihal/references/auto-init-guard.md
 @.rihal/references/output-format.md
 @.rihal/references/council-protocol.md
 </required_reading>

package/rihal/workflows/do.md

@@ -3,6 +3,7 @@ Analyze freeform text from the user and route to the most appropriate Rihal comm
 </purpose>
 
 <required_reading>
+@.rihal/references/auto-init-guard.md
 @.rihal/references/output-format.md
 @.rihal/references/verb-dictionary.md
 @.rihal/references/dispatch-banner.md
@@ -11,6 +12,11 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <process>
 
+<step name="auto_init_check">
+Run the auto-init guard from `@.rihal/references/auto-init-guard.md` before anything else.
+If the project is not initialized, complete the inline init flow, then continue.
+</step>
+
 <step name="parse_args">
 Extract `$ARGUMENTS`, detect `--auto` flag, and check config mode:
 

package/rihal/workflows/execute.md

@@ -143,6 +143,7 @@ via filesystem and git state.
 </runtime_compatibility>
 
 <required_reading>
+@.rihal/references/auto-init-guard.md
 @.rihal/references/output-format.md
 Read STATE.md before any operation to load project context.
 

package/rihal/workflows/init.md

@@ -1,9 +1,9 @@
 # Workflow: rihal-init
 
 <purpose>
-Begin the rihla. This is the first command a user runs after dropping Rihal files into a project. It detects project state, asks a handful of configuration questions, scans existing context (if any), writes `.rihal/RIHLA.md` as the journey baseline, and routes to the right next command.
+Begin the rihla. This is the entry point for configuring Rihal in a project. Runs automatically on first use of any rihal command (via auto-init-guard in do.md), or explicitly via /rihal-init for a full setup with codebase scan.
 
-This replaces the older `/rihal-generate-project-context` workflow — init is the single entry point for configuring Rihal in a project.
+No manual "rcode install" needed per project — just use any /rihal-* command and this triggers automatically when config is missing.
 </purpose>
 
 ## Step 0 — Usage check

package/rihal/workflows/new-project.md

@@ -4,6 +4,7 @@ Initialize a new project through unified flow: questioning, research (optional),
 </purpose>
 
 <required_reading>
+@.rihal/references/auto-init-guard.md
 @.rihal/references/output-format.md
 
 Read all files referenced by the invoking prompt's execution_context before starting.

package/rihal/workflows/plan.md

@@ -41,6 +41,7 @@ End with Next Up routing to /rihal-execute.
 </output_format>
 
 <required_reading>
+@.rihal/references/auto-init-guard.md
 @.rihal/references/output-format.md
 Read all files referenced by the invoking prompt's execution_context before starting.
 

package/rihal/workflows/status.md

@@ -7,6 +7,7 @@ Render a human-readable project status dashboard. All data comes from a single `
 </purpose>
 
 <required_reading>
+@.rihal/references/auto-init-guard.md
 @.rihal/references/output-format.md
 </required_reading>