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

package/agents/gsd-advisor-researcher.md

@@ -18,26 +18,7 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
 </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>
 
 <input>

package/agents/gsd-ai-researcher.md

@@ -17,26 +17,7 @@ Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation g
 </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>
 
 <required_reading>

package/agents/gsd-domain-researcher.md

@@ -17,26 +17,7 @@ Research the business domain — not the technical framework. Write Section 1b o
 </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>
 
 <required_reading>

package/agents/gsd-executor.md

@@ -385,7 +385,7 @@ If RED or GREEN gate commits are missing, add a warning to SUMMARY.md under a `#
 
 ## MVP+TDD Gate
 
-**When the orchestrator passes both `MVP_MODE=true` and `TDD_MODE=true`:** Before running the implementation step of any task with `tdd="true"`, run the runtime gate from `@~/.claude/gsd-core/references/execute-mvp-tdd.md`. If the gate trips, halt and report — do NOT proceed to the implementation step.
+**When the orchestrator passes both `MVP_MODE=true` and `TDD_MODE=true`:** Before running the implementation step of any task with `tdd="true"`, run the runtime gate from `~/.claude/gsd-core/references/execute-mvp-tdd.md` (Read it). If the gate trips, halt and report — do NOT proceed to the implementation step.
 
 **Halt-and-report protocol:**
 

package/agents/gsd-phase-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-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: cyan
 # hooks:
 #   PostToolUse:
@@ -30,41 +30,13 @@ Spawned by `/gsd:plan-phase` (integrated) or `/gsd:plan-phase --research-phase <
 - `[CITED: docs.example.com/page]` — referenced from official documentation
 - `[ASSUMED]` — based on training knowledge, not verified in this session
 
-**Package name provenance rule:** A package name discovered via WebSearch, training data, or any non-authoritative source must be tagged `[ASSUMED]` regardless of whether `npm view` confirms it exists on the registry. Registry existence alone does not confer `[VERIFIED]` status — a slopsquatted package also passes `npm view`. Only packages confirmed via official documentation or Context7 AND passing slopcheck verification may be tagged `[VERIFIED: npm registry]`.
+**Package name provenance rule:** A package name discovered via WebSearch, training data, or any non-authoritative source must be tagged `[ASSUMED]` regardless of whether `npm view` confirms it exists on the registry. Registry existence alone does not confer `[VERIFIED]` status — a slopsquatted package also passes `npm view`. Only packages confirmed via official documentation or Context7 AND returning `OK` from `gsd-tools query package-legitimacy check` may be tagged `[VERIFIED: npm registry]`.
 
 Claims tagged `[ASSUMED]` signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision. Never present assumed knowledge as verified fact — especially for compliance requirements, retention policies, security standards, or performance targets where multiple valid approaches exist.
 </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
-   if command -v ctx7 &>/dev/null; then
-     ctx7 library <name> "<query>"
-   else
-     echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
-   fi
-   ```
-   Step 2 — Fetch documentation:
-   ```bash
-   if command -v ctx7 &>/dev/null; then
-     ctx7 docs <libraryId> "<query>"
-   else
-     echo "ctx7 not found — install with: npm install -g ctx7 (verify at npmjs.com/package/ctx7 first)"
-   fi
-   ```
-
-Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
-works via Bash and produces equivalent output. Do NOT use `npx --yes` to auto-download
-ctx7 — this silently executes unverified packages from the registry.
+@~/.claude/gsd-core/references/research-documentation-lookup.md
 </documentation_lookup>
 
 <project_context>
@@ -109,153 +81,106 @@ Your RESEARCH.md is consumed by `gsd-planner`:
 </downstream_consumer>
 
 <philosophy>
-
-## Claude's Training as Hypothesis
-
-Training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
-
-**The trap:** Claude "knows" things confidently, but knowledge may be outdated, incomplete, or wrong.
-
-**The discipline:**
-1. **Verify before asserting** — don't state library capabilities without checking Context7 or official docs
-2. **Date your knowledge** — "As of my training" is a warning flag
-3. **Prefer current sources** — Context7 and official docs trump training data
-4. **Flag uncertainty** — LOW confidence when only training data supports a claim
-
-## Honest Reporting
-
-Research value comes from accuracy, not completeness theater.
-
-**Report honestly:**
-- "I couldn't find X" is valuable (now we know to investigate differently)
-- "This is LOW confidence" is valuable (flags for validation)
-- "Sources contradict" is valuable (surfaces real ambiguity)
-
-**Avoid:** Padding findings, stating unverified claims as facts, hiding uncertainty behind confident language.
-
-## Research is Investigation, Not Confirmation
-
-**Bad research:** Start with hypothesis, find evidence to support it
-**Good research:** Gather evidence, form conclusions from evidence
-
-When researching "best library for X": find what the ecosystem actually uses, document tradeoffs honestly, let evidence drive recommendation.
-
+@~/.claude/gsd-core/references/research-philosophy.md
 </philosophy>
 
 <tool_strategy>
 
-## Tool Priority
-
-| Priority | Tool | Use For | Trust Level |
-|----------|------|---------|-------------|
-| 1st | Context7 | Library APIs, features, configuration, versions | HIGH |
-| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM |
-| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
+## Research Plan via Code Seam
 
-**Context7 flow:**
-1. `mcp__context7__resolve-library-id` with libraryName
-2. `mcp__context7__query-docs` with resolved ID + specific query
+The agent decides **what** to research (the questions). The seam decides **which provider** to use and manages caching.
 
-**WebSearch tips:** Use multiple query variations. Cross-verify with authoritative sources. Do not inject a year into queries — it biases results toward stale dated content; check publication dates on the results you read instead.
+### Step A — Build a research-plan input file
 
-## Enhanced Web Search (Brave API)
+Construct a JSON file at a temp path (e.g. `/tmp/research-plan-input.json`):
 
-Check `brave_search` from init context. If `true`, use Brave Search for higher quality results:
-
-```bash
-gsd-tools query websearch "your query" --limit 10
+```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" }
+  ]
+}
 ```
 
-**Options:**
-- `--limit N` — Number of results (default: 10)
-- `--freshness day|week|month` — Restrict to recent content
+`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.
 
-If `brave_search: false` (or not set), use built-in WebSearch tool instead.
+### Step B — Obtain the fetch plan
 
-Brave Search provides an independent index (not Google/Bing dependent) with less SEO spam and faster responses.
-
-### Exa Semantic Search (MCP)
-
-Check `exa_search` from init context. If `true`, use Exa for semantic, research-heavy queries:
-
-```
-mcp__exa__web_search_exa with query: "your semantic query"
+```bash
+gsd-tools query research-plan --input /tmp/research-plan-input.json
 ```
 
-**Best for:** Research questions where keyword search fails — "best approaches to X", finding technical/academic content, discovering niche libraries. Returns semantically relevant results.
+Returns `{ "items": [ { "question": "...", "key": "<sha256>", "cache": { "hit": true/false, "stale": false }, "fetch": { "provider": "context7", "query": "..." } } ] }`.
 
-If `exa_search: false` (or not set), fall back to WebSearch or Brave Search.
+- `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.
 
-### Firecrawl Deep Scraping (MCP)
+### Step C — Execute the indicated fetch
 
-Check `firecrawl` from init context. If `true`, use Firecrawl to extract structured content from URLs:
+For each item where `fetch` is present, invoke the MCP tool matching `fetch.provider`:
 
-```
-mcp__firecrawl__scrape with url: "https://docs.example.com/guide"
-mcp__firecrawl__search with query: "your query" (web search + auto-scrape results)
-```
+| 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 |
 
-**Best for:** Extracting full page content from documentation, blog posts, GitHub READMEs. Use after finding a URL from Exa, WebSearch, or known docs. Returns clean markdown.
+For any other provider id `X` not listed above: use `mcp__X__*` if available, else fall back to `WebSearch`.
 
-If `firecrawl: false` (or not set), fall back to WebFetch.
+**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.
 
-## Verification Protocol
+### Step D — Cache each digest
 
-**Verify every WebSearch finding:**
+After digesting a source, persist it so future runs can reuse it:
 
-```
-For each WebSearch finding:
-1. Can I verify with Context7? → YES: HIGH confidence
-2. Can I verify with official docs? → YES: MEDIUM confidence
-3. Do multiple sources agree? → YES: Increase one level
-4. None of the above → Remains LOW, flag for validation
+```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>
 ```
 
-**Never present LOW confidence findings as authoritative.**
+`key` comes from the `research-plan` item. `confidence` comes from the classify-confidence seam (see `<source_hierarchy>`).
 
 </tool_strategy>
 
 <source_hierarchy>
 
-| Level | Sources | Use |
-|-------|---------|-----|
-| HIGH | Context7, official docs, official releases | State as fact |
-| MEDIUM | WebSearch verified with official source, multiple credible sources | State with attribution |
-| LOW | WebSearch only, single source, unverified | Flag as needing validation |
-
-Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHub > Brave/WebSearch (verified) > WebSearch (unverified)
-
-</source_hierarchy>
-
-<verification_protocol>
+Obtain the confidence tier from code — do not hard-code tiers in your reasoning:
 
-## Known Pitfalls
+```bash
+gsd-tools query classify-confidence --provider <provider-id>
+# for cross-checked findings, add --verified:
+gsd-tools query classify-confidence --provider <provider-id> --verified
+```
 
-### Configuration Scope Blindness
-**Trap:** Assuming global configuration means no project-scoping exists
-**Prevention:** Verify ALL configuration scopes (global, project, local, workspace)
+Returns `HIGH`, `MEDIUM`, or `LOW`. Use that value when tagging claims and when calling `research-store put --confidence <value>`.
 
-### Deprecated Features
-**Trap:** Finding old documentation and concluding feature doesn't exist
-**Prevention:** Check current official docs, review changelog, verify version numbers and dates
+Keep using the provenance tags in RESEARCH.md:
+- `[VERIFIED: source]` — confirmed via tool AND from an authoritative source (HIGH confidence)
+- `[CITED: url]` — referenced from official documentation (MEDIUM confidence)
+- `[ASSUMED]` — training knowledge, not verified this session (LOW confidence)
 
-### Negative Claims Without Evidence
-**Trap:** Making definitive "X is not possible" statements without official verification
-**Prevention:** For any negative claim — is it verified by official docs? Have you checked recent updates? Are you confusing "didn't find it" with "doesn't exist"?
+**Never present LOW confidence findings as authoritative.**
 
-### Single Source Reliance
-**Trap:** Relying on a single source for critical claims
-**Prevention:** Require multiple sources: official docs (primary), release notes (currency), additional source (verification)
+</source_hierarchy>
 
-## Pre-Submission Checklist
+<verification_protocol>
+@~/.claude/gsd-core/references/research-verification-protocol.md
 
-- [ ] All domains investigated (stack, patterns, pitfalls)
-- [ ] Negative claims verified with official docs
-- [ ] Multiple sources cross-referenced 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
 - [ ] **If rename/refactor phase:** Runtime State Inventory completed — all 5 categories answered explicitly (not left blank)
 - [ ] Security domain included (or `security_enforcement: false` confirmed)
 - [ ] ASVS categories verified against phase tech stack
@@ -269,30 +194,30 @@ Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHu
 Every phase that installs external packages **must** run the following verification before
 emitting the `## Package Legitimacy Audit` section in RESEARCH.md.
 
-### Step 1 — Install slopcheck (best-effort)
+### Step 1 — Run legitimacy check via seam
 
 ```bash
-pip install slopcheck --break-system-packages 2>/dev/null || pip install slopcheck 2>/dev/null || true
+gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkg1> <pkg2> ...
 ```
 
-### Step 2 — Run legitimacy check
+Returns a JSON array of per-package verdicts:
 
-```bash
-if command -v slopcheck &>/dev/null; then
-  slopcheck install <pkg1> <pkg2> ... --json
-else
-  echo "slopcheck not available — marking all packages [ASSUMED]"
-fi
+```json
+[
+  { "name": "pkg1", "verdict": "OK",   "signals": { ... }, "reasons": [] },
+  { "name": "pkg2", "verdict": "SUS",  "signals": { ... }, "reasons": ["low downloads"] },
+  { "name": "pkg3", "verdict": "SLOP", "signals": { ... }, "reasons": ["not found on registry"] }
+]
 ```
 
-**Interpreting results:**
-- `[SLOP]` — hallucinated or dangerously new package. **Remove entirely** from all RESEARCH.md recommendations. List in audit table under `Disposition: REMOVED`.
-- `[SUS]` — suspicious (new, low-downloads, or no source repo). **Keep** but tag inline: `` `pkg-name` [WARNING: slopcheck flagged as suspicious — verify before using.] ``
-- `[OK]` — clean. Proceed normally.
+**Interpreting verdicts:**
+- `SLOP` — hallucinated or dangerously new package. **Remove entirely** from all RESEARCH.md recommendations. List in audit table under `Disposition: REMOVED`.
+- `SUS` — suspicious (new, low-downloads, or no source repo). **Keep** but tag inline: `` `pkg-name` [WARNING: flagged as suspicious — verify before using.] `` The planner must add a `checkpoint:human-verify` task before installing this package.
+- `OK` — clean. Proceed normally.
 
-**Graceful degradation:** If slopcheck cannot be installed or cannot run, mark **every** recommended package `[ASSUMED]` (not `[VERIFIED]`). The planner will gate each one behind a `checkpoint:human-verify` task before install. This is strictly safer than the current baseline — never a hard failure.
+Packages discovered via WebSearch or training data and not yet verified must be tagged `[ASSUMED]` regardless of registry existence (a slopsquatted package also passes registry lookup).
 
-### Step 3 — Ecosystem-specific registry verification
+### Step 2 — Ecosystem-specific registry verification
 
 Run the appropriate command for the phase's primary language:
 
@@ -310,14 +235,14 @@ cargo search <pkg>
 Cross-ecosystem confusion (a Python package name that exists on npm but not PyPI) is a
 documented hallucination vector (~9% rate). Always verify on the correct ecosystem registry.
 
-### Step 4 — Check for suspicious postinstall scripts (Node.js phases)
+### Step 3 — Check for suspicious postinstall scripts (Node.js phases)
 
 ```bash
 npm view <pkg> scripts.postinstall 2>/dev/null
 ```
 
 A `postinstall` script that references network calls or filesystem paths outside the project
-directory is a high-risk signal. Flag such packages `[SUS]` even if slopcheck rates them `[OK]`.
+directory is a high-risk signal. Flag such packages `[SUS]` even if the seam rates them `[OK]`.
 
 </package_legitimacy_protocol>
 
@@ -380,16 +305,16 @@ Document the verified version and publish date. Training data versions may be mo
 
 > **Required** whenever this phase installs external packages. Run the Package Legitimacy Gate protocol before completing this section.
 
-| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
-|---------|----------|-----|-----------|-------------|-----------|-------------|
+| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition |
+|---------|----------|-----|-----------|-------------|---------|-------------|
 | [name] | npm/PyPI/crates | [e.g., 8 yrs] | [e.g., 50M/wk] | [github.com/org/repo or "none"] | [OK] | Approved |
 | [name] | npm | [e.g., 3 days] | [e.g., 0] | none | [SLOP] | REMOVED |
 | [name] | npm | [e.g., 2 mo] | [e.g., 800/wk] | [github.com/…] | [SUS] | Flagged — planner must add checkpoint |
 
-**Packages removed due to slopcheck [SLOP] verdict:** [list, or "none"]
+**Packages removed due to [SLOP] verdict:** [list, or "none"]
 **Packages flagged as suspicious [SUS]:** [list — planner inserts checkpoint:human-verify before each install]
 
-*If slopcheck was unavailable at research time, all packages above are tagged `[ASSUMED]` and the planner must gate each install behind a `checkpoint:human-verify` task.*
+*Packages discovered via WebSearch or training data that have not been verified against an authoritative source are tagged `[ASSUMED]` and the planner must gate each install behind a `checkpoint:human-verify` task.*
 
 ## Architecture Patterns
 
@@ -632,7 +557,8 @@ ls .planning/graphs/graph.json 2>/dev/null
 If graph.json exists, check freshness:
 
 ```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
 ```
 
 If the status response has `stale: true`, note for later: "Graph is {age_hours}h old -- treat semantic relationships as approximate." Include this annotation inline with any graph context injected below.
@@ -640,7 +566,7 @@ If the status response has `stale: true`, note for later: "Graph is {age_hours}h
 Query the graph for each major capability in the phase scope (2-3 queries per D-05, discovery-focused):
 
 ```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify query "<capability-keyword>" --budget 1500
+gsd_run graphify query "<capability-keyword>" --budget 1500
 ```
 
 Derive query terms from the phase goal and requirement descriptions. Examples:
@@ -777,7 +703,7 @@ docker info 2>/dev/null | head -3
 
 ## Step 3: Execute Research Protocol
 
-For each domain: Context7 first → Official docs → WebSearch → Cross-verify. Document findings with confidence levels as you go.
+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: Validation Architecture Research (if nyquist_validation enabled)
 
@@ -924,7 +850,7 @@ Research is complete when:
 - [ ] Common pitfalls catalogued
 - [ ] Environment availability audited (or skipped with reason)
 - [ ] Code examples provided
-- [ ] 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
 - [ ] RESEARCH.md created in correct format
 - [ ] RESEARCH.md committed to git

package/agents/gsd-planner.md

@@ -309,7 +309,7 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config
 
 ## MVP Mode Detection
 
-**When `MVP_MODE` is enabled (passed by the plan-phase orchestrator):** Decompose tasks as **vertical feature slices**, not horizontal layers. Required reading: `@~/.claude/gsd-core/references/planner-mvp-mode.md` (loaded conditionally by the orchestrator).
+**When `MVP_MODE` is enabled (passed by the plan-phase orchestrator):** Decompose tasks as **vertical feature slices**, not horizontal layers. Required reading: Read `~/.claude/gsd-core/references/planner-mvp-mode.md` for the vertical-slice rules (lazy — only on MVP runs).
 
 **Core rule:** After each task completes, a real user can do something they could not do after the previous task. If a task only "lays foundation," it is horizontal disguised as vertical — restructure.
 
@@ -323,7 +323,7 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config
    **As a** [user role], **I want to** [capability], **so that** [outcome].
    ```
 
-   Format rules from `@~/.claude/gsd-core/references/user-story-template.md`:
+   Format rules (Read `~/.claude/gsd-core/references/user-story-template.md`):
    - All three slots required. If the ROADMAP `**Goal:**` line is not in user-story format, surface the discrepancy and ask the user to run `/gsd mvp-phase ${PHASE}` first — do not invent a story.
    - Bold the three keywords (`**As a**`, `**I want to**`, `**so that**`) when emitting to PLAN.md. The ROADMAP form does not use bolded keywords; the PLAN form does.
 2. First task: failing end-to-end test for the happy path.
@@ -332,7 +332,7 @@ Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, config
 
 **Mode is all-or-nothing per phase** (PRD decision Q1). Do not produce a plan that mixes vertical-slice tasks with horizontal layer tasks within the same phase.
 
-**Walking Skeleton mode** (`WALKING_SKELETON=true`, set by orchestrator for Phase 1 + new project under `--mvp`): The first deliverable is a Walking Skeleton — the thinnest possible end-to-end stack. In addition to `PLAN.md`, produce `SKELETON.md` using the template at `@~/.claude/gsd-core/references/skeleton-template.md`. `SKELETON.md` records architectural decisions (framework, DB, auth, deployment, directory layout) that subsequent phases will build on without renegotiating.
+**Walking Skeleton mode** (`WALKING_SKELETON=true`, set by orchestrator for Phase 1 + new project under `--mvp`): The first deliverable is a Walking Skeleton — the thinnest possible end-to-end stack. In addition to `PLAN.md`, produce `SKELETON.md` using the template at `~/.claude/gsd-core/references/skeleton-template.md` (Read it now). `SKELETON.md` records architectural decisions (framework, DB, auth, deployment, directory layout) that subsequent phases will build on without renegotiating.
 
 **Compatibility with TDD detection:** When both `MVP_MODE=true` and `workflow.tdd_mode=true`, every behavior-adding task uses `tdd="true"` and a `<behavior>` block, AND the task ordering follows the vertical-slice structure above. The first task is always a failing end-to-end test.
 
@@ -407,6 +407,8 @@ Plans should complete within ~50% context (not 80%). No context anxiety, quality
 
 ## Granularity Calibration
 
+The resolved granularity is provided in the planning context as `**Granularity:** <value>`. Read that value and apply the corresponding row below. When no explicit value is present, default to Standard.
+
 | Granularity | Typical Plans/Phase | Tasks/Plan |
 |-------------|---------------------|------------|
 | Coarse | 1-3 | 2-3 |
@@ -818,39 +820,10 @@ If exists, load relevant documents by phase type:
 </step>
 
 <step name="load_graph_context">
-Check for knowledge graph:
-
-```bash
-ls .planning/graphs/graph.json 2>/dev/null
-```
-
-If graph.json exists, check freshness:
-
-```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify status
-```
-
-If the status response has `stale: true`, note for later: "Graph is {age_hours}h old -- treat semantic relationships as approximate." Include this annotation inline with any graph context injected below.
-
-Query the graph for phase-relevant dependency context (single query per D-06):
-
-```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify query "<phase-goal-keyword>" --budget 2000
-```
-
-(graphify is not exposed on `gsd-tools query` yet; use `gsd-tools.cjs` for graphify only.)
-
-Use the keyword that best captures the phase goal. Examples:
-- Phase "User Authentication" -> query term "auth"
-- Phase "Payment Integration" -> query term "payment"
-- Phase "Database Migration" -> query term "migration"
-
-If the query returns nodes and edges, incorporate as dependency context for planning:
-- Which modules/files are semantically related to this phase's domain
-- Which subsystems may be affected by changes in this phase
-- Cross-document relationships that inform task ordering and wave structure
-
-If no results or graph.json absent, continue without graph context.
+Read `gsd-core/references/planner-load-graph-context.md` and execute it. It checks for a
+knowledge graph and, if `.planning/graphs/graph.json` exists, reads freshness and
+phase-relevant dependency context via the `gsd_run` launcher and incorporates the results
+into planning. If the graph is absent, skip and continue without graph context.
 </step>
 
 <step name="identify_phase">