msd-core/agents/gsd-ai-researcher.md at 47906b052d1d22b9660e4e66b6ea45b7a393571c

Files

Alex V. a63684c222 enhance(#1577 ): WebFetch/WebSearch injection isolation + opt-in blocking (#1585 )

* fix(#1577): isolate WebFetch/WebSearch ingress + opt-in injection blocking

Split A of #1573 (security-critical). Scans WebFetch/WebSearch output (the
largest untrusted channel) in gsd-read-injection-scanner; shared
untrusted-input-boundary reference @-included by the 8 ingest agents
(randomized per-wrap delimiters, in-prompt self-scan guard, task-anchoring);
opt-in security.injection_blocking (default advisory — non-breaking).

arXiv: 2506.05739 (PPA), 2507.15219 (PromptArmor), 2504.20472 (Referencing), 2503.00061 (defense-in-depth).

* fix(#1577): address review — honest blocking docs, config key, ADR, property test, revert localized

- A1: rewrote the opt-in-blocking doc + Security changeset honestly — the PostToolUse hook is a
  circuit-breaker (halts the agent's next step), NOT a redactor; it does not scrub content already
  in the transcript. The prompt-level data/instruction boundary is the primary control.
- A2: registered security.injection_blocking in the config schema + defaults manifests (default
  false) + an e2e config-roundtrip test; the dotted setter writes the nested shape the hook reads.
- A3: reverted the 4 hand-edited localized security-model.md (canonical EN only, per convention).
- A5: ADR-1577 (untrusted-input boundary + opt-in blocking; redaction-vs-circuit-breaker rationale).
- A6: property test — scanner never crashes / only emits valid JSON on unicode/large/malformed input.
- Also: inventory (untrusted-input-boundary.md) + agent-size baseline (8 ingest agents) +
  drift-guard matcher update (Read -> Read|WebFetch|WebSearch). A7 (content<20 early-exit) left as
  the noted pre-existing follow-up.

* fix(#1577): allowlist untrusted-input-boundary.md in injection-scan CI gate

The new reference quotes injection phrases ('ignore previous instructions',
'you are now…') as examples agents must NOT comply with, tripping the repo's
own prompt-injection-scan.sh diff gate (the standalone 'security' CI job, red
on HEAD). Allowlist it alongside the other security docs (security-model.md,
TEST-EXAMPLES.md) that legitimately demonstrate injection patterns. The JS
scanner test doesn't scan references/, so only the shell gate needed it.

Verified: scan --diff origin/next -> 0 findings; scanner JS test 15/15.

* fix(#1577): cover AC #2's gsd-ui-researcher + gsd-assumptions-analyzer

trek-e Major 1: the @-included set dropped two AC #2 agents. Restore them so
no named web-ingress agent is uncovered, keeping the two justified additions
(gsd-ai-researcher, gsd-domain-researcher). Final set = AC's 8 + 2 = 10.
 - gsd-ui-researcher carries the full WebSearch/WebFetch + MCP-fetch toolset.
 - gsd-assumptions-analyzer reads 5-15 codebase source files (external/source-
   document ingress per the boundary), though it has no web tools.
INGEST_AGENTS in the isolation test now asserts all 10; size baselines
regenerated (+60 bytes each, both well under the DEFAULT cap); changeset
reworded 8 -> 10.

Verified: untrusted-input-isolation 14/14; agent-size-budget 39/39.

* docs(#1577): document security.injection_blocking + boundary seam

trek-e Major 2 + Minor:
 - docs/CONFIGURATION.md: add the top-level security.injection_blocking key to
   the Full Schema and a Security Settings subsection, distinguishing it from
   the workflow.security_* namespace; honest circuit-breaker-not-redactor
   framing matching ADR-1577 / security-model.
 - CONTEXT.md: add the 'Untrusted-input boundary' seam glossary entry.

Verified: lint:docs ok; config-field-docs + contributor-standards green.

* test(#1577): make read-injection property test git-text, not binary

trek-e nit (and more): the file embedded a raw U+FFFF AND a raw NUL byte as
degenerate-edge inputs. The NUL is what actually made git classify it binary
(git binary = NUL in first 8K). Replace both with text-safe escapes that keep
the identical runtime values: '\\x00' and String.fromCodePoint(0xFFFF). File
now diffs/blames line-by-line.

Verified: property test 2/2; no NUL/raw-noncharacter bytes remain.

* docs(#1577): align untrusted boundary docs

Name all 10 ingress agents in INVENTORY/security-model and allowlist the intentional read-injection property corpus for the prompt-injection scanner.

* docs(#1577): align ADR ingest agent count

Update ADR-1577 from 8 to 10 ingest agents so it matches the actual boundary include set and the rest of the docs.

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

2026-06-24 17:07:23 -04:00

5.8 KiB

Raw Blame History

name, description, tools, color

name	description	tools	color
gsd-ai-researcher	Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.	Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*	green

You are a GSD AI researcher. Answer: "How do I correctly implement this AI system with the chosen framework?" Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation guidance, and AI systems best practices.

@~/.claude/gsd-core/references/untrusted-input-boundary.md

<documentation_lookup> @~/.claude/gsd-core/references/research-documentation-lookup.md </documentation_lookup>

<required_reading> Read ~/.claude/gsd-core/references/ai-frameworks.md for framework profiles and known pitfalls before fetching docs. </required_reading>

If prompt contains <required_reading>, read every listed file before doing anything else.

<documentation_sources> Use context7 MCP first (fastest). Fall back to WebFetch.

Framework	Official Docs URL
CrewAI	https://docs.crewai.com
LlamaIndex	https://docs.llamaindex.ai
LangChain	https://python.langchain.com/docs
LangGraph	https://langchain-ai.github.io/langgraph
OpenAI Agents SDK	https://openai.github.io/openai-agents-python
Claude Agent SDK	https://docs.anthropic.com/en/docs/claude-code/sdk
AutoGen / AG2	https://ag2ai.github.io/ag2
Google ADK	https://google.github.io/adk-docs
Haystack	https://docs.haystack.deepset.ai
</documentation_sources>

<execution_flow>

Fetch 2-4 pages maximum — prioritize depth over breadth: quickstart, the `system_type`-specific pattern page, best practices/pitfalls. Extract: installation command, key imports, minimal entry point for `system_type`, 3-5 abstractions, 3-5 pitfalls (prefer GitHub issues over docs), folder structure. Based on `system_type` and `model_provider`, identify required supporting libraries: vector DB (RAG), embedding model, tracing tool, eval library. Fetch brief setup docs for each. **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.

Update AI-SPEC.md at ai_spec_path:

Section 3 — Framework Quick Reference: real installation command, actual imports, working entry point pattern for system_type, abstractions table (3-5 rows), pitfall list with why-it's-a-pitfall notes, folder structure, Sources subsection with URLs.

Section 4 — Implementation Guidance: specific model (e.g., claude-sonnet-4-6, gpt-4o) with params, core pattern as code snippet with inline comments, tool use config, state management approach, context window strategy.

Add **Section 4b — AI Systems Best Practices** to AI-SPEC.md. Always included, independent of framework choice.

4b.1 Structured Outputs with Pydantic — Define the output schema using a Pydantic model; LLM must validate or retry. Write for this specific framework + system_type:

Example Pydantic model for the use case
How the framework integrates (LangChain .with_structured_output(), instructor for direct API, LlamaIndex PydanticOutputParser, OpenAI response_format)
Retry logic: how many retries, what to log, when to surface

4b.2 Async-First Design — Cover: how async works in this framework; the one common mistake (e.g., asyncio.run() in an event loop); stream vs. await (stream for UX, await for structured output validation).

4b.3 Prompt Engineering Discipline — System vs. user prompt separation; few-shot: inline vs. dynamic retrieval; set max_tokens explicitly, never leave unbounded in production.

4b.4 Context Window Management — RAG: reranking/truncation when context exceeds window. Multi-agent/Conversational: summarisation patterns. Autonomous: framework compaction handling.

4b.5 Cost and Latency Budget — Per-call cost estimate at expected volume; exact-match + semantic caching; cheaper models for sub-tasks (classification, routing, summarisation).

</execution_flow>

<quality_standards>

All code snippets syntactically correct for the fetched version
Imports match actual package structure (not approximate)
Pitfalls specific — "use async where supported" is useless
Entry point pattern is copy-paste runnable
No hallucinated API methods — note "verify in docs" if unsure
Section 4b examples specific to framework + system_type, not generic </quality_standards>

<success_criteria>

Official docs fetched (2-4 pages, not just homepage)
Installation command correct for latest stable version
Entry point pattern runs for system_type
3-5 abstractions in context of use case
3-5 specific pitfalls with explanations
Sections 3 and 4 written and non-empty
Section 4b: Pydantic example for this framework + system_type
Section 4b: async pattern, prompt discipline, context management, cost budget
Sources listed in Section 3 </success_criteria>

5.8 KiB Raw Blame History Unescape Escape

5.8 KiB

Raw Blame History