docs: update failure topology and gist sync audit

Author: bniladridas

docs/telemetry/failure_topology.md

@@ -1,8 +1,8 @@
 # Failure Topology & Telemetry Analysis
 
-**Date:** 2026-06-25  
+**Date:** 2026-06-26  
 **Data Scope:** 432 log files, 1,306 total telemetry traces from `~/.cursor/replay`  
-**Phase:** Complete (Observation Phase transitioned to Evidence-Driven Roadmap)
+**Phase:** Complete (Reference Search capability integrated, validated via 8/8 regression scenarios)
 
 ---
 
@@ -201,14 +201,23 @@ Based on the segmented telemetry showing the **User Rejection Gap**, the impleme
     Success is defined as reducing `insufficient_evidence` on clean developer traces from **6.5%** to a target below **2.0%**.
   * **Scope Limitation:** Strictly constrained to search paths inside the repository root. No broad shell commands, git watchers, or autonomous code edits. Do not modify or remove existing telemetry.
 
-### 6.3 Blocked Features (Freeze Maintained)
+### 6.3 Priority 3: Reference Search (Complete)
+* **Status:** **Complete.** See `docs/telemetry/reference_search_report.md`.
+* **Target Failure Class:** Retrieval capability gaps.
+* **Implementation Guardrails:**
+  * **Guardrail 1: Strictly Deterministic Routing:** Reference query resolution must not fall back to fuzzy LLM ranking or broad `grep` searches.
+  * **Guardrail 2: Keep Telemetry Clean:** Track invocation via `reference_tool_hits` and resolution rate via `caller_resolution_rate`.
+  * **Scope Limitation:** Strictly restricted to exposing the existing `SymbolService::find_references` backend to `ExecutionEngine` and tool routing layers.
+
+### 6.4 Blocked Features (Freeze Maintained)
 Do NOT implement:
 * Repair Loop / Autonomous code modification.
 * Natural Language $\rightarrow$ Command Translation (Shell Translator) - **Postponed Longest**.
 * Git History/Status UI dashboards.
 * New framework abstractions.
+* Symbol Search work (until telemetry justifies it).
 
-### 6.4 Key Success Metric
+### 6.5 Key Success Metric
 * **Target:** Reduce the production-only `user_rejected` rate from **42.0%** to a target below **10%** before introducing any other major capabilities, ensuring the agent immediately heads in the correct direction.
 
 ---
@@ -292,15 +301,28 @@ Remaining **4.6% `insufficient_evidence`** (10 traces):
 
 **Note:** The 8x `replay` and 2x `CommandRouter` traces in §7.4 were attributed to routing/meta carryover in §7.2 (resolved to 14 remaining). After the find fix, 4 additional multi-word binary traces are resolved. The remaining 10 `insufficient_evidence` traces are from synthetic benchmarks (nonexistent symbols) or routing-edge cases — not retrieval failures.
 
-### 7.7 Roadmap Decision
+### 7.7 Reference Search Verification & Outcomes
+
+The Reference Search capability was validated against four acceptance queries, resolving them entirely via the `references` tool and direct `read` commands, eliminating broad `grep` fallback:
+
+| Acceptance Query | Tool Execution Path | Status | Resolution Type | caller_resolution_rate |
+|---|---|---|---|:---:|
+| `who calls ReplayService` | `references ReplayService` $\rightarrow$ `read` | PASS | Explicit Caller Search | 1.0 |
+| `where is CommandRouter referenced` | `references CommandRouter` $\rightarrow$ `read` | PASS | Explicit Caller Search | 1.0 |
+| `who uses ToolResult` | `references ToolResult` $\rightarrow$ `read` | PASS | Explicit Caller Search | 1.0 |
+| `where is SessionState used` | `references SessionState` $\rightarrow$ `read` | PASS | Explicit Caller Search | 1.0 |
+
+All 8/8 regression scenarios pass successfully.
+
+### 7.8 Roadmap Decision
 
-**Status:** Directory-Aware Find cycle is **complete**.
+**Status:** Both Directory-Aware Find and Reference Search cycles are **complete**.
 
-**Next bottleneck** (clean developer traces): `insufficient_evidence` at **4.6%** — below the 2.0% target means the retrieval layer has achieved its success criterion.
+**Next bottleneck:** Retrieval layers now possess deterministic capabilities for both definition lookup and caller references, resulting in 100% caller resolution rate on the acceptance query set without grep fallback.
 
-**Recommended next target:** Evaluate from telemetry once sufficient production data accumulates post-deployment. Do not pre-select a target without data.
+**Recommended next target:** Stop and wait for production telemetry. Do not initiate any new capability work or Symbol Search cycle.
 
 **Implementation freeze maintained for:**
 - Subagents / repair loops / shell translation / git dashboards.
-- Any new find ranking features or LLM-augmented search.
+- Semantic search / AST indexing / tree-sitter.
 

docs/telemetry/gist_sync_audit.md

@@ -0,0 +1,55 @@
+# Gist Synchronization Audit Report
+
+**Date:** 2026-06-26  
+**Target Gist:** [6f4560edbce637a4bb3f6b310d5adae7](https://gist.github.com/bniladridas/6f4560edbce637a4bb3f6b310d5adae7)  
+**Objective:** Compare Gist contents against the local repository and formulate a synchronization plan.
+
+---
+
+## 1. File Status Matrix
+
+| File Name / Path | Status Category | Location | Purpose / Content |
+| :--- | :--- | :--- | :--- |
+| `docs/telemetry/commit_plan.md` | **In Repo Only** | Repository | Git commit strategy and guidelines. |
+| `docs/telemetry/final_verification.md` | **In Repo Only** | Repository | Verification output of regression runs. |
+| `docs/telemetry/find_implementation_audit.md` | **In Repo Only** | Repository | Audit of the original find logic. |
+| `docs/telemetry/next_capability_report.md` | **In Repo Only** | Repository | Roadmap analysis proposing Reference Search. |
+| `docs/telemetry/reference_search_report.md` | **In Repo Only** | Repository | Details of the implemented Reference Search capability. |
+| `docs/telemetry/ui_audit.md` | **In Repo Only** | Repository | Audit of current terminal agent loop UI elements. |
+| `docs/proposals/controlled_edit_design.md` | **In Repo Only** | Repository | Proposal for Controlled Edit Mode v1. |
+| `docs/proposals/controlled_edit_feasibility_report.md` | **In Repo Only** | Repository | Feasibility verification of checkpoint/compile/rollback. |
+| `analyze_production_only.py` | **In Gist Only** | Gist | Script to isolate clean developer trace logs. |
+| `analyze_traces.py` | **In Gist Only** | Gist | Script to parse baseline telemetry logs and build statistics. |
+| `generation_guide.md` | **In Gist Only** | Gist | Markdown instructions on how traces were generated. |
+| `inspect_all_production_inputs.py` | **In Gist Only** | Gist | Telemetry parsing script for developer input queries. |
+| `inspect_unknown_failures.py` | **In Gist Only** | Gist | Script to parse and list unclassified telemetry errors. |
+| `simulate_postfix_clean.py` | **In Gist Only** | Gist | Telemetry cleanup simulation script. |
+| [directory_aware_find_report.md](file:///Users/bniladridas/Desktop/cursor/docs/telemetry/directory_aware_find_report.md) | **Present in Both but Different** | Both | Directory-aware find design and implementation outcomes. |
+| [failure_topology.md](file:///Users/bniladridas/Desktop/cursor/docs/telemetry/failure_topology.md) | **Present in Both but Different** | Both | Authority topology document mapping trace failures and freezes. |
+| None | **Present in Both and Identical** | N/A | No files match this category. |
+
+---
+
+## 2. File Drift Analysis
+
+### 2.1 `failure_topology.md`
+* **Gist State:** Outdated. Lists Priority 2 (Directory-Aware Find) as "Approved to Build" and lacks Priority 3 (Reference Search). The roadmap decision section (§7.5) still recommends Directory-Aware Find as the next cycle target.
+* **Repository State:** Ahead. Marks both Directory-Aware Find and Reference Search as completed. Includes a new verification table (§7.7) showing 100% resolution rates for the Reference Search acceptance queries, and sets the updated target/freeze decisions.
+
+### 2.2 `directory_aware_find_report.md`
+* **Gist State:** Outdated/Partial. Only captures a quick hotfix for a specific defect (multi-word terms regex literals).
+* **Repository State:** Ahead. Records the complete directory-aware find system architecture, CamelCase ranking, directory hit metrics, and final trace verification benchmarks.
+
+---
+
+## 3. Synchronization Recommendations
+
+### 3.1 Files to Update in the Gist
+* **`failure_topology.md`:** Overwrite Gist version with local version to accurately reflect the completed Reference Search cycle and updated freezes.
+* **`directory_aware_find_report.md`:** Overwrite Gist version with local version to capture the complete implementation report.
+
+### 3.2 Files to Remove from the Gist
+* **None.** The Python scripts and `generation_guide.md` are useful history of how traces were parsed and cleansed, and are fine to keep in the Gist.
+
+### 3.3 Files to Keep Repo-Only
+* **All other repository telemetry/reports (`commit_plan.md`, `final_verification.md`, `next_capability_report.md`, `reference_search_report.md`, `ui_audit.md`, `find_implementation_audit.md`)** and **proposals (`controlled_edit_design.md`, `controlled_edit_feasibility_report.md`)**: Keep repo-only. These document internal C++ codebase context, detailed verification, and future proposals that don't need to bloat the shared Gist.