The Update Loop in One Mental Model

OpenWiki's distinctive behavior becomes clearest when a repository looks unchanged but one documented fact is no longer safely grounded. The update loop connects the ideas already established: source and Git signals, Claim freshness, the page queue, sparse page decisions, and durability proofs. Seeing those pieces as one operating model lets a reader decide whether OpenWiki should return a no-op, create focused repair work, or continue through finalization—and understand why those decisions constrain one another.

When a clean repository is not a no-op

Imagine an existing page that explains a relationship among components. The working tree is clean, and the page itself has not been edited since the last successful run. Yet one evidence resource attached to a Claim now resolves to a different version because the source changed in a committed refactor. A timestamp-based updater sees no local edit to the wiki and stops. OpenWiki does not. For the documentation to remain trustworthy, the source change matters even when the generated page has not changed yet.

The loop begins by establishing the current run. Language is validated before state is created, and the repository source is compared with the source identity associated with the active plan or prior coverage. For an update, ordinary Git-based checks look for meaningful changes, an interrupted prior run, language changes, or other conditions that make regeneration necessary. Those checks answer whether the repository appears to need documentation work. They do not answer whether every existing factual proposition is still grounded.

Claims preflight supplies that second signal. It loads the persisted Claim sidecars and resolves each evidence resource against its recorded version. A resource with the same version is current. A changed version makes the owning Claim stale. A resource that disappears or cannot be located makes it unresolved. The distinction is not a verdict about the sentence. It is a precise reason that the sentence needs a new look.

Only when the Git-based preflight says the update can be skipped, the Claims runtime reports no issues, and every existing page has complete baseline coverage can OpenWiki attempt a strict no-op. Even then, it checks source stability while finalizing the current Claim state and publishing the no-op metadata. If the source moves during that window, the system falls back to real work. This is a useful architectural rule: an optimization is allowed only after it has passed the same kind of consistency checks that make an ordinary update meaningful.

flowchart TD Begin["begin: validate language and source"] --> Git["Git and baseline checks"] Git --> ClaimsPre["Claims preflight"] ClaimsPre --> Clean{"No work signals, zero issues, complete coverage?"} Clean -->|yes| Noop["stable no-op proof and return"] Clean -->|no| Plan["planning"] Plan --> Required["add required issue jobs"] Required --> Page["next_page"] Page --> Submit["sparse submit_page"] Submit --> Proof["page durability proof"] Proof --> More{"pending jobs remain?"} More -->|yes| Page More -->|no| Finish["finish"]

The decision path shows why queue state and evidence state cannot be evaluated independently. A clean queue does not erase stale evidence, and a current Claim does not make an unplanned page complete if the page manifest lacks coverage.

Why focused repair is the normal update

When OpenWiki proceeds, it does not ask the agent to restate every fact on every page.