fix(context): adaptive surfacing dropped the memory most worth recalling (ADR-0029)

Found while writing an MCP test. A saved hard constraint ("must not add a
Redis dependency") was not surfaced for the task "rate limiting", and the
report said it had been "ranked below the budget cut". The budget was 19,200
tokens and the record was 12. It had not lost a budget contest -- it never
entered one.

`ContextRanker.rank` returns only what it could score: a candidate sharing no
term with the task is absent from the result, not present with score zero.
`select()` iterated that list and applied the budget to it, so any record with
no lexical overlap was dropped before the budget was consulted. Measured on a
real .verity/: task "speed up the cache" surfaced 0 of 4 records, all silently
discarded.

This inverts the mechanism's purpose. Persisted memory is most valuable when
the decisive fact is NOT inferable from the task's wording -- that is exactly
ADR-0020's finding, the first pilot in eight to produce a success-rate split.
Selecting memory by lexical overlap optimizes against the one case it exists
for. And `classify.py` protects MEMORY items as CRITICAL unconditionally, but
nothing that never reaches the pipeline can be protected by it.

Unscored candidates now rank last instead of vanishing, so every candidate is
either selected or genuinely did not fit (invariant 6's principle applied to
selection). `degraded_reason` says when this happened and what was done.
Keyed on ContextItem.id, not content_hash -- the hash is empty on a plain
item, which made every unscored candidate look like a duplicate of every
other, caught by a test failing for exactly that reason.

Same pass also wires the last two engines to MCP, the CLI having been
exercised first as rule 5 requires:
  - `risk_of_changing`  -- per-file tiers with reasons; refuses an empty graph
  - `should_recall_memory` -- the trigger, budget and records, and it
    distinguishes "nothing crossed a threshold" from "nothing is saved"

This is the third finding in one verification pass with the same shape
(0027, 0028, 0029): a collaborator returned less than the caller assumed, the
caller could not tell "nothing found" from "nothing looked at", and the
resulting message was confidently wrong rather than absent. ADR-0029 names it
as a class and the check that catches it.

644 tests pass, lint clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Juanpacol

CLAUDE.md

@@ -125,7 +125,7 @@ src/verityai/
 │   └── evidence.py       the retained artifact: diff + manifest (ADR-0027)
 ├── analysis/facts.py     AST fact extraction (carried over from T6)
 ├── cli/main.py           the verity command
-├── mcp/server.py         MCP server — 19 tools over the same core
+├── mcp/server.py         MCP server — 21 tools over the same core
 ```
 
 ### `.verity/` on disk
@@ -209,7 +209,7 @@ has the detail; the short version:
 ## Development
 
 ```bash
-pytest tests/           # 634 tests, no network, no services, no fixtures needed
+pytest tests/           # 644 tests, no network, no services, no fixtures needed
 ruff check src/ tests/
 ruff format src/ tests/
 ```

docs/adr/0025-adaptive-context-prepass.md

@@ -102,8 +102,14 @@ specific mechanism in `prune.py`:
   `critical_retention` against the *merged* list rather than the original
   transcript: surfaced items are the CRITICAL ones, so the original baseline
   would exclude exactly what is at risk and the check would pass vacuously.
-  MCP remains deliberately unwired, and **the pilot remains not run** — no
-  claim about this mechanism's effect is made anywhere.
+  MCP is now wired too (`risk_of_changing`, `should_recall_memory`), the CLI
+  having been exercised first as rule 5 requires. **The pilot remains not
+  run** — no claim about this mechanism's effect is made anywhere.
+
+  Wiring MCP immediately surfaced a defect this ADR's own design carried
+  from the start: `select()` dropped every candidate the BM25 ranker could
+  not score, which is exactly the memory most worth recalling. See
+  [ADR-0029](0029-unrankable-memory-is-not-irrelevant-memory.md).
 - The threshold constants (`_HIGH_WINDOW_USAGE`, `_LOW_RELEVANT_RATIO`,
   `_DEFAULT_BUDGET_RATIO`) are placeholders pending exactly that pilot —
   they should not be read as tuned values.

docs/adr/0029-unrankable-memory-is-not-irrelevant-memory.md

@@ -0,0 +1,110 @@
+# ADR-0029: Unrankable memory is not irrelevant memory
+
+- **Status**: Accepted
+- **Date**: 2026-08-10
+- **Context**: found while writing an MCP test for `should_recall_memory`.
+  A saved hard constraint — "must not add a Redis dependency" — was not
+  surfaced for the task "rate limiting", and the report said it had been
+  "ranked below the budget cut". The budget was 19,200 tokens and the record
+  was 12. It had not lost a budget contest; it had never entered one.
+
+## The defect
+
+`ContextRanker.rank` returns only the candidates it could score. A candidate
+sharing no term with the task is **absent from the result**, not present with
+score zero:
+
+```
+ContextRanker().rank("rate limiting", [redis_constraint, token_bucket_decision])
+  -> 1 item:  score=0.0164  "decision: use a token bucket for rate limiting"
+     (the Redis constraint is simply not there)
+```
+
+`select()` iterated `ranking.items` and applied the budget to that. So any
+record with no lexical overlap with the task was dropped **before** the budget
+was consulted, and then reported as a budget outcome. Measured on a real
+`.verity/`: task "speed up the cache" surfaced **0 of 4** records, all four
+silently discarded.
+
+Three things make this worse than a ranking imperfection:
+
+1. **It removes exactly the records worth recalling.** The value of persisted
+   memory is highest when the decisive fact is *not* inferable from the task's
+   wording. That is [ADR-0020](0020-arbitrary-tiebreak-pilot.md)'s finding —
+   the first pilot in eight to produce a success-rate split did so precisely
+   because the correct answer had no linguistic convention pointing at it.
+   Selecting memory by lexical overlap optimizes against the one case the
+   mechanism exists for.
+2. **`classify.py` protects MEMORY items as CRITICAL unconditionally**, and
+   the prune pipeline honours that. But nothing that never reaches the
+   pipeline can be protected by it. The guarantee was real and simply
+   unreachable.
+3. **The explanation was wrong, not merely missing.** "Ranked below the budget
+   cut" tells a reader to raise the budget. Raising it would have changed
+   nothing.
+
+## Decision
+
+Unscored candidates are ordered **last**, not dropped:
+
+```python
+scored_ids = {scored.item.id for scored in ranking.items}
+ordered = [scored.item for scored in ranking.items]
+unscored = [item for item in candidates if item.id not in scored_ids]
+ordered.extend(unscored)
+```
+
+Relevance still orders the budget; it can no longer make a record vanish
+before the budget applies. This is invariant 6's principle — *the parts must
+sum to the whole* — applied to selection rather than to parsing: every
+candidate is now either selected or genuinely did not fit, and
+`test_nothing_is_lost_between_candidates_and_the_budget` asserts it.
+
+When any candidate was unrankable, `degraded_reason` says so and says what
+was done about it, distinct from the ranker's own degradation:
+
+```
+degraded  no embed_fn configured; 4 candidate(s) share no term with the task
+          and could not be ranked; they were ordered last rather than dropped,
+          so a constraint with no lexical overlap can still be surfaced
+```
+
+Keyed on `ContextItem.id`, not `content_hash`: the hash is populated by
+whoever built the item and is empty on a plain one, which would make every
+unscored candidate look like a duplicate of every other. (Found by a test
+failing for that exact reason.)
+
+## Consequences
+
+- On the real `.verity/` used to check this, task "speed up the cache" goes
+  from 0 of 4 records surfaced to 4 of 4, with the reason stated.
+- Budgets now bind more often, which is the correct pressure: the point of
+  `plan_budget`'s conservative 15% default is to bound cost, and it can only
+  do that against candidates that actually reach it.
+- **Not addressed here:** ordering *among* unscored candidates is their
+  original order, which is arbitrary with respect to importance. A hard
+  constraint and a stale discovery compete on nothing but position. Ranking
+  memory by kind and recency rather than by term overlap is the real fix, and
+  it needs a pilot to justify a specific ordering rather than a guess — the
+  same reason ADR-0025's thresholds are still placeholders.
+- Embeddings would reduce the incidence (a semantic ranker scores everything)
+  but not the defect: `rank()` would still be free to return a short list, and
+  `select()` must not assume otherwise.
+
+## The pattern, now three for three
+
+This is the third finding in one verification pass with the same shape, and at
+this point it is worth naming as a class rather than three coincidences:
+
+| | What was silently returned | What the caller reported |
+|---|---|---|
+| [0027](0027-retained-trial-evidence.md) | a hash of a tree, not the tree | "retained, re-derivable" |
+| [0028](0028-the-mocked-test-that-could-not-fail.md) | zero graph nodes, wrong path form | `low` risk — "needs no scrutiny" |
+| 0029 | fewer items than were passed in | "ranked below the budget cut" |
+
+In each case a collaborator returned less than the caller assumed, the caller
+had no way to distinguish "nothing found" from "nothing looked at", and the
+resulting message was **confidently wrong** rather than absent. The check that
+would have caught all three is the same one: *when a function returns fewer
+things than it was given, does anything assert the difference is accounted
+for?* That question is now a test in all three places.

docs/adr/README.md

@@ -46,6 +46,7 @@ verdict was "this pilot could not have detected an effect."
 | [0026](0026-risk-adaptive-verification.md) | Can verification depth scale with file risk, using only signals already in the graph? | Yes — `classify_file_risk` tiers by path convention / blast radius / fan-in / untested symbols; `rules_for_tier` gates rule depth; both builtin rules tagged with risk tiers and sql-injection caveat backfilled |
 | [0027](0027-retained-trial-evidence.md) | Did ADR-0022 actually close invariant 7? | **No** — six checkable failures, including a default output path inside `.gitignore` and a CLI that could not express the metric ADR-0022 claimed to reproduce. Evidence is now a diff against a hash-pinned fixture; unretained ⇒ unpublishable, mechanically |
 | [0028](0028-the-mocked-test-that-could-not-fail.md) | Did ADR-0026's risk tiering work outside its own tests? | **No** — any path form but the ingester's silently yielded zero signals and a clean-looking `low` for every file. The suite's only `MagicMock` could not express the difference; tests rewritten against a real graph, and `unittest.mock` is gone |
+| [0029](0029-unrankable-memory-is-not-irrelevant-memory.md) | Does adaptive surfacing recall the records that matter most? | **It did the opposite** — BM25 omits zero-overlap candidates entirely, so a constraint sharing no word with the task was dropped before the budget applied and reported as a budget outcome. 0 of 4 records surfaced on a real store. Unscored candidates now rank last instead of vanishing |
 
 ## Pre-pivot (superseded)
 

src/verityai/context/adaptive.py

@@ -152,17 +152,46 @@ def select(
     ranker = ranker or ContextRanker()
     ranking = ranker.rank(task, candidates)
 
+    # `ContextRanker.rank` returns only what it could score: a candidate whose
+    # text shares no term with the task is absent from `ranking.items`, not
+    # present with score zero. Selecting from that list alone would silently
+    # lose exactly the record most worth recalling -- a hard constraint like
+    # "must not add a Redis dependency" against the task "speed up the cache"
+    # has no lexical overlap at all, and pilot 8's whole finding is that the
+    # decisive fact is the one that cannot be inferred from the wording.
+    #
+    # So unscored candidates are ranked *last*, not dropped. Relevance still
+    # orders the budget; it just cannot make a record vanish before the budget
+    # is considered. Invariant 6's principle -- the parts must sum to the
+    # whole -- applied to selection rather than to parsing.
+    # Keyed on `ContextItem.id`, which always exists. `content_hash` is
+    # populated by whoever built the item and is empty on a plain one, so
+    # using it here would make every unscored candidate look like a duplicate
+    # of every other.
+    scored_ids = {scored.item.id for scored in ranking.items}
+    ordered = [scored.item for scored in ranking.items]
+    unscored = [item for item in candidates if item.id not in scored_ids]
+    ordered.extend(unscored)
+
     selected: list[ContextItem] = []
     used = 0
-    for scored in ranking.items:
-        if used + scored.item.token_count > plan.budget:
+    for item in ordered:
+        if used + item.token_count > plan.budget:
             continue
-        selected.append(scored.item)
-        used += scored.item.token_count
+        selected.append(item)
+        used += item.token_count
+
+    reasons = [ranking.degraded_reason] if ranking.degraded_reason else []
+    if unscored:
+        reasons.append(
+            f"{len(unscored)} candidate(s) share no term with the task and could not be "
+            "ranked; they were ordered last rather than dropped, so a constraint with no "
+            "lexical overlap can still be surfaced"
+        )
 
     return SurfaceDecision(
         items=selected,
         plan=plan,
         trigger=trigger,
-        degraded_reason=ranking.degraded_reason,
+        degraded_reason="; ".join(reasons) or None,
     )

src/verityai/mcp/server.py

@@ -395,6 +395,123 @@ def check_security() -> str:
         report = scan_repo(store.root.parent)
         return render_report(report, title="SECURITY", caveats=caveats_for(report.violations))
 
+    @server.tool()
+    def risk_of_changing(paths: list[str]) -> str:
+        """Tier files you are about to change: how much verification each earns.
+
+        Call this before editing several files at once, or when deciding
+        where to spend review effort. Returns low/medium/high per file with
+        the reasons behind it -- blast radius, fan-in, untested public
+        symbols, and path conventions like `auth/` or `migrations/`.
+
+        A tier is a *depth*, not a finding: "high" does not mean the file is
+        broken, it means a change there deserves more scrutiny than a change
+        to a leaf. Nothing here gates the security scan -- run `check_security`
+        as well, always.
+
+        Paths must be repo-relative as `build_code_graph` stored them
+        (`src/pkg/mod.py`). Absolute paths are relativized when possible; a
+        path that cannot be resolved is reported as such rather than silently
+        tiered low, since "no signals found" and "no risk found" are different
+        answers.
+        """
+        from verityai.graph.query import GraphQuery
+        from verityai.reliability.risk import classify_paths
+
+        if not paths:
+            return "No paths given. Pass the files you are about to change."
+
+        store = _store()
+        with _graph() as graph:
+            if not graph.stats().get("nodes.total"):
+                return (
+                    "The code graph is empty, so every file would tier 'low' for lack of "
+                    "signals -- which would read as 'nothing needs scrutiny' when nothing "
+                    "was measured. Call build_code_graph first."
+                )
+            verdicts = classify_paths(paths, GraphQuery(graph), repo_root=store.root.parent)
+
+        order = {"high": 0, "medium": 1, "low": 2}
+        lines: list[str] = []
+        for path, (tier, reasons) in sorted(
+            verdicts.items(), key=lambda kv: (order[kv[1][0]], kv[0])
+        ):
+            lines.append(f"[{tier.upper()}] {path}")
+            lines.extend(f"    {reason}" for reason in reasons)
+        return "\n".join(lines)
+
+    @server.tool()
+    def should_recall_memory(task: str, context_sample: str = "") -> str:
+        """Ask whether now is the moment to pull saved decisions back in.
+
+        Call this when a task has been running for a while, when you notice
+        you are re-deriving something, or before starting a subtask -- the
+        cases where an agent typically *does not* think to check its own
+        memory, which is exactly why this exists as a prompt-able tool.
+
+        `context_sample` is whatever slice of your working context you can
+        pass; the answer is only about what you hand over (Verity cannot see
+        your window). With no sample this reports what is on file without a
+        trigger judgement.
+
+        Returns the trigger and its threshold, the budget and its basis, and
+        the records worth surfacing -- or says plainly that nothing crossed a
+        threshold, which is a different answer from "there is nothing saved".
+        """
+        from verityai.context.adaptive import (
+            no_trigger_reason,
+            plan_budget,
+            select,
+            should_surface,
+        )
+        from verityai.memory.surface import candidates_for
+
+        store = _store()
+        counter = TokenCounter()
+        candidates = candidates_for(store, task, counter)
+        if not candidates:
+            return "Nothing is saved in .verity/ yet, so there is nothing to recall."
+
+        if not context_sample.strip():
+            lines = [
+                f"No context sample given, so no trigger was computed. {len(candidates)} "
+                "record(s) are on file:",
+            ]
+            lines.extend(f"  - {' '.join(c.content.split())[:100]}" for c in candidates[:10])
+            return "\n".join(lines)
+
+        items = load(context_sample)
+        pipeline = ContextPipeline(counter=counter)
+        measured = [pipeline.measure(item, n) for n, item in enumerate(items)]
+        health = compute_health(classify_all(measured), counter=counter)
+
+        trigger = should_surface(health)
+        if trigger is None:
+            return (
+                f"No trigger: {no_trigger_reason(health)}.\n"
+                f"{len(candidates)} record(s) are on file and none are being pushed. "
+                "This is a judgement about the context you passed, not a claim that "
+                "the records are irrelevant -- call get_state to read them anyway."
+            )
+
+        plan = plan_budget(counter, health)
+        decision = select(candidates, task, plan, trigger=trigger)
+
+        lines = [
+            f"RECALL NOW: {trigger.reason}",
+            f"  budget {plan.budget:,} of {plan.window:,} tokens",
+            f"  basis  {plan.basis}",
+            "",
+        ]
+        if decision.degraded_reason:
+            lines.append(f"  degraded: {decision.degraded_reason}")
+            lines.append("")
+        lines.extend(f"  - {' '.join(item.content.split())[:160]}" for item in decision.items)
+        withheld = len(candidates) - len(decision.items)
+        if withheld:
+            lines.append(f"\n  ({withheld} more ranked below the budget cut; get_state has all.)")
+        return "\n".join(lines)
+
     @server.tool()
     def check_architecture() -> str:
         """Check every import against the project's declared dependency policy.