PROP-058 — Documentation maintenance

1. Mandate and scope

04The owner set the frame on 2026-09-10 (J-013, J-014): the product ships up to ten times a day and merges up to a hundred pull requests, documentation drifts between checks and that risk is accepted; a version is a contract on behaviour, not a set of files; no technical lock binds a product release to the documentation. The regulation therefore measures drift, shows it to the reader and keeps a team promise to reconcile fully on a calendar.

05This regulation binds the manual org.vibevm.core/vibevm-docs and every other doc package of the org.vibevm groups; a second project that wants the same ritual receives it as a flow package later (PROP-057 ##obs-revisit), not by reading this PROP.

06The regulation grows only from what happened: each rule below names the journal entries that produced or confirmed it; a rule born without an entry is a hypothesis (J-013, J-014 — twice a rule written from habit turned out to be one).

2. Three sources of drift

• 07The product changes — a command, a flag, a manifest field, a behaviour, the text of a spec fact. The machine sees it: rule cites the current text of the spec, derived blocks regenerate from the current binary, examples run as golden tests, the coverage gate sees commands, fields and obligations without a page (J-001, J-058, J-088). Stale prose the machine does not see; a human reads it at full reconciliation (PROP-057 ##OBS-PROSE-STALENESS-IS-HUMAN).
• The world changes — questions without a page, a new scenario, agents that find no answer by anchor. The signals of §6 and the page of the week catch it (hypothesis until the site is deployed: J-112 recorded that before deployment the weekly loop sees only the linter and the reading rota).
• The text ages — the ladder of terms is broken by insertions, a term appears before it is introduced, the tone drifts, a page has not been read for a year. The style linter, the reading dates in reviews.toml, reading aloud and the rule of five edits catch it (J-060, J-093, J-112).

3. Five loops

08Five loops with five triggers: a commit, a week, a month, a calendar promise, and the owner's decision to bump the version. Each has an input, an output and a gate; none of them fails a product build.

• 09The commit loop. A product change a user can see — a new or changed command, flag, manifest or lock-file field, report format, error message with an address, a spec fact marked actionstage="doc", a new PROP — carries its documentation in the same commit, as DEV-GUIDE.md and RUNTIME-GUIDE.md already do; when that is impossible, the commit carries a debt line (§8). This is a habit kept by the pull-request checkbox «documentation: updated / debt recorded / not needed», never a lock (J-013; PROP-057 ##OBS-NO-RELEASE-LOCK).
• A documentation-only change takes the short path: edit → vibe doc check --style --examples --citations on the pages touched → one commit docs(vibevm-docs): … (J-093: the style linter runs before every commit that adds prose).
• The first action of any edit is git status and a check for a live conflicting writer; two central sessions in one tree stop (J-005). In a tree shared with parallel workers, commits name their paths explicitly — git commit -m … -- <paths>, never a bare commit or git add -A (J-072, J-090).
• The weekly loop, 30–60 minutes, in this order: a cheap model runs vibe doc todo --format md and vibe doc check over the whole package and files the report; the central session sorts the queue — what is fixed in five minutes is fixed now, at most five edits per loop, what is bigger becomes a debt line with severity, what is disputable becomes a one-line question to the owner; the signals of the week (§6) each become an edit, a debt line or «observation without action: reason»; the page of the week — the next page along reviews.toml — is read aloud by the owner or the central session as the reader of the style law, every stumble becomes an edit or a debt line, and the reading date goes into reviews.toml; a journal entry closes the loop with what was done, deferred and surprising (J-112: rehearsed 2026-09-12 in 25 minutes).
• The monthly loop, half a day, with the owner: the eight metrics of §9 as a table with their trend; an audit of the corpus — every top-level command, manifest field and kind has a page, the glossary keeps one word to one meaning, terms are introduced where readers look for them, duplicates and dead pages, the llms tiers within their budgets, a sample of ten prompts run through an agent; the analytics of the site; the lag of adaptations; the drain of docs: debt — every line closed, given an atom or re-rated with a reason; the ticks that slipped past the linter go into its lists and false positives fix the rule; every journal entry of the month still owing a decision gets one, and the regulation is amended with a date and the entries; the owner reads three pages aloud — one new, one most visited, one oldest by reviews.toml; the documentation package is published again under the same number, with a dated entry in the changelog written by hand from the journal, for as long as PROP-057 ##VERSION-OVERWRITE-POLICY holds (hypothesis until the first monthly rehearsal, A6.3).
• The full reconciliation, a day or two, once a quarter and before a major milestone — a promise the team makes itself, never a release condition: a cheap model builds the documentation against the current release binary, not a debug one (J-001), runs vibe doc todo and vibe doc check with every flag, all examples and all prompts through an agent, and files the report; the central session closes the gaps — new pages or debt with an atom, regenerated derived, updated golden examples, repaired citations; every page is reread against the current product with --help and the spec open beside it, in the order of reviews.toml from the least recently read, and each page reread gets the date; adaptations are reread against their sources; the package ships a version compatible with the current product release, the site shows it as latest, and after publication the root links of the domain to /doc/sitemap.xml and /doc/llms.txt are checked with curl (J-004); the report goes to the journal with the gaps before and after, the pages reread and rewritten, and the time. The only gate is the reconciliation's own: zero gaps and no reading date older than the reconciliation (hypothesis until the first reconciliation, A6.5).
• A reconciliation starts from a green self-check panel, otherwise documentation drift is indistinguishable from inherited debt (J-026, J-048, J-100).
• The version change, hours: the owner bumps the product version — no gate on that step; a cheap model records the surface snapshot of the new version against the current release binary, vibe doc surface --record <new>, beside the snapshot the last reconciliation or version change left — one snapshot while the number stands still, overwritten in place by vibe doc surface --record 1.0.0, for as long as PROP-057 ##VERSION-OVERWRITE-POLICY holds; vibe doc diff <old> <new> names the pages to update with a reason each — an empty list is also an answer; the central session updates only the pages named and writes new ones for what appeared without a page, the rest becomes docs: debt with an atom; a human changelog between versions is written from the diff by hand and the diff itself is never published; the package is published again under that same number, with a dated entry in the changelog and the new [[documents]] version, and the site shows it as latest; the journal records how many pages the diff named, how many were updated, and the time (J-017, J-099; PROP-057 ##OBS-SURFACE-SNAPSHOTS, ##OBS-NOTHING-LEAKS).
• Known limit of the diff: the manual's derived blocks show top-level help only, so a changed flag of a subcommand lands in the queue as «needs a new page» rather than as a page to update; whether subcommands get their own derived blocks or prose is decided in a weekly loop from the queue, not in advance (J-099).

4. Tools

• 10vibe doc todo is the maintenance queue by the current state, with no «since» comparison: commands, fields and obligations without a page, red examples, unresolvable citations, structural divergences of adaptations, page age by reviews.toml, docs: debt lines from BACKLOG.md, and the linter's statistics; --format md for the weekly report, --format json for the metrics. It prints numbers and never fails a build; every section carries measured, and a metric the run could not take is null, never 0 — «no findings» and «nobody looked» must print differently (J-099). Examples run only with --examples, because a sandbox per fixture costs minutes and the weekly reading should not.
• vibe doc check holds the internal checks — examples, citations, derived, coverage, media, translations, style — and --prompts runs the prompts of scenario pages through an agent and checks their asserts; that flag is expensive and stays out of the panel: by hand, by sample in the monthly loop, in full at reconciliation (J-065: prompts written without a run hid three product defects and three wrong asserts).
• vibe doc surface --record <version> writes the structural snapshot of the product for a declared version to maintenance/surface/<version>.json — commands and flags from --help, manifest and lock-file fields read from the real parser, schemas, the text of the facts marked actionstage="doc", the format registry — keyed by the version number alone; vibe doc diff <old> <new> turns two snapshots into pages with reasons through the citation graph, the derived sources and the coverage map. Both are the documentation developers' kitchen; the site renders nothing of it (J-099; PROP-057 ##OBS-SURFACE-SNAPSHOTS).
• maintenance/reviews.toml records when each page was last read aloud and by whom, and the date of the last full reconciliation; the order of its rows is the reading rota. It is authored data, never a generated record: a date and a reader, never a revision, a hash or «checked against». A page with no row has never been read aloud, and the queue says exactly that. The reader is named by a name people recognise or by a role such as «central session», never by the name of a model (J-112).
• JOURNAL.md of the documentation package is the journal of §5; during the campaign it lived in the campaign zone and moved into the package by consolidation, sorted, cross-linked and shortened where an entry carried private infrastructure, an unconfirmed defect of a neighbouring crate or user-local identifiers (J-111); vibe doc todo reads it without a flag.
• CHANGELOG.md of the documentation package says what changed for the reader, by version, in human text written from the journal; the output of vibe doc diff is its source, never its content (PROP-057 ##OBS-NOTHING-LEAKS).
• Documentation debt lives in the host's BACKLOG.md as lines prefixed docs: with a severity and the address of the change (§8); the panel counts them and prints drift as a number (PROP-047 ##DEBT-IS-A-LIST-NOT-A-RATIO).
• The package carries the checklists the loops are run by — maintenance/weekly.md, maintenance/monthly.md, maintenance/release.md, and after the first reconciliation maintenance/reconcile.md written from what was lived; a checklist item without a rule here is a hypothesis.

5. The journal and its laws

11The journal is one table that is only appended to: date; type — успех, неудача, находка, наблюдение; a stable id J-NNN; what happened; the evidence — a command, a commit, an anchor, a file; and «→ регламент» — which rule the entry confirms, changes or creates, or «observation without action: reason».

• 12Law one. The entry is written in the same atom where the event happened — a red probe, a false positive of the linter, a refuted prediction, a workaround, a trick that worked — never «at the end of the week from memory» (J-046, J-063, J-066: three entries that would have been lost a day later).
• Law two. The «→ регламент» field stays empty no longer than one monthly loop; vibe doc todo counts the entries owing a decision as one of the eight metrics (J-099: 0 of 112 at consolidation).
• Law three. A rule without an entry is a hypothesis: every rule of the regulation cites the entries that produced it, and a rule without a citation is marked «hypothesis» and checked (J-013, J-014, J-016: the release lock, the version tags and the content-hash pins were all written from habit and all fell to the owner's word).
• The journal ships with the package, so an entry names no private infrastructure, no unconfirmed defect of a neighbouring product, no user-local identifier and no temporary path; the campaign-side gate that checks those patterns runs over the package journal before every commit that touches it (J-046, J-111).
• Predictions are part of the journal: each is an entry when made and an entry when confirmed or refuted with a number (J-011, J-037, J-036 — the legacy prediction refuted by the inventory, and the campaign's thirteen predictions in the ledger).

6. Signals

• 13From the build: unresolvable citations, red examples, coverage holes, structural divergences of adaptations, linter statistics — all in vibe doc todo (J-088, J-093).
• From the product: new commands, fields, obligations and PROPs without a page are visible to the coverage gate as current gaps, never as «changes since» (J-084, J-088).
• From the owner: the decision to bump the product version — the only event that starts the version loop (J-017).
• From prompts: a red assert when an agent runs them, or an agent that did not understand the prompt — an edit or a docs: debt line; two failures in a row — a rewrite (J-065).
• From people: questions in chat and issues, the owner's remarks when reading aloud — an edit or a debt line (J-112: two stumbles on the first page read).
• From agents: the skill vibevm-docs asks an agent that found no answer by anchor to record the question as a docs-gap: line in the consuming project's BACKLOG.md, for the host in its own — whether a skill may write into a foreign file is the owner's open question (§12), so until his word the skill only proposes (hypothesis).
• From the site: views, exits and reading time per page from the analytics tag, search queries without a result once search exists, the search console — the monthly loop's input (hypothesis until the site is deployed, J-112).
• From the journal: entries with an empty «→ регламент» field — the monthly loop's input (§5 law two).

7. The discipline of small edits

• 14One edit is one commit docs(vibevm-docs): … with a concrete description, so the reading rota and the rule of five can count them (J-112: five edits, five commits).
• Anchors do not change; derived is never edited by hand; a number or a field name in prose stands only with a rule beside it (PROP-057 ##OBS-RULE-EDGE-UNPINNED; J-058).
• A term inserted by an edit is introduced on the spot — a glossary link, an italic introduction or a gloss — and a term used in another sense is replaced by an ordinary word rather than linked; the style linter is green on the page before the commit (J-060, J-093, J-112).
• The rule of five. The fifth small edit of one page since its last reading aloud puts the page into the reading rota as the next page of the week: accumulated patches break the ladder invisibly to each patch's author (hypothesis — no page has reached five edits yet).
• A small edit that pulls other pages after it is not small: it becomes a debt line with an atom (J-062: seven pages described a layout vibe init does not create, and the fix was an atom, not a patch).

8. Documentation debt

• 15A debt line is a row of the host's BACKLOG.md prefixed docs:, with a severity P1–P3 and the address of the change it owes a page to; a line without an address is not accepted. The monthly loop drains the list; the full reconciliation takes what is left (J-064: «needs an author» was closed by a rule written into a script, not row by row).
• Debt is measured as a list and printed as a number — P1 lines are the sixth metric — never as a ratio and never as a red step (PROP-047 ##DEBT-IS-A-LIST-NOT-A-RATIO; J-013).

9. The eight metrics of the monthly loop

16Eight numbers and no more, in a table in the monthly report with the trend beside each; vibe doc todo --format json produces them, and a number the run could not take is null (J-099).

• 17Gaps at the start of the month — rows of the queue by coverage, examples and citations; towards zero.
• Page age — the median of days since the last reading by reviews.toml; below ninety (J-112: the first reading set the median to zero for one page and left forty-seven pages without a row).
• Adaptation divergences — the structural divergences --translations finds, because the project keeps no revisions to sum lag by; towards zero at full reconciliation (P2-O7, J-079).
• Coverage of obligations — vibe doc check --coverage; one hundred per cent (J-084, J-088).
• Style findings per thousand words — the linter over the corpus; towards zero (J-093: 4.31 at consolidation, 4.13 after the first weekly loop).
• Debt — docs: lines in BACKLOG.md by severity; P1 equals zero.
• Findings owing a decision — journal entries with an empty «→ регламент»; all decided.
• Days since the last full reconciliation — by the date in reviews.toml; at most ninety at the quarterly cadence.

10. Gates

• 18Only internal breakage of the documentation is red in the panel: a red example, a derived block that no longer builds, a vanished citation anchor, a page the pivot cannot read. Drift and debt are printed as numbers (PROP-057 ##OBS-NO-RELEASE-LOCK; J-074, J-088).
• No gate binds a product release to the documentation, and no step of the panel goes red because the product moved ahead of the manual (J-013).
• A phase border or a reconciliation runs the cross-cutting checks — codegen, the map, wire-diff, conform, facts — on a warm shared build directory and takes the per-crate evidence from the workers' reports; the full panel runs once before a merge into the mainline (the owner's word of 2026-09-12; J-100, J-104).

11. How the tooling is changed

19The documentation tools are code, and the campaign that built them left rules for the work packets that change them; they bind the coder tier and the central session alike.

• 20Parallel packets in one tree commit only with explicit paths and never stage a neighbour's files; packets that share an entry-point file — an export barrel, a build script — get it split in advance or run one after the other (J-072, J-090).
• A worker never stops a process it did not start; a busy binary is waited for or built into a private target directory, and a worker that flips the features of the shared binary returns it to the panel's state or says it could not (J-105, J-110).
• The packet gate runs conform check over the whole workspace against the baseline, not over the packet's own paths: a worker that extends an old file answers for its budget, and the baseline is frozen only by the owner's word with a reason (J-100).
• Before/after measurements are taken one at a time and with no other packet's codegen in the tree; a test that reads generated code is not measured during parallel work (J-101).
• Whatever writes bytes into a golden corpus pins its dependencies explicitly — default-features = false and one feature — so a projection is never a function of the build graph; a commit that blesses a corpus runs wire-diff and files its output (J-069, J-104).
• A step over the output of vibe doc build runs at least once over the real manual before it is committed, and a builder runs once over the real registry: fixtures did not catch a copy step that lost two projections of three, a shelf that stayed empty, or a table that lost its first row (J-097, J-108).
• A diagnosis of someone else's anomaly written into a packet is a hypothesis marked «verify», never an order «fix it this way»; the worker reproduces first and may change the commit subject to the fact (J-107).
• A test of a surface with behaviour asserts the behaviour — pages in the navigation, a request for the manifest — and not only the addresses of requests; a server edits the head of a shell template in place and never inserts (J-106, J-109).
• A number in a packet is a hypothesis until measured on the built output — the content-security policy expected two inline scripts and the output carried forty-seven (J-096); a generator's zero exit code is not evidence, the page count is (J-040).

12. How the regulation changes, and the open questions

• 21The regulation is not dogma: it changes in the monthly loop by the journal, each change a dated edit of this PROP citing the entries J-NNN that caused it (§5 law three).
• Once a quarter the owner is asked which loops proved superfluous, which metrics nobody reads and which rules never fired; a rule that did not fire in a quarter is marked «dormant» and leaves the checklists, a rule without an entry stays «hypothesis» — the regulation loses weight rather than gains it (hypothesis until the first quarter).
• Open to the owner: the cadences — week and month as written, or two weeks and a quarter; who is on duty for the weekly loop — the owner with the central session, or the session alone with a report; whether small edits ship as a patch version weekly or accumulate to the monthly release.
• Open to the owner: whether the skill may write docs-gap: lines into a consuming project's BACKLOG.md by its own will, or only propose them (§6).
• Open to the owner: the cadence of the full reconciliation — quarterly, before a major milestone, or both; the recommendation is both, with the owner's right to postpone.
• Open to the owner: whether examples with expect stay golden tests in the panel — the one technical link between product and documentation — or become a measurer too; the recommendation is to keep them: they are edited like any golden file and cost minutes (PROP-057 ##OBS-EXAMPLES-GOLDEN).
• Open to the owner: whether vibe doc diff <version> now — the inner hint of which pages to reread first at reconciliation — is allowed; the command exists behind --allow-now and refuses by default until his word.

13. Roles by tier

• 22The owner reads the page of the week when he wishes, reads three pages aloud and decides on the regulation in the monthly loop, sets the date of the full reconciliation and accepts its report, bumps the product version and accepts the changelog.
• The central session edits prose when a commit requires it, sorts the queue and makes the small edits of the week, writes the journal entries, audits the corpus, rewrites pages, amends the regulation, writes changelogs, rereads pages against the product at reconciliation and updates the pages a version diff names.
• The coder tier changes the tools — todo, check, surface, diff, the generators of derived — by findings of the loops, under §11.
• A cheap model runs todo and check and files the report, collects metrics and analytics, drafts adaptations, records surface snapshots and runs the diff.