@limina-labs/momentum 0.31.2 → 0.32.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.

package/adapters/antigravity/instructions/AGENTS.md

@@ -14,7 +14,7 @@
 | 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`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**
@@ -184,6 +184,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,7 @@
 | 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`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**
@@ -237,6 +237,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/AGENTS.md

@@ -14,7 +14,7 @@
 | 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`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**
@@ -150,6 +150,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/bin/momentum.js

@@ -404,6 +404,53 @@ 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;
+}
+
 function removeOrphans(targetDir, prevManifest, currentSet, opts = {}) {
   if (!prevManifest || !Array.isArray(prevManifest.managedFiles)) return [];
   const currentRel = new Set(
@@ -1023,13 +1070,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 +1115,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 +1235,14 @@ 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)');
+  }
+
   // 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 +1278,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`);
   }

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
 
@@ -50,7 +50,7 @@ When you're ready to turn the result into a project, run `/start-project`. To tu
    ```
 
 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?

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

package/core/commands/start-phase.md

@@ -11,6 +11,12 @@ After setup, **executes the plan end-to-end autonomously** — no per-group appr
 ## Setup Steps (run once at phase start)
 
 1. Read current state:
+   - **Founded gate** (`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 and
+     run `/start-project` first (it authors the foundation docs from your
+     brainstorm and plans Phase 0). Never start a phase on an unfounded
+     project.
    - Read `specs/status.md`
 
 2. Check for blocking bugs (pre-phase bug check):

package/core/commands/start-project.md

@@ -1,83 +1,204 @@
-Scaffold a new project from a clear idea.
+Found the project from a clear idea.
+
+**Founding is about content, not structure** (see `core/project-lifecycle.md`,
+ADR-0008): this command authors the foundation docs — project charter,
+principles, success criteria, roadmap — plus the `status.md` Summary, and
+plans Phase 0. It works on ANY repo state: freshly `momentum init`-ed,
+brand-new/empty, or full of existing code. Structure (directories, commands,
+hooks, tracking skeleton) is owned by `momentum init`, not by this command.
+
+momentum ships **no placeholder foundation docs** — these files do not exist
+until this command writes them. Their absence is the "not founded" signal
+that `/brainstorm-phase`, `/start-phase`, and `/validate` check.
 
-Run this on a NEW or EMPTY repository when you know what you're building.
 If you're still exploring the idea, run `/brainstorm-idea` first.
+**Authoring happens only after you explicitly approve the draft.** See the
+[Brainstorm Gate Contract](#brainstorm-gate-contract) below.
 
-Turns a settled concept into a fully spec-driven project: vision, roadmap, Phase 0 ready to go. **Scaffolding happens only after you explicitly approve the plan.** See the [Brainstorm Gate Contract](#brainstorm-gate-contract) below.
+## When to use
+
+- `momentum init` has run and `specs/status.md` says "Not founded"
+- You just finished `/brainstorm-idea` and the idea is settled
+- An existing codebase adopted momentum and needs its foundation docs written
 
 ## Steps
 
-0. **Enter the brainstorm gate**:
+0. **Check machinery, then enter the brainstorm gate**:
+   - If there is no momentum scaffold (no `.momentum/`, no `specs/status.md`),
+     stop and run `momentum init` first — init owns structure; this command
+     owns content.
    ```bash
    mkdir -p .momentum && touch .momentum/brainstorm-active
    ```
-   From here until Step 8, do NOT call `Write`/`Edit`/`MultiEdit` on any path under `specs/`. The PreToolUse hook will block such calls.
+   From here until Step 6, do NOT call `Write`/`Edit`/`MultiEdit` on any path
+   under `specs/`. The PreToolUse hook will block such calls.
 
-1. Confirm the idea is clear — ask if needed:
-   - What does this project build or do?
+1. Confirm the idea is clear — ask if needed (one question at a time):
+   - What does this project build or do? For whom?
    - What type of repository? (monorepo with architecture specs / standard library or package)
    - What is the primary tech stack / language?
    - Any hard constraints (performance, compliance, dependencies)?
 
 2. Determine repo type from answers:
-   - Monorepo → full architecture constitution in `specs/architecture/`
-   - Standard → implementation tracking only
-
-3. **Plan the scaffold in conversation only** — no file writes yet:
-   - Sketch the vision (charter, principles, success criteria) in chat
-   - For monorepo: sketch initial architecture (core abstractions, interfaces, contracts)
-   - Design the phase roadmap (natural phases, dependencies)
-   - Draft Phase 0 contents using the [Group Execution Pattern](#group-execution-pattern)
-   - List every file that scaffolding will create (paths only — content stays in chat)
-
-4. Present the scaffolding plan for approval:
-   - Show the proposed file list
-   - Show key sections of vision + Phase 0
-   - Ask: "Ready to scaffold? This will create N files. Approve to proceed."
+   - Monorepo → also author an architecture constitution in `specs/architecture/`
+   - Standard → foundation docs + phases only
+
+3. **Draft the foundation in conversation only** — no file writes yet:
+   - Charter: problem, solution, stakeholders, scope in/out, success
+   - Principles: 3–6 project-specific principles that resolve trade-offs
+   - Success criteria: measurable targets with how-to-measure
+   - Roadmap: natural phases with key deliverables and rough version targets
+   - `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)
+   - 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
+   - Ask: "Ready to found the project? This will write N files. Approve to proceed."
 
 5. **On approval — exit the gate**:
    ```bash
    rm .momentum/brainstorm-active
    ```
 
-6. Scaffold directory structure:
-   ```bash
-   mkdir -p docs specs/backlog/details specs/changelog specs/decisions \
-     specs/phases specs/planning specs/vision scripts \
-     .claude/commands .agent/rules
-   touch specs/backlog/details/.gitkeep
-   # monorepo only:
-   mkdir -p specs/architecture/adrs specs/benchmarks
-   ```
-
-7. Create all files in one batch:
-   - `specs/vision/project-charter.md` — problem, goals, non-goals, stakeholders
-   - `specs/vision/principles.md` — engineering principles
-   - `specs/vision/success-criteria.md` — measurable completion criteria
-   - For monorepo: `specs/architecture/` first-pass architecture doc
+6. Write the foundation in one batch:
+   - `specs/vision/project-charter.md`
+   - `specs/vision/principles.md`
+   - `specs/vision/success-criteria.md`
    - `specs/planning/roadmap.md`
+   - 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`
-   - `CLAUDE.md` (the primary instruction file — full rules included)
-   - `specs/index.md` (OKF bundle root), `specs/decisions/impact-map.md`
-   - `specs/status.md`, `specs/backlog/backlog.md`
-   - `specs/decisions/0000-template.md`, `specs/decisions/README.md`
-   - `specs/phases/README.md`, `specs/README.md`
-   - `specs/changelog/YYYY-MM.md`
-
-8. Initial git commit:
-    ```bash
-    git add .
-    git commit -m "feat: initialize spec-driven project — {project name}
+     (log the founding decisions from this conversation in `history.md`)
+   - Refresh bundle listings: `momentum okf index`
 
-    - Vision, roadmap, Phase 0 brainstormed and ready
-    - Full spec-driven structure: specs/, CLAUDE.md, commands, hooks
-    - Ready for /start-phase"
+7. Commit the founding:
+    ```bash
+    git add specs/
+    git commit -m "docs: found {project name} — vision, roadmap, Phase 0"
     ```
+    (On a brand-new repo this may be the first content commit on the default
+    branch — the bootstrap exception to Rule 6. On a repo with existing code,
+    normal branch discipline applies.)
 
-9. Report to user:
-   - Summary of what was created
+8. Report to user:
+   - Summary of what was founded
    - Phase 0 goal and key deliverables
-   - Prompt: "Project scaffolded. Run `/start-phase` to begin Phase 0."
+   - Prompt: "Project founded. Run `/start-phase` to begin Phase 0."
+
+---
+
+## Foundation Doc Formats
+
+Author real content into these shapes (frontmatter included). These formats
+live here — momentum ships no copyable placeholder versions.
+
+### `specs/vision/project-charter.md`
+
+```markdown
+---
+type: Vision
+---
+
+# Project Charter
+
+> **Project**: {name}
+> **Created**: {today}
+
+## Problem Statement
+{Who has what problem; why it matters}
+
+## Solution
+{What this project builds; how it solves the problem}
+
+## Stakeholders
+| Role | Name / Team | Responsibility |
+|------|-------------|----------------|
+| Owner | {…} | Final decisions |
+| Users | {…} | Primary audience |
+
+## Scope
+### In
+- {…}
+### Out
+- {…}
+
+## Success
+{How you'll know it worked — point at success-criteria.md targets}
+```
+
+### `specs/vision/principles.md`
+
+```markdown
+---
+type: Vision
+---
+
+# Principles
+
+> Guiding decisions throughout the project. When trade-offs arise, these resolve them.
+
+## Core Principles
+1. **{Name}** — {one-line rule of decision}
+2. …
+```
+
+(Good defaults to adapt: simplicity first; ship incrementally; defer scope,
+not quality; document decisions. Replace or extend to match THIS project.)
+
+### `specs/vision/success-criteria.md`
+
+```markdown
+---
+type: Vision
+---
+
+# Success Criteria
+
+> Measurable targets. When all are met, the project has achieved its goals.
+
+## Phase 0 Targets
+| Criterion | Target | How to Measure |
+|-----------|--------|----------------|
+| {…} | {…} | {command / metric} |
+
+## Long-Term Targets
+| Criterion | Target | How to Measure |
+|-----------|--------|----------------|
+| {…} | {…} | {…} |
+```
+
+### `specs/planning/roadmap.md`
+
+```markdown
+---
+type: Roadmap
+---
+
+# Roadmap
+
+> **Start Date**: {today}
+
+## Vision
+{One sentence: what this project becomes at full maturity}
+
+## Timeline
+| Phase | Name | Status | Key Deliverables |
+|-------|------|--------|------------------|
+| 0 | {Bootstrap/…} | Not Started (target v0.1.0) | {…} |
+| 1 | {…} | Not Started | {…} |
+
+## Guiding Principles
+1. Ship working software in every phase
+2. Each phase leaves the project in a releasable state
+3. Defer scope, not quality
+```
 
 ---
 
@@ -87,29 +208,30 @@ This command runs in two phases: **brainstorm** (conversational, no disk writes)
 
 ### Sentinel-driven enforcement
 
-A file `.momentum/brainstorm-active` exists for the lifetime of the brainstorm phase. While it exists, the Claude Code `brainstorm-gate.sh` PreToolUse hook blocks any `Write`/`Edit`/`MultiEdit` call whose target lives under `specs/`. The hook is the safety net; the discipline below is the primary contract.
+A file `.momentum/brainstorm-active` exists for the lifetime of the brainstorm phase. While it exists, the `brainstorm-gate.sh` PreToolUse hook blocks any `Write`/`Edit`/`MultiEdit` call whose target lives under `specs/`. The hook is the safety net; the discipline below is the primary contract.
 
 ### Sequence
 
 1. **Enter brainstorm** — `mkdir -p .momentum && touch .momentum/brainstorm-active`
-2. **Draft in conversation only** — vision sketch, architecture sketch, roadmap, Phase 0 plan all live in chat. NEVER call `Write`/`Edit`/`MultiEdit` on `specs/` paths during this phase.
-3. **Present for approval** — show the user the full draft including the list of files scaffolding will create. Ask: "Ready to scaffold? Approve to proceed."
-4. **Exit brainstorm on approval** — `rm .momentum/brainstorm-active`, then create all files in one batch and commit.
+2. **Draft in conversation only** — charter, principles, success criteria, roadmap, architecture sketch, Phase 0 plan all live in chat. NEVER call `Write`/`Edit`/`MultiEdit` on `specs/` paths during this phase.
+3. **Present for approval** — show the user the full draft including the list of files founding will create. Ask: "Ready to found the project? Approve to proceed."
+4. **Exit brainstorm on approval** — `rm .momentum/brainstorm-active`, then write all files in one batch and commit.
 
 ### Red flags — STOP and stay in conversation
 
 | If you find yourself thinking… | …STOP and stay in conversation |
 |---|---|
-| "I'll create the directory structure now so I can see it" | The conversation IS the plan. The hook will block any `specs/` write. |
-| "The user said the project name; I'll start scaffolding" | Project name ≠ approval. Show the full plan, then ask. |
-| "I'll write `specs/vision/project-charter.md` first while we figure out the rest" | All-or-nothing: every file goes in one batch on approval. Otherwise the project ends up half-scaffolded if the user changes their mind. |
-| "It's an empty repo, no harm in writing early" | Scaffolding an empty repo creates a commitment to the structure. Approval first. |
+| "The scaffold already exists, so founding must already be done" | Structure ≠ content. If charter/roadmap don't exist, the project is NOT founded — that's exactly what this command fixes. |
+| "The user said the project name; I'll start writing files" | Project name ≠ approval. Show the full draft, then ask. |
+| "I'll write the charter first while we figure out the rest" | All-or-nothing: every file goes in one batch on approval. Otherwise the project ends up half-founded if the user changes their mind. |
+| "I'll fill what I know and leave `_(TBD)_` for the rest" | TBD placeholders are the failure mode this command exists to prevent. Draft best-effort content, mark `<!-- refine: -->`, ask the user. |
+| "This is a big codebase, founding doesn't apply" | Existing code makes founding MORE valuable — the charter records what the code is for. |
 
 ### Anti-rationalization counters
 
-- "Faster to scaffold incrementally as we decide each piece" — no: incremental scaffolding makes "undo" expensive. Batch on approval.
-- "The user obviously wants this, they ran the command" — they want a project scaffolded; they have not yet seen the proposed structure.
-- "The roadmap is generic enough I can write it now" — even a generic roadmap is a commitment; show it first.
+- "Faster to write files incrementally as we decide each piece" — no: incremental writes make "undo" expensive. Batch on approval.
+- "The user obviously wants this, they ran the command" — they want the project founded; they have not yet seen the proposed content.
+- "A generic roadmap is better than none, I'll write it now" — even a generic roadmap is a commitment; show it first.
 
 ---
 
@@ -136,7 +258,8 @@ Standard layout:
 
 ## Key Principles
 - Idea should already be clear before running this — use `/brainstorm-idea` to get there
+- Founding = content; `momentum init` = structure. Never scaffold placeholder docs.
 - Phase 0 scope should be achievable in a focused sprint
 - Architecture sketch is a starting point, not a commitment
 - Record all key decisions from the dialogue in Phase 0's `history.md`
-- **Brainstorm Gate**: see the contract above. Scaffolding only after explicit approval.
+- **Brainstorm Gate**: see the contract above. Writing only after explicit approval.

package/core/commands/validate.md

@@ -21,6 +21,16 @@ Run with no arguments for a fast index-first check, or pass `--deep` for a full
    - Bugs, Features, Tech Debt, Enhancements
    - Report any missing table as a failure
 
+2b. Founded state (`core/project-lifecycle.md`, ADR-0008):
+   - founded ⟺ `specs/vision/project-charter.md` AND
+     `specs/planning/roadmap.md` both exist
+   - Phase directories exist under `specs/phases/` while NOT founded →
+     FAILURE: "phase work exists but the project is not founded — run
+     `/start-project` to author the foundation docs"
+   - Not founded with no phase directories is the VALID Installed state —
+     report informationally ("not founded yet — `/start-project` when
+     ready"), never as a failure
+
 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:`

package/core/foundation-placeholder-hashes.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "ADR-0008 — FROZEN FOREVER. Normalized-body sha256 of every version of the four foundation templates ever shipped by momentum init (v0.4.0 'feat(core): add specs-templates tree' 2026-04-21 through v0.31.2; the v0.27.0 OKF revision was frontmatter-only, so each path has exactly one normalized hash). momentum upgrade removes a foundation file ONLY if its normalized body hashes into this set — proof the user never edited it. The templates were deleted from core/specs-templates in Phase 25, so this set can never grow. Normalization: CRLF→LF, strip one leading YAML frontmatter block, String.trim(), append a single trailing newline.",
+  "normalization": "crlf-to-lf | strip-one-leading-yaml-frontmatter-block | trim | append-single-newline",
+  "paths": {
+    "specs/vision/project-charter.md": [
+      "7cf00ea97e544d1b1fa940733f2dda8fcbdaebd61a8e632603dccbac51e3b2fa"
+    ],
+    "specs/vision/principles.md": [
+      "033c7bced5f46ad40c163e74873dfcbc036f6e9141471917871a883846a0b01f"
+    ],
+    "specs/vision/success-criteria.md": [
+      "b48b942ce86f1628fa72863e8d5c5c72641ac761d28ecc4adafcfc3e63314271"
+    ],
+    "specs/planning/roadmap.md": [
+      "37edbdc1e812d72c19031a1a1e44b9d4125d0e7380f3c1b2131dbfa2a4d1dcad"
+    ]
+  }
+}

package/core/instructions/navigation.md

@@ -6,7 +6,7 @@
 | 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`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**

package/core/instructions/rules-body.md

@@ -7,6 +7,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/core/project-lifecycle.md

@@ -0,0 +1,68 @@
+# Project Lifecycle Contract
+
+> Normative contract for how a momentum project comes into being
+> (ADR-0008). Command docs reference these states; the CLI enforces the
+> Installed-state shape; command contracts enforce the gates.
+
+A momentum project moves through three states. Each state has exactly one
+owning command. State is determined by **file existence** — never by file
+content, markers, or heuristics.
+
+## States
+
+| # | State | Owner | What exists |
+|---|-------|-------|-------------|
+| 1 | **Installed** | `momentum init` | Machinery: adapter surfaces (commands/rules/hooks/scripts), git hooks, and the contentless-by-nature specs skeleton — `specs/status.md` (in the "Not founded" state), `specs/backlog/backlog.md` (empty tables), `specs/changelog/`, `specs/decisions/` (template + README), `specs/phases/` (README + index), `specs/adhoc/`. **No foundation docs.** |
+| 2 | **Founded** | `/start-project` | Everything above PLUS the authored foundation docs: `specs/vision/project-charter.md`, `specs/vision/principles.md`, `specs/vision/success-criteria.md`, `specs/planning/roadmap.md`, and a filled `status.md` Summary. |
+| 3 | **Phase loop** | `/brainstorm-phase` → `/start-phase` → `/complete-phase` | Everything above PLUS `specs/phases/phase-N-*/` directories. |
+
+## The founded predicate
+
+```
+founded ⟺ specs/vision/project-charter.md exists
+          AND specs/planning/roadmap.md exists
+```
+
+The minimal load-bearing pair: *why the project exists* + *where it's
+going*. `principles.md` and `success-criteria.md` are authored at founding
+but their absence never blocks phase work (tolerates legacy projects).
+
+## Rules
+
+1. **`momentum init` never writes foundation docs.** A placeholder document
+   satisfies structural checks while carrying zero information; absence is
+   the honest, machine-checkable signal.
+2. **`/start-project` founds the project — content, not structure.** It
+   authors the four foundation docs from the brainstorm/conversation under
+   the brainstorm-gate + explicit-approval contract. It works on any repo
+   state (empty, freshly init'd, or full of code). If machinery is missing,
+   it routes to `momentum init` first.
+3. **Phase commands gate on founded.** `/brainstorm-phase` and
+   `/start-phase` check the predicate before any phase work. Not founded →
+   STOP and route to `/start-project` (offering to draft the foundation
+   docs with the user from available context — best-effort and marked for
+   refinement beats absent).
+4. **`/validate` checks the invariant** `phase dirs exist ⟹ founded` as a
+   failure. "Installed but not founded, no phases" is a valid state, not an
+   error.
+5. **`/migrate` reports "not founded"** — it never creates foundation
+   placeholders.
+6. **`momentum upgrade` heals legacy installs**: foundation files whose
+   frontmatter-stripped, whitespace-normalized body hash matches any
+   historically shipped template (see
+   `core/foundation-placeholder-hashes.json` — frozen) are removed with a
+   report. Any user-edited file is untouched. `--dry-run` previews.
+
+## Routing (what an agent does per state)
+
+| Observed state | Correct next step |
+|---|---|
+| No `.momentum/` machinery | `momentum init` |
+| Installed, not founded, idea unclear | `/brainstorm-idea` (writes nothing) |
+| Installed, not founded, idea clear | `/start-project` (founds it) |
+| Founded, no phase planned | `/brainstorm-phase` |
+| Founded, phase planned | `/start-phase` |
+
+`status.md` in the Installed state carries this routing inline ("Not
+founded — run `/brainstorm-idea` → `/start-project`"), so Rule 1
+orientation self-corrects on every adapter.

package/core/specs-templates/CLAUDE.md

@@ -14,7 +14,7 @@
 | 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`) |
 | How to contribute? | `docs/developer-guide.md` |
 
 > **First file to read: ALWAYS `specs/status.md`.**
@@ -30,6 +30,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/core/specs-templates/specs/README.md

@@ -15,14 +15,19 @@ type: Guide
 | `changelog/` | Monthly change logs |
 | `decisions/` | Architecture Decision Records (ADRs) |
 | `phases/` | Phase plans, tasks, and history |
-| `planning/` | Roadmap and release plan |
-| `vision/` | Project charter, principles, success criteria |
+| `planning/` | Roadmap and release plan — created at founding (`/start-project`) |
+| `vision/` | Project charter, principles, success criteria — created at founding (`/start-project`) |
+
+Foundation docs (`vision/`, `planning/roadmap.md`) are **authored, not
+scaffolded**: they don't exist until `/start-project` founds the project
+from your brainstorm. Their absence means "not founded yet" — phase
+commands will route you to `/start-project` first.
 
 ## Workflow
 
 ```
 /brainstorm-idea     →  explore an idea (no files written)
-/start-project       →  scaffold vision + roadmap + Phase 0
+/start-project       →  found the project: author vision + roadmap, plan Phase 0
 /start-phase         →  begin a phase
 /track               →  log a discovery mid-phase
 /complete-phase      →  verify, release, retrospective

package/core/specs-templates/specs/index.md

@@ -6,7 +6,6 @@ okf_version: "0.1"
 
 * [Status](/status.md) - current project state — the first file to read
 * [Backlog](/backlog/backlog.md) - bugs, features, tech debt, enhancements
-* [Roadmap](/planning/roadmap.md) - phase timeline and upcoming work
 
 # Directories
 

package/core/specs-templates/specs/status.md

@@ -5,13 +5,19 @@ type: Status
 # Project Status
 
 > **Last Updated**: YYYY-MM-DD
-> **Current Phase**: Phase 0 — Bootstrap (`not started`)
+> **Current Phase**: _Not founded_ — run `/brainstorm-idea`, then `/start-project`
 > **Latest Release**: None
 > **Health**: On Track
 
 ## Summary
 
-<!-- One paragraph describing what this project is and what it does. -->
+_Not founded yet. momentum machinery is installed, but this project has no
+foundation docs (charter, principles, success criteria, roadmap) — they are
+authored at founding, never scaffolded. Explore the idea with
+`/brainstorm-idea` (writes nothing), then run `/start-project` to found the
+project: it authors the foundation docs from your brainstorm and plans
+Phase 0. Phase commands stop and route you here until the project is
+founded._
 
 ## Completed Phases
 
@@ -37,13 +43,13 @@ type: Status
 
 | Phase | Branch | Status | Progress |
 |-------|--------|--------|----------|
-| _(none — no active phase)_ | | | |
+| _(none — project not founded yet)_ | | | |
 
 ## Upcoming Phases
 
 | Phase | Name | Status | Key Deliverables |
 |-------|------|--------|-----------------|
-| _(TBD)_ | | | |
+| _(defined at founding — see `/start-project`)_ | | | |
 
 ## Blockers
 
@@ -59,7 +65,8 @@ type: Status
 
 ## Next Actions
 
-1. Run `/brainstorm-idea` to explore the concept, then `/start-project` to scaffold
+1. Run `/brainstorm-idea` to explore the idea (conversation only — writes nothing)
+2. Run `/start-project` to found the project — authors charter, principles, success criteria, and roadmap, then plans Phase 0
 
 ## Key Decisions Made
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limina-labs/momentum",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
   "homepage": "https://trymomentum.github.io",
   "bin": {

package/core/specs-templates/specs/planning/roadmap.md

@@ -1,23 +0,0 @@
----
-type: Roadmap
----
-
-# Roadmap
-
-> **Last Updated**: YYYY-MM-DD
-
-## Vision
-
-<!-- One sentence: what does this project become at full maturity? -->
-
-## Release Plan
-
-| Version | Phase | Key Deliverables | Target |
-|---------|-------|-----------------|--------|
-| v0.1.0 | Phase 0 — Bootstrap | _(TBD)_ | _(TBD)_ |
-
-## Guiding Principles
-
-1. Ship working software in every phase
-2. Each phase leaves the project in a releasable state
-3. Defer scope, not quality

package/core/specs-templates/specs/vision/principles.md

@@ -1,16 +0,0 @@
----
-type: Vision
----
-
-# Principles
-
-> Guiding decisions throughout the project. When trade-offs arise, these resolve them.
-
-## Core Principles
-
-1. **Simplicity first** — the simplest solution that solves the problem is the right one
-2. **Ship incrementally** — each phase leaves the project in a releasable state
-3. **Defer scope, not quality** — cut features before cutting correctness
-4. **Document decisions** — every significant choice gets an ADR
-
-<!-- Add or replace principles to match this project's values. -->

package/core/specs-templates/specs/vision/project-charter.md

@@ -1,35 +0,0 @@
----
-type: Vision
----
-
-# Project Charter
-
-> **Project**: <Project Name>
-> **Created**: YYYY-MM-DD
-
-## Problem Statement
-
-<!-- What problem does this project solve? Who has this problem? Why does it matter? -->
-
-## Solution
-
-<!-- What does this project build or do? How does it solve the problem? -->
-
-## Stakeholders
-
-| Role | Name / Team | Responsibility |
-|------|-------------|----------------|
-| Owner | _(TBD)_ | Final decisions |
-| Users | _(TBD)_ | Primary audience |
-
-## Scope
-
-### In
-- _(TBD)_
-
-### Out
-- _(TBD)_
-
-## Success
-
-<!-- How will you know this project succeeded? See `success-criteria.md` for measurable targets. -->

package/core/specs-templates/specs/vision/success-criteria.md

@@ -1,19 +0,0 @@
----
-type: Vision
----
-
-# Success Criteria
-
-> Measurable targets. When all are met, the project has achieved its goals.
-
-## Phase 0 Targets
-
-| Criterion | Target | How to Measure |
-|-----------|--------|----------------|
-| _(TBD)_ | _(TBD)_ | _(TBD)_ |
-
-## Long-Term Targets
-
-| Criterion | Target | How to Measure |
-|-----------|--------|----------------|
-| _(TBD)_ | _(TBD)_ | _(TBD)_ |