@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/workflows/review.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
 Each CLI gets the same prompt (PROJECT.md context, phase plans, requirements) and
@@ -208,7 +210,8 @@ Provide structured feedback on plan quality, completeness, and risks.
 {research if present}
 
 ### Plans to Review
-{all PLAN.md contents}
+For each `*-PLAN.md` in the phase directory, in glob order, include its full content preceded by a `####` header carrying the plan's **repo-relative path** (e.g. `#### .planning/phases/<phase>/<NN>-PLAN.md`). The path header is the citable anchor for findings about the plan itself — cite it as `<repo-relative plan path>:<line>` (name the heading in prose beside the citation if it helps the reader); reserve `path:line` for repo files the plan references.
+{per-plan: `#### <repo-relative plan path>` + full plan contents}
 
 ## Review Instructions
 
@@ -220,6 +223,13 @@ Provide structured feedback on plan quality, completeness, and risks.
 
 Findings citing `file:line` evidence are weighted far more heavily than impressionistic ones; a review that only restates the plan's own claims has low value.
 
+**Plan coverage is mandatory (#3301).** The exact list of plan ids and the total plan count for
+this review are given in the "## Plan Coverage Manifest" section below. Give **every** listed id
+its own `##`-level section headed with that id **verbatim** (e.g. `## 12.6-01`) before writing any
+cross-plan comparison, an overall risk assessment, or a consensus-style summary. A review that
+stops before every id has its own section is an incomplete review, not a summary — if you must
+stop early, say so explicitly and name which ids you did not reach.
+
 Analyze each plan and provide:
 
 1. **Summary** — One-paragraph assessment
@@ -254,14 +264,57 @@ RUN_DIR="{run_dir}"   # from gather_context
 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 numbered path
-PLAN_INDEX=0
+# 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.
+# 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.
+PLAN_COUNT=0
+PLAN_ID_BULLETS=""
 for PLAN_FILE in "${PHASE_DIR}"/*-PLAN.md; do
-  PADDED_IDX=$(printf '%02d' "$PLAN_INDEX")
-  cp "$PLAN_FILE" "${RUN_DIR}/gsd-review-plan-${PADDED_IDX}.md"
-  PLAN_INDEX=$((PLAN_INDEX + 1))
+  PLAN_BASENAME=$(basename "$PLAN_FILE")
+  PLAN_ID="${PLAN_BASENAME%-PLAN.md}"
+  PLAN_COUNT=$((PLAN_COUNT + 1))
+  PLAN_ID_BULLETS="${PLAN_ID_BULLETS}- ${PLAN_ID}
+"
 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.
+{
+  echo ""
+  echo "## Plan Coverage Manifest"
+  echo ""
+  echo "Total plans in this review: ${PLAN_COUNT}"
+  echo ""
+  echo "Plan ids (give each one its own \`##\`-level section, headed verbatim):"
+  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"
@@ -277,6 +330,15 @@ 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"
+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).
@@ -292,6 +354,20 @@ declared in the manifest — timeout floor, probe, prompt/output channel, empty-
 behaviour that data genuinely cannot express is a named first-party `handler` (ADR-2782 D6), never
 a bespoke block here.
 
+**Effort and model resolution (#4255).** A lane's reasoning effort and model each resolve through
+their own declared key, and the resolution order is inspectable rather than implicit:
+
+| piece | order, highest first |
+|---|---|
+| model | pinned reviewer-instance `--model` → the lane's `modelConfigKey` (`review.models.<slug>`) → the CLI's own default |
+| effort | the lane's `effortConfigKey` (`review.effort.<slug>`) → the lane's declared `defaultEffort` → **nothing emitted**, so the CLI's own configuration applies |
+
+Both come from the LANE. Effort in particular is never read from an agent's execution settings:
+until #4255 it was resolved by querying `gsd-plan-checker`, so every prompt-fed lane ran at that
+verifier's `low` and, because the rendered argument is a CLI config override, it silently beat the
+effort the operator had configured for the reviewer CLI itself. A lane that declares no effort
+emits no argument at all — a value borrowed from an unrelated agent is worse than no value.
+
 **Timeout guidance (#2194):** prompt-fed source-grounded reviews are slow — measured ~570 s for
 Codex at `xhigh` effort and ~525 s for headless Claude on a large plan set. Each lane declares its
 own `timeoutFloorMs` and the runner enforces it internally, but the **Bash tool call wrapping the
@@ -434,7 +510,14 @@ for SLUG in $(echo "$SELECTED_REVIEWERS" | tr ',' ' '); do
   DISPATCH_SLUGS="$DISPATCH_SLUGS $SLUG"
 done
 
-for SLUG in $DISPATCH_SLUGS; do
+# Rewrapped through unquoted command substitution, not consumed as a bare
+# `$DISPATCH_SLUGS`: bash word-splits an unquoted scalar on IFS by default,
+# but zsh does not, so a bare re-split collapsed every slug onto one
+# iteration under zsh whenever 2+ reviewers were selected (gsd-core#4109).
+# Unquoted `$(...)` re-splits identically under both shells regardless of
+# `SH_WORD_SPLIT` — same reason the accumulator-building loop above already
+# works under both.
+for SLUG in $(printf '%s' "$DISPATCH_SLUGS"); do
   if [ "$PARALLEL_LANES" = "true" ]; then
     run_review_lane "$SLUG" &
   else
@@ -452,7 +535,9 @@ wait
 # 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.
-for SLUG in $DISPATCH_SLUGS; do
+# 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
     cat "$LANE_RESULT" >> "$RUN_DIR/gsd-review-lane-results.jsonl"
@@ -513,7 +598,10 @@ if [ "${LANE_LINES:-0}" -eq 0 ]; then
   # failure stub does not. If a slug has no stub at all, it is not a skip.
   DISPATCHED_COUNT=0
   SKIPPED_COUNT=0
-  for SLUG in $DISPATCH_SLUGS; do
+  # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+  # `$DISPATCH_SLUGS` word-splits under bash but not zsh, collapsing every
+  # slug onto one iteration there whenever 2+ reviewers were selected.
+  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
@@ -536,8 +624,90 @@ fi
   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
+`.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`/
+`ALL_LANES_SKIPPED` gate above.
+
+CodeRabbit is excluded — it is a diff-only lane that never receives the source-grounding prompt
+(and therefore never receives the manifest or the per-id section instruction either), the same fact
+that already excludes it from grounded-review weighting in the Consensus Summary below.
+
+The match is intentionally lenient about *where* an id appears (a `##`-headed section is asked for,
+but plain prose mentioning the id still counts as coverage — grading only the letter of the
+formatting instruction would produce false INCOMPLETE verdicts against a reviewer that cited real
+evidence correctly). It is strict about *what* counts as a match: the id is regex-escaped (a
+decimal phase like `12.6` must not let `12X6-01` satisfy `12.6-01` through an unescaped `.`), and a
+`-`/word character immediately before or after the candidate match does not count as a boundary (so
+a threat id like `T-04-07` elsewhere in the review must not register as covering plan `04-07`).
+
+```bash
+RUN_DIR="{run_dir}"
+MANIFEST="$RUN_DIR/.plans-manifest.md"
+
+# Recompute — a shell variable does not survive across separate fenced blocks
+# (each is its own process), so DISPATCH_SLUGS from the gate-check block above
+# cannot be assumed to still be set here. Same recomputation as that block and
+# as invoke_reviewers.
+DISPATCH_SLUGS=""
+for SLUG in $(echo "$SELECTED_REVIEWERS" | tr ',' ' '); do
+  case " $DISPATCH_SLUGS " in
+    *" $SLUG "*) continue ;;
+  esac
+  DISPATCH_SLUGS="$DISPATCH_SLUGS $SLUG"
+done
+
+# Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+# `$DISPATCH_SLUGS` word-splits under bash but not zsh, collapsing every
+# slug onto one iteration there whenever 2+ reviewers were selected.
+for SLUG in $(printf '%s' "$DISPATCH_SLUGS"); do
+  [ "$SLUG" = "coderabbit" ] && continue
+  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 "failed or returned empty output" "$REVIEW_FILE" 2>/dev/null && continue
+
+  node -e '
+    const fs = require("fs");
+    const { escapeRegex } = require("./gsd-core/bin/lib/pattern.cjs");
+    const manifest = fs.readFileSync(process.argv[1], "utf8");
+    const review = fs.readFileSync(process.argv[2], "utf8");
+    const ids = manifest.split("\n")
+      .filter((l) => l.startsWith("- "))
+      .map((l) => l.slice(2).trim())
+      .filter(Boolean);
+    const missing = ids.filter((id) => {
+      const re = new RegExp("(?<![\\w-])" + escapeRegex(id) + "(?![\\w-])");
+      return !re.test(review);
+    });
+    process.stdout.write(JSON.stringify({ complete: missing.length === 0, missing_ids: missing, total: ids.length }));
+  ' "$MANIFEST" "$REVIEW_FILE" > "$RUN_DIR/.plan-coverage-$SLUG.json"
+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
+only when there is something to report):
+
+```yaml
+plan_coverage:        # only present if at least one graded lane is incomplete
+  <slug>:
+    total: 7
+    missing: ["12.6-07"]
+```
+
 Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`:
 
+Capture only the existing conflict entry bytes after the exact `## Plan-Revision Conflicts`
+heading and before the end of the first exact `<!-- gsd:plan-revision-conflicts:begin -->` /
+`<!-- gsd:plan-revision-conflicts:end -->` pair immediately after the artifact title, if present,
+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.
 
 **Reviewer instances (#1517, optional):** when instances ran, frontmatter records their
@@ -580,10 +750,19 @@ trimmed_reviewers:        # only present if at least one reviewer was trimmed
     plan_truncation_pct: 22
     hard_failed: false
     note_injected: true
+plan_coverage:            # only present if at least one graded lane is incomplete (#3301)
+  ollama:
+    total: 7
+    missing: ["12.6-07"]
 ---
 
 # Cross-AI Plan Review — Phase {N}
 
+<!-- gsd:plan-revision-conflicts:begin -->
+## Plan-Revision Conflicts
+{preserved_plan_revision_conflict_entries}
+<!-- gsd:plan-revision-conflicts:end -->
+
 <!-- Sections are RENDERED from each lane's declared `reviewsSection`, in descriptor order.
      There is deliberately no hardcoded per-reviewer heading list here any more: a hand-maintained
      list is exactly the drift #2781 was filed about, and it silently disagreed with the roster.
@@ -666,6 +845,19 @@ NOT a preservation failure. This copy is deliberately NOT part of the commit abo
 step names only `{padded_phase}-REVIEWS.md` explicitly, never a directory glob, so
 `.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
+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
+set — adding one means adding its stem to this list consciously. Lane slugs never begin with
+any excluded stem (`prompt`, `instructions`, `plan-`, `project`, `roadmap`, `context`,
+`research`, `requirements`), so a lane report can never be excluded by accident.
+
 Preservation and cleanup MUST run in the same fenced block below (a shell variable cannot
 survive across separate fences — each is its own process). `mkdir -p` and every `cp` are
 exit-status checked; `rm -rf "$RUN_DIR"` runs ONLY if nothing was preserved (nothing to
@@ -679,7 +871,20 @@ shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null
 RUN_DIR="{run_dir}"
 DIAG_DIR="{phase_dir}/.review-diagnostics"
 
-_DIAG_MD=( "$RUN_DIR"/gsd-review-*.md )
+# #4097: `gsd-review-*.md` matches BOTH lane outputs (reports, diagnostic stubs) and the
+# run's own assembled input copies (see the #4097 note above). Filter by basename against
+# 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`).
+_DIAG_MD=()
+for f in "$RUN_DIR"/gsd-review-*.md; do
+  case "$(basename "$f")" in
+    gsd-review-prompt*|gsd-review-instructions*|gsd-review-plan-*|gsd-review-project*|gsd-review-roadmap*|gsd-review-context*|gsd-review-research*|gsd-review-requirements*) ;;
+    *) _DIAG_MD+=("$f") ;;
+  esac
+done
 _DIAG_ERR=()
 for f in "$RUN_DIR"/gsd-review-*.err; do
   [ -s "$f" ] && _DIAG_ERR+=("$f")

package/gsd-core/workflows/scan.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Lightweight codebase assessment. Spawns a single gsd-codebase-mapper agent for one focus area,
 producing targeted documents in `.planning/codebase/`.

package/gsd-core/workflows/section-manifest.json

@@ -150,6 +150,18 @@
         "read": "gsd-core/workflows/progress/steps/forensic-audit.md"
       }
     ],
+    "quick-batch": [
+      {
+        "id": "research-phase",
+        "when": "flag:--research",
+        "read": "gsd-core/workflows/quick-batch/steps/research-phase.md"
+      },
+      {
+        "id": "verification-wave",
+        "when": "flag:--validate",
+        "read": "gsd-core/workflows/quick-batch/steps/verification-wave.md"
+      }
+    ],
     "quick": [
       {
         "id": "discussion-phase",

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

@@ -23,7 +23,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_AUDITOR=$(gsd_run query agent-skills gsd-security-auditor)
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 

package/gsd-core/workflows/session-report.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Generate a post-session summary document capturing work performed, outcomes achieved, and estimated resource usage. Writes SESSION_REPORT.md to .planning/reports/ for human review and stakeholder sharing.
 </purpose>

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

@@ -1,3 +1,5 @@
+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, node repair, subagent timeouts,
 inline plan threshold, cross-AI execution, base branch, branch templates, response language,

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

@@ -60,7 +60,7 @@ if [[ -z "${GSD_CONFIG_PATH:-}" ]]; then
 fi
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Store `$GSD_CONFIG_PATH`. Every subsequent read/write uses it.
 </step>
@@ -163,12 +163,13 @@ namespace — any other slug fails with `Unknown config key`.
 Settable keys (the shipped registry's model-bearing lanes):
 
 `review.models.agy` (Antigravity), `review.models.claude`, `review.models.codex`,
-`review.models.gemini`, `review.models.kimi-code`, `review.models.llama_cpp`,
-`review.models.lm_studio`, `review.models.ollama`, `review.models.opencode`.
+`review.models.cursor`, `review.models.gemini`, `review.models.kimi-code`,
+`review.models.llama_cpp`, `review.models.lm_studio`, `review.models.ollama`,
+`review.models.opencode`.
 
-Reviewer lanes `cursor`, `qwen`, and `coderabbit` declare no `modelConfigKey` —
-there is nothing to configure for them here (whether they should have a
-per-lane model key is a separate question, out of scope for this workflow).
+Reviewer lanes `qwen` and `coderabbit` declare no `modelConfigKey` — there is
+nothing to configure for them here (whether they should have a per-lane model
+key is a separate question, out of scope for this workflow).
 If the user asks for one of those, say exactly that and skip.
 
 ```text
@@ -208,8 +209,8 @@ If it is not one of the settable keys, print:
 
 ```text
 Rejected: review.models.<slug> is not settable — only the reviewer lanes whose
-keys are enumerated above can be configured here. (cursor, qwen, and
-coderabbit have no per-lane model key.)
+keys are enumerated above can be configured here. (qwen and coderabbit have no
+per-lane model key.)
 ```
 
 and re-prompt.

package/gsd-core/workflows/settings.md

@@ -28,7 +28,7 @@ if [[ -z "${GSD_CONFIG_PATH:-}" ]]; then
 fi
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Creates `config.json` (at the resolved path) with defaults if missing. `INIT` still holds `state.load` output for any step that needs STATE fields.
 Store `$GSD_CONFIG_PATH` — all subsequent reads and writes use this path, not a hardcoded `.planning/config.json`, so active-workstream installs target the correct file (#2282).
@@ -60,6 +60,7 @@ Parse current values (default to `true` if not present):
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
 - `workflow.use_worktrees` — whether parallel executor agents run in worktree isolation (honored when the runtime declares a `dispatch.isolation` primitive — `harness-worktree` or `orchestrator-worktree`; runtimes declaring `none` default it to `false` and fail closed on an explicit `true` — #1521, #2486, #2584)
+- `workflow.compact_content` — load token-minimized instruction variants where they exist, trading rarely-needed elaboration for a smaller always-loaded instruction window (default: false if absent; #4139)
 - `model_policy.provider` — provider slug for model policy (default: `null`; known values: anthropic, openai, google, qwen; set via /gsd:config --advanced)
 - `model_policy.budget` — budget level for model policy (default: `null`; known values: high, medium, low; set via /gsd:config --advanced)
 - `model_policy.high` — model ID for high-cost tier (default: `null`; set via /gsd:config --advanced)
@@ -131,7 +132,7 @@ Intel, Graphify, Graph auto-update _(conditional — only when graphify=on)_
 Model Profile, Auto-Advance, Branching
 
 ### Misc
-Context Warnings, Research Qs
+Context Warnings, Compact Content, Research Qs
 
 **Conditional visibility — code_review_depth:** This question is shown only when the user's chosen `code_review` value (after they answer that question, or the pre-selected value if unchanged) is on. If `code_review` is off, omit the `code_review_depth` question from the AskUserQuestion block and preserve the existing `workflow.code_review_depth` value in config (do not overwrite). Implementation: ask the Model + Planning + Execution-up-to-Code-Review questions first; if `code_review=on`, include `code_review_depth` in the same batch; otherwise skip it. Conceptually this is a one-branch split on the `code_review` answer.
 
@@ -382,6 +383,15 @@ AskUserQuestion([
       { label: "No", description: "Disable warnings. Allows Claude to reach auto-compact naturally. Good for long unattended runs." }
     ]
   },
+  {
+    question: "Use token-minimized instruction content where available? (smaller context footprint)",
+    header: "Compact Content",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended)", description: "Full instruction detail loaded every time." },
+      { label: "Yes", description: "Terser instructions where a compact variant exists; canonical detail loads only when actually needed." }
+    ]
+  },
   {
     question: "Research best practices before asking questions? (web search during new-project and discuss-phase)",
     header: "Research Qs",
@@ -475,7 +485,8 @@ Merge new settings into existing config.json:
     "research_before_questions": true/false,
     "discuss_mode": "discuss" | "assumptions",
     "skip_discuss": true/false,
-    "use_worktrees": true/false   // never written as true when the runtime's dispatch.isolation is none; omitted entirely when the user chose "Leave unchanged" (#2486)
+    "use_worktrees": true/false,  // never written as true when the runtime's dispatch.isolation is none; omitted entirely when the user chose "Leave unchanged" (#2486)
+    "compact_content": true/false
   },
   "plan_review": {
     "source_grounding": true/false
@@ -532,7 +543,7 @@ Merge new settings into existing config.json:
 
   `code_review_depth` is written only if the `code_review` question was answered `on`; otherwise leave the existing value in place.
 
-- **Non-capability keys** (`model_profile`, `commit_docs`, `workflow.plan_check`, `workflow.verifier`, `workflow.auto_advance`, `workflow.text_mode`, `workflow.research_before_questions`, `workflow.discuss_mode`, `workflow.skip_discuss`, `workflow.use_worktrees`, `plan_review.source_grounding`, `graphify.auto_update`, `git.*`, `hooks.*`, `model_policy.*`): write via `gsd_run query config-set <key.path> <value>` as before.
+- **Non-capability keys** (`model_profile`, `commit_docs`, `workflow.plan_check`, `workflow.verifier`, `workflow.auto_advance`, `workflow.text_mode`, `workflow.compact_content`, `workflow.research_before_questions`, `workflow.discuss_mode`, `workflow.skip_discuss`, `workflow.use_worktrees`, `plan_review.source_grounding`, `graphify.auto_update`, `git.*`, `hooks.*`, `model_policy.*`): write via `gsd_run query config-set <key.path> <value>` as before.
 
 `model_profile` is written on Q1 "Adaptive (Recommended)" (→ adaptive) or Q1 "Inherit" (→ inherit) immediately; for Q1 "Standard tier…", `model_profile` is written from Q2's answer. If Q1 = "Standard tier…" but Q2 is cancelled, leave the existing `model_profile` value unchanged — do not write any new value.
 
@@ -586,7 +597,8 @@ Write `~/.gsd/defaults.json` with:
     "code_review": <current>,
     "code_review_depth": <current>,
     "ui_review": <current>,
-    "skip_discuss": <current>
+    "skip_discuss": <current>,
+    "compact_content": <current>
   },
   "plan_review": {
     "source_grounding": <current>
@@ -632,6 +644,7 @@ Display:
 | Git Tagging          | {On/Off} |
 | Skip Discuss         | {On/Off} |
 | Context Warnings     | {On/Off} |
+| Compact Content      | {On/Off} |
 | Saved as Defaults    | {Yes/No} |
 
 These settings apply to future /gsd:plan-phase and /gsd:execute-phase runs.
@@ -650,7 +663,7 @@ Quick commands:
 
 <success_criteria>
 - [ ] Current config read
-- [ ] User presented with 24 settings (profile + workflow toggles + features + git branching + git tagging + ctx warnings), grouped into six sections: Planning, Execution, Docs & Output, Features, Model & Pipeline, Misc. `code_review_depth` is conditional on `code_review=on`. Model profile uses a two-question split (Q1: Adaptive / Standard tier / Inherit; Q2: Quality / Balanced / Budget — only when Standard tier chosen) to stay within the 4-option AskUserQuestion cap while exposing all 5 valid profiles (#3784). Drift Guard (`plan_review.source_grounding`) is in the Planning section.
+- [ ] User presented with 25 settings (profile + workflow toggles + features + git branching + git tagging + ctx warnings + compact content), grouped into six sections: Planning, Execution, Docs & Output, Features, Model & Pipeline, Misc. `code_review_depth` is conditional on `code_review=on`. Model profile uses a two-question split (Q1: Adaptive / Standard tier / Inherit; Q2: Quality / Balanced / Budget — only when Standard tier chosen) to stay within the 4-option AskUserQuestion cap while exposing all 5 valid profiles (#3784). Drift Guard (`plan_review.source_grounding`) is in the Planning section.
 - [ ] Config updated with model_profile, workflow, and git sections
 - [ ] User offered to save as global defaults (~/.gsd/defaults.json)
 - [ ] Changes confirmed to user

package/gsd-core/workflows/ship.md

@@ -30,7 +30,7 @@ INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
 
@@ -309,16 +309,16 @@ Example configured sections:
 
 **8. TDD Audit section:**
 
-Reconstruct the per-commit TDD gate trail before squash-merge discards it. Walk the PR branch's own commits (merges excluded) and read each commit's `gate_status:` trailer with Git's native trailer machinery — never a raw `%B` grep, which would also match the string written in prose:
+Reconstruct the per-commit TDD gate trail before squash-merge discards it. Walk the PR branch's own commits (merges excluded) and read each commit's `gate-status:` trailer with Git's native trailer machinery — never a raw `%B` grep, which would also match the string written in prose:
 
 ```bash
 # Anchor on the merge-base so a stale local ${BASE_BRANCH} ref cannot over-count.
 RANGE_BASE=$(git merge-base "${BASE_BRANCH}" HEAD)
 git log "${RANGE_BASE}..HEAD" --no-merges --reverse \
-  --format='%H%x1f%s%x1f%(trailers:key=gate_status,valueonly,separator=%x2c)%x1e'
+  --format='%H%x1f%s%x1f%(trailers:key=gate-status,valueonly,separator=%x2c)%x1e'
 ```
 
-Records are separated by `\x1e`; the fields inside each are `\x1f`-separated — `<sha>`, `<subject>`, `<gate_status value>`.
+Records are separated by `\x1e`; the fields inside each are `\x1f`-separated — `<sha>`, `<subject>`, `<gate-status value>`.
 
 Pair commits by their conventional-commit type (the `type:` prefix of the subject):
 
@@ -326,16 +326,16 @@ Pair commits by their conventional-commit type (the `type:` prefix of the subjec
 - A `refactor:`, `docs:`, or `chore:` commit that is not consumed as an Impl pairing is a standalone row with Impl commit `—`.
 - A `feat:`/`fix:` commit with no preceding unpaired `test:` is a standalone row.
 
-Surface each commit's `gate_status:` value, normalized to exactly one of `skill`, `fallback`, `exempt`, or `missing` — never the raw trailer text. A commit whose trailer is absent, whose value is none of the first three, or which carries more than one `gate_status:` trailer (ambiguous) is counted as **missing** and still listed. This section is informational; it never blocks the ship.
+Surface each commit's `gate-status:` value, normalized to exactly one of `skill`, `fallback`, `exempt`, or `missing` — never the raw trailer text. A commit whose trailer is absent, whose value is none of the first three, or which carries more than one `gate-status:` trailer (ambiguous) is counted as **missing** and still listed. This section is informational; it never blocks the ship.
 
-**Self-suppress when every commit is missing (#2431):** the execute pipeline only writes `gate_status:` trailers when TDD mode is active. If every commit in the scan normalizes to `missing`, skip this section and the aggregate trailer (step 9) entirely — a 100%-missing table is pure noise. Only emit when at least one commit carries a real value (`skill`, `fallback`, or `exempt`).
+**Self-suppress when every commit is missing (#2431):** the execute pipeline only writes `gate-status:` trailers when TDD mode is active. If every commit in the scan normalizes to `missing`, skip this section and the aggregate trailer (step 9) entirely — a 100%-missing table is pure noise. Only emit when at least one commit carries a real value (`skill`, `fallback`, or `exempt`).
 
-Harden every table cell against injection, not just subjects: escape `|` as `\|` and strip `\r`/`\n` from both commit subjects and the rendered `gate_status` value. Prefer NUL (`-z` / `%x00`) record separation, and reject any record whose fields contain the `\x1f`/`\x1e` delimiters, so an adversarial commit message cannot corrupt record or field boundaries.
+Harden every table cell against injection, not just subjects: escape `|` as `\|` and strip `\r`/`\n` from both commit subjects and the rendered `gate-status` value. Prefer NUL (`-z` / `%x00`) record separation, and reject any record whose fields contain the `\x1f`/`\x1e` delimiters, so an adversarial commit message cannot corrupt record or field boundaries.
 
 ```markdown
 ## TDD Audit
 
-| Test commit | Impl commit | gate_status |
+| Test commit | Impl commit | gate-status |
 |---|---|---|
 | `a1b2c3d` test: failing parser test | `e4f5g6h` feat: implement parser | skill |
 | `i7j8k9l` test: failing export test | `m0n1o2p` feat: implement export | fallback |
@@ -346,12 +346,12 @@ Aggregate: 2 skill, 1 fallback, 1 exempt — 0 missing.
 
 This `## TDD Audit` section is the final body section — it renders after the configured `pr_body_sections`, immediately before the aggregate trailer — so the frozen core sections and the append-only configured sections both keep their existing order.
 
-**9. Aggregate gate_status trailer (final line)** (only when step 8 was emitted — i.e., at least one real `gate_status` value exists):
+**9. Aggregate gate-status trailer (final line)** (only when step 8 was emitted — i.e., at least one real `gate-status` value exists):
 
 After every other section — including any configured `pr_body_sections` — emit the audit aggregate as a single Git trailer on the **final line** of the PR body, preceded by a blank line so it parses as a valid trailer:
 
 ```
-gate_status: skill=2, fallback=1, exempt=1, missing=0
+gate-status: skill=2, fallback=1, exempt=1, missing=0
 ```
 
 Use the exact key order `skill=`, `fallback=`, `exempt=`, `missing=` so downstream tooling parses it stably. Keeping it last means a GitHub squash-merge that defaults its commit message to the PR description carries the aggregate into `${BASE_BRANCH}`, preserving the audit footprint in `git log` after the PR branch is deleted. (Best-effort: it depends on the repo's squash-message default; the in-body `## TDD Audit` section is the source of truth regardless.)

package/gsd-core/workflows/sketch-wrap-up.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Curate sketch design findings and package them into a persistent project skill for future
 UI implementation. Reads from `.planning/sketches/`, writes skill to `./.claude/skills/sketch-findings-[project]/`

package/gsd-core/workflows/sketch.md

@@ -102,7 +102,7 @@ RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "
 COMMIT_DOCS=$(gsd_run query config-get commit_docs --raw 2>/dev/null || echo "true")
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 </step>
 
 <step name="mood_intake">

package/gsd-core/workflows/smart-entry.md

@@ -34,7 +34,7 @@ RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "
 SNAPSHOT=$(gsd_run smart-entry --json 2>/dev/null)
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 Parse `SNAPSHOT` as JSON. It has the shape: