release: v1.108.117 — _meta.verdict on the file & symbol read tools

Phase 2 of the retrieval-verdict work. get_file_content, get_file_outline,
and get_symbol_source now emit _meta.verdict: a miss returns state=absent
plus did_you_mean near-miss candidates (exact-basename/same-name ranked
first), and successful reads carry state=ok for parity with search_symbols.
get_file_outline separates "not indexed" from "indexed but no symbols".

Additive only: error strings and existing keys unchanged. No INDEX_VERSION
bump, no tool-count or schema change, inline compute. 13 new tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.117] - 2026-07-10 - `_meta.verdict` on the file & symbol read tools
+
+### Added
+
+- **`get_file_content`, `get_file_outline`, and `get_symbol_source` now emit
+  `_meta.verdict`** — the same honesty contract that already covers the search tools now
+  covers the read tools, where an agent most often burns tokens chasing a path or symbol
+  id that isn't there. A miss returns `state: "absent"` plus a `did_you_mean` list of
+  near-miss candidates, so the agent corrects the target instead of retrying the same
+  wrong one.
+- **Path near-misses** rank an exact-basename match in a different directory (right
+  filename, wrong folder) ahead of stem substring matches. **Symbol near-misses** rank a
+  same-name symbol in another file/kind ahead of substring matches. Both are computed
+  only on the miss path.
+- **`get_file_outline` distinguishes "file not indexed" from "file indexed but exposes no
+  symbols"** — the latter is a real `absent` (a data/config file, or constructs the parser
+  does not surface) with no suggestions, so the agent does not re-request the outline
+  expecting a different result.
+
+### Changed
+
+- The file/symbol verdict logic lives in the same `retrieval/verdict.py` module as the
+  search verdict (`build_file_verdict` / `build_symbol_verdict` plus index-aware
+  `file_verdict_for_index` / `symbol_verdict_for_index` wrappers). Successful reads now
+  also carry `_meta.verdict: {state: "ok"}` so the field is present on every outcome,
+  matching `search_symbols`. All additive — error strings and existing keys are unchanged.
+
+NO INDEX_VERSION bump; no tool-count or input-schema change; inline compute, no new
+background or network behavior. `tests/test_negative_evidence.py` extended (13 new cases:
+path/symbol near-miss ranking, the three file-tool states, and the batch/single symbol paths).
+
 ## [1.108.116] - 2026-07-10 - Unified retrieval verdict (`_meta.verdict`)
 
 ### Added

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "1.108.116"
+version = "1.108.117"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

src/jcodemunch_mcp/retrieval/verdict.py

@@ -158,3 +158,213 @@ def build_verdict(
             negative_evidence["related_existing"] = did_you_mean
 
     return {"verdict": verdict, "negative_evidence": negative_evidence}
+
+
+def suggest_paths(
+    requested_path: Optional[str],
+    source_files: Optional[Sequence[str]],
+    cap: int = 5,
+) -> list:
+    """Indexed paths that plausibly match a missing ``requested_path``.
+
+    Exact-basename matches in a different directory come first (the agent had
+    the filename right, the directory wrong), then stem substring matches. The
+    requested path itself is never suggested.
+    """
+    if not requested_path or not source_files:
+        return []
+    req = str(requested_path).replace("\\", "/")
+    req_base = req.rsplit("/", 1)[-1].lower()
+    req_stem = req_base.rsplit(".", 1)[0] if "." in req_base else req_base
+    exact: list = []
+    partial: list = []
+    seen: set = set()
+    for f in source_files:
+        norm = str(f).replace("\\", "/")
+        if norm == req or f in seen:
+            continue
+        base = norm.rsplit("/", 1)[-1].lower()
+        stem = base.rsplit(".", 1)[0] if "." in base else base
+        if base == req_base:
+            exact.append(f)
+            seen.add(f)
+        elif req_stem and len(req_stem) >= 3 and (req_stem in stem or stem in req_stem):
+            partial.append(f)
+            seen.add(f)
+    return (exact + partial)[:cap]
+
+
+def _symbol_name_of(symbol_id: Optional[str]) -> str:
+    """Bare name from a symbol id like ``path::Name#kind`` (or a plain name)."""
+    if not symbol_id:
+        return ""
+    s = str(symbol_id)
+    if "::" in s:
+        s = s.rsplit("::", 1)[-1]
+    if "#" in s:
+        s = s.split("#", 1)[0]
+    return s.lower()
+
+
+def suggest_symbol_ids(
+    requested_id: Optional[str],
+    symbols: Optional[Sequence[dict]],
+    cap: int = 5,
+) -> list:
+    """Indexed symbol ids whose name matches a missing ``requested_id``.
+
+    Same-name symbols (right name, wrong file/kind) rank ahead of substring
+    matches. Operates on the index's raw symbol dicts.
+    """
+    name = _symbol_name_of(requested_id)
+    if not name or not symbols:
+        return []
+    exact: list = []
+    partial: list = []
+    seen: set = set()
+    for s in symbols:
+        sid = s.get("id")
+        if not sid or sid == requested_id or sid in seen:
+            continue
+        sname = str(s.get("name", "")).lower()
+        if not sname:
+            continue
+        if sname == name:
+            exact.append(sid)
+            seen.add(sid)
+        elif len(name) >= 3 and (name in sname or sname in name):
+            partial.append(sid)
+            seen.add(sid)
+        if len(exact) >= cap:
+            break
+    return (exact + partial)[:cap]
+
+
+def build_file_verdict(
+    *,
+    present: bool,
+    requested_path: Optional[str] = None,
+    source_files: Optional[Sequence[str]] = None,
+    index_stale: bool = False,
+    empty_symbols: bool = False,
+) -> dict:
+    """`_meta.verdict` for the file-read tools.
+
+    * ``present=False`` — the path is not in the index: ``absent`` plus a
+      ``did_you_mean`` list of near-miss paths.
+    * ``present=True, empty_symbols=True`` — the file is indexed but yields no
+      symbols (data/config file, or constructs the parser does not surface):
+      ``absent`` with no suggestions, so the agent does not retry the outline.
+    * otherwise — ``ok``.
+    """
+    if not present:
+        state = STATE_ABSENT
+        note = "Path is not in the index. " + _NOTES[STATE_ABSENT]
+        suggestions = suggest_paths(requested_path, source_files)
+    elif empty_symbols:
+        state = STATE_ABSENT
+        note = (
+            "File is indexed but exposes no extractable symbols (a data/config "
+            "file, or constructs the parser does not surface). Re-requesting the "
+            "outline will not change this."
+        )
+        suggestions = []
+    else:
+        state = STATE_OK
+        note = _NOTES[STATE_OK]
+        suggestions = []
+    verdict = {
+        "state": state,
+        "channels": {"index": "stale" if index_stale else "fresh"},
+        "note": note,
+    }
+    if suggestions:
+        verdict["did_you_mean"] = suggestions
+    return verdict
+
+
+def symbol_verdict_for_index(
+    index,
+    *,
+    found_count: int,
+    requested_id: Optional[str] = None,
+) -> dict:
+    """Index-aware wrapper over :func:`build_symbol_verdict`."""
+    return build_symbol_verdict(
+        found_count=found_count,
+        requested_id=requested_id,
+        symbols=getattr(index, "symbols", None) if found_count == 0 else None,
+        index_stale=_index_is_stale(index),
+    )
+
+
+def _index_source_files(index) -> list:
+    """Best-effort list of indexed source paths (keys of ``file_languages``)."""
+    langs = getattr(index, "file_languages", None)
+    if isinstance(langs, dict):
+        return list(langs.keys())
+    return []
+
+
+def _index_is_stale(index) -> bool:
+    """Whether the index SHA lags the live git HEAD (never raises)."""
+    try:
+        from .freshness import FreshnessProbe
+
+        probe = FreshnessProbe(
+            source_root=getattr(index, "source_root", "") or None,
+            indexed_at=getattr(index, "indexed_at", ""),
+            index_sha=getattr(index, "git_head", None),
+            file_mtimes=getattr(index, "file_mtimes", None),
+        )
+        return probe.repo_is_stale
+    except Exception:
+        return False
+
+
+def file_verdict_for_index(
+    index,
+    *,
+    present: bool,
+    requested_path: Optional[str] = None,
+    empty_symbols: bool = False,
+) -> dict:
+    """Index-aware wrapper over :func:`build_file_verdict` for the file tools."""
+    return build_file_verdict(
+        present=present,
+        requested_path=requested_path,
+        source_files=_index_source_files(index) if not present else None,
+        index_stale=_index_is_stale(index),
+        empty_symbols=empty_symbols,
+    )
+
+
+def build_symbol_verdict(
+    *,
+    found_count: int,
+    requested_id: Optional[str] = None,
+    symbols: Optional[Sequence[dict]] = None,
+    index_stale: bool = False,
+) -> dict:
+    """`_meta.verdict` for ``get_symbol_source``.
+
+    ``found_count == 0`` yields ``absent`` plus ``did_you_mean`` symbol ids that
+    share the requested name; any resolved symbol yields ``ok`` (a partial batch
+    is still a hit).
+    """
+    if found_count == 0:
+        state = STATE_ABSENT
+        note = "Symbol id is not in the index. " + _NOTES[STATE_ABSENT]
+        suggestions = suggest_symbol_ids(requested_id, symbols)
+    else:
+        state = STATE_OK
+        note = _NOTES[STATE_OK]
+        suggestions = []
+    verdict = {
+        "state": state,
+        "channels": {"index": "stale" if index_stale else "fresh"},
+        "note": note,
+    }
+    if suggestions:
+        verdict["did_you_mean"] = suggestions
+    return verdict

src/jcodemunch_mcp/tools/get_file_content.py

@@ -3,6 +3,7 @@
 import time
 from typing import Optional
 
+from ..retrieval.verdict import file_verdict_for_index
 from ..storage import IndexStore, cost_avoided, estimate_savings, record_savings
 from ._utils import index_status_to_tool_error, resolve_repo
 
@@ -28,7 +29,15 @@ def get_file_content(
     if not index:
         return index_status_to_tool_error(store.inspect_index(owner, name))
     if not index.has_source_file(file_path):
-        return {"error": f"File not found: {file_path}"}
+        return {
+            "error": f"File not found: {file_path}",
+            "file": file_path,
+            "_meta": {
+                "verdict": file_verdict_for_index(
+                    index, present=False, requested_path=file_path
+                )
+            },
+        }
 
     content = store.get_file_content(owner, name, file_path, _index=index)
     if content is None:
@@ -89,5 +98,6 @@ def get_file_content(
             "tokens_saved": tokens_saved,
             "total_tokens_saved": total_saved,
             **cost_avoided(tokens_saved, total_saved),
+            "verdict": file_verdict_for_index(index, present=True),
         },
     }

src/jcodemunch_mcp/tools/get_file_outline.py

@@ -7,6 +7,7 @@
 
 from ..storage import IndexStore, record_savings, estimate_savings, cost_avoided
 from ..parser import Symbol, build_symbol_tree
+from ..retrieval.verdict import file_verdict_for_index
 from ._utils import load_repo_index_or_error
 
 
@@ -26,6 +27,11 @@ def _get_file_outline_single(
             "language": "",
             "file_summary": "",
             "symbols": [],
+            "_meta": {
+                "verdict": file_verdict_for_index(
+                    index, present=False, requested_path=file_path
+                )
+            },
         }
 
     # Filter symbols to this file
@@ -57,6 +63,9 @@ def _get_file_outline_single(
                 "tokens_saved": tokens_saved,
                 "total_tokens_saved": total_saved,
                 **cost_avoided(tokens_saved, total_saved),
+                "verdict": file_verdict_for_index(
+                    index, present=True, empty_symbols=True
+                ),
                 "tip": "Tip: use file_paths=[...] to query multiple files in one call.",
             },
         }
@@ -84,6 +93,7 @@ def _get_file_outline_single(
             "tokens_saved": tokens_saved,
             "total_tokens_saved": total_saved,
             **cost_avoided(tokens_saved, total_saved),
+            "verdict": file_verdict_for_index(index, present=True),
             "tip": "Tip: use file_paths=[...] to query multiple files in one call.",
         },
     }

src/jcodemunch_mcp/tools/get_symbol.py

@@ -7,6 +7,7 @@
 from pathlib import Path
 from typing import Optional
 
+from ..retrieval.verdict import suggest_symbol_ids, symbol_verdict_for_index
 from ..storage import IndexStore, record_savings, estimate_savings, cost_avoided as _cost_avoided
 from ._utils import index_status_to_tool_error, resolve_repo, resolve_fqn
 
@@ -282,7 +283,11 @@ def get_symbol_source(
         symbol = index.get_symbol(sid)
 
         if not symbol:
-            errors_out.append({"id": sid, "error": f"Symbol not found: {sid}"})
+            err = {"id": sid, "error": f"Symbol not found: {sid}"}
+            _sug = suggest_symbol_ids(sid, index.symbols)
+            if _sug:
+                err["did_you_mean"] = _sug
+            errors_out.append(err)
             continue
 
         source = store.get_symbol_content(owner, name, sid, _index=index)
@@ -420,15 +425,26 @@ def get_symbol_source(
     if batch_mode:
         meta["symbol_count"] = len(symbols_out)
         meta["freshness"] = _probe.summary(symbols_out)
+        meta["verdict"] = symbol_verdict_for_index(
+            index,
+            found_count=len(symbols_out),
+            requested_id=(ids[0] if len(ids) == 1 else None),
+        )
         if _runtime_summary:
             meta["runtime_freshness"] = _runtime_summary
         return {"symbols": symbols_out, "errors": errors_out, "_meta": meta}
 
     # Single mode: flat object or error
     if errors_out:
-        return {"error": errors_out[0]["error"]}
+        verdict = symbol_verdict_for_index(
+            index, found_count=0, requested_id=errors_out[0]["id"]
+        )
+        return {"error": errors_out[0]["error"], "_meta": {"verdict": verdict}}
     result = symbols_out[0]
     meta["hint"] = "Use get_context_bundle(symbol_id) to retrieve source + imports in one call"
+    meta["verdict"] = symbol_verdict_for_index(
+        index, found_count=len(symbols_out), requested_id=symbol_id
+    )
     meta["freshness"] = _probe.summary(symbols_out)
     if _runtime_summary:
         meta["runtime_freshness"] = _runtime_summary