@limina-labs/momentum 0.30.2

package/adapters/claude-code/commands/dispatch.md

@@ -0,0 +1,154 @@
+Parallel multi-project fan-out + synthesis. One sub-agent per listed project, each tailored to the user's intent: audit (read-only) or fix (writes allowed, on a feature branch). All results synthesised into a single answer. Writes one dispatch-NNN.md artifact and one session log line.
+
+> **Three doors, one library.** This is the slash-command door for Claude Code. The CLI door is `momentum dispatch <r1> <r2> ... --prompt "<text>"` and the natural-language inference door fires when the user describes a multi-repo audit / alignment task. All three doors call `core/orchestration/dispatch.js` so the output shape is identical.
+
+## When to use
+
+- "What breaks if I rename X across all repos?" — multi-project audit (sub-agents stay read-only by intent).
+- "Get me the current state of A AND B so I can align a change." — pre-coordination context fetch (read-only by intent).
+- "Where does Y come from across the stack?" — cross-cutting investigation (read-only by intent).
+- "Fix the same typo in all three repos." — one-shot multi-project change (sub-agents write on feature branches; you review per repo).
+- "Bump the lint config to v2 across the stack." — repeatable code-mod (writes allowed).
+
+Do NOT use `/dispatch` for **sustained multi-step features that need wave ordering, contracts, or a persistent saga** — use [`/swarm`](/swarm/) instead. Do NOT use it when you want to TRANSFER control rather than fan it out — use `/handoff`. Do NOT use it for single-project tasks — use `/scout` or just work in that project directly.
+
+## Inference guidance (read this in non-slash contexts too)
+
+Treat ANY of these as a dispatch invocation even without an explicit `/dispatch`:
+
+- "Audit X across repos A, B, C."
+- "What's the state of A, B, and C right now?"
+- "Find every place that does X across the ecosystem."
+
+When inferring, narrate it: `▸ inferred: dispatch (multi-repo audit). Use /dispatch next time for predictable behavior.`
+
+Do NOT use dispatch for single-repo questions — use `/scout`. Do NOT use dispatch when you want to TRANSFER control rather than just READ — use `/handoff`.
+
+## Usage
+
+```
+/dispatch <repo1> <repo2> [repo3 ...] "<user intent>"
+```
+
+Repos are member ids from `ecosystem.json` (or relative/absolute paths).
+
+## Steps
+
+### Step 1 — Identify the targets + intent
+
+Resolve each repo arg to an absolute path via the ecosystem manifest. Capture the user's high-level intent (the rest of the slash-command line).
+
+### Step 2 — Capability-route the dispatch mode
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const adapter = orchestration.capabilityRouting.loadAdapter('<momentum-root>', 'claude-code');
+const { mode, notes } = orchestration.capabilityRouting.chooseMode(adapter, 'dispatch');
+```
+
+Claude Code declares `parallelSubagents: true` — `mode='parallel'`, no notes. If you're on an adapter where `mode='sequential'`, narrate the note up front (`▸ <degraded-mode note>`) so the user knows what they're getting.
+
+### Step 3 — Fan out sub-agents (parallel on Claude Code)
+
+For EACH target repo, in a SINGLE message use the Task tool to spawn a sub-agent with:
+
+- Sub-agent system prompt: "You are a DISPATCH SUB-AGENT for momentum's quick-verb layer. You are working in `<repo>`. The user intent below is authoritative — if it asks to audit / investigate / report, return a structured JSON result without writing files. If it asks to fix / refactor / migrate, you may write code, but commit on a feature branch per Rule 6 (Git Lifecycle) and surface the branch name in your result so the originating session can review. When in doubt about whether to write, prefer reading and surface the proposed change in `findings` instead."
+- Sub-agent task prompt: user intent + the specific repo.
+- If the originating session is in read-only mode (the user passed `--read-only` to the CLI floor, or the recipe was invoked with the `--read-only` flag), prepend an explicit "READ-ONLY: do not write any files" line to the sub-agent system prompt regardless of intent.
+- Expected return shape (sub-agent renders as a single JSON block):
+
+```json
+{
+  "repo": "<absolute path>",
+  "summary": "...one-paragraph answer focused on this repo...",
+  "filesRead": ["..."],
+  "filesWritten": ["..."],
+  "branch": "feat/short-desc",
+  "findings": [
+    { "kind": "discovery", "title": "...", "detail": "...", "recommendedBacklogPriority": "P2", "recommendedBacklogType": "tech-debt" }
+  ]
+}
+```
+
+`filesWritten` + `branch` are present only when the sub-agent actually wrote (user intent was a fix/refactor/migrate). For pure audits, omit them. `findings` apply Rule 3 thresholds.
+
+Sub-agents run concurrently because they are dispatched in the same message — Claude Code's Task tool runs each in its own context.
+
+### Step 4 — Wait for all sub-agents, capture failures
+
+If any sub-agent fails or returns no result, capture the failure with `{ repo, error: { message } }` and CONTINUE. Never abort the whole dispatch on a single sub-agent failure — the synthesis still proceeds with partial results.
+
+### Step 5 — Synthesise
+
+Read the per-repo results IN THIS AGENT'S CONTEXT and produce a synthesis paragraph that DIRECTLY ANSWERS the user's intent. Mention any failures explicitly in the synthesis (don't let them disappear).
+
+### Step 6 — Record the run
+
+```js
+orchestration.dispatch.record({
+  repos: [/* absolute paths */],
+  userIntent: '<user intent>',
+  mode,
+  modeNotes: notes,
+  perRepoResults: [/* per-repo entries */],
+  failures: [/* entries with .error */],
+  synthesis: '<your synthesised paragraph>',
+  originatingRepo: '<this repo absolute path>',
+  ecosystem: { rootPath: '<...>', memberId: '<...>' },
+  duration: <ms>,
+});
+```
+
+This writes `.momentum/runs/dispatch-NNN.md` (synthesis + collapsible per-repo blocks + failure manifest) and appends one line to the ecosystem session log.
+
+### Step 7 — Hand findings to the tracking contract
+
+For each finding from each per-repo result, call:
+
+```js
+orchestration.tracking.proposeDiscovery({
+  primitive: 'dispatch',
+  finding,
+  targetRepo: '<repo where the finding was identified>',
+});
+```
+
+Synthesis itself gets a `[NOTE]` in the ORIGINATING repo's active phase history when it answers a meaningful coordination question; pass through:
+
+```js
+orchestration.tracking.proposeHistoryNote({
+  primitive: 'dispatch',
+  originatingRepo,
+  message: '<one-line summary of what dispatch surfaced>',
+  runArtifactRef: '<.momentum/runs/dispatch-NNN.md>',
+});
+```
+
+### Step 8 — Render the result
+
+Output to the user:
+
+```
+▸ Synthesis
+<synthesis paragraph>
+
+▸ Per-repo (expand to see detail)
+  ▼ <repo1>: <one-line>
+  ▼ <repo2>: <one-line>
+  ...
+
+→ logged to sessions/<today>.md
+→ trace at .momentum/runs/dispatch-NNN.md
+```
+
+## Tracking contract
+
+- **Auto every time:** session log line + dispatch-NNN.md artifact.
+- **Auto only when meaningful:** per-repo `[DISCOVERY]` in each scouted repo's active phase history; `[NOTE]` in the originating repo's active phase history when the synthesis records a meaningful cross-repo state.
+- **Never:** `[DISPATCH]` entry types or `backlog.md` entries without explicit user confirmation.
+
+## Errors
+
+- A repo arg doesn't resolve → emit a warning, skip it, continue with the rest.
+- All repo args fail to resolve → abort with error.
+- A sub-agent throws → captured in `failures[]`, synthesis still runs.

package/adapters/claude-code/commands/handoff.md

@@ -0,0 +1,85 @@
+Cross-session control transfer with a structured context block. Writes `<toRepo>/.momentum/inbox/handoff-NNN.md` so a fresh agent session in that repo can pick up where you left off, and emits a `[DECISION]` in this repo's active phase history.
+
+> **Three doors, one library.** This is the slash-command door for Claude Code. The CLI door is `momentum handoff <repo> [flags]` and the natural-language inference door fires when the user describes a control-transfer task ("now continue in X"). All three doors call `core/orchestration/handoff.js`.
+
+## When to use
+
+- You finished work in repo A and want the next session in repo B to continue with full context.
+- You hit a stopping point that requires switching repos and want decisions preserved.
+- DO NOT use handoff for read-only context fetches — use `/scout` for that. DO NOT use handoff for multi-repo audits — use `/dispatch`.
+
+## Inference guidance (read this in non-slash contexts too)
+
+Treat ANY of these as a handoff invocation:
+
+- "Now switch to <repo> and continue."
+- "I'm done here — pick up in <other repo>."
+- "Hand off the rest to <repo>."
+
+When inferring, narrate it: `▸ inferred: handoff (control transfer). Use /handoff next time for predictable behavior.`
+
+## Usage
+
+```
+/handoff <repo> [optional one-line summary]
+```
+
+`<repo>` is a member id from `ecosystem.json` (or a path). The slash command will infer the context block from this session — recent edits, key decisions, files touched, suggested verification commands, any open questions.
+
+## Steps
+
+### Step 1 — Identify the target repo + summary
+
+Resolve `<repo>` via `ecosystem.json`. If the user provided a summary line, use it. Otherwise, generate a one-line summary that captures what work remains to be picked up.
+
+### Step 2 — Collect the context block
+
+Pull together (inferred from THIS session's history):
+
+- `decisions[]` — ADRs created, technology choices made, or other significant choices.
+- `filesTouched[]` — the files edited in this session.
+- `verificationCommands[]` — what to run to confirm the picked-up state (tests, lints, smoke commands).
+- `openQuestions[]` — anything the receiving agent needs to resolve.
+
+Keep it tight — the receiving agent will read this first.
+
+### Step 3 — Write the handoff
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const block = await orchestration.handoff.handoff({
+  fromRepo: '<this repo absolute path>',
+  toRepo: '<target repo absolute path>',
+  summary: '<one-line>',
+  decisions: [...],
+  filesTouched: [...],
+  verificationCommands: [...],
+  openQuestions: [...],
+  ecosystem: { rootPath: '<ecosystem root>', memberId: '<this repo member id>' },
+});
+```
+
+This writes `<toRepo>/.momentum/inbox/handoff-NNN.md`, appends one line to the ecosystem session log, AND emits a `[DECISION]` in this repo's active phase `history.md` (handoff IS a cross-repo decision).
+
+### Step 4 — Tell the user
+
+Output:
+
+```
+▸ handoff written: <toRepo>/.momentum/inbox/handoff-NNN.md
+▸ logged [DECISION] in <originating phase>/history.md
+
+Next: open a fresh session in <toRepo>. The SessionStart hook will detect
+the handoff and prompt "Read now? [y/skip]". Or run /continue (or
+`momentum continue`) explicitly.
+```
+
+## Tracking contract
+
+- **Auto every time:** session log line + `.momentum/inbox/handoff-NNN.md` in receiving repo + `[DECISION]` entry in originating active phase history.
+- **Never:** `[HANDOFF]` entry types. Use existing `[DECISION]`.
+
+## Errors
+
+- Target repo doesn't exist → report and stop.
+- Target repo is the same as the originating repo → report (handoff to self is meaningless) and stop.

package/adapters/claude-code/commands/review-code.md

@@ -0,0 +1,194 @@
+Run a multi-perspective code review of the pending changes on the current branch.
+
+> **This command is Claude-Code-specific.** It uses the Task tool to dispatch
+> role-based subagents in parallel. Equivalent functionality for other agents
+> would live in their respective `adapters/<agent>/commands/` overlay (e.g.,
+> Cursor would ship a prompt-based variant). Do not generalize this into
+> `core/commands/` — generalization would lose the parallel-subagent value.
+
+## When to use
+
+- Before `/sync-docs` and `/complete-phase` at the end of a phase
+- After a non-trivial commit on a feature branch, before opening a PR
+- Whenever you want a fresh, independent read on what was just built
+
+This command does NOT modify code. It produces a consolidated review and asks
+you which findings to act on.
+
+## Steps
+
+### Step 1 — Determine review scope
+
+Default scope: the diff between the current branch and `main`. Run:
+```bash
+git diff main...HEAD --stat
+git diff main...HEAD
+```
+
+If the user passed an argument, honor it:
+- `staged` → `git diff --cached`
+- `working` → `git diff` (unstaged changes)
+- `<commit-sha>` → `git diff <commit-sha>...HEAD`
+- `<file-path>` → restrict review to that path within the default scope
+
+If no diff exists, report "no changes to review" and stop.
+
+### Step 2 — Read the rules of the project
+
+Before dispatching reviewers, read:
+- `CLAUDE.md` (rules and constraints — the complete rulebook)
+- `specs/status.md` (current phase context)
+
+This ensures every reviewer scores the diff against THIS project's rules,
+not generic best practices alone.
+
+### Step 3 — Dispatch reviewers in parallel
+
+Use the Task tool to spawn three subagents in **a single message with three
+parallel tool calls** (do NOT serialize). Each subagent gets the same diff
+and the same rules context, but a different role.
+
+#### Reviewer A — Security (OWASP / STRIDE)
+
+Prompt template:
+> You are reviewing a code diff for **security only**. Use the OWASP Top 10
+> and STRIDE threat categories as your lens.
+>
+> Diff:
+> ```
+> <paste the diff from Step 1>
+> ```
+>
+> Project rules excerpt:
+> ```
+> <paste the relevant constraints from CLAUDE.md — especially "No secrets in code">
+> ```
+>
+> Return findings in this exact format:
+>
+> ```
+> ## Security review
+>
+> ### Critical
+> - [finding] (file:line) — [why it's critical]
+>
+> ### Important
+> - [finding] (file:line) — [explanation]
+>
+> ### Minor
+> - [finding] (file:line) — [explanation]
+> ```
+>
+> If no findings at a severity level, write "(none)". Do NOT speculate beyond
+> what the diff shows. Do NOT propose code fixes — only flag the issue.
+
+#### Reviewer B — QA (test coverage, edge cases, regressions)
+
+Prompt template:
+> You are reviewing a code diff for **test coverage and edge cases only**.
+>
+> Diff:
+> ```
+> <paste the diff from Step 1>
+> ```
+>
+> Project rules excerpt:
+> ```
+> <paste Rule 12 (Verify Before Claim) from CLAUDE.md>
+> ```
+>
+> For each meaningful behavior change in the diff, ask:
+> - Is there a test that exercises it?
+> - What edge cases are uncovered (empty input, large input, concurrent
+>   access, error paths)?
+> - Could this break an existing test or production path?
+>
+> Return findings in the same Critical/Important/Minor format as the security
+> reviewer. "(none)" when applicable.
+
+#### Reviewer C — Architecture (rule compliance, pattern consistency)
+
+Prompt template:
+> You are reviewing a code diff for **architectural fit and rule compliance**.
+>
+> Diff:
+> ```
+> <paste the diff from Step 1>
+> ```
+>
+> Full rules:
+> ```
+> <paste CLAUDE.md (rules section)>
+> ```
+>
+> For each change, ask:
+> - Does it violate any of the 12 autonomous rules?
+> - Does it match the patterns established elsewhere in the codebase?
+>   (Check 2-3 nearby files for convention.)
+> - Does it create a hidden coupling, a leaky abstraction, or an
+>   adapter/contract violation?
+> - Is it documented where rules say it should be (history.md, ADR, etc.)?
+>
+> Return findings in the Critical/Important/Minor format. "(none)" when
+> applicable.
+
+### Step 4 — Consolidate
+
+Once all three subagents return:
+
+1. Merge findings into a single report ordered:
+   ```
+   ## Code Review
+
+   ### Critical (N)
+   - [security] finding (file:line)
+   - [arch] finding (file:line)
+
+   ### Important (N)
+   - [qa] finding (file:line)
+   - [security] finding (file:line)
+
+   ### Minor (N)
+   - [arch] finding (file:line)
+   ```
+2. Tag each finding with its reviewer (`[security]`, `[qa]`, `[arch]`).
+3. De-duplicate findings that multiple reviewers raised — combine into one
+   line and tag with all reviewers (`[security][arch]`).
+4. If a finding is at Critical and conflicts with a Minor finding from a
+   different reviewer, surface BOTH and note the disagreement.
+
+### Step 5 — Present to user, ask what to act on
+
+Show the consolidated report. Then ask:
+> "Which findings should I act on now? Options:
+>   1. All Critical
+>   2. All Critical + Important
+>   3. Specific items (list IDs)
+>   4. None — log all findings to backlog only
+>   5. Cancel"
+
+For findings the user wants to act on now: implement them as separate commits
+on the current branch (each commit ≤ one finding).
+
+For findings the user wants to defer: add each as a backlog item via the
+`/track` flow with appropriate priority (Critical → P0/P1, Important → P1/P2,
+Minor → P2/P3).
+
+### Step 6 — Honor Rule 12 on any fixes
+
+If you implement any fix in Step 5, run the relevant verification (test,
+lint, typecheck) BEFORE marking it done — per Rule 12 (Verify Before Claim).
+
+## Constraints
+
+- Subagents are **read-only**: they MUST NOT edit files, run code-modifying
+  commands, or commit. They return findings as text only.
+- Dispatch all three subagents in a **single message with parallel tool
+  calls** — do not sequence them.
+- The review NEVER auto-fixes findings. The user always decides what to act
+  on (Step 5).
+- Findings tied to specific lines should include `file:line` so the user can
+  navigate quickly.
+- If a reviewer's output is malformed (missing severity headers), re-dispatch
+  that single reviewer with a stricter format reminder. Do not silently
+  reformat — that hides reviewer mistakes.

package/adapters/claude-code/commands/scout.md

@@ -0,0 +1,119 @@
+Read-only context fetch from one ecosystem member repo. Returns a structured summary, writes a scout-NNN.md run artifact, and appends one line to the ecosystem session log.
+
+> **Three doors, one library.** This is the slash-command door for Claude Code. The CLI door is `momentum scout <repo> "<prompt>"` and the natural-language inference door fires when the user describes a single-repo, read-only context-fetch task without naming a primitive (see "Inference guidance" below). All three doors call `core/orchestration/scout.js` so the output shape is identical.
+
+## When to use
+
+- You're about to make a change in this repo but you need to know the current state of a related repo first (auth shape, API contract, schema, recent decisions).
+- A user asks "what's the situation in `<repo>`?" — that's scout.
+- You want a durable record of a context-fetch you just did, not just a chat message.
+
+## Inference guidance (read this in non-slash contexts too)
+
+Treat ANY of these as a scout invocation even without an explicit `/scout`:
+
+- "What's the current X in repo Y?"
+- "Before I make the change here, get me the latest state from `<sibling repo>`."
+- "Read repo Y and tell me about its current Z."
+
+When inferring, narrate it: `▸ inferred: scout (single repo, read-only). Use /scout next time for predictable behavior.`
+
+Do NOT use scout for multi-repo questions — use `/dispatch`. Do NOT use scout when you're about to write into the target repo — use `/handoff`.
+
+## Usage
+
+```
+/scout <repo> "<prompt>"
+```
+
+`<repo>` is either a member id from `ecosystem.json` or a relative/absolute path. `<prompt>` is the user's question.
+
+## Steps
+
+### Step 1 — Identify the target repo + prompt
+
+Parse the user's invocation. If they said `/scout sapience auth endpoint shape` then:
+
+- repo = `sapience`
+- prompt = `auth endpoint shape`
+
+Resolve `sapience` to an absolute path via the ecosystem manifest (`ecosystem.json` → `members[]`).
+
+### Step 2 — Spawn a read-only sub-agent
+
+Use the Task tool with a prompt that:
+
+1. Tells the sub-agent: "you are a SCOUT for momentum's orchestration layer."
+2. Provides the target repo path and the user's prompt.
+3. Instructs the sub-agent to: read `specs/status.md`, recent files under `specs/architecture/` and `specs/phases/<active>/history.md`, and any keyword-matching files. NO writes.
+4. Asks the sub-agent to return a structured JSON object:
+   ```json
+   {
+     "summary": "...one-paragraph answer to the prompt...",
+     "filesRead": ["specs/status.md", "..."],
+     "findings": [
+       { "kind": "discovery", "title": "...", "detail": "...", "recommendedBacklogPriority": "P2" }
+     ]
+   }
+   ```
+   `findings` should ONLY include real bugs, real tech debt, real enhancements — applying the same threshold as Rule 3 (Auto-Track Discoveries). DO NOT include orchestration metadata or anything that doesn't deserve a backlog entry.
+
+### Step 3 — Record the run
+
+Once the sub-agent returns:
+
+```js
+const orchestration = require('<momentum-root>/core/orchestration');
+const result = orchestration.scout.record({
+  repo: '<resolved repo path>',
+  prompt: '<user prompt>',
+  summary: '<sub-agent summary>',
+  filesRead: [/* ... */],
+  findings: [/* ... */],
+  ecosystem: { rootPath: '<ecosystem root>', memberId: '<this repo member id>' },
+  duration: <ms>,
+});
+```
+
+This writes `.momentum/runs/scout-NNN.md` in THIS repo (originating) and appends one line to the ecosystem session log. The library handles run-id allocation.
+
+### Step 4 — Hand findings to the tracking contract
+
+For each finding the sub-agent returned, call:
+
+```js
+orchestration.tracking.proposeDiscovery({
+  primitive: 'scout',
+  finding,
+  targetRepo: '<scouted repo path>',
+});
+```
+
+The helper applies Rule 3 criteria. If `shouldWrite=true`, it appends a `[DISCOVERY]` entry to the scouted repo's active phase history. If `shouldWrite=false`, only the session log line above stays — no curated-layer write.
+
+### Step 5 — Narrate the result
+
+Output the summary, then the artifact path:
+
+```
+▸ scout <repo>: <prompt>
+  ▸ reading specs/status.md
+  ▸ reading specs/architecture/...
+  ▸ found: <finding summary>   (one line per finding written by tracking)
+
+<summary text>
+
+→ logged to sessions/<today>.md
+→ trace at <artifact path>
+```
+
+## Tracking contract
+
+- **Auto every time:** ecosystem session log line + scout-NNN.md artifact in THIS repo.
+- **Auto only when meaningful:** `[DISCOVERY]` entry in the SCOUTED repo's active phase history, when the agent judges a finding worth backlog tracking (Rule 3 thresholds). NEVER write `[SCOUT]` entries — use existing entry types.
+- **Never:** `backlog.md` entries without explicit user confirmation. Tracking helper proposes; user OKs.
+
+## Errors
+
+- Repo not found in ecosystem manifest → report and stop.
+- Repo not in any ecosystem (this repo is standalone) → fall back to running scout in-process via CLI; suggest the user run `momentum scout <path> "<prompt>"` directly.