From dc4b90ae4b202007524e0576ff92b010b7460567 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Sun, 24 May 2026 23:12:24 -0400 Subject: [PATCH] docs(#15): ADR for cross-AI convergence flags in existing orchestration (#242) * docs(#15): propose convergence flag naming and doc-only test-gate exception * docs(#15): define convergence config and allowed AI selection --- .../adr/15-autonomous-cross-ai-convergence.md | 175 ++++++++++++++++++ docs/adr/README.md | 1 + docs/contributing/bootstrap.md | 9 +- 3 files changed, 183 insertions(+), 2 deletions(-) create mode 100644 docs/adr/15-autonomous-cross-ai-convergence.md diff --git a/docs/adr/15-autonomous-cross-ai-convergence.md b/docs/adr/15-autonomous-cross-ai-convergence.md new file mode 100644 index 000000000..7cd104b46 --- /dev/null +++ b/docs/adr/15-autonomous-cross-ai-convergence.md @@ -0,0 +1,175 @@ +# Cross-AI Plan Convergence via Existing Orchestration Commands + +- **Status:** Proposed +- **Date:** 2026-05-24 +- **Issue:** #15 + +Current orchestration commands (`/gsd-autonomous` and `/gsd-progress --next --auto`) route planning through `gsd-plan-phase` and only use local/Claude subagent review paths. The cross-AI convergence path already exists (`/gsd-plan-review-convergence`, `/gsd-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. + +## Decision + +Do not add a new command. Add convergence as an orchestration policy in existing commands, with `/gsd-progress` as the primary operator surface. + +1. Add a shared **plan strategy seam** for orchestration workflows: + - `plan_strategy=local|converge` + - `local` maps to `gsd-plan-phase` + - `converge` maps to `gsd-plan-review-convergence` +2. Expose the strategy via existing entry points: + - `/gsd-progress --next --auto --converge` (primary) + - `/gsd-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 `/gsd-review` and `/gsd-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 (`gsd-code-review` and `gsd-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) + +- `/gsd-progress --next --auto [--converge|--cross-ai] [reviewer flags] [--max-cycles N]` +- `/gsd-autonomous [existing flags] [--converge|--cross-ai] [reviewer flags] [--max-cycles N]` + +### Planning Step Routing + +- `plan_strategy=local`: + - orchestrator step uses `gsd-plan-phase` (current behavior). +- `plan_strategy=converge`: + - orchestrator step uses `gsd-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: + - `gsd 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 (`/gsd-autonomous --cross-ai`)** + - Files: `commands/gsd/autonomous.md`, `workflows/autonomous.md` + - Problem: solves issue #15 directly but leaves `/gsd-progress --next --auto` inconsistent. + - Benefit: smallest blast radius. + - Drawback: two orchestration modes diverge in behavior. + +2. **Progress-primary + autonomous parity (Chosen)** + - Files: `commands/gsd/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 `gsd-code-review` into cross-AI convergence loop. +- New reviewer config schema (reuse existing `review.*` keys). +- Changing default planning strategy without explicit opt-in. +- Altering `gsd-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/gsd/progress.md` +- `get-shit-done/workflows/progress.md` +- `get-shit-done/workflows/next.md` +- `commands/gsd/autonomous.md` +- `get-shit-done/workflows/autonomous.md` +- `commands/gsd/plan-review-convergence.md` +- `get-shit-done/workflows/plan-review-convergence.md` +- `commands/gsd/review.md` +- `docs/COMMANDS.md` (`/gsd-plan-review-convergence`, `/gsd-review`) +- `docs/CONFIGURATION.md` (`workflow.plan_review_convergence`, `review.default_reviewers`, `review.models.*`) diff --git a/docs/adr/README.md b/docs/adr/README.md index f62d641f3..f15347d0d 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -45,6 +45,7 @@ See **[CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#prop | [0011-review-default-reviewers.md](0011-review-default-reviewers.md) | Review default-reviewers selection policy for /gsd:review | Accepted | | [0011-review-default-reviewers-prd.md](0011-review-default-reviewers-prd.md) | PRD for review.default_reviewers feature (#3464) | Reference | | [0012-command-routing-hub.md](0012-command-routing-hub.md) | CommandRoutingHub as single dispatch seam for CJS command families | Superseded by ADR-0174 | +| [15-autonomous-cross-ai-convergence.md](15-autonomous-cross-ai-convergence.md) | Cross-AI plan convergence via existing orchestration commands | Proposed | | [3524-cjs-sdk-hard-seam.md](3524-cjs-sdk-hard-seam.md) | CJS↔SDK hard seam — single canonical owner per responsibility (#3524) | Superseded by ADR-0174 | | [3660-runtime-artifact-layout-module.md](3660-runtime-artifact-layout-module.md) | Runtime Artifact Layout Module owns per-runtime artifact placement | Proposed | | [0174-retire-gsd-sdk-package-boundary.md](0174-retire-gsd-sdk-package-boundary.md) | Retire @opengsd/gsd-sdk package boundary — single-runtime collapse | Accepted | diff --git a/docs/contributing/bootstrap.md b/docs/contributing/bootstrap.md index 214cbf81d..faf4bb0e1 100644 --- a/docs/contributing/bootstrap.md +++ b/docs/contributing/bootstrap.md @@ -217,5 +217,10 @@ gsd-test-summary ``` `gsd-test-summary` runs the full suite in a Docker container and emits a concise -`Mac: N failed / Docker: N failed` summary. Both lines must show `0 failed` before -a PR is opened. See [CLAUDE.md](../../CLAUDE.md) for the required PR-flow ordering. +`Mac: N failed / Docker: N failed` summary. + +- **Default rule (code changes):** both lines must show `0 failed` before a PR is opened. +- **Exception (ADR/doc-only PRs):** if the diff is documentation-only (for example `docs/adr/*.md`, `docs/**/*.md`, `README*.md`) and contains no executable-code or test changes, `gsd-test-summary` is optional. + +When using the doc-only exception, note it explicitly in the PR body (for example: +"Doc-only PR; gsd-test-summary not required by docs-only exception in `docs/contributing/bootstrap.md`").