forge-workflow 0.0.10 → 0.1.0-beta.2

package/bin/forge.js

@@ -13,7 +13,7 @@
  *   bunx forge setup --agents claude,cursor
  *
  * CLI Flags:
- *   --path, -p <dir>     Target project directory (creates if needed)
+ *   --path, -p <dir>     Target project directory (docs verify|detect require existing dir)
  *   --quick, -q          Use all defaults, minimal prompts
  *   --skip-external      Skip external services configuration
  *   --agents <list>      Specify agents (--agents claude cursor OR --agents=claude,cursor)
@@ -38,33 +38,41 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
-const { execSync, execFileSync, spawnSync } = require('node:child_process');
+const { execSync } = require('node:child_process');
 
-// Get version from package.json (single source of truth)
+// Get version from package.json (single source of truth). packageDir stays a
+// runtime value for asset copying, but the require is a static relative path so
+// `bun build --compile` can bundle package.json.
 const packageDir = path.dirname(__dirname);
-const packageJson = require(path.join(packageDir, 'package.json'));
+const packageJson = require('../package.json');
 const VERSION = packageJson.version;
 
 // Load PluginManager for discoverable agent architecture
 const PluginManager = require('../lib/plugin-manager');
-const { scaffoldGithubBeadsSync } = require('../lib/setup');
+const { populateAgentSkills, listCanonicalSkills } = require('../lib/skills-sync');
 const { copyEssentialDocs } = require('../lib/docs-copy');
-const { listTopics, getTopicContent } = require('../lib/docs-command');
+const {
+  listTopics,
+  getTopicContent,
+  validateDocs,
+  formatDocsValidation,
+  writeDocsBaseline,
+} = require('../lib/docs-command');
 const { resetSoft, resetHard, reinstall } = require('../lib/reset');
 const { loadCommands, executeCommand } = require('../lib/commands/_registry');
+const { resolveCommandOpts } = require('../lib/commands/_resolve-command-opts');
+const { getPackageRoot } = require('../lib/package-root');
 const { enforceStageEntry } = require('../lib/workflow/enforce-stage');
 const { normalizeStageId } = require('../lib/workflow/stages');
 
-// Load enhanced onboarding modules
-const contextMerge = require(path.join(packageDir, 'lib', 'context-merge'));
-const projectDiscovery = require(path.join(packageDir, 'lib', 'project-discovery'));
+// Load enhanced onboarding modules (static relative requires — bundleable)
+const contextMerge = require('../lib/context-merge');
+const projectDiscovery = require('../lib/project-discovery');
 
 // Load lib modules for symlink, beads, and PAT setup
-const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require(path.join(packageDir, 'lib', 'symlink-utils'));
-const beadsSetupLib = require(path.join(packageDir, 'lib', 'beads-setup'));
-const { beadsHealthCheck } = require(path.join(packageDir, 'lib', 'beads-health-check'));
-const { setupPAT } = require(path.join(packageDir, 'lib', 'pat-setup'));
-const { DEFAULT_BEADS_VERSION, detectDefaultBranch, templateWorkflows, scaffoldBeadsSync } = require(path.join(packageDir, 'lib', 'beads-sync-scaffold'));
+const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require('../lib/symlink-utils');
+const beadsSetupLib = require('../lib/beads-setup');
+const { scaffoldBeadsSync } = require('../lib/beads-sync-scaffold');
 
 // Load incremental setup modules
 const { detectEnvironment } = require('../lib/detect-agent');
@@ -74,6 +82,12 @@ const { ActionCollector, isNonInteractive } = require('../lib/setup-utils');
 const { renderSetupSummary } = require('../lib/setup-summary-renderer');
 const { smartMergeAgentsMd } = require('../lib/smart-merge');
 const { checkLefthookStatus } = require('../lib/lefthook-check');
+const {
+  FORGE_USER_LEFTHOOK_YML,
+  forgeShouldWriteLefthookConfig,
+  installNativeGitHooks,
+  verifyHooksActive,
+} = require('../lib/lefthook-wiring');
 const { detectHusky, migrateHusky } = require('../lib/husky-migration');
 // workflowProfiles: module exists and is tested but not yet wired into setup flow
 // Will be activated when workflow profile selection is added to interactive setup
@@ -94,37 +108,10 @@ let actionLog = new SetupActionLog();
 // Detected package manager
 let PKG_MANAGER = 'npm';
 
-/**
- * Securely execute a command with PATH validation
- * Mitigates SonarCloud S4036: Ensures executables are from trusted locations
- * @param {string} command - The command to execute
- * @param {string[]} args - Command arguments
- * @param {object} options - execFileSync options
- */
-function secureExecFileSync(command, args = [], options = {}) {
-  try {
-    // Resolve command's full path to validate it's in a trusted location
-    const isWindows = process.platform === 'win32';
-    const pathResolver = isWindows ? 'where.exe' : 'which';
-
-    const result = spawnSync(pathResolver, [command], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore']
-    });
-
-    if (result.status === 0 && result.stdout) {
-      // Command found - use resolved path for execution
-      // Handle both CRLF (Windows) and LF (Unix) line endings
-      const resolvedPath = result.stdout.trim().split(/\r?\n/)[0].trim();
-      return execFileSync(resolvedPath, args, options);
-    }
-  } catch (_err) { // NOSONAR - S2486: Intentionally ignored; falls back to direct command execution below
-  }
-
-  // Fallback: execute with command name (maintains compatibility)
-  // This is safe for our use case as we only execute known, hardcoded commands
-  return execFileSync(command, args, options);
-}
+// Securely execute a command with PATH validation (SonarCloud S4036).
+// Delegates to the shared helper, which also handles Windows npm/npx/lefthook
+// cmd shims that cannot be spawned directly (kernel issue 9997d516).
+const { secureExecFileSync } = require('../lib/shell-utils');
 
 /**
  * Load agent definitions from plugin architecture
@@ -146,7 +133,8 @@ function loadAgentsFromPlugins() {
       customSetup: plugin.setup?.customSetup || '',
       needsConversion: plugin.setup?.needsConversion || false,
       copyCommands: plugin.setup?.copyCommands || false,
-      promptFormat: plugin.setup?.promptFormat || false
+      promptFormat: plugin.setup?.promptFormat || false,
+      skillsDir: plugin.directories?.skills || null
     };
   });
 
@@ -295,25 +283,6 @@ function _checkWritePermission(filePath) {
   }
 }
 
-/**
- * Reads workflow command names from .claude/commands/*.md in the package directory.
- * @returns {string[]} Command names (filenames without .md extension)
- */
-function getWorkflowCommands() {
-  const commandsDir = path.join(packageDir, '.claude', 'commands');
-  try {
-    return fs.readdirSync(commandsDir)
-      .filter(f => f.endsWith('.md'))
-      .map(f => f.replace(/\.md$/, ''));
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      console.warn(`Warning: .claude/commands directory not found at ${commandsDir}`);
-    } else {
-      console.warn(`Warning: failed to read .claude/commands — ${err.code}: ${err.message}`);
-    }
-    return [];
-  }
-}
 
 
 // Helper function to safely execute commands (no user input)
@@ -432,72 +401,26 @@ function checkPrerequisites() {
   return { errors, warnings };
 }
 
-// Universal SKILL.md content
-const SKILL_CONTENT = `---
-name: forge-workflow
-description: 7-stage TDD-first workflow for feature development. Use when building features, fixing bugs, or shipping PRs.
-category: Development Workflow
-tags: [tdd, workflow, pr, git, testing]
-tools: [Bash, Read, Write, Edit, Grep, Glob]
----
-
-# Forge Workflow Skill
-
-A TDD-first workflow for AI coding agents. Ship features with confidence.
-
-## When to Use
-
-Automatically invoke this skill when the user wants to:
-- Build a new feature
-- Fix a bug
-- Create a pull request
-- Run the development workflow
-
-## 7 Stages
-
-| Stage | Command | Description |
-|-------|---------|-------------|
-| utility | \`/status\` | Check current context, active work, recent completions |
-| 1 | \`/plan\` | Design intent -> research -> branch + worktree + task list |
-| 2 | \`/dev\` | TDD development (implementer -> spec review -> quality review) |
-| 3 | \`/validate\` | Type check, lint, security, tests - all fresh output |
-| 4 | \`/ship\` | Push branch and create PR with full documentation |
-| 5 | \`/review\` | Address ALL PR feedback (GitHub Actions, Greptile, SonarCloud) |
-| 6 | \`/premerge\` | Update docs, hand off PR to user |
-| 7 | \`/verify\` | Post-merge health check (CI on main, close Beads) |
-
-## Workflow Flow
-
-\`\`\`
-/status -> /plan -> /dev -> /validate -> /ship -> /review -> /premerge -> /verify
-\`\`\`
-
-## Core Principles
-
-- **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
-- **Research-First**: Understand before building, document decisions
-- **Security Built-In**: OWASP Top 10 analysis for every feature
-- **Documentation Progressive**: Update at each stage, verify at end
-`;
 
 // Cursor MDC rule content
 const CURSOR_RULE = `---
-description: Forge 7-Stage TDD Workflow
+description: Forge TDD Workflow Template
 alwaysApply: true
 ---
 
 # Forge Workflow Commands
 
-Use these commands via \`/command-name\`:
+Use these default-template commands via \`/command-name\`:
 
 - \`/status\` (utility) - Check current context, active work, recent completions
-1. \`/plan\` - Design intent Q&A, research, branch + task list
-2. \`/dev\` - Subagent-driven TDD per task (spec + quality review)
-3. \`/validate\` - Type check, lint, security, tests (HARD-GATE)
-4. \`/ship\` - Push and create PR with design doc reference
-5. \`/review\` - Handle ALL PR issues (Actions, Greptile, SonarCloud)
-6. \`/premerge\` - Complete docs on feature branch, hand off PR to user
-7. \`/verify\` - Post-merge health check (CI on main, close Beads)
+- \`/plan\` - Design intent Q&A, research, branch + task list
+- \`/dev\` - Subagent-driven TDD per task (spec + quality review)
+- \`/validate\` - Type check, lint, security, tests (HARD-GATE)
+- \`/ship\` - Push and create PR with design doc reference
+- \`/review\` - Handle ALL PR issues (Actions, Greptile, SonarCloud)
+- \`/verify\` - Post-merge health check (CI on main, close Beads)
+
+Pre-merge gate (not a numbered stage): finish docs + confirm CI green + hand off the PR — embedded in the /ship and /review stages.
 
 See AGENTS.md for full workflow details.
 `;
@@ -543,17 +466,6 @@ function writeFile(filePath, content) {
   }
 }
 
-function readFile(filePath) {
-  try {
-    return fs.readFileSync(filePath, 'utf8');
-  } catch (err) {
-    if (process.env.DEBUG) {
-      console.warn(`  ⚠ Could not read ${filePath}: ${err.message}`);
-    }
-    return null;
-  }
-}
-
 function copyFile(src, dest) {
   try {
     const destPath = path.resolve(projectRoot, dest);
@@ -612,11 +524,6 @@ function createSymlinkOrCopy(source, target, options = {}) {
   return libCreateSymlinkOrCopy(fullSource, fullTarget, options);
 }
 
-function stripFrontmatter(content) {
-  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
-  return match ? match[1] : content;
-}
-
 // Read existing .env.local
 function readEnvFile() {
   const envPath = path.join(projectRoot, '.env.local');
@@ -781,7 +688,6 @@ async function detectProjectStatus() {
     type: 'fresh', // 'fresh', 'upgrade', or 'partial'
     hasAgentsMd: fs.existsSync(path.join(projectRoot, 'AGENTS.md')),
     hasClaudeMd: fs.existsSync(path.join(projectRoot, 'CLAUDE.md')),
-    hasClaudeCommands: fs.existsSync(path.join(projectRoot, '.claude/commands')),
     hasEnvLocal: fs.existsSync(path.join(projectRoot, '.env.local')),
     existingEnvVars: {},
     agentsMdSize: 0,
@@ -815,9 +721,9 @@ async function detectProjectStatus() {
   }
 
   // Determine installation type
-  if (status.hasAgentsMd && status.hasClaudeCommands) {
+  if (status.hasAgentsMd) {
     status.type = 'upgrade'; // Full forge installation exists
-  } else if (status.hasClaudeCommands || status.hasEnvLocal) {
+  } else if (status.hasEnvLocal) {
     status.type = 'partial'; // Agent-specific files exist (not just base files from postinstall)
   }
   // else: 'fresh' - new installation (or just postinstall baseline with AGENTS.md)
@@ -1665,7 +1571,6 @@ function displayMcpStatus(selectedAgents) {
   // Show manual setup instructions for GUI-based agents
   const manualMcpMap = {
     cursor: 'Cursor: Configure via Cursor Settings > MCP',
-    cline: 'Cline: Install via MCP Marketplace',
   };
   const needsManualMcp = Object.entries(manualMcpMap)
     .filter(([key]) => selectedAgents.includes(key))
@@ -1748,39 +1653,6 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
   const { added, preserved } = writeEnvTokens(tokens, true);
   displayEnvTokenResults(added, preserved);
 
-  // GitHub-Beads issue sync setup
-  console.log('');
-  const enableSync = await askYesNo(question, 'Enable GitHub ↔ Beads issue sync?', true);
-  if (enableSync) {
-    try {
-      const result = await scaffoldGithubBeadsSync(projectRoot, packageDir);
-      for (const f of result.created) {
-        console.log(`  Created: ${f}`);
-      }
-      for (const f of result.skipped) {
-        console.log(`  Skipped: ${f} (already exists)`);
-      }
-
-      // PAT setup guidance for Beads sync (non-fatal)
-      // Skip if --sync flag is set — handleSyncScaffold will handle PAT setup
-      if (!SYNC_ENABLED) {
-        try {
-          const patResult = setupPAT(projectRoot, { interactive: !NON_INTERACTIVE });
-          if (patResult.success) {
-            console.log('  ✓ Beads sync PAT configured');
-          } else if (patResult.reminder) {
-            console.log(`  ℹ ${patResult.reminder}`);
-          } else if (patResult.instructions) {
-            console.log(`  ℹ ${patResult.instructions.split('\n')[0]}`);
-          }
-        } catch (_patErr) {
-          // PAT setup is best-effort — don't block sync scaffold
-        }
-      }
-    } catch (err) {
-      console.error(`  Error scaffolding GitHub-Beads sync: ${err.message}`);
-    }
-  }
 }
 
 // Display the Forge banner
@@ -1891,26 +1763,20 @@ function minimalInstall() {
   console.log('');
 }
 
-// Helper: Setup Claude agent
-function setupClaudeAgent(skipFiles = {}) {
-  // Copy commands from package (unless skipped)
-  if (skipFiles.claudeCommands) {
-    console.log('  Skipped: .claude/commands/ (keeping existing)');
-  } else {
-    const cmds = getWorkflowCommands();
-    let copied = 0;
-    cmds.forEach(cmd => {
-      const src = path.join(packageDir, `.claude/commands/${cmd}.md`);
-      if (copyFile(src, `.claude/commands/${cmd}.md`)) copied++;
-    });
-    console.log(`  Copied: ${copied} workflow commands`);
-  }
+// ⚠️ LEGACY / DEAD SETUP PATH ⚠️
+// The functions below (setupClaudeAgent, setupCursorAgent, copyAgentRules,
+// setupClaudeMcpConfig, setupAgent, quickSetup, dryRunSetup, …) are the OLD
+// inline setup implementation. `forge setup` is now the registry command in
+// lib/commands/setup.js, which takes priority in the dispatcher and `return`s
+// before the inline `if (command === 'setup')` block is ever reached. This copy
+// is kept only until the inline setup subsystem is fully removed — the authority
+// is lib/commands/setup.js. Do not add behavior here; edit lib/commands/setup.js.
 
-  // Copy rules
-  const rulesSrc = path.join(packageDir, '.claude/rules/workflow.md');
-  copyFile(rulesSrc, '.claude/rules/workflow.md');
-
-  // Copy scripts
+// Helper: Setup Claude agent
+function setupClaudeAgent() {
+  // Skills-only surface: per-skill SKILL.md dirs are populated by createAgentSkill.
+  // Claude receives policy via CLAUDE.md → AGENTS.md, NOT an always-on
+  // `.claude/rules/workflow.md` (that canonical file was removed). Only scripts copy.
   const scriptSrc = path.join(packageDir, '.claude/scripts/load-env.sh');
   copyFile(scriptSrc, '.claude/scripts/load-env.sh');
 }
@@ -1921,61 +1787,23 @@ function setupCursorAgent() {
   console.log('  Created: .cursor/rules/forge-workflow.mdc');
 }
 
-// Helper: Convert command to agent-specific format
-function convertCommandToAgentFormat(cmd, content, agent) {
-  let targetContent = content;
-  let targetFile = cmd;
-
-  if (agent.needsConversion) {
-    targetContent = stripFrontmatter(content);
+// Helper: Create skill file for agent
+function createAgentSkill(agent, agentKey) {
+  if (agentKey === 'codex') {
+    // Codex global skill install is handled via buildCodexSkillInstallPlan in setup.js
+    return;
   }
 
-  if (agent.promptFormat) {
-    targetFile = cmd.replace('.md', '.prompt.md');
-    targetContent = stripFrontmatter(content);
-  }
+  if (!agent.hasSkill || !agent.skillsDir) return;
 
-  return { targetFile, targetContent };
-}
-
-// Helper: Copy commands for agent
-function copyAgentCommands(agent, claudeCommands) {
-  if (!claudeCommands) return;
-  if (!agent.needsConversion && !agent.copyCommands && !agent.promptFormat) return;
-
-  Object.entries(claudeCommands).forEach(([cmd, content]) => {
-    const { targetFile, targetContent } = convertCommandToAgentFormat(cmd, content, agent);
-    const targetDir = agent.dirs[0]; // First dir is commands/workflows
-    writeFile(`${targetDir}/${targetFile}`, targetContent);
+  // Skills-only surface: populate every canonical skill into the agent skills dir
+  // (.claude/skills, .cursor/skills) from the packaged canonical `skills/` source.
+  const { written } = populateAgentSkills({
+    sourceRoot: packageDir,
+    targetSkillsDir: path.join(projectRoot, agent.skillsDir),
+    clean: true,
   });
-  console.log(`  Converted: ${Object.keys(claudeCommands).length} workflow commands`);
-}
-
-// Helper: Copy rules for agent
-function copyAgentRules(agent) {
-  if (!agent.needsConversion) return;
-
-  const workflowMdPath = path.join(projectRoot, '.claude/rules/workflow.md');
-  if (!fs.existsSync(workflowMdPath)) return;
-
-  const rulesDir = agent.dirs.find(d => d.includes('/rules'));
-  if (!rulesDir) return;
-
-  const ruleContent = readFile(workflowMdPath);
-  if (ruleContent) {
-    writeFile(`${rulesDir}/workflow.md`, ruleContent);
-  }
-}
-
-// Helper: Create skill file for agent
-function createAgentSkill(agent) {
-  if (!agent.hasSkill) return;
-
-  const skillDir = agent.dirs.find(d => d.includes('/skills/'));
-  if (skillDir) {
-    writeFile(`${skillDir}/SKILL.md`, SKILL_CONTENT);
-    console.log('  Created: forge-workflow skill');
-  }
+  console.log(`  Created: ${written.length} skills in ${agent.skillsDir}/`);
 }
 
 // Helper: Setup MCP config for Claude
@@ -2010,7 +1838,7 @@ function createAgentLinkFile(agent, symlinkOnly = false) {
 }
 
 // Setup specific agent
-function setupAgent(agentKey, claudeCommands, skipFiles = {}) {
+function setupAgent(agentKey, skipFiles = {}) {
   const agent = AGENTS[agentKey];
   if (!agent) return;
 
@@ -2028,14 +1856,8 @@ function setupAgent(agentKey, claudeCommands, skipFiles = {}) {
     setupCursorAgent();
   }
 
-  // Convert/copy commands
-  copyAgentCommands(agent, claudeCommands);
-
-  // Copy rules if needed
-  copyAgentRules(agent);
-
   // Create SKILL.md
-  createAgentSkill(agent);
+  createAgentSkill(agent, agentKey);
 
   // Setup MCP configs
   if (agentKey === 'claude') {
@@ -2069,7 +1891,6 @@ function displayInstallationStatus(projectStatus) {
   }
 
   if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
-  if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
   if (projectStatus.hasEnvLocal) console.log('  - .env.local');
   console.log('');
 }
@@ -2133,7 +1954,6 @@ async function promptForFileOverwrite(question, fileType, exists, skipFiles) {
 
   const fileLabels = {
     agentsMd: { prompt: 'Found existing AGENTS.md. Overwrite?', message: 'AGENTS.md', key: 'agentsMd' },
-    claudeCommands: { prompt: 'Found existing .claude/commands/. Overwrite?', message: '.claude/commands/', key: 'claudeCommands' }
   };
 
   const config = fileLabels[fileType];
@@ -2308,35 +2128,12 @@ async function installAgentsMd(skipFiles) {
   }
 }
 
-/**
- * Load Claude commands for conversion
- */
-function loadClaudeCommands(selectedAgents) {
-  const claudeCommands = {};
-  const needsClaudeCommands = selectedAgents.includes('claude') ||
-    selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands);
-
-  if (!needsClaudeCommands) {
-    return claudeCommands;
-  }
-
-  getWorkflowCommands().forEach(cmd => {
-    const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
-    const content = readFile(cmdPath);
-    if (content) {
-      claudeCommands[`${cmd}.md`] = content;
-    }
-  });
-
-  return claudeCommands;
-}
-
 /**
  * Setup agents with progress indication
  * Delegates to setupSelectedAgents to avoid duplicate implementations (S4144)
  */
-function setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles) {
-  setupSelectedAgents(selectedAgents, claudeCommands, skipFiles);
+function setupAgentsWithProgress(selectedAgents, skipFiles) {
+  setupSelectedAgents(selectedAgents, skipFiles);
 }
 
 /**
@@ -2351,15 +2148,11 @@ function displaySetupSummary(selectedAgents) {
   console.log('What\'s installed:');
   console.log('  - AGENTS.md (universal instructions)');
 
-  const workflowCount = getWorkflowCommands().length;
   selectedAgents.forEach(key => {
     const agent = AGENTS[key];
     if (agent.linkFile) {
       console.log(`  - ${agent.linkFile} (${agent.name})`);
     }
-    if (agent.hasCommands) {
-      console.log(`  - .claude/commands/ (${workflowCount} workflow commands)`);
-    }
     if (agent.hasSkill) {
       const skillDir = agent.dirs.find(d => d.includes('/skills/'));
       if (skillDir) {
@@ -2464,12 +2257,10 @@ async function _interactiveSetup() {
   // Track which files to skip based on user choices
   const skipFiles = {
     agentsMd: false,
-    claudeCommands: false
   };
 
   // Ask about overwriting existing files
   await promptForFileOverwrite(question, 'agentsMd', projectStatus.hasAgentsMd, skipFiles);
-  await promptForFileOverwrite(question, 'claudeCommands', projectStatus.hasClaudeCommands, skipFiles);
 
   if (projectStatus.type !== 'fresh') {
     console.log('');
@@ -2492,19 +2283,13 @@ async function _interactiveSetup() {
   setupCoreDocs();
   console.log('');
 
-  // Load Claude commands if needed
-  let claudeCommands = {};
-  if (selectedAgents.includes('claude') || selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands)) {
-    // First ensure Claude is set up
-    if (selectedAgents.includes('claude')) {
-      setupAgent('claude', null, skipFiles);
-    }
-    // Then load the commands
-    claudeCommands = loadClaudeCommands(selectedAgents);
+  // Setup Claude first if selected, then remaining agents
+  if (selectedAgents.includes('claude')) {
+    setupAgent('claude', skipFiles);
   }
 
   // Setup each selected agent with progress indication
-  setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles);
+  setupAgentsWithProgress(selectedAgents, skipFiles);
 
   // =============================================
   // STEP 2: Project Tools Setup
@@ -2530,6 +2315,16 @@ async function _interactiveSetup() {
 }
 
 // Parse CLI flags
+// Issue command aliases hidden from `forge --help`: the bare passthroughs that
+// duplicate `forge issue <sub>` plus the plural `issues`. They stay registered and
+// routable (back-compat), but are omitted from help so `forge issue` reads as the
+// single canonical issue surface (kernel issue 450c6e34). The canonical `issue` is
+// deliberately NOT listed here — it stays documented.
+const ISSUE_ALIAS_COMMANDS = [
+  'create', 'update', 'claim', 'close', 'show', 'list',
+  'ready', 'blocked', 'stale', 'orphans', 'lint', 'claims', 'issues',
+];
+
 function parseFlags() {
   const flags = {
     quick: false,
@@ -2554,7 +2349,8 @@ function parseFlags() {
 
   // Issue passthrough commands delegate all flags to bd.
   // Skip global parsing so flags like --type, -p, --help reach the handler intact.
-  const issuePassthroughCommands = ['create', 'update', 'claim', 'close', 'show', 'list', 'ready', 'issue', 'issues'];
+  // Canonical `issue` plus the hidden back-compat aliases (single source of truth).
+  const issuePassthroughCommands = [...ISSUE_ALIAS_COMMANDS, 'issue'];
   if (issuePassthroughCommands.includes(args[0])) {
     return flags;
   }
@@ -2757,6 +2553,7 @@ function showHelp() {
   console.log('Options:');
   console.log('  --path, -p <dir>     Target project directory (default: current directory)');
   console.log('                       Creates the directory if it doesn\'t exist');
+  console.log('                       Exception: docs verify|detect --path requires an existing directory');
   console.log('  --quick, -q          Use all defaults, minimal prompts');
   console.log('                       Auto-selects: all agents, GitHub Code Quality, ESLint');
   console.log('  --skip-external      Skip external services configuration');
@@ -2802,9 +2599,29 @@ function showHelp() {
   console.log('Also works with bun:');
   console.log('  bunx forge setup --quick');
   console.log('');
-
-  // Append auto-discovered registry commands
+  // Adoption profile + gate/classification config is owned by `forge init`, not
+  // `forge setup`. The --minimal/--standard/--full profile flags are `forge init`
+  // shortcuts (setup only reads them for `--dry-run` preview), so point there.
+  console.log('Adoption profile, gates & classification (configured by `forge init`, not setup):');
+  console.log('  forge init --minimal | --standard | --full   # adoption-profile shortcut');
+  console.log('                                               # (or: --profile minimal|standard|full)');
+  console.log('  forge init --classification critical|standard|refactor');
+  console.log('  `forge init` writes `.forge/config.yaml` (gate + classification config).');
+  console.log('  Run `forge init --help` for all profile/classification/harness flags.');
+  console.log('');
+
+  // Append auto-discovered registry commands. Hidden issue aliases (the bare
+  // passthroughs + plural `issues`, plus any command self-declaring `hidden: true`)
+  // still route and execute, but are trimmed from this enumeration so `forge issue`
+  // reads as the single canonical issue surface. This registry instance is loaded
+  // solely to render help, so deleting from its Map only affects the printed list —
+  // command dispatch (main) uses a separate registry and is unaffected.
   const helpRegistry = loadCommands(path.join(__dirname, '..', 'lib', 'commands'));
+  for (const [name, cmd] of [...helpRegistry.commands]) {
+    if (ISSUE_ALIAS_COMMANDS.includes(name) || cmd.hidden === true) {
+      helpRegistry.commands.delete(name);
+    }
+  }
   const registryHelp = helpRegistry.getHelp();
   if (registryHelp) {
     console.log('Additional commands:');
@@ -2813,6 +2630,26 @@ function showHelp() {
   }
 }
 
+// Per-command help. When `--help` follows a known subcommand (e.g. `forge status
+// --help`), render THAT command's usage/description/flags instead of the global
+// setup banner — a newcomer asking for a command's help should not get the
+// installer's help.
+function printCommandHelp(cmd) {
+  console.log(`forge ${cmd.name} — ${cmd.description}`);
+  if (cmd.usage) {
+    console.log('');
+    console.log(/^(Usage:|forge )/.test(cmd.usage) ? cmd.usage : `Usage: ${cmd.usage}`);
+  }
+  const flagEntries = cmd.flags && typeof cmd.flags === 'object' ? Object.entries(cmd.flags) : [];
+  if (flagEntries.length > 0) {
+    console.log('');
+    console.log('Flags:');
+    for (const [flag, desc] of flagEntries) {
+      console.log(`  ${flag.padEnd(16)} ${desc}`);
+    }
+  }
+}
+
 // Detect Husky and offer migration to Lefthook
 // Called before installGitHooks() in setup flows
 async function handleHuskyMigration() {
@@ -2863,80 +2700,104 @@ async function handleHuskyMigration() {
 function installGitHooks() {
   console.log('Installing git hooks (TDD enforcement)...');
 
-  // Skip lefthook.yml creation if binary is not available
-  const lefthookStatus = checkLefthookStatus(projectRoot);
-  if (!lefthookStatus.binaryAvailable) {
-    if (lefthookStatus.message) {
-      console.warn(`  \u26A0 Skipping lefthook setup: ${lefthookStatus.message}`);
-    } else {
-      console.warn('  \u26A0 Skipping lefthook setup: binary not available');
-    }
-    return;
-  }
+  // Install the Forge hook SCRIPTS first, UNCONDITIONALLY - they back BOTH the lefthook
+  // pre-commit job AND the native .git/hooks fallback below, so they must exist whether
+  // or not the lefthook binary is available.
+  installForgeHookScripts();
 
-  // Check if lefthook.yml exists (it should, as it's in the package)
-  const lefthookConfig = path.join(packageDir, 'lefthook.yml');
-  const targetHooks = path.join(projectRoot, '.forge/hooks');
+  const lefthookStatus = checkLefthookStatus(projectRoot);
+  let lefthookInstalled = false;
 
-  try {
-    // Copy lefthook.yml to project root
-    const lefthookTarget = path.join(projectRoot, 'lefthook.yml');
-    if (!fs.existsSync(lefthookTarget)) {
-      if (copyFile(lefthookConfig, 'lefthook.yml')) {
+  if (lefthookStatus.binaryAvailable) {
+    try {
+      // Write the REAL user-facing lefthook.yml - never the repo's own dev config (which
+      // references repo-internal scripts/ a user project lacks), and never leave
+      // lefthook's stock commented-out example in place. Overwrite only a missing file
+      // or a fully-commented stub, never a config with active jobs (kernel e452422c).
+      const lefthookTarget = path.join(projectRoot, 'lefthook.yml');
+      if (forgeShouldWriteLefthookConfig(lefthookTarget)) {
+        fs.writeFileSync(lefthookTarget, FORGE_USER_LEFTHOOK_YML, 'utf8');
         console.log('  ✓ Created lefthook.yml');
       }
-    }
-
-    // Copy check-tdd.js hook script
-    const hookSource = path.join(packageDir, '.forge/hooks/check-tdd.js');
-    if (fs.existsSync(hookSource)) {
-      // Ensure .forge/hooks directory exists
-      if (!fs.existsSync(targetHooks)) {
-        fs.mkdirSync(targetHooks, { recursive: true });
-      }
 
-      const hookTarget = path.join(targetHooks, 'check-tdd.js');
-      if (copyFile(hookSource, hookTarget)) {
-        console.log('  ✓ Created .forge/hooks/check-tdd.js');
-
-        // Make hook executable (Unix systems)
-        try {
-          fs.chmodSync(hookTarget, 0o755);
-        } catch (err) {
-          // Windows doesn't need chmod
-          console.warn('chmod not available (Windows):', err.message);
-        }
-      }
-    }
-
-    // Try to install lefthook hooks
-    // SECURITY: Using execFileSync with hardcoded commands (no user input)
-    try {
-      // Try npx first (local install), fallback to global
+      // Install lefthook's git hooks. Try local (npx) first, then a global binary.
+      // SECURITY: execFileSync with hardcoded commands (no user input).
       try {
         secureExecFileSync('npx', ['lefthook', 'install'], { stdio: 'inherit', cwd: projectRoot });
         console.log('  ✓ Lefthook hooks installed (local)');
+        lefthookInstalled = true;
       } catch (error_) {
-        // Fallback to global lefthook
         console.warn('npx lefthook failed, trying global:', error_.message);
-        execFileSync('lefthook', ['version'], { stdio: 'ignore' });
-        execFileSync('lefthook', ['install'], { stdio: 'inherit', cwd: projectRoot });
+        secureExecFileSync('lefthook', ['version'], { stdio: 'ignore' });
+        secureExecFileSync('lefthook', ['install'], { stdio: 'inherit', cwd: projectRoot });
         console.log('  ✓ Lefthook hooks installed (global)');
+        lefthookInstalled = true;
       }
     } catch (err) {
       console.warn('Lefthook installation failed:', err.message);
-      console.log('  ℹ Lefthook not found. Install it:');
-      console.log('    bun add -d lefthook  (recommended)');
-      console.log('    OR: bun add -g lefthook  (global)');
-      console.log('    Then run: bunx lefthook install');
     }
+  } else if (lefthookStatus.message) {
+    console.warn(`  ⚠ lefthook binary unavailable: ${lefthookStatus.message}`);
+  }
+
+  // Native fallback: when lefthook is unavailable or its install failed, wire native
+  // .git/hooks so raw `git commit` / `git push` still enforce the TDD gate - the moat is
+  // never silently inert (B3). Runs regardless of whether a package.json exists.
+  if (!lefthookInstalled) {
+    const native = installNativeGitHooks(projectRoot);
+    if (native.installed) {
+      console.log(`  ✓ Native git hooks installed (${native.written.join(', ')}) - lefthook fallback`);
+    } else if (native.skipped && native.skipped.length > 0) {
+      console.warn(`  ⚠ Native hook(s) skipped to preserve existing hooks: ${native.skipped.join(', ')}`);
+    } else {
+      console.warn(`  ⚠ Could not install native git hooks: ${native.reason || 'unknown'}`);
+    }
+  }
 
-    console.log('');
+  // VERIFY LOUDLY: never let setup silently no-op. If pre-commit enforcement is not
+  // actually active after all of the above, say so unmistakably and set a failure code.
+  const verdict = verifyHooksActive(projectRoot);
+  if (verdict.active) {
+    console.log(`  ✓ Git hook enforcement active (${verdict.method}).`);
+  } else {
+    const addCmd = PKG_MANAGER === 'bun'
+      ? 'bun add -d'
+      : PKG_MANAGER === 'npm'
+        ? 'npm install --save-dev'
+        : `${PKG_MANAGER} add -D`;
+    console.error('');
+    console.error('  ============================================================');
+    console.error('  ⚠ TDD ENFORCEMENT IS NOT ACTIVE');
+    console.error(`     ${verdict.reason || 'no pre-commit hook is installed'}.`);
+    console.error('     `forge ship` will block until hooks are active. To fix:');
+    console.error(`       ${addCmd} lefthook  &&  npx lefthook install`);
+    console.error('     (or re-run `forge setup` in the repo root).');
+    console.error('  ============================================================');
+    console.error('');
+    process.exitCode = 1;
+  }
 
-  } catch (error) {
-    console.log('  ⚠ Failed to install hooks:', error.message);
-    console.log('  You can install manually later with: lefthook install');
-    console.log('');
+  console.log('');
+}
+
+// Copy the Forge hook scripts (check-tdd.js + the native-hook adapter) into the
+// project's .forge/hooks/. Runs UNCONDITIONALLY - independent of the lefthook binary -
+// because both the lefthook pre-commit job and the native fallback invoke them.
+function installForgeHookScripts() {
+  const targetHooks = path.join(projectRoot, '.forge/hooks');
+  for (const name of ['check-tdd.js', 'forge-native-hook.js']) {
+    const src = path.join(packageDir, '.forge/hooks', name);
+    if (!fs.existsSync(src)) continue;
+    if (!fs.existsSync(targetHooks)) fs.mkdirSync(targetHooks, { recursive: true });
+    const dest = path.join(targetHooks, name);
+    if (copyFile(src, dest)) {
+      console.log(`  ✓ Created .forge/hooks/${name}`);
+      try {
+        fs.chmodSync(dest, 0o755); // NOSONAR - hook scripts must be executable
+      } catch (err) {
+        console.warn('chmod not available (Windows):', err.message);
+      }
+    }
   }
 }
 
@@ -2987,6 +2848,18 @@ function isBeadsInitialized() {
   return beadsSetupLib.isBeadsInitialized(projectRoot);
 }
 
+function migrateExistingBeadsLocalState() {
+  if (!fs.existsSync(path.join(projectRoot, '.beads'))) {
+    return;
+  }
+
+  try {
+    beadsSetupLib.ensureBeadsGitExclude(projectRoot);
+  } catch (err) {
+    console.warn(`  Warning: failed to migrate Beads local state: ${err.message}`);
+  }
+}
+
 // Initialize Beads in the project using the defensive safeBeadsInit wrapper
 // Handles config/gitignore writes, hook snapshot/restore, and JSONL pre-seeding
 function initializeBeads(installType) {
@@ -3044,18 +2917,6 @@ function initializeBeads(installType) {
     }
     console.log('  ✓ Beads initialized');
 
-    // Run post-init health check (non-fatal)
-    try {
-      const health = beadsHealthCheck(projectRoot);
-      if (health.healthy) {
-        console.log('  ✓ Beads health check passed');
-      } else {
-        console.log(`  ⚠ Beads health check failed at ${health.failedStep}: ${health.error}`);
-      }
-    } catch (_healthErr) {
-      // Health check is best-effort — don't block setup
-    }
-
     return true;
   } catch (err) {
     console.log('  ⚠ Failed to initialize Beads:', err.message);
@@ -3131,6 +2992,7 @@ async function promptBeadsSetup(question) {
   const beadsStatus = checkForBeads();
 
   if (beadsInitialized) {
+    migrateExistingBeadsLocalState();
     console.log('✓ Beads is already initialized in this project');
     console.log('');
     return;
@@ -3364,6 +3226,10 @@ function autoSetupBeadsInQuickMode() {
   const beadsStatus = checkForBeads();
   const beadsInitialized = isBeadsInitialized();
 
+  if (beadsInitialized) {
+    migrateExistingBeadsLocalState();
+  }
+
   if (!beadsInitialized && beadsStatus) {
     console.log('📦 Initializing Beads...');
     initializeBeads(beadsStatus);
@@ -3415,7 +3281,19 @@ function autoInstallLefthook() {
     return;
   }
 
-  // Not in package.json at all — full install
+  // Not in package.json at all — full install.
+  // GUARD (kernel 22e33dbf): with no package.json in projectRoot, an
+  // `npm install --save-dev lefthook` / `bun add lefthook` resolves against the nearest
+  // ANCESTOR package.json and installs lefthook into the WRONG project (or fails). Skip
+  // the package-manager install entirely — installGitHooks() then wires native
+  // .git/hooks, which need no package.json, so enforcement is still live.
+  if (!fs.existsSync(path.join(projectRoot, 'package.json'))) {
+    console.log('  ℹ No package.json here — skipping lefthook npm install (would target an ancestor).');
+    console.log('    Git hook enforcement will use the native .git/hooks fallback instead.');
+    console.log('');
+    return;
+  }
+
   console.log('📦 Installing lefthook for git hooks...');
   try {
     // SECURITY: secureExecFileSync with PKG_MANAGER — cross-platform support
@@ -3463,11 +3341,10 @@ function autoSetupToolsInQuickMode() {
     console.log('📦 Initializing Skills...');
     initializeSkills(skillsStatus);
     console.log('');
-  } else if (!skillsStatus) {
-    const installCmd = PKG_MANAGER === 'bun' ? 'bun add -g' : 'npm install -g';
-    console.log(`  ℹ Skills not found — install with: ${installCmd} @forge/skills`);
-    console.log('');
   }
+  // No hint when the optional Skills CLI is absent: setup bundles and renders
+  // Forge's skills itself, and the previously advertised "@forge/skills"
+  // package does not exist on npm (kernel issue 6e554b41).
 }
 
 // Helper: Configure default external services in quick mode - extracted to reduce cognitive complexity
@@ -3522,9 +3399,11 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Auto-setup project tools (Beads, Skills)
   autoSetupToolsInQuickMode();
 
-  // Load Claude commands and setup agents (reuse existing helpers)
-  const claudeCommands = loadAndSetupClaudeCommands(selectedAgents);
-  setupSelectedAgents(selectedAgents, claudeCommands);
+  // Setup Claude first if selected, then remaining agents
+  if (selectedAgents.includes('claude')) {
+    setupAgent('claude');
+  }
+  setupSelectedAgents(selectedAgents);
 
   // Detect Husky and migrate before installing Lefthook hooks
   await handleHuskyMigration();
@@ -3649,7 +3528,6 @@ function displayExistingInstallation(projectStatus) {
     : 'Found partial installation:');
 
   if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
-  if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
   if (projectStatus.hasEnvLocal) console.log('  - .env.local');
   console.log('');
 }
@@ -3658,7 +3536,6 @@ function displayExistingInstallation(projectStatus) {
 async function promptForOverwriteDecisions(question, projectStatus) {
   const skipFiles = {
     agentsMd: false,
-    claudeCommands: false
   };
 
   if (projectStatus.hasAgentsMd) {
@@ -3667,12 +3544,6 @@ async function promptForOverwriteDecisions(question, projectStatus) {
     console.log(overwriteAgents ? '  Will overwrite AGENTS.md' : '  Keeping existing AGENTS.md');
   }
 
-  if (projectStatus.hasClaudeCommands) {
-    const overwriteCommands = await askYesNo(question, 'Found existing .claude/commands/. Overwrite?', true);
-    skipFiles.claudeCommands = !overwriteCommands;
-    console.log(overwriteCommands ? '  Will overwrite .claude/commands/' : '  Keeping existing .claude/commands/');
-  }
-
   if (projectStatus.type !== 'fresh') {
     console.log('');
   }
@@ -3680,41 +3551,14 @@ async function promptForOverwriteDecisions(question, projectStatus) {
   return skipFiles;
 }
 
-// Helper: Load and setup Claude commands - extracted to reduce cognitive complexity
-function loadAndSetupClaudeCommands(selectedAgents, skipFiles) {
-  const claudeCommands = {};
-  const needsClaudeCommands = selectedAgents.includes('claude') ||
-    selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands);
-
-  if (!needsClaudeCommands) {
-    return claudeCommands;
-  }
-
-  // First ensure Claude is set up
-  if (selectedAgents.includes('claude')) {
-    setupAgent('claude', null, skipFiles);
-  }
-
-  // Then load the commands (from existing or newly created)
-  getWorkflowCommands().forEach(cmd => {
-    const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
-    const content = readFile(cmdPath);
-    if (content) {
-      claudeCommands[`${cmd}.md`] = content;
-    }
-  });
-
-  return claudeCommands;
-}
-
 // Helper: Setup all selected agents - extracted to reduce cognitive complexity
-function setupSelectedAgents(selectedAgents, claudeCommands, skipFiles) {
+function setupSelectedAgents(selectedAgents, skipFiles) {
   const totalAgents = selectedAgents.length;
   selectedAgents.forEach((agentKey, index) => {
     const agent = AGENTS[agentKey];
     console.log(`\n[${index + 1}/${totalAgents}] Setting up ${agent.name}...`);
     if (agentKey !== 'claude') { // Claude already done above
-      setupAgent(agentKey, claudeCommands, skipFiles);
+      setupAgent(agentKey, skipFiles);
     }
   });
 
@@ -3814,11 +3658,13 @@ async function interactiveSetupWithFlags(flags) {
   setupCoreDocs();
   console.log('');
 
-  // Load Claude commands if needed (delegated to helper)
-  const claudeCommands = loadAndSetupClaudeCommands(selectedAgents, skipFiles);
+  // Setup Claude first if selected (delegated to helper), then remaining agents
+  if (selectedAgents.includes('claude')) {
+    setupAgent('claude', skipFiles);
+  }
 
   // Setup each selected agent with progress indication (delegated to helper)
-  setupSelectedAgents(selectedAgents, claudeCommands, skipFiles);
+  setupSelectedAgents(selectedAgents, skipFiles);
 
   // Handle external services step (delegated to helper)
   await handleExternalServicesStep(flags, rl, question, selectedAgents, projectStatus);
@@ -3832,14 +3678,20 @@ async function interactiveSetupWithFlags(flags) {
 
 // Main
 // Helper: Handle --path setup
-function handlePathSetup(targetPath) {
+function handlePathSetup(targetPath, options = {}) {
   const resolvedPath = path.resolve(targetPath);
 
   // Create directory if it doesn't exist
   if (!fs.existsSync(resolvedPath)) {
+    if (options.create === false) {
+      console.error(`Error: ${resolvedPath} does not exist`);
+      process.exit(1);
+    }
     try {
-      fs.mkdirSync(resolvedPath, { recursive: true });
+    fs.mkdirSync(resolvedPath, { recursive: true });
+    if (!options.quiet) {
       console.log(`Created directory: ${resolvedPath}`);
+    }
     } catch (err) {
       console.error(`Error creating directory: ${err.message}`);
       process.exit(1);
@@ -3855,8 +3707,10 @@ function handlePathSetup(targetPath) {
   // Change to target directory
   try {
     process.chdir(resolvedPath);
-    console.log(`Working directory: ${resolvedPath}`);
-    console.log('');
+    if (!options.quiet) {
+      console.log(`Working directory: ${resolvedPath}`);
+      console.log('');
+    }
   } catch (err) {
     console.error(`Error changing to directory: ${err.message}`);
     process.exit(1);
@@ -3866,6 +3720,15 @@ function handlePathSetup(targetPath) {
   return resolvedPath;
 }
 
+function resolvePathForDryRun(targetPath) {
+  const resolvedPath = path.resolve(targetPath);
+  if (fs.existsSync(resolvedPath) && !fs.statSync(resolvedPath).isDirectory()) {
+    console.error(`Error: ${resolvedPath} is not a directory`);
+    process.exit(1);
+  }
+  return resolvedPath;
+}
+
 // Helper: Determine selected agents from flags
 function determineSelectedAgents(flags) {
   if (flags.all) {
@@ -3914,15 +3777,10 @@ function dryRunSetup(agents) {
       addFileAction(dir + '/', 'Create agent directory');
     }
 
-    // Claude-specific files
+    // Claude-specific files (skills are listed by the per-skill block below)
     if (agentKey === 'claude') {
-      const cmds = getWorkflowCommands();
-      for (const cmd of cmds) {
-        addFileAction(`.claude/commands/${cmd}.md`, 'Workflow command');
-      }
       addFileAction('.claude/rules/workflow.md', 'Workflow rules');
       addFileAction('.claude/scripts/load-env.sh', 'Environment loader script');
-      addFileAction('.claude/skills/forge-workflow/SKILL.md', 'Forge workflow skill');
       addFileAction('.mcp.json', 'MCP server configuration');
       addFileAction('CLAUDE.md', 'Claude root config (links to AGENTS.md)');
     }
@@ -3932,15 +3790,7 @@ function dryRunSetup(agents) {
       addFileAction('.cursor/rules/forge-workflow.mdc', 'Cursor workflow rule');
     }
 
-    // Agent commands (converted from Claude format)
-    if (agent.needsConversion || agent.copyCommands || agent.promptFormat) {
-      const cmds = getWorkflowCommands();
-      const targetDir = agent.dirs[0];
-      for (const cmd of cmds) {
-        const ext = agent.promptFormat ? '.prompt.md' : '.md';
-        addFileAction(`${targetDir}/${cmd}${ext}`, 'Converted workflow command');
-      }
-    }
+
 
     // Agent rules (copied from Claude)
     if (agent.needsConversion) {
@@ -3950,11 +3800,10 @@ function dryRunSetup(agents) {
       }
     }
 
-    // Agent skill
-    if (agent.hasSkill) {
-      const skillDir = agent.dirs.find(d => d.includes('/skills/'));
-      if (skillDir) {
-        addFileAction(`${skillDir}/SKILL.md`, 'Forge workflow skill');
+    // Agent skill — enumerate canonical skills per-agent (codex handled globally elsewhere)
+    if (agentKey !== 'codex' && agent.hasSkill && agent.skillsDir) {
+      for (const skill of listCanonicalSkills(packageDir)) {
+        addFileAction(`${agent.skillsDir}/${skill.name}/SKILL.md`, 'Forge stage skill');
       }
     }
 
@@ -3988,6 +3837,8 @@ async function executeSetup(config) {
   checkPrerequisites();
   console.log('');
 
+  migrateExistingBeadsLocalState();
+
   // Copy AGENTS.md (only if not exists — preserve user customizations; actionLog tracks it)
   const agentsDest = path.join(projectRoot, 'AGENTS.md');
   if (fs.existsSync(agentsDest)) {
@@ -4002,15 +3853,11 @@ async function executeSetup(config) {
   setupCoreDocs();
   console.log('');
 
-  // Load Claude commands — use loadAndSetupClaudeCommands when claude is selected
-  // so that .claude/commands/ are seeded before reading them
-  const claudeCommands = agents.includes('claude')
-    ? loadAndSetupClaudeCommands(agents)
-    : loadClaudeCommands(agents);
-
-  // Setup agents with progress output (setupSelectedAgents skips claude internally
-  // since loadAndSetupClaudeCommands already handled it above)
-  setupSelectedAgents(agents, claudeCommands);
+  // Setup Claude first if selected, then remaining agents
+  if (agents.includes('claude')) {
+    setupAgent('claude');
+  }
+  setupSelectedAgents(agents);
 
   // Detect Husky and migrate before installing Lefthook hooks
   await handleHuskyMigration();
@@ -4036,36 +3883,12 @@ async function executeSetup(config) {
 // Helper: Scaffold Beads GitHub sync when --sync flag is provided
 async function handleSyncScaffold() {
   console.log('');
-  console.log('Scaffolding Beads GitHub sync workflows (--sync)...');
+  console.log('Beads GitHub sync scaffolding is deprecated (--sync).');
   try {
-    // Scaffold sync files using the new lib module
     const result = scaffoldBeadsSync(projectRoot, packageDir);
-    for (const f of (result.filesCreated || [])) {
-      console.log(`  Created: ${f}`);
-    }
-    for (const f of (result.filesSkipped || [])) {
-      console.log(`  Skipped: ${f} (already exists)`);
-    }
-
-    // Detect default branch and pin forge-managed workflows to the repo baseline Beads version.
-    const branch = detectDefaultBranch(projectRoot);
-    const beadsVersion = DEFAULT_BEADS_VERSION;
-    const workflowDir = path.join(projectRoot, '.github', 'workflows');
-    templateWorkflows(workflowDir, branch, beadsVersion, result.filesCreated || []);
-    console.log(`  Branch: ${branch}, Beads version: ${beadsVersion}`);
-
-    // PAT setup: interactive when possible, reminder otherwise
-    try {
-      const patResult = setupPAT(projectRoot, { interactive: !NON_INTERACTIVE });
-      if (patResult.success) {
-        console.log('  PAT configured for Beads sync');
-      } else if (patResult.reminder) {
-        console.log(`  ${patResult.reminder}`);
-      } else if (patResult.instructions) {
-        console.log(`  ${patResult.instructions.split('\n')[0]}`);
-      }
-    } catch (_patErr) {
-      // PAT setup is best-effort — don't block sync scaffold
+    console.log(`  ${result.message}`);
+    for (const f of result.filesRemoved || []) {
+      console.log(`  Removed deprecated sync file: ${f}`);
     }
   } catch (err) {
     console.error(`  Error scaffolding GitHub-Beads sync: ${err.message}`);
@@ -4089,6 +3912,11 @@ async function handleSetupCommand(selectedAgents, flags) {
   }
 }
 
+async function runInteractiveSetupFallback(flags, interactiveSetup = interactiveSetupWithFlags) {
+  migrateExistingBeadsLocalState();
+  return interactiveSetup(flags);
+}
+
 // Helper: Handle external services configuration
 async function handleExternalServices(skipExternal, selectedAgents) {
   if (skipExternal) {
@@ -4119,6 +3947,17 @@ async function handleExternalServices(skipExternal, selectedAgents) {
 async function main() {
   const command = args[0];
   const flags = parseFlags();
+  const suppressJsonIntrospectionOutput = ['options', 'explain'].includes(command) && args.includes('--json');
+  const suppressCommandJsonOutput = args.includes('--json');
+  const suppressDocsDetectOutput = command === 'docs' && args[1] === 'detect';
+  const profileDryRunArgs = ['--minimal', '--standard', '--full'];
+  const suppressAdoptionDryRunOutput = flags.dryRun && (
+    command === 'init' || (command === 'setup' && profileDryRunArgs.some(arg => args.includes(arg)))
+  );
+  const suppressStructuredOutput = suppressJsonIntrospectionOutput ||
+    suppressCommandJsonOutput ||
+    suppressDocsDetectOutput ||
+    suppressAdoptionDryRunOutput;
 
   // Wire up incremental setup state from parsed flags
   FORCE_MODE = flags.force;
@@ -4128,20 +3967,33 @@ async function main() {
   SYNC_ENABLED = flags.sync;
   actionLog = new SetupActionLog();
 
-  if (NON_INTERACTIVE) {
+  // The non-interactive agent-selection notice is DEBUG-ONLY (kernel issue
+  // a9bbd065): it used to print on stderr for EVERY command run by a non-TTY
+  // agent/CI, polluting otherwise-clean command output. It only matters when
+  // setup-style agent selection actually happens, so it now requires --verbose
+  // (or FORGE_DEBUG=1) to appear.
+  if (NON_INTERACTIVE && (VERBOSE_MODE || process.env.FORGE_DEBUG === '1') && !suppressStructuredOutput) {
     const agentFlag = flags.agents;
     if (agentFlag && agentFlag.length > 0) {
       // flags.agents is a comma-separated string (e.g. "claude,cursor")
       const agentDisplay = agentFlag.replace(/,/g, ', ');
-      console.log(`Non-interactive mode: using provided agent selection (${agentDisplay})`);
+      console.error(`Non-interactive mode: using provided agent selection (${agentDisplay})`);
     } else {
-      console.log('Non-interactive mode: using default agent selection (all)');
+      console.error('Non-interactive mode: using default agent selection (all)');
     }
   }
 
-  // Show help
+  // Show help. `--help` after a known registry subcommand (e.g. `forge status
+  // --help`) renders that command's usage; bare `forge --help` keeps the global
+  // banner. `setup` is special-cased OUT: the global banner IS setup's detailed
+  // help, so `forge setup --help` must keep showing it (not the terse registry line).
   if (flags.help) {
-    showHelp();
+    const helpRegistry = loadCommands(path.join(__dirname, '..', 'lib', 'commands'));
+    if (command && command !== 'setup' && helpRegistry.commands.has(command)) {
+      printCommandHelp(helpRegistry.commands.get(command));
+    } else {
+      showHelp();
+    }
     return;
   }
 
@@ -4153,8 +4005,11 @@ async function main() {
 
   // Handle --path option: change to target directory
   if (flags.path) {
+    const createTargetPath = !(command === 'docs' && ['verify', 'detect'].includes(args[1]));
     // Update projectRoot after changing directory to maintain state consistency
-    projectRoot = handlePathSetup(flags.path);
+    projectRoot = suppressAdoptionDryRunOutput
+      ? resolvePathForDryRun(flags.path)
+      : handlePathSetup(flags.path, { quiet: suppressStructuredOutput, create: createTargetPath });
   }
 
   // Load command registry (auto-discovered commands from lib/commands/)
@@ -4180,24 +4035,51 @@ async function main() {
   // Registry command dispatch — auto-discovered commands take priority
   if (registry.commands.has(command)) {
     try {
+      // Resolve the issue backend (flag > env > config > default) and, for issue
+      // commands, strip the selector tokens (--kernel / --issue-backend) from the
+      // args so they never reach the handler or bd. For the kernel backend this
+      // also assembles the driver + migrated broker (B1/B2).
+      const { commandOpts, args: dispatchArgs } = await resolveCommandOpts(
+        command,
+        args.slice(1),
+        { env: process.env, projectRoot },
+      );
       const result = await executeCommand(
         registry.commands,
         command,
-        args.slice(1),
+        dispatchArgs,
         flags,
         projectRoot,
         {
+          // Pass interactivity so issue writes render a human confirmation at a real
+          // terminal but stay machine-parseable JSON when piped/scripted (842a8be7).
+          commandOpts: { ...(commandOpts || {}), isInteractive: Boolean(process.stdout.isTTY) },
           enforceStage: (context) => enforceStageEntry({
             commandName: context.commandName,
             args: context.args,
             flags: context.flags,
             projectRoot: context.projectRoot,
+            // Kernel is the source of truth for workflow stage state: resolve the
+            // active worktree's issue and persist/read currentStage in the kernel
+            // so `ship` is reachable from a pure-CLI plan->dev->validate flow.
+            autoResolveKernel: true,
           }),
         }
       );
       if (result && !result.success) {
+        if (
+          typeof result.output === 'string' &&
+          result.output.length > 0 &&
+          result.output !== result.error
+        ) {
+          process.stdout.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+        }
         console.error(result.error || result.message || 'Command failed');
-        process.exit(1);
+        // Issue commands surface the issue-command-contract exit_code as
+        // `result.exitCode` (e.g. not-found=3, validation=6). Honor it so failed
+        // commands no longer collapse to exit 1; other registry commands omit
+        // `exitCode` and keep the historical exit 1.
+        process.exit(Number.isInteger(result.exitCode) ? result.exitCode : 1);
       }
       if (result && typeof result.output === 'string' && result.output.length > 0) {
         process.stdout.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
@@ -4217,6 +4099,7 @@ async function main() {
         args: args.slice(1),
         flags,
         projectRoot,
+        autoResolveKernel: true,
       });
     } catch (err) {
       console.error(`Error running '${command}':`, err.message);
@@ -4257,6 +4140,12 @@ async function main() {
       return;
     }
 
+    if (flags.sync && selectedAgents.length === 0) {
+      migrateExistingBeadsLocalState();
+      await handleSyncScaffold();
+      return;
+    }
+
     // Agents specified via flag or --yes default (non-quick mode)
     if (selectedAgents.length > 0) {
       await handleSetupCommand(selectedAgents, flags);
@@ -4264,7 +4153,7 @@ async function main() {
     }
 
     // Interactive setup (skip-external still applies)
-    await interactiveSetupWithFlags(flags);
+    await runInteractiveSetupFallback(flags);
   } else if (command === 'recommend') {
     const { handleRecommend, formatRecommendations } = require('../lib/commands/recommend');
     const result = handleRecommend(flags, projectRoot);
@@ -4285,9 +4174,68 @@ async function main() {
       }
       console.log('');
       console.log('  Usage: forge docs <topic>');
+      console.log('         forge docs verify [--path <dir>] [--json] [--baseline <file>] [--write-baseline <file>] [--min-docstring-coverage <percent>]');
+      console.log('         forge docs detect [--path <dir>] [--json]');
       console.log('');
+      console.log('  Note: forge docs verify|detect --path requires an existing directory.');
+      console.log('');
+    } else if (topic === 'verify' || topic === 'detect') {
+      const minCoverageIndex = args.indexOf('--min-docstring-coverage');
+      let minDocstringCoverage = 0;
+      if (minCoverageIndex >= 0) {
+        const rawMinCoverage = args[minCoverageIndex + 1];
+        const parsedMinCoverage = Number(rawMinCoverage);
+        if (!rawMinCoverage || !Number.isFinite(parsedMinCoverage) || parsedMinCoverage < 0 || parsedMinCoverage > 100) {
+          console.error('Error: --min-docstring-coverage must be a number between 0 and 100');
+          process.exitCode = 1;
+          return;
+        }
+        minDocstringCoverage = parsedMinCoverage;
+      }
+      const baselineIndex = args.indexOf('--baseline');
+      const writeBaselineIndex = args.indexOf('--write-baseline');
+      const baselinePath = baselineIndex >= 0 ? args[baselineIndex + 1] : null;
+      const writeBaselinePath = writeBaselineIndex >= 0 ? args[writeBaselineIndex + 1] : null;
+      if (topic === 'detect' && writeBaselineIndex >= 0) {
+        console.error('Error: --write-baseline is only supported with `forge docs verify`');
+        process.exitCode = 1;
+        return;
+      }
+      if (baselineIndex >= 0 && (!baselinePath || baselinePath.startsWith('-'))) {
+        console.error('Error: --baseline requires a file path');
+        process.exitCode = 1;
+        return;
+      }
+      if (writeBaselineIndex >= 0 && (!writeBaselinePath || writeBaselinePath.startsWith('-'))) {
+        console.error('Error: --write-baseline requires a file path');
+        process.exitCode = 1;
+        return;
+      }
+      let result;
+      try {
+        result = validateDocs(projectRoot, { baselinePath, minDocstringCoverage });
+        if (writeBaselinePath) {
+          writeDocsBaseline(projectRoot, writeBaselinePath, result);
+        }
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (args.includes('--json') || topic === 'detect') {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatDocsValidation(result));
+      }
+      const hasUnbaselinedFailure = result.failures.some((failure) => failure.type !== 'broken-link');
+      if ((!writeBaselinePath && !result.ok) || (writeBaselinePath && hasUnbaselinedFailure)) {
+        process.exitCode = 1;
+      }
     } else {
-      const result = getTopicContent(topic, packageDir);
+      // `forge docs` reads packaged docs; route through the asset root so any
+      // embedded topic resolves in a compiled binary too. (Full docs/ embedding
+      // for arbitrary topics is deferred to step 3 — see the step-2 plan note.)
+      const result = getTopicContent(topic, getPackageRoot(packageDir));
       if (result.error) {
         console.error(`  Error: ${result.error}`);
         process.exitCode = 1;
@@ -4389,9 +4337,34 @@ async function main() {
     console.log('  To set up in your project:');
     console.log(`    ${runCmd} forge setup`);
     console.log('');
-  } else {
-    // Explicit invocation with no command: run minimal install
+  } else if (command === undefined && fs.existsSync(path.join(projectRoot, 'AGENTS.md'))) {
+    // Bare `forge` in an INITIALIZED project orients instead of mutating: render the
+    // same read-only one-glance view as `forge status`. Newcomers typing `forge` to
+    // get their bearings should never trigger the minimal install.
+    try {
+      const { commandOpts, args: dispatchArgs } = await resolveCommandOpts(
+        'status',
+        [],
+        { env: process.env, projectRoot },
+      );
+      const result = await executeCommand(registry.commands, 'status', dispatchArgs, flags, projectRoot, { commandOpts });
+      if (result && typeof result.output === 'string' && result.output.length > 0) {
+        process.stdout.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+      }
+    } catch (err) {
+      console.error(`Error running 'status':`, err.message);
+      process.exit(1);
+    }
+  } else if (command === undefined) {
+    // Explicit invocation with no command in an UNINITIALIZED project: run minimal install.
     minimalInstall();
+  } else {
+    // Defined but unrecognized command → fail honestly instead of printing the
+    // installer banner with exit 0 (kernel b3bae4f3). A typo like `forge bogusxyz`
+    // must be detectable by scripts (non-zero exit) and humans (a real error).
+    console.error(`Error: Unknown command '${command}'`);
+    console.error("Run 'forge --help' to see the available commands.");
+    process.exit(1);
   }
 }
 
@@ -4815,7 +4788,6 @@ if (require.main === module) {
 
 module.exports = {
   ensureDirWithNote,
-  getWorkflowCommands,
   validateDirectoryPathInput,
   validateUserInput,
 };