@opengsd/gsd-core 1.3.1 → 1.4.0-rc.1

package/agents/gsd-project-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
 color: cyan
 # hooks:
 #   PostToolUse:
@@ -33,53 +33,11 @@ Your files feed the roadmap:
 </role>
 
 <documentation_lookup>
-When you need library or framework documentation, check in this order:
-
-1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
-   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
-   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
-
-2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
-   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
-
-   Step 1 — Resolve library ID:
-   ```bash
-   npx --yes ctx7@latest library <name> "<query>"
-   ```
-   Step 2 — Fetch documentation:
-   ```bash
-   npx --yes ctx7@latest docs <libraryId> "<query>"
-   ```
-
-Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
-works via Bash and produces equivalent output.
+@~/.claude/gsd-core/references/research-documentation-lookup.md
 </documentation_lookup>
 
 <philosophy>
-
-## Training Data = Hypothesis
-
-Claude's training is 6-18 months stale. Knowledge may be outdated, incomplete, or wrong.
-
-**Discipline:**
-1. **Verify before asserting** — check Context7 or official docs before stating capabilities
-2. **Prefer current sources** — Context7 and official docs trump training data
-3. **Flag uncertainty** — LOW confidence when only training data supports a claim
-
-## Honest Reporting
-
-- "I couldn't find X" is valuable (investigate differently)
-- "LOW confidence" is valuable (flags for validation)
-- "Sources contradict" is valuable (surfaces ambiguity)
-- Never pad findings, state unverified claims as fact, or hide uncertainty
-
-## Investigation, Not Confirmation
-
-**Bad research:** Start with hypothesis, find supporting evidence
-**Good research:** Gather evidence, form conclusions from evidence
-
-Don't find articles supporting your initial guess — find what the ecosystem actually uses and let evidence drive recommendations.
-
+@~/.claude/gsd-core/references/research-philosophy.md
 </philosophy>
 
 <research_modes>
@@ -94,132 +52,95 @@ Don't find articles supporting your initial guess — find what the ecosystem ac
 
 <tool_strategy>
 
-## Tool Priority Order
+## Research Plan via Code Seam
 
-### 1. Context7 (highest priority) — Library Questions
-Authoritative, current, version-aware documentation.
+The agent decides **what** to research (the questions). The seam decides **which provider** to use and manages caching.
 
-```
-1. mcp__context7__resolve-library-id with libraryName: "[library]"
-2. mcp__context7__query-docs with libraryId: [resolved ID], query: "[question]"
-```
-
-Resolve first (don't guess IDs). Use specific queries. Trust over training data.
-
-### 2. Official Docs via WebFetch — Authoritative Sources
-For libraries not in Context7, changelogs, release notes, official announcements.
-
-Use exact URLs (not search result pages). Check publication dates. Prefer /docs/ over marketing.
+### Step A — Build a research-plan input file
 
-### 3. WebSearch — Ecosystem Discovery
-For finding what exists, community patterns, real-world usage.
+Construct a JSON file at a temp path (e.g. `/tmp/research-plan-input.json`):
 
-**Query templates:**
+```json
+{
+  "ecosystem": "<npm|pypi|crates|...>",
+  "config": { "exa_search": true/false, "brave_search": true/false, "firecrawl": true/false, "tavily_search": true/false },
+  "questions": [
+    { "text": "How does X work?", "kind": "docs", "library": "x", "version": "1.2.3" },
+    { "text": "Best practices for Y?", "kind": "web" }
+  ]
+}
 ```
-Ecosystem: "[tech] best practices", "[tech] recommended libraries"
-Patterns:  "how to build [type] with [tech]", "[tech] architecture patterns"
-Problems:  "[tech] common mistakes", "[tech] gotchas"
-```
-
-Use multiple query variations. Mark WebSearch-only findings as LOW confidence. Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
 
-### Enhanced Web Search (Brave API)
+`config` comes from the init context (availability flags). `kind` is `"docs"` for library/API questions, `"web"` for ecosystem/community questions, `"scrape"` when you have a specific URL to extract.
 
-Check `brave_search` from orchestrator context. If `true`, use Brave Search for higher quality results:
+### Step B — Obtain the fetch plan
 
 ```bash
-gsd-tools query websearch "your query" --limit 10
+gsd-tools query research-plan --input /tmp/research-plan-input.json
 ```
 
-**Options:**
-- `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+Returns `{ "items": [ { "question": "...", "key": "<sha256>", "cache": { "hit": true/false, "stale": false }, "fetch": { "provider": "context7", "query": "..." } } ] }`.
 
-If `brave_search: false` (or not set), use built-in WebSearch tool instead.
+- `cache.hit && !cache.stale` → reuse the cached digest; no fetch needed.
+- `cache.hit && cache.stale` → fetch anyway to refresh; the old entry is returned as a fallback.
+- no `cache` field → cache miss; must fetch.
 
-Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
+### Step C — Execute the indicated fetch
 
-### Exa Semantic Search (MCP)
+For each item where `fetch` is present, invoke the MCP tool matching `fetch.provider`:
 
-Check `exa_search` from orchestrator context. If `true`, use Exa for research-heavy, semantic queries:
+| provider id | MCP tool / built-in |
+|-------------|---------------------|
+| `context7` | `mcp__context7__resolve-library-id` then `mcp__context7__query-docs` |
+| `ref` | `mcp__ref__*` (use the appropriate ref MCP tool for the query) |
+| `jina` | `mcp__jina__*` (use the appropriate jina MCP tool for the query) |
+| `exa` | `mcp__exa__web_search_exa` with `fetch.query` |
+| `tavily` | `mcp__tavily__search` with `fetch.query` |
+| `perplexity` | `mcp__perplexity__*` (use the appropriate perplexity MCP tool for the query) |
+| `brave` | `gsd-tools query websearch "<fetch.query>"` (Brave-backed) or built-in `WebSearch` |
+| `firecrawl` | `mcp__firecrawl__scrape` with url (scrape kind) or `mcp__firecrawl__search` |
+| `websearch` | built-in `WebSearch` tool |
+| `webfetch` | built-in `WebFetch` tool |
 
-```
-mcp__exa__web_search_exa with query: "your semantic query"
-```
+For any other provider id `X` not listed above: use `mcp__X__*` if available, else fall back to `WebSearch`.
 
-**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries, ecosystem exploration. Returns semantically relevant results rather than keyword matches.
+**WebSearch tip:** Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
 
-If `exa_search: false` (or not set), fall back to WebSearch or Brave Search.
+### Step D — Cache each digest
 
-### Firecrawl Deep Scraping (MCP)
+After digesting a source, persist it so future runs can reuse it:
 
-Check `firecrawl` from orchestrator context. If `true`, use Firecrawl to extract structured content from discovered URLs:
-
-```
-mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
-mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
+```bash
+gsd-tools query research-store put <key> \
+  --content "<one-paragraph digest>" \
+  --source <curated|web> \
+  --provider <provider-id> \
+  --confidence <HIGH|MEDIUM|LOW> \
+  --kind <docs|web>
 ```
 
-**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs, comparison articles. Use after finding a relevant URL from Exa, WebSearch, or known docs. Returns clean markdown instead of raw HTML.
+`key` comes from the `research-plan` item. `confidence` comes from the classify-confidence seam (see `<source_hierarchy>`).
 
-If `firecrawl: false` (or not set), fall back to WebFetch.
+</tool_strategy>
 
-## Verification Protocol
+<source_hierarchy>
 
-**WebSearch findings must be verified:**
+Obtain the confidence tier from code — do not hard-code tiers in your reasoning:
 
+```bash
+gsd-tools query classify-confidence --provider <provider-id>
+# for cross-checked findings, add --verified:
+gsd-tools query classify-confidence --provider <provider-id> --verified
 ```
-For each finding:
-1. Verify with Context7? YES → HIGH confidence
-2. Verify with official docs? YES → MEDIUM confidence
-3. Multiple sources agree? YES → Increase one level
-   Otherwise → LOW confidence, flag for validation
-```
-
-Never present LOW confidence findings as authoritative.
 
-## Confidence Levels
+Returns `HIGH`, `MEDIUM`, or `LOW`. Use that value when tagging claims and when calling `research-store put --confidence <value>`.
 
-| Level | Sources | Use |
-|-------|---------|-----|
-| HIGH | Context7, official documentation, official releases | State as fact |
-| MEDIUM | WebSearch verified with official source, multiple credible sources agree | State with attribution |
-| LOW | WebSearch only, single source, unverified | Flag as needing validation |
+**Never present LOW confidence findings as authoritative.**
 
-**Source priority:** Context7 → Exa (verified) → Firecrawl (official docs) → Official GitHub → Brave/WebSearch (verified) → WebSearch (unverified)
-
-</tool_strategy>
+</source_hierarchy>
 
 <verification_protocol>
-
-## Research Pitfalls
-
-### Configuration Scope Blindness
-**Trap:** Assuming global config means no project-scoping exists
-**Prevention:** Verify ALL scopes (global, project, local, workspace)
-
-### Deprecated Features
-**Trap:** Old docs → concluding feature doesn't exist
-**Prevention:** Check current docs, changelog, version numbers
-
-### Negative Claims Without Evidence
-**Trap:** Definitive "X is not possible" without official verification
-**Prevention:** Is this in official docs? Checked recent updates? "Didn't find" ≠ "doesn't exist"
-
-### Single Source Reliance
-**Trap:** One source for critical claims
-**Prevention:** Require official docs + release notes + additional source
-
-## Pre-Submission Checklist
-
-- [ ] All domains investigated (stack, features, architecture, pitfalls)
-- [ ] Negative claims verified with official docs
-- [ ] Multiple sources for critical claims
-- [ ] URLs provided for authoritative sources
-- [ ] Publication dates checked (prefer recent/current)
-- [ ] Confidence levels assigned honestly
-- [ ] "What might I have missed?" review completed
-
+@~/.claude/gsd-core/references/research-verification-protocol.md
 </verification_protocol>
 
 <output_formats>
@@ -564,7 +485,7 @@ Orchestrator provides: project name/description, research mode, project context,
 
 ## Step 3: Execute Research
 
-For each domain: Context7 → Official Docs → WebSearch → Verify. Document with confidence levels.
+For each domain, use the `<tool_strategy>` seam (Steps A–D): build questions JSON, call `gsd-tools query research-plan`, run the indicated provider per item, then cache each digest. Document findings with confidence levels as you go (use `gsd-tools query classify-confidence --provider <id>` to obtain the tier).
 
 ## Step 4: Quality Check
 
@@ -678,7 +599,7 @@ Research is complete when:
 - [ ] Feature landscape mapped (table stakes, differentiators, anti-features)
 - [ ] Architecture patterns documented
 - [ ] Domain pitfalls catalogued
-- [ ] Source hierarchy followed (Context7 → Official → WebSearch)
+- [ ] Source hierarchy followed (research-plan seam determines provider order; classify-confidence seam determines tiers)
 - [ ] All findings have confidence levels
 - [ ] Output files created in `.planning/research/`
 - [ ] SUMMARY.md includes roadmap implications

package/agents/gsd-ui-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-ui-researcher
 description: Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.
-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
 color: "#E879F9"
 # hooks:
 #   PostToolUse:
@@ -28,26 +28,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 </role>
 
 <documentation_lookup>
-When you need library or framework documentation, check in this order:
-
-1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
-   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
-   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
-
-2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
-   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
-
-   Step 1 — Resolve library ID:
-   ```bash
-   npx --yes ctx7@latest library <name> "<query>"
-   ```
-   Step 2 — Fetch documentation:
-   ```bash
-   npx --yes ctx7@latest docs <libraryId> "<query>"
-   ```
-
-Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
-works via Bash and produces equivalent output.
+@~/.claude/gsd-core/references/research-documentation-lookup.md
 </documentation_lookup>
 
 <project_context>

package/agents/gsd-verifier.md

@@ -466,8 +466,11 @@ ls $BUILD_OUTPUT_DIR/*.{js,css} 2>/dev/null | wc -l
 # Module exports expected functions
 node -e "const m = require('$MODULE_PATH'); console.log(typeof m.$FUNCTION_NAME)" 2>/dev/null | grep -q "function"
 
-# Test suite passes (if tests exist for this phase's code)
-npm test -- --grep "$PHASE_TEST_PATTERN" 2>&1 | grep -q "passing"
+# A test EXISTS (existence proof — enumerate, do NOT run the suite)
+cargo test -- --list 2>/dev/null | grep -q "$PHASE_TEST_PATTERN"   # pytest --collect-only -q · npx vitest list · go test -list '.*'
+
+# A specific test PASSES (run ONE named test, never the whole suite)
+cargo test "$TEST_NAME" -- --exact   # pytest -k "$TEST_NAME" · npx vitest run -t "$TEST_NAME"
 ```
 
 2. **Run each check** and record pass/fail:
@@ -487,6 +490,7 @@ npm test -- --grep "$PHASE_TEST_PATTERN" 2>&1 | grep -q "passing"
 - Each check must complete in under 10 seconds
 - Do not start servers or services — only test what's already runnable
 - Do not modify state (no writes, no mutations, no side effects)
+- **Run the full workspace test command at most once per verification.** Never filter a full run per must-have (`<full-suite> 2>&1 | grep X` repeated per truth) — it re-runs everything and yields no new evidence. Prove a test exists by enumeration (`--list` / `--collect-only`); prove one passes via a single named test. If a full run is genuinely required, run it once and `grep` the saved output.
 - If the project has no runnable entry points yet, skip with: "Step 7b: SKIPPED (no runnable entry points)"
 
 ## Step 7c: Probe Execution
@@ -572,6 +576,8 @@ Classify status using this decision tree IN ORDER (most restrictive first):
 
 **passed is ONLY valid when the human verification section is empty.** If you identified items requiring human testing in Step 8, status MUST be human_needed.
 
+> **Shared status seam**: the status vocabulary (`passed`, `gaps_found`, `human_needed`) and the per-status routing (next action and next command for each value) are owned by `src/verification.cts` via `gsd_run query verification.status`. This agent is the single emitter of the frontmatter status field; consumers (ship.md, execute-phase.md) read routing from that query instead of re-deriving it.
+
 **Score:** `verified_truths / total_truths`
 
 ## Step 9b: Filter Deferred Items

package/bin/install.js

@@ -31,6 +31,10 @@ const {
 const {
   resolveAntigravityGlobalDir,
 } = require('../gsd-core/bin/lib/runtime-homes.cjs');
+const {
+  applyWorktreeBaseRef,
+  readBaseRefFromSettings,
+} = require('../gsd-core/bin/lib/worktree-base-ref.cjs');
 
 /**
  * Runtimes that register hyphen-form `name:` per #2808 AND copy agent bodies
@@ -1997,6 +2001,8 @@ function convertCopilotToolName(claudeTool) {
   if (claudeToCopilotTools[claudeTool]) {
     return claudeToCopilotTools[claudeTool];
   }
+  // mcp__{tavily,ref,jina,exa,firecrawl}__* use the generic MCP passthrough like exa/firecrawl;
+  // add explicit Copilot registry mappings when the io.github ids are confirmed (#657 follow-up)
   // Default: lowercase
   return claudeTool.toLowerCase();
 }
@@ -2795,14 +2801,22 @@ function convertClaudeAgentToClineAgent(content) {
 // ── End Cline converters ─────────────────────────────────────────────────────
 
 function convertSlashCommandsToCodexSkillMentions(content) {
-  // Convert colon-style skill invocations to Codex $ prefix
+  // Colon-style /gsd: never appears as a filesystem path segment, so no boundary guard is needed (unlike the hyphen-style below).
   let converted = content.replace(/\/gsd:([a-z0-9-]+)/gi, (_, commandName) => {
     return `$gsd-${String(commandName).toLowerCase()}`;
   });
   // Convert hyphen-style command references (workflow output) to Codex $ prefix.
-  // Negative lookbehind excludes file paths like bin/gsd-tools.cjs where
-  // the slash is preceded by a word char, dot, or another slash.
-  converted = converted.replace(/(?<![a-zA-Z0-9./])\/gsd-([a-z0-9-]+)/gi, (_, commandName) => {
+  // A real /gsd-<cmd> MENTION is defined positively by two boundaries, so any
+  // in-path occurrence is excluded by construction (no denylist of preceding
+  // chars to maintain — see #712, supersedes the #637/#704 lookbehind treadmill):
+  //   1. Left boundary: opens at start-of-string, whitespace, or an inline-prose
+  //      delimiter (backtick/quote/paren/bracket) — e.g. `/gsd-execute-phase`.
+  //   2. Right boundary: the command token is NOT followed by a path separator
+  //      `/` (a path continues: `/gsd-core/bin/...`; a command does not). The
+  //      `(?![a-z0-9/-])` also blocks regex backtracking to a shorter command.
+  // This converts backtick-wrapped MENTIONS (`/gsd-foo`) while leaving backtick-
+  // wrapped PATHS (`/gsd-core/workflows/update.md`) untouched (#712).
+  converted = converted.replace(/(?<=^|[\s`"'([])\/gsd-([a-z0-9-]+)(?![a-z0-9/-])/gi, (_, commandName) => {
     return `$gsd-${String(commandName).toLowerCase()}`;
   });
   return converted;
@@ -8575,6 +8589,10 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // agentsSrc is declared here (let, not const) because installCodexConfig() inside the
   // Codex config block below also references it, and that block is outside the try scope.
   let agentsSrc = path.join(src, 'agents');
+  // Capture upgrade signal BEFORE files are written (#683). Must be declared at function
+  // scope (outside the try block below) so it is accessible in the settings section later.
+  // Absent VERSION = fresh install; present VERSION = upgrade/re-install.
+  const priorInstallExisted = fs.existsSync(path.join(targetDir, 'gsd-core', 'VERSION'));
   try {
   installerMigrationResult = runInstallerMigrations({
     configDir: targetDir,
@@ -10106,6 +10124,68 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       ? buildHookCommand(targetDir, 'gsd-update-banner.js', hookOpts)
       : localCmd('gsd-update-banner.js'));
 
+  // #683: Set worktree.baseRef:"head" in settings.local.json for local Claude installs.
+  // Both fresh and upgrade paths apply only when worktrees are enabled for the project.
+  // Never applies to global installs, non-Claude runtimes, or when the user already
+  // has an explicit baseRef in EITHER settings.local.json OR settings.json (no-clobber).
+  // Guard: skip entirely when settings is not a plain object (e.g. parsed to [] or primitive)
+  // to avoid crashing applyWorktreeBaseRef on unexpected top-level shapes.
+  if (isLocalClaude && settings !== null && typeof settings === 'object' && !Array.isArray(settings)) {
+    // Read shared settings.json baseRef so no-clobber spans both files (#683 FIX 1).
+    // shared settings.json no-clobber is checked here; settings.local.json no-clobber
+    // is enforced inside applyWorktreeBaseRef itself.
+    const sharedSettingsForBaseRef = readSettings(path.join(targetDir, 'settings.json')) || {};
+    const sharedBaseRef = readBaseRefFromSettings(sharedSettingsForBaseRef);
+
+    // Compute worktrees-enabled ONCE for both fresh and upgrade paths (FIX A: DRY + consistency).
+    // Read workflow.use_worktrees from .planning/config.json by walking up from
+    // targetDir (same walk-up pattern as readGsdRuntimeProfileResolver). Defaults
+    // to enabled (true) when the file is missing, unreadable, or the key is absent;
+    // only boolean false disables (string "false" stays enabled).
+    let worktreesEnabled = true; // default: enabled
+    try {
+      let probeDir = path.resolve(targetDir);
+      for (let depth = 0; depth < 8; depth += 1) {
+        const candidate = path.join(probeDir, '.planning', 'config.json');
+        if (fs.existsSync(candidate)) {
+          try {
+            const parsed = JSON.parse(stripJsonComments(fs.readFileSync(candidate, 'utf-8')));
+            if (parsed && typeof parsed === 'object' &&
+                parsed.workflow && parsed.workflow.use_worktrees === false) {
+              worktreesEnabled = false;
+            }
+          } catch {
+            // Malformed config.json — treat as enabled (safe fallback).
+          }
+          break;
+        }
+        const parent = path.dirname(probeDir);
+        if (parent === probeDir) break;
+        probeDir = parent;
+      }
+    } catch {
+      // Any unexpected error reading .planning — default to enabled.
+    }
+
+    if (worktreesEnabled && sharedBaseRef === null) {
+      if (!priorInstallExisted) {
+        // Fresh install — apply no-clobber baseRef set.
+        // canonical no-clobber logic: src/worktree-base-ref.cts applyWorktreeBaseRef (#683)
+        const { changed } = applyWorktreeBaseRef(settings);
+        if (changed) {
+          console.log(`  ${green}✓${reset} Set worktree.baseRef:"head" for Claude Code worktrees (forks phase worktrees off HEAD; #683)`);
+        }
+      } else {
+        // Upgrade — auto-apply no-clobber baseRef set when worktrees are enabled.
+        const { changed } = applyWorktreeBaseRef(settings);
+        if (changed) {
+          console.log(`  ${green}✓${reset} Enabled worktree.baseRef:"head" for Claude Code worktrees (forks phase worktrees off HEAD; #683)`);
+        }
+      }
+    }
+    // When worktreesEnabled is false: do nothing, print nothing (both fresh and upgrade).
+  }
+
   persistActiveProfileMarker();
   return {
     settingsPath,
@@ -10943,6 +11023,7 @@ module.exports = {
     install,
     installAllRuntimes,
     uninstall,
+    convertSlashCommandsToCodexSkillMentions,
     convertClaudeCommandToCodexSkill,
     convertClaudeToOpencodeFrontmatter,
     convertClaudeToKiloFrontmatter,

package/commands/gsd/graphify.md

@@ -79,7 +79,8 @@ Modes:
 Run:
 
 ```bash
-node $HOME/.claude/gsd-core/bin/gsd-tools.cjs graphify query <term>
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify query <term>
 ```
 
 Parse the JSON output and display results:
@@ -95,7 +96,8 @@ Parse the JSON output and display results:
 Run:
 
 ```bash
-node $HOME/.claude/gsd-core/bin/gsd-tools.cjs graphify status
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify status
 ```
 
 Parse the JSON output and display:
@@ -119,7 +121,8 @@ Surface both so the agent can choose.
 Run:
 
 ```bash
-node $HOME/.claude/gsd-core/bin/gsd-tools.cjs graphify diff
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify diff
 ```
 
 Parse the JSON output and display:
@@ -137,7 +140,8 @@ If no snapshot exists, suggest running `build` twice (first to create, second to
 Run the pre-flight check first:
 
 ```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify build
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify build
 ```
 
 Parse the JSON output:
@@ -156,12 +160,13 @@ GSD > Building knowledge graph...
 Run the build, copy artifacts, write the diff snapshot, and report the summary in a single foreground Bash call so the whole pipeline survives to completion. Use a `timeout` of `600000` ms (10 minutes), which covers the `graphify.build_timeout` ceiling (default 300 s) with margin:
 
 ```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
 graphify update . \
   && cp graphify-out/graph.json .planning/graphs/graph.json \
   && { [ -f graphify-out/graph.html ] && cp graphify-out/graph.html .planning/graphs/graph.html || true; } \
   && cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md \
-  && node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify build snapshot \
-  && node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify status
+  && gsd_run graphify build snapshot \
+  && gsd_run graphify status
 ```
 
 Do NOT pass `run_in_background: true`. Typical builds complete in 15-60 seconds and the entire chain must run foreground.

package/commands/gsd/import.md

@@ -33,8 +33,12 @@ $ARGUMENTS
 
 <process>
 If `--from-gsd2` is in $ARGUMENTS:
-Run: `node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" from-gsd2`
-Pass `--path <dir>` if provided. Present the migration result to the user.
+Run the reverse-migration (append `--path <dir>` if provided):
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run from-gsd2
+```
+Present the migration result to the user.
 Stop here (do not run the standard import workflow).
 
 Otherwise, execute the import workflow end-to-end.

package/commands/gsd/plan-phase.md

@@ -22,8 +22,8 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 **Research-only mode (`--research-phase <N>`):** Spawn `gsd-phase-researcher` for phase `N`, write `RESEARCH.md`, then exit before the planner runs. Useful for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops where iterating on research alone is dramatically cheaper than re-spawning the planner. Replaces the deleted research-phase command (#3042).
 
 **Research-only modifiers:**
-- **No flag** — when `RESEARCH.md` already exists, prompt the user to choose `update / view / skip`.
-- **`--research`** — force-refresh: re-spawn the researcher unconditionally, no prompt. Skips the existing-RESEARCH.md menu.
+- **No flag** — when `RESEARCH.md` already exists, auto-uses it: emits a one-line notice and exits cleanly, no prompt.
+- **`--research`** — force-refresh: re-spawn the researcher unconditionally, no prompt. Bypasses the existing-RESEARCH.md auto-use path.
 - **`--view`** — view-only: print existing `RESEARCH.md` to stdout. Does not spawn the researcher. Cheapest mode for the correction-without-replanning loop. If no `RESEARCH.md` exists yet, errors with a hint to drop `--view`.
 
 **Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results.

package/gsd-core/bin/check-latest-version.cjs

@@ -21,6 +21,7 @@
  */
 
 const { execNpm } = require('./lib/shell-command-projection.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
 
 // Sourced from the single Package Identity seam (#498), not re-typed. The seam
 // bakes the value from package.json at build time, so it is a code constant —
@@ -98,9 +99,9 @@ function main() {
   } else {
     process.stderr.write(`check-latest-version: ${r.reason}: ${r.detail}\n`);
   }
-  process.exit(r.ok ? 0 : 1);
+  return r.ok ? 0 : 1;
 }
 
-if (require.main === module) main();
+if (require.main === module) runMain(main);
 
 module.exports = { checkLatestVersion, CHECK_REASON, PACKAGE_NAME };