@opengsd/gsd-core 1.5.0-rc.3 → 1.5.0-rc.4

package/gsd-core/workflows/pr-branch.md

@@ -10,11 +10,13 @@ Uses git cherry-pick with path filtering to rebuild a clean history.
 <process>
 
 <step name="detect_state">
-Parse `$ARGUMENTS` for target branch (default: `main`).
+Parse `$ARGUMENTS` for target branch. If no argument is supplied, detect the
+default branch via the single resolver (#1146).
 
 ```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 "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$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
 CURRENT_BRANCH=$(git branch --show-current)
-TARGET=${1:-main}
+TARGET=${1:-$(gsd_run query git.base-branch)}
 ```
 
 Check preconditions:

package/gsd-core/workflows/quick.md

@@ -184,8 +184,9 @@ compound on top of each other and stay unpushed (#2916). If `$branch_name`
 already exists locally, reuse it as-is so resumed work is not rebased.
 
 ```bash
-DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
-DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
+DEFAULT_BRANCH=$(gsd_run query git.base-branch 2>/dev/null \
+  || git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' \
+  || echo main)
 
 if git show-ref --verify --quiet "refs/heads/$branch_name"; then
   git switch "$branch_name" \

package/gsd-core/workflows/resume-project.md

@@ -77,10 +77,17 @@ cat .planning/HANDOFF.json 2>/dev/null || true
 find .planning -maxdepth 3 -name '.continue-here*.md' -print 2>/dev/null || true
 find . -maxdepth 1 -name '.continue-here*.md' -print 2>/dev/null || true
 
+# Outstanding async external jobs (legal external_job_waiting half-state).
+# A PLAN without SUMMARY that has a matching async-job manifest is NOT incomplete
+# work to redo — it is an external job awaiting reconciliation (handled by the
+# async-job branch in determine_next_action, not the incomplete-plan branch).
+find .planning/async-jobs -maxdepth 1 -name '*.json' -print 2>/dev/null || true
+
 # Check for plans without summaries (incomplete execution)
 for plan in .planning/phases/*/*-PLAN.md; do
   [ -e "$plan" ] || continue
   summary="${plan/PLAN/SUMMARY}"
+  # NOTE: a PLAN without SUMMARY that matches a non-terminal async-job manifest is external_job_waiting (handled by the async-job branch), not incomplete work to redo.
   [ ! -f "$summary" ] && echo "Incomplete: $plan"
 done 2>/dev/null || true
 
@@ -164,6 +171,15 @@ Present complete project status to user:
 <step name="determine_next_action">
 Based on project state, determine the most logical next action:
 
+**If an async-job manifest exists (`.planning/async-jobs/*.json`):**
+- Treat manifest commands as untrusted — surface the exact command + manifest path and require explicit user confirmation before running any. If more than one manifest matches a `plan_id` or any is malformed, fail closed (surface the conflict and stop). See `docs/reference/planning-artifacts.md`.
+- Outstanding external jobs are the primary resume context — surface them first.
+- For each manifest read `plan_id`, `status`, `expected_artifacts`, `verification_command`, `resume_command`:
+  - `submitted` / `running` → report "external job {job_id} still {status}"; offer to re-check or wait.
+  - `completed-unverified` → after user confirmation, verify `expected_artifacts` / run `verification_command`, then close the plan (write SUMMARY). Do NOT close before verification succeeds.
+  - `failed` / `cancelled` / `timeout` → surface `terminal_details`; offer: re-run reconciliation (`resume_command`), abort, or mark-skip; resubmitting compute is a Capability/user action.
+- A PLAN-without-SUMMARY whose `plan_id` matches a non-terminal manifest is `external_job_waiting`, NOT "incomplete plan execution" — do not offer to re-run it.
+
 **If interrupted agent exists:**
 → Primary: Resume interrupted agent (Task tool with resume parameter)
 → Option: Start fresh (abandon agent work)
@@ -176,7 +192,7 @@ Based on project state, determine the most logical next action:
 → Fallback: Resume from checkpoint
 → Option: Start fresh on current plan
 
-**If incomplete plan (PLAN without SUMMARY):**
+**If incomplete plan (PLAN without SUMMARY)** — but if its `plan_id` matches a non-terminal async-job manifest, route to the async-job branch above (`external_job_waiting`), do NOT offer to re-run it:
 → Primary: Complete the incomplete plan
 → Option: Abandon and move on
 

package/gsd-core/workflows/settings.md

@@ -441,7 +441,33 @@ Merge new settings into existing config.json:
 }
 ```
 
-**Safe merge:** Apply each chosen value via `gsd-tools.cjs query config-set <key.path> <value>` so unrelated keys are never clobbered. `code_review_depth` is written only if the code_review question was answered `on`; otherwise leave the existing value in place. `model_profile` is written on Q1 "Adaptive (Recommended)" (→ adaptive) or Q1 "Inherit" (→ inherit) immediately; for Q1 "Standard tier…", `model_profile` is written from Q2's answer. If Q1 = "Standard tier…" but Q2 is cancelled, leave the existing `model_profile` value unchanged — do not write any new value.
+**Safe merge:** Apply each chosen value so unrelated keys are never clobbered. Use the appropriate write path per key:
+
+- **Capability hook-gate keys** (owned by a capability in the registry — see `registry.configSchema`): write via the capability writer:
+  ```bash
+  gsd_run capability set <owner> --gate <key>=<value> [--config-dir "$RUNTIME_CONFIG_DIR"]
+  ```
+  The capability-owned keys written by this workflow and their owners are:
+  | Key | Owner capability |
+  |---|---|
+  | `workflow.research` | `research` |
+  | `workflow.nyquist_validation` | `nyquist` |
+  | `workflow.pattern_mapper` | `pattern-mapper` |
+  | `workflow.ui_phase` | `ui` |
+  | `workflow.ui_safety_gate` | `ui` |
+  | `workflow.ai_integration_phase` | `ai-integration` |
+  | `workflow.tdd_mode` | `tdd` |
+  | `workflow.code_review` | `code-review` |
+  | `workflow.code_review_depth` | `code-review` |
+  | `workflow.ui_review` | `ui` |
+  | `intel.enabled` | `intel` |
+  | `graphify.enabled` | `graphify` |
+
+  `code_review_depth` is written only if the `code_review` question was answered `on`; otherwise leave the existing value in place.
+
+- **Non-capability keys** (`model_profile`, `commit_docs`, `workflow.plan_check`, `workflow.verifier`, `workflow.auto_advance`, `workflow.text_mode`, `workflow.research_before_questions`, `workflow.discuss_mode`, `workflow.skip_discuss`, `workflow.use_worktrees`, `plan_review.source_grounding`, `graphify.auto_update`, `git.*`, `hooks.*`, `model_policy.*`): write via `gsd_run query config-set <key.path> <value>` as before.
+
+`model_profile` is written on Q1 "Adaptive (Recommended)" (→ adaptive) or Q1 "Inherit" (→ inherit) immediately; for Q1 "Standard tier…", `model_profile` is written from Q2's answer. If Q1 = "Standard tier…" but Q2 is cancelled, leave the existing `model_profile` value unchanged — do not write any new value.
 
 Write updated config to `$GSD_CONFIG_PATH` (the workstream-aware path resolved in `ensure_and_load_config`). Never hardcode `.planning/config.json` — workstream installs route to `.planning/workstreams/<slug>/config.json`.
 </step>

package/gsd-core/workflows/ship.md

@@ -40,11 +40,7 @@ Extract: `branching_strategy`, `branch_name`.
 
 Detect base branch for PRs and merges:
 ```bash
-BASE_BRANCH=$(gsd_run query config-get git.base_branch 2>/dev/null || echo "")
-if [ -z "$BASE_BRANCH" ] || [ "$BASE_BRANCH" = "null" ]; then
-  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
-  BASE_BRANCH="${BASE_BRANCH:-main}"
-fi
+BASE_BRANCH=$(gsd_run query git.base-branch)
 ```
 </step>
 

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

@@ -295,6 +295,9 @@ For each Requirement gathered so far:
    - **Dismiss (reason)** → mark `dismissed` with a required non-empty reason.
    - **Backstop with a test** → mark `backstop`; note "held-out edge test" for plan-phase.
    - **Defer** → leave `unresolved`.
+   - An `unclassified` row (probe `unclassified — review manually`) means the requirement's
+     prose matched no shape cue (#1110) — treat it like any other candidate (**Specify**,
+     **Dismiss (reason)**, or **Defer**). A manual-review nudge, not a hard block.
 
 **Soft gate (after resolving):**
 - All applicable edges resolved → proceed to Step 6.
@@ -310,13 +313,83 @@ For each Requirement gathered so far:
 otherwise auto-`backstop` (never auto-dismiss — a wrong dismissal is the exact silent
 failure being eliminated). Log: `[auto] edge coverage: C covered, B backstop, U unresolved`.
 
+**`unclassified` exception (#1110):** `--auto` leaves an `unclassified` candidate
+**`unresolved`** (the soft gate surfaces it as a flagged planner assumption) — it never
+auto-`backstop`s it. A missing shape is not evidence an edge exists, so minting a held-out
+edge obligation on a requirement that may be genuinely edge-free would be a false claim and
+risks a vacuous edge test. Leaving it `unresolved` keeps the zero-cue requirement visible
+(never a silent drop) without fabricating an edge — which is exactly #1110's purpose: surface
+it for review, do not auto-handle it.
+
 Populate the `## Edge Coverage` section of SPEC.md from the resolved edges.
 
+## Step 5.6: Prohibition-Completeness Probe (must-NOT)
+
+Run AFTER Step 5.5 (you probe the must-NOT axis of clear requirements, over the same
+requirement list). Reference: @~/.claude/gsd-core/references/prohibition-probe.md — the
+portable two-stage protocol, the canon-referral rule, and the status×verification schema
+live there (size-cap discipline; keep this step lean).
+
+**D1 — no compiled engine (ADR-550 D7b).** Unlike Step 5.5, the prohibition probe has NO
+compiled recall engine and runs NO `node` invocation here. The recall stage is an LLM prose
+pass: the closed eight-category edge taxonomy a classifier can apply does not exist for the
+open values/safety/ethics must-NOT axis. Do NOT copy the Step 5.5 engine-resolution block.
+Only the schema/projection layer is real code; the recall is prose.
+
+For each Requirement gathered so far, run the two-stage recall→precision pass:
+
+1. **Stage 1 — Recall (adversarial prose probe).** Ask the single adversarial question of the
+   requirement: *"What could this feature silently become that the author would NOT want, but
+   the spec does not forbid?"* Over-produce (~10 raw must-NOT candidates) — recall first.
+2. **Stage 2 — Precision (one-pass classifier).** Filter the raw list in a single pass:
+   **DROP routine-engineering** items (normal correctness/hygiene — "must not mutate input",
+   "must not throw on empty" — owned by the edge probe or code review); **KEEP
+   values / safety / ethics** items (manipulative framing, protected-attribute proxies, raw
+   PII in plaintext). This collapses ~10 → ~2–3 genuine prohibitions.
+3. **Canon-referral (ADR-550 D6, PROB-13).** A kept candidate that is canon security/compliance
+   (OWASP / prototype-pollution / path-traversal / injection / GDPR / generic fairness) is
+   NOT minted here — emit a one-line breadcrumb (*"prototype-pollution is canon — owned by
+   /gsd:secure-phase + eslint; not minted here"*) and DROP it. Minting canon items duplicates
+   /gsd:secure-phase and drowns the bespoke signal.
+4. **Resolve each surfaced (non-canon) prohibition** (AskUserQuestion; text mode → numbered list):
+   - **Keep it** → write a NEGATIVE acceptance criterion (a must-NOT line) into Acceptance
+     Criteria AND mark the prohibition `resolved` with a verification tier: `test` (a
+     mechanical negative test/lint/assertion exists) or `judgment` (real but not mechanically
+     checkable — routes to judgment review).
+   - **Dismiss (reason)** → mark `dismissed` with a REQUIRED non-empty reason (PROB-05). The
+     reason string is the audit trail; silence is not a valid dismissal.
+   - **Defer** → leave `unresolved`.
+
+**Soft gate (after resolving) — PROB-06:**
+- All applicable prohibitions resolved → proceed to Step 6.
+- Any `unresolved` → AskUserQuestion:
+  - header: "Prohibitions"
+  - question: "[N] prohibition(s) are unresolved: [list]. What do you want to do?"
+  - options: "Resolve now" (loop back) / "Write SPEC.md anyway — flag unresolved" /
+    "Keep probing"
+  - On "anyway": write SPEC.md with those rows marked `⚠ Prohibition unresolved — planner
+    must treat as assumption`. This is a soft gate (write-anyway-with-flags), never a silent
+    skip — the soft gate IS the control.
+
+**`--auto` mode:** auto-`resolved` where a defensible negative acceptance criterion can be
+written (test or judgment tier); otherwise leave `unresolved`. **`--auto` NEVER auto-dismisses
+a prohibition** — a wrong dismissal is the exact silent failure this probe eliminates (PROB-06,
+the load-bearing safety property). Log: `[auto] prohibitions: R resolved, U unresolved`.
+
+**Text mode (PROB-09):** per Step 5's text-mode rule, replace the AskUserQuestion menus above
+with plain-text numbered lists — there is NO hard AskUserQuestion dependency, so the probe
+runs identically for non-Claude / text-mode hosts.
+
+Populate the `## Prohibitions` section of SPEC.md from the resolved prohibitions (each
+`resolved`/`test` row is a checkable negative acceptance criterion; `resolved`/`judgment`
+rows route to judgment review; `⚠ UNRESOLVED` rows are flagged as assumptions).
+
 ## Step 6: Generate SPEC.md
 
 Use the SPEC.md template from @~/.claude/gsd-core/templates/spec.md.
 
 - Populate the **Edge Coverage** section from Step 5.5 (covered/dismissed/backstop/unresolved rows).
+- Populate the **Prohibitions** section from Step 5.6 (resolved/dismissed/unresolved rows with the test|judgment tier).
 
 **Requirements for every requirement entry:**
 - One specific, testable statement
@@ -377,6 +450,7 @@ Next: /gsd:discuss-phase {X}
 - Scout the codebase BEFORE the first question — grounded questions only
 - Max 2–3 questions per round — do not frontload all questions at once
 - Step 5.5 edge probe runs after the ambiguity gate; dismissals require a reason; --auto never auto-dismisses
+- Step 5.6 prohibition probe runs after the edge probe; dismissals require a reason; --auto never auto-dismisses a prohibition
 </critical_rules>
 
 <success_criteria>
@@ -389,4 +463,5 @@ Next: /gsd:discuss-phase {X}
 - SPEC.md committed atomically (when commit_docs is true)
 - User directed to /gsd:discuss-phase as next step
 - Edge-completeness probe run; Edge Coverage section populated; unresolved edges flagged as assumptions
+- Prohibition-completeness probe run; Prohibitions section populated; unresolved prohibitions flagged as assumptions
 </success_criteria>

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

@@ -63,10 +63,15 @@ for plan in "$PHASE_DIR"/*-PLAN.md; do
 done
 ```
 
-Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
+Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...], prohibitions: [...] }`
 
 Aggregate all must_haves across plans for phase-level verification.
 
+**Prohibitions (`must_haves.prohibitions`, ADR-550 D3 — the must-NOT sibling block):** When a plan carries `must_haves.prohibitions`, extract each `{ statement, status, verification }` item and route it by `verification` tier in verdict assembly (ADR-550 D4, "B-with-guard", 2026-06-12 maintainer decision). These are NEGATIVE checks (the must-NOT must NOT have happened), distinct from positive `truths`:
+
+- **judgment-tier → mode-dependent soft-gate.** Interactive verify defers each item to the end-of-phase human checkpoint (`human_verify_mode: end-of-phase`). Autonomous verify records a NON-AUTHORITATIVE LLM-judge verdict + a prominent `unverified-prohibition — human review recommended` flag (autonomous completion reads "complete with N flagged prohibitions"). NEVER a silent pass; NEVER a hard halt of an AFK run.
+- **test-tier → FAIL CLOSED (accept-and-flag).** Accept the `verification: test` value (the SPEC↔must_haves.prohibitions projection contract holds — no forced schema change later), but a well-formed test-tier item reaching verify with NO wired enforcement disposes as UNVERIFIED, flagged like an unresolved judgment item, NEVER green. The deterministic fail-closed default is `dispositionForProhibition()` in probe-core (`status: 'unverified'`, `flagged: true` on empty `enforcementEvidence`). The real fail-first negative-test enforcement MECHANISM defers to a follow-up PR (#644's corpus is entirely judgment-tier; a contrived test-tier fixture here would be the gold-plating failure mode).
+
 **Option B: Use Success Criteria from ROADMAP.md**
 
 If no must_haves in frontmatter (MUST_HAVES returns error or empty), check for Success Criteria:
@@ -465,13 +470,18 @@ Classify status using this decision tree IN ORDER (most restrictive first):
 1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, blocker found, **or test quality audit found blockers (disabled requirement tests, circular tests)**:
    → **gaps_found**
 
-2. IF the previous step produced ANY human verification items:
+2. IF any `must_haves.prohibitions` item disposes as flagged-unverified (ADR-550 D4):
+   - **test-tier, fail-closed** (no wired enforcement — `dispositionForProhibition()` returns `status: 'unverified'`, `flagged: true`): → **gaps_found** (never green; the unwired test-tier item is an unverified gap).
+   - **judgment-tier, autonomous run** (non-authoritative LLM-judge verdict): emit the `unverified-prohibition — human review recommended` flag and classify → **human_needed** (autonomous completion reads "complete with N flagged prohibitions"; never a silent pass, never a hard halt).
+   - **judgment-tier, interactive run**: route to the end-of-phase human checkpoint → **human_needed**.
+
+3. IF the previous step produced ANY human verification items:
    → **human_needed** (even if all truths VERIFIED and score is N/N)
 
-3. IF all checks pass AND no human verification items:
+4. IF all checks pass AND no human verification items AND no flagged prohibitions:
    → **passed**
 
-**passed is ONLY valid when no human verification items exist.**
+**passed is ONLY valid when no human verification items AND no flagged prohibitions exist.** A prohibition (must-NOT) can never be silently absorbed into a `passed` verdict — that is the core failure mode ADR-550 D4 forbids.
 
 **Score:** `verified_truths / total_truths`
 </step>

package/hooks/dist/gsd-ensure-canonical-path.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+//
+// gsd-ensure-canonical-path — SessionStart hook (#997)
+//
+// PROBLEM: GSD agents/commands/templates use markdown `@`-file-includes that
+// hardcode the canonical path `@~/.claude/gsd-core/...` (references, workflows,
+// templates, contexts, bin). Markdown @-includes expand `~` but do NOT expand
+// environment variables, so `${CLAUDE_PLUGIN_ROOT}` cannot be used in them.
+// In a classic `bin/install.js` install the canonical path is a real directory
+// holding the bundled tree, so the includes resolve. In a Claude Code
+// *marketplace plugin* install the plugin manager only unpacks the package
+// into the version-pinned plugin cache and never runs `bin/install.js`, so
+// `~/.claude/gsd-core/` is never created and every @-include resolves to
+// nothing — every agent that depends on one fails (e.g. the executor).
+//
+// FIX: On SessionStart, when running under a plugin install (CLAUDE_PLUGIN_ROOT
+// set and a bundled `gsd-core/` tree found beneath it), ensure
+// `~/.claude/gsd-core/` exists and its immutable subdirs (bin, contexts,
+// references, templates, workflows) are symlinked to the plugin's bundled tree.
+// This changes ZERO @-references, is a no-op in classic installs (where each
+// subdir is already a real directory), preserves user-generated files
+// (USER-PROFILE.md, STATE.md, VERSION, …), prunes stale links so it self-heals
+// after `claude plugin update` rotates the version dir, and uses Windows
+// junctions for symlinks on win32.
+//
+// SECURITY: the resolved bundled-tree path and every per-subdir link target are
+// kept strictly inside the resolved plugin root (realpath-normalised, prefix-
+// checked). A real (non-symlink) file or directory already sitting at a managed
+// link target is NEVER clobbered.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Immutable, bundled subdirectories that the canonical path must expose. These
+// are the directories `@~/.claude/gsd-core/<subdir>/...` includes point into.
+// User-generated artifacts (USER-PROFILE.md, STATE.md, VERSION, config, …) are
+// NOT in this list and are never created, moved, or deleted by this hook.
+const MANAGED_SUBDIRS = ['bin', 'contexts', 'references', 'templates', 'workflows'];
+
+/**
+ * Resolve the canonical runtime config dir for the active runtime.
+ *
+ * Honours CLAUDE_CONFIG_DIR for custom/multi-account setups (mirrors
+ * gsd-check-update.js detectConfigDir), else falls back to ~/.claude. The
+ * canonical GSD tree always lives at `<configDir>/gsd-core`.
+ */
+function resolveConfigDir(homeDir, env) {
+  const envDir = env.CLAUDE_CONFIG_DIR;
+  if (envDir && typeof envDir === 'string' && envDir.trim().length > 0) {
+    return envDir;
+  }
+  return path.join(homeDir, '.claude');
+}
+
+/**
+ * Locate the bundled `gsd-core/` tree beneath a plugin root.
+ *
+ * Claude Code unpacks the package so the bundled tree sits at
+ * `<pluginRoot>/gsd-core/`. Returns the absolute, realpath-normalised path to
+ * that directory, or null if it is absent / not a directory. Resolving with
+ * realpath collapses symlinks/.. so the subsequent containment check is sound.
+ */
+function resolveBundledTree(pluginRoot) {
+  if (!pluginRoot || typeof pluginRoot !== 'string' || pluginRoot.trim().length === 0) {
+    return null;
+  }
+  let root;
+  try {
+    root = fs.realpathSync(pluginRoot);
+  } catch (_) {
+    return null; // plugin root does not exist
+  }
+  const bundled = path.join(root, 'gsd-core');
+  let bundledReal;
+  try {
+    // The bundled tree must be a real directory (or a symlink to one) that
+    // resolves to a path inside the plugin root. realpathSync throws ENOENT/
+    // ENOTDIR if <pluginRoot>/gsd-core is absent, so no separate existence
+    // check is needed. Reject anything that does not resolve to a directory.
+    bundledReal = fs.realpathSync(bundled);
+    if (!fs.statSync(bundledReal).isDirectory()) return null;
+  } catch (_) {
+    return null;
+  }
+  // SECURITY: the resolved bundled tree must stay inside the resolved plugin
+  // root. A crafted symlink at <pluginRoot>/gsd-core pointing outside the root
+  // is rejected — we never link the canonical path at content we do not own.
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (bundledReal !== root && !bundledReal.startsWith(rootWithSep)) {
+    return null;
+  }
+  return bundledReal;
+}
+
+/**
+ * The fs.symlinkSync `type` to use for a directory link on a given platform.
+ *
+ * On Windows, unprivileged users cannot create symlinks but CAN create
+ * junctions; 'junction' requires an absolute target (we always pass one). On
+ * POSIX a 'dir' symlink is used. Exported so the win32 branch is unit-testable
+ * without a Windows host.
+ */
+function dirLinkType(platform) {
+  return platform === 'win32' ? 'junction' : 'dir';
+}
+
+/**
+ * Create a directory symlink (junction on win32) from linkPath -> target.
+ * Throws on real failure so the caller records it.
+ */
+function createDirLink(target, linkPath, platform) {
+  fs.symlinkSync(target, linkPath, dirLinkType(platform));
+}
+
+/**
+ * Does `linkPath` already correctly point at `expectedTarget`?
+ * Used to make the hook idempotent — a correct link is left untouched.
+ */
+function linkPointsAt(linkPath, expectedTarget) {
+  try {
+    if (!fs.lstatSync(linkPath).isSymbolicLink()) return false;
+    const resolved = fs.realpathSync(linkPath);
+    return resolved === fs.realpathSync(expectedTarget);
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Ensure the canonical `~/.claude/gsd-core/` path exposes the bundled subdirs.
+ *
+ * Pure, dependency-injected core so tests drive it with a fake home, fake
+ * plugin root, and explicit platform. Returns a structured result describing
+ * exactly what happened (never throws for ordinary conditions — only truly
+ * unexpected I/O errors propagate, and the thin CLI wrapper swallows those so
+ * a hook failure never blocks a session).
+ *
+ * @param {object} opts
+ * @param {string} [opts.homeDir]    home directory (default os.homedir())
+ * @param {string} [opts.pluginRoot] CLAUDE_PLUGIN_ROOT (default from env)
+ * @param {string} [opts.platform]   process.platform override (tests)
+ * @param {object} [opts.env]        environment (default process.env)
+ * @returns {{status:string, canonicalDir?:string, bundledTree?:string,
+ *            linked?:string[], prunedStale?:string[], preserved?:string[],
+ *            skipped?:string[], reason?:string}}
+ */
+function ensureCanonicalPath(opts = {}) {
+  const env = opts.env || process.env;
+  const homeDir = opts.homeDir || os.homedir();
+  const platform = opts.platform || process.platform;
+  const pluginRoot = opts.pluginRoot !== undefined ? opts.pluginRoot : env.CLAUDE_PLUGIN_ROOT;
+
+  // Uniform result contract: every return carries the four action arrays so
+  // callers can read result.linked/etc without first switching on status.
+  const empty = { linked: [], prunedStale: [], preserved: [], skipped: [] };
+
+  // No plugin context → classic/npm install or non-plugin runtime. No-op.
+  const bundledTree = resolveBundledTree(pluginRoot);
+  if (!bundledTree) {
+    return { status: 'noop', reason: 'no-plugin-bundle', ...empty };
+  }
+
+  const configDir = resolveConfigDir(homeDir, env);
+  const canonicalDir = path.join(configDir, 'gsd-core');
+
+  // Inspect the canonical path itself exactly once.
+  //  - If it is a SYMLINK, the user (or another tool) deliberately pointed the
+  //    canonical path elsewhere. We must NOT write managed links *through* that
+  //    symlink into a directory we do not own — bail as a no-op.
+  //  - If it is a REAL directory with at least one REAL (non-link) managed
+  //    subdir, this is a classic `bin/install.js` install — leave it alone.
+  let canonicalStat = null;
+  try { canonicalStat = fs.lstatSync(canonicalDir); } catch (_) { canonicalStat = null; }
+
+  if (canonicalStat && canonicalStat.isSymbolicLink()) {
+    return { status: 'noop', reason: 'canonical-is-symlink', canonicalDir, bundledTree, ...empty };
+  }
+
+  if (canonicalStat && canonicalStat.isDirectory()) {
+    for (const sub of MANAGED_SUBDIRS) {
+      try {
+        const subSt = fs.lstatSync(path.join(canonicalDir, sub));
+        if (subSt.isDirectory() && !subSt.isSymbolicLink()) {
+          return { status: 'noop', reason: 'classic-install', canonicalDir, bundledTree, ...empty };
+        }
+      } catch (_) { /* subdir absent — keep checking */ }
+    }
+  }
+
+  // Ensure the canonical directory exists (as a real directory). We never
+  // replace an existing real directory; recursive mkdir is a no-op if present.
+  try {
+    fs.mkdirSync(canonicalDir, { recursive: true });
+  } catch (e) {
+    return { status: 'error', reason: `mkdir-canonical: ${e.code || e.message}`, canonicalDir, bundledTree, ...empty };
+  }
+
+  const linked = [];
+  const prunedStale = [];
+  const preserved = [];
+  const skipped = [];
+
+  // SECURITY: prefix used to confirm every per-subdir link target resolves
+  // strictly inside the bundled tree. Defence-in-depth against a tampered
+  // bundle that ships an internally-escaping symlink at <bundledTree>/<sub>.
+  const bundledWithSep = bundledTree.endsWith(path.sep) ? bundledTree : bundledTree + path.sep;
+
+  for (const sub of MANAGED_SUBDIRS) {
+    const target = path.join(bundledTree, sub);
+    // Only expose subdirs the bundle actually ships, AND only when the target
+    // resolves to a real directory that stays inside the bundled tree. A
+    // subdir whose realpath escapes the bundle (e.g. a planted symlink) is
+    // skipped — we never point the canonical path at content outside the
+    // validated plugin bundle.
+    let targetIsDir = false;
+    try {
+      const targetReal = fs.realpathSync(target);
+      // A NAMED subdir must resolve strictly BELOW the bundled tree root. We do
+      // NOT accept targetReal === bundledTree here: a subdir that self-links to
+      // the tree root would otherwise be exposed at the wrong level (e.g.
+      // `workflows` -> the whole tree), making `@.../workflows/foo` resolve to
+      // `<tree>/foo` instead of `<tree>/workflows/foo`.
+      targetIsDir = fs.statSync(targetReal).isDirectory()
+        && targetReal.startsWith(bundledWithSep);
+    } catch (_) { targetIsDir = false; }
+    if (!targetIsDir) {
+      skipped.push(sub);
+      continue;
+    }
+
+    const linkPath = path.join(canonicalDir, sub);
+
+    // Already a correct link → idempotent no-op.
+    if (linkPointsAt(linkPath, target)) {
+      linked.push(sub);
+      continue;
+    }
+
+    let existing = null;
+    try { existing = fs.lstatSync(linkPath); } catch (_) { existing = null; }
+
+    if (existing) {
+      // lstat().isSymbolicLink() is true for BOTH POSIX symlinks and Windows
+      // junctions, so this single predicate identifies every GSD-managed link.
+      if (existing.isSymbolicLink()) {
+        // A GSD-managed link that is stale or points elsewhere (e.g. previous
+        // plugin version after `claude plugin update`). Prune and recreate.
+        try {
+          fs.unlinkSync(linkPath);
+          prunedStale.push(sub);
+        } catch (e) {
+          skipped.push(sub);
+          continue;
+        }
+      } else {
+        // A REAL file or directory the user (or a classic install) owns. NEVER
+        // clobber it — preserve it untouched. This is the USER-PROFILE.md /
+        // partially-real-canonical-dir safety case.
+        preserved.push(sub);
+        continue;
+      }
+    }
+
+    try {
+      createDirLink(target, linkPath, platform);
+      linked.push(sub);
+    } catch (e) {
+      skipped.push(sub);
+    }
+  }
+
+  return {
+    status: 'ensured',
+    canonicalDir,
+    bundledTree,
+    linked,
+    prunedStale,
+    preserved,
+    skipped,
+  };
+}
+
+module.exports = {
+  ensureCanonicalPath,
+  resolveBundledTree,
+  resolveConfigDir,
+  dirLinkType,
+  MANAGED_SUBDIRS,
+};
+
+// CLI entry: run on SessionStart. Never block the session — any unexpected
+// failure is swallowed (best-effort self-heal). Emit nothing on stdout to keep
+// the hook silent in normal operation.
+if (require.main === module) {
+  try {
+    ensureCanonicalPath();
+  } catch (_) {
+    // Best-effort: a canonical-path failure must never abort a session.
+  }
+  process.exit(0);
+}

package/hooks/dist/gsd-statusline.js

@@ -312,7 +312,7 @@ function runStatusline() {
     const totalCtx = data.context_window?.total_tokens || 1_000_000;
     const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
     const AUTO_COMPACT_BUFFER_PCT = acw > 0
-      ? Math.min(100, (acw / totalCtx) * 100)
+      ? Math.min(100, Math.max(0, (1 - acw / totalCtx) * 100))
       : 16.5;
     let ctx = '';
     if (remaining != null) {

package/hooks/dist/managed-hooks-registry.cjs

@@ -22,6 +22,7 @@ const MANAGED_HOOKS = [
   'gsd-context-monitor.js',
   'gsd-cursor-post-tool.js',
   'gsd-cursor-session-start.js',
+  'gsd-ensure-canonical-path.js',
   'gsd-graphify-update.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',