@limina-labs/momentum 0.32.0 → 0.34.0

package/README.md

@@ -182,6 +182,7 @@ and is idempotent. (ADR-0005.)
 | 🧭 **Phases** | Plan → execute → verify → release. Every phase has a brainstorm, plan, tasks, history. |
 | 📋 **Backlog** | Bugs / features / tech debt / enhancements with priorities and per-item context. |
 | 📜 **History** | Append-only log of decisions, discoveries, scope changes. The *why* outlives any session. |
+| ⚙️ **Config** | `specs/config.md` — forge, publish target, branch flow, test/build commands. Recipes adapt to your project, not npm+GitHub defaults. |
 | ⚖️ **Rules** | 13 autonomous agent rules — orient first, verify before claim, log every decision. |
 | 🛠️ **Skills** | ~15 slash commands your agent runs — start, complete, sync, review, validate. |
 | 🌐 **Multi-project** | Ecosystem mode (state layer) + Orchestration primitives (action layer) for cross-project work. |

package/adapters/antigravity/instructions/AGENTS.md

@@ -15,6 +15,7 @@
 | Phase tasks/progress? | `specs/phases/phase-N-*/tasks.md` |
 | Why was X chosen? | `specs/decisions/NNNN-*.md` |
 | Roadmap / timeline? | `specs/planning/roadmap.md` (authored at founding — `/start-project`) |
+| Project config (forge, publish, branch flow)? | `specs/config.md` (inferred by `momentum init`, authored at `/start-project`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**

package/adapters/codex/adapter.js

@@ -167,6 +167,10 @@ function transformCommandsIntoSkills(targetDir, recordManaged) {
 
   let count = 0;
   for (const file of fs.readdirSync(commandsDir)) {
+    // Skip macOS AppleDouble sidecars FIRST: `._complete-phase.md` ends with
+    // `.md`, so an endsWith check alone would mint a `._complete-phase/SKILL.md`
+    // junk skill dir (Phase 27 G4 — the source of the ._* skill-dir litter).
+    if (file.startsWith('._') || file === '.DS_Store') continue;
     if (!file.endsWith('.md')) continue;
     const name = file.replace(/\.md$/, '');
     const body = fs.readFileSync(path.join(commandsDir, file), 'utf8');
@@ -223,3 +227,6 @@ function renderSkillMarkdown(name, description, recipeBody) {
     recipeBody.endsWith('\n') ? recipeBody : recipeBody + '\n',
   ].join('\n');
 }
+
+// Phase 27 G4 — exported for the AppleDouble-filter regression test.
+module.exports.transformCommandsIntoSkills = transformCommandsIntoSkills;

package/adapters/codex/instructions/AGENTS.md

@@ -15,6 +15,7 @@
 | Phase tasks/progress? | `specs/phases/phase-N-*/tasks.md` |
 | Why was X chosen? | `specs/decisions/NNNN-*.md` |
 | Roadmap / timeline? | `specs/planning/roadmap.md` (authored at founding — `/start-project`) |
+| Project config (forge, publish, branch flow)? | `specs/config.md` (inferred by `momentum init`, authored at `/start-project`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**
@@ -47,6 +48,7 @@ The shipped recipe set (one skill per recipe, all under
 | log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/adapters/codex/instructions/surfaces.md

@@ -24,6 +24,7 @@ The shipped recipe set (one skill per recipe, all under
 | log | Append a manual narrative entry to the history of the phase bound to your branch (fallback: status.md) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/adapters/opencode/adapter.js

@@ -173,6 +173,8 @@ function ensureCommandFrontmatter(targetDir) {
   }
   let count = 0;
   for (const file of fs.readdirSync(commandsDir)) {
+    // Skip AppleDouble sidecars first — `._x.md` ends with `.md` (Phase 27 G4).
+    if (file.startsWith('._') || file === '.DS_Store') continue;
     if (!file.endsWith('.md')) continue;
     const filePath = path.join(commandsDir, file);
     const body = fs.readFileSync(filePath, 'utf8');

package/adapters/opencode/instructions/AGENTS.md

@@ -15,6 +15,7 @@
 | Phase tasks/progress? | `specs/phases/phase-N-*/tasks.md` |
 | Why was X chosen? | `specs/decisions/NNNN-*.md` |
 | Roadmap / timeline? | `specs/planning/roadmap.md` (authored at founding — `/start-project`) |
+| Project config (forge, publish, branch flow)? | `specs/config.md` (inferred by `momentum init`, authored at `/start-project`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**
@@ -47,6 +48,7 @@ The shipped recipe set (one command per recipe):
 | lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/adapters/opencode/instructions/surfaces.md

@@ -24,6 +24,7 @@ The shipped recipe set (one command per recipe):
 | lanes | Work with lanes — concurrent workstreams in one repo (Rule 15) |
 | migrate | Onboard an existing project into momentum |
 | validate | Check spec structure health |
+| sync-config | Re-infer project shape, show config drift, apply on approval (ENH-062)
 | ecosystem | Cross-repo ecosystem coordination |
 | initiative | Manage cross-repo initiatives |
 | session | Append a manual narrative entry to today's ecosystem session log |

package/bin/antigravity.js

@@ -29,6 +29,7 @@ const PLUGIN_NAME = 'momentum';
 function copyDirRecursive(src, dest, dryRun, log) {
   const entries = fs.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
+    if (entry.name.startsWith('._') || entry.name === '.DS_Store') continue; // Phase 27 G4 — no AppleDouble litter
     const s = path.join(src, entry.name);
     const d = path.join(dest, entry.name);
     if (entry.isDirectory()) {

package/bin/lanes.js

@@ -18,6 +18,7 @@ const { spawnSync } = require('child_process');
 
 const MOMENTUM_ROOT = path.resolve(__dirname, '..');
 const state = require(path.join(MOMENTUM_ROOT, 'core', 'lanes', 'lib', 'state'));
+const cleanup = require(path.join(MOMENTUM_ROOT, 'core', 'lanes', 'lib', 'cleanup'));
 
 // ─── small helpers ───────────────────────────────────────────────────────
 
@@ -39,7 +40,7 @@ function parseFlags(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--no-worktree' || a === '--rm-worktree' || a === '--execute' ||
-        a === '--force' || a === '--json' || a === '--ack-all') {
+        a === '--force' || a === '--json' || a === '--ack-all' || a === '--no-remote') {
       flags[a.slice(2)] = true;
     } else if (a.startsWith('--')) {
       flags[a.slice(2)] = argv[++i];
@@ -197,7 +198,7 @@ function cmdDone(cwd, argv) {
 function cmdClose(cwd, argv) {
   const { flags, positional } = parseFlags(argv);
   const id = positional[0];
-  if (!id) return fail('usage: momentum lanes close <lane-id> [--rm-worktree]');
+  if (!id) return fail('usage: momentum lanes close <lane-id> [--rm-worktree] [--force] [--no-remote]');
   const anchor = requireAnchor(cwd);
   if (!anchor) return;
   let lane;
@@ -206,10 +207,21 @@ function cmdClose(cwd, argv) {
   } catch (err) {
     return fail(err.message);
   }
-  if (flags['rm-worktree'] && lane.worktree) {
-    const res = git(cwd, 'worktree', 'remove', lane.worktree, '--force');
-    if (res.status === 0) console.log(`✓ worktree removed: ${lane.worktree}`);
-    else console.log(`⚠ could not remove worktree (${res.stderr.trim()}) — remove manually`);
+  // ENH-063: close does FULL cleanup — local + remote branch (default-branch-
+  // safe) + lane state, plus the worktree with --rm-worktree. Best-effort: an
+  // unmerged branch is refused (never force-deleted) but that does not fail close.
+  const res = cleanup.cleanupTarget({
+    cwd,
+    branch: lane.branch,
+    worktree: flags['rm-worktree'] ? lane.worktree : null,
+    laneId: id,
+    deleteRemote: !flags['no-remote'],
+    force: Boolean(flags.force),
+  });
+  const glyph = { removed: '✓', deleted: '✓', cleared: '✓', skipped: 'ℹ', blocked: '⚠' };
+  for (const a of res.actions) console.log(`  ${glyph[a.status] || '·'} ${a.step}: ${a.detail}`);
+  if (!res.ok) {
+    console.log(`⚠ some cleanup refused (${res.blocked.join(', ')}) — e.g. an unmerged branch; rerun with --force only if intended`);
   }
   console.log(`✓ lane '${id}' closed`);
 }
@@ -243,6 +255,13 @@ Usage:
   momentum lanes land <id> [--into <ref>] [--execute] [--force] [--mark-landed]
       --mark-landed      bookkeeping only: record an out-of-band merge that
                          already happened (done + merged lane → landed)
+  momentum lanes cleanup <branch> [--worktree P] [--lane ID] [flags]
+      Remove a spent branch's worktree + branch + lane state, default-branch-safe
+      --no-remote  skip origin delete   --force  allow -D / dirty worktree
+      --dry-run    report only          --keep-state  leave lane dir untouched
+  momentum lanes reconcile [--execute] [--into <ref>] [--json]
+      Sweep landed/merged lanes whose terminal merge happened out-of-band
+      (human/forge) and clean them once verified contained in <ref>
 
 State lives at <git-common-dir>/momentum/lanes — shared by all worktrees,
 untracked, no daemon. Substrate: plain git worktrees by default; treehouse
@@ -287,6 +306,10 @@ function dispatch(argv, cwd) {
       return delegate('signals', 'cmdInbox', rest);
     case 'land':
       return delegate('land', 'cmdLand', rest);
+    case 'cleanup':
+      return delegate('cleanup', 'cmdCleanup', rest);
+    case 'reconcile':
+      return delegate('reconcile', 'cmdReconcile', rest);
     case '--help':
     case '-h':
     case 'help':

package/bin/momentum.js

@@ -451,6 +451,172 @@ function migrateFoundationDocs(srcRoot, target) {
   return result;
 }
 
+/**
+ * Phase 26 — Project Config (ADR-0009).
+ *
+ * init: after the specs skeleton, infer + write `specs/config.md` and the
+ * derived `.momentum/config-cache.json` (only when the file is absent —
+ * re-init leaves an authored file alone).
+ *
+ * upgrade: write inferred config for FOUNDED projects only (charter +
+ * roadmap exist — ADR-0008); unfounded projects author them at /start-project.
+ * When the file exists, refresh the derived cache from the content source of
+ * truth and report any drift on the machine-inferable fields (never clobber
+ * user edits).
+ *
+ * specs/ is user content — the config file is NOT recorded in the managed
+ * manifest (orphan cleanup must never touch it). The cache is gitignored by the
+ * existing `.momentum/*` rule.
+ */
+function installConfig(target, { dryRun, upgradeMode } = {}) {
+  const prefsLib = require('../core/config');
+  const specsDir = path.join(target, 'specs');
+  if (!fileExists(specsDir)) return; // no specs skeleton → nothing to do
+  const prefsPath = path.join(specsDir, 'config.md');
+  const exists = fileExists(prefsPath);
+
+  if (!exists) {
+    // upgrade only writes config for founded projects (migration).
+    if (upgradeMode && !prefsLib.isFounded(target)) return;
+    const prefs = prefsLib.inferConfig(target);
+    if (dryRun) {
+      console.log(`  ✋ would add:     specs/config.md (inferred: language=${prefs.language}, forge=${prefs.git_forge})`);
+      return;
+    }
+    prefsLib.writeConfig(specsDir, prefs, { inferred: true });
+    prefsLib.writeConfigCache(target, prefs);
+    console.log(`  + added:    specs/config.md (inferred: language=${prefs.language}, forge=${prefs.git_forge})`);
+    return;
+  }
+
+  // File exists: refresh the derived cache from the content source of truth.
+  // A present-but-garbage file parses to an all-defaults object; detect that
+  // (zero known keys present in the raw file) and LEAVE it untouched rather
+  // than silently overwriting the user's (broken) content with defaults.
+  const raw = (() => {
+    try {
+      return prefsLib.parseConfigMarkdown(fs.readFileSync(prefsPath, 'utf8'));
+    } catch {
+      return {};
+    }
+  })();
+  const hasAnyKey = prefsLib.KNOWN_KEYS.some((k) => k in raw);
+  if (!hasAnyKey) {
+    console.log(`  ⚠️  specs/config.md exists but is empty/unparseable — left untouched (fix or delete it)`);
+    return;
+  }
+  const stored = prefsLib.readConfig(specsDir);
+  if (!dryRun) prefsLib.writeConfigCache(target, stored);
+
+  // Drift detection (upgrade only, founded only): report changed inferable
+  // fields and point at the approval-gated fix. Never clobber user edits —
+  // the user applies the change explicitly via `momentum config sync`.
+  if (upgradeMode && prefsLib.isFounded(target)) {
+    const inferred = prefsLib.inferConfig(target);
+    const drifted = prefsLib.INFERABLE_KEYS.filter((k) => !prefsLib.valuesEqual(inferred[k], stored[k]));
+    if (drifted.length) {
+      console.log(`  ⚠️  specs/config.md drifted from manifests on: ${drifted.join(', ')} — run 'momentum config sync' to review + apply`);
+    }
+  }
+}
+
+/**
+ * Ask the user a single question and resolve with their trimmed answer.
+ * Works whether stdin is a TTY or piped (tests pipe input). On EOF without an
+ * answer, resolves to the empty string so callers can treat it as "skip".
+ * @param {string} query
+ * @returns {Promise<string>}
+ */
+function askQuestion(query) {
+  const readline = require('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      rl.close();
+      resolve(v);
+    };
+    // EOF (piped stdin, no answer) resolves to '' so callers treat it as skip.
+    rl.on('close', () => finish(''));
+    rl.question(query, (answer) => finish((answer || '').trim()));
+  });
+}
+
+/**
+ * ENH-062 — proactive, approval-gated config drift sync. Re-infers the project
+ * shape and diffs it against specs/config.md. When drift is found, shows the
+ * per-field old→new diff and asks the user which fields to apply (or "all" /
+ * "skip"). Nothing is written without explicit approval.
+ * @param {string} targetDir
+ * @param {object} [opts] { dryRun }
+ */
+async function syncConfig(targetDir, opts = {}) {
+  const prefsLib = require('../core/config');
+  const specsDir = path.join(targetDir, 'specs');
+  if (!fileExists(specsDir)) {
+    console.log('  ⚠️  no specs/ skeleton — run momentum init first');
+    return;
+  }
+  const { exists, drift } = prefsLib.diffConfig(specsDir, targetDir);
+
+  if (!exists) {
+    // Migration: a founded project with no config.md yet → create it.
+    if (prefsLib.isFounded(targetDir)) {
+      if (opts.dryRun) {
+        const p = prefsLib.inferConfig(targetDir);
+        console.log(`  ✋ would add:     specs/config.md (inferred: language=${p.language}, forge=${p.git_forge})`);
+        return;
+      }
+      const prefs = prefsLib.inferConfig(targetDir);
+      prefsLib.writeConfig(specsDir, prefs, { inferred: true });
+      prefsLib.writeConfigCache(targetDir, prefs);
+      console.log(`  + added:    specs/config.md (inferred: language=${prefs.language}, forge=${prefs.git_forge})`);
+    } else {
+      console.log('  ⚠️  project not founded — run /start-project to author specs/config.md');
+    }
+    return;
+  }
+
+  if (drift.length === 0) {
+    console.log('  ✓ specs/config.md matches the inferred project shape — nothing to sync');
+    return;
+  }
+
+  console.log('\n  Project shape changed since specs/config.md was written:\n');
+  for (const d of drift) {
+    console.log(`    • ${d.key}: ${JSON.stringify(d.old)} → ${JSON.stringify(d.new)}`);
+  }
+  console.log('');
+
+  if (opts.dryRun) {
+    console.log(`  ✋ would sync ${drift.length} field(s) — re-run without --dry-run to apply`);
+    return;
+  }
+
+  const answer = await askQuestion('  Apply? [a]ll / comma-separated keys / [s]kip: ');
+  const a = answer.toLowerCase();
+  if (a === 's' || a === '' || a === 'skip') {
+    console.log('  ↩️  skipped — specs/config.md left unchanged');
+    return;
+  }
+  let keys;
+  if (a === 'a' || a === 'all' || a === 'y' || a === 'yes') {
+    keys = drift.map((d) => d.key);
+  } else {
+    const wanted = new Set(a.split(',').map((s) => s.trim()));
+    keys = drift.filter((d) => wanted.has(d.key)).map((d) => d.key);
+    if (keys.length === 0) {
+      console.log('  ↩️  no matching keys — specs/config.md left unchanged');
+      return;
+    }
+  }
+  const updated = prefsLib.mergeConfigDrift(specsDir, targetDir, keys);
+  console.log(`  ✓ synced ${keys.join(', ')} → specs/config.md (cache refreshed)`);
+  return updated;
+}
+
 function removeOrphans(targetDir, prevManifest, currentSet, opts = {}) {
   if (!prevManifest || !Array.isArray(prevManifest.managedFiles)) return [];
   const currentRel = new Set(
@@ -1038,10 +1204,17 @@ function init(targetDir, agent, opts = {}) {
   const specsSrc = path.join(src, 'core', 'specs-templates');
   copyDir(specsSrc, target, {
     skipIfExists: true,
-    skipRelPaths: new Set(['CLAUDE.md']),
+    // CLAUDE.md is adapter-owned (written separately); config.md is
+    // inferred per-project by installConfig (Phase 26) — neither is
+    // copied as a static template.
+    skipRelPaths: new Set(['CLAUDE.md', 'config.md']),
     record: false, // specs are install-once / user-owned — never orphan them
   });
 
+  // Phase 26 — infer + write specs/config.md + the derived hook cache.
+  console.log('→ Inferring project config...');
+  installConfig(target, { dryRun: _dryRun });
+
   installPrimaryInstruction(src, target, adapterDir, adapter.primaryInstruction);
 
   // Adapter overlay — per-agent commands/agent-rules/scripts (additive)
@@ -1243,6 +1416,12 @@ function upgrade(targetDir, agent, opts = {}) {
     console.log('  = no untouched placeholders (foundation docs are authored or absent)');
   }
 
+  // Phase 26 — project config (ADR-0009). Founded projects get an
+  // inferred specs/config.md on first upgrade; existing files get their
+  // derived cache refreshed + drift reported (never clobbered).
+  console.log('→ Inferring project config...');
+  installConfig(target, { dryRun: _dryRun, upgradeMode: true });
+
   // Orphan cleanup — only remove files this agent's prior version installed
   // that this version no longer ships. Other agents' files are untouched.
   orphans = removeOrphans(target, { managedFiles: prevAgentFiles }, _managedCollector, {
@@ -1441,6 +1620,7 @@ Ecosystem use — entry/exit commands (run from any repo):
                                       existing ecosystem
   momentum leave                      Detach THIS repo from its ecosystem
   momentum doctor                     Diagnose state + list available transitions
+  momentum doctor --clean [--execute] Sweep stray artifacts (AppleDouble/.bak/orphan worktrees)
   momentum antigravity plugin-pack    Pack momentum skills as a native Antigravity plugin ([--global])
 
 Ecosystem use — operator toolkit (advanced):
@@ -1471,6 +1651,7 @@ Waves — wave plan from dependency annotations (Phase 21c, one engine every sca
 OKF — specs/ as an Open Knowledge Format bundle (Phase 24, ADR-0005):
   momentum okf check [dir]            OKF v0.1 conformance report for <dir>/specs
   momentum okf index [dir]            Regenerate bundle indexes (root/phases/decisions)
+  momentum config sync [target-dir]   Re-infer project shape, show config drift, apply on approval
 
 Options:
   --agent <name>                      Agent to install for. \`init\` asks when this
@@ -1919,6 +2100,22 @@ async function main() {
       console.error(`\nError: ${err.message}`);
       exitCode = 1;
     }
+  } else if (args[0] === 'config') {
+    try {
+      const sub = args[1];
+      const target = args[2] ? path.resolve(args[2]) : process.cwd();
+      if (sub === 'sync') {
+        const dryRun = args.includes('--dry-run') || _dryRun;
+        await syncConfig(target, { dryRun });
+      } else {
+        console.error(`Unknown config subcommand: ${sub || '(none)'}`);
+        console.error('Usage: momentum config sync [target-dir] [--dry-run]');
+        exitCode = 1;
+      }
+    } catch (err) {
+      console.error(`\nError: ${err.message}`);
+      exitCode = 1;
+    }
   } else {
     console.error(`Unknown command: ${args[0]}`);
     console.error('Run "momentum --help" for usage.');

package/bin/state-commands.js

@@ -129,8 +129,103 @@ function cmdLeave(args) {
   console.log(`✓ Left "${reg.ecosystemName}". Now standalone.`);
 }
 
+// ── Phase 27 G4 — stray-artifact sweep (`momentum doctor --clean`) ──────────
+
+const BAK_ROOTS = ['.claude', '.agents', '.opencode', '.codex', '.githooks', 'scripts'];
+
+/** Bounded walk collecting AppleDouble sidecars anywhere (always junk). */
+function walkAppleDouble(dir, acc, depth) {
+  if (depth > 8) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (e.name === '.git' || e.name === 'node_modules') continue;
+    const abs = path.join(dir, e.name);
+    if (e.name.startsWith('._') || e.name === '.DS_Store') { acc.appleDouble.push(abs); continue; }
+    if (e.isDirectory()) walkAppleDouble(abs, acc, depth + 1);
+  }
+}
+
+/** `.bak` files under a momentum-managed root only (never user backups). */
+function collectBaks(dir, acc, depth) {
+  if (depth > 8) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) collectBaks(abs, acc, depth + 1);
+    else if (e.name.endsWith('.bak')) acc.baks.push(abs);
+  }
+}
+
+/** Find stray artifacts: AppleDouble, momentum `.bak` litter, orphan worktrees. */
+function findStrayArtifacts(root) {
+  const { spawnSync } = require('child_process');
+  const acc = { appleDouble: [], baks: [], prunableWorktrees: [], orphanWorktreeDirs: [] };
+  walkAppleDouble(root, acc, 0);
+  for (const sub of BAK_ROOTS) collectBaks(path.join(root, sub), acc, 0);
+  for (const f of ['CLAUDE.md.bak', 'AGENTS.md.bak']) {
+    const p = path.join(root, f);
+    if (fs.existsSync(p)) acc.baks.push(p);
+  }
+  // registered worktrees whose directory is gone → prunable
+  const registered = new Set();
+  const wl = spawnSync('git', ['worktree', 'list', '--porcelain'], { cwd: root, encoding: 'utf8' });
+  if (wl.status === 0) {
+    for (const line of wl.stdout.split('\n')) {
+      if (line.startsWith('worktree ')) {
+        const p = line.slice('worktree '.length);
+        registered.add(realpathOf(p));
+        if (p !== root && !fs.existsSync(p)) acc.prunableWorktrees.push(p);
+      }
+    }
+  }
+  // .claude/worktrees/* leftover dirs not registered as git worktrees
+  const cw = path.join(root, '.claude', 'worktrees');
+  try {
+    for (const name of fs.readdirSync(cw)) {
+      const abs = path.join(cw, name);
+      if (fs.statSync(abs).isDirectory() && !registered.has(realpathOf(abs))) acc.orphanWorktreeDirs.push(abs);
+    }
+  } catch { /* no .claude/worktrees */ }
+  return acc;
+}
+
+function sweepStrayArtifacts(root, execute) {
+  const { spawnSync } = require('child_process');
+  const stray = findStrayArtifacts(root);
+  const total = stray.appleDouble.length + stray.baks.length
+    + stray.prunableWorktrees.length + stray.orphanWorktreeDirs.length;
+  const rel = (p) => path.relative(root, p) || p;
+
+  console.log(execute ? 'Cleaning stray artifacts:' : 'Stray artifacts (dry-run — pass --execute to remove):');
+  if (total === 0) { console.log('  ✓ none — tree is clean'); return 0; }
+
+  for (const p of stray.appleDouble) {
+    if (execute) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* ignore */ } }
+    console.log(`  ${execute ? '✓ removed' : '·'} AppleDouble: ${rel(p)}`);
+  }
+  for (const p of stray.baks) {
+    if (execute) { try { fs.rmSync(p, { force: true }); } catch { /* ignore */ } }
+    console.log(`  ${execute ? '✓ removed' : '·'} .bak: ${rel(p)}`);
+  }
+  for (const p of stray.orphanWorktreeDirs) {
+    if (execute) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* ignore */ } }
+    console.log(`  ${execute ? '✓ removed' : '·'} orphan worktree dir: ${rel(p)}`);
+  }
+  if (stray.prunableWorktrees.length) {
+    if (execute) spawnSync('git', ['worktree', 'prune'], { cwd: root });
+    for (const p of stray.prunableWorktrees) console.log(`  ${execute ? '✓ pruned' : '·'} stale worktree ref: ${rel(p)}`);
+  }
+  console.log(execute ? `✓ cleaned ${total} stray artifact(s)` : `${total} stray artifact(s) — rerun with --execute to remove`);
+  return 0;
+}
+
 function cmdDoctor(args) {
-  void args;
+  // Phase 27 G4 — `momentum doctor --clean [--execute]` sweeps stray artifacts.
+  if (args && args.includes('--clean')) {
+    return sweepStrayArtifacts(realpathOf(process.cwd()), args.includes('--execute'));
+  }
   const cwd = realpathOf(process.cwd());
   lib._clearRootCache();
   const state = stateLib.detectState(cwd);
@@ -176,6 +271,17 @@ function cmdDoctor(args) {
     }
   } catch (_err) { /* advisory is best-effort — never block doctor */ }
 
+  // Phase 27 G4 — stray-artifact advisory (best-effort, non-blocking).
+  try {
+    const stray = findStrayArtifacts(cwd);
+    const n = stray.appleDouble.length + stray.baks.length
+      + stray.prunableWorktrees.length + stray.orphanWorktreeDirs.length;
+    if (n > 0) {
+      console.log(`Advisory: ${n} stray artifact(s) (AppleDouble / .bak / orphan worktrees) — run \`momentum doctor --clean\` to review, \`--clean --execute\` to remove.`);
+      console.log('');
+    }
+  } catch { /* best-effort */ }
+
   const transitions = stateLib.availableTransitions(state, reg || {});
   if (transitions.length === 0) {
     console.log('No suggested next steps for this state.');
@@ -215,4 +321,6 @@ module.exports = {
   cmdLeave,
   cmdDoctor,
   formatStateLabel,
+  findStrayArtifacts,
+  sweepStrayArtifacts,
 };

package/core/commands/brainstorm-idea.md

@@ -44,6 +44,25 @@ When you're ready to turn the result into a project, run `/start-project` — it
 
 4. Iterate until the idea is clear.
 
+4b. **Config discovery** — once the idea is settled, gather the
+    project-shape config that `/start-project` will author into
+    `specs/config.md` (ADR-0009). Ask one question at a time; if the
+    user is unsure, suggest a default from the idea's context:
+    - **Git forge**: "Which forge? GitHub / GitLab / Bitbucket / Gitea /
+      Forgejo / bare-ssh?" (default from `git remote get-url origin` if a
+      repo exists, else GitHub)
+    - **Language + framework**: "What language/framework? Node+Next.js /
+      Python+FastAPI / Rust+Actix / Go / …?" (default from manifests if a
+      repo exists, else ask)
+    - **Publish/deploy target**: "How does this ship? npm publish / pypi /
+      crates.io / deploy-only (Vercel/Fly/…) / none?" (sets `publish_target`
+      + `release_flow`)
+    - **Branch flow**: "How do changes land? feature → staging → main /
+      feature → main / feature-branch-only?" (sets `branch_flow` +
+      `end_state`; default `feature → staging → main`)
+    Carry the settled config as context into `/start-project` so it
+    authors `specs/config.md` alongside the charter/roadmap in one batch.
+
 5. **Exit the brainstorm gate** before any follow-up command:
    ```bash
    rm .momentum/brainstorm-active

package/core/commands/brainstorm-phase.md

@@ -34,6 +34,13 @@ The brainstorm output IS the phase files — there is no intermediate design doc
    - Read `specs/planning/roadmap.md` — what's the next planned phase?
    - Is the planned phase still the right next step given what was learned?
 
+2b. Read verification defaults from config:
+    - Read `specs/config.md` (`core/config.js` → `readConfig('specs')`)
+      for `test_command` and `build_command`. When absent, default to
+      `npm test` / no build. Use these as the default verification commands in
+      the phase's deliverables table (overview.md) unless the phase needs
+      something different — call out any deviation explicitly.
+
 3. Define scope with the user (one question at a time):
    - What is the goal of this phase?
    - What are the key deliverables?