@mhd-ghaith-abtah/flow 0.7.2-beta.0 → 0.8.0-beta.0

package/lib/commands/doctor.js

@@ -49,6 +49,7 @@ export default async function doctor(args, ctx) {
     adapters: [],
     clis: [],
     upstreams: [],
+    collisions: [],
   };
 
   // Adapter + CLI checks depend on a parsed config.
@@ -60,6 +61,12 @@ export default async function doctor(args, ctx) {
   // Upstream presence — cheap detection from install-state.
   report.upstreams = probeUpstreams(ctx, report.state.home);
 
+  // Cross-scope collision checks (E7-004). Detects e.g. ECC installed at
+  // both ~/.claude/rules/ecc and <cwd>/.claude/rules/ecc, which happens
+  // when a user changes --ecc-scope without uninstalling the previous
+  // scope's content. Cheap fs.existsSync checks, no parsing required.
+  report.collisions = probeCollisions(ctx, report.state.home);
+
   if (json) {
     // Strip the internal `raw` catalog payload — JSON consumers want doctor
     // results, not the entire catalog dumped.
@@ -220,16 +227,65 @@ function probeUpstreams(ctx, homeState) {
   if (!homeState.parsed?.upstreams) return [];
   const out = [];
   for (const [name, rec] of Object.entries(homeState.parsed.upstreams)) {
-    out.push({
+    const entry = {
       name,
       status: rec.installed ? '✓' : 'ℹ',
       subset: rec.subset,
       version: rec.version || 'not pinned',
-    });
+    };
+    // Surface the Caveman fork status so users know we're shipping from a
+    // pinned fork tag pending JuliusBrussee/caveman#407 merging upstream.
+    // Hint level (ℹ) on purpose — it's expected state, not a problem.
+    if (name === 'caveman' && rec.source === 'npx-from-fork') {
+      entry.note = `installed from fork (${rec.fork_tag || 'pinned'}); tracking upstream PR #${rec.upstream_pr || 407}`;
+    }
+    out.push(entry);
   }
   return out;
 }
 
+/**
+ * E7-004: detect ECC installed at both user-scope (~/.claude/rules/ecc)
+ * AND project-scope (<cwd>/.claude/rules/ecc). Happens when a user
+ * switches --ecc-scope without uninstalling the previous scope's content.
+ * Returns an array of collision entries; empty array when no drift.
+ *
+ * Probe is intentionally cheap (existsSync only, no parsing) so it adds
+ * negligible cost to every doctor run.
+ *
+ * @param {Object} ctx - doctor invocation context
+ * @param {Object} homeState - parsed home install-state (for the recorded scope)
+ * @returns {Array<{kind:string,status:string,detail:string,fix:string}>}
+ */
+function probeCollisions(ctx, homeState) {
+  const collisions = [];
+  const homeDir = ctx.home || process.env.HOME;
+  if (!homeDir) return collisions;
+  const cwd = ctx.cwd || process.cwd();
+
+  const userEccDir = join(homeDir, '.claude', 'rules', 'ecc');
+  const projectEccDir = join(cwd, '.claude', 'rules', 'ecc');
+  const userPresent = existsSync(userEccDir);
+  const projectPresent = existsSync(projectEccDir);
+
+  if (userPresent && projectPresent) {
+    const recordedScope = homeState?.parsed?.upstreams?.ecc?.install_scope || null;
+    const expected = recordedScope === 'project' ? projectEccDir : userEccDir;
+    const stale = recordedScope === 'project' ? userEccDir : projectEccDir;
+    const scopeLabel = recordedScope ?? 'unknown (no install_scope recorded)';
+    collisions.push({
+      kind: 'ecc-scope-collision',
+      status: '⚠',
+      detail: `ECC content found at BOTH ${userEccDir} and ${projectEccDir}. Recorded scope: ${scopeLabel}.`,
+      fix: recordedScope
+        ? `Active install is at ${expected}. Remove the stale one (likely safe): rm -rf ${stale}`
+        : `No install_scope recorded — re-run \`/flow-init --update\` or \`flow install --ecc-scope <user|project>\` so the state file knows which scope owns the install, then remove whichever path doesn't match.`,
+    });
+  }
+
+  return collisions;
+}
+
 function countSeverities(report) {
   const counts = { ok: 0, info: 0, warn: 0, fail: 0 };
   const items = [
@@ -240,6 +296,7 @@ function countSeverities(report) {
     ...report.adapters,
     ...report.clis,
     ...report.upstreams,
+    ...(report.collisions || []),
   ];
   for (const item of items) {
     if (!item) continue;
@@ -288,6 +345,16 @@ function renderHuman(report, { verbose }) {
     lines.push('Upstreams:');
     for (const u of report.upstreams) {
       lines.push(`  ${u.name}:  ${tag(u.status)}  subset=${u.subset || '—'}  version=${u.version}`);
+      if (u.note) lines.push(`          ${chalk.dim(u.note)}`);
+    }
+  }
+
+  if (report.collisions && report.collisions.length > 0) {
+    lines.push('');
+    lines.push('Collisions:');
+    for (const col of report.collisions) {
+      lines.push(`  ${col.kind}:  ${tag(col.status)}  ${col.detail}`);
+      lines.push(`          ${chalk.dim('Fix: ' + col.fix)}`);
     }
   }
 
@@ -371,19 +438,27 @@ async function runRepairUpstream(name, ctx) {
     console.log(chalk.dim(`  - npx will install the exact pinned version.`));
     console.log(chalk.dim(`  - If the pinned version was a commit hash (e.g. "unknown@<date>"), use git checkout in _bmad/ instead.`));
   } else if (name === 'ecc') {
-    console.log(`  ${chalk.cyan(`cd ~/.claude/rules && git fetch --all && git checkout ${record.version}`)}`);
+    const scope = record.install_scope || 'user';
+    const target = scope === 'project' ? 'claude-project' : 'claude';
+    const rulesDir = scope === 'project' ? '<projectRoot>/.claude/rules' : '~/.claude/rules';
+    console.log(`  ${chalk.cyan(`cd ${rulesDir} && git fetch --all && git checkout ${record.version}`)}`);
     console.log();
     console.log(chalk.dim('  Notes:'));
-    console.log(chalk.dim(`  - ECC ships as a git checkout under ~/.claude/rules. The pinned value is a git ref.`));
-    console.log(chalk.dim(`  - If ~/.claude/rules/ isn't a git checkout, re-run the ECC installer:`));
-    console.log(chalk.dim(`    npx @everything-claude-code/ecc install --target claude --profile ${record.subset}`));
+    console.log(chalk.dim(`  - ECC ships as a git checkout under ${rulesDir}. The pinned value is a git ref.`));
+    console.log(chalk.dim(`  - Recorded install scope: ${scope} (target: --target ${target}).`));
+    console.log(chalk.dim(`  - If ${rulesDir}/ isn't a git checkout, re-run the ECC installer:`));
+    console.log(chalk.dim(`    npx -y -p "github:affaan-m/ECC#98bd5174" ecc-install --target ${target} --profile ${record.subset}`));
+    console.log(chalk.dim(`    (Pinned to ECC main post-merge of #2006 until ecc-universal@2.x lands on npm.)`));
   } else if (name === 'caveman') {
-    console.log(`  ${chalk.cyan(`curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash`)}`);
+    console.log(`  ${chalk.cyan(`npx -y "github:mhd-ghaith-abtah/caveman#flow-pin-v0.1"`)}`);
     console.log();
     console.log(chalk.dim('  Notes:'));
-    console.log(chalk.dim(`  - Caveman ships only via curl-pipe-bash. The pinned version (${record.version}) is informational; the installer always lands on main.`));
-    console.log(chalk.dim(`  - To inspect first: set FLOW_INSPECT_INSTALL_SCRIPTS=1 and re-run /flow-init.`));
-    console.log(chalk.dim(`  - Local hook patches (e.g., project-scope from PR #407) at ~/.claude/hooks/caveman-*.pre-scope-patch will be overwritten — reapply them after.`));
+    console.log(chalk.dim(`  - Flow installs Caveman from a temporary fork (mhd-ghaith-abtah/caveman @ flow-pin-v0.1).`));
+    console.log(chalk.dim(`    Fork = upstream main + JuliusBrussee/caveman#407 (project-scope gating) patches.`));
+    console.log(chalk.dim(`  - Pinned version: ${record.version}. When #407 merges upstream Flow will swap back.`));
+    console.log(chalk.dim(`  - To inspect first: gh repo view mhd-ghaith-abtah/caveman --branch flow-pin-v0.1`));
+    console.log(chalk.dim(`    or set FLOW_INSPECT_INSTALL_SCRIPTS=1 and re-run /flow-init.`));
+    console.log(chalk.dim(`  - Track upstream merge status: gh pr view 407 --repo JuliusBrussee/caveman`));
   }
 
   console.log();

package/lib/commands/init.js

@@ -1,19 +1,38 @@
-// lib/commands/init.js — `flow init` headless entry point.
+// lib/commands/init.js — `flow init` entry point.
 //
-// v0.7 scope: the *interactive* installer lives in skills/flow-init/workflow.md
-// (Claude Code reads the workflow and runs it). The headless `flow init` CLI
-// path is intentionally thin — it prints the plan, then either:
-//   • dispatches to `claude` CLI to run /flow-init (if `claude` is in $PATH), or
-//   • prints clear instructions for running /flow-init manually.
+// Two paths:
 //
-// Why thin: porting the full interactive workflow to Node duplicates ~800 LOC
-// of decision logic already in workflow.md. Better to have one source of truth.
+//   1. **Interactive (default inside Claude Code):** the rich Q&A lives
+//      in skills/flow-init/workflow.md. The CLI just prints the
+//      slash-command nudge so the user runs /flow-init in-session
+//      where the LLM can drive the prompts, error recovery, and
+//      multi-step ceremony.
+//
+//   2. **Headless (--yes outside Claude Code, npx-first):** chain
+//      detect → questions (pre-populated) → upstream dispatch → MCP
+//      registration → optional BMad migration → scaffold the project
+//      via lib/init/orchestrate.js. This is the v0.8 npx-first install
+//      path. Tests + CI scripts hit this branch.
+//
+// --dry-run shows the plan + halts before any execution in either path.
 
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { execa } from 'execa';
-import { loadCatalog, resolveProfile } from '../catalog.js';
+import { loadCatalog } from '../catalog.js';
 import { resolveRepoRoot } from '../repo-root.js';
 import plan from './plan.js';
+import { runInit, defaultAnswersForProfile } from '../init/orchestrate.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_PATH = resolve(__dirname, '..', '..', 'package.json');
+
+function readFlowVersion() {
+  try { return JSON.parse(readFileSync(PKG_PATH, 'utf8')).version; }
+  catch { return 'unknown'; }
+}
 
 /**
  * @param {Object} args
@@ -21,11 +40,29 @@ import plan from './plan.js';
  */
 export default async function init(args, ctx) {
   const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
-  loadCatalog(repoRoot);  // validate parseable; throws on bad catalog
-
+  const catalog = loadCatalog(repoRoot);
   const profileName = args.profile ?? 'standard';
   const yes = Boolean(args.yes);
   const dryRun = Boolean(args['dry-run']);
+  const cwd = ctx.cwd || process.cwd();
+
+  // Repair mode: skip everything except scaffold. Useful when the user
+  // accidentally deleted docs/flow/sprint.yaml or .claude/flow.config.yaml
+  // and wants Flow to put them back without re-running upstream installers
+  // (which would re-fetch BMad/ECC/Caveman from network for no reason).
+  if (args.repair) {
+    return runRepair({ catalog, cwd, args });
+  }
+
+  // Update mode: re-run the chain against an existing install. Reads
+  // recorded answers from install-state.json, lets CLI flags override
+  // (e.g. swap profile, change --ecc-scope), then runs the chain. The
+  // upstream dispatchers + mcp.js are already idempotent (skip when
+  // already-installed), so --update is mostly about computing the
+  // delta + force-rewriting flow.config.yaml.
+  if (args.update) {
+    return runUpdate({ catalog, cwd, args });
+  }
 
   // Always show the plan first.
   console.log(chalk.dim(`Resolving plan for profile '${profileName}'…`));
@@ -33,54 +70,324 @@ export default async function init(args, ctx) {
   await plan({ ...args, profile: profileName }, ctx);
   console.log();
 
-  if (dryRun) {
+  if (dryRun && !yes) {
+    // dry-run without --yes is plan-only.
     console.log(chalk.dim('(--dry-run: stopping before execution)'));
     return 0;
   }
 
-  // Inside Claude Code: just tell the user to run /flow-init. Don't fork.
+  // Headless path: --yes (or --yes + --dry-run for the integration-test path).
+  if (yes) {
+    return runHeadless({ catalog, cwd, profileName, args, dryRun });
+  }
+
+  // Interactive path inside Claude Code: nudge to slash command.
   if (ctx.insideClaudeCode) {
     console.log(chalk.bold('Inside Claude Code — run the slash command:'));
     console.log(`  ${chalk.cyan('/flow-init')}${profileName !== 'standard' ? ` --profile ${profileName}` : ''}`);
     return 0;
   }
 
-  // Outside Claude Code: try to dispatch to `claude` CLI.
-  if (!yes) {
-    console.log(chalk.yellow('?'), `Run the interactive installer via the \`claude\` CLI? [y/N]`);
-    console.log(chalk.dim('  (Re-run with --yes to skip this prompt, or use --dry-run to preview only.)'));
-    return 0;  // Non-interactive default: stop. CI scripts use --yes.
+  // Outside Claude Code, no --yes: show both paths.
+  console.log(chalk.bold('Choose an installation path:'));
+  console.log();
+  console.log(`  ${chalk.cyan('flow init --profile ' + profileName + ' --yes')}    # headless install (this CLI)`);
+  console.log(`  ${chalk.cyan('claude')} → ${chalk.cyan('/flow-init')}                          # interactive install (Claude Code)`);
+  console.log();
+  console.log(chalk.dim('Re-run with --dry-run for a preview, or --yes to install headlessly.'));
+  return 0;
+}
+
+/**
+ * Run the orchestrator end-to-end with pre-populated answers from the
+ * resolved profile + CLI overrides.
+ */
+async function runHeadless({ catalog, cwd, profileName, args, dryRun }) {
+  // Pre-populate every Q&A slot from the profile defaults so askAll()
+  // never fires an interactive prompt. Honor --ecc-scope override.
+  const overrides = {};
+  if (args['ecc-scope']) overrides.eccScope = args['ecc-scope'];
+  if (args['bmad-subset']) overrides.bmadSubset = args['bmad-subset'];
+  if (args['ecc-subset']) overrides.eccSubset = args['ecc-subset'];
+  const cliAnswers = defaultAnswersForProfile(catalog, profileName, overrides);
+
+  console.log(chalk.bold('━━━ flow init (headless) ━━━'));
+  console.log(chalk.dim(`  profile=${profileName}  cwd=${cwd}  dry-run=${dryRun}`));
+  console.log();
+
+  const result = await runInit({
+    cwd,
+    catalog,
+    flowVersion: readFlowVersion(),
+    cliAnswers,
+    dryRun,
+    force: Boolean(args.force),
+    continueOnUpstreamError: Boolean(args['continue-on-error']),
+  });
+
+  if (!result.ok) {
+    console.error(chalk.red(`✗ init halted: ${result.haltReason}`));
+    for (const [name, r] of Object.entries(result.upstreamResults)) {
+      if (r && !r.ok && r.error) console.error(chalk.dim(`  ${name}: ${r.error}`));
+    }
+    return 1;
+  }
+
+  // Render the manifest.
+  console.log(chalk.bold('Upstream installers:'));
+  for (const [name, r] of Object.entries(result.upstreamResults)) {
+    const tag = r.stateRecord?.skipped ? chalk.dim('skipped') : (r.ok ? chalk.green('✓') : chalk.red('✗'));
+    console.log(`  ${name}:  ${tag}  ${chalk.dim(r.command?.source || '')}`);
+  }
+  console.log();
+  if (result.mcpResults.length > 0) {
+    console.log(chalk.bold('MCPs:'));
+    for (const m of result.mcpResults) {
+      const tag = m.stateRecord?.skipped ? chalk.dim('already-registered') : (m.ok ? chalk.green('✓') : chalk.red('✗'));
+      console.log(`  ${m.id}:  ${tag}`);
+    }
+    console.log();
   }
+  if (result.secretsResult && result.secretsResult.store !== 'skipped') {
+    console.log(chalk.bold('Secrets:'));
+    if (result.secretsResult.ok) {
+      const tag = result.secretsResult.store === 'env-file' ? chalk.green('✓') : chalk.dim('printed');
+      const where = result.secretsResult.path
+        ? chalk.dim(` → ${result.secretsResult.path}`)
+        : chalk.dim(` (${result.secretsResult.store} — copy lines above)`);
+      console.log(`  ${tag} ${result.secretsResult.envVarsWritten.length} var(s) for ${result.secretsResult.mcpsCovered.join(', ')}${where}`);
+    } else {
+      console.log(`  ${chalk.red('✗')} ${result.secretsResult.error}`);
+    }
+    console.log();
+  }
+  if (result.migrationResult) {
+    console.log(chalk.bold('BMad migration:'));
+    console.log(`  ${chalk.green('✓')}  ${result.migrationResult.storiesImported} stories, ${result.migrationResult.epicsImported} epics`);
+    console.log();
+  }
+  console.log(chalk.bold('Files:'));
+  for (const p of result.scaffoldManifest.written) console.log(`  ${chalk.green('+')} ${p}`);
+  for (const p of result.scaffoldManifest.skipped) console.log(`  ${chalk.dim('=')} ${p} ${chalk.dim('(exists; use --force to overwrite)')}`);
+  console.log();
+  console.log(chalk.green('✓ flow init complete'));
+  if (dryRun) console.log(chalk.yellow('  (--dry-run: nothing was actually written)'));
+  return 0;
+}
 
-  const claudeAvailable = await hasClaudeCli();
-  if (!claudeAvailable) {
-    console.error(chalk.yellow('⚠'), 'The `claude` CLI is not on $PATH.');
-    console.error('  Install Claude Code (https://claude.com/claude-code), then:');
-    console.error(`    ${chalk.cyan('claude')}    # start a session`);
-    console.error(`    ${chalk.cyan('/flow-init')}  # inside the session`);
-    return 2;
+/**
+ * Repair mode: recreate missing project-scope scaffold files
+ * (.claude/flow.config.yaml, docs/flow/sprint.yaml, deferred.md,
+ * .claude/flow/install-state.json) without re-running upstream
+ * installers or MCPs. Reads the profile + answers from the existing
+ * install-state.json so the regenerated config matches what the user
+ * picked at install time.
+ *
+ * Refuses to run if no install-state.json exists — there's nothing
+ * authoritative to repair from. User should run `flow init --yes`
+ * instead.
+ */
+async function runRepair({ catalog, cwd, args }) {
+  const statePath = join(cwd, '.claude', 'flow', 'install-state.json');
+  if (!existsSync(statePath)) {
+    console.error(chalk.red('✗ flow init --repair: no .claude/flow/install-state.json found'));
+    console.error(chalk.dim('  Repair needs a prior install to read profile + answers from.'));
+    console.error(chalk.dim('  Run `flow init --profile <name> --yes` to do a fresh install instead.'));
+    return 1;
   }
 
-  // Dispatch: open `claude` with /flow-init prefilled.
-  console.log(chalk.dim('Dispatching to `claude` CLI…'));
+  let state;
   try {
-    await execa('claude', ['/flow-init', ...(profileName !== 'standard' ? ['--profile', profileName] : [])], {
-      stdio: 'inherit',
-      env: { ...process.env, FLOW_REPO_ROOT: repoRoot }
-    });
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch (err) {
+    console.error(chalk.red(`✗ flow init --repair: failed to parse install-state.json: ${err.message}`));
+    return 2;
+  }
+  if (!state.profile || !state.answers) {
+    console.error(chalk.red('✗ flow init --repair: install-state.json missing required profile/answers fields'));
+    return 2;
+  }
+
+  const profileName = state.profile;
+  const answers = state.answers;
+  const dryRun = Boolean(args['dry-run']);
+
+  console.log(chalk.bold('━━━ flow init (repair) ━━━'));
+  console.log(chalk.dim(`  profile=${profileName}  cwd=${cwd}  dry-run=${dryRun}`));
+  console.log();
+
+  // Import scaffold lazily so the regular init path doesn't pay for it.
+  const { scaffold } = await import('../init/scaffold.js');
+  const { resolveProfile } = await import('../catalog.js');
+  const resolved = resolveProfile(catalog, profileName);
+
+  const manifest = scaffold({
+    cwd,
+    profile: profileName,
+    answers,
+    resolvedProfile: resolved,
+    catalog,
+    flowVersion: readFlowVersion(),
+    upstreamResults: state.upstreams || {},
+    migrationResult: state.migration || null,
+  }, { dryRun, force: false });
+
+  if (manifest.written.length === 0 && manifest.skipped.length > 0 && manifest.dirs.length === 0) {
+    console.log(chalk.green('✓ Nothing to repair — all scaffold files already present.'));
     return 0;
+  }
+
+  console.log(chalk.bold('Files:'));
+  for (const p of manifest.written) console.log(`  ${chalk.green('+')} ${p} ${chalk.dim('(recreated)')}`);
+  for (const p of manifest.skipped) console.log(`  ${chalk.dim('=')} ${p} ${chalk.dim('(present, untouched)')}`);
+  if (manifest.dirs.length > 0) {
+    for (const d of manifest.dirs) console.log(`  ${chalk.green('+')} ${d}/ ${chalk.dim('(directory created)')}`);
+  }
+  console.log();
+  console.log(chalk.green('✓ flow init --repair complete'));
+  if (dryRun) console.log(chalk.yellow('  (--dry-run: nothing was actually written)'));
+  return 0;
+}
+
+/**
+ * Update mode: re-run the install chain against an existing install,
+ * with CLI flags taking precedence over recorded answers. The chain
+ * itself is idempotent (upstream dispatchers + mcp.js skip on already-
+ * installed state), so most of this function is about loading the prior
+ * state, computing the delta, and force-rewriting flow.config.yaml so
+ * the on-disk config reflects whatever changed.
+ *
+ * Behavior:
+ *   - No install-state.json → exit 1 (nothing to update from; hint
+ *     toward `flow init --yes` for a fresh install).
+ *   - install_scope change (user → project or vice-versa) → exit 1
+ *     with hint. Scope swaps need uninstall + reinstall because the
+ *     filesystem layout is fundamentally different; mid-flight swap
+ *     would leave stale content at the old scope's location.
+ *   - Otherwise: run the chain with the new resolved answers + force=true
+ *     on scaffold. Emit a delta summary at the end.
+ */
+async function runUpdate({ catalog, cwd, args }) {
+  const statePath = join(cwd, '.claude', 'flow', 'install-state.json');
+  if (!existsSync(statePath)) {
+    console.error(chalk.red('✗ flow init --update: no .claude/flow/install-state.json found'));
+    console.error(chalk.dim('  Update needs a prior install to read from.'));
+    console.error(chalk.dim('  Run `flow init --profile <name> --yes` to do a fresh install.'));
+    return 1;
+  }
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
   } catch (err) {
-    if (err.exitCode != null) return err.exitCode;
-    console.error(chalk.red(`✗ Failed to launch claude: ${err.message}`));
+    console.error(chalk.red(`✗ flow init --update: failed to parse install-state.json: ${err.message}`));
+    return 2;
+  }
+  if (!state.profile || !state.answers) {
+    console.error(chalk.red('✗ flow init --update: install-state.json missing required profile/answers fields'));
+    return 2;
+  }
+
+  const prevProfile = state.profile;
+  const prevAnswers = state.answers;
+  const dryRun = Boolean(args['dry-run']);
+
+  // Apply CLI overrides on top of recorded answers. We DON'T re-derive
+  // from defaultAnswersForProfile because the user may have customized
+  // individual adapter / subset values via --with / --without at install
+  // time and we shouldn't blow those away.
+  const newProfileName = args.profile || prevProfile;
+  const newAnswers = { ...prevAnswers, profile: newProfileName };
+  if (args['ecc-scope']) newAnswers.eccScope = args['ecc-scope'];
+  if (args['bmad-subset']) newAnswers.bmadSubset = args['bmad-subset'];
+  if (args['ecc-subset']) newAnswers.eccSubset = args['ecc-subset'];
+
+  // If the profile changed, re-derive adapter/subset defaults from the
+  // new profile UNLESS the user explicitly overrode them. This is the
+  // "swap profile" use case (e.g. mini → team) where the user expects
+  // team's adapters + subsets to take effect.
+  if (newProfileName !== prevProfile) {
+    const newDefaults = defaultAnswersForProfile(catalog, newProfileName);
+    for (const key of ['issueTracker', 'pr', 'e2e', 'verify', 'bmadSubset', 'eccSubset', 'eccScope', 'cavemanSubset']) {
+      // Only update if the user didn't already pin it via CLI override above.
+      const cliKey = ({
+        eccScope: 'ecc-scope', bmadSubset: 'bmad-subset', eccSubset: 'ecc-subset',
+      })[key];
+      if (cliKey && args[cliKey]) continue;
+      newAnswers[key] = newDefaults[key];
+    }
+  }
+
+  // Hard halt on install_scope change — too destructive to do mid-flight.
+  if (prevAnswers.eccScope && newAnswers.eccScope !== prevAnswers.eccScope) {
+    console.error(chalk.red(`✗ flow init --update: install_scope change (${prevAnswers.eccScope} → ${newAnswers.eccScope}) is not supported mid-flight`));
+    console.error(chalk.dim('  Scope swaps need uninstall + reinstall to avoid stale content at the old location.'));
+    console.error(chalk.dim('  Suggested:'));
+    console.error(chalk.dim(`    flow uninstall --execute --yes${prevAnswers.eccScope === 'project' ? ' --remove-project-ecc' : ''}`));
+    console.error(chalk.dim(`    flow init --profile ${newProfileName} --ecc-scope ${newAnswers.eccScope} --yes`));
+    return 1;
+  }
+
+  // Compute + show the delta before running anything.
+  const deltas = computeDeltas(prevAnswers, newAnswers);
+
+  console.log(chalk.bold('━━━ flow init (update) ━━━'));
+  console.log(chalk.dim(`  was: profile=${prevProfile}  →  now: profile=${newProfileName}  cwd=${cwd}  dry-run=${dryRun}`));
+  console.log();
+  if (deltas.length === 0) {
+    console.log(chalk.green('✓ No changes — install matches the requested state.'));
+    console.log(chalk.dim('  (Re-run with --force to refresh flow.config.yaml anyway.)'));
+    if (!args.force) return 0;
+  } else {
+    console.log(chalk.bold('Changes:'));
+    for (const d of deltas) console.log(`  ${chalk.yellow('Δ')} ${d.key}: ${chalk.dim(`${formatVal(d.from)} → ${formatVal(d.to)}`)}`);
+    console.log();
+  }
+
+  const result = await runInit({
+    cwd,
+    catalog,
+    flowVersion: readFlowVersion(),
+    cliAnswers: newAnswers,
+    dryRun,
+    // Force scaffold rewrite so flow.config.yaml picks up the new answers.
+    // Without this, the existing flow.config.yaml would be preserved and
+    // the on-disk config would drift from install-state.json.
+    force: true,
+    continueOnUpstreamError: Boolean(args['continue-on-error']),
+  });
+
+  if (!result.ok) {
+    console.error(chalk.red(`✗ update halted: ${result.haltReason}`));
     return 1;
   }
+
+  console.log(chalk.green('✓ flow init --update complete'));
+  if (dryRun) console.log(chalk.yellow('  (--dry-run: nothing was actually written)'));
+  return 0;
 }
 
-async function hasClaudeCli() {
-  try {
-    await execa('which', ['claude']);
-    return true;
-  } catch {
-    return false;
+/**
+ * Compute a flat list of {key, from, to} deltas between two answer sets.
+ * Used by --update to surface what changed before running the chain.
+ *
+ * @param {Object} prev
+ * @param {Object} next
+ * @returns {Array<{key: string, from: any, to: any}>}
+ */
+function computeDeltas(prev, next) {
+  const out = [];
+  const keys = new Set([...Object.keys(prev), ...Object.keys(next)]);
+  for (const key of keys) {
+    if (prev[key] !== next[key]) {
+      out.push({ key, from: prev[key], to: next[key] });
+    }
   }
+  return out;
+}
+
+function formatVal(v) {
+  if (v == null) return '∅';
+  if (typeof v === 'string') return v;
+  return JSON.stringify(v);
 }

package/lib/commands/install.js

@@ -26,6 +26,7 @@ import { existsSync, mkdirSync, copyFileSync, writeFileSync, readFileSync, readd
 import { resolve, join, dirname } from 'node:path';
 import chalk from 'chalk';
 import { loadCatalog, resolveProfile, listProfiles } from '../catalog.js';
+import { applyEccScopeOverride } from './plan.js';
 import { resolveRepoRoot } from '../repo-root.js';
 
 /**
@@ -44,6 +45,10 @@ export default async function install(args, ctx) {
   }
 
   const profile = resolveProfile(catalog, profileName);
+  // CLI --ecc-scope overrides the profile default (E7-002 follow-up).
+  // Validates against user|project; throws on typo to avoid silent
+  // fallback to profile default.
+  const eccScope = applyEccScopeOverride(profile.ecc_install_scope, args['ecc-scope']);
   const yes = Boolean(args.yes);
   const dryRun = Boolean(args['dry-run']);
   const scope = args.scope ?? 'both';
@@ -83,7 +88,7 @@ export default async function install(args, ctx) {
   console.log(`Adapters:     ${profile.adapters.length}  (${profile.adapters.join(', ')})`);
   console.log(`MCPs:         ${profile.mcps.length}  (${profile.mcps.join(', ') || chalk.dim('none')})`);
   console.log(`BMad subset:  ${profile.bmad_subset}  ${chalk.dim('(this CLI will NOT run BMad installer)')}`);
-  console.log(`ECC subset:   ${profile.ecc_subset}   ${chalk.dim('(this CLI will NOT run ECC installer)')}`);
+  console.log(`ECC subset:   ${profile.ecc_subset}   ${chalk.dim(`(scope: ${eccScope} — this CLI will NOT run ECC installer)`)}`);
   console.log(`Caveman:      ${profile.caveman_subset}  ${chalk.dim('(this CLI will NOT run Caveman installer)')}`);
   console.log();
   console.log(`Operations:   ${operations.length}`);