feat(fase2b): OKF-navigated bundle context replaces chunk-stuffing

Closes the honest Fase 2a limitation: docs_dir==bundle_dir let keyword
chunk-stuffing leak the verdict's realization rate ("0.82") into the debate /
generation prompt regardless of the ExpeL fold (it surfaced from both
verdict-led-fro.md AND golden.json). The realization signal now reaches the
hypothesis prompt ONLY via the gated ExpeL fold.

- okf.py: bundle_context() + Bundle.context_files render the navigated bundle
  (index + frontmatter + cross-links) as the agent read-context, EXCLUDING
  type: verdict (maalbilde §2/§4). Pure stdlib, still MAF-free.
- datasource.py: bundle_citations() derives first-class citations from the
  navigated non-verdict files.
- run_project: on the bundle path context + citations + debate tools come from
  navigation (tools=[]; navigation replaces query-time RAG); the road path keeps
  chunk-stuffing unchanged.

Load-bearing (maalbilde §7): the marker is upgraded from the minted verdict id
to the realization signal itself. The empty-store control now asserts "0.82"
reaches NO prompt — RED against the pre-2b chunk-stuffing path, green after
navigation (TDD red->green). New okf-level test_bundle_context_excludes_verdict_layer
guards the seam directly.

Suite 133->134 passed, 4 skipped; mypy + ruff check clean. Reverted unrelated
ruff-format drift (backends/budget/verdicts/test_contracts) to keep the diff
surgical.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MHR8iKxJRxDiDfNw8HZmWE

src/portfolio_optimiser/run.py

@@ -35,6 +35,7 @@ from portfolio_optimiser.backends import Profile, get_backend, resolve_model
 from portfolio_optimiser.budget import Budget, BudgetMiddleware, TokenMeter
 from portfolio_optimiser.contracts import load_contracts
 from portfolio_optimiser.datasource import (
+    bundle_citations,
     chunk_dict_to_citation,
     make_retrieval_tool,
     retrieve_chunks,
@@ -116,18 +117,20 @@ def _project_by_id(project_id: str) -> Project:
     raise ValueError(f"unknown project_id: {project_id!r}")
 
 
-def _project_from_bundle(bundle_dir: str, project_id: str) -> Project:
+def _project_from_bundle(
+    bundle_dir: str, project_id: str, *, bundle: okf.Bundle | None = None
+) -> Project:
     """Derive a minimal ``Project`` from an OKF bundle (so a bundle the loop runs need NOT be a
     road reference-domain project). Only ``id`` + ``name`` reach the generation prompt
     (``generate._build_messages``), so ``cost_items`` is empty and ``verdict_input`` is unused here
     (the Layer-2 decision flows via the ``verdict_input`` argument). Fail-fast: the bundle's IR
-    ``project_id`` must match the requested id."""
+    ``project_id`` must match the requested id. ``bundle`` reuses an already-navigated bundle to
+    avoid a second navigation."""
     ir = okf.load_ir_projection(bundle_dir)
     if ir["project_id"] != project_id:
         raise ValueError(f"bundle project_id {ir['project_id']!r} != requested {project_id!r}")
-    project_file = next(
-        (f for f in okf.navigate_bundle(bundle_dir).files if f.type == "project"), None
-    )
+    nav = bundle if bundle is not None else okf.navigate_bundle(bundle_dir)
+    project_file = next((f for f in nav.files if f.type == "project"), None)
     name = (
         project_file.frontmatter.get("title", project_id).strip('"')
         if project_file is not None
@@ -190,23 +193,29 @@ async def run_project(
         verdict_input,
     )
 
-    # 2-3. Project + cited chunks (first-class provenance citations). An OKF-bundle run derives its
-    # project from the bundle (need not be a road reference-domain project).
-    project = (
-        _project_from_bundle(bundle_dir, project_id)
-        if bundle_dir is not None
-        else _project_by_id(project_id)
-    )
-    chunks = retrieve_chunks("cost saving measure", docs_dir, top_k)
-    citations = [chunk_dict_to_citation(c) for c in chunks]
+    # 2-3. Project + agent read-context + first-class citations. A bundle run derives ALL THREE from
+    # the navigated OKF bundle via progressive disclosure (verdict layer EXCLUDED — målbilde §2/§4),
+    # NOT keyword chunk-stuffing; the road path keeps the chunk-retrieval data source. ``debate_tools``
+    # is the query-time retrieval surface — empty on the bundle path (navigation already placed the
+    # curated context in the prompt, and a docs_dir==bundle_dir tool would re-leak the verdict layer).
+    if bundle_dir is not None:
+        bundle = okf.navigate_bundle(bundle_dir)
+        project = _project_from_bundle(bundle_dir, project_id, bundle=bundle)
+        context = okf.bundle_context(bundle)
+        citations = bundle_citations(bundle)
+        debate_tools: list[Any] = []
+    else:
+        project = _project_by_id(project_id)
+        chunks = retrieve_chunks("cost saving measure", docs_dir, top_k)
+        citations = [chunk_dict_to_citation(c) for c in chunks]
+        context = "\n".join(c["snippet"] for c in chunks)
+        debate_tools = [make_retrieval_tool(docs_dir, top_k=top_k)]
     if not citations:
         raise ValueError(f"no citable content in docs_dir: {docs_dir!r}")
-    context = "\n".join(c["snippet"] for c in chunks)
 
-    # 4. Budget + maker-checker debate (round-capped; Layer-1 HITL optional).
-    # The shared meter is driven on the debate's chat calls by the BudgetMiddleware
-    # (the brief's named short-circuit mechanism); the retrieval tool exposes the
-    # citation-bearing data source to the agents (no longer string-stuffed out-of-band).
+    # 4. Budget + maker-checker debate (round-capped; Layer-1 HITL optional). The shared meter is
+    # driven on the debate's chat calls by the BudgetMiddleware (the brief's named short-circuit
+    # mechanism); ``debate_tools`` exposes the citation-bearing data source on the road path.
     meter = (
         meter
         if meter is not None
@@ -214,12 +223,11 @@ async def run_project(
     )
     factory = client_factory if client_factory is not None else _default_factory(profile)
     budget_mw = BudgetMiddleware(meter)
-    retrieval_tool = make_retrieval_tool(docs_dir, top_k=top_k)
     debate = fresh_workflow(
         factory,
         max_rounds=max_rounds,
         enable_layer1_hitl=enable_layer1_hitl,
-        tools=[retrieval_tool],
+        tools=debate_tools,
         middleware=[budget_mw],
     )
     result = await debate.run(f"Find a cost-saving measure for {project.id}.\nContext:\n{context}")