@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

package/gsd-core/workflows/execute-phase/steps/regression-gate.md

@@ -0,0 +1,42 @@
+# Step: regression_gate_run
+
+Run the resolved prior-phase test command one-shot, bounded by a timeout, so a
+watch-mode runner (vitest defaults to watch in a TTY; jest `--watch`) cannot
+hang this gate forever (#1857). Uses the shared `normalize-test-command` helper
+— the same one the post-merge gate uses — so the two gate paths cannot drift.
+
+Expects `REGRESSION_FILES` (from the prior step) in scope for the pytest branch.
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+# Resolve test command: project config > Makefile > language sniff
+REG_TEST_CMD=$(gsd_run query config-get workflow.test_command --default "" 2>/dev/null || true)
+if [ -z "$REG_TEST_CMD" ]; then
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
+    REG_TEST_CMD="make test"
+  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
+    REG_TEST_CMD="just test"
+  elif [ -f "package.json" ]; then
+    REG_TEST_CMD="npm test"
+  elif [ -f "Cargo.toml" ]; then
+    REG_TEST_CMD="cargo test"
+  elif [ -f "go.mod" ]; then
+    REG_TEST_CMD="go test ./..."
+  elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+    REG_TEST_CMD="python -m pytest ${REGRESSION_FILES} -q --tb=short"
+  else
+    REG_TEST_CMD="true"
+  fi
+fi
+# #1857: normalize to a one-shot form (defeat vitest/jest watch mode) and bound
+# with a timeout so a watch-mode runner cannot hang the gate indefinitely.
+REG_TEST_CMD=$(gsd_run query normalize-test-command "$REG_TEST_CMD" --cwd . 2>/dev/null || echo "$REG_TEST_CMD")
+TEST_GATE_TIMEOUT=$(gsd_run query config-get workflow.test_gate_timeout 2>/dev/null || echo "600")
+timeout "$TEST_GATE_TIMEOUT" bash -c "$REG_TEST_CMD" 2>&1
+REG_TEST_EXIT=$?
+if [ "$REG_TEST_EXIT" -eq 124 ]; then
+  echo "✗ REGRESSION GATE ABORTED — test runner did not exit within ${TEST_GATE_TIMEOUT}s, likely stuck in watch/dev mode (e.g. vitest without 'run'). Run tests one-shot (e.g. 'vitest run'), set workflow.test_command, or raise workflow.test_gate_timeout."
+fi
+```
+
+**On `REG_TEST_EXIT` 124 (`REGRESSION GATE ABORTED`):** HALT — do not proceed to verification. The runner did not exit within the budget (watch/dev mode is the likely cause). Surface the watch-mode cause and the recovery options; never silently continue.

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

@@ -1289,31 +1289,7 @@ For each VERIFICATION.md found, look for test file references:
 
 Collect all unique test file paths into `REGRESSION_FILES`.
 
-**Step 3: Run regression tests (if any found)**
-
-```bash
-# Resolve test command: project config > Makefile > language sniff
-REG_TEST_CMD=$(gsd_run query config-get workflow.test_command --default "" 2>/dev/null || true)
-if [ -z "$REG_TEST_CMD" ]; then
-  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then
-    REG_TEST_CMD="make test"
-  elif [ -f "Justfile" ] || [ -f "justfile" ]; then
-    REG_TEST_CMD="just test"
-  elif [ -f "package.json" ]; then
-    REG_TEST_CMD="npm test"
-  elif [ -f "Cargo.toml" ]; then
-    REG_TEST_CMD="cargo test"
-  elif [ -f "go.mod" ]; then
-    REG_TEST_CMD="go test ./..."
-  elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
-    REG_TEST_CMD="python -m pytest ${REGRESSION_FILES} -q --tb=short"
-  else
-    REG_TEST_CMD="true"
-  fi
-fi
-# Detect test runner and run prior phase tests
-eval "$REG_TEST_CMD" 2>&1
-```
+**Step 3: Run regression tests (if any found)** — Read and execute `gsd-core/workflows/execute-phase/steps/regression-gate.md`. It resolves the project test command, normalizes it to a one-shot form (defeating vitest/jest watch mode via the shared `normalize-test-command` helper), runs it under `workflow.test_gate_timeout`, and aborts on timeout with a watch-mode hint (#1857). On `REGRESSION GATE ABORTED` (exit 124), HALT — do not proceed to verification.
 
 **Step 4: Report results**
 

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

@@ -610,6 +610,10 @@ SKETCH_FINDINGS_PATH=$(ls ./.claude/skills/sketch-findings-*/SKILL.md 2>/dev/nul
 PHASE_DIR_FOR_SPEC=$(_gsd_field "$INIT" phase_dir)
 SPEC_FILE=$(ls "${PHASE_DIR_FOR_SPEC}"/*-SPEC.md 2>/dev/null | grep -Ev -- '-(AI|UI)-SPEC\.md$' | head -1)
 SPEC_PATH="${SPEC_FILE}"
+# Resolve the phase UI-SPEC separately (the glob above excludes -UI-SPEC.md); it carries the
+# ## UI Considerations section the planner lifts by the same rule as ## Edge Coverage (#1867).
+UI_SPEC_FILE=$(ls "${PHASE_DIR_FOR_SPEC}"/*-UI-SPEC.md 2>/dev/null | head -1)
+UI_SPEC_PATH="${UI_SPEC_FILE}"
 ```
 
 ## 7.5. Verify Nyquist Artifacts
@@ -693,6 +697,19 @@ echo "✓ API surface regenerated: ${API_SURFACE_PATH}"  # injected into step 8
 
 Continue to step 8.
 
+## 7.95. Spec-less Probe Fallback (gate)
+
+When the SPEC did not supply `## Edge Coverage` / `## Prohibitions`, plan-phase runs the probe protocol
+and authors the predicates into PLAN.md `must_haves` (ADR-857 Phase 6 — the *else branch* of the
+`<downstream_consumer>` lift below). Core workflow-body substrate, not a capability rail (D-03). Runs
+after `$SPEC_FILE` (Step 7), before the gsd-planner spawn (Step 8).
+
+**Read and run** the gate + edge probe in `~/.claude/gsd-core/references/specless-probe-fallback.md`
+(§0 default-ON toggle + per-section absence via the `spec-section` helper, visibly skipping when
+disabled or no requirement IDs; §A deterministic edge probe → `$COVERAGE` when `EDGE_ABSENT`; §B
+prohibition recall in the planner). Pass `$COVERAGE` and `$SPECLESS_FALLBACK_DISABLED` into Step 8.
+
+
 ## 8. Spawn gsd-planner Agent
 
 Display banner:
@@ -769,6 +786,22 @@ ${MVP_MODE === 'true' ? `
 **MVP Mode is ENABLED.** Read `~/.claude/gsd-core/references/planner-mvp-mode.md` now and follow its vertical-slice planning rules. Each plan must deliver a complete vertical slice — thin end-to-end functionality rather than horizontal layers.
 </mvp_mode_active>
 ` : ''}
+
+<specless_probe_fallback>
+**Spec-less probe fallback** (only when step 7.95 set `EDGE_ABSENT` and/or `PROHIB_ABSENT`). The SPEC
+omitted that section — author its predicates into `must_haves` via the `<downstream_consumer>`
+else-branch below, per §A/§B/§C of `~/.claude/gsd-core/references/specless-probe-fallback.md`
+(descriptor-less prohibitions, never auto-dismiss, no silent drops).
+
+Edge coverage report (`$COVERAGE`, present when `EDGE_ABSENT`):
+
+```json
+{COVERAGE}
+```
+${SPECLESS_FALLBACK_DISABLED ? `
+**⚠ ${SPECLESS_FALLBACK_DISABLED}** — record this in the plan (a visible, recorded choice); do not generate probe predicates this run.
+` : ''}
+
 </planning_context>
 
 <downstream_consumer>
@@ -777,8 +810,9 @@ Output consumed by /gsd:execute-phase. Plans need:
 - Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task)
 - Verification criteria
 - must_haves for goal-backward verification
-- If the SPEC has an `## Edge Coverage` section, lift every `covered` edge's acceptance criterion into `must_haves.truths` as a plain string, and every `backstop` edge **as a structured flat-scalar marker** — an object item `{ statement: <the check>, verification: backstop }`, NOT a prose note (the verifier branches deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110 fragility). Use a flat scalar `verification:` continuation key, never a nested object (ADR-550 #1278). At verify time a `backstop` truth the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason `insufficient_spec`), never a silent pass (#1154; see `references/honest-verifier.md`). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them.
-- If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) carrying `statement` + `status` + `verification`; unresolved prohibitions are explicit assumptions — surface them in the plan, do not silently drop them. A prohibition is a must-NOT (negative) check that belongs in its own `must_haves.prohibitions` block. Never place a must-NOT under `must_haves.truths` — that block keeps positive-observable semantics only.
+- If the SPEC has an `## Edge Coverage` section, lift every `covered` edge's acceptance criterion into `must_haves.truths` as a plain string, and every `backstop` edge **as a structured flat-scalar marker** — an object item `{ statement: <the check>, verification: backstop }`, NOT a prose note (the verifier branches deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110 fragility). Use a flat scalar `verification:` continuation key, never a nested object (ADR-550 #1278). At verify time a `backstop` truth the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason `insufficient_spec`), never a silent pass (#1154; see `references/honest-verifier.md`). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them. **Otherwise** (`EDGE_ABSENT`): apply the SAME lift to the fallback report `{COVERAGE}` (per §C of `references/specless-probe-fallback.md`); a SPEC-supplied section is never re-run.
+- If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) with `statement`+`status`+`verification`, via the single `projectProhibitions` serializer (Hyrum — no second serializer); unresolved -> flagged assumptions, don't drop; never put a must-NOT under `truths`. **Otherwise** (`PROHIB_ABSENT`), author the recalled prohibitions into the SAME block via the SAME `projectProhibitions` contract but **descriptor-less** (no `check_*`) so each disposes flagged-unverified; never auto-dismiss. Section-level precedence + no-silent-drop equality apply (§C).
+- If a `-UI-SPEC.md` exists (resolved above as `UI_SPEC_PATH`) with a `## UI Considerations` section, lift it by the **identical rule** as `## Edge Coverage` above — `covered` → `must_haves.truths` string, `backstop` → flat scalar `{ statement, verification: backstop }`, `unresolved` → explicit planner assumption (no new verb — ADR-550 #1278/#1154; #1867). Read it from `UI_SPEC_PATH` (the SPEC glob excludes `-UI-SPEC.md`).
 - **"Artifacts this phase produces" section (MANDATORY)** — list every symbol this phase creates: decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths. The plan-review-convergence source-grounding pass reads this section to exclude newly-created symbols from drift verification; omitting it causes new symbols to be flagged for acknowledgement.
 </downstream_consumer>
 
@@ -825,6 +859,7 @@ Every task MUST include these fields — they are NOT optional:
 - [ ] must_haves derived from phase goal
 - [ ] Every PLAN.md includes an "Artifacts this phase produces" section listing symbols created by this phase (decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths)
 - [ ] Every SPEC ## Edge Coverage covered/backstop edge is represented in a plan's must_haves (no silent drops)
+- [ ] Every UI-SPEC ## UI Considerations covered/backstop consideration is represented in a plan's must_haves (no silent drops)
 - [ ] Every SPEC ## Prohibitions resolved item is represented in a plan's must_haves.prohibitions (no silent drops)
 </quality_gate>
 ```

package/gsd-core/workflows/quick.md

@@ -134,7 +134,7 @@ AGENT_SKILLS_CHECKER=$(gsd_run query agent-skills gsd-plan-checker)
 AGENT_SKILLS_VERIFIER=$(gsd_run query agent-skills gsd-verifier)
 ```
 
-Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
+Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `reviewer_model`, `commit_docs`, `branch_name`, `quick_id`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
 
 ```bash
 USE_WORKTREES=$(gsd_run query config-get workflow.use_worktrees --raw 2>/dev/null || echo "true")
@@ -868,7 +868,7 @@ Agent(
   Output: ${QUICK_DIR}/${quick_id}-REVIEW.md
   Depth: quick",
   subagent_type="gsd-code-reviewer",
-  model="{executor_model}"
+  model="{reviewer_model}"
 )
 ```
 

package/gsd-core/workflows/review.md

@@ -234,7 +234,8 @@ GEMINI_MODEL=$(gsd_run query config-get review.models.gemini 2>/dev/null | jq -r
 CLAUDE_MODEL=$(gsd_run query config-get review.models.claude 2>/dev/null | jq -r '.' 2>/dev/null || true)
 CODEX_MODEL=$(gsd_run query config-get review.models.codex 2>/dev/null | jq -r '.' 2>/dev/null || true)
 OPENCODE_MODEL=$(gsd_run query config-get review.models.opencode 2>/dev/null | jq -r '.' 2>/dev/null || true)
-# review.models.agy is reserved for future model-pinning support; agy selects its model internally
+# review.models.agy, when set, is passed to agy as --model (escape hatch for a
+# pinned model that 404s server-side); otherwise agy uses its persisted default.
 AGY_MODEL=$(gsd_run query config-get review.models.agy 2>/dev/null | jq -r '.' 2>/dev/null || true)
 
 # #1115: `--dangerously-bypass-hook-trust` only exists on codex-cli >= 0.137.0.
@@ -373,7 +374,7 @@ fi
 
 **Antigravity CLI:**
 
-**Maintainer note — why this block has three layers (last updated against agy 1.0.2):**
+**Maintainer note — why this block has three layers (last updated against agy 1.0.16):**
 
 `agy -p` (the `--print` non-interactive flag) works correctly on macOS and Linux: it sends the
 prompt, receives the model response, and writes it to stdout. On **native Windows** it silently
@@ -408,7 +409,9 @@ and Step 3 fires with a clear error message in REVIEWS.md. No silent corruption.
 Invocation specifics (verified agy 1.0.0, macOS arm64 and Linux amd64):
 - `-p` takes the prompt as a **flag value** — `echo X | agy -p` errors with "flag needs an argument: -p"
 - `--print-timeout` defaults to 5m, aligning with this workflow's global timeout
-- No `-m` / `--model` flag — agy selects the model internally
+- `--model "<name>"` selects the model (available since agy ~1.0.3; `agy models` lists
+  them). When `review.models.agy` is set it is passed as `--model`; otherwise agy uses
+  its persisted default (`agy models`).
 
 ```bash
 # Pre-flight: snapshot the transcript watermark before invoking agy.
@@ -432,14 +435,41 @@ if [ -f "$_AGY_CACHE" ]; then
 fi
 
 # Step 1 — primary invocation: stdout works on macOS, Linux, and WSL.
-# Bound the run with agy's OWN `--print-timeout` (issue #687). On a large,
-# file-path-rich prompt agy's agentic Cascade can loop on its code_search/grep
-# steps and never converge; `--print-timeout` is agy's native cap for print mode
-# (defaults to 5m — see maintainer note above), so we pass it explicitly to let a
-# stalled run self-terminate through the tool's own mechanism. A non-zero exit
-# (timeout or crash) discards any partial output so the Step 2 transcript fallback
-# / Step 3 stub take over.
-agy --print-timeout 300s -p "$(cat /tmp/gsd-review-prompt-{phase}.md)" 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
+# Three hardening invariants (#2073), all mirroring the Cursor block's discipline:
+#   * FILE-REFERENCE prompt (not inline `$(cat …)`) — a large review prompt (≈197 KB
+#     for 6 plans + CONTEXT + RESEARCH + REQUIREMENTS) overflows the exec arg list
+#     (`bash: agy: Argument list too long`, rc 126), indistinguishable from a model
+#     failure when stderr is suppressed.
+#   * EXTERNAL `timeout` wrapper when available (GNU `timeout` / `gtimeout`) —
+#     `--print-timeout` is agy's native cap but it CANNOT fire before agy creates a
+#     session; under concurrent heavy runs one process can stall pre-session (no
+#     `brain/<conv-id>/` dir, alive at 583 s despite `--print-timeout 300s`). The
+#     external cap bounds wall-clock regardless. Stock macOS lacks `timeout`, so
+#     the block probes for it and falls back to --print-timeout alone there.
+#   * `--model` from `review.models.agy` when set — escape hatch for a pinned model
+#     that 404s server-side (exits 0 with empty stdout AND empty transcript).
+#   * stdin tied to /dev/null so agy never blocks on a tty.
+# A non-zero exit (external timeout = 124, crash, etc.) discards any partial output
+# so the Step 2 transcript fallback / Step 3 diagnostic take over.
+if [ -n "$AGY_MODEL" ] && [ "$AGY_MODEL" != "null" ]; then
+  set -- --model "$AGY_MODEL"
+else
+  set --
+fi
+_AGY_PROMPT="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. Output only the resulting markdown review. Do not edit any files."
+# Capability-probe an external wall-clock killer (GNU coreutils `timeout` or the
+# macOS Homebrew `gtimeout`). Stock macOS ships NEITHER — a bare `timeout …` would
+# fail with rc 127 ("command not found") and silently lose the reviewer, so fall
+# back to agy's native --print-timeout alone in that case. The external cap, when
+# available, is set HIGHER than --print-timeout so it only backstops a pre-session
+# stall (which --print-timeout cannot bound — #2073 mode 3) and never pre-empts a
+# healthy run. Mirrors the probe in scripts/base64-scan.sh.
+_AGY_KILLER="$(command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null || true)"
+if [ -n "$_AGY_KILLER" ]; then
+  "$_AGY_KILLER" 600 agy --print-timeout 540s "$@" -p "$_AGY_PROMPT" </dev/null 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
+else
+  agy --print-timeout 540s "$@" -p "$_AGY_PROMPT" </dev/null 2>/dev/null > /tmp/gsd-review-antigravity-{phase}.md
+fi
 _AGY_RC=$?
 if [ "$_AGY_RC" -ne 0 ]; then
   : > /tmp/gsd-review-antigravity-{phase}.md
@@ -473,9 +503,25 @@ if [ ! -s /tmp/gsd-review-antigravity-{phase}.md ]; then
   fi
 fi
 
-# Step 3 — final guard: both approaches yielded nothing (auth error, first-run setup, path schema changed, etc.)
+# Step 3 — final guard: both approaches yielded nothing (auth error, first-run setup,
+# path schema changed, 404'd pinned model, pre-session stall, etc.)
 if [ ! -s /tmp/gsd-review-antigravity-{phase}.md ]; then
-  echo "Antigravity review failed or returned empty output." > /tmp/gsd-review-antigravity-{phase}.md
+  {
+    echo "Antigravity review failed or returned empty output."
+    # #2073 mode 2: a pinned model that 404s exits 0 with empty stdout AND an empty
+    # transcript — the only evidence is in agy's own log. Surface it instead of a
+    # bare generic stub so the failure is diagnosable.
+    _AGY_LOG="$HOME/.gemini/antigravity-cli/cli.log"
+    if [ -f "$_AGY_LOG" ]; then
+      _AGY_ERR=$(grep -iE 'agent executor error|NOT_FOUND|Publisher model' "$_AGY_LOG" | tail -3)
+      if [ -n "$_AGY_ERR" ]; then
+        echo "agy log hint (pinned model may be unavailable — run 'agy models' and set review.models.agy):"
+        echo "$_AGY_ERR"
+      fi
+    fi
+    # #2073 mode 3: pre-session stall tell — no new conversation dir appeared.
+    echo "If no agy run started, that is the pre-session-stall case: check whether a new ~/.gemini/antigravity-cli/brain/<conv-id>/ dir appeared within ~30s of launch."
+  } > /tmp/gsd-review-antigravity-{phase}.md
 fi
 ```
 

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

@@ -354,13 +354,15 @@ Built-in tier defaults by runtime:
 | Runtime    | `opus`                        | `sonnet`                        | `haiku`                       |
 |------------|-------------------------------|---------------------------------|-------------------------------|
 | `claude`   | `claude-opus-4-8`             | `claude-sonnet-5`             | `claude-haiku-4-5`            |
-| `codex`    | `gpt-5.5`                     | `gpt-5.4`                       | `gpt-5.4-mini`                |
+| `codex`    | `gpt-5.6-sol`                 | `gpt-5.6-terra`                 | `gpt-5.6-luna`                |
 | `gemini`   | `gemini-3.1-pro-preview`      | `gemini-3-flash`                | `gemini-2.5-flash-lite`       |
 | `qwen`     | `qwen3-max-2026-01-23`        | `qwen3-coder-plus`              | `qwen3-coder-next`            |
 | `opencode` | `anthropic/claude-opus-4-8`   | `anthropic/claude-sonnet-5`   | `anthropic/claude-haiku-4-5`  |
 | `copilot`  | `claude-opus-4-8`             | `claude-sonnet-5`             | `claude-haiku-4-5`            |
 | `hermes`   | `anthropic/claude-opus-4-8`   | `anthropic/claude-sonnet-5`   | `anthropic/claude-haiku-4-5`  |
-| Group B (`kilo`, `cline`, `cursor`, `windsurf`, `augment`, `trae`, `codebuddy`, `antigravity`) | (no built-in default — your runtime handles model selection) | | |
+| `kilo`     | `anthropic/claude-opus-4-8`   | `anthropic/claude-sonnet-5`   | `anthropic/claude-haiku-4-5`  |
+| `pi`       | `claude-opus-4-8`             | `claude-sonnet-5`             | `claude-haiku-4-5`            |
+| Group B (`cline`, `cursor`, `windsurf`, `augment`, `trae`, `codebuddy`, `antigravity`) | (no built-in default — your runtime handles model selection) | | |
 
 Display a table to the user showing the effective configuration:
 
@@ -387,8 +389,8 @@ AskUserQuestion([
     options: [
       { label: "Keep current (<runtime>)", description: "Configure overrides for the current runtime." },
       { label: "Common runtimes", description: "claude, codex, gemini, qwen" },
-      { label: "Additional runtimes", description: "opencode, copilot, hermes" },
-      { label: "Other (Group B or custom)", description: "kilo, cline, cursor, windsurf, augment, trae, codebuddy, antigravity, or a custom runtime string." }
+      { label: "Additional runtimes", description: "opencode, copilot, hermes, kilo" },
+      { label: "Other (Group B or custom)", description: "cline, cursor, windsurf, augment, trae, codebuddy, antigravity, or a custom runtime string." }
     ]
   }
 ])
@@ -423,7 +425,8 @@ AskUserQuestion([
     options: [
       { label: "opencode", description: "OpenCode (uses anthropic/ prefix)." },
       { label: "copilot", description: "GitHub Copilot." },
-      { label: "hermes", description: "Hermes (uses anthropic/ prefix)." }
+      { label: "hermes", description: "Hermes (uses anthropic/ prefix)." },
+      { label: "kilo", description: "Kilo Code (uses anthropic/ prefix)." }
     ]
   }
 ])
@@ -627,7 +630,7 @@ AskUserQuestion([
     options: [
       { label: "anthropic", description: "claude-opus-4-8 / claude-sonnet-5 / claude-haiku-4-5 (Anthropic / Claude)" },
       { label: "anthropic-fable", description: "claude-fable-5 / claude-sonnet-5 / claude-haiku-4-5 (Anthropic / Claude Fable opt-in)" },
-      { label: "openai", description: "gpt-5.5 / gpt-5.4 / gpt-5.4-mini (OpenAI / Codex)" },
+      { label: "openai", description: "gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna (OpenAI / Codex)" },
       { label: "Other known provider", description: "Type google or qwen; both still use the canonical tier mapping." }
     ]
   }
@@ -662,9 +665,9 @@ Canonical tier mappings by provider and budget:
 | anthropic-fable | high   | claude-fable-5             | claude-fable-5             | claude-sonnet-5          |
 | anthropic-fable | medium | claude-opus-4-8            | claude-sonnet-5          | claude-haiku-4-5           |
 | anthropic-fable | low    | claude-haiku-4-5           | claude-haiku-4-5           | claude-haiku-4-5           |
-| openai    | high   | gpt-5.5                    | gpt-5.5                    | gpt-5.5                    |
-| openai    | medium | gpt-5.5                    | gpt-5.4                    | gpt-5.4-mini               |
-| openai    | low    | gpt-5.4-mini               | gpt-5.4-mini               | gpt-5.4-mini               |
+| openai    | high   | gpt-5.6-sol                | gpt-5.6-sol                | gpt-5.6-sol                |
+| openai    | medium | gpt-5.6-sol                | gpt-5.6-terra              | gpt-5.6-luna               |
+| openai    | low    | gpt-5.6-luna               | gpt-5.6-luna               | gpt-5.6-luna               |
 | google    | high   | gemini-3.1-pro-preview     | gemini-3.1-pro-preview     | gemini-3.1-pro-preview     |
 | google    | medium | gemini-3.1-pro-preview     | gemini-3-flash             | gemini-2.5-flash-lite      |
 | google    | low    | gemini-2.5-flash-lite      | gemini-2.5-flash-lite      | gemini-2.5-flash-lite      |

package/gsd-core/workflows/settings.md

@@ -73,8 +73,8 @@ Parse current values (default to `true` if not present):
 ```
 Note: Quality, Balanced, Budget, and Adaptive profiles assign semantic tiers
 (Opus/Sonnet/Haiku) to each agent. When `runtime` is set in .planning/config.json,
-tiers resolve to runtime-native model IDs — on Codex that's gpt-5.5 / gpt-5.4 /
-gpt-5.4-mini with appropriate reasoning effort. See "Runtime-Aware Profiles" in
+tiers resolve to runtime-native model IDs — on Codex that's gpt-5.6-sol / gpt-5.6-terra /
+gpt-5.6-luna with appropriate reasoning effort. See "Runtime-Aware Profiles" in
 docs/CONFIGURATION.md.
 
 If `runtime` is unset on a non-Claude runtime, the profile tiers have no effect on

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

@@ -223,7 +223,7 @@ Agent(
 ## 8. Handle Checker Return
 
 **If `## UI-SPEC VERIFIED`:**
-Display dimension results. Proceed to step 10.
+Display dimension results. Proceed to step 9.5.
 
 **If `## ISSUES FOUND`:**
 Display blocking issues. Proceed to step 9.
@@ -264,6 +264,151 @@ Options:
 
 Use AskUserQuestion for the choice.
 
+**On "Force approve":** proceed to step 9.5 (the UI-consideration probe still runs on the accepted UI-SPEC, so state coverage is recorded even when quality FLAGs were accepted), then step 10. **On "Edit manually" / "Abandon":** exit without running the probe.
+
+## 9.5. UI-Consideration Probe (post-verification)
+
+Run AFTER the checker approves the UI-SPEC (VERIFIED, or force-approved at step 9) — never inline
+during authoring, so a revision-loop researcher rewrite (step 9) cannot clobber the section and the
+`## UI Considerations` block is committed with the FINAL UI-SPEC. This is the visual analog of
+spec-phase Step 5.5's edge probe, retargeted to the UI element/state axis. Reference:
+@~/.claude/gsd-core/references/ui-consideration-probe.md.
+
+**Skip conditions:** if `--auto` and the UI-SPEC already carries a resolved `## UI Considerations`
+section (re-run), the write-back is idempotent (it REPLACES that section, never appends). If the
+runtime is non-Claude and the probe engine cannot be resolved, the shim FAILS LOUD (below) — it
+never silently no-ops (a silent skip would drop the whole state-coverage axis).
+
+**Runtime coverage compute — resolve and invoke ui-consideration-probe.cjs:**
+
+```bash
+# Resolve the compiled ui-consideration-probe.cjs against the GSD install dir via RUNTIME_DIR
+# (#448) — NOT the consuming project's git root — falling back to git toplevel / $HOME/.claude.
+# Mirrors spec-phase.md Step 5.5's edge-probe resolution idiom verbatim (same candidate paths).
+_GSD_RT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+UI_PROBE_JS=$(for _c in \
+  "$_GSD_RT/gsd-core/bin/lib/ui-consideration-probe.cjs" \
+  "$_GSD_RT/bin/lib/ui-consideration-probe.cjs" \
+  "$_GSD_RT/.claude/bin/lib/ui-consideration-probe.cjs" \
+  "$HOME/.claude/gsd-core/bin/lib/ui-consideration-probe.cjs" \
+  "$HOME/.claude/bin/lib/ui-consideration-probe.cjs"; do
+  [ -f "$_c" ] && { echo "$_c"; break; }
+done)
+
+# Graceful degradation — never a silent skip. Build ONLY when $_GSD_RT is a verified GSD source
+# checkout (has tsconfig.build.json + src/ui-consideration-probe.cts), pinned with --prefix so we
+# never trigger the CONSUMING project's own build during a ui-phase. Real installs ship the
+# compiled .cjs via prepublishOnly, so this path only matters in a GSD dev checkout.
+if [ -z "$UI_PROBE_JS" ]; then
+  if [ -f "$_GSD_RT/tsconfig.build.json" ] && [ -f "$_GSD_RT/src/ui-consideration-probe.cts" ]; then
+    npm --prefix "$_GSD_RT" run build:lib 2>/dev/null || true
+    UI_PROBE_JS=$(for _c in \
+      "$_GSD_RT/gsd-core/bin/lib/ui-consideration-probe.cjs" \
+      "$_GSD_RT/bin/lib/ui-consideration-probe.cjs" \
+      "$_GSD_RT/.claude/bin/lib/ui-consideration-probe.cjs" \
+      "$HOME/.claude/gsd-core/bin/lib/ui-consideration-probe.cjs" \
+      "$HOME/.claude/bin/lib/ui-consideration-probe.cjs"; do
+      [ -f "$_c" ] && { echo "$_c"; break; }
+    done)
+  fi
+  if [ -z "$UI_PROBE_JS" ]; then
+    echo "ERROR: ui-consideration-probe.cjs not found — reinstall GSD or run \`npm run build:lib\` in your GSD checkout." >&2
+    exit 1
+  fi
+fi
+
+# Element extraction (MANUAL BY DESIGN — not an oversight): the agent reads the researcher-authored
+# UI-SPEC prose (the described surfaces — the Design System / Copywriting rows and any element the
+# researcher named) and writes ONE object per UI element/surface: {"id","text"} where text is the
+# prose describing it. This mirrors spec-phase Step 5.5's edge-probe REQS_JSON step VERBATIM — a
+# hand-populated heredoc guarded by the fail-loud <replace:> check below — the established, shipped
+# pattern for feeding a probe from a prose spec. It is NOT mechanized on purpose: a UI-SPEC has no
+# single machine-parseable "elements" column — surfaces are distributed across design-token tables
+# (Design System / Typography / Color), the Copywriting section, and prose the researcher names, so a
+# regex/table parse would fail-OPEN (miss a prose-named surface, or feed a design-token row as a bogus
+# element). The agent-authored heredoc + fail-loud guard is the conservative choice, identical to the
+# requirement-side edge-probe path (RR-04). If a future UI-SPEC gains a canonical element table,
+# revisit to parse it. Populate the heredoc from the UI-SPEC; the guard below fails loud on a
+# forgotten substitution (never a no-op).
+ELEMENTS_JSON=$(mktemp "${TMPDIR:-/tmp}/ui-probe-elements-XXXXXX") && mv "$ELEMENTS_JSON" "${ELEMENTS_JSON}.json" && ELEMENTS_JSON="${ELEMENTS_JSON}.json" || exit 1
+cat > "$ELEMENTS_JSON" <<'JSON'
+[
+  { "id": "E1", "text": "<replace: element/surface description from the UI-SPEC prose>" }
+]
+JSON
+if ! node -e 'const a=require(process.argv[1]);if(!Array.isArray(a)||a.length===0)process.exit(1);if(a.some(e=>typeof e.text!=="string"||!e.text.trim()||e.text.includes("<replace:")))process.exit(1)' "$ELEMENTS_JSON" 2>/dev/null; then
+  rm -f "$ELEMENTS_JSON"
+  echo "ERROR: ui-probe elements JSON is empty/invalid or still holds the <replace: …> placeholder — populate \$ELEMENTS_JSON from the UI-SPEC's described surfaces before this step runs." >&2
+  exit 1
+fi
+# Invoke the compiled engine and CAPTURE its report. FATAL-INVOKE GUARD: use `if ! COVERAGE=$(…)`,
+# NEVER a bare `COVERAGE=$(node …)` — a bare capture swallows the engine's exit 2 (invalid shape /
+# bad input) and falls through to prose re-derivation: fail-OPEN at the exact boundary the engine
+# validation protects.
+if ! COVERAGE=$(node "$UI_PROBE_JS" "$ELEMENTS_JSON"); then
+  rm -f "$ELEMENTS_JSON"
+  echo "ERROR: ui-consideration-probe engine failed (invalid shapes or bad input) — fix the element(s) and re-run; never proceed with empty coverage." >&2
+  exit 1
+fi
+rm -f "$ELEMENTS_JSON"
+# Malformed-report guard: exit 0 but garbage. The report must parse as { items[], coverage{} }.
+if ! printf '%s' "$COVERAGE" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let r;try{r=JSON.parse(s)}catch{process.exit(1)}if(!r||!Array.isArray(r.items)||typeof r.coverage!=="object"||r.coverage===null)process.exit(1)})'; then
+  echo "ERROR: ui-consideration-probe produced an unparseable or malformed coverage report — refusing to proceed with the resolution loop." >&2
+  exit 1
+fi
+# Zero-applicable guard: a report where NO category applied across ANY element is far more likely a
+# classification miss (or malformed elements) than a genuinely state-free UI. Surface it loudly.
+APPLICABLE=$(printf '%s' "$COVERAGE" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let n=0;try{n=JSON.parse(s).coverage.applicable}catch{n=0}process.stdout.write(String(n))})')
+if [ "$APPLICABLE" = "0" ]; then
+  echo "WARNING: ui-consideration-probe proposed ZERO applicable categories across all elements — likely a classification miss or malformed elements, not a genuinely state-free UI. Do NOT silently write an empty UI Considerations section." >&2
+fi
+```
+
+If `$APPLICABLE` is `0`, do NOT proceed silently: ask via AskUserQuestion ("The UI probe found no
+applicable state considerations — is this genuinely a state-free surface, or should we revisit the
+element descriptions?"). Only write an empty section after explicit confirmation.
+
+**Propose-then-confirm (the partial-cue mitigation — load-bearing).** For each element, the engine
+reports the DETECTED element kinds (`classifyElement` over the built `.cjs`). The prose classifier
+is heuristic and LOSSY: a surface that is genuinely both a form and a list, but whose prose trips
+only the form cue, under-covers — and because SOMETHING classified, no `unclassified` signal fires.
+So SURFACE the detected kinds to the user (AskUserQuestion) and ask whether any real element kind
+was missed. If the user ADDs a kind, re-run that element with an authored `elements` override
+(the union of detected + added) so the missed categories are raised. A single tripped cue is a
+SIGNAL, not proof the element is only that kind — the confirm step, not the heuristic, is what makes
+coverage sound.
+
+**Resolution loop** (mirror spec-phase 5.5): resolve each applicable consideration via
+AskUserQuestion — **Specify** (→ `covered`, write a concrete truth) / **Dismiss (reason required)** /
+**Backstop** (a held-out/visual UI-state test) / **Defer** (→ `unresolved`). An `unclassified` row is
+a manual-review nudge, not a hard block. Text mode (`workflow.text_mode` / `--text`) → numbered lists.
+
+**Kind-confirmation under `--auto`.** The propose-then-confirm step above is an AskUserQuestion, so
+under `--auto` it follows the spec-phase 5.5 convention (replace AskUserQuestion with Claude's
+recommended choice): Claude re-reads each element's prose and authors the `elements` override (the
+union of the detected kinds + any kind it identifies as missed) instead of prompting — so `--auto`
+recall rests on Claude's kind-identification, not the heuristic cue-match alone. This matters because
+`autoResolve` (below) is a RESOLUTION floor only: it resolves the *detected* categories and cannot
+recover a kind that was never surfaced, so recall is fixed HERE, at kind-confirmation, before
+resolution runs.
+
+**`--auto` mode (two layers).** The adapter's `autoResolve` is the CODE floor: every applicable
+consideration auto-`backstop`s (carrying the taxonomy question as its resolution) and an
+`unclassified` candidate stays `unresolved` — it NEVER auto-`dismiss`es and never auto-backstops an
+unclassified item (#1110). On top of that floor the workflow MAY upgrade an item to `covered` when a
+defensible acceptance criterion can be written (the same judgment spec-phase 5.5 applies in prose).
+An auto `--auto` run therefore leaves un-upgraded backstops as `backstop`: at verify time each one
+with no wired evidence routes to `insufficient_spec → human_needed` — never a silent pass (#1154).
+That surfacing is the intended honest-verifier behavior, not over-flagging.
+
+**Write-back.** Populate a `## UI Considerations` section in the UI-SPEC from the resolved
+considerations, in the format the shipped plan-phase `## UI Considerations` lift rule reads:
+`covered` → a truth string; `backstop` → a flat scalar `{ statement, verification: backstop }`;
+`unresolved` → an explicit `⚠ unresolved — planner must treat as assumption` row. Empty-state and
+error-state COPY stays in `## Copywriting Contract` — the considerations section covers shape-rooted
+STATE coverage and REFERENCES those rows rather than restating the copy (de-dup). IDEMPOTENT: if a
+`## UI Considerations` section already exists, REPLACE it — never append a duplicate.
+
 ## 10. Present Final Status
 
 Display:

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

@@ -122,11 +122,11 @@ Handle return:
 
 **State B (create):**
 1. Read template from `~/.claude/gsd-core/templates/VALIDATION.md`
-2. Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
+2. Fill: frontmatter (**set `status: validated`**), Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
 3. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
 
 **State A (update):**
-1. Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter
+1. Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter (**set `status: validated`**)
 2. Append audit trail:
 
 ```markdown

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

@@ -288,14 +288,15 @@ if [ -z "$TEST_CMD" ]; then
     echo "⚠ No test runner detected — skipping test suite"
   fi
 fi
-# Detect test runner and run all tests (timeout: 5 minutes)
+# Run all tests (timeout: 5 min). #1857: normalize to one-shot so watch mode exits.
+TEST_CMD=$(gsd_run query normalize-test-command "$TEST_CMD" --cwd . 2>/dev/null || echo "$TEST_CMD")
 TEST_EXIT=0
 timeout 300 bash -c "$TEST_CMD" 2>&1
 TEST_EXIT=$?
 if [ "${TEST_EXIT}" -eq 0 ]; then
   echo "✓ Test suite passed"
 elif [ "${TEST_EXIT}" -eq 124 ]; then
-  echo "⚠ Test suite timed out after 5 minutes"
+  echo "⚠ Test suite timed out after 5 minutes — likely watch/dev mode"
 else
   echo "✗ Test suite failed (exit code ${TEST_EXIT})"
 fi

package/gsd-core/workflows/verify-work.md

@@ -58,6 +58,44 @@ MVP_MODE=$(gsd_run query phase.mvp-mode "${phase_number}" ${GSD_WS} --pick activ
 ```
 </step>
 
+<step name="verify_pre_hooks">
+**Verify:pre gate dispatch.** Before verification begins, dispatch every active
+gate hook registered at the `verify:pre` loop extension point. Each gate is
+data-driven — resolved from the capability registry, not hardcoded here.
+
+```bash
+VERIFY_PRE_HOOKS_JSON=$(gsd_run loop render-hooks verify:pre --raw)
+PHASE_DIR=$(printf '%s' "$INIT" | jq -r '.phase_dir // empty')
+```
+
+Resolve active gate hooks from `VERIFY_PRE_HOOKS_JSON` where `kind == "gate"`.
+For each active gate hook, run its declared check (a `check.query` gate runs
+`gsd_run check ${hook.check.query} "${PHASE_DIR}" --raw`; a `predicate` gate
+runs `gsd_run check predicate --predicate '<hook.check.predicate as JSON>' --phase-dir "${PHASE_DIR}" --raw`):
+
+```bash
+GATE_RESULT=$(gsd_run check "${hook_check_query}" "${PHASE_DIR}" --raw)
+GATE_BLOCK=$(printf '%s' "$GATE_RESULT" | jq -r '.block // false' 2>/dev/null || echo "false")
+```
+
+**Two-step gate contract (same as execute:wave:post / execute:post):**
+
+- **Step 1 — command failure:** if the `gsd_run check ...` invocation itself
+  fails (non-zero exit, no JSON), route by the gate's `onError`. An `onError:
+  halt` gate HALTs; an `onError: skip` gate logs a warning and continues.
+- **Step 2 — block evaluation:** parse `GATE_RESULT.block`. For a **blocking
+  gate** (`hook.blocking == true`) with `block == true`: HALT — do not begin UAT,
+  present the gate's `message`, and tell the user what artifact resolves it. For
+  a **non-blocking gate** with a non-empty `message`: print
+  `⚠ {hook.capId} advisory: {GATE_RESULT.message}` and continue. For any gate
+  with `block == false`: continue silently.
+
+Example — the `ai-integration` capability's `api-coverage.verify-pre` gate
+(when `workflow.api_coverage_gate` is on) blocks here if the phase integrates an
+external API without a decided COVERAGE.md matrix. Present its `message` and
+point the user at producing COVERAGE.md before re-running verification.
+</step>
+
 <step name="check_active_session">
 **First: Check for active UAT sessions**