Claims: Giving Documentation a Memory of Its Evidence
OpenWiki's page queue explains how work survives an interruption, but it does not by itself explain whether a page's factual content survived a source change. The Claims system answers that narrower question: which material propositions does a page make, what repository evidence supports them, and is that evidence still the same? Understanding Claims lets a reader distinguish a readable citation from an updateable grounding record and predict when OpenWiki must revisit a page even if Git appears clean.
A Claim is more than a citation
A citation usually points a reader toward a source. A Claim in OpenWiki is a proposition designed to be checked again. It is an atomic, independently falsifiable statement about the repository, accompanied by one or more evidence records. The statement is meant to capture a material truth—such as a responsibility, relationship, lifecycle rule, or failure behavior—not merely the existence of a function, a type, or a file.
That materiality test matters because a generated wiki can become less useful if it records every implementation fact with equal weight. One symbol may support several different Claims when it establishes different truths, while a single Claim may connect several components when their relationship is the fact a reader needs to understand. The boundary is not “one Claim per line of code.” It is whether the proposition would change a reader's architectural model, an implementation decision, an operational expectation, or a safe plan for changing the repository if it turned out to be false.
Each Claim has a stable OpenWiki-generated identifier, a statement, and evidence. The identifier gives the proposition continuity across updates. If the wording changes but the underlying proposition is still the same kind of page-owned fact, the update can revise that Claim in place. If an entirely new material fact appears, OpenWiki can allocate a new identifier. If the fact is no longer true or no longer belongs on the page, it can be explicitly retracted. Without a stable identity, every update would have to guess whether a new sentence is a revision, a duplicate, or an unrelated assertion.
Claims are not embedded in the Markdown body. They live in OpenWiki-owned JSON sidecars below openwiki/.claims/, mirroring the generated page layout. A sidecar contains the schema version, a hash of the exact Markdown bytes it grounds, the page's complete Claim set, and, when eligible, a verification event. The page itself remains readable: a human sees an explanation, headings, links, and diagrams rather than a block of machine bookkeeping. The sidecar gives the maintenance system the structured state it needs without forcing that state into every sentence.
The separation also clarifies ownership. The agent authors the prose and proposes factual decisions, but it does not edit the Claims sidecar directly. The Claims store validates and atomically persists that state. A run-scoped session holds mutable Claims while a page is being worked on, tracks which page owns each global identifier, and exposes a compact form for model-facing inspection. The Claims runtime connects the session to the repository evidence resolver, performs preflight, and provides the strict finalization boundary.
This division prevents two kinds of drift from being confused. The Markdown can change while the Claims remain old; the page-version hash then shows that the sidecar no longer describes the current bytes. Or the source can change while the Markdown and sidecar still agree with each other; evidence preflight then shows that the proposition needs review. A page is not grounded merely because its prose and sidecar were once written together. Grounding is a relationship among the current body, the persisted Claim set, and the current evidence.
The same model explains why personal mode has a different boundary. Personal ingestion can preserve raw connector material and attach confidence labels or contested sections, but connector-derived facts are not converted into the repository-grounded Claims used by code mode. The data may be useful without having the same locally re-resolvable identity. OpenWiki keeps those semantics separate instead of using one word—“grounded”—to conceal different evidence conditions.
Evidence versions turn change into a question
Repository evidence uses a canonical repo:// resource. The resource names a repository-relative path and may include an inclusive line range such as #L20-L48. Bare filesystem paths are not accepted as equivalent aliases. The explicit namespace gives the resolver one well-defined subject and makes it possible to reject references that escape the repository or point into private Git metadata or generated OpenWiki output.
The resolver's safety checks are part of the evidence model, not an afterthought. It normalizes path separators and rejects traversal, absolute or drive-letter paths, control characters, .git, and openwiki/. It also checks the physical path rather than trusting only its lexical spelling. A symbolic link or filesystem alias that redirects a supposedly local source elsewhere is refused. This matters because evidence is being used to support a factual statement; silently reading a different target would undermine both the claim and the update decision.
When a resource resolves, OpenWiki attaches an opaque version token. For whole-file evidence, the token is derived from a SHA-256 hash of the file. For a line range, the version includes a hash of the selected content and resolver-owned information about its surrounding lines. The consumer does not need to understand the encoding. It compares the current token with the token saved on the Claim.
That opacity is a useful design boundary. The resolver owns the question “does this resource still represent the same evidence?” The model owns the question “what does the changed evidence mean for the page?” If the version token changed, OpenWiki does not automatically rewrite the sentence or retract the Claim. It creates a reason to inspect the current source. A model can then decide that the proposition remains true, needs new wording or evidence, or should be removed.
Line ranges illustrate the balance between resilience and caution. Source movement does not necessarily change the underlying evidence. If the selected lines move or their surrounding position changes while the selected text remains identifiable, the resolver can relocate the range and keep the prior version stable. If the selected content changes, the resolver can use surrounding anchors to locate the new span and issue a new version. If the anchors are ambiguous or the range cannot be found, resolution returns no evidence rather than choosing one candidate by guesswork.
The last behavior is essential. A reference system that always returns the nearest-looking lines might appear resilient while grounding a Claim in the wrong code. OpenWiki accepts the cost of an unresolved issue when identity is uncertain. The subsequent update has more work to do, but it does not silently convert ambiguity into confidence.
The important output of this exchange is not a hash. It is a classified maintenance decision.
Preflight separates current, stale, and unresolved
Before an update or a resumed initialization, OpenWiki runs Claims preflight. It loads the persisted sidecars and resolves each evidence resource against the version recorded for that Claim. A resource that returns the same version is current. A resource that still exists but returns a different version creates a stale issue. A resource that no longer resolves creates an unresolved issue. If the resolver itself fails—for example, because the environment cannot safely read the repository—that error is not reinterpreted as evidence that the file was deleted.
The distinction between stale and unresolved carries practical meaning. Stale says that the source identity remains available but its content has changed. Unresolved says that OpenWiki cannot currently establish the referenced evidence at all. Both require attention, but neither is an automatic retraction. A deleted file might have been replaced by a new mechanism elsewhere; a changed function might still support the same architectural rule. Those are interpretation decisions for the page worker, now made with current source rather than stale memory.
Preflight also discovers orphaned sidecars whose Markdown pages no longer exist. That prevents structured grounding state from quietly accumulating after page deletion. Issues are sorted deterministically by page, kind, and Claim identifier, so the same evidence state produces a stable work view rather than an arbitrary order.
The result feeds directly into the update gate. OpenWiki evaluates Git-based signals such as meaningful source changes, the prior update status, and language changes, but it performs Claims validation before deciding that an update can be skipped. A clean working tree is insufficient if a Claim is stale or unresolved. Complete baseline coverage matters as well: a legacy page lacking a page-manifest entry is not promoted to “known current” simply because no new Git change is visible.
A strict no-op therefore requires three conditions to hold together: ordinary update checks say no meaningful documentation work is needed, Claims preflight reports no issues, and every existing page has complete baseline coverage. Even then, OpenWiki snapshots the source, finalizes the current Claim state, snapshots again, and checks that the source remained stable while the no-op was being established. If that stability proof fails, the run returns to real planning rather than publishing a convenient shortcut.
When an update proceeds, known issues become required page work. OpenWiki groups issues by the page that owns the Claim and adds a page job if the planner did not already schedule that page or delete it. The affected evidence resources become starting points for the worker, which means the update can direct attention toward the source that moved instead of asking the agent to rediscover the entire repository. This is a coverage rule, not a conclusion about the truth of the Claim.
The value—and limit—of structured grounding
Claims give OpenWiki a memory of why a page says what it says. They allow evidence freshness to be checked without interpreting opaque versions, allow stable propositions to survive a wording change, and let the queue focus on pages with actual grounding debt. They also make a stronger final proof possible: the system can compare the persisted Claim set with the page bytes and refuse to mark a page durable when the two no longer agree.
But structured grounding is not the same as complete understanding. The system can only recheck propositions that the authoring process represented as Claims. A page may omit an important fact, choose a poor boundary, or misunderstand what changed while still using valid evidence for the Claims it did record. The evidence resolver can establish that a file or range changed; it cannot decide whether a reader should revise the page's central explanation.
That limitation is why OpenWiki's Claim guidance emphasizes substantive propositions rather than a shallow fact for every symbol. The goal is not to maximize the number of records. It is to cover the material truths that future readers and agents rely on, while avoiding a sidecar that is too noisy to guide maintenance. The quality boundary is therefore both technical and editorial: deterministic code protects identity, freshness, ownership, and persistence, while the agent must still make a defensible interpretation of current source.
A page queue without Claims would know that a page needs to be regenerated, but not which factual relationships deserve review. Claims without the queue would know that evidence changed, but lack a durable unit in which to perform and record the repair. Together they turn a source change into an explicit question about a page's meaning. The next step is to see how OpenWiki answers that question without asking the worker to resubmit every fact it already knows to be current.