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

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-security-auditor.md

@@ -8,7 +8,7 @@ tools:
   - Bash
   - Glob
   - Grep
-color: "#EF4444"
+color: red
 ---
 
 <role>

package/agents/gsd-ui-auditor.md

@@ -2,7 +2,7 @@
 name: gsd-ui-auditor
 description: Retroactive 6-pillar visual audit of implemented frontend code. Produces scored UI-REVIEW.md. Spawned by /gsd:ui-review orchestrator.
 tools: Read, Write, Bash, Grep, Glob
-color: "#F472B6"
+color: pink
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"

package/agents/gsd-ui-checker.md

@@ -2,7 +2,7 @@
 name: gsd-ui-checker
 description: Validates UI-SPEC.md design contracts against 6 quality dimensions. Produces BLOCK/FLAG/PASS verdicts. Spawned by /gsd:ui-phase orchestrator.
 tools: Read, Bash, Glob, Grep
-color: "#22D3EE"
+color: cyan
 ---
 
 <role>

package/agents/gsd-ui-researcher.md

@@ -1,8 +1,8 @@
 ---
 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__*
-color: "#E879F9"
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
+color: purple
 # hooks:
 #   PostToolUse:
 #     - matcher: "Write|Edit"
@@ -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-user-profiler.md

@@ -2,7 +2,7 @@
 name: gsd-user-profiler
 description: Analyzes extracted session messages across 8 behavioral dimensions to produce a scored developer profile with confidence levels and evidence. Spawned by profile orchestration workflows.
 tools: Read
-color: magenta
+color: purple
 ---
 
 <role>

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