@voybio/ace-swarm 0.1.0

package/assets/.agents/skills/codesnipe/references/dual-codebase-playbook.md

@@ -0,0 +1,671 @@
+---
+name: codesnipe
+description: 
+  Dual-codebase precision comparison via ast-grep. Builds a symbol registry for YOUR (HOME) codebase first, then surgically snipes a TARGET codebase to find what is relevant, inspiring, addable, or comparable — scored and ranked before a single implementation line is read. Companion to codemunch; where codemunch holistically maps one codebase, codesnipe triangulates two.
+---
+
+# CodeSnipe — Dual-Codebase Precision Intelligence
+
+**IMPORTANT**: CodeSnipe is NOT a code reader. It is a code comparator. Before reading
+a single implementation line from the TARGET, you MUST first build a symbol registry
+of the HOME codebase. Every TARGET symbol you retrieve must first earn a relevance score
+against the HOME registry. Low-scoring symbols are DISCARDED — not read, not summarised,
+not discussed. The sniper does not spray. The sniper fires once, and only at verified targets.
+
+**The Two-Question Contract** (borrowed from jcodemunch-mcp's dual-server philosophy):
+1. "What does TARGET *do* relative to HOME?" — answered by OUTLINE phase only.
+2. "How does TARGET *do it*?" — answered only for symbols that scored ≥ 8 in relevance.
+
+Reading a symbol that scored < 8 is a token waste and a protocol violation.
+
+---
+
+## 0. ACE Role Declaration
+
+CodeSnipe operates as a `capability-research` module with a **comparative output contract**.
+
+- **Emits** `SOURCE_VALIDATED` events per symbol snipe (with relevance score attached).
+- **Emits** `GATE_FAILED` if the HOME registry is empty when TARGET sniping begins.
+- **Writes** to `./agent-state/snipe/` (separate namespace from codemunch artifacts).
+- **Blocks** downstream modules from acting on TARGET patterns that lack HOME context.
+- **Hands off** via `HANDOFF.json` once `SNIPE_COMPARISON.md` is locked and scored.
+
+ACE Clarity Protocol headers must be used at each phase boundary.
+
+---
+
+## 0.1 MICE Boundaries
+
+| Rule | Enforcement |
+|---|---|
+| **Modular** | Compares codebases at symbol level; does NOT modify HOME or TARGET code. |
+| **Interoperable** | All findings written as standardized artifacts in `./agent-state/snipe/`. |
+| **Customizable** | Intent parameter (`steal/compare/debug/integrate`) controls scoring weights. |
+| **Extensible** | New comparison criteria added via scoring formula weights, not ad-hoc rules. |
+
+## 0.2 Goal Orientation
+
+- `DELETE_PROTOCOL`: Discard all TARGET symbols scoring < 8. No token waste on irrelevant code.
+- `ARTIFACT_PROTOCOL`: Session MUST produce `SNIPE_COMPARISON.md` minimum. No artifact = failed session.
+- `AGENCY_PROTOCOL`: HOME registry drives all TARGET queries. Never read TARGET without HOME context.
+
+
+
+---
+
+## 1. The Dual-Context Model
+
+Every CodeSnipe session operates with two explicit roles:
+
+```
+HOME  = the codebase you OWN, MAINTAIN, or are WORKING ON.
+        Source of truth for "what we already do."
+
+TARGET = the codebase you are STUDYING, COMPARING AGAINST, or DRAWING FROM.
+         Source of potential patterns, ideas, missing features, or alternative
+         implementations.
+```
+
+**The Relevance Score** gates all TARGET reads:
+
+| Score | Signal | Action |
+|---|---|---|
+| 20 | Exact symbol name match in HOME | Read TARGET implementation; direct comparison possible |
+| 12–19 | Structural/semantic overlap with HOME | Read TARGET implementation; likely inspiration or divergence |
+| 8–11 | Partial name or pattern overlap | Read signature only; decide before reading body |
+| 4–7 | Weak thematic connection | Log to KNOWN_UNKNOWNS; do not read |
+| 0–3 | No meaningful connection to HOME | Discard |
+
+The scoring formula (adapted from jcodemunch-mcp's weighted search):
+```
+score = 0
+score += 20  if exact name match (HOME symbol name == TARGET symbol name)
+score += 10  if name substring match
+score += 5   per shared word in name
+score += 8   if full signature pattern match (same function shape)
+score += 4   if return type matches a HOME type
+score += 3   if parameter types overlap with HOME types
+score += 5   if TARGET docstring mentions a concept present in HOME
+score += 2   per shared decorator/attribute
+```
+
+Compute this BEFORE running any `ast-grep` pattern to read an implementation.
+
+---
+
+## 2. The Snipe Socratic Stack
+
+Run this stack in order. **The first question you cannot answer from the HOME registry
+is your first ast-grep snipe into the TARGET.**
+
+**Tier 0 — Establish HOME Baseline**
+1. What symbols does HOME export publicly? (functions, types, classes, constants)
+2. What are HOME's primary design patterns? (builder, registry, pipeline, actor, etc.)
+3. What problems does HOME solve? (one sentence per module)
+4. Where are HOME's extension/plugin points?
+5. What does HOME conspicuously NOT do? (known gaps, TODOs, deferred features)
+
+**Tier 1 — Profile TARGET at Outline Level**
+6. What languages and structure does TARGET use?
+7. What is TARGET's stated purpose? Does it overlap with HOME's domain?
+8. What public symbols does TARGET expose? (names only — no implementations yet)
+9. Which TARGET symbol names appear verbatim or approximately in HOME?
+10. Which TARGET module names map to HOME module names?
+
+**Tier 2 — Score and Rank**
+11. Which TARGET symbols scored ≥ 12 against HOME? (prime snipe candidates)
+12. Which TARGET symbols represent concepts HOME has TODOs for?
+13. Which TARGET patterns appear 3+ times but are absent from HOME?
+14. Does TARGET solve any HOME Tier-5 Socratic question (known gaps)?
+
+**Tier 3 — Precision Extraction (only for score ≥ 8 symbols)**
+15. How does TARGET implement the high-score symbol? (read body now)
+16. What does TARGET do that HOME does differently? (divergence analysis)
+17. Is TARGET's approach adoptable in HOME's architecture without breaking changes?
+18. What would adoption cost? (new dependencies, refactors, interface changes)
+
+> **Rule**: Write every scored symbol into `SNIPE_RELEVANCE_MAP.md` immediately.
+> A symbol discussed without a recorded score is a protocol violation.
+
+---
+
+## 3. Execution Protocol
+
+### Phase 0 — HOME Registry Build `[STATE_ANALYSIS]`
+
+**Never skip this phase.** No TARGET sniping without a complete HOME registry.
+
+**Step 1 — HOME public API surface**
+```bash
+# Rust
+ast-grep --pattern 'pub fn $NAME($$$)' --lang rust --json | \
+  jq '.[] | {name: .metaVariables.NAME, file: .file, line: .range.start.line}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+
+ast-grep --pattern 'pub struct $NAME' --lang rust --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "struct", file: .file}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+
+ast-grep --pattern 'pub trait $NAME' --lang rust --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "trait", file: .file}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+
+# Python
+ast-grep --pattern 'def $NAME($$$):' --lang python --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "function", file: .file}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+
+ast-grep --pattern 'class $NAME:' --lang python --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "class", file: .file}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+
+# TypeScript / JavaScript
+ast-grep --pattern 'export function $NAME($$$)' --lang ts --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "function", file: .file}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+
+ast-grep --pattern 'export class $NAME' --lang ts --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "class", file: .file}' \
+  >> ./agent-state/snipe/HOME_REGISTRY.jsonl
+```
+
+**Step 2 — HOME gap map (known unknowns)**
+```bash
+# Extract TODOs, FIXMEs, unimplemented stubs — these are prime adoption targets
+grep -rn "TODO\|FIXME\|HACK\|unimplemented!\|todo!()" \
+  --include="*.rs" --include="*.py" --include="*.ts" \
+  | grep -v ".git" | head -50 \
+  >> ./agent-state/snipe/HOME_GAP_MAP.txt
+
+# Rust: unimplemented/todo macros (structural, not comment)
+ast-grep --pattern 'unimplemented!()' --lang rust
+ast-grep --pattern 'todo!()' --lang rust
+```
+
+**Step 3 — HOME pattern fingerprint**
+```bash
+# What recurring structural patterns define HOME's style?
+# Rust: error enum pattern
+ast-grep --pattern 'pub enum $NAME { $$$ }' --lang rust | grep -i "err\|Error\|Fail"
+
+# Rust: Result-returning public functions (count as percentage of all pub fns)
+ast-grep --pattern 'pub fn $NAME($$$) -> Result<$$$>' --lang rust
+
+# Python: decorator usage (marks framework patterns)
+ast-grep --pattern '@$DECORATOR' --lang python --json | \
+  jq -r '.[] | .metaVariables.DECORATOR' | sort | uniq -c | sort -rn | head -15
+```
+
+**Output**: Write `SNIPE_HOME_REGISTRY.md`:
+```markdown
+# SNIPE_HOME_REGISTRY.md
+Generated: <timestamp>
+HOME Path: <path>
+Language(s): <langs>
+
+## Public Symbol Inventory
+| Symbol | Kind | File | Notes |
+|--------|------|------|-------|
+| <name> | fn/class/trait/type | <file> | |
+
+## Pattern Fingerprint
+- Primary error handling: <Result/Exception/Either>
+- Primary concurrency: <async/sync/threaded>
+- Decorator/attribute patterns: <list>
+- Extension points: <list>
+
+## Known Gaps (from TODOs/unimplemented)
+- <file:line>: <todo text>
+```
+
+**Gate**: HOME registry must contain ≥ 1 symbol before proceeding to Phase 1.
+If HOME is empty or inaccessible, emit `GATE_FAILED` and halt.
+
+---
+
+### Phase 1 — TARGET Outline (No Reads Yet) `[STRATEGY_SELECTOR]`
+
+Extract TARGET structure at the symbol-name level only. Zero implementations read.
+
+**Step 4 — TARGET skeleton**
+```bash
+# Run from TARGET directory. Mirror HOME's Phase 0 queries exactly.
+cd <TARGET_PATH>
+
+# Rust
+ast-grep --pattern 'pub fn $NAME($$$)' --lang rust --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "function", file: .file}' \
+  >> ./agent-state/snipe/TARGET_OUTLINE.jsonl
+
+# Python
+ast-grep --pattern 'def $NAME($$$):' --lang python --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "function", file: .file}' \
+  >> ./agent-state/snipe/TARGET_OUTLINE.jsonl
+
+# TypeScript
+ast-grep --pattern 'export function $NAME($$$)' --lang ts --json | \
+  jq '.[] | {name: .metaVariables.NAME, kind: "function", file: .file}' \
+  >> ./agent-state/snipe/TARGET_OUTLINE.jsonl
+```
+
+**Step 5 — TARGET structural shape (without reading bodies)**
+```bash
+# Module/file structure
+find . -type f \( -name "*.rs" -o -name "*.py" -o -name "*.ts" \) \
+  | grep -v ".git" | sort
+
+# Public type surface
+ast-grep --pattern 'pub struct $NAME { $$$ }' --lang rust   # Rust types
+ast-grep --pattern 'class $NAME:' --lang python              # Python classes
+ast-grep --pattern 'interface $NAME' --lang ts               # TS interfaces
+```
+
+**Step 6 — TARGET dependency profile**
+```bash
+# What external deps does TARGET use that HOME does not?
+# (Compare against HOME's Cargo.toml / pyproject.toml / package.json)
+cat Cargo.toml | grep -A50 "\[dependencies\]"    # Rust
+cat pyproject.toml | grep -A30 "dependencies"       # Python
+cat package.json | python3 -c "import sys,json; d=json.load(sys.stdin); [print(k) for k in d.get('dependencies',{}).keys()]"  # Node
+
+# New deps in TARGET but not HOME = potential new capabilities
+```
+
+**Output**: Write `SNIPE_TARGET_OUTLINE.md`:
+```markdown
+# SNIPE_TARGET_OUTLINE.md
+TARGET Path/URL: <path>
+Language(s): <langs>
+Symbol Count: <n>
+
+## Symbol Names (outline only)
+| Symbol | Kind | File |
+|--------|------|------|
+| <name> | fn/class/type | <file> |
+
+## Dependencies Not in HOME
+- <dep>: <apparent purpose>
+```
+
+---
+
+### Phase 2 — Relevance Scoring `[EXECUTION_LOG]`
+
+This is the **core of CodeSnipe**. No TARGET implementation is read until every symbol
+has a score. Score computation is done against the HOME registry in memory.
+
+**Step 7 — Name-match pass**
+```bash
+# For each TARGET symbol name, check if it exists in HOME registry
+# (Run this as a shell one-liner using the JSONL registries)
+
+# Exact matches (score += 20)
+comm -12 \
+  <(jq -r '.name' ./agent-state/snipe/HOME_REGISTRY.jsonl | sort) \
+  <(jq -r '.name' ./agent-state/snipe/TARGET_OUTLINE.jsonl | sort) \
+  > ./agent-state/snipe/EXACT_MATCHES.txt
+
+# Substring matches (score += 10 each)
+while IFS= read -r target_name; do
+  grep -i "$target_name" ./agent-state/snipe/HOME_REGISTRY.jsonl && echo "SUBSTR_MATCH: $target_name"
+done < <(jq -r '.name' ./agent-state/snipe/TARGET_OUTLINE.jsonl) \
+  >> ./agent-state/snipe/SUBSTR_MATCHES.txt
+```
+
+**Step 8 — Structural pattern match (signature shape)**
+```bash
+# For each TARGET symbol, check if HOME has similar signatures
+# Use ast-grep on TARGET to find signatures matching HOME patterns
+
+# Example: if HOME uses Result<T, E> returns extensively,
+# check if TARGET also returns Result-like types
+ast-grep --pattern 'fn $NAME($$$) -> Result<$T, $E>' --lang rust  # (run in TARGET)
+ast-grep --pattern 'def $NAME($$$) -> $RETURN:' --lang python      # (run in TARGET)
+
+# Cross-reference: which TARGET fns return types that exist in HOME?
+ast-grep --pattern 'fn $NAME($$$) -> $RET' --lang rust --json | \
+  jq -r '.[] | .metaVariables.RET' \
+  | grep -Ff <(jq -r '.name' ./agent-state/snipe/HOME_REGISTRY.jsonl)
+```
+
+**Step 9 — Gap alignment pass**
+```bash
+# Does TARGET have implementations for HOME's known gaps?
+# For each TODO in HOME_GAP_MAP.txt, search TARGET for related symbols
+
+while IFS= read -r gap; do
+  keyword=$(echo "$gap" | grep -oP '(?<=TODO|FIXME)[^$]+' | tr -cs 'a-zA-Z' ' ' | head -c50)
+  echo "=== Gap: $keyword ===" >> ./agent-state/snipe/GAP_COVERAGE.txt
+  grep -i "$keyword" ./agent-state/snipe/TARGET_OUTLINE.jsonl \
+    >> ./agent-state/snipe/GAP_COVERAGE.txt
+done < ./agent-state/snipe/HOME_GAP_MAP.txt
+```
+
+**Output**: Write `SNIPE_RELEVANCE_MAP.md`:
+```markdown
+# SNIPE_RELEVANCE_MAP.md
+
+## Tier A — Prime Snipe Targets (score ≥ 12)
+| TARGET Symbol | Score | Reason | HOME Counterpart | File |
+|---|---|---|---|---|
+| `parse_file` | 20 | Exact name match | `parse_file` | extractor.py |
+| `LanguageSpec` | 15 | Name+type overlap | `LangConfig` | languages.py |
+
+## Tier B — Worth Reading Signature (score 8–11)
+| TARGET Symbol | Score | Reason | File |
+|---|---|---|---|
+
+## Tier C — Gap Coverage (HOME TODO resolved by TARGET)
+| HOME Gap | TARGET Symbol | File |
+|---|---|---|
+
+## Discarded (score < 8)
+Count: <n> symbols discarded. Not read. Not discussed.
+```
+
+---
+
+### Phase 3 — Precision Extraction `[EXECUTION_LOG]`
+
+**Only Tier A and Tier B symbols reach this phase.**
+
+**Step 10 — Snipe Tier A implementations**
+```bash
+# For each Tier A symbol, extract full implementation via ast-grep
+# Replace SYMBOL_NAME with actual name from SNIPE_RELEVANCE_MAP.md
+
+# Rust function body
+ast-grep --pattern 'fn SYMBOL_NAME($$$) { $$$ }' --lang rust
+
+# Rust with impl context (method)
+ast-grep --pattern 'impl $TYPE { $$$ fn SYMBOL_NAME($$$) { $$$ } $$$ }' --lang rust
+
+# Python function body
+ast-grep --pattern 'def SYMBOL_NAME($$$): $$$' --lang python
+
+# TypeScript
+ast-grep --pattern 'function SYMBOL_NAME($$$): $RET { $$$ }' --lang ts
+ast-grep --pattern 'SYMBOL_NAME($$$): $RET { $$$ }' --lang ts   # method
+```
+
+**Step 11 — Divergence extraction (how HOME and TARGET differ)**
+```bash
+# For exact-match symbols (score == 20), extract both HOME and TARGET implementations
+# to compare approaches
+
+# HOME implementation
+cd <HOME_PATH>
+ast-grep --pattern 'fn SYMBOL_NAME($$$) { $$$ }' --lang rust > /tmp/home_impl.txt
+
+# TARGET implementation
+cd <TARGET_PATH>
+ast-grep --pattern 'fn SYMBOL_NAME($$$) { $$$ }' --lang rust > /tmp/target_impl.txt
+
+# Structural diff: how many lines? How many patterns differ?
+wc -l /tmp/home_impl.txt /tmp/target_impl.txt
+diff /tmp/home_impl.txt /tmp/target_impl.txt | head -40
+```
+
+**Step 12 — Pattern sniping (recurring TARGET idioms absent from HOME)**
+```bash
+# Idioms seen 3+ times in TARGET but absent from HOME
+
+# Example: if TARGET uses a registry pattern
+ast-grep --pattern '$REGISTRY.insert($KEY, $VAL)' --lang rust  # (run in TARGET)
+ast-grep --pattern '$REGISTRY[$KEY] = $VAL' --lang python       # (run in TARGET)
+
+# Check if HOME has equivalent
+ast-grep --pattern '$REGISTRY.insert($KEY, $VAL)' --lang rust  # (run in HOME)
+# If 0 results → this is a pattern gap
+
+# Extract TARGET's registry pattern instances
+ast-grep --pattern 'PATTERN' --lang rust --json | \
+  jq '.[] | {file: .file, line: .range.start.line, text: .text}' \
+  >> ./agent-state/snipe/SNIPE_EXTRACTS.jsonl
+```
+
+---
+
+### Phase 4 — Artifact Generation `[ARTIFACT_UPDATE]`
+
+All snipe findings are crystallised into locked artifacts.
+
+**Required artifacts:**
+
+| Artifact | Contents |
+|---|---|
+| `SNIPE_HOME_REGISTRY.md` | HOME symbol inventory, pattern fingerprint, gap map |
+| `SNIPE_TARGET_OUTLINE.md` | TARGET symbol names, module structure (no implementations) |
+| `SNIPE_RELEVANCE_MAP.md` | Scored symbol table, Tier A/B/C/Discarded |
+| `SNIPE_EXTRACTS.jsonl` | Raw ast-grep output for Tier A/B symbols |
+| `SNIPE_COMPARISON.md` | Final comparison: divergence, adoption cost, inspiration |
+| `EVIDENCE_LOG.md` | All ast-grep command outputs (append-only, shared with codemunch) |
+
+**Artifact write protocol:**
+```bash
+# Every snipe command appends to EVIDENCE_LOG
+echo "## Snipe: fn parse_file (TARGET extractor.py)" >> ./agent-state/snipe/EVIDENCE_LOG.md
+ast-grep --pattern 'def parse_file($$$):' --lang python --json \
+  >> ./agent-state/snipe/EVIDENCE_LOG.md
+```
+
+**Optional artifacts by intent:**
+
+| Intent | Extra Artifact |
+|---|---|
+| `steal` | `ADOPTION_PLAN.md` — step-by-step integration into HOME |
+| `compare` | `DIVERGENCE_ANALYSIS.md` — side-by-side of same-named symbols |
+| `debug` | `BUG_TRIANGULATION.md` — TARGET's solution to HOME's bug |
+| `integrate` | `INTERFACE_BRIDGE.md` — data schema + API contract between HOME and TARGET |
+
+---
+
+### Phase 5 — Synthesis `[VERIFICATION]`
+
+Read ONLY the artifacts. Final reasoning pass over structured data, not raw code.
+
+**Step 13 — Snipe self-verification checklist**
+- [ ] `SNIPE_HOME_REGISTRY.md` contains ≥ 5 symbols (HOME is meaningfully mapped)
+- [ ] `SNIPE_RELEVANCE_MAP.md` has at least 1 Tier A symbol
+- [ ] Every Tier A symbol in `SNIPE_EXTRACTS.jsonl` has an evidence entry
+- [ ] Tier C gap coverage attempted for all HOME TODO items
+- [ ] Discarded symbol count is documented (proof that low-signal symbols were filtered)
+- [ ] `SNIPE_COMPARISON.md` exists and contains a recommendation
+
+**Step 14 — SNIPE_COMPARISON.md structure**
+
+```markdown
+# SNIPE_COMPARISON.md
+
+## Executive Summary
+HOME: <one sentence>
+TARGET: <one sentence>
+Overlap: <n> exact matches, <n> structural matches
+Key Finding: <one sentence — what's the most important thing TARGET has?>
+
+## Tier A Analysis (Direct Comparisons)
+### `symbol_name`
+- **HOME approach**: <2-3 sentences from HOME impl>
+- **TARGET approach**: <2-3 sentences from TARGET impl>
+- **Divergence**: <where/why they differ>
+- **Recommendation**: adopt / adapt / ignore
+
+## Tier C Gap Coverage (TARGET solves HOME TODOs)
+| HOME Gap | TARGET Solution | Adoption Complexity |
+|---|---|---|
+
+## Pattern Gaps (TARGET idioms absent from HOME)
+| Pattern | Frequency in TARGET | Adoption Note |
+|---|---|---|
+
+## Inspiration Extracts
+<curated list of TARGET patterns worth considering, with ast-grep evidence refs>
+```
+
+**Step 15 — HANDOFF**
+```json
+{
+  "meta": { "timestamp": "<ISO8601>", "skill": "codesnipe", "session_id": "<uuid>" },
+  "transition": {
+    "from": "capability-research",
+    "to": "capability-spec",
+    "status": "READY_FOR_HANDOFF",
+    "reason": "Dual-codebase comparison complete. Adoption candidates identified."
+  },
+  "payload": {
+    "primary_artifact": "./agent-state/snipe/SNIPE_COMPARISON.md",
+    "home_registry": "./agent-state/snipe/SNIPE_HOME_REGISTRY.md",
+    "target_outline": "./agent-state/snipe/SNIPE_TARGET_OUTLINE.md",
+    "relevance_map": "./agent-state/snipe/SNIPE_RELEVANCE_MAP.md",
+    "evidence_pointer": "./agent-state/snipe/EVIDENCE_LOG.md",
+    "tier_a_count": "<n>",
+    "adoption_candidates": ["<symbol1>", "<symbol2>"]
+  }
+}
+```
+
+---
+
+## 4. Intent-Specific Modes
+
+### `--intent steal`
+Focus: Extract and integrate a specific TARGET pattern into HOME.
+- Phase 0–1 run as normal.
+- Phase 2: Restrict scoring to symbols related to the stated feature.
+- Phase 3: Extract full implementation + dependencies.
+- Phase 4+: Generate `ADOPTION_PLAN.md` with interface changes needed in HOME.
+
+### `--intent compare`
+Focus: Understand how TARGET solves a problem HOME also solves.
+- Run Phase 0–3 fully.
+- Phase 4: Generate `DIVERGENCE_ANALYSIS.md` for every Tier A symbol.
+- Emphasis: WHY do they differ, not just HOW.
+
+### `--intent debug`
+Focus: HOME has a bug; TARGET may have fixed it.
+- Phase 0: Map HOME bug site via ast-grep (find the failing pattern).
+- Phase 1: Search TARGET for same pattern, look for fixes.
+- Phase 2: Score TARGET fixes by structural similarity to HOME's bug site.
+- Phase 4: Generate `BUG_TRIANGULATION.md`.
+
+```bash
+# Snipe a specific bug pattern in TARGET
+# Example: HOME has panics on unwrap(), does TARGET handle this better?
+ast-grep --pattern '$EXPR.unwrap()' --lang rust   # (HOME: find all panic sites)
+ast-grep --pattern '$EXPR.unwrap()' --lang rust   # (TARGET: compare frequency)
+ast-grep --pattern '$EXPR.unwrap_or($DEFAULT)' --lang rust  # (TARGET: safer pattern?)
+ast-grep --pattern 'match $EXPR { Ok($V) => $OK, Err($E) => $ERR }' --lang rust
+```
+
+### `--intent integrate`
+Focus: HOME needs to consume or extend TARGET as a library/module.
+- Phase 0: Map HOME's consumption points (where would TARGET connect?).
+- Phase 1: Map TARGET's public API surface (exports, entry points only).
+- Phase 2: Score TARGET exports against HOME consumption points.
+- Phase 4: Generate `INTERFACE_BRIDGE.md` with schema + integration plan.
+
+---
+
+## 5. ast-grep Snipe Commands Reference
+
+### Surgical Symbol Extraction (Tier A reads)
+```bash
+# Named function (any language variant)
+ast-grep --pattern 'fn TARGET_FN($$$) { $$$ }' --lang rust
+ast-grep --pattern 'def TARGET_FN($$$): $$$' --lang python
+ast-grep --pattern 'function TARGET_FN($$$) { $$$ }' --lang ts
+ast-grep --pattern 'TARGET_FN($$$): $RET { $$$ }' --lang ts   # method
+
+# Named type/class
+ast-grep --pattern 'struct TARGET_TYPE { $$$ }' --lang rust
+ast-grep --pattern 'class TARGET_CLASS: $$$' --lang python
+ast-grep --pattern 'interface TARGET_IFACE { $$$ }' --lang ts
+```
+
+### Cross-Codebase Pattern Search
+```bash
+# Run identical patterns in both HOME and TARGET; compare match counts
+# HOME:
+cd <HOME_PATH> && ast-grep --pattern '$EXPR?' --lang rust --json | jq length
+# TARGET:
+cd <TARGET_PATH> && ast-grep --pattern '$EXPR?' --lang rust --json | jq length
+# If TARGET has 5× more ? usage → different error philosophy
+```
+
+### Relevance Scoring Helpers
+```bash
+# Count shared symbol names between HOME and TARGET registries
+comm -12 \
+  <(jq -r '.name' ./agent-state/snipe/HOME_REGISTRY.jsonl | sort -u) \
+  <(jq -r '.name' ./agent-state/snipe/TARGET_OUTLINE.jsonl | sort -u) \
+  | wc -l
+
+# List all shared names
+comm -12 \
+  <(jq -r '.name' ./agent-state/snipe/HOME_REGISTRY.jsonl | sort -u) \
+  <(jq -r '.name' ./agent-state/snipe/TARGET_OUTLINE.jsonl | sort -u)
+```
+
+---
+
+## 6.1 Wrong-Stuff Protocol
+
+When comparison reveals issues:
+
+| Finding | Classification | Route To |
+|---|---|---|
+| HOME symbol contradicts its own spec | `spec_violation` | `agent-spec` |
+| TARGET pattern reveals HOME implementation gap | `implementation_bug` | `agent-builder` |
+| HOME registry incomplete for comparison | `invalid_source` | re-run Phase 0 |
+| HOME documentation mismatches code structure | `documentation_drift` | `agent-docs` |
+
+## 6.2 Anti-Patterns
+
+| Anti-Pattern | Correct Behavior |
+|---|---|
+| Reading TARGET without HOME registry | Build HOME registry first (Phase 0); always |
+| Reading symbols scoring < 8 | Discard; log to `KNOWN_UNKNOWNS` only |
+| Comparing without intent parameter | Intent controls scoring weights; always specify |
+| Spraying reads across all TARGET files | Snipe only scored, ranked symbols |
+| Session ends without `SNIPE_COMPARISON.md` | Every session produces comparison artifact |
+
+---
+
+## 6. Failure Modes & Circuit Breakers
+
+| Failure | Signal | Recovery |
+|---|---|---|
+| HOME registry empty | Gate blocks Phase 1 | Re-run Phase 0 with correct HOME path |
+| All TARGET symbols score < 8 | Zero Tier A/B symbols | Log to DECISIONS.md: "TARGET unrelated to HOME"; abort |
+| TARGET language ≠ HOME language | Phase 2 scoring can't use signatures | Score by name and pattern concept only; flag in SNIPE_COMPARISON.md |
+| Target is too large (>500 files) | Outline phase takes too long | Restrict to top-level modules only; flag as `PARTIAL_SNIPE` |
+| Intent changes mid-session | New focus discovered | Re-enter Phase 2 with updated scoring weights; do NOT re-run Phase 0 |
+
+---
+
+## 7. Activation
+
+```
+snipe --home <path> --target <path|repo> --intent <steal|compare|debug|integrate> [--lang <lang>]
+```
+
+**Example invocations:**
+```bash
+# Study how fastapi handles dependency injection vs our framework
+snipe --home ./myapi --target fastapi/fastapi --intent compare
+
+# Steal incremental indexing pattern from jcodemunch into our build tool
+snipe --home ./build-tool --target ./jcodemunch-mcp --intent steal
+
+# Find how TARGET fixed the panic we have in our parser
+snipe --home ./myparser --target nom-rs/nom --intent debug
+
+# Understand how to consume TARGET as a library in HOME
+snipe --home ./myapp --target ./some-sdk --intent integrate
+```
+
+CodeSnipe will automatically build the HOME registry, profile TARGET at outline level,
+score all symbols, extract only what earned it, and produce `SNIPE_COMPARISON.md`
+with concrete adoption recommendations.
+
+**No raw file reads. No unscored symbol access. Precision only.**