@hanzlaa/rcode 4.10.5 → 4.11.0

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `init`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `benchmarks`, `eval`, `scan`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `init`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `benchmarks`, `eval`, `scan`, `verifier`, `discuss-phase`, `ui-phase`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CLAUDE.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `init`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `github-sync`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `rcode`, `review`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `init`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, `getting-started`, `do-router`, `milestone-health`, `modules`, `project-types`, `roadmapper`, `token`, `verifier`, `discuss-phase`, `ui-phase`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -366,6 +366,9 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `benchmarks` — `benchmarks/` scripts and benchmark reports
 - `eval` — `test/eval/` behavioral drift baselines and eval harness
 - `scan` — `/rcode-scan` workflow and existing-codebase analysis
+- `verifier` — `rcode-verifier` agent, verification playbook/rules, VERIFICATION.md flow
+- `discuss-phase` — `/rcode-discuss-phase` workflow and its gray-area/standing checks
+- `ui-phase` — `/rcode-ui-phase` workflow, UI-SPEC.md/WIREFRAMES.md generation, design-library
 - `<phase-id>` — numeric phase scope when committing inside a phase (e.g. `docs(15)`, `feat(8.3)`)
 - `<sprint-id>` — numeric sprint scope inside a phase (e.g. `feat(15.1)`)
 

package/cli/install.js

@@ -159,7 +159,9 @@ const ConfigSchema = z.object({
     branching_strategy: z.string().optional(),
   }).optional(),
   // Declared for validation only — default ('every') lives in the hook (rcode-hooks.cjs prompt-router).
-  // Install does NOT write this key; the feature stays dormant until hooks are opted into via /rcode-enable-hooks.
+  // Install does NOT write this key; the nudge behavior itself is controlled by
+  // whether hooks were enabled at install time (resolveEnableHooks / --no-hooks)
+  // or later via /rcode-enable-hooks.
   prompt_nudge: z.enum(['every', 'once-per-intent', 'when-stale', 'off']).optional(),
 }).passthrough();
 
@@ -199,6 +201,10 @@ function parseArgs(argv) {
     // #199 — git pre-commit hook. null = install if .git/ present (default).
     // Set false by --no-git-hooks, true by --git-hooks.
     gitHooks: null,
+    // Claude Code guardrail hooks (.claude/settings.json). null = resolve via
+    // resolveEnableHooks() (interactive prompt, or default-on for --yes/non-TTY).
+    // Set false by --no-hooks, true by --enable-hooks.
+    enableHooks: null,
     // global install mode — targets ~/.claude/, skips per-project artifacts
     global: false,
     // silent — suppress non-error output (used by postinstall auto-run)
@@ -242,6 +248,8 @@ function parseArgs(argv) {
     else if (arg === '--no-backup') opts.noBackup = true;             // #381
     else if (arg === '--no-git-hooks') opts.gitHooks = false;         // #199
     else if (arg === '--git-hooks') opts.gitHooks = true;             // #199
+    else if (arg === '--no-hooks') opts.enableHooks = false;
+    else if (arg === '--enable-hooks') opts.enableHooks = true;
     else if (arg === '--global') opts.global = true;
     else if (arg === '--local-only') opts.localOnly = true; // #938 — force self-contained install (don't defer to global skills)
     else if (arg === '--silent') opts.silent = true;
@@ -526,6 +534,91 @@ async function resolveCommitPlanning(opts) {
   return choice === 'commit';
 }
 
+/**
+ * Resolve whether to merge rcode's guardrail hooks (pre-edit, bash-guard,
+ * prompt-router, etc.) into .claude/settings.json at install time. Default
+ * is ON — flag wins, else interactive confirm (Y default) on TTY installs,
+ * else default-on for --yes/--no-prompt/non-TTY runs so hooks work out of
+ * the box without requiring a separate /rcode-enable-hooks step.
+ */
+async function resolveEnableHooks(opts) {
+  if (opts.enableHooks !== null) return opts.enableHooks;
+  if (opts.global) return false; // global install has no project-local .claude/settings.json target
+  if (!opts.ides.includes('claude')) return false; // hooks are Claude Code specific
+  if (opts.noPrompt || opts.yes || !process.stdin.isTTY) return true;
+
+  const enable = await clack.confirm({
+    message: '🛡️  Enable rcode guardrail hooks in .claude/settings.json? (pre-edit checks, bash-guard, prompt-router, etc.)',
+    initialValue: true,
+  });
+
+  if (clack.isCancel(enable)) {
+    clack.cancel('Install cancelled.');
+    process.exit(0);
+  }
+
+  return enable;
+}
+
+/**
+ * Merge rcode's opt-in guardrail hooks (rcode/templates/settings-hooks.json)
+ * into .claude/settings.json. Idempotent — skips matcher+command pairs that
+ * already exist. Mirrors the /rcode-enable-hooks workflow so a fresh install
+ * doesn't require running that command separately.
+ *
+ * Returns: { action: 'merged' | 'skipped-flag' | 'skipped-template-missing' | 'skipped-error' }
+ */
+function ensureRcodeSettingsHooks(target, options = {}) {
+  if (options.enableHooks !== true) return { action: 'skipped-flag' };
+
+  const templatePath = path.join(PACKAGE_ROOT, 'rcode', 'templates', 'settings-hooks.json');
+  if (!fs.existsSync(templatePath)) return { action: 'skipped-template-missing' };
+
+  let template;
+  try {
+    template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+  } catch {
+    return { action: 'skipped-error' };
+  }
+
+  const settingsDir = path.join(target, '.claude');
+  const settingsPath = path.join(settingsDir, 'settings.json');
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      return { action: 'skipped-error' };
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+
+  for (const [hookType, matchers] of Object.entries(template.hooks || {})) {
+    settings.hooks[hookType] = settings.hooks[hookType] || [];
+    for (const incoming of matchers) {
+      let existingMatcher = settings.hooks[hookType].find((m) => m.matcher === incoming.matcher);
+      if (!existingMatcher) {
+        existingMatcher = { matcher: incoming.matcher, hooks: [] };
+        settings.hooks[hookType].push(existingMatcher);
+      }
+      for (const hook of incoming.hooks) {
+        const dup = existingMatcher.hooks.some((h) => h.command === hook.command && h.type === hook.type);
+        if (!dup) existingMatcher.hooks.push(hook);
+      }
+    }
+  }
+
+  try {
+    fs.mkdirSync(settingsDir, { recursive: true });
+    writeFileAtomic(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    return { action: 'merged' };
+  } catch {
+    return { action: 'skipped-error' };
+  }
+}
+
 function printHelp() {
   console.log(`
 rcode installer
@@ -542,6 +635,8 @@ Options:
   --language <lang>  set communication_language (default: English)
   --mode <guided|yolo> default mode (default: guided)
   --ide <name>       target IDE (claude, cursor, gemini; default: claude)
+  --enable-hooks     merge rcode guardrail hooks into .claude/settings.json (default: on)
+  --no-hooks         skip guardrail hooks; enable later via /rcode-enable-hooks
   --dry-run          preview what would be written; exit without writing any files
   --list-files       alias for --dry-run
   --help             this text
@@ -969,6 +1064,147 @@ function ensureRcodeGitignore(target, options = {}) {
   }
 }
 
+/**
+ * Splice a BEGIN/END-delimited block into a text file, creating the file if
+ * missing, replacing the block in place if a prior version exists, or
+ * appending if the file exists without the block yet. Shared by any
+ * "own one marked section of a user-owned file" writer (gitignore, rule
+ * files, etc.) so the splice logic (and its edge cases — missing END,
+ * trailing newlines) lives in one place.
+ *
+ * Returns: { action: 'created' | 'appended' | 'updated' | 'already-present' | 'skipped-error', error? }
+ */
+function spliceMarkedBlockIntoFile(filePath, begin, end, block) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      writeFileAtomic(filePath, block);
+      return { action: 'created' };
+    }
+    const existing = fs.readFileSync(filePath, 'utf8');
+
+    function splice(text, newBlock) {
+      const start = text.indexOf(begin);
+      if (start < 0) return null;
+      const endIdx = text.indexOf(end, start);
+      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;
+      if (text[sliceEnd] === '\n') sliceEnd += 1;
+      return text.slice(0, sliceStart) + newBlock + text.slice(sliceEnd);
+    }
+
+    if (existing.includes(begin)) {
+      const rewritten = splice(existing, block);
+      if (rewritten !== null && rewritten !== existing) {
+        writeFileAtomic(filePath, rewritten);
+        return { action: 'updated' };
+      }
+      return { action: 'already-present' };
+    }
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    writeFileAtomic(filePath, existing + sep + block);
+    return { action: 'appended' };
+  } catch (err) {
+    return { action: 'skipped-error', error: err.message };
+  }
+}
+
+/**
+ * Ensure every installed IDE's rule file carries a short, rcode-owned block
+ * pointing agents at `/rcode-do` as the preferred entry point for non-trivial
+ * work. This is NOT a full CLAUDE.md/AGENTS.md rewrite — it only owns its own
+ * marked section (or, for cursor/windsurf, a dedicated rcode-* rule file) so
+ * a project's existing rule content is never touched or reordered.
+ *
+ * - claude / vscode → root CLAUDE.md (splice, file created if missing)
+ * - codex           → root AGENTS.md (splice, file created if missing)
+ * - cursor          → .cursor/rules/rcode-prefer-do.mdc (dedicated, always rewritten)
+ * - windsurf        → .windsurf/rules/rcode-prefer-do.mdc (dedicated, always rewritten)
+ * - gemini / antigravity / grok → skipped (no single canonical project rule file yet)
+ *
+ * Returns: { [ide]: { action, error? } } per IDE actually written.
+ */
+function ensureRcodePreferredCommandRule(target, ides) {
+  const results = {};
+  const idSet = new Set(ides || []);
+
+  const md = (heading) => [
+    `## ${heading}`,
+    '',
+    'This project has [rcode](https://www.npmjs.com/package/@hanzlaa/rcode) installed —',
+    'persistent project memory, specialist agents, and structured workflows under `.rcode/`.',
+    '',
+    'For any non-trivial task (new feature, bug fix that needs investigation, multi-file',
+    'change, planning) prefer routing through **`/rcode-do <task description>`** — rcode\'s',
+    'command picker — instead of working ad hoc. It picks the right rcode command (plan,',
+    'execute, review, debug, etc.) for the task and keeps `.rcode/state.json` and the',
+    'Memory Bank in sync. Skip it only for trivial single-line/single-file edits that',
+    'don\'t need planning or memory.',
+  ].join('\n');
+
+  if (idSet.has('claude') || idSet.has('vscode')) {
+    const BEGIN = '<!-- ===== rcode-managed rule block (npx @hanzlaa/rcode install) ===== -->';
+    const END = '<!-- ===== end rcode-managed rule block ===== -->';
+    const block = `${BEGIN}\n\n${md('Working with rcode')}\n\n${END}\n`;
+    results.claude = spliceMarkedBlockIntoFile(path.join(target, 'CLAUDE.md'), BEGIN, END, block);
+  }
+
+  if (idSet.has('codex')) {
+    const BEGIN = '<!-- ===== rcode-managed rule block (npx @hanzlaa/rcode install) ===== -->';
+    const END = '<!-- ===== end rcode-managed rule block ===== -->';
+    const block = `${BEGIN}\n\n${md('Working with rcode')}\n\n${END}\n`;
+    results.codex = spliceMarkedBlockIntoFile(path.join(target, 'AGENTS.md'), BEGIN, END, block);
+  }
+
+  if (idSet.has('cursor')) {
+    const content = [
+      '---',
+      'description: Prefer rcode\'s /rcode-do command for non-trivial work',
+      'alwaysApply: true',
+      '---',
+      '',
+      md('Working with rcode'),
+      '',
+    ].join('\n');
+    try {
+      const p = path.join(target, '.cursor', 'rules', 'rcode-prefer-do.mdc');
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      writeFileAtomic(p, content);
+      results.cursor = { action: 'written' };
+    } catch (err) {
+      results.cursor = { action: 'skipped-error', error: err.message };
+    }
+  }
+
+  if (idSet.has('windsurf')) {
+    const content = [
+      '---',
+      'description: Prefer rcode\'s /rcode-do command for non-trivial work',
+      'trigger: always_on',
+      '---',
+      '',
+      md('Working with rcode'),
+      '',
+    ].join('\n');
+    try {
+      const p = path.join(target, '.windsurf', 'rules', 'rcode-prefer-do.mdc');
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      writeFileAtomic(p, content);
+      results.windsurf = { action: 'written' };
+    } catch (err) {
+      results.windsurf = { action: 'skipped-error', error: err.message };
+    }
+  }
+
+  return results;
+}
+
 /**
  * Ensure .git/hooks/pre-commit includes the rcode-managed block that auto-syncs
  * state.json when .planning/ or .rcode/brain/sources.yaml files change.
@@ -2071,6 +2307,9 @@ async function installInner(opts) {
   // Resolve commit-planning preference (interactive prompt or flag) — #189.
   opts.commitPlanning = await resolveCommitPlanning(opts);
 
+  // Resolve guardrail-hooks preference (interactive prompt or flag). Default on.
+  opts.enableHooks = await resolveEnableHooks(opts);
+
   console.log(`\n🕌 ${bold('rcode')} ${pc.cyan('v' + pkgVersion)} ${dim('→')} ${opts.target}`);
 
   // Detect an existing install and surface it (#195).
@@ -2771,6 +3010,14 @@ async function installInner(opts) {
   // Respects --no-git-hooks flag; skips silently when .git/ is absent.
   const hookReport = ensureRcodePreCommitHook(opts.target, { gitHooks: opts.gitHooks });
 
+  // Merge rcode guardrail hooks into .claude/settings.json (pre-edit, bash-guard,
+  // prompt-router, etc). Default-on; resolved above via resolveEnableHooks().
+  const settingsHooksReport = ensureRcodeSettingsHooks(opts.target, { enableHooks: opts.enableHooks });
+
+  // Point each installed IDE's rule file at /rcode-do as the preferred entry point
+  // for non-trivial work — an rcode-owned marked block/file, not a full rewrite.
+  const preferredCommandReports = ensureRcodePreferredCommandRule(opts.target, opts.ides);
+
   // Pull rcode brain content (v2.0 — issue #158).
   // Runs rcode-tools brain pull as a detached background process. Placeholder
   // URLs are skipped gracefully so this does not fail a fresh install.
@@ -2835,6 +3082,30 @@ async function installInner(opts) {
     }[hookReport.action] || 'pre-commit hook unchanged';
     console.log('  ' + dim(hookMsg));
   }
+  if (settingsHooksReport) {
+    const settingsHooksMsg = {
+      'merged': 'guardrail hooks enabled (.claude/settings.json)',
+      'skipped-flag': 'guardrail hooks skipped (--no-hooks or declined)',
+      'skipped-template-missing': 'guardrail hooks skipped (settings-hooks.json template missing)',
+      'skipped-error': 'guardrail hooks skipped (error merging .claude/settings.json)',
+    }[settingsHooksReport.action] || 'guardrail hooks unchanged';
+    console.log('  ' + dim(settingsHooksMsg));
+  }
+  if (preferredCommandReports && Object.keys(preferredCommandReports).length > 0) {
+    const RULE_FILE = { claude: 'CLAUDE.md', codex: 'AGENTS.md', cursor: '.cursor/rules/rcode-prefer-do.mdc', windsurf: '.windsurf/rules/rcode-prefer-do.mdc' };
+    for (const [ide, report] of Object.entries(preferredCommandReports)) {
+      const file = RULE_FILE[ide] || ide;
+      const msg = {
+        'created': `${file}: /rcode-do rule added`,
+        'appended': `${file}: /rcode-do rule appended`,
+        'updated': `${file}: /rcode-do rule refreshed`,
+        'already-present': `${file}: /rcode-do rule already present`,
+        'written': `${file}: /rcode-do rule written`,
+        'skipped-error': `${file}: /rcode-do rule skipped (${report.error})`,
+      }[report.action] || `${file}: /rcode-do rule unchanged`;
+      console.log('  ' + dim(msg));
+    }
+  }
   if (skipped > 0) console.log('  ' + dim(`${skipped} files skipped (unchanged)`));
 
   // Diff display for preserved files (#251)