claude-code-pilot 3.1.1 → 3.2.0

package/src/pilot/workflows/ingest-docs.md

@@ -0,0 +1,328 @@
+# Ingest Docs Workflow
+
+Scan a repo for mixed planning documents (ADR, PRD, SPEC, DOC), synthesize them into a consolidated context, and bootstrap or merge into `.planning/`.
+
+- `[path]` — optional target directory to scan (defaults to repo root)
+- `--mode new|merge` — override auto-detect (defaults: `new` if `.planning/` absent, `merge` if present)
+- `--manifest <file>` — YAML file listing `{path, type, precedence?}` per doc; overrides heuristic classification
+- `--resolve auto|interactive` — conflict resolution (v1: only `auto` is supported; `interactive` is reserved)
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► INGEST DOCS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+<step name="parse_arguments">
+
+Parse `$ARGUMENTS`:
+
+- First positional token (if not a flag) → `SCAN_PATH` (default: `.`)
+- `--mode new|merge` → `MODE` (default: auto-detect)
+- `--manifest <file>` → `MANIFEST_PATH` (optional)
+- `--resolve auto|interactive` → `RESOLVE_MODE` (default: `auto`; reject `interactive` in v1 with message "interactive resolution is planned for a future release")
+
+**Validate paths:**
+
+```bash
+case "{SCAN_PATH}" in *..*) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;; esac
+test -d "{SCAN_PATH}" || echo "PATH_NOT_FOUND"
+if [ -n "{MANIFEST_PATH}" ]; then
+  case "{MANIFEST_PATH}" in *..*) echo "SECURITY_ERROR: manifest path contains traversal"; exit 1 ;; esac
+  test -f "{MANIFEST_PATH}" || echo "MANIFEST_NOT_FOUND"
+fi
+```
+
+**Containment (required):** After resolving `SCAN_PATH` and `MANIFEST_PATH` relative to the repo root, canonicalize each with `realpath` (or platform equivalent) and assert the result is under `realpath("$REPO_ROOT")`. Reject absolute paths outside the repo (e.g. `/tmp`, `C:\Windows`) even when they do not contain `..`.
+
+If `PATH_NOT_FOUND` or `MANIFEST_NOT_FOUND`: display error and exit.
+
+</step>
+
+<step name="init_and_mode_detect">
+
+Run the init query:
+
+```bash
+INIT=$(gsd-sdk query init.ingest-docs)
+```
+
+Parse `project_exists`, `planning_exists`, `has_git`, `project_path` from INIT.
+
+**Auto-detect MODE** if not set:
+- `planning_exists: true` → `MODE=merge`
+- `planning_exists: false` → `MODE=new`
+
+If user passed `--mode new` but `.planning/` already exists: display warning and require explicit confirm via `AskUserQuestion` (approve-revise-abort from `references/gate-prompts.md`) before overwriting.
+
+If `has_git: false` and `MODE=new`: initialize git:
+```bash
+git init
+```
+
+**Detect runtime** using the same pattern as `new-project.md`:
+- execution_context path `/.codex/` → `RUNTIME=codex`
+- `/.gemini/` → `RUNTIME=gemini`
+- `/.opencode/` or `/.config/opencode/` → `RUNTIME=opencode`
+- else → `RUNTIME=claude`
+
+Fall back to env vars (`CODEX_HOME`, `GEMINI_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`) if execution_context is unavailable.
+
+</step>
+
+<step name="discover_docs">
+
+Build the doc list from three sources, in order:
+
+**1. Manifest (if provided)** — authoritative:
+
+Read `MANIFEST_PATH`. Expected YAML shape:
+
+```yaml
+docs:
+  - path: docs/adr/0001-db.md
+    type: ADR
+    precedence: 0   # optional, lower = higher precedence
+  - path: docs/prd/auth.md
+    type: PRD
+```
+
+Each entry provides `path` (required, relative to repo root) + `type` (required, one of ADR|PRD|SPEC|DOC) + `precedence` (optional integer).
+
+**2. Directory conventions** (skipped when manifest is provided):
+
+```bash
+# ADRs
+find {SCAN_PATH} -type f \( -path '*/adr/*' -o -path '*/adrs/*' -o -name 'ADR-*.md' -o -regex '.*/[0-9]\{4\}-.*\.md' \) 2>/dev/null
+
+# PRDs
+find {SCAN_PATH} -type f \( -path '*/prd/*' -o -path '*/prds/*' -o -name 'PRD-*.md' \) 2>/dev/null
+
+# SPECs / RFCs
+find {SCAN_PATH} -type f \( -path '*/spec/*' -o -path '*/specs/*' -o -path '*/rfc/*' -o -path '*/rfcs/*' -o -name 'SPEC-*.md' -o -name 'RFC-*.md' \) 2>/dev/null
+
+# Generic docs (fall-through candidates)
+find {SCAN_PATH} -type f -path '*/docs/*' -name '*.md' 2>/dev/null
+```
+
+De-duplicate the union (a file matched by multiple patterns is one doc).
+
+**3. Content heuristics** (run during classification, not here) — the classifier handles frontmatter `type:` and H1 inspection for docs that didn't match a convention.
+
+**Cap:** hard limit of 50 docs per invocation (documented v1 constraint). If the discovered set exceeds 50:
+
+```
+GSD > Discovered {N} docs, which exceeds the v1 cap of 50.
+      Use --manifest to narrow the set to ≤ 50 files, or run
+      /ccp:ingest-docs again with a narrower <path>.
+```
+
+Exit without proceeding.
+
+**Display discovered set** and request approval (see `references/gate-prompts.md` — `yes-no-pick` pattern works; or `approve-revise-abort`):
+
+```
+Discovered {N} documents:
+  {N} ADR | {N} PRD | {N} SPEC | {N} DOC | {N} unclassified
+
+  docs/adr/0001-architecture.md       [ADR]    (from manifest|directory|heuristic)
+  docs/adr/0002-database.md           [ADR]    (directory)
+  docs/prd/auth.md                    [PRD]    (manifest)
+  ...
+```
+
+**Text mode:** apply the same `--text`/`text_mode` rule as other workflows — replace `AskUserQuestion` with a numbered list.
+
+Use `AskUserQuestion` (approve-revise-abort):
+- question: "Proceed with classification of these {N} documents?"
+- header: "Approve?"
+- options: Approve | Revise | Abort
+
+On Abort: exit cleanly with "Ingest cancelled."
+On Revise: exit with guidance to re-run with `--manifest` or a narrower path.
+
+</step>
+
+<step name="classify_parallel">
+
+Create staging directory:
+
+```bash
+mkdir -p .planning/intel/classifications/
+```
+
+For each discovered doc, spawn `gsd-doc-classifier` in parallel. In Claude Code, issue all Task calls in a single message with multiple tool uses so the harness runs them concurrently. For Copilot / sequential runtimes, fall back to sequential dispatch.
+
+Per-spawn prompt fields:
+- `FILEPATH` — absolute path to the doc
+- `OUTPUT_DIR` — `.planning/intel/classifications/`
+- `MANIFEST_TYPE` — the type from the manifest if present, else omit
+- `MANIFEST_PRECEDENCE` — the precedence integer from the manifest if present, else omit
+- `<required_reading>` — `agents/ccp:doc-classifier.md` (the agent definition itself)
+
+Collect the one-line confirmations from each classifier. If any classifier errors out, surface the error and abort without touching `.planning/` further.
+
+</step>
+
+<step name="synthesize">
+
+Spawn `gsd-doc-synthesizer` once:
+
+```
+Task({
+  subagent_type: "gsd-doc-synthesizer",
+  prompt: "
+    CLASSIFICATIONS_DIR: .planning/intel/classifications/
+    INTEL_DIR: .planning/intel/
+    CONFLICTS_PATH: .planning/INGEST-CONFLICTS.md
+    MODE: {MODE}
+    EXISTING_CONTEXT: {paths to existing .planning files if MODE=merge, else empty}
+    PRECEDENCE: {array from manifest defaults or default ['ADR','SPEC','PRD','DOC']}
+
+    <required_reading>
+    - agents/ccp:doc-synthesizer.md
+    - get-shit-done/references/doc-conflict-engine.md
+    </required_reading>
+  "
+})
+```
+
+The synthesizer writes:
+- `.planning/intel/decisions.md`, `.planning/intel/requirements.md`, `.planning/intel/constraints.md`, `.planning/intel/context.md`
+- `.planning/intel/SYNTHESIS.md`
+- `.planning/INGEST-CONFLICTS.md`
+
+</step>
+
+<step name="conflict_gate">
+
+Read `.planning/INGEST-CONFLICTS.md`. Count entries in each bucket (the synthesizer always writes the three-bucket header; parse the `### BLOCKERS ({N})`, `### WARNINGS ({N})`, `### INFO ({N})` lines).
+
+Apply the safety semantics from `references/doc-conflict-engine.md`. Operation noun: `ingest`.
+
+**If BLOCKERS > 0:**
+
+Render the report to the user, then display:
+
+```
+GSD > BLOCKED: {N} blockers must be resolved before ingest can proceed.
+```
+
+Exit WITHOUT writing PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md. The staging intel files remain for inspection. The safety gate holds — no destination files are written when blockers exist.
+
+**If WARNINGS > 0 and BLOCKERS = 0:**
+
+Render the report, then ask via AskUserQuestion (approve-revise-abort):
+- question: "Review the competing variants above. Resolve manually and proceed, or abort?"
+- header: "Approve?"
+- options: Approve | Abort
+
+On Abort: exit cleanly with "Ingest cancelled. Staged intel preserved at `.planning/intel/`."
+
+**If BLOCKERS = 0 and WARNINGS = 0:**
+
+Proceed to routing silently, or optionally display `GSD > No conflicts. Auto-resolved: {N}.`
+
+</step>
+
+<step name="route_new_mode">
+
+**Applies only when MODE=new.**
+
+Audit PROJECT.md field requirements that `gsd-roadmapper` expects. For fields derivable from `.planning/intel/SYNTHESIS.md` (project scope, goals/non-goals, constraints, locked decisions), synthesize from the intel. For fields NOT derivable (project name, developer-facing success metric, target runtime), prompt via `AskUserQuestion` one at a time — minimal question set, no interrogation.
+
+Delegate to `gsd-roadmapper`:
+
+```
+Task({
+  subagent_type: "gsd-roadmapper",
+  prompt: "
+    Mode: new-project-from-ingest
+    Intel: .planning/intel/SYNTHESIS.md (entry point)
+    Per-type intel: .planning/intel/{decisions,requirements,constraints,context}.md
+    User-supplied fields: {collected in previous step}
+
+    Produce:
+    - .planning/PROJECT.md
+    - .planning/REQUIREMENTS.md
+    - .planning/ROADMAP.md
+    - .planning/STATE.md
+
+    Treat ADR-locked decisions as locked in PROJECT.md <decisions> blocks.
+  "
+})
+```
+
+</step>
+
+<step name="route_merge_mode">
+
+**Applies only when MODE=merge.**
+
+Load existing `.planning/ROADMAP.md`, `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, all `CONTEXT.md` files under `.planning/phases/`.
+
+The synthesizer has already hard-blocked on any LOCKED-in-ingest vs LOCKED-in-existing contradiction; if we reach this step, no such blockers remain.
+
+Plan the merge:
+- **New requirements** from synthesized `.planning/intel/requirements.md` that do not overlap existing REQUIREMENTS.md entries → append to REQUIREMENTS.md
+- **New decisions** from synthesized `.planning/intel/decisions.md` that do not overlap existing CONTEXT.md `<decisions>` blocks → write to a new phase's CONTEXT.md or append to the next milestone's requirements
+- **New scope** → derive phase additions following the `new-milestone.md` pattern; append phases to `.planning/ROADMAP.md`
+
+Preview the merge diff to the user and gate via approve-revise-abort before writing.
+
+</step>
+
+<step name="finalize">
+
+Commit the ingest results:
+
+```bash
+gsd-sdk query commit "docs: ingest {N} docs from {SCAN_PATH} (#2387)" \
+  .planning/PROJECT.md \
+  .planning/REQUIREMENTS.md \
+  .planning/ROADMAP.md \
+  .planning/STATE.md \
+  .planning/intel/ \
+  .planning/INGEST-CONFLICTS.md
+```
+
+(For merge mode, substitute the actual set of modified files.)
+
+Display completion:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► INGEST DOCS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show:
+- Mode ran (new or merge)
+- Docs ingested (count + type breakdown)
+- Decisions locked, requirements created, constraints captured
+- Conflict report path (`.planning/INGEST-CONFLICTS.md`)
+- Next step: `/ccp:plan-phase 1` (new mode) or `/ccp:plan-phase N` (merge, pointing at the first newly-added phase)
+
+</step>
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
+- Write PROJECT.md, REQUIREMENTS.md, ROADMAP.md, or STATE.md when BLOCKERs exist in the conflict report
+- Skip the 50-doc cap — larger sets must use `--manifest` to narrow the scope
+- Auto-resolve LOCKED-vs-LOCKED ADR contradictions — those are BLOCKERs in both modes
+- Merge competing PRD acceptance variants into a combined criterion — preserve all variants for user resolution
+- Bypass the discovery approval gate — users must see the classified doc list before classifiers spawn
+- Skip path validation on `SCAN_PATH` or `MANIFEST_PATH`
+- Implement `--resolve interactive` in this v1 — the flag is reserved; reject with a future-release message

package/src/pilot/workflows/plan-review-convergence.md

@@ -0,0 +1,329 @@
+<purpose>
+Cross-AI plan convergence loop — automates the manual chain:
+gsd-plan-phase N → gsd-review N --codex → gsd-plan-phase N --reviews → gsd-review N --codex → ...
+Each step runs inside an isolated Agent that calls the corresponding Skill.
+Orchestrator only does: init, loop control, parse CYCLE_SUMMARY for HIGH count, stall detection, escalation.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+@$HOME/.claude/pilot/references/revision-loop.md
+@$HOME/.claude/pilot/references/gates.md
+@$HOME/.claude/pilot/references/agent-contracts.md
+</required_reading>
+
+<process>
+
+## 1. Parse and Normalize Arguments
+
+Extract from $ARGUMENTS: phase number, reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`), `--max-cycles N`, `--text`, `--ws`.
+
+```bash
+PHASE=$(echo "$ARGUMENTS" | grep -oE '[0-9]+\.?[0-9]*' | head -1)
+
+REVIEWER_FLAGS=""
+echo "$ARGUMENTS" | grep -q '\-\-codex' && REVIEWER_FLAGS="$REVIEWER_FLAGS --codex"
+echo "$ARGUMENTS" | grep -q '\-\-gemini' && REVIEWER_FLAGS="$REVIEWER_FLAGS --gemini"
+echo "$ARGUMENTS" | grep -q '\-\-claude' && REVIEWER_FLAGS="$REVIEWER_FLAGS --claude"
+echo "$ARGUMENTS" | grep -q '\-\-opencode' && REVIEWER_FLAGS="$REVIEWER_FLAGS --opencode"
+echo "$ARGUMENTS" | grep -q '\-\-ollama' && REVIEWER_FLAGS="$REVIEWER_FLAGS --ollama"
+echo "$ARGUMENTS" | grep -q '\-\-lm-studio' && REVIEWER_FLAGS="$REVIEWER_FLAGS --lm-studio"
+echo "$ARGUMENTS" | grep -q '\-\-llama-cpp' && REVIEWER_FLAGS="$REVIEWER_FLAGS --llama-cpp"
+echo "$ARGUMENTS" | grep -q '\-\-all' && REVIEWER_FLAGS="$REVIEWER_FLAGS --all"
+if [ -z "$REVIEWER_FLAGS" ]; then REVIEWER_FLAGS="--codex"; fi
+
+MAX_CYCLES=$(echo "$ARGUMENTS" | grep -oE '\-\-max-cycles\s+[0-9]+' | awk '{print $2}')
+if [ -z "$MAX_CYCLES" ]; then MAX_CYCLES=3; fi
+
+GSD_WS=""
+echo "$ARGUMENTS" | grep -qE '\-\-ws\s+\S+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE '\-\-ws\s+\S+')
+```
+
+## 1.5. Config Gate (feature disabled by default)
+
+```bash
+CONVERGENCE_ENABLED=$(gsd-sdk query config-get workflow.plan_review_convergence 2>/dev/null || echo "false")
+```
+
+**If `CONVERGENCE_ENABLED` is not `"true"`:** Display and exit:
+
+```text
+gsd-plan-review-convergence is disabled (workflow.plan_review_convergence=false).
+
+This feature automates the plan→review→replan loop using external AI reviewers.
+Enable it with:
+
+  gsd config-set workflow.plan_review_convergence true
+
+Then re-run: /ccp:plan-review-convergence {PHASE}
+```
+
+## 2. Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/pilot/bin/ccp:tools.cjs" init plan-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_dir`, `phase_number`, `padded_phase`, `phase_name`, `has_plans`, `plan_count`, `commit_docs`, `text_mode`, `response_language`.
+
+**If `response_language` is set:** All user-facing output should be in `{response_language}`.
+
+Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number.
+
+## 3. Validate Phase + Pre-flight Gate
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/pilot/bin/ccp:tools.cjs" roadmap get-phase "${PHASE}")
+```
+
+**If `found` is false:** Error with available phases. Exit.
+
+Display startup banner:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PLAN CONVERGENCE — Phase {phase_number}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Reviewers: {REVIEWER_FLAGS}
+ Max cycles: {MAX_CYCLES}
+```
+
+## 4. Initial Planning (if no plans exist)
+
+**If `has_plans` is true:** Skip to step 5. Display: `Plans found: {plan_count} PLAN.md files — skipping initial planning.`
+
+**If `has_plans` is false:**
+
+Display: `◆ No plans found — spawning initial planning agent...`
+
+```text
+Agent(
+  description="Initial planning Phase {PHASE}",
+  prompt="Run /ccp:plan-phase for Phase {PHASE}.
+
+Execute: Skill(skill='gsd-plan-phase', args='{PHASE} {GSD_WS}')
+
+Complete the full planning workflow. Do NOT return until planning is complete and PLAN.md files are committed.",
+  mode="auto"
+)
+```
+
+After agent returns, verify plans were created:
+```bash
+PLAN_COUNT=$(ls ${phase_dir}/${padded_phase}-*-PLAN.md 2>/dev/null | wc -l)
+```
+
+If PLAN_COUNT == 0: Error — initial planning failed. Exit.
+
+Display: `Initial planning complete: ${PLAN_COUNT} PLAN.md files created.`
+
+## 5. Convergence Loop
+
+Initialize loop variables:
+
+```text
+cycle = 0
+prev_high_count = Infinity
+```
+
+### 5a. Review (Spawn Agent)
+
+Increment `cycle`.
+
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — spawning review agent...`
+
+```text
+Agent(
+  description="Cross-AI review Phase {PHASE} cycle {cycle}",
+  prompt="Run /ccp:review for Phase {PHASE}.
+
+Execute: Skill(skill='gsd-review', args='--phase {PHASE} {REVIEWER_FLAGS} {GSD_WS}')
+
+Complete the full review workflow. Do NOT return until REVIEWS.md is committed.
+
+IMPORTANT — CYCLE_SUMMARY contract (required):
+Your final response MUST include a machine-readable line of exactly this form:
+
+  CYCLE_SUMMARY: current_high=<N>
+
+Where <N> is the integer count of HIGH-severity concerns that REMAIN UNRESOLVED in this cycle's findings.
+
+Counting rules:
+  INCLUDE in the count:
+    - Newly raised HIGHs in this cycle
+    - PARTIALLY RESOLVED HIGHs: concern acknowledged and a mitigation is in progress, but not yet verified/completed
+    - Previously raised HIGHs that are still unresolved
+
+  EXCLUDE from the count:
+    - FULLY RESOLVED HIGHs: concern addressed with verification complete (closed ticket, verification log, or reviewer sign-off)
+    - HIGH mentions in retrospective/summary tables comparing cycles
+    - Quoted excerpts from prior reviews referencing past HIGH items
+
+Definitions:
+  PARTIALLY RESOLVED — concern acknowledged and mitigation is in progress but not yet verified/completed (e.g., open ticket exists but fix not landed).
+  FULLY RESOLVED — concern addressed with verification complete (closed ticket, verification log, or explicit reviewer sign-off confirming closure).
+
+Your final response MUST also include this section immediately after the CYCLE_SUMMARY line:
+
+## Current HIGH Concerns
+[List each unresolved HIGH with a brief description, one per bullet]
+[If none: write exactly 'None.']",
+  mode="auto"
+)
+```
+
+After agent returns, verify REVIEWS.md exists:
+```bash
+REVIEWS_FILE=$(ls ${phase_dir}/${padded_phase}-REVIEWS.md 2>/dev/null)
+```
+
+If REVIEWS_FILE is empty: Error — review agent did not produce REVIEWS.md. Exit.
+
+### 5b. Extract HIGH Count from CYCLE_SUMMARY Contract
+
+**Do NOT grep REVIEWS.md for HIGH count.** REVIEWS.md accumulates history across cycles — resolved HIGHs from prior cycles remain in the file as audit trail, inflating a raw grep count and causing false stall detection.
+
+Parse HIGH_COUNT from the review agent's return message via the CYCLE_SUMMARY contract:
+
+```bash
+# Extract the integer from "CYCLE_SUMMARY: current_high=N" in the agent's return message
+HIGH_COUNT=$(echo "$REVIEW_AGENT_RETURN" | grep -oE 'CYCLE_SUMMARY:\s*current_high=[0-9]+' | head -1 | grep -oE '[0-9]+$')
+
+if [ -z "$HIGH_COUNT" ]; then
+  # Distinguish malformed contract from completely absent contract
+  if echo "$REVIEW_AGENT_RETURN" | grep -q 'CYCLE_SUMMARY:'; then
+    echo "CYCLE_SUMMARY present but current_high is malformed — expected integer, got non-numeric value. Retry or switch reviewer."
+  else
+    echo "Review agent did not honor the CYCLE_SUMMARY contract — cannot determine HIGH count. Retry or switch reviewer."
+  fi
+  exit 1
+fi
+
+# Extract the ## Current HIGH Concerns section from the agent's return message
+HIGH_LINES=$(echo "$REVIEW_AGENT_RETURN" | awk '/^## Current HIGH Concerns/{found=1; next} found && /^##/{exit} found{print}')
+
+if [ "${HIGH_COUNT}" -gt 0 ] && [ -z "${HIGH_LINES}" ]; then
+  echo "⚠ Review agent's CYCLE_SUMMARY reports ${HIGH_COUNT} HIGHs but did not provide ## Current HIGH Concerns section — continuing with incomplete escalation details."
+fi
+```
+
+**If HIGH_COUNT == 0 (converged):**
+
+```bash
+node "$HOME/.claude/pilot/bin/ccp:tools.cjs" state planned-phase --phase "${PHASE}" --name "${phase_name}" --plans "${PLAN_COUNT}"
+```
+
+Display:
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► CONVERGENCE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Phase {phase_number} converged in {cycle} cycle(s).
+ No HIGH concerns remaining.
+
+ REVIEWS.md: {REVIEWS_FILE}
+ Next: /ccp:execute-phase {PHASE}
+```
+
+Exit — convergence achieved.
+
+**If HIGH_COUNT > 0:** Continue to 5c.
+
+### 5c. Stall Detection + Escalation Check
+
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH concerns found`
+
+**Stall detection:** If `HIGH_COUNT >= prev_high_count`:
+```text
+⚠ Convergence stalled — HIGH concern count not decreasing
+  ({HIGH_COUNT} HIGH concerns, previous cycle had {prev_high_count})
+```
+
+**Max cycles check:** If `cycle >= MAX_CYCLES`:
+
+If `TEXT_MODE` is true, present as plain-text numbered list:
+```text
+Plan convergence did not complete after {MAX_CYCLES} cycles.
+{HIGH_COUNT} HIGH concerns remain:
+
+{HIGH_LINES}
+
+How would you like to proceed?
+
+1. Proceed anyway — Accept plans with remaining HIGH concerns and move to execution
+2. Manual review — Stop here, review REVIEWS.md and address concerns manually
+
+Enter number:
+```
+
+Otherwise use AskUserQuestion:
+```js
+AskUserQuestion([
+  {
+    question: "Plan convergence did not complete after {MAX_CYCLES} cycles. {HIGH_COUNT} HIGH concerns remain:\n\n{HIGH_LINES}\n\nHow would you like to proceed?",
+    header: "Convergence",
+    multiSelect: false,
+    options: [
+      { label: "Proceed anyway", description: "Accept plans with remaining HIGH concerns and move to execution" },
+      { label: "Manual review", description: "Stop here — review REVIEWS.md and address concerns manually" }
+    ]
+  }
+])
+```
+
+If "Proceed anyway": Display final status and exit.
+If "Manual review":
+```text
+Review the concerns in: {REVIEWS_FILE}
+
+To replan manually:  /ccp:plan-phase {PHASE} --reviews
+To restart loop:     /ccp:plan-review-convergence {PHASE} {REVIEWER_FLAGS}
+```
+Exit workflow.
+
+### 5d. Replan (Spawn Agent)
+
+**If under max cycles:**
+
+Update `prev_high_count = HIGH_COUNT`.
+
+Display: `◆ Spawning replan agent with review feedback...`
+
+```text
+Agent(
+  description="Replan Phase {PHASE} with review feedback cycle {cycle}",
+  prompt="Run /ccp:plan-phase with --reviews for Phase {PHASE}.
+
+Execute: Skill(skill='gsd-plan-phase', args='{PHASE} --reviews --skip-research {GSD_WS}')
+
+This will replan incorporating cross-AI review feedback from REVIEWS.md.
+Do NOT return until replanning is complete and updated PLAN.md files are committed.
+
+IMPORTANT: When gsd-plan-phase outputs '## PLANNING COMPLETE', that means replanning is done. Return at that point.",
+  mode="auto"
+)
+```
+
+After agent returns → go back to **step 5a** (review again).
+
+</process>
+
+<success_criteria>
+- [ ] Config gate checked before running — exits with enable instructions if workflow.plan_review_convergence is false
+- [ ] Initial planning via Agent → Skill("gsd-plan-phase") if no plans exist
+- [ ] Review via Agent → Skill("gsd-review") — isolated, not inline; {GSD_WS} forwarded
+- [ ] Replan via Agent → Skill("gsd-plan-phase --reviews") — isolated, not inline
+- [ ] Orchestrator only does: init, config gate, loop control, parse CYCLE_SUMMARY for HIGH count, stall detection, escalation
+- [ ] HIGH count extracted from review agent's CYCLE_SUMMARY return message (not by grepping REVIEWS.md)
+- [ ] Review agent prompt defines CYCLE_SUMMARY: current_high=<N> contract with PARTIALLY/FULLY RESOLVED definitions
+- [ ] Abort with clear error if CYCLE_SUMMARY is absent; distinguish malformed from absent
+- [ ] Warn if HIGH_COUNT > 0 but ## Current HIGH Concerns section is absent from return message
+- [ ] Each Agent fully completes its Skill before returning
+- [ ] Loop exits on: no HIGH concerns (converged) OR max cycles (escalation)
+- [ ] Stall detection reported when HIGH count not decreasing
+- [ ] STATE.md updated on convergence completion
+</success_criteria>