release: v2.0.0 — evidence memory (includes unreleased 1.10.0)

.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "codebase-index",
   "displayName": "Codebase Index",
   "description": "Give Claude a precise local map of your codebase: find implementations, trace behavior, and predict change impact with file-line evidence.",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "author": {
     "name": "codebase-index contributors"
   },

.claude/skills/codebase-index/.skill_version

@@ -1 +1 @@
-1.9.0
+2.0.0

.claude/skills/codebase-index/SKILL.md

@@ -1,32 +1,34 @@
 ---
 name: codebase-index
-description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository.
-allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository, and verify evidence gathered earlier before relying on it.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index verify *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
 ---
 
 # Codebase Index
 
 Use the local index before reading repository files.
 
-The operating principle is **Find → Trace → Predict**:
+The operating principle is **Find → Trace → Verify → Predict**:
 
 - **Find** the implementation with ranked retrieval.
 - **Trace** behavior through definitions, callers, dependencies, and paths.
+- **Verify** that evidence you already hold is still true before relying on it.
 - **Predict** change impact while preserving an explicit evidence trail.
 
 ## Route the question
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --json` |
-| How does X work? | `codebase-index explain "X" --json` |
+| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
+| How does X work? | `codebase-index explain "X" --session <tag> --json` |
 | What is this codebase? | `codebase-index architecture --json` |
 | Find a named symbol | `codebase-index symbol "X" --json` |
 | Who calls or references X? | `codebase-index refs "X" --json` |
 | What changes if X changes? | `codebase-index impact "X" --json` |
 | What does my current diff affect? | `codebase-index diff-impact --json` |
 | How are X and Y connected? | `codebase-index path "X" "Y" --json` |
 | Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
 | Produce a human graph | `codebase-index graph "X" --output <path>` |
 
 Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
@@ -38,21 +40,41 @@ or routing remain unclear.
 
 ## Evidence protocol
 
-1. Run the best-matching command with `--json`.
-2. Check `index` before trusting the payload:
+1. Pick one session tag for this conversation (for example `auth-fix-1`) and
+   pass `--session <tag>` to every `search` and `explain`.
+2. Run the best-matching command with `--json`.
+3. Check `index` before trusting the payload:
    - missing → run `codebase-index index`, then repeat;
    - stale with fewer than 20 changed files → run `codebase-index update`;
    - stale with 20 or more changed files → run `codebase-index index`;
    - fresh → continue.
-3. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-4. Trace one additional hop only when the question requires behavior,
+4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
+5. Trace one additional hop only when the question requires behavior,
    ownership, or impact.
-5. Answer with `file:line` evidence and state uncertainty explicitly.
+6. Before answering or editing from evidence gathered earlier in the task, run
+   `codebase-index verify --session <tag> --json` and reread anything whose
+   state is not `valid` or `relocated`.
+7. Answer with `file:line` evidence and state uncertainty explicitly.
 
 Do not open whole files when a line range is available. A snippet may already
 be sufficient. `skeletonized: true` means the response intentionally folded
 unrelated body lines; read the supplied range when the missing body matters.
 
+## Evidence memory
+
+- `reused: true` with `snippet: null` — this session already received that
+  exact text and its source is unchanged. Use your earlier copy; if you can no
+  longer see it, Read the range.
+- `memory.invalidated` — evidence this session received has changed since.
+  Treat your earlier copy as wrong and reread before relying on it.
+- `stale: true` — the index is older than the file. Run `codebase-index update`
+  or Read the range.
+- A tag belongs to one context. Never give it to a subagent or another
+  conversation. Start a new tag after the context is cleared or compacted, or
+  whenever earlier snippets are no longer visible to you.
+
+Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
+
 ## Confidence contract
 
 - **high** — answer from the indexed evidence.

.claude/skills/codebase-index/references/commands.md

@@ -17,6 +17,9 @@ Useful search options:
 - `--offset <pagination offset>`
 - `--raw` to disable snippet skeletonization
 - `--no-fallback` to suppress fallback suggestions
+- `--session <tag>` to name this conversation's context: unchanged evidence it
+  already received comes back as `reused: true` without the snippet, and
+  evidence that changed is listed under `memory.invalidated`
 
 `explain` uses the HOW_IT_WORKS intent and a larger default token budget. Prefer
 it over repeatedly rewording a broad search.
@@ -49,6 +52,18 @@ codebase-index graph "<target>" --direction both --depth 2 --output graph.html
 For headless work, use `--output`; do not use `--open`. Exports also support
 `--format graphml|dot|neo4j`.
 
+## Evidence
+
+```bash
+codebase-index verify --session <tag> --json
+codebase-index verify "<path:start-end@hash>" ... --json
+```
+
+- `verify` is read-only and needs no index: it checks evidence against the
+  working tree. `all_valid` is true only when every checked span still holds.
+- `--strict` exits 1 when anything is invalid (useful in scripts).
+- See [memory.md](memory.md) for verdict states and when to reread.
+
 ## Index health
 
 ```bash

.claude/skills/codebase-index/references/memory.md

@@ -0,0 +1,49 @@
+# Evidence Memory
+
+Load this when you use `--session`, when a packet contains `reused`, `stale` or
+`memory`, or when you want to cite evidence for later.
+
+## What is guaranteed
+
+Evidence is identified by the exact bytes of a file span. `reused: true` is set
+only when this session already received the same text — or the whole span —
+and those bytes are unchanged now. Nothing is decided by query similarity, and
+memory stores no source text.
+
+## Verdict states
+
+| state | still true? | do this |
+|---|---|---|
+| `valid` | yes | use it |
+| `relocated` | yes — identical content moved inside the file | use it; cite the new lines |
+| `changed` | no | reread the range before relying on it |
+| `ambiguous` | no — identical content now occurs more than once | reread |
+| `deleted` | no — file gone; a rename or move counts as deleted | search again |
+| `excluded` | no — now ignored or secret-like | do not read it |
+| `unreadable` | no | search again |
+
+## Reread even when evidence is valid
+
+- You are about to edit and need the exact current text.
+- The earlier snippet was a skeleton or a signature and you need the body.
+- Your context was cleared or compacted, or you cannot see the earlier snippet.
+- A tool output was truncated.
+
+## Citing evidence across conversations
+
+`codebase-index verify --session <tag> --json` lists everything the session
+received as `path:start-end@hash` references. Keep the references next to the
+conclusions they support in notes or handoffs:
+
+```text
+Refunds are capped at the invoice total [billing/refund.py:3-4@3f9a2c1b7d4e8a90]
+```
+
+Later, from any agent, check them before trusting the note:
+
+```bash
+codebase-index verify "billing/refund.py:3-4@3f9a2c1b7d4e8a90" --json
+```
+
+`all_valid: true` means every cited span still holds exactly. Otherwise reread
+the invalid spans and re-derive the conclusion; do not patch the old one.

.claude/skills/codebase-index/references/response-contract.md

@@ -16,13 +16,21 @@ Each result can contain:
 - `snippet`
 - `skeletonized`
 - `elided_lines`
+- `stale` — only when the index text no longer matches the file
+- `reused` — only with `--session`, when `snippet` was withheld because this
+  session already received that exact text from unchanged source
 
 `recommended_reads` is the read plan. Start with its first one to three entries
 and use exact line ranges. An entry with `truncated: true` was capped at the
 definition head (`max_read_lines`, default 120); `line_end_full` gives the real
 extent. Read the capped range first and continue only when the head is not
 enough.
 
+With `--session`, the packet also carries `memory`: `session`, `reused`,
+`tokens_saved`, and `invalidated` — references to evidence the session received
+that has since changed. `available: false` means nothing was withheld. See
+[memory.md](memory.md).
+
 `pagination.has_more` and `pagination.next_offset` indicate additional results.
 Prefer a more specific command or a larger token budget before paging.
 

.claude/skills/codebase-index/scripts/cbx

@@ -4,7 +4,7 @@
 # - Whitelists subcommands so the skill can never invoke destructive ones (clean/init/watch).
 set -euo pipefail
 
-ALLOWED="search explain architecture symbol refs impact diff-impact path describe graph stats doctor update index"
+ALLOWED="search explain architecture symbol refs impact diff-impact path describe verify graph stats doctor update index"
 
 sub="${1:-}"
 case " $ALLOWED " in

.claude/skills/codebase-index/scripts/cbx.ps1

@@ -10,7 +10,7 @@ param(
 $ErrorActionPreference = "Stop"
 $allowed = @(
     "search", "explain", "architecture", "symbol", "refs", "impact", "diff-impact",
-    "path", "describe", "graph", "stats", "doctor", "update", "index"
+    "path", "describe", "verify", "graph", "stats", "doctor", "update", "index"
 )
 
 if ($allowed -notcontains $Subcommand) {

.codex/skills/codebase-index/.skill_version

@@ -1 +1 @@
-1.9.0
+2.0.0

.codex/skills/codebase-index/SKILL.md

@@ -1,32 +1,34 @@
 ---
 name: codebase-index
-description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository.
-allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository, and verify evidence gathered earlier before relying on it.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index verify *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
 ---
 
 # Codebase Index
 
 Use the local index before reading repository files.
 
-The operating principle is **Find → Trace → Predict**:
+The operating principle is **Find → Trace → Verify → Predict**:
 
 - **Find** the implementation with ranked retrieval.
 - **Trace** behavior through definitions, callers, dependencies, and paths.
+- **Verify** that evidence you already hold is still true before relying on it.
 - **Predict** change impact while preserving an explicit evidence trail.
 
 ## Route the question
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --json` |
-| How does X work? | `codebase-index explain "X" --json` |
+| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
+| How does X work? | `codebase-index explain "X" --session <tag> --json` |
 | What is this codebase? | `codebase-index architecture --json` |
 | Find a named symbol | `codebase-index symbol "X" --json` |
 | Who calls or references X? | `codebase-index refs "X" --json` |
 | What changes if X changes? | `codebase-index impact "X" --json` |
 | What does my current diff affect? | `codebase-index diff-impact --json` |
 | How are X and Y connected? | `codebase-index path "X" "Y" --json` |
 | Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
 | Produce a human graph | `codebase-index graph "X" --output <path>` |
 
 Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
@@ -38,21 +40,41 @@ or routing remain unclear.
 
 ## Evidence protocol
 
-1. Run the best-matching command with `--json`.
-2. Check `index` before trusting the payload:
+1. Pick one session tag for this conversation (for example `auth-fix-1`) and
+   pass `--session <tag>` to every `search` and `explain`.
+2. Run the best-matching command with `--json`.
+3. Check `index` before trusting the payload:
    - missing → run `codebase-index index`, then repeat;
    - stale with fewer than 20 changed files → run `codebase-index update`;
    - stale with 20 or more changed files → run `codebase-index index`;
    - fresh → continue.
-3. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-4. Trace one additional hop only when the question requires behavior,
+4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
+5. Trace one additional hop only when the question requires behavior,
    ownership, or impact.
-5. Answer with `file:line` evidence and state uncertainty explicitly.
+6. Before answering or editing from evidence gathered earlier in the task, run
+   `codebase-index verify --session <tag> --json` and reread anything whose
+   state is not `valid` or `relocated`.
+7. Answer with `file:line` evidence and state uncertainty explicitly.
 
 Do not open whole files when a line range is available. A snippet may already
 be sufficient. `skeletonized: true` means the response intentionally folded
 unrelated body lines; read the supplied range when the missing body matters.
 
+## Evidence memory
+
+- `reused: true` with `snippet: null` — this session already received that
+  exact text and its source is unchanged. Use your earlier copy; if you can no
+  longer see it, Read the range.
+- `memory.invalidated` — evidence this session received has changed since.
+  Treat your earlier copy as wrong and reread before relying on it.
+- `stale: true` — the index is older than the file. Run `codebase-index update`
+  or Read the range.
+- A tag belongs to one context. Never give it to a subagent or another
+  conversation. Start a new tag after the context is cleared or compacted, or
+  whenever earlier snippets are no longer visible to you.
+
+Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
+
 ## Confidence contract
 
 - **high** — answer from the indexed evidence.

.codex/skills/codebase-index/references/commands.md

@@ -17,6 +17,9 @@ Useful search options:
 - `--offset <pagination offset>`
 - `--raw` to disable snippet skeletonization
 - `--no-fallback` to suppress fallback suggestions
+- `--session <tag>` to name this conversation's context: unchanged evidence it
+  already received comes back as `reused: true` without the snippet, and
+  evidence that changed is listed under `memory.invalidated`
 
 `explain` uses the HOW_IT_WORKS intent and a larger default token budget. Prefer
 it over repeatedly rewording a broad search.
@@ -49,6 +52,18 @@ codebase-index graph "<target>" --direction both --depth 2 --output graph.html
 For headless work, use `--output`; do not use `--open`. Exports also support
 `--format graphml|dot|neo4j`.
 
+## Evidence
+
+```bash
+codebase-index verify --session <tag> --json
+codebase-index verify "<path:start-end@hash>" ... --json
+```
+
+- `verify` is read-only and needs no index: it checks evidence against the
+  working tree. `all_valid` is true only when every checked span still holds.
+- `--strict` exits 1 when anything is invalid (useful in scripts).
+- See [memory.md](memory.md) for verdict states and when to reread.
+
 ## Index health
 
 ```bash

.codex/skills/codebase-index/references/memory.md

@@ -0,0 +1,49 @@
+# Evidence Memory
+
+Load this when you use `--session`, when a packet contains `reused`, `stale` or
+`memory`, or when you want to cite evidence for later.
+
+## What is guaranteed
+
+Evidence is identified by the exact bytes of a file span. `reused: true` is set
+only when this session already received the same text — or the whole span —
+and those bytes are unchanged now. Nothing is decided by query similarity, and
+memory stores no source text.
+
+## Verdict states
+
+| state | still true? | do this |
+|---|---|---|
+| `valid` | yes | use it |
+| `relocated` | yes — identical content moved inside the file | use it; cite the new lines |
+| `changed` | no | reread the range before relying on it |
+| `ambiguous` | no — identical content now occurs more than once | reread |
+| `deleted` | no — file gone; a rename or move counts as deleted | search again |
+| `excluded` | no — now ignored or secret-like | do not read it |
+| `unreadable` | no | search again |
+
+## Reread even when evidence is valid
+
+- You are about to edit and need the exact current text.
+- The earlier snippet was a skeleton or a signature and you need the body.
+- Your context was cleared or compacted, or you cannot see the earlier snippet.
+- A tool output was truncated.
+
+## Citing evidence across conversations
+
+`codebase-index verify --session <tag> --json` lists everything the session
+received as `path:start-end@hash` references. Keep the references next to the
+conclusions they support in notes or handoffs:
+
+```text
+Refunds are capped at the invoice total [billing/refund.py:3-4@3f9a2c1b7d4e8a90]
+```
+
+Later, from any agent, check them before trusting the note:
+
+```bash
+codebase-index verify "billing/refund.py:3-4@3f9a2c1b7d4e8a90" --json
+```
+
+`all_valid: true` means every cited span still holds exactly. Otherwise reread
+the invalid spans and re-derive the conclusion; do not patch the old one.