Files
msd-core/docs/adr/15-autonomous-cross-ai-convergence.md
Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
2026-10-06 01:47:40 +02:00

192 lines
11 KiB
Markdown

# Cross-AI Plan Convergence via Existing Orchestration Commands
- **Status:** Accepted — ratified 2026-07-17 (originally Proposed 2026-05-24); see "Ratification" below
- **Date:** 2026-05-24
- **Issue:** #15
Current orchestration commands (`/msd-autonomous` and `/msd-progress --next --auto`) route planning through `msd-plan-phase` and only use local/Claude subagent review paths. The cross-AI convergence path already exists (`/msd-plan-review-convergence`, `/msd-review`, `review.default_reviewers`, `review.models.*`) but is not wired into these orchestrators. This creates a gap: users can configure cross-AI reviewers yet still get local-only planning in autonomous/auto-chain execution.
## Ratification (2026-07-17): Proposed → Accepted
Ratified by explicit maintainer directive after the shipped implementation was independently re-verified; the Status field had read "Proposed" for roughly 8 weeks after the underlying decision had already landed.
**Evidence the decision shipped:**
- Primary, parity, and alias surfaces are present verbatim: `commands/msd/progress.md:4,28` (`--next --converge`, `--cross-ai` alias, reviewer flags, `--max-cycles N`) and `commands/msd/autonomous.md:4,40-41` (`--converge`, `--cross-ai` alias).
- The `plan_strategy=local|converge` seam is implemented in `msd-core/workflows/next.md:260-313` (`PLAN_STRATEGY` parsing, `CONVERGENCE_ARGS` build, feature-gate check, Route-3 override) and mirrored in `msd-core/workflows/autonomous.md:19-90,378-419`.
- Fail-fast-on-disabled-gate behavior matches the ADR's Failure Policy exactly: `next.md:279-292` and the equivalent block in `autonomous.md` check `workflow.plan_review_convergence` via `config-get` and abort with the exact `msd config-set workflow.plan_review_convergence true` instruction — no silent downgrade to `local`.
- The config contract is shipped: `msd-core/bin/shared/config-schema.manifest.json:36` (`workflow.plan_review_convergence`), `:54` (`review.default_reviewers`), `:123,141` (`review.models.*`); documented identically in `docs/CONFIGURATION.md:225,316` and `docs/COMMANDS.md:620-622,850-852`.
- Dedicated regression tests exist: `tests/adr-15-progress-converge.test.cjs` (179 lines, describe block titled `'ADR-15: /msd:progress --next --auto --converge (#1190)'`) and `tests/autonomous-converge.test.cjs` (225 lines, covering the parity surface under `'autonomous --converge flag (#711)'` — this file does not itself reference ADR-15 by name).
- Landing commits: `092340d18` (`fix(#711): wire autonomous convergence flag`, 2026-06-10, parity surface) and `0b3a2e5f9` (`feat(#1190): wire --converge primary surface into /msd:progress --next (ADR-15) (#1237)`, 2026-06-14) — the latter's commit body states "ADR-15 designates /msd-progress --next --auto --converge as the PRIMARY plan-convergence surface" and confirms the wiring gap the ADR called out is closed.
- No later ADR references or supersedes ADR-15: `grep -rl 'ADR-15' docs/adr/*.md` returns only `docs/adr/README.md`'s own index row (line 158), which still lists it as "Proposed" — the stale bookkeeping entry this ratification corrects.
**Governance state:** Issue #15 CLOSED — stateReason COMPLETED (closed 2026-05-25T03:12:26Z). Follow-up test-coverage issue #1190 ("test(coverage): fill Proposed-ADR test gaps") also CLOSED — stateReason COMPLETED (closed 2026-06-14T19:52:24Z).
## Decision
Do not add a new command. Add convergence as an orchestration policy in existing commands, with `/msd-progress` as the primary operator surface.
1. Add a shared **plan strategy seam** for orchestration workflows:
- `plan_strategy=local|converge`
- `local` maps to `msd-plan-phase`
- `converge` maps to `msd-plan-review-convergence`
2. Expose the strategy via existing entry points:
- `/msd-progress --next --auto --converge` (primary)
- `/msd-autonomous --converge` (parity path for users who prefer autonomous directly)
- keep `--cross-ai` as a compatibility alias for `--converge`
3. Reuse existing reviewer selection semantics from `/msd-review` and `/msd-plan-review-convergence`:
- explicit reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`)
- `--all`
- `review.default_reviewers` and `review.models.*` config
4. Add pass-through flags (no new command surface):
- `--converge` (primary)
- `--cross-ai` (alias)
- reviewer selector flags listed above
- `--max-cycles N` (forwarded per phase)
5. Keep convergence behind existing feature gate:
- if `workflow.plan_review_convergence=false` and `--converge` (or alias) is requested, fail fast with actionable enable instructions.
6. Keep post-execution review behavior unchanged in this slice (`msd-code-review` and `msd-ui-review` stay as-is). Cross-AI code-review fanout is deferred.
7. Define convergence eligibility and allowed AIs via config (no new command):
- enable gate: `workflow.plan_review_convergence=true`
- allowed reviewer set: `review.default_reviewers` (for no-flag converge runs)
- per-reviewer model selection: `review.models.*`
## Interface Contract
### Existing CLI Surfaces (No New Command)
- `/msd-progress --next --auto [--converge|--cross-ai] [reviewer flags] [--max-cycles N]`
- `/msd-autonomous [existing flags] [--converge|--cross-ai] [reviewer flags] [--max-cycles N]`
### Planning Step Routing
- `plan_strategy=local`:
- orchestrator step uses `msd-plan-phase` (current behavior).
- `plan_strategy=converge`:
- orchestrator step uses `msd-plan-review-convergence`.
- convergence workflow remains owner of HIGH counting (`CYCLE_SUMMARY`), stall detection, and escalation.
### Failure Policy
- If `--converge` (or `--cross-ai`) is requested but convergence gate is disabled:
- stop before planning dispatch
- emit exact enable command:
- `msd config-set workflow.plan_review_convergence true`
- no silent downgrade to `local` strategy.
### Configuration Contract (Enable + Allowed AIs)
Convergence is configurable without introducing new config namespaces.
1. Enable convergence:
- `workflow.plan_review_convergence: true`
2. Define which AIs are allowed by default for convergence runs:
- `review.default_reviewers: ["codex", "gemini"]` (example)
3. Optionally pin models per allowed reviewer:
- `review.models.codex`, `review.models.gemini`, etc.
Precedence for reviewer selection in converge mode:
1. Explicit CLI reviewer flags (`--codex`, `--gemini`, `--all`, etc.)
2. `review.default_reviewers`
3. If neither resolves to any reviewer, fail fast with actionable message.
Example config:
```json
{
"workflow": {
"plan_review_convergence": true
},
"review": {
"default_reviewers": ["codex", "gemini"],
"models": {
"codex": "gpt-5.4",
"gemini": "gemini-2.5-pro"
}
}
}
```
## Flag Naming
Issue #15 asks for a flag such as `--converge` or `--cross-ai` on autonomous execution. `--converge` is the better primary term because it names the behavior (plan-review convergence loop), not the transport (external AI) or mode label (`autonomous`).
1. Primary: `--converge`
2. Alias: `--cross-ai`
3. Avoid: introducing `--autonomous-*` variants (the command already defines that mode)
## Options Considered
1. **Autonomous-only flag (`/msd-autonomous --cross-ai`)**
- Files: `commands/msd/autonomous.md`, `workflows/autonomous.md`
- Problem: solves issue #15 directly but leaves `/msd-progress --next --auto` inconsistent.
- Benefit: smallest blast radius.
- Drawback: two orchestration modes diverge in behavior.
2. **Progress-primary + autonomous parity (Chosen)**
- Files: `commands/msd/progress.md`, `workflows/progress.md`, `workflows/next.md`, plus autonomous wiring
- Problem: must keep two orchestrators aligned.
- Solution: one shared plan-strategy seam consumed by both commands.
- Benefit: better locality; users who already drive from `progress --next --auto` get convergence without switching workflows.
3. **Config-only global toggle (no per-run flag)**
- Files: config schema + both orchestrators
- Benefit: minimal CLI syntax expansion.
- Drawback: less control per run; harder to do targeted high-cost convergence only when needed.
- Decision: defer; keep explicit runtime flag.
## Rubber-Duck Design Notes
Expected behavior: the two existing orchestration entry points should be able to opt into cross-AI plan convergence without adding another top-level command.
Actual behavior: both orchestration entry points always take the local planning route, so external reviewers are never reached unless the user abandons orchestration flow and runs convergence manually.
Wrong assumptions surfaced:
1. "Enabling `workflow.plan_review_convergence` changes orchestration behavior." It does not unless the convergence command is explicitly routed.
2. "Cross-AI config propagates automatically into autonomous/next flows." It only applies where convergence/review workflows are invoked.
3. "Adding a separate command is required." Existing orchestration commands are sufficient if they expose a strategy seam and clear flag naming.
Root architectural gap: orchestration flows lack a plan strategy seam (`local` vs `converge`).
## Scope
### In scope
- Plan strategy seam shared by existing orchestration commands.
- `--cross-ai` pass-through contract on existing commands.
- `--converge` primary flag naming and `--cross-ai` compatibility alias.
- Feature-gate behavior contract for convergence strategy.
- Config contract for enabling convergence and selecting allowed AIs.
- Documentation updates tied to command/config behavior.
### Out of scope
- New top-level command creation.
- Reworking `msd-code-review` into cross-AI convergence loop.
- New reviewer config schema (reuse existing `review.*` keys).
- Changing default planning strategy without explicit opt-in.
- Altering `msd-plan-review-convergence` internal loop semantics.
## Consequences
- No new command tax on docs, routing, and long-term maintenance.
- Existing orchestration habits (`progress --next --auto` and autonomous) can opt into convergence consistently.
- Existing review configuration gets leverage without new schema.
- Backward compatibility is preserved by default.
- Explicit failure on disabled gate avoids silent false-confidence automation.
## References
- Issue: #15
- `commands/msd/progress.md`
- `msd-core/workflows/progress.md`
- `msd-core/workflows/next.md`
- `commands/msd/autonomous.md`
- `msd-core/workflows/autonomous.md`
- `commands/msd/plan-review-convergence.md`
- `msd-core/workflows/plan-review-convergence.md`
- `commands/msd/review.md`
- `docs/COMMANDS.md` (`/msd-plan-review-convergence`, `/msd-review`)
- `docs/CONFIGURATION.md` (`workflow.plan_review_convergence`, `review.default_reviewers`, `review.models.*`)