feat: add trustworthy change evidence across hosts

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+
+- **Explicit source freshness**: Add opt-in `index_status({ checkFreshness: true })` and `ocbi status --check-freshness --json` across supported hosts. Keep stored catalog readiness, source freshness, and coordinator state distinct; expose shared structured status without refreshing indexes.
+- **Source-linked pre-edit tests**: Add opt-in `includeTests` to `codebase_edit_context`, reusing current-source JS/TS discovery for direct target and one-hop caller references. Return complete budgeted citations and selected-only structured evidence across hosts, distinguish discovery caps from response omissions, and preserve explicit non-coverage labels.
+- **Working-tree impact**: Add `pr_impact({ workingTree: true })` and `ocbi impact --working-tree [--json]` for current indexed staged, unstaged, and untracked file-level graph evidence. Require explicit incremental refresh for stale bytes, preserve local Git/index state, disclose path/provenance/consistency limits, and report UNKNOWN for deleted, unindexed, symbol-free, or capped coverage.
+
 ### Changed
 
 - **Unified codebase explorer**: Replace separate architecture/network/symbol views with a categorized module directory and one module → exact file → symbol drill-down. Stable caller → focus → callee layouts use paged neighbors, direct navigation, and inspectable original callsites, including self-calls. Refine typography, category cards, snapshot totals, metadata density, and evidence panels; show module-anchored display paths while preserving original locations and add sticky narrow-layout section jumps. Keep whole-snapshot Changes, Hotspots, and Cycles in Analyze without losing exploration state. Preserve offline HTML, public export/tool arguments, safe snapshot data, search/history, responsive dialogs, and dark/light themes; remove draggable-network layout code.
@@ -16,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Consumer-visible evidence correctness**: Count only retained source and graph rows in pre-edit details, close truncated source fences at whole lines, and reserve outer-heading/final-truncation overhead before source fitting. Credit source only when its complete fitted block survives final composition. Allow structural-mode architecture maps to read branch files from SQLite without a vector store. Add native-backed citation, Unicode/CRLF, scope, and token-budget acceptance.
+- **Pre-edit source identity and cancellation**: Resolve canonical native symbol IDs before fitting target source, including large fragmented declarations, instead of accepting ranked body slices, suffix paths, or enclosing declarations. Cap source blocks at 512 tokens, withhold missing source, preserve default host roots, and share the exact lookup with evaluation. Keep selection-hook test references metadata-only and honor cancellation after empty lookups.
+- **Working-tree snapshot integrity**: Detect concurrent database publication even when source hashes and catalog counts are unchanged. Reject lossy UTF-8 Git paths and retain only project-local endpoints for cross-boundary renames.
+
 - **Concurrent branch materialization**: Use invocation-unique worktree registration names and a common-Git-directory lease around registration/deregistration, preventing overlapping calls from reading or recycling partially initialized peer metadata. Keep fetches and indexing callbacks concurrent, preserve cancellation cleanup and fail-closed retention, and cover peer preservation plus real multiprocess overlap.
 - **Directory watcher permission recovery**: Recover readable, policy-selected directory and project-root registrations rejected with `EPERM` or `EACCES`, including empty directories that later gain source files. Reuse the one-shot polling cutover and catch-up reconciliation without broadening ignored, excluded, restricted, protected-index, unreadable, or external-configuration scope. Exercise actual Chokidar 6 directory resources in the watcher/Indexer acceptance checks.
 - **Visualizer cyclic groups and graph scale**: Detect module and symbol strongly connected components iteratively, including direct recursion and loops longer than five symbols. Preserve distinct symbol IDs and page search, hotspot, relationship, and cyclic-group lists instead of silently capping results.

README.md

@@ -20,7 +20,7 @@ ocbi status --project /path/to/repo --host jcode
 ocbi search "retry recovery" --project /path/to/repo
 ```
 
-`cbi` remains available as a compatibility alias. `ocbi` provides status, indexing, search, definition lookup, and direct caller or callee inspection. See [Installation and host setup](docs/installation.md#human-cli) for the full command reference.
+`cbi` remains available as a compatibility alias. `ocbi` provides status, indexing, search, definition lookup, direct caller/callee inspection, and current indexed working-tree impact. See [Installation and host setup](docs/installation.md#human-cli) for the full command reference.
 
 ## Highlights
 
@@ -105,10 +105,10 @@ See [Installation and host setup](docs/installation.md) for complete instruction
 
 ## Recommended workflow
 
-1. **Check readiness when unknown** with `index_status` or `/status`; index only when needed.
+1. **Check stored readiness when unknown** with `index_status` or `/status`; use `index_status({checkFreshness:true})` when source/HEAD freshness matters. Ordinary status does not scan source; index only when needed.
 2. **Orient in unfamiliar code** with one compact `codebase_context` first pass (`tokenBudget: 600`, `limit: 5`), then inspect the evidence. Skip this step when the task is already scoped.
 3. **Go directly to known definitions or relationships** with `implementation_lookup`, `call_graph`, or `call_graph_path`.
-4. **Optionally prepare a known edit target** with `codebase_edit_context` for bounded source and direct graph evidence.
+4. **Optionally prepare a known edit target** with `codebase_edit_context` for bounded source and direct graph evidence; `includeTests:true` adds source-linked JS/TS test references, not runtime coverage.
 5. **Choose metadata or matching source** with `codebase_peek` or `codebase_search`; do not repeat context calls unnecessarily.
 6. **Read known paths or match literals directly** with targeted reads or `grep`.
 
@@ -123,7 +123,7 @@ See [Installation and host setup](docs/installation.md) for complete instruction
 | Find analogous implementations or duplicates | `find_similar` |
 | Find direct callers or callees | `call_graph` |
 | Find a path between two symbols | `call_graph_path` |
-| Analyze a branch or pull request blast radius | `pr_impact` |
+| Analyze branch/PR impact, or current indexed work with `workingTree:true` | `pr_impact` |
 
 See [Tools and commands](docs/tools.md) for host availability, tool details, MCP prompts, and slash commands.
 

docs/installation.md

@@ -207,18 +207,28 @@ The concise `ocbi` command is for terminal use. `cbi` remains available as a com
 ```bash
 # Inspect readiness, then create or refresh the index
 ocbi status --project /path/to/repo --host jcode
+# Optional read-only source/HEAD freshness check with machine-readable status
+ocbi status --check-freshness --json --project /path/to/repo --host jcode
 ocbi index --project /path/to/repo --host jcode
 
 # Search and inspect code from the terminal
 ocbi search "retry recovery" --project /path/to/repo --limit 5
 ocbi definition Indexer --project /path/to/repo
 ocbi graph callers Indexer --project /path/to/repo
+
+# Refresh edited source, then inspect the current indexed dirty tree without committing
+ocbi index --project /path/to/repo --host omp
+ocbi impact --working-tree --json --project /path/to/repo --host omp
 ```
 
 Use `ocbi index --dry-run` for a parse-only embedding-token total, `--estimate-only` for an estimate, and `ocbi --help` for command usage.
 
+Ordinary status reports stored catalog facts with freshness explicitly not checked. `--check-freshness` compares current selected source/configuration and HEAD with the index; it does not refresh the index or request embeddings. A successfully inspected missing/stale index still exits successfully; operational failures exit nonzero. The `--check-freshness` and status `--json` flags apply only to status (workspace status retains its separate JSON contract).
+
 Without `--project`, the CLI discovers the nearest containing Git checkout and reuses its project configuration and branch catalog, even from a nested package directory. MCP startup uses the same rule. Nested repositories, submodules, and linked worktrees retain their own checkout roots. Non-Git directories keep the current directory as their scope. An explicit `--project` is never widened, so use `--project .` to deliberately index only a child directory.
 
+`ocbi impact` requires `--working-tree` and accepts optional `--json` plus project/host/config selection. It reports the union of staged, unstaged, and untracked changes against the current indexed files, not staged source or deleted historical declarations. Refresh stale source with ordinary `ocbi index` first; impact inspection itself does not index or contact GitHub. Missing graph coverage or the 200-path cap produces UNKNOWN risk. See [Impact evidence](tools.md#pr_impact) for provenance and consistency limits.
+
 ### Private history on GitHub.com and Enterprise
 
 Enable sources in the **project-local** host configuration using `repositoryHistory.repositories` (see [Configuration](configuration.md#private-github-history)). Selectors accept `[HOST/]OWNER/REPO`: bare `owner/repo` defaults to GitHub.com, and explicit `github.com/OWNER/REPO` normalizes to that same lowercase identity. Enterprise selectors normalize to lowercase `hostname/owner/repo`. Use a DNS hostname only, with no URL scheme, credentials, port, or traversal components.

docs/pre-edit-context-design.md

@@ -14,15 +14,19 @@ The tool accepts:
 - `symbol` and optional `filePath`: an authoritative target when known
 - `tokenBudget`: total returned context budget
 - `callerLimit` and `calleeLimit`: direct graph-edge limits
+- `includeTests` (default false): current-source JS/TS test-reference evidence
+- `includeApiImpact` (default false): bounded Express/fetch associations
 
 It returns a single token-bounded evidence pack containing:
 
-1. The authoritative target implementation source, when a symbol resolves.
+1. A bounded excerpt of the authoritative target implementation source, when a symbol resolves.
 2. Direct callers and callees for that resolved symbol, with locations and edge types.
 3. A short risk note when the target is ambiguous, unresolved, or graph data is unavailable.
 4. Conceptual retrieval evidence when no target can be resolved.
 
-The first release must not claim test coverage or related-test certainty. The current index has test-path-aware ranking, but no durable test-to-symbol relationship. Test discovery is a separate, measurable follow-up.
+The initial release did not claim test coverage. The opt-in test section now reuses native AST-backed `discoverSymbolTests`: direct target references precede graph neighbors, and one-hop caller-test references follow them. Target `filePath` disambiguation leaves test-directory scope independent. Returned callback citations, evidence labels, selected-only structured details, discovery caps, and response omissions remain inspectable; no static link claims runtime coverage or passing tests. See [Tools and commands](tools.md#codebase_edit_context) for the current contract.
+
+Resolved targets use canonical native symbol IDs and declaration coordinates rather than ranked body fragments. The shared per-indexer lookup serves both production and evaluation. Source blocks are capped at 512 tokens, preserve declaration starts and whole-line fences, and leave response space for relationships and test references. Unreadable source retains canonical metadata but receives no source-included credit.
 
 ## Integration boundaries