@limina-labs/momentum 0.30.2

package/core/ecosystem/lib/state.js

@@ -0,0 +1,295 @@
+'use strict';
+
+/**
+ * Repo state detection — the contract Phase 10's `momentum doctor`
+ * and entry/exit commands depend on.
+ *
+ * A momentum-managed directory is in exactly one state. Knowing the
+ * state lets us decide what commands the user can run next.
+ *
+ * States:
+ *   standalone           — momentum-installed; not in any ecosystem.
+ *   member               — momentum-installed; pointer present; listed
+ *                          in a reachable ecosystem's manifest.
+ *   leader               — ecosystem root (has ecosystem.json); not
+ *                          itself a member of another ecosystem.
+ *   leader-and-member    — ecosystem root that is ALSO a member of a
+ *                          different ecosystem (rare; legal).
+ *   broken-manifest      — has ecosystem.json that fails validation.
+ *   broken-pointer       — has pointer block but is NOT registered
+ *                          in any reachable ecosystem.
+ *   broken-orphan        — registered in an ecosystem but the pointer
+ *                          block is missing from the primary file.
+ *
+ * `availableTransitions(state)` returns user-facing next-step commands
+ * for the doctor recipe to print as teaching output.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const lib = require('./index');
+const pointer = require('./pointer');
+
+const MAX_PARENT_WALK_DEFAULT = 5;
+const MAX_PARENT_WALK_ENV = 'MOMENTUM_MAX_PARENT_WALK';
+
+/**
+ * Resolve the active parent-walk limit, honoring `MOMENTUM_MAX_PARENT_WALK`
+ * env override. Negative/non-numeric values fall back to the default.
+ */
+function getMaxParentWalk() {
+  const raw = process.env[MAX_PARENT_WALK_ENV];
+  if (raw === undefined || raw === '') return MAX_PARENT_WALK_DEFAULT;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return MAX_PARENT_WALK_DEFAULT;
+  return Math.floor(n);
+}
+
+/**
+ * Detect the current state of `repoPath`. Inspects four signals:
+ *   - ecosystem.json presence + validity here
+ *   - pointer block in primary instruction file
+ *   - membership in any reachable ecosystem (walks up + scans siblings)
+ *
+ * Returns one of the seven state strings documented at the top.
+ *
+ * Note on cost: this calls `loadManifest` + `validateManifest` for any
+ * ecosystem.json in scope. For doctor-style invocations the overhead
+ * is irrelevant. State is not cached; callers cache if needed.
+ */
+function detectState(repoPath) {
+  const abs = path.resolve(repoPath);
+
+  // 1. Is this directory itself an ecosystem root?
+  let isLeader = false;
+  let leaderBroken = false;
+  const localManifestPath = path.join(abs, lib.MANIFEST_FILENAME);
+  if (safeIsFile(localManifestPath)) {
+    isLeader = true;
+    try {
+      const manifest = lib.loadManifest(abs);
+      const v = lib.validateManifest(manifest);
+      if (!v.ok) leaderBroken = true;
+    } catch (_err) {
+      leaderBroken = true;
+    }
+  }
+
+  // 2. Pointer block present?
+  const hasPtr = pointer.hasPointerBlock(abs);
+
+  // 3. Is this directory registered as a member of some reachable ecosystem?
+  const registration = findRegistration(abs);
+  const isRegistered = registration !== null;
+
+  // Combine signals.
+  if (leaderBroken) return 'broken-manifest';
+  if (isLeader && hasPtr && isRegistered) return 'leader-and-member';
+  if (isLeader) return 'leader';
+  if (hasPtr && isRegistered) return 'member';
+  if (hasPtr && !isRegistered) return 'broken-pointer';
+  if (!hasPtr && isRegistered) return 'broken-orphan';
+  return 'standalone';
+}
+
+/**
+ * Walk up looking for ecosystem.json files, scanning each manifest's
+ * members[].path to see if `repoAbs` is registered. Returns
+ *   { rootPath, ecosystemName, memberId, memberRole }
+ * on first match, or null. Bounded by MAX_PARENT_WALK.
+ *
+ * The walk pattern mirrors session-append.sh: an ecosystem is a SIBLING
+ * of its members, so from a member we walk up and check each sibling
+ * for ecosystem.json (and also check `current` itself in case the caller
+ * is in the ecosystem root).
+ */
+function findRegistration(repoAbs) {
+  const max = getMaxParentWalk();
+  let current = repoAbs;
+  for (let depth = 0; depth <= max; depth++) {
+    // Check current dir's siblings.
+    const parent = path.dirname(current);
+    let siblings = [];
+    try {
+      siblings = fs.readdirSync(parent, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => path.join(parent, e.name));
+    } catch (_err) {
+      // unreadable parent — skip siblings, keep walking
+    }
+    for (const sib of siblings) {
+      const reg = matchInManifest(sib, repoAbs);
+      if (reg) return reg;
+    }
+    // Also check `current` itself (handles leader+member case).
+    const selfReg = matchInManifest(current, repoAbs);
+    if (selfReg) return selfReg;
+
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function matchInManifest(candidateRoot, repoAbs) {
+  const manifestPath = path.join(candidateRoot, lib.MANIFEST_FILENAME);
+  if (!safeIsFile(manifestPath)) return null;
+  let manifest;
+  try {
+    manifest = lib.loadManifest(candidateRoot);
+  } catch (_err) {
+    return null;
+  }
+  if (!lib.validateManifest(manifest).ok) return null;
+  for (const m of lib.listMembers(manifest)) {
+    if (!m || typeof m.path !== 'string') continue;
+    const memberAbs = path.resolve(candidateRoot, m.path);
+    if (samePath(memberAbs, repoAbs)) {
+      return {
+        rootPath: candidateRoot,
+        ecosystemName: manifest.name,
+        memberId: m.id,
+        memberRole: m.role,
+      };
+    }
+  }
+  return null;
+}
+
+function safeIsFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Path equality that's symlink-aware. On macOS `/tmp/foo` and
+ * `/private/tmp/foo` are the same path but compare unequal as strings.
+ * realpathSync collapses both; if either side cannot be realpathed
+ * (missing file) we fall back to a strict string compare.
+ */
+function samePath(a, b) {
+  if (a === b) return true;
+  let ra = a;
+  let rb = b;
+  try {
+    ra = fs.realpathSync(a);
+  } catch (_e) { /* keep original */ }
+  try {
+    rb = fs.realpathSync(b);
+  } catch (_e) { /* keep original */ }
+  return ra === rb;
+}
+
+/**
+ * Teaching output for `momentum doctor`. Returns an array of
+ *   { command, description }
+ * objects describing what the user can do from the given state.
+ * `context` carries any extra info detection produced (ecosystemName,
+ * memberId, etc.) so transitions can be rendered with concrete names.
+ */
+function availableTransitions(state, context = {}) {
+  switch (state) {
+    case 'standalone':
+      return [
+        {
+          command: 'momentum join <ecosystem-path>',
+          description: 'Attach this repo to an existing ecosystem (e.g. ../my-ecosystem).',
+        },
+        {
+          command: 'momentum init --ecosystem <name>',
+          description: 'Create a new ecosystem in a sibling directory and register this repo as the first member.',
+        },
+      ];
+    case 'member': {
+      const name = context.ecosystemName ? `"${context.ecosystemName}"` : '<ecosystem>';
+      return [
+        {
+          command: 'momentum leave',
+          description: `Detach this repo from ${name} (strips pointer + removes manifest entry).`,
+        },
+        {
+          command: 'momentum ecosystem status',
+          description: `Show ${name}'s members and per-member git state.`,
+        },
+      ];
+    }
+    case 'leader':
+      return [
+        {
+          command: 'momentum ecosystem add <repo-path>',
+          description: 'Register another momentum-installed repo as a member of this ecosystem.',
+        },
+        {
+          command: 'momentum ecosystem status',
+          description: 'List members and per-member git state.',
+        },
+        {
+          command: 'momentum ecosystem remove <member-id>',
+          description: 'Unregister a member (inverse of add).',
+        },
+      ];
+    case 'leader-and-member': {
+      const name = context.ecosystemName ? `"${context.ecosystemName}"` : '<parent-ecosystem>';
+      return [
+        {
+          command: 'momentum ecosystem add <repo-path>',
+          description: 'Register a member of THIS ecosystem.',
+        },
+        {
+          command: 'momentum ecosystem status',
+          description: 'List members of THIS ecosystem.',
+        },
+        {
+          command: 'momentum leave',
+          description: `Detach from parent ecosystem ${name} (keeps this dir as a leader).`,
+        },
+      ];
+    }
+    case 'broken-manifest':
+      return [
+        {
+          command: '(fix or remove ecosystem.json)',
+          description: 'The manifest at this path fails validation. Repair it by hand, or delete it to revert to standalone.',
+        },
+      ];
+    case 'broken-pointer':
+      return [
+        {
+          command: 'momentum leave',
+          description: 'Strip the dangling pointer block (recovers to standalone).',
+        },
+        {
+          command: 'momentum join <ecosystem-path>',
+          description: 'Re-attach to an ecosystem if the previous one moved.',
+        },
+      ];
+    case 'broken-orphan': {
+      const name = context.ecosystemName ? `"${context.ecosystemName}"` : '<ecosystem>';
+      return [
+        {
+          command: `momentum join ${context.rootPath ? path.relative(process.cwd(), context.rootPath) : '<ecosystem-path>'}`,
+          description: `Re-inject the missing pointer (you are listed in ${name} but the pointer block is gone).`,
+        },
+        {
+          command: `momentum ecosystem remove ${context.memberId || '<id>'}`,
+          description: `Remove the orphan entry from ${name}'s manifest (run from the ecosystem root).`,
+        },
+      ];
+    }
+    default:
+      return [];
+  }
+}
+
+module.exports = {
+  MAX_PARENT_WALK_DEFAULT,
+  MAX_PARENT_WALK_ENV,
+  getMaxParentWalk,
+  detectState,
+  findRegistration,
+  availableTransitions,
+};

package/core/ecosystem/schema/ecosystem.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/ecosystem-v1.json",
+  "title": "Momentum Ecosystem Manifest",
+  "description": "Declares a set of related momentum-installed repos that coordinate as one product. Lives at the root of an ecosystem repo (sibling to its member repos).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "version", "members"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Lowercase slug identifying the ecosystem. Used as the default folder name for `momentum ecosystem init`."
+    },
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Manifest schema version. Locked to 1 until a breaking change."
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO-8601 date the ecosystem manifest was created."
+    },
+    "members": {
+      "type": "array",
+      "description": "Repos belonging to this ecosystem. Each entry references a sibling directory on disk.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "path", "role"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "minLength": 1,
+            "maxLength": 64,
+            "description": "Stable slug for this member. Used in dependency edges and session log entries."
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Filesystem path to the member repo, relative to the ecosystem root."
+          },
+          "role": {
+            "type": "string",
+            "enum": ["platform", "client", "library", "infra", "bench", "other"],
+            "description": "Coarse role classification. Used by /track and consumers to render groupings."
+          },
+          "owns": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Optional list of named artifacts this member owns (e.g. `openapi.json`, `aws.account.XXX`). Free-form identifiers."
+          },
+          "consumes": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Optional list of named artifacts this member consumes from siblings."
+          }
+        }
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "description": "Directed edges between members. Used for cross-repo coordination (deploy order, contract drift).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to", "kind"],
+        "properties": {
+          "from": {"type": "string", "description": "Member id of the dependent."},
+          "to": {"type": "string", "description": "Member id of the dependency."},
+          "kind": {
+            "type": "string",
+            "enum": ["api-contract", "library", "deploy", "build-time", "other"],
+            "description": "Nature of the dependency."
+          },
+          "note": {"type": "string", "description": "Optional human-readable note."}
+        }
+      }
+    }
+  }
+}

package/core/ecosystem/schema/initiative.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/initiative-v1.json",
+  "title": "Momentum Ecosystem Initiative Frontmatter",
+  "description": "YAML frontmatter shape for an initiative file (initiatives/NNNN-slug.md). The file body is free-form markdown; only the frontmatter block is schema-validated.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "slug", "status", "started", "owner", "repos"],
+  "properties": {
+    "id": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonically-increasing initiative number. Allocated by `momentum ecosystem initiative create`."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "URL-safe slug used in the filename (NNNN-slug.md) and in session log references."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title. Defaults to slug if not provided."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["in-progress", "closed", "abandoned"],
+      "description": "Lifecycle state. `closed` requires a non-empty closed date."
+    },
+    "started": {"type": "string", "format": "date"},
+    "closed": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO-8601 date the initiative was closed. Required when status is `closed`."
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Free-form identifier (GitHub handle, email, or name)."
+    },
+    "repos": {
+      "type": "array",
+      "minItems": 1,
+      "items": {"type": "string"},
+      "description": "Member ids from the ecosystem manifest. Repos contributing to this initiative."
+    },
+    "tags": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Optional free-form tags for filtering."
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"status": {"const": "closed"}}},
+      "then": {"required": ["closed"]}
+    }
+  ]
+}

package/core/ecosystem/scripts/session-append.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# Append an event line to today's ecosystem session log.
+#
+# Sourced by core/scripts/check-history-reminder.sh (via the existing
+# PostToolUse hook installed by `momentum init`). Safe to invoke
+# anywhere — no-ops silently when the current directory is not inside
+# a registered ecosystem member.
+#
+# Inputs (positional):
+#   $1 — event kind  (commit | pr | deploy | log)
+#   $2 — event summary (one line, no embedded newlines)
+#   $3 — optional context (sha, PR number, deploy tag, …)
+#
+# Resolves the ecosystem root by walking up from $PWD looking for a
+# sibling directory containing ecosystem.json (bounded to 5 parents by
+# default; override via MOMENTUM_MAX_PARENT_WALK env var — see
+# core/ecosystem/lib/state.js for the JS counterpart).
+# Resolves the member id by matching $PWD against the manifest's
+# members[].path entries.
+#
+# Writes one line to <ecosystem-root>/sessions/$(date -u +%F).md:
+#   HH:MMZ [<member-id>] <kind> <summary> (<context>)
+#
+# If this is the first append today, prepends a header line naming the
+# active initiative (if any).
+
+set -eu
+
+EVENT_KIND="${1:-}"
+EVENT_SUMMARY="${2:-}"
+EVENT_CONTEXT="${3:-}"
+
+if [ -z "$EVENT_KIND" ] || [ -z "$EVENT_SUMMARY" ]; then
+  exit 0
+fi
+
+# ── Resolve ecosystem root (bounded walk-up, looking for siblings) ──────────
+# The ecosystem is a SIBLING of member repos. From a member repo we walk
+# up one level and look at each sibling for ecosystem.json.
+
+find_ecosystem_root() {
+  local start="$PWD"
+  local current="$start"
+  local depth=0
+  local max_depth="${MOMENTUM_MAX_PARENT_WALK:-5}"
+  # Guard against non-numeric / negative env value.
+  case "$max_depth" in
+    ''|*[!0-9]*) max_depth=5 ;;
+  esac
+  while [ $depth -le $max_depth ]; do
+    # Same-directory check (caller might already be in ecosystem root)
+    if [ -f "$current/ecosystem.json" ]; then
+      echo "$current"
+      return 0
+    fi
+    # Sibling check
+    local parent
+    parent=$(dirname "$current")
+    if [ "$parent" = "$current" ]; then return 1; fi
+    for sibling in "$parent"/*; do
+      if [ -d "$sibling" ] && [ -f "$sibling/ecosystem.json" ]; then
+        echo "$sibling"
+        return 0
+      fi
+    done
+    current="$parent"
+    depth=$((depth + 1))
+  done
+  return 1
+}
+
+ROOT=$(find_ecosystem_root 2>/dev/null) || exit 0
+[ -z "$ROOT" ] && exit 0
+[ -f "$ROOT/ecosystem.json" ] || exit 0
+
+# ── Resolve member id by matching $PWD against manifest.members[].path ─────
+
+resolve_member_id() {
+  python3 - "$ROOT" "$PWD" <<'PY' 2>/dev/null || echo ""
+import sys, json, os
+root, pwd = sys.argv[1], os.path.realpath(sys.argv[2])
+try:
+    with open(os.path.join(root, "ecosystem.json")) as f:
+        m = json.load(f)
+except Exception:
+    sys.exit(0)
+for member in m.get("members", []):
+    abs_path = os.path.realpath(os.path.join(root, member.get("path", "")))
+    # Match pwd that is == abs_path or any descendant
+    try:
+        rel = os.path.relpath(pwd, abs_path)
+    except ValueError:
+        continue
+    if rel == "." or (not rel.startswith("..") and not os.path.isabs(rel)):
+        print(member.get("id", ""))
+        sys.exit(0)
+PY
+}
+
+MEMBER_ID=$(resolve_member_id)
+[ -z "$MEMBER_ID" ] && exit 0
+
+# ── Write the line ─────────────────────────────────────────────────────────
+
+SESSION_DIR="$ROOT/sessions"
+mkdir -p "$SESSION_DIR"
+TODAY=$(date -u +%F)
+SESSION_FILE="$SESSION_DIR/$TODAY.md"
+HHMM=$(date -u +%H:%M)
+
+# ── BUG-004 fix: serialize concurrent writers via mkdir lock ────────────────
+# `mkdir` is atomic on POSIX filesystems and portable across macOS/Linux
+# without depending on flock (which is not present by default on macOS).
+# The lock covers the "check + header-write + append" sequence so two
+# concurrent commits in different member repos can't both write the
+# header or interleave their data lines.
+LOCK_DIR="$SESSION_FILE.lock"
+acquire_session_lock() {
+  local tries=100  # ~5s total at 50ms each
+  while [ $tries -gt 0 ]; do
+    if mkdir "$LOCK_DIR" 2>/dev/null; then
+      return 0
+    fi
+    sleep 0.05
+    tries=$((tries - 1))
+  done
+  return 1
+}
+release_session_lock() {
+  rmdir "$LOCK_DIR" 2>/dev/null || true
+}
+trap release_session_lock EXIT INT TERM
+
+# If we cannot acquire the lock within the budget, drop the event silently
+# rather than corrupt the file. Session events are advisory; momentum's
+# correctness does not depend on every one landing.
+if ! acquire_session_lock; then
+  exit 0
+fi
+
+# First write of the day → write header (and active initiative banner).
+if [ ! -f "$SESSION_FILE" ]; then
+  {
+    echo "# Session $TODAY"
+    if [ -f "$ROOT/.state/active-initiative" ]; then
+      ACTIVE=$(tr -d '[:space:]' < "$ROOT/.state/active-initiative")
+      if [ -n "$ACTIVE" ]; then
+        echo "Active initiative: $ACTIVE"
+      fi
+    fi
+    echo ""
+  } > "$SESSION_FILE"
+fi
+
+# Build the line; quote context only if present.
+if [ -n "$EVENT_CONTEXT" ]; then
+  echo "${HHMM}Z [$MEMBER_ID] ${EVENT_KIND}: ${EVENT_SUMMARY} (${EVENT_CONTEXT})" >> "$SESSION_FILE"
+else
+  echo "${HHMM}Z [$MEMBER_ID] ${EVENT_KIND}: ${EVENT_SUMMARY}" >> "$SESSION_FILE"
+fi
+
+# Cache last session date for cheap subsequent reads.
+mkdir -p "$ROOT/.state"
+echo "$TODAY" > "$ROOT/.state/last-session"
+
+# Lock is released by the EXIT trap.
+exit 0

package/core/ecosystem/templates/ecosystem-agents.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 agent commands you should invoke when working across member repos. Each has a CLI fallback under `momentum <name>`; the agent 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 agent 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 agent 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.