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

package/gsd-core/references/api-coverage.md

@@ -0,0 +1,104 @@
+# API Coverage Gate (Full Coverage by Default — Opt Out, Never Opt In)
+
+> Reference for the `api-coverage` gate on the `ai-integration` capability (#1562).
+> Config key: `workflow.api_coverage_gate` (default `true`). Gate point: `verify:pre`.
+
+## The problem this closes
+
+"We integrated the API" too often silently means "we integrated whatever the
+first use case exercised." Every un-built capability is then an invisible hole,
+discovered later by a user who reasonably expected it to work. The phase sealed
+green because its tasks completed — nobody *decided* the gaps were acceptable,
+because nobody *enumerated* them.
+
+This gate makes the API surface **visible and decided** before the phase can
+seal. Full coverage is the default starting position; the coverage matrix is the
+*subtraction record*. Every gap is an explicit, reasoned opt-out rather than a
+surprise.
+
+## When it fires
+
+The gate runs at `verify:pre` (before `/gsd:verify-work` begins UAT). A phase is
+treated as an external-API integration when **either**:
+
+1. a `COVERAGE.md` matrix is present in the phase directory (the planner produced
+   one at `plan:pre`), **or**
+2. the phase scope shows a strong external-API-integration signal (an integration
+   verb co-occurring with an external-API noun, or an explicit `<Service>
+   API|SDK|REST|GraphQL` surface) and no matrix yet exists.
+
+Non-API phases (refactors, bug fixes, internal-only work, features that merely
+*mention* an existing internal API) do **not** fire the gate — the trigger
+requires a compound signal, so a bare word like "api" in "the public API of
+UserController" is intentionally ignored.
+
+## The two touch points
+
+1. **Plan time (`plan:pre`).** A contribution to the planner prompts it to run
+   the deterministic detector over the phase scope and, when an integration is
+   detected, produce `COVERAGE.md`. See
+   `capabilities/ai-integration/fragments/api-coverage-plan-pre.md`.
+2. **Seal time (`verify:pre`).** The blocking `api-coverage.verify-pre` gate
+   runs `check api-coverage.verify-pre <phase-dir>` and blocks unless a valid
+   matrix exists (or no integration is detected).
+
+## The coverage matrix format
+
+Canonical form — a markdown table (human-editable, diff-friendly):
+
+```markdown
+# API Coverage — <service>
+
+> Full coverage by default. Opt-outs are explicit, reasoned decisions.
+
+| capability | decision | reason |
+|---|---|---|
+| search | INTEGRATE | |
+| playlists | INTEGRATE | |
+| skip | OPT-OUT | not needed yet — tracked for follow-up phase |
+```
+
+- **`INTEGRATE` is the default.** Every capability starts as INTEGRATE.
+- **Every `OPT-OUT` MUST carry a one-line reason** (`not needed`, `not needed
+  yet`, `explicitly out of scope`, …). An opt-out without a reason is an
+  un-decided hole — the exact failure mode this gate exists to close.
+- A fenced ` ```coverage ` JSON block (`[{"capability":…,"decision":…,"reason":…}]`)
+  is also accepted for machine-generated matrices.
+
+Rules enforced at seal time: the matrix must be non-empty; every capability name
+must be non-empty and unique; every decision must be `INTEGRATE` or `OPT-OUT`;
+every `OPT-OUT` must have a reason. Violations block the seal with a precise
+error.
+
+## A second integration against the same need
+
+A second platform for an existing capability (e.g. adding YouTube alongside
+Spotify for media playback) starts from the **same full-coverage baseline** as
+the first. Do not carry over the first integration's opt-outs silently —
+re-decide each capability for the new surface, so a first-class/fallback
+asymmetry cannot accumulate into a later user-facing bug.
+
+## The matrix persists
+
+`COVERAGE.md` is a phase artifact. A future phase that extends the same
+integration starts from the recorded surface and decisions rather than from
+zero — the matrix is the durable subtraction record.
+
+## Tuning
+
+- **Disable entirely:** set `workflow.api_coverage_gate: false` in
+  `.planning/config.json` (the gate unregisters from `verify:pre`).
+- **Widen the trigger vocabulary:** the detector accepts `--verbs` / `--nouns`
+  overrides (see `capabilities/ai-integration/fragments/api-coverage-plan-pre.md`).
+  The default vocabulary is additive-only.
+
+## Detector CLI
+
+```bash
+echo "$PHASE_SCOPE" | node gsd-core/bin/lib/api-coverage.cjs --json
+# exit 0 = integration detected, 1 = none, 2 = startup error
+```
+
+The detector is a pure function (`detectApiIntegration` → `{ detected, signals,
+terms }`) shared by the plan-time prompt and the seal-time gate, so the
+low-false-positive guarantee is testable rather than a judgment call.

package/gsd-core/references/model-profiles.md

@@ -45,10 +45,10 @@ Model profiles control which Claude model each GSD agent uses. This allows balan
 | Phase type | Agents |
 |---|---|
 | `planning` | gsd-planner, gsd-roadmapper, gsd-pattern-mapper |
-| `discuss` | (reserved — no subagent today) |
+| `discuss` | `gsd-assumptions-analyzer` |
 | `research` | gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-codebase-mapper, gsd-ui-researcher |
 | `execution` | gsd-executor, gsd-debugger, gsd-doc-writer |
-| `verification` | gsd-verifier, gsd-plan-checker, gsd-integration-checker, gsd-nyquist-auditor, gsd-ui-checker, gsd-ui-auditor, gsd-doc-verifier |
+| `verification` | gsd-verifier, gsd-plan-checker, gsd-integration-checker, gsd-nyquist-auditor, gsd-ui-checker, gsd-ui-auditor, gsd-doc-verifier, gsd-code-reviewer |
 | `completion` | (reserved — no subagent today) |
 
 ### Resolution precedence (highest to lowest)

package/gsd-core/references/planning-config.md

@@ -256,6 +256,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.node_repair` | boolean | `true` | `true`, `false` | Attempt automatic repair of failed plan nodes |
 | `workflow.node_repair_budget` | number | `2` | Any positive integer | Max repair retries per failed node |
 | `workflow.ai_integration_phase` | boolean | `true` | `true`, `false` | Run /gsd:ai-integration-phase before planning AI system phases |
+| `workflow.api_coverage_gate` | boolean | `true` | `true`, `false` | Require an explicit API-coverage decision (full-by-default, opt-out-not-opt-in) before a phase that integrates an external API/SDK/service can seal. At plan:pre prompts a COVERAGE.md matrix; at verify:pre a blocking gate fails the seal unless the matrix exists with every non-integrated capability an explicit, reasoned opt-out (#1562) |
 | `workflow.ui_phase` | boolean | `true` | `true`, `false` | Generate UI-SPEC.md for frontend phases |
 | `workflow.ui_safety_gate` | boolean | `true` | `true`, `false` | Require safety gate approval for UI changes |
 | `workflow.text_mode` | boolean | `false` | `true`, `false` | Use plain-text numbered lists instead of AskUserQuestion menus |
@@ -269,6 +270,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.mvp_mode` | boolean | `false` | `true`, `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces (progress, stats, graphify) all treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability. |
 | `workflow.context_guard_mode` | string | `"warn"` | `"auto"`, `"warn"`, `"off"` | Context exhaustion guard mode for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using degradation signals from `context-budget.md`. `"warn"` (default): emit a warning and recommend `/gsd:pause-work` when POOR tier is detected. `"auto"`: automatically invoke `/gsd:pause-work` before the next wave when POOR tier is detected. `"off"`: disable the guard. The guard is heuristic — no programmatic context-% API exists. |
 | `workflow.plan_chunked` | boolean | `false` | `true`, `false` | Enable chunked planning mode. When `true`, the plan-phase orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3–5 min each). Each plan is committed individually for crash resilience. Particularly useful on Windows where long-lived Tasks may hang on stdio. Also activated by the `--chunked` flag. |
+| `workflow.specless_probe_fallback` | boolean | `true` | `true`, `false` | Gate the SPEC-less probe fallback in `plan-phase`. When `true` (default), a phase that did not supply a `## Edge Coverage` / `## Prohibitions` SPEC section (header absent or present-but-empty) runs the existing probe protocol — the deterministic `edge-probe.cjs` for edges and an in-planner LLM recall pass for prohibitions — and authors the resulting predicates into PLAN.md `must_haves` (section-level precedence: a SPEC-supplied section is never re-run or overwritten). When `false`, the fallback is skipped but the skip is recorded: plan-phase emits a visible "probe fallback disabled" marker, never a silent skip. |
 | `workflow.code_review_command` | string\|null | `null` | Any shell command | External code-review command integrated into `/gsd:ship`. The diff is piped to the command via stdin; the command must output JSON with a `verdict` field (`"APPROVED"` or `"REVISE"`). Non-zero exit or `"REVISE"` verdict blocks the ship workflow. When unset, the built-in review flow runs. Example: `my-review-tool --review`. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
 | `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow |

package/gsd-core/references/specless-probe-fallback.md

@@ -0,0 +1,172 @@
+# Spec-less Probe Fallback — protocol
+
+Lazy-loaded by `workflows/plan-phase.md` step 7.95 (the gate) and the `<specless_probe_fallback>`
+planner block. When a phase SPEC did NOT supply `## Edge Coverage` / `## Prohibitions`, plan-phase
+runs the same probe protocol the SPEC path uses and authors the predicates into PLAN.md `must_haves`
+(ADR-857 Phase 6 — the *else branch* of the `<downstream_consumer>` SPEC-conditional lift). This is
+core workflow-body substrate — NOT the `PLAN_PRE_HOOKS_JSON contribution into planner` capability rail
+(D-03). Section absence is detected by the shared `spec-section` helper in the gate; this file holds the
+*run-the-probe* half so the capped plan-phase.md stays lean (#717/#1074 budget).
+
+## 0. Gate — toggle + per-section absence (run first, in the orchestrator)
+
+Reads the default-ON toggle and computes `EDGE_ABSENT` / `PROHIB_ABSENT` via the shared `spec-section`
+helper; records a VISIBLE skip when disabled or when the phase has no requirement IDs (never a silent
+skip, never a hard-fail). Sets `SPECLESS_FALLBACK`, `EDGE_ABSENT`, `PROHIB_ABSENT`, and
+`SPECLESS_FALLBACK_DISABLED` for §A and the planner prompt.
+
+```bash
+# Toggle defaults ON (D-04 / RAIL-05): any value other than literal "false" enables.
+SPECLESS_CFG=$(gsd_run query config-get workflow.specless_probe_fallback 2>/dev/null || echo "true")
+SPECLESS_FALLBACK=true; [[ "$SPECLESS_CFG" == "false" ]] && SPECLESS_FALLBACK=false
+
+# Per-section absence (D-05 / RAIL-03): "not supplied" = header absent OR present-but-empty. The
+# shared, tested `spec-section` helper (src/spec-section.cts -> bin/lib/spec-section.cjs) is the SINGLE
+# source of truth for the canonical SPEC headings (suffix-tolerant) and table-row counting, replacing
+# ad-hoc awk (contract pinned by tests/spec-section.test.cjs). Resolve via the edge-probe install-dir
+# idiom; build only in a source checkout, else fail loud (never silently mis-detect).
+_GSD_RT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+_gsd_lib() { for _d in "$_GSD_RT/gsd-core/bin/lib" "$_GSD_RT/bin/lib" "$_GSD_RT/.claude/bin/lib" "$HOME/.claude/gsd-core/bin/lib" "$HOME/.claude/bin/lib"; do [ -f "$_d/$1" ] && { echo "$_d/$1"; return; }; done; }
+SPEC_SECTION_JS=$(_gsd_lib spec-section.cjs)
+if [ -z "$SPEC_SECTION_JS" ] && [ -f "$_GSD_RT/tsconfig.build.json" ] && [ -f "$_GSD_RT/src/spec-section.cts" ]; then
+  npm --prefix "$_GSD_RT" run build:lib 2>/dev/null || true; SPEC_SECTION_JS=$(_gsd_lib spec-section.cjs)
+fi
+[ -n "$SPEC_SECTION_JS" ] || { echo "ERROR: spec-section.cjs not found - reinstall GSD or run build:lib." >&2; exit 1; }
+# supplied => header present AND >=1 row; missing $SPEC_FILE => supplied:false => fallback fires.
+EDGE_ABSENT=1;   node "$SPEC_SECTION_JS" "$SPEC_FILE" edges       2>/dev/null | grep -q '"supplied":true' && EDGE_ABSENT=0
+PROHIB_ABSENT=1; node "$SPEC_SECTION_JS" "$SPEC_FILE" prohibitions 2>/dev/null | grep -q '"supplied":true' && PROHIB_ABSENT=0
+
+# Disabled path - record the skip VISIBLY, never silently (RAIL-05 / PROH-4); the note rides into the
+# planner prompt (Step 8) so the plan records that no probe predicates were generated.
+SPECLESS_FALLBACK_DISABLED=""
+if [[ "$SPECLESS_FALLBACK" != "true" ]]; then
+  echo "WARNING: probe fallback disabled (workflow.specless_probe_fallback=false); skip recorded, not silent." >&2
+  SPECLESS_FALLBACK_DISABLED="probe fallback disabled (workflow.specless_probe_fallback=false): no probe-derived predicates generated for SPEC-absent sections this run."
+fi
+
+# Nothing-to-probe guard: the fallback derives predicates from requirement TEXT, so zero requirement
+# IDs => nothing to probe => skip VISIBLY (like the disabled path), NOT a hard-fail. Prevents a
+# no-SPEC + no-requirements phase from aborting under the default-ON fallback. The orchestrator
+# substitutes {phase_req_ids}; empty/whitespace/TBD => no requirements. (A still-literal token is
+# non-empty, so an unsubstituted run correctly hits the reference's fail-loud guard instead.)
+SPECLESS_REQ_IDS="{phase_req_ids}"
+if [[ "$SPECLESS_FALLBACK" == "true" ]] && { [ -z "${SPECLESS_REQ_IDS// /}" ] || [ "${SPECLESS_REQ_IDS}" = "TBD" ]; }; then
+  echo "info: spec-less probe fallback: phase has no requirement IDs - nothing to probe; skipping (visible skip)." >&2
+  SPECLESS_FALLBACK=false
+  SPECLESS_FALLBACK_DISABLED="spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)."
+fi
+```
+
+## A. Edge probe (deterministic) — run when `SPECLESS_FALLBACK=true` AND `EDGE_ABSENT=1`
+
+Mirrors spec-phase Step 5.5 verbatim; the ONLY divergence (D-02) is sourcing `$REQS_JSON` from the
+phase requirement IDs (`{phase_req_ids}`) instead of a SPEC interview. Leave `$COVERAGE` empty when
+`EDGE_ABSENT=0` — a SPEC-supplied section is never re-run (section-level precedence).
+
+```bash
+# Resolve the compiled edge-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 (spec-phase.md:198 idiom).
+_GSD_RT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+EDGE_PROBE_JS=$(for _c in \
+  "$_GSD_RT/gsd-core/bin/lib/edge-probe.cjs" "$_GSD_RT/bin/lib/edge-probe.cjs" \
+  "$_GSD_RT/.claude/bin/lib/edge-probe.cjs" "$HOME/.claude/gsd-core/bin/lib/edge-probe.cjs" \
+  "$HOME/.claude/bin/lib/edge-probe.cjs"; do [ -f "$_c" ] && { echo "$_c"; break; }; done)
+# Build ONLY inside a verified GSD source checkout; --prefix pins npm so we never trigger the
+# consuming project's build:lib. Never silent-skip (RR-04) — fail loud if unresolvable.
+if [ -z "$EDGE_PROBE_JS" ]; then
+  if [ -f "$_GSD_RT/tsconfig.build.json" ] && [ -f "$_GSD_RT/src/edge-probe.cts" ]; then
+    npm --prefix "$_GSD_RT" run build:lib 2>/dev/null || true
+    EDGE_PROBE_JS=$(for _c in \
+      "$_GSD_RT/gsd-core/bin/lib/edge-probe.cjs" "$_GSD_RT/bin/lib/edge-probe.cjs" \
+      "$_GSD_RT/.claude/bin/lib/edge-probe.cjs" "$HOME/.claude/gsd-core/bin/lib/edge-probe.cjs" \
+      "$HOME/.claude/bin/lib/edge-probe.cjs"; do [ -f "$_c" ] && { echo "$_c"; break; }; done)
+  fi
+  [ -n "$EDGE_PROBE_JS" ] || { echo "ERROR: edge-probe.cjs not found — reinstall GSD or run \`npm run build:lib\`." >&2; exit 1; }
+fi
+
+# THE ONE DIVERGENCE (D-02): source requirements from THIS phase. Populate the heredoc from
+# {phase_req_ids}, pulling each requirement's text from REQUIREMENTS.md: {"id","text","shapes"?}.
+# mktemp suffix trick is BSD/GNU portable (#1520).
+REQS_JSON=$(mktemp "${TMPDIR:-/tmp}/edge-probe-reqs-XXXXXX") && mv "$REQS_JSON" "${REQS_JSON}.json" && REQS_JSON="${REQS_JSON}.json" || exit 1
+cat > "$REQS_JSON" <<'JSON'
+[
+  { "id": "R1", "text": "<replace: requirement text from REQUIREMENTS.md for each {phase_req_ids} id>" }
+]
+JSON
+# Guard — fail loud on empty/invalid array OR a still-present `<replace:>` placeholder (forgotten
+# substitution would yield a bogus report). Never a silent no-op.
+if ! node -e 'const a=require(process.argv[1]);if(!Array.isArray(a)||a.length===0)process.exit(1);if(a.some(r=>typeof r.text!=="string"||!r.text.trim()||r.text.includes("<replace:")))process.exit(1)' "$REQS_JSON" 2>/dev/null; then
+  echo "ERROR: edge-probe requirements JSON is empty/invalid or still holds the <replace: …> placeholder — populate \$REQS_JSON from {phase_req_ids} before running." >&2
+  exit 1
+fi
+# Invoke + CAPTURE, exit-checked (engine FAILS CLOSED exit 2 on bad shape; a bare COVERAGE=$(node …)
+# would swallow it and fall through to prose re-derivation = fail-OPEN).
+if ! COVERAGE=$(node "$EDGE_PROBE_JS" "$REQS_JSON"); then
+  rm -f "$REQS_JSON"
+  echo "ERROR: edge-probe engine failed (invalid shapes or bad input) — fix the requirement(s); never proceed with empty coverage." >&2
+  exit 1
+fi
+rm -f "$REQS_JSON"
+# Exit-0-but-garbage guard: report must parse as JSON with { 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: edge-probe produced an unparseable/malformed coverage report — refusing to proceed." >&2
+  exit 1
+fi
+# Zero-applicable guard: surface a likely classification miss loudly (spec-phase 5.5:277 shape).
+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: edge-probe proposed ZERO applicable edges across all phase requirements — likely a classification miss, not a genuinely edge-free phase. Do NOT silently write an empty fallback Edge Coverage." >&2
+fi
+```
+
+**Edge `--auto` resolution rules (reuse spec-phase 5.5 verbatim, D-06):** auto-`covered` where a
+defensible acceptance criterion can be written (→ a plain `must_haves.truths` string); else
+auto-`backstop` → author it as a **structured flat-scalar marker** `{ statement: <the check>,
+verification: backstop }` in `must_haves.truths`, NOT a prose note (the verifier branches
+deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110
+fragility; flat scalar `verification:` key, never a nested object, ADR-550 #1278). A `backstop` truth
+the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason
+`insufficient_spec`), never a silent pass (#1154; `references/honest-verifier.md`). **Never
+auto-dismiss** (a wrong dismissal is the exact silent failure this eliminates). An `unclassified` row
+stays **`unresolved`** (#1110) — never auto-`backstop`ped — and is surfaced to the planner as a flagged
+assumption. Pass `$COVERAGE` (+ the gate's `$SPECLESS_FALLBACK_DISABLED` note) into the gsd-planner
+prompt (Step 8). When `EDGE_ABSENT=0`, `$COVERAGE` is empty and this does not run.
+
+## B. Prohibition recall (LLM prose pass) — run when `PROHIB_ABSENT=1`
+
+There is NO compiled prohibition engine and NO `node` invocation (ADR-550 D7b) — the gsd-planner runs
+this in-prompt. Full two-stage protocol, canon-referral rule, and status×verification schema live in
+`~/.claude/gsd-core/references/prohibition-probe.md` (do not inline it). Summary:
+
+- **Stage 1 — Recall (adversarial).** Per requirement: *"What could this feature silently become that
+  the author would NOT want, but the spec does not forbid?"* Over-produce (~10 raw must-NOT candidates).
+- **Stage 2 — Precision.** DROP routine-engineering (normal correctness/hygiene — owned by the edge
+  probe or code review); KEEP values / safety / ethics (~2–3 survive).
+- **Canon-referral drop (ADR-550 D6).** A kept candidate that is canon security/compliance (OWASP /
+  prototype-pollution / path-traversal / injection / GDPR / generic fairness) is NOT minted — emit a
+  one-line breadcrumb and DROP it.
+
+**Fallback `--auto` divergence (D-06 / RAIL-04 / PROH-1):** author each kept prohibition as
+**flagged-unverified with NO wired-check descriptor**. NEVER write `check_kind` / `check_target` /
+`check_rule` / `check_violation_fixture` / `check_clean_fixture` — there is no human to wire/verify a
+check, and a descriptor-less item is what keeps it fail-closed (it disposes
+`{status:'unverified', flagged:true}` downstream via the reused `dispositionForProhibition`). **Never
+auto-dismiss**; never fabricate a check path. Surface any `unresolved` prohibition as a flagged
+assumption — never a silent drop.
+
+## C. Authoring (the `<downstream_consumer>` else-branch)
+
+Author the fallback report into `must_haves` with the SAME lift the SPEC path uses — only the source
+changes (the fallback report, not the SPEC):
+
+- **Edges →** every `covered` edge's acceptance criterion → `must_haves.truths` as a plain string;
+  every `backstop` edge → `must_haves.truths` as a structured `{ statement, verification: backstop }`
+  marker (NOT prose; #1110/#1278), which abstains → `human_needed` at verify time when unconfirmed
+  (#1154); every `unresolved`/`unclassified` row → an explicit flagged assumption (never a silent drop).
+- **Prohibitions →** every kept prohibition → the `must_haves.prohibitions:` sibling block (NOT
+  `truths`, ADR-550 D3) via the single `projectProhibitions` serializer (Hyrum — no second
+  serializer), authored **descriptor-less** (no `check_*` scalar) so each disposes flagged-unverified.
+- **Section-level precedence:** a SPEC-supplied section is never re-run or overwritten — exactly one
+  producer per section.
+- **No-silent-drop equality:** for each section, (# probe-surfaced items) == (# authored into
+  `must_haves` + # surfaced as flagged assumptions).

package/gsd-core/references/ui-consideration-probe.md

@@ -0,0 +1,73 @@
+# UI-Consideration Probe — Spec-Completeness Reference
+
+The **third** adapter of the shared `probe-core` resolution model (ADR-550 Decision 7), on
+the **UI element/state axis**. It surfaces the shape-rooted UI *state* considerations a
+UI-SPEC must resolve before a dimension may PASS — the visual analog of the requirement-side
+[edge-probe](./edge-probe.md), reusing its exact lifecycle, validators, and plan-phase lift
+(see edge-probe.md for the shared status×verification model — this doc does not re-argue it).
+
+**Axis boundary (this is a MIXED axis).** This compiled taxonomy covers ONLY the finite,
+project-independent shape-rooted content/robustness states. The **open**, domain/UX-dependent
+considerations — real-time/offline/optimistic-UI, deep accessibility (WCAG breadth),
+internationalization / RTL depth, and emerging interaction paradigms — are open-ended and are
+prose-owned in the companion [domain-probes.md](./domain-probes.md) technology/UX bank, NOT
+here. Forcing them into a closed compiled taxonomy is the wrong model.
+
+## Inputs
+
+A list of UI elements, each a `{ id, text, elements? }` record where `text` is the
+researcher-authored description and `elements` is an optional author-supplied override of the
+element classification. The six element kinds are: `form`, `list-collection`, `nav`, `media`,
+`interactive-control`, `static-content`. When `elements` is absent, a heuristic classifier
+proposes kinds from the prose (propose-then-confirm) — the author may correct the kind.
+
+## Taxonomy (8 categories)
+
+Closed and small by design: the finite, project-independent content/robustness states every
+UI surface must account for. Growth toward open UX topics happens in `domain-probes.md`, not by
+bloating this closed core.
+
+| id | name | applies to element kinds | consideration question |
+|----|------|--------------------------|------------------------|
+| empty | Empty / no data | form, list-collection, media | What is shown when there is no data — zero items, an unfilled form, or absent media? |
+| loading | Loading / in-flight | form, list-collection, media, nav | What is shown while data or content is still loading (skeleton, spinner, progressive reveal)? |
+| error | Error / failure | form, list-collection, media, nav | What is shown when the load or submit fails (message, retry affordance, partial fallback)? |
+| populated | Populated / happy path | list-collection, media | What does the normal populated (happy-path) state look like at a typical volume of content? |
+| partial | Partial / incomplete | form, list-collection | What is shown for partial or incomplete data — some fields or rows present, others missing? |
+| overflow | Overflow / truncation | list-collection, nav, static-content | What happens when content exceeds its container — scroll, clip, wrap, or truncate? |
+| zero-one-many | Zero / one / many | list-collection | How does the layout read at zero, one, and many items (singular vs plural copy, spacing)? |
+| long-text | Long text | form, static-content, interactive-control, nav | What happens with unusually long text — truncation, wrapping, ellipsis, or reflow? |
+
+## Relevance filter + resolution states
+
+The probe reuses the edge-probe rails verbatim (ADR-550 Decision 7 — see
+[edge-probe.md](./edge-probe.md#relevance-filter--resolution-states) for the full model):
+
+1. **Relevance filter first.** Classify each element's kind(s), then raise only the categories
+   whose `applies to element kinds` intersect. A static label is never asked about loading or
+   empty state — that is what makes an unresolved consideration meaningful.
+2. **Dismissal requires a reason string.** Silence is not a resolution; the reason is the audit
+   trail.
+3. **Zero-classification surfaces one `unclassified` candidate (#1110).** An element whose prose
+   matched no kind cue yields exactly one soft `unclassified — review manually` item
+   (`category: "unclassified"`, `status: "unresolved"`) — never a silent drop, never a guessed
+   kind. `unclassified` is a review signal, **not** a ninth taxonomy category; an explicit
+   `elements: []` opt-out stays silent.
+
+Each raised consideration carries the shared two orthogonal axes — `status`
+(`resolved | dismissed | unresolved`) and, when resolved, a `verification` tier
+(`explicit | backstop`). A `backstop` consideration lifts into `must_haves.truths` and, at
+verify time, is confirmed only by explicit evidence (a wired held-out/property test) or routes
+to `insufficient_spec → human_needed` — never a silent pass (the honest-verifier disposition,
+#1154). See [honest-verifier.md](./honest-verifier.md).
+
+## Closed / open boundary
+
+The **8 ids above are the closed, compiled subset** — finite and project-independent, so a
+compiled taxonomy is legitimate (the same property that makes edge-probe's data-shape taxonomy
+closed). The **open subset is prose-owned in [domain-probes.md](./domain-probes.md)**:
+real-time/offline/optimistic-UI, deep accessibility (WCAG breadth), i18n / RTL depth, and
+emerging interaction paradigms (gesture/voice/reduced-motion/print) are open-ended and
+cue-triggered — they do not belong in this closed taxonomy. This probe **complements** the
+`gsd-ui-checker` six quality dimensions (it adds a state-coverage axis); it does not change the
+BLOCK/FLAG/PASS enum or the dimensions themselves.

package/gsd-core/templates/UI-SPEC.md

@@ -79,6 +79,31 @@ Accent reserved for: {explicit list — never "all interactive elements"}
 
 ---
 
+## UI Considerations
+
+> Populated by the ui-phase UI-consideration probe (Step 9.5) and lifted by plan-phase's
+> `## UI Considerations` lift rule via the identical rule as SPEC `## Edge Coverage`. Shape-rooted UI *state*
+> coverage (empty / loading / error / populated / partial / overflow / zero-one-many / long-text).
+> Empty-state and error-state COPY live in `## Copywriting Contract` above — this section covers
+> state coverage and REFERENCES those rows rather than restating the copy (de-dup).
+
+Applicable state considerations resolved: {N covered, M backstop, K unresolved — or "none applicable"}
+
+| Category | Element(s) | Status | Resolution / Reason |
+|----------|------------|--------|---------------------|
+| {empty} | {list-collection} | ✅ covered | {concrete truth string — e.g. "Empty results render the documented 'No results' copy"} |
+| {long-text} | {static-content} | 🧪 backstop | {held-out/visual UI-state test — lifts as `{ statement, verification: backstop }`} |
+| {overflow} | {list-collection} | ⚠ unresolved | {planner treats as assumption} |
+
+<!-- Status vocabulary (locked by probe-core projectTruths):
+     ✅ covered   → a plain truth string lifted into must_haves.truths
+     🧪 backstop  → a flat scalar { statement, verification: backstop }; at verify time, no explicit
+                    evidence → insufficient_spec → human_needed (never a silent pass, #1154)
+     ⚠ unresolved → an explicit planner assumption (surfaced, never silently dropped)
+     Rows are REPLACED (not appended) on a probe re-run — idempotent. -->
+
+---
+
 ## Registry Safety
 
 | Registry | Blocks Used | Safety Gate |

package/gsd-core/templates/VALIDATION.md

@@ -1,6 +1,8 @@
 ---
 phase: {N}
 slug: {phase-slug}
+# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
+# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
 status: draft
 nyquist_compliant: false
 wave_0_complete: false

package/gsd-core/templates/config.json

@@ -18,7 +18,8 @@
     "plan_bounce_passes": 2,
     "cross_ai_execution": false,
     "cross_ai_command": "",
-    "cross_ai_timeout": 300
+    "cross_ai_timeout": 300,
+    "test_gate_timeout": 600
   },
   "ship": {
     "pr_body_sections": []

package/gsd-core/workflows/audit-fix.md

@@ -124,7 +124,15 @@ if [ -z "$AUDIT_TEST_CMD" ]; then
     AUDIT_TEST_CMD="true"
   fi
 fi
-eval "$AUDIT_TEST_CMD" 2>&1 | tail -20
+# #1857: normalize to one-shot (defeat vitest/jest watch mode) + bound with a
+# timeout so a watch-mode runner cannot hang the audit gate indefinitely.
+AUDIT_TEST_CMD=$(gsd_run query normalize-test-command "$AUDIT_TEST_CMD" --cwd . 2>/dev/null || echo "$AUDIT_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 "$AUDIT_TEST_CMD" 2>&1 | tail -20
+AUDIT_TEST_EXIT=${PIPESTATUS[0]}
+if [ "$AUDIT_TEST_EXIT" -eq 124 ]; then
+  echo "✗ Audit test gate timed out after ${TEST_GATE_TIMEOUT}s — likely stuck in watch/dev mode (e.g. vitest without 'run'). Run tests one-shot (e.g. 'vitest run') or raise workflow.test_gate_timeout."
+fi
 ```
 
 **c. If tests pass** — commit atomically:

package/gsd-core/workflows/audit-milestone.md

@@ -153,17 +153,20 @@ Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` a
 
 If no active validate-phase step hook exists: skip entirely.
 
-For each phase directory, check `*-VALIDATION.md`. If exists, parse frontmatter (`nyquist_compliant`, `wave_0_complete`).
+For each phase directory, check `*-VALIDATION.md`. If exists, parse frontmatter (`status`, `nyquist_compliant`, `wave_0_complete`).
 
 Classify per phase:
 
 | Status | Condition |
 |--------|-----------|
-| COMPLIANT | `nyquist_compliant: true` and all tasks green |
-| PARTIAL | VALIDATION.md exists, `nyquist_compliant: false` or red/pending |
+| COMPLIANT | `status: validated` and `nyquist_compliant: true` and all tasks green |
+| PARTIAL | `status: validated` and (`nyquist_compliant: false` or red/pending) |
+| NOT-VALIDATED | `status: draft` (or absent) — validate-phase has not yet reconciled this file (#2117) |
 | MISSING | No VALIDATION.md |
 
-Add to audit YAML: `nyquist: { compliant_phases, partial_phases, missing_phases, overall }`
+> **NOT-VALIDATED vs PARTIAL (#2117):** A phase reads `status: draft` when it was seeded by plan-phase but never reconciled by validate-phase, OR when its `VALIDATION.md` predates the `status` field (files written before #2117 stay `draft` whether or not validation ran). In both cases `nyquist_compliant` is not authoritative, so this is a coverage TODO ("run validate-phase") — not a compliance failure. Re-running validate-phase promotes the file to `status: validated` and yields the real COMPLIANT/PARTIAL verdict. Only `status: validated` + `nyquist_compliant: false` is a genuine PARTIAL.
+
+Add to audit YAML: `nyquist: { compliant_phases, partial_phases, not_validated_phases, missing_phases, overall }`
 
 Discovery only — never auto-calls `/gsd:validate-phase`.
 

package/gsd-core/workflows/code-review-fix.md

@@ -23,6 +23,10 @@ INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_FIXER=$(gsd_run query agent-skills gsd-code-fixer)
 AGENT_SKILLS_REVIEWER=$(gsd_run query agent-skills gsd-code-reviewer)
+# #2072: resolve the routed models so model_overrides / models.<phaseType> are honored
+# (gsd-code-reviewer → "verification", gsd-code-fixer → "execution"); thread them below.
+REVIEWER_MODEL=$(gsd_run query resolve-model gsd-code-reviewer --raw)
+FIXER_MODEL=$(gsd_run query resolve-model gsd-code-fixer --raw)
 ```
 
 Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
@@ -194,7 +198,7 @@ echo "Fix scope: ${FIX_SCOPE}"
 Use Agent() to spawn agent:
 
 ```text
-Agent(subagent_type="gsd-code-fixer", prompt="
+Agent(subagent_type="gsd-code-fixer", model="{FIXER_MODEL}", prompt="
 <files_to_read>
 ${REVIEW_PATH}
 </files_to_read>
@@ -277,7 +281,7 @@ if [ "$AUTO_MODE" = "true" ]; then
     
     # Spawn gsd-code-reviewer agent to re-review (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
     # (This overwrites REVIEW_PATH with latest review state)
-    Agent(subagent_type="gsd-code-reviewer", prompt="
+    Agent(subagent_type="gsd-code-reviewer", model="{REVIEWER_MODEL}", prompt="
 <config>
 depth: ${REVIEW_DEPTH}
 phase_dir: ${PHASE_DIR}
@@ -311,7 +315,7 @@ ${AGENT_SKILLS_REVIEWER}")
     # Still has issues — spawn fixer again (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
     echo "Issues remain. Applying fixes for iteration ${ITERATION}..."
     
-    Agent(subagent_type="gsd-code-fixer", prompt="
+    Agent(subagent_type="gsd-code-fixer", model="{FIXER_MODEL}", prompt="
 <files_to_read>
 ${REVIEW_PATH}
 </files_to_read>

package/gsd-core/workflows/code-review.md

@@ -22,6 +22,9 @@ PHASE_ARG="${1}"
 INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_REVIEWER=$(gsd_run query agent-skills gsd-code-reviewer)
+# #2072: resolve the routed model so model_overrides / models.verification are honored
+# (the resolver maps gsd-code-reviewer → phaseType "verification"); thread it below.
+REVIEWER_MODEL=$(gsd_run query resolve-model gsd-code-reviewer --raw)
 ```
 
 Parse from init JSON: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `padded_phase`, `commit_docs`.
@@ -482,7 +485,7 @@ Spawn the gsd-code-reviewer agent:
 Print: `◆ Spawning code reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
 
 ```
-Agent(subagent_type="gsd-code-reviewer", prompt="
+Agent(subagent_type="gsd-code-reviewer", model="{REVIEWER_MODEL}", prompt="
 <files_to_read>
 ${FILES_TO_READ}
 </files_to_read>

package/gsd-core/workflows/discuss-phase-assumptions.md

@@ -68,6 +68,9 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 INIT=$(gsd_run query init.phase-op "${PHASE}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_ANALYZER=$(gsd_run query agent-skills gsd-assumptions-analyzer)
+# #2072: resolve the routed model so model_overrides / models.discuss are honored
+# (the resolver maps gsd-assumptions-analyzer → phaseType "discuss"); thread it below.
+ANALYZER_MODEL=$(gsd_run query resolve-model gsd-assumptions-analyzer --raw)
 ```
 
 Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`,
@@ -255,7 +258,7 @@ If no USER-PROFILE.md: calibration_tier = "standard"
 **Spawn Explore subagent** (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)**:**
 
 ```
-Agent(subagent_type="gsd-assumptions-analyzer", prompt="""
+Agent(subagent_type="gsd-assumptions-analyzer", model="{ANALYZER_MODEL}", prompt="""
 Analyze the codebase for Phase {PHASE}: {phase_name}.
 
 Phase goal: {roadmap_description}

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

@@ -94,14 +94,18 @@ if [ -z "$TEST_CMD" ]; then
     echo "⚠ No test runner detected — skipping post-merge test gate"
   fi
 fi
-# Run test suite with 5-minute timeout
+# #1857: normalize to a one-shot form (defeat vitest/jest watch mode) via the
+# same shared normalize-test-command helper the regression gate uses, then bound
+# with the configured timeout so a watch-mode runner cannot hang the gate.
+TEST_CMD=$(gsd_run query normalize-test-command "$TEST_CMD" --cwd . 2>/dev/null || echo "$TEST_CMD")
+TEST_GATE_TIMEOUT=$(gsd_run query config-get workflow.test_gate_timeout 2>/dev/null || echo "600")
 TEST_EXIT=0
-timeout 300 bash -c "$TEST_CMD" 2>&1
+timeout "$TEST_GATE_TIMEOUT" bash -c "$TEST_CMD" 2>&1
 TEST_EXIT=$?
 if [ "${TEST_EXIT}" -eq 0 ]; then
   echo "✓ Post-merge test gate passed — no cross-plan conflicts"
 elif [ "${TEST_EXIT}" -eq 124 ]; then
-  echo "⚠ Post-merge test gate timed out after 5 minutes"
+  echo "⚠ POST-MERGE TEST GATE TIMED OUT after ${TEST_GATE_TIMEOUT}s — the runner did not exit, likely stuck in watch/dev mode (e.g. vitest without 'run'). Verify tests with a one-shot command (e.g. 'vitest run') or raise workflow.test_gate_timeout."
 else
   echo "✗ Post-merge test gate failed (exit code ${TEST_EXIT})"
   WAVE_FAILURE_COUNT=$((WAVE_FAILURE_COUNT + 1))
@@ -110,7 +114,7 @@ fi
 
 **If `TEST_EXIT` is 0 (pass):** `✓ Post-merge test gate: {N} tests passed — no cross-plan conflicts` → continue to orchestrator tracking update.
 
-**If `TEST_EXIT` is 124 (timeout):** Log warning, treat as non-blocking, continue. Tests may need a longer budget or manual run.
+**If `TEST_EXIT` is 124 (timeout):** The runner did not exit within the budget — surface the printed message clearly (watch/dev mode is the likely cause; #1857). Treated as non-blocking (a genuinely long suite may just need a larger `workflow.test_gate_timeout`), but it is NEVER silently ignored — the watch-mode cause is named so the user can fix it (one-shot command / `workflow.test_command` / larger timeout).
 
 **If `TEST_EXIT` is non-zero (test failure):** Increment `WAVE_FAILURE_COUNT` to track
 cumulative failures across waves. Subsequent waves should report: