@limina-labs/momentum 0.30.2

package/core/commands/brainstorm-phase.md

@@ -0,0 +1,129 @@
+Brainstorm the next phase before creating it.
+
+Run AFTER `/complete-phase` and BEFORE `/start-phase`.
+
+## Important: No Separate Design Document
+
+All output goes directly into the phase directory as standard phase files.
+The brainstorm output IS the phase files — there is no intermediate design doc.
+
+**But — and this is the whole point of this command — those phase files MUST NOT exist on disk until the user has explicitly approved the draft.** See the [Brainstorm Gate Contract](#brainstorm-gate-contract) below.
+
+## Steps
+
+0. **Enter the brainstorm gate**:
+   ```bash
+   mkdir -p .momentum && touch .momentum/brainstorm-active
+   ```
+   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:
+   - 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?
+
+2. Check the roadmap:
+   - Read `specs/planning/roadmap.md` — what's the next planned phase?
+   - Is the planned phase still the right next step given what was learned?
+
+3. Define scope with the user (one question at a time):
+   - What is the goal of this phase?
+   - What are the key deliverables?
+   - What are the acceptance criteria?
+   - What are the non-goals (explicitly out of scope)?
+
+4. For monorepo — identify reference specs:
+   - Which architecture docs in `specs/architecture/` are relevant?
+   - Are there any spec gaps that need to be filled first?
+   - If gaps exist, propose an ADR or addendum before proceeding.
+
+5. Gap analysis (monorepo only):
+   - Cross-reference brainstormed design against architecture specs
+   - Verify interface counts, field names, error codes match exactly
+   - Record findings and resolutions
+
+6. **Draft phase files in conversation only** — do NOT call `Write`/`Edit`/`MultiEdit`:
+   - `overview.md` — goal, key decisions table, scope (in/out), deliverables with verification commands, acceptance criteria
+   - `plan.md` — full implementation plan using the Group Execution Pattern (see below)
+   - `tasks.md` — granular checklist mirroring plan.md tasks
+   - `history.md` — initial entries logging all decisions from this brainstorm session
+
+   Show the user the full draft in the chat. Iterate on revisions in the chat. Nothing on disk yet.
+
+7. Present for user approval:
+   - Show key sections of overview.md and plan.md
+   - Ask: "Does this look right? Any changes before I write the phase files?"
+
+8. **On approval — exit the gate and write**:
+   ```bash
+   rm .momentum/brainstorm-active
+   ```
+   Then write all four files to `specs/phases/phase-N-shortname/` and commit:
+   ```bash
+   git add specs/phases/phase-N-shortname/
+   git commit -m "docs: brainstorm Phase N — {phase name}"
+   ```
+
+9. Prompt: "Phase N is planned. Run `/start-phase` when ready to begin."
+
+---
+
+## 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 `brainstorm-gate.sh` PreToolUse hook (shared across Claude Code, Codex, and Antigravity) blocks any write-class tool 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** — all overview/plan/tasks/history content lives in the chat. NEVER call `Write`/`Edit`/`MultiEdit` on `specs/` paths during this phase. The hook will block such calls; the contract makes the intent visible.
+3. **Present for approval** — show the user the full draft. Ask: "Does this look right? Any changes before I write the phase files?"
+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 just write a quick draft to disk so I can see it" | The conversation IS the draft. The hook will block this. |
+| "The user will approve, no point waiting" | Approval changes the conversation. Don't pre-commit to text the user might still revise. |
+| "I'll create the directory now to save a step later" | Don't. Wait for approval. |
+| "The brainstorm session was interrupted; I'll just remove the sentinel" | Only remove it when you have explicit approval AND are about to write. Premature removal recreates the failure mode. |
+
+### Anti-rationalization counters
+
+- "Drafting to disk is faster than drafting in chat" — false: revisions in chat are free; revisions on disk require re-edits.
+- "Only writing scratch files, not the real specs" — the hook can't tell scratch from real; keep both in conversation.
+- "It's fine, the user said proceed" — proceed only AFTER the explicit approval step, not before.
+
+---
+
+## Group Execution Pattern for plan.md
+
+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
+- One question at a time — don't overwhelm
+- Each phase should be completable in a focused sprint
+- If scope is too large, suggest splitting into sub-phases
+- Record any discoveries in history.md
+- **Brainstorm Gate**: see the contract above. No writes until approval.

package/core/commands/complete-phase.md

@@ -0,0 +1,130 @@
+Verify, finalize, and release a completed phase.
+
+> **Which phase is yours (Rule 15):** the phase bound to your branch — that
+> is the phase this command completes. `status.md`'s Active Phase table is
+> the fallback and the cross-lane overview. When other lanes are in flight,
+> landing follows the Rule 6 **Landing Order**: one lane at a time, full
+> suite green on updated `main` between landings, remaining lanes rebase.
+
+## Steps
+
+### Verify
+
+1. Read the phase's acceptance criteria:
+   - Read `specs/phases/phase-N-*/overview.md`
+
+2. Verify all tasks are done:
+   - Read `specs/phases/phase-N-*/tasks.md`
+   - 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):
+   - 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
+   - If any command fails → STOP, report failure to user, do NOT proceed to Finalize
+   - If a command can't run in the current environment, say so explicitly — do not silently skip
+
+   **Refuse to advance to Finalize without fresh, captured evidence.** Memory of "tests passed earlier this phase" is not evidence — re-run them now.
+
+4. If this phase built a learning loop, verify:
+   - Locked evaluator exists in `tests/benchmarks/`
+   - Convergence measurement logged (scalar improved)
+   - If not → report to user, do NOT proceed
+
+5. Check for new bugs discovered during the phase:
+   - Grep `specs/backlog/backlog.md` for items tagged to this phase
+
+### Finalize
+
+**Step F0: Sync docs from phase history (run BEFORE other finalize steps)**
+- Run `/sync-docs` to propagate all history-recorded changes to relevant documents
+- If /sync-docs finds nothing to update, proceed directly
+
+6. Create retrospective:
+   - `specs/phases/phase-N-*/retrospective.md`
+   - What went well, what didn't, lessons learned
+   - **Append a `## Verification Evidence` section** with the captured output from Step 3:
+     - For each validation command: command line, exit code, last 50 lines of output (or full output if shorter)
+     - Format as fenced code blocks with the command as the heading
+     - This is the durable record that Rule 12 was honored — it must exist before the release section runs
+
+7. Update all tracking:
+   - `specs/phases/README.md` → mark `Complete`
+   - `specs/status.md` → remove this lane's row from the Active Phase table
+     (leave other lanes' rows untouched — Rule 15), update current phase,
+     add release version
+   - `specs/planning/roadmap.md` → update phase status
+   - `specs/changelog/YYYY-MM.md` → add release entry
+
+### Release
+
+> **Gate (Rule 12):** Do NOT enter Release if `retrospective.md` lacks a `## Verification Evidence` section. If evidence is missing, return to Step 3 and capture it.
+
+8. Commit all remaining changes and push:
+   ```bash
+   git add -A
+   git commit -m "docs: complete Phase N - {phase name}"
+   git push origin phase-N-shortname
+   ```
+
+9. Ask the user ONCE for approval to release — present the full plan:
+   ```
+   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
+
+   Proceed?
+   ```
+   Wait for a single "yes" before running any of the following steps.
+
+10. On approval, execute all three steps in sequence.
+
+    **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.
+
+    ```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
+    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
+    ```
+
+12. Report summary to user:
+    - What was delivered
+    - GitHub Release URL
+    - What's next
+
+13. Delete the merged phase branch (ENH-042 — now that merge → main + release
+    are confirmed; do NOT skip this, or stale branches accumulate on origin):
+    ```bash
+    git branch -d phase-N-shortname             # local — `-d` (not `-D`) refuses if unmerged
+    git push origin --delete phase-N-shortname  # remote
+    ```
+
+14. Branch-hygiene self-audit (ENH-042) — confirm no released phase left a
+    dangling branch:
+    ```bash
+    # Any origin branch for an already-released phase should be gone.
+    git branch -r | grep -E 'origin/(phase-|chore/|audit/)' || echo "✓ clean — no stale branches"
+    ```
+    For each match, verify it is fully merged into `main`
+    (`git branch -r --merged main`) and delete it per step 13. Leave any
+    *unmerged* branch alone and surface it to the user.

package/core/commands/ecosystem.md

@@ -0,0 +1,161 @@
+Cross-repo ecosystem coordination (Phase 9 Tier 1).
+
+The ecosystem layer threads multiple momentum-installed repos into one
+coherent unit of work. Use it when a feature or release spans more than
+one repo and you want shared status, shared initiative tracking, and a
+shared daily session log.
+
+> Per-repo phases, backlog, and history stay where they are. The
+> ecosystem layer is additive — it never writes into a member repo's
+> `specs/`. The only touch is one fenced line in CLAUDE.md / AGENTS.md.
+
+## When to use
+
+- The work-at-hand is spread across two or more repos that already have
+  momentum installed (e.g. a backend repo + a frontend repo + an infra
+  repo all participating in one product launch).
+- A user asks for cross-repo status: "what's in flight across the X
+  constellation right now?"
+- A user names an "initiative" or "cross-repo feature" by name — see if
+  it exists as `<ecosystem-root>/initiatives/NNNN-<slug>.md`.
+- A user asks "what happened today?" — read today's session log.
+
+## Discovery
+
+Always start by checking for an ecosystem root:
+
+```bash
+# Walk up from $PWD (bounded to 5 parents) AND scan siblings for
+# ecosystem.json — the helper in core/ecosystem/lib/index.js does this.
+node -e "console.log(require('./core/ecosystem/lib').findRoot(process.cwd()))"
+```
+
+If no ecosystem root exists and the work clearly spans repos, suggest:
+`momentum ecosystem init <name>` from the parent directory.
+
+## Subcommands
+
+### `status`
+
+```
+momentum ecosystem status
+```
+
+Prints the manifest (name, members, dependency edges) and per-member
+git state (modified files + last commit). Use this as the first read
+when context-switching into multi-repo work.
+
+### `add <repo-path>`
+
+```
+momentum ecosystem add ../<repo-name> --role <platform|client|library|infra|bench|other> [--id <id>]
+```
+
+Registers a momentum-installed repo as a member of the current
+ecosystem. Idempotent — safe to re-run. Writes one fenced line into
+the target's CLAUDE.md / AGENTS.md pointing back at the ecosystem.
+
+Pre-flight: target must have CLAUDE.md or AGENTS.md (i.e. have been
+through `momentum init`). The command refuses non-momentum targets.
+
+### `remove <id>`
+
+```
+momentum ecosystem remove <member-id>
+```
+
+Strips the member from `ecosystem.json` and removes the fenced pointer
+from the target's primary instruction file. Tolerant of missing target
+(the manifest is updated even if the member directory is gone).
+
+### `init [name]`
+
+```
+momentum ecosystem init <name>
+```
+
+Scaffolds a fresh ecosystem root: `ecosystem.json`, `initiatives/`,
+`sessions/`, `.state/`, `README.md`, `.gitignore`. Runs `git init` and
+produces the initial commit (best-effort — if git identity is missing
+the scaffold is still valid, user can commit later).
+
+## On-disk layout
+
+```
+<ecosystem-root>/
+├── ecosystem.json          ← manifest (members, roles, dep edges)
+├── README.md
+├── initiatives/            ← cross-repo features (see /initiative)
+│   └── NNNN-<slug>.md
+├── sessions/               ← daily activity log
+│   └── YYYY-MM-DD.md       ← appended by member-repo PostToolUse hook
+├── .state/                 ← runtime state (gitignored)
+│   ├── active-initiative
+│   └── last-session
+└── .gitignore
+```
+
+See `core/ecosystem/layout.md` for the full reference.
+
+## Reading the session log
+
+Today's session file (`sessions/$(date -u +%F).md`) is auto-populated
+by member-repo hooks every time a `git commit` or `gh pr {merge,create}`
+runs. Each line:
+
+```
+HH:MMZ [<member-id>] <kind>: <summary> (<context>)
+```
+
+For a narrated entry not tied to a tool event, use the `/session` slash
+command (`/session log "..."`).
+
+## Reading the manifest
+
+```bash
+cat <ecosystem-root>/ecosystem.json
+```
+
+Or programmatically:
+
+```js
+const lib = require('<momentum>/core/ecosystem/lib');
+const root = lib.findRoot(process.cwd());
+const manifest = lib.loadManifest(root);
+manifest.members.forEach((m) => console.log(m.id, m.role, m.path));
+```
+
+## Composition with other commands
+
+- `/initiative` — manage individual cross-repo features inside this
+  ecosystem (`create`, `status`, `close`, `list`). See its recipe.
+- `/session log <message>` — append a manual narrative entry to
+  today's session log.
+- `/track` — backlog item tracking; lives inside each member repo's
+  `specs/backlog/`. The ecosystem doesn't aggregate backlogs (yet —
+  Tier 2 work).
+- `momentum init` — adds a brand-new momentum project. The ecosystem
+  layer only registers existing momentum-installed repos.
+
+## Failure modes
+
+- "not inside an ecosystem root" — caller is not in or under an
+  ecosystem. Either `cd` into one, or `momentum ecosystem init <name>`
+  to create one.
+- "target doesn't look momentum-installed" — the path passed to `add`
+  doesn't have CLAUDE.md / AGENTS.md. Run `momentum init` on the
+  target first.
+- "member id already registered" — the id is taken by another path.
+  Pass `--id <different>` or `remove` the existing entry first.
+
+## Key principles
+
+- **Strictly additive** — never modify a member repo's `specs/` or any
+  file beyond the one fenced line in its primary instruction file.
+- **Discovery first** — every command walks up looking for the
+  ecosystem root; nothing assumes the cwd.
+- **Idempotent** — `add` is safe to re-run; `remove` is safe even when
+  the target is gone.
+- **Member-internal autonomy** — each member repo's per-repo phases,
+  backlog, history, sync-docs all keep working unchanged. The
+  ecosystem is a thread across them, not a replacement for them.

package/core/commands/hotfix.md

@@ -0,0 +1,64 @@
+Ship an ad-hoc change without a full phase — a bounded `quick-task` (bugfix /
+chore / audit / dependency bump) or a declared `spike` (throwaway exploration).
+Preserves git discipline + tracking; a quick-task still passes the Rule 12
+verification gate. For net-new features or cross-cutting work, use
+`/brainstorm-phase` instead — see the Rule 14 escalation check below.
+
+## Steps
+
+1. **Pick the work type** (see `specs/adhoc/README.md`):
+   - Default → `quick-task`. With `--spike` (or when the user says "spike" /
+     "experiment") → `spike` (gate-exempt, throwaway).
+
+2. **Rule 14 escalation check — STOP if this should be a phase.** Escalate to
+   `/brainstorm-phase` instead if the change: touches more than ~5 files of
+   production code, modifies anything under `specs/architecture/`, needs an
+   ADR, changes a public contract/interface, or displaces a planned phase.
+   When in doubt, ask the user. Do NOT smuggle a phase-sized change through
+   the ad-hoc lane.
+
+3. **Branch** (Rule 6 — never work on `main`/`staging`):
+   - quick-task bugfix → `fix/BUG-NNN-short-desc`
+   - quick-task chore → `chore/short-desc`
+   - spike → `spike/short-desc`
+
+4. **Open the ad-hoc record.** Choose `<id>`: the backlog id if one exists
+   (e.g. `BUG-009`), else `YYYY-MM-DD-<slug>`. Then:
+   ```bash
+   mkdir -p specs/adhoc/<id>
+   cp specs/adhoc/_TEMPLATE.md specs/adhoc/<id>/record.md
+   ```
+   Fill **Current / Expected / Unchanged Behavior**. The Unchanged-Behavior
+   line is the blast-radius guardrail — be explicit about what must NOT change.
+
+5. **Track it** (Rule 3): ensure the backlog has a row (`/track` if not). A
+   pure chore with no backlog id is fine — note "Backlog: none" in the record.
+
+6. **Do the work.** Commit with Conventional Commits (the `commit-msg` hook
+   enforces this). Keep commits atomic.
+
+7. **Verify (Rule 12) — the gate.**
+   - `quick-task`: run the real verification command(s); paste fresh output
+     (command + exit status) into the record's `## Verification Evidence`.
+     This is REQUIRED before merge.
+   - `spike`: write `spike — gate-exempt` there plus one line on what was
+     learned and the follow-up (file a backlog item if the spike found work).
+
+8. **Log the why** (Rule 8, phase-optional): append decisions/discoveries to
+   `specs/adhoc/<id>/record.md` (or `specs/adhoc/history.md`) via `/log`.
+   Update `specs/changelog/YYYY-MM.md` with a one-line entry.
+
+9. **Merge + (optional) release** — needs explicit user approval (Rule 6):
+   - Ask the user before merging to `main`/`staging`. After approval, authorize
+     the single push with the sentinel the `pre-push` hook consumes:
+     ```bash
+     touch .momentum/merge-approved   # single-use; consumed on push to main
+     ```
+   - If this ships a version bump, add a row to the **Ad-hoc / Patch Releases**
+     section of `specs/status.md` (NOT the Completed Phases table). The
+     `pre-push` release-tag gate requires the record's `## Verification
+     Evidence` to be non-empty — so a spike must not cut a release tag.
+
+10. **Clean up**: after a confirmed merge, delete the branch
+    (`git branch -d <branch>` + `git push origin --delete <branch>`), and set
+    the record `Status:` to `shipped` (or `abandoned` for a dropped spike).

package/core/commands/initiative.md

@@ -0,0 +1,119 @@
+Manage cross-repo initiatives in an ecosystem.
+
+Initiatives are first-class records of features that span multiple
+member repos. Each initiative is one markdown file under
+`<ecosystem-root>/initiatives/NNNN-<slug>.md` with a small YAML
+frontmatter block (id, slug, status, started, owner, repos).
+
+This command must be run from inside an ecosystem root or any of its
+member repos (the ecosystem root is discovered by walking up).
+
+## Subcommands
+
+```
+/initiative create <slug>     Create a new initiative + activate it
+/initiative status [<slug>]   Print the named (or active) initiative card
+/initiative close <slug>      Populate the Close section + deactivate
+/initiative list              List all initiatives in this ecosystem
+```
+
+## Steps for `create`
+
+1. Locate the ecosystem root via the walk-up helper
+   (`core/ecosystem/lib/index.js → findRoot`). If none found, abort
+   with a clear message: "Not inside an ecosystem. Run `momentum
+   ecosystem init` first."
+
+2. Validate the `<slug>` matches `/^[a-z][a-z0-9-]*$/`. If not, abort.
+
+3. Allocate the next initiative id via `nextInitiativeId(root)`
+   (scans existing files for the highest `NNNN-` prefix).
+
+4. Prompt the user (one question at a time) for:
+   - **Why** — one-paragraph motivation
+   - **Repos involved** — defaults to all members; allow comma-separated
+     subset
+   - **Owner** — defaults to git config user.name or env USER
+
+5. Render the initiative file from
+   `core/ecosystem/templates/initiative-template.md`, substituting the
+   frontmatter + the user's "Why" text. Leave the
+   "Per-repo contributions", "Linked decisions", "Deploy chronology"
+   sections empty (they'll fill in as work lands).
+
+6. Write the file to `<root>/initiatives/<NNNN>-<slug>.md` via
+   `writeInitiative(filePath, frontmatter, content)`. This re-validates
+   the frontmatter.
+
+7. Set the slug as the active initiative:
+   `setActive(root, slug)` (writes `<root>/.state/active-initiative`).
+
+8. Print confirmation:
+   ```
+   Created initiative 0042-<slug>.md. Active.
+   ```
+
+## Steps for `status`
+
+1. Resolve the target slug: argument if given; else read
+   `<root>/.state/active-initiative`; else abort with
+   "No active initiative. Pass <slug> or `/initiative create` first."
+
+2. Load the file via `loadInitiative(root, slug)`. Print:
+   - Frontmatter as a header block (status, owner, started, repos)
+   - "Per-repo contributions" section verbatim
+   - For each repo in `repos[]`, run `gh pr list --repo <owner>/<repo>
+     --state open --json number,title,headRefName` (best-effort; degrade
+     gracefully if `gh` not authenticated) and append a one-line
+     summary per open PR.
+   - For each repo, print last 3 commits via `git -C <repo-path>
+     log -3 --oneline`.
+
+3. If `<root>/.state/active-initiative` matches this slug, print:
+   `(active)` in the header.
+
+## Steps for `close`
+
+1. Resolve slug from argument (required for close — no implicit
+   "close the active one" to avoid surprises).
+
+2. Load the initiative; abort if already `status: closed`.
+
+3. Prompt the user (one question at a time):
+   - **What shipped?**
+   - **What was deferred?**
+   - **What was learned?**
+
+4. Append a populated `## Close` section (preserving any existing
+   sections above it). Set frontmatter `status: closed` and
+   `closed: <today>`. Write back via `writeInitiative`.
+
+5. If this slug was active, clear `.state/active-initiative` via
+   `clearActive(root)`.
+
+6. Print confirmation:
+   ```
+   Closed initiative <slug>. State cleared.
+   ```
+
+## Steps for `list`
+
+1. Read every `NNNN-*.md` file in `<root>/initiatives/`. Sort by
+   numeric id ascending.
+
+2. For each, print:
+   ```
+   NNNN <slug>  status  started→closed-or-‹in-progress›  repos: a, b, c
+   ```
+
+3. If `.state/active-initiative` is set, mark that row with `←active`.
+
+## Key principles
+
+- **Idempotent prompts** — running `/initiative create <existing-slug>`
+  must refuse with a clear error, never silently overwrite.
+- **Frontmatter is the source of truth** — body sections are free-form
+  human writing; the agent doesn't reformat them when re-reading.
+- **Cross-repo, not in-repo** — initiatives live in the ecosystem root,
+  not inside any one member's `specs/`. The member-repo phases stay
+  authoritative for their own work; initiatives link across them.