What OpenWiki Makes Reliable—and What It Cannot
OpenWiki should be judged not by whether an agent can write a convincing page, but by whether the system can preserve a truthful relationship among that page, its evidence, and the source as the source changes. The question is what the product actually makes reliable: which transitions, records, and repairs are mechanically enforced, which judgments still belong to the authoring agent or operator, and when the different execution surfaces are appropriate. That judgment supports a practical decision about using OpenWiki as a maintained repository wiki, a personal knowledge space, an integrated host workflow, or a reviewable CI process.
Reliability is a chain, not a model score
OpenWiki's central innovation is not a more confident version of text generation. It is the chain around generation. A repository change creates a question about existing documentation. The system compares source identity and Claim evidence, chooses whether a run can legitimately no-op or needs a new plan, turns the plan into durable page jobs, and accepts a page only after its Markdown and structured factual state agree. Deterministic finalization then makes the accepted artifact navigable and explicit about its provenance. The next change begins the loop again.
The loop separates four kinds of truth that are often mixed together in an AI documentation product:
- The source truth: what the current repository or external source contains.
- The author's interpretation: which relationships and propositions deserve to be explained.
- The durable process state: what OpenWiki has planned, completed, skipped, or invalidated.
- The reader artifact: the Markdown, metadata, links, and visual graph people and agents consume.
OpenWiki's strongest guarantees operate between these layers. They do not make the layers identical. A source version can be current while an explanation is incomplete. A page can be beautifully formatted while a Claim is stale. A protocol call can succeed while the host agent missed an important subsystem. The architecture is valuable because it makes those distinctions visible instead of allowing a polished paragraph to stand in for all of them.
Where the architecture earns trust
It makes progress durable at the right granularity
The ordered page queue is a practical answer to the failure mode of all-or-nothing generation. A repository wiki is large enough that a model or process can stop partway through. OpenWiki records the run in openwiki/.run.json, persists the normalized queue, and treats a page as complete only after the page's Markdown and Claims have passed their durability proof. Completed pages can therefore remain useful when a later worker fails.
That does not mean every partial run is presented as successful. A worker that fails before submission, or exits without submitting, is rolled back to its pre-worker Markdown and sidecar and marked skipped. Finish can preserve the other completed pages, but it records an interrupted update and requires a later run to retry the skipped work. A source change during finalization is handled similarly: the run can finish the work it can prove, returns sourceChanged: true, and asks for another update rather than pretending the moving source was fully covered.
This is a meaningful reliability property because it aligns the unit of recovery with the unit of meaning. A page is large enough to be a useful explanation and small enough to prove and retry. A single global checkpoint would preserve less information; an individual sentence checkpoint would make the system too fragmented to operate. The design does not remove failure, but it prevents failure from erasing or falsifying unrelated progress.
The cost is visible operational state. Operators must understand that skipped is deferred work, that an interrupted status is not equivalent to a clean no-op, and that a persistent checkout is needed for true resume. A hosted CI runner typically discards the transient checkpoint, so its durable continuity comes from the committed wiki and full Git history, not from the local run file.
It makes factual maintenance more precise than timestamp refresh
Claims give OpenWiki a way to ask a source-specific question. Each material proposition has an identity and repository evidence with a resolver-owned version.