@limina-labs/momentum 0.30.2

package/core/ecosystem/templates/ecosystem-claude.md

@@ -0,0 +1,79 @@
+# {{NAME}} — Ecosystem (Coordination Layer)
+
+> **You are in a momentum ecosystem coordination root — NOT a project.**
+> This directory coordinates work across multiple sibling project repos.
+> Auto-managed by `momentum`. The content above `## Project Extensions`
+> may be refreshed by `momentum upgrade`.
+
+## What this directory is
+
+| Path | Purpose |
+|------|---------|
+| `ecosystem.json` | Manifest: members, roles, dependency edges |
+| `initiatives/` | Cross-repo feature files (`NNNN-<slug>.md`) — first-class records of features that span >1 member |
+| `sessions/` | Auto-appended daily activity log (`YYYY-MM-DD.md`); member-repo hooks write here |
+| `.state/` | Runtime state (gitignored) — active initiative pointer, etc. |
+| `CLAUDE.md` / `AGENTS.md` | These instructions |
+
+**There are no `specs/` here.** Per-project specs, phases, backlog, and history stay in each member repo. The ecosystem layer is strictly additive — it never writes into a member's `specs/`.
+
+## Cross-repo work? Write an initiative — NEVER plan implementation here
+
+If a feature, refactor, or coordination effort touches MORE THAN ONE member repo, the entry point is an **initiative**:
+
+```bash
+momentum ecosystem initiative create <slug> \
+  --why "<one-paragraph motivation>" \
+  --repos <member-id-1>,<member-id-2> \
+  --owner <you>
+```
+
+This writes `initiatives/NNNN-<slug>.md` and sets it as active. The initiative is the *only* place cross-repo scope, deploy chronology, and links to per-repo decisions live. Per-repo implementation phases stay in each member's `specs/phases/`.
+
+**Anti-pattern:** do not create planning notes, task lists, or "phase" files directly in this coordination root. There is no `specs/phases/`. If you find yourself reaching for one, you are working in the wrong layer — switch to a member repo or create an initiative.
+
+## Orchestration primitives (use these for multi-repo work)
+
+These are slash commands you should invoke when working across member repos. Each has a CLI fallback under `momentum <name>`; the slash command is the LLM-synthesis door, the CLI is the keyword/scripted door.
+
+| Primitive | When to use |
+|---|---|
+| `/scout <repo>` | Read-only context fetch from another member ("what's in `<repo>/specs/status.md` right now?"). Use before planning any cross-repo work. |
+| `/dispatch <r1> <r2> "<intent>"` | Parallel multi-repo audit/investigation ("audit how X is implemented across A, B, C"). Spawns one sub-agent per repo and synthesises. **Do NOT use `momentum dispatch` from the CLI for synthesis** — CLI mode produces keyword summaries only; use the slash command. |
+| `/handoff <repo>` | Transfer context to an agent working in another member repo. Writes a structured handoff into the target's `.momentum/inbox/`. The receiving agent picks it up via `/continue` on session start. |
+| `/continue` | Pick up a pending handoff from this repo's inbox (SessionStart hook surfaces these automatically). |
+| `/initiative create <slug>` | Same as the CLI above; the slash door also wires the active initiative for follow-up `/session log` entries. |
+| `/session log "<note>"` | Append a narrative entry to today's `sessions/YYYY-MM-DD.md`. Auto-events (commits/PRs) are logged by the PostToolUse hook in each member; use `/session log` for decisions, problems hit, checkpoint notes. |
+
+## Discovery — how to find current state
+
+```bash
+momentum ecosystem status        # manifest summary + per-member git state
+cat ecosystem.json               # raw manifest
+ls initiatives/                  # all initiatives, active marked in .state/active-initiative
+tail sessions/$(date -u +%F).md  # what happened today
+```
+
+## Quick member management
+
+```bash
+momentum ecosystem add ../<repo-name>    # register a member (must already be `momentum init`-installed)
+momentum ecosystem remove <member-id>    # unregister
+```
+
+`add` also injects a fenced pointer block into the member's `CLAUDE.md`/`AGENTS.md` so agents working *inside* the member know they're part of this ecosystem and can reach the orchestration primitives.
+
+## Docs
+
+- Full ecosystem mode: https://trymomentum.github.io/ecosystem/
+- Orchestration primitives: https://trymomentum.github.io/orchestration/
+- Concepts: https://trymomentum.github.io/concepts/
+
+---
+
+## Project Extensions
+
+> Everything below this heading is preserved across `momentum upgrade`.
+> Add ecosystem-specific notes, conventions, cross-repo references,
+> escalation contacts, etc. here. Anything above this heading is
+> managed by momentum and may be refreshed on upgrade.

package/core/ecosystem/templates/ecosystem-settings-claude.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/sessionstart-handoff.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/core/ecosystem/templates/initiative-template.md

@@ -0,0 +1,50 @@
+---
+id: 0
+slug: replace-me
+title: Replace me
+status: in-progress
+started: 1970-01-01
+owner: replace-me
+repos: []
+---
+
+# Initiative {{ID}} — {{TITLE}}
+
+> Cross-repo feature spanning {{REPOS}}.
+> Started {{STARTED}} by {{OWNER}}.
+
+## Why
+
+One short paragraph that captures the motivation for this initiative.
+What problem are we solving? Why does it span multiple repos? What
+becomes possible once it ships?
+
+## Per-repo contributions
+
+For each member repo touched, list the contributing branches, PRs,
+and phases. Update as work lands.
+
+- **{{REPO_1}}**: …
+- **{{REPO_2}}**: …
+
+## Linked decisions
+
+ADRs, scope changes, or decisions taken in any member repo's
+`specs/decisions/` or `specs/phases/<phase>/history.md` that this
+initiative implements or depends on. Cross-repo links allowed.
+
+- …
+
+## Deploy chronology
+
+When the initiative ships in stages across repos, log the order here.
+Timestamps in UTC. Format:
+`YYYY-MM-DD HH:MMZ — <member> <sha> — <one-line summary>`
+
+- …
+
+## Close
+
+Populated by `momentum ecosystem initiative close <slug>`. Captures:
+what shipped, what was deferred, what was learned. Mirrors the role of
+a phase retrospective at the cross-repo level.

package/core/engines/subagent-dispatch.md

@@ -0,0 +1,80 @@
+# Subagent Dispatch Contract
+
+This contract defines the core coordination patterns for how AI coding agents (such as Claude Code or Antigravity) dispatch background subagents or sub-tasks autonomously during a development phase.
+
+Adapters that declare `subagents: true` in their capabilities must implement these dispatch interfaces to keep the core workflow tool-agnostic.
+
+---
+
+## 1. Persona and Role Declarations
+
+When spawning a subagent, the parent agent must declare a specialized **Persona** or **Role** from this list. Do not use generic or ad-hoc personas.
+
+| Role Name | Scope & Focus | Typical Tools Needed |
+|-----------|---------------|----------------------|
+| `QA Engineer` | Writes test files, designs edge-case inputs, runs validations | `read_file`, `write_file`, `command` |
+| `Security Reviewer` | Analyzes code for secrets leakage, unsafe operations, overflow risks | `read_file` |
+| `Architecture Guard` | Asserts alignment with SOLID, DIP boundaries, and design specs | `read_file` |
+| `Researcher` | Gathers context, reads library documentation, runs web searches | `read_file`, `read_url`, `web_search` |
+| `Developer` | Implements logic changes, fixes bugs, formats code | `read_file`, `write_file`, `command` |
+
+---
+
+## 2. Dispatch Patterns
+
+The engine supports two primary coordination patterns for executing subagents:
+
+### Pattern A: Sequential with Feedback
+
+Used for iterative refinement of a single task (such as bug fixing or feature implementation).
+
+```mermaid
+sequenceDiagram
+    Parent Agent->>Subagent (Developer): Run task with instructions
+    Subagent (Developer)->>Parent Agent: Proposed edits & code
+    Parent Agent->>Parent Agent: Run Group Verification Command
+    alt Verification Passes
+        Parent Agent->>Parent Agent: Commit & check tasks
+    else Verification Fails (Strike N)
+        Parent Agent->>Subagent (Developer): Return stdout/stderr feedback & reframe instructions
+    end
+```
+
+*   **Strike/Retry Budget**: The sequential loop is capped at a maximum of **3 strikes** (reframes) before the parent agent must perform a discretionary stop and request user intervention.
+
+### Pattern B: Parallel Fan-Out
+
+Used for comprehensive review, research, or cross-cutting analysis.
+
+```mermaid
+sequenceDiagram
+    Parent Agent->>Subagent (Security): Review branch changes
+    Parent Agent->>Subagent (QA): Review branch changes
+    Parent Agent->>Subagent (Arch): Review branch changes
+    Subagent (Security)->>Parent Agent: Report findings
+    Subagent (QA)->>Parent Agent: Report findings
+    Subagent (Arch)->>Parent Agent: Report findings
+    Parent Agent->>Parent Agent: Aggregate into markdown report
+```
+
+*   **Aggregation**: Parent agents must aggregate parallel subagent outputs into a single consolidated, user-visible markdown document (e.g. `/review-code` aggregates security, QA, and architectural reviews).
+
+---
+
+## 3. Error Handling and Aggression
+
+1.  **Failing Fast**: If a subagent encounters a permission error, missing credentials, or external billing failure, it must immediately report this to the parent. The parent must perform a discretionary stop.
+2.  **No Leaked Side-Effects**: Subagents must only operate within the target workspace. Any temporary scratch directories must be cleaned up on completion.
+3.  **Validation Dominance**: The parent agent's validation commands always override a subagent's claim of completion. A task is only `[x]` complete if the parent-executed verification command exits `0`.
+
+---
+
+## 4. Adapter Integration Guides
+
+### Claude Code (`claude-code`)
+*   **Wiring**: Claude Code dispatches subagents using the native `Task` tool.
+*   **Context Sizing**: Limit subagent task descriptions to keep prompt overhead low.
+
+### Antigravity (`antigravity`)
+*   **Wiring**: Antigravity dispatches subagents using the native `invoke_subagent` and `define_subagent` tools.
+*   **Artifact Alignment**: The parent Antigravity agent updates `task.md` and `implementation_plan.md` in the parent context when subagents report success.

package/core/git-hooks/commit-msg

@@ -0,0 +1,14 @@
+#!/bin/sh
+# momentum commit-msg hook (Phase 19 — Lifecycle Hardening).
+# Validates that the commit subject is a Conventional Commit. All logic lives
+# in run-check.js (shared with the installer + /hotfix, unit-tested) so this
+# wrapper stays trivial. Vendor-neutral: pure git, runs under any agent.
+#
+# Bypass for emergencies:  MOMENTUM_SKIP_HOOKS=1 git commit ...
+dir=$(dirname "$0")
+if command -v node >/dev/null 2>&1; then
+  exec node "$dir/run-check.js" commit-msg "$1"
+fi
+# No node on PATH — cannot enforce; allow rather than block the commit.
+echo "momentum: node not found on PATH — skipping commit-msg validation." >&2
+exit 0

package/core/git-hooks/contract.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * Phase 19 — Lifecycle Hardening, Group 0.
+ *
+ * Canonical contract for momentum's git-lifecycle + ad-hoc-work enforcement.
+ * PURE functions + constants only — NO fs access, NO process side effects —
+ * so that the git hooks (core/git-hooks/run-check.js), the installer
+ * (bin/momentum.js), and the /hotfix command all share ONE source of truth,
+ * and the logic is unit-testable in isolation.
+ *
+ * Vendor-neutral by design (DIP): pure git, no forge API. Enforcement lives in
+ * plain git hooks that work on any forge and under any agent. See
+ * core/lifecycle-contract.md for the full reference.
+ */
+
+const CONTRACT = {
+  // Hooks ship as plain scripts in a tracked dir, wired via
+  // `git config core.hooksPath`. No husky/lefthook — zero dependencies.
+  hooksPath: '.githooks',
+
+  // Emergency bypass for ALL momentum git hooks (e.g. MOMENTUM_SKIP_HOOKS=1).
+  skipEnv: 'MOMENTUM_SKIP_HOOKS',
+
+  // Single-use sentinel authorizing ONE push to a protected branch. Created
+  // by the agent only after the user approves a merge; consumed on use.
+  mergeApprovedSentinel: '.momentum/merge-approved',
+
+  // Direct pushes to these branches are blocked unless the sentinel exists.
+  // 'master' included for downstream repos that haven't renamed to 'main'.
+  protectedBranches: ['main', 'master', 'staging'],
+
+  // Canonical Verification-Evidence heading in retrospective.md (Rule 12).
+  // The same heading gates ad-hoc records (specs/adhoc/<id>/record.md).
+  verifyEvidenceHeading: '## Verification Evidence',
+
+  // Allowed Conventional-Commit types: momentum's stated set
+  // (feat/fix/docs/refactor/chore/infra) plus the standard extras the project
+  // actually uses (test/perf/build/ci/style/revert).
+  conventionalTypes: [
+    'feat', 'fix', 'docs', 'refactor', 'chore', 'infra',
+    'test', 'perf', 'build', 'ci', 'style', 'revert',
+  ],
+
+  // First-class work types (Rule 14). 'phase' = full ceremony; 'quick-task' =
+  // ad-hoc record + Rule 12 gate, no phase scaffold; 'spike' = declared,
+  // gate-exempt, throwaway.
+  workTypes: ['phase', 'quick-task', 'spike'],
+};
+
+// Subjects that bypass type validation (git-generated or WIP markers).
+// 'merge: ' covers the house merge style `merge: x → y` alongside git's
+// default `Merge ` (BUG-015 — CLAUDE.md Naming Conventions + repo history).
+const COMMIT_SUBJECT_BYPASS = /^(Merge |merge: |Revert "|fixup!|squash!|amend!|Initial commit$)/;
+
+/**
+ * True when the emergency bypass env var is set to a truthy value.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function skipRequested(env) {
+  const e = env || (typeof process !== 'undefined' ? process.env : {});
+  const v = e[CONTRACT.skipEnv];
+  return v != null && v !== '' && v !== '0' && String(v).toLowerCase() !== 'false';
+}
+
+/**
+ * The first non-empty, non-comment line of a commit message (the subject).
+ * @param {string} message
+ * @returns {string}
+ */
+function firstMeaningfulLine(message) {
+  if (!message) return '';
+  for (const raw of String(message).split('\n')) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    return line;
+  }
+  return '';
+}
+
+/**
+ * True when a commit subject conforms to Conventional Commits (or is a
+ * git-generated/WIP subject that bypasses validation).
+ * @param {string} subject
+ * @param {string[]} [types]
+ */
+function isValidCommitSubject(subject, types) {
+  const s = (subject || '').trim();
+  if (s === '') return false;
+  if (COMMIT_SUBJECT_BYPASS.test(s)) return true;
+  const typeAlt = (types || CONTRACT.conventionalTypes).join('|');
+  // type(scope)!: description — scope and ! optional; single space after colon.
+  const re = new RegExp('^(' + typeAlt + ')(\\([^)]+\\))?(!)?: .+');
+  return re.test(s);
+}
+
+/**
+ * Validate a full commit message; returns { subject, valid }.
+ * @param {string} message
+ * @param {string[]} [types]
+ */
+function validateCommitMessage(message, types) {
+  const subject = firstMeaningfulLine(message);
+  return { subject, valid: isValidCommitSubject(subject, types) };
+}
+
+/** refs/heads/main -> 'main'; non-branch refs -> null. */
+function branchFromRef(ref) {
+  if (!ref) return null;
+  const m = /^refs\/heads\/(.+)$/.exec(ref);
+  return m ? m[1] : null;
+}
+
+/** refs/tags/v1.2.3 -> 'v1.2.3'; non-tag refs -> null. */
+function tagFromRef(ref) {
+  if (!ref) return null;
+  const m = /^refs\/tags\/(.+)$/.exec(ref);
+  return m ? m[1] : null;
+}
+
+/** True for a semver release tag (v1.2.3, v1.2.3-rc.1, ...). */
+function isReleaseTag(tag) {
+  return !!tag && /^v\d+\.\d+\.\d+/.test(tag);
+}
+
+/** True when `branch` is in the protected list. */
+function branchIsProtected(branch, list) {
+  return !!branch && (list || CONTRACT.protectedBranches).includes(branch);
+}
+
+/**
+ * True when `content` (a retrospective.md or ad-hoc record) has a non-empty
+ * `## Verification Evidence` section — i.e. ≥1 non-blank, non-heading line
+ * before the next heading.
+ * @param {string} content
+ * @param {string} [heading]
+ */
+function retroHasEvidence(content, heading) {
+  if (!content) return false;
+  const target = (heading || CONTRACT.verifyEvidenceHeading).trim();
+  const lines = String(content).split('\n');
+  const idx = lines.findIndex((l) => l.trim() === target);
+  if (idx === -1) return false;
+  for (let i = idx + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (/^#{1,6}\s/.test(line)) break; // next heading ends the section
+    if (line !== '') return true;
+  }
+  return false;
+}
+
+/**
+ * Parse a pre-push stdin line: "<localRef> <localSha> <remoteRef> <remoteSha>".
+ * Returns null for malformed lines.
+ */
+function parsePrePushLine(line) {
+  const parts = (line || '').trim().split(/\s+/);
+  if (parts.length < 4 || parts[0] === '') return null;
+  const [localRef, localSha, remoteRef, remoteSha] = parts;
+  return { localRef, localSha, remoteRef, remoteSha };
+}
+
+module.exports = {
+  CONTRACT,
+  COMMIT_SUBJECT_BYPASS,
+  skipRequested,
+  firstMeaningfulLine,
+  isValidCommitSubject,
+  validateCommitMessage,
+  branchFromRef,
+  tagFromRef,
+  isReleaseTag,
+  branchIsProtected,
+  retroHasEvidence,
+  parsePrePushLine,
+};

package/core/git-hooks/pre-push

@@ -0,0 +1,15 @@
+#!/bin/sh
+# momentum pre-push hook (Phase 19 — Lifecycle Hardening).
+# Blocks (a) direct pushes to protected branches without the single-use
+# .momentum/merge-approved sentinel, and (b) release-tag pushes lacking
+# verification evidence (Rule 12). Logic lives in run-check.js (unit-tested).
+# Vendor-neutral: pure git, runs under any agent on any forge.
+#
+# git passes <remote> <url> as args and the pushed refs on stdin; we forward
+# both. Bypass for emergencies:  MOMENTUM_SKIP_HOOKS=1 git push ...
+dir=$(dirname "$0")
+if command -v node >/dev/null 2>&1; then
+  exec node "$dir/run-check.js" pre-push "$@"
+fi
+echo "momentum: node not found on PATH — skipping pre-push checks." >&2
+exit 0

package/core/git-hooks/run-check.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Phase 19 — Lifecycle Hardening, Group 1.
+ *
+ * momentum git-hook dispatcher: a thin I/O layer over the pure contract in
+ * ./contract.js. Invoked by the .githooks/commit-msg and .githooks/pre-push
+ * shell wrappers. All decision logic lives in contract.js (unit-tested);
+ * this file only does fs/stdin/exit-code plumbing.
+ *
+ * Vendor-neutral: pure git, no forge API. Runs under any agent on any forge.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const C = require('./contract');
+
+// git invokes hooks with cwd = repo root.
+function repoRoot() {
+  return process.cwd();
+}
+
+function fail(msg) {
+  process.stderr.write(`\n✖ momentum git hook blocked this action:\n  ${msg}\n`);
+  process.stderr.write(`\n  Emergency bypass (use sparingly): ${C.CONTRACT.skipEnv}=1 <git command>\n\n`);
+  process.exit(1);
+}
+
+// ── commit-msg ────────────────────────────────────────────────────────────────
+function commitMsg(msgFile) {
+  if (C.skipRequested()) process.exit(0);
+  let content = '';
+  try {
+    content = fs.readFileSync(msgFile, 'utf8');
+  } catch {
+    process.exit(0); // no message file — let git handle it
+  }
+  const { subject, valid } = C.validateCommitMessage(content);
+  if (valid) process.exit(0);
+  fail(
+    `commit subject is not a Conventional Commit:\n      "${subject}"\n` +
+    `  Expected:  <type>(scope?)!: description\n` +
+    `  where <type> is one of: ${C.CONTRACT.conventionalTypes.join(', ')}`
+  );
+}
+
+// ── pre-push ──────────────────────────────────────────────────────────────────
+function findLatestRetro(root) {
+  const specsDir = path.join(root, 'specs');
+  if (!fs.existsSync(specsDir)) return null;
+  const candidates = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('._')) continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        walk(p);
+      } else if (
+        e.name === 'retrospective.md' ||
+        (e.name === 'record.md' && dir.split(path.sep).includes('adhoc'))
+      ) {
+        try {
+          candidates.push({ p, mtime: fs.statSync(p).mtimeMs });
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  };
+  walk(specsDir);
+  if (!candidates.length) return null;
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  return candidates[0].p;
+}
+
+function prePush() {
+  if (C.skipRequested()) process.exit(0);
+
+  let input = '';
+  try {
+    input = fs.readFileSync(0, 'utf8'); // git pipes ref lines on stdin
+  } catch {
+    input = '';
+  }
+  const root = repoRoot();
+  const lines = input.split('\n').map((l) => l.trim()).filter(Boolean);
+
+  for (const line of lines) {
+    const parsed = C.parsePrePushLine(line);
+    if (!parsed) continue;
+    if (/^0+$/.test(parsed.localSha)) continue; // branch/tag deletion — skip
+
+    // (1) Block direct push to a protected branch without the approval sentinel.
+    const branch = C.branchFromRef(parsed.remoteRef);
+    if (C.branchIsProtected(branch)) {
+      const sentinel = path.join(root, C.CONTRACT.mergeApprovedSentinel);
+      if (fs.existsSync(sentinel)) {
+        try {
+          fs.unlinkSync(sentinel); // single-use: consume on push
+        } catch {
+          /* ignore */
+        }
+        process.stderr.write(
+          `  momentum: '${C.CONTRACT.mergeApprovedSentinel}' consumed — push to '${branch}' authorized.\n`
+        );
+      } else {
+        fail(
+          `direct push to protected branch '${branch}' is blocked.\n` +
+          `  Merging to '${branch}' needs explicit human approval. After the user approves,\n` +
+          `  authorize a single push with the single-use sentinel:\n` +
+          `      touch ${C.CONTRACT.mergeApprovedSentinel}\n` +
+          `  (it is consumed on push).`
+        );
+      }
+    }
+
+    // (2) Block a release-tag push lacking verification evidence (Rule 12 / FEAT-019).
+    const tag = C.tagFromRef(parsed.remoteRef);
+    if (C.isReleaseTag(tag)) {
+      const retro = findLatestRetro(root);
+      // Only enforce where the retrospective convention is in use. A project
+      // with no retrospective at all is not gated.
+      if (retro) {
+        let content = '';
+        try {
+          content = fs.readFileSync(retro, 'utf8');
+        } catch {
+          content = '';
+        }
+        if (!C.retroHasEvidence(content)) {
+          fail(
+            `release tag '${tag}' is blocked: the most recent retrospective\n` +
+            `      (${path.relative(root, retro)})\n` +
+            `  has no non-empty '${C.CONTRACT.verifyEvidenceHeading}' section.\n` +
+            `  Capture fresh verification output there (Rule 12) before tagging a release.`
+          );
+        }
+      }
+    }
+  }
+  process.exit(0);
+}
+
+// ── dispatch ──────────────────────────────────────────────────────────────────
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === 'commit-msg') {
+  commitMsg(rest[0]);
+} else if (cmd === 'pre-push') {
+  prePush();
+} else {
+  process.stderr.write(`momentum run-check: unknown command '${cmd}'\n`);
+  process.exit(0); // unknown → don't block
+}

package/core/instructions/legacy-project-md-hashes.json

@@ -0,0 +1,12 @@
+{
+  "description": "SHA-256 of every historically shipped revision of core/agent-rules/project.md (retired by Phase 23 / ADR-0004). Used by `momentum upgrade` to distinguish a pristine installed copy (delete) from a user-customized one (keep + deprecation warning). Harvested 2026-07-04 via: git log --all --format=%H -- core/agent-rules/project.md | while read c; do git ls-tree $c -- core/agent-rules/project.md; done | awk '{print $3}' | sort -u | xargs -I{} sh -c 'git cat-file blob {} | shasum -a 256'",
+  "sha256": [
+    "42956f18f619aaa2a666326b3873ca41d8aa6c530d3eff2240f12592bdcf1916",
+    "e9e99f7b4230bfdb95a44fe967d5d7559eec7d7f559158dca3e822887b77988a",
+    "59117d0f582f1f387a9851dc322b91e97d6eba19d091de2b2a258238ad6f4629",
+    "bd41b8a1369f88ffaaee13f7d441c845b2ab30789695c8460b7a2d1f7acadfd7",
+    "175bc78d3370130c195fb0a5c4b1cc151c5594e8c7eb1c759db0906abaa4b8ee",
+    "1d3815740b5956e9524ab8f3acf3cccfe11c20560c08d7f1d0aef2ca0a0f14a9",
+    "e35fd7461cab76fb61b8bf601c837ac278b476507d9d56319281a9a332038313"
+  ]
+}

package/core/instructions/navigation.md

@@ -0,0 +1,14 @@
+## Navigation (Where to Find Things)
+
+| Question | File |
+|----------|------|
+| Current state / what phase? | `specs/status.md` |
+| 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` |
+| How to contribute? | `docs/developer-guide.md` |
+
+> **First file to read: ALWAYS `specs/status.md`.**
+
+---