@pareto4/pp-core 1.5.0

package/pp-core/workflows/plan-review-convergence.md

@@ -0,0 +1,369 @@
+<purpose>
+Cross-AI plan convergence loop — automates the manual chain:
+pp-plan-phase N → pp-review N --codex → pp-plan-phase N --reviews → pp-review N --codex → ...
+Plan-phase runs inline (bare Skill at depth 0) so it can spawn pp-planner/pp-plan-checker at depth 1.
+Review runs inside an isolated Agent (leaf skill — Bash only, no sub-agents needed).
+Orchestrator only does: init, loop control, parse CYCLE_SUMMARY for HIGH and actionable non-HIGH counts, stall detection, escalation.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+@$HOME/.claude/pp-core/references/revision-loop.md
+@$HOME/.claude/pp-core/references/gates.md
+@$HOME/.claude/pp-core/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
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+CONVERGENCE_ENABLED=$(pp_run query config-get workflow.plan_review_convergence 2>/dev/null || echo "false")
+```
+
+**If `CONVERGENCE_ENABLED` is not `"true"`:** Display and exit:
+
+```text
+pp-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: /pp:plan-review-convergence {PHASE}
+```
+
+## 2. Initialize
+
+```bash
+INIT=$(pp_run 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=$(pp_run 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 — running initial planning inline... (plan-phase runs here in the orchestrator — no output until planning is complete, ~1–5 min; expected, not a freeze)`
+
+```text
+Skill(skill="pp-plan-phase", args="{PHASE} {GSD_WS}")
+```
+
+Run plan-phase **inline** (do NOT wrap it in Agent()). The convergence orchestrator runs at depth 0 with Agent available, so inline plan-phase can spawn pp-planner and pp-plan-checker at depth 1 — the one level of nesting that works on Claude Code. Wrapping plan-phase in Agent() would push it to depth 1 where the Agent tool is absent, preventing it from spawning any sub-agents. Wait until plan-phase completes and PLAN.md files are committed before continuing.
+
+After plan-phase completes, 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_unresolved_count = Infinity
+```
+
+### 5a. Review (Spawn Agent)
+
+Increment `cycle`.
+
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — spawning review agent... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
+
+```text
+Agent(
+  description="Cross-AI review Phase {PHASE} cycle {cycle}",
+  prompt="Run /pp:review for Phase {PHASE}.
+
+Execute: Skill(skill='pp-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> current_actionable=<M>
+
+Where <N> is the integer count of HIGH-severity concerns that REMAIN UNRESOLVED in this cycle's findings.
+Where <M> is the integer count of actionable MEDIUM/LOW concerns that REMAIN UNRESOLVED because the latest PLAN.md files do not yet incorporate them or explicitly defer/reject them.
+
+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
+    - MEDIUM/LOW concerns that are already incorporated into a PLAN.md task, action, acceptance_criteria, verify command, must_haves item, threat model, artifact list, or explicit deferral/rejection rationale
+
+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).
+  ACTIONABLE — a non-HIGH review finding that would be invisible to /pp:execute-phase unless it is incorporated into PLAN.md or explicitly deferred/rejected in PLAN.md.
+
+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.']
+
+## Current Actionable Non-HIGH Concerns
+[List each unresolved actionable MEDIUM/LOW with a brief description and the PLAN.md change still needed, one per bullet]
+[If none: write exactly 'None.']
+These two sections MUST be the final content of your response, in this exact order, with no additional "## " headings after them (the source-grounding "Verification coverage" block is appended to REVIEWS.md, not to this return message).",
+  mode="auto"
+)
+```
+
+### Source-grounding pass (config: `plan_review.source_grounding`, default on)
+
+Run this pass unless `plan_review.source_grounding` is `false`. It verifies every symbol the plan cites against the project source before approval, catching hallucinated symbols at review time instead of execution time.
+
+1. **Enumerate cited symbols.** List every referenced symbol by kind, quoting the plan line for each (coverage must be auditable): decorators (`@name`), classes/methods (`Class.method`), functions (`module.function`), CLI flags (`--name`), file paths, dataclass/struct fields.
+2. **Exclude new artifacts.** Do NOT verify symbols the plan declares under its "Artifacts this phase produces" section — those are created by this phase, not references to existing code.
+3. **Resolve each remaining symbol** using the effective authority adapter (resolved deterministically — see step 4a):
+   - `grep` — ripgrep / Read the source; confirm the name appears as a real declaration.
+   - `intel` — consult `.planning/intel/API-SURFACE.md` / `api-map.json` (only when `intel.enabled`).
+   Record one verdict per symbol: **VERIFIED** (quote `file:line`), **MISSING** (adapter can check this language/kind and the symbol is absent), **AMBIGUOUS** (multiple candidates), or **UNCHECKABLE** (adapter cannot analyze this language/kind — e.g. non-JS under `intel`, or any signature under `grep`). Never treat UNCHECKABLE as verified or missing.
+4a. **Resolve effective authority** (deterministic — replaces manual `intel.enabled` reasoning):
+   ```bash
+   EFFECTIVE_AUTHORITY=$(pp_run drift-guard authority --raw)
+   ```
+4. **Severity & gating** — classify each symbol's verdict using the seam (do not apply the table manually):
+   ```bash
+   # For each symbol, e.g.:
+   RESULT=$(pp_run drift-guard severity --status <verdict> --authority "$EFFECTIVE_AUTHORITY")
+   # $RESULT is JSON: {"severity":"…","hardBlock":true|false}
+   ```
+   - `hardBlock: true` (HIGH at authority `lsp`/`scip`) — stops the review cycle immediately; do not proceed until the plan author resolves the missing symbol.
+   - `hardBlock: false`, severity `needs-acknowledgement` — plan proceeds only if the author confirms the symbol is genuinely new or dynamically resolved, and that acknowledgement is recorded.
+   - `AMBIGUOUS` → MEDIUM. `UNCHECKABLE` → INFO.
+   - Signature mismatches cannot be asserted under `grep`/`intel`; report the signature as UNCHECKABLE.
+5. **Coverage block.** Append a "Verification coverage" section to `REVIEWS.md` listing every UNCHECKABLE/skipped symbol and why — a clean review must never silently mean "nothing was checked."
+
+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 unresolved counts from CYCLE_SUMMARY Contract
+
+**Do NOT grep REVIEWS.md for HIGH or actionable counts.** REVIEWS.md accumulates history across cycles — resolved findings from prior cycles remain in the file as audit trail, inflating a raw grep count and causing false stall detection.
+
+Parse HIGH_COUNT and ACTIONABLE_COUNT from the review agent's return message via the CYCLE_SUMMARY contract:
+
+```bash
+# Extract integers from "CYCLE_SUMMARY: current_high=N current_actionable=M" in the agent's return message
+SUMMARY_LINE=$(echo "$REVIEW_AGENT_RETURN" | grep -oE 'CYCLE_SUMMARY:.*' | head -1)
+HIGH_COUNT=$(echo "$SUMMARY_LINE" | grep -oE 'current_high=[0-9]+' | head -1 | grep -oE '[0-9]+$')
+ACTIONABLE_COUNT=$(echo "$SUMMARY_LINE" | grep -oE 'current_actionable=[0-9]+' | head -1 | grep -oE '[0-9]+$')
+
+if [ -z "$SUMMARY_LINE" ]; then
+  echo "Review agent did not honor the CYCLE_SUMMARY contract — cannot determine unresolved review counts. Retry or switch reviewer."
+  exit 1
+fi
+
+if [ -z "$HIGH_COUNT" ]; then
+  echo "CYCLE_SUMMARY present but current_high is missing or malformed — expected integer, got non-numeric or absent value. Retry or switch reviewer."
+  exit 1
+fi
+
+if [ -z "$ACTIONABLE_COUNT" ]; then
+  echo "CYCLE_SUMMARY present but current_actionable is missing or malformed — expected integer, got non-numeric or absent value. Retry or switch reviewer."
+  exit 1
+fi
+
+UNRESOLVED_COUNT=$((HIGH_COUNT + ACTIONABLE_COUNT))
+
+# 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}')
+ACTIONABLE_LINES=$(echo "$REVIEW_AGENT_RETURN" | awk '/^## Current Actionable Non-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 [ "${ACTIONABLE_COUNT}" -gt 0 ] && [ -z "${ACTIONABLE_LINES}" ]; then
+  echo "⚠ Review agent's CYCLE_SUMMARY reports ${ACTIONABLE_COUNT} actionable non-HIGH concerns but did not provide ## Current Actionable Non-HIGH Concerns section — continuing with incomplete escalation details."
+fi
+```
+
+**If HIGH_COUNT == 0 and ACTIONABLE_COUNT == 0 (converged):**
+
+```bash
+pp_run 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.
+ No actionable MEDIUM/LOW review findings remain outside PLAN.md.
+
+ REVIEWS.md: {REVIEWS_FILE}
+ Next: /pp:execute-phase {PHASE}
+```
+
+Exit — convergence achieved.
+
+**If HIGH_COUNT > 0 or ACTIONABLE_COUNT > 0:** Continue to 5c.
+
+### 5c. Stall Detection + Escalation Check
+
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH, {ACTIONABLE_COUNT} actionable non-HIGH review concerns found`
+
+**Stall detection:** If `UNRESOLVED_COUNT >= prev_unresolved_count`:
+```text
+⚠ Convergence stalled — unresolved review concern count not decreasing
+  ({UNRESOLVED_COUNT} unresolved concerns, previous cycle had {prev_unresolved_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 and {ACTIONABLE_COUNT} actionable non-HIGH concerns remain:
+
+{HIGH_LINES}
+
+{ACTIONABLE_LINES}
+
+How would you like to proceed?
+
+1. Proceed anyway — Accept plans with remaining review 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 and {ACTIONABLE_COUNT} actionable non-HIGH concerns remain:\n\n{HIGH_LINES}\n\n{ACTIONABLE_LINES}\n\nHow would you like to proceed?",
+    header: "Convergence",
+    multiSelect: false,
+    options: [
+      { label: "Proceed anyway", description: "Accept plans with remaining review 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:  /pp:plan-phase {PHASE} --reviews
+To restart loop:     /pp:plan-review-convergence {PHASE} {REVIEWER_FLAGS}
+```
+Exit workflow.
+
+### 5d. Replan (Inline)
+
+**If under max cycles:**
+
+Update `prev_unresolved_count = UNRESOLVED_COUNT`.
+
+Display: `◆ Replanning inline with review feedback... (plan-phase runs here in the orchestrator — no output until replanning is complete, ~1–5 min; expected, not a freeze)`
+
+```text
+Skill(skill="pp-plan-phase", args="{PHASE} --reviews --skip-research {GSD_WS}")
+```
+
+Run plan-phase **inline** (do NOT wrap it in Agent()). Same rationale as step 4: the convergence orchestrator runs at depth 0 with Agent available, so inline plan-phase can spawn pp-planner and pp-plan-checker at depth 1. Wrapping in Agent() pushes plan-phase to depth 1 where the Agent tool is absent — the replan loop can never produce a revised plan when HIGHs are found. This is the root cause of bug #936. Actionable MEDIUM/LOW findings must be incorporated into executable PLAN.md content or explicitly deferred/rejected in the relevant PLAN.md before convergence can complete. Wait until plan-phase completes (outputs '## PLANNING COMPLETE') and updated PLAN.md files are committed before continuing.
+
+After plan-phase completes → 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 inline Skill("pp-plan-phase") if no plans exist — NOT wrapped in Agent() (bug #936: depth-1 Agent has no Agent tool)
+- [ ] Review via Agent → Skill("pp-review") — isolated Agent is correct; pp-review is a Bash leaf with no sub-agent spawns; {GSD_WS} forwarded
+- [ ] Replan via inline Skill("pp-plan-phase --reviews") — NOT wrapped in Agent(); inline lets plan-phase spawn pp-planner/pp-plan-checker at depth 1
+- [ ] Orchestrator only does: init, config gate, loop control, parse CYCLE_SUMMARY for HIGH and actionable non-HIGH counts, stall detection, escalation
+- [ ] HIGH and actionable non-HIGH counts extracted from review agent's CYCLE_SUMMARY return message (not by grepping REVIEWS.md)
+- [ ] Review agent prompt defines CYCLE_SUMMARY: current_high=<N> current_actionable=<M> contract with PARTIALLY/FULLY RESOLVED/ACTIONABLE 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
+- [ ] Abort with clear error if current_actionable is absent or malformed
+- [ ] Warn if ACTIONABLE_COUNT > 0 but ## Current Actionable Non-HIGH Concerns section is absent from return message
+- [ ] The review Agent fully completes pp-review before returning (plan-phase runs inline — no Agent wrap)
+- [ ] Loop exits on: no HIGH concerns and no actionable non-HIGH concerns (converged) OR max cycles (escalation)
+- [ ] Stall detection reported when total unresolved review concern count is not decreasing
+- [ ] STATE.md updated on convergence completion
+</success_criteria>

package/pp-core/workflows/plant-seed.md

@@ -0,0 +1,230 @@
+<purpose>
+Capture a forward-looking idea as a structured seed file with trigger conditions.
+Seeds auto-surface during /pp:new-milestone when trigger conditions match the
+new milestone's scope.
+
+Seeds beat deferred items because they:
+- Preserve WHY the idea matters (not just WHAT)
+- Define WHEN to surface (trigger conditions, not manual scanning)
+- Track breadcrumbs (code references, related decisions)
+- Auto-present at the right time via new-milestone scan
+
+**One-shot capture**: the seed file is written immediately from the idea text alone.
+Trigger / Why / Scope are optional enrichment — they can be provided now or added
+later. The file is never gated behind questions.
+</purpose>
+
+<process>
+
+<step name="parse-idea">
+Parse `$ARGUMENTS` for the idea summary.
+
+First, check for an enrich flag:
+
+```bash
+if echo "$ARGUMENTS" | grep -qE '\-\-enrich[[:space:]]+SEED-[0-9]+'; then
+  ENRICH_TARGET=$(echo "$ARGUMENTS" | grep -oE 'SEED-[0-9]+')
+  SEED_FILE=$(ls .planning/seeds/${ENRICH_TARGET}-*.md 2>/dev/null | head -1)
+  # Skip to enrich-seed step — do not prompt for $IDEA
+else
+  if [ -n "$ARGUMENTS" ]; then
+    IDEA="$ARGUMENTS"
+  else
+    # Ask only when no arguments at all
+    # What's the idea? (one sentence)
+    IDEA="<user response>"
+  fi
+fi
+```
+
+If `$ENRICH_TARGET` is set, skip straight to the `enrich-seed` step. Do not set `$IDEA` and do not run `create-seed-dir`, `generate-seed-id`, `write-seed`, `collect-breadcrumbs`, `commit-seed`, or `confirm`.
+
+If `$ARGUMENTS` is non-empty and contains no `--enrich` flag, treat the full value as `$IDEA` (no prompt).
+
+Only prompt for the idea when `$ARGUMENTS` is empty and no enrich target is present. Store the response as `$IDEA`.
+</step>
+
+<step name="create-seed-dir">
+```bash
+mkdir -p .planning/seeds
+```
+</step>
+
+<step name="generate-seed-id">
+```bash
+# Find next seed number
+EXISTING=$( (ls .planning/seeds/SEED-*.md 2>/dev/null || true) | wc -l )
+NEXT=$((EXISTING + 1))
+PADDED=$(printf "%03d" $NEXT)
+```
+
+Generate slug from idea summary.
+</step>
+
+<step name="write-seed">
+Write `.planning/seeds/SEED-{PADDED}-{slug}.md` immediately with sensible defaults:
+
+- `trigger_when`: default is `"when relevant"` — the seed will surface during any
+  new-milestone scan; the user can narrow it later via `--enrich`
+- `scope`: default is `"unknown"` — the user can update it via `--enrich`
+
+```markdown
+---
+id: SEED-{PADDED}
+status: dormant
+planted: {ISO date}
+planted_during: {current milestone/phase from STATE.md, or "unknown" if not in a GSD project}
+trigger_when: when relevant
+scope: unknown
+---
+
+# SEED-{PADDED}: {$IDEA}
+
+## Why This Matters
+
+_To be filled in. Run `/pp:capture --seed --enrich SEED-{PADDED}` to add context._
+
+## When to Surface
+
+**Trigger:** when relevant
+
+This seed will surface during `/pp:new-milestone` when the milestone scope matches.
+
+## Scope Estimate
+
+**Unknown** — run `/pp:capture --seed --enrich SEED-{PADDED}` to estimate effort.
+
+## Breadcrumbs
+
+_No breadcrumbs collected yet._
+
+## Notes
+
+_Captured via one-shot seed capture. Enrich with trigger, why, and scope at your convenience._
+```
+</step>
+
+<step name="collect-breadcrumbs">
+After writing the file, search the codebase for relevant references:
+
+Extract one or two key terms from `$IDEA` (the most distinctive noun or phrase) and store as `$KEYWORD`.
+
+```bash
+# Derive a single keyword for breadcrumb search.
+# Lower-case, strip punctuation, take the first token longer than 2 chars.
+KEYWORD=$(printf '%s' "$IDEA" \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr -cs 'a-z0-9' '\n' \
+  | awk 'length > 2 {print; exit}')
+KEYWORD="${KEYWORD:-seed}"  # fallback to literal "seed" if extraction yields nothing
+```
+
+```bash
+# Find files related to the idea keywords ($KEYWORD derived from $IDEA)
+grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
+```
+
+Also check:
+- Current STATE.md for related decisions
+- ROADMAP.md for related phases
+- todos/ for related captured ideas
+
+If any breadcrumbs are found, update the Breadcrumbs section of the seed file.
+Store relevant file paths as `$BREADCRUMBS`.
+</step>
+
+<step name="commit-seed">
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+pp_run query commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
+```
+</step>
+
+<step name="confirm">
+```text
+✅ Seed planted: SEED-{PADDED}
+
+"{$IDEA}"
+File: .planning/seeds/SEED-{PADDED}-{slug}.md
+
+Trigger and scope are set to defaults. Run `/pp:capture --seed --enrich SEED-{PADDED}`
+to add trigger conditions, rationale, and scope estimate at your convenience.
+
+This seed will surface automatically when you run /pp:new-milestone.
+```
+</step>
+
+<step name="enrich-seed">
+**Optional enrichment — only run this step when `--enrich` flag is present.**
+
+If `--enrich` flag is in `$ARGUMENTS`:
+- `$ENRICH_TARGET` and `$SEED_FILE` are already set by `parse-idea`. Derive `$SEED_ID` from `$ENRICH_TARGET` (e.g. `SEED_ID="$ENRICH_TARGET"`). If `$SEED_FILE` is empty, fall back to the most-recently modified file in `.planning/seeds/` and set `$SEED_ID` from its filename.
+- Ask focused questions to build a complete seed:
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** 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. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
+```text
+AskUserQuestion(
+  header: "Trigger",
+  question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
+  options: []  // freeform
+)
+```
+
+Store as `$TRIGGER`.
+
+```text
+AskUserQuestion(
+  header: "Why",
+  question: "Why does this matter? What problem does it solve or what opportunity does it create?",
+  options: []
+)
+```
+
+Store as `$WHY`.
+
+```text
+AskUserQuestion(
+  header: "Scope",
+  question: "How big is this? (rough estimate)",
+  options: [
+    { label: "Small", description: "A few hours — could be a quick task" },
+    { label: "Medium", description: "A phase or two — needs planning" },
+    { label: "Large", description: "A full milestone — significant effort" }
+  ]
+)
+```
+
+Store as `$SCOPE`.
+
+Update the seed file's frontmatter and sections with the gathered values:
+- Set `trigger_when: {$TRIGGER}`
+- Set `scope: {$SCOPE}`
+- Fill in `## Why This Matters` with `{$WHY}`
+- Fill in `## When to Surface` trigger detail
+- Fill in `## Scope Estimate` elaboration
+
+Commit the update:
+```bash
+pp_run query commit "docs: enrich seed ${SEED_ID} — trigger + why + scope" --files "$SEED_FILE"
+```
+
+Confirm:
+```text
+✅ Seed enriched: ${SEED_ID}
+Trigger: {$TRIGGER}
+Scope: {$SCOPE}
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Seed file created in .planning/seeds/ in one step, no questions required
+- [ ] Frontmatter includes status, trigger_when (default: "when relevant"), scope (default: "unknown")
+- [ ] File is written BEFORE any optional enrichment questions are asked
+- [ ] Committed to git
+- [ ] User shown confirmation with file path
+- [ ] Optional --enrich path available for adding trigger, why, scope post-capture
+</success_criteria>