@limina-labs/momentum 0.30.2

package/bin/waves.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * `momentum waves` — render the wave plan at any scale (Phase 21c,
+ * FEAT-028 — ADR-0003).
+ *
+ *   momentum waves                 phase scale: non-complete phases from
+ *                                  overview.md frontmatter (`deps:`, OKF
+ *                                  bundle) — legacy index.json fallback
+ *   momentum waves --tasks [ref]   task scale: group waves for a tasks.md —
+ *                                  ref = phase id or a tasks.md path;
+ *                                  default = the phase bound to the current
+ *                                  branch (Rule 15), fallback status.md
+ *   momentum waves --json          machine shape (unstable, internal)
+ *
+ * Waves feed lanes: wave-1 nodes print suggested `momentum lanes open`
+ * commands. Cross-repo (ecosystem) waves stay with `momentum swarm`,
+ * which consumes the same engine.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MOMENTUM_ROOT = path.resolve(__dirname, '..');
+const { computeWaveLayers } = require(path.join(MOMENTUM_ROOT, 'core', 'waves', 'lib', 'waves'));
+const graphs = require(path.join(MOMENTUM_ROOT, 'core', 'waves', 'lib', 'plan-graph'));
+
+function git(cwd, ...args) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+
+/** Resolve the tasks.md to plan from a ref (phase id, path, or branch binding). */
+function resolveTasksFile(cwd, ref) {
+  const root = git(cwd, 'rev-parse', '--show-toplevel');
+  if (!root) return { error: 'not inside a git repository' };
+  if (ref) {
+    const asPath = path.resolve(cwd, ref);
+    if (fs.existsSync(asPath) && asPath.endsWith('.md')) return { file: asPath, label: ref };
+    const asPhase = path.join(root, 'specs', 'phases', ref, 'tasks.md');
+    if (fs.existsSync(asPhase)) return { file: asPhase, label: ref };
+    return { error: `cannot resolve '${ref}' to a phase or tasks.md path` };
+  }
+  // Rule 15 binding: phase-* branch with a matching phase dir.
+  const branch = git(cwd, 'symbolic-ref', '--short', 'HEAD');
+  if (branch && /^phase-/.test(branch)) {
+    const f = path.join(root, 'specs', 'phases', branch, 'tasks.md');
+    if (fs.existsSync(f)) return { file: f, label: branch };
+  }
+  // Fallback: first status.md Active Phase row with an existing dir.
+  try {
+    const status = fs.readFileSync(path.join(root, 'specs', 'status.md'), 'utf8');
+    const section = status.split(/^## Active Phase/m)[1] || '';
+    const tokens = [...section.split(/^## /m)[0].matchAll(/`(phase-[A-Za-z0-9._-]+)`/g)].map((m) => m[1]);
+    for (const t of tokens) {
+      const f = path.join(root, 'specs', 'phases', t, 'tasks.md');
+      if (fs.existsSync(f)) return { file: f, label: `${t} (status.md fallback)` };
+    }
+  } catch { /* no status.md */ }
+  return { error: 'no tasks.md resolvable — pass a phase id or path: momentum waves --tasks <ref>' };
+}
+
+function render(waves, { json, kind, suggest }) {
+  if (json) {
+    console.log(JSON.stringify({ unstable: true, kind, waves }, null, 2));
+    return;
+  }
+  if (waves.length === 0) {
+    console.log(`no pending ${kind} — nothing to schedule`);
+    return;
+  }
+  for (const w of waves) {
+    console.log(`wave ${w.index}: ${w.nodes.join('  ')}`);
+  }
+  if (suggest && waves[0]) {
+    console.log('');
+    console.log('wave 1 can start now — open a lane per node:');
+    for (const n of waves[0].nodes) {
+      console.log(`  momentum lanes open ${suggest(n)}`);
+    }
+  }
+}
+
+function runWaves(argv, cwd = process.cwd()) {
+  const json = argv.includes('--json');
+  const args = argv.filter((a) => a !== '--json');
+
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    console.log(`momentum waves — wave plan from dependency annotations (one engine, every scale)
+
+  momentum waves                 phase scale (overview.md frontmatter "deps"; complete = satisfied)
+  momentum waves --tasks [ref]   task-group scale ("## Group N — t (deps: G0)" in tasks.md;
+                                 fully-checked groups = satisfied); ref = phase id | path;
+                                 default = the phase bound to your branch (Rule 15)
+  --json                         machine shape (unstable, internal)
+
+Waves feed lanes (momentum lanes open …) and land sequentially (momentum
+lanes land). Cross-repo waves: momentum swarm (same engine).`);
+    return 0;
+  }
+
+  try {
+    if (args[0] === '--tasks') {
+      const resolved = resolveTasksFile(cwd, args[1]);
+      if (resolved.error) {
+        console.error(`✗ ${resolved.error}`);
+        return 1;
+      }
+      const graph = graphs.taskGraph(resolved.file);
+      if (!graph || graph.groups.length === 0) {
+        console.error(`✗ no "## Group …" headings found in ${resolved.file}`);
+        return 1;
+      }
+      console.log(`task-group waves for ${resolved.label}:`);
+      const satisfied = graph.groups.filter((g) => g.satisfied).map((g) => g.id);
+      if (satisfied.length) console.log(`(satisfied, dropped: ${satisfied.join(', ')})`);
+      const waves = graph.nodes.length
+        ? computeWaveLayers(graph.nodes, graph.edges, { label: 'waves --tasks' })
+        : [];
+      render(waves, { json, kind: 'task groups', suggest: null });
+      return 0;
+    }
+
+    const root = git(cwd, 'rev-parse', '--show-toplevel');
+    if (!root) {
+      console.error('✗ not inside a git repository');
+      return 1;
+    }
+    const graph = graphs.phaseGraph(root);
+    if (!graph) {
+      console.error('✗ no phase metadata found (specs/phases/*/overview.md frontmatter, or legacy specs/phases/index.json)');
+      return 1;
+    }
+    console.log(`phase waves (non-complete phases; ${graph.source} "deps"):`);
+    const waves = graph.nodes.length
+      ? computeWaveLayers(graph.nodes, graph.edges, { label: 'waves' })
+      : [];
+    render(waves, { json, kind: 'phases', suggest: (n) => n });
+    return 0;
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    return 1;
+  }
+}
+
+module.exports = { runWaves };

package/core/adapter-capabilities.md

@@ -0,0 +1,112 @@
+# Adapter Capability Matrix
+
+> Single source of truth for what each shipped adapter declares it can
+> do. Generated from the `capabilities` block on each adapter's
+> `adapter.js`. Audited automatically by
+> `tests/adapter-capabilities-declared.test.js`.
+>
+> Phase 11 (v0.14.0) unified the declared shape: every capability is
+> now a **uniform boolean**. "Future-planned" or caveated notes live in
+> the adapter's separate `roadmap` block — they no longer pollute the
+> capability values. The orchestration library's
+> `core/orchestration/capability-routing.js` reads this matrix to
+> decide which primitives run in parallel vs sequential per adapter.
+
+## How to read this matrix
+
+A capability cell is one of:
+- ✅ — declared `true`
+- ❌ — declared `false`
+
+Footnotes (¹, ², …) link to roadmap entries when the declaration has
+forward-looking context (e.g., "planned for a future Codex feature
+drop"). The boolean itself reflects today's truth — never aspirational
+behaviour.
+
+If you add a new adapter, fill in **every** column. The audit test
+asserts every adapter declares the full capability surface that
+orchestration code depends on.
+
+## Matrix (as of 2026-07-05, Phase 22 G0 — opencode column added)
+
+| Capability | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| `hooks` | ✅⁵ | ✅ | ✅ | ✅ |
+| `slashCommands` | ✅⁵ | ✅ | ✅ | ❌¹ |
+| `subagents` | ✅⁵ | ✅ | ✅² | ✅ |
+| `parallelSubagents` | ✅⁵ | ✅ | ❌² | ✅ |
+| `sessionStartHook` | ✅⁵ | ✅ | ✅ | ❌³ |
+| `skills` | ✅⁵ | ❌ | ❌⁴ | ❌ |
+| `browser` | ❌ | ❌ | ❌⁴ | ❌ |
+| `computerUse` | ❌ | ❌ | ❌⁴ | ❌ |
+| `artifacts` (adapter-specific) | — | — | — | ✅ |
+| `planningMode` (adapter-specific) | ✅ | — | — | ✅ |
+
+## Phase 17 (v0.20.0) + Phase 17.5 (v0.20.2) + Phase 18 (v0.20.4) — `/swarm` cross-adapter
+
+Phase 17 (v0.20.0) delivered the conductor + supervisor architecture,
+files-as-channels coordination, indexing strategies, and intervention
+surface — Claude Code only. Phase 17.5 (v0.20.2) layered five
+portability subcommands (`claim` / `release` / `focus` / `join` /
+`absorb`), lease enforcement at the `manifest.js` write chokepoint, and
+a typed signal protocol. The underlying `core/swarm/` library is
+platform-agnostic.
+
+**Phase 18 (v0.20.4)** brings the full 13-subcommand swarm surface to
+Codex and Antigravity via an `adapter.spawn(directive)` contract added
+to every adapter:
+
+| Adapter | What ships in Phase 18 |
+|---|---|
+| Codex | `adapter.spawn()` shells `codex --cwd <repoPath> --agent swarm-supervisor`; supervisor TOML at `.codex/agents/swarm-supervisor.toml`; recipe → skill transform produces `.agents/skills/swarm/SKILL.md`; AGENTS.md gains `## Swarm — Lookup Pattern` and `## MCP cwd shim — Codex configuration` sections. |
+| Antigravity | `adapter.spawn()` launches a DETACHED `agy --new-project --dangerously-skip-permissions --print-timeout <bound> -p <boot prompt>` from `repoPath` (real 1.x flags — Phase 22b), logging to `.momentum/swarm-supervisor-<swarm>-w<wave>.log`; workflow at `.agents/workflows/swarm.md` auto-registers as `/swarm`; supervisor skill at `.agents/skills/swarm-supervisor/SKILL.md`; AGENTS.md gains `## Swarm — Lookup Pattern` section. |
+
+### Capability flips — outcome of G4 live VAL evidence
+
+Phase 18 G4 live evidence (`specs/phases/phase-18-swarm-parity/evidence/val-001-codex.txt` + `val-002-antigravity.txt`) concluded **neither flip lands**:
+
+- **Codex `parallelSubagents`** stays `false`. `codex features list` shows `enable_fanout: under development: false` at codex-cli 0.133.0. Flipping `parallelSubagents` requires `enable_fanout: stable: true` upstream.
+- **Antigravity `sessionStartHook`** stays `false` — but for a NEW reason (Phase 22b, VAL-002 resolved): a literal SessionStart event does not exist on Antigravity's five-event hook surface. The equivalent capability ships via the `momentum-session-context` PreInvocation hook (`ephemeralMessage` injection at `invocationNum 0`, ADR-0006); the flag flips once the injection round-trip is verified live (re-probe blocked by the intermittent agy 1.0.16 hook-runner hang, ENH-054). Evidence: `specs/phases/phase-22b-antigravity-2-adoption/evidence/fact-sheet.md` §5.
+
+The swarm subcommand row in the parity matrix flips to `shipped¹⁴` for
+both Codex + Antigravity — the surface is complete; only the two
+capability flags remain `false` pending the listed upstream / operator
+conditions.
+
+### Roadmap footnotes
+
+1. **Antigravity `slashCommands: false`** — chat-driven UI. Orchestration primitives reach Antigravity users via natural-language inference (the main agent picks the primitive from the user's prose) plus the `momentum` CLI floor that works on every adapter.
+2. **Codex `subagents` / `parallelSubagents`** — Codex declares a subagent surface, but parallel fan-out has not yet been validated by momentum smoke tests. The capability-routing helper treats Codex as sequential for `dispatch` until a future release proves parallel viability in CI. Subagent existence is `true`; parallel fan-out is `false`. Promote `parallelSubagents` to `true` once Codex parallel dispatch is exercised end-to-end.
+3. **Antigravity `sessionStartHook: false`** — a literal SessionStart event does not exist on Antigravity (five-event surface, Phase 22b/ADR-0006). The banner ships via the `momentum-session-context` PreInvocation hook (`ephemeralMessage` at `invocationNum 0`); AGENTS.md text keeps the fallback hint. Flag flips once the injection round-trip is verified live (ENH-054). `/continue` and `momentum continue` work regardless.
+4. **Codex `skills` / `browser` / `computerUse`** — declared `false` today; planned for a future Codex feature drop. When Codex ships those features, flip the boolean and remove the corresponding `roadmap` entry in the same PR.
+
+5. **opencode (Phase 22, LIVE-validated 2026-07-05)** — every boolean set from real-runtime evidence against opencode 1.17.13 with real model calls (free tier, zero credentials) — see `specs/phases/phase-22-opencode-adapter/evidence/val-opencode-live.txt`. `parallelSubagents: true` earned via overlapping task-tool timestamps; `skills: true` earned via a live skill-tool load of momentum-orient (**a momentum first — no other adapter has live-validated skills**); `sessionStartHook: true` — earned post-phase (fix/opencode-sessionstart-banner): the banner fired live in a served session once rewired onto the generic `event` bus (a named "session.created" hook key never fires on 1.17.x). Run-mode is deliberately excluded — the event handler hangs `opencode run` (upstream issue candidate) and a session-start banner is meaningless non-interactively.
+
+## ENH-023 and ENH-024 closed (Phase 11 G0)
+
+These two open backlog items tracked the type inconsistencies in the
+pre-Phase-11 matrix:
+
+- **ENH-023** — `subagents` was bool on Claude Code and Antigravity but
+  an explanatory string on Codex.
+- **ENH-024** — `skills` / `browser` / `computerUse` were `false` on
+  Claude Code but `'future'` sentinel strings on Codex; Antigravity did
+  not declare them at all.
+
+Phase 11 Group 0 unified all three adapters around uniform booleans and
+moved every caveat into the `roadmap` field. `tests/
+adapter-capabilities-declared.test.js` now enforces the uniform shape.
+
+## Read this if you are…
+
+- **…building an orchestration primitive** (Phase 11 and onward): read
+  the boolean cell; if `false`, degrade per the capability-routing
+  helper. Surface degraded-mode notes from the adapter's `roadmap`
+  block in the user-visible banner so they understand why.
+- **…adding a new adapter**: declare *every* row above on your
+  adapter's `capabilities` block as a boolean. Use the `roadmap` block
+  for forward-looking notes — never embed them in the capability
+  value. The audit test will fail otherwise.
+- **…closing a roadmap entry**: flip the corresponding boolean to
+  `true` (or remove if no longer relevant), delete the `roadmap`
+  entry, and update this matrix doc in the same PR.

package/core/adapter-parity-matrix.md

@@ -0,0 +1,170 @@
+# Adapter Parity Matrix (Phase 16 Rework)
+
+> Feature × adapter shipping status. Complement to
+> `core/adapter-capabilities.md` (which tracks PRIMITIVES like
+> `hooks: true`).
+>
+> This matrix answers: "is feature X actually shipped on adapter Y via
+> which native idiom, and if degraded, how?" Audited by
+> `tests/adapter-parity-matrix.test.js` — every cell must declare a
+> status. Silent gaps were the failure mode this audit prevents.
+>
+> Introduced in Phase 16 Rework (2026-06-11) — replaces the per-adapter
+> capability-only view with a per-feature native-idiom view.
+
+## Status legend
+
+| Status | Meaning |
+|---|---|
+| `shipped` | Feature wired via the platform-native idiom and verified |
+| `shipped-degraded` | Wired but runs in documented degraded mode. Cell's footnote explains |
+| `not-applicable` | Platform's runtime model doesn't surface this feature, by design |
+
+If you add a feature OR a new adapter, every (feature, adapter) cell
+must declare a status. The audit test fails on blank cells.
+
+## Conceptual categories
+
+Three categories drive the matrix (introduced Phase 16 Rework — see
+overview.md):
+
+| Category | What it is | Mental model |
+|---|---|---|
+| **Recipe** | Step-by-step instructions agent FOLLOWS | "Follow this procedure" |
+| **Persona / Skill** | Identity / capability agent LOADS to BECOME | "BE a security reviewer" |
+| **Parallel worker / Subagent** | Spawned sibling that works in parallel | "Go do this concurrently" |
+
+## Matrix
+
+### Recipes (phase + orchestration commands)
+
+| Recipe | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| `/brainstorm-idea` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/brainstorm-phase` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/start-project` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/start-phase` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/complete-phase` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/sync-docs` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/track` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/review` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/log` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/migrate` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/validate` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/ecosystem` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/initiative` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/session` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/systematic-debug` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/scout` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/dispatch` | shipped¹⁷ | shipped¹ | shipped-degraded⁴ | shipped³ |
+| `/handoff` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/continue` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/review-code` | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+| `/swarm` (Phase 17 + 17.5) | shipped¹⁷ | shipped¹ | shipped¹⁴ | shipped¹⁴ |
+| `/hotfix` (Phase 19) | shipped¹⁷ | shipped¹ | shipped² | shipped³ |
+
+### Personas (skills)
+
+| Skill | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| `momentum-orient` | shipped¹⁷ | not-applicable⁵ | shipped⁶ | shipped⁷ |
+| `momentum-reviewer-security` | shipped-as-subagent¹⁸ | not-applicable⁵ | shipped-as-subagent⁸ | shipped⁷ |
+| `momentum-reviewer-qa` | shipped-as-subagent¹⁸ | not-applicable⁵ | shipped-as-subagent⁸ | shipped⁷ |
+| `momentum-reviewer-architecture` | shipped-as-subagent¹⁸ | not-applicable⁵ | shipped-as-subagent⁸ | shipped⁷ |
+
+### Hooks
+
+| Hook | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| `PreToolUse` (brainstorm-gate) | shipped¹⁹ | shipped⁹ | shipped¹⁰ | shipped¹¹ |
+| `PostToolUse` (history reminder) | shipped¹⁹ | shipped⁹ | shipped¹⁰ | shipped¹¹ |
+| `SessionStart` (handoff banner) | shipped¹⁹ | shipped⁹ | shipped¹⁰ | shipped-as-preinvocation¹¹ |
+
+### Git-lifecycle hooks (Phase 19 — agent-agnostic)
+
+| Hook | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| `commit-msg` (Conventional Commits) | shipped¹⁵ | shipped¹⁵ | shipped¹⁵ | shipped¹⁵ |
+| `pre-push` (merge gate + verify-evidence) | shipped¹⁵ | shipped¹⁵ | shipped¹⁵ | shipped¹⁵ |
+
+### Overlay surfaces
+
+| Surface | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| Primary instruction file (CLAUDE.md / AGENTS.md) | shipped | shipped | shipped | shipped |
+| `commands` overlay | shipped¹⁷ | shipped | shipped | shipped-as-workflows¹² |
+| `agent-rules` overlay | not-applicable¹⁶ | not-applicable¹⁶ | not-applicable¹⁶ | not-applicable¹⁶ |
+| `scripts` overlay (hooks) | shipped | shipped | shipped | shipped |
+| `engines` overlay | shipped | shipped | shipped | shipped |
+| `workflows` overlay (Phase 16) | not-applicable⁵ | not-applicable⁵ | not-applicable⁵ | shipped¹³ |
+| `skills` overlay (Phase 16) | shipped¹⁷ | not-applicable⁵ | shipped⁶ | shipped⁷ |
+| `agents` overlay (Phase 16) | shipped¹⁸ | not-applicable⁵ | shipped⁸ | not-applicable⁵ |
+
+### Ecosystem features
+
+| Feature | opencode | Claude Code | Codex | Antigravity |
+|---|---|---|---|---|
+| `momentum init/upgrade` install | shipped | shipped | shipped | shipped |
+| Ecosystem manifest awareness (`ecosystem.json`) | shipped | shipped | shipped | shipped |
+| SessionStart ecosystem banner | shipped¹⁹ | shipped⁹ | shipped¹⁰ | shipped-as-preinvocation¹¹ |
+| Auto session log (PostToolUse) | shipped¹⁹ | shipped⁹ | shipped¹⁰ | shipped¹¹ |
+| Managed `CLAUDE.md` / `AGENTS.md` on `ecosystem init` | shipped | shipped | shipped | shipped |
+
+## Footnotes
+
+1. **Claude Code recipes** — installed as Markdown files at `.claude/commands/<name>.md`. User invokes `/<name>` and Claude Code loads the recipe content as the prompt. Native-idiom.
+
+2. **Codex recipes** — currently installed as Markdown files at `.codex/commands/<name>.md` with a lookup table in `AGENTS.md` ("Recipes Lookup Pattern"). User invokes by name in natural language ("run brainstorm-phase" or "/brainstorm-phase") and the agent finds the matching file. ENH-036 (in-progress) converts each recipe into a native Codex skill at `.agents/skills/<name>/SKILL.md` so they become first-class auto-discovered skills instead of instruction-following text. Custom prompts at `~/.codex/prompts/` are user-scoped only and do not satisfy the repo-shared requirement.
+
+3. **Antigravity recipes** — installed as workflow files at `.agent/workflows/<name>.md` (singular `.agent/` per official docs; gated by Group 4 live smoke — Google's own materials disagree). User types `/<name>` and `agy` auto-registers the workflow as a slash command. YAML frontmatter `--- description: ... ---` optional but recommended for auto-detection.
+
+4. **Codex `/dispatch`** — recipe text instructs natural-language parallel fan-out across multiple subagents (`agents.max_threads = 6` default). Marked `shipped-degraded` until VAL-001 live evidence confirms real-runtime parallel fan-out vs sequential degradation. Capability flip in Group 5.1.
+
+5. **`not-applicable` cells** — the platform's runtime model doesn't surface this overlay or feature. Examples: Claude Code has no per-project skill/agent/workflow file-discovery surface today; Antigravity uses skills (not separate agents/) for personas; Codex uses subagents (not workflows) for parallel work.
+
+6. **Codex skills + momentum-orient** — Codex skills live at `.agents/skills/<name>/SKILL.md` (shared convention with Antigravity; NOT `.codex/skills/`). Momentum installs `momentum-orient` here (Rule-1 orient discipline persona). Marked `shipped` based on vendor doc compliance; live discovery confirmed by VAL-001 in Group 4.
+
+7. **Antigravity skills + reviewers + orient** — installed at `.agents/skills/<name>/SKILL.md` as directories. Each contains SKILL.md with YAML frontmatter (`name`, `description`) + persona body. Loaded by `agy` when the matching skill name is invoked or auto-detected.
+
+8. **Codex reviewer subagents** — installed at `.codex/agents/<name>.toml` (TOML schema with `name`, `description`, `developer_instructions`, `sandbox_mode = "read-only"`). Spawned by natural-language request in the `/review-code` recipe. Codex auto-discovers TOML files in `.codex/agents/` per vendor docs.
+
+9. **Claude Code hooks** — wired via `.claude/settings.json` with matchers `Write|Edit|MultiEdit` for PreToolUse/PostToolUse and no matcher for SessionStart. Hook scripts in `scripts/`. Default-on for users with Claude Code installed.
+
+10. **Codex hooks** — wired via `.codex/hooks.json` with matchers `apply_patch|Bash` for PreToolUse/PostToolUse and no matcher for SessionStart. Per Codex docs (https://developers.openai.com/codex/hooks) the canonical `tool_name` for shell commands is `Bash` — earlier `shell` matcher was a bug (BUG-007, fixed 2026-06-13). Hooks are **enabled by default** in current Codex CLI (`hooks` is `stable: true` in `codex features list`); the first run prompts users to trust each hook via `/hooks`. The legacy `[features] hooks = true` opt-in remains as a fallback.
+
+11. **Antigravity hooks (Phase 22b, verified live)** — vendor named-group `.agents/hooks.json` over the real five events; every hook delegates through `scripts/antigravity-hook-adapter.sh` (ADR-0006), which translates camelCase payloads and emits decision JSON. PreToolUse/PostToolUse fire-verified against agy 1.0.16 (captured payloads under `specs/phases/phase-22b-antigravity-2-adoption/evidence/hook-captures/`). SessionStart does not exist — the handoff/ecosystem banner ships as a PreInvocation `ephemeralMessage` injection at `invocationNum 0` (hence `shipped-as-preinvocation`); AGENTS.md text keeps the fallback hint.
+
+12. **Antigravity `commands` overlay as workflows** — the cross-adapter `core/commands/*.md` content ships to `.agent/workflows/` on Antigravity (recipes become workflows). The destination is shared with the `workflows` overlay key; conflict detection prevents duplicates.
+
+13. **Antigravity `workflows` overlay (Phase 22b, path locked)** — adapter-specific workflows ship to `.agents/workflows/` (canonical root, ADR-0006). Live probe verified slash registration including planted path-matrix markers; agy accepts four root spellings and `.agents/` is the vendor-canonical one. Evidence: `specs/phases/phase-22b-antigravity-2-adoption/evidence/fact-sheet.md` §1/§3.
+
+14. **`/swarm` (Phase 17 v0.20.0 + Phase 17.5 v0.20.2 + Phase 18 v0.20.4)** — Phase 18 v0.20.4 brings full Codex + Antigravity parity to the swarm primitive. Implementation: a platform-agnostic `adapter.spawn(directive)` contract added in Phase 18 G0; Codex dispatch + supervisor TOML + MCP cwd shim documented in G1; Antigravity workflow + supervisor skill + AGENTS.md section in G2; multi-adapter synthetic e2e + Codex/Antigravity install fingerprints in G3. **Capability flips deferred** based on G4 live evidence: Codex `parallelSubagents` stays `false` (gated on `codex features list` showing `enable_fanout: stable: true` — currently `under development`); Antigravity `sessionStartHook` stays `false` (Phase 22b: the event does not exist — see footnote 11; VAL-002 RESOLVED with vendor-runtime evidence). Phase 22b also rewrote the Antigravity spawn onto the real CLI surface: detached `agy --new-project --dangerously-skip-permissions --print-timeout <bound> -p <boot prompt>` from `repoPath` with a per-repo supervisor log (live smoke: BOOT-OK — `specs/phases/phase-22b-antigravity-2-adoption/evidence/spawn-smoke.md`). Codex VAL-001 evidence unchanged at `specs/phases/phase-18-swarm-parity/evidence/val-001-codex.txt`.
+
+15. **Git-lifecycle hooks (Phase 19, FEAT-018/019)** — vendor-neutral, *agent-agnostic* git hooks installed identically for all three adapters: `bin/momentum.js::installGitHooks()` copies `core/git-hooks/*` to the target's `.githooks/` and runs `git config core.hooksPath .githooks` (warn-not-clobber if husky / a custom hooks path exists). `commit-msg` validates Conventional Commits; `pre-push` blocks direct pushes to protected branches without the single-use `.momentum/merge-approved` sentinel and blocks release-tag pushes lacking a non-empty `## Verification Evidence` (Rule 12). Escape hatch: `MOMENTUM_SKIP_HOOKS=1`. These are git hooks, not agent tool-event hooks — the mechanism is identical regardless of agent; the per-column cells exist only for matrix uniformity. Forge-neutral by design (no GitHub/GitLab API); see `core/lifecycle-contract.md`.
+
+16. **`agent-rules` overlay retired (Phase 23 / ADR-0004)** — the condensed `.agent/rules/project.md` file is no longer shipped by any adapter: no agent auto-loaded it, and the full detailed rules (Red Flags + anti-rationalization + Rule 13) now ride each adapter's auto-loaded primary instruction file, generated from the single canonical source at `core/instructions/rules-body.md`. `momentum upgrade` migrates existing installs (pristine → removed; customized → kept + deprecation warning). The `destinations['agent-rules']` contract key stays reserved for future per-adapter rule overlays.
+
+17. **opencode recipes + skills (Phase 22, LIVE-validated)** — recipes install at `.opencode/commands/<name>.md` where each file registers natively as `/<name>` ([opencode commands docs](https://opencode.ai/docs/commands/)); `runInstall` prepends `description` frontmatter for the command picker. Live evidence (G5): `opencode run "/validate"` executed the recipe end-to-end. Momentum skills install at `.opencode/skills/<name>/SKILL.md`; live evidence: the skill tool loaded `momentum-orient` in a real session, and a same-named duplicate on the `.agents/skills/` path (Codex/Antigravity convention) coexisted without error — the `skills` capability boolean is `true`, a momentum first. Full transcript: `specs/phases/phase-22-opencode-adapter/evidence/val-opencode-live.txt`.
+
+18. **opencode agents (Phase 22)** — reviewers + swarm supervisor at `.opencode/agents/<name>.md` (markdown agents, [opencode agents docs](https://opencode.ai/docs/agents/)). The three reviewers declare `mode: subagent` + `permission: edit: deny` (+ read-only bash allowlist) — true sandbox-level read-only, not just prompt-level. Spawn contract: `opencode run --dir <repoPath> --agent swarm-supervisor` (`--dir` pins cwd natively; no MCP shim needed, unlike Codex footnote 14).
+
+19. **opencode momentum plugin (Phase 22 + banner fix, LIVE-validated)** — one self-contained JS plugin at `.opencode/plugins/momentum.js` ([opencode plugins docs](https://opencode.ai/docs/plugins/)) wires the three enforcement hooks; reads the same `.momentum/` sentinels as the other adapters' shell hooks. Live evidence (G5 `val-opencode-live.txt` + `specs/adhoc/fix-opencode-sessionstart-banner/record.md`): the gate blocked a real specs/ edit during `brainstorm-active`; the history reminder stamped after a real write (callID correlation — `tool.execute.after` carries no args); the handoff banner fired in a live served session after being rewired onto the generic `event` bus (a named "session.created" hook key never fires on 1.17.x). Run-mode exclusion by design: the event handler's presence hangs `opencode run` (1.17.13, upstream issue candidate) and a session-start banner is meaningless non-interactively. Remaining degraded cells: ecosystem SessionStart context banner + auto session log not yet wired through the plugin (ENH-058; use `/session` or the `momentum` CLI).
+
+## Read this if you are…
+
+- **…asking "is feature X on adapter Y today?"** — find the row, read the cell. Footnote explains how it's shipped (or why not).
+- **…adding a new feature** — add a row; declare every cell. The audit test fails otherwise.
+- **…adding a new adapter** — add a column; declare every cell.
+- **…upgrading a degraded cell to `shipped`** — confirm via live test, flip the cell, drop the footnote in the same PR. Also update `core/adapter-capabilities.md` if the underlying capability boolean changed.
+
+## How the audit test parses this matrix
+
+`tests/adapter-parity-matrix.test.js` reads this file and asserts:
+
+1. Every row's cell count matches the column header count.
+2. Every cell declares a known status: `shipped` / `shipped-degraded` / `not-applicable` / `shipped-as-<other-category>` / `shipped-gated`, optionally with a parenthetical detail and a footnote marker.
+3. Cells with `shipped-degraded`, `not-applicable`, `shipped-gated`, or `shipped-as-<other>` reference a footnote.
+
+Rows in non-table prose are ignored. Tables under any `###` heading
+in this file are audited if their header includes at least one adapter
+display name.

package/core/commands/brainstorm-idea.md

@@ -0,0 +1,98 @@
+Explore any idea through structured dialogue before committing to anything.
+
+Use this to think through a concept, technical direction, product decision, or architecture question. **Nothing gets written to disk.** The output is a clear, structured summary you can act on.
+
+When you're ready to turn the result into a project, run `/start-project`. To turn a decision into an ADR, run `/log` with `--decision`.
+
+## When to use
+
+- You have a vague idea and want to think it through
+- You're weighing technical options and need to reason carefully
+- You want to explore a product direction before committing to building it
+- You're considering a significant architecture or process change
+
+---
+
+## Steps
+
+0. **Enter the brainstorm gate**:
+   ```bash
+   mkdir -p .momentum && touch .momentum/brainstorm-active
+   ```
+   While this sentinel exists, the PreToolUse hook (`core/scripts/brainstorm-gate.sh`, wired by Claude Code + Codex + Antigravity) blocks any write-class tool call to `specs/`. This command should not write to disk at all — the sentinel guards against accidental scratch-file leakage (e.g., a stray `specs/decisions/draft.md`).
+
+1. Ask one question at a time to understand the idea:
+   - What is the core problem or opportunity?
+   - Who is this for? (user, system, team)
+   - What are the 2–3 options or directions worth exploring?
+   - What constraints matter most? (time, cost, complexity, reversibility)
+   - What does success look like?
+
+2. After understanding the idea, reflect back a structured summary **in the chat** (no file):
+
+   ```
+   ## Idea Summary
+
+   **Problem**: ...
+   **Options explored**: ...
+   **Key constraints**: ...
+   **Recommendation**: ...
+   **Open questions**: ...
+   ```
+
+3. Ask: "Does this capture it? Anything to refine?"
+
+4. Iterate until the idea is clear.
+
+5. **Exit the brainstorm gate** before any follow-up command:
+   ```bash
+   rm .momentum/brainstorm-active
+   ```
+
+6. Close with one of:
+   - "Ready to build this? Run `/start-project` to scaffold it as a project."
+   - "Want to explore further before committing? Ask away."
+   - "This is a decision, not a project — want to log it as an ADR with `/log --decision`?"
+
+---
+
+## Brainstorm Gate Contract
+
+This command runs in two phases: **brainstorm** (conversational, no disk writes) and **commit** (writes files to disk on explicit approval).
+
+### Sentinel-driven enforcement
+
+A file `.momentum/brainstorm-active` exists for the lifetime of the brainstorm phase. While it exists, the `brainstorm-gate.sh` PreToolUse hook (shared across Claude Code, Codex, and Antigravity) blocks any write-class tool call whose target lives under `specs/`. The hook is the safety net; the discipline below is the primary contract.
+
+For `/brainstorm-idea` specifically, there is no "commit phase" — this command never writes phase or spec files. The gate exists to prevent accidental scratch files from appearing under `specs/` during open-ended exploration. The sentinel is removed when the user picks a direction (or exits the conversation) so the follow-up command (`/start-project`, `/log`, etc.) starts clean.
+
+### Sequence
+
+1. **Enter brainstorm** — `mkdir -p .momentum && touch .momentum/brainstorm-active`
+2. **Draft in conversation only** — the idea summary lives in chat, not a file. NEVER call `Write`/`Edit`/`MultiEdit` on `specs/` paths during this phase.
+3. **User picks a direction** — the next step is a different command, not a file write.
+4. **Exit brainstorm before that command** — `rm .momentum/brainstorm-active`.
+
+### Red flags — STOP and stay in conversation
+
+| If you find yourself thinking… | …STOP and stay in conversation |
+|---|---|
+| "I'll save the idea summary to a file so we don't lose it" | The user is the one who decides if it's worth saving. Keep it in chat; let them pick the destination (`/log --decision`, `/start-project`, etc.). |
+| "I'll create `specs/ideas/foo.md` as a scratch file" | This command has no scratch files. The hook will block. |
+| "The brainstorm session is going long; I'll dump notes to disk for safekeeping" | Long conversations are normal; chat is durable. |
+
+### Anti-rationalization counters
+
+- "It's just a note, not a real spec" — the hook can't tell a note from a spec; the discipline is consistent across all three brainstorm commands.
+- "The user might forget the conclusion" — summarize in chat; they can copy if they want.
+- "Other commands need this content" — they'll get it from the conversation context.
+
+---
+
+## Key Principles
+
+- One question at a time — don't overwhelm
+- No files written during brainstorming — this is thinking, not building
+- The summary is the deliverable — concise, clear, actionable
+- Stay generic — works for software, process, product, or architecture ideas
+- **Brainstorm Gate**: see the contract above. No writes during the session.