@imdeadpool/guardex 6.1.0 → 7.0.0

package/bin/multiagent-safety.js

@@ -54,7 +54,6 @@ const TEMPLATE_FILES = [
   'githooks/pre-commit',
   'githooks/pre-push',
   'githooks/post-merge',
-  'githooks/post-checkout',
   'codex/skills/guardex/SKILL.md',
   'codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   'claude/commands/guardex.md',
@@ -98,7 +97,6 @@ const EXECUTABLE_RELATIVE_PATHS = new Set([
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
-  '.githooks/post-checkout',
 ]);
 
 const CRITICAL_GUARDRAIL_PATHS = new Set([
@@ -106,7 +104,6 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
-  '.githooks/post-checkout',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/agent-worktree-prune.sh',
@@ -134,7 +131,6 @@ const MANAGED_GITIGNORE_PATHS = [
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
-  '.githooks/post-checkout',
   'oh-my-codex/',
   '.codex/skills/guardex/SKILL.md',
   '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
@@ -167,158 +163,84 @@ const COMMAND_TYPO_ALIASES = new Map([
 const SUGGESTIBLE_COMMANDS = [
   'status',
   'setup',
-  'init',
   'doctor',
-  'review',
   'agents',
   'finish',
   'report',
-  'copy-prompt',
-  'copy-commands',
   'protect',
   'sync',
   'cleanup',
-  'release',
+  'prompt',
+  'help',
+  'version',
+  // deprecated aliases still routable with a warning
+  'init',
   'install',
   'fix',
   'scan',
+  'review',
+  'copy-prompt',
+  'copy-commands',
   'print-agents-snippet',
-  'help',
-  'version',
+  'release',
 ];
 const CLI_COMMAND_DESCRIPTIONS = [
   ['status', 'Show GuardeX CLI + service health without modifying files'],
-  ['setup', 'Install + repair guardrails in a git repo (supports --no-gitignore, --parent-workspace-view)'],
-  ['init', 'Alias of setup (bootstrap + repair guardrails in a git repo)'],
-  ['doctor', 'Repair safety setup drift, then verify repo safety'],
-  ['report', 'Generate security/safety reports (for example: OpenSSF scorecard)'],
-  ['finish', 'Auto-commit completed agent branches, then run PR finish flow'],
-  ['copy-prompt', 'Print the AI-ready setup checklist'],
-  ['copy-commands', 'Print setup checklist as executable commands only'],
+  ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target)'],
+  ['doctor', 'Repair drift + verify (auto-sandboxes on protected main)'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
-  ['sync', 'Check or sync agent branches with origin/<base>'],
-  ['cleanup', 'Cleanup agent branches/worktrees (watch mode defaults to 60-minute idle threshold)'],
+  ['sync', 'Sync agent branches with origin/<base>'],
+  ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
+  ['cleanup', 'Prune merged/stale agent branches and worktrees'],
   ['agents', 'Start/stop repo-scoped review + cleanup bots'],
-  ['install', 'Install templates/locks/hooks without running full setup (supports --no-gitignore)'],
-  ['fix', 'Repair broken or missing guardrail files/config (supports --no-gitignore)'],
-  ['scan', 'Report safety issues and exit non-zero on findings'],
-  ['print-agents-snippet', 'Print the AGENTS.md snippet template'],
-  ['release', 'Publish GuardeX from maintainer release repo'],
+  ['prompt', 'Print AI setup checklist (--exec, --snippet)'],
+  ['report', 'Security/safety reports (e.g. OpenSSF scorecard)'],
   ['help', 'Show this help output'],
   ['version', 'Print GuardeX version'],
 ];
-const CORE_COMMAND_NAMES = new Set([
-  'setup',
-  'doctor',
-  'status',
-  'finish',
-  'cleanup',
-  'sync',
-  'scan',
+const DEPRECATED_COMMAND_ALIASES = new Map([
+  ['init', { target: 'setup', hint: 'gx setup' }],
+  ['install', { target: 'setup', hint: 'gx setup --install-only' }],
+  ['fix', { target: 'setup', hint: 'gx setup --repair' }],
+  ['scan', { target: 'status', hint: 'gx status --strict' }],
+  ['copy-prompt', { target: 'prompt', hint: 'gx prompt' }],
+  ['copy-commands', { target: 'prompt', hint: 'gx prompt --exec' }],
+  ['print-agents-snippet', { target: 'prompt', hint: 'gx prompt --snippet' }],
+  ['review', { target: 'agents', hint: 'gx agents start (runs review + cleanup)' }],
 ]);
 const AGENT_BOT_DESCRIPTIONS = [
-  ['review', 'Start PR monitor + codex-agent review flow (default interval: 30s)'],
-  ['agents', 'Start/stop both review and cleanup bots for this repo'],
+  ['agents', 'Start/stop review + cleanup bots for this repo'],
 ];
 
-const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-Rex for your repo) in this repository for Codex or Claude.
-
-1) Install (if missing):
-   npm i -g @imdeadpool/guardex
-
-2) Bootstrap safety in this repo:
-   gx setup
-   # alias: gx init
-
-   - Setup detects global OMX/OpenSpec/codex-auth npm packages first.
-   - If one is missing and setup asks for approval, reply explicitly:
-     - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
-     - n = skip global installs
-   - Setup also checks GitHub CLI (gh), required for PR/merge automation.
-   - If gh is missing: install it from https://cli.github.com/ and rerun gx setup.
-
-3) If setup reports warnings/errors, repair + re-check:
-   gx doctor
-
-4) Optional: start continuous PR monitor from this repo:
-   gx review --interval 30
-
-5) Confirm next safe agent workflow commands:
-   bash scripts/codex-agent.sh "task" "agent-name"
-   bash scripts/agent-branch-start.sh "task" "agent-name"
-   python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
-   bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --base dev --via-pr --wait-for-merge
-   - For every new user message/task, repeat the same cycle:
-     start isolated agent branch/worktree -> claim file locks -> implement/verify ->
-     finish via PR/merge cleanup into dev with scripts/agent-branch-finish.sh.
-   - Finished branches stay available by default for audit/follow-up.
-     Remove them explicitly when done:
-     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
-   - To finalize all completed agent branches in one pass:
-     gx finish --all
-
-6) OpenSpec default change flow (core profile):
-   /opsx:propose <change-name>
-   /opsx:apply
-   /opsx:archive
-   - Full guide: docs/openspec-getting-started.md
-
-7) Optional: enable expanded OpenSpec workflow commands:
-   openspec config profile <profile-name>
-   openspec update
-   - Expanded path: /opsx:new -> /opsx:ff or /opsx:continue -> /opsx:apply -> /opsx:verify -> /opsx:archive
-
-8) Optional: create OpenSpec planning workspace:
-   bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
-
-9) Optional: protect extra branches:
-   gx protect add release staging
-
-10) Optional: sync your current agent branch with latest base branch:
-   gx sync --check
-   gx sync
-
-11) Optional (GitHub remote cleanup): enable:
-   Settings -> General -> Pull Requests -> Automatically delete head branches
-
-12) Optional (fork sync with Pull app):
-   cp .github/pull.yml.example .github/pull.yml
-   # then edit .github/pull.yml:
-   # - set rules[].base to your fork branch (main/master/dev)
-   # - set rules[].upstream to upstream-owner:branch
-   # install app: https://github.com/apps/pull
-   # validate config: https://pull.git.ci/check/<owner>/<repo>
-
-13) Optional (PR review bot with cr-gpt GitHub App):
-   - install app: https://github.com/apps/cr-gpt
-   - in GitHub repo Settings -> Secrets and variables -> Actions -> Variables:
-     add OPENAI_API_KEY (your API key)
-   - the app reviews new/updated pull requests automatically
-
-14) Optional: test PR review action workflow
-   - gx setup installs .github/workflows/cr.yml
-   - open or update a PR
-   - check Actions -> "Code Review" run logs + PR timeline comments
+const AI_SETUP_PROMPT = `GuardeX (gx) setup checklist for Codex/Claude in this repo.
+
+1) Install:         npm i -g @imdeadpool/guardex && gh --version
+2) Bootstrap:       gx setup         # installs hooks/templates + verifies; prompts Y/N for global OMX/OpenSpec/codex-auth
+3) If degraded:     gx doctor        # repair + re-verify
+4) Per task:        bash scripts/codex-agent.sh "<task>" "<agent>"
+                    # or manual:
+                    #   bash scripts/agent-branch-start.sh "<task>" "<agent>"
+                    #   python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
+                    #   bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --via-pr --wait-for-merge
+5) Finalize all:    gx finish --all
+6) Cleanup:         gx cleanup
+7) OpenSpec:        /opsx:propose -> /opsx:apply -> /opsx:archive   (see docs/openspec-getting-started.md)
+8) Protect:         gx protect add release staging                  (optional)
+9) Sync:            gx sync --check && gx sync                      (optional; rebase onto base)
+10) Fork sync:      cp .github/pull.yml.example .github/pull.yml    (optional; install https://github.com/apps/pull)
+11) PR review bot:  install https://github.com/apps/cr-gpt + set OPENAI_API_KEY in Actions variables (uses .github/workflows/cr.yml)
+12) GitHub repo:    enable Settings -> PRs -> Automatically delete head branches
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
 gh --version
 gx setup
 gx doctor
-gx review --interval 30
-bash scripts/codex-agent.sh "task" "agent-name"
-bash scripts/agent-branch-start.sh "task" "agent-name"
-python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
-bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --base dev --via-pr --wait-for-merge
+bash scripts/codex-agent.sh "<task>" "<agent>"
 gx finish --all
-gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
-bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
-openspec config profile <profile-name>
-openspec update
+gx cleanup
 gx protect add release staging
-gx sync --check
 gx sync
-cp .github/pull.yml.example .github/pull.yml
 `;
 
 const SCORECARD_RISK_BY_CHECK = {
@@ -364,15 +286,12 @@ function statusDot(status) {
   return colorize('●', '33'); // yellow for degraded/unknown
 }
 
-function commandCatalogLines(indent = '  ', { coreOnly = false } = {}) {
-  const entries = coreOnly
-    ? CLI_COMMAND_DESCRIPTIONS.filter(([name]) => CORE_COMMAND_NAMES.has(name))
-    : CLI_COMMAND_DESCRIPTIONS;
-  const maxCommandLength = entries.reduce(
+function commandCatalogLines(indent = '  ') {
+  const maxCommandLength = CLI_COMMAND_DESCRIPTIONS.reduce(
     (max, [command]) => Math.max(max, command.length),
     0,
   );
-  return entries.map(
+  return CLI_COMMAND_DESCRIPTIONS.map(
     ([command, description]) => `${indent}${command.padEnd(maxCommandLength + 2)}${description}`,
   );
 }
@@ -389,7 +308,7 @@ function agentBotCatalogLines(indent = '  ') {
 
 function printToolLogsSummary() {
   const usageLine = `    $ ${SHORT_TOOL_NAME} <command> [options]`;
-  const commandDetails = commandCatalogLines('    ', { coreOnly: true });
+  const commandDetails = commandCatalogLines('    ');
   const agentBotDetails = agentBotCatalogLines('    ');
 
   if (!supportsAnsiColors()) {
@@ -434,7 +353,7 @@ function printToolLogsSummary() {
     }
     console.log(`  ${pipe}${line.slice(2)}`);
   }
-  console.log(`  ${corner}─ ${colorize(`Try '${SHORT_TOOL_NAME} doctor' to repair drift, or '${SHORT_TOOL_NAME} help' for the full command list.`, '2')}`);
+  console.log(`  ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
 }
 
 function usage(options = {}) {
@@ -455,19 +374,12 @@ AGENT BOT
 ${agentBotCatalogLines().join('\n')}
 
 NOTES
-  - Running ${TOOL_NAME} with no command defaults to: ${SHORT_TOOL_NAME} status
-  - Short alias: ${SHORT_TOOL_NAME}
-  - ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup
-  - ${TOOL_NAME} setup asks for Y/N approval before global installs
-  - ${TOOL_NAME} setup checks GitHub CLI (gh) and prints install guidance if missing
-  - For other repos: ${SHORT_TOOL_NAME} setup --target <repo-path> then ${SHORT_TOOL_NAME} doctor --target <repo-path>
-  - Optional parent-folder Source Control view: ${SHORT_TOOL_NAME} setup --target <repo-path> --parent-workspace-view
-  - In initialized repos, setup/install/fix block in-place writes on protected main by default
-  - setup/doctor auto-finish clean pending agent/* branches via PR flow into the current local base branch
-  - doctor auto-runs in a sandbox agent branch/worktree on protected main and tries auto-finish PR flow
-  - agent-branch-finish merges by default and keeps agent branches/worktrees until explicit cleanup
-  - use '${SHORT_TOOL_NAME} cleanup' to remove merged agent branches/worktrees (optionally remote refs too)
-  - Legacy command aliases are still supported: ${LEGACY_NAMES.join(', ')}`);
+  - No command = ${SHORT_TOOL_NAME} status. ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup.
+  - Global installs need Y/N approval; GitHub CLI (gh) is required for PR automation.
+  - Target another repo: ${SHORT_TOOL_NAME} <cmd> --target <repo-path>.
+  - On protected main, setup/install/fix/doctor auto-sandbox via agent branch + PR flow.
+  - Run '${SHORT_TOOL_NAME} cleanup' to prune merged agent branches/worktrees.
+  - Legacy aliases: ${LEGACY_NAMES.join(', ')}.`);
 
   if (outsideGitRepo) {
     console.log(`
@@ -513,6 +425,90 @@ function isGitRepo(targetPath) {
   return result.status === 0;
 }
 
+const NESTED_REPO_DEFAULT_MAX_DEPTH = 6;
+const NESTED_REPO_DEFAULT_SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.cache',
+  'target',
+  'vendor',
+  '.venv',
+  '.pnpm-store',
+]);
+const NESTED_REPO_WORKTREE_RELATIVE_DIR = path.join('.omx', 'agent-worktrees');
+
+function discoverNestedGitRepos(rootPath, opts = {}) {
+  const maxDepth = Number.isFinite(opts.maxDepth) ? Math.max(1, opts.maxDepth) : NESTED_REPO_DEFAULT_MAX_DEPTH;
+  const extraSkip = new Set(Array.isArray(opts.extraSkip) ? opts.extraSkip : []);
+  const includeSubmodules = Boolean(opts.includeSubmodules);
+  const resolvedRoot = path.resolve(rootPath);
+
+  const rootCommonDir = (() => {
+    const result = run('git', ['-C', resolvedRoot, 'rev-parse', '--git-common-dir'], { cwd: resolvedRoot });
+    if (result.status !== 0) return null;
+    const raw = result.stdout.trim();
+    if (!raw) return null;
+    return path.resolve(resolvedRoot, raw);
+  })();
+
+  const workreeSkipAbsolute = path.join(resolvedRoot, NESTED_REPO_WORKTREE_RELATIVE_DIR);
+  const found = new Set();
+  found.add(resolvedRoot);
+
+  function shouldSkipDir(dirName) {
+    return NESTED_REPO_DEFAULT_SKIP_DIRS.has(dirName) || extraSkip.has(dirName);
+  }
+
+  function walk(currentPath, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(currentPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(currentPath, entry.name);
+
+      if (entry.name === '.git') {
+        if (entry.isDirectory()) {
+          if (entryPath === path.join(resolvedRoot, '.git')) continue;
+          found.add(path.dirname(entryPath));
+        } else if (includeSubmodules && entry.isFile()) {
+          found.add(path.dirname(entryPath));
+        }
+        continue;
+      }
+
+      if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+      if (shouldSkipDir(entry.name)) continue;
+      if (entryPath === workreeSkipAbsolute) continue;
+      walk(entryPath, depth + 1);
+    }
+  }
+
+  walk(resolvedRoot, 0);
+
+  const filtered = Array.from(found).filter((repoPath) => {
+    if (repoPath === resolvedRoot) return true;
+    if (!rootCommonDir) return true;
+    const childResult = run('git', ['-C', repoPath, 'rev-parse', '--git-common-dir'], { cwd: repoPath });
+    if (childResult.status !== 0) return true;
+    const childCommonDirRaw = childResult.stdout.trim();
+    if (!childCommonDirRaw) return true;
+    const childCommonDir = path.resolve(repoPath, childCommonDirRaw);
+    return childCommonDir !== rootCommonDir;
+  });
+
+  const [root, ...rest] = filtered;
+  rest.sort((a, b) => a.localeCompare(b));
+  return [root, ...rest];
+}
+
 function toDestinationPath(relativeTemplatePath) {
   if (relativeTemplatePath.startsWith('scripts/')) {
     return relativeTemplatePath;
@@ -709,7 +705,8 @@ function writeLockState(repoRoot, payload, dryRun) {
   fs.writeFileSync(lockPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
 }
 
-function ensurePackageScripts(repoRoot, dryRun) {
+function ensurePackageScripts(repoRoot, dryRun, options = {}) {
+  const force = Boolean(options.force);
   const packagePath = path.join(repoRoot, 'package.json');
   if (!fs.existsSync(packagePath)) {
     return { status: 'skipped', file: 'package.json', note: 'package.json not found' };
@@ -722,30 +719,15 @@ function ensurePackageScripts(repoRoot, dryRun) {
     throw new Error(`Unable to parse package.json in target repo: ${error.message}`);
   }
 
-  const wantedScripts = {
-    'agent:codex': 'bash ./scripts/codex-agent.sh',
-    'agent:review:watch': 'bash ./scripts/review-bot-watch.sh',
-    'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
-    'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
-    'agent:finish': `${SHORT_TOOL_NAME} finish --all`,
-    'agent:cleanup': `${SHORT_TOOL_NAME} cleanup`,
-    'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
-    'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
-    'agent:locks:allow-delete': 'python3 ./scripts/agent-file-locks.py allow-delete',
-    'agent:locks:release': 'python3 ./scripts/agent-file-locks.py release',
-    'agent:locks:status': 'python3 ./scripts/agent-file-locks.py status',
-    'agent:plan:init': 'bash ./scripts/openspec/init-plan-workspace.sh',
-    'agent:change:init': 'bash ./scripts/openspec/init-change-workspace.sh',
-    'agent:protect:list': `${SHORT_TOOL_NAME} protect list`,
-    'agent:branch:sync': `${SHORT_TOOL_NAME} sync`,
-    'agent:branch:sync:check': `${SHORT_TOOL_NAME} sync --check`,
-    'agent:safety:setup': `${SHORT_TOOL_NAME} setup`,
-    'agent:safety:scan': `${SHORT_TOOL_NAME} scan`,
-    'agent:safety:fix': `${SHORT_TOOL_NAME} fix`,
-    'agent:safety:doctor': `${SHORT_TOOL_NAME} doctor`,
-  };
+  const existingScripts = pkg.scripts && typeof pkg.scripts === 'object'
+    ? pkg.scripts
+    : {};
+  const hasExistingAgentScripts = Object.keys(existingScripts).some((key) => key.startsWith('agent:'));
+  if (hasExistingAgentScripts && !force) {
+    return { status: 'unchanged', file: 'package.json', note: 'preserved existing agent:* scripts' };
+  }
 
-  pkg.scripts = pkg.scripts || {};
+  pkg.scripts = existingScripts;
   let changed = false;
   for (const [key, value] of Object.entries(REQUIRED_PACKAGE_SCRIPTS)) {
     if (pkg.scripts[key] !== value) {
@@ -765,7 +747,8 @@ function ensurePackageScripts(repoRoot, dryRun) {
   return { status: 'updated', file: 'package.json' };
 }
 
-function ensureAgentsSnippet(repoRoot, dryRun) {
+function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
+  const force = Boolean(options.force);
   const agentsPath = path.join(repoRoot, 'AGENTS.md');
   const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
   const managedRegex = new RegExp(
@@ -782,6 +765,9 @@ function ensureAgentsSnippet(repoRoot, dryRun) {
 
   const existing = fs.readFileSync(agentsPath, 'utf8');
   if (managedRegex.test(existing)) {
+    if (!force) {
+      return { status: 'unchanged', file: 'AGENTS.md', note: 'preserved existing guardex-managed block' };
+    }
     const next = existing.replace(managedRegex, snippet);
     if (next === existing) {
       return { status: 'unchanged', file: 'AGENTS.md' };
@@ -925,10 +911,18 @@ function parseCommonArgs(rawArgs, defaults) {
 }
 
 function parseSetupArgs(rawArgs, defaults) {
-  const setupDefaults = { ...defaults, parentWorkspaceView: false };
+  const setupDefaults = {
+    ...defaults,
+    parentWorkspaceView: false,
+    recursive: true,
+    nestedMaxDepth: NESTED_REPO_DEFAULT_MAX_DEPTH,
+    nestedSkipDirs: [],
+    includeSubmodules: false,
+  };
   const forwardedArgs = [];
 
-  for (const arg of rawArgs) {
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
     if (arg === '--parent-workspace-view') {
       setupDefaults.parentWorkspaceView = true;
       continue;
@@ -937,6 +931,34 @@ function parseSetupArgs(rawArgs, defaults) {
       setupDefaults.parentWorkspaceView = false;
       continue;
     }
+    if (arg === '--no-recursive' || arg === '--no-nested' || arg === '--single-repo') {
+      setupDefaults.recursive = false;
+      continue;
+    }
+    if (arg === '--recursive' || arg === '--nested') {
+      setupDefaults.recursive = true;
+      continue;
+    }
+    if (arg === '--max-depth') {
+      const raw = requireValue(rawArgs, index, '--max-depth');
+      const parsed = Number.parseInt(raw, 10);
+      if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error('--max-depth requires a positive integer');
+      }
+      setupDefaults.nestedMaxDepth = parsed;
+      index += 1;
+      continue;
+    }
+    if (arg === '--skip-nested') {
+      const raw = requireValue(rawArgs, index, '--skip-nested');
+      setupDefaults.nestedSkipDirs.push(raw);
+      index += 1;
+      continue;
+    }
+    if (arg === '--include-submodules') {
+      setupDefaults.includeSubmodules = true;
+      continue;
+    }
     forwardedArgs.push(arg);
   }
 
@@ -1092,6 +1114,7 @@ function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
 function buildSandboxDoctorArgs(options, sandboxTarget) {
   const args = ['doctor', '--target', sandboxTarget];
   if (options.dryRun) args.push('--dry-run');
+  if (options.force) args.push('--force');
   if (options.skipAgents) args.push('--skip-agents');
   if (options.skipPackageJson) args.push('--skip-package-json');
   if (options.skipGitignore) args.push('--no-gitignore');
@@ -3528,11 +3551,11 @@ function runInstallInternal(options) {
   }
 
   if (!options.skipPackageJson) {
-    operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun)));
+    operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
   }
 
   if (!options.skipAgents) {
-    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun)));
+    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
   }
 
   const hookResult = configureHooks(repoRoot, Boolean(options.dryRun));
@@ -3582,11 +3605,11 @@ function runFixInternal(options) {
   }
 
   if (!options.skipPackageJson) {
-    operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun)));
+    operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
   }
 
   if (!options.skipAgents) {
-    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun)));
+    operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
   }
 
   const hookResult = configureHooks(repoRoot, Boolean(options.dryRun));
@@ -4453,23 +4476,87 @@ function setup(rawArgs) {
     }
   }
 
-  assertProtectedMainWriteAllowed(options, 'setup');
-  const installPayload = runInstallInternal(options);
-  installPayload.operations.push(ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)));
-  if (options.parentWorkspaceView) {
-    installPayload.operations.push(ensureParentWorkspaceView(installPayload.repoRoot, Boolean(options.dryRun)));
+  const topRepoRoot = resolveRepoRoot(options.target);
+  const discoveredRepos = options.recursive
+    ? discoverNestedGitRepos(topRepoRoot, {
+        maxDepth: options.nestedMaxDepth,
+        extraSkip: options.nestedSkipDirs,
+        includeSubmodules: options.includeSubmodules,
+      })
+    : [topRepoRoot];
+
+  if (discoveredRepos.length > 1) {
+    console.log(
+      `[${TOOL_NAME}] Detected ${discoveredRepos.length} git repos under ${topRepoRoot}. Installing into each (use --no-recursive to limit to the top-level).`,
+    );
+    for (const repoPath of discoveredRepos) {
+      const marker = repoPath === topRepoRoot ? ' (top-level)' : '';
+      console.log(`[${TOOL_NAME}]   - ${repoPath}${marker}`);
+    }
   }
-  printOperations('Setup/install', installPayload, options.dryRun);
 
-  const fixPayload = runFixInternal({
-    target: options.target,
-    dryRun: options.dryRun,
-    dropStaleLocks: true,
-    skipAgents: options.skipAgents,
-    skipPackageJson: options.skipPackageJson,
-    skipGitignore: options.skipGitignore,
-  });
-  printOperations('Setup/fix', fixPayload, options.dryRun);
+  let aggregateErrors = 0;
+  let aggregateWarnings = 0;
+  let lastScanResult = null;
+
+  for (const repoPath of discoveredRepos) {
+    const perRepoOptions = { ...options, target: repoPath };
+    const repoLabel = discoveredRepos.length > 1 ? ` [${path.relative(topRepoRoot, repoPath) || '.'}]` : '';
+
+    if (discoveredRepos.length > 1) {
+      console.log(`[${TOOL_NAME}] ── Setup target: ${repoPath} ──`);
+    }
+
+    assertProtectedMainWriteAllowed(perRepoOptions, 'setup');
+    const installPayload = runInstallInternal(perRepoOptions);
+    installPayload.operations.push(ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(perRepoOptions.dryRun)));
+    if (perRepoOptions.parentWorkspaceView) {
+      installPayload.operations.push(ensureParentWorkspaceView(installPayload.repoRoot, Boolean(perRepoOptions.dryRun)));
+    }
+    printOperations(`Setup/install${repoLabel}`, installPayload, perRepoOptions.dryRun);
+
+    const fixPayload = runFixInternal({
+      target: repoPath,
+      dryRun: perRepoOptions.dryRun,
+      force: perRepoOptions.force,
+      dropStaleLocks: true,
+      skipAgents: perRepoOptions.skipAgents,
+      skipPackageJson: perRepoOptions.skipPackageJson,
+      skipGitignore: perRepoOptions.skipGitignore,
+    });
+    printOperations(`Setup/fix${repoLabel}`, fixPayload, perRepoOptions.dryRun);
+
+    if (perRepoOptions.dryRun) {
+      continue;
+    }
+
+    if (perRepoOptions.parentWorkspaceView) {
+      const parentWorkspace = buildParentWorkspaceView(installPayload.repoRoot);
+      console.log(`[${TOOL_NAME}] Parent workspace view: ${parentWorkspace.workspacePath}`);
+    }
+
+    const scanResult = runScanInternal({ target: repoPath, json: false });
+    const currentBaseBranch = currentBranchName(scanResult.repoRoot);
+    const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
+      baseBranch: currentBaseBranch,
+      dryRun: perRepoOptions.dryRun,
+    });
+    printScanResult(scanResult, false);
+    if (autoFinishSummary.enabled) {
+      console.log(
+        `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
+      );
+      for (const detail of autoFinishSummary.details) {
+        console.log(`[${TOOL_NAME}]   ${detail}`);
+      }
+    } else if (autoFinishSummary.details.length > 0) {
+      console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
+    }
+
+    aggregateErrors += scanResult.errors;
+    aggregateWarnings += scanResult.warnings;
+    lastScanResult = scanResult;
+  }
 
   if (options.dryRun) {
     console.log(`[${TOOL_NAME}] Dry run setup done.`);
@@ -4477,32 +4564,11 @@ function setup(rawArgs) {
     return;
   }
 
-  if (options.parentWorkspaceView) {
-    const parentWorkspace = buildParentWorkspaceView(installPayload.repoRoot);
-    console.log(`[${TOOL_NAME}] Parent workspace view: ${parentWorkspace.workspacePath}`);
-  }
-
-  const scanResult = runScanInternal({ target: options.target, json: false });
-  const currentBaseBranch = currentBranchName(scanResult.repoRoot);
-  const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
-    baseBranch: currentBaseBranch,
-    dryRun: options.dryRun,
-  });
-  printScanResult(scanResult, false);
-  if (autoFinishSummary.enabled) {
-    console.log(
-      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
-    );
-    for (const detail of autoFinishSummary.details) {
-      console.log(`[${TOOL_NAME}]   ${detail}`);
-    }
-  } else if (autoFinishSummary.details.length > 0) {
-    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
-  }
-
-  if (scanResult.errors === 0 && scanResult.warnings === 0) {
-    console.log(`[${TOOL_NAME}] ✅ Setup complete.`);
-    console.log(`[${TOOL_NAME}] Copy AI setup prompt with: ${SHORT_TOOL_NAME} copy-prompt`);
+  if (aggregateErrors === 0 && aggregateWarnings === 0) {
+    const repoCount = discoveredRepos.length;
+    const suffix = repoCount > 1 ? ` (${repoCount} repos)` : '';
+    console.log(`[${TOOL_NAME}] ✅ Setup complete.${suffix}`);
+    console.log(`[${TOOL_NAME}] Copy AI setup prompt with: ${SHORT_TOOL_NAME} prompt`);
     console.log(
       `[${TOOL_NAME}] OpenSpec core workflow: /opsx:propose -> /opsx:apply -> /opsx:archive`,
     );
@@ -4512,7 +4578,13 @@ function setup(rawArgs) {
     console.log(`[${TOOL_NAME}] OpenSpec guide: docs/openspec-getting-started.md`);
   }
 
-  setExitCodeFromScan(scanResult);
+  if (lastScanResult) {
+    setExitCodeFromScan({
+      ...lastScanResult,
+      errors: aggregateErrors,
+      warnings: aggregateWarnings,
+    });
+  }
 }
 
 function ensureMainBranch(repoRoot) {
@@ -4811,6 +4883,31 @@ function copyCommands() {
   process.exitCode = 0;
 }
 
+function prompt(rawArgs) {
+  const args = Array.isArray(rawArgs) ? rawArgs : [];
+  let variant = 'prompt';
+  for (const arg of args) {
+    if (arg === '--exec' || arg === '--commands') variant = 'exec';
+    else if (arg === '--snippet' || arg === '--agents') variant = 'snippet';
+    else if (arg === '--prompt' || arg === '--full') variant = 'prompt';
+    else if (arg === '-h' || arg === '--help') variant = 'help';
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (variant === 'help') {
+    console.log(
+      `${SHORT_TOOL_NAME} prompt commands:\n` +
+      `  ${SHORT_TOOL_NAME} prompt           Print AI setup checklist\n` +
+      `  ${SHORT_TOOL_NAME} prompt --exec    Print setup commands only (shell-ready)\n` +
+      `  ${SHORT_TOOL_NAME} prompt --snippet Print the AGENTS.md managed-block template`,
+    );
+    process.exitCode = 0;
+    return;
+  }
+  if (variant === 'exec') return copyCommands();
+  if (variant === 'snippet') return printAgentsSnippet();
+  return copyPrompt();
+}
+
 function cleanup(rawArgs) {
   const options = parseCleanupArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -5289,6 +5386,29 @@ function normalizeCommandOrThrow(command) {
   return command;
 }
 
+function warnDeprecatedAlias(aliasName) {
+  const entry = DEPRECATED_COMMAND_ALIASES.get(aliasName);
+  if (!entry) return;
+  console.error(
+    `[${TOOL_NAME}] '${aliasName}' is deprecated and will be removed in a future major release. ` +
+    `Use: ${entry.hint}`,
+  );
+}
+
+function extractFlag(args, ...names) {
+  const flagSet = new Set(names);
+  let found = false;
+  const remaining = [];
+  for (const arg of args) {
+    if (flagSet.has(arg)) {
+      found = true;
+    } else {
+      remaining.push(arg);
+    }
+  }
+  return { found, remaining };
+}
+
 function main() {
   const args = process.argv.slice(2);
 
@@ -5312,90 +5432,42 @@ function main() {
     return;
   }
 
-  if (command === 'status') {
-    status(rest);
-    return;
-  }
-
-  if (command === 'setup' || command === 'init') {
-    setup(rest);
-    return;
+  // Deprecated direct aliases — route to new surface and warn once.
+  if (DEPRECATED_COMMAND_ALIASES.has(command)) {
+    warnDeprecatedAlias(command);
+    if (command === 'init') return setup(rest);
+    if (command === 'install') return install(rest);
+    if (command === 'fix') return fix(rest);
+    if (command === 'scan') return scan(rest);
+    if (command === 'copy-prompt') return copyPrompt();
+    if (command === 'copy-commands') return copyCommands();
+    if (command === 'print-agents-snippet') return printAgentsSnippet();
+    if (command === 'review') return review(rest);
   }
 
-  if (command === 'doctor') {
-    doctor(rest);
-    return;
-  }
-
-  if (command === 'review') {
-    review(rest);
-    return;
-  }
-
-  if (command === 'agents') {
-    agents(rest);
-    return;
-  }
-
-  if (command === 'finish') {
-    finish(rest);
-    return;
-  }
-
-  if (command === 'report') {
-    report(rest);
-    return;
-  }
-
-  if (command === 'copy-prompt') {
-    copyPrompt();
-    return;
-  }
-
-  if (command === 'copy-commands') {
-    copyCommands();
-    return;
-  }
-
-  if (command === 'protect') {
-    protect(rest);
-    return;
-  }
-
-  if (command === 'sync') {
-    sync(rest);
-    return;
-  }
-
-  if (command === 'cleanup') {
-    cleanup(rest);
-    return;
-  }
-
-  if (command === 'release') {
-    release(rest);
-    return;
-  }
-
-  if (command === 'install') {
-    install(rest);
-    return;
-  }
-
-  if (command === 'fix') {
-    fix(rest);
-    return;
-  }
-
-  if (command === 'scan') {
-    scan(rest);
-    return;
-  }
-
-  if (command === 'print-agents-snippet') {
-    printAgentsSnippet();
-    return;
-  }
+  if (command === 'status') {
+    const { found: strict, remaining } = extractFlag(rest, '--strict');
+    if (strict) return scan(remaining);
+    return status(remaining);
+  }
+
+  if (command === 'setup') {
+    const installOnly = extractFlag(rest, '--install-only', '--only-install');
+    if (installOnly.found) return install(installOnly.remaining);
+    const repairOnly = extractFlag(installOnly.remaining, '--repair', '--fix-only');
+    if (repairOnly.found) return fix(repairOnly.remaining);
+    return setup(repairOnly.remaining);
+  }
+
+  if (command === 'prompt') return prompt(rest);
+  if (command === 'doctor') return doctor(rest);
+  if (command === 'agents') return agents(rest);
+  if (command === 'finish') return finish(rest);
+  if (command === 'report') return report(rest);
+  if (command === 'protect') return protect(rest);
+  if (command === 'sync') return sync(rest);
+  if (command === 'cleanup') return cleanup(rest);
+  if (command === 'release') return release(rest);
 
   const suggestion = maybeSuggestCommand(command);
   if (suggestion) {