forge-workflow 0.1.0-beta.4 → 0.1.0-beta.5

package/bin/forge.js

@@ -80,10 +80,8 @@ const { firstPositionalIndex } = require('../lib/global-flags');
 const contextMerge = require('../lib/context-merge');
 const projectDiscovery = require('../lib/project-discovery');
 
-// Load lib modules for symlink, beads, and PAT setup
+// Load lib modules for symlink setup
 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');
@@ -113,7 +111,6 @@ let FORCE_MODE = false;
 let VERBOSE_MODE = false;
 let NON_INTERACTIVE = false;
 let SYMLINK_ONLY = false;   // --symlink: fail instead of copy fallback
-let SYNC_ENABLED = false;   // --sync: scaffold Beads GitHub sync workflows
 let actionLog = new SetupActionLog();
 
 // Detected package manager
@@ -429,7 +426,7 @@ Use these default-template commands via \`/command-name\`:
 - \`/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)
+- \`/verify\` - Post-merge health check (CI on main, close kernel issues)
 
 Pre-merge gate (not a numbered stage): finish docs + confirm CI green + hand off the PR — embedded in the /ship and /review stages.
 
@@ -706,9 +703,7 @@ async function detectProjectStatus() {
     agentsMdLines: 0,
     claudeMdLines: 0,
     // Project tools status
-    hasBeads: isBeadsInitialized(),
     hasSkills: isSkillsInitialized(),
-    beadsInstallType: checkForBeads(),
     skillsInstallType: checkForSkills(),
     // Enhanced: Auto-detected project context
     autoDetected: null
@@ -2196,15 +2191,6 @@ function displaySetupSummary(selectedAgents) {
   console.log('Project Tools Status:');
   console.log('');
 
-  // Beads status
-  if (isBeadsInitialized()) {
-    console.log('  ✓ Beads initialized - Track work: forge ready');
-  } else if (checkForBeads()) {
-    console.log('  ! Beads available - Run: bd init');
-  } else {
-    console.log(`  - Beads not installed - Run: ${PKG_MANAGER} install -g @beads/bd && bd init`);
-  }
-
   // Skills status
   if (isSkillsInitialized()) {
     console.log('  ✓ Skills initialized - Manage skills: skills list');
@@ -2351,7 +2337,7 @@ function parseFlags() {
     verbose: false,   // Show file-by-file detail in setup summary
     dryRun: false,    // Preview planned actions without writing files
     symlink: false,   // Create CLAUDE.md as symlink to AGENTS.md (--symlink)
-    sync: false,      // Scaffold Beads GitHub sync workflows (--sync)
+    skillsOnly: false, // Install skills without Git or harness hook enforcement
   };
 
   // Issue passthrough commands delegate all flags to bd.
@@ -2417,8 +2403,8 @@ function parseFlags() {
     } else if (arg === '--symlink') {
       flags.symlink = true;
       i++;
-    } else if (arg === '--sync') {
-      flags.sync = true;
+    } else if (arg === '--skills-only' || arg === '--no-hooks') {
+      flags.skillsOnly = true;
       i++;
     } else if (arg === '--interview') {
       flags.interview = true;
@@ -2577,6 +2563,8 @@ function showHelp() {
   console.log('  --type <type>        Set workflow profile type manually');
   console.log('                       Options: critical, standard, simple, hotfix, docs, refactor');
   console.log('  --dry-run            Preview planned actions without writing any files');
+  console.log('  --skills-only        Install skills without Git hooks, Forge-native, or harness hooks');
+  console.log('                       Alias: --no-hooks');
   console.log('  --interview          Force context interview (gather project information)');
   console.log('  --budget <mode>      Budget mode for recommend (free, open-source, startup, professional, custom)');
   console.log('  --yes, -y            Non-interactive setup with sensible defaults');
@@ -2602,6 +2590,7 @@ function showHelp() {
   console.log('  npx forge setup --yes                    # Non-interactive, defaults to claude');
   console.log('  npx forge setup --yes --agents cursor   # Non-interactive, specific agent');
   console.log('  npx forge setup --all --skip-external    # All agents, no services');
+  console.log('  npx forge setup --agents claude --skills-only # Skills without hook enforcement');
   console.log('  npx forge setup --merge=smart            # Use intelligent merge for existing files');
   console.log('  npx forge setup --type=critical          # Set workflow profile manually');
   console.log('  npx forge setup --interview              # Force context interview');
@@ -2835,121 +2824,6 @@ function checkForLefthook() {
   return status;
 }
 
-// Check if Beads is installed (global, local, or bunx-capable)
-function checkForBeads() {
-  // Try global install first
-  try {
-    secureExecFileSync('bd', ['version'], { stdio: 'ignore' });
-    return 'global';
-  } catch (err) {
-    // Not global
-    console.warn('Beads not found globally:', err.message);
-  }
-
-  // Check if bunx can run it
-  try {
-    secureExecFileSync('bunx', ['@beads/bd', 'version'], { stdio: 'ignore' });
-    return 'bunx';
-  } catch (err) {
-    // Not bunx-capable
-    console.warn('Beads not available via bunx:', err.message);
-  }
-
-  // Check local project installation
-  const pkgPath = path.join(projectRoot, 'package.json');
-  if (!fs.existsSync(pkgPath)) return null;
-
-  try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    const isInstalled = pkg.devDependencies?.['@beads/bd'] || pkg.dependencies?.['@beads/bd'];
-    return isInstalled ? 'local' : null;
-  } catch (err) {
-    console.warn('Failed to check Beads in package.json:', err.message);
-    return null;
-  }
-}
-// Check if Beads is initialized in project — delegates to lib/beads-setup
-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) {
-  console.log('Initializing Beads in project...');
-
-  // Build the execBdInit function based on installType
-  const execBdInit = (root) => {
-    // SECURITY: execFileSync with hardcoded commands
-    if (installType === 'global') {
-      secureExecFileSync('bd', ['init'], { stdio: 'inherit', cwd: root });
-    } else if (installType === 'bunx') {
-      secureExecFileSync('bunx', ['@beads/bd', 'init'], { stdio: 'inherit', cwd: root });
-    } else if (installType === 'local') {
-      secureExecFileSync('npx', ['bd', 'init'], { stdio: 'inherit', cwd: root });
-    }
-  };
-
-  // Derive prefix from package.json name or directory name
-  let prefix;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
-    prefix = pkg.name || path.basename(projectRoot);
-  } catch (_e) {
-    prefix = path.basename(projectRoot);
-  }
-
-  try {
-    const result = beadsSetupLib.safeBeadsInit(projectRoot, {
-      prefix,
-      execBdInit,
-      restoreLefthook: (root) => {
-        try {
-          secureExecFileSync('lefthook', ['install'], { stdio: 'ignore', cwd: root });
-        } catch (_e) {
-          // lefthook may not be installed yet — non-fatal
-        }
-      }
-    });
-
-    if (result.skipped) {
-      console.log('  ✓ Beads already initialized');
-      return true;
-    }
-
-    if (!result.success) {
-      for (const e of result.errors) {
-        console.log(`  ⚠ ${e}`);
-      }
-      console.log('  Run manually: bd init');
-      return false;
-    }
-
-    for (const w of result.warnings) {
-      console.warn(`  ⚠ ${w}`);
-    }
-    console.log('  ✓ Beads initialized');
-
-    return true;
-  } catch (err) {
-    console.log('  ⚠ Failed to initialize Beads:', err.message);
-    console.log('  Run manually: bd init');
-    return false;
-  }
-}
-
 // Check if Skills CLI is installed
 function checkForSkills() {
   // Try global install first
@@ -3006,60 +2880,6 @@ function initializeSkills(installType) {
   }
 }
 
-// Prompt for Beads setup - extracted to reduce cognitive complexity
-async function promptBeadsSetup(question) {
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('Beads Setup (Recommended)');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('');
-
-  const beadsInitialized = isBeadsInitialized();
-  const beadsStatus = checkForBeads();
-
-  if (beadsInitialized) {
-    migrateExistingBeadsLocalState();
-    console.log('✓ Beads is already initialized in this project');
-    console.log('');
-    return;
-  }
-
-  if (beadsStatus) {
-    // Already installed, just need to initialize
-    console.log(`ℹ Beads is installed (${beadsStatus}), but not initialized`);
-    const initBeads = await question('Initialize Beads in this project? (y/n): ');
-
-    if (initBeads.toLowerCase() === 'y') {
-      initializeBeads(beadsStatus);
-    } else {
-      console.log('Skipped Beads initialization. Run manually: bd init');
-    }
-    console.log('');
-    return;
-  }
-
-  // Not installed
-  console.log('ℹ Beads is not installed');
-  const installBeads = await question('Install Beads? (y/n): ');
-
-  if (installBeads.toLowerCase() !== 'y') {
-    console.log('Skipped Beads installation');
-    console.log('');
-    return;
-  }
-
-  console.log('');
-  console.log('Choose installation method:');
-  console.log('  1. Global (recommended) - Available system-wide');
-  console.log('  2. Local - Project-specific devDependency');
-  console.log('  3. Bunx - Use via bunx (requires bun)');
-  console.log('');
-  const method = await question('Choose method (1-3): ');
-
-  console.log('');
-  installBeadsWithMethod(method);
-  console.log('');
-}
-
 // Helper: Install tool via bunx - extracted to reduce cognitive complexity
 function installViaBunx(packageName, versionArgs, initFn, toolName) {
   console.log('Testing bunx capability...');
@@ -3073,68 +2893,6 @@ function installViaBunx(packageName, versionArgs, initFn, toolName) {
   }
 }
 
-// Helper: Install Beads with chosen method - extracted to reduce cognitive complexity
-// SECURITY NOTE: Downloads and executes a remote PowerShell script.
-// The npm @beads/bd package is broken on Windows (GitHub Issue #1031, closed "not planned"),
-// so the official PowerShell installer is the only supported path.
-// Mitigations: HTTPS transport (prevents MITM), official beads repo, user-visible URL.
-// TODO: Pin to a versioned release tag once beads publishes tagged releases (e.g. v0.49.1).
-const BEADS_INSTALL_PS1_URL = 'https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1';
-
-function installBeadsOnWindows() {
-  console.log('  (Windows detected: using PowerShell installer)');
-  console.log(`  Downloading: ${BEADS_INSTALL_PS1_URL}`);
-  secureExecFileSync('powershell.exe', [
-    '-NoProfile', '-NonInteractive', '-Command',
-    `irm ${BEADS_INSTALL_PS1_URL} | iex`
-  ], { stdio: 'inherit' });
-}
-
-function installBeadsWithMethod(method) {
-  try {
-    // SECURITY: secureExecFileSync with hardcoded commands
-    if (method === '1') {
-      console.log('Installing Beads globally...');
-      if (process.platform === 'win32') {
-        installBeadsOnWindows();
-      } else {
-        const pkgManager = PKG_MANAGER === 'bun' ? 'bun' : 'npm';
-        secureExecFileSync(pkgManager, ['install', '-g', '@beads/bd'], { stdio: 'inherit' });
-      }
-      console.log('  ✓ Beads installed globally');
-      initializeBeads('global');
-    } else if (method === '2') {
-      console.log('Installing Beads locally...');
-      // On Windows, npm postinstall for @beads/bd runs Expand-Archive which has EPERM file-locking
-      // (GitHub Issue #1031, closed "not planned") — same root cause as global install.
-      // Redirect Windows users to the global PowerShell installer instead.
-      if (process.platform === 'win32') {
-        console.log('  ⚠ Local install not supported on Windows (npm @beads/bd EPERM issue).');
-        console.log('  Falling back to global PowerShell installer...');
-        installBeadsOnWindows();
-      } else {
-        const pkgManager = PKG_MANAGER === 'bun' ? 'bun' : 'npm';
-        secureExecFileSync(pkgManager, ['install', '-D', '@beads/bd'], { stdio: 'inherit', cwd: projectRoot });
-      }
-      console.log('  ✓ Beads installed');
-      // On Windows the fallback was global (PowerShell installer), so init as 'global'
-      initializeBeads(process.platform === 'win32' ? 'global' : 'local');
-    } else if (method === '3') {
-      installViaBunx('@beads/bd', ['version'], initializeBeads, 'Beads');
-    } else {
-      console.log('Invalid choice. Skipping Beads installation.');
-    }
-  } catch (err) {
-    console.warn('Beads installation failed:', err.message);
-    console.log('  ⚠ Failed to install Beads:', err.message);
-    if (process.platform === 'win32') {
-      console.log(`  Run manually: irm ${BEADS_INSTALL_PS1_URL} | iex`);
-    } else {
-      console.log(`  Run manually: ${PKG_MANAGER === 'bun' ? 'bun add -g' : 'npm install -g'} @beads/bd && bd init`);
-    }
-  }
-}
-
 // Helper: Get package-manager-specific install args for Skills
 function getSkillsInstallArgs(scope) {
   const globalFlag = scope === 'global' ? '-g' : '-D';
@@ -3223,68 +2981,23 @@ async function promptSkillsSetup(question) {
   console.log('');
 }
 
-// Interactive setup for Beads and Skills
-async function setupProjectTools(rl, question) {
+// Interactive setup for Skills
+async function setupProjectTools(_rl, question) {
   console.log('');
   console.log('═══════════════════════════════════════════════════════════');
   console.log('  STEP 2: Project Tools (Recommended)');
   console.log('═══════════════════════════════════════════════════════════');
   console.log('');
-  console.log('Forge recommends three tools for enhanced workflows:');
-  console.log('');
-  console.log('• Beads - Git-backed issue tracking');
-  console.log('  Persists tasks across sessions, tracks dependencies.');
-  console.log('  Command: forge ready, forge create, forge close');
+  console.log('Forge recommends the following tool for enhanced workflows:');
   console.log('');
   console.log('• Skills - Universal SKILL.md management');
   console.log('  Manage AI agent skills across all agents.');
   console.log('  Command: skills create, skills list, skills sync');
   console.log('');
 
-  // Use helper functions to reduce complexity
-  await promptBeadsSetup(question);
   await promptSkillsSetup(question);
 }
 
-// Auto-setup Beads in quick mode - extracted to reduce cognitive complexity
-function autoSetupBeadsInQuickMode() {
-  const beadsStatus = checkForBeads();
-  const beadsInitialized = isBeadsInitialized();
-
-  if (beadsInitialized) {
-    migrateExistingBeadsLocalState();
-  }
-
-  if (!beadsInitialized && beadsStatus) {
-    console.log('📦 Initializing Beads...');
-    initializeBeads(beadsStatus);
-    console.log('');
-  } else if (!beadsInitialized && !beadsStatus) {
-    console.log('📦 Installing Beads globally...');
-    try {
-      // SECURITY: use PowerShell on Windows (npm @beads/bd is broken on Windows - Issue #1031)
-      if (process.platform === 'win32') {
-        installBeadsOnWindows();
-      } else {
-        const pkgManager = PKG_MANAGER === 'bun' ? 'bun' : 'npm';
-        secureExecFileSync(pkgManager, ['install', '-g', '@beads/bd'], { stdio: 'inherit' });
-      }
-      console.log('  ✓ Beads installed globally');
-      initializeBeads('global');
-    } catch (err) {
-      // Installation failed - provide manual instructions
-      console.log('  ⚠ Could not install Beads automatically');
-      console.log(`    Error: ${err.message}`);
-      if (process.platform === 'win32') {
-        console.log(`  Run manually: irm ${BEADS_INSTALL_PS1_URL} | iex`);
-      } else {
-        console.log(`  Run manually: ${PKG_MANAGER === 'bun' ? 'bun add -g' : 'npm install -g'} @beads/bd && bd init`);
-      }
-    }
-    console.log('');
-  }
-}
-
 // Helper: Auto-install lefthook if not present - extracted to reduce cognitive complexity
 function autoInstallLefthook() {
   const status = checkForLefthook();
@@ -3340,26 +3053,9 @@ function autoInstallLefthook() {
 }
 
 // Helper: Verify a tool is callable after install - extracted to reduce cognitive complexity
-function verifyToolInstall(command, args, toolName) {
-  try {
-    secureExecFileSync(command, args, { stdio: 'ignore' });
-    return true;
-  } catch (_err) { // NOSONAR - S2486: Intentionally ignored; verification failure is handled by caller
-    console.log(`  ⚠ ${toolName} installed but not callable. Check your PATH.`);
-    return false;
-  }
-}
 
 // Helper: Auto-setup tools (Skills) in quick mode - extracted to reduce cognitive complexity
 function autoSetupToolsInQuickMode() {
-  // Beads: auto-install or initialize
-  autoSetupBeadsInQuickMode();
-
-  // Post-install verification for Beads
-  if (isBeadsInitialized()) {
-    verifyToolInstall('bd', ['version'], 'Beads');
-  }
-
   // Skills: only initialize if already installed (recommended tool)
   const skillsStatus = checkForSkills();
   if (skillsStatus && !isSkillsInitialized()) {
@@ -3421,7 +3117,7 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Auto-install lefthook if missing
   autoInstallLefthook();
 
-  // Auto-setup project tools (Beads, Skills)
+  // Auto-setup project tools (Skills)
   autoSetupToolsInQuickMode();
 
   // Setup Claude first if selected, then remaining agents
@@ -3440,11 +3136,6 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Configure external services with defaults (unless skipped)
   configureDefaultExternalServices(skipExternal);
 
-  // --sync flag: scaffold Beads GitHub sync workflows without prompting
-  if (SYNC_ENABLED) {
-    await handleSyncScaffold();
-  }
-
   // Progressive setup summary
   console.log('');
   console.log(renderSetupSummary(actionLog, selectedAgents, VERBOSE_MODE));
@@ -3862,8 +3553,6 @@ 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)) {
@@ -3894,32 +3583,12 @@ async function executeSetup(config) {
   // External services (unless skipped)
   await handleExternalServices(skipExternal, agents);
 
-  // --sync flag: scaffold Beads GitHub sync workflows without prompting
-  if (SYNC_ENABLED) {
-    await handleSyncScaffold();
-  }
-
   // Progressive setup summary
   console.log('');
   console.log(renderSetupSummary(actionLog, agents, VERBOSE_MODE));
   console.log('');
 }
 
-// Helper: Scaffold Beads GitHub sync when --sync flag is provided
-async function handleSyncScaffold() {
-  console.log('');
-  console.log('Beads GitHub sync scaffolding is deprecated (--sync).');
-  try {
-    const result = scaffoldBeadsSync(projectRoot, packageDir);
-    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}`);
-  }
-}
-
 // Helper: Handle setup command in non-quick mode
 async function handleSetupCommand(selectedAgents, flags) {
   // Allow callers (e.g. reinstall) to override projectRoot without process.chdir()
@@ -3938,7 +3607,6 @@ async function handleSetupCommand(selectedAgents, flags) {
 }
 
 async function runInteractiveSetupFallback(flags, interactiveSetup = interactiveSetupWithFlags) {
-  migrateExistingBeadsLocalState();
   return interactiveSetup(flags);
 }
 
@@ -3989,7 +3657,6 @@ async function main() {
   VERBOSE_MODE = flags.verbose;
   NON_INTERACTIVE = flags.nonInteractive || flags.yes || isNonInteractive();
   SYMLINK_ONLY = flags.symlink;
-  SYNC_ENABLED = flags.sync;
   actionLog = new SetupActionLog();
 
   // The non-interactive agent-selection notice is DEBUG-ONLY (kernel issue
@@ -4159,11 +3826,10 @@ async function main() {
       console.error(`Error running '${command}':`, err.message);
       process.exit(1);
     }
-    // NOTE: the autonomous-shepherd per-command trigger is intentionally NOT wired here.
-    // The reconcile engine + daemon land in this PR; the auto-fire wiring is deferred to a
-    // follow-up (W-S4c) because a naive dispatch-finally trigger spawns a session-outliving
-    // daemon on EVERY command, which breaks test isolation (Windows rmSync EBUSY) and needs
-    // its own firing-policy + containment design. Start the daemon via `forge shepherd daemon`.
+    // NOTE: an autonomous-shepherd every-command dispatch-finally trigger is intentionally
+    // NOT wired here. Automatic firing is deliberately limited to the approved seams:
+    // supported session start, successful push, and successful non-dry-run ship. Ordinary
+    // commands cannot spawn a session-outliving daemon or break test isolation.
     return;
   }
 
@@ -4216,12 +3882,6 @@ 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);
@@ -4621,20 +4281,6 @@ function checkGitWorkingDirectory() {
   }
 }
 
-// Helper: Update Beads issue after PR rollback
-function updateBeadsIssue(commitMessage) {
-  const issueMatch = commitMessage.match(/#(\d+)/);
-  if (!issueMatch) return;
-
-  try {
-    const { execFileSync } = require('node:child_process');
-    execFileSync('bd', ['update', issueMatch[1], '--status', 'reverted', '--comment', 'PR reverted'], { stdio: 'inherit' });
-    console.log(`     Updated Beads issue #${issueMatch[1]} to 'reverted'`);
-  } catch {
-    // Beads not installed - silently continue
-  }
-}
-
 // Helper: Handle commit rollback
 function handleCommitRollback(target, dryRun, execSync) {
   if (dryRun) {
@@ -4656,10 +4302,6 @@ function handlePrRollback(target, dryRun, execSync) {
     files.trim().split('\n').forEach(f => console.log(`       - ${f}`));
   } else {
     execSync(`git revert -m 1 --no-edit ${target}`, { stdio: 'inherit' });
-
-    // Update Beads issue if linked
-    const commitMsg = execSync(`git log -1 --format=%B ${target}`, { encoding: 'utf-8' });
-    updateBeadsIssue(commitMsg);
   }
 }
 

package/docs/INDEX.md

@@ -49,7 +49,7 @@ This is the canonical map for Forge documentation. DeepWiki and other generated
 - [Protected path manifest](reference/PROTECTED_PATH_MANIFEST.md) - protected path manifest schema, harness enforcement mapping, and evidence command.
 - [Patch format](reference/patch-md-format.md) - `.forge/patch.md` conventions.
 - [Upgrade safety](reference/upgrade-safety.md) - trust policy and rollback limits.
-- [Insights and recap](reference/INSIGHTS_RECAP.md) - `forge insights` and `forge recap` evidence sources, output, and limitations.
+- [Insights and recap](reference/INSIGHTS_RECAP.md) - `forge insights` and `forge recap <issue>` evidence sources, output, and limitations.
 - [Examples](reference/EXAMPLES.md) - worked examples.
 - [Test environment](reference/test-environment.md) - test harness notes.
 - [Agent permissions](reference/agent-permissions.md) - agent permission model.

package/docs/guides/BEADS_GITHUB_SYNC.md

@@ -1,32 +1,3 @@
-# Beads/GitHub Sync Deprecation
+# Beads/GitHub Sync (Retired)
 
-Beads/GitHub workflow sync is deprecated. Forge no longer ships active `github-to-beads.yml` or `beads-to-github.yml` workflow templates, and `forge setup --sync` must not create new Beads/GitHub sync scaffolding.
-
-## Current Behavior
-
-- `.beads/` is local runtime/export state and is not committed.
-- `forge setup --sync` is retained only as a compatibility cleanup path and removes old generated Beads/GitHub sync files from existing installs when they are present.
-- Plain `forge setup` does not perform Beads/GitHub sync cleanup as a side effect.
-- `forge sync` may still run local Beads/Dolt sync operations while Beads compatibility remains, but it is not GitHub issue lifecycle sync.
-
-## Removed Generated Files
-
-The `forge setup --sync` compatibility cleanup removes the old generated files:
-
-```text
-.github/workflows/github-to-beads.yml
-.github/workflows/beads-to-github.yml
-.github/beads-mapping.json
-.github/beads-sync-config.json
-.github/scripts/beads-sync/*.mjs
-scripts/github-beads-sync.config.json
-scripts/github-beads-sync/*.mjs
-```
-
-Unrelated GitHub workflows are preserved.
-
-## Replacement Direction
-
-Future GitHub issue sync must use Forge Kernel/server authority. Local-only work is durable in local Kernel SQLite. Team or cross-machine issue state is serialized through server authority, then GitHub issues can be updated as a projection from that authority.
-
-Do not commit live `.beads/` files, create metadata-only PRs, or bypass protected branches to update issue tracker state.
+**Historical.** Beads/GitHub workflow sync was retired with **D45** — Beads is no longer a live Forge feature, so there is nothing left to keep in sync. Forge ships no `github-to-beads.yml` or `beads-to-github.yml` templates and never scaffolds new sync files. Bringing an existing Beads store into Forge is a one-time import, `forge migrate --from beads`; after that the Forge Kernel is the sole issue-state authority, and GitHub issue updates are a server-side projection from that authority (see [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](../work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md)). Installs that still carry old generated sync files are cleaned automatically: the `forge setup` compatibility cleanup removes the old generated files, with no flag required.

package/docs/guides/MIGRATION.md

@@ -1,6 +1,6 @@
 # Migration Guide
 
-Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.0.11 public framing.
+Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.1.0-beta.5 public framing.
 
 ## What Changed
 
@@ -26,7 +26,7 @@ Use both entry points correctly:
 
 - `forge init` creates the `.forge/` adoption skeleton.
 - `forge setup` installs agent instructions, skills, harness files, local Beads compatibility, and optional setup material.
-- `forge setup --sync` is deprecated and retained only to remove old generated Beads/GitHub sync scaffolding when present.
+- `forge setup` also removes old generated Beads/GitHub sync scaffolding when present, with no flag needed.
 
 ## From Singular Agent Flags
 
@@ -39,8 +39,8 @@ forge setup --agents claude,cursor
 
 ## Version Labels
 
-- `0.0.11` is the package version for this public docs/readiness release.
-- `0.0.10` is the previous published package version.
+- `0.1.0-beta.5` is the current prerelease package version.
+- `0.1.0-beta.4` is the previous prerelease package version.
 - Internal labels such as `0.0.19` or `v3` describe roadmap slices or historical codenames. Do not present them as current package versions.
 
 ## Safe Upgrade Path