@opengsd/gsd-core 1.11.0 → 1.13.0

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

@@ -37,7 +37,7 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 If $ARGUMENTS contains a phase number, load context:
 
 ```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
+_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}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; 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
 GSD_WS=""
 echo "$ARGUMENTS" | grep -qE -- '--ws[[:space:]]+[A-Za-z0-9._-]+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE -- '--ws[[:space:]]+[A-Za-z0-9._-]+')
 PHASE_ARG=$(echo "$ARGUMENTS" | sed -E 's/--ws[[:space:]]+[A-Za-z0-9._-]+//g' | xargs)
@@ -50,7 +50,7 @@ AGENT_SKILLS_CHECKER=$(gsd_run query agent-skills gsd-plan-checker)
 
 Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `has_verification`, `uat_path`, `state_path`, `roadmap_path`, `response_language`.
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 ```bash
 # MVP mode detection via the centralized phase.mvp-mode resolver.
@@ -61,15 +61,26 @@ 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.
+**Verify:pre capability dispatch.** Before verification begins, dispatch every
+active hook registered at the `verify:pre` loop extension point — of **every**
+kind, not gates alone. Each hook 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')
 ```
 
+Read the `activeHooks` array from `VERIFY_PRE_HOOKS_JSON` in-context (do NOT pipe through a shell parser).
+
+**If `activeHooks` is empty or absent:** skip silently to `check_active_session`.
+
+**Contribution dispatch:** inject every `kind == "contribution"` fragment per @gsd-core/references/loop-hook-dispatch.md (skip when none), before the steps and gates below.
+
+**Step dispatch:** dispatch every `kind == "step"` hook per @gsd-core/references/loop-hook-dispatch.md (skip when none) — not one shape of one. A step here is advisory: it never blocks the start of UAT, and a step that errors is routed by its own `onError` without failing verification. ⚠ **Validate `ref.command` in-context before any shell use** (third-party manifest input) — loop-hook-dispatch.md § `step`.
+
+Record the union of `produces` artefact names declared by the active step entries as `VERIFY_PRE_PRODUCED` — `extract_tests` consumes it below. An entry declaring `produces: []` contributes nothing, which is the normal case.
+
 ⚠ **Validate `check` before shell use** (third-party manifest input) — `loop-hook-dispatch.md` § `gate`.
 
 Resolve active gate hooks from `VERIFY_PRE_HOOKS_JSON` where `kind == "gate"`.
@@ -161,6 +172,27 @@ ls "$phase_dir"/*-SUMMARY.md 2>/dev/null || true
 ```
 
 Read each SUMMARY.md to extract testable deliverables.
+
+**Commit-claim reconciliation (#3968).** A SUMMARY's `commits:` frontmatter is a MEASURED
+number (the executor derives it from its on-disk plan commit ledger and records the base as
+`plan_head_before:`), and this is where that claim is checked against reality with the SAME
+instrument — the executor's own narration is never the last word. For each `*-SUMMARY.md`:
+```bash
+BASE=$(grep -oE '^plan_head_before: [0-9a-f]{7,40}' "$SUMMARY_FILE" | awk '{print $2}')
+CLAIMED=$(grep -oE '^commits: [0-9]+' "$SUMMARY_FILE" | grep -oE '[0-9]+' || echo absent)
+ACTUAL=$(git rev-list --count "${BASE}"..HEAD)
+```
+- A `commits: absent` or `plan_head_before: absent` SUMMARY (pre-#3968 legacy) is reported as
+  a WARNING with the measured git state, not a mismatch.
+- `ACTUAL == CLAIMED` is consistent. `ACTUAL == CLAIMED + 1` is ALSO consistent: the
+  SUMMARY/metadata commit itself lands after the executor measured, so exactly one
+  post-measurement commit is expected.
+- Anything else is a **BLOCKER** — the phase must not read as done: real project evidence
+  (#3968) showed 14 plans declaring `commits: 1` with zero git activity, their code sitting
+  uncommitted and one `git reset --hard` from loss. Record it as `commit_claim_mismatch`
+  with both numbers and the SUMMARY path; a mismatch means either the executor narrated
+  instead of measuring or commits were lost after the fact — both require reconciliation
+  before the phase can pass.
 </step>
 
 <step name="extract_tests">
@@ -187,6 +219,35 @@ Read the JSON result (`mode`, `total`, `all_auto_covered`, `auto_passed[]`, `pre
 
 The cold-start smoke test injection below still applies in `coverage` mode.
 
+**Verify:pre produced-artefact seam (#3866).** If `VERIFY_PRE_PRODUCED` (recorded in
+`verify_pre_hooks`) is empty or absent, skip this paragraph entirely — derivation is unchanged.
+Otherwise, for each artefact name in it, locate the artefact the producing step wrote under
+`$PHASE_DIR` and merge its checkpoints into the test list **additively**.
+
+**The artefact contract.** A consumable artefact is a Markdown file holding a list of checkpoint
+entries in the **same shape `extract_tests` already emits and `create_uat_file` already consumes** —
+each entry a `name` (brief test name) and an `expected` (specific, user-observable outcome).
+Nothing else is read: extra fields are ignored, not an error. There is no new schema and no new
+parser — a producing step writes what a checkpoint already looks like. An artefact that yields zero
+parseable entries is treated exactly like an absent one (see below).
+
+Merge rules:
+
+- ⚠ **Validate the artefact name in-context before resolving it** (third-party manifest input).
+  An artefact name is a registry-declared name, **not** a path: check the value you read from
+  `produces` against `^[A-Za-z0-9][A-Za-z0-9._-]*$` yourself — **never** by pasting it into a
+  shell command to be tested there. A name carrying `/`, `..`, a leading `-`, a leading path
+  separator, or any shell metacharacter is a malformed manifest: record a warning, skip that
+  name, continue. Only a validated name is resolved, and only against what the step wrote inside
+  `$PHASE_DIR` — never above it, and never through a symlink that leaves it.
+- A name with no artefact on disk means that step was inactive, skipped, or failed. Note it to the
+  user and derive normally — **never drop a deliverable and never block UAT over it.**
+- Merged entries are added to, never subtracted from, what `coverage:` classification and the
+  prose fallback produce. An `auto_passed[]` entry stays un-presented; a `present[]` entry stays a
+  human checkpoint. This seam can deepen UAT, not suppress it.
+- Deduplicate against already-derived checkpoints by `name`, keeping the earlier entry's
+  `expected` text so a produced artefact cannot silently rewrite a criterion.
+
 **Extract testable deliverables from SUMMARY.md (legacy fallback — used when `mode: legacy`):**
 
 Parse for:
@@ -534,6 +595,8 @@ VERIFY_POST_HOOKS_JSON=$(gsd_run loop render-hooks verify:post --raw)
 SECURITY_FILE=$(ls "${PHASE_DIR}"/*-SECURITY.md 2>/dev/null | head -1)
 ```
 
+**Generic step dispatch:** dispatch every `kind == "step"` hook from `VERIFY_POST_HOOKS_JSON` per @gsd-core/references/loop-hook-dispatch.md (skip silently when none). Each step is advisory and best-effort — honor `onError` and continue. The secure-phase handling below is an additional specialization of one such hook, not a replacement for the generic dispatch.
+
 Resolve active step hooks from `VERIFY_POST_HOOKS_JSON` where `kind == "step"` and `ref.skill == "secure-phase"`.
 
 If an active secure-phase step hook exists AND `SECURITY_FILE` is empty, dispatch the registry-provided skill stem:
@@ -633,7 +696,7 @@ All tests passed. Phase {phase} marked complete.
 <step name="scan_phase_artifacts">
 Run phase artifact scan to surface any open items before marking phase verified:
 
-`audit-open` is CJS-only until registered on `gsd-tools.cjs query`:
+`audit-open` is CJS-only until registered on `gsd_run query`:
 
 ```bash
 gsd_run query audit-open --json
@@ -647,9 +710,12 @@ Parse the JSON output. For the CURRENT PHASE ONLY, surface:
 If any are found, display:
 ```
 Phase {N} Artifact Check
-─────────────────────────────────────────────────
+
+---
+
 {list each item with status and file path}
-─────────────────────────────────────────────────
+
+---
 These items are open. Proceed anyway? [Y/n]
 ```
 
@@ -685,9 +751,7 @@ Diagnosis runs automatically - no user prompt. Parallel agents investigate simul
 
 Display:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► PLANNING FIXES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► PLANNING FIXES
 
 ◆ Spawning planner for gap closure... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
@@ -752,9 +816,7 @@ On return:
 
 Display:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► VERIFYING FIX PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► VERIFYING FIX PLANS
 
 ◆ Spawning plan checker... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)
 ```
@@ -795,7 +857,7 @@ Return one of:
 
 On return:
 - **VERIFICATION PASSED:** Proceed to `present_ready`
-- **ISSUES FOUND:** Proceed to `revision_loop`
+- **ISSUES FOUND:** Count BLOCKER + WARNING entries in the YAML issues block; an entry whose severity is missing or unrecognized counts as a BLOCKER (fail closed). If zero — every entry is explicitly INFO — display `ℹ advisory — {dimension}: {description}` per entry and proceed to `present_ready`; INFO is advisory and never enters the loop (#3724). Otherwise proceed to `revision_loop`
 </step>
 
 <step name="revision_loop">
@@ -828,6 +890,15 @@ ${AGENT_SKILLS_PLANNER}
 
 <instructions>
 Read existing PLAN.md files. Make targeted updates to address checker issues.
+
+`required_property` + evidence + severity BIND. `fix_hint` is ONE non-binding example route: a
+smaller or different mechanism reaching the same property addresses the issue in full — say which
+you used. Re-check locked decisions, capability guidance (CLAUDE.md, project skills) and the
+constraints these plans already encode BEFORE editing; if a hint would contradict one, or the
+property is unreachable without breaking one, return `## REVISION_CONFLICT` with the conflict and
+the alternatives rather than applying or working around it. Full contract:
+`gsd-core/references/planner-revision.md`, which you load in revision mode.
+
 Do NOT replan from scratch unless issues are fundamental.
 </instructions>
 """,
@@ -839,7 +910,23 @@ Do NOT replan from scratch unless issues are fundamental.
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-After planner returns → spawn checker again (verify_gap_plans logic)
+**If the planner returns `## REVISION_CONFLICT`:** do NOT increment `iteration_count` and do NOT
+re-spawn the checker — a conflict is not resolvable by re-running the same loop, so it must not
+consume retry budget. Present the conflict table and its alternatives to the user and ask which
+to take: adopt a named alternative / override the named constraint and apply the hint / amend the
+constraint itself. Every option resolves the conflict; accepting the plans with the blocker still
+open is NOT offered here — that choice belongs to the max-iteration escalation below. Re-spawn
+the planner with the chosen resolution and then **re-evaluate its return from the top of this
+handler** — never fall through to the checker spawn below, because a second conflict is still a
+conflict, not a revised plan, and only a NON-conflict return may reach the checker or increment
+`iteration_count`.
+
+**Bounded:** a conflict naming the SAME `required_property` twice in a row (no successful revision in between) is a stall, and so is
+the THIRD conflict return of this loop whatever property it names — alternating property names
+would otherwise never trip the repeat rule. Stop re-spawning and route it to the same
+max-iteration escalation below.
+
+**On any other return** → spawn checker again (verify_gap_plans logic)
 Increment iteration_count
 
 **If iteration_count >= 3:**
@@ -858,9 +945,7 @@ Wait for user response.
 **Present completion and next steps:**
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- GSD ► FIXES READY ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### GSD ► FIXES READY ✓
 
 **Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created
 
@@ -871,7 +956,7 @@ Wait for user response.
 
 Plans verified and ready for execution.
 
-───────────────────────────────────────────────────────────────
+---
 
 ## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
@@ -879,7 +964,7 @@ Plans verified and ready for execution.
 
 `/clear` then `/gsd:execute-phase {phase} --gaps-only`
 
-───────────────────────────────────────────────────────────────
+---
 ```
 </step>
 

package/hooks/dist/gsd-agent-isolation-guard.js

@@ -65,6 +65,23 @@ const path = require('path');
 const os = require('os');
 const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
 const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+
+// Required at module top, alongside the other ./lib requires — NOT behind
+// ensureRuntimeBuild() below. Terminating on a parse/timeout failure must
+// never depend on the gitignored build artifacts this hook self-heals for
+// its own registry lookups (#3911).
+//
+// This guard's outer catch (main(), below) has always exited 0 (fail open):
+// that outer catch only covers payload PARSING failing before applicability
+// could even be determined (malformed stdin JSON, etc.) — the guard's real
+// fail-closed logic (a GSD project whose dispatch-isolation configuration
+// cannot be verified) is handled separately, inside evaluateDispatch/
+// resolveIsolationState, and already returns a 'block' decision through the
+// normal exit-2 path rather than through this catch. So an unparseable
+// payload has nothing to enforce; allowing it preserves today's behavior
+// exactly.
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 // #3582: gsd-core/bin/lib/*.cjs (runtime-name-policy.cjs, capability-registry.cjs
 // below) are tsc build artifacts (ADR-457), gitignored and absent on a raw
 // plugin-marketplace / git-clone install that never ran `npm run build:lib`.
@@ -95,40 +112,40 @@ function parseHarnessFlag(flag) {
   return { param: m[1], value: m[2] };
 }
 
-// ─── #3566: per-install runtime marker ────────────────────────────────────────
+// ─── #3897 rung 2: per-install runtime marker, single canonical owner ────────
 // bin/install.js writes `<install>/gsd-core/.gsd-runtime` for EVERY runtime
 // install (#2297), co-located with VERSION. Unlike `~/.gsd/defaults.json` —
 // which is host-wide and names whichever runtime's install ran LAST, the exact
 // leakage #2840's config.cjs change exists to prevent — the marker describes
 // THIS install, which is the property runtime identity needs on a machine
-// with 2+ runtimes. Mirrors readInstallRuntimeMarker in src/model-resolver.cts
-// (same cache + test-seam shape); this hook cannot import that module without
-// dragging the whole model-resolution stack into a PreToolUse hot path, so the
-// 5-line read lives here against the same sibling-layout assumption the hook's
-// own require('../gsd-core/bin/lib/…') already makes. Epic #3473 B3 owns
-// consolidating every marker reader into one shared seam.
-let _installMarkerCache; // undefined = unread; null = known absent; string = value
-
+// with 2+ runtimes. Previously this hook held its own private reader/cache
+// (one of four #3897 found); it now delegates to the single canonical owner,
+// `src/runtime-slash.cts` (compiled to gsd-core/bin/lib/runtime-slash.cjs),
+// reached through `ensureRuntimeBuild()` like every other compiled-lib require
+// in this file (`scripts/lint-hooks-runtime-build-seam.cjs`).
 function readInstallRuntimeMarker() {
-  if (_installMarkerCache !== undefined) return _installMarkerCache;
   try {
-    const markerPath = path.join(__dirname, '..', 'gsd-core', '.gsd-runtime');
-    const raw = fs.readFileSync(markerPath, 'utf-8').trim();
-    _installMarkerCache = raw || null;
+    ensureRuntimeBuild();
+    const runtimeSlash = require('../gsd-core/bin/lib/runtime-slash.cjs');
+    return runtimeSlash.readInstallRuntimeMarker();
   } catch {
-    // No marker: dev/source tree, or an install predating #2297 — "no signal
-    // from this rung", never a resolution failure. Falls through to the
-    // defaults rung below.
-    _installMarkerCache = null;
+    // Unbuilt runtime library, or any other failure reaching the canonical
+    // owner — "no signal from this rung" (N4), never a resolution failure.
+    return null;
   }
-  return _installMarkerCache;
 }
 
-// Test seam for the marker rung (the dev/source tree has no marker file, so
-// the read always bottoms out at null there — same seam contract as
-// model-resolver.cts's _setInstallRuntimeMarkerForTests, #2297).
+// Test seam for the marker rung — forwards to the canonical owner's seam so
+// this hook and runtime-slash.cjs always share one cache (#3897 rung 2).
 function _setInstallRuntimeMarkerForTests(value) {
-  _installMarkerCache = value;
+  try {
+    ensureRuntimeBuild();
+    const runtimeSlash = require('../gsd-core/bin/lib/runtime-slash.cjs');
+    runtimeSlash._setInstallRuntimeMarkerForTests(value);
+  } catch {
+    // Test-only seam; an unbuilt library here means the test itself will fail
+    // downstream, which is a louder and more actionable signal than throwing here.
+  }
 }
 
 /**
@@ -282,18 +299,40 @@ function resolveRegistryIsolation(cwd, configPath) {
 
   if (isolation === 'harness-worktree') {
     let useWorktrees = true;
+    // #3972: the opt-out read shares the ONE owner every other
+    // isolation-deciding surface uses — planning-workspace's
+    // worktreesOptedOut ladder (scoped own-key wins; root inherited under
+    // the GSD_WORKSTREAM gate; strict === false). A flat single-file read
+    // here made a workstream-LOCAL opt-out invisible, so the sentinel-absent
+    // fallback denied a sequential dispatch the config explicitly allowed.
+    // Reached through ensureRuntimeBuild() like every other compiled-lib
+    // require in this file (scripts/lint-hooks-runtime-build-seam.cjs); if
+    // the library is unreachable the flat-root read below remains as the
+    // degraded fallback — today's behavior, never worse.
+    let ladderAnswered = false;
     try {
-      const raw = fs.readFileSync(configPath, 'utf-8');
-      const parsedCfg = JSON.parse(raw);
-      if (parsedCfg && typeof parsedCfg === 'object' && parsedCfg.workflow &&
-          typeof parsedCfg.workflow === 'object' && parsedCfg.workflow.use_worktrees === false) {
-        useWorktrees = false;
-      }
+      ensureRuntimeBuild();
+      const { worktreesOptedOut } = require('../gsd-core/bin/lib/planning-workspace.cjs');
+      useWorktrees = !worktreesOptedOut(cwd);
+      ladderAnswered = true;
     } catch {
-      // Unreadable config already propagated to the outer caller's catch
-      // before this point in practice (resolveRuntimeIdentity reads it
-      // first); tolerate defensively and keep the conservative (enforce)
-      // default rather than silently disabling the guard.
+      // Unbuilt runtime library or a ladder failure — fall through to the
+      // legacy flat-root read (conservative: keep enforcing).
+    }
+    if (!ladderAnswered) {
+      try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsedCfg = JSON.parse(raw);
+        if (parsedCfg && typeof parsedCfg === 'object' && parsedCfg.workflow &&
+            typeof parsedCfg.workflow === 'object' && parsedCfg.workflow.use_worktrees === false) {
+          useWorktrees = false;
+        }
+      } catch {
+        // Unreadable config already propagated to the outer caller's catch
+        // before this point in practice (resolveRuntimeIdentity reads it
+        // first); tolerate defensively and keep the conservative (enforce)
+        // default rather than silently disabling the guard.
+      }
     }
     if (!useWorktrees) isolation = 'none';
   }
@@ -476,7 +515,7 @@ function evaluateDispatch(data, { clock = Date } = {}) {
 /* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
 function main() {
   let input = '';
-  const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+  const stdinTimeout = setTimeout(() => allow(undefined), 3000);
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
   process.stdin.on('end', () => {
@@ -486,18 +525,18 @@ function main() {
       const decision = evaluateDispatch(data);
       if (decision.action === 'block') {
         const out = { decision: 'block', reason: decision.reason, reason_code: decision.reasonCode };
-        process.stdout.write(JSON.stringify(out));
         // Kimi feeds stderr (not stdout) back to the model on exit 2.
-        process.stderr.write(decision.reason);
-        process.exit(2);
+        deny(out, decision.reason);
       }
-      process.exit(0);
+      allow(undefined);
     } catch {
       // Silent fail — never block valid tool calls due to hook errors
       // (malformed payload, etc.). This is distinct from resolveIsolationState's
       // internal error handling, which DOES deny — this outer catch only
       // covers payload parsing before applicability could even be determined.
-      process.exit(0);
+      // ON_CRASH is declared ALLOW at module top: this preserves today's
+      // exit(0) fail-open behavior exactly (#3911).
+      crash(ON_CRASH, undefined);
     }
   });
 }

package/hooks/dist/gsd-check-update-worker.js

@@ -156,5 +156,22 @@ const result = {
 };
 
 if (cacheFile) {
-  try { fs.writeFileSync(cacheFile, JSON.stringify(result)); } catch (e) {}
-}
+  // #4091: the cache file is shared per-PACKAGE across every runtime's worker
+  // (#607/#1421), so concurrent statusline/banner readers parse it while this
+  // worker writes it. A direct writeFileSync truncates before writing — a
+  // reader landing mid-write sees a torn/empty record (its JSON.parse catch
+  // swallows it, so the symptom is an intermittently blank update segment).
+  // Publish atomically instead: stage under a unique same-directory temp
+  // (same filesystem, so rename(2) is atomic — readers see the old or the new
+  // record, never a partial one), then renameSync into place. Failure policy
+  // is unchanged (#3582 degrade): any error is swallowed and the temp, if
+  // left behind, is best-effort removed.
+  const tmp = cacheFile + '.tmp-' + process.pid;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(result));
+    fs.renameSync(tmp, cacheFile);
+  } catch (e) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch (e2) {}
+  }}

package/hooks/dist/gsd-config-reload.js

@@ -20,11 +20,17 @@
 
 const fs = require('fs');
 const path = require('path');
+const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+
+// This hook only injects an advisory config-reload summary; a crash mid-parse
+// must not block the session or the FileChanged event that triggered it — the
+// agent simply keeps using the config context it already had (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 let input = '';
 // Timeout guard: if stdin does not close within 8s exit silently rather than
 // hanging until Claude Code kills the process and reports "hook error".
-const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+const stdinTimeout = setTimeout(() => allow(undefined), 8000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
@@ -42,24 +48,23 @@ process.stdin.on('end', () => {
     // inject spurious additionalContext.
     const basename = path.basename(filePath);
     if (basename !== 'config.json') {
-      process.exit(0);
+      allow(undefined);
     }
     const expectedPath = path.resolve(cwd, '.planning', 'config.json');
     if (path.resolve(filePath) !== expectedPath) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // On unlink (deletion) emit a brief notice and exit
     if (event === 'unlink') {
-      process.stdout.write(JSON.stringify({
+      allow({
         hookSpecificOutput: {
           hookEventName: 'FileChanged',
           additionalContext:
             'GSD config (.planning/config.json) was deleted. ' +
             'Falling back to built-in defaults for this session.',
         },
-      }));
-      process.exit(0);
+      });
     }
 
     // Read the updated config file
@@ -68,17 +73,16 @@ process.stdin.on('end', () => {
       const raw = fs.readFileSync(filePath, 'utf8');
       config = JSON.parse(raw);
     } catch (e) {
-      if (e && e.code === 'ENOENT') process.exit(0);
+      if (e && e.code === 'ENOENT') allow(undefined);
       // Malformed JSON — inform the agent without crashing
-      process.stdout.write(JSON.stringify({
+      allow({
         hookSpecificOutput: {
           hookEventName: 'FileChanged',
           additionalContext:
             'GSD config (.planning/config.json) was modified but could not be parsed. ' +
             'Check the file for JSON syntax errors.',
         },
-      }));
-      process.exit(0);
+      });
     }
 
     // Build a concise summary of key config fields the agent cares about
@@ -127,7 +131,9 @@ process.stdin.on('end', () => {
       },
     }));
   } catch (e) {
-    // Silent fail — never block the session on a config reload error
-    process.exit(0);
+    // Silent fail — never block the session on a config reload error.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });