Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(docs): self-repair for hallucinated symbol refs, cross-reference prompt discipline, repo-wide link resolution on updates (#872)
Raghav Chamadiya466afd8613db
diff --git a/packages/core/src/repowise/core/generation/interlinking.py b/packages/core/src/repowise/core/generation/interlinking.pyindex 41f9fd077..2f52ccae3 100644--- a/packages/core/src/repowise/core/generation/interlinking.py+++ b/packages/core/src/repowise/core/generation/interlinking.py@@ -34,6 +34,10 @@ _BACKTICK_REF_RE = re.compile(r"(?<!`)` *([A-Za-z_/.][\w./\-]*?) *`(?!`)")# Markdown code fence — content inside is verbatim source, not refs._FENCE_RE = re.compile(r"```.*?```", re.DOTALL)+# Page types whose target_path is a real file path. Shared with+# related_pages, which widens the same index the same way.+FILE_BACKED_PAGE_TYPES = frozenset({"file_page", "api_contract", "infra_page"})+# ---------------------------------------------------------------------------# Link index@@ -67,7 +71,7 @@ class LinkIndex:if not page.target_path:continueidx.by_target[page.target_path] = page.page_id- if page.page_type in {"file_page", "api_contract", "infra_page"}:+ if page.page_type in FILE_BACKED_PAGE_TYPES:idx.by_path[page.target_path] = page.page_idbase = Path(page.target_path).name# Don't overwrite — first wins to avoid ambiguous basename collisions.@@ -75,9 +79,7 @@ class LinkIndex:elif page.page_type == "symbol_spotlight":# target_path is "file::name" — map the qualified formif "::" in page.target_path:- idx.by_symbol_qname.setdefault(- page.target_path, page.page_id- )+ idx.by_symbol_qname.setdefault(page.target_path, page.page_id)# Augment with symbol qualified_names from the parser even when# the symbol itself didn't get a spotlight — the link resolves@@ -92,12 +94,33 @@ class LinkIndex:idx.by_symbol_qname.setdefault(qname, host_page)# Last-segment match for `Foo.bar` → `bar`if "." in qname:- idx.by_symbol_qname.setdefault(- qname.rsplit(".", 1)[-1], host_page- )+ idx.by_symbol_qname.setdefault(qname.rsplit(".", 1)[-1], host_page)return idx+ def add_prior_page_ids(self, prior_page_ids: Any) -> None:+ """Widen resolution with page ids persisted from prior runs.++ On an incremental update only the affected pages are in the run's+ page set, so a ref to any unchanged file would fail to resolve and+ the regenerated pages would lose their cross-page links. A page_id+ is ``"{page_type}:{target_path}"``, so the persisted ids carry+ enough to rebuild the path tables. Current-run pages always win+ (``setdefault``); the reader drops links whose target no longer+ exists, so stale prior ids are harmless. Only file-backed and+ symbol pages are added — other page types are not path-shaped.+ """+ for pid in prior_page_ids or ():+ ptype, _, tpath = str(pid).partition(":")+ if not tpath:+ continue+ if ptype in FILE_BACKED_PAGE_TYPES:+ self.by_target.setdefault(tpath, str(pid))+ self.by_path.setdefault(tpath, str(pid))+ self.by_basename.setdefault(Path(tpath).name, str(pid))+ elif ptype == "symbol_spotlight" and "::" in tpath:+ self.by_symbol_qname.setdefault(tpath, str(pid))+def resolve(self, ref: str) -> str | None:"""Resolve a single ref to a ``page_id``; ``None`` if unmatched."""if not ref:@@ -156,9 +179,12 @@ def resolve_wiki_links(if target in seen_targets:continueseen_targets.add(target)- kind = "file" if "/" in ref or ref.endswith(- (".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java")- ) else "symbol"+ kind = (+ "file"+ if "/" in ref+ or ref.endswith((".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java"))+ else "symbol"+ )links.append(WikiLink(anchor=ref, target_page_id=target, kind=kind))if len(links) >= max_links_per_page:break@@ -173,17 +199,26 @@ def resolve_wiki_links(def attach_wiki_links_and_backlinks(pages: list[GeneratedPage],parsed_files: list[Any] | None = None,+ prior_page_ids: Any = None,) -> None:"""Populate ``metadata['wiki_links']`` and ``metadata['backlinks']``.Mutates each :class:`GeneratedPage` in place. Idempotent and safeto call on a partially-populated page set — pages with no resolvedrefs simply get empty lists.++ ``prior_page_ids`` widens forward-link resolution to pages persisted+ from earlier runs (see :meth:`LinkIndex.add_prior_page_ids`); without+ it an incremental update can only link within its own diff. Backlinks+ are still built for current-run pages only — a prior page's stored+ backlinks are not reachable from here and refresh on its next+ regeneration."""if not pages:returnindex = LinkIndex.build(pages, parsed_files)+ index.add_prior_page_ids(prior_page_ids)by_id: dict[str, GeneratedPage] = {p.page_id: p for p in pages}# First pass — resolve forward links per page.@@ -235,12 +270,8 @@ def attach_wiki_links_and_backlinks(log.info("wiki_links.resolved",pages=len(pages),- total_forward_links=sum(- len(p.metadata.get("wiki_links") or []) for p in pages- ),- pages_with_backlinks=sum(- 1 for p in pages if p.metadata.get("backlinks")- ),+ total_forward_links=sum(len(p.metadata.get("wiki_links") or []) for p in pages),+ pages_with_backlinks=sum(1 for p in pages if p.metadata.get("backlinks")),)diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.pyindex 8879cce69..98144e173 100644--- a/packages/core/src/repowise/core/generation/models.py+++ b/packages/core/src/repowise/core/generation/models.py@@ -145,6 +145,13 @@ class GenerationConfig:# that carry a decision; harvested candidates pass the same substring gate# as every other source before storage.harvest_decisions: bool = True+ # ---- In-loop self-repair (hallucinated symbol refs) ----------------+ # When the post-generation validator flags at least this many backtick+ # identifiers that do not exist in the documented file, the tier-1 file+ # page is re-generated ONCE with the invalid refs named in a corrective+ # note, and the cleaner of the two drafts is kept. 0 disables the retry.+ # Pages reused from a prior run are never retried (validated back then).+ repair_warning_threshold: int = 2jobs_dir: str = ".repowise/jobs"large_file_source_pct: float = 0.4 # use structural summary when source tokens > budget * thislanguage: str = "en"diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.pyindex ba2494ae5..9b97b4821 100644--- a/packages/core/src/repowise/core/generation/page_generator/core.py+++ b/packages/core/src/repowise/core/generation/page_generator/core.py@@ -16,7 +16,7 @@ from __future__ import annotationsimport hashlibimport uuidfrom collections.abc import Callable-from dataclasses import dataclass+from dataclasses import dataclass, replacefrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -307,19 +307,19 @@ class PageGenerator(PerTypeGenerationMixin):target_path=parsed.file_info.path,content_hash=content_hash,)- # Phase-2 harvest: pull any trailing decision block out of the page- # before it is wrapped + stored. The gate verifies each quote against- # ``file_source_snippet`` — exactly what the model was shown — so a- # quote it can't have seen is dropped. Stored on page.metadata for the- # persistence layer to fold into the evidence pipeline.- harvested: list[dict] = []- if self._config.harvest_decisions:- clean_content, harvested = harvest_decisions(- response.content,- source_text=ctx.file_source_snippet or "",- evidence_file=parsed.file_info.path,+ harvested = self._strip_harvested_decisions(response, ctx, parsed.file_info.path)+ # Cross-check LLM output against actual symbols+ hal_warnings = _validate_symbol_references(response.content, parsed)+ repair_outcome: str | None = None+ threshold = self._config.repair_warning_threshold+ if (+ threshold > 0+ and len(hal_warnings) >= threshold+ and not response.usage.get("reused_from_prior_run")+ ):+ response, harvested, hal_warnings, repair_outcome = await self._repair_file_page(+ parsed, ctx, user_prompt, response, harvested, hal_warnings)- response.content = clean_contentpage = self._build_generated_page("file_page",parsed.file_info.path,@@ -331,8 +331,6 @@ class PageGenerator(PerTypeGenerationMixin):)if harvested:page.metadata["harvested_decisions"] = harvested- # Cross-check LLM output against actual symbols- hal_warnings = _validate_symbol_references(response.content, parsed)if hal_warnings:log.warning("hallucination_check",@@ -341,9 +339,85 @@ class PageGenerator(PerTypeGenerationMixin):refs=hal_warnings[:5],)page.metadata["hallucination_warnings"] = hal_warnings+ if repair_outcome:+ page.metadata["self_repair"] = repair_outcome_attach_file_provenance(page, ctx)return page+ def _strip_harvested_decisions(+ self,+ response: GeneratedResponse,+ ctx: FilePageContext,+ evidence_file: str,+ ) -> list[dict]:+ """Phase-2 harvest: pull any trailing decision block out of the page+ before it is wrapped + stored. The gate verifies each quote against+ ``file_source_snippet`` — exactly what the model was shown — so a+ quote it can't have seen is dropped. Returned for page.metadata so the+ persistence layer can fold it into the evidence pipeline.+ """+ if not self._config.harvest_decisions:+ return []+ clean_content, harvested = harvest_decisions(+ response.content,+ source_text=ctx.file_source_snippet or "",+ evidence_file=evidence_file,+ )+ response.content = clean_content+ return harvested++ async def _repair_file_page(+ self,+ parsed: ParsedFile,+ ctx: FilePageContext,+ user_prompt: str,+ response: GeneratedResponse,+ harvested: list[dict],+ hal_warnings: list[str],+ ) -> tuple[GeneratedResponse, list[dict], list[str], str]:+ """Bounded self-repair for hallucinated symbol references.++ Re-calls the provider once with the invalid refs named in a corrective+ note, re-validates, and keeps whichever draft validates cleaner. Both+ calls' tokens are folded into the kept response so page-level token+ accounting (and cost) reflects the real spend. One retry per page,+ never recursive; the caller has already excluded reused prior pages.+ """+ path = parsed.file_info.path+ correction = (+ "\n\nIMPORTANT CORRECTION: a previous draft of this page referenced "+ "identifiers that do not exist in this file: "+ + ", ".join(f"`{r}`" for r in sorted(hal_warnings)[:15])+ + ". Do not mention these names. Only reference symbols, imports, "+ "exports, and files that appear in the context above."+ )+ # No target_path/content_hash here: the retry must reach the provider,+ # since the cross-run reuse gate would hand back the draft that failed.+ retry = await self._call_provider("file_page", user_prompt + correction, str(uuid.uuid4()))+ retry_harvested = self._strip_harvested_decisions(retry, ctx, path)+ retry_warnings = _validate_symbol_references(retry.content, parsed)+ improved = len(retry_warnings) < len(hal_warnings)+ log.info(+ "hallucination_repair",+ path=path,+ warnings_before=len(hal_warnings),+ warnings_after=len(retry_warnings),+ kept="retry" if improved else "original",+ )+ if improved:+ kept, kept_harvested, kept_warnings = retry, retry_harvested, retry_warnings+ else:+ kept, kept_harvested, kept_warnings = response, harvested, hal_warnings+ # replace() rather than mutating: either draft may also live in the+ # in-memory prompt cache, which must keep its per-call token counts.+ kept = replace(+ kept,+ input_tokens=response.input_tokens + retry.input_tokens,+ output_tokens=response.output_tokens + retry.output_tokens,+ cached_tokens=response.cached_tokens + retry.cached_tokens,+ )+ return kept, kept_harvested, kept_warnings, "improved" if improved else "kept_original"+async def _generate_file_page_tier2(self,parsed: ParsedFile,diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.pyindex ea16a0a51..793a0d72e 100644--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py@@ -542,7 +542,13 @@ class _GenerationRun:try:from ..interlinking import attach_wiki_links_and_backlinks- attach_wiki_links_and_backlinks(all_pages, self.parsed_files)+ attach_wiki_links_and_backlinks(+ all_pages,+ self.parsed_files,+ # On incremental updates only the affected pages are in+ # all_pages; the persisted ids keep resolution repo-wide.+ prior_page_ids=list(self.gen._prior_pages or {}),+ )except Exception as exc:log.debug("interlinking.failed", error=str(exc))diff --git a/packages/core/src/repowise/core/generation/page_generator/validation.py b/packages/core/src/repowise/core/generation/page_generator/validation.pyindex ffa27b461..defa9727c 100644--- a/packages/core/src/repowise/core/generation/page_generator/validation.py+++ b/packages/core/src/repowise/core/generation/page_generator/validation.py@@ -201,11 +201,7 @@ def _validate_symbol_references(# (catches Click command names, decorator arguments, dict keys, etc.)# The source is in the context, but we only have the parsed file here.# Use docstring and symbol names as a cheap approximation.- if (- hasattr(parsed, "file_info")- and hasattr(parsed.file_info, "path")- and parsed.docstring- ):+ if hasattr(parsed, "file_info") and hasattr(parsed.file_info, "path") and parsed.docstring:known.update(w for w in parsed.docstring.split() if w.isidentifier())warnings: list[str] = []@@ -221,9 +217,17 @@ def _validate_symbol_references(# Skip all-uppercase (likely constants from other files: `MAX_RETRIES`)if ref.isupper():continue+ # Skip dotted refs entirely: they are member/attribute accesses+ # (`GeneratedPage.updated_at`, `config.coverage_pct`) or qualified+ # module paths. Dataclass fields, ORM columns, and cross-file+ # attribute chains are not AST symbols, so they cannot be verified+ # here and were the dominant false-positive source in dogfooding.+ # Whole-name hallucinations — the high-signal case — are+ # single-segment and still flagged below.+ if "." in ref:+ continue# Check against known names- base = ref.split(".")[-1]- if ref in known or base in known:+ if ref in known:continue# Skip if the ref is a substring of any known symbol (covers partial# references like `parse` when `parse_file` exists)diff --git a/packages/core/src/repowise/core/generation/related_pages.py b/packages/core/src/repowise/core/generation/related_pages.pyindex cc7bed178..209544637 100644--- a/packages/core/src/repowise/core/generation/related_pages.py+++ b/packages/core/src/repowise/core/generation/related_pages.py@@ -18,6 +18,7 @@ from typing import Anyimport structlog+from .interlinking import FILE_BACKED_PAGE_TYPES as _FILE_BACKEDfrom .interlinking import LinkIndexfrom .models import GeneratedPage@@ -30,9 +31,6 @@ _REASON_PRIORITY = ("imports", "imported-by", "co-changes-with", "same-module")_PER_REASON_CAP = 5_TOTAL_CAP = 12-# Page types whose target_path is a real file path.-_FILE_BACKED = frozenset({"file_page", "api_contract", "infra_page"})-def _co_change_partners(git_meta: dict | None) -> list[tuple[str, float]]:"""``(partner_path, co_change_count)`` pairs, strongest first."""@@ -93,12 +91,12 @@ def attach_related_pages(returnindex = LinkIndex.build(pages)+ index.add_prior_page_ids(prior_page_ids)titles = {p.page_id: p.title for p in pages}for pid in prior_page_ids or ():- ptype, _, tpath = str(pid).partition(":")- if ptype in _FILE_BACKED and tpath:- index.by_path.setdefault(tpath, pid)- titles.setdefault(pid, tpath)+ _, _, tpath = str(pid).partition(":")+ if tpath:+ titles.setdefault(str(pid), tpath)pr = pagerank or {}# Adjacency from the import graph: src imports dst.diff --git a/packages/core/src/repowise/core/generation/report.py b/packages/core/src/repowise/core/generation/report.pyindex 1bda65051..d5d59895a 100644--- a/packages/core/src/repowise/core/generation/report.py+++ b/packages/core/src/repowise/core/generation/report.py@@ -24,6 +24,7 @@ class GenerationReport:decisions_extracted: int = 0elapsed_seconds: float = 0.0hallucination_warning_count: int = 0+ self_repaired_page_count: int = 0@classmethoddef from_pages(@@ -37,6 +38,7 @@ class GenerationReport:) -> GenerationReport:by_type = dict(Counter(p.page_type for p in pages))hal_count = sum(1 for p in pages if p.metadata.get("hallucination_warnings"))+ repair_count = sum(1 for p in pages if p.metadata.get("self_repair"))return cls(pages_by_type=by_type,total_input_tokens=sum(p.input_tokens for p in pages),@@ -47,6 +49,7 @@ class GenerationReport:decisions_extracted=decisions_count,elapsed_seconds=elapsed,hallucination_warning_count=hal_count,+ self_repaired_page_count=repair_count,)@property@@ -92,5 +95,7 @@ def render_report(report: GenerationReport, console: object) -> None:"Hallucination warnings",f"[yellow]{report.hallucination_warning_count}[/yellow]",)+ if report.self_repaired_page_count:+ table.add_row("Self-repaired pages", str(report.self_repaired_page_count))console.print(table) # type: ignore[union-attr]diff --git a/packages/core/src/repowise/core/generation/templates/file_page.j2 b/packages/core/src/repowise/core/generation/templates/file_page.j2index 517b3ca01..d27abdd1e 100644--- a/packages/core/src/repowise/core/generation/templates/file_page.j2+++ b/packages/core/src/repowise/core/generation/templates/file_page.j2@@ -234,4 +234,11 @@ examples where helpful.This file is stable and low-centrality. Provide a concise overview focused on thepublic API only. Skip implementation details.{% endif %}+Cross-references: when a dependency, dependent, or co-change partner listed+above genuinely explains this file's behavior, name it in backticks exactly as+listed (e.g. `path/to/file.py` or `SymbolName`) so the reference resolves to a+wiki link. Do not add references purely for link density, do not mention a file+just because it imports this one, and never name a file or symbol that is not+listed in the context above.+Generate a complete wiki page following the sections above.diff --git a/packages/core/src/repowise/core/generation/templates/module_page.j2 b/packages/core/src/repowise/core/generation/templates/module_page.j2index 23b9de2d1..b05f554fd 100644--- a/packages/core/src/repowise/core/generation/templates/module_page.j2+++ b/packages/core/src/repowise/core/generation/templates/module_page.j2@@ -88,6 +88,11 @@ Most active file: `{{ module_git_summary.most_active_file }}`({{ module_git_summary.most_active_commits_90d }} commits in 90 days){% endif %}+Cross-references: name the module's key files and the neighboring modules it consumes+or serves in backticks exactly as listed above so they resolve to wiki links. Mention+a neighbor only where it explains this module's role: no references added purely for+link density, and no reciprocal mentions out of symmetry.+Generate a complete wiki page following the sections above. Required sections in theoutput: ## Overview, ## Public API Summary, ## Architecture Notes. Use the suppliedkey files, decisions, and external systems to ground the narrative; do not fabricatediff --git a/tests/unit/generation/test_interlinking.py b/tests/unit/generation/test_interlinking.pyindex 29ca3bd81..5aa6c7565 100644--- a/tests/unit/generation/test_interlinking.py+++ b/tests/unit/generation/test_interlinking.py@@ -122,6 +122,46 @@ def test_index_resolves_basename_when_unique():)+def test_prior_page_ids_widen_forward_resolution():+ """On an incremental update, refs to pages outside the run's subset+ resolve via the persisted prior ids; backlinks stay run-local."""+ pages = [+ _make_page(+ "file_page",+ "src/app/main.py",+ content="Delegates to `src/lib/utils.py` and reuses `helpers.py`.",+ ),+ ]++ attach_wiki_links_and_backlinks(+ pages,+ prior_page_ids=[+ "file_page:src/lib/utils.py",+ "file_page:src/lib/helpers.py",+ "module_page:community-3", # not path-shaped, ignored+ ],+ )++ targets = {link["target_page_id"] for link in pages[0].metadata["wiki_links"]}+ assert targets == {"file_page:src/lib/utils.py", "file_page:src/lib/helpers.py"}+++def test_current_run_pages_win_over_prior_ids():+ """A page regenerated this run resolves to itself, not a stale prior id."""+ pages = [+ _make_page("file_page", "a.py", content="Uses `b.py`."),+ _make_page("file_page", "b.py", content=""),+ ]++ attach_wiki_links_and_backlinks(pages, prior_page_ids=["file_page:b.py"])++ assert pages[0].metadata["wiki_links"] == [+ {"anchor": "b.py", "target_page_id": "file_page:b.py", "kind": "file"}+ ]+ # b.py is in the run, so its backlink from a.py is materialized.+ assert pages[1].metadata["backlinks"][0]["source_page_id"] == "file_page:a.py"++def test_link_index_build_returns_expected_keys():pages = [_make_page("file_page", "src/x.py"),diff --git a/tests/unit/generation/test_self_repair.py b/tests/unit/generation/test_self_repair.pynew file mode 100644index 000000000..f25773a3d--- /dev/null+++ b/tests/unit/generation/test_self_repair.py@@ -0,0 +1,145 @@+"""Bounded self-repair for hallucinated symbol references.++When ``_validate_symbol_references`` flags >= ``repair_warning_threshold``+invalid backtick refs on a tier-1 file page, the generator re-calls the+provider exactly once with a corrective note naming the bad refs and keeps+whichever draft validates cleaner. Reused prior-run pages are never retried.+"""++from __future__ import annotations++import networkx as nx++from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.models import GenerationConfig, compute_page_id+from repowise.core.generation.page_generator import PageGenerator, PriorPage+from repowise.core.ingestion.models import ParsedFile+from repowise.core.providers.llm.base import GeneratedResponse+from repowise.core.providers.llm.mock import MockProvider++from .conftest import _make_file_info, _make_symbol++# `PhantomThing` / `GhostHelper` match no symbol, import, or export of the+# parsed file below, are >2 chars, mixed-case, and path-free, so the+# validator flags them. `Thing` is the file's real (and only) symbol.+BAD_CONTENT = "## Overview\n\nUses `PhantomThing` and `GhostHelper` for math."+CLEAN_CONTENT = "## Overview\n\nUses `Thing` for math."+++def _parsed(path: str = "pkg/mod.py") -> ParsedFile:+ return ParsedFile(+ file_info=_make_file_info(path=path),+ symbols=[_make_symbol(name="Thing", file_path=path)],+ imports=[],+ exports=["Thing"],+ docstring="mod",+ parse_errors=[],+ content_hash="h",+ )+++def _gen_and_ctx(responses: list[GeneratedResponse], **config_overrides):+ config = GenerationConfig(**config_overrides)+ provider = MockProvider(responses=responses)+ gen = PageGenerator(provider, ContextAssembler(config), config)+ parsed = _parsed()+ g = nx.DiGraph()+ g.add_node(parsed.file_info.path)+ ctx = gen._assembler.assemble_file_page(parsed, g, {}, {}, {}, b"x = 1\n")+ return gen, provider, parsed, ctx+++async def test_retry_adopts_cleaner_draft_and_sums_tokens() -> None:+ gen, provider, parsed, ctx = _gen_and_ctx(+ [+ GeneratedResponse(BAD_CONTENT, 100, 50),+ GeneratedResponse(CLEAN_CONTENT, 200, 80),+ ]+ )++ page = await gen._generate_file_page_from_ctx(parsed, ctx)++ assert provider.call_count == 2+ assert page.content == CLEAN_CONTENT+ assert page.metadata["self_repair"] == "improved"+ assert "hallucination_warnings" not in page.metadata+ # Both calls' tokens land on the page so cost accounting is honest.+ assert page.input_tokens == 300+ assert page.output_tokens == 130+++async def test_retry_prompt_names_bad_refs_on_top_of_original() -> None:+ gen, provider, parsed, ctx = _gen_and_ctx(+ [+ GeneratedResponse(BAD_CONTENT, 100, 50),+ GeneratedResponse(CLEAN_CONTENT, 200, 80),+ ]+ )++ await gen._generate_file_page_from_ctx(parsed, ctx)++ original = provider.calls[0]["user_prompt"]+ retry = provider.calls[1]["user_prompt"]+ assert retry.startswith(original)+ assert "`PhantomThing`" in retry+ assert "`GhostHelper`" in retry+++async def test_retry_keeps_original_when_not_improved() -> None:+ gen, provider, parsed, ctx = _gen_and_ctx(+ [+ GeneratedResponse(BAD_CONTENT, 100, 50),+ GeneratedResponse(BAD_CONTENT, 200, 80), # retry just as bad+ ]+ )++ page = await gen._generate_file_page_from_ctx(parsed, ctx)++ assert provider.call_count == 2+ assert page.content == BAD_CONTENT+ assert page.metadata["self_repair"] == "kept_original"+ assert sorted(page.metadata["hallucination_warnings"]) == ["GhostHelper", "PhantomThing"]+ assert page.input_tokens == 300 # retry cost still counted+++async def test_no_retry_below_threshold() -> None:+ one_warning = "Uses `PhantomThing` and `Thing`."+ gen, provider, parsed, ctx = _gen_and_ctx([GeneratedResponse(one_warning, 100, 50)])++ page = await gen._generate_file_page_from_ctx(parsed, ctx)++ assert provider.call_count == 1+ assert "self_repair" not in page.metadata+ assert page.metadata["hallucination_warnings"] == ["PhantomThing"]+++async def test_zero_threshold_disables_retry() -> None:+ gen, provider, parsed, ctx = _gen_and_ctx(+ [GeneratedResponse(BAD_CONTENT, 100, 50)],+ repair_warning_threshold=0,+ )++ page = await gen._generate_file_page_from_ctx(parsed, ctx)++ assert provider.call_count == 1+ assert "self_repair" not in page.metadata+ assert len(page.metadata["hallucination_warnings"]) == 2+++async def test_reused_prior_page_is_never_retried() -> None:+ gen, provider, parsed, ctx = _gen_and_ctx([GeneratedResponse(CLEAN_CONTENT, 100, 50)])+ gen._prior_pages = {+ compute_page_id("file_page", parsed.file_info.path): PriorPage(+ source_hash="unused",+ model_name=provider.model_name,+ content=BAD_CONTENT,+ content_hash=gen._reuse_content_hash(parsed),+ )+ }++ page = await gen._generate_file_page_from_ctx(parsed, ctx)++ assert provider.call_count == 0 # reuse gate hit, no LLM call at all+ assert page.content == BAD_CONTENT+ assert "self_repair" not in page.metadata+ assert len(page.metadata["hallucination_warnings"]) == 2diff --git a/tests/unit/generation/test_symbol_validation.py b/tests/unit/generation/test_symbol_validation.pynew file mode 100644index 000000000..41e86c230--- /dev/null+++ b/tests/unit/generation/test_symbol_validation.py@@ -0,0 +1,42 @@+"""Unit tests for the symbol-reference hallucination validator."""++from __future__ import annotations++from repowise.core.generation.page_generator.validation import _validate_symbol_references+from repowise.core.ingestion.models import ParsedFile++from .conftest import _make_file_info, _make_symbol+++def _parsed() -> ParsedFile:+ return ParsedFile(+ file_info=_make_file_info(path="pkg/mod.py"),+ symbols=[_make_symbol(name="Thing", file_path="pkg/mod.py")],+ imports=[],+ exports=["Thing"],+ docstring="mod",+ parse_errors=[],+ content_hash="h",+ )+++def test_flags_unknown_single_name() -> None:+ warns = _validate_symbol_references("Uses `PhantomThing` heavily.", _parsed())+ assert warns == ["PhantomThing"]+++def test_known_symbol_and_export_pass() -> None:+ assert _validate_symbol_references("`Thing` is exported.", _parsed()) == []+++def test_dotted_member_access_is_never_flagged() -> None:+ """Attribute chains can't be verified from the symbol table (dataclass+ fields and ORM columns are not symbols), so dotted refs are skipped even+ when no segment is known."""+ content = "`Thing.updated_at` and `config.coverage_pct` and `Fake.member` too."+ assert _validate_symbol_references(content, _parsed()) == []+++def test_paths_commands_and_short_refs_pass() -> None:+ content = "See `pkg/mod.py`, run `repowise-update`, index `db` by `x`."+ assert _validate_symbol_references(content, _parsed()) == []