@limina-labs/momentum 0.32.0 → 0.33.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/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/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/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, {
@@ -1471,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
@@ -1919,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

@@ -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?

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/start-phase.md

@@ -119,9 +119,33 @@ Once a phase plan is approved, this command executes the plan end-to-end without
 
 ### Hard stop — always
 
-**Merge to staging/main + release.** After the final group's verification passes, STOP. Ask the user:
-
-> "All groups complete and verified. Ready to merge `<phase-branch>` → staging (then main), tag `v<version>`, and run `npm publish --access public`. Approve to proceed?"
+**Merge to a protected branch + release.** After the final group's
+verification passes, STOP. Read the project's config
+(`specs/config.md` via `core/config.js` →
+`readConfig('<repo>/specs')`; returns `null` when absent → use the
+defaults below) and ask the user the gate question matching the project's
+`end_state`:
+
+- **`merge-after-yes`** (default): "All groups complete and verified. Ready
+  to merge `<phase-branch>` → `<branch_flow in order>` (e.g. `staging`, then
+  `main`), tag `v<version>`. Approve to proceed?"
+- **`staging-promotion`**: "All groups complete and verified. Ready to merge
+  `<phase-branch>` → `staging`. Tag `v<version>` + release after you promote
+  to `main`. Approve to proceed?"
+- **`feature-branch-only`**: "All groups complete and verified. The feature
+  branch `<phase-branch>` is pushed. Merge, tag, and release are yours to
+  do. Review the branch?"
+
+Then append: "Project-specific release/publish/deploy steps (e.g.
+`npm publish`, forge release creation) run from `## Project Extensions` in
+CLAUDE.md/AGENTS.md — consult them now if any apply."
+
+The gate stops at the truly universal git primitives — `git merge` +
+`git tag -a` + `git push origin <tag>`. Forge-specific release creation
+(`gh release create`, `glab release create`, …) and registry publishes
+(`npm publish`, `twine upload`, …) are NOT in this template; they live in
+`## Project Extensions` + `specs/config.md` (`release_command`,
+`publish_target`, `release_flow`).
 
 This is the only place the engine asks. Do NOT skip it.
 

package/core/commands/start-project.md

@@ -51,14 +51,20 @@ If you're still exploring the idea, run `/brainstorm-idea` first.
    - `status.md` Summary paragraph (what this project is)
    - For monorepo: first-pass architecture sketch (core abstractions, interfaces)
    - Phase 0 contents using the [Group Execution Pattern](#group-execution-pattern)
+   - **Config** (`specs/config.md`, ADR-0009): the project-shape
+     settings recipe templates read at execution time (forge, publish target,
+     branch flow, verification commands — see the [Config Format](#config-format)).
+     Carry the values settled during `/brainstorm-idea`; when `momentum init`
+     already inferred them, confirm the inferred file. `protected_branches`
+     is derived from `branch_flow`.
    - Use the [Foundation Doc Formats](#foundation-doc-formats) below; author
      real content from the brainstorm — never emit `_(TBD)_` placeholders.
      Where understanding is genuinely thin, write the best-effort version,
      mark the specific line `<!-- refine: ... -->`, and ask the user.
 
 4. Present the founding draft for approval:
-   - Show the charter, roadmap, and key Phase 0 sections in chat
-   - List every file that will be created
+   - Show the charter, roadmap, config table, and key Phase 0 sections in chat
+   - List every file that will be created (including `specs/config.md`)
    - Ask: "Ready to found the project? This will write N files. Approve to proceed."
 
 5. **On approval — exit the gate**:
@@ -71,12 +77,17 @@ If you're still exploring the idea, run `/brainstorm-idea` first.
    - `specs/vision/principles.md`
    - `specs/vision/success-criteria.md`
    - `specs/planning/roadmap.md`
+   - `specs/config.md` (from the config table above; overwrite the
+     `momentum init`-inferred file if present — founding owns the content)
    - Update `specs/status.md`: Summary, Current Phase (Phase 0 `not started`),
      Upcoming Phases, Next Actions
    - For monorepo: `specs/architecture/` first-pass doc(s)
    - `specs/phases/phase-0-shortname/{overview,plan,tasks,history}.md`
      (log the founding decisions from this conversation in `history.md`)
-   - Refresh bundle listings: `momentum okf index`
+   - Refresh the derived cache: `core/config.js` →
+     `writeConfigCache('.', readConfig('specs'))` so the pre-push
+     hook's `protected_branches` matches the authored `branch_flow`;
+     then `momentum okf index` to refresh bundle listings
 
 7. Commit the founding:
     ```bash
@@ -202,6 +213,41 @@ type: Roadmap
 
 ---
 
+## Config Format
+
+Author `specs/config.md` in this shape (`type: Config` → OKF bundle).
+Lists (`branch_flow`, `protected_branches`) are comma-separated;
+`protected_branches` is derived from `branch_flow`. The trust layer (human
+authorization for protected-branch pushes) is invariant, NOT a preference
+(ADR-0009); bypass only via `MOMENTUM_SKIP_HOOKS=1`.
+
+```markdown
+---
+type: Config
+---
+
+# Project Config
+
+> Recipes read these at execution time; missing values fall back to npm/GitHub
+> defaults. Edit freely.
+
+| Key | Value |
+|-----|-------|
+| language | node |
+| framework | nextjs |
+| test_command | npm test |
+| build_command | npm run build |
+| publish_target | npm |
+| git_forge | github |
+| release_command | gh release create |
+| release_flow | tag-and-publish |
+| end_state | merge-after-yes |
+| branch_flow | staging, main |
+| protected_branches | staging, main |
+```
+
+---
+
 ## Brainstorm Gate Contract
 
 This command runs in two phases: **brainstorm** (conversational, no disk writes) and **commit** (writes files to disk on explicit approval).

package/core/commands/sync-config.md

@@ -0,0 +1,43 @@
+Sync the project's `specs/config.md` with the project's current shape — review drift and apply on approval.
+
+Momentum infers project shape (language, framework, publish target, git forge)
+from manifests (`package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / …) and
+the git remote. When that shape changes — you switched CI from GitHub Actions to
+GitLab, adopted a framework, renamed the package — `specs/config.md` can drift
+from reality. This command re-infers and shows the difference, then asks before
+writing anything (ENH-062 — approval-gated, never a silent mutation).
+
+## Steps
+
+1. Run:
+   ```
+   momentum config sync
+   ```
+   (pass a `target-dir` to sync a different project; `--dry-run` to preview.)
+
+2. Read the output:
+   - `✓ matches the inferred project shape — nothing to sync` → no drift, done.
+   - A per-field `old → new` list → drift detected.
+
+3. At the prompt, decide:
+   - `a` / `all` → apply every drifted field.
+   - `language,git_forge` (comma-separated keys) → apply only those.
+   - `s` / `skip` / empty → leave `specs/config.md` unchanged.
+
+4. On approval, momentum rewrites `specs/config.md` and refreshes the derived
+   `.momentum/config-cache.json`. The **trust layer is untouched** — protected
+   branches can only ever be *added*, never removed (ADR-0009). Only the
+   inferable fields (`language`, `framework`, `publish_target`, `git_forge`) are
+   ever offered; user-authored fields (`branch_flow`, `end_state`, commands) are
+   never flagged or overwritten.
+
+5. Report to the user what changed (or that nothing changed). If drift was
+   found and skipped, note they can re-run `momentum config sync` any time.
+
+## When to run this proactively
+
+- After a visible project-shape change (new framework, forge move, language
+  bump) — offer to run `/sync-config` rather than silently editing config.
+- `momentum upgrade` prints a drift warning when it detects one; route the user
+  to this command to resolve it.
+- Never auto-edit `specs/config.md` outside this approval flow.

package/core/commands/validate.md

@@ -31,6 +31,20 @@ Run with no arguments for a fast index-first check, or pass `--deep` for a full
      report informationally ("not founded yet — `/start-project` when
      ready"), never as a failure
 
+2c. Config (ADR-0009) — WARNING, never a failure (recipes fall back to
+    npm/GitHub defaults when absent):
+    - founded AND no `specs/config.md` → WARNING: "config not set
+      — recipes will use npm/GitHub defaults; run `momentum upgrade` to
+      infer them, or author at `/start-project`"
+    - `specs/config.md` exists → drift check: compare the
+      machine-inferable fields (`language`, `framework`, `publish_target`,
+      `git_forge`) against the manifests + `git remote get-url origin`
+      (`core/config.js` → `inferConfig('.')` vs
+      `readConfig('specs')`); on mismatch → WARNING: "config
+      drifted from manifests on: <fields> — edit by hand or delete the file
+      + re-run `momentum upgrade`"
+    - Not founded → skip (config author at founding)
+
 3. For each phase directory under `specs/phases/` (OKF bundle, ADR-0005):
    - Verify all 4 files present: `overview.md`, `plan.md`, `tasks.md`, `history.md`
    - Verify `overview.md` frontmatter carries `type: Phase` and a `status:`