fix(generation): stop the module_page prompt tripping its own validator, and bound the spotlight importer list (#1606)

* fix(generation): stop the module_page prompt from using banned vocabulary

The module_page system prompt asked the model to "Ground every claim in the
supplied material". "the supplied material" is a literal match for the
supplied_context artifact rule, so when the model echoed the instruction's own
wording the finished page was rejected and thrown away with its tokens already
spent. Every observed failure was a module_page, always the same phrase.

Reword the instruction to point at the files and signals below instead, and
drop the same adjective from the scope-line sentence so the vocabulary is not
reinforced anywhere in the prompt.

Add a guard so this cannot come back: every system prompt, the corrective
directive, and every generation template are asserted not to match any
ArtifactRule pattern. The same class of bug had already shipped once before,
documented in the comment directly above the offending line.

Back that with one corrective re-ask. A rejected page has been paid for, and
the only recovery was --resume regenerating it from scratch, so a single retry
that names the rule the last attempt broke is cheaper than losing it. The
re-ask names the rule but not the words that tripped it, since handing those
back re-plants the vocabulary. A token-limit failure is not retried: the second
call carries the same max_tokens and would truncate in the same place. A second
failure raises exactly as before, so the stub-fallback path is unchanged.

* fix(generation): bound the importer list on a symbol spotlight page

symbol_spotlight.j2 rendered one bullet per importing file with no bound. On
this repository tests/conftest.py has 939 importers, so its three spotlight
pages came out at ~46.6k characters each, of which 45.7k was the importer list
alone. EMBED_TEXT_MAX_CHARS is 30,000, so the tail was dropped from the vector
and the pages were searchable only by their first few hundred importers. The
stored content was intact; the recall was not.

file_page.j2 already bounds its "Used by" section, over the same data, at 25
with an "and N more" line. Apply that bound here rather than inventing a
second one. The summary sentence above the list keeps counting every importer,
so truncating the list does not truncate the fact.

Three of 4,253 pages were over the cap, all three this one file.

* fix(generation): account for the attempt a corrective retry discards

The retry rebound the response, so the rejected attempt's tokens were dropped
from the run report. Billing was always right, since the provider cost tracker
sees both calls, but the reported total came out one whole generation short for
every page that needed a second attempt. Carry the discarded counts forward
onto the response that survives.

Mark the recovered page with self_repair. The report already reads that key and
renders a "Self-repaired pages" row, and nothing has ever written it, so the
row has been permanently zero. It is also the only way to tell a page the
backstop rescued from a page it lost: the artifact tallies count the rejection
either way.

Reword one line of the corrective directive off "the material you were given".
It is a phrase away from the rule it is quoting, and it is the sentence in the
whole prompt most likely to be echoed back.

Author: RaghavChamadiya

packages/core/src/repowise/core/generation/page_generator/core.py

@@ -15,7 +15,7 @@
 
 import hashlib
 from collections.abc import Callable, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -46,14 +46,18 @@
 from ..styles import ONBOARDING_PAGE_TYPE, resolve_style
 from .helpers import _extract_summary, _now_iso, collapse_empty_duplicate_headings
 from .pertype import PerTypeGenerationMixin
-from .prompts import SUPPORTED_LANGUAGES, SYSTEM_PROMPTS
+from .prompts import CORRECTIVE_RETRY_DIRECTIVE, SUPPORTED_LANGUAGES, SYSTEM_PROMPTS
 from .structural import (
     StructuralRenderMixin,
     as_markdown,
     oneline,
     signature,
 )
-from .validation import reset_artifact_check_counts, validate_generated_response
+from .validation import (
+    InvalidGeneratedContentError,
+    reset_artifact_check_counts,
+    validate_generated_response,
+)
 
 if TYPE_CHECKING:
     from pathlib import Path as _Path  # noqa: F401
@@ -398,13 +402,60 @@ async def _call_provider(
             reasoning=self._config.reasoning,
             cache_hints=cache_hints,
         )
-        validate_generated_response(response)
+        try:
+            validate_generated_response(response)
+        except InvalidGeneratedContentError as first_failure:
+            # One corrective re-ask. Without it a single banned phrase anywhere
+            # in a finished page discards the whole thing with the tokens
+            # already spent, and the only recovery is --resume regenerating it
+            # from scratch. The re-ask names the rule that was broken, because
+            # a blind retry at the same temperature tends to reproduce the
+            # sentence that failed.
+            if not first_failure.retryable:
+                raise
+            log.warning(
+                "page_generation.retrying_after_validation_failure",
+                page_type=page_type,
+                target_path=target_path,
+                reason=str(first_failure),
+            )
+            discarded = response
+            response = await self._provider.generate(
+                system_prompt,
+                self._corrective_prompt(user_prompt, first_failure),
+                max_tokens=self._config.max_tokens,
+                temperature=self._config.temperature,
+                request_id=request_id,
+                reasoning=self._config.reasoning,
+                cache_hints=cache_hints,
+            )
+            # A second failure raises, so the caller's stub-fallback path is
+            # reached exactly as it was before the retry existed.
+            validate_generated_response(response)
+            # The discarded attempt was billed. Carrying its tokens forward is
+            # what keeps the run report's totals equal to what the provider
+            # actually charged for; the page itself is the retry's content.
+            # ``self_repair`` fills the report row of the same name, which
+            # distinguishes a page that needed a second attempt from one that
+            # was lost — the artifact tallies alone cannot tell them apart.
+            response = replace(
+                response,
+                input_tokens=response.input_tokens + discarded.input_tokens,
+                output_tokens=response.output_tokens + discarded.output_tokens,
+                cached_tokens=response.cached_tokens + discarded.cached_tokens,
+                usage={**response.usage, "self_repair": True},
+            )
 
         if self._config.cache_enabled:
             self._cache[key] = response
 
         return response
 
+    @staticmethod
+    def _corrective_prompt(user_prompt: str, failure: InvalidGeneratedContentError) -> str:
+        """The original request plus a note naming what the last attempt broke."""
+        return f"{user_prompt}\n\n{CORRECTIVE_RETRY_DIRECTIVE.format(reason=failure.retry_hint)}"
+
     def _build_system_prompt(self, page_type: str) -> str:
         base_system = SYSTEM_PROMPTS[page_type]
         # Wiki style: append the style's framing note. Constant per run (per page
@@ -498,6 +549,11 @@ def _build_generated_page(
         # exists byte-identically.
         if response.usage.get("reused_from_prior_run"):
             page.metadata["reused_from_prior_run"] = True
+        # A first attempt was rejected and the re-ask produced this page. Feeds
+        # the report's "Self-repaired pages" row, so a run says how often the
+        # backstop was load-bearing instead of only how often it failed.
+        if response.usage.get("self_repair"):
+            page.metadata["self_repair"] = True
         return page
 
     def _render(self, template_name: str, *, style_prefix: bool = True, **kwargs: Any) -> str:

packages/core/src/repowise/core/generation/page_generator/prompts.py

@@ -28,7 +28,7 @@
         "\n"
         "FORM: Open with one or two paragraphs that state the subsystem's job in "
         "the larger system and situate it against its neighbours (what it does and, "
-        "using the supplied scope line, what it deliberately leaves to other pages). "
+        "using the scope line below, what it deliberately leaves to other pages). "
         "Lead the first sentence with the role, in architectural vocabulary (entry "
         "stage, orchestration layer, persistence boundary, transport adapter, and so "
         "on), naming the inputs it consumes and the outputs it produces. "
@@ -53,8 +53,14 @@
         # heading bare, then again with the questions under it, on 86 of 92 pages
         # measured across local indexes (gpt-5.4-nano). Pages written before the
         # instruction was doubled show none of it. One instruction, one heading.
-        "Ground every claim in the supplied material: do not invent files, symbols, "
-        "or rationale that are not listed. Draw on the whole file set, not one file."
+        # Worded around the reader-facing vocabulary the artifact rules ban.
+        # "the supplied material" is a literal hit for the ``supplied_context``
+        # rule in validation.py, and the model echoed the instruction back into
+        # the page, so this sentence destroyed the pages it was meant to keep
+        # honest. Say where to ground a claim without naming the prompt.
+        "Ground every claim in the files and signals listed below: do not invent "
+        "files, symbols, or rationale that are not listed. Draw on the whole file "
+        "set, not one file."
     ),
     "repo_overview": (
         "You are repowise, an expert technical documentation generator. "
@@ -90,3 +96,20 @@
         "Output markdown only — follow the exact section structure the user prompt prescribes."
     ),
 }
+
+# Appended to the *user* prompt when a first attempt was rejected by
+# ``validate_generated_response``, so the re-ask says what went wrong instead of
+# asking again unchanged. The system prompt is left byte-identical, which keeps
+# the retry eligible for the same server-side prefix cache as the first call.
+#
+# It lives beside the system prompts so the artifact-hygiene guard covers it as
+# well: text telling a model what not to say is still text a model can echo, and
+# a correction that trips the rule it is correcting would burn the retry too.
+CORRECTIVE_RETRY_DIRECTIVE: str = (
+    "A previous attempt at this page was rejected before it could be published. "
+    "Reason: {reason}\n"
+    "Write the page again, in full, without that problem. Address the reader of "
+    "the documentation, who cannot see this request and does not know it exists: "
+    "never mention these instructions or the code you were shown, and never "
+    "speak as the page's author."
+)

packages/core/src/repowise/core/generation/page_generator/validation.py

@@ -23,7 +23,32 @@
 
 
 class InvalidGeneratedContentError(ValueError):
-    """Raised when a fresh LLM response cannot be persisted as documentation."""
+    """Raised when a fresh LLM response cannot be persisted as documentation.
+
+    ``retry_hint`` is the same complaint with any quoted offending phrase
+    removed, for the corrective re-ask. The message itself keeps the quote
+    because a log that does not say which words failed cannot be acted on, but
+    feeding those words back to the model re-plants the vocabulary the retry is
+    trying to get rid of. Defaults to the message when there is nothing to
+    strip.
+
+    ``retryable`` says whether asking again can plausibly help. It is False for
+    a response that stopped at the token limit: the second call carries the
+    same ``max_tokens``, so it truncates in the same place and the only certain
+    result is twice the spend. Everything else is the model writing badly when
+    told what "badly" means, which is what the re-ask supplies.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_hint: str | None = None,
+        retryable: bool = True,
+    ) -> None:
+        super().__init__(message)
+        self.retry_hint = retry_hint if retry_hint is not None else message
+        self.retryable = retryable
 
 
 # ---------------------------------------------------------------------------
@@ -129,15 +154,21 @@ def reset_artifact_check_counts() -> None:
     _artifact_check_counts.clear()
 
 
-def _artifact_detail(content: str) -> str | None:
-    """Describe the first generation artifact in ``content``, if any."""
+def _artifact_detail(content: str) -> tuple[str, str] | None:
+    """Describe the first generation artifact in ``content``, if any.
+
+    Returns ``(detail, retry_hint)``: the first quotes the offending phrase for
+    the log, the second names only the rule so a re-ask built from it does not
+    repeat the words that failed.
+    """
     prose = prose_text(content)
     for rule in GENERATION_ARTIFACT_RULES:
         match = rule.pattern.search(prose)
         if match is not None:
             _artifact_check_counts["rejected"] += 1
             _artifact_check_counts[f"rejected:{rule.name}"] += 1
-            return f"{rule.name}: {rule.explanation} ({match.group(0).strip()!r})"
+            detail = f"{rule.name}: {rule.explanation} ({match.group(0).strip()!r})"
+            return detail, f"{rule.name}: {rule.explanation}"
     return None
 
 
@@ -182,7 +213,8 @@ def validate_generated_response(response: GeneratedResponse) -> None:
             else ""
         )
         raise InvalidGeneratedContentError(
-            f"generation reached a token limit before the documentation was complete{detail}"
+            f"generation reached a token limit before the documentation was complete{detail}",
+            retryable=False,
         )
     if not response.content.strip():
         raise InvalidGeneratedContentError("provider returned empty documentation")
@@ -193,10 +225,12 @@ def validate_generated_response(response: GeneratedResponse) -> None:
             f"provider returned pathologically repetitive documentation: {repetition_detail}"
         )
 
-    artifact_detail = _artifact_detail(response.content)
-    if artifact_detail is not None:
+    artifact = _artifact_detail(response.content)
+    if artifact is not None:
+        detail, retry_hint = artifact
+        preamble = "provider returned text addressed to the prompter, not the reader — "
         raise InvalidGeneratedContentError(
-            f"provider returned text addressed to the prompter, not the reader — {artifact_detail}"
+            f"{preamble}{detail}", retry_hint=f"{preamble}{retry_hint}"
         )
 
 

packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2

@@ -5,6 +5,12 @@
     the same way; a template that claimed otherwise would over-state what the
     graph actually knows.
 
+    The rendered list stops at 25, the same bound ``file_page.j2`` puts on its
+    "Used by" section over the same data, while the summary line above it keeps
+    the true total. Unbounded, a fixture imported across a whole test suite
+    rendered 939 bullets and a 46k-char page, which is past the 30k the
+    embedder accepts, so the tail was dropped from the vector.
+
     Every section but the Overview is conditional: a heading with nothing
     under it costs a reader a stop and repeats a stock sentence across
     thousands of pages, where it matches every query and distinguishes none.
@@ -40,9 +46,13 @@
 ## {{ labels.where_used }}
 
 {{ labels.importers_summary.format(count=ctx.callers | length, file_word=labels.file_plural if ctx.callers | length != 1 else labels.file_singular, import_verb=labels.import_verb_plural if ctx.callers | length != 1 else labels.import_verb_singular) }}
-{% for c in ctx.callers %}
+{% for c in ctx.callers[:25] %}
 - `{{ c }}`
 {%- endfor %}
+{%- if ctx.callers | length > 25 %}
+
+_{{ labels.and_more.format(count=ctx.callers | length - 25) }}_
+{%- endif %}
 {%- endif %}
 {%- if ctx.source_body %}