@opengsd/gsd-core 1.19.0 → 1.20.0

package/gsd-core/workflows/review.md

@@ -31,7 +31,7 @@ command -v kimi >/dev/null 2>&1 && echo "kimi-code:available" || echo "kimi-code
 # hosts and defaults come from each lane's descriptor
 gsd_run review-lane availability || { echo "WARNING: review-lane availability failed or is unsupported by this gsd-tools; treating local lanes as missing" >&2; printf 'ollama:missing\nlm_studio:missing\nllama_cpp:missing\n'; }
 
-# jq prerequisite (#2589). The config/model/budget lookups in this workflow no
+# jq prerequisite (#2589). The config/model lookups in this workflow no
 # longer need jq — they use the native --raw/--pick flags. But the lanes listed
 # under "jq-dependent reviewer lanes" below parse structured JSON that gsd-tools
 # does not emit (OpenAI-compatible /v1/chat/completions responses, opencode's
@@ -245,7 +245,7 @@ Output your review in markdown format.
 
 Write to a temp file: `{run_dir}/gsd-review-prompt.md`
 
-Also write individual section files so the budget tool can re-trim per reviewer:
+Append the plan coverage manifest to the prompt:
 
 ```bash
 # #2962: zsh aborts the block on an unmatched for-list glob (nomatch); bash passes it through. nullglob both.
@@ -253,38 +253,21 @@ shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null
 
 RUN_DIR="{run_dir}"   # from gather_context
 
-# Write individual section files for per-reviewer budget trimming
-# These are always written so reviewers with a budget can invoke prompt-budget
-cp "$INSTRUCTIONS_BLOCK_FILE" "${RUN_DIR}/gsd-review-instructions.md"
-cp "$ROADMAP_SECTION_FILE" "${RUN_DIR}/gsd-review-roadmap.md"
-
-# Plan files: copy each PLAN.md to a predictable path named after its source
-# plan id (#3959: a bare padded index discards provenance — the budget tool's
-# per-plan `### <file>` header then renders a run-dir artifact name no reviewer
-# or consensus step can resolve. The plan id keeps the gsd-review-plan-*.md glob
-# prepare_trimmed_prompt_for_reviewer consumes.)
-for PLAN_FILE in "${PHASE_DIR}"/*-PLAN.md; do
-  PLAN_BASENAME=$(basename "$PLAN_FILE")
-  PLAN_ID="${PLAN_BASENAME%-PLAN.md}"
-  cp "$PLAN_FILE" "${RUN_DIR}/gsd-review-plan-${PLAN_ID}.md"
-done
-
 # #3301: plan coverage manifest — tell reviewers exactly which plan ids exist and
 # how many there are, so a review that silently covers 6 of 7 plans is no longer
 # indistinguishable from one that covers all 7. The id is the plan file's own
 # basename with the `-PLAN.md` suffix stripped (e.g. `12.6-01-PLAN.md` ->
 # `12.6-01`) — NOT the `plan:` frontmatter key, which holds only the bare
 # in-phase sequence number ("01") and can never reconstruct the phase-qualified
-# id reviewers need to cite. The filename is guaranteed present for every copied
-# plan, so no plan is ever dropped from the manifest for lacking a key.
+# id reviewers need to cite. The filename is guaranteed present for every plan,
+# so no plan is ever dropped from the manifest for lacking a key.
 # Count and bullets are both derived directly from the glob loop below, never
 # from re-splitting an accumulated string: bash word-splits an unquoted `$VAR`
 # on IFS by default, but zsh does not (no `setopt SH_WORD_SPLIT` here), so a
 # prior `PLAN_IDS="$PLAN_IDS $id"` + `for x in $PLAN_IDS` round-trip silently
 # collapsed every id onto one iteration under zsh whenever there were 2+ plans
-# (gsd-core#4099). Direct glob iteration (`for f in "${PHASE_DIR}"/*-PLAN.md`,
-# same pattern as the copy loop above) is identical under both shells, so this
-# never needs word-splitting at all.
+# (gsd-core#4099). Direct glob iteration (`for f in "${PHASE_DIR}"/*-PLAN.md`)
+# is identical under both shells, so this never needs word-splitting at all.
 PLAN_COUNT=0
 PLAN_ID_BULLETS=""
 for PLAN_FILE in "${PHASE_DIR}"/*-PLAN.md; do
@@ -295,10 +278,8 @@ for PLAN_FILE in "${PHASE_DIR}"/*-PLAN.md; do
 "
 done
 
-# Named to avoid BOTH existing RUN_DIR globs: `gsd-review-*.md` (reviewer
-# reports, invoke_reviewers) and `gsd-review-plan-*.md` (the plan copies just
-# above) — a manifest matching either would be picked up as a report or as a
-# plan to review.
+# Dot-prefixed so the `gsd-review-*.md` glob over RUN_DIR (reviewer reports,
+# invoke_reviewers) can never pick it up as a report.
 {
   echo ""
   echo "## Plan Coverage Manifest"
@@ -309,33 +290,11 @@ done
   printf '%s' "$PLAN_ID_BULLETS"
 } > "${RUN_DIR}/.plans-manifest.md"
 
-# Optional section files (only if content was included in the combined prompt)
-if [ -f ".planning/PROJECT.md" ]; then
-  cp .planning/PROJECT.md "${RUN_DIR}/gsd-review-project.md"
-fi
-_CTX=( "${PHASE_DIR}"/*-CONTEXT.md )
-if [ ${#_CTX[@]} -gt 0 ]; then
-  cat "${_CTX[@]}" > "${RUN_DIR}/gsd-review-context.md"
-fi
-_RESEARCH=( "${PHASE_DIR}"/*-RESEARCH.md )
-if [ ${#_RESEARCH[@]} -gt 0 ]; then
-  cat "${_RESEARCH[@]}" > "${RUN_DIR}/gsd-review-research.md"
-fi
-if [ -f ".planning/REQUIREMENTS.md" ]; then
-  cp .planning/REQUIREMENTS.md "${RUN_DIR}/gsd-review-requirements.md"
-fi
-
-# #3301: append the manifest to BOTH files reviewers actually read — the
-# per-lane budget-trimmed instructions file (descriptor lanes get
-# `--instructions-file`) and the full combined prompt (combined-prompt lanes
-# read the whole file). The `instructions` fragment is in prompt-budget's
-# `minimumFor` floor set and is never trimmed, so this survives per-lane
-# budget trimming intact.
-cat "${RUN_DIR}/.plans-manifest.md" >> "${RUN_DIR}/gsd-review-instructions.md"
+# #3301: append the manifest to the one prompt file every lane reads.
 cat "${RUN_DIR}/.plans-manifest.md" >> "${RUN_DIR}/gsd-review-prompt.md"
 ```
 
-Note: `INSTRUCTIONS_BLOCK_FILE`, `ROADMAP_SECTION_FILE`, and `PHASE_DIR` come from prompt assembly; `RUN_DIR` is the run-scoped dir from `gather_context` (#2358) re-assigned from `{run_dir}` above. Copy the temp files written during prompt assembly to these section paths (or write each section here if the prompt was built inline).
+Note: `PHASE_DIR` comes from prompt assembly; `RUN_DIR` is the run-scoped dir from `gather_context` (#2358) re-assigned from `{run_dir}` above. Every lane receives `gsd-review-prompt.md` whole — it is never trimmed per lane (#4559). A lane whose prompt exceeds its cap is refused in `invoke_reviewers`, not shortened.
 </step>
 
 <step name="invoke_reviewers">
@@ -408,35 +367,6 @@ REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 # user's intent; here it would fire exactly the requests the default exists to prevent.
 PARALLEL_LANES=$(gsd_run query config-get review.parallel_lanes --raw 2>/dev/null || echo "false")
 
-# Shared budget-trim helper. Was defined inside the Ollama leg; it is lane-agnostic, so it is
-# hoisted here now that any lane may declare a promptBudgetKey. Returns non-zero when the budget
-# is too small for the minimum review set (prompt-budget exit 2 / 11).
-prepare_trimmed_prompt_for_reviewer() {
-  REVIEWER_KEY="$1"; REVIEWER_BUDGET="$2"; OUTPUT_PROMPT="$3"; OUTPUT_META="$4"
-
-  PLAN_FILE_ARGS=""
-  for p in "$RUN_DIR"/gsd-review-plan-*.md; do
-    [ -f "$p" ] && PLAN_FILE_ARGS="$PLAN_FILE_ARGS --plan-file $p"
-  done
-  PROJECT_ARG=""
-  [ -f "$RUN_DIR/gsd-review-project.md" ] && PROJECT_ARG="--project-file $RUN_DIR/gsd-review-project.md"
-  CONTEXT_ARG=""
-  [ -f "$RUN_DIR/gsd-review-context.md" ] && CONTEXT_ARG="--context-file $RUN_DIR/gsd-review-context.md"
-  RESEARCH_ARG=""
-  [ -f "$RUN_DIR/gsd-review-research.md" ] && RESEARCH_ARG="--research-file $RUN_DIR/gsd-review-research.md"
-  REQUIREMENTS_ARG=""
-  [ -f "$RUN_DIR/gsd-review-requirements.md" ] && REQUIREMENTS_ARG="--requirements-file $RUN_DIR/gsd-review-requirements.md"
-
-  gsd_run query prompt-budget \
-    --budget "$REVIEWER_BUDGET" \
-    --instructions-file "$RUN_DIR/gsd-review-instructions.md" \
-    --roadmap-file "$RUN_DIR/gsd-review-roadmap.md" \
-    $PLAN_FILE_ARGS $PROJECT_ARG $CONTEXT_ARG $RESEARCH_ARG $REQUIREMENTS_ARG \
-    --output-prompt "$OUTPUT_PROMPT" \
-    --output-metadata "$OUTPUT_META"
-  return $?
-}
-
 gsd_run query review-lane plan \
   --selected "$SELECTED_REVIEWERS" --run-dir "$RUN_DIR" --repo-root "$REPO_ROOT" --json \
   > "$RUN_DIR/gsd-review-lanes.json"
@@ -453,36 +383,18 @@ run_review_lane() {
   # `local` is hygiene, not a live fix: each `&`-dispatched call already forks its own subshell, so
   # concurrent lanes cannot share these today. Scoped anyway so the isolation is a property of this
   # function rather than of the dispatch mechanism happening to fork.
-  local SLUG LANE_BUDGET PROMPT_ARG TRIMMED
+  local SLUG
   SLUG="$1"
-  # Per-lane prompt budget. The lane declares its own `promptBudgetKey`; `plan` resolved it,
-  # applying #2797's sentinel rule (-1 = unset → fall back to the global budget; 0 legitimately
-  # means "do not trim this lane"). Trimming itself stays in prompt-budget, which owns it.
-  LANE_BUDGET=$(gsd_run query review-lane plan --selected "$SLUG" --run-dir "$RUN_DIR" \
-                  --repo-root "$REPO_ROOT" --json 2>/dev/null \
-                | sed -n 's/.*"promptBudget": *\([0-9-]*\).*/\1/p' | head -1)
-  PROMPT_ARG=""
-  if [ -n "$LANE_BUDGET" ] && [ "$LANE_BUDGET" != "null" ] && [ "$LANE_BUDGET" -gt 0 ] 2>/dev/null; then
-    TRIMMED="$RUN_DIR/gsd-review-prompt-$SLUG.md"
-    if prepare_trimmed_prompt_for_reviewer "$SLUG" "$LANE_BUDGET" "$TRIMMED" \
-         "$RUN_DIR/gsd-review-prompt-$SLUG.metadata.json"; then
-      PROMPT_ARG="--prompt-file $TRIMMED"
-    else
-      # A budget too small for the minimum review set drops the lane just as silently as an empty
-      # response used to (#2605), so leave the skip visible in the review output, not only on stderr.
-      echo "$SLUG review skipped: prompt budget (${LANE_BUDGET} tokens) too small for the minimum review set." \
-        > "$RUN_DIR/gsd-review-$SLUG.md"
-      # Was `continue` when this was a loop body. Inside a function that keyword is not the loop
-      # control it looks like — `return 0` is what skips this lane and leaves it with no result line.
-      return 0
-    fi
-  fi
+  # #4559: no per-lane trimming. Every lane receives the whole prompt; `review-lane invoke` measures it
+  # against the lane's cap (its own `promptBudgetKey`, the global `review.max_prompt_tokens`, or the
+  # default derived from its declared context window) and REFUSES a lane that is over, writing a
+  # `review did not run: prompt exceeds` stub. A trimmed prompt reviewed something other than the plans.
 
   # One invocation, whatever the lane's transport, prompt channel, output channel or handler.
   # `--explicit` marks a lane the user NAMED: ADR-2782 D4 — not finding a lane nobody asked for is
   # normal, failing to run one somebody asked for is an error.
   gsd_run query review-lane invoke --slug "$SLUG" \
-    --run-dir "$RUN_DIR" --repo-root "$REPO_ROOT" $PROMPT_ARG $EXPLICIT_FLAG --json \
+    --run-dir "$RUN_DIR" --repo-root "$REPO_ROOT" $EXPLICIT_FLAG --json \
     > "$RUN_DIR/gsd-review-lane-result-$SLUG.json"
 }
 
@@ -527,13 +439,17 @@ wait
 
 # Aggregate in SELECTED_REVIEWERS order, NOT completion order, so the JSONL a concurrent run
 # produces is byte-identical to the one a sequential run produces. This is post-join and therefore
-# single-threaded, so `>>` here is safe. A lane that was budget-skipped, or that never started,
-# leaves no result file and correctly contributes no line.
+# single-threaded, so `>>` here is safe. A lane that never started leaves no result file, and a lane
+# REFUSED for its prompt cap (#4559: reason `prompt_exceeds_context`) is deliberately left out of the
+# aggregate — it did not run, so it must not count as a lane result or feed models:/model_sources:.
+# Its own result file stays in RUN_DIR for the `refused_reviewers` frontmatter.
 # Rewrapped through unquoted command substitution (gsd-core#4109) — see the
 # dispatch loop above for why a bare `$DISPATCH_SLUGS` collapses under zsh.
 for SLUG in $(printf '%s' "$DISPATCH_SLUGS"); do
   LANE_RESULT="$RUN_DIR/gsd-review-lane-result-$SLUG.json"
-  if [ -f "$LANE_RESULT" ]; then
+  # The refusal is the PARSED `reason` field — a failed lane whose `detail` merely mentions the
+  # string is a real lane result and must stay in the aggregate.
+  if [ -f "$LANE_RESULT" ] && ! node -e 'try{process.exit(JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).reason==="prompt_exceeds_context"?0:1)}catch{process.exit(1)}' "$LANE_RESULT"; then
     cat "$LANE_RESULT" >> "$RUN_DIR/gsd-review-lane-results.jsonl"
   fi
 done
@@ -546,7 +462,9 @@ review: it keeps its "failed or returned empty output" header (#2494/#2605/#2794
 
 A lane that will not run reports a typed reason rather than an empty file — `missing_binary`,
 `probe_failed`, `probe_timeout`, `missing_required_binary`, `host_unreachable`,
-`egress_host_changed`, `unknown_handler`, `budget_too_small`. **`egress_host_changed` means the lane
+`egress_host_changed`, `unknown_handler`, `prompt_exceeds_context` (the prompt is over
+the lane's cap — refused, never trimmed; its review file carries a `review did not run: prompt exceeds` stub).
+**`egress_host_changed` means the lane
 was consented to send plans to one destination and `.planning/config.json` now names another; it is
 blocked, not silently redirected** (ADR-2782 D5).
 
@@ -563,7 +481,7 @@ Display progress:
 **#3352 (ADR-3473 §8.5): no artifact from failed inputs.** Before rendering anything, gate on
 whether any lane actually produced a result — "every lane failed" is exactly "the aggregate
 JSONL has zero lines" (§`invoke_reviewers`'s aggregation loop already builds this file as a
-byproduct; a lane that never started or was budget-skipped contributes no line either way).
+byproduct; a lane that never started or was refused for its prompt cap contributes no line either way).
 
 ```bash
 RUN_DIR="{run_dir}"
@@ -575,7 +493,7 @@ TOTAL_LANE_FAILURE="false"
 ALL_LANES_SKIPPED="false"
 if [ "${LANE_LINES:-0}" -eq 0 ]; then
   # Zero lines means every dispatched lane left no result JSON — either every one
-  # was budget-skipped (N5: a skip is not a failure) or every one actually failed
+  # was refused for its prompt cap (N5: a refusal is not a failure) or every one actually failed
   # to run. Re-derive the dispatched-slug set the same way invoke_reviewers did
   # (SELECTED_REVIEWERS is a shell block boundary — recompute, do not assume the
   # earlier step's local DISPATCH_SLUGS variable survived into this block).
@@ -586,10 +504,10 @@ if [ "${LANE_LINES:-0}" -eq 0 ]; then
     esac
     DISPATCH_SLUGS="$DISPATCH_SLUGS $SLUG"
   done
-  # Distinguish by whether every dispatched slug's stub markdown says "skipped":
-  # a skip stub always does (see run_review_lane's budget branch, which writes
-  # this exact text before returning without ever invoking the lane); a real
-  # failure stub does not. If a slug has no stub at all, it is not a skip.
+  # Distinguish by whether every dispatched slug's stub markdown carries the refusal marker:
+  # `review-lane invoke` writes `review did not run: prompt exceeds ...` (#4559) before returning
+  # without ever probing or spawning the lane; a real failure stub does not. If a slug has no
+  # stub at all, it is not a refusal.
   DISPATCHED_COUNT=0
   SKIPPED_COUNT=0
   # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
@@ -598,7 +516,7 @@ if [ "${LANE_LINES:-0}" -eq 0 ]; then
   for SLUG in $(printf '%s' "$DISPATCH_SLUGS"); do
     DISPATCHED_COUNT=$((DISPATCHED_COUNT + 1))
     STUB="$RUN_DIR/gsd-review-$SLUG.md"
-    if [ -f "$STUB" ] && grep -q "review skipped: prompt budget" "$STUB" 2>/dev/null; then
+    if [ -f "$STUB" ] && grep -q "review did not run: prompt exceeds" "$STUB" 2>/dev/null; then
       SKIPPED_COUNT=$((SKIPPED_COUNT + 1))
     fi
   done
@@ -611,15 +529,16 @@ fi
 ```
 
 - **If `ALL_LANES_SKIPPED=true`:** do NOT write `REVIEWS.md` and do NOT run the commit below —
-  there is nothing to review. Report to the user that every selected lane was budget-skipped
-  (not a failure) and stop; do not proceed to `present_results`' summary claiming a review ran.
+  there is nothing to review. Report to the user that every selected lane refused its prompt cap
+  (not a failure; name the cap and the `review.context_window_tokens.<slug>` /
+  `review.max_prompt_tokens_per_reviewer.<slug>` keys that raise it) and stop; do not proceed to `present_results`' summary claiming a review ran.
 - **If `TOTAL_LANE_FAILURE=true`:** do NOT write `REVIEWS.md` and do NOT run the commit below.
   Report the total lane failure to the user (name the lanes that were dispatched and point at
   their `.err`/stub files preserved under `.review-diagnostics/` by `present_results`) and stop.
 - **Otherwise** (at least one lane produced a result — R1, unchanged): proceed exactly as below.
 
 **#3301: plan coverage check.** For each dispatched lane that produced a *real* review (not a
-stub, not budget-skipped, not empty), check whether its output mentions every plan id from
+stub, not refused for its prompt cap, not empty), check whether its output mentions every plan id from
 `.plans-manifest.md` — the same manifest `build_prompt` gave the reviewer, so the expected-id list
 here can never diverge from what the reviewer was actually told. This is diagnostic only: it never
 blocks the workflow, never fails a lane, and never changes the `TOTAL_LANE_FAILURE`/
@@ -673,7 +592,7 @@ for SLUG in $(printf '%s' "$DISPATCH_SLUGS"); do
   REVIEW_FILE="$RUN_DIR/gsd-review-$SLUG.md"
   [ -f "$REVIEW_FILE" ] || continue
   [ -s "$REVIEW_FILE" ] || continue
-  grep -q "review skipped: prompt budget" "$REVIEW_FILE" 2>/dev/null && continue
+  grep -q "review did not run: prompt exceeds" "$REVIEW_FILE" 2>/dev/null && continue
   grep -q "failed or returned empty output" "$REVIEW_FILE" 2>/dev/null && continue
 
   node -e '
@@ -696,7 +615,7 @@ done
 
 Each `${RUN_DIR}/.plan-coverage-<slug>.json` carries `{complete, missing_ids, total}` for one
 graded lane. Collect these into a `plan_coverage` frontmatter block — **only** when at least one
-graded lane has `complete: false` (mirrors the existing `trimmed_reviewers` precedent: present
+graded lane has `complete: false` (mirrors the `refused_reviewers` precedent: present
 only when there is something to report):
 
 ```yaml
@@ -714,7 +633,7 @@ heading and before the end of the first exact `<!-- gsd:plan-revision-conflicts:
 as `{preserved_plan_revision_conflict_entries}`. Ignore identical headings or delimiters in reviewer
 output: reviewers do not own blocking state. Restore the captured bytes at the explicit slot below.
 
-After all reviewers complete, collect trim metadata files written during the run. For each reviewer that was trimmed (i.e. a `.metadata.json` file exists and `hardFailed` or `omitted` is non-empty, or `projectMdShrunk` is true, or `planTruncationPct > 0`), include a `trimmed_reviewers` block in the frontmatter. Omit the key entirely if no reviewer was trimmed.
+After all reviewers complete, collect the lanes that were refused for their prompt cap (#4559): each dispatched lane whose `${RUN_DIR}/gsd-review-lane-result-<slug>.json` has `"reason": "prompt_exceeds_context"`. For each, include a `refused_reviewers` entry in the frontmatter with `estimated_tokens`, `cap` and `cap_source` copied from that file's `refusal` object (`estimatedTokens`, `cap`, `capSource`). Omit the key entirely if no lane was refused. A refused lane's section in the body renders its `review did not run: prompt exceeds` stub, never an empty section.
 
 **Reviewer instances (#1517, optional):** when instances ran, frontmatter records their
 names, each gets its own `## <Adapter> Review (<instance>)` section, and ≥2 same-cli
@@ -746,16 +665,11 @@ models:                   # resolved model per reviewer; `unknown` when not reco
 model_sources:            # how each value above was determined
   codex: "banner"
   antigravity: "unknown"
-trimmed_reviewers:        # only present if at least one reviewer was trimmed
+refused_reviewers:        # only present if at least one lane was refused for its prompt cap (#4559)
   ollama:
-    budget: 6000
-    effective_budget: 5400
-    estimated_tokens: 5380
-    omitted: [context, research]
-    project_md_shrunk: true
-    plan_truncation_pct: 22
-    hard_failed: false
-    note_injected: true
+    estimated_tokens: 61000
+    cap: 6000
+    cap_source: lane      # lane | global | context-window
 plan_coverage:            # only present if at least one graded lane is incomplete (#3301)
   ollama:
     total: 7
@@ -819,7 +733,7 @@ present as complete. Report instead:
 ```
 ### GSD ► REVIEW FAILED
 
-Phase {N}: every selected reviewer lane {failed to produce a result|was budget-skipped} — no
+Phase {N}: every selected reviewer lane {failed to produce a result|refused its prompt cap} — no
 REVIEWS.md was written.
 
 {If the preserve+cleanup block below reports success: "Diagnostics preserved:
@@ -852,11 +766,9 @@ step names only `{padded_phase}-REVIEWS.md` explicitly, never a directory glob,
 `.review-diagnostics/` is never swept into it.
 
 **#4097: preserve lane OUTPUT, never the run's own input copies.** `RUN_DIR` holds not only
-lane outputs — prompt assembly (the `gather_context`/section-copy step above) also writes the
-run's assembled INPUTS there under the same `gsd-review-` prefix: the combined prompt, the
-instructions/roadmap sections, a copy of every plan under review, the project/context/research/
-requirements sections, and the per-lane trimmed prompts. Those are byte-identical duplicates of
-files already committed under `.planning/`; sweeping them into `.review-diagnostics/` buries
+lane outputs — prompt assembly also writes the run's assembled INPUT there under the same
+`gsd-review-` prefix: the combined prompt (`gsd-review-prompt.md`). It duplicates files already
+committed under `.planning/`; sweeping them into `.review-diagnostics/` buries
 the actual evidence under plan duplicates and grows the phase directory on every run. The
 exclusion list below is CLOSED and owned here: this workflow itself writes every input
 basename at prompt-assembly time, so a future input file CANNOT silently join the evidence
@@ -882,8 +794,10 @@ DIAG_DIR="{phase_dir}/.review-diagnostics"
 # the closed input set this workflow itself writes — direct glob iteration with a `case`
 # filter, no string accumulator, identical under bash and zsh (#4099/#4109), and the
 # `nullglob` set at the top of this fence keeps an empty RUN_DIR an empty array (#2962).
-# `gsd-review-prompt*` deliberately covers BOTH the combined prompt (`gsd-review-prompt.md`)
-# and the per-lane trimmed prompts (`gsd-review-prompt-<slug>.md`).
+# `gsd-review-prompt*` is the one input file this workflow now writes (#4559 removed the
+# per-lane trimmed prompts and the section copies). The section-copy names stay excluded:
+# a run dir reused from an earlier GSD version can still hold them, and they are inputs,
+# not lane evidence.
 _DIAG_MD=()
 for f in "$RUN_DIR"/gsd-review-*.md; do
   case "$(basename "$f")" in
@@ -908,9 +822,8 @@ if [ ${#_DIAG_MD[@]} -gt 0 ] || [ ${#_DIAG_ERR[@]} -gt 0 ]; then
   # unique per run BY CONSTRUCTION — uniqueness never depends on the clock. The
   # UTC stamp is only a sort key in front of it, and is omitted entirely if `date`
   # fails. Lane basenames are unchanged INSIDE the subdirectory, so evidence still
-  # correlates back to its lane, and nothing inside $RUN_DIR is renamed (both
-  # `prepare_trimmed_prompt_for_reviewer` and the lane invocation resolver depend
-  # on those exact basenames).
+  # correlates back to its lane, and nothing inside $RUN_DIR is renamed (the
+  # lane invocation resolver depends on those exact basenames).
   _DIAG_STAMP="$(date -u +%Y%m%dT%H%M%SZ 2>/dev/null || true)"
   _DIAG_RUN_DIR="$DIAG_DIR/${_DIAG_STAMP:+${_DIAG_STAMP}-}$(basename "$RUN_DIR")"
   # `mkdir -p` still creates $DIAG_DIR itself, so a plain FILE sitting at

package/gsd-core/workflows/secure-phase.md

@@ -181,7 +181,7 @@ gsd_run query commit "docs(phase-${PHASE}): add/update security threat verificat
 GSD > PHASE {N} THREAT-SECURE
 threats_open: 0 — no blocking threats remain (threats_open: 0).
 ▶ /gsd:validate-phase {N}    validate test coverage
-▶ /gsd:verify-work {N}       run UAT
+▶ /gsd:verify-work {N}       run UAT; once UAT and verification pass it marks the phase complete (ROADMAP + STATE); if it refuses on stale verification, re-run /gsd:execute-phase {N} then verify again
 ```
 
 Display `/clear` reminder.

package/gsd-core/workflows/settings-advanced.md

@@ -1,8 +1,7 @@
 Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
 
 <purpose>
-Interactive configuration of GSD power-user knobs — plan bounce, planner stall detection, node
-repair, subagent timeouts, inline plan threshold, cross-AI execution, base branch, branch templates, response language,
+Interactive configuration of GSD power-user knobs — plan bounce, planner stall detection and timing, node repair, subagent timeouts, inline plan threshold, cross-AI execution, base branch, branch templates, response language,
 context window, gitignored search, graphify build timeout, runtime model tier overrides, and
 model policy configuration (provider + budget → canonical tier mapping, or manual model ID
 assignment per cost tier).
@@ -50,6 +49,8 @@ shown in parentheses:
 
 Planning Tuning:
 - `planner.stall_detection_enabled` (default: `true`)
+- `planner.stall_threshold_minutes` (default: `10`)
+- `planner.stall_detect_interval_minutes` (default: `5`)
 - `workflow.plan_bounce` (default: `false`)
 - `workflow.plan_bounce_passes` (default: `2`)
 - `workflow.plan_bounce_script` (default: `null`)
@@ -106,10 +107,10 @@ in `$ARGUMENTS` OR `text_mode` is true in config. When `TEXT_MODE=true`, replace
 choice number or free-text value.
 
 **Numeric-input validation.** For any numeric field (`*_passes`, `*_budget`, `*_timeout`,
-`*_threshold`, `context_window`, `graphify.build_timeout`), if the user types a value that
+`*_threshold`, `*_minutes`, `context_window`, `graphify.build_timeout`), if the user types a value that
 is not a non-negative integer, the workflow MUST reject it, state which value was invalid,
 and re-prompt that single field. The minimum accepted value is field-specific and is stated
-in each field's prompt below — `workflow.plan_bounce_passes` and `workflow.max_discuss_passes`
+in each field's prompt below — the `*_passes` fields and the `planner.stall_*_minutes` fields
 require `>= 1`; all other numeric fields accept `>= 0`. An empty input means "keep current"
 — the existing value is retained. Non-numeric input is never silently coerced.
 
@@ -127,7 +128,9 @@ stored verbatim as a string.
 
 ### Section 1 — Planning Tuning
 
-Before offering the disabled choice, display this warning verbatim:
+Asked as four calls, 1a–1d (`AskUserQuestion` takes at most 4 questions per call).
+
+**1a — Planner watchdog.** Before offering the disabled choice, display this warning verbatim:
 
 `Warning: disabling planner stall detection gives up bounded automatic recovery if the runtime loses an agent completion handoff. Planning still waits through the runtime-native completion mechanism, but you may need to interrupt and use the filesystem fallback.`
 
@@ -141,7 +144,40 @@ AskUserQuestion([
       { label: "Yes (default: true)", description: "Poll for completion markers and plan-file activity, with bounded recovery." },
       { label: "No (false)", description: "Await runtime-native completion without polling. Gives up bounded automatic recovery if completion handoff is lost." }
     ]
+  }
+])
+```
+
+**1b — Stall timing.** Ask only when `planner.stall_detection_enabled` is effectively `true` after 1a (anything but boolean `false`); otherwise skip 1b.
+`planner.stall_threshold_minutes`: idle time before plan-phase offers recovery; raise it for slow models. `planner.stall_detect_interval_minutes`: check cadence. Both integer `>= 1`.
+
+```text
+AskUserQuestion([
+  {
+    question: "Planner stall threshold (minutes)? (current: <value or 10>)",
+    header: "Stall Threshold",
+    multiSelect: false,
+    options: [
+      { label: "Keep current", description: "Leave the threshold unchanged." },
+      { label: "Enter minutes", description: "Integer >= 1. Default: 10." }
+    ]
   },
+  {
+    question: "Planner stall check interval (minutes)? (current: <value or 5>)",
+    header: "Stall Interval",
+    multiSelect: false,
+    options: [
+      { label: "Keep current", description: "Leave the interval unchanged." },
+      { label: "Enter minutes", description: "Integer >= 1. Default: 5." }
+    ]
+  }
+])
+```
+
+**1c — Plan bounce.**
+
+```text
+AskUserQuestion([
   {
     question: "Run external plan-bounce validator against generated PLAN.md? (current: <value or false>)",
     header: "Plan Bounce",
@@ -169,7 +205,14 @@ AskUserQuestion([
       { label: "Clear (null)", description: "Unset the script path." },
       { label: "Enter path", description: "Type an absolute or repo-relative path. Receives PLAN.md path as first argument." }
     ]
-  },
+  }
+])
+```
+
+**1d — Timeouts.**
+
+```text
+AskUserQuestion([
   {
     question: "Subagent timeout (milliseconds)? (current: <value or 300000>)",
     header: "Subagent Timeout",
@@ -180,12 +223,12 @@ AskUserQuestion([
     ]
   },
   {
-    question: "Inline plan threshold — tasks allowed inline before splitting to PLAN.md? (current: <value or 3>)",
+    question: "Inline plan threshold — plans with this many tasks or fewer execute inline instead of spawning a subagent? (current: <value or 2>)",
     header: "Inline Plan Threshold",
     multiSelect: false,
     options: [
       { label: "Keep current", description: "Leave threshold unchanged." },
-      { label: "Enter number", description: "Integer count. Non-numeric rejected. Default: 3" }
+      { label: "Enter number", description: "Integer >= 0. Non-numeric rejected. Default: 2. Set 0 to always spawn a subagent." }
     ]
   }
 ])
@@ -535,7 +578,9 @@ anything not listed in Sections 1–8 MUST survive the update):
   ...existing_config,
   "planner": {
     ...existing_planner,
-    "stall_detection_enabled": <new|existing>
+    "stall_detection_enabled": <new|existing>,
+    "stall_threshold_minutes": <new|existing>,
+    "stall_detect_interval_minutes": <new|existing>
   },
   "workflow": {
     ...existing_workflow,
@@ -772,6 +817,8 @@ Display:
 | Setting                                    | Value |
 |--------------------------------------------|-------|
 | planner.stall_detection_enabled            | {true/false} |
+| planner.stall_threshold_minutes            | {minutes} |
+| planner.stall_detect_interval_minutes      | {minutes} |
 | workflow.plan_bounce                       | {on/off} |
 | workflow.plan_bounce_passes                | {n} |
 | workflow.plan_bounce_script                | {path/null} |
@@ -826,6 +873,7 @@ UI/AI phase gates), use /gsd:settings.
 - [ ] Eight sections rendered (Planning, Execution, Discussion, Cross-AI, Git, Runtime/Output, Runtime Model Tiers, Model Policy)
 - [ ] Every field pre-selected to its current value (or documented default if absent)
 - [ ] Disabling planner stall detection shows the bounded-recovery warning before writing `false`
+- [ ] Stall threshold/interval asked only while stall detection is on; no call exceeds 4 questions
 - [ ] Numeric inputs validated — non-numeric rejected and re-prompted
 - [ ] Branch-template inputs validated — non-default must contain a placeholder
 - [ ] Null-allowed fields accept an empty input as a clear

package/gsd-core/workflows/ship.md

@@ -73,6 +73,18 @@ Verify the work is ready to ship:
    ```
    Present `$NEXT_ACTION` to the user and, when `$NEXT_COMMAND` is non-empty, show it as the command to run next. These two are message text only — the block/allow decision has already been made from `$STATUS`, so a concurrent write between the reads cannot change the gate's verdict. The query already covers every status in its closed set, so no per-status arm is needed.
 
+1a. **Phase marked complete?** (#5221) Verified is not complete: `/gsd:verify-work` completes the phase.
+   ```bash
+   ANALYZE=$(gsd_run query roadmap.analyze ${GSD_WS:+--ws=${GSD_WS##* }}) || { echo "roadmap.analyze failed — see the error above" >&2; exit 1; }
+   if [[ "$ANALYZE" == @file:* ]]; then ANALYZE=$(cat "${ANALYZE#@file:}"); fi
+   # roadmap_record: phase -> every ROADMAP record of it reads complete. Fail closed: only true ships.
+   VERDICT=$(jq -er --arg p "$PHASE_NUMBER" 'def n:split(".")|map(sub("^0+(?=[0-9])";""))|join(".");if .error=="ROADMAP.md not found" then "skip" elif has("roadmap_record")|not then error("no roadmap_record") else .roadmap_record as $r|($p|n) as $k|if $r==null then "unreadable" elif ($r|type)!="object" then error("bad roadmap_record") elif ($r|has($k)|not) then "unrecorded" elif $r[$k] then "complete" else "incomplete" end end' <<<"$ANALYZE") || { echo "roadmap.analyze output unparseable" >&2; exit 1; }
+   [ "$VERDICT" != unreadable ] || { echo "ROADMAP_TABLE_UNREADABLE: the ROADMAP.md progress table does not parse (e.g. a row with the wrong cell count); fix it, then re-run /gsd:ship" >&2; exit 1; }
+   [ "$VERDICT" != unrecorded ] || { echo "PHASE_NOT_RECORDED: ROADMAP.md has no checklist entry or progress-table row for phase ${PHASE_NUMBER}; add one, run /gsd:verify-work ${PHASE_NUMBER}, then re-run /gsd:ship" >&2; exit 1; }
+   [ "$VERDICT" != incomplete ] || { echo "PHASE_NOT_COMPLETE: Run /gsd:verify-work ${PHASE_NUMBER} (completes the phase), then re-run /gsd:ship" >&2; [[ $PHASE_NUMBER =~ ^[A-Za-z]?[0-9] ]] || echo "Custom-id phase: the phase tools cannot find its directory yet, so after verifying, tick its ROADMAP.md checklist entry by hand" >&2; exit 1; }
+   ```
+   Only a phase whose every ROADMAP record (checklist entry, progress-table Status) reads complete ships; a phase with no record blocks. A missing ROADMAP.md skips the check; an analyze failure stops. This reads the record to catch a missed write-back — it is not a completion verdict (ADR-3180 §7.4, Amendment 10; step 1 already holds the disk verdict). `roadmap_record` keys use `foldPhaseId`; `def n` above must fold the same way.
+
 2. **Clean working tree?**
    ```bash
    git status --short

package/hooks/dist/gsd-graphify-update.sh

@@ -81,6 +81,12 @@ case "$COMMAND" in
   *) exit 0 ;;
 esac
 
+# #5548: inherited repo-location vars (GIT_DIR, GIT_INDEX_FILE, ...) would override
+# cwd for every git call below. Drop git's own list minus the config-injection vars.
+for v in $(git rev-parse --local-env-vars 2>/dev/null); do
+  case "$v" in GIT_CONFIG|GIT_CONFIG_PARAMETERS|GIT_CONFIG_COUNT) ;; *) unset "$v" ;; esac
+done
+
 # Gate 3 — inside git repo
 git rev-parse --git-dir >/dev/null 2>&1 || exit 0
 

package/hooks/dist/gsd-statusline.js

@@ -18,6 +18,7 @@ const os = require('os');
 // monkeypatching childProcess.execFileSync.
 const childProcess = require('child_process');
 const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+const { gitEnv } = require('./lib/git-probe.js');
 
 // This hook's build-seam outer catch (require.main guard just below) has
 // always exited 0 (fail open — the statusline renders on EVERY prompt, so a
@@ -934,7 +935,7 @@ function readGitStatus(dir) {
     // or untracked files; overflow still degrades safely to segment-absent via
     // the catch below.
     return childProcess.execFileSync('git', ['-C', dir, 'status', '--porcelain=v2', '--branch'],
-      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env: readOnlyGitEnv() });
+      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env: readOnlyGitEnv(gitEnv()) });
   } catch (e) {
     return null;
   }
@@ -1029,7 +1030,7 @@ function readStateHeadCommits(root, stamp) {
   try {
     return childProcess.execFileSync('git', // allow-index-refresh: rev-list walks the commit graph and never opens the index
       ['-C', root, 'rev-list', '--left-right', '--count', `${stamp}...HEAD`],
-      { encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
+      { env: gitEnv(), encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
         stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
   } catch (e) {
     return null;

package/hooks/dist/gsd-windsurf-pre-write.js

@@ -31,7 +31,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { allow, deny } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // #3911 (ADR-3889 Phase 7): the exit(2) call site (block(), below) is
 // migrated to hook-exit.js's deny(undefined, reason) — see
@@ -64,10 +64,10 @@ const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeou
 // Parity: tests/git-optional-locks-parity.test.cjs.
 // A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
 // (#3582), so the compiled owner can be absent. This guard only runs
-// `git rev-parse`, which never opens the index, so the unmodified environment
+// `git rev-parse`, which never opens the index, so the scrubbed gitEnv() base
 // loses nothing; requiring the artifact unguarded would throw at load and the
 // containment guard would silently stop running.
-let readOnlyGitEnv = () => process.env;
+let readOnlyGitEnv = (base = process.env) => base;
 try {
   const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
   ensureRuntimeBuild();
@@ -77,7 +77,7 @@ try {
 }
 
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv(gitEnv()) });
 }
 
 // Walk up from `start` to find the nearest existing DIRECTORY (not merely an