@limina-labs/momentum 0.36.0 → 0.37.0

package/bin/momentum.js

@@ -2198,6 +2198,22 @@ async function main() {
       console.error(`\nError: ${err.message}`);
       exitCode = 1;
     }
+  } else if (args[0] === 'claim') {
+    try {
+      const { runClaim } = require('./team');
+      exitCode = runClaim(args.slice(1));
+    } catch (err) {
+      console.error(`\nError: ${err.message}`);
+      exitCode = 1;
+    }
+  } else if (args[0] === 'team') {
+    try {
+      const { runTeam } = require('./team');
+      exitCode = runTeam(args.slice(1));
+    } catch (err) {
+      console.error(`\nError: ${err.message}`);
+      exitCode = 1;
+    }
   } else {
     console.error(`Unknown command: ${args[0]}`);
     console.error('Run "momentum --help" for usage.');

package/bin/team.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/**
+ * `momentum team` + `momentum claim` — git-native team coordination (Phase 30a
+ * Team-Walk, ADR-0012). No daemon; every command computes from git + files.
+ *
+ *   momentum claim <namespace> <key>   atomic cross-machine allocation (ref-CAS)
+ *   momentum team whoami               show the resolved durable actor
+ *   momentum team sync                 fetch coordination refs + recompile views
+ */
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MOMENTUM_ROOT = path.resolve(__dirname, '..');
+const claimLib = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'claim'));
+const refcas = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'refcas'));
+const compile = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'compile'));
+const presenceLib = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'presence'));
+const approvalsLib = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'approvals'));
+const queueLib = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'queue'));
+const leaseLib = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'lib', 'lease'));
+const { createRelay } = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'relay', 'server'));
+const { CONTRACT } = require(path.join(MOMENTUM_ROOT, 'core', 'team', 'contract'));
+const identity = require(path.join(MOMENTUM_ROOT, 'core', 'identity'));
+
+function repoRoot(cwd) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') flags.json = true;
+    else if (a.startsWith('--')) flags[a.slice(2)] = argv[++i];
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+function insideRepo(cwd) {
+  return spawnSync('git', ['rev-parse', '--git-dir'], { cwd, encoding: 'utf8' }).status === 0;
+}
+
+// ─── momentum claim ────────────────────────────────────────────────────────
+
+function runClaim(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const [namespace, key] = positional;
+  if (!namespace || !key) {
+    console.error('usage: momentum claim <namespace> <key> [--remote origin] [--actor id]');
+    console.error('  e.g. momentum claim phase 30a  |  momentum claim version 0.37.0  |  momentum claim id BUG-028');
+    return 1;
+  }
+  const cwd = process.cwd();
+  if (!insideRepo(cwd)) { console.error('✗ not inside a git repository'); return 1; }
+  const actor = flags.actor || identity.resolveActor(cwd).id;
+  let res;
+  try {
+    res = claimLib.claimKey(cwd, namespace, key, { remote: flags.remote, actor });
+  } catch (err) {
+    console.error(`✗ claim failed: ${err.message}`);
+    return 1;
+  }
+  if (res.won) {
+    console.log(`✓ claimed ${namespace}/${key} as '${actor}'  (${res.ref})`);
+    return 0;
+  }
+  const who = res.winner && res.winner.actor ? res.winner.actor : 'someone else';
+  console.error(`✗ ${namespace}/${key} already claimed by '${who}' — pick another`);
+  return 2; // distinct from usage(1) so recipes can gate on "lost"
+}
+
+// ─── momentum team ─────────────────────────────────────────────────────────
+
+function runTeam(argv) {
+  const sub = argv[0];
+  const cwd = process.cwd();
+  if (sub === 'whoami') {
+    const a = identity.resolveActor(cwd);
+    console.log(`${a.id}  (source: ${a.source}${a.email ? `, ${a.email}` : ''})`);
+    return 0;
+  }
+  if (sub === 'sync') {
+    if (!insideRepo(cwd)) { console.error('✗ not inside a git repository'); return 1; }
+    const remote = argv[1] && !argv[1].startsWith('--') ? argv[1] : 'origin';
+    const ok = refcas.fetchAll(cwd, remote);
+    const root = repoRoot(cwd);
+    const rec = root ? compile.compileStatusFile(root) : { changed: false };
+    console.log(ok
+      ? `✓ synced coordination refs from ${remote} (refs/momentum/*). Fragments arrive via branch integration.`
+      : `⚠ could not fetch from ${remote} — working offline; coordination is eventually consistent`);
+    if (rec.changed) console.log('✓ recompiled the Active-Phase table in specs/status.md');
+    return 0;
+  }
+  if (sub === 'compile') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const rec = compile.compileStatusFile(root);
+    console.log(rec.path
+      ? (rec.changed ? '✓ recompiled Active-Phase table in specs/status.md' : '✓ specs/status.md already current')
+      : 'ℹ no specs/status.md to compile into');
+    return 0;
+  }
+  if (sub === 'board') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    console.log(compile.compileActivePhase(root));
+    return 0;
+  }
+  if (sub === 'record') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const { flags } = parseFlags(argv.slice(1));
+    if (!flags.branch) { console.error('usage: momentum team record --branch B [--phase P] [--status S] [--progress "..."]'); return 1; }
+    const actor = flags.actor || identity.resolveActor(root).id;
+    compile.recordActivePhase(root, actor, {
+      branch: flags.branch, phase: flags.phase || '', status: flags.status || '', progress: flags.progress || '',
+    });
+    console.log(`✓ recorded active-phase row for '${flags.branch}' as '${actor}'`);
+    return 0;
+  }
+  if (sub === 'heartbeat') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const { flags } = parseFlags(argv.slice(1));
+    const actor = flags.actor || identity.resolveActor(root).id;
+    presenceLib.heartbeat(root, actor, { branch: flags.branch, lane: flags.lane, activity: flags.activity });
+    console.log(`✓ heartbeat for '${actor}'`);
+    return 0;
+  }
+  if (sub === 'presence') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const now = Date.now();
+    const list = presenceLib.presence(root, now);
+    if (!list.length) { console.log('(no presence recorded)'); return 0; }
+    for (const p of list) {
+      console.log(`${p.liveness === 'active' ? '●' : p.liveness === 'idle' ? '◐' : '○'} ${p.actor}  ${p.liveness}  ${p.branch || ''}${p.activity ? '  — ' + p.activity : ''}`);
+    }
+    return 0;
+  }
+  if (sub === 'approve') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const { flags, positional } = parseFlags(argv.slice(1));
+    const change = positional[0];
+    if (!change) { console.error('usage: momentum team approve <change> [--verdict approve|reject]'); return 1; }
+    const actor = flags.actor || identity.resolveActor(root).id;
+    approvalsLib.approve(root, actor, change, { verdict: flags.verdict || 'approve' });
+    console.log(`✓ ${flags.verdict === 'reject' ? 'rejected' : 'approved'} '${change}' as '${actor}'`);
+    return 0;
+  }
+  if (sub === 'check') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const { flags, positional } = parseFlags(argv.slice(1));
+    const change = positional[0];
+    if (!change || !flags.author) { console.error('usage: momentum team check <change> --author <a> [--threshold N] [--allow-self]'); return 1; }
+    const threshold = flags.threshold ? parseInt(flags.threshold, 10) : 1;
+    const allowSelf = argv.includes('--allow-self');
+    const approvers = approvalsLib.approversFor(root, change, flags.author, allowSelf);
+    if (approvers.length >= threshold) {
+      console.log(`✓ '${change}' satisfied — ${approvers.length}/${threshold} approval(s): ${approvers.join(', ')}`);
+      return 0;
+    }
+    console.error(`✗ '${change}' not satisfied — ${approvers.length}/${threshold} peer approval(s)${allowSelf ? '' : ' (author self-approval does not count)'}`);
+    return 2;
+  }
+  if (sub === 'turn') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const action = argv[1];
+    const runway = argv[2] || 'main';
+    const actor = identity.resolveActor(root).id;
+    if (action === 'take') {
+      const r = queueLib.takeTurn(root, runway, actor);
+      if (r.held) { console.log(`✓ took the '${runway}' landing turn as '${actor}'`); return 0; }
+      console.error(`✗ '${runway}' turn held by '${r.holder}' — wait or coordinate`); return 2;
+    }
+    if (action === 'release') { queueLib.releaseTurn(root, runway); console.log(`✓ released the '${runway}' turn`); return 0; }
+    if (action === 'holder') { const h = queueLib.turnHolder(root, runway); console.log(h ? `${runway}: held by '${h}'` : `${runway}: free`); return 0; }
+    console.error('usage: momentum team turn <take|release|holder> [runway]');
+    return 1;
+  }
+  if (sub === 'lease') {
+    const root = repoRoot(cwd);
+    if (!root) { console.error('✗ not inside a git repository'); return 1; }
+    const action = argv[1];
+    const resource = argv[2];
+    if (!action || !resource) { console.error('usage: momentum team lease <acquire|release|owner> <resource>'); return 1; }
+    const actor = identity.resolveActor(root).id;
+    if (action === 'acquire') {
+      const r = leaseLib.acquireLease(root, resource, actor);
+      if (r.held) { console.log(`✓ leased '${resource}' as '${actor}'`); return 0; }
+      console.error(`✗ '${resource}' leased by '${r.owner}'`); return 2;
+    }
+    if (action === 'release') { leaseLib.releaseLease(root, resource); console.log(`✓ released lease '${resource}'`); return 0; }
+    if (action === 'owner') { const o = leaseLib.leaseOwner(root, resource); console.log(o ? `${resource}: owned by '${o}'` : `${resource}: free`); return 0; }
+    console.error('usage: momentum team lease <acquire|release|owner> <resource>');
+    return 1;
+  }
+  if (sub === 'contract') {
+    console.log(JSON.stringify(CONTRACT, null, 2));
+    return 0;
+  }
+  if (sub === 'relay') {
+    const { flags } = parseFlags(argv.slice(1));
+    const relay = createRelay({ port: flags.port ? parseInt(flags.port, 10) : 0 });
+    relay.listen((port) => {
+      console.log(`✓ momentum coordination relay (authority-free) on http://127.0.0.1:${port}`);
+      console.log(`  set relay_url=http://127.0.0.1:${port} for teammates; Ctrl-C to stop.`);
+    });
+    return 0; // server keeps the process alive
+  }
+  console.error('usage: momentum team <whoami|sync|board|record|compile|heartbeat|presence|approve|check|turn|lease|contract|relay>');
+  return 1;
+}
+
+module.exports = { runTeam, runClaim };

package/core/identity/index.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Actor identity (Phase 30a Team-Walk, ADR-0012).
+ *
+ * momentum was identity-blind — "actors" were random per-process UUIDs
+ * (bin/swarm.js) and branch names (core/lanes/lib/signals.js). Team mode needs
+ * a DURABLE actor so coordination writes, claims, and approvals can say WHO.
+ *
+ * The zero-config source is git's own identity (`git config user.email` /
+ * `user.name`), overridable by $MOMENTUM_ACTOR, with a deterministic fallback
+ * (stable per repo+user) when git identity is unset. No accounts, no server.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+function git(cwd, ...args) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (res.status !== 0) return null;
+  return res.stdout.trim();
+}
+
+/** Slugify an email/name into a stable, path-safe actor id. */
+function slug(s) {
+  const out = String(s)
+    .toLowerCase()
+    .trim()
+    .replace(/@.*$/, '') // email local-part
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return out || 'anon';
+}
+
+/**
+ * Resolve the durable actor for `cwd`.
+ * Precedence: $MOMENTUM_ACTOR → git config user.email → deterministic fallback.
+ * `env` is injectable for testing (defaults to process.env).
+ * Returns { id, name, email, source }.
+ */
+function resolveActor(cwd, env) {
+  env = env || process.env;
+  const dir = cwd || process.cwd();
+
+  const override = env.MOMENTUM_ACTOR && env.MOMENTUM_ACTOR.trim();
+  if (override) {
+    return { id: slug(override), name: override, email: null, source: 'env' };
+  }
+
+  const email = git(dir, 'config', 'user.email');
+  const name = git(dir, 'config', 'user.name');
+  if (email) {
+    return { id: slug(email), name: name || email, email, source: 'git' };
+  }
+
+  // Deterministic fallback — stable per repo+user without a git identity.
+  const root = git(dir, 'rev-parse', '--show-toplevel') || dir;
+  const user = env.USER || env.USERNAME || 'unknown';
+  const h = crypto.createHash('sha256').update(`${user}::${root}`).digest('hex').slice(0, 8);
+  return { id: `anon-${h}`, name: `anon-${h}`, email: null, source: 'fallback' };
+}
+
+module.exports = { resolveActor, slug };

package/core/team/contract/index.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/**
+ * Published coordination contract (Phase 30c Team-Fly, ADR-0014).
+ *
+ * The versioned, third-party-consumable description of momentum's git-native
+ * team-coordination state — the fragment layout and the `refs/momentum/*`
+ * namespace — so dashboards, CI, or other tools can read team state without
+ * momentum. Realizes the Lanes-arc "publish the lane-state contract" decision
+ * (ADR-0003 §5). Breaking changes bump CONTRACT_VERSION (pinned by a test).
+ *
+ * Zero dependencies.
+ */
+
+const CONTRACT_VERSION = '1.0.0';
+
+const CONTRACT = {
+  version: CONTRACT_VERSION,
+  fragments: {
+    location: '.momentum/team/<view>/<actor>-<seq>-<kind>.json  (committed)',
+    views: ['active-phase', 'presence', 'approvals'],
+    shape: { actor: 'string', seq: 'number', ts: 'iso8601', kind: 'string', payload: 'object' },
+    invariant: 'an actor writes only files prefixed with its own <actor>- → conflict-free by construction',
+  },
+  refs: {
+    namespace: 'refs/momentum/*  (fetched via +refs/momentum/*:refs/momentum/*)',
+    claims: 'refs/momentum/{claims,version,phase,id}/<key>   first-push-wins allocation',
+    queue: 'refs/momentum/queue/<runway>-holder             single-holder landing turn',
+    leases: 'refs/momentum/leases/<resource>                single-owner cross-machine lease',
+    payload: 'empty-tree commit whose message is JSON { actor, key, ts, ... }',
+  },
+  relay: {
+    optional: true,
+    authorityFree: true,
+    protocol: 1,
+    endpoints: ['POST /publish', 'GET /events?since=N', 'GET /health'],
+    absence: 'no relay_url → git-native fallback; nothing depends on it',
+  },
+};
+
+module.exports = { CONTRACT, CONTRACT_VERSION };

package/core/team/lib/approvals.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Reviewer≠author approvals ledger (Phase 30b Team-Run, ADR-0013).
+ *
+ * The trust gate finally distinguishes self-approval from peer review. Approvals
+ * are attributed fragments; a change is `satisfied` when it has >= threshold
+ * approvals by actors DIFFERENT from the author. Deliberately CLIENT-SIDE HONEST
+ * — ADR-0009's trust invariant is unchanged and true server-side enforcement
+ * stays an optional forge-adapter concern. `allowSelf` restores solo behavior
+ * (single-operator N=1 compatibility).
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const fragments = require('./fragments');
+
+const APPROVALS_VIEW = 'approvals';
+
+/** Record an attributed approval (or a `reject` verdict) for `change`. */
+function approve(repoRoot, approver, change, opts) {
+  opts = opts || {};
+  return fragments.writeFragment(repoRoot, APPROVALS_VIEW, approver, 'approval', {
+    change: String(change),
+    verdict: opts.verdict || 'approve',
+  }, opts);
+}
+
+/** Distinct approvers (latest verdict = approve) for a change, honoring reviewer≠author. */
+function approversFor(repoRoot, change, author, allowSelf) {
+  const forChange = fragments
+    .readFragments(repoRoot, APPROVALS_VIEW)
+    .filter((f) => f.payload.change === String(change));
+  const latest = fragments.foldLatest(forChange, (f) => f.actor);
+  return [...latest.values()]
+    .filter((f) => f.payload.verdict === 'approve')
+    .filter((f) => allowSelf || f.actor !== author)
+    .map((f) => f.actor);
+}
+
+/** True when `change` has >= threshold qualifying approvals. */
+function satisfied(repoRoot, change, opts) {
+  const { author, threshold = 1, allowSelf = false } = opts || {};
+  return approversFor(repoRoot, change, author, allowSelf).length >= threshold;
+}
+
+module.exports = { approve, approversFor, satisfied, APPROVALS_VIEW };

package/core/team/lib/claim.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Collision-free allocation claims (Phase 30a Team-Walk G1, ADR-0012).
+ *
+ * Thin policy layer over refcas: ensure the coordination refspec is installed
+ * (so the claim travels on ordinary `git fetch`), resolve the durable actor,
+ * then attempt the ref compare-and-swap. Used by `momentum claim` and, via the
+ * recipes, by /brainstorm-phase, /start-phase, /hotfix, and /complete-phase.
+ *
+ * Folds ENH-057: a release reserves its version with `claim version <X>` before
+ * tagging — a stale bump loses the CAS and is refused, so two sessions can never
+ * burn a version again.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const refcas = require('./refcas');
+const identity = require('../../identity');
+
+/**
+ * Claim `key` in `namespace`. Returns refcas result:
+ * { won, ref, oid, winner, error }.
+ */
+function claimKey(cwd, namespace, key, opts) {
+  opts = opts || {};
+  const remote = opts.remote || 'origin';
+  const actor = opts.actor || identity.resolveActor(cwd).id;
+  refcas.installRefspec(cwd, remote); // idempotent — makes the ref travel on fetch
+  return refcas.claim(cwd, { namespace, key, actor, remote, extra: opts.extra || {} });
+}
+
+module.exports = { claimKey };

package/core/team/lib/compile.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Compile per-actor fragments into rendered coordination views (Phase 30a
+ * Team-Walk G2, ADR-0012).
+ *
+ * Fragments are collision-free but unreadable on their own; `compile` folds them
+ * (last-writer-per-key) into a human view. The Active-Phase table is the first
+ * view — each lane writes its OWN row fragment, so Rule 15's "one row per active
+ * lane, own-row-touch only" stops being a social convention and becomes
+ * mechanical (you can only write files under your own actor prefix).
+ *
+ * `applyManaged` splices a rendered view between managed markers in a doc
+ * (e.g. status.md), inserting the block if the markers are absent — the same
+ * marked-region pattern momentum already uses for the ecosystem pointer.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const fragments = require('./fragments');
+
+const ACTIVE_PHASE_VIEW = 'active-phase';
+
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Record this lane's Active-Phase row as a fragment (own-row, last-writer-wins). */
+function recordActivePhase(repoRoot, actor, payload, opts) {
+  return fragments.writeFragment(repoRoot, ACTIVE_PHASE_VIEW, actor, 'row', payload, opts);
+}
+
+/** Read + fold the Active-Phase rows (one per lane branch, latest wins). */
+function activePhaseRows(repoRoot) {
+  const folded = fragments.foldLatest(
+    fragments.readFragments(repoRoot, ACTIVE_PHASE_VIEW),
+    (f) => f.payload.branch
+  );
+  return [...folded.values()].sort((a, b) =>
+    String(a.payload.phase || '').localeCompare(String(b.payload.phase || '')) ||
+    String(a.payload.branch).localeCompare(String(b.payload.branch)));
+}
+
+/** Render the Active-Phase rows as a markdown table. */
+function renderActivePhaseTable(rows) {
+  const header =
+    '| Phase | Branch | Actor | Status | Progress |\n' +
+    '|-------|--------|-------|--------|----------|';
+  if (!rows.length) return `${header}\n| _(no active lanes)_ | | | | |`;
+  const body = rows
+    .map((f) => {
+      const p = f.payload;
+      return `| ${p.phase || ''} | ${p.branch} | ${f.actor} | ${p.status || ''} | ${p.progress || ''} |`;
+    })
+    .join('\n');
+  return `${header}\n${body}`;
+}
+
+/** Compile the Active-Phase table for a repo. */
+function compileActivePhase(repoRoot) {
+  return renderActivePhaseTable(activePhaseRows(repoRoot));
+}
+
+/**
+ * Splice `rendered` between `<!-- momentum:team:<name>:begin/end -->` markers in
+ * `content`, inserting the block at the end if the markers are absent.
+ * Idempotent: re-applying with the same rendered text is a no-op.
+ */
+function applyManaged(content, name, rendered) {
+  const begin = `<!-- momentum:team:${name}:begin -->`;
+  const end = `<!-- momentum:team:${name}:end -->`;
+  const block = `${begin}\n${rendered}\n${end}`;
+  const re = new RegExp(`${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}`);
+  if (re.test(content)) return content.replace(re, block);
+  return `${content.trimEnd()}\n\n${block}\n`;
+}
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Render the Active-Phase table from fragments into `specs/status.md`, spliced
+ * between managed markers (inserted if absent). Returns { changed, path } or
+ * { changed:false } when there is no status file. This is what makes the shared
+ * board real: N actors' fragments compile into one conflict-free table.
+ */
+function compileStatusFile(repoRoot) {
+  const statusPath = path.join(repoRoot, 'specs', 'status.md');
+  let content;
+  try { content = fs.readFileSync(statusPath, 'utf8'); } catch { return { changed: false }; }
+  const rendered = compileActivePhase(repoRoot);
+  const next = applyManaged(content, ACTIVE_PHASE_VIEW, rendered);
+  if (next === content) return { changed: false, path: statusPath };
+  fs.writeFileSync(statusPath, next);
+  return { changed: true, path: statusPath };
+}
+
+module.exports = {
+  ACTIVE_PHASE_VIEW,
+  recordActivePhase,
+  activePhaseRows,
+  renderActivePhaseTable,
+  compileActivePhase,
+  applyManaged,
+  compileStatusFile,
+};

package/core/team/lib/fragments.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Per-actor append-only coordination fragments (Phase 30a Team-Walk, ADR-0012).
+ *
+ * Bulk coordination state (the status Active-Phase table, changelog, later the
+ * backlog) is the ONLY thing that crosses machines today (committed specs) — and
+ * it conflicts on every concurrent edit. The fix is the towncrier/reno pattern:
+ * each actor writes its own append-only fragment files; a compile step folds
+ * them into the rendered view. Because an actor only ever writes paths beginning
+ * with its own `<actor>-` prefix, two actors NEVER touch the same file — the
+ * merge is conflict-free BY CONSTRUCTION.
+ *
+ * Fragments live under <repo>/.momentum/team/<view>/ and are COMMITTED (the one
+ * exception to the gitignored .momentum/ — see the `!.momentum/team/` rule).
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SEQ_WIDTH = 6;
+
+function teamRoot(repoRoot) {
+  return path.join(repoRoot, '.momentum', 'team');
+}
+function viewDir(repoRoot, view) {
+  return path.join(teamRoot(repoRoot), String(view));
+}
+
+function pad(seq) {
+  return String(seq).padStart(SEQ_WIDTH, '0');
+}
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Highest existing seq for `actorId` in `view` (0 if none). */
+function maxSeq(repoRoot, view, actorId) {
+  const dir = viewDir(repoRoot, view);
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return 0; }
+  const re = new RegExp(`^${escapeRe(actorId)}-(\\d+)-`);
+  let max = 0;
+  for (const n of names) {
+    const m = n.match(re);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  return max;
+}
+
+/**
+ * Append a fragment. Filename `<actor>-<seq>-<kind>.json` — own-prefix only,
+ * so concurrent writers never collide. `actor` may be an id string or an
+ * identity object ({ id }). `opts.ts` / `opts.seq` are injectable for testing.
+ * Returns the written fragment (with its `file` path).
+ */
+function writeFragment(repoRoot, view, actor, kind, payload, opts) {
+  opts = opts || {};
+  const dir = viewDir(repoRoot, view);
+  fs.mkdirSync(dir, { recursive: true });
+  const actorId = typeof actor === 'string' ? actor : actor.id;
+  const seq = opts.seq != null ? opts.seq : maxSeq(repoRoot, view, actorId) + 1;
+  const safeKind = String(kind).replace(/[^A-Za-z0-9._-]+/g, '-');
+  const frag = {
+    actor: actorId,
+    seq,
+    ts: opts.ts || new Date().toISOString(),
+    kind: safeKind,
+    payload,
+  };
+  const file = path.join(dir, `${actorId}-${pad(seq)}-${safeKind}.json`);
+  fs.writeFileSync(file, JSON.stringify(frag, null, 2) + os.EOL);
+  return Object.assign({ file }, frag);
+}
+
+/** All fragments in a view, stable-sorted by (ts, actor, seq). */
+function readFragments(repoRoot, view) {
+  const dir = viewDir(repoRoot, view);
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const frags = [];
+  for (const n of names) {
+    if (!n.endsWith('.json')) continue;
+    try {
+      frags.push(JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8')));
+    } catch { /* skip malformed */ }
+  }
+  frags.sort((a, b) =>
+    (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0) ||
+    (a.actor < b.actor ? -1 : a.actor > b.actor ? 1 : 0) ||
+    (a.seq - b.seq));
+  return frags;
+}
+
+/**
+ * Fold fragments to the latest per key (own-row / last-writer-wins semantics).
+ * `keyFn(frag)` derives the key; because input is stable-sorted, later
+ * fragments win. Returns a Map(key → fragment).
+ */
+function foldLatest(fragments, keyFn) {
+  const map = new Map();
+  for (const f of fragments) map.set(keyFn(f), f);
+  return map;
+}
+
+module.exports = { teamRoot, viewDir, writeFragment, readFragments, foldLatest, maxSeq };

package/core/team/lib/lease.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * Cross-machine leases via ref-CAS (Phase 30c Team-Fly, ADR-0014).
+ *
+ * Swarm's leases are WALL-CLOCK with no fencing (core/swarm/lib/manifest.js) —
+ * clock skew alone can make two machines both believe they own a repo. Fly moves
+ * lease acquisition to `refs/momentum/leases/<resource>` ref-CAS: exactly one
+ * owner at a time ACROSS machines; the remote arbitrates, no fencing service.
+ * Same first-push-wins primitive as claims and queue turns.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const { spawnSync } = require('child_process');
+const refcas = require('./refcas');
+
+const LEASE_NS = 'leases';
+
+function gitRes(cwd, args) { return spawnSync('git', args, { cwd, encoding: 'utf8' }); }
+
+/** Acquire an exclusive lease on `resource`. Returns { held, owner }. */
+function acquireLease(cwd, resource, actor, remote) {
+  const res = refcas.claim(cwd, { namespace: LEASE_NS, key: resource, actor, remote: remote || 'origin' });
+  if (res.won) return { held: true, owner: typeof actor === 'string' ? actor : actor.id };
+  return { held: false, owner: res.winner && res.winner.actor };
+}
+
+/** Release a lease (delete the ref locally + on remote). */
+function releaseLease(cwd, resource, remote) {
+  const ref = refcas.refPath(LEASE_NS, resource);
+  gitRes(cwd, ['push', remote || 'origin', `:${ref}`]);
+  gitRes(cwd, ['update-ref', '-d', ref]);
+  return true;
+}
+
+/** Current owner of a lease (best-effort remote read), or null. */
+function leaseOwner(cwd, resource, remote) {
+  const w = refcas.readClaim(cwd, { namespace: LEASE_NS, key: resource, remote: remote || 'origin' });
+  return w && w.actor ? w.actor : null;
+}
+
+module.exports = { acquireLease, releaseLease, leaseOwner, LEASE_NS };

package/core/team/lib/presence.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * Team presence — heartbeat-on-invocation (Phase 30b Team-Run, ADR-0013).
+ *
+ * No daemon: any `momentum` command refreshes a short-TTL presence fragment;
+ * liveness (active/idle/offline) is DERIVED from `last_seen` age against config
+ * thresholds. Presence rides the same collision-free fragment substrate as the
+ * Active-Phase table (own-actor prefix → no write contention).
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const fragments = require('./fragments');
+
+const PRESENCE_VIEW = 'presence';
+const DEFAULT_IDLE = 600;     // seconds → "idle" after 10 min
+const DEFAULT_OFFLINE = 3600; // seconds → "offline" after 1 hr
+
+/** Refresh this actor's presence. `ctx` = { branch, lane, activity }. */
+function heartbeat(repoRoot, actor, ctx, opts) {
+  ctx = ctx || {};
+  opts = opts || {};
+  return fragments.writeFragment(repoRoot, PRESENCE_VIEW, actor, 'beat', {
+    branch: ctx.branch || null,
+    lane: ctx.lane || null,
+    activity: ctx.activity || null,
+    last_seen: opts.ts || new Date().toISOString(),
+  }, opts);
+}
+
+/** Derive liveness from a presence fragment given `now` (ms epoch). */
+function liveness(fragment, now, thresholds) {
+  const idle = (thresholds && thresholds.idle) || DEFAULT_IDLE;
+  const offline = (thresholds && thresholds.offline) || DEFAULT_OFFLINE;
+  const seen = new Date(fragment.payload.last_seen || fragment.ts).getTime();
+  const age = (now - seen) / 1000;
+  if (age <= idle) return 'active';
+  if (age <= offline) return 'idle';
+  return 'offline';
+}
+
+/** Latest presence per actor + derived liveness, sorted by actor. */
+function presence(repoRoot, now, thresholds) {
+  const folded = fragments.foldLatest(
+    fragments.readFragments(repoRoot, PRESENCE_VIEW),
+    (f) => f.actor
+  );
+  return [...folded.values()]
+    .map((f) => Object.assign({ actor: f.actor, liveness: liveness(f, now, thresholds) }, f.payload))
+    .sort((a, b) => a.actor.localeCompare(b.actor));
+}
+
+module.exports = { heartbeat, liveness, presence, PRESENCE_VIEW, DEFAULT_IDLE, DEFAULT_OFFLINE };

package/core/team/lib/queue.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * Shared merge-queue turn across contributors (Phase 30b Team-Run, ADR-0013).
+ *
+ * Walk's `lanes land` FIFO turn was per-clone; Run makes it TEAM-WIDE. The
+ * runway is a single-holder ref-CAS lock (`refs/momentum/queue/<runway>-holder`):
+ * exactly one contributor holds the landing turn at a time, ACROSS machines, via
+ * the same first-push-wins primitive as claims. Extends Rule 6 Landing Order to
+ * N humans — the remote arbitrates the turn, no server.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const { spawnSync } = require('child_process');
+const refcas = require('./refcas');
+
+const QUEUE_NS = 'queue';
+
+function gitRes(cwd, args) { return spawnSync('git', args, { cwd, encoding: 'utf8' }); }
+
+function turnKey(runway) { return `${runway}-holder`; }
+function turnRef(runway) { return refcas.refPath(QUEUE_NS, turnKey(runway)); }
+
+/**
+ * Try to take the runway's landing turn. Returns { held, holder }.
+ * If another contributor holds it, `held:false` and `holder` names them.
+ */
+function takeTurn(cwd, runway, actor, remote) {
+  remote = remote || 'origin';
+  const res = refcas.claim(cwd, { namespace: QUEUE_NS, key: turnKey(runway), actor, remote });
+  if (res.won) return { held: true, holder: typeof actor === 'string' ? actor : actor.id };
+  return { held: false, holder: res.winner && res.winner.actor };
+}
+
+/** Release the turn (delete the holder ref locally + on the remote). */
+function releaseTurn(cwd, runway, remote) {
+  remote = remote || 'origin';
+  const ref = turnRef(runway);
+  gitRes(cwd, ['push', remote, `:${ref}`]);  // delete on remote (idempotent)
+  gitRes(cwd, ['update-ref', '-d', ref]);    // delete locally
+  return true;
+}
+
+/** Who currently holds the runway (best-effort remote read), or null if free. */
+function turnHolder(cwd, runway, remote) {
+  const w = refcas.readClaim(cwd, { namespace: QUEUE_NS, key: turnKey(runway), remote: remote || 'origin' });
+  return w && w.actor ? w.actor : null;
+}
+
+module.exports = { takeTurn, releaseTurn, turnHolder, turnRef, QUEUE_NS };

package/core/team/lib/refcas.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * Git-ref compare-and-swap for atomic, cross-machine claims (Phase 30a, ADR-0012).
+ *
+ * Allocation collisions (two people both picking "the next phase" / version /
+ * backlog id) CANNOT be prevented by committed fragments — fragments merge too
+ * LATE (you only see the other write after a merge, by which point you've both
+ * already picked). A claim needs a pre-merge, atomic, single-winner channel.
+ * Git gives us one for free: pushing a NEW ref to the remote is atomic — the
+ * first push creates refs/momentum/<ns>/<key>; a second push of a different
+ * object is a non-fast-forward and is REJECTED. The remote arbitrates; no
+ * server exists.
+ *
+ * The claim payload rides in the commit message of an empty-tree commit the
+ * ref points at, so the winner (and when) is auditable via ordinary git.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const { spawnSync } = require('child_process');
+
+const REFNS = 'refs/momentum';
+
+function gitRes(cwd, args, input) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8', input });
+}
+function git(cwd, ...args) {
+  const r = gitRes(cwd, args);
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+function refPath(namespace, key) {
+  const safe = String(key).replace(/[^A-Za-z0-9._-]+/g, '-');
+  return `${REFNS}/${namespace}/${safe}`;
+}
+
+/** Empty tree oid for this repo's hash algorithm. */
+function emptyTree(cwd) {
+  const r = gitRes(cwd, ['mktree'], '');
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/** Build a claim commit (empty tree, message = claim payload). Returns oid or null. */
+function claimCommit(cwd, payload) {
+  const tree = emptyTree(cwd);
+  if (!tree) return null;
+  return git(cwd, 'commit-tree', tree, '-m', JSON.stringify(payload));
+}
+
+/**
+ * Attempt to atomically claim `key` in `namespace` against `remote`.
+ * Returns { won, ref, oid, winner, error }. On loss, `winner` is the payload
+ * that currently holds the ref (best-effort read).
+ */
+function claim(cwd, opts) {
+  const { namespace, key, actor, remote = 'origin', extra = {} } = opts;
+  const ref = refPath(namespace, key);
+  const payload = Object.assign(
+    { actor: typeof actor === 'string' ? actor : actor && actor.id, key: String(key), ts: new Date().toISOString() },
+    extra
+  );
+  const oid = claimCommit(cwd, payload);
+  if (!oid) {
+    const e = new Error('claim: could not create claim object (not a git repo?)');
+    e.code = 'ENOGIT';
+    throw e;
+  }
+  // create-only push: NO --force. First writer wins; others are non-ff-rejected.
+  const push = gitRes(cwd, ['push', remote, `${oid}:${ref}`]);
+  if (push.status === 0) {
+    return { won: true, ref, oid, winner: payload };
+  }
+  const winner = readClaim(cwd, { namespace, key, remote });
+  return { won: false, ref, oid, winner, error: (push.stderr || '').trim() };
+}
+
+/**
+ * Read the payload currently holding a claim ref (fetches it first).
+ * Returns the parsed payload, or null if unclaimed / unreachable.
+ */
+function readClaim(cwd, { namespace, key, remote = 'origin' }) {
+  const ref = refPath(namespace, key);
+  gitRes(cwd, ['fetch', remote, `${ref}:${ref}`]); // best-effort; ignore failure
+  const msg = git(cwd, 'log', '-1', '--format=%B', ref);
+  if (!msg) return null;
+  try { return JSON.parse(msg.trim()); } catch { return { raw: msg.trim() }; }
+}
+
+/** Claimed keys in a namespace (local refs; call fetchAll first for freshness). */
+function listClaims(cwd, namespace) {
+  const out = git(cwd, 'for-each-ref', '--format=%(refname)', `${REFNS}/${namespace}`);
+  if (!out) return [];
+  const prefix = `${REFNS}/${namespace}/`;
+  return out.split('\n').filter(Boolean).map((r) => r.slice(prefix.length));
+}
+
+/** Fetch all coordination refs from remote into local refs/momentum/*. */
+function fetchAll(cwd, remote = 'origin') {
+  return gitRes(cwd, ['fetch', remote, `+${REFNS}/*:${REFNS}/*`]).status === 0;
+}
+
+/** Ensure `git fetch` carries refs/momentum/*. Idempotent — true if it added the spec. */
+function installRefspec(cwd, remote = 'origin') {
+  const spec = `+${REFNS}/*:${REFNS}/*`;
+  const existing = git(cwd, 'config', '--get-all', `remote.${remote}.fetch`) || '';
+  if (existing.split('\n').includes(spec)) return false;
+  gitRes(cwd, ['config', '--add', `remote.${remote}.fetch`, spec]);
+  return true;
+}
+
+module.exports = { claim, readClaim, listClaims, fetchAll, installRefspec, refPath, REFNS };

package/core/team/relay/client.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * Relay client (Phase 30c Team-Fly, ADR-0014).
+ *
+ * GRACEFUL ABSENCE is the whole point: with no relayUrl (or an unreachable one),
+ * publish/poll are no-ops that report `skipped` — the caller simply falls back to
+ * git-native `team sync`. Nothing depends on the relay; it carries no authority.
+ *
+ * Zero dependencies — node http only.
+ */
+
+const http = require('http');
+
+function request(method, url, body) {
+  return new Promise((resolve) => {
+    let u;
+    try { u = new URL(url); } catch { return resolve({ ok: false, skipped: true, reason: 'no relay' }); }
+    const data = body != null ? JSON.stringify(body) : null;
+    const req = http.request(
+      {
+        hostname: u.hostname, port: u.port, path: u.pathname + u.search, method,
+        headers: data ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(data) } : {},
+      },
+      (res) => {
+        let out = '';
+        res.on('data', (c) => { out += c; });
+        res.on('end', () => { try { resolve(JSON.parse(out || '{}')); } catch { resolve({ ok: false }); } });
+      }
+    );
+    req.on('error', () => resolve({ ok: false, skipped: true, reason: 'unreachable' }));
+    req.setTimeout(1500, () => { req.destroy(); resolve({ ok: false, skipped: true, reason: 'timeout' }); });
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+/** Publish a coordination event. No-op (skipped) when relayUrl is absent. */
+async function publish(relayUrl, event) {
+  if (!relayUrl) return { ok: false, skipped: true, reason: 'no relay' };
+  return request('POST', relayUrl.replace(/\/$/, '') + '/publish', event);
+}
+
+/** Poll events since `since`. Returns { events } (possibly empty), never throws. */
+async function poll(relayUrl, since) {
+  if (!relayUrl) return { ok: false, skipped: true, events: [] };
+  const r = await request('GET', relayUrl.replace(/\/$/, '') + `/events?since=${since || 0}`);
+  return Array.isArray(r.events) ? r : { ok: false, skipped: true, events: [] };
+}
+
+module.exports = { publish, poll };

package/core/team/relay/server.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * Optional self-hostable coordination relay (Phase 30c Team-Fly, ADR-0014).
+ *
+ * AUTHORITY-FREE by design: it mirrors coordination EVENTS (fragment/claim
+ * notifications) so teams get near-real-time visibility WITHOUT waiting for a git
+ * sync. It never gates, approves, or lands — remove it and nothing about
+ * correctness changes; the plane falls straight back to git-native (Walk/Run).
+ * momentum ships this code; it does NOT run a hosted service — operators self-host.
+ *
+ * Minimal store-and-poll protocol (no external deps):
+ *   POST /publish   { ...event }   → { ok, seq, protocol }
+ *   GET  /events?since=N           → { protocol, events: [...] }
+ *   GET  /health                   → { ok, protocol }
+ *
+ * Zero dependencies — node http only.
+ */
+
+const http = require('http');
+
+const PROTOCOL_VERSION = 1;
+
+function createRelay(opts) {
+  opts = opts || {};
+  const events = [];
+
+  const server = http.createServer((req, res) => {
+    if (req.method === 'POST' && req.url === '/publish') {
+      let body = '';
+      req.on('data', (c) => { body += c; if (body.length > 1e6) req.destroy(); });
+      req.on('end', () => {
+        try {
+          const ev = JSON.parse(body || '{}');
+          const stored = Object.assign({}, ev, { seq: events.length + 1 });
+          events.push(stored);
+          res.writeHead(200, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, seq: stored.seq, protocol: PROTOCOL_VERSION }));
+        } catch {
+          res.writeHead(400, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'bad json' }));
+        }
+      });
+      return;
+    }
+    if (req.method === 'GET' && req.url.startsWith('/events')) {
+      const since = Number(new URL(req.url, 'http://x').searchParams.get('since') || 0);
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ protocol: PROTOCOL_VERSION, events: events.filter((e) => e.seq > since) }));
+      return;
+    }
+    if (req.method === 'GET' && req.url === '/health') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, protocol: PROTOCOL_VERSION }));
+      return;
+    }
+    res.writeHead(404); res.end();
+  });
+
+  return {
+    listen(cb) { server.listen(opts.port || 0, '127.0.0.1', () => cb(server.address().port)); },
+    close(cb) { server.close(cb); },
+    events,
+    server,
+  };
+}
+
+module.exports = { createRelay, PROTOCOL_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limina-labs/momentum",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Agent-agnostic, specs-driven development framework — single project or multi-project ecosystem",
   "homepage": "https://trymomentum.github.io",
   "bin": {