@limina-labs/momentum 0.30.2

package/bin/okf.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `momentum okf` — OKF v0.1 bundle utilities (Phase 24, ADR-0005).
+ *
+ *   momentum okf check [dir]   conformance report for <dir>/specs
+ *   momentum okf index [dir]   regenerate bundle indexes (root/phases/decisions)
+ *
+ * The migration itself runs inside `momentum upgrade`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const okf = require('../core/lib/okf-migrate');
+
+function usage() {
+  console.log(`momentum okf — Open Knowledge Format (v${okf.OKF_VERSION}) bundle utilities
+
+  momentum okf check [dir]   conformance report for <dir>/specs (exit 1 on violations)
+  momentum okf index [dir]   regenerate specs/index.md + phases/ + decisions/ listings
+
+  Migration of legacy JSON state (phases/index.json, decisions/impact-map.json)
+  runs as part of \`momentum upgrade\`.`);
+}
+
+function runOkf(args) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+    usage();
+    return sub ? 0 : 1;
+  }
+  const target = path.resolve(args[1] || process.cwd());
+
+  if (sub === 'check') {
+    const report = okf.check(target);
+    if (!report.applicable) {
+      console.error(`✗ no specs/ directory at ${target}`);
+      return 1;
+    }
+    for (const w of report.warnings) console.error(`  ⚠ ${w}`);
+    if (report.violations.length) {
+      console.log(`OKF v${okf.OKF_VERSION} conformance: ${path.join(target, 'specs')}`);
+      for (const v of report.violations) console.log(`  ✗ ${v.rel} — ${v.problem}`);
+      console.log(`✗ ${report.violations.length} violation(s) across ${report.files} markdown file(s)`);
+      return 1;
+    }
+    console.log(`✓ specs/ is an OKF v${okf.OKF_VERSION} conformant bundle (${report.files} markdown file(s))`);
+    return 0;
+  }
+
+  if (sub === 'index') {
+    if (!fs.existsSync(path.join(target, 'specs'))) {
+      console.error(`✗ no specs/ directory at ${target}`);
+      return 1;
+    }
+    const changed = okf.generateIndexes(target);
+    if (!changed.length) {
+      console.log('= bundle indexes up to date');
+    } else {
+      for (const rel of changed) console.log(`✓ wrote specs/${rel}`);
+    }
+    return 0;
+  }
+
+  console.error(`Unknown okf subcommand: ${sub}`);
+  console.error('Run "momentum okf help" for usage.');
+  return 1;
+}
+
+module.exports = { runOkf };

package/bin/orchestration-commands.js

@@ -0,0 +1,305 @@
+'use strict';
+
+// CLI verbs for orchestration primitives.
+//
+// Three doors, one library. This is the CLI door — `momentum scout`,
+// `momentum dispatch`, `momentum handoff`, `momentum continue`. All
+// dispatch into core/orchestration/* so output shape is identical to
+// the slash-command and natural-language inference doors.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MOMENTUM_ROOT = path.resolve(__dirname, '..');
+const orchestration = require(path.join(MOMENTUM_ROOT, 'core', 'orchestration'));
+const { findRegistration } = require(path.join(MOMENTUM_ROOT, 'core', 'ecosystem', 'lib', 'state'));
+
+// ── shared helpers ─────────────────────────────────────────────────────────
+
+function resolveEcosystemFromCwd(repoPath) {
+  try {
+    const reg = findRegistration(repoPath);
+    if (reg && reg.rootPath) {
+      return { rootPath: reg.rootPath, memberId: reg.memberId };
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function resolveTargetRepo(spec, ecosystem) {
+  // Allow either a manifest member id or a relative/absolute path.
+  if (!spec) return null;
+  if (path.isAbsolute(spec) && fs.existsSync(spec)) return spec;
+
+  if (ecosystem && ecosystem.rootPath) {
+    const lib = require(path.join(MOMENTUM_ROOT, 'core', 'ecosystem', 'lib', 'index'));
+    try {
+      const manifest = lib.loadManifest(ecosystem.rootPath);
+      for (const m of lib.listMembers(manifest)) {
+        if (m.id === spec) {
+          return path.resolve(ecosystem.rootPath, m.path);
+        }
+      }
+    } catch {
+      // fall through to path resolution
+    }
+  }
+
+  const asRel = path.resolve(process.cwd(), spec);
+  if (fs.existsSync(asRel)) return asRel;
+  return null;
+}
+
+function printOrchHelp(verb) {
+  const blocks = {
+    scout: [
+      'Usage: momentum scout <repo> "<prompt>"',
+      '',
+      'Read-only context fetch from one ecosystem member repo.',
+      '',
+      'Doors:',
+      '  - slash:    /scout <repo> "<prompt>"        (Claude Code, Codex)',
+      '  - natural:  describe a single-repo read-only task in prose',
+      '  - cli:      momentum scout <repo> "<prompt>"  (universal floor)',
+      '',
+      'Tracking contract: session log + scout-NNN.md auto every time;',
+      '[DISCOVERY] in scouted repo only if finding meets Rule 3 criteria.',
+    ],
+    dispatch: [
+      'Usage: momentum dispatch <repo1> [repo2 ...] --prompt "<text>"',
+      '',
+      'Parallel multi-repo fan-out + synthesis.',
+      '',
+      'Flags:',
+      '  --prompt "<text>"   high-level intent (tailored per-repo at runtime)',
+      '  --sequential        force sequential mode (testing aid)',
+      '',
+      'Doors: /dispatch (slash) | natural-language inference | momentum dispatch (CLI)',
+      '',
+      'Tracking contract: session log + dispatch-NNN.md auto every time;',
+      'per-repo [DISCOVERY] only for meaningful findings.',
+    ],
+    handoff: [
+      'Usage: momentum handoff <repo> [--summary "<text>"]',
+      '',
+      'Write a context block to <repo>/.momentum/inbox/handoff-NNN.md so',
+      'a new agent session in that repo can pick up where you left off.',
+      '',
+      'Tracking contract: writes the inbox file AND emits a [DECISION] in',
+      'the originating repo\'s active phase history (handoff IS a decision).',
+    ],
+    continue: [
+      'Usage: momentum continue [--handoff <id>]',
+      '',
+      'Pick up a pending handoff in the current repo. With no --handoff,',
+      'lists pending handoffs and picks the oldest unread.',
+    ],
+  };
+  for (const line of blocks[verb] || []) console.log(line);
+}
+
+/**
+ * Light-weight flag parser. `knownFlags` may be:
+ *   - a string array of flag tokens (value flags — consume the next non-flag token)
+ *   - an object { valueFlags: [...], boolFlags: [...] } for explicit shapes
+ */
+function parseFlags(args, knownFlags) {
+  let valueFlags = [];
+  let boolFlags = [];
+  if (Array.isArray(knownFlags)) {
+    valueFlags = knownFlags;
+  } else if (knownFlags && typeof knownFlags === 'object') {
+    valueFlags = knownFlags.valueFlags || [];
+    boolFlags = knownFlags.boolFlags || [];
+  }
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (valueFlags.includes(a)) {
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[a.slice(2)] = next;
+        i++;
+      } else {
+        flags[a.slice(2)] = true;
+      }
+    } else if (boolFlags.includes(a)) {
+      flags[a.slice(2)] = true;
+    } else if (a === '--help' || a === '-h') {
+      flags.help = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+// ── cmdScout ───────────────────────────────────────────────────────────────
+
+async function cmdScout(args) {
+  const { positional, flags } = parseFlags(args, []);
+  if (flags.help || positional.length < 2) {
+    printOrchHelp('scout');
+    process.exit(flags.help ? 0 : positional.length === 0 ? 1 : 1);
+  }
+  const repoSpec = positional[0];
+  const prompt = positional.slice(1).join(' ');
+  const originatingRepo = process.cwd();
+  const ecosystem = resolveEcosystemFromCwd(originatingRepo);
+  const targetRepo = resolveTargetRepo(repoSpec, ecosystem);
+
+  if (!targetRepo) {
+    console.error(`Error: could not resolve <repo> "${repoSpec}" — not a member id and not an existing path.`);
+    process.exit(1);
+  }
+
+  const result = await orchestration.scout.scout({
+    repo: targetRepo,
+    prompt,
+    originatingRepo,
+    ecosystem: ecosystem || undefined,
+  });
+
+  // Renderer already printed lifecycle lines; final summary goes to stdout.
+  process.stdout.write('\n');
+  process.stdout.write(result.summary + '\n');
+}
+
+// ── cmdDispatch ────────────────────────────────────────────────────────────
+
+async function cmdDispatch(args) {
+  const { positional, flags } = parseFlags(args, {
+    valueFlags: ['--prompt'],
+    boolFlags: ['--sequential'],
+  });
+  if (flags.help || positional.length === 0 || !flags.prompt) {
+    printOrchHelp('dispatch');
+    process.exit(flags.help ? 0 : 1);
+  }
+  const originatingRepo = process.cwd();
+  const ecosystem = resolveEcosystemFromCwd(originatingRepo);
+  const repos = positional
+    .map((spec) => ({ spec, abs: resolveTargetRepo(spec, ecosystem) }))
+    .filter((entry) => {
+      if (!entry.abs) {
+        console.error(`Warning: skipping unresolved repo "${entry.spec}"`);
+        return false;
+      }
+      return true;
+    })
+    .map((entry) => entry.abs);
+
+  if (repos.length === 0) {
+    console.error('Error: no resolvable repos in dispatch list.');
+    process.exit(1);
+  }
+
+  const dispatch = orchestration.dispatch;
+  const result = await dispatch.dispatch({
+    repos,
+    userIntent: flags.prompt,
+    originatingRepo,
+    ecosystem: ecosystem || undefined,
+    forceSequential: Boolean(flags.sequential),
+  });
+
+  process.stdout.write('\n');
+  process.stdout.write(result.synthesis + '\n');
+  if (result.failures.length) {
+    process.stdout.write(`\n${result.failures.length} repo(s) failed:\n`);
+    for (const f of result.failures) {
+      process.stdout.write(`  - ${f.repo}: ${f.error && f.error.message ? f.error.message : f.error}\n`);
+    }
+  }
+}
+
+// ── cmdHandoff ─────────────────────────────────────────────────────────────
+
+async function cmdHandoff(args) {
+  const { positional, flags } = parseFlags(args, ['--summary', '--decision', '--file', '--verify', '--question']);
+  if (flags.help || positional.length === 0) {
+    printOrchHelp('handoff');
+    process.exit(flags.help ? 0 : 1);
+  }
+  const originatingRepo = process.cwd();
+  const ecosystem = resolveEcosystemFromCwd(originatingRepo);
+  const targetRepo = resolveTargetRepo(positional[0], ecosystem);
+
+  if (!targetRepo) {
+    console.error(`Error: could not resolve <repo> "${positional[0]}".`);
+    process.exit(1);
+  }
+
+  const summary = flags.summary || `Continue work from ${path.basename(originatingRepo)}.`;
+  const block = await orchestration.handoff.handoff({
+    fromRepo: originatingRepo,
+    toRepo: targetRepo,
+    summary,
+    decisions: arrayify(flags.decision),
+    filesTouched: arrayify(flags.file),
+    verificationCommands: arrayify(flags.verify),
+    openQuestions: arrayify(flags.question),
+    ecosystem: ecosystem || undefined,
+  });
+
+  process.stdout.write(`\n▸ handoff written: ${block.inboxPath}\n`);
+}
+
+// ── cmdContinue ────────────────────────────────────────────────────────────
+
+async function cmdContinue(args) {
+  const { positional, flags } = parseFlags(args, ['--handoff']);
+  if (flags.help) {
+    printOrchHelp('continue');
+    process.exit(0);
+  }
+  const originatingRepo = process.cwd();
+  const ecosystem = resolveEcosystemFromCwd(originatingRepo);
+  const block = await orchestration.continueHandoff.continueHandoff({
+    repo: originatingRepo,
+    handoffId: flags.handoff || (positional.length ? positional[0] : undefined),
+    ecosystem: ecosystem || undefined,
+  });
+
+  if (!block) {
+    process.stdout.write('▸ no pending handoffs in this repo\n');
+    return;
+  }
+  process.stdout.write(`\n▸ picking up handoff-${block.handoffId} from ${path.basename(block.fromRepo)}\n\n`);
+  process.stdout.write(`Summary: ${block.summary}\n`);
+  if (block.decisions.length) {
+    process.stdout.write('\nDecisions:\n');
+    for (const d of block.decisions) process.stdout.write(`  - ${d}\n`);
+  }
+  if (block.filesTouched.length) {
+    process.stdout.write('\nFiles touched:\n');
+    for (const f of block.filesTouched) process.stdout.write(`  - ${f}\n`);
+  }
+  if (block.verificationCommands.length) {
+    process.stdout.write('\nVerification:\n');
+    for (const v of block.verificationCommands) process.stdout.write(`  $ ${v}\n`);
+  }
+  if (block.openQuestions.length) {
+    process.stdout.write('\nOpen questions:\n');
+    for (const q of block.openQuestions) process.stdout.write(`  ? ${q}\n`);
+  }
+}
+
+function arrayify(v) {
+  if (v == null || v === false) return [];
+  if (Array.isArray(v)) return v;
+  return [String(v)];
+}
+
+module.exports = {
+  cmdScout,
+  cmdDispatch,
+  cmdHandoff,
+  cmdContinue,
+  // exported for tests:
+  resolveTargetRepo,
+  resolveEcosystemFromCwd,
+};

package/bin/state-commands.js

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * Phase 10 — top-level state commands: `join`, `leave`, `doctor`.
+ *
+ * These are user-facing verbs that let a repo move between Standalone,
+ * Member, and Leader states without having to know about the
+ * `momentum ecosystem` operator toolkit.
+ *
+ * Internally they compose the existing `momentum ecosystem add/remove`
+ * primitives so there is exactly one place that mutates manifests +
+ * pointer blocks. State preconditions are checked first to surface
+ * clear errors before any mutation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const stateLib = require('../core/ecosystem/lib/state');
+const pointerLib = require('../core/ecosystem/lib/pointer');
+const lib = require('../core/ecosystem/lib');
+
+function cmdJoin(args) {
+  if (!args || args.length === 0) {
+    throw new Error(
+      'join: missing <ecosystem-path>. Try `momentum doctor` to see what is reachable from here.',
+    );
+  }
+  let ecosystemPath = path.resolve(process.cwd(), args[0]);
+  if (!fs.existsSync(path.join(ecosystemPath, lib.MANIFEST_FILENAME))) {
+    throw new Error(
+      `join: ${ecosystemPath} has no ecosystem.json. Did you mean a different path?`,
+    );
+  }
+  // Normalize via realpath so the manifest stores a clean relative
+  // path (../project) instead of a cross-symlink monstrosity
+  // (../../../private/tmp/.../project) on macOS where /tmp → /private/tmp.
+  try {
+    ecosystemPath = fs.realpathSync(ecosystemPath);
+  } catch (_e) { /* keep resolved form */ }
+
+  const cwd = realpathOf(process.cwd());
+  lib._clearRootCache();
+  const state = stateLib.detectState(cwd);
+
+  if (state === 'leader' || state === 'leader-and-member') {
+    throw new Error(
+      'join: this directory is itself an ecosystem root. ' +
+        'Use `momentum ecosystem add <repo-path>` to register members instead.',
+    );
+  }
+
+  if (state === 'member') {
+    const reg = stateLib.findRegistration(cwd);
+    if (reg && path.resolve(reg.rootPath) === ecosystemPath) {
+      console.log(
+        `Already a member of "${reg.ecosystemName}" at ${reg.rootPath}. No changes.`,
+      );
+      return;
+    }
+    throw new Error(
+      `join: this repo is already a member of a different ecosystem ` +
+        `("${reg ? reg.ecosystemName : '?'}"). Run \`momentum leave\` first.`,
+    );
+  }
+
+  // standalone / broken-pointer / broken-orphan — proceed with ecosystem add.
+  const { runEcosystem } = require('./ecosystem');
+  runEcosystem(['add', cwd, '--ecosystem', ecosystemPath]);
+
+  // Re-detect post-mutation to confirm.
+  lib._clearRootCache();
+  const after = stateLib.detectState(cwd);
+  if (after === 'member' || after === 'leader-and-member') {
+    const reg = stateLib.findRegistration(cwd);
+    console.log('');
+    console.log(`✓ Joined "${reg ? reg.ecosystemName : '?'}" as member "${reg ? reg.memberId : '?'}".`);
+  }
+}
+
+function cmdLeave(args) {
+  // No required args; opt-in flags TBD.
+  void args;
+  const cwd = realpathOf(process.cwd());
+  lib._clearRootCache();
+  const state = stateLib.detectState(cwd);
+
+  if (state === 'standalone') {
+    console.log('Already standalone. No changes.');
+    return;
+  }
+  if (state === 'leader') {
+    throw new Error(
+      'leave: this directory is an ecosystem root with no membership in another ecosystem. ' +
+        'There is nothing to leave.',
+    );
+  }
+  if (state === 'broken-manifest') {
+    throw new Error(
+      'leave: ecosystem.json in this directory fails validation. ' +
+        'Repair or delete it manually before running leave.',
+    );
+  }
+
+  if (state === 'broken-pointer') {
+    // Pointer present but no registration. Just strip pointer to recover.
+    const primary = pointerLib.findPrimaryInstructionFile(cwd);
+    if (primary) {
+      pointerLib.stripPointer(path.join(cwd, primary));
+      console.log('Stripped dangling pointer. Now standalone.');
+    } else {
+      console.log('No pointer block found. No changes.');
+    }
+    return;
+  }
+
+  // member / leader-and-member / broken-orphan — find registration and remove.
+  const reg = stateLib.findRegistration(cwd);
+  if (!reg) {
+    throw new Error(
+      'leave: could not locate this repo in any reachable ecosystem manifest. ' +
+        'Try `momentum doctor` for diagnostics.',
+    );
+  }
+
+  const { runEcosystem } = require('./ecosystem');
+  runEcosystem(['remove', reg.memberId, '--ecosystem', reg.rootPath]);
+  console.log('');
+  console.log(`✓ Left "${reg.ecosystemName}". Now standalone.`);
+}
+
+function cmdDoctor(args) {
+  void args;
+  const cwd = realpathOf(process.cwd());
+  lib._clearRootCache();
+  const state = stateLib.detectState(cwd);
+  const reg = stateLib.findRegistration(cwd);
+
+  console.log(`Path:  ${cwd}`);
+  console.log(`State: ${formatStateLabel(state)}`);
+  if (reg) {
+    console.log(`Ecosystem: ${reg.ecosystemName}`);
+    console.log(`  root:    ${reg.rootPath}`);
+    console.log(`  member:  ${reg.memberId}  (role: ${reg.memberRole || 'other'})`);
+  } else if (state === 'leader' || state === 'leader-and-member') {
+    try {
+      const manifest = lib.loadManifest(cwd);
+      console.log(`Ecosystem: ${manifest.name}`);
+      console.log(`  members: ${manifest.members.length}`);
+    } catch (_err) { /* shown via state */ }
+  }
+  console.log('');
+
+  // Phase 22b G3 — Antigravity runtime advisory. Only for projects whose
+  // momentum install targets antigravity (lock file), and only ADVISES the
+  // official installer — momentum never provisions vendor binaries (see the
+  // VAL-002 adjudication record).
+  try {
+    const lockPath = path.join(cwd, '.momentum', 'installed.json');
+    if (fs.existsSync(lockPath)) {
+      const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+      if (lock.agent === 'antigravity' || (lock.agents && lock.agents['antigravity'])) {
+        const { spawnSync } = require('child_process');
+        const agyBin = process.env.AGY_BIN || 'agy';
+        const found = agyBin.includes(path.sep)
+          ? fs.existsSync(agyBin)
+          : spawnSync('which', [agyBin], { stdio: 'ignore' }).status === 0;
+        if (!found) {
+          console.log('Advisory: this project targets Antigravity but the `agy` CLI is not on PATH.');
+          console.log('  Headless features (swarm spawn, orchestration CLI floor) need it.');
+          console.log('  Official installer: curl -fsSL https://antigravity.google/cli/install.sh | bash');
+          console.log('  (The Antigravity IDE works without it — this only affects CLI/headless use.)');
+          console.log('');
+        }
+      }
+    }
+  } catch (_err) { /* advisory is best-effort — never block doctor */ }
+
+  const transitions = stateLib.availableTransitions(state, reg || {});
+  if (transitions.length === 0) {
+    console.log('No suggested next steps for this state.');
+    return;
+  }
+  console.log('What you can do next:');
+  for (const t of transitions) {
+    console.log('');
+    console.log(`  ${t.command}`);
+    console.log(`    ${t.description}`);
+  }
+}
+
+function realpathOf(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch (_e) {
+    return path.resolve(p);
+  }
+}
+
+function formatStateLabel(state) {
+  const labels = {
+    standalone: 'Standalone — momentum-installed, not in any ecosystem',
+    member: 'Member — part of an ecosystem',
+    leader: 'Leader — this directory IS an ecosystem root',
+    'leader-and-member': 'Leader+Member — ecosystem root that is also a member of another ecosystem',
+    'broken-manifest': 'Broken (manifest) — ecosystem.json fails validation',
+    'broken-pointer': 'Broken (pointer) — pointer block present but no matching ecosystem',
+    'broken-orphan': 'Broken (orphan) — registered in an ecosystem but pointer block missing',
+  };
+  return labels[state] || state;
+}
+
+module.exports = {
+  cmdJoin,
+  cmdLeave,
+  cmdDoctor,
+  formatStateLabel,
+};