openrig/docs/reference/knowledge-maturity.md

doc, title, stage, warrant

doc	title	stage	warrant
reference	Knowledge maturity — the epistemic ladder	established	The maturity ladder makes trust explicit by tying claims to visible stages, promotion rules, and durable evidence.

Knowledge maturity — the epistemic ladder

This document is the addressed canonical home for the maturity model: the ladder, its timescales, promotion and demotion, the warrant rule, and where maturity is carried on each surface. A corpus that cannot state its own trust model cannot tell you it is rotting — that is why this document exists.

The ladder

Knowledge climbs four rungs:

DATA → FIELD NOTES / OBSERVATIONS → INSIGHTS → CANON

Trust tracks maturity, and a claim's address tells you its trust. Each rung's expected rate of change is roughly an order slower than the one below:

Rung	Timescale of change	Where it lives (by address)
Canon	years — "it was always true; we only discover and curate it"	conventions/ · doctrine/ · primitives · SOP.md · CULTURE.md
Insights	months — stable, still earning	the upper half of LEARNED.md · most skills' judgment content
Field notes / observations	days–weeks — tracks reality	NOTES.md · the raw half of LEARNED.md · field-notes/
Data	continuous	stream events · transcripts · receipts · logs

Canon is defined by its timescale

"What makes something canon is that its expected rate of change is very long." Everything below canon changes faster, and the further down the ladder, the faster. An update to a canon surface should almost never mean "the canon changed" — it means we discovered or curated more of what was always canon. LEARNED.md is the file that tracks a changing reality; SOP.md is the file that accretes settled truth.

The lived consequence: a canon diff should read as addition. Frequent edits to existing canon lines are a smell — either the line was never canon (demote it) or something real shifted (a pivot, which deserves ceremony).

Promotion and demotion

Promotion is an explicit act at each rung: harvest / notice → fold, in own words → curate (explicit, dated). Content enters the lived layer (LEARNED.md) at whatever maturity it has, proves itself stable over time, and graduates.

Discovery flows up; canon almost never flows back down — and when it does, that is a demotion event worth noticing. Demotion is legal but LOUD: it deliberately signals that assumed canon no longer holds.

The warrant rule

A promoted claim carries its compressed warrant — the scar, evidence, or ruling that earned it travels with it. "Canon without warrants is cargo cult with good formatting." Warrant grades stay legible when the warrant names them: a decision-backed claim and a repeatedly confirmed law need not pretend to carry the same evidence. This document's own frontmatter practices the rule.

Maturity is multi-dimensional

The epistemic ladder above is one dimension. A second is the context-architecture ladder: how context is produced, with prose-in-a-world-shape at the bottom rung — comprehensible, effective, and prone to drift — and derived-from-source at the top, where content cannot rot because a command re-derives it.

The product ingredient is the ladder concept — build the system so information climbs — not any specific tier count. Tier counts here are descriptive, not normative. Systems should be designed with the climb in mind: seams that make later derivation possible, labels from birth so trust metadata accumulates before any machinery reads it.

Two encodings, one ladder

Maturity is carried differently per surface. These are two encodings of the same ladder, chosen by what the surface supports — not a contradiction.

Corpus and tree files carry maturity by ADDRESS. The filename law is the ladder: NOTES.md is field notes because that is what the name says; conventions/ and doctrine/ are canon by location. Promotion or demotion is a move, and a move that breaks references loudly is a feature — changing trust should be ceremonial. No per-section level tags are needed; the address is the tag.

Pack, lore, and scope items carry maturity as a stage FIELD from birth, using the shipped vocabulary (four rungs plus two exits):

wip | provisional | established | canonical | superseded | retired

superseded must name its successor; retired means do-not-use. These are the ONLY valid values — invented stages (shape, shaped, draft) are rejected. Items minted under new conventions carry a stage from birth: labeling from day one is free, retrofitting is archaeology.

This section is the stage-vocabulary source for lore and pack work. The taxonomy axis (WORLD / LORE / SKILLS / MISSION) is orthogonal to stage: taxonomy says what kind, stage says how trusted.

What maturity is not

Two axes are habitually conflated with maturity and are not it:

• Audience / placement. Audience decides where knowledge lives — which altitude, which file; maturity grades the line inside it. A pod-level item can be raw observation, a seat-level one can be canon. Promotion to canon is a maturity event, not a move up the tree. Facts about mechanisms can skip rungs (a one-command verification settles them); inferences about practice must accrue evidence.
• Feature lifecycle. "Feature lifecycle is separate from epistemic maturity" — lifecycle (active | deprecated | retired) answers whether agents should still build on a behavior; maturity answers how trustworthy a piece of knowledge is.

Direction, not construction

A possible end-state is a level-first corpus tree where one address string carries trust, domain, claim, and freshness at once. It is direction only.

Nothing in this document is mechanized: no enforcement tooling, no mass relabeling, and no new tier scheme. This document establishes the vocabulary above and labeling from birth; readers, parity checks, and promotion tooling remain outside its scope.