@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/workflows/sync-skills.md

@@ -11,7 +11,7 @@ Sync managed `gsd-*` skill directories from one canonical runtime's skills root
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--from <runtime>` | Yes | *(none)* | Source runtime — the canonical runtime to copy from |
-| `--to <runtime\|all>` | Yes | *(none)* | Destination runtime or `all` supported runtimes |
+| `--to <runtime\|all>` | Yes | *(none)* | Destination runtime or `all` supported runtimes. **Must equal `--from`** — cross-runtime sync is refused (#3025: skill content/layout is runtime-specific and produced by the installer's per-runtime converters; use the installer for a different runtime). |
 | `--dry-run` | No | *on by default* | Preview changes without writing anything |
 | `--apply` | No | *off* | Execute the diff (overrides dry-run) |
 
@@ -50,6 +50,61 @@ fi
 - If `--from` is missing or unrecognized: print error and exit
 - If `--to` is missing or unrecognized: print error and exit
 - If `--from` == `--to` (single destination): print `[no-op: source and destination are the same runtime]` and exit
+- If any `--to` destination differs from `--from` (cross-runtime): REFUSE with the installer pointer below and exit. sync only supports identity sync — see the guard.
+- If `--from` or any `--to` value is not a runtime-id shape (`^[a-z0-9][a-z0-9-]*$`): REFUSE and exit — runtime ids are lowercase alphanumeric (+ hyphen); this rejects shell metacharacters before any interpolation (see security guard).
+
+**#3025 — Runtime-id shape validation (security: run BEFORE any interpolation):**
+
+`--from`/`--to` are interpolated into later `echo`/heredoc/`[[ ]]` contexts. Reject any value that is not a runtime-id shape BEFORE it reaches them, so a hostile value (e.g. `--to '$(cmd)'`, captured wholesale by the parser) cannot execute via command substitution in an error message.
+
+```bash
+# #3025 (security): runtime ids are lowercase alphanumeric (+ hyphen). Reject
+# anything else BEFORE any echo/heredoc/[[ ]] so a hostile --from/--to value
+# cannot execute via command substitution in a later error message.
+is_runtime_id() { [[ "$1" =~ ^[a-z0-9][a-z0-9-]*$ ]]; }
+if ! is_runtime_id "$FROM_RUNTIME"; then
+  echo "error: invalid --from runtime id (not lowercase alphanumeric): '$FROM_RUNTIME'" >&2
+  exit 1
+fi
+for DEST in "${TO_RUNTIMES[@]}"; do
+  if ! is_runtime_id "$DEST"; then
+    echo "error: invalid --to runtime id (not lowercase alphanumeric): '$DEST'" >&2
+    exit 1
+  fi
+done
+```
+
+**#3025 — Cross-runtime refuse guard (run BEFORE Step 2 resolution / Step 5 copy):**
+
+Skill content and directory layout are runtime-specific. The installer applies per-runtime
+converters, adapter headers, brand swaps, and layout rules at install time, and two runtimes
+(`grok`, `gemini`) resolve to ANOTHER runtime's skills root. A verbatim copy from one runtime's
+skills root therefore produces content the installer would never have written for the destination,
+and can damage a runtime the user never named. Every cross-runtime pair is unsafe (content and/or
+layout and/or aliasing); only identity (`--from` == `--to`) is safe. Refuse cross-runtime and point
+the user at the installer — the only path that produces correctly converted skills.
+
+```bash
+# #3025: refuse cross-runtime skill sync before any resolution or copy.
+for DEST in "${TO_RUNTIMES[@]}"; do
+  if [[ "$DEST" != "$FROM_RUNTIME" ]]; then
+    cat >&2 <<EOF
+error: cross-runtime skill sync is not supported (--from $FROM_RUNTIME --to $DEST).
+       Skill content and directory layout are runtime-specific: the installer applies
+       per-runtime converters, adapter headers, brand swaps, and layout rules that a
+       verbatim copy cannot reproduce, and some runtimes share another runtime's skills
+       root — so a cross-runtime sync can damage a runtime you did not name.
+       To install correctly-converted skills for the '$DEST' runtime, run the GSD
+       installer for that runtime (not sync):
+         npx -y @opengsd/gsd-core@latest --global --<runtime>
+       (grok and gemini have no dedicated installer flag — they alias the codex and
+       claude skills roots respectively, which is itself why sync refuses them.)
+       sync only supports identity sync, where --from and --to are the same runtime.
+EOF
+    exit 1
+  fi
+done
+```
 
 ---
 
@@ -175,12 +230,12 @@ DEST_ROOT=$(gsd_run query skills-root "$DEST_RUNTIME" --raw)
 
 mkdir -p "$DEST_ROOT"
 
-# #3025: verbatim cp -r copies the SOURCE runtime's converted skill form, which
-# corrupts skills for destinations that need a different conversion (e.g. Claude
-# SKILL.md → Codex TOML agent). Until the installer exposes a per-skill conversion
-# CLI, sync is limited to runtime pairs that share the same skill format.
-# Run `gsd install --<dest-runtime> --local` to get correctly converted skills
-# for a destination that uses a different format.
+# #3025: cross-runtime sync is refused in Step 1's guard (skill content/layout is
+# runtime-specific; a verbatim copy corrupts destinations and can alias another
+# runtime's root). This loop is therefore reached only for IDENTITY sync, where
+# every skill is SKIP (source == destination) and the create/update lists are
+# empty. If per-runtime conversion is ever wired in, this is where it would go;
+# until then the cp -r must never run for a destination != source.
 
 for SKILL in $CREATE_LIST $UPDATE_LIST; do
   rm -rf "$DEST_ROOT/$SKILL"
@@ -215,6 +270,6 @@ Sync complete: <N> skills synced to <M> runtime(s).
 
 ## Limitations
 
-- Sync copies files verbatim and does not apply runtime-specific content transformations. Use the GSD installer directly for runtimes that require format conversion.
+- Sync copies files verbatim and does not apply runtime-specific content transformations. **Cross-runtime sync is refused** (#3025): skill content and layout are runtime-specific, and some runtimes alias another runtime's skills root, so a verbatim cross-runtime copy corrupts the destination (and can damage a runtime you did not name). Only identity sync (`--from` == `--to`) is supported. To install skills for a different runtime, run the GSD installer for that runtime (`npx -y @opengsd/gsd-core@latest --global --<runtime>`).
 - Cross-project skills (`.agents/skills/`) are out of scope — this command only touches global runtime skills roots.
 - Bidirectional sync is not supported. Choose one canonical source with `--from`.

package/gsd-core/workflows/transition.md

@@ -36,6 +36,31 @@ Mark current phase complete and advance to next. This is the natural point where
 
 <process>
 
+<step name="post_completion_mode" priority="first">
+
+**Invocation mode — read this FIRST.** This workflow runs two ways:
+
+1. **Standalone transition** (normal path): the phase is being marked complete AND
+   transitioned by this workflow. Run EVERY step below in order — `verify_completion`,
+   `update_roadmap_and_state` (which calls `gsd_run query phase.complete`), then the
+   post-processing.
+
+2. **Post-completion delegation** (invoked by `execute-phase` after its auto-chain
+   completion — #1526): `phase.complete` was already called by execute-phase's
+   `update_roadmap` step and verification already passed in execute-phase's
+   `verify_phase_goal`. SKIP `verify_completion` and `update_roadmap_and_state`
+   (re-running `phase.complete` would double-write STATE.md/ROADMAP.md). Run
+   `cleanup_handoff` (stale `.continue-here` handoffs are still cleared post-completion),
+   then BEGIN at `evolve_project` and run every step from there through
+   `offer_next_phase` (this is the post-processing parity set: graduation scan,
+   session-continuity, project-reference, accumulated-context, current-position/progress).
+   `archive_prompts` is a documented no-op in either mode.
+
+Detect post-completion mode when the caller states that phase completion and
+verification have already run. When in doubt, run standalone (mode 1) — it is
+idempotent enough to be safe, just slower.
+</step>
+
 <step name="load_project_state" priority="first">
 
 Before transition, read project state:
@@ -77,12 +102,22 @@ cat .planning/config.json 2>/dev/null || true
 **Check for verification debt in this phase:**
 
 ```bash
-# Run a preliminary frontmatter check via awk — the runtime launcher is not yet
-# defined at this step, so avoid any runtime tool calls here.
+_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
+# #3492: resolve THIS phase's own report through the single shared seam
+# (src/verification.cts resolveVerificationFile) instead of a blind
+# `*-VERIFICATION.md` glob — a stray ad-hoc worksheet (e.g.
+# `03-CORRECTION-VERIFICATION.md`) alphabetically outranks the real report
+# and previously fed this awk parse the wrong file.
+VERIFICATION_FILE=$(gsd_run query verification.resolve-file .planning/phases/XX-current --raw 2>/dev/null)
 # awk extracts only the status: field between the two --- fences to avoid
 # false positives from historical body text (e.g. previous_status: gaps_found).
-VERIFY_STATUS=$(awk 'NR==1&&/^---$/{in_fm=1;next}in_fm&&/^---$/{exit}in_fm&&/^status: /{print $2}' \
-  .planning/phases/XX-current/*-VERIFICATION.md 2>/dev/null | head -1)
+# FNR (not NR) re-arms the frontmatter scan per input file: NR only ever arms
+# on the very FIRST line of the very first file, so a multi-file input would
+# silently read empty status for every file after the first. The resolver
+# above always hands back a single path, but the parse stays correct even if
+# that ever changes.
+VERIFY_STATUS=$(awk 'FNR==1&&/^---$/{in_fm=1;next}in_fm&&/^---$/{exit}in_fm&&/^status: /{print $2}' \
+  "$VERIFICATION_FILE" 2>/dev/null | head -1)
 ```
 
 **If VERIFY_STATUS is not `passed`:**
@@ -95,10 +130,10 @@ Verification incomplete: ${VERIFY_STATUS:-missing}
 Resolve before transition. Review: `/gsd:audit-uat`
 ```
 
-This preliminary check blocks obviously unresolved verification before the
-launcher is available. `gsd-tools.cjs query phase.complete` remains the
-authoritative stale-aware gate and fail-closes unless canonical verification
-status is `passed`.
+This preliminary check blocks obviously unresolved verification early, ahead
+of the authoritative gate below. `gsd-tools.cjs query phase.complete` (in
+`update_roadmap_and_state`) remains the authoritative stale-aware gate and
+fail-closes unless canonical verification status is `passed`.
 
 **If all plans complete:**
 
@@ -165,7 +200,6 @@ If found, delete them — phase is complete, handoffs are stale.
 **Delegate ROADMAP.md and STATE.md updates to `gsd-tools.cjs query phase.complete`:**
 
 ```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
 TRANSITION=$(gsd_run query phase.complete "${current_phase}")
 ```
 
@@ -194,7 +228,8 @@ Evolve PROJECT.md to reflect learnings from completed phase.
 **Read phase summaries:**
 
 ```bash
-cat .planning/phases/XX-current/*-SUMMARY.md
+_SUMMARIES=( .planning/phases/XX-current/*-SUMMARY.md )
+if [ -e "${_SUMMARIES[0]}" ]; then cat "${_SUMMARIES[@]}"; fi
 ```
 
 **Assess requirement changes:**
@@ -417,7 +452,7 @@ ROADMAP=$(gsd_run query roadmap.analyze)
 
 This returns all phases with goals, disk status, and completion info.
 
-**Section-manifest gate (#2994):** `gsd_run` is already established above (`update_roadmap_and_state` step) — fetch the dedicated `init.transition` bundle for the workstream-collision-check gate below:
+**Section-manifest gate (#2994):** `gsd_run` is already established above (`verify_completion` step) — fetch the dedicated `init.transition` bundle for the workstream-collision-check gate below:
 
 ```bash
 INIT_TRANSITION=$(gsd_run query init.transition)

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

@@ -132,14 +132,14 @@ Create UI design contract for Phase {phase_number}: {phase_name}
 Answer: "What visual and interaction contracts does this phase need?"
 </objective>
 
-<files_to_read>
+<required_reading>
 - {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
 - {context_path} (USER DECISIONS from /gsd:discuss-phase)
 - {research_path} (Technical Research — stack decisions)
 - {SKETCH_FINDINGS_PATH} (Sketch Findings — validated design decisions, CSS patterns, visual direction from /gsd:sketch, if exists)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_UI}
 
@@ -155,7 +155,7 @@ padded_phase: {padded_phase}
 </config>
 ```
 
-Omit null file paths from `<files_to_read>`.
+Omit null file paths from `<required_reading>`.
 
 <!-- #2508 runtime-aware-dispatch -->
 
@@ -205,11 +205,11 @@ Validate UI design contract for Phase {phase_number}: {phase_name}
 Check all 6 dimensions. Return APPROVED or BLOCKED.
 </objective>
 
-<files_to_read>
+<required_reading>
 - {phase_dir}/{padded_phase}-UI-SPEC.md (UI Design Contract — PRIMARY INPUT)
 - {context_path} (USER DECISIONS — check compliance)
 - {research_path} (Technical Research — check stack alignment)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_UI_CHECKER}
 

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

@@ -84,12 +84,12 @@ Conduct 6-pillar visual audit of Phase {phase_number}: {phase_name}
 {If no UI-SPEC: "Audit against abstract 6-pillar standards."}
 </objective>
 
-<files_to_read>
+<required_reading>
 - {summary_paths} (Execution summaries)
 - {plan_paths} (Execution plans — what was intended)
 - {ui_spec_path} (UI Design Contract — audit baseline, if exists)
 - {context_path} (User decisions, if exists)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_UI_REVIEWER}
 

package/gsd-core/workflows/update.md

@@ -78,7 +78,7 @@ Parse output:
 - Line 4 = resolved GSD config dir (e.g. `/Users/me/.claude`, `/Users/me/.gemini`); empty if scope is `UNKNOWN`. Capture this as `GSD_DIR` and pass it to subsequent steps so they don't re-derive the runtime path.
 - If scope is `UNKNOWN`, proceed to install using the `--claude --global` fallback.
 
-`update-context` reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so `CWD=$HOME` does not misdetect as LOCAL), env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in `tests/issue-498-update-context.test.cjs`.
+`update-context` reproduces the previous detection cascade — preferred-config-dir fast path, local-over-global with same-path dedup (so `CWD=$HOME` does not misdetect as LOCAL), env-var overrides (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `KILO_CONFIG`, `XDG_CONFIG_HOME`, `CODEX_HOME`, …), and semver validation — but as a tested projection rather than ~280 lines of inline bash. Branch coverage lives in `tests/update-context.test.cjs`.
 
 If multiple runtime installs are detected and the invoking runtime cannot be determined from execution_context, ask the user which runtime to update before running install.
 

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

@@ -110,7 +110,7 @@ Print: `◆ Spawning nyquist auditor... (runs in a subagent — no output until
 ```
 Agent(
   prompt="Read ~/.claude/agents/gsd-nyquist-auditor.md for instructions.\n\n" +
-    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
+    "<required_reading>{PLAN, SUMMARY, impl files, VALIDATION.md}</required_reading>" +
     "<gaps>{gap list}</gaps>" +
     "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
     "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>" +

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

@@ -70,6 +70,8 @@ VERIFY_PRE_HOOKS_JSON=$(gsd_run loop render-hooks verify:pre --raw)
 PHASE_DIR=$(printf '%s' "$INIT" | jq -r '.phase_dir // empty')
 ```
 
+⚠ **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"`.
 For each active gate hook, run its declared check (a `check.query` gate runs
 `gsd_run check ${hook.check.query} "${PHASE_DIR}" --raw`; a `predicate` gate
@@ -570,7 +572,7 @@ If execution verification is waiting only on human UAT and this session recorded
 
 ```bash
 PHASE_DIR=$(printf '%s' "$INIT" | jq -r '.phase_dir // empty')
-VERIFICATION_FILE=$(ls "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null | head -1)
+VERIFICATION_FILE=$(gsd_run query verification.resolve-file "$PHASE_DIR" --raw 2>/dev/null)
 VERIFICATION_STATUS=$(gsd_run query verification.status "$PHASE_DIR" 2>/dev/null)
 VERIFICATION_STATUS_VALUE=$(printf '%s' "$VERIFICATION_STATUS" | jq -r '.status // empty' 2>/dev/null || echo "")
 PHASE_VERIFICATION_STATUS="$VERIFICATION_STATUS_VALUE"
@@ -704,11 +706,11 @@ Agent(
 **Phase:** {phase_number}
 **Mode:** gap_closure
 
-<files_to_read>
+<required_reading>
 - {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses)
 - {state_path} (Project State)
 - {roadmap_path} (Roadmap)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_PLANNER}
 
@@ -769,9 +771,9 @@ Agent(
 **Phase:** {phase_number}
 **Phase Goal:** Close diagnosed gaps from UAT
 
-<files_to_read>
+<required_reading>
 - {phase_dir}/*-PLAN.md (Plans to verify)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_CHECKER}
 
@@ -813,9 +815,9 @@ Agent(
 **Phase:** {phase_number}
 **Mode:** revision
 
-<files_to_read>
+<required_reading>
 - {phase_dir}/*-PLAN.md (Existing plans)
-</files_to_read>
+</required_reading>
 
 ${AGENT_SKILLS_PLANNER}
 

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

@@ -43,8 +43,9 @@
 // authoritative — `none`/`orchestrator-worktree` ALLOW immediately
 // (sequential/orchestrator-managed dispatch is legitimate, not a bug); an
 // absent/stale sentinel falls back to a conservative registry+config check
-// (GSD_RUNTIME env > .planning/config.json `runtime` — no confident signal
-// degrades to inert rather than guessing 'claude', see resolveRegistryIsolation)
+// (GSD_RUNTIME env > .planning/config.json `runtime` > the per-install
+// `.gsd-runtime` marker, #3566 — no confident signal degrades to inert rather
+// than guessing 'claude', see resolveRegistryIsolation)
 // gated additionally by `workflow.use_worktrees` — read directly, in-process,
 // no subprocess spawn.
 //
@@ -63,6 +64,15 @@ const fs = require('fs');
 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');
+// #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`.
+// Self-heal before the first such require (resolveRegistryIsolation, below) —
+// see ensureRuntimeBuild's own header for the full rationale. This module
+// itself (gsd-core/bin/ensure-runtime-build.cjs) depends on nothing under
+// ./lib, so requiring it here is always safe.
+const { ensureRuntimeBuild, RuntimeBuildError } = require('../gsd-core/bin/ensure-runtime-build.cjs');
 
 // No other executor-shaped subagent_type exists in agents/ today
 // (verified: only agents/gsd-executor.md). A Set, not a bare string compare,
@@ -85,6 +95,42 @@ function parseHarnessFlag(flag) {
   return { param: m[1], value: m[2] };
 }
 
+// ─── #3566: per-install runtime marker ────────────────────────────────────────
+// 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
+
+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;
+  } 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;
+  }
+  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).
+function _setInstallRuntimeMarkerForTests(value) {
+  _installMarkerCache = value;
+}
+
 /**
  * Resolve this project's declared `runtime` identity WITHOUT defaulting to
  * 'claude' when no explicit signal exists (#3045 MAJOR 2).
@@ -100,9 +146,10 @@ function parseHarnessFlag(flag) {
  *
  * Returns `{ runtimeId, confident }`. `confident` is true only when an
  * explicit signal exists (GSD_RUNTIME env override, a `runtime` key literally
- * present in config.json, or a `runtime` persisted to `~/.gsd/defaults.json`
- * by the installer — see below); false means "cannot determine" and callers
- * must NOT silently substitute 'claude' — see resolveRegistryIsolation.
+ * present in config.json, the per-install `.gsd-runtime` marker, or a
+ * `runtime` persisted to `~/.gsd/defaults.json` by the installer — see
+ * below); false means "cannot determine" and callers must NOT silently
+ * substitute 'claude' — see resolveRegistryIsolation.
  *
  * #3045 BLOCKER 2 fix: precedence is GSD_RUNTIME env > config.json `runtime`
  * key > `~/.gsd/defaults.json` `runtime`. The first two are unchanged; the
@@ -117,6 +164,17 @@ function parseHarnessFlag(flag) {
  * (`nativeModelAliases` short-circuits it) and therefore correctly still rely
  * on config.json/env. Reading the installer's own persisted signal makes
  * "confident" the common case instead.
+ *
+ * #3566: the per-install `.gsd-runtime` marker now sits BETWEEN config.json
+ * and defaults.json. defaults.json is host-wide and names whichever runtime
+ * installed LAST — on a 2-runtime machine that confidently resolves the WRONG
+ * runtime (a Codex install's `runtime:"codex"` leaking into Claude projects),
+ * and when the wrong runtime declares no harnessIsolationFlag the guard goes
+ * silently inert. The marker describes THIS install (written for every
+ * runtime since #2297), which is the source #2840's config.cjs change names
+ * as correct. defaults.json stays as the final rung so single-runtime default
+ * installs and pre-#2297 installs (no marker on disk) keep the #3045
+ * BLOCKER 2 behavior.
  */
 function resolveRuntimeIdentity(cwd, configPath, resolveRuntimeNameFromCandidates) {
   const envRuntime = resolveRuntimeNameFromCandidates(process.env.GSD_RUNTIME);
@@ -132,6 +190,13 @@ function resolveRuntimeIdentity(cwd, configPath, resolveRuntimeNameFromCandidate
     if (configRuntime) return { runtimeId: configRuntime, confident: true };
   }
 
+  // #3566: the per-install marker, above the host-wide defaults — see the
+  // block comment on readInstallRuntimeMarker. An empty/whitespace-only file
+  // or an unknown value degrades exactly like the other rungs (no signal /
+  // future-runtime tolerance via resolveRuntimeNameFromCandidates).
+  const markerRuntime = resolveRuntimeNameFromCandidates(readInstallRuntimeMarker());
+  if (markerRuntime) return { runtimeId: markerRuntime, confident: true };
+
   // #3045 BLOCKER 2: fall back to the installer-persisted default. Read
   // defensively — an absent/corrupt/non-object defaults.json is "no signal",
   // never a resolution failure (this function only ever throws for the
@@ -183,6 +248,15 @@ function resolveHarnessFlag(runtimeId, runtimes) {
  * run, e.g. a manual Agent() call before any sentinel has been written).
  */
 function resolveRegistryIsolation(cwd, configPath) {
+  // #3582: self-heal the compiled runtime library BEFORE either require
+  // below — this is the only reaching path to both (resolveRegistryIsolation
+  // is the sole caller of each), so one call here covers both. Throws
+  // RuntimeBuildError on an unbuildable tree; the caller (resolveIsolationState)
+  // already wraps this whole function in try/catch and folds any error into
+  // its fail-closed `error` result — evaluateDispatch below distinguishes a
+  // RuntimeBuildError there so it surfaces this seam's actionable message
+  // instead of being misreported as an unreadable config.json (#3050 lesson).
+  ensureRuntimeBuild();
   const { resolveRuntimeNameFromCandidates } = require('../gsd-core/bin/lib/runtime-name-policy.cjs');
   const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');
 
@@ -360,13 +434,27 @@ function evaluateDispatch(data, { clock = Date } = {}) {
   if (!state.gsdProject) return { action: 'allow' };
 
   if (state.error) {
-    const reason =
-      `Agent isolation guard: could not read or resolve this project's dispatch-isolation ` +
-      `configuration ('.planning/config.json' under '${cwd}'). Refusing to dispatch ` +
-      `subagent_type="${subagentType}" without being able to verify whether isolation is ` +
-      `required — a guard that cannot verify must not answer "safe" (#3050). Retry once the ` +
-      `project configuration is readable.`;
-    return { action: 'block', reason };
+    // #3582: a missing/unbuildable compiled runtime library (RuntimeBuildError,
+    // thrown by ensureRuntimeBuild in resolveRegistryIsolation) is a DIFFERENT,
+    // actionable failure from an unreadable/unparsable config.json — surface
+    // its own message instead of misreporting it as the generic
+    // "could not read or resolve ... configuration" text (the exact #3050
+    // misreport this issue exists to fix). Both cases still fail closed
+    // (block); only the message differs.
+    const isBuildFailure = state.error instanceof RuntimeBuildError;
+    const reason = isBuildFailure
+      ? `Agent isolation guard: cannot resolve this project's dispatch-isolation ` +
+        `configuration because the GSD runtime library failed to self-build. ` +
+        `${state.error.message} Refusing to dispatch subagent_type="${subagentType}" until ` +
+        `the runtime library is built — a guard that cannot verify must not answer "safe" ` +
+        `(#3050).`
+      : `Agent isolation guard: could not read or resolve this project's dispatch-isolation ` +
+        `configuration ('.planning/config.json' under '${cwd}'). Refusing to dispatch ` +
+        `subagent_type="${subagentType}" without being able to verify whether isolation is ` +
+        `required — a guard that cannot verify must not answer "safe" (#3050). Retry once the ` +
+        `project configuration is readable.`;
+    const reasonCode = isBuildFailure ? REASON_CODE.RUNTIME_BUILD_FAILED : REASON_CODE.CONFIG_UNREADABLE;
+    return { action: 'block', reason, reasonCode };
   }
 
   if (state.isolation !== 'harness-worktree') return { action: 'allow' };
@@ -382,7 +470,7 @@ function evaluateDispatch(data, { clock = Date } = {}) {
     `${parsed.param}="${parsed.value}". Add ${parsed.param}="${parsed.value}" to the Agent() ` +
     `call so the executor runs in an isolated worktree instead of the primary checkout ` +
     `(gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md).`;
-  return { action: 'block', reason };
+  return { action: 'block', reason, reasonCode: REASON_CODE.HARNESS_FLAG_MISSING };
 }
 
 /* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
@@ -397,7 +485,7 @@ function main() {
       const data = JSON.parse(input);
       const decision = evaluateDispatch(data);
       if (decision.action === 'block') {
-        const out = { decision: 'block', reason: decision.reason };
+        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);
@@ -425,4 +513,5 @@ module.exports = {
   resolveHarnessFlag,
   resolveRegistryIsolation,
   parseHarnessFlag,
+  _setInstallRuntimeMarkerForTests,
 };

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

@@ -11,18 +11,61 @@
 
 const fs = require('fs');
 const path = require('path');
-const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
-// Latest-version lookup is delegated to the single deterministic adapter
-// (#498). checkLatestVersion() owns the npm-view call, the timeout/semver
-// policy, and the package name — sourced from the baked Package Identity seam.
-// The previous `require('../package.json').name` (#378) never yielded a name in
-// the installed tree — at the time it resolved to the synthetic
-// {"type":"commonjs"} marker GSD wrote at the config root, which has no `.name`,
-// so the background check never reported updates. Since #2544 GSD writes no
-// marker there at all, so that require would now fail to resolve outright.
-// Either way the name must come from the baked seam, never a walk-up.
-const { checkLatestVersion } = require('../gsd-core/bin/check-latest-version.cjs');
-const { PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs');
+
+// #3582: gsd-core/bin/lib/semver-compare.cjs and package-identity.cjs (and,
+// transitively, check-latest-version.cjs's own gsd-core/bin/lib/cli-exit.cjs
+// + shell-command-projection.cjs) are tsc build artifacts (ADR-457),
+// gitignored and absent on a raw plugin-marketplace / git-clone install that
+// never ran `npm run build:lib`. This worker is a DETACHED SessionStart
+// background process (spawned with stdio: 'ignore') — a build failure here
+// must DEGRADE to the no-signal fallbacks below (mirroring the
+// managed-hooks-registry.cjs degrade just below) so the worker still runs to
+// completion and writes a result cache record, rather than dying silently
+// with no visible signal and no cache-file write at all.
+//
+// This try/require/ensureRuntimeBuild/require/catch shape repeats (with
+// different destructured names) in hooks/gsd-check-update.js and
+// hooks/gsd-update-banner.js. It is deliberately NOT extracted into a shared
+// hooks/lib/ helper: scripts/lint-hooks-runtime-build-seam.cjs enforces this
+// exact seam textually, PER FILE — it greps each hooks/ file for its OWN
+// literal `require('.../ensure-runtime-build.cjs')` + `ensureRuntimeBuild(`
+// call co-occurring with its OWN literal `require('.../gsd-core/bin/lib/*.cjs')`.
+// A generic helper taking the compiled module's path as a variable would move
+// the literal compiled-lib require OUT of this file and into the helper,
+// called with a non-literal argument — the scan's regex (see that script's
+// "Known limitations") cannot see a require() called with a variable, so this
+// file would then read as "requires nothing" and the lint would stop
+// protecting it. A ceremony-only helper (just the ensureRuntimeBuild call,
+// each caller keeping its own literal compiled-lib require) fails the SAME
+// way from the other side: it would remove this file's own literal
+// `require('.../ensure-runtime-build.cjs')` + `ensureRuntimeBuild(` call,
+// which the lint also requires to be textually present in THIS file. Either
+// shape needs the lint script itself widened to special-case the helper,
+// which is a bigger, riskier change than the ~6 duplicated lines it would
+// save; kept inline instead.
+let isSemverNewer = () => false;
+let checkLatestVersion = () => ({ ok: false });
+let PACKAGE_NAME = null;
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs'));
+  // Latest-version lookup is delegated to the single deterministic adapter
+  // (#498). checkLatestVersion() owns the npm-view call, the timeout/semver
+  // policy, and the package name — sourced from the baked Package Identity seam.
+  // The previous `require('../package.json').name` (#378) never yielded a name in
+  // the installed tree — at the time it resolved to the synthetic
+  // {"type":"commonjs"} marker GSD wrote at the config root, which has no `.name`,
+  // so the background check never reported updates. Since #2544 GSD writes no
+  // marker there at all, so that require would now fail to resolve outright.
+  // Either way the name must come from the baked seam, never a walk-up.
+  ({ checkLatestVersion } = require('../gsd-core/bin/check-latest-version.cjs'));
+  ({ PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs'));
+} catch (e) {
+  // Runtime library missing/broken and could not self-build — degrade to the
+  // no-signal fallbacks declared above; the worker still writes a result
+  // cache record (package_name: null, update_available: false).
+}
 // Authoritative list of managed hooks — shared with tests to retire source-grep
 // assertions (pending-migration-to-typed-ir [#455]).
 // NOTE: managed-hooks-registry.cjs must be in HOOKS_TO_COPY (scripts/build-hooks.js)
@@ -63,7 +106,7 @@ try {
 // (e.g., gsd-intel-*.js) must be ignored to avoid permanent stale warnings (#1750)
 // MANAGED_HOOKS is imported from ./managed-hooks-registry.cjs above.
 
-let staleHooks = [];
+const staleHooks = [];
 if (configDir) {
   // #3023: the bundle's directory name is runtime-descriptor-driven (pi stages
   // it as `gsd-hooks/`), so deriving it as `<configDir>/hooks` silently scanned