ace-swarm 2.1.0 → 2.1.2

package/assets/.agents/skills/codesnipe/SKILL.md

@@ -1,671 +1,64 @@
 ---
 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.
+description:
+  Compare a HOME codebase with a TARGET codebase by scoring TARGET symbols against HOME first. Use when you need adoption candidates, divergence analysis, bug triangulation, or integration ideas instead of broad repo browsing.
 ---
 
-# CodeSnipe — Dual-Codebase Precision Intelligence
+# CodeSnipe
 
-**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.
+Use this skill to perform evidence-backed, dual-codebase comparison without wasting attention on low-signal TARGET code.
 
-**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.
+## Purpose
 
-Reading a symbol that scored < 8 is a token waste and a protocol violation.
+Build a HOME-aware relevance map so only the most comparable or adoptable TARGET symbols are extracted, analyzed, and handed off.
 
----
-
-## 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)
+## Canonical Use Cases
 
-# 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
+1. A team wants to adopt a pattern from another repository and needs ranked implementation candidates instead of broad comparison notes.
+2. A bug or gap in the HOME codebase might already be solved in a TARGET codebase, and the team wants precise triangulation.
+3. An integration or competitor study requires knowing what TARGET does relative to HOME before deeper reading begins.
 
-# 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
-```
+## Inputs
 
-**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
+- HOME codebase path
+- TARGET codebase path or checkout
+- Comparison intent such as `steal`, `compare`, `debug`, or `integrate`
+- ast-grep plus any lightweight registry artifacts already available under `agent-state/snipe/`
 
-# 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)
+## Workflow
 
-# 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)
-```
+1. Build a HOME symbol registry and pattern fingerprint first.
+2. Outline TARGET at the symbol-name and module-shape level without reading implementations.
+3. Score TARGET symbols against HOME and record the relevance map.
+4. Extract only symbols that meet the score threshold, then analyze divergence or adoption fit.
+5. Write the comparison artifacts and handoff recommendation under `agent-state/snipe/`.
 
-**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
+## Outputs
 
-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 |
-
----
+- `agent-state/snipe/SNIPE_HOME_REGISTRY.md`
+- `agent-state/snipe/SNIPE_TARGET_OUTLINE.md`
+- `agent-state/snipe/SNIPE_RELEVANCE_MAP.md`
+- `agent-state/snipe/SNIPE_EXTRACTS.jsonl`
+- `agent-state/snipe/SNIPE_COMPARISON.md`
 
-## 7. Activation
+## Validation
 
-```
-snipe --home <path> --target <path|repo> --intent <steal|compare|debug|integrate> [--lang <lang>]
-```
+- Verify the HOME registry exists before any TARGET implementation read occurs.
+- Verify every discussed TARGET symbol has a recorded relevance score in `SNIPE_RELEVANCE_MAP.md`.
+- Verify the final comparison artifact contains at least one explicit recommendation: adopt, adapt, ignore, or unrelated.
 
-**Example invocations:**
-```bash
-# Study how fastapi handles dependency injection vs our framework
-snipe --home ./myapi --target fastapi/fastapi --intent compare
+## References
 
-# Steal incremental indexing pattern from jcodemunch into our build tool
-snipe --home ./build-tool --target ./jcodemunch-mcp --intent steal
+- `references/dual-codebase-playbook.md` preserves the detailed scoring formula, phase recipes, and intent-specific extraction playbooks.
 
-# Find how TARGET fixed the panic we have in our parser
-snipe --home ./myparser --target nom-rs/nom --intent debug
+## Compatibility
 
-# Understand how to consume TARGET as a library in HOME
-snipe --home ./myapp --target ./some-sdk --intent integrate
-```
+- `SKILL.md` is the canonical portable contract for this skill.
+- The detailed comparison cookbook lives under `references/` for progressive disclosure and should not replace the top-level contract.
+- The workflow remains portable anywhere HOME/TARGET code can be queried structurally with ast-grep and basic shell tooling.
 
-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.
+## Failure Policy
 
-**No raw file reads. No unscored symbol access. Precision only.**
+- If the HOME registry is empty or cannot be built, halt before reading TARGET implementations.
+- If all TARGET symbols score below the threshold, report that the TARGET is unrelated or low-yield instead of forcing comparison.
+- Do not read or summarize unscored TARGET symbols; treat that as a protocol violation.