@opengsd/gsd-core 1.9.1 → 1.10.0

package/gsd-core/bin/gsd-tools.cjs

@@ -264,6 +264,9 @@ const { resolveActiveWorkstream, applyResolvedWorkstreamEnv } = require('./lib/a
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
+// #3024: resolve skills root for the sync-skills workflow (install.js is not
+// shipped in installed trees; gsd-tools IS shipped, so the workflow calls this).
+const { getGlobalSkillsBase, isRegisteredRuntimeId } = require('./lib/runtime-homes.cjs');
 // #1561 — assumption-delta advisory checkpoint detector (pure function).
 const { detectAssumptionDelta } = require('./lib/assumption-delta.cjs');
 const verify = require('./lib/verify.cjs');
@@ -1044,6 +1047,37 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           commands.cmdCurrentTimestamp(args[1] || 'full', raw);
   }
 
+  function routeSkillsRoot({ args, raw, error }) {
+    // #3024: resolve the global skills base directory for a runtime.
+    // The sync-skills workflow previously shelled out to install.js --skills-root,
+    // but install.js is not shipped in installed trees. gsd-tools IS shipped, so
+    // the workflow now calls `gsd-tools query skills-root <runtime>` instead.
+    const runtime = args[1];
+    if (!runtime) {
+      error('Usage: gsd-tools query skills-root <runtime>');
+    }
+    // Defect B (#3024): validate the runtime id against the shipped capability
+    // registry's canonical runtime set BEFORE resolving anything.
+    // getGlobalSkillsBase falls through getGlobalConfigDir's unknown-runtime
+    // branch to claude's skills root for ANY id it doesn't recognize, so an
+    // unknown, empty/whitespace-only, path-traversal, or shell-metacharacter
+    // runtime arg would otherwise silently resolve to claude's path instead of
+    // failing loudly. isRegisteredRuntimeId does an own-property lookup (not a
+    // bare index), rejecting `__proto__`/`constructor`/`prototype` runtime
+    // ids, and is the SAME validator install.js's `--skills-root` entry point
+    // calls, so the two shipped entry points can never diverge on which
+    // runtime ids they accept.
+    if (!isRegisteredRuntimeId(runtime)) {
+      error(`Unknown runtime "${runtime}" — must be a registered runtime id`);
+    }
+    const trimmedRuntime = typeof runtime === 'string' ? runtime.trim() : '';
+    const skillsRoot = getGlobalSkillsBase(trimmedRuntime);
+    if (skillsRoot === null) {
+      error(`No skills root found for runtime "${trimmedRuntime}"`);
+    }
+    output({ skills_root: skillsRoot }, raw, skillsRoot);
+  }
+
   function routeProjectInstructionFile({ args, cwd, raw, error }) {
     // #1529: pure runtime→filename projection. Backs the
           // `gsd_run query project-instruction-file --runtime <r>` call in
@@ -1145,16 +1179,33 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     const cp = require('node:child_process');
     const fsx = require('node:fs');
     const os = require('node:os');
-    const { REVIEWER_LANES } = require('./lib/review-lane-descriptor.cjs');
+    const { REVIEWER_LANES, mergeReviewerLanes } = require('./lib/review-lane-descriptor.cjs');
     const { resolveLanePlan } = require('./lib/review-lane-invocation.cjs');
     const runner = require('./lib/review-lane-runner.cjs');
     const cfgLoader = require('./lib/config-loader.cjs');
+    const capabilityLoader = require('./lib/capability-loader.cjs');
 
     const flag = (name) => {
       const i = args.indexOf(name);
       return i !== -1 && args[i + 1] && !String(args[i + 1]).startsWith('--') ? args[i + 1] : null;
     };
     const sub = args[1];
+    // Fail fast on an unrecognized subcommand. Without this check, `sub` fell through
+    // to the `sub !== 'invoke'` usage-error branch far below (after loading the
+    // capability registry AND building a per-lane plan for every lane — which itself
+    // spawns one child `query resolve-execution` process per lane via `effortFor`,
+    // up to 12 subprocess spawns for the default lane set) before ever reporting the
+    // error. That made an invalid subcommand slow instead of instant, and under bench
+    // load (many sequential node spawns) `review-lane bogus` could exceed a caller's
+    // spawn timeout and be killed before writing anything to stderr — the CI-observed
+    // failure was empty stdout AND stderr, not the expected usage message (#3148).
+    // `plan`/`invoke` are the only subs that need the expensive plan-building path
+    // below; `sections`/`flags` return earlier still. Anything else errors here, before
+    // any of that work starts.
+    if (!['plan', 'invoke', 'sections', 'flags'].includes(sub)) {
+      error("Usage: review-lane <plan|invoke|sections|flags> [--selected a,b] [--run-dir D] [--repo-root R]");
+      return;
+    }
     const runDir = flag('--run-dir') || '.';
     const repoRoot = flag('--repo-root') || cwd;
 
@@ -1176,8 +1227,30 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
 
     const selected = (flag('--selected') || '')
       .split(',').map((s) => s.trim()).filter(Boolean);
-    const laneBySlug = new Map(REVIEWER_LANES.map((l) => [l.slug, l]));
-    const chosen = selected.length ? selected : REVIEWER_LANES.map((l) => l.slug);
+    // ADR-2782 D8 (#2927): the lane map is first-party ∪ INSTALLED overlay
+    // `reviewer` bodies, first-party winning on slug collision. Before this merge
+    // the map was built from the frozen REVIEWER_LANES array alone, so an installed,
+    // consented third-party reviewer lane was roster-visible (deriveReviewerSlugs)
+    // and disclosed at install (collectReviewerLaneSurfaces) but never selectable,
+    // plannable, or invocable — `sections`/`flags`/`plan`/`invoke` all consumed this
+    // one map. The overlay body is field-identical to a ReviewerLane (ADR-2782 D1,
+    // "no translation layer"), so `mergeReviewerLanes` is a pure merge, not a
+    // projection. loadRegistry is TOTAL and never throws on a malformed overlay
+    // (it skips the cap with a warning), and mergeReviewerLanes is total in turn,
+    // so a bad third-party manifest cannot take the first-party lanes down with it.
+    // `includeInstalled` is what merges project + global overlay caps into the
+    // registry; without it the base is first-party-only and this is a no-op.
+    let mergedLanes = REVIEWER_LANES;
+    try {
+      const registry = capabilityLoader.loadRegistry({ includeInstalled: true, cwd });
+      mergedLanes = mergeReviewerLanes(REVIEWER_LANES, registry);
+    } catch {
+      // A registry load failure must never block first-party review. Degrade to the
+      // static set — identical to pre-fix behavior — rather than crashing review-lane.
+      mergedLanes = REVIEWER_LANES;
+    }
+    const laneBySlug = new Map(mergedLanes.map((l) => [l.slug, l]));
+    const chosen = selected.length ? selected : mergedLanes.map((l) => l.slug);
 
     if (sub === 'sections') {
       const rows = chosen
@@ -1307,7 +1380,16 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     // cannot be interrupted by --test-force-exit and hangs a whole CI chunk to its 10-minute kill.
     const deps = {
       spawn: (binary, argv, opts) => {
-        const r = cp.spawnSync(binary, argv, {
+        // #3086: on Windows, reviewer CLIs (gemini, codex, etc.) are installed
+        // as .cmd shims. spawnSync with a bare name + shell:false fails with
+        // ENOENT (CreateProcess cannot start .cmd). Apply the same #2667 shim
+        // gate used in runWithTimeout: detect .cmd/.bat and mediate through
+        // cmd.exe /d /s /c with an explicit argv array (no shell:true).
+        const isWin = process.platform === 'win32';
+        const winShim = isWin && /\.(cmd|bat)$/i.test(path.basename(binary));
+        const spawnBinary = winShim ? (process.env.ComSpec || 'cmd.exe') : binary;
+        const spawnArgv = winShim ? ['/d', '/s', '/c', binary, ...argv] : argv;
+        const r = cp.spawnSync(spawnBinary, spawnArgv, {
           input: opts.input,
           encoding: 'utf8',
           timeout: opts.timeoutMs,
@@ -1564,6 +1646,24 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     // `orchestrator-worktree`. It requires `--cwd-target` (the GSD-created
     // worktree path) and optionally `--prompt`; without a target there is
     // nothing to bind, so `exec` is null.
+    //
+    // #3045 CORE REDESIGN: this is now the SOLE resolver of "what isolation
+    // applies to this dispatch", and — as an unconditional side effect — it
+    // PERSISTS that resolved decision (mode + harnessFlag + phase/plan
+    // identifiers, written together in one atomic write) to the sentinel the
+    // guard hooks read. Previously the sentinel was written by prose-gated
+    // shell blocks in `executor-isolation-dispatch.md` that a model was told
+    // to "read and run" — a prose-gated writer for a guard against
+    // prose-gated values is the same defect class the guard exists to close.
+    // The workflow MUST call this query to learn ISOLATION at all, so
+    // recording here is structurally unskippable. `--phase`/`--plan` are
+    // optional identifiers threaded through from the caller (workflow shell
+    // variables); `--force-isolation <mode>` lets a caller that has
+    // additional context this resolver cannot see (the #2474 per-plan
+    // submodule intersection, computed in shell in
+    // `per-plan-worktree-gate.md`) override the naturally-resolved mode
+    // while still going through this single write path. Best-effort: a
+    // sentinel write failure here must never fail the wave.
     const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'none']);
     let isolation = 'none';
     let runtimeId = null;
@@ -1622,6 +1722,40 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       harnessFlag = null;
     }
 
+    // `--force-isolation <mode>` overrides the naturally-resolved mode with
+    // context this resolver has no way to see on its own (e.g. the #2474
+    // per-plan submodule intersection). Invalid/unrecognized values are
+    // ignored rather than erroring — this is a best-effort recording call,
+    // not a hard usage gate. Forcing to 'none' clears harnessFlag/exec since
+    // neither applies to sequential dispatch.
+    const forceIdx = args.indexOf('--force-isolation');
+    const forcedIsolation = forceIdx !== -1 ? args[forceIdx + 1] : undefined;
+    if (forcedIsolation && VALID_ISOLATION.has(forcedIsolation)) {
+      isolation = forcedIsolation;
+      if (isolation === 'none') {
+        harnessFlag = null;
+        exec = null;
+      }
+    }
+
+    const phaseIdx = args.indexOf('--phase');
+    const phaseArg = phaseIdx !== -1 && args[phaseIdx + 1] && !args[phaseIdx + 1].startsWith('--')
+      ? args[phaseIdx + 1]
+      : null;
+    const planIdx = args.indexOf('--plan');
+    const planArg = planIdx !== -1 && args[planIdx + 1] && !args[planIdx + 1].startsWith('--')
+      ? args[planIdx + 1]
+      : null;
+
+    // Side-effect write (#3045 CORE REDESIGN) — see the doc comment above.
+    // Never allowed to affect this query's own stdout contract or throw.
+    try {
+      writeDispatchIsolationSentinel(cwd, { isolation, harnessFlag, phase: phaseArg, plan: planArg });
+    } catch {
+      // writeDispatchIsolationSentinel already swallows its own errors into
+      // a { recorded: false } result; this catch is defense in depth only.
+    }
+
     if (args.indexOf('--json') !== -1) {
       output({ runtime: runtimeId, isolation, exec, harnessFlag }, raw);
     } else {
@@ -1629,6 +1763,110 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     }
   }
 
+  /**
+   * Atomically persist the resolved dispatch-isolation decision to the
+   * run-scoped sentinel both isolation guard hooks read
+   * (hooks/gsd-agent-isolation-guard.js, hooks/gsd-cursor-subagent-start.js;
+   * shared reader hooks/lib/isolation-sentinel.js). Extracted so
+   * `routeDispatchIsolation` (the #3045 CORE REDESIGN primary write path)
+   * and `routeRecordDispatchIsolation` (the explicit verb, kept for the
+   * per-plan degrade call site and back-compat/tests) share exactly one
+   * write implementation. Never throws — returns `{ recorded, path, error? }`.
+   */
+  function writeDispatchIsolationSentinel(cwd, { isolation, harnessFlag = null, phase = null, plan = null }) {
+    const nodePath = require('path');
+    const nodeFs = require('fs');
+    const sentinelDir = nodePath.join(cwd, '.gsd');
+    const sentinelPath = nodePath.join(sentinelDir, 'dispatch-isolation-sentinel.json');
+    const payload = {
+      isolation,
+      harness_flag: harnessFlag || null,
+      phase: phase || null,
+      plan: plan || null,
+      written_at: Date.now(),
+    };
+    try {
+      nodeFs.mkdirSync(sentinelDir, { recursive: true });
+      // Atomic write: unique temp file + rename, so a concurrent reader (a
+      // guard hook firing mid-write) never observes a partially-written
+      // sentinel. Unique per-process+time so concurrent orchestrator-worktree
+      // invocations sharing the same sentinelDir never collide on the temp name.
+      const tmpPath = `${sentinelPath}.tmp-${process.pid}-${Date.now()}`;
+      nodeFs.writeFileSync(tmpPath, JSON.stringify(payload));
+      nodeFs.renameSync(tmpPath, sentinelPath);
+      return { recorded: true, path: '.gsd/dispatch-isolation-sentinel.json' };
+    } catch (err) {
+      return { recorded: false, path: '.gsd/dispatch-isolation-sentinel.json', error: err && err.message };
+    }
+  }
+
+  function routeRecordDispatchIsolation({ args, cwd, raw, error }) {
+    // #3045: `routeDispatchIsolation` (the `dispatch-isolation` query) is now
+    // the PRIMARY write path for the sentinel (CORE REDESIGN) — it records
+    // as an unconditional side effect of resolving ISOLATION, which the
+    // workflow must call to learn the value at all. This verb remains as an
+    // explicit fallback for callers that resolve isolation through some
+    // other means (or need to force a specific value, e.g. a caller with no
+    // access to `--force-isolation` context) and for direct test coverage of
+    // the write primitive. Both verbs share exactly one write implementation
+    // (`writeDispatchIsolationSentinel`) so there is only one atomic-write
+    // code path to reason about.
+    //
+    // Best-effort: a write failure here must never fail the workflow — the
+    // guard hooks' own sentinel-absent path degrades to a conservative
+    // registry+config check, so a missing sentinel is safe, just less precise.
+    //
+    // Output: { recorded: true|false, path, error? }
+    const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'none']);
+    const isoIdx = args.indexOf('--isolation');
+    const isolation = isoIdx !== -1 ? args[isoIdx + 1] : undefined;
+    if (!isolation || !VALID_ISOLATION.has(isolation)) {
+      error(
+        'Usage: record-dispatch-isolation --isolation <harness-worktree|orchestrator-worktree|none> ' +
+        '[--harness-flag <flag>|--harness-flag=<flag>] [--phase <n>] [--plan <id>]',
+        ERROR_REASON.USAGE,
+      );
+      return;
+    }
+    // #3045 MAJOR: the space-separated form rejects any value starting with
+    // `--` (to avoid swallowing a missing value followed by another flag),
+    // but that is exactly the shape of Cursor's real `harnessIsolationFlag`
+    // — it declares the bare CLI flag `--worktree`
+    // (gsd-core/bin/lib/capability-registry.cjs), which could therefore
+    // never be persisted. (Windsurf declares NO `harnessIsolationFlag` at
+    // all — its `hostIntegration.dispatch.isolation` is `none`; per
+    // ADR-1239 it "genuinely cannot benefit" from worktree isolation
+    // because it lacks named/concurrent subagent dispatch, so this is not a
+    // gap to close for Windsurf.) The `--harness-flag=<value>` equals form
+    // (mirrors the `--cwd=<path>` convention already used by this
+    // dispatcher's top-level arg parsing above) carries the value
+    // unambiguously and is never subject to that guard — any future runtime
+    // whose registered flag happens to be bare-CLI-shaped benefits the same
+    // way Cursor's does.
+    let harnessFlag = null;
+    const flagEqArg = args.find((a) => a.startsWith('--harness-flag='));
+    if (flagEqArg) {
+      const value = flagEqArg.slice('--harness-flag='.length);
+      harnessFlag = value.length > 0 ? value : null;
+    } else {
+      const flagIdx = args.indexOf('--harness-flag');
+      harnessFlag = flagIdx !== -1 && args[flagIdx + 1] && !args[flagIdx + 1].startsWith('--')
+        ? args[flagIdx + 1]
+        : null;
+    }
+    const phaseIdx = args.indexOf('--phase');
+    const phase = phaseIdx !== -1 && args[phaseIdx + 1] && !args[phaseIdx + 1].startsWith('--')
+      ? args[phaseIdx + 1]
+      : null;
+    const planIdx = args.indexOf('--plan');
+    const plan = planIdx !== -1 && args[planIdx + 1] && !args[planIdx + 1].startsWith('--')
+      ? args[planIdx + 1]
+      : null;
+
+    const result = writeDispatchIsolationSentinel(cwd, { isolation, harnessFlag, phase, plan });
+    output(result, raw);
+  }
+
   function routeResolveDispatchType({ args, cwd, raw, error }) {
     // #2508 Phase 4 Option A: resolve a requested GSD subagent name to the
            // type an Agent() call should use on the current runtime. On
@@ -2033,6 +2271,86 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           teamsStatus.cmdTeamsStatus(cwd, { active: args.includes('--active') });
   }
 
+  // #3023 follow-up (adversarial review finding): the shared hook bundle's
+  // directory name is runtime-descriptor-driven (bin/install.js
+  // `hostBehaviors.sharedHooksDirName`; default 'hooks', pi renames it to
+  // 'gsd-hooks'). A hardcoded 'hooks' literal in GSD_PREFIX_MANAGED_DIRS left
+  // this scan blind to a renamed bundle: `fs.existsSync(configDir/hooks)` is
+  // false for a pi install, so the ENTIRE gsd-hooks/ tree — including any
+  // user-added file inside it — was invisible to detect-custom-files and
+  // therefore never backed up before the next clean-install wipe (silent
+  // data loss).
+  //
+  // Resolution order, mirroring bin/install.js's own resolveSharedHooksDirName:
+  //   1. Read the per-install runtime marker written by the installer at
+  //      <configDir>/gsd-core/.gsd-runtime (#2297).
+  //   2. Look up that runtime's `hostBehaviors.sharedHooksDirName` in the
+  //      SHIPPED capability registry (./lib/capability-registry.cjs — a data
+  //      module in the same installed tree as this file). Deliberately NOT
+  //      `require('bin/install.js')`: that file is never shipped into an
+  //      installed tree (the #3024/#2071 bug class), so only the shipped data
+  //      module is read here.
+  //
+  // Asymmetric fallback: when the runtime or its descriptor cannot be
+  // determined (an install predating the marker, an unreadable/corrupt
+  // registry, or an unrecognized runtime id) this does NOT guess a single
+  // name — it returns every known candidate name instead. Over-scanning is
+  // safe here: a candidate directory that does not exist is silently skipped
+  // by the caller's `fs.existsSync` guard, and a file already tracked in the
+  // manifest is never reported as custom. Under-scanning is the actual bug
+  // being fixed: it would make a user's file vanish on the next wipe without
+  // ever being backed up.
+  function resolveSharedHooksDirCandidates(configDir) {
+    const DEFAULT_NAME = 'hooks';
+    // A resolved name is joined onto configDir and read back — reject
+    // anything that isn't a plain, separator-free segment so a corrupt
+    // registry value can never walk the scan outside the config root.
+    const isSafeSegment = (name) =>
+      typeof name === 'string' &&
+      name.trim() !== '' &&
+      name.trim() === name &&
+      name !== '.' &&
+      name !== '..' &&
+      !name.includes('/') &&
+      !name.includes('\\');
+
+    let registry = null;
+    try {
+      registry = require('./lib/capability-registry.cjs');
+    } catch {
+      registry = null;
+    }
+
+    const knownNames = new Set([DEFAULT_NAME]);
+    if (registry && registry.runtimes && typeof registry.runtimes === 'object') {
+      for (const desc of Object.values(registry.runtimes)) {
+        const name = desc && desc.runtime && desc.runtime.hostBehaviors &&
+          desc.runtime.hostBehaviors.sharedHooksDirName;
+        if (isSafeSegment(name)) knownNames.add(name);
+      }
+    }
+
+    let runtimeId = null;
+    try {
+      const markerPath = path.join(configDir, 'gsd-core', '.gsd-runtime');
+      const raw = fs.readFileSync(markerPath, 'utf8').trim();
+      runtimeId = raw || null;
+    } catch {
+      runtimeId = null;
+    }
+
+    if (runtimeId && registry && registry.runtimes && registry.runtimes[runtimeId]) {
+      const desc = registry.runtimes[runtimeId];
+      const name = desc && desc.runtime && desc.runtime.hostBehaviors &&
+        desc.runtime.hostBehaviors.sharedHooksDirName;
+      return [isSafeSegment(name) ? name : DEFAULT_NAME];
+    }
+
+    // Runtime undeterminable: scan every known candidate (see asymmetric
+    // fallback comment above).
+    return Array.from(knownNames);
+  }
+
   async function routeDetectCustomFiles({ args, cwd, raw, error }) {
     const configDirIdx = args.indexOf('--config-dir');
           const configDir = configDirIdx !== -1 ? args[configDirIdx + 1] : null;
@@ -2073,7 +2391,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           ];
           const GSD_PREFIX_MANAGED_DIRS = [
             'agents',
-            'hooks',
+            ...resolveSharedHooksDirCandidates(resolvedConfigDir),
             'skills',
           ];
 
@@ -2605,6 +2923,133 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           }
   }
 
+  // `gsd_run query context-predicates` — selector surface for the CONTEXT.md
+  // predicate fact-store (ADR-1671, #2928 Phase 1 row S9). Parses the
+  // repo-root CONTEXT.md LIVE via the compiled context-predicates.cjs on
+  // every call — it never reads the committed docs/CONTEXT-INDEX.json (that
+  // artifact is a CI drift-guard byproduct, not a query source, so it can
+  // never go stale relative to the live predicates it answers about).
+  //
+  // Selectors: --class <CLASS>, --prefix <dotted.prefix>, --contains <text>.
+  // At least one is required. When more than one is given they are ANDed
+  // together — the same documented precedence selectPredicates() itself
+  // implements (see context-predicates.cjs doc comment: "Select predicates
+  // by one or more optional criteria (ANDed together)"); no selector is
+  // silently dropped or overridden by another.
+  //
+  // Flag parsing mirrors routePromptBudget's Map-based flagMap: the three
+  // known flags are recognized in both the space-separated `--flag value`
+  // form and the inline-assignment `--flag=value` form (the latter is the
+  // escape hatch for a flag-shaped selector value, e.g. `--contains=--dry-run`
+  // — #2928 review finding C; the space-separated form has no such escape by
+  // design, since a following `--...` token always reads as a missing value).
+  // `--class=` (empty value) and `--class==A` (double-equals typo shape)
+  // are rejected the same way under either form. On a duplicate flag the
+  // FIRST occurrence wins (`Map.set` only fires when the key is absent),
+  // which is deterministic across repeated invocations with identical argv.
+  //
+  // Prototype-pollution safety: selector values are only ever compared via
+  // `===`/`.startsWith()`/`.includes()` against ordinary string fields — this
+  // route never uses a user-supplied string as an object property key
+  // (`obj[userValue] = ...`), so `--class __proto__` / `constructor` /
+  // `prototype` are just non-matching ordinary strings, not property-access
+  // vectors. `flagMap` itself is a `Map`, immune to prototype pollution by
+  // construction.
+  function routeContextPredicates({ args, cwd, raw, error }) {
+    const { parsePredicates, selectPredicates } = require('./lib/context-predicates.cjs');
+
+    const KNOWN_FLAGS = new Set(['--class', '--prefix', '--contains']);
+    const flagMap = new Map();
+    for (let i = 1; i < args.length; i++) {
+      const current = args[i];
+      if (typeof current !== 'string' || !current.startsWith('--')) continue;
+
+      // Inline-assignment escape hatch (`--flag=value`, mirrors the `--config-dir=`/
+      // `--runtime=` convention in routeUpdateContext elsewhere in this file). This is
+      // the ONLY way to pass a flag-shaped selector value (e.g. searching CONTEXT.md
+      // for the literal substring "--dry-run"): the space-separated form below always
+      // treats a following `--...` token as a missing value, by design, so it has no
+      // escape hatch on its own (#2928 review finding C).
+      const eqFlag = [...KNOWN_FLAGS].find((f) => current.startsWith(`${f}=`));
+      if (eqFlag) {
+        const value = current.slice(eqFlag.length + 1);
+        // Reject an empty value (`--class=`) and the `--class==A` double-equals typo
+        // shape (a value starting with `=`) the same way the pre-existing malformed-
+        // assignment behavior did — never silently accept "=A" as a literal value.
+        if (value === '' || value.startsWith('=')) {
+          error(`context-predicates: ${eqFlag} requires a non-empty value`, ERROR_REASON.USAGE);
+          return;
+        }
+        if (!flagMap.has(eqFlag)) flagMap.set(eqFlag, value);
+        continue;
+      }
+
+      if (!KNOWN_FLAGS.has(current)) {
+        error(`Unknown flag for context-predicates: ${current}`, ERROR_REASON.USAGE);
+        return;
+      }
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        if (!flagMap.has(current)) flagMap.set(current, null);
+        continue;
+      }
+      if (!flagMap.has(current)) flagMap.set(current, next);
+      i++;
+    }
+
+    const hasClass = flagMap.has('--class');
+    const hasPrefix = flagMap.has('--prefix');
+    const hasContains = flagMap.has('--contains');
+
+    if (!hasClass && !hasPrefix && !hasContains) {
+      error(
+        'Usage: gsd-tools query context-predicates --class <CLASS> | --prefix <dotted.prefix> | --contains <text> ' +
+        '(selectors are ANDed when combined)',
+        ERROR_REASON.USAGE,
+      );
+      return;
+    }
+
+    const requireNonEmpty = (flagName, rawValue) => {
+      if (rawValue === null || rawValue === undefined || rawValue.trim() === '') {
+        error(`context-predicates: ${flagName} requires a non-empty value`, ERROR_REASON.USAGE);
+        return null;
+      }
+      return rawValue;
+    };
+
+    const opts = {};
+    if (hasClass) {
+      const v = requireNonEmpty('--class', flagMap.get('--class'));
+      if (v === null) return;
+      opts.klass = v;
+    }
+    if (hasPrefix) {
+      const v = requireNonEmpty('--prefix', flagMap.get('--prefix'));
+      if (v === null) return;
+      opts.prefix = v;
+    }
+    if (hasContains) {
+      const v = requireNonEmpty('--contains', flagMap.get('--contains'));
+      if (v === null) return;
+      opts.contains = v;
+    }
+
+    const contextMdPath = path.join(__dirname, '..', '..', 'CONTEXT.md');
+    let markdown;
+    try {
+      markdown = fs.readFileSync(contextMdPath, 'utf8');
+    } catch (err) {
+      error(`context-predicates: cannot read ${contextMdPath}: ${err && err.message}`, ERROR_REASON.USAGE);
+      return;
+    }
+
+    const { predicates } = parsePredicates(markdown);
+    const matches = selectPredicates(predicates, opts);
+
+    output({ matched: matches.length, predicates: matches }, raw);
+  }
+
   function routeUpdateContext({ args, cwd, raw, error }) {
     // #498: resolve the installed GSD version, scope, runtime, and config dir
           // for /gsd:update. Replaces ~280 lines of inline bash in update.md with a
@@ -2912,6 +3357,7 @@ const HOST_COMMAND_ROUTERS = {
     'normalize-test-command': routeNormalizeTestCommand,
     'dispatch-should-flatten': routeDispatchShouldFlatten,
     'dispatch-isolation': routeDispatchIsolation,
+    'record-dispatch-isolation': routeRecordDispatchIsolation,
     'resolve-dispatch-type': routeResolveDispatchType,
     'agent-skills': routeAgentSkills,
     'skill-manifest': routeSkillManifest,
@@ -2940,6 +3386,7 @@ const HOST_COMMAND_ROUTERS = {
     'restore-custom-files': routeRestoreCustomFiles,
     'from-gsd2': routeFromGsd2,
     'prompt-budget': routePromptBudget,
+    'context-predicates': routeContextPredicates,
     'review-lane': routeReviewLane,
     'update-context': routeUpdateContext,
     'classify-confidence': routeClassifyConfidence,
@@ -2948,6 +3395,7 @@ const HOST_COMMAND_ROUTERS = {
     'user-story': routeUserStory,
     'drift-guard': routeDriftGuard,
     'windows': routeWindows,
+    'skills-root': routeSkillsRoot,
 };
 
 // Returns true when consumed (suppress "Unknown command"), false to fall
@@ -3143,6 +3591,121 @@ function runWithTimeout(argv) {
 
 // ─── CLI Router ───────────────────────────────────────────────────────────────
 
+// Top-level usage string — emitted by `gsd-tools` (no args) and by
+// `gsd-tools --help` / any `--help` request below.
+// CR feedback: the command list must enumerate every top-level command
+// supported by the dispatcher so `--help` is actually useful for
+// discovery; previously it was a partial subset that didn't include
+// phase / roadmap / milestone / progress / etc.
+//
+// Module-scoped (not function-local) so it can be exported and compared
+// against HOST_COMMAND_ROUTERS in a parity test (DEFECT.GENERATIVE-FIX) —
+// this string and HOST_COMMAND_ROUTERS/SKIP_ROOT_RESOLUTION are three
+// independently hand-maintained sites and nothing previously caught them
+// drifting apart when a query command was added to only one or two.
+const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
+  'Commands: agent, agent-skills, assumption-delta, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, pr-subrepo, ' +
+  'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, ' +
+  'context-predicates, current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
+  'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
+  'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
+  'capability, classify-confidence, git, learnings, list-seeds, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
+  'profile-sample, progress, project-instruction-file, prompt-budget, quick-tasks-append, requirements, research-plan, research-store, resolve-granularity, resolve-model, restore-custom-files, roadmap, scaffold, smart-entry, state, ' +
+  'config-set-model-profile, dispatch-isolation, dispatch-should-flatten, record-dispatch-isolation, estimate-calibrate, estimate-calibration, estimate-check, resolve-dispatch-type, ' +
+  'resolve-execution, review-lane, skill-manifest, skills-root, state-snapshot, stats, summary-extract, teams-status, todo, uat, update-context, verification, websearch, windows, ' +
+  'task, template, user-story, validate, verify, verify-path-exists, verify-summary, eval, workstream, worktree\n\n' +
+  'Global flags:\n' +
+  '  --raw              Emit raw output without post-processing\n' +
+  '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
+  '  --cwd <path>       Override working directory for project-root resolution\n' +
+  '  --ws <name>        Override active workstream (or set GSD_WORKSTREAM)\n' +
+  '  --json-errors      Emit structured JSON error objects on stderr (or set GSD_JSON_ERRORS=1)\n\n' +
+  'For command-specific argument requirements, invoke the command without args ' +
+  '(e.g. `gsd-tools phase add`) — the resulting error lists what is required.';
+
+// Multi-repo guard: resolve project root for commands that read/write .planning/.
+// Skip for pure-utility commands that don't touch .planning/ to avoid unnecessary
+// filesystem traversal on every invocation.
+// 'loop' and 'capability' are intentionally NOT in SKIP_ROOT_RESOLUTION.
+// Both are registry/config queries that resolve activation via
+// .planning/config.json; they need the project root (cwd) for correct
+// `when` key resolution. If one is ever moved to SKIP_ROOT_RESOLUTION,
+// move the other at the same time (keep them consistent).
+//
+// Module-scoped for the same reason as TOP_LEVEL_USAGE above — kept
+// module-private and exposed to the dispatch-table/help-string/skip-list
+// parity test only through the read-only skipsRootResolution() predicate
+// below (never as the live Set itself; see that function's doc comment).
+const SKIP_ROOT_RESOLUTION = new Set([
+  'generate-slug', 'current-timestamp', 'verify-path-exists',
+  // #2844: verify-summary was previously skipped, leaving relative file-claim
+  // paths resolved against the raw process.cwd() — invoking from a subdirectory
+  // manufactured "missing files" on an otherwise-correct SUMMARY. It now goes
+  // through findProjectRoot so claims resolve against the project root.
+  'template', 'frontmatter', 'detect-custom-files',
+  // #1854: restore-custom-files operates on a runtime config dir passed
+  // explicitly via --config-dir; it never reads .planning/.
+  'restore-custom-files',
+  'worktree', 'prompt-budget',
+  // context-predicates is a pure repo-root CONTEXT.md read (like
+  // prompt-budget); it never touches .planning/, so it needs no project
+  // root resolution and must work from any cwd (including one with no
+  // .planning/ directory at all).
+  'context-predicates',
+  'research-store', 'research-plan', 'package-legitimacy', 'classify-confidence',
+  'user-story', // pure string validation — no .planning/ access needed
+  // #1529: pure runtime→filename projection via getProjectInstructionFile; no
+  // .planning/ access needed, and resolving project root would break workflow
+  // invocations that run before .planning/ exists (new-project Step 1).
+  'project-instruction-file',
+  // #1579: eval.score is pure arithmetic (covered/total + infra weights); it
+  // needs no .planning/ access, so skip the findProjectRoot traversal.
+  'eval',
+]);
+
+// Read-only accessor for SKIP_ROOT_RESOLUTION (DEFECT.MUTABLE-EXPORTED-SET,
+// #2928 review). The Set above stays module-private and mutable internally
+// (main() only ever calls .has() on it), but exporting the live Set directly
+// would let any importer call .add()/.delete() on it — Object.freeze() does
+// not lock Set.prototype.add/delete, so freezing the instance would not have
+// closed this — and silently change dispatch behavior for every caller in the
+// process. Export this predicate instead; it exposes membership without
+// exposing a mutation surface.
+function skipsRootResolution(command) {
+  return SKIP_ROOT_RESOLUTION.has(command);
+}
+
+/**
+ * Resolve the worktree root for a given cwd, warning to stderr when git
+ * could not determine it (reason 'git_timed_out') rather than silently
+ * trusting a best-effort fallback (#3050). Extracted from main() so it can
+ * be driven directly in tests via injected deps.
+ *
+ * @param {string} cwd
+ * @param {{ existsSync?: (p: string) => boolean, resolveWorktreeRoot?: (cwd: string) => { root: string, reason: string }, writeWarning?: (msg: string) => void }} [deps]
+ * @returns {string} resolved cwd
+ */
+function resolveMainWorktreeCwd(cwd, deps = {}) {
+  const existsSync = deps.existsSync || fs.existsSync;
+  const resolveWorktreeRoot = deps.resolveWorktreeRoot || require('./lib/worktree-safety.cjs').resolveWorktreeRoot;
+  const writeWarning = deps.writeWarning || ((msg) => process.stderr.write(msg));
+
+  if (existsSync(path.join(cwd, '.planning'))) {
+    return cwd;
+  }
+  const { root: worktreeRoot, reason: worktreeRootReason } = resolveWorktreeRoot(cwd);
+  if (worktreeRootReason === 'git_timed_out') {
+    writeWarning(
+      'WARNING: could not determine the git worktree root (git timed out). ' +
+      'Planning artifacts (STATE.md, ROADMAP.md, etc.) may be written to the ' +
+      `wrong tree — proceeding with "${worktreeRoot}" as a best-effort fallback. ` +
+      'Retry the command; if this persists, check for a stalled filesystem mount ' +
+      'or a stale git index lock (.git/index.lock) in this worktree.\n'
+    );
+  }
+  return worktreeRoot;
+}
+
 async function main() {
   let args = process.argv.slice(2);
 
@@ -3200,13 +3763,7 @@ async function main() {
   // Resolve worktree root: in a linked worktree, .planning/ lives in the main worktree.
   // However, in monorepo worktrees where the subdirectory itself owns .planning/,
   // skip worktree resolution — the CWD is already the correct project root.
-  const { resolveWorktreeRoot } = require('./lib/worktree-safety.cjs');
-  if (!fs.existsSync(path.join(cwd, '.planning'))) {
-    const worktreeRoot = resolveWorktreeRoot(cwd);
-    if (worktreeRoot !== cwd) {
-      cwd = worktreeRoot;
-    }
-  }
+  cwd = resolveMainWorktreeCwd(cwd);
 
   // Optional workstream override for parallel milestone work.
   // Priority: --ws flag > GSD_WORKSTREAM env var > session/shared pointer > null.
@@ -3276,30 +3833,6 @@ async function main() {
     }
   }
 
-  // Top-level usage string — emitted by `gsd-tools` (no args) and by
-  // `gsd-tools --help` / any `--help` request below.
-  // CR feedback: the command list must enumerate every top-level command
-  // supported by the dispatcher so `--help` is actually useful for
-  // discovery; previously it was a partial subset that didn't include
-  // phase / roadmap / milestone / progress / etc.
-  const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
-    'Commands: agent, agent-skills, assumption-delta, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, pr-subrepo, ' +
-    'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, ' +
-    'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
-    'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
-    'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
-    'capability, classify-confidence, git, learnings, list-seeds, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
-    'profile-sample, progress, project-instruction-file, prompt-budget, quick-tasks-append, requirements, research-plan, research-store, resolve-granularity, resolve-model, restore-custom-files, roadmap, scaffold, smart-entry, state, ' +
-    'task, template, user-story, validate, verify, verify-path-exists, verify-summary, eval, workstream, worktree\n\n' +
-    'Global flags:\n' +
-    '  --raw              Emit raw output without post-processing\n' +
-    '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
-    '  --cwd <path>       Override working directory for project-root resolution\n' +
-    '  --ws <name>        Override active workstream (or set GSD_WORKSTREAM)\n' +
-    '  --json-errors      Emit structured JSON error objects on stderr (or set GSD_JSON_ERRORS=1)\n\n' +
-    'For command-specific argument requirements, invoke the command without args ' +
-    '(e.g. `gsd-tools phase add`) — the resulting error lists what is required.';
-
   if (!command) {
     error(TOP_LEVEL_USAGE);
   }
@@ -3326,35 +3859,6 @@ async function main() {
     }
   }
 
-  // Multi-repo guard: resolve project root for commands that read/write .planning/.
-  // Skip for pure-utility commands that don't touch .planning/ to avoid unnecessary
-  // filesystem traversal on every invocation.
-  // 'loop' and 'capability' are intentionally NOT in SKIP_ROOT_RESOLUTION.
-  // Both are registry/config queries that resolve activation via
-  // .planning/config.json; they need the project root (cwd) for correct
-  // `when` key resolution. If one is ever moved to SKIP_ROOT_RESOLUTION,
-  // move the other at the same time (keep them consistent).
-  const SKIP_ROOT_RESOLUTION = new Set([
-    'generate-slug', 'current-timestamp', 'verify-path-exists',
-    // #2844: verify-summary was previously skipped, leaving relative file-claim
-    // paths resolved against the raw process.cwd() — invoking from a subdirectory
-    // manufactured "missing files" on an otherwise-correct SUMMARY. It now goes
-    // through findProjectRoot so claims resolve against the project root.
-    'template', 'frontmatter', 'detect-custom-files',
-    // #1854: restore-custom-files operates on a runtime config dir passed
-    // explicitly via --config-dir; it never reads .planning/.
-    'restore-custom-files',
-    'worktree', 'prompt-budget',
-    'research-store', 'research-plan', 'package-legitimacy', 'classify-confidence',
-    'user-story', // pure string validation — no .planning/ access needed
-    // #1529: pure runtime→filename projection via getProjectInstructionFile; no
-    // .planning/ access needed, and resolving project root would break workflow
-    // invocations that run before .planning/ exists (new-project Step 1).
-    'project-instruction-file',
-    // #1579: eval.score is pure arithmetic (covered/total + infra weights); it
-    // needs no .planning/ access, so skip the findProjectRoot traversal.
-    'eval',
-  ]);
   if (!SKIP_ROOT_RESOLUTION.has(command)) {
     cwd = findProjectRoot(cwd);
   }
@@ -3511,5 +4015,14 @@ if (require.main === module) {
 // synthetic registry + requireModule injections.
 // ADR-1244 Phase 5: export dispatchOverlayCapabilityCommand + defaultRequireFromInstallRoot for
 // the third-party overlay dispatch + install-root confinement tests.
-module.exports = { dispatchCapabilityCommand, dispatchOverlayCapabilityCommand, defaultRequireFromInstallRoot, dispatchHostCommand, HOST_COMMAND_ROUTERS };
+module.exports = {
+  dispatchCapabilityCommand,
+  dispatchOverlayCapabilityCommand,
+  defaultRequireFromInstallRoot,
+  dispatchHostCommand,
+  HOST_COMMAND_ROUTERS,
+  TOP_LEVEL_USAGE,
+  skipsRootResolution,
+  resolveMainWorktreeCwd,
+};