@limina-labs/momentum 0.31.2 → 0.33.0

package/README.md

@@ -82,6 +82,12 @@ Work happens in **phases** — one repeatable unit of work, five stages:
 
 **Brainstorm → Plan → Execute → Verify → Release**
 
+New projects begin with a one-time **founding** step: `/brainstorm-idea`
+explores the idea (writes nothing), then `/start-project` authors the
+charter, principles, success criteria, and roadmap from that brainstorm —
+momentum never ships placeholder docs, and phase commands wait until the
+project is founded.
+
 Your agent drives all of it: scopes through dialogue (disk writes gated until
 you approve), plans groups + tasks + acceptance criteria, commits per group
 with conventional commits, and marks tasks done only with passing evidence.
@@ -176,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

@@ -14,7 +14,8 @@
 | What's in the backlog? | `specs/backlog/backlog.md` |
 | Phase tasks/progress? | `specs/phases/phase-N-*/tasks.md` |
 | Why was X chosen? | `specs/decisions/NNNN-*.md` |
-| Roadmap / timeline? | `specs/planning/roadmap.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`.**
@@ -184,6 +185,10 @@ Before ANY work, read `specs/status.md`. This tells you:
 - What's blocking progress
 - What P0 items need attention
 
+If `status.md` says **Not founded**, stop: the project has no charter or
+roadmap yet — foundation docs are authored at founding, never scaffolded
+(`core/project-lifecycle.md`). Route to `/start-project` before any phase work.
+
 ### Rule 2: Auto-Update Tracking After Changes
 
 After completing ANY meaningful work, automatically update:

package/adapters/codex/instructions/AGENTS.md

@@ -14,7 +14,8 @@
 | What's in the backlog? | `specs/backlog/backlog.md` |
 | Phase tasks/progress? | `specs/phases/phase-N-*/tasks.md` |
 | Why was X chosen? | `specs/decisions/NNNN-*.md` |
-| Roadmap / timeline? | `specs/planning/roadmap.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 |
@@ -237,6 +239,10 @@ Before ANY work, read `specs/status.md`. This tells you:
 - What's blocking progress
 - What P0 items need attention
 
+If `status.md` says **Not founded**, stop: the project has no charter or
+roadmap yet — foundation docs are authored at founding, never scaffolded
+(`core/project-lifecycle.md`). Route to `/start-project` before any phase work.
+
 ### Rule 2: Auto-Update Tracking After Changes
 
 After completing ANY meaningful work, automatically update:

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/instructions/AGENTS.md

@@ -14,7 +14,8 @@
 | What's in the backlog? | `specs/backlog/backlog.md` |
 | Phase tasks/progress? | `specs/phases/phase-N-*/tasks.md` |
 | Why was X chosen? | `specs/decisions/NNNN-*.md` |
-| Roadmap / timeline? | `specs/planning/roadmap.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 |
@@ -150,6 +152,10 @@ Before ANY work, read `specs/status.md`. This tells you:
 - What's blocking progress
 - What P0 items need attention
 
+If `status.md` says **Not founded**, stop: the project has no charter or
+roadmap yet — foundation docs are authored at founding, never scaffolded
+(`core/project-lifecycle.md`). Route to `/start-project` before any phase work.
+
 ### Rule 2: Auto-Update Tracking After Changes
 
 After completing ANY meaningful work, automatically update:

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/momentum.js

@@ -404,6 +404,219 @@ function migrateAgentRules(srcRoot, target, dests) {
   return 'kept-customized';
 }
 
+/**
+ * Foundation docs are authored, not scaffolded (Phase 25 / ADR-0008).
+ * Legacy installs (≤ v0.31.2) shipped four placeholder foundation docs
+ * (vision/charter/principles/success-criteria + planning/roadmap.md). A copy
+ * whose frontmatter-stripped, whitespace-normalized body sha256 matches a
+ * historically shipped template (core/foundation-placeholder-hashes.json —
+ * frozen forever) carries provably zero user content: remove it, returning
+ * the project to the clean "not founded" signal that /start-project fills.
+ * Any file with user edits is untouched. specs/ is user content — never
+ * recorded in the managed manifest, so orphan cleanup can never touch it.
+ * Returns { removed: [rel], wouldRemove: [rel], keptAuthored, absent }.
+ */
+function migrateFoundationDocs(srcRoot, target) {
+  const crypto = require('crypto');
+  const manifest = JSON.parse(
+    fs.readFileSync(
+      path.join(srcRoot, 'core', 'foundation-placeholder-hashes.json'),
+      'utf8'
+    )
+  );
+  const result = { removed: [], wouldRemove: [], keptAuthored: 0, absent: 0 };
+  for (const [rel, hashes] of Object.entries(manifest.paths)) {
+    const abs = path.join(target, ...rel.split('/'));
+    if (!fileExists(abs)) { result.absent++; continue; }
+    // Normalization mirrors the manifest's recorded contract exactly:
+    // CRLF→LF, strip one leading YAML frontmatter block, trim, single \n.
+    let body = fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n');
+    body = body.replace(/^---\n[\s\S]*?\n---\n/, '');
+    body = body.trim() + '\n';
+    const hash = crypto.createHash('sha256').update(body).digest('hex');
+    if (!hashes.includes(hash)) { result.keptAuthored++; continue; }
+    if (_dryRun) {
+      console.log(`  ✋ would remove: ${rel} (untouched init placeholder — foundation docs are authored via /start-project, ADR-0008)`);
+      result.wouldRemove.push(rel);
+      continue;
+    }
+    fs.rmSync(abs);
+    try { fs.rmdirSync(path.dirname(abs)); } catch { /* dir not empty — fine */ }
+    console.log(`  🗑  removed: ${rel} (untouched init placeholder — foundation docs are authored via /start-project)`);
+    result.removed.push(rel);
+  }
+  if (result.removed.length || result.wouldRemove.length) {
+    console.log('  → project is not yet founded — run /start-project to author the foundation docs.');
+  }
+  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(
@@ -991,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)
@@ -1023,13 +1243,13 @@ function init(targetDir, agent, opts = {}) {
   console.log('Next steps:');
   console.log('');
   const displayName = adapter.displayName || agent;
-  console.log('  Explore an idea first:');
+  console.log('  Explore the idea first (writes nothing):');
   console.log(`    Open ${displayName} and run: /brainstorm-idea`);
   console.log('');
-  console.log('  Ready to scaffold a project:');
+  console.log('  Found the project — author the charter + roadmap, plan Phase 0:');
   console.log(`    Open ${displayName} and run: /start-project`);
   console.log('');
-  console.log('  Existing project — plan your next phase:');
+  console.log('  Already founded — plan your next phase:');
   console.log(`    Open ${displayName} and run: /brainstorm-phase`);
   console.log('');
   console.log('  See docs: https://github.com/LiminaLabsAI/momentum');
@@ -1068,7 +1288,7 @@ function upgrade(targetDir, agent, opts = {}) {
 
   _dryRun = !!opts.dryRun;
   _managedCollector = new Set();
-  let agentRulesResult, primaryInstructionResult, gitignoreResult, orphans = [];
+  let agentRulesResult, primaryInstructionResult, gitignoreResult, foundationResult, orphans = [];
   try {
   // Upgrade slash commands
   console.log('→ Upgrading slash commands...');
@@ -1188,6 +1408,20 @@ function upgrade(targetDir, agent, opts = {}) {
   console.log('→ Refreshing .gitignore...');
   gitignoreResult = refreshGitignore(src, target);
 
+  // Foundation docs — authored, not scaffolded (Phase 25 / ADR-0008).
+  // Remove provably-untouched init placeholders; authored files stay.
+  console.log('→ Checking foundation docs (authored, not scaffolded)...');
+  foundationResult = migrateFoundationDocs(src, target);
+  if (!foundationResult.removed.length && !foundationResult.wouldRemove.length) {
+    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, {
@@ -1223,6 +1457,9 @@ function upgrade(targetDir, agent, opts = {}) {
   }
   console.log(`  agent-rules:         ${agentRulesResult}`);
   console.log(`  .gitignore:          ${gitignoreResult}`);
+  if (foundationResult && foundationResult.removed.length) {
+    console.log(`  foundation docs:     removed ${foundationResult.removed.length} untouched placeholder(s) — not yet founded; run /start-project`);
+  }
   if (orphans.length) {
     console.log(`  removed (orphaned):  ${orphans.length} file(s) — see 🗑 lines above`);
   }
@@ -1413,6 +1650,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
@@ -1861,6 +2099,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/core/commands/brainstorm-idea.md

@@ -2,7 +2,7 @@ Explore any idea through structured dialogue before committing to anything.
 
 Use this to think through a concept, technical direction, product decision, or architecture question. **Nothing gets written to disk.** The output is a clear, structured summary you can act on.
 
-When you're ready to turn the result into a project, run `/start-project`. To turn a decision into an ADR, run `/log` with `--decision`.
+When you're ready to turn the result into a project, run `/start-project` — it **founds** the project: authors the charter, principles, success criteria, and roadmap from this brainstorm and plans Phase 0. It works whether or not `momentum init` has already scaffolded the machinery (structure ≠ content — see `core/project-lifecycle.md`). To turn a decision into an ADR, run `/log` with `--decision`.
 
 ## When to use
 
@@ -44,13 +44,32 @@ When you're ready to turn the result into a project, run `/start-project`. To tu
 
 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
    ```
 
 6. Close with one of:
-   - "Ready to build this? Run `/start-project` to scaffold it as a project."
+   - "Ready to build this? Run `/start-project` to found the project — it authors the foundation docs (charter, principles, success criteria, roadmap) from this brainstorm and plans Phase 0. An existing `momentum init` scaffold doesn't change this: init owns structure, founding owns content."
    - "Want to explore further before committing? Ask away."
    - "This is a decision, not a project — want to log it as an ADR with `/log --decision`?"
 

package/core/commands/brainstorm-phase.md

@@ -18,6 +18,14 @@ The brainstorm output IS the phase files — there is no intermediate design doc
    From this point until Step 8, do NOT call any write-class tool on any path under `specs/`. The PreToolUse hook (`core/scripts/brainstorm-gate.sh`, wired by Claude Code + Codex + Antigravity) will block such calls; this step makes the intent explicit.
 
 1. Review current state:
+   - **Founded gate first** (`core/project-lifecycle.md`, ADR-0008): verify
+     `specs/vision/project-charter.md` AND `specs/planning/roadmap.md` exist.
+     If either is missing, the project is NOT founded — STOP: remove the
+     sentinel (`rm .momentum/brainstorm-active`) and route to
+     `/start-project`, offering to draft the foundation docs with the user
+     from the context already in this conversation (best-effort content
+     marked for refinement beats absent docs). Re-run this command once
+     founded. Never plan a phase on an unfounded project.
    - Read `specs/status.md` — what phase just completed?
    - Read the completed phase's `history.md` — what was learned?
    - Read `specs/backlog/backlog.md` — any P0/P1 items to address first?
@@ -26,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?

package/core/commands/complete-phase.md

@@ -18,6 +18,11 @@ Verify, finalize, and release a completed phase.
    - If any `[ ]` unchecked items remain → report to user, do NOT proceed
 
 3. **Run project-specific validation and capture fresh evidence** (per Rule 12 — Verify Before Claim):
+   - Read `specs/config.md` (`core/config.js` → `readConfig('specs')`)
+     for `test_command` and `build_command`. When the file is absent or a
+     value is missing, fall back to `npm test` / no build (the historical
+     defaults). Run `test_command` always; run `build_command` when it is not
+     `none`.
    - Run all defined validation commands: tests, linting, type checks, build, smoke tests
    - Capture each command's stdout/stderr (e.g., redirect to a temp file with `tee`)
    - Note exit codes
@@ -67,49 +72,62 @@ Verify, finalize, and release a completed phase.
    git push origin phase-N-shortname
    ```
 
-9. Ask the user ONCE for approval to release — present the full plan:
+9. Ask the user ONCE for approval to release — present the full plan, walking
+   the project's `branch_flow` (from `specs/config.md`; default
+   `[staging, main]`) in order. The plan stops at the universal git primitives
+   (`git merge` + `git tag -a` + `git push origin <tag>`); forge-specific
+   release creation and registry publishes are NOT listed here — they run
+   from `## Project Extensions` + `specs/config.md` (`release_command`,
+   `publish_target`, `release_flow`) after the tag is pushed.
    ```
    Ready to release vX.Y.Z. This will:
-     1. Merge phase-N-shortname → staging
-     2. Merge staging → main
-     3. Tag vX.Y.Z and create GitHub Release
+     1. Merge phase-N-shortname → <branch_flow[0]> (e.g. staging)
+     2. …promote through <branch_flow[1..]> (e.g. main)
+     3. Tag vX.Y.Z and push the tag
+
+   Project-specific release/publish/deploy (forge release, npm publish, …)
+   run from ## Project Extensions + specs/config.md after the tag lands.
 
    Proceed?
    ```
    Wait for a single "yes" before running any of the following steps.
 
-10. On approval, execute all three steps in sequence.
+10. On approval, execute the merge sequence + tag in order.
 
     **Landing Order (Rule 6/15):** if another lane landed on `main` since
     this branch last rebased, rebase this branch onto updated `main` and
     re-run the suite BEFORE merging. Never land two lanes back-to-back
     without the suite passing in between.
 
+    Walk `branch_flow` (default `[staging, main]`) hop by hop — one merge per
+    protected branch in order, approval covered by the single "yes" above:
     ```bash
-    # step 1 — phase branch → staging
-    git checkout staging && git pull origin staging
-    git merge --no-ff phase-N-shortname -m "merge: phase-N-shortname → staging (vX.Y.Z)"
-    git push origin staging
-
-    # step 2 — staging → main
-    git checkout main && git pull origin main
-    git merge --no-ff staging -m "merge: staging → main (vX.Y.Z — Phase N: {phase name})"
-    git push origin main
-
-    # step 3 — tag + GitHub Release
+    # step 1 — phase branch → branch_flow[0]
+    git checkout <branch_flow[0]> && git pull origin <branch_flow[0]>
+    git merge --no-ff phase-N-shortname -m "merge: phase-N-shortname → <branch_flow[0]> (vX.Y.Z)"
+    git push origin <branch_flow[0]>
+
+    # step 2.. — promote through each remaining branch_flow entry
+    #   (e.g. staging → main)
+    git checkout <branch_flow[1]> && git pull origin <branch_flow[1]>
+    git merge --no-ff <branch_flow[0]> -m "merge: <branch_flow[0]> → <branch_flow[1]> (vX.Y.Z — Phase N: {phase name})"
+    git push origin <branch_flow[1]>
+
+    # final step — tag + push the tag (universal git; forge release + publish
+    # are project-specific — run them from ## Project Extensions now)
     git tag -a vX.Y.Z -m "Phase N: {phase name}"
     git push origin vX.Y.Z
-    gh release create vX.Y.Z \
-      --title "vX.Y.Z — Phase N: {phase name}" \
-      --notes "## Phase N: {phase name}
-    {bullet summary of what was delivered}
-    ### Next: Phase N+1 — {next phase name}" \
-      --target main
     ```
+    For `end_state: feature-branch-only` (config), SKIP the merge
+    sequence — the branch is already pushed; only tag (if the project tags
+    releases on the feature branch) per `## Project Extensions`. For
+    `end_state: staging-promotion`, merge to `branch_flow[0]` only and stop;
+    tag + release happen after the user promotes to `main`.
 
 12. Report summary to user:
     - What was delivered
-    - GitHub Release URL
+    - Tag URL (`git push origin vX.Y.Z` output) — forge release/publish
+      status from `## Project Extensions` if any ran
     - What's next
 
 13. Delete the merged phase branch (ENH-042 — now that merge → main + release

package/core/commands/migrate.md

@@ -22,6 +22,12 @@ This command fills gaps without overwriting anything the project already has.
    `brainstorm-idea`, `brainstorm-phase`, `start-project`, `start-phase`, `complete-phase`,
    `log`, `sync-docs`, `track`, `migrate`, `validate`
 
+   **Foundation docs are NOT migration gaps** (`core/project-lifecycle.md`,
+   ADR-0008): `specs/vision/*` and `specs/planning/roadmap.md` are authored
+   via `/start-project`, never copied from templates. If they're missing,
+   report "not founded — run `/start-project`" in the result; do NOT create
+   them here.
+
 2. **Report gap summary** — present findings before making any changes:
    ```
    Found: 8 / Missing: 4 items
@@ -64,6 +70,7 @@ This command fills gaps without overwriting anything the project already has.
    ✓ Migration complete.
    Added: 4 items
    Skipped: 6 items (already existed — not overwritten)
+   Founded: no — charter/roadmap missing; run /start-project to author them
    Needs manual attention:
      - 3 phases marked status 'unknown' in overview.md frontmatter — verify manually
      - specs/status.md: already exists — verify Current Phase matches the phase frontmatter