= Minerva Documentation
:toc: macro
:toclevels: 2
This file defines the organization and maintenance rules for Minerva
documentation. It is an operating guide, not a project status ledger. Current
work is in
https://github.com/OwlRoute/minerva/blob/main/todos.adoc[`todos.adoc`]
(repository only; not shipped in the crate archive). Completed work is in Git
history and the local `archive/` directory.
toc::[]
== Documentation invariants
* Code and tests define shipped behavior. A contradictory document is stale
unless it is explicitly marked as target or planned state.
* Each document has one responsibility and one time model. Stable guidance,
current work, historical record, target architecture, and point-in-time
decisions do not share a ledger.
* Compatibility surfaces are documented where callers look for them:
manifests, configuration, wire layouts, lifecycle ordering, errors, feature
flags, extension hooks, and user-visible diagnostics.
* Claims name their evidence. Behavioral guarantees cite guarding tests or
proof artifacts. Performance claims name a reproducible measurement.
* A document owns interpretation and navigation. It does not duplicate source
inventories that can be discovered from the tree.
== Read in this order
. xref:docs/glossary.adoc[Glossary] establishes the load-bearing vocabulary.
. xref:docs/day-one.adoc[Day one] exercises the public surface as a new
consumer would. Its companion,
xref:docs/what-is-proven.adoc[what is proven], maps claims to evidence.
. xref:docs/consumer-guide.adoc[Consumer guide] records the supported public
surface and migrations.
. xref:docs/target_arch/index.adoc[Target architecture] states the north star,
capability boundaries, and non-goals.
. xref:docs/horizons.adoc[Horizons] records possible growth with firing
signals. Read it with the
https://github.com/OwlRoute/minerva/blob/main/owner-comments.adoc[owner rulings]
(repository only) before choosing
a new initiative.
. xref:docs/crdt-vision.adoc[CRDT vision] narrows the target architecture for
CRDT-facing work and records its witness ledger.
. xref:docs/μή.adoc[μή] defines the working-session prohibitions and document
hygiene.
. Read the relevant PRD, foundations note, and co-located module note before
changing that subsystem.
== Document classes
[cols="2,3,3",options="header"]
|===
| Location | Responsibility | Time model
| `DOCS.adoc`
| Documentation operating guide and navigation.
| Stable. Change only when the documentation system changes.
| `CHANGELOG.md`
| Release notes for crates.io consumers: one section per published version,
with migrations summarized from the consumer guide's table.
| Append a section at each release. Never rewrite a published section.
| `todos.adoc`
| Outstanding, plan-backed work with firing signals, risks, and priorities.
| Present tense. Remove completed work to the archive.
| `owner-comments.adoc`
| Standing rulings, grounds, and unwind conditions for gated work.
| Append or amend through an explicit ruling. Do not paraphrase it elsewhere.
| `docs/target_arch/`
| Architectural thesis, capability boundaries, non-goals, and imagined
primitives.
| Target state. Mark unimplemented surfaces plainly.
| `docs/horizons.adoc`
| Growth avenues, intake questions, firing signals, and anti-avenues.
| Forward-looking and event-driven, never an implementation queue.
| `docs/crdt-vision.adoc`
| CRDT-specific architecture, hazards, evidence, and staged arcs.
| Forward-looking. Update when an arc or its evidence changes.
| `docs/prd/NNNN-*.adoc`
| Requirements, invariants, non-goals, compatibility surfaces, and acceptance
evidence for one product boundary.
| Point-in-time decision record with an explicit implementation status.
| `docs/metis-*.adoc` and other foundations notes
| Derivations, laws, counterexamples, and design boundaries shared across
implementations.
| Stable reference. Amend when the underlying argument changes.
| `src/<module>/mod.adoc`
| Implementer-facing map of one module beside its source.
| Live with the code. Re-synchronize paths and line references when it moves.
| `docs/consumer-guide.adoc`
| Public API expectations, migrations, and caller-owned responsibilities.
| Live compatibility surface.
| `docs/day-one.adoc`
| Minimal public-surface narrative backed by executable examples.
| Live with its integration test.
| `docs/what-is-proven.adoc`
| Claim-to-evidence index across tests, models, fuzzing, and proofs.
| Dated evidence inventory. Re-verify counts before changing them.
| `docs/glossary.adoc`
| Terms whose names carry architectural meaning.
| Stable vocabulary. Admit a term only when it supports an invariant or
boundary.
| `docs/μή.adoc`
| Rules for conducting implementation and documentation sessions.
| Stable discipline derived from rulings and observed failures.
| `docs/miscellany/`, `docs/lit-review/`, and `docs/research/`
| Scoping notes, research intake, and external material.
| Evidence or working record, not shipped contract. State provenance and
verification limits.
| `archive/`
| Superseded status ledgers and completed chronology retained locally.
| Historical and intentionally ignored by git.
|===
== Sources of truth
Behavior::
Code and executable tests. Rustdoc is part of the public surface and must
agree with both.
Public compatibility::
The consumer guide plus the relevant PRD and wire or manifest specification.
If they disagree with shipped behavior, reconcile them in the same slice.
Architecture::
Target architecture for direction, PRDs for accepted boundary decisions,
foundations notes for derivations, and owner rulings for gated policy.
Current work::
`todos.adoc`. It contains only unresolved work. Completion records go to
the archive and git history.
Verification status::
The evidence index and reproducible command output. Do not turn this file
into a rolling test-count or release-status log.
== File placement and names
* Use AsciiDoc (`.adoc`) for maintained project documentation.
* Name PRDs `NNNN-kebab-title.adoc` under `docs/prd/`.
* Name co-located module notes `mod.adoc` beside the corresponding
`mod.rs`.
* Put cross-cutting derivations and foundations under `docs/`. Do not hide
compatibility requirements in miscellany.
* Put transient scoping and research intake in the appropriate non-contract
directory and label its provenance.
* Archive replaced ledgers under `archive/`. Keep the tracked replacement
self-contained because fresh clones do not contain the archive.
== Writing conventions
Prose::
Write for a senior Rust reader. Follow ADS-STE100 Simplified Technical
English where technical precision permits it. Use short declarative
sentences. Use one term for one concept. Prefer active voice. Put one
instruction in each sentence. State conditions before actions. Do not use
contractions or em dashes. Familiar technical and bibliographic
abbreviations are controlled vocabulary. These include `e.g.`, `i.e.`,
`et al.`, and `cf.`. Prefer a period to a semicolon in prose.
Project terms, Rust identifiers, mathematical terms, and quoted protocol
text are controlled vocabulary. State invariants, ownership, capability
boundaries, failure semantics, and tradeoffs. Do not explain clear syntax or
control flow.
Contracts::
Distinguish shipped, planned, gated, and rejected states explicitly. Use
normative language only for an actual contract.
Security and operations::
Document concrete trust boundaries, validation, resource bounds,
cancellation, retries, shutdown, and partial-failure behavior where they
exist. Do not add generic security boilerplate.
Examples::
Prefer examples compiled or synchronized by tests. Mark illustrative
pseudocode so it cannot be mistaken for an accepted API.
Claims::
Use exact type, method, error, feature, and frame names. Date measurements
and verification counts. State assumptions and known limits next to the
claim.
== References
* Use AsciiDoc `xref:` links for repository documentation.
* Co-located `mod.adoc` notes may cite `path:line`. Update them
when source moves.
* PRDs and foundations notes cite stable symbol names or bare paths rather
than volatile line numbers.
* Link to the owning document instead of copying its explanation.
* Every added xref must resolve, and every named test or symbol must exist.
* Preserve exact Unicode names in paths and vocabulary.
== Change workflow
. Identify the document class and its source of truth before editing.
. State the invariant or compatibility surface the change records.
. Update all documents that own the same boundary in one coherent slice:
public rustdoc, PRD, consumer migration, module note, and evidence index as
applicable.
. Remove superseded status prose instead of layering a second current story
beside it.
. Move completed tracker history to `archive/`. Keep only unresolved work in
`todos.adoc`.
. Re-run the relevant executable examples, documentation checks, and broad
verification proportional to the affected contract.
. Record the durable decision in the owning document and git history, not in
this index.
== Verification
At minimum:
* render changed AsciiDoc when Asciidoctor is available.
* resolve every added xref and verify named symbols and tests.
* run `cargo fmt --all --check` and `git diff --check`.
* run rustdoc with warnings denied when source docs or public links change.
* run tests that compile or synchronize examples.
* run the repository review gate before commit.
For wire layouts, manifests, configuration, public API, lifecycle ordering, or
error contracts, run the focused contract tests and the broad workspace matrix.
Documentation-only edits do not excuse stale or unverifiable claims.
== Archival
The local `archive/` directory preserves superseded ledgers for convenient
reference but is not part of a fresh clone. Git history remains the durable
record. An archived file receives an `archived-through` attribute. The new
tracked file must stand alone without the archive.