@opengsd/gsd-core 1.13.0 → 1.15.0

package/hooks/dist/gsd-context-monitor.js

@@ -14,6 +14,9 @@
 // Thresholds:
 //   WARNING  (remaining <= 35%): Agent should wrap up current task
 //   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+// Both fire-points are overridable per project via .planning/config.json
+// (hooks.context_warning_threshold / hooks.context_critical_threshold, #4285);
+// the values above are the defaults used when the keys are absent or unusable.
 //
 // Debounce: 5 tool uses between warnings to avoid spam
 // Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
@@ -30,8 +33,8 @@ const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
 // context warning is far cheaper than stalling the agent's work (#3911).
 const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
-const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
-const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35% (default, see resolveThresholds)
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25% (default, see resolveThresholds)
 const STALE_SECONDS = 60;      // ignore metrics older than 60s
 const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
 // How long after a PreCompact readings stay suspect. The watermark records the
@@ -57,6 +60,41 @@ const COMPACT_GRACE_SECONDS = 60;
 // watermark this far ahead pushes first recovery from +61 to +66 (measured).
 const WATERMARK_SKEW_SECONDS = 5;
 
+// Resolve the two fire-points from the project's `.planning/config.json`
+// (#4285). The constants above are the DEFAULTS; a project overrides either one
+// through `hooks.context_warning_threshold` / `hooks.context_critical_threshold`,
+// which is what keeps a tuned fire-point alive across updates — this file is in
+// the MANAGED registry, so an edit to the constants is re-staged away by the
+// next install.
+//
+// TOTAL and never-throwing: this hook must not block the tool call it rides in
+// on, so every unusable input degrades to the default instead of raising.
+// Unusable is decided by Number.isFinite, which is type-strict (the string
+// "30" and true are both rejected, unlike the global isFinite), plus the 0-100
+// domain of the remaining_percentage these are compared against.
+//
+// The PAIR is validated too, and falls back TOGETHER. `critical >= warning` has
+// no coherent reading — critical fires deeper into the window than warning —
+// and honouring one side of an inconsistent pair silently picks which of the
+// operator's two numbers to discard. This also rejects a single override that
+// contradicts the OTHER key's default (warning 20 with critical absent, i.e.
+// 25); the resulting pair is the same nonsense either way. Set-time validation
+// cannot stand in for this check: `config-set` writes one key per call, so
+// tuning both (warning first, then critical) is transiently inconsistent on
+// disk, and refusing it there would block a legitimate configuration.
+function resolveThresholds(hooks) {
+  const defaults = { warning: WARNING_THRESHOLD, critical: CRITICAL_THRESHOLD };
+  if (!hooks || typeof hooks !== 'object') return defaults;
+
+  const usable = (value, fallback) =>
+    (Number.isFinite(value) && value >= 0 && value <= 100) ? value : fallback;
+
+  const warning = usable(hooks.context_warning_threshold, WARNING_THRESHOLD);
+  const critical = usable(hooks.context_critical_threshold, CRITICAL_THRESHOLD);
+
+  return critical < warning ? { warning, critical } : defaults;
+}
+
 // One DEFINITION of what counts as a lifecycle event name, shared by the #3709
 // PreCompact reset and the #2289 output-envelope allowlist. Two call sites, one
 // rule — so the two cannot drift into disagreeing about what "no event name" is.
@@ -164,14 +202,11 @@ function writeSentinel(target, payload) {
 }
 
 let input = '';
-// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
-// Windows/Git Bash, or slow Claude Code piping during large outputs),
-// exit silently instead of hanging until Claude Code kills the process
-// and reports "hook error". See #775, #1162.
-const stdinTimeout = setTimeout(() => allow(undefined), 10000);
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
+// Assigned by main(); the handler below clears it. Declared out here rather
+// than inside main() because the handler closes over it.
+let stdinTimeout = null;
+
+const handleStdinEnd = () => {
   clearTimeout(stdinTimeout);
   try {
     const data = JSON.parse(input);
@@ -266,18 +301,26 @@ process.stdin.on('end', () => {
       allow(undefined);
     }
 
-    // Check if context warnings are disabled via config.
+    // Check if context warnings are disabled via config, and resolve the two
+    // fire-points from the same read (#4285 — one config read, not two).
     // Collapsed existsSync+readFileSync into a single read guarded by try/catch
     // (ENOENT or parse error → use defaults, same as old "planningDir absent" branch).
     const cwd = data.cwd || process.cwd();
+    let thresholds = { warning: WARNING_THRESHOLD, critical: CRITICAL_THRESHOLD };
     try {
       const configPath = path.join(cwd, '.planning', 'config.json');
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       if (config.hooks?.context_warnings === false) {
         allow(undefined);
       }
+      // After the disable check, not before: a disabled monitor exits above and
+      // never reaches a threshold, so resolving first would only add work to the
+      // path that does nothing. allow() exits the process (it does not throw),
+      // so this line is unreachable when warnings are off.
+      thresholds = resolveThresholds(config.hooks);
     } catch (e) {
-      // Missing or unparseable config → proceed with defaults (context warnings enabled)
+      // Missing or unparseable config → proceed with defaults (context warnings
+      // enabled, thresholds at the constants above, which `thresholds` already holds)
     }
 
     // If no metrics file, this is a subagent or fresh session -- exit silently.
@@ -352,7 +395,7 @@ process.stdin.on('end', () => {
     const usedPct = metrics.used_pct;
 
     // No warning needed
-    if (remaining > WARNING_THRESHOLD) {
+    if (remaining > thresholds.warning) {
       allow(undefined);
     }
 
@@ -389,7 +432,7 @@ process.stdin.on('end', () => {
 
     warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
 
-    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const isCritical = remaining <= thresholds.critical;
     const currentLevel = isCritical ? 'critical' : 'warning';
 
     // Emit immediately on first warning, then debounce subsequent ones
@@ -491,4 +534,34 @@ process.stdin.on('end', () => {
     // exit(0) fail-open behavior exactly (#3911).
     crash(ON_CRASH, undefined);
   }
-});
+};
+
+// The stdin adapter is the only side-effecting statement in this file, so it is
+// the only thing that must not run on `require()`. Gating it lets a test import
+// `resolveThresholds` and drive it directly — the repo's own conclusion for a
+// seam like this (CONTEXT-INDEX, on the ROADMAP Requirements parser: a closure
+// reachable only by spawning the CLI is one "no fast-check property can do").
+// A spawn-per-case property test is not the same test: it would exercise the
+// resolver at whatever pairs survive to an observable severity, not over its
+// whole numeric domain.
+/* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
+function main() {
+  // Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+  // Windows/Git Bash, or slow Claude Code piping during large outputs),
+  // exit silently instead of hanging until Claude Code kills the process
+  // and reports "hook error". See #775, #1162.
+  stdinTimeout = setTimeout(() => allow(undefined), 10000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => input += chunk);
+  process.stdin.on('end', handleStdinEnd);
+}
+
+if (require.main === module) {
+  main();
+}
+
+// Exported for the #4285 property test only. The two constants ride along so a
+// test asserts the fallback pair against the SOURCE of truth rather than
+// re-hardcoding 35/25 — a test carrying its own copy of the defaults would stay
+// green if the constants were edited.
+module.exports = { resolveThresholds, WARNING_THRESHOLD, CRITICAL_THRESHOLD };

package/hooks/dist/gsd-cursor-subagent-start.js

@@ -62,8 +62,8 @@ const { allow } = require('./lib/hook-exit.js');
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
 // writeCursorHooksJson so the require always resolves post-install.
 const { resolveStatePath } = require('./lib/cursor-workspace.js');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
-const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 // #3582: gsd-core/bin/lib/*.cjs (runtime-homes.cjs, worktree-safety.cjs,
 // runtime-name-policy.cjs, capability-registry.cjs — required below, inside
 // resolveIsolationEvidence and resolveFallbackIsolation) are tsc build
@@ -491,18 +491,25 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `Refusing to allow this subagent to spawn until the runtime library is built — a guard ` +
         `that cannot verify must not answer "safe" (#3050).`,
       reasonCode: REASON_CODE.RUNTIME_BUILD_FAILED,
+      sentinelDiscarded: null,
     };
   }
 
+  // #3045 BLOCKER fix: a fresh sentinel is authoritative for THIS dispatch's
+  // actual resolved isolation — see the doc comment above.
+  // #3045 SECURITY F2: a fresh sentinel that names a DIFFERENT plan/phase
+  // than this dispatch is not applicable to it — fall through to the
+  // conservative fallback exactly as a stale sentinel would.
+  // Hoisted (readSentinel never throws) so the "present, fresh, but did not
+  // apply" case (#4594 row 15) can be reported on every deny path below
+  // instead of silently discarded.
+  const sentinel = readSentinel(root, { clock });
+  const applies = sentinelAppliesToDispatch(sentinel, dispatchIds);
+  const sentinelDiscarded = buildSentinelDiscard(sentinel, dispatchIds);
+
   let declaredIsolation;
   try {
-    // #3045 BLOCKER fix: a fresh sentinel is authoritative for THIS
-    // dispatch's actual resolved isolation — see the doc comment above.
-    // #3045 SECURITY F2: a fresh sentinel that names a DIFFERENT
-    // plan/phase than this dispatch is not applicable to it — fall through
-    // to the conservative fallback exactly as a stale sentinel would.
-    const sentinel = readSentinel(root, { clock });
-    declaredIsolation = (sentinel.present && !sentinel.stale && sentinelAppliesToDispatch(sentinel, dispatchIds))
+    declaredIsolation = (sentinel.present && !sentinel.stale && applies)
       ? sentinel.isolation
       : resolveFallbackIsolation(root, configPath);
   } catch {
@@ -513,8 +520,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `dispatch-isolation configuration ('.planning/config.json' exists under "${root}"). ` +
         `Refusing to allow this subagent to spawn 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.`,
+        `Retry once the project configuration is readable.` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.CONFIG_UNREADABLE,
+      sentinelDiscarded,
     };
   }
 
@@ -530,8 +539,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `GSD subagent isolation guard: this project's dispatch isolation resolves to ` +
         `"harness-worktree", but the subagentStart payload for this dispatch carries no usable ` +
         `subagent_type. Refusing to allow it to spawn without being able to confirm whether it ` +
-        `is a GSD executor — a guard that cannot verify must not answer "safe" (#3050).`,
+        `is a GSD executor — a guard that cannot verify must not answer "safe" (#3050).` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.NO_SUBAGENT_TYPE,
+      sentinelDiscarded,
     };
   }
 
@@ -547,8 +558,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `"harness-worktree", but whether "${root}" is running in an isolated Cursor worktree ` +
         `could not be determined (git did not respond). Refusing to allow subagent_type=` +
         `"${subagentType}" to spawn without being able to verify isolation — a guard that ` +
-        `cannot verify must not answer "safe" (#3050). Retry once git is responsive.`,
+        `cannot verify must not answer "safe" (#3050). Retry once git is responsive.` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.CANNOT_DETERMINE_ISOLATION,
+      sentinelDiscarded,
     };
   }
 
@@ -560,8 +573,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
       `which is not an isolated Cursor worktree — it would edit the user's primary checkout ` +
       `directly, with no consent and no warning. Start an isolated session first (the ` +
       `"--worktree" CLI flag or the "/worktree" chat command; Cursor manages these worktrees ` +
-      `under "~/.cursor/worktrees/") and retry.`,
+      `under "~/.cursor/worktrees/") and retry.` +
+      (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
     reasonCode: REASON_CODE.NOT_ISOLATED_WORKTREE,
+    sentinelDiscarded,
   };
 }
 
@@ -611,7 +626,12 @@ function main() {
         decision = { action: 'allow' };
       }
       if (decision.action === 'deny') {
-        const out = { permission: 'deny', user_message: decision.reason, reason_code: decision.reasonCode };
+        const out = {
+          permission: 'deny',
+          user_message: decision.reason,
+          reason_code: decision.reasonCode,
+          sentinel_discarded: decision.sentinelDiscarded ?? null,
+        };
         if (additionalContext !== null) out.additional_context = additionalContext;
         process.stdout.write(JSON.stringify(out));
         return;

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

@@ -26,12 +26,24 @@
 //   .env, .secrets, and .env.<suffix> — EXCEPT .env.example / .env.sample /
 //   .env.template / .env.dist, which are the non-secret templates GSD's own
 //   phase prompt tells executors to read.
-//   Stated cost: this is narrower than the retired `Read(.env.*)` rule — a
-//   real secret stored in `.env.example` is not protected.
+//   Stated cost (#4580): the exemption matches the token's FINAL EXTENSION,
+//   not the whole name, so the trusted set is `.env.<anything>.example` /
+//   `.sample` / `.template` / `.dist` — an unbounded family, not four fixed
+//   names. A real secret named `.env.prod-real-secrets.example` is NOT
+//   protected, and renaming any secret to end in one of those four
+//   extensions bypasses the guard across Read, Grep and Bash alike. This is
+//   the deliberate cost of #4580, which fixed the prior whole-name
+//   comparison wrongly refusing committed, secret-free templates like
+//   `.env.local.example`.
 //   A token containing `:` is also tested on the part after its LAST `:`,
 //   so `git show HEAD:.env`, `origin/main:config/.env` and `C:\proj\.env`
-//   are caught without git-specific parsing. No whitespace trimming: the
-//   commit message `fix: .env parsing` yields ` .env parsing`, not a name.
+//   are caught without git-specific parsing. Leading/interior whitespace is
+//   still NOT trimmed: the commit message `fix: .env parsing` yields
+//   ` .env parsing`, which is prose, not a name. TRAILING dots and spaces ARE
+//   stripped from the basename before classification (`.env.`, `.env..`,
+//   `.env `, `.env. ` all normalize to `.env`), because Win32 strips trailing
+//   dots and spaces from each path component, so these are aliases for the
+//   same on-disk file, not distinct names.
 //
 // Bash analysis is a two-pass token scan, not a shell:
 //   pass 1 tokenizes with quote state, comments, redirect operators (with fd
@@ -74,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 |
@@ -86,6 +103,7 @@
 'use strict';
 
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+const { finalExtension, normalizeWindowsBasename, lastSegment } = require('./lib/filename-classification.js');
 
 // Fail open on a hook-internal error (see header). Declared ONCE so the
 // outer catch states its policy explicitly (#3911).
@@ -114,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
@@ -148,21 +175,18 @@ const GLOB_PROBES = [
 // ---------------------------------------------------------------------------
 
 function isSecretBasename(name) {
-  if (name === '.env' || name === '.secrets') return true;
-  if (name.startsWith('.env.')) {
-    const suffix = name.slice('.env.'.length);
-    return suffix !== '' && !NON_SECRET_ENV_SUFFIXES.has(suffix.toLowerCase());
+  // Win32 strips trailing dots/spaces per path component, so `.env.`,
+  // `.env ` etc. resolve to the real `.env` on Windows — normalize FIRST so
+  // those aliases can't bypass classification.
+  const n = normalizeWindowsBasename(name);
+  if (n === '.env' || n === '.secrets') return true;
+  if (n.startsWith('.env.')) {
+    const suffix = n.slice('.env.'.length);
+    return suffix !== '' && !NON_SECRET_ENV_SUFFIXES.has(finalExtension(suffix).toLowerCase());
   }
   return false;
 }
 
-// Last `/`- or `\`-separated segment, ignoring trailing separators.
-function lastSegment(tok) {
-  const s = tok.replace(/[\\/]+$/, '');
-  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
-  return i === -1 ? s : s.slice(i + 1);
-}
-
 // True when the token's basename — or the basename of the part after its
 // last `:` (git `<ref>:<path>`, Windows drive) — is a secret name. Folded to
 // lower case once at the top so `.ENV` / `.Secrets` match on the
@@ -247,7 +271,19 @@ function globAltSelectsSecret(alt) {
   if (/^[*?]+$/.test(alt)) return false; // pure wildcard: equivalent to no glob
   const wild = alt.search(/[*?[]/);
   const lit = wild === -1 ? alt : alt.slice(0, wild);
-  if (lit.startsWith('.env.')) return true;
+  // #4580: when there is no wildcard, `alt` (== `lit`) is a WHOLE literal
+  // filename, so classify it exactly the same way Read/Bash do (by its
+  // FINAL extension, via isSecretBasename) rather than by a `.env.`-prefix
+  // heuristic — that heuristic mis-blocked multi-dot templates like
+  // `.env.local.example`. When a wildcard IS present, `lit` is only a
+  // PARTIAL literal prefix (`.env.local.exam*` can still select
+  // `.env.local`), which cannot be classified exactly, so the original
+  // conservative prefix rule stays.
+  if (wild === -1) {
+    if (isSecretBasename(lit)) return true;
+  } else if (lit.startsWith('.env.')) {
+    return true;
+  }
   if (lit !== '' && ('.env.'.startsWith(lit) || '.secrets'.startsWith(lit))) return true;
   let re;
   try {
@@ -260,10 +296,14 @@ function globAltSelectsSecret(alt) {
 
 // Returns null (allowed), 'secret-read', or 'glob-too-complex'.
 function classifyGrepGlob(glob) {
-  const segIdx = glob.replace(/\/+$/, '').lastIndexOf('/');
+  // Segment via the SAME `lastSegment` helper Read/Bash use (namesSecret),
+  // rather than a hand-rolled forward-slash-only split — the two used to
+  // diverge on a backslash-bearing glob (`config\.env`), which `lastSegment`
+  // reduces to `.env` but a `/`-only split left untouched, letting it escape
+  // this arm's predicate while Read/Bash still blocked it.
   // Case-fold the last segment (GLOB_PROBES are lower case) so `.ENV*` and
   // `*.ENV` select the secret namespace on case-insensitive filesystems.
-  const segment = (segIdx === -1 ? glob : glob.slice(segIdx + 1)).toLowerCase();
+  const segment = lastSegment(glob).toLowerCase();
   const alts = expandBraces(segment);
   if (alts === null) return 'glob-too-complex';
   return alts.some(globAltSelectsSecret) ? 'secret-read' : null;
@@ -814,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/dist/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);
     }
   }
@@ -449,13 +471,17 @@ function contextTokenSuffix(currentUsage) {
 // --- Compact state format (opt-in) ---------------------------------------------
 
 /**
- * Collapse GSD's free-text status (often a multi-sentence narrative) to a
- * single keyword, built on the canonical normalizer (#2162 approval
- * condition): normalizeStateStatus() in state-document.cjs owns the status
- * vocabulary (discussing / planning / executing / verifying / completed /
- * paused) so the two can't drift. "paused" — the canonical stuck state — is
- * uppercased to PAUSED, the one state worth shouting about. Statuses the
- * normalizer passes through unrecognized fall back to their first word,
+ * Collapse GSD's status value to a single keyword, built on the canonical
+ * normalizer (#2162 approval condition): normalizeStateStatus() in
+ * state-document.cjs owns the status vocabulary (discussing / planning /
+ * executing / verifying / completed / paused) so the two can't drift.
+ * #4186: the normalizer recognizes the DECLARED vocabulary by anchored
+ * whole-field match — vocabulary values (the state writer persists tokens)
+ * collapse to their keyword; free-text narratives are no longer
+ * keyword-guessed from substrings (a `.planning/` mention in non-English
+ * prose used to render `planning`), and pass through unrecognized to the
+ * first-word fallback below. "paused" — the canonical stuck state — is
+ * uppercased to PAUSED, the one state worth shouting about. The fallback is
  * capped at 16 chars so a rogue STATE.md can't blow up the line.
  * Returns null for empty input.
  */
@@ -486,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
@@ -743,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;
@@ -755,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 ------------------------------------------------------------------
@@ -930,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
@@ -1038,6 +1088,7 @@ module.exports = {
   STATE_HEAD_ADVISORY_COMMITS, isValidStateHeadStamp,
   readStateHeadCommits, parseRevListCounts, deriveStateFreshness,
   formatStateFreshness, resolveStatuslineOptions,
+  renderBracketPhaseDisplay, renderBracketMilestoneDisplay,
 };
 
 /**
@@ -1055,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);
@@ -1071,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 });
 }