@limina-labs/momentum 0.30.2

package/core/commands/lanes.md

@@ -0,0 +1,94 @@
+Work with lanes — concurrent workstreams in one repo (Rule 15 mechanism).
+
+> **Which phase is yours (Rule 15):** the phase bound to your branch;
+> `momentum lanes` shows every lane in flight. The board is the
+> cross-lane overview — your branch is still the binding.
+
+## When to use
+
+- The user asks "what's running?", "what else is in flight?", or wants to
+  start a second workstream without abandoning the first.
+- You are about to start work that should NOT live on the current branch.
+- A finished lane needs to be landed in order.
+
+## Subcommands
+
+All state lives at `<git-common-dir>/momentum/lanes` — shared by every
+worktree, untracked, no daemon. Run from anywhere inside the repo.
+
+### See the board
+
+```bash
+momentum lanes            # every lane: plan node, grade, status, age, ✉ unread, ⚠ overlaps
+momentum lanes queue      # landing order (FIFO of done lanes) + freshness flags
+```
+
+The board footer always shows **queue pressure** (done-but-unlanded lanes
++ oldest wait). Rising pressure means landings — the human-attention step
+— are the bottleneck; surface it to the user rather than opening more lanes.
+
+### Plan waves first (N ideas → N lanes)
+
+```bash
+momentum waves            # phase-scale waves from overview.md frontmatter "deps"
+momentum waves --tasks    # group waves for the phase bound to your branch
+```
+
+Dependencies are annotations in the plans themselves (`(deps: G0, G1)`
+group-heading suffix; `deps:` frontmatter on each phase's overview.md —
+OKF bundle, ADR-0005; legacy `specs/phases/index.json` still read as a
+fallback until the project runs `momentum upgrade`).
+Wave-1 nodes are safe to open as lanes NOW; later waves unblock as their
+dependencies land.
+
+### Open a lane
+
+```bash
+momentum lanes open <branch> [--grade phase|quick-task|spike] \
+  [--touches core/**,docs/] [--path <dir>] [--from <ref>] [--no-worktree]
+```
+
+- Creates a git worktree at `../<repo>.lanes/<id>` by default (reuses an
+  existing checkout of the branch; `--no-worktree` for GitButler-style
+  virtual branches).
+- The plan node and grade are inferred from the branch name (Rule 15:
+  `phase-*` ↔ phase directory; `fix/* chore/* feat/*` → ad-hoc
+  quick-task); spikes must be declared with `--grade spike`.
+- Declare `--touches` honestly — overlap warnings (advisory) are how
+  parallel lanes avoid semantic collisions before any agent runs.
+- Heed preflight warnings (non-executable committed scripts, node
+  version) — they are the fresh-worktree traps.
+
+### Signal another lane's session
+
+```bash
+momentum lanes signal <id> <pause|resume|redirect|kill|message> [text]
+momentum lanes inbox <id> [--ack <seq>|--ack-all]
+```
+
+Check YOUR lane's inbox at natural checkpoints (group boundaries, before
+landing) and ack what you've acted on.
+
+### Mark done and land
+
+```bash
+momentum lanes done <id>          # enter the landing queue
+momentum lanes land <id>          # validate: turn, freshness, graded gate
+momentum lanes land <id> --execute# merge --no-ff into the CURRENT branch
+momentum lanes close <id> [--rm-worktree]
+```
+
+Landing follows the Rule 6 **Landing Order**: one lane at a time, run the
+suite on the updated integration branch before the next landing,
+remaining lanes rebase (they get an advisory inbox nudge automatically).
+Gates are graded per Rule 14: a `spike` lands gate-exempt; a `quick-task`
+needs its `specs/adhoc/<id>/record.md`; a `phase` needs a retrospective
+with a non-empty `## Verification Evidence` section (Rule 12).
+`land` never pushes — pushes to protected branches keep their own
+approval gate.
+
+## Tracking
+
+Opening/closing lanes is not itself phase history; the WORK inside a lane
+follows the normal rules (Rule 2 tracking, Rule 8 history in the lane's
+own phase, Rule 15 own-row/append-only discipline for shared files).

package/core/commands/log.md

@@ -0,0 +1,45 @@
+Record a manual entry in the active phase history file — or, when no phase is
+active, in the ad-hoc work record (off-phase decisions are never dropped).
+
+> **Which phase is yours (Rule 15):** the phase bound to your branch — branch
+> `phase-N-shortname` ↔ `specs/phases/phase-N-shortname/`. `status.md`'s
+> Active Phase table is the fallback (detached HEAD, no matching directory)
+> and the cross-lane overview, not the binding.
+
+## Steps
+
+1. Resolve your phase from the current branch (`git branch --show-current`):
+   a `phase-*` branch with a matching `specs/phases/<branch>/` directory binds
+   to that phase. Fallback: the `specs/status.md` Active Phase table. A
+   non-phase branch (`fix/*`, `chore/*`, `feat/*`) is ad-hoc work — see below.
+2. Find the history file:
+   - **Phase lane**: `specs/phases/<phase-bound-to-your-branch>/history.md`
+   - **No active phase** (between phases, or `/hotfix` quick-task / spike work):
+     the `specs/adhoc/<id>/record.md` you are working in, else
+     `specs/adhoc/history.md` (create it from the same entry format if absent).
+     Off-phase work still captures its *why* (Rule 8) — it just lives here.
+3. Determine entry type from the message:
+   - Decision about technology/architecture → [DECISION]
+   - Phase scope added/removed → [SCOPE_CHANGE]
+   - Bug/tech debt/enhancement found → [DISCOVERY]
+   - New planned feature → [FEATURE]
+   - Architecture pattern changed → [ARCH_CHANGE]
+   - Evaluator defined or changed → [EVALUATOR]
+   - Anything else → [NOTE]
+4. Extract or infer topics (2-5 keywords)
+5. Identify affects-phases (check `status:` frontmatter in `specs/phases/*/overview.md`)
+6. Identify affects-specs (check `specs/decisions/impact-map.md`)
+7. Append the formatted entry to history.md (APPEND ONLY):
+
+```
+### [TYPE] YYYY-MM-DD — Short title (max 10 words)
+Topics: topic-1, topic-2, topic-3
+Affects-phases: phase-N-name (or "none")
+Affects-specs: path/to/file.md#section (or "none")
+Detail: One to three sentences describing what changed and why.
+
+---
+```
+
+8. If the entry introduces a topic not in the `specs/decisions/impact-map.md` table, add a row
+9. Confirm: "Logged [TYPE] entry to [phase or ad-hoc] history."

package/core/commands/migrate.md

@@ -0,0 +1,70 @@
+Onboard an existing project with a manual or outdated momentum-like structure into proper momentum format.
+
+This command fills gaps without overwriting anything the project already has.
+
+## Steps
+
+1. **Detect existing structure** — scan for what momentum expects vs what is present:
+
+   | Item | Expected path | Present? |
+   |------|--------------|---------|
+   | Spec root | `specs/` | |
+   | Status file | `specs/status.md` | |
+   | Backlog | `specs/backlog/backlog.md` | |
+   | Bundle root | `specs/index.md` (OKF, `okf_version`) | |
+   | Decisions dir | `specs/decisions/` | |
+   | Planning dir | `specs/planning/` | |
+   | Changelog dir | `specs/changelog/` | |
+   | Hook script | `scripts/check-history-reminder.sh` | |
+   | Claude commands | `.claude/commands/` | |
+
+   For `.claude/commands/`, list which of the standard momentum commands are missing:
+   `brainstorm-idea`, `brainstorm-phase`, `start-project`, `start-phase`, `complete-phase`,
+   `log`, `sync-docs`, `track`, `migrate`, `validate`
+
+2. **Report gap summary** — present findings before making any changes:
+   ```
+   Found: 8 / Missing: 4 items
+   Will add:
+     - specs/backlog/details/ (.gitkeep)
+     - specs/index.md (OKF bundle root)
+     - .claude/commands/validate.md
+     - .claude/commands/migrate.md
+   Will skip (already exist):
+     - specs/status.md
+     - specs/backlog/backlog.md
+   ```
+   Ask the user to confirm before proceeding.
+
+3. **Fill gaps (skip-if-exists for all files)**:
+   - Copy any missing momentum template files from `specs-templates/` — never overwrite
+     files the project already has
+   - Add any missing momentum commands to `.claude/commands/` — skip ones already present
+   - Add `scripts/check-history-reminder.sh` if absent (and chmod +x)
+
+4. **Phase metadata reconciliation** (OKF bundle, ADR-0005):
+   - Run `momentum upgrade` — it migrates any legacy `specs/phases/index.json`
+     / `specs/decisions/impact-map.json` into frontmatter + `impact-map.md`,
+     sweeps `type:` frontmatter across `specs/**/*.md`, and generates the
+     bundle indexes
+   - For any `phase-*` directory whose `overview.md` still lacks `status:`
+     frontmatter, add:
+     ```yaml
+     ---
+     type: Phase
+     status: unknown
+     ---
+     ```
+   - Inform the user: "N phases marked status 'unknown' — update the
+     frontmatter manually to match actual state"
+   - Finish with `momentum okf check` and report any remaining violations
+
+5. **Report result**:
+   ```
+   ✓ Migration complete.
+   Added: 4 items
+   Skipped: 6 items (already existed — not overwritten)
+   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/review.md

@@ -0,0 +1,31 @@
+Review and groom the backlog between phases.
+
+## Steps
+
+1. Read `specs/status.md` and `specs/backlog/backlog.md`
+
+2. For each category, assess:
+   - Are priorities still accurate?
+   - Should items move to active/next phase?
+   - Are any items resolved or deprecated?
+   - Orphaned items without a phase?
+
+3. Check for dependencies:
+   - P0 bugs blocking progress
+   - Features depending on unresolved tech debt
+   - Items open 3+ months without progress
+
+4. Update `specs/backlog/backlog.md` with changes
+
+5. Update `specs/status.md` if blockers changed
+
+6. Commit:
+   ```bash
+   git add specs/
+   git commit -m "docs(backlog): grooming for Phase N"
+   ```
+
+7. Report:
+   - Total open items by type and priority
+   - P0/P1 items requiring attention
+   - Recommended actions

package/core/commands/session.md

@@ -0,0 +1,79 @@
+Append a manual narrative entry to today's ecosystem session log.
+
+The session log auto-fills with structural events (commits, PR
+opens/merges) via the PostToolUse hook in each registered member repo.
+Use `/session log` for narrative entries — decisions, problems hit,
+checkpoint notes — that don't correspond to a tool event.
+
+## Usage
+
+```
+/session log "<message>"
+```
+
+## Steps
+
+1. Locate the ecosystem root via
+   `core/ecosystem/lib/index.js → findRoot(process.cwd())`.
+   If no ecosystem root exists, refuse with a clear message: "Not
+   inside an ecosystem. Run `momentum ecosystem init` first or `cd`
+   into a registered member repo."
+
+2. Determine the calling member id (when relevant): match
+   `realpath($PWD)` against each `manifest.members[].path`. If no
+   match, write the entry with a `[meta]` tag instead.
+
+3. Build the line:
+   ```
+   HH:MMZ [<member-id-or-meta>] note: <message>
+   ```
+
+4. If today's session file doesn't exist yet, prepend a header:
+   ```
+   # Session YYYY-MM-DD
+   Active initiative: <slug>      (if .state/active-initiative is set)
+
+   ```
+
+5. Append the line to `<ecosystem-root>/sessions/$(date -u +%F).md`.
+
+6. Update `<ecosystem-root>/.state/last-session` to today's date.
+
+7. Print confirmation:
+   ```
+   Logged: HH:MMZ [<member-id>] note: <message>
+   ```
+
+## When to use vs auto-events
+
+| Use `/session log` for… | Auto-events already cover… |
+|---|---|
+| "Decided to defer X to Tier 2" | `git commit` (the actual change record) |
+| "Discovered the SQL was dropping scope filter" | `gh pr create/merge` |
+| "Bumped Y version pin in lock to address Z" | future: deploy events (Group 3 v2) |
+| "Switching context from sapience to frontend" | future: hook-detected directory changes |
+
+## Mechanism
+
+`/session log` is a thin wrapper around the same
+`core/ecosystem/scripts/session-append.sh` helper used by the
+PostToolUse hook. From bash:
+
+```bash
+$MOMENTUM_SCRIPTS/session-append.sh log "<message>" "<optional-context>"
+```
+
+## Idempotency / safety
+
+- Multiple `/session log` calls in the same minute produce multiple
+  lines. Concurrent writes (a `/session log` plus a `git commit` hook
+  in another member repo at the same instant) are serialized via a
+  per-session-file `mkdir` lock (Phase 10 / BUG-004). ~5s acquisition
+  budget; on timeout the event is dropped rather than risking
+  corruption.
+- The walk-up that locates the ecosystem root honors the
+  `MOMENTUM_MAX_PARENT_WALK` env var (default 5).
+- Outside an ecosystem the helper silently no-ops, so harmless to
+  invoke speculatively.
+- The session log is gitignore-free (committed) but `.state/` is not —
+  to share session history across machines, push the ecosystem repo.

package/core/commands/start-phase.md

@@ -0,0 +1,161 @@
+Begin a new implementation phase.
+
+After setup, **executes the plan end-to-end autonomously** — no per-group approval prompts, no "should I commit?" interruptions. The engine stops once: at the merge + release gate after the final group's verification passes. See the [Autonomous Execution Contract](#autonomous-execution-contract) below.
+
+> **Which phase is yours (Rule 15):** the phase bound to your branch — branch
+> `phase-N-shortname` ↔ `specs/phases/phase-N-shortname/`. `status.md`'s
+> Active Phase table is the fallback and the cross-lane overview. Starting a
+> phase while other lanes are active is normal — add your lane's row to the
+> table; never replace or rewrite other lanes' rows.
+
+## Setup Steps (run once at phase start)
+
+1. Read current state:
+   - Read `specs/status.md`
+
+2. Check for blocking bugs (pre-phase bug check):
+   - Scan `specs/backlog/backlog.md` for P0/P1 items
+   - If P0 bugs exist → report to user, recommend fixing first
+   - If only P1 → continue but note them
+
+3. Create the phase directory if it doesn't exist:
+   ```
+   specs/phases/phase-N-shortname/
+   ├── overview.md    ← Scope, goals, deliverables, acceptance criteria
+   ├── plan.md        ← Implementation approach with group execution pattern
+   ├── tasks.md       ← Granular checklist [ ] / [x]
+   └── history.md     ← Append-only log
+   ```
+   Use `/brainstorm-phase` first if these files don't exist yet.
+
+   Note: if running `/start-phase` without `/brainstorm-phase` first, create
+   `history.md` now — an empty append-only log with the entry-types header table.
+
+   **Swarm-member briefs (Phase 17+)**: when `/start-phase` is invoked from
+   a swarm conductor (env vars `MOMENTUM_SWARM_ID` + `MOMENTUM_SWARM_WAVE`
+   + `MOMENTUM_SWARM_INITIATIVE` + `MOMENTUM_SWARM_SESSION` are set),
+   prepend a YAML frontmatter block to `overview.md` with these fields:
+   ```yaml
+   ---
+   swarm: <NNNN-slug>
+   wave: <integer>
+   initiative: <slug>
+   claimed_by_session: <uuid>
+   ---
+   ```
+   Solo (non-swarm) briefs omit the block entirely — they remain plain
+   markdown. See `core/swarm/lib/brief.js` for the canonical helper.
+
+4. Set phase metadata (OKF bundle, ADR-0005):
+   - Read the phase's `overview.md` and `tasks.md`
+   - Extract key topics: technology names, services, architectural concepts
+   - Add/update the frontmatter at the top of the phase's `overview.md`:
+     ```yaml
+     ---
+     type: Phase
+     status: in-progress
+     tags: [topic-1, topic-2]
+     ```
+     (add `deps: [phase-M-name]` when this phase depends on another
+     unfinished phase — `momentum waves` reads it)
+   - Refresh the bundle listings: `momentum okf index`
+
+5. Update `specs/phases/README.md`:
+   - Change phase status: `Not Started` → `In Progress`
+
+6. Update `specs/status.md`:
+   - Set "Current Phase" to the new phase (with other lanes active, the most
+     recently started lane; the Active Phase table is the full picture)
+   - Add this phase's row to the "Active Phase" table
+     (Phase | Branch | Status | Progress) — one row per active lane; touch
+     ONLY your own row (Rule 15)
+   - Clear/update blockers
+
+7. For monorepo only — identify relevant architecture specs:
+   - Check `specs/planning/release-plan.md` for this phase's deliverables
+   - List which specs in `specs/architecture/` are relevant
+   - Note them in the phase's `plan.md` under "Reference Specs"
+
+8. If this phase requires a locked evaluator (learning/optimization loop):
+   - Add "Lock [Evaluator]" as the FIRST task in `tasks.md`
+
+9. Create git branch and initial commit:
+   ```bash
+   git checkout main && git pull origin main
+   git checkout -b phase-N-shortname
+   git add specs/
+   git commit -m "docs: start Phase N - {phase name}"
+   git push -u origin phase-N-shortname
+   ```
+
+10. Update `specs/changelog/YYYY-MM.md` with phase start entry.
+
+## After Setup: Execute the Plan Autonomously
+
+Once steps 1–10 complete, **proceed to implement the phase** per the [Autonomous Execution Contract](#autonomous-execution-contract). For each group in `plan.md` (in declared execution order):
+
+1. **Mark the group's first task `[/]`** in `tasks.md` (in-progress).
+2. **Implement the group's tasks.** Read, write code, add tests as the group requires.
+3. **Run the group's verification command** (per Rule 12 — Verify Before Claim). Read the actual output.
+4. **Mark tasks `[x]`** in `tasks.md` only if verification passed.
+5. **Append a history entry** to `history.md` per Rule 8 (one entry per group minimum, more if `[DECISION]`/`[DISCOVERY]` events happen).
+6. **Commit the group** with the per-group commit message declared in `plan.md`.
+7. **Push to the phase branch.**
+8. **Proceed to the next group.** Do NOT ask "ready for Group N+1?" — the answer is always yes.
+
+After the final group's verification passes: **STOP.** Ask the user the single hard-stop question in the contract below.
+
+---
+
+## Autonomous Execution Contract
+
+Once a phase plan is approved, this command executes the plan end-to-end without per-group approvals. The contract below defines what proceeds silently and where the engine MUST stop.
+
+### 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?"
+
+This is the only place the engine asks. Do NOT skip it.
+
+### Discretionary stop — rare, judgment-based
+
+Interrupt only when continuing would cause real harm or a wrong result that's hard to undo. Examples:
+
+- Destructive git operation not in the plan (force-push to main, `git reset --hard origin/...`, branch deletion of unmerged work)
+- A discovery that invalidates the agreed plan (not just adds to it — `[DISCOVERY]` + backlog entry handles additions silently)
+- A required external action the engine can't perform (paid API spend, credential setup, account configuration)
+- Repeated unresolved failure on the same task (Phase 7b will codify a 3-strikes retry budget; before 7b, use judgment)
+
+A discretionary stop is rare. The default is to proceed.
+
+### Pre-authorized actions — proceed silently
+
+The engine does all of these without asking:
+
+- Create the phase feature branch
+- Commit per the conventional commit style and the per-group commit message in `plan.md`
+- Push the phase branch to origin
+- Run tests, lint, typecheck, build commands
+- Update `specs/status.md`, the phase's `overview.md` frontmatter, `specs/phases/README.md`, the active phase's `tasks.md` and `history.md`
+- Append to `specs/changelog/YYYY-MM.md`
+- Create ADRs from discoveries (per Rule 8 / Rule 10)
+- Add backlog entries from discoveries (per Rule 3)
+- Read any file in the repo
+
+### Anti-patterns — DO NOT
+
+| Anti-pattern | Correct behavior |
+|---|---|
+| Asking "should I commit Group N now?" after each group | Commit per the plan's per-group commit message. Do not ask. |
+| Asking "should I push?" after the first commit | Push immediately after the first commit; thereafter on milestones. Do not ask. |
+| Asking "ready for Group 1?" after Group 0 | Proceed to Group 1 immediately when Group 0 verification passes. |
+| Pausing to summarize progress between groups | Update `tasks.md` and move on. Summaries are for the user when they ask. |
+| Asking "ready for tests?" before Group N's verification step | Verification is part of Group N. Run it. |
+
+### Cross-references
+
+- **Rule 6 (Git Lifecycle)**: pre-authorizes branch creation, commits, pushes to feature branch. The autonomy contract is the execution-time application of Rule 6.
+- **Rule 8 (History)**: every group ends with a history append. Do this silently.
+- **Rule 12 (Verify Before Claim)**: every group's last task is verification. Run the command, read the output, mark `[x]` only if passing.

package/core/commands/start-project.md

@@ -0,0 +1,142 @@
+Scaffold a new project from a clear idea.
+
+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.
+
+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.
+
+## Steps
+
+0. **Enter the brainstorm gate**:
+   ```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.
+
+1. Confirm the idea is clear — ask if needed:
+   - What does this project build or do?
+   - 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."
+
+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
+   - `specs/planning/roadmap.md`
+   - `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}
+
+    - Vision, roadmap, Phase 0 brainstormed and ready
+    - Full spec-driven structure: specs/, CLAUDE.md, commands, hooks
+    - Ready for /start-phase"
+    ```
+
+9. Report to user:
+   - Summary of what was created
+   - Phase 0 goal and key deliverables
+   - Prompt: "Project scaffolded. Run `/start-phase` to begin Phase 0."
+
+---
+
+## Brainstorm Gate Contract
+
+This command runs in two phases: **brainstorm** (conversational, no disk writes) and **commit** (writes files to disk on explicit approval).
+
+### 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.
+
+### 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.
+
+### 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. |
+
+### 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.
+
+---
+
+## Group Execution Pattern
+
+Declare the execution order at the top of every plan.md:
+
+```
+# Sequential:  Group 0 → Group 1 → Group 2
+# Parallel:    (Groups 0 + 1 + 2 in parallel) → Group 3
+# Mixed:       Group 0 → (Groups 1 + 2 in parallel) → Group 3
+```
+
+Every group header declares:
+- `**Sequential.**` or `**Parallel with Groups X and Y.**`
+- External dependencies (libraries, services, running processes)
+- Commit message for the group
+
+Standard layout:
+- **Group 0** — contracts, types, migrations (sequential, blocks everything)
+- **Middle groups** — independent feature areas (parallel candidates)
+- **Second-to-last** — wiring and integration (sequential)
+- **Last** — verification: tests, benchmarks, smoke tests (sequential)
+
+## Key Principles
+- Idea should already be clear before running this — use `/brainstorm-idea` to get there
+- 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.