@opengsd/gsd-core 1.7.0-rc.5 → 1.7.0

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/workflows/add-tests.md

@@ -308,7 +308,7 @@ If there are passing tests to commit:
 
 ```bash
 git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command" -- {test files}
 ```
 
 Present next steps:

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/debug.md

@@ -190,6 +190,8 @@ Create `.planning/debug/{slug}.md` with initial state using the Write tool (neve
 
 After initial context setup, spawn the session manager to handle the full checkpoint/continuation loop. The session manager handles specialist_hint dispatch internally: when gsd-debugger returns ROOT CAUSE FOUND it extracts the specialist_hint field and invokes the matching skill (e.g. typescript-expert, swift-concurrency) before offering fix options.
 
+> **Foreground, blocking spawn — #2196.** The `Agent(subagent_type="gsd-debug-session-manager", …)` call below is FOREGROUND and BLOCKING — it returns the compact session summary directly. Wait for it; do not background it, and do not poll for it. Never pass an agent or session identifier to `TaskOutput` — an agent ID is NOT a task ID, so `TaskOutput <agent-id>` always returns `No task found with ID`. If the spawn returns no usable result (the handoff is lost), do NOT claim the session is still running: preserve the checkpoint at `.planning/debug/{slug}.md`, report the failed handoff plainly, and resume by re-spawning the session manager or via `/gsd:debug continue {slug}`.
+
 Print before spawning (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 ```
 [debug] Delegating loop to session manager...

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

@@ -1056,11 +1056,13 @@ AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "fal
 ```
 
 When executor returns a checkpoint AND `AUTO_MODE` is `true`:
-- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
-- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
+- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`. **Except `blocking-human`.**
+- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`. **Except `blocking-human`.**
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
 
-**Standard flow (not auto-mode, or human-action type):**
+**Carve-out — overrides all branches above.** If the returned `Gate:` is `blocking-human`, or its `<what-built>` mentions `Package verification required before install` or `Package install failed — human verification required`, never auto-approve or auto-select, regardless of type. Present to user (standard flow below). Log `⛔ blocking-human gate — auto-mode suspended`.
+
+**Standard flow (not auto-mode, human-action, or blocking-human):**
 
 1. Spawn agent for checkpoint plan
 2. Agent runs until checkpoint task or auth gate → returns structured state

package/gsd-core/workflows/fast.md

@@ -64,32 +64,18 @@ Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`
 
 <step name="log_to_state">
 If `.planning/STATE.md` exists and has a "Quick Tasks Completed" table, append a row
-that matches the existing table's schema. If no table exists, skip silently.
-If the table's schema is unrecognized, skip with a brief log rather than append a
-malformed row.
+that matches the existing table's schema via the schema-backed `gsd-tools
+quick-tasks-append` helper (`markdown-table.cjs`'s `appendQuickTaskRow`; #2133,
+ADR-2143 §3/§7). If no table exists, skip silently. If the table's schema is
+unrecognized, the helper fails loud (non-zero exit) instead of silently guessing
+a column count — this replaces the prior inline `awk NF-2` arithmetic that was
+the root cause of #2133.
 
 ```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
 # Detect whether STATE.md has a Quick Tasks Completed table
 if grep -q "Quick Tasks Completed" .planning/STATE.md 2>/dev/null; then
-  # Read the table header line to determine the column schema.
-  # quick.md Step 7 creates a 5-column table:
-  #   | # | Description | Date | Commit | Directory |
-  # Count pipe characters in the header to determine column count.
-  HEADER_LINE=$(grep -A2 "Quick Tasks Completed" .planning/STATE.md 2>/dev/null | grep "^|" | head -1)
-  # Count columns: number of | separators minus 1 gives column count
-  COL_COUNT=$(echo "$HEADER_LINE" | awk -F'|' '{print NF-1}')
-
-  if [ "$COL_COUNT" -eq 5 ] && echo "$HEADER_LINE" | grep -qi "Description" && echo "$HEADER_LINE" | grep -qi "Commit" && echo "$HEADER_LINE" | grep -qi "Directory"; then
-    # 5-column schema from quick.md Step 7: | # | Description | Date | Commit | Directory |
-    # Determine the next row number by counting existing data rows (non-separator, non-header).
-    NEXT_NUM=$(awk '/Quick Tasks Completed/{found=1} found && /^\|/ && !/^[|][-: |]*[|]$/ && !/Description/{count++} END{print count+1}' .planning/STATE.md 2>/dev/null || echo "1")
-    # Get the latest commit hash (short)
-    COMMIT_HASH=$(git rev-parse --short HEAD 2>/dev/null || echo "—")
-    echo "| $NEXT_NUM | $TASK | $(date +%Y-%m-%d) | $COMMIT_HASH | — |" >> .planning/STATE.md
-  else
-    # Unrecognized table schema — skip to avoid appending a malformed row.
-    echo "⚠ fast.md log_to_state: Quick Tasks Completed table has unrecognized schema (${COL_COUNT} columns); skipping STATE.md update."
-  fi
+  gsd_run quick-tasks-append --task "$TASK" || echo "⚠ fast.md log_to_state: could not append Quick Tasks row (see message above); continuing."
 fi
 ```
 </step>

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
@@ -808,6 +812,7 @@ Output consumed by /gsd:execute-phase. Plans need:
 - 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. **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>
 
@@ -854,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/progress.md

@@ -536,7 +536,7 @@ State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
 | Condition | Meaning | Action |
 |-----------|---------|--------|
 | current phase < highest phase | More phases remain | Go to **Route C** |
-| current phase = highest phase | Milestone complete | Go to **Route D** |
+| current phase = highest phase | All phases complete | Go to **Route D** |
 
 ---
 
@@ -602,7 +602,7 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 ---
 
-**Route D: Milestone complete**
+**Route D: All phases complete (milestone ready to close)**
 
 ```
 ---

package/gsd-core/workflows/quick.md

@@ -971,6 +971,8 @@ Use `date` from init:
 | ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) |
 ```
 
+For a schema-safe append outside this workflow (e.g. from fast.md), `gsd-tools quick-tasks-append --task <text>` performs the equivalent write via the shared, schema-backed `appendQuickTaskRow` helper (#2133, ADR-2143 §3/§7).
+
 **7d. Update "Last activity" line:**
 
 Use `date` from init:

package/gsd-core/workflows/review.md

@@ -255,6 +255,8 @@ shell-interpolated). Exact invocation in `gsd-core/references/reviewer-instances
 
 For each selected CLI, invoke in sequence (not parallel — avoid rate limits):
 
+**Timeout guidance (#2194):** prompt-fed source-grounded reviews are slow — measured ~570s for Codex at `xhigh` effort and ~525s for headless Claude on a large plan set. Each of the Gemini / Claude / Codex blocks below MUST be invoked with a high Bash `timeout:` — at least `900000` (15 min), and `1200000` (20 min) for Codex `xhigh` or headless Claude — so a lane is not killed mid-review. On Claude Code, raise the host cap via `BASH_MAX_TIMEOUT_MS` if a review can exceed it. A silent empty output after a long run is a **timeout kill, not a crash** — the Codex `0xc0000142` misdiagnosis persisted because the empty-output branches below cannot distinguish the two; treat an empty result on a slow lane as a dropped lane and re-run with more time rather than diagnosing a CLI/sandbox failure. A cross-AI review that silently drops a lane is blind in one eye.
+
 **Gemini:**
 ```bash
 if [ -n "$GEMINI_MODEL" ] && [ "$GEMINI_MODEL" != "null" ]; then
@@ -364,7 +366,12 @@ fi
 # prompt as an ARGUMENT, not stdin. A full review prompt can exceed the OS argument limit, so
 # reference the prompt file by path rather than inlining it. Capture stderr so a failure is
 # diagnosable instead of a silent empty result.
-CURSOR_PROMPT_ARG="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."
+# #2176: same absolute-root anchor as the Antigravity block — cursor-agent runs
+# in the repo cwd, but repo-relative references in the assembled prompt still
+# need an explicit root to resolve against. rev-parse (not bare pwd) so the
+# anchor is correct even when /gsd:review is invoked from a repo subdirectory.
+_CURSOR_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+CURSOR_PROMPT_ARG="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. The repository under review is at $_CURSOR_ROOT — resolve every relative file path in the review request against that absolute root. Output only the resulting markdown review. Do not edit any files."
 cursor-agent -p --mode ask --trust --output-format text "$CURSOR_PROMPT_ARG" 2>/tmp/gsd-review-cursor-{phase}.err > /tmp/gsd-review-cursor-{phase}.md
 if [ ! -s /tmp/gsd-review-cursor-{phase}.md ]; then
   echo "Cursor review failed or returned empty output. stderr:" > /tmp/gsd-review-cursor-{phase}.md
@@ -456,7 +463,19 @@ if [ -n "$AGY_MODEL" ] && [ "$AGY_MODEL" != "null" ]; then
 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."
+# #2176: grant the reviewer the repo under review. Without --add-dir, agy's
+# permission context never receives the cwd repo — the agent anchors on its own
+# ~/.gemini/antigravity-cli/scratch dir and reviews the plan text in isolation
+# (the exact failure the Review Instructions forbid). Capability-probed like the
+# Codex bypass flag so an older agy without --add-dir still runs; the prompt
+# anchor below keeps absolute-path reads possible on that fallback.
+if agy --help 2>/dev/null | grep -q -- '--add-dir'; then
+  set -- "$@" --add-dir "$_AGY_WS"
+fi
+# #2176: anchor the prompt to the absolute repo root so repo-relative references
+# in the assembled review prompt resolve even on the no---add-dir fallback, and
+# require an explicit self-report if the reviewer still cannot read the repo.
+_AGY_PROMPT="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. The repository under review is at $_AGY_WS — resolve every relative file path in the review request against that absolute root and verify claims against those files. If you cannot read files under $_AGY_WS, begin your output with the exact line REVIEWED-WITHOUT-REPO-ACCESS before the review. 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
@@ -523,6 +542,26 @@ if [ ! -s /tmp/gsd-review-antigravity-{phase}.md ]; then
     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
+
+# #2176: blind-review marker. Two tells that the reviewer ran without repo
+# access: the prompt's mandated REVIEWED-WITHOUT-REPO-ACCESS self-report in the
+# first lines of output, or the agent DECLARING the scratch dir as its
+# workspace. Both patterns are anchored — the self-report to the head of the
+# file, the scratch tell to a workspace-declaration phrasing — so a grounded
+# review that merely QUOTES these strings (e.g. reviewing this very file) is
+# never mis-stamped. Stamp a machine-readable marker so the Consensus Summary
+# down-weights the review instead of counting an ungrounded verdict at full
+# weight. (Temp file + mv, no in-place sed — BSD/GNU safe.)
+if [ -s /tmp/gsd-review-antigravity-{phase}.md ] && \
+   { head -5 /tmp/gsd-review-antigravity-{phase}.md | grep -q 'REVIEWED-WITHOUT-REPO-ACCESS' || \
+     grep -qiE '(workspace|working) (directory|dir).{0,40}antigravity-cli/scratch' /tmp/gsd-review-antigravity-{phase}.md; }; then
+  {
+    echo "> [reviewed-without-repo-access] This reviewer ran without visibility into the repo under review — down-weight its verdict in the Consensus Summary."
+    echo ""
+    cat /tmp/gsd-review-antigravity-{phase}.md
+  } > /tmp/gsd-review-antigravity-{phase}.md.tmp && \
+  mv /tmp/gsd-review-antigravity-{phase}.md.tmp /tmp/gsd-review-antigravity-{phase}.md
+fi
 ```
 
 **Ollama (local, OpenAI-compatible):**
@@ -835,7 +874,7 @@ trimmed_reviewers:        # only present if at least one reviewer was trimmed
 
 ## Consensus Summary
 
-{synthesize common concerns across all reviewers. CodeRabbit is a diff-only reviewer (it never received the source-grounding prompt), so do not weight its verdict as a grounded plan review — fold in its diff findings, but base plan-level consensus on the prompt-fed reviewers.}
+{synthesize common concerns across all reviewers. CodeRabbit is a diff-only reviewer (it never received the source-grounding prompt), so do not weight its verdict as a grounded plan review — fold in its diff findings, but base plan-level consensus on the prompt-fed reviewers. A reviewer output carrying the `[reviewed-without-repo-access]` marker (or beginning with `REVIEWED-WITHOUT-REPO-ACCESS`) ran without repo access (#2176) — treat it the same way: note its concerns, but do not count its verdict at full consensus weight.}
 
 ### Agreed Strengths
 {strengths mentioned by 2+ reviewers}

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

@@ -108,7 +108,7 @@ Agent(
     "<files_to_read>{PLAN, SUMMARY, impl files, SECURITY.md}</files_to_read>" +
     "<threat_register>{threat register}</threat_register>" +
     "<config>asvs_level: {SECURITY_ASVS}, block_on: {SECURITY_BLOCK_ON}</config>" +
-    "<constraints>Never modify implementation files. Verify mitigations exist — do not scan for new threats. Escalate implementation gaps.</constraints>" +
+    "<constraints>Never modify implementation files. Verify mitigations exist — do not scan for new threats. Escalate implementation gaps. Return a structured verdict only — do NOT write SECURITY.md (the orchestrator owns the file write).</constraints>" +
     "${AGENT_SKILLS_AUDITOR}",
   subagent_type="gsd-security-auditor",
   model="{AUDITOR_MODEL}",

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

@@ -360,7 +360,9 @@ Built-in tier defaults by runtime:
 | `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)." }
     ]
   }
 ])

package/gsd-core/workflows/ship.md

@@ -394,9 +394,15 @@ gsd_run query state.update "Last Activity" "$(date +%Y-%m-%d)"
 gsd_run query state.update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}"
 ```
 
-If `commit_docs` is true:
+If `commit_docs` is true, commit the ship-note AND push it onto the PR branch so
+it reaches the default branch when the PR merges. Without this push the ship-note
+commit stays local-only and is silently discarded when the branch is deleted on
+merge (#2138). The `[ci skip]` trailer suppresses the redundant pipeline the push
+would otherwise trigger (GitHub honors `[ci skip]` / `[skip ci]`):
+
 ```bash
-gsd_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .planning/STATE.md
+gsd_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER} [ci skip]" --files .planning/STATE.md
+git push origin ${CURRENT_BRANCH} 2>&1 || echo "⚠ track_shipping: ship-note push failed — it is local-only; rerun: git push origin ${CURRENT_BRANCH}"
 ```
 </step>
 

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

@@ -456,7 +456,7 @@ Write to: `{phase_dir}/{padded_phase}-SPEC.md`
 
 ```bash
 git add "${phase_dir}/${padded_phase}-SPEC.md"
-git commit -m "spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)"
+git commit -m "spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)" -- "${phase_dir}/${padded_phase}-SPEC.md"
 ```
 
 If `commit_docs` is false: Skip commit. Note that SPEC.md was written but not committed.

package/gsd-core/workflows/transition.md

@@ -597,7 +597,7 @@ Do NOT auto-invoke any further slash commands.
 
 ---
 
-**Route B: Milestone complete (all phases done)**
+**Route B: All phases complete (milestone ready to close)**
 
 **This route is only reached when:**
 - `is_last_phase: true` AND no other active workstreams exist (or flat mode)