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
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.pyindex 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.3diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex 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 FilePageContextfrom ..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) -> Generit 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 recordof 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_CONFIDENCElog.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.pyindex 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 structlogfrom ..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: samefields, 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 isnothing to keep fresh. The moment a key shows up the page is rewrittenwholesale, 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.pyindex 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 fnmatchfrom 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:@propertydef 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.pyindex 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 == contentand existing.source_hash == source_hash@@ -124,6 +142,7 @@ def _apply_page_upsert(existing.summary = summaryexisting.target_path = target_pathexisting.freshness_status = freshness_status+ existing.confidence = confidenceexisting.metadata_json = meta_jsonexisting.parent_page_id = parent_page_idexisting.display_order = display_orderdiff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.pyindex 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 Anyfrom sqlalchemy import or_, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.generation.page_selection import STALE_STATUSESfrom repowise.core.persistence.crud import get_kg_layers, get_kg_tour_stepsfrom repowise.core.persistence.decision_graph import get_governing_decisionsfrom 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.confidencefreshness["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.confidencefreshness["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"] = Nonefreshness["freshness_status"] = Nonediff --git a/packages/ui/__tests__/docs/docs-reader-confidence.test.tsx b/packages/ui/__tests__/docs/docs-reader-confidence.test.tsxdeleted file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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 thanbeside the title. Someone who has read to here knows the page isthin; 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.tsindex 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.pyindex 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 iswritten:* 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 asummary 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 PageGeneratorfrom 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_THRESHOLDasync 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_CONFIDENCEassert 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_CONFIDENCEasync 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.confidenceasync 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