@limina-labs/momentum 0.30.2

package/core/swarm/supervise.md

@@ -0,0 +1,81 @@
+You are a **swarm supervisor** for momentum. Your role is to drive a single repo's phase end-to-end under a conductor's coordination.
+
+This recipe is platform-agnostic — Claude Code is the v0.20.0 carrier; Codex + Antigravity wire in via Phase 18.
+
+## Hard invariants
+
+1. **cwd is pinned.** You are spawned with `--cwd <repoPath>`. Never `cd` elsewhere. Reads + writes are scoped to your repo.
+2. **You don't see other supervisors.** Other repos in the swarm are not visible to you. Communicate via the inbox (questions) or wait for the conductor to broadcast/`tell` you context.
+3. **You don't write to the swarm manifest.** Only the conductor mutates `<eco>/swarms/<id>/manifest.json`. You write your saga step to `<repo>/.momentum/runs/dispatch-run-NNN.json`; the conductor reads it.
+4. **You follow standard momentum discipline.** `/start-phase` → implement → `/sync-docs` → `/complete-phase`. The conductor wired your brief with swarm frontmatter; otherwise this is a normal phase loop.
+
+## Boot sequence (first turn)
+
+1. Read these env vars (all required):
+   - `MOMENTUM_SWARM_ID` — e.g. `0007-user-auth`
+   - `MOMENTUM_SWARM_WAVE` — your wave number
+   - `MOMENTUM_SWARM_INITIATIVE` — the initiative slug
+   - `MOMENTUM_SWARM_SESSION` — your owning session id (write into saga records)
+   - `MOMENTUM_ECOSYSTEM_ROOT` — absolute path to the ecosystem root
+   - `MOMENTUM_SWARM_CONTEXT` — absolute path to your swarm-context.md
+2. Read your phase brief (`specs/phases/<phase-slug>/overview.md`). Its frontmatter declares your `swarm:` / `wave:` / `initiative:` / `claimed_by_session:`.
+3. Read `MOMENTUM_SWARM_CONTEXT` if it exists — this is where the conductor appends `/swarm tell` and `/swarm broadcast` content.
+4. Read your contract files at `<MOMENTUM_ECOSYSTEM_ROOT>/swarms/<MOMENTUM_SWARM_ID>/contracts/` — any whose `consumers` or `owner` include your repo id.
+5. Run `/start-phase` for this repo's phase. The recipe is unchanged — it picks up the brief frontmatter automatically.
+
+## Per-turn loop
+
+Each conductor poll cycle:
+
+1. Re-read `MOMENTUM_SWARM_CONTEXT` from the bottom up; integrate any new content the conductor pushed.
+2. Implement the next task per your phase's `plan.md`.
+3. Commit with the conventional commit style declared in `plan.md`.
+4. Update `<repo>/.momentum/runs/dispatch-run-NNN.json` with your saga step (allocate via the existing `core/orchestration/run-artifact.js` helper; mark `primitive: "swarm-supervise"`). Required fields: `swarm_id`, `saga_id`, `wave`, `step_n`, `tasks_done`, `tasks_total`, `head_sha`, `last_commit`. Set `done: true` only after `/complete-phase` succeeds.
+5. If you need a user decision you can't make alone, write `<eco>/swarms/<MOMENTUM_SWARM_ID>/inbox/NNNN-<slug>.md` (see core/swarm/inbox.js) and stop until it resolves.
+
+## Inbox protocol
+
+Write an inbox item when:
+- A required input is ambiguous and the conductor's context plus your brief don't disambiguate.
+- A test failure is not caused by your code (likely a contract mismatch from an earlier wave).
+- You hit a token-budget warning at 90% of `tokens_budget`.
+
+Do NOT write an inbox item for normal coding choices — those belong to your /sync-docs + /complete-phase loop.
+
+## Contract enforcement
+
+If you produce a contract surface this wave:
+1. Author the contract artifact at `<eco>/swarms/<MOMENTUM_SWARM_ID>/contracts/<surface>.contract.json` per `core/swarm/schema/contract.schema.json`.
+2. Compute its `content_hash` (SHA256 of canonical-JSON serialization of `shape`).
+3. Wave checkpoint will fail if a downstream consumer's expectation doesn't match.
+
+If you consume a contract surface:
+1. Read the producer's contract from `contracts/`.
+2. Generate any required client/types code per your phase plan.
+3. If shape diverges from what your phase brief expected, raise an inbox item — don't silently adapt.
+
+## Completion
+
+When `/complete-phase` succeeds in this repo:
+1. Write the final dispatch-run record with `done: true` and `exit_status: "success"`.
+2. Append a `[SWARM]` history entry to your repo's `history.md`:
+   ```
+   ### [SWARM] YYYY-MM-DD — Wave <N> completed — <swarm-id>
+   Topics: swarm, wave-<N>, <initiative-slug>
+   Affects-phases: <phase-slug>
+   Affects-specs: ../swarms/<swarm-id>/manifest.json
+   Detail: Wave <N> of swarm <swarm-id> finished in this repo. <one-line summary>.
+   ```
+3. Wait for the conductor's next poll cycle to pick up your completion. Do not announce — the materialized board does that.
+
+## Failure / cancel
+
+If your wave is cancelled (you see `signal: cancel` propagated through `<eco>/swarms/<id>/signals/`, or your supervisor session is killed):
+1. DO NOT force-push.
+2. DO NOT delete the branch.
+3. Leave your dispatch-run record with `exit_status: "cancelled"`.
+4. Your branch remains for forensics or `/swarm resume`.
+
+---
+
+This recipe is platform-agnostic. Claude Code is the v0.20.0 carrier. Codex (Phase 18) uses an MCP cwd shim to honor "cwd is pinned"; Antigravity uses the Agent Manager workflow to launch one supervisor per cwd.

package/core/waves/lib/plan-graph.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Plan-graph readers for the wave engine (Phase 21c, ADR-0003 §3).
+ *
+ * Dependency annotations live in the files that already exist:
+ *   - task groups:  `## Group N — title (deps: G0, G1)` in tasks.md;
+ *     a group whose checkboxes are all `[x]` is SATISFIED and drops out
+ *     of the graph (its dependents unblock).
+ *   - phases:       `status:` / `deps:` frontmatter on each phase's
+ *     overview.md (OKF bundle format, ADR-0005). Legacy
+ *     specs/phases/index.json is read as a fallback (with an upgrade
+ *     nudge) so a new CLI keeps working in not-yet-migrated projects.
+ *     Deps on `complete` phases are satisfied; only non-complete phases
+ *     are scheduled.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const frontmatter = require('../../lib/frontmatter');
+
+const GROUP_HEADING = /^##\s+Group\s+([A-Za-z0-9.\-]+)\s*(?:[—–-]\s*(.*?))?\s*$/;
+const DEPS_SUFFIX = /\(deps:\s*([^)]*)\)\s*$/i;
+const CHECKBOX = /^\s*-\s*\[( |x|X|\/)\]/;
+
+/** Normalize a group token: bare numbers get the G prefix ("2" → "G2"). */
+function groupId(token) {
+  const t = String(token).trim();
+  return /^\d/.test(t) ? `G${t}` : t.toUpperCase();
+}
+
+/**
+ * Parse a tasks.md body into group nodes.
+ * @returns {{id, title, deps: string[], boxes: number, done: number, satisfied: boolean}[]}
+ */
+function parseTaskGroups(body) {
+  const groups = [];
+  let current = null;
+  for (const line of String(body).split('\n')) {
+    const h = line.match(GROUP_HEADING);
+    if (h) {
+      let title = (h[2] || '').trim();
+      let deps = [];
+      const d = title.match(DEPS_SUFFIX) || line.match(DEPS_SUFFIX);
+      if (d) {
+        deps = d[1].split(',').map((s) => groupId(s)).filter(Boolean);
+        title = title.replace(DEPS_SUFFIX, '').trim();
+      }
+      current = { id: groupId(h[1]), title, deps, boxes: 0, done: 0 };
+      groups.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const c = line.match(CHECKBOX);
+    if (c) {
+      current.boxes += 1;
+      if (c[1] === 'x' || c[1] === 'X') current.done += 1;
+    }
+  }
+  for (const g of groups) {
+    g.satisfied = g.boxes > 0 && g.done === g.boxes;
+  }
+  return groups;
+}
+
+/**
+ * Wave input for a tasks.md file: unsatisfied groups only; deps on
+ * satisfied (or unknown) groups are dropped.
+ * @returns {{ nodes: string[], edges: {from,to}[], groups }} or null when unreadable
+ */
+function taskGraph(tasksFile) {
+  let body;
+  try {
+    body = fs.readFileSync(tasksFile, 'utf8');
+  } catch {
+    return null;
+  }
+  const groups = parseTaskGroups(body);
+  const pending = groups.filter((g) => !g.satisfied);
+  const pendingIds = new Set(pending.map((g) => g.id));
+  const edges = [];
+  for (const g of pending) {
+    for (const dep of g.deps) {
+      if (pendingIds.has(dep)) edges.push({ from: g.id, to: dep });
+    }
+  }
+  return { nodes: pending.map((g) => g.id), edges, groups };
+}
+
+/** Natural compare so phase-2 sorts before phase-10 (index.json had insertion order). */
+function naturalCompare(a, b) {
+  const ax = a.split(/(\d+)/);
+  const bx = b.split(/(\d+)/);
+  for (let i = 0; i < Math.max(ax.length, bx.length); i += 1) {
+    const as = ax[i] || '';
+    const bs = bx[i] || '';
+    if (as === bs) continue;
+    const an = Number(as);
+    const bn = Number(bs);
+    if (!Number.isNaN(an) && !Number.isNaN(bn)) return an - bn;
+    return as < bs ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Phase metadata from OKF frontmatter: scans specs/phases/[star]/overview.md
+ * for `status:` (plus `deps:`, `tags:`). Returns null when NO phase dir
+ * carries status frontmatter — the caller then falls back to index.json.
+ */
+function phasesFromFrontmatter(repoRoot) {
+  const phasesDir = path.join(repoRoot, 'specs', 'phases');
+  let entries;
+  try {
+    entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const phases = {};
+  for (const e of entries.filter((d) => d.isDirectory()).sort((a, b) => naturalCompare(a.name, b.name))) {
+    let content;
+    try {
+      content = fs.readFileSync(path.join(phasesDir, e.name, 'overview.md'), 'utf8');
+    } catch {
+      continue;
+    }
+    const { data } = frontmatter.parse(content);
+    if (!data || !data.status) continue;
+    phases[e.name] = {
+      status: String(data.status),
+      topics: Array.isArray(data.tags) ? data.tags : [],
+      deps: Array.isArray(data.deps) ? data.deps : [],
+    };
+  }
+  return Object.keys(phases).length ? phases : null;
+}
+
+let nudged = false;
+
+/**
+ * Wave input for the phase scale: non-complete phases; deps on complete
+ * phases satisfied. Prefers overview.md frontmatter (OKF); falls back to
+ * legacy specs/phases/index.json with a one-time stderr nudge.
+ * @returns {{ nodes, edges, phases, source }} or null when neither exists
+ */
+function phaseGraph(repoRoot) {
+  let phases = phasesFromFrontmatter(repoRoot);
+  let source = 'overview.md frontmatter';
+  if (!phases) {
+    let index;
+    try {
+      index = JSON.parse(fs.readFileSync(path.join(repoRoot, 'specs', 'phases', 'index.json'), 'utf8'));
+    } catch {
+      return null;
+    }
+    phases = index.phases || {};
+    source = 'index.json (legacy)';
+    if (!nudged) {
+      nudged = true;
+      console.error('note: reading legacy specs/phases/index.json — run `momentum upgrade` to migrate specs/ to the OKF bundle format');
+    }
+  }
+  const pending = Object.keys(phases).filter((id) => phases[id].status !== 'complete');
+  const pendingSet = new Set(pending);
+  const edges = [];
+  for (const id of pending) {
+    for (const dep of phases[id].deps || []) {
+      if (pendingSet.has(dep)) edges.push({ from: id, to: dep });
+    }
+  }
+  return { nodes: pending, edges, phases, source };
+}
+
+module.exports = { parseTaskGroups, taskGraph, phaseGraph, phasesFromFrontmatter, groupId };

package/core/waves/lib/waves.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * The recursive wave engine (Phase 21c, FEAT-028 — see ADR-0003).
+ *
+ * ONE algorithm for every scale of the plan graph (ecosystem ⊃ repos ⊃
+ * phases ⊃ tasks): Kahn layering over dependency edges. Nodes with no
+ * remaining inbound edges form the next wave; lexicographic order inside
+ * a wave keeps repeated runs identical; a stuck non-empty remainder is a
+ * cycle, reported with its participants.
+ *
+ * Extracted from core/swarm/lib/wave-ordering.js (Phase 17) — swarm is
+ * now a thin adapter over this engine. The `label` option lets adapters
+ * keep their historical error strings byte-for-byte.
+ *
+ * Edge semantics: { from: A, to: B } means A DEPENDS ON B → B runs first.
+ */
+
+/**
+ * @param {string[]} nodeIds — non-empty list of node ids
+ * @param {{from: string, to: string}[]} edges — dependency edges
+ * @param {{label?: string}} [opts] — error-message prefix (default 'computeWaves')
+ * @returns {{ index: number, nodes: string[] }[]}
+ */
+function computeWaveLayers(nodeIds, edges, opts = {}) {
+  const label = opts.label || 'computeWaves';
+  if (!Array.isArray(nodeIds) || nodeIds.length === 0) {
+    throw new Error(`${label}: impactedRepos must be a non-empty array`);
+  }
+  for (const n of nodeIds) {
+    if (typeof n !== 'string' || n.length === 0) {
+      throw new TypeError(`${label}: impactedRepos must be non-empty strings (got ${JSON.stringify(n)})`);
+    }
+  }
+  const included = new Set(nodeIds);
+
+  const inDegree = new Map();
+  const adj = new Map();
+  for (const n of included) {
+    inDegree.set(n, 0);
+    adj.set(n, []);
+  }
+
+  if (Array.isArray(edges)) {
+    for (const dep of edges) {
+      if (!dep || typeof dep !== 'object') continue;
+      const { from, to } = dep;
+      if (typeof from !== 'string' || typeof to !== 'string') continue;
+      if (!included.has(from) || !included.has(to)) continue; // outside the subgraph
+      if (from === to) {
+        throw new Error(`${label}: self-dependency on "${from}" — invalid edge`);
+      }
+      adj.get(to).push(from); // B → A: the dependency unlocks the dependent
+      inDegree.set(from, inDegree.get(from) + 1);
+    }
+  }
+
+  const waves = [];
+  let waveIndex = 1;
+  const remaining = new Set(included);
+
+  while (remaining.size > 0) {
+    const ready = [];
+    for (const n of remaining) {
+      if (inDegree.get(n) === 0) ready.push(n);
+    }
+    if (ready.length === 0) {
+      throw new Error(`${label}: cycle detected involving ${[...remaining].sort().join(', ')}`);
+    }
+    ready.sort();
+    waves.push({ index: waveIndex, nodes: ready });
+    waveIndex += 1;
+    for (const n of ready) {
+      remaining.delete(n);
+      for (const target of adj.get(n) || []) {
+        inDegree.set(target, inDegree.get(target) - 1);
+      }
+    }
+  }
+  return waves;
+}
+
+module.exports = { computeWaveLayers };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@limina-labs/momentum",
+  "version": "0.30.2",
+  "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
+  "homepage": "https://trymomentum.github.io",
+  "bin": {
+    "momentum": "bin/momentum.js"
+  },
+  "files": [
+    "bin/",
+    "core/",
+    "adapters/**/adapter.js",
+    "adapters/**/settings.json",
+    "adapters/**/hooks.json",
+    "adapters/**/plugins/**",
+    "adapters/**/instructions/**",
+    "adapters/**/commands/**",
+    "adapters/**/agent-rules/**",
+    "adapters/**/scripts/**",
+    "adapters/**/workflows/**",
+    "adapters/**/skills/**",
+    "adapters/**/agents/**"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1 tests/*.test.js",
+    "capture-evidence": "MOMENTUM_CAPTURE_EVIDENCE=1 node --test --test-concurrency=1 tests/swarm-e2e-scenarios.test.js tests/swarm-portability-e2e.test.js",
+    "generate-instructions": "node scripts/generate-instructions.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "ai",
+    "spec-driven",
+    "momentum",
+    "workflow"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LiminaLabsAI/momentum.git"
+  }
+}