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

package/lib/commands/setup.js

@@ -13,7 +13,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
-const { execSync } = require('node:child_process');
+const { execFileSync, execSync } = require('node:child_process');
 
 // Compute packageDir relative to this file (lib/commands/setup.js -> project root).
 // packageDir stays a runtime value for asset copying; requires use static
@@ -28,6 +28,7 @@ const VERSION = packageJson.version;
 // packaged-ASSET read below goes through `getPackageRoot(packageDir)`; the
 // module-`require` paths above keep `packageDir` (bundler handles those).
 const { getPackageRoot } = require('../package-root');
+const { cleanupDeprecatedSyncFiles } = require('../deprecated-sync-cleanup');
 
 // Load PluginManager for discoverable agent architecture
 const PluginManager = require('../plugin-manager');
@@ -53,9 +54,8 @@ const { askYesNo: _askYesNoBase } = require('../ui-utils');
 const contextMerge = require('../context-merge');
 const projectDiscovery = require('../project-discovery');
 
-// Load lib modules for symlink, beads, and PAT setup
+// Load lib modules for symlink setup
 const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require('../symlink-utils');
-const { scaffoldBeadsSync } = require('../beads-sync-scaffold');
 const { resolveSyncBackend } = require('../sync-backend');
 const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
 
@@ -69,11 +69,13 @@ const { smartMergeAgentsMd } = require('../smart-merge');
 const { checkLefthookStatus } = require('../lefthook-check');
 const {
   FORGE_USER_LEFTHOOK_YML,
+  FORGE_USER_LEFTHOOK_YML_NO_TDD,
   forgeShouldWriteLefthookConfig,
   installNativeGitHooks,
   verifyHooksActive,
   resolveGitHooksDir,
 } = require('../lefthook-wiring');
+const { detectExistingTddGate, describeExistingGateDeferral } = require('../existing-tdd-gate');
 const { resolveShellRuntime } = require('../runtime-health');
 const {
   buildCodexSkillInstallPlan,
@@ -89,6 +91,10 @@ const initCommand = require('./init');
 const fileUtils = require('../file-utils');
 const detectionUtils = require('../detection-utils');
 const { detectHusky, migrateHusky } = require('../husky-migration');
+const {
+  issueGeneratedHarnessClaudeAuthorization,
+  completeGeneratedHarnessClaudeAuthorization,
+} = require('../protected-state-authority');
 
 // --- Module-level state (deferred from ForgeContext migration) ---
 // Follow-up tracked in forge-vi7v: migrate setup state to a ForgeContext instance passed via handler args.
@@ -99,7 +105,6 @@ let FORCE_MODE = false;
 let VERBOSE_MODE = false;
 let NON_INTERACTIVE = false;
 let SYMLINK_ONLY = false;
-let SYNC_ENABLED = false;
 let actionLog = new SetupActionLog();
 let PKG_MANAGER = 'npm';
 let SETUP_NOTES = [];
@@ -162,6 +167,92 @@ function safeExec(cmd, opts = {}) {
   }
 }
 
+/**
+ * Resolve the current source revision without passing Git arguments through a shell.
+ * @param {string} cwd - Repository working directory
+ * @param {Function} commandRunner - execFileSync-compatible runner for tests
+ * @returns {string} Full source HEAD, or empty when Git cannot resolve it
+ */
+function resolveCurrentSourceHead(cwd = projectRoot, commandRunner = execFileSync) {
+  try {
+    return commandRunner('git', ['rev-parse', '--verify', 'HEAD^{commit}'], {
+      cwd,
+      stdio: 'pipe',
+    }).toString().trim();
+  } catch (_e) { // NOSONAR — fail closed when the source revision is unavailable
+    return '';
+  }
+}
+
+/**
+ * Normalize Git's Windows checkout line endings before authorizing the exact
+ * root CLAUDE.md pointer bytes.
+ * @param {Buffer|string} content - Existing CLAUDE.md bytes
+ * @returns {Buffer} LF-normalized content
+ */
+function normalizeClaudePointerContent(content) {
+  return Buffer.from(String(content || '').replace(/\r\n/g, '\n'));
+}
+
+function readCleanClaudePointerWorktreeContent(cwd, commandRunner) {
+	const tempIndexDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-claude-index-'));
+	const tempIndex = path.join(tempIndexDir, 'index');
+	const env = { ...process.env, GIT_INDEX_FILE: tempIndex };
+	try {
+		commandRunner('git', ['read-tree', 'HEAD'], {
+			cwd,
+			env,
+			stdio: 'pipe',
+		});
+		commandRunner('git', ['add', '--', 'CLAUDE.md'], {
+			cwd,
+			env,
+			stdio: 'pipe',
+		});
+		return commandRunner('git', ['show', ':CLAUDE.md'], {
+			cwd,
+			env,
+			encoding: null,
+			stdio: 'pipe',
+		});
+	} finally {
+		fs.rmSync(tempIndexDir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Read the exact staged CLAUDE.md bytes that the protected-state hook will hash.
+ * @param {string} cwd - Repository working directory
+ * @param {Function} commandRunner - execFileSync-compatible runner for tests
+ * @returns {Buffer} Staged bytes, or the worktree bytes when the file is untracked
+ */
+function readStagedClaudePointerContent(cwd = projectRoot, commandRunner = execFileSync) {
+	try {
+		const stagedContent = commandRunner('git', ['show', ':CLAUDE.md'], {
+			cwd,
+			encoding: null,
+			stdio: 'pipe',
+		});
+		try {
+			return readCleanClaudePointerWorktreeContent(cwd, commandRunner);
+		} catch (_worktreeError) {
+			return stagedContent;
+		}
+	} catch (showError) {
+		try {
+			commandRunner('git', ['ls-files', '--error-unmatch', '--', 'CLAUDE.md'], {
+				cwd,
+				encoding: 'utf8',
+				stdio: 'pipe',
+			});
+			throw showError;
+		} catch (trackedError) {
+			if (trackedError?.status !== 1) throw showError;
+		}
+		return readCleanClaudePointerWorktreeContent(cwd, commandRunner);
+	}
+}
+
 /**
  * Detect package manager
  */
@@ -174,7 +265,6 @@ function detectPackageManager() {
 
 
 const WORKFLOW_RUNTIME_ASSETS = Object.freeze([
-  'scripts/beads-context.sh',
   'scripts/conflict-detect.sh',
   'scripts/dep-guard-analyze.js',
   'scripts/dep-guard.sh',
@@ -218,7 +308,6 @@ function validateAgents(agentList) {
 // Prerequisite check function
 function checkPrerequisites(options = {}) {
   const requireGithubCli = options.requireGithubCli !== false;
-  const requireBeadsCli = options.requireBeadsCli === true;
   const requireJq = options.requireJq === true;
   const commandRunner = options.commandRunner || safeExec;
   const errors = [];
@@ -255,15 +344,13 @@ function checkPrerequisites(options = {}) {
     }
   }
 
-  if (requireBeadsCli) {
-    // Issue tracking runs on the local Forge Kernel store, which auto-provisions
-    // on first use — there is no external CLI to install. Surface only whether
-    // team sync is wired up yet.
-    if (resolveSyncBackend({ projectRoot, env: options.env }) === 'local-noop') {
-      console.log('  ✓ Kernel issue store (local-noop sync: single-machine until a sync server is configured)');
-    } else {
-      console.log('  ✓ Kernel issue store');
-    }
+  // Issue tracking runs on the local Forge Kernel store, which auto-provisions
+  // on first use — there is no external CLI to install. Surface only whether
+  // team sync is wired up yet.
+  if (resolveSyncBackend({ projectRoot, env: options.env }) === 'local-noop') {
+    console.log('  ✓ Kernel issue store (local-noop sync: single-machine until a sync server is configured)');
+  } else {
+    console.log('  ✓ Kernel issue store');
   }
 
   // Check Node.js version
@@ -800,9 +887,7 @@ async function detectProjectStatus() {
     claudeMdLines: 0,
     // Project tools status — the Kernel issue store is always present (it
     // auto-provisions on first use), so issue tracking needs no install probe.
-    hasBeads: true,
     hasSkills: isSkillsInitialized(),
-    beadsInstallType: 'kernel',
     skillsInstallType: checkForSkills(),
     // Enhanced: Auto-detected project context
     autoDetected: null
@@ -1654,6 +1739,13 @@ function ensureDirWithNote(dir, purpose) { // eslint-disable-line no-unused-vars
 
 // Setup core documentation and directories
 function setupCoreDocs() {
+  // Review skills reference this root contract in every installed repository.
+  // It is a consumer-owned extension point after creation, so setup never overwrites it.
+  const codingStandardsDest = path.join(projectRoot, 'CODING_STANDARDS.md');
+  if (!fs.existsSync(codingStandardsDest)) {
+    copyFile(path.join(getPackageRoot(packageDir), 'CODING_STANDARDS.md'), 'CODING_STANDARDS.md');
+  }
+
   // docs/planning/ and docs/research/ are created lazily on first use
   // by /plan Phase 1 and Phase 2 respectively, via ensureDirWithNote().
   // TEMPLATE.md and PROGRESS.md are also deferred to first use.
@@ -2058,12 +2150,40 @@ function setupCursorHooksConfig() {
 
 // Helper: Create agent link file
 // When symlinkOnly is true (--symlink flag), skip copy fallback
-function createAgentLinkFile(agent, symlinkOnly = false) {
+async function createAgentLinkFile(agent, symlinkOnly = false) {
   if (!shouldLinkAgentsMd(agent)) return;
 
   const result = createSymlinkOrCopy('AGENTS.md', agent.linkFile, { symlinkOnly });
   if (result) {
-    console.log(`  ${result === 'linked' ? 'Linked' : 'Copied'}: ${agent.linkFile}`);
+    const action = result === 'linked' ? 'Linked' : result === 'copied' ? 'Copied' : 'Preserved import';
+    console.log(`  ${action}: ${agent.linkFile}`);
+  }
+  if (agent.linkFile !== 'CLAUDE.md' || result !== 'existing-import') return;
+
+  try {
+    const sourceHead = resolveCurrentSourceHead();
+    const content = readStagedClaudePointerContent();
+    const actor = process.env.FORGE_PROTECTED_STATE_ACTOR || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'unknown';
+    const authorization = await issueGeneratedHarnessClaudeAuthorization(projectRoot, {
+      actor,
+      content,
+      sourceHead,
+    });
+    if (!authorization.success) {
+      console.warn(`  Warning: Could not authorize existing CLAUDE.md import: ${authorization.error}`);
+      return;
+    }
+    const completion = await completeGeneratedHarnessClaudeAuthorization(projectRoot, {
+      actor,
+      capabilityId: authorization.capabilityId,
+      content,
+      sourceHead,
+    });
+    if (!completion.success) {
+      console.warn(`  Warning: Could not complete CLAUDE.md import authorization: ${completion.error}`);
+    }
+  } catch (error) {
+    console.warn(`  Warning: Could not record CLAUDE.md import authorization: ${error.message}`);
   }
 }
 
@@ -2071,7 +2191,7 @@ function createAgentLinkFile(agent, symlinkOnly = false) {
 
 
 // Setup specific agent
-async function setupAgent(agentKey, skipFiles = {}) {
+async function setupAgent(agentKey, skipFiles = {}, options = {}) {
   const agent = AGENTS[agentKey];
   if (!agent) return;
 
@@ -2111,15 +2231,17 @@ async function setupAgent(agentKey, skipFiles = {}) {
   // Projects Forge's TDD-gate + protected-path enforcement onto each harness's
   // native hook surface. Codex hooks are GLOBAL-config scope and intentionally
   // not written at project setup (see lib/hook-renderer.js).
-  if (agentKey === 'claude') {
-    setupClaudeHooksConfig();
-  }
-  if (agent.customSetup === 'cursor') {
-    setupCursorHooksConfig();
+  if (!options.skillsOnly) {
+    if (agentKey === 'claude') {
+      setupClaudeHooksConfig();
+    }
+    if (agent.customSetup === 'cursor') {
+      setupCursorHooksConfig();
+    }
   }
 
   // Create link file (SYMLINK_ONLY = --symlink flag disables copy fallback)
-  createAgentLinkFile(agent, SYMLINK_ONLY);
+  await createAgentLinkFile(agent, SYMLINK_ONLY);
 }
 
 
@@ -2756,6 +2878,48 @@ function resolveHookEnforcementState(root = projectRoot) {
   }
 }
 
+// True when .forge/config.yaml already states a rail.tdd_intent choice EXPLICITLY (either
+// config shape the resolver accepts). Setup must never overwrite that: otherwise the
+// `forge gate enable rail.tdd_intent` we advertise would be undone by the next `forge setup`.
+function hasExplicitTddRailChoice(root) {
+  try {
+    const { loadRawConfig } = require('../config-writer');
+    const config = loadRawConfig(root) || {};
+    const viaGates = config.workflow && config.workflow.gates && config.workflow.gates['rail.tdd_intent'];
+    const viaRails = config.rails && config.rails['rail.tdd_intent'];
+    return Boolean(
+      (viaGates && viaGates.enabled !== undefined) || (viaRails && viaRails.enabled !== undefined)
+    );
+  } catch {
+    return false; // unreadable config → treat as unset; setConfigOverride reports any real failure
+  }
+}
+
+/**
+ * Defer Forge's TDD gate to a pre-existing one: turn `rail.tdd_intent` off in
+ * .forge/config.yaml so the installed hook scripts are genuinely inert, instead of stacking a
+ * second gate on the same commit (kernel 5b425a85 / 2699b234). No-op when nothing was detected
+ * (a repo with no gate keeps the default-ON rail) or when the user already chose explicitly.
+ *
+ * @returns {{ deferred: boolean, reason?: string }}
+ */
+function applyExistingGateDeferral(root, detection) {
+  if (!detection || !detection.found) return { deferred: false, reason: 'no-existing-gate' };
+  if (hasExplicitTddRailChoice(root)) return { deferred: false, reason: 'explicit-user-choice' };
+
+  const { setConfigOverride } = require('../config-writer');
+  try {
+    setConfigOverride(root, ['workflow', 'gates', 'rail.tdd_intent', 'enabled'], false);
+  } catch (error) {
+    // An unreadable/malformed .forge/config.yaml must not make `forge setup` fail outright
+    // just because a pre-existing gate was detected. Report and DON'T defer: the caller keys
+    // hook wiring off `deferred`, so falling back to the normal install keeps config and
+    // wiring agreeing, instead of turning the gate off in neither place or in only one.
+    return { deferred: false, reason: 'config-write-failed', error: error.message };
+  }
+  return { deferred: true };
+}
+
 function describeHookEnforcement(root = projectRoot) {
   const state = resolveHookEnforcementState(root);
   if (!state.resolved) {
@@ -2837,6 +3001,32 @@ function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin
   // init deliberately degrades to a warning rather than failing, and repair runs inside
   // another command's flow.
   const loud = options.loud === true;
+
+  // BEFORE wiring anything: does this repo already enforce TDD/source-test coupling on
+  // pre-commit? If so, defer to it rather than silently stacking a second gate on the same
+  // commit — the in-the-wild beta.3 report (kernel 5b425a85 / 2699b234). The deferral is
+  // VISIBLE (report below) and reversible with one command.
+  const existingGate = detectExistingTddGate(projectRoot);
+  const deferral = applyExistingGateDeferral(projectRoot, existingGate);
+  // Only claim a deferral when one actually happened. describeExistingGateDeferral() states
+  // that Forge did NOT install its gate and that rail.tdd_intent is off — both false when we
+  // declined to defer, so printing it unconditionally would misreport the installed state.
+  if (deferral.deferred) {
+    console.warn(describeExistingGateDeferral(existingGate));
+    addSetupNote(`Deferred Forge's TDD gate to the existing pre-commit gate in ${existingGate.source}.`);
+  } else if (existingGate.found) {
+    const why = deferral.reason === 'explicit-user-choice'
+      ? 'rail.tdd_intent is set explicitly in .forge/config.yaml, so your choice stands'
+      : `Forge could not update .forge/config.yaml (${deferral.error})`;
+    console.warn(
+      `  ⚠ Detected an existing pre-commit TDD/coupling gate in ${existingGate.source}, but did NOT defer to it:\n` +
+      `    ${why}.\n` +
+      '    Forge\'s own TDD gate is installed as usual, so BOTH gates run on the same commit.\n' +
+      '    Want only yours? Run: forge gate disable rail.tdd_intent'
+    );
+    addSetupNote(`Existing pre-commit gate in ${existingGate.source} detected; Forge's TDD gate installed anyway (${deferral.reason}).`);
+  }
+
   // Honest header: when the TDD gate is disabled in config the hooks install but are inert,
   // so don't announce "(TDD enforcement)" for a state the user turned off (issue eda6d866).
   console.log(
@@ -2876,7 +3066,18 @@ function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin
     // clobber a config that already has active jobs (kernel c713fce7).
     const lefthookTarget = path.join(projectRoot, 'lefthook.yml');
     if (forgeShouldWriteLefthookConfig(lefthookTarget)) {
-      fs.writeFileSync(lefthookTarget, FORGE_USER_LEFTHOOK_YML, 'utf8');
+      // When we actually DEFERRED, write the variant WITHOUT Forge's forge-tdd job so the
+      // commit is never blocked by two gates. Key this off `deferral.deferred`, not off
+      // `existingGate.found`: applyExistingGateDeferral declines to defer when the user has
+      // an explicit rail.tdd_intent choice, and suppressing the wiring anyway would leave
+      // config saying "enabled" while the hook was never installed — making
+      // `forge gate enable rail.tdd_intent` silently ineffective in exactly the repos this
+      // feature targets.
+      fs.writeFileSync(
+        lefthookTarget,
+        deferral.deferred ? FORGE_USER_LEFTHOOK_YML_NO_TDD : FORGE_USER_LEFTHOOK_YML,
+        'utf8'
+      );
       actionLog.add('lefthook.yml', 'created');
       console.log('  ✓ Created lefthook.yml');
     }
@@ -2924,7 +3125,12 @@ function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin
   // inert (B3). This repair path only warns (never sets a failure exit code) since it can
   // run mid-stage under enforce-stage's repairWorkflowRuntimeAssets().
   if (!lefthookInstalled) {
-    const native = installNativeGitHooks(projectRoot);
+    // Skip the native pre-commit hook when the repo already has its own TDD/coupling gate —
+    // pre-push is still wired, so only the double-gated surface is given up.
+    const native = installNativeGitHooks(
+      projectRoot,
+      existingGate.found ? { skipHooks: ['pre-commit'] } : {}
+    );
     if (native.installed) {
       console.log(`  ✓ Native git hooks installed (${native.written.join(', ')}) - lefthook fallback`);
     } else if (native.skipped && native.skipped.length > 0) {
@@ -3093,7 +3299,7 @@ function initializeSkills(installType) {
 
 // Ensure the issue store during interactive setup. No prompt: the Forge Kernel
 // ships with Forge and auto-provisions, so there is nothing to install or pick.
-async function promptBeadsSetup(_question) {
+async function promptIssueStoreSetup(_question) {
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('Issue Store (Forge Kernel)');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -3219,17 +3425,14 @@ async function promptSkillsSetup(question) {
   console.log('');
 }
 
-// Interactive setup for Beads and Skills
-
-
-// Interactive setup for Beads and Skills
+// Interactive setup for the issue store and 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('Forge recommends these tools for enhanced workflows:');
   console.log('');
   console.log('• Issue tracking (Forge Kernel) - zero-install, git-backed');
   console.log('  Persists tasks across sessions, tracks dependencies.');
@@ -3241,7 +3444,7 @@ async function setupProjectTools(rl, question) {
   console.log('');
 
   // Use helper functions to reduce complexity
-  await promptBeadsSetup(question);
+  await promptIssueStoreSetup(question);
   await promptSkillsSetup(question);
 }
 
@@ -3395,7 +3598,8 @@ async function ensureGitHooksInstalled(targetRoot = projectRoot) {
 
 
 // Quick setup with defaults
-async function quickSetup(selectedAgents, skipExternal) {
+async function quickSetup(selectedAgents, skipExternal, options = {}) {
+  const skillsOnly = options.skillsOnly === true;
   showBanner('Quick Setup');
   console.log('');
   console.log('Quick mode: Using defaults...');
@@ -3403,7 +3607,6 @@ async function quickSetup(selectedAgents, skipExternal) {
 
   // Check prerequisites
   checkPrerequisites({
-    requireBeadsCli: true,
     requireGithubCli: true,
     requireJq: true,
   });
@@ -3423,41 +3626,46 @@ async function quickSetup(selectedAgents, skipExternal) {
 
   ensureWorkflowShellPolicy(selectedAgents);
 
-  // Auto-install lefthook if missing
-  autoInstallLefthook();
+  // Auto-install lefthook if missing unless the caller explicitly requested skills only.
+  if (!skillsOnly) {
+    autoInstallLefthook();
+  }
 
   // Auto-setup project tools (Kernel issue store, Skills)
   await autoSetupToolsInQuickMode();
 
   // Setup Claude first if selected, then setup remaining agents
   if (selectedAgents.includes('claude')) {
-    await setupAgent('claude');
+    await setupAgent('claude', {}, { skillsOnly });
   }
-  await setupSelectedAgents(selectedAgents);
+  await setupSelectedAgents(selectedAgents, undefined, { skillsOnly });
   ensureWorkflowRuntimeAssets(selectedAgents);
 
   // Detect Husky and migrate before installing Lefthook hooks
-  await handleHuskyMigration();
+  if (!skillsOnly) {
+    await handleHuskyMigration();
+  }
 
   // Install git hooks for TDD enforcement. LOUD: this is the `forge setup` handler,
   // so an inert-hooks result must fail non-zero (B3), not end green.
   console.log('');
-  installGitHooks({ loud: true });
+  if (skillsOnly) {
+    console.log('Skipping git and harness hooks (--skills-only).');
+  } else {
+    installGitHooks({ loud: true });
+  }
 
   // Configure external services with defaults (unless skipped)
   configureDefaultExternalServices(skipExternal);
 
-  // --sync flag: scaffold Beads GitHub sync workflows without prompting
-  if (SYNC_ENABLED) {
-    await handleSyncScaffold();
-  }
+  removeDeprecatedSyncFiles();
 
   // Progressive setup summary
   console.log('');
   console.log(renderSetupSummary(actionLog, selectedAgents, VERBOSE_MODE, { status: getSetupSummaryStatus() }));
   printSetupNotes();
   // One-step onboarding: run `forge init` when config is still absent (ac0b38c7).
-  // Hooks + Beads already handled above, so init skips those side effects.
+  // Hooks + issue store already handled above, so init skips those side effects.
   await finalizeWorkflowConfig({ hooksAlreadyInstalled: true });
   console.log('');
 }
@@ -3617,13 +3825,13 @@ async function promptForOverwriteDecisions(question, projectStatus, flags = {})
 
 
 // Helper: Setup all selected agents - extracted to reduce cognitive complexity
-async function setupSelectedAgents(selectedAgents, skipFiles) {
+async function setupSelectedAgents(selectedAgents, skipFiles, options = {}) {
   const totalAgents = selectedAgents.length;
   for (const [index, agentKey] of selectedAgents.entries()) {
     const agent = AGENTS[agentKey];
     console.log(`\n[${index + 1}/${totalAgents}] Setting up ${agent.name}...`);
     if (agentKey !== 'claude') { // Claude already done above
-      await setupAgent(agentKey, skipFiles);
+      await setupAgent(agentKey, skipFiles, options);
     }
   }
 
@@ -3691,7 +3899,6 @@ async function interactiveSetupWithFlags(flags) {
 
   // Check agent-independent prerequisites first
   checkPrerequisites({
-    requireBeadsCli: true,
     requireGithubCli: false,
     requireJq: true,
   });
@@ -3740,11 +3947,11 @@ async function interactiveSetupWithFlags(flags) {
 
   // Setup Claude first if selected (delegated to helper), then remaining agents
   if (selectedAgents.includes('claude')) {
-    await setupAgent('claude', skipFiles);
+    await setupAgent('claude', skipFiles, flags);
   }
 
   // Setup each selected agent with progress indication (delegated to helper)
-  await setupSelectedAgents(selectedAgents, skipFiles);
+  await setupSelectedAgents(selectedAgents, skipFiles, flags);
   ensureWorkflowRuntimeAssets(selectedAgents);
 
   // Handle external services step (delegated to helper)
@@ -3758,7 +3965,7 @@ async function interactiveSetupWithFlags(flags) {
 
   // One-step onboarding: this path never writes .forge/config.yaml itself, so
   // run `forge init` when the config is still absent (ac0b38c7).
-  await finalizeWorkflowConfig();
+  await finalizeWorkflowConfig({ hooksAlreadyInstalled: flags.skillsOnly === true });
 }
 
 // Main
@@ -3831,7 +4038,7 @@ function determineSelectedAgents(flags) {
 // Shared setup executor — used by handleSetupCommand
 
 // Dry-run setup — enumerate planned actions without writing files
-function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
+function dryRunSetup(agents, options = {}) { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
   const collector = new ActionCollector();
 
   // Helper: add create or skip based on whether file exists
@@ -3844,8 +4051,9 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
     }
   }
 
-  // AGENTS.md
+  // Root policy files
   addFileAction('AGENTS.md', 'Copy workflow documentation');
+  addFileAction('CODING_STANDARDS.md', 'Install Forge coding standards');
 
   // Per-agent planned actions
   for (const agentKey of agents) {
@@ -3901,10 +4109,12 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
     }
   }
 
-  // Git hooks
-  addFileAction('lefthook.yml', 'Git hook configuration');
-  addFileAction('.forge/hooks/check-tdd.js', 'TDD enforcement hook');
-  addFileAction('.forge/hooks/forge-native-hook.js', 'Native-hook enforcement adapter (Claude/Cursor)');
+  // Git and harness hooks are opt-out for skills-only setup.
+  if (options.skillsOnly !== true) {
+    addFileAction('lefthook.yml', 'Git hook configuration');
+    addFileAction('.forge/hooks/check-tdd.js', 'TDD enforcement hook');
+    addFileAction('.forge/hooks/forge-native-hook.js', 'Native-hook enforcement adapter (Claude/Cursor)');
+  }
 
   // Print dry-run summary
   console.log('');
@@ -3919,14 +4129,19 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
 
 
 async function executeSetup(config) {
-  const { agents, skipExternal, keepExisting = false, commandRunner } = config;
+  const {
+    agents,
+    skipExternal,
+    keepExisting = false,
+    commandRunner,
+    skillsOnly = false,
+  } = config;
 
   showBanner('Installing for specified agents...');
   console.log('');
 
   // Check prerequisites
   checkPrerequisites({
-    requireBeadsCli: true,
     requireGithubCli: requiresGithubCliForSetup(agents),
     requireJq: true,
     commandRunner,
@@ -3953,60 +4168,62 @@ async function executeSetup(config) {
 
   // Setup Claude first if selected, then remaining agents
   if (agents.includes('claude')) {
-    await setupAgent('claude', skipFiles);
+    await setupAgent('claude', skipFiles, { skillsOnly });
   }
-  await setupSelectedAgents(agents, skipFiles);
+  await setupSelectedAgents(agents, skipFiles, { skillsOnly });
   ensureWorkflowRuntimeAssets(agents);
   ensureWorkflowShellPolicy(agents);
-  repairDeclaredLefthookDependency(agents);
+  if (!skillsOnly) {
+    repairDeclaredLefthookDependency(agents);
+  }
 
   // Detect Husky and migrate before installing Lefthook hooks
-  await handleHuskyMigration();
+  if (!skillsOnly) {
+    await handleHuskyMigration();
+  }
 
   // Install git hooks for TDD enforcement. LOUD: this is the `forge setup` handler,
   // so an inert-hooks result must fail non-zero (B3), not end green.
   console.log('');
-  installGitHooks({ loud: true });
+  if (skillsOnly) {
+    console.log('Skipping git and harness hooks (--skills-only).');
+  } else {
+    installGitHooks({ loud: true });
+  }
 
   // External services (unless skipped)
   await handleExternalServices(skipExternal, agents);
 
-  // --sync flag: scaffold Beads GitHub sync workflows without prompting
-  if (SYNC_ENABLED) {
-    await handleSyncScaffold();
-  }
+  removeDeprecatedSyncFiles();
 
   // Progressive setup summary
   console.log('');
   console.log(renderSetupSummary(actionLog, agents, VERBOSE_MODE, { status: getSetupSummaryStatus() }));
   printSetupNotes();
   // One-step onboarding: run `forge init` when config is still absent (ac0b38c7).
-  // Hooks + Beads already handled above, so init skips those side effects.
+  // Hooks + issue store already handled above, so init skips those side effects.
   await finalizeWorkflowConfig({ hooksAlreadyInstalled: true });
   console.log('');
 }
 
-// Helper: Scaffold Beads GitHub sync when --sync flag is provided
-
-
-// Helper: Scaffold Beads GitHub sync when --sync flag is provided
-async function handleSyncScaffold() {
-  console.log('');
-  console.log('Beads GitHub sync scaffolding is deprecated (--sync).');
+/**
+ * Remove generated Beads/GitHub sync files left behind by older installs.
+ *
+ * Runs on every setup — there is no longer a flag for it. Only files whose
+ * content matches a known generated template are removed, so user-owned files
+ * at the same paths are preserved.
+ */
+function removeDeprecatedSyncFiles() {
   try {
-    const result = scaffoldBeadsSync(projectRoot, getPackageRoot(packageDir));
-    console.log(`  ${result.message}`);
-    for (const f of result.filesRemoved || []) {
-      console.log(`  Removed deprecated sync file: ${f}`);
+    const result = cleanupDeprecatedSyncFiles(projectRoot, { packageDir: getPackageRoot(packageDir) });
+    for (const file of result.removed || []) {
+      console.log(`  Removed deprecated sync file: ${file}`);
     }
   } catch (err) {
-    console.error(`  Error scaffolding GitHub-Beads sync: ${err.message}`);
+    console.error(`  Error removing deprecated sync files: ${err.message}`);
   }
 }
 
-// Helper: Handle setup command in non-quick mode
-
-
 // Helper: Handle setup command in non-quick mode
 async function handleSetupCommand(selectedAgents, flags) {
   if (!Array.isArray(selectedAgents) || selectedAgents.length === 0) {
@@ -4024,6 +4241,7 @@ async function handleSetupCommand(selectedAgents, flags) {
       skipExternal: flags.skipExternal,
       keepExisting: flags.keep,
       commandRunner: flags.commandRunner,
+      skillsOnly: flags.skillsOnly,
     });
   } finally {
     projectRoot = savedRoot;
@@ -4168,6 +4386,7 @@ const SETUP_FLAG_DEFAULTS = Object.freeze({
   sync: false,
   symlink: false,
   nonInteractive: false,
+  skillsOnly: false,
 });
 
 const SIMPLE_SETUP_FLAG_UPDATES = Object.freeze({
@@ -4186,6 +4405,8 @@ const SIMPLE_SETUP_FLAG_UPDATES = Object.freeze({
   '--symlink': { symlink: true },
   '--yes': { yes: true, nonInteractive: true },
   '-y': { yes: true, nonInteractive: true },
+  '--skills-only': { skillsOnly: true },
+  '--no-hooks': { skillsOnly: true },
 });
 
 function parseAgentFlag(argv, currentIndex, isFlagToken) {
@@ -4262,9 +4483,9 @@ function mergeSetupFlags(flags, argv) {
     standard: Boolean(flags.standard || setupFlags.standard),
     full: Boolean(flags.full || setupFlags.full),
     skipExternal: Boolean(flags.skipExternal || setupFlags.skipExternal),
-    sync: Boolean(flags.sync || setupFlags.sync),
     symlink: Boolean(flags.symlink || setupFlags.symlink),
     nonInteractive: Boolean(flags.nonInteractive || setupFlags.nonInteractive),
+    skillsOnly: Boolean(flags.skillsOnly || setupFlags.skillsOnly),
   };
 }
 
@@ -4309,7 +4530,6 @@ module.exports = {
     if (flags.verbose) VERBOSE_MODE = true;
     if (flags.nonInteractive || flags.yes) NON_INTERACTIVE = true;
     if (flags.symlink) SYMLINK_ONLY = true;
-    if (flags.sync) SYNC_ENABLED = true;
     actionLog = new SetupActionLog();
     resetSetupNotes();
     PKG_MANAGER = detectPackageManager();
@@ -4327,6 +4547,12 @@ module.exports = {
       }
 
       const [profile] = selectedProfiles;
+      if (flags.skillsOnly) {
+        return {
+          success: false,
+          error: `--skills-only cannot be combined with --${profile}.`,
+        };
+      }
       return initCommand.handler([`--profile=${profile}`, '--yes', ...(flags.force ? ['--force'] : [])], flags, projectRoot);
     }
 
@@ -4351,7 +4577,7 @@ module.exports = {
 
     if (flags.dryRun) {
       if (selectedAgents.length === 0) selectedAgents = ['claude'];
-      dryRunSetup(selectedAgents);
+      dryRunSetup(selectedAgents, { skillsOnly: flags.skillsOnly });
       return { success: true };
     }
 
@@ -4360,12 +4586,7 @@ module.exports = {
       if (selectedAgents.length === 0 || (flags.yes && !flags.agents)) {
         selectedAgents = Object.keys(AGENTS);
       }
-      await quickSetup(selectedAgents, flags.skipExternal);
-      return { success: true };
-    }
-
-    if (flags.sync && selectedAgents.length === 0) {
-      await handleSyncScaffold();
+      await quickSetup(selectedAgents, flags.skipExternal, { skillsOnly: flags.skillsOnly });
       return { success: true };
     }
 
@@ -4406,6 +4627,8 @@ module.exports = {
   ensureGitHooksInstalled,
   forgeShouldWriteLefthookConfig,
   FORGE_USER_LEFTHOOK_YML,
+  applyExistingGateDeferral,
+  installGitHooks,
   setupClaudeMcpConfig,
   setupCursorMcpConfig,
   setupClaudePermissions,
@@ -4428,16 +4651,18 @@ module.exports = {
   repairRuntimeReadiness,
   _showBanner: showBanner,
   backupAndRemoveLegacyCursorRules,
+  resolveCurrentSourceHead,
+  normalizeClaudePointerContent,
+  readStagedClaudePointerContent,
 
   // State accessors for testing
-  _getState: () => ({ projectRoot, FORCE_MODE, VERBOSE_MODE, NON_INTERACTIVE, SYMLINK_ONLY, SYNC_ENABLED, PKG_MANAGER }),
+  _getState: () => ({ projectRoot, FORCE_MODE, VERBOSE_MODE, NON_INTERACTIVE, SYMLINK_ONLY, PKG_MANAGER }),
   _setState: (state) => {
     if (state.projectRoot !== undefined) projectRoot = state.projectRoot;
     if (state.FORCE_MODE !== undefined) FORCE_MODE = state.FORCE_MODE;
     if (state.VERBOSE_MODE !== undefined) VERBOSE_MODE = state.VERBOSE_MODE;
     if (state.NON_INTERACTIVE !== undefined) NON_INTERACTIVE = state.NON_INTERACTIVE;
     if (state.SYMLINK_ONLY !== undefined) SYMLINK_ONLY = state.SYMLINK_ONLY;
-    if (state.SYNC_ENABLED !== undefined) SYNC_ENABLED = state.SYNC_ENABLED;
     if (state.PKG_MANAGER !== undefined) PKG_MANAGER = state.PKG_MANAGER;
   },
 };