docs: document /gsd-progress --converge as primary convergence surface

core/commands/workflow-commands.mdx

@@ -146,7 +146,7 @@
 </ParamField>
 
 <ParamField query="--research-phase N" type="string">
   Research-only mode. Spawns the researcher for phase `N`, writes `RESEARCH.md`, and exits before the planner runs. Useful for cross-phase research or iterating on research alone without replanning.
 </ParamField>
 
 <ParamField query="--gaps" type="flag">
@@ -170,7 +170,7 @@
 </ParamField>
 
 <ParamField query="--reviews" type="flag">
   Replan incorporating cross-AI feedback from a `REVIEWS.md` file produced by `/gsd-review`.
 </ParamField>
 
 <ParamField query="--skip-verify" type="flag">
@@ -214,7 +214,7 @@
 </ParamField>
 
 <ParamField query="--ollama" type="flag">
   Use a local Ollama server (OpenAI-compatible, default host `http://localhost:11434`). Configure the model via `review.models.ollama`.
 </ParamField>
 
 <ParamField query="--lm-studio" type="flag">
@@ -230,14 +230,14 @@
 </ParamField>
 
 <ParamField query="--max-cycles N" type="number">
   Maximum number of replan → review cycles before escalating to you. Default: `3`.
 </ParamField>
 
 ---
 
 ## `/gsd-execute-phase N`
 
 Execute all plans in a phase with wave-based parallelization.
 
 **Syntax**
 
@@ -250,20 +250,20 @@
 
 **What it does**
 
 Discovers all plan files in the phase, analyzes task dependencies, groups them into parallel execution waves, spawns subagents for each wave, and collects results. Phase verification and completion only trigger when no incomplete plans remain after the selected wave finishes.
 
 **Flags**
 
 <ParamField query="--wave N" type="number">
   Execute only Wave `N` of the phase. Use to pace execution, manage API usage limits, or perform a staged rollout.
 </ParamField>
 
 <ParamField query="--gaps-only" type="flag">
   Execute only gap-closure plans — those with `gap_closure: true` in their frontmatter. Run this after `/gsd-verify-work` creates fix plans.
 </ParamField>
 
 <ParamField query="--interactive" type="flag">
   Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gap closures.
 </ParamField>
 
 ---
@@ -322,6 +322,8 @@
 /gsd-progress
 /gsd-progress --next
 /gsd-progress --next --auto
+/gsd-progress --next --auto --converge
+/gsd-progress --next --auto --converge --codex --max-cycles 4
 /gsd-progress --do "add rate limiting to the API"
 /gsd-progress --forensic
 ```
@@ -330,6 +332,8 @@
 
 Your unified situational command. In default mode it shows a progress report and intelligently routes to the next action. With `--next` it advances automatically. With `--do` it maps natural language intent to the most appropriate GSD command, confirms the match, and hands off.
 
+`/gsd-progress --next --auto --converge` is the primary hands-free entry point for plan-review convergence: when the next action is planning, the step is routed through `/gsd-plan-review-convergence` instead of `/gsd-plan-phase`, and the converge mode is preserved across the rest of the `--auto` chain.
+
 **Flags**
 
 <ParamField query="--next" type="flag">
@@ -340,6 +344,14 @@
   Like `--next`, but after the determined step completes, re-invokes `/gsd-progress --next --auto` automatically to keep chaining steps. Enables hands-free plan → execute → verify progression until a blocking decision is required.
 </ParamField>
 
+<ParamField query="--converge" type="flag">
+  When the next routed action is planning (Route 3), run it through the cross-AI plan-review **convergence** loop instead of `/gsd-plan-phase`. `--cross-ai` is accepted as an alias. Requires `workflow.plan_review_convergence: true` — if the flag is set while the feature gate is off, the command fails fast and prints the enable hint instead of silently falling back to standard planning. When combined with `--auto`, converge mode is forwarded into every re-invocation so the entire chain stays under the convergence policy.
+</ParamField>
+
+<ParamField query="Reviewer flags" type="flag">
+  With `--converge`, reviewer selectors and `--max-cycles N` are forwarded to `/gsd-plan-review-convergence` unchanged: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`. See [Cross-AI review](/core/guides/cross-ai-review) for the full reviewer matrix.
+</ParamField>
+
 <ParamField query='--do "task description"' type="string">
   Smart dispatcher. Matches freeform natural language to the best GSD command using routing rules, confirms the match, then hands off execution.
 </ParamField>
@@ -348,6 +360,10 @@
   Append a 6-check integrity audit after the standard progress report.
 </ParamField>
 
+<Warning>
+  `workflow.plan_review_convergence` is disabled by default. Enable it with `gsd config-set workflow.plan_review_convergence true` before using `--converge`, or the command will exit with the enable hint.
+</Warning>
+
 ---
 
 ## `/gsd-autonomous`

core/guides/cross-ai-review.mdx

@@ -1,10 +1,10 @@
 ---
 title: "Cross-AI Plan Review: Get Peer Feedback Before Writing Code"
 sidebarTitle: "Cross-AI Review"
 description: "Send phase plans to multiple AI reviewers with /gsd-review, feed the results into replanning, and automate convergence with /gsd-plan-review-convergence."
 ---
 
 Cross-AI review lets you send your phase plans to multiple AI providers simultaneously and collect structured feedback before any code is written. Each reviewer produces an independent assessment of the plan's feasibility, risks, and gaps, and GSD synthesizes the results into a single `REVIEWS.md` artifact that the planner can consume directly to drive a more informed replan.
 
 ## Running /gsd-review
 
@@ -29,7 +29,7 @@
   | `--claude` | Claude (separate session) | `claude` CLI installed |
   | `--codex` | Codex CLI | `codex` CLI installed |
   | `--opencode` | OpenCode | `opencode` CLI installed |
   | `--qwen` | Qwen Code | Qwen CLI installed and API key set |
   | `--cursor` | Cursor agent | Cursor configured with agent access |
   | `--agy` / `--antigravity` | Antigravity CLI | Free with Google credentials |
   | `--all` | All detected reviewers | Each respective CLI must be installed and authenticated |
@@ -61,20 +61,33 @@
 ```
 
 <Note>
   `--reviews` skips the research step by default — it assumes your RESEARCH.md is still valid and focuses the planner's attention on addressing the specific concerns raised in REVIEWS.md. Combine `--reviews --research` to force a full research refresh before replanning.
 </Note>
 
 ## Automated convergence loop
 
-Run `/gsd-plan-review-convergence N` to automate the plan → review → replan cycle until no HIGH concerns remain. The command spawns a planning agent and one or more review agents, counts unresolved HIGH concerns in each cycle's `CYCLE_SUMMARY`, and replans automatically until the plan converges or the cycle cap is reached.
+GSD exposes two entry points into the plan → review → replan loop:
+
+- **`/gsd-progress --next --auto --converge`** — the preferred hands-free surface. When `--next` routes to planning, the step is dispatched through `/gsd-plan-review-convergence` automatically, and converge mode is preserved across the rest of the `--auto` chain (plan → execute → verify → next phase). Use this when you want one command to drive the whole milestone under the convergence policy.
+- **`/gsd-plan-review-convergence N`** — the direct command. Use this when you only want to converge the plan for a specific phase without running the rest of the workflow.
+
+Both surfaces require `workflow.plan_review_convergence: true` and accept the same reviewer flags and `--max-cycles N`. `--cross-ai` is accepted as an alias for `--converge` on `/gsd-progress`.
 
 ```bash
+# Direct convergence on a single phase
 /gsd-plan-review-convergence 3                    # Default reviewers, 3 cycles max
 /gsd-plan-review-convergence 3 --codex            # Codex-only convergence loop
 /gsd-plan-review-convergence 3 --all              # All reviewers
 /gsd-plan-review-convergence 3 --all --max-cycles 5   # Extend cap to 5 cycles
+
+# Hands-free via /gsd-progress (planning steps route through convergence)
+/gsd-progress --next --auto --converge
+/gsd-progress --next --auto --converge --codex --max-cycles 4
+/gsd-progress --next --auto --cross-ai --all
 ```
 
+Either way, the underlying loop is the same — `/gsd-progress --next --auto --converge` just wires it into the standard workflow router so you do not have to invoke it phase-by-phase. If you request `--converge` while `workflow.plan_review_convergence` is `false`, the command stops before planning and prints the enable hint instead of silently falling back to `/gsd-plan-phase`.
+
 <Steps>
   <Step title="Plan">
     Spawns a planning agent to produce PLAN.md for the phase.
@@ -86,7 +99,7 @@
     Parses the `CYCLE_SUMMARY` from REVIEWS.md to count unresolved HIGH-severity concerns.
   </Step>
   <Step title="Converge or replan">
     If HIGH count is zero, the loop exits successfully. If HIGH count is non-zero and cycles remain, replans with `--reviews` feedback and repeats from Step 2.
   </Step>
   <Step title="Escalate on stall">
     If the HIGH count stops decreasing across cycles, the command warns about a stall and offers the choice to proceed manually or extend the cycle cap.