@accelerationguy/accel 1.0.0

package/modules/momentum/bin/install.js

@@ -0,0 +1,563 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+const banner = `
+${cyan}  ███╗   ███╗ ██████╗ ███╗   ███╗███████╗███╗   ██╗████████╗██╗   ██╗███╗   ███╗
+  ████╗ ████║██╔═══██╗████╗ ████║██╔════╝████╗  ██║╚══██╔══╝██║   ██║████╗ ████║
+  ██╔████╔██║██║   ██║██╔████╔██║█████╗  ██╔██╗ ██║   ██║   ██║   ██║██╔████╔██║
+  ██║╚██╔╝██║██║   ██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║   ██║   ██║   ██║██║╚██╔╝██║
+  ██║ ╚═╝ ██║╚██████╔╝██║ ╚═╝ ██║███████╗██║ ╚████║   ██║   ╚██████╔╝██║ ╚═╝ ██║
+  ╚═╝     ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝    ╚═════╝ ╚═╝     ╚═╝${reset}
+
+  Momentum Framework ${dim}v${pkg.version}${reset}
+  Builder's Automated State Engine for Claude Code
+`;
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasWorkspace = args.includes('--workspace') || args.includes('-w');
+
+// Parse --config-dir argument
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    return configDirArg.split('=')[1];
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+
+// Parse --workspace-dir argument
+function parseWorkspaceDirArg() {
+  const idx = args.findIndex(arg => arg === '--workspace-dir');
+  if (idx !== -1) {
+    const nextArg = args[idx + 1];
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--workspace-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  return null;
+}
+const explicitWorkspaceDir = parseWorkspaceDirArg();
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx momentum-framework [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}                 Install commands globally (to ~/.claude)
+    ${cyan}-l, --local${reset}                  Install commands locally (to ./.claude)
+    ${cyan}-w, --workspace${reset}              Install workspace layer (.accel/momentum/ in current directory)
+    ${cyan}-c, --config-dir <path>${reset}      Specify custom Claude config directory
+    ${cyan}--workspace-dir <path>${reset}        Specify workspace root (default: cwd)
+    ${cyan}-h, --help${reset}                   Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Full install: global commands + workspace layer${reset}
+    npx momentum-framework --global --workspace
+
+    ${dim}# Global commands only (no workspace data)${reset}
+    npx momentum-framework --global
+
+    ${dim}# Workspace layer only (assumes commands already installed)${reset}
+    npx momentum-framework --workspace
+
+    ${dim}# Install to current project only${reset}
+    npx momentum-framework --local --workspace
+
+  ${yellow}What gets installed:${reset}
+    ${cyan}Commands (--global or --local):${reset}
+      commands/momentum/       - Slash commands (/momentum:surface-create, etc.)
+      skills/momentum/         - Skill framework (tasks, templates, context)
+
+    ${cyan}Workspace (--workspace):${reset}
+      .accel/momentum/data/          - JSON data surfaces (active, backlog, projects, entities, state)
+      .accel/momentum/hooks/         - All hooks (surface + session + command)
+      .accel/momentum/momentum-mcp/  - Momentum MCP server (npm install auto-runs)
+      .accel/momentum/workspace.json - Workspace manifest
+      .accel/momentum/operator.json  - Operator profile (guided setup via /momentum:scaffold)
+      .mcp.json            - MCP server registration (merged)
+`);
+  process.exit(0);
+}
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * Recursively copy directory
+ */
+function copyDir(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Write JSON file only if it doesn't already exist
+ */
+function writeJsonIfNew(filePath, data) {
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Detect v1/v2 artifacts that need migration.
+ * Returns array of { path, label, type } objects.
+ * Does NOT modify anything — detection only.
+ */
+function detectV1Artifacts(claudeDir, workspaceDir) {
+  const found = [];
+
+  if (workspaceDir) {
+    // vector-mcp in .accel/momentum/ (no longer ships with Momentum)
+    const vectorMcpDir = path.join(workspaceDir, '.accel/momentum', 'vector-mcp');
+    if (fs.existsSync(vectorMcpDir)) {
+      found.push({
+        path: vectorMcpDir,
+        label: '.accel/momentum/vector-mcp/',
+        reason: 'Vector MCP no longer ships with Momentum — install vector-core separately',
+        type: 'directory'
+      });
+    }
+
+    // Session hooks in .claude/hooks/ that moved to .accel/momentum/hooks/
+    const movedHooks = ['momentum-pulse-check.py', 'psmm-injector.py', 'satellite-detection.py'];
+    const claudeHooksDir = path.join(workspaceDir, '.claude', 'hooks');
+    if (fs.existsSync(claudeHooksDir)) {
+      for (const hook of movedHooks) {
+        const hookPath = path.join(claudeHooksDir, hook);
+        if (fs.existsSync(hookPath)) {
+          found.push({
+            path: hookPath,
+            label: `.claude/hooks/${hook}`,
+            reason: 'Hooks now live in .accel/momentum/hooks/ — duplicate here causes double-fire',
+            type: 'file'
+          });
+        }
+      }
+    }
+
+    // v2-suffixed hook files in .accel/momentum/hooks/ (now redundant — canonical names have v2 content)
+    const v2SuffixedHooks = ['active-hook-v2.py', 'backlog-hook-v2.py', 'momentum-pulse-check.py'];
+    const momentumHooksDir = path.join(workspaceDir, '.accel/momentum', 'hooks');
+    if (fs.existsSync(momentumHooksDir)) {
+      for (const hook of v2SuffixedHooks) {
+        const hookPath = path.join(momentumHooksDir, hook);
+        if (fs.existsSync(hookPath)) {
+          found.push({
+            path: hookPath,
+            label: `.accel/momentum/hooks/${hook}`,
+            reason: 'v2-suffixed duplicate — canonical name now has v2 content',
+            type: 'file'
+          });
+        }
+      }
+    }
+
+    // Stale -v2 hook paths in .claude/settings.json
+    const settingsPath = path.join(workspaceDir, '.claude', 'settings.json');
+    if (fs.existsSync(settingsPath)) {
+      try {
+        const raw = fs.readFileSync(settingsPath, 'utf-8');
+        if (raw.includes('-v2.py')) {
+          found.push({
+            path: settingsPath,
+            label: '.claude/settings.json → stale -v2 hook paths',
+            reason: 'Hook paths reference -v2.py files that are now archived — will rewrite to canonical names',
+            type: 'settings-v2-paths'
+          });
+        }
+      } catch (e) { /* skip */ }
+    }
+
+    // vector-mcp entry in .mcp.json
+    const mcpJsonPath = path.join(workspaceDir, '.mcp.json');
+    if (fs.existsSync(mcpJsonPath)) {
+      try {
+        const mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
+        if (mcpConfig.mcpServers && mcpConfig.mcpServers['vector-mcp']) {
+          found.push({
+            path: mcpJsonPath,
+            label: '.mcp.json → vector-mcp entry',
+            reason: 'Vector MCP no longer registered by Momentum — install vector-core for Vector MCP',
+            type: 'mcp-entry'
+          });
+        }
+      } catch (e) { /* skip */ }
+    }
+  }
+
+  // Old markdown templates in momentum-framework/
+  if (claudeDir) {
+    const oldTemplates = ['active-md.md', 'backlog-md.md', 'state-md.md'];
+    const templatesDir = path.join(claudeDir, 'momentum-framework', 'templates');
+    if (fs.existsSync(templatesDir)) {
+      for (const tmpl of oldTemplates) {
+        const tmplPath = path.join(templatesDir, tmpl);
+        if (fs.existsSync(tmplPath)) {
+          found.push({
+            path: tmplPath,
+            label: `momentum-framework/templates/${tmpl}`,
+            reason: 'Replaced by JSON templates in v3 — no longer used by scaffold',
+            type: 'file'
+          });
+        }
+      }
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Archive a single artifact (file or directory) to .accel/momentum/_archive/upgrade-v3/
+ */
+function archiveArtifact(artifact, archiveDir) {
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  if (artifact.type === 'directory') {
+    const destName = path.basename(artifact.path);
+    const destPath = path.join(archiveDir, destName);
+    copyDir(artifact.path, destPath);
+    fs.rmSync(artifact.path, { recursive: true });
+  } else if (artifact.type === 'file') {
+    const destPath = path.join(archiveDir, path.basename(artifact.path));
+    fs.copyFileSync(artifact.path, destPath);
+    fs.unlinkSync(artifact.path);
+  } else if (artifact.type === 'mcp-entry') {
+    // For MCP entries, remove the key from JSON
+    const mcpConfig = JSON.parse(fs.readFileSync(artifact.path, 'utf-8'));
+    delete mcpConfig.mcpServers['vector-mcp'];
+    fs.writeFileSync(artifact.path, JSON.stringify(mcpConfig, null, 2));
+  } else if (artifact.type === 'settings-v2-paths') {
+    // Rewrite -v2.py hook paths to canonical names in settings.json
+    let raw = fs.readFileSync(artifact.path, 'utf-8');
+    raw = raw.replace(/active-hook-v2\.py/g, 'active-hook.py');
+    raw = raw.replace(/backlog-hook-v2\.py/g, 'backlog-hook.py');
+    raw = raw.replace(/momentum-pulse-check-v2\.py/g, 'momentum-pulse-check.py');
+    fs.writeFileSync(artifact.path, raw);
+  }
+}
+
+/**
+ * Run upgrade cleanup interactively.
+ * Detects v1/v2 artifacts, warns the user, prompts for confirmation, archives.
+ * Returns a promise that resolves when cleanup is complete or skipped.
+ */
+function runUpgradeCleanup(claudeDir, workspaceDir) {
+  const artifacts = detectV1Artifacts(claudeDir, workspaceDir);
+  if (artifacts.length === 0) return Promise.resolve();
+
+  const momentumDir = workspaceDir ? path.join(workspaceDir, '.accel/momentum') : path.join(process.cwd(), '.accel/momentum');
+  const archiveDir = path.join(momentumDir, '_archive', 'upgrade-v3');
+
+  console.log(`  ${yellow}=== UPGRADE DETECTED ===${reset}`);
+  console.log(`  Found ${artifacts.length} artifact(s) from a previous Momentum version:\n`);
+  for (const a of artifacts) {
+    console.log(`  ${yellow}!${reset} ${a.label}`);
+    console.log(`    ${dim}${a.reason}${reset}`);
+  }
+  console.log(`\n  ${dim}These will be archived to: ${archiveDir.replace(os.homedir(), '~')}${reset}`);
+  console.log(`  ${dim}Nothing is deleted — you can recover from the archive.${reset}\n`);
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`  Archive these artifacts? ${dim}[Y/n]${reset}: `, (answer) => {
+      rl.close();
+      const proceed = !answer.trim() || answer.trim().toLowerCase() === 'y';
+      if (proceed) {
+        for (const a of artifacts) {
+          archiveArtifact(a, archiveDir);
+          console.log(`  ${green}archived${reset} ${a.label}`);
+        }
+        console.log('');
+      } else {
+        console.log(`  ${dim}Skipped cleanup. Old artifacts left in place.${reset}\n`);
+      }
+      resolve();
+    });
+  });
+}
+
+/**
+ * Install commands and skill framework
+ */
+function installCommands(isGlobal) {
+  const src = path.join(__dirname, '..');
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const defaultGlobalDir = configDir || path.join(os.homedir(), '.claude');
+  const claudeDir = isGlobal ? defaultGlobalDir : path.join(process.cwd(), '.claude');
+
+  const locationLabel = isGlobal
+    ? claudeDir.replace(os.homedir(), '~')
+    : claudeDir.replace(process.cwd(), '.');
+
+  console.log(`  Installing commands to ${cyan}${locationLabel}${reset}\n`);
+
+  // Copy commands
+  const commandsSrc = path.join(src, 'src', 'commands');
+  const commandsDest = path.join(claudeDir, 'commands', 'momentum');
+  copyDir(commandsSrc, commandsDest);
+  const commandCount = fs.readdirSync(commandsSrc).filter(f => f.endsWith('.md')).length;
+  console.log(`  ${green}+${reset} commands/momentum/ (${commandCount} slash commands)`);
+
+  // Copy skill entry point
+  const skillSrc = path.join(src, 'src', 'skill');
+  const skillDest = path.join(claudeDir, 'skills', 'momentum');
+  copyDir(skillSrc, skillDest);
+  console.log(`  ${green}+${reset} skills/momentum/ (entry point + MCP package sources)`);
+
+  // Copy MCP package sources into skill (for scaffold reference)
+  const packagesSrc = path.join(src, 'src', 'packages');
+  const packagesDest = path.join(claudeDir, 'skills', 'momentum', 'packages');
+  copyDir(packagesSrc, packagesDest);
+
+  // Copy Momentum framework (tasks, templates, context, frameworks)
+  const frameworkSrc = path.join(src, 'src', 'framework');
+  const frameworkDest = path.join(claudeDir, 'momentum-framework');
+  copyDir(frameworkSrc, frameworkDest);
+  console.log(`  ${green}+${reset} momentum-framework/ (tasks, templates, context, frameworks, utils)`);
+
+  // Copy all hooks to momentum-framework/hooks/ (source for scaffold)
+  const hooksFrameworkDest = path.join(claudeDir, 'momentum-framework', 'hooks');
+  fs.mkdirSync(hooksFrameworkDest, { recursive: true });
+  const hooksSrcDir = path.join(src, 'src', 'hooks');
+  const hookFiles = fs.readdirSync(hooksSrcDir).filter(f => f.endsWith('.py'));
+  for (const hookFile of hookFiles) {
+    fs.copyFileSync(path.join(hooksSrcDir, hookFile), path.join(hooksFrameworkDest, hookFile));
+  }
+  console.log(`  ${green}+${reset} momentum-framework/hooks/ (${hookFiles.length} hooks for scaffold)`);
+
+  console.log(`\n  ${green}Commands installed.${reset}\n`);
+}
+
+/**
+ * Install workspace layer (.accel/momentum/)
+ */
+function installWorkspace() {
+  const src = path.join(__dirname, '..');
+  const workspaceDir = expandTilde(explicitWorkspaceDir) || process.cwd();
+  const momentumDir = path.join(workspaceDir, '.accel/momentum');
+
+  console.log(`  Installing workspace layer to ${cyan}${momentumDir.replace(os.homedir(), '~')}${reset}\n`);
+
+  // Create .accel/momentum directories
+  fs.mkdirSync(path.join(momentumDir, 'data'), { recursive: true });
+  fs.mkdirSync(path.join(momentumDir, 'hooks'), { recursive: true });
+  console.log(`  ${green}+${reset} .accel/momentum/data/`);
+  console.log(`  ${green}+${reset} .accel/momentum/hooks/`);
+
+  // Initialize JSON data surfaces (don't overwrite existing)
+  const dataSurfaces = {
+    'active.json': { items: [], last_updated: null },
+    'backlog.json': { items: [], last_updated: null },
+    'projects.json': { projects: [], last_updated: null },
+    'entities.json': { entities: [], last_updated: null },
+    'state.json': { drift_score: 0, areas: {}, last_groom: null, last_updated: null },
+    'psmm.json': { sessions: {} }
+  };
+  let surfaceCount = 0;
+  for (const [filename, data] of Object.entries(dataSurfaces)) {
+    if (writeJsonIfNew(path.join(momentumDir, 'data', filename), data)) {
+      surfaceCount++;
+    }
+  }
+  if (surfaceCount > 0) {
+    console.log(`  ${green}+${reset} .accel/momentum/data/ (${surfaceCount} JSON surfaces initialized)`);
+  } else {
+    console.log(`  ${dim}  .accel/momentum/data/ (existing surfaces preserved)${reset}`);
+  }
+
+  // Copy workspace.json template (don't overwrite existing)
+  const workspaceJsonDest = path.join(momentumDir, 'workspace.json');
+  if (!fs.existsSync(workspaceJsonDest)) {
+    const templateSrc = path.join(src, 'src', 'templates', 'workspace.json');
+    if (fs.existsSync(templateSrc)) {
+      const template = JSON.parse(fs.readFileSync(templateSrc, 'utf-8'));
+      template.workspace = path.basename(workspaceDir);
+      template.created = new Date().toISOString().split('T')[0];
+      fs.writeFileSync(workspaceJsonDest, JSON.stringify(template, null, 2));
+      console.log(`  ${green}+${reset} .accel/momentum/workspace.json (manifest)`);
+    }
+  } else {
+    console.log(`  ${dim}  .accel/momentum/workspace.json (existing manifest preserved)${reset}`);
+  }
+
+  // Copy operator.json template (don't overwrite existing)
+  const operatorJsonDest = path.join(momentumDir, 'operator.json');
+  if (!fs.existsSync(operatorJsonDest)) {
+    const operatorSrc = path.join(src, 'src', 'templates', 'operator.json');
+    if (fs.existsSync(operatorSrc)) {
+      fs.copyFileSync(operatorSrc, operatorJsonDest);
+      console.log(`  ${green}+${reset} .accel/momentum/operator.json (operator profile — complete via /momentum:scaffold)`);
+    }
+  } else {
+    console.log(`  ${dim}  .accel/momentum/operator.json (existing profile preserved)${reset}`);
+  }
+
+  // Copy momentum-mcp
+  const mcpSrc = path.join(src, 'src', 'packages', 'momentum-mcp');
+  const mcpDest = path.join(momentumDir, 'momentum-mcp');
+  copyDir(mcpSrc, mcpDest);
+  console.log(`  ${green}+${reset} .accel/momentum/momentum-mcp/`);
+
+  // Copy all hooks to .accel/momentum/hooks/
+  const allHooksSrc = path.join(src, 'src', 'hooks');
+  const hookEntries = fs.readdirSync(allHooksSrc).filter(f => f.endsWith('.py'));
+  for (const file of hookEntries) {
+    fs.copyFileSync(path.join(allHooksSrc, file), path.join(momentumDir, 'hooks', file));
+  }
+  console.log(`  ${green}+${reset} .accel/momentum/hooks/ (${hookEntries.length} hooks)`);
+
+  // npm install for momentum-mcp
+  console.log(`\n  Installing MCP dependencies...`);
+  try {
+    execSync('npm install', { cwd: mcpDest, stdio: 'pipe' });
+    console.log(`  ${green}+${reset} momentum-mcp dependencies installed`);
+  } catch (e) {
+    console.log(`  ${yellow}!${reset} momentum-mcp npm install failed — run manually in .accel/momentum/momentum-mcp/`);
+  }
+
+  // Merge MCP registration into .mcp.json
+  const mcpJsonPath = path.join(workspaceDir, '.mcp.json');
+  let mcpConfig = { mcpServers: {} };
+  if (fs.existsSync(mcpJsonPath)) {
+    try {
+      mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
+    } catch (e) { /* start fresh */ }
+  }
+  mcpConfig.mcpServers['momentum-mcp'] = {
+    type: 'stdio',
+    command: 'node',
+    args: ['./.accel/momentum/momentum-mcp/index.js']
+  };
+  fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2));
+  console.log(`  ${green}+${reset} .mcp.json (momentum-mcp registered)`);
+
+  console.log(`\n  ${green}Workspace layer installed.${reset}`);
+  console.log(`  Run ${cyan}/momentum:scaffold${reset} to complete setup (hook wiring, operator profile).\n`);
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const globalPath = configDir || path.join(os.homedir(), '.claude');
+  const globalLabel = globalPath.replace(os.homedir(), '~');
+
+  console.log(`  ${yellow}What would you like to install?${reset}
+
+  ${cyan}1${reset}) Full install  ${dim}(commands to ${globalLabel} + workspace layer to .accel/momentum/)${reset}
+  ${cyan}2${reset}) Commands only  ${dim}(${globalLabel})${reset}
+  ${cyan}3${reset}) Workspace only ${dim}(.accel/momentum/ in current directory)${reset}
+`);
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    const choice = answer.trim() || '1';
+    if (choice === '1' || choice === '2') {
+      installCommands(true);
+    }
+    if (choice === '1' || choice === '3') {
+      installWorkspace();
+    }
+    if (choice !== '1' && choice !== '2' && choice !== '3') {
+      installCommands(true);
+      installWorkspace();
+    }
+    console.log(`  ${green}Done!${reset} Launch Claude Code and run ${cyan}/momentum:scaffold${reset} to complete setup.\n`);
+  });
+}
+
+// Main
+async function main() {
+  if (hasHelp) {
+    return; // Already handled above
+  }
+
+  if (hasGlobal || hasLocal || hasWorkspace) {
+    if (hasGlobal && hasLocal) {
+      console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+      process.exit(1);
+    }
+
+    // Detect and offer cleanup of v1/v2 artifacts before installing
+    const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+    const cleanupClaudeDir = (hasGlobal || hasLocal)
+      ? (hasGlobal ? (configDir || path.join(os.homedir(), '.claude')) : path.join(process.cwd(), '.claude'))
+      : null;
+    const cleanupWorkspaceDir = hasWorkspace
+      ? (expandTilde(explicitWorkspaceDir) || process.cwd())
+      : null;
+
+    await runUpgradeCleanup(cleanupClaudeDir, cleanupWorkspaceDir);
+
+    if (hasGlobal || hasLocal) {
+      installCommands(hasGlobal);
+    }
+    if (hasWorkspace) {
+      installWorkspace();
+    }
+    console.log(`  ${green}Done!${reset} Launch Claude Code and run ${cyan}/momentum:scaffold${reset} to complete setup.\n`);
+  } else {
+    promptLocation();
+  }
+}
+
+main();

package/modules/momentum/integration.js

@@ -0,0 +1,131 @@
+/**
+ * Momentum Integration — consumes events from Drive and Radar
+ *
+ * Integration points:
+ *   1. Drive -> Momentum:  Consumes `phase-progress` events to update workspace state.
+ *   2. Radar -> Momentum:  Consumes `audit-complete` events to create backlog items
+ *      for audit findings that need remediation.
+ *
+ * Event schemas consumed:
+ *   - shared/events/schemas/phase-progress.schema.json  (from Drive)
+ *   - shared/events/schemas/audit-complete.schema.json   (from Radar)
+ *
+ * Usage inside Momentum's hook or pulse check:
+ *   const integration = require('./integration');
+ *   const { stateUpdates, backlogItems } = integration.processIncomingEvents();
+ *
+ * @module modules/momentum/integration
+ */
+
+const eventBus = require('../../shared/events/event-bus');
+
+/**
+ * Consume pending phase-progress events emitted by Drive.
+ *
+ * Returns raw events so Momentum can update its workspace state surface
+ * (e.g. the "active" or "state" data surface).
+ *
+ * @returns {Array<{file: string, event: object}>} Array of phase-progress events
+ */
+function consumePhaseProgress() {
+  return eventBus.consume('momentum', ['phase-progress']);
+}
+
+/**
+ * Consume pending audit-complete events emitted by Radar.
+ *
+ * @returns {Array<{file: string, event: object}>} Array of audit-complete events
+ */
+function consumeAuditResults() {
+  return eventBus.consume('momentum', ['audit-complete']);
+}
+
+/**
+ * Convert a single audit-complete event payload into a Momentum backlog item.
+ *
+ * The backlog item follows the structure expected by Momentum's backlog
+ * data surface: an object with title, priority, source, and metadata.
+ *
+ * @param {object} auditPayload - The event payload from an audit-complete event
+ * @param {number} auditPayload.findings - Total findings count
+ * @param {number} auditPayload.critical - Critical findings count
+ * @param {string} auditPayload.report   - Path to the audit report
+ * @returns {object} A backlog item ready for insertion into the backlog surface
+ */
+function auditToBacklogItem(auditPayload) {
+  const { findings, critical, report } = auditPayload;
+
+  const priority = critical > 0 ? 'critical' : findings > 5 ? 'high' : 'normal';
+
+  return {
+    title: `Radar audit: ${findings} finding(s), ${critical} critical`,
+    priority,
+    source: 'radar',
+    status: 'pending',
+    createdAt: new Date().toISOString(),
+    metadata: {
+      findings,
+      critical,
+      report,
+    },
+  };
+}
+
+/**
+ * Convert a phase-progress event payload into a workspace state update.
+ *
+ * @param {object} progressPayload - The event payload from a phase-progress event
+ * @param {string} progressPayload.phase          - Phase name
+ * @param {string} progressPayload.status         - Phase status
+ * @param {string} [progressPayload.planPath]      - Path to the plan
+ * @param {number} [progressPayload.completedTasks] - Completed task count
+ * @param {number} [progressPayload.totalTasks]    - Total task count
+ * @returns {object} A state update object for Momentum's state surface
+ */
+function progressToStateUpdate(progressPayload) {
+  const { phase, status, planPath, completedTasks, totalTasks } = progressPayload;
+
+  return {
+    surface: 'state',
+    key: `drive.${phase.replace(/\s+/g, '_').toLowerCase()}`,
+    value: {
+      phase,
+      status,
+      planPath: planPath || null,
+      completedTasks: completedTasks || 0,
+      totalTasks: totalTasks || 0,
+      updatedAt: new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Process all incoming events in one pass.
+ *
+ * This is the primary entry point for Momentum's integration layer.
+ * Call it during Momentum's hook execution or pulse check to:
+ *   1. Pull phase-progress events and build state updates
+ *   2. Pull audit-complete events and build backlog items
+ *
+ * @returns {{
+ *   stateUpdates: Array<object>,
+ *   backlogItems: Array<object>
+ * }}
+ */
+function processIncomingEvents() {
+  const progressEvents = consumePhaseProgress();
+  const auditEvents = consumeAuditResults();
+
+  const stateUpdates = progressEvents.map((e) => progressToStateUpdate(e.event.payload));
+  const backlogItems = auditEvents.map((e) => auditToBacklogItem(e.event.payload));
+
+  return { stateUpdates, backlogItems };
+}
+
+module.exports = {
+  consumePhaseProgress,
+  consumeAuditResults,
+  auditToBacklogItem,
+  progressToStateUpdate,
+  processIncomingEvents,
+};