feat(sdd): add configurable search strategy for code-reading phases

internal/assets/skills/_shared/persistence-contract.md

@@ -85,6 +85,20 @@ Why this split:
 - Sub-agents read for SDD: SDD artifacts are large; inlining them in the orchestrator prompt would consume the entire context window
 - Sub-agents always write: they have the complete detail on what happened; nuance is lost by the time results flow back to the orchestrator
 
+## Search Strategy Context
+
+The orchestrator MAY pass `search_strategy` config to sub-agents that read code. This is optional — phases MUST default to `grep` behavior when absent.
+
+```yaml
+search_strategy:
+  mode: grep | hybrid          # default: grep (current behavior)
+  rag:                          # present only when mode: hybrid
+    mcp_tool: "tool_name"       # MCP tool name for semantic search (REQUIRED for hybrid)
+    reindex_tool: "tool_name"   # optional — fire-and-forget after sdd-apply batch
+```
+
+Sub-agents that receive this config follow **Section E** from `sdd-phase-common.md` for code search. Sub-agents that do NOT read code (sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-archive) ignore this config entirely.
+
 ## Orchestrator Prompt Instructions for Sub-Agents
 
 Non-SDD:

internal/assets/skills/_shared/sdd-phase-common.md

@@ -87,3 +87,62 @@ Example:
 **Skill Resolution**: injected — 3 skills (react-19, typescript, tailwind-4)
 (other values: `fallback-registry`, `fallback-path`, or `none — no registry found`)
 ```
+
+## E. Code Search Protocol
+
+Phases that investigate or read existing code (`sdd-explore`, `sdd-apply`, `sdd-verify`) MUST follow this protocol instead of ad-hoc Grep+Read.
+
+### Reading the config
+
+```
+Read search_strategy from project context:
+├── engram: included in sdd-init/{project} observation → search_strategy block
+├── openspec: openspec/config.yaml → search_strategy key
+└── Not found → default to mode=grep (current behavior, zero change)
+```
+
+### Mode behavior
+
+| Mode | Behavior |
+|------|----------|
+| `grep` | Current behavior — Grep + Read. No RAG tool calls. Default when config is absent. |
+| `hybrid` | RAG-first cascade with grep fallback. Requires `search_strategy.rag.mcp_tool`. |
+
+If `mode` is `hybrid` but `rag.mcp_tool` is missing or empty, fall back to `grep` and include a warning in the return envelope's `risks` field.
+
+### Hybrid cascade
+
+```
+1. Semantic query → call configured mcp_tool with a natural-language description
+   of what you're looking for
+   ├── Results sufficient (≥2 relevant snippets)? → use them, done
+   └── Results insufficient or empty?
+       ↓
+2. Exact search → Grep for symbols, patterns, or file paths
+   ├── Context clear from matches? → done
+   └── Need surrounding context?
+       ↓
+3. Targeted read → Read with specific line range (NOT full files)
+```
+
+Each step is strictly additive — the cascade never produces worse results than grep-only.
+
+### Grep-only path (mode=grep or missing)
+
+Use Grep to find relevant code, then Read with targeted line ranges. This is identical to current behavior. No RAG tool is called.
+
+### When RAG tool is unavailable at runtime
+
+If `mode` is `hybrid` but the MCP tool call fails (tool not found, server down, timeout):
+1. Log the failure
+2. Fall back to grep behavior for the remainder of this phase
+3. Include in return envelope `risks`: "RAG search unavailable, fell back to grep — consider checking MCP server status"
+
+### Reindex hook (sdd-apply only)
+
+After completing artifact persistence in sdd-apply, IF `search_strategy.rag.reindex_tool` is configured:
+1. Call `reindex_tool` once with the list of files modified in this batch
+2. Fire-and-forget — do NOT wait for completion, do NOT block on the result
+3. If the call fails, log it and continue — grep fallback guarantees correctness
+
+Do NOT call reindex per individual file write. One call per batch only.

internal/assets/skills/sdd-apply/SKILL.md

@@ -39,7 +39,7 @@ Follow **Section A** from `skills/_shared/sdd-phase-common.md`.
 Before writing ANY code:
 1. Read the specs — understand WHAT the code must do
 2. Read the design — understand HOW to structure the code
-3. Read existing code in affected files — understand current patterns
+3. Read `search_strategy` from project context (per Section E's "Reading the config" procedure) — cache the result; it is reused by the reindex hook in Step 6. Then read existing code in affected files following **Section E** from `skills/_shared/sdd-phase-common.md` for code search (uses hybrid cascade if configured, grep otherwise)
 4. Check the project's coding conventions from `config.yaml`
 
 #### Step 2b: Read Previous Apply-Progress (if exists)
@@ -131,6 +131,10 @@ When saving apply-progress:
 2. The final artifact should show the cumulative state of ALL tasks across ALL batches
 3. Format: keep the same structure but ensure no completed task is lost from prior batches
 
+#### Reindex Hook (Section E)
+
+After persisting apply-progress, follow the reindex hook protocol from Section E of `sdd-phase-common.md`. Use the `search_strategy` config cached in Step 2.
+
 ### Step 7: Return Summary
 
 Return to the orchestrator:

internal/assets/skills/sdd-explore/SKILL.md

@@ -49,16 +49,18 @@ Parse what the user wants to explore:
 
 ### Step 3: Investigate the Codebase
 
-Read relevant code to understand:
+Read `search_strategy` from project context (per Section E's "Reading the config" procedure) to determine whether to use grep-only or hybrid (RAG+grep) mode. Then follow **Section E** from `skills/_shared/sdd-phase-common.md` for all code search operations.
+
+Understand:
 - Current architecture and patterns
 - Files and modules that would be affected
 - Existing behavior that relates to the request
 - Potential constraints or risks
 
 ```
 INVESTIGATE:
-├── Read entry points and key files
-├── Search for related functionality
+├── Search for related functionality (via Section E cascade)
+├── Read entry points and key files (targeted line ranges, not full files)
 ├── Check existing tests (if any)
 ├── Look for patterns already in use
 └── Identify dependencies and coupling

internal/assets/skills/sdd-init/SKILL.md

@@ -117,6 +117,39 @@ Determine whether Strict TDD Mode should be enabled. The resolution follows a pr
 
 **Do NOT ask the user interactively.** The preference is resolved from existing config. If the user wants to change it, they run `gentle-ai sync` with the TUI or set `strict_tdd` in `openspec/config.yaml`.
 
+### Step 3.5: Detect Search Strategy
+
+Detect whether a RAG-capable MCP tool is available for semantic code search. The resolution follows the SAME priority chain as Strict TDD Mode — first match wins:
+
+```
+1. Read from system prompt / agent config (highest priority):
+   ├── Search for "search_strategy" marker in the agent's system prompt file
+   │   (e.g., CLAUDE.md, GEMINI.md, .cursorrules, etc.)
+   ├── If found → use the configured mode value
+   └── This is the preference set by the user in the gentle-ai TUI
+
+2. If no marker found, check openspec config:
+   ├── Read openspec/config.yaml → search_strategy block
+   └── If found → use that value
+
+3. If nothing found, auto-detect MCP tools:
+   ├── Scan available MCP tools for RAG-capable entries
+   │   (look for names/descriptions suggesting semantic/vector code search,
+   │    e.g., "rag_query", "code_search", "semantic_search", "project_rag")
+   ├── RAG tool found:
+   │   ├── search_strategy.mode: hybrid
+   │   ├── search_strategy.rag.mcp_tool: {tool_name}
+   │   └── If a companion reindex tool is detected (same prefix or explicit "reindex" name):
+   │       └── search_strategy.rag.reindex_tool: {reindex_tool_name}
+   └── No RAG tool found:
+       ├── search_strategy.mode: grep
+       └── grep is the silent default — do NOT prompt the user
+```
+
+**Do NOT ask the user interactively.** The preference is resolved from existing config or auto-detection. If the user wants to change it, they set `search_strategy` in `openspec/config.yaml` or run `gentle-ai sync` with the TUI.
+
+The resolved `search_strategy` config is persisted alongside `strict_tdd` in Step 8 (engram), Step 5 (openspec config), or both (hybrid).
+
 ### Step 4: Initialize Persistence Backend
 
 If mode resolves to `openspec`, create this directory structure:
@@ -145,6 +178,13 @@ context: |
 
 strict_tdd: {true/false}
 
+search_strategy:
+  mode: {grep/hybrid}            # default: grep (from Step 3.5)
+  # Uncomment and fill when mode is hybrid (detected in Step 3.5):
+  # rag:
+  #   mcp_tool: "{tool_name}"     # MCP tool name for semantic search
+  #   reindex_tool: "{tool_name}" # optional — fire-and-forget after sdd-apply batch
+
 rules:
   proposal:
     - Include rollback plan for risky changes
@@ -241,7 +281,7 @@ mem_save(
   topic_key: "sdd-init/{project-name}",
   type: "architecture",
   project: "{project-name}",
-  content: "{your detected project context from Steps 1-7}"
+  content: "{your detected project context from Steps 1-7, including search_strategy from Step 3.5}"
 )
 ```
 
@@ -265,6 +305,7 @@ Return:
 **Stack**: {detected stack}
 **Persistence**: engram
 **Strict TDD Mode**: {enabled ✅ / disabled ❌ / unavailable (no test runner)}
+**Search Strategy**: {grep (default) / hybrid — {rag.mcp_tool}}
 
 ### Testing Capabilities
 | Capability | Status |
@@ -306,6 +347,7 @@ Ready for /sdd-explore <topic> or /sdd-new <change-name>.
 **Stack**: {detected stack}
 **Persistence**: openspec
 **Strict TDD Mode**: {enabled ✅ / disabled ❌ / unavailable (no test runner)}
+**Search Strategy**: {grep (default) / hybrid — {rag.mcp_tool}}
 
 ### Testing Capabilities
 {same table as above}
@@ -327,6 +369,7 @@ Ready for /sdd-explore <topic> or /sdd-new <change-name>.
 **Stack**: {detected stack}
 **Persistence**: none (ephemeral)
 **Strict TDD Mode**: {enabled ✅ / disabled ❌ / unavailable (no test runner)}
+**Search Strategy**: {grep (default) / hybrid — {rag.mcp_tool}}
 
 ### Testing Capabilities
 {same table as above}

internal/assets/skills/sdd-verify/SKILL.md

@@ -76,11 +76,13 @@ Read tasks.md
 
 ### Step 4: Check Correctness (Static Specs Match)
 
+Read `search_strategy` from project context (per Section E's "Reading the config" procedure). Then follow **Section E** from `skills/_shared/sdd-phase-common.md` for all code search operations. Use the hybrid cascade (RAG+grep) if configured, or grep-only otherwise.
+
 For EACH spec requirement and scenario, search the codebase for structural evidence:
 
 ```
 FOR EACH REQUIREMENT in specs/:
-├── Search codebase for implementation evidence
+├── Search codebase for implementation evidence (via Section E cascade)
 ├── For each SCENARIO:
 │   ├── Is the GIVEN precondition handled in code?
 │   ├── Is the WHEN action implemented?

testdata/golden/sdd-antigravity-skill-sdd-init.golden

@@ -117,6 +117,39 @@ Determine whether Strict TDD Mode should be enabled. The resolution follows a pr
 
 **Do NOT ask the user interactively.** The preference is resolved from existing config. If the user wants to change it, they run `gentle-ai sync` with the TUI or set `strict_tdd` in `openspec/config.yaml`.
 
+### Step 3.5: Detect Search Strategy
+
+Detect whether a RAG-capable MCP tool is available for semantic code search. The resolution follows the SAME priority chain as Strict TDD Mode — first match wins:
+
+```
+1. Read from system prompt / agent config (highest priority):
+   ├── Search for "search_strategy" marker in the agent's system prompt file
+   │   (e.g., CLAUDE.md, GEMINI.md, .cursorrules, etc.)
+   ├── If found → use the configured mode value
+   └── This is the preference set by the user in the gentle-ai TUI
+
+2. If no marker found, check openspec config:
+   ├── Read openspec/config.yaml → search_strategy block
+   └── If found → use that value
+
+3. If nothing found, auto-detect MCP tools:
+   ├── Scan available MCP tools for RAG-capable entries
+   │   (look for names/descriptions suggesting semantic/vector code search,
+   │    e.g., "rag_query", "code_search", "semantic_search", "project_rag")
+   ├── RAG tool found:
+   │   ├── search_strategy.mode: hybrid
+   │   ├── search_strategy.rag.mcp_tool: {tool_name}
+   │   └── If a companion reindex tool is detected (same prefix or explicit "reindex" name):
+   │       └── search_strategy.rag.reindex_tool: {reindex_tool_name}
+   └── No RAG tool found:
+       ├── search_strategy.mode: grep
+       └── grep is the silent default — do NOT prompt the user
+```
+
+**Do NOT ask the user interactively.** The preference is resolved from existing config or auto-detection. If the user wants to change it, they set `search_strategy` in `openspec/config.yaml` or run `gentle-ai sync` with the TUI.
+
+The resolved `search_strategy` config is persisted alongside `strict_tdd` in Step 8 (engram), Step 5 (openspec config), or both (hybrid).
+
 ### Step 4: Initialize Persistence Backend
 
 If mode resolves to `openspec`, create this directory structure:
@@ -145,6 +178,13 @@ context: |
 
 strict_tdd: {true/false}
 
+search_strategy:
+  mode: {grep/hybrid}            # default: grep (from Step 3.5)
+  # Uncomment and fill when mode is hybrid (detected in Step 3.5):
+  # rag:
+  #   mcp_tool: "{tool_name}"     # MCP tool name for semantic search
+  #   reindex_tool: "{tool_name}" # optional — fire-and-forget after sdd-apply batch
+
 rules:
   proposal:
     - Include rollback plan for risky changes
@@ -241,7 +281,7 @@ mem_save(
   topic_key: "sdd-init/{project-name}",
   type: "architecture",
   project: "{project-name}",
-  content: "{your detected project context from Steps 1-7}"
+  content: "{your detected project context from Steps 1-7, including search_strategy from Step 3.5}"
 )
 ```
 
@@ -265,6 +305,7 @@ Return:
 **Stack**: {detected stack}
 **Persistence**: engram
 **Strict TDD Mode**: {enabled ✅ / disabled ❌ / unavailable (no test runner)}
+**Search Strategy**: {grep (default) / hybrid — {rag.mcp_tool}}
 
 ### Testing Capabilities
 | Capability | Status |
@@ -306,6 +347,7 @@ Ready for /sdd-explore <topic> or /sdd-new <change-name>.
 **Stack**: {detected stack}
 **Persistence**: openspec
 **Strict TDD Mode**: {enabled ✅ / disabled ❌ / unavailable (no test runner)}
+**Search Strategy**: {grep (default) / hybrid — {rag.mcp_tool}}
 
 ### Testing Capabilities
 {same table as above}
@@ -327,6 +369,7 @@ Ready for /sdd-explore <topic> or /sdd-new <change-name>.
 **Stack**: {detected stack}
 **Persistence**: none (ephemeral)
 **Strict TDD Mode**: {enabled ✅ / disabled ❌ / unavailable (no test runner)}
+**Search Strategy**: {grep (default) / hybrid — {rag.mcp_tool}}
 
 ### Testing Capabilities
 {same table as above}