Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(generation): stop a keyless wiki warning about every page it has (#1383)

Raghav Chamadiya8008d38e13bb
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index 8931302e3..e2c2b745a 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -440,22 +440,45 @@ class GenerationConfig:
# one. These three values are the distinctions that are actually available at
# the moment a page is written, and no more than that — a finer scale would be
# a number with nothing behind it.
-
-#: A page whose only renderer is a template: file pages, symbol spotlights.
-#: Every statement on it came from the parse, the import graph or git history,
-#: and no model saw it. There is nothing on the page to be unsure about.
+#
+# The axis is *trust*, not completeness. A page can be thin and still be
+# entirely true, and the two questions have separate carriers: whether a model
+# has written a page yet is ``provider_name`` (see ``MODEL_WRITTEN_PAGE_TYPES``
+# and the reader's upgrade affordance), and confidence stays out of it.
+# Collapsing the two is what this comment block previously got wrong; see
+# ``STUB_PAGE_CONFIDENCE``.
+
+#: A page whose statements all came from the parse, the import graph or git
+#: history, with no model in the loop: file pages, symbol spotlights, and the
+#: deterministic renderings of the four model-written types produced by a
+#: keyless run. There is nothing on the page to be unsure about.
TEMPLATE_PAGE_CONFIDENCE = 1.0
#: A page a model wrote from assembled material. It is grounded in that
#: material and checked against it, but it is a summary of the code rather
#: than an extraction from it, so it is not the same claim a template page
-#: makes. Above the reader UI's banner threshold: worth reading normally.
+#: makes. Nothing gates on the difference; it is reported, not enforced.
MODEL_PAGE_CONFIDENCE = 0.8
-#: The structural stub standing in for a page a model was meant to write —
-#: because the provider call failed, or because no key was configured. It is
-#: real material with the prose missing, which is the one case a reader has to
-#: be told about, so it sits below the banner threshold.
+#: The structural stub substituted for a model page whose provider call
+#: **failed**, and only that. Paired with :data:`STUB_FALLBACK_ERROR`, which
+#: carries the error; :func:`is_stub_fallback` is the predicate.
+#:
+#: This deliberately no longer covers the keyless run. Both cases render the
+#: same template, so stamping both 0.3 read as "0.3 is what a template module
+#: page is worth". A keyless run produces *every* model-written page that way,
+#: so the reader's banner landed on the repository overview and all of its
+#: subsystem pages at once, on precisely the wikis with nothing wrong with
+#: them: an index built without a key is that shape by design, and the product
+#: told its reader to distrust all of it.
+#:
+#: What survives is the case the number was introduced for: a page that was
+#: meant to carry prose and lost it to an outage. That page is a stand-in for
+#: something the run intended and failed to produce, and it is the one state a
+#: reader cannot infer from the page itself. The keyless rendering stands in
+#: for nothing. It is the finished deterministic page, and it takes
+#: :data:`TEMPLATE_PAGE_CONFIDENCE`, exactly as ``_model_free_onboarding_page``
+#: already argued for the subkinds it renders without a model.
STUB_PAGE_CONFIDENCE = 0.3
diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.py
index 1bbfe05cb..e39e741a3 100644
--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py
+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py
@@ -24,6 +24,7 @@ from ..context_assembler import FilePageContext
from ..models import (
GENERATION_LEVELS,
STUB_FALLBACK_ERROR,
+ STUB_PAGE_CONFIDENCE,
GeneratedPage,
compute_source_hash,
)
@@ -52,8 +53,18 @@ def _stub_fallback(page: GeneratedPage, page_type: str, exc: Exception) -> Gener
it back: this page still has to count as a failure in the job checkpoint,
and must not reach the vector store that ``--resume`` treats as its record
of what is already done.
+
+ Lowering the confidence here rather than in ``_stub_page`` is the whole of
+ the distinction. Both paths render the identical template, so the bytes
+ cannot tell them apart. What differs is that this one was *supposed* to be
+ prose. A keyless run's stub is a finished deterministic page and keeps
+ :data:`TEMPLATE_PAGE_CONFIDENCE`; this one is a stand-in for something the
+ run intended and could not produce, and that is the state worth flagging to
+ a reader. Stamping both meant a keyless wiki flagged every model-written
+ page it had, which is all of them.
"""
page.metadata[STUB_FALLBACK_ERROR] = str(exc)[:500]
+ page.confidence = STUB_PAGE_CONFIDENCE
log.warning(
"page_generation.stub_fallback",
page_type=page_type,
diff --git a/packages/core/src/repowise/core/generation/page_generator/structural.py b/packages/core/src/repowise/core/generation/page_generator/structural.py
index 380c30c63..87bd64135 100644
--- a/packages/core/src/repowise/core/generation/page_generator/structural.py
+++ b/packages/core/src/repowise/core/generation/page_generator/structural.py
@@ -32,7 +32,6 @@ import structlog
from ..models import (
GENERATION_LEVELS,
- STUB_PAGE_CONFIDENCE,
TEMPLATE_PAGE_CONFIDENCE,
GeneratedPage,
compute_page_id,
@@ -345,7 +344,6 @@ class StructuralRenderMixin:
target_path: str,
title: str,
template: str,
- confidence: float = TEMPLATE_PAGE_CONFIDENCE,
**render_kwargs: Any,
) -> GeneratedPage:
"""Render one template page and wrap it as a GeneratedPage.
@@ -353,10 +351,14 @@ class StructuralRenderMixin:
The mirror of ``_build_generated_page`` for the no-model path: same
fields, zero tokens, ``provider_name="template"``.
- ``confidence`` is a parameter rather than a constant because the two
- callers make different claims. A sole renderer's page is everything the
- page is meant to be; a stub is the same material with the prose
- missing, and a reader has to be told which one they are looking at.
+ Confidence is a constant here, not a parameter. It used to be
+ overridable so a stub could claim less than a sole renderer's page,
+ on the reasoning that a reader had to be told which they were looking
+ at. Every page this renders makes the same claim, whichever caller
+ asked for it: the statements came from the index and no model saw
+ them. The only page that claims less is one whose provider call
+ failed, and ``_stub_fallback`` lowers that one after the fact, because
+ the failure is not knowable here.
"""
content = self._render(template, style_prefix=False, **render_kwargs)
now = _now_iso()
@@ -376,7 +378,7 @@ class StructuralRenderMixin:
target_path=target_path,
created_at=now,
updated_at=now,
- confidence=confidence,
+ confidence=TEMPLATE_PAGE_CONFIDENCE,
)
def _structural_page(
@@ -425,13 +427,26 @@ class StructuralRenderMixin:
No render key: a stub is not what the page is meant to be, so there is
nothing to keep fresh. The moment a key shows up the page is rewritten
wholesale, and until then rebuilding it costs nothing.
+
+ Confidence stays at the template default. Every statement this renders
+ came from the index and no model saw it, which is exactly the claim
+ :data:`TEMPLATE_PAGE_CONFIDENCE` makes. It is the same argument
+ ``_model_free_onboarding_page`` already makes for the subkinds it
+ finishes without a model. That the page is *thin* is a different
+ question with its own carrier: ``provider_name='template'`` is what the
+ tree's "not written yet" marker and the reader's upgrade affordance
+ read, and neither consults confidence.
+
+ The provider-outage path stamps :data:`STUB_PAGE_CONFIDENCE` over this
+ afterwards (see ``_stub_fallback``), because there the page stands in
+ for prose the run tried and failed to write, which is the one thing a
+ reader cannot tell from the page itself.
"""
return self._render_page(
page_type=page_type,
target_path=target_path,
title=title,
template=f"{_STUB_PREFIX}/{template}",
- confidence=STUB_PAGE_CONFIDENCE,
**render_kwargs,
)
diff --git a/packages/core/src/repowise/core/generation/page_selection.py b/packages/core/src/repowise/core/generation/page_selection.py
index 0ea5f43c7..232b7aaaa 100644
--- a/packages/core/src/repowise/core/generation/page_selection.py
+++ b/packages/core/src/repowise/core/generation/page_selection.py
@@ -18,7 +18,14 @@ import fnmatch
from dataclasses import dataclass, field
# Page freshness values that count as "needs refresh" for ``--stale``.
-_STALE_STATUSES = frozenset({"stale", "expired"})
+#
+# Public because it is the product's one definition of the word. The MCP
+# ``get_context`` freshness block reports the same judgement to an agent that
+# ``repowise generate --stale`` acts on, and it used to reach that judgement by
+# thresholding ``confidence`` instead, which is a different axis and on a
+# keyless index a permanently wrong answer. Two spellings of "stale" in one
+# product is how they drift apart, so there is one.
+STALE_STATUSES = frozenset({"stale", "expired"})
@dataclass(frozen=True)
@@ -38,7 +45,7 @@ class PageRecord:
@property
def is_stale(self) -> bool:
- return self.freshness_status in _STALE_STATUSES
+ return self.freshness_status in STALE_STATUSES
@dataclass(frozen=True)
diff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.py
index 1073e9d87..8a60a1e4c 100644
--- a/packages/core/src/repowise/core/persistence/crud/pages.py
+++ b/packages/core/src/repowise/core/persistence/crud/pages.py
@@ -115,6 +115,24 @@ def _apply_page_upsert(
# from the page's own bytes, so they can legitimately change while the
# content hash does not: a renamed page, or one whose siblings moved.
# A field left out here is frozen at whatever the first run wrote.
+ #
+ # ``confidence`` belongs here for the same reason ``freshness_status``
+ # does: it is decided by *how* the page was written, not by what the
+ # page says, so it can move while the bytes do not. A stub renders
+ # identically whether the run never asked for prose or asked and lost
+ # the call, and its ``source_hash`` is a hash of that render, so both
+ # transitions land in this branch with every compared field equal:
+ #
+ # * a keyless page written at 0.3 by a version that stamped both
+ # stub kinds alike stays 0.3 forever, on every subsequent run,
+ # because nothing else would ever write the corrected value;
+ # * a provider outage over an existing keyless stub records the
+ # failure in ``metadata_json`` (right below) while leaving the
+ # confidence saying nothing went wrong.
+ #
+ # The second is the one that matters: the marker and the number would
+ # disagree on the same row, and they are meant to be two halves of one
+ # statement.
if (
existing.content == content
and existing.source_hash == source_hash
@@ -124,6 +142,7 @@ def _apply_page_upsert(
existing.summary = summary
existing.target_path = target_path
existing.freshness_status = freshness_status
+ existing.confidence = confidence
existing.metadata_json = meta_json
existing.parent_page_id = parent_page_id
existing.display_order = display_order
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index 484cd3250..3bbaeb254 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -16,6 +16,7 @@ from typing import Any
from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.generation.page_selection import STALE_STATUSES
from repowise.core.persistence.crud import get_kg_layers, get_kg_tour_steps
from repowise.core.persistence.decision_graph import get_governing_decisions
from repowise.core.persistence.models import (
@@ -769,19 +770,44 @@ async def _resolve_one_target(
result_data["decisions"] = governing
# --- Freshness ---
+ #
+ # ``is_stale`` reads ``freshness_status`` through the same predicate
+ # ``repowise generate --stale`` uses, rather than thresholding
+ # ``confidence``. Two separate corrections in one line.
+ #
+ # The axis was wrong: freshness is whether a page has fallen behind the
+ # code it documents, confidence is how far its statements can be trusted
+ # while it has not. Thresholding the latter reported a *module* page as
+ # stale on the day it was built, because generation stamped every module
+ # page a keyless run rendered below the threshold. File and symbol targets
+ # were unaffected, since their pages are template renders at full
+ # confidence, so this was a module-target bug rather than a whole-tool one.
+ #
+ # The word was also being redefined: importing the CLI's set keeps one
+ # meaning of "stale" in the product. A hand-rolled ``!= "fresh"`` would
+ # quietly widen it to cover ``tombstone`` and ``outdated`` too, which is a
+ # different claim than the one the flag makes.
if include is None or "freshness" in include:
freshness: dict[str, Any] = {}
+
+ def _is_stale(row: Page) -> bool:
+ # Defensive on None: the column is NOT NULL with a "fresh" default
+ # and every write path passes it, but the old expression guarded
+ # its input and dropping the guard would turn a hand-written row
+ # into a stale one rather than a fresh one.
+ return (row.freshness_status or "fresh") in STALE_STATUSES
+
if page:
freshness["confidence_score"] = page.confidence
freshness["freshness_status"] = page.freshness_status
- freshness["is_stale"] = (page.confidence or 1.0) < 0.6
+ freshness["is_stale"] = _is_stale(page)
elif target_type == "symbol" and file_path_for_git:
sym_page_id = f"file_page:{file_path_for_git}"
sym_page = await session.get(Page, sym_page_id)
if sym_page:
freshness["confidence_score"] = sym_page.confidence
freshness["freshness_status"] = sym_page.freshness_status
- freshness["is_stale"] = (sym_page.confidence or 1.0) < 0.6
+ freshness["is_stale"] = _is_stale(sym_page)
else:
freshness["confidence_score"] = None
freshness["freshness_status"] = None
diff --git a/packages/ui/__tests__/docs/docs-reader-confidence.test.tsx b/packages/ui/__tests__/docs/docs-reader-confidence.test.tsx
deleted file mode 100644
index c088b3bed..000000000
--- a/packages/ui/__tests__/docs/docs-reader-confidence.test.tsx
+++ /dev/null
@@ -1,100 +0,0 @@
-import { describe, it, expect, beforeAll } from "vitest";
-import { render, screen } from "@testing-library/react";
-import { DocsReader } from "../../src/docs/docs-reader.js";
-import type { DocPage } from "@repowise-dev/types/docs";
-
-/**
- * The low-confidence warning had never rendered for anyone.
- *
- * Generation wrote a constant 1.0 into every page's `confidence`, so the
- * condition guarding this banner could not be true on any real wiki. It was
- * shipped, styled, and unreachable — and untested, because a test would have
- * had to construct the value no page ever had.
- *
- * Generation now writes three values, and the lowest of them — a structural
- * stub standing in for a page a model was meant to write — falls under this
- * threshold. These assert the banner at values on both sides of it.
- */
-
-const WARNING = /generated with low confidence/i;
-
-// The reader scrolls its pane back to the top on every page change, and jsdom
-// implements no scrolling. Stubbed here rather than in the shared setup: it is
-// this component's requirement, not the suite's.
-beforeAll(() => {
- Element.prototype.scrollTo = () => {};
-});
-
-function makePage(overrides: Partial<DocPage> = {}): DocPage {
- return {
- id: "p1",
- repository_id: "r1",
- page_type: "module_page",
- title: "Resolution Layer",
- content: "The layer turns references into edges.",
- target_path: "core/resolvers",
- source_hash: "h",
- model_name: "m",
- provider_name: "template",
- input_tokens: 0,
- output_tokens: 0,
- cached_tokens: 0,
- generation_level: 3,
- version: 1,
- confidence: 1,
- freshness_status: "fresh",
- metadata: {},
- created_at: "2026-08-01T00:00:00Z",
- updated_at: "2026-08-01T00:00:00Z",
- ...overrides,
- } as DocPage;
-}
-
-function renderReader(page: DocPage) {
- return render(
- <DocsReader
- page={page}
- repoId="r1"
- persona="contributor"
- sidebarOpen={false}
- buildPageHref={(id) => `?page=${id}`}
- LinkComponent={({ href, children, ...rest }) => (
- <a href={href} {...rest}>
- {children}
- </a>
- )}
- />,
- );
-}
-
-describe("DocsReader low-confidence warning", () => {
- it("warns on a page written with low confidence", () => {
- // 0.3 is what generation stamps on a structural stub: real material with
- // the prose missing, standing in for a page a model never wrote.
- renderReader(makePage({ confidence: 0.3 }));
-
- expect(screen.getByText(WARNING)).toBeTruthy();
- });
-
- it("stays quiet on a model-written page", () => {
- // 0.8. A model page is grounded and checked — normal to read, not suspect.
- renderReader(makePage({ confidence: 0.8 }));
-
- expect(screen.queryByText(WARNING)).toBeNull();
- });
-
- it("stays quiet on a template-rendered page", () => {
- renderReader(makePage({ confidence: 1 }));
-
- expect(screen.queryByText(WARNING)).toBeNull();
- });
-
- it("stays quiet when confidence is absent rather than low", () => {
- // Zero is the "nobody measured this" value the column carries before a
- // page has been through generation. Warning on it would put the flag on
- // every page of an older wiki, which is the opposite of a trust signal.
- renderReader(makePage({ confidence: 0 }));
-
- expect(screen.queryByText(WARNING)).toBeNull();
- });
-});
diff --git a/packages/ui/__tests__/docs/docs-reader-prose-notice.test.tsx b/packages/ui/__tests__/docs/docs-reader-prose-notice.test.tsx
new file mode 100644
index 000000000..cfe949ea5
--- /dev/null
+++ b/packages/ui/__tests__/docs/docs-reader-prose-notice.test.tsx
@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { DocsReader } from "../../src/docs/docs-reader.js";
+import type { DocPage } from "@repowise-dev/types/docs";
+
+/**
+ * What the reader says about a page with no prose on it, and to whom.
+ *
+ * This used to be a bordered warning above the content ("generated with low
+ * confidence, verify against the source") gated on `confidence < 0.5`.
+ * Generation stamped that value on every deterministic page, not only on the
+ * ones where a provider call had failed, so an index built without a key
+ * opened every page it had under a trust warning about pages assembled
+ * entirely from the parse, the import graph and git history. The banner was
+ * loudest exactly where it was least true.
+ *
+ * Two things changed. Generation now reserves the low value for a page whose
+ * provider call actually failed, and the reader keys on the marker that
+ * records that failure rather than on the number, so an already-published
+ * wiki reads correctly without being reindexed. What is left is one quiet line
+ * at the end of the content, beside the affordance that fixes it.
+ */
+
+const OLD_BANNER = /generated with low confidence/i;
+const PROSE_LOST = /did not complete/i;
+const CAN_WRITE = /a model can write/i;
+
+beforeAll(() => {
+ Element.prototype.scrollTo = () => {};
+});
+
+function makePage(overrides: Partial<DocPage> = {}): DocPage {
+ return {
+ id: "p1",
+ repository_id: "r1",
+ page_type: "module_page",
+ title: "Resolution Layer",
+ content: "The layer turns references into edges.",
+ target_path: "core/resolvers",
+ source_hash: "h",
+ model_name: "m",
+ provider_name: "template",
+ input_tokens: 0,
+ output_tokens: 0,
+ cached_tokens: 0,
+ generation_level: 3,
+ version: 1,
+ confidence: 1,
+ freshness_status: "fresh",
+ metadata: {},
+ created_at: "2026-08-01T00:00:00Z",
+ updated_at: "2026-08-01T00:00:00Z",
+ ...overrides,
+ } as DocPage;
+}
+
+function renderReader(page: DocPage, opts: { upgradeSlot?: boolean } = {}) {
+ const { upgradeSlot = true } = opts;
+ return render(
+ <DocsReader
+ page={page}
+ repoId="r1"
+ persona="contributor"
+ sidebarOpen={false}
+ buildPageHref={(id) => `?page=${id}`}
+ upgradeSlot={upgradeSlot ? <button>Write with AI</button> : undefined}
+ LinkComponent={({ href, children, ...rest }) => (
+ <a href={href} {...rest}>
+ {children}
+ </a>
+ )}
+ />,
+ );
+}
+
+describe("DocsReader prose-lost notice", () => {
+ it("says nothing alarming on a deterministic page", () => {
+ // The case that made this a bug: a keyless run's module page. It offers to
+ // have prose written and makes no claim about trustworthiness.
+ renderReader(makePage());
+
+ expect(screen.queryByText(OLD_BANNER)).toBeNull();
+ expect(screen.queryByText(PROSE_LOST)).toBeNull();
+ expect(screen.getByText(CAN_WRITE)).toBeTruthy();
+ });
+
+ it("stays quiet on an already-published page still carrying the old 0.3", () => {
+ // No reindex required. Wikis published before the split have keyless stubs
+ // stamped 0.3 with no failure marker; keying on the marker is what lets
+ // those read correctly today rather than after a rebuild.
+ renderReader(makePage({ confidence: 0.3 }));
+
+ expect(screen.queryByText(OLD_BANNER)).toBeNull();
+ expect(screen.queryByText(PROSE_LOST)).toBeNull();
+ // Asserted positively too: without this the test would also pass if the
+ // reader rendered nothing at all, which is a different bug.
+ expect(screen.getByText(CAN_WRITE)).toBeTruthy();
+ });
+
+ it("names the lost prose when a provider call actually failed", () => {
+ renderReader(
+ makePage({
+ confidence: 0.3,
+ metadata: { stub_fallback_error: "upstream 529 overloaded" },
+ }),
+ );
+
+ expect(screen.getByText(PROSE_LOST)).toBeTruthy();
+ // One line, not two: the caveat replaces the generic offer rather than
+ // stacking a second block on top of it.
+ expect(screen.queryByText(CAN_WRITE)).toBeNull();
+ });
+
+ it("says nothing at all on a model-written page", () => {
+ renderReader(makePage({ confidence: 0.8, provider_name: "anthropic" }));
+
+ expect(screen.queryByText(OLD_BANNER)).toBeNull();
+ expect(screen.queryByText(PROSE_LOST)).toBeNull();
+ expect(screen.queryByText(CAN_WRITE)).toBeNull();
+ });
+
+ it("still names the lost prose with no upgrade affordance to offer", () => {
+ // The VS Code webview mounts the reader without an `upgradeSlot`. The
+ // caveat is a statement about the page, not a label on a button, so it has
+ // to survive on its own. This is the arm the web app never exercises.
+ renderReader(
+ makePage({
+ confidence: 0.3,
+ metadata: { stub_fallback_error: "upstream 529 overloaded" },
+ }),
+ { upgradeSlot: false },
+ );
+
+ expect(screen.getByText(PROSE_LOST)).toBeTruthy();
+ });
+
+ it("ignores a metadata shape that is not an object", () => {
+ // Artifacts have carried `metadata` as null and, on older snapshots, as a
+ // non-object. Neither may throw, and neither is a failure record.
+ renderReader(makePage({ metadata: null as never }));
+ expect(screen.queryByText(PROSE_LOST)).toBeNull();
+
+ renderReader(makePage({ metadata: "oops" as never }));
+ expect(screen.queryByText(PROSE_LOST)).toBeNull();
+ });
+
+ it("ignores an empty error string", () => {
+ // The marker is the error text. An empty one records nothing, and reading
+ // it as a failure would put the caveat on a page with no failure behind it.
+ renderReader(makePage({ metadata: { stub_fallback_error: "" } }));
+
+ expect(screen.queryByText(PROSE_LOST)).toBeNull();
+ expect(screen.getByText(CAN_WRITE)).toBeTruthy();
+ });
+});
diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsx
index 592294bb5..9189d31b4 100644
--- a/packages/ui/src/docs/docs-reader.tsx
+++ b/packages/ui/src/docs/docs-reader.tsx
@@ -11,7 +11,7 @@ import {
import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";
import { cn } from "../lib/cn";
import { formatRelativeTime, formatTokens } from "../lib/format";
-import { getPageLabel } from "../lib/page-types";
+import { getPageLabel, isStubFallbackPage } from "../lib/page-types";
import { computeDocNav } from "./doc-nav";
import { filterMarkdownByPersona, type ReaderPersona } from "./reader-persona";
import { WikiMarkdown } from "../wiki/wiki-markdown";
@@ -235,6 +235,12 @@ function DocsReaderBody({
// prose outstanding, which is what the upgrade affordance is for.
const isTemplatePage = page.provider_name === "template";
+ // Of those, the ones where prose was attempted and lost rather than never
+ // asked for. This is the only per-page trust caveat the reader still draws,
+ // and it rides along with the affordance that fixes it instead of getting a
+ // callout of its own. See the end-of-content block below.
+ const proseLost = isStubFallbackPage(page);
+
// The reader renders the page title as the H1 above the body, but generated
// content often opens with its own "# <title>" line (the deterministic
// templates do), so the same heading shows twice. Drop a leading H1 that
@@ -491,15 +497,6 @@ function DocsReaderBody({
</details>
)}
- {/* Low-confidence flag */}
- {page.confidence > 0 && page.confidence < 0.5 && (
- <div className="mb-4 flex items-start gap-1.5 rounded-md border border-[var(--color-warning)]/40 bg-[var(--color-warning)]/10 px-3 py-2">
- <span className="text-xs text-[var(--color-text-primary)]">
- This page was generated with low confidence — verify against the source before relying on it.
- </span>
- </div>
- )}
-
{/* Human notes (read-only callout; editing lives in the rail) */}
{page.human_notes && (
<div className="mb-4 rounded-lg border border-[var(--color-border-accent)] bg-[var(--color-accent-blue)]/5 px-4 py-3">
@@ -528,12 +525,30 @@ function DocsReaderBody({
{/* The upgrade affordance, at the end of the content rather than
beside the title. Someone who has read to here knows the page is
thin; someone at the title does not yet, and an accent pill up
- there competed with the h1 for a decision they could not make. */}
- {isTemplatePage && upgradeSlot && (
+ there competed with the h1 for a decision they could not make.
+
+ The prose-lost caveat rides in the same block rather than in a
+ banner of its own. It used to be a bordered warning callout
+ above the content keyed on `confidence < 0.5`, which generation
+ stamped on every deterministic page, so an index built without
+ a key opened every page it had under "verify against the source
+ before relying on it", about pages that are pure index output
+ and have nothing to verify. Same sentence, same place as the
+ action that resolves it, no alarm colour: the reader is told
+ once, at the point it is actionable.
+
+ `proseLost` is checked on its own rather than under
+ `isTemplatePage`. A failed page is always a template here,
+ because the fallback substitutes a template render, so the two
+ are equivalent today. Coupling them would mean any other writer
+ of the marker could stamp a real provider name and silently
+ lose the caveat. */}
+ {(proseLost || (isTemplatePage && upgradeSlot)) && (
<div className="mt-8 flex flex-wrap items-center gap-x-3 gap-y-2 border-t border-[var(--color-border-default)] pt-4">
<p className="text-xs text-[var(--color-text-tertiary)]">
- This page is built from the index. A model can write the how and
- why on top of it.
+ {proseLost
+ ? "This page is built from the index. A model was meant to write over it on the last run and the call did not complete."
+ : "This page is built from the index. A model can write the how and why on top of it."}
</p>
{upgradeSlot}
</div>
diff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.ts
index b765c5e02..bc1f1f775 100644
--- a/packages/ui/src/lib/page-types.ts
+++ b/packages/ui/src/lib/page-types.ts
@@ -109,6 +109,33 @@ export function isStubPage(
return page.provider_name === "template";
}
+/** Metadata key core stamps with the provider error a page fell back over.
+ * Mirrors `STUB_FALLBACK_ERROR` in core's generation/models.py. */
+export const STUB_FALLBACK_ERROR = "stub_fallback_error";
+
+/** True when this page is a stub standing in for prose a run TRIED to write
+ * and lost to a provider error, as opposed to one a keyless or `--no-prose`
+ * run rendered deterministically on purpose.
+ *
+ * Both look identical on the page: same template, same `provider_name`. The
+ * difference is only that one of them was supposed to be something else, and
+ * that is the half a reader cannot infer, so it is the half worth saying.
+ * `isStubPage` covers the other half ("no prose yet") and is what the tree
+ * marker and the upgrade affordance read.
+ *
+ * Keyed on the marker rather than on `confidence < 0.5`, deliberately. Until
+ * this was split, generation stamped 0.3 on both kinds, so a threshold read
+ * of an already-published wiki cannot tell them apart and would flag every
+ * page of every keyless index, which is the bug. The marker is only ever
+ * written on the failure path, in every version that has written it, so it
+ * reads correctly against old and new artifacts alike and needs no reindex. */
+export function isStubFallbackPage(
+ page: { metadata?: Record<string, unknown> | null } | null | undefined,
+): boolean {
+ const value = page?.metadata?.[STUB_FALLBACK_ERROR];
+ return typeof value === "string" && value.length > 0;
+}
+
// ---------------------------------------------------------------------------
// Onboarding collection
// ---------------------------------------------------------------------------
diff --git a/tests/unit/generation/test_page_confidence.py b/tests/unit/generation/test_page_confidence.py
index b947690e8..90e2964a6 100644
--- a/tests/unit/generation/test_page_confidence.py
+++ b/tests/unit/generation/test_page_confidence.py
@@ -10,12 +10,20 @@ Three values, because three distinctions are actually available when a page is
written:
* a template page is everything the parse, the graph and git history know, with
- no model in the loop;
+ no model in the loop, including the deterministic rendering of a
+ model-written type by a keyless or ``--no-prose`` run;
* a model page is grounded in that material and checked against it, but it is a
summary of the code rather than an extraction from it;
-* a stub is that same material with the prose missing, standing in for a page a
- model was meant to write. That is the one a reader has to be warned about, so
- it is the one that sits below the banner threshold.
+* a stub the run substituted for a model page whose provider call *failed* is
+ that same material standing in for prose that was attempted and lost. That is
+ the one a reader cannot infer from the page, so it is the only one flagged.
+
+The third bullet used to cover the keyless render too, and that was the bug: a
+keyless run produces every model-written page this way, so the reader's warning
+landed on the repository overview and all of its subsystem pages at once, on
+wikis with nothing wrong with them. ``confidence`` is a trust axis; whether a
+model has written a page yet is ``provider_name``, and the two must not be read
+off one number.
"""
from __future__ import annotations
@@ -34,11 +42,17 @@ from repowise.core.generation.models import (
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.mock import MockProvider
-# The reader UI shows its warning below this. Duplicated from the component on
-# purpose: the point of the values above is where they sit relative to it, and
-# a test that imported the threshold would move with it and stop asserting the
-# relationship.
-BANNER_THRESHOLD = 0.5
+# There is deliberately no threshold constant here any more.
+#
+# This file used to carry a hand-copied ``BANNER_THRESHOLD = 0.5``, on the
+# reasoning that what mattered about the three values was which side of the
+# reader's warning they fell on. That warning is gone: the reader now keys its
+# one caveat on the ``stub_fallback_error`` marker, because a number could not
+# tell a failed page from a deterministic one. Nothing in the product reads
+# 0.5, so asserting against it would be asserting against a fiction.
+#
+# What is left to protect is the ordering and the identities, which is what
+# these assert.
class _OutageProvider(MockProvider):
@@ -77,7 +91,6 @@ async def test_a_template_page_is_fully_confident(
)
assert page.confidence == TEMPLATE_PAGE_CONFIDENCE
- assert page.confidence > BANNER_THRESHOLD
async def test_a_model_written_page_is_confident_but_not_certain(generator):
@@ -87,8 +100,8 @@ async def test_a_model_written_page_is_confident_but_not_certain(generator):
assert page.confidence == MODEL_PAGE_CONFIDENCE
assert page.confidence < TEMPLATE_PAGE_CONFIDENCE
- # A model page is normal, not suspect: it must not raise the reader's flag.
- assert page.confidence > BANNER_THRESHOLD
+ # A model page is normal, not suspect: it sits above the failure value.
+ assert page.confidence > STUB_PAGE_CONFIDENCE
async def test_a_page_lost_to_a_provider_outage_says_so(outage_generator):
@@ -104,22 +117,51 @@ async def test_a_page_lost_to_a_provider_outage_says_so(outage_generator):
assert page.metadata[STUB_FALLBACK_ERROR]
assert page.confidence == STUB_PAGE_CONFIDENCE
- assert page.confidence < BANNER_THRESHOLD
+ assert page.confidence < MODEL_PAGE_CONFIDENCE
-async def test_a_keyless_stub_is_marked_the_same_way(config):
- """No provider is configured at all, so nothing wrote the prose either."""
- deterministic = GenerationConfig(
+def _deterministic_generator() -> PageGenerator:
+ config = GenerationConfig(
max_tokens=1024, token_budget=2000, max_concurrency=2, deterministic=True
)
- generator = PageGenerator(MockProvider(), ContextAssembler(deterministic), deterministic)
+ return PageGenerator(MockProvider(), ContextAssembler(config), config)
- page = await generator.generate_module_page(
+
+async def test_a_keyless_page_is_not_flagged():
+ """The regression this file now guards.
+
+ No provider is configured, so no model was asked and none failed. What
+ renders is the deterministic page: every statement came from the index,
+ which is the template claim exactly. Flagging it told a keyless user their
+ whole wiki was doubtful, about an index that is that shape by design.
+ """
+ page = await _deterministic_generator().generate_module_page(
"Resolution Layer", "python", [], nx.DiGraph(), target_path="core/resolvers"
)
- assert page.confidence == STUB_PAGE_CONFIDENCE
- assert page.confidence < BANNER_THRESHOLD
+ assert page.confidence == TEMPLATE_PAGE_CONFIDENCE
+ # Nothing was attempted, so there is no failure to record. This is the key
+ # the reader keys its caveat on, and it must stay absent here.
+ assert STUB_FALLBACK_ERROR not in page.metadata
+
+
+async def test_the_two_stub_kinds_are_distinguishable(outage_generator):
+ """Same template, same provider name, opposite claims.
+
+ The bytes cannot tell these apart, so if confidence agreed too there would
+ be nothing left that could. Asserted together rather than apart because the
+ failure mode is the pair collapsing, which either test alone still passes.
+ """
+ keyless = await _deterministic_generator().generate_module_page(
+ "A", "python", [], nx.DiGraph(), target_path="a"
+ )
+ lost = await outage_generator.generate_module_page(
+ "B", "python", [], nx.DiGraph(), target_path="b"
+ )
+
+ assert keyless.provider_name == lost.provider_name == "template"
+ assert keyless.confidence != lost.confidence
+ assert keyless.confidence > lost.confidence
async def test_the_run_produces_more_than_one_value(
@@ -152,4 +194,29 @@ async def test_the_run_produces_more_than_one_value(
]
assert len({p.confidence for p in pages}) == 3
- assert min(p.confidence for p in pages) < BANNER_THRESHOLD
+ assert min(p.confidence for p in pages) == STUB_PAGE_CONFIDENCE
+
+
+async def test_the_overview_keeps_its_value_through_post_processing(
+ outage_generator, sample_repo_structure
+):
+ """The value has to still be there after the wrappers have run.
+
+ ``_stub_fallback`` sets confidence and hands the page on; the overview then
+ goes through more post-processing than any other page type: the package
+ table, the capability table, the architecture map and the source-evidence
+ pass all touch the page afterwards. None of them rewrites ``confidence``
+ today, and this is what says so: a wrapper that rebuilt the page instead of
+ mutating it would silently restore the default, putting a failed page back
+ at full confidence with its failure marker still attached.
+ """
+ page = await outage_generator.generate_repo_overview(
+ sample_repo_structure,
+ pagerank={},
+ sccs=[],
+ community={},
+ repo_name="demo",
+ )
+
+ assert page.metadata[STUB_FALLBACK_ERROR]
+ assert page.confidence == STUB_PAGE_CONFIDENCE