@opengsd/gsd-core 1.14.0 → 1.15.0

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

@@ -337,6 +337,30 @@ function resolveRegistryIsolation(cwd, configPath) {
     if (!useWorktrees) isolation = 'none';
   }
 
+  // #4734: a harness worktree can never be created in a directory that is not
+  // a git repository (or a repository with no commits) — git's definitive
+  // exit-128 answer on `rev-parse HEAD`. Demanding the isolation flag there
+  // blocked every flag-less dispatch the moment the sentinel went stale, on a
+  // root where no worktree can exist. Degrade to 'none' exactly like the
+  // use_worktrees opt-out above; the classification is owned by
+  // `classifyGitHead` (worktree-base-ref.cjs) — the same single owner the
+  // base-check's degrade decision uses — and ambiguous or failed resolutions
+  // keep the conservative (enforce) default, matching that check's own
+  // fail-closed treatment of the same classes.
+  if (isolation === 'harness-worktree') {
+    try {
+      ensureRuntimeBuild();
+      const { classifyGitHead } = require('../gsd-core/bin/lib/worktree-base-ref.cjs');
+      if (classifyGitHead({ cwd }).status === 'definitive-absence') {
+        isolation = 'none';
+      }
+    } catch {
+      // Unbuilt or unreadable runtime library — keep the conservative
+      // (enforce) default rather than silently disabling the guard, same
+      // posture as the ladder fallback above.
+    }
+  }
+
   return { isolation, harnessFlag };
 }
 

package/hooks/gsd-secret-read-guard.js

@@ -86,7 +86,12 @@
 //   on plain commands, without arming the compound-`cd` prompt". Writes to
 //   secret files are out of scope (Write/Edit were never gated). Commands
 //   over 1 MiB are denied outright (`command-too-large`) rather than
-//   scanned partially or waved through.
+//   scanned partially or waved through. (#4639 adds one more, by design: the
+//   value of `--env-file` under a container runtime is exempt, so the
+//   container's own command can print the interpolated environment
+//   (`alpine printenv`, `docker compose config`) — the same exposure class
+//   as the pre-existing volume-mount gap (`-v .env:/s`); the flag's value
+//   itself is a name, never contents.)
 //
 // Triggers on: Read, Grep, Bash tool calls (Kimi: ReadFile, Grep, Shell)
 // Action: BLOCK (decision: 'block', exit 2) — codes secret-read |
@@ -127,6 +132,15 @@ const NON_READING_COMMANDS = new Set([
   'basename', 'dirname', 'realpath', 'file', 'echo', 'printf',
 ]);
 
+// #4639: container runtimes take `--env-file <file>` — the runtime opens the
+// file itself, interpolates it into the container environment, and returns
+// nothing to the agent, so the flag's VALUE is a name, never contents. The
+// same category NON_READING_COMMANDS encodes, expressed as a flag value. Only
+// the flag's value under these runtimes is exempt; every other operand in the
+// segment is still checked, so the carve-out cannot launder a read.
+const CONTAINER_RUNTIMES = new Set(['docker', 'docker-compose', 'podman', 'nerdctl']);
+const ENV_FILE_FLAG_RE = /^--env-file(=|$)/;
+
 // Shell interpreters that run a script from `-c`, a file operand, or stdin
 // (heredoc / here-string / piped `echo`|`printf`). `su` is here for its `-c`
 // form (`su [user] -c 'cmd'`); a bare `su user` resolves to file mode, which
@@ -840,7 +854,19 @@ function findSecretRead(command, depth) {
 
     if (NON_READING_COMMANDS.has(base)) continue;
 
+    // #4639: exempt ONLY the value of `--env-file`, and only when the
+    // segment's command word is a container runtime. A bare `--env-file`
+    // consumes the next operand; `--env-file=<value>` is a single word.
+    const envFileExempt = CONTAINER_RUNTIMES.has(base);
+    let skipNext = false;
     for (const w of operands) {
+      if (envFileExempt) {
+        if (skipNext) { skipNext = false; continue; }
+        if (ENV_FILE_FLAG_RE.test(w.text)) {
+          if (!w.text.includes('=')) skipNext = true; // bare flag consumes the next operand
+          continue;
+        }
+      }
       if (namesSecret(normalizeOperand(w.text))) return w.text;
     }
   }

package/hooks/gsd-statusline.js

@@ -42,6 +42,10 @@ if (require.main === module) {
 const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
 const { normalizeStateStatus } = require('../gsd-core/bin/lib/state-document.cjs');
+const {
+  renderBracketPhaseDisplay,
+  renderBracketMilestoneDisplay,
+} = require('../gsd-core/bin/lib/phase-id-display.cjs');
 // #2850: reuse the existing workstream resolution seams rather than
 // re-implementing CLI>env>store precedence or path construction inline.
 // peekActiveWorkstream is the read-only sibling of the store-tier lookup
@@ -359,16 +363,26 @@ function renderProgressBar(percent) {
  * Progress bar is opt-in: appended to the milestone segment only when
  * progress.percent is present in frontmatter; absent → empty string.
  */
-function formatGsdState(s) {
+function formatGsdState(s, opts = {}) {
   // #2850: workstream mode with nothing resolvable — an observable signal,
   // never silent emptiness (distinguishes from "GSD isn't installed here").
   if (s.noActiveWorkstream) return NO_ACTIVE_WORKSTREAM_LABEL;
 
   const parts = [];
+  const bracket = opts.convention === 'bracket';
+  const bracketMilestone = bracket
+    ? renderBracketMilestoneDisplay(s.milestone, opts.projectCode)
+    : null;
+  const phaseLabel = (phase) => {
+    const display = bracket
+      ? renderBracketPhaseDisplay(s.milestone, phase, opts.projectCode)
+      : null;
+    return display ?? `Phase ${phase}`;
+  };
 
   // Milestone segment: version + name + (opt-in) progress bar
   if (s.milestone || s.milestoneName) {
-    const ver = s.milestone || '';
+    const ver = bracketMilestone ?? s.milestone ?? '';
     const name = (s.milestoneName && s.milestoneName !== 'milestone') ? s.milestoneName : '';
     const bar = renderProgressBar(s.percent);
     const pieces = [ver, name, bar].filter(Boolean);
@@ -384,7 +398,8 @@ function formatGsdState(s) {
     // stage = whichever lifecycle status was written by the orchestrator
     //   (discussing / planning / executing / verifying)
     const stage = s.status || '';
-    parts.push(stage ? `Phase ${s.activePhase} ${stage}` : `Phase ${s.activePhase}`);
+    const phase = phaseLabel(s.activePhase);
+    parts.push(stage ? `${phase} ${stage}` : phase);
   } else if (s.nextAction && phasesStr) {
     // Scene 2: idle + a recommended next command is visible to the user.
     // Surfaces "what to run next" without the user opening STATE.md.
@@ -402,9 +417,16 @@ function formatGsdState(s) {
     // earlier so no existing project's status-line changes shape.
     if (s.status) parts.push(s.status);
     if (s.phaseNum && s.phaseTotal) {
+      const bracketPhase = bracket
+        ? renderBracketPhaseDisplay(s.milestone, s.phaseNum, opts.projectCode)
+        : null;
       const phase = s.phaseName
-        ? `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
-        : `ph ${s.phaseNum}/${s.phaseTotal}`;
+        ? bracketPhase
+          ? `${bracketPhase} ${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
+          : `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
+        : bracketPhase
+          ? `${bracketPhase} (${s.phaseNum}/${s.phaseTotal})`
+          : `ph ${s.phaseNum}/${s.phaseTotal}`;
       parts.push(phase);
     }
   }
@@ -490,17 +512,24 @@ function shortGsdStatus(status) {
  * default format — and collapses narrative statuses via shortGsdStatus().
  * The default "full" format is untouched.
  */
-function formatGsdStateCompact(s) {
+function formatGsdStateCompact(s, opts = {}) {
   // #2850: mirrors formatGsdState's observable "nothing resolvable" signal.
   if (s.noActiveWorkstream) return NO_ACTIVE_WORKSTREAM_LABEL;
 
   const parts = [];
+  const bracket = opts.convention === 'bracket';
+  const bracketMilestone = bracket
+    ? renderBracketMilestoneDisplay(s.milestone, opts.projectCode)
+    : null;
 
-  if (s.milestone) parts.push(s.milestone);
+  if (s.milestone) parts.push(bracketMilestone ?? s.milestone);
 
   const phaseId = s.activePhase || s.phaseNum;
   if (phaseId) {
-    parts.push(s.phaseTotal ? `P${phaseId}/${s.phaseTotal}` : `P${phaseId}`);
+    const bracketPhase = bracket
+      ? renderBracketPhaseDisplay(s.milestone, phaseId, opts.projectCode)
+      : null;
+    parts.push(bracketPhase ?? (s.phaseTotal ? `P${phaseId}/${s.phaseTotal}` : `P${phaseId}`));
   }
 
   // Scene exclusivity mirrors formatGsdState's if/else chain: an in-flight
@@ -747,7 +776,7 @@ function formatStateFreshness(fresh) {
  * entry points — this collapses both onto one resolver.
  *
  * @param {object} cfg — parsed .planning/config.json (readGsdConfig())
- * @returns {{ showLastCommand: boolean, position: 'end'|'front', stateFormat: 'full'|'compact', showGit: boolean, showStateFreshness: boolean }}
+ * @returns {{ showLastCommand: boolean, position: 'end'|'front', stateFormat: 'full'|'compact', showGit: boolean, showStateFreshness: boolean, convention: string|null, projectCode: string|null }}
  */
 function resolveStatuslineOptions(cfg) {
   const showLastCommand = getConfigValue(cfg, 'statusline.show_last_command') === true;
@@ -759,7 +788,22 @@ function resolveStatuslineOptions(cfg) {
   const stateFormat = getConfigValue(cfg, 'statusline.state_format') === 'compact' ? 'compact' : 'full';
   const showGit = getConfigValue(cfg, 'statusline.show_git') === true;
   const showStateFreshness = getConfigValue(cfg, 'statusline.show_state_freshness') === true;
-  return { showLastCommand, position, stateFormat, showGit, showStateFreshness };
+  const convention = getConfigValue(cfg, 'phase_id_convention') === 'bracket'
+    ? 'bracket'
+    : null;
+  const projectCodeValue = getConfigValue(cfg, 'project_code');
+  const projectCode = typeof projectCodeValue === 'string' && projectCodeValue !== ''
+    ? projectCodeValue
+    : null;
+  return {
+    showLastCommand,
+    position,
+    stateFormat,
+    showGit,
+    showStateFreshness,
+    convention,
+    projectCode,
+  };
 }
 
 // --- stdin ------------------------------------------------------------------
@@ -934,7 +978,9 @@ function runStatusline() {
     // freshness git spawn here would spend a subprocess on discarded output.
     if (!task) {
       const state = readGsdState(dir, { stateFreshness: options.showStateFreshness }) || {};
-      gsdStateStr = options.stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
+      gsdStateStr = options.stateFormat === 'compact'
+        ? formatGsdStateCompact(state, options)
+        : formatGsdState(state, options);
     }
 
     // Output
@@ -1042,6 +1088,7 @@ module.exports = {
   STATE_HEAD_ADVISORY_COMMITS, isValidStateHeadStamp,
   readStateHeadCommits, parseRevListCounts, deriveStateFreshness,
   formatStateFreshness, resolveStatuslineOptions,
+  renderBracketPhaseDisplay, renderBracketMilestoneDisplay,
 };
 
 /**
@@ -1059,7 +1106,15 @@ function renderStatusline(data) {
   // key from reaching only one of them.
   let lastCmdSuffix = '';
   let gitSuffix = '';
-  let options = { showLastCommand: false, position: 'end', stateFormat: 'full', showGit: false, showStateFreshness: false };
+  let options = {
+    showLastCommand: false,
+    position: 'end',
+    stateFormat: 'full',
+    showGit: false,
+    showStateFreshness: false,
+    convention: null,
+    projectCode: null,
+  };
   try {
     const cfg = readGsdConfig(dir);
     options = resolveStatuslineOptions(cfg);
@@ -1075,7 +1130,9 @@ function renderStatusline(data) {
   } catch (e) { /* swallow */ }
 
   const state = readGsdState(dir, { stateFreshness: options.showStateFreshness }) || {};
-  const gsdStateStr = options.stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
+  const gsdStateStr = options.stateFormat === 'compact'
+    ? formatGsdStateCompact(state, options)
+    : formatGsdState(state, options);
   const middle = gsdStateStr ? `\x1b[2m${gsdStateStr}\x1b[0m` : null;
   return composeStatusline({ model, ctx: '', middle, dirname, lastCmdSuffix, gitSuffix, position: options.position });
 }

package/hooks/gsd-validate-commit.sh

@@ -16,6 +16,21 @@ set -euo pipefail
 # Idempotent and failure-proof by construction: unset vars expand to "" (a
 # no-op rm -f target), and `|| true` guarantees the trap itself never changes
 # the script's exit status.
+# Subprocess exit statuses, pre-initialised so they can never be inherited from
+# the ambient environment. Each is captured as `... || VAR=$?`, which assigns
+# ONLY on the failure branch; on success the variable keeps whatever it already
+# held, and `${VAR:-0}` defaults only when unset or empty. So an EXPORTED
+# CONFIG_STATUS / CMD_STATUS / CLASSIFY_STATUS — from a CI wrapper, a .envrc, or
+# another hook — survived into the success path and was read as "the subprocess
+# failed". Measured: `CLASSIFY_STATUS=3 git commit -m "nope: bad"` printed
+# "validator disabled for this call" and exited 0, silently accepting a
+# non-conforming commit. Same for CONFIG_STATUS and CMD_STATUS. Found by the
+# security review of #4429; the gate is fail-open by design on a genuine
+# subprocess failure (#3838), which is exactly what made this bypass quiet.
+CONFIG_STATUS=0
+CMD_STATUS=0
+CLASSIFY_STATUS=0
+
 ENABLED_ERR=""
 CMD_ERR=""
 CLASSIFY_ERR=""
@@ -61,6 +76,12 @@ if [ -f .planning/config.json ]; then
       process.exit(3);
     }
   " 2>"$ENABLED_ERR") || CONFIG_STATUS=$?
+  # Pre-initialised, NOT left to `${...:-0}` alone: the capture below only
+  # assigns on the `||` branch, so on SUCCESS the variable keeps whatever it
+  # already held — and an EXPORTED variable of this name is inherited from the
+  # ambient environment. `${VAR:-0}` defaults only when unset/empty, so
+  # `CONFIG_STATUS=3 git commit …` made this hook print "validator disabled" and exit 0,
+  # silently accepting a non-conforming commit. Found by review of #4429.
   CONFIG_STATUS=${CONFIG_STATUS:-0}
   if [ "$CONFIG_STATUS" != "0" ]; then
     # Could not determine the opt-in flag at all (node missing, JSON parse
@@ -103,6 +124,12 @@ CMD=$(echo "$INPUT" | node -e "
     }
   });
 " 2>"$CMD_ERR") || CMD_STATUS=$?
+# Pre-initialised, NOT left to `${...:-0}` alone: the capture below only
+# assigns on the `||` branch, so on SUCCESS the variable keeps whatever it
+# already held — and an EXPORTED variable of this name is inherited from the
+# ambient environment. `${VAR:-0}` defaults only when unset/empty, so
+# `CMD_STATUS=3 git commit …` made this hook print "validator disabled" and exit 0,
+# silently accepting a non-conforming commit. Found by review of #4429.
 CMD_STATUS=${CMD_STATUS:-0}
 if [ "$CMD_STATUS" != "0" ]; then
   # Could not extract tool_input.command at all (node missing, malformed
@@ -127,6 +154,12 @@ GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
     process.exit(3);
   }
 " "$CMD" 2>"$CLASSIFY_ERR" || CLASSIFY_STATUS=$?
+# Pre-initialised, NOT left to `${...:-0}` alone: the capture below only
+# assigns on the `||` branch, so on SUCCESS the variable keeps whatever it
+# already held — and an EXPORTED variable of this name is inherited from the
+# ambient environment. `${VAR:-0}` defaults only when unset/empty, so
+# `CLASSIFY_STATUS=3 git commit …` made this hook print "validator disabled" and exit 0,
+# silently accepting a non-conforming commit. Found by review of #4429.
 CLASSIFY_STATUS=${CLASSIFY_STATUS:-0}
 if [ "$CLASSIFY_STATUS" != "0" ] && [ "$CLASSIFY_STATUS" != "1" ]; then
   # 0 = is a git commit (validate below); 1 = genuinely not a git commit
@@ -557,7 +590,7 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
     fi
     # Single source of truth for the accepted commit-type list (#3811): the
     # 10 built-ins plus whatever passed the safe-token filter above. Both the
-    # regex alternation and the human-readable error text below are derived
+    # membership test and the human-readable error text below are derived
     # from this ONE array — no hand-synced second copy.
     #
     # The `"${EXTRA_COMMIT_TYPES[@]+"${EXTRA_COMMIT_TYPES[@]}"}"` form (not
@@ -568,7 +601,6 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
     # /bin/bash 3.2.57 on macOS. The `${arr[@]+word}` form is the
     # nounset-safe idiom for "expand if set, empty otherwise" on empty arrays.
     COMMIT_TYPES=("${BUILTIN_COMMIT_TYPES[@]}" "${EXTRA_COMMIT_TYPES[@]+"${EXTRA_COMMIT_TYPES[@]}"}")
-    COMMIT_TYPE_ALT=$(IFS='|'; echo "${COMMIT_TYPES[*]}")
     COMMIT_TYPE_LIST=$(printf '%s, ' "${COMMIT_TYPES[@]}")
     COMMIT_TYPE_LIST="${COMMIT_TYPE_LIST%, }"
     # Typed `valid_types` array (#3811 review finding): CONTRIBUTING.md bans
@@ -580,8 +612,35 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
     # or `\`.
     COMMIT_TYPES_JSON=$(printf '"%s",' "${COMMIT_TYPES[@]}")
     COMMIT_TYPES_JSON="[${COMMIT_TYPES_JSON%,}]"
-    # Validate Conventional Commits format
-    if ! [[ "$SUBJECT" =~ ^($COMMIT_TYPE_ALT)(\(.+\))?:[[:space:]].+ ]]; then
+    # Validate Conventional Commits format.
+    #
+    # #4429: do NOT build `^(type1|type2|...)` out of COMMIT_TYPES. That
+    # alternation grows with the CONFIGURED list, and how large a pattern can be
+    # compiled is a property of the platform's regex engine. bash 3.2.57 / BSD
+    # libc (macOS, this file's stated target) caps it at 64 KiB - bisected: a
+    # 65504-byte alternation compiles, 65515 fails. bash 5.2 / glibc has no
+    # reachable cap, so this half never bit Linux. Past a cap `[[ =~ ]]`
+    # returns 2, and `if !` cannot tell a COMPILE ERROR from "the subject does
+    # not conform" - so a valid `feat(auth): ...` was blocked with
+    # CONVENTIONAL_COMMITS_VIOLATION while `feat` sat in its own valid_types.
+    #
+    # Match the SHAPE with a fixed-size pattern, then test membership against
+    # the array. The regex no longer depends on how many types are configured,
+    # and the loop adds no subprocess or pipe (the #4429 hazard this file
+    # already avoids elsewhere). The character class is exactly the safe-token
+    # filter `^[a-z][a-z0-9-]*$` applied above, so it captures every type that
+    # can legally reach COMMIT_TYPES and no token that cannot.
+    SUBJECT_TYPE=''
+    if [[ "$SUBJECT" =~ ^([a-z][a-z0-9-]*)(\(.+\))?:[[:space:]].+ ]]; then
+      SUBJECT_TYPE="${BASH_REMATCH[1]}"
+    fi
+    COMMIT_TYPE_OK=0
+    if [ -n "$SUBJECT_TYPE" ]; then
+      for _known_type in "${COMMIT_TYPES[@]}"; do
+        if [ "$_known_type" = "$SUBJECT_TYPE" ]; then COMMIT_TYPE_OK=1; break; fi
+      done
+    fi
+    if [ "$COMMIT_TYPE_OK" -ne 1 ]; then
       # Emit typed `code` and `valid_types` fields alongside `reason` (#2974,
       # #3811). Tests assert on the stable code string and the typed array;
       # the reason is the human-readable copy, never grepped by tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "main": ".opencode/plugins/gsd-core.js",
   "bin": {
@@ -124,7 +124,7 @@
     "lint:frontmatter-scalar-broad-grep": "node scripts/lint-frontmatter-scalar-broad-grep.cjs",
     "lint:removed-but-needed": "node scripts/lint-removed-but-needed.cjs",
     "lint:response-language": "node scripts/lint-response-language-coverage.cjs",
-    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/lint-portable-grep.cjs && node scripts/lint-allowed-tools-parity.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs && node scripts/lint-workflow-shellcheck.cjs && npm run lint:response-language",
+    "lint:ci": "npm run lint && npm run lint:skill-deps && npm run lint:generated-sync && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && npm run lint:retired-runtime-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-allow-test-rule-refs.cjs && node scripts/lint-resolution-provenance.cjs && node scripts/lint-portable-timeout.cjs && node scripts/lint-portable-grep.cjs && node scripts/lint-allowed-tools-parity.cjs && node scripts/lint-phase-arg-assignment.cjs && node scripts/validate-registry.cjs && node scripts/lint-table-schema-drift.cjs && node scripts/lint-pr-branch-pattern-drift.cjs && node scripts/lint-fix-has-regression-tests.cjs && node scripts/lint-example-parser-parity.cjs && node scripts/lint-docs-command-form.cjs && node scripts/lint-plan-count-drift.cjs && node scripts/lint-milestone-window-drift.cjs && node scripts/lint-phase-enumeration-drift.cjs && node scripts/lint-planning-prompt-drift.cjs && node scripts/lint-unreachable-guard-drift.cjs && node scripts/lint-completion-ratio-drift.cjs && node scripts/lint-slug-derivation-drift.cjs && node scripts/lint-state-field-drift.cjs && node scripts/lint-state-write-path-drift.cjs && node scripts/lint-completion-predicate-drift.cjs && node scripts/lint-planning-snapshot-bypass-drift.cjs && node scripts/lint-health-diagnostic-rule-table.cjs && node scripts/lint-planning-artifact-writer-drift.cjs && node scripts/lint-frontmatter-scalar-broad-grep.cjs && node scripts/lint-removed-but-needed.cjs && node scripts/lint-no-adhoc-regex-escape.cjs && node scripts/lint-vendored-deps.cjs && node scripts/lint-docs-guard-registration.cjs && node scripts/lint-source-test-name-collision.cjs && npm run lint:hooks-runtime-build-seam && node scripts/check-contract-drift.cjs && node scripts/lint-mutation-test-derivation-drift.cjs && node scripts/lint-seam-enforcement.cjs && node scripts/lint-workflow-shellcheck.cjs && npm run lint:response-language",
     "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
     "lint:regression-names": "node scripts/lint-regression-test-names.cjs",
     "lint:descriptions": "node scripts/lint-descriptions.cjs",
@@ -136,6 +136,7 @@
     "lint:docs": "node scripts/lint-docs-required.cjs",
     "lint:qa-smells": "node scripts/qa-smell-ratchet.cjs",
     "lint:legacy-name": "node scripts/lint-legacy-dir-name.cjs",
+    "lint:retired-runtime-name": "node scripts/lint-retired-runtime-name.cjs",
     "lint:seam-enforcement": "node scripts/lint-seam-enforcement.cjs",
     "lint:docs-command-form": "node scripts/lint-docs-command-form.cjs",
     "lint:hooks-runtime-build-seam": "node scripts/lint-hooks-runtime-build-seam.cjs",

package/scripts/build-hooks.js

@@ -11,16 +11,25 @@ const path = require('path');
 const vm = require('vm');
 
 const HOOKS_DIR = path.join(__dirname, '..', 'hooks');
+const REPO_ROOT = path.join(HOOKS_DIR, '..');
 const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 // Per-process staging directory for atomic writes. Using process.pid in the
 // name eliminates all contention between concurrent builders: each process
 // owns its own staging dir and never races with another builder's cleanup.
-// Lives under hooks/ so it shares a filesystem with DIST_DIR (POSIX
-// rename(2) is only atomic within the same filesystem) but is NOT inside
-// DIST_DIR — so readers that readdirSync(DIST_DIR) (e.g. bin/install.js,
-// install-hooks-copy tests) never observe a transient ".tmp" sibling.
-// The parent pattern hooks/.dist-staging-*/ is gitignored.
-const STAGE_DIR = path.join(HOOKS_DIR, `.dist-staging-${process.pid}`);
+// A SIBLING of hooks/ (not inside it) — still on the same filesystem as
+// DIST_DIR (both live under the repo checkout), so rename(2) stays atomic —
+// but this way nothing that walks or copies hooks/ as a whole can ever
+// observe this directory being created/populated/deleted concurrently.
+// tests/gsd-validate-commit-sigpipe.test.cjs's fixture setup does exactly
+// that (fs.cpSync(HOOKS_DIR, ..., {recursive: true})), and when its walk
+// entered a staging dir that a concurrent build-hooks.js run deleted
+// mid-iteration, Node's native recursive-copy (std::filesystem under the
+// hood) threw an uncaught C++ exception and aborted the whole process with
+// SIGABRT — not a catchable JS error. Moving the staging dir out of hooks/
+// closes that race for every current and future hooks/-tree walker, not
+// just that one call site (which also gained its own defensive filter).
+// The parent pattern .dist-staging-*/ (repo root) is gitignored.
+const STAGE_DIR = path.join(REPO_ROOT, `.dist-staging-${process.pid}`);
 
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [

package/scripts/check-contract-drift.cjs

@@ -27,6 +27,10 @@
  *   7. Reverse direction: a workflow/command matching a quoted `## TOKEN`
  *      no agent declares or emits is dispatch-on-phantom
  *      (unmatched_consumer_token) — F9's shape from the consumer side.
+ *   8. Every reference pointer an agent file carries either resolves to
+ *      exactly the regular file it names, contained under
+ *      gsd-core/references/, or is reported (unresolved_reference_include) —
+ *      a pointer the follower declines is never silently dropped (#4930).
  *
  * Exit 0 = clean. Exit 1 = violations (with diagnostics on stderr).
  */
@@ -35,6 +39,9 @@
 
 const fs   = require('fs');
 const path = require('path');
+// The repo's ONE containment decision (ADR-4650, src/security.cts) — realpath-resolved, so an
+// intermediate component referring outside the root is refused before this loop reads the file.
+const { tryWithinRoot } = require('../gsd-core/bin/lib/security.cjs');
 
 function resolveRoot(argv) {
   const idx = argv.indexOf('--root');
@@ -92,8 +99,9 @@ function toRepoRelative(absPath) {
 /**
  * referenceIncludes(content)
  *
- * Plain scan for `@~/.claude/gsd-core/references/*.md` tokens anywhere in an
- * agent file's content -- inside an `<execution_context>` block (already
+ * Plain scan for `@~/.claude/gsd-core/references/*.md` tokens (and the bare
+ * `@gsd-core/references/*.md` spelling, #4841) anywhere in an agent file's
+ * content -- inside an `<execution_context>` block (already
  * covered structurally by `executionContextRefs` in command-contract-helpers,
  * but a raw regex over the whole string picks those up too) and, just as
  * importantly, OUTSIDE one: agents frequently point at a reference doc from
@@ -105,17 +113,94 @@ function toRepoRelative(absPath) {
  * lives in `gsd-core/references/planner-guidance.md`, which the agent only
  * `@`-includes -- so the producer scan below must follow these includes to
  * see markers an agent's contract legitimately delegates to a reference doc.
- * Returns ROOT-relative paths (`gsd-core/references/foo.md`), de-duplicated.
+ * Returns `{ includes, declined }`: `includes` are ROOT-relative paths
+ * (`gsd-core/references/foo.md`), de-duplicated; `declined` are the pointers
+ * this scan refused to follow, as written, each with its reason (#4930).
  */
 function referenceIncludes(content) {
   const seen = new Set();
-  const re = /@~\/\.claude\/gsd-core\/references\/[A-Za-z0-9._-]+\.md/g;
+  const declined = new Map();
+  // Both spellings the agent corpus has carried: the installed-path form the
+  // installer rewrites per profile, and the bare repo-relative `@gsd-core/…`
+  // form (#4841) that it does not. The bare form is now refused in agents/ by
+  // tests/shipped-reference-cites.test.cjs; it is followed here so a pointer
+  // that slips past that gate is still scanned rather than silently dropped.
+  //
+  // THE TOKEN IS CAPTURED WHOLE AND THE NAME GRAMMAR IS ANCHORED AT BOTH ENDS.
+  // Nested names are allowed (`few-shot-examples/verifier.md`); every segment
+  // starts with `[A-Za-z0-9_-]` — narrower than "non-dot", since `+x.md` and
+  // `é.md` do not match either — so a `.` or `..` segment is never a name.
+  // Anchoring is what makes that a statement about the whole pointer rather
+  // than about its first few segments: an earlier form of this pattern ended
+  // at `\.md` with no following boundary, so `…/references/tdd.md/xx/yy` was
+  // followed as `tdd.md`, and THIS FUNCTION'S CALLER READS THE PATH IT
+  // RETURNS — `fs.readFileSync` in main()'s agent loop — so a truncated prefix
+  // folded the wrong file's text into the scanned corpus. Matching the whole
+  // whitespace-delimited token and requiring it to satisfy the grammar end to
+  // end closes that by construction, and for any separator spelling rather
+  // than the ones a boundary lookahead happens to enumerate.
+  //
+  // ANCHORING DOES NOT ESTABLISH CONTAINMENT, and an earlier revision of this
+  // comment said it did. The grammar's refusal of `.`/`..` segments covers the
+  // TEXTUAL half only: an intermediate component that refers outside the tree
+  // is resolved transparently on the way to the file. Containment is decided
+  // separately, below, by `tryWithinRoot` — and it has to be, because this
+  // loop READS what it resolves.
+  //
+  // A token that does not parse WHOLE is declined rather than truncated — the
+  // conservative half of the same rule — and the decline is RETURNED, not
+  // dropped (#4930): main() reports it as unresolved_reference_include. A
+  // skipped pointer is a scan this tool did not perform, and the verdict it
+  // prints depends on that scan, so the skip has to be visible in the tool's
+  // own output. tests/shipped-reference-cites.test.cjs reports the same token
+  // for the shipped agents/ tree; this is the half that holds for any --root.
+  // FOUR spellings. `@$HOME/.claude/` is a second installed-path form the installer rewrites
+  // explicitly (applyAgentPathRewritesInner's `/\$HOME\/\.claude\//g` replace, beside the `~/.claude/`
+  // one). The fourth is a FAMILY rather than a string: `--relative-includes` (#4377) makes a local
+  // install emit project-relative includes whose prefix is DERIVED from the resolved config dir, so it
+  // is matched by SHAPE — one or MORE leading segments before `gsd-core` (a config dir nested under
+  // the project root emits `@config/nested/gsd-core/…`), none of them `.` or `..`. The `+` keeps the
+  // bare form the bare form by construction, since it needs a segment BEFORE `gsd-core`.
+  //
+  // THE SHAPE IS NARROWER THAN THE FAMILY, and saying otherwise would be the overstatement this
+  // function has already had to retract once. `_computePathPrefix` can emit a prefix this character
+  // class does not match — a config dir named `config+nested` or `ümlaut` — and widening the class to
+  // arbitrary directory names is what would turn every `@scope/…` token in prose into a pointer. So a
+  // prefix outside the class is not followed, which is where this follower was for ALL
+  // project-relative spellings before #4841. The gate's own comment states the same bound; the two
+  // must not drift apart, because between them they are the only record of it.
+  const re = /@(?:(?:~|\$HOME)\/\.claude\/|(?:(?!\.\.?\/)[A-Za-z0-9._-]+\/)+)?gsd-core\/references\/(\S+)/g;
+  const name = /^(?:[A-Za-z0-9_-][A-Za-z0-9._-]*\/)*[A-Za-z0-9_-][A-Za-z0-9._-]*\.md$/;
+  // Trailing prose punctuation is not part of a filename — a pointer may end a
+  // sentence or sit inside backticks, parentheses or bold markers. The class
+  // cannot eat into `.md`, which ends at `d`.
+  // START-ANCHORED: this tests a CUT SUFFIX, so it must be punctuation END TO END. An unanchored
+  // `/…$/` answers true for `/xx?`, which would let the loop cut a separator and call the remainder a
+  // name — `tdd.md/xx?` following as `tdd.md`, the defect this whole function was rewritten to close.
+  const trailingProseOnly = /^[.,;:!?)\]}>"'`*]+$/;
   let m;
   while ((m = re.exec(content)) !== null) {
-    const relPath = 'gsd-core/references/' + m[0].slice('@~/.claude/gsd-core/references/'.length);
-    seen.add(relPath);
+    const raw = m[1];
+    // MINIMAL strip, same rule as the gate: shortest trailing run whose removal yields a valid name.
+    let candidate = null;
+    for (let cut = 0; cut <= raw.length; cut++) {
+      const probe = raw.slice(0, raw.length - cut);
+      if (cut > 0 && !trailingProseOnly.test(raw.slice(raw.length - cut))) break;
+      if (name.test(probe)) { candidate = probe; break; }
+    }
+    if (candidate === null) {
+      declined.set(m[0], 'does not name a reference whole — the text continues past the name, so nothing is followed');
+      continue;
+    }
+    // AMBIGUITY, mirrored from the gate. If the UNSTRIPPED token also names something, the strip would
+    // pick one of two readings — and this loop READS what it picks, so it declines rather than guess.
+    if (candidate !== raw && fs.existsSync(path.join(ROOT, 'gsd-core', 'references', raw))) {
+      declined.set(m[0], `is ambiguous — \`${raw}\` itself names something on disk, so stripping it to \`${candidate}\` would pick one of two readings; neither is followed`);
+      continue;
+    }
+    seen.add('gsd-core/references/' + candidate);
   }
-  return [...seen];
+  return { includes: [...seen], declined: [...declined].map(([pointer, reason]) => ({ pointer, reason })) };
 }
 
 function remedyFor(kind) {
@@ -158,6 +243,7 @@ function main() {
   const candidateMarkers = new Map();
   const agentTexts = new Map();
   const unclosedFenceViolations = [];
+  const includeViolations = [];
 
   // #4407: .compact.md variant siblings are an alternate rendering of their
   // canonical agent's SAME contract, not a distinct one — excluded so they
@@ -173,12 +259,41 @@ function main() {
     // Single pass over the agent's @-included references: each file is read
     // once and feeds BOTH the read-tag fold (agentTexts) and marker
     // extraction (producer/candidate attribution).
+    // #4930: every include this loop does NOT fold in is reported, never
+    // swallowed. An unfollowed include is text the marker verdict below was
+    // computed without, so a decline that leaves no trace in the output makes
+    // that verdict unexplainable. (lint-command-contract's @-ref existence rule
+    // covers commands' <execution_context> only, not agents.)
     const includeTexts = [];
-    for (const refRelPath of referenceIncludes(content)) {
+    const reportInclude = (pointer, reason) => includeViolations.push({
+      kind: 'unresolved_reference_include',
+      agent,
+      marker: null,
+      detail: `${toRepoRelative(abs)}: ${pointer} ${reason}`,
+    });
+    const { includes, declined } = referenceIncludes(content);
+    for (const { pointer, reason } of declined) reportInclude(pointer, reason);
+    for (const refRelPath of includes) {
+      // CONTAIN BEFORE READ. The name grammar refuses `.`/`..` segments, which covers the TEXTUAL
+      // half of containment and nothing else: an intermediate path component that refers outside
+      // the tree is resolved transparently on the way to the file, so a textually-clean name can
+      // still address something outside `references/`. This loop READS what it resolves and folds
+      // the text into the scanned corpus, so the real path is what has to be checked.
+      const refsDir = path.join(ROOT, 'gsd-core', 'references');
+      const contained = tryWithinRoot(refRelPath.slice('gsd-core/references/'.length), refsDir);
+      if (contained === null) {
+        reportInclude(refRelPath, 'does not resolve inside gsd-core/references/');
+        continue;
+      }
       try {
-        includeTexts.push(fs.readFileSync(path.join(ROOT, refRelPath), 'utf-8'));
-      } catch {
-        // include miss — lint-command-contract rule 4 owns @-ref existence
+        // Read the ContainedPath the predicate returned, never a re-joined path (ADR-4650).
+        if (!fs.lstatSync(contained).isFile()) {
+          reportInclude(refRelPath, 'is not a regular file');
+          continue;
+        }
+        includeTexts.push(fs.readFileSync(contained, 'utf-8'));
+      } catch (e) {
+        reportInclude(refRelPath, e && e.code === 'ENOENT' ? 'does not exist' : `could not be read (${e && e.code})`);
       }
     }
     agentTexts.set(agent, [content, ...includeTexts].join('\n'));
@@ -237,6 +352,7 @@ function main() {
   const allViolations = [
     ...parseViolations,
     ...unclosedFenceViolations,
+    ...includeViolations,
     ...contractViolationsList,
     ...readTagViolationsList,
     ...reverseViolationsList,