The maturity layer · MRK-2.0 · producer classes
From the Markdown you have to the graph you want.
MRK-1.0 asks one question and answers it pass or fail: does this article stand alone, say what it applies to, keep a stable id, and carry a date? A typical corpus passes on 31% of articles at first audit. That number is a fine place to start and a poor map. It cannot tell you whether the other 69% is one edit away or a rewrite away, and it stops measuring the moment an article passes, even though everything a knowledge graph can do lives above that bar.
The Structure Graduation Ladder replaces the single bar with five rungs of machine-readiness, each with mechanical criteria a tool can score. It is how a corpus graduates toward a deterministic, queryable knowledge graph one enumerable step at a time, without leaving Markdown, and without a big-bang migration to a component CMS. The destination is the one structured-content practice has long described: typed topics in the DITA tradition, a governed taxonomy, and a SHACL-guarded knowledge graph. The ladder is the on-ramp to it, a maturity path for teams starting from the Markdown they already have rather than a component CMS.
A number is not a map
"31% pass" is a headline. What a team actually needs is a backlog: every article on a rung, and its next rung naming the exact, finite edit that promotes it. The ladder turns "get machine-ready" from a cliff into enumerable work; it keeps measuring past the old pass line, all the way to the graph, so the same instrument tells you both that you have started and how far you have left to go.
Two headline metrics fall out of the histogram on the right. Contract rate is the share of the corpus at L1 or above: the old pass number, preserved. Graph-ready rate is the share at L3 or above: the number that predicts whether deterministic retrieval is even possible for a given answer. That second number is the one to move.
It is also where structure work earns its budget line. Every article that reaches L3 widens the set of questions a machine can answer deterministically and cite, which is what moves the shift-left ratio and, with it, cost per answer. Measure the payoff there, not in deflection.
The five rungs
Each rung is a superset of the one below: L3 implies L2 implies L1. None of them asks you to leave Markdown; L1 through L4 are reached by enriching front matter and turning on the projection, never by re-authoring prose.
- L0 · Prose. Free text, or front matter that fails the schema or an editorial clause (a section that does not yet stand alone). A machine must read the whole blob and guess.
- L1 · Contracted. The four MRK-1.0 clauses hold: it validates, every section is self-contained, applicability is data, and it carries an owner, a verified date, and a lifecycle. Today's bar: the 31% of a typical first audit. A machine can lift a section, scope it, date it, cite it.
- L2 · Typed. Every section carries a role (the resolution, the cause, the prerequisite, not "section 4"), the article's type satisfies its section shape, and visibility is declared. A machine can retrieve by function and apply answer-safety filters.
- L3 · Linked. It participates in the graph: at least one typed relation or section prerequisite, concepts bound to the vocabulary layer, and it projects cleanly to RDF. A machine can traverse relationships and do impact analysis.
- L4 · Reasoned. The projected graph passes SHACL, and retrieval is served graph-first with vector demoted to intent only. Rule-based, explainable, deterministic answers. L4 is the top producer class of MRK-2.0.
Score your corpus
L0 through L3 are fully mechanical: a validator, a few field checks, and a clean projection. L4 adds a mechanical half (SHACL over the corpus graph) and one operational attestation: that graph-first retrieval is actually wired up, the same honest human gate MRK already uses for self-containment.
The reference scorer reads a corpus, prints the distribution, and, for anything below L4, names the blocking edit. It is the ladder.py to MRK-1.0's check-jsonschema: run it today against the Markdown you have.
Run it
Download mrk-tools.zip: the MRK tools kit (python -m mrk ladder and its siblings), a hash-locked requirements.txt, and a three-article sample corpus. In an unzipped copy, run python3 -m venv .venv, then .venv/bin/pip install --require-hashes -r requirements.txt, then .venv/bin/python -m mrk ladder --graph-first sample/*.yaml, which prints the output shown here. The kit bundles the spec files it reads, mrk-1.1.schema.json, mrk-1.1.context.jsonld, and the SHACL shapes.ttl, and runs offline (Python 3.12 or newer): additive, backward-compatible, free to adopt.
Measured vs attested. --graph-first is your own statement that graph-first retrieval is wired up. To have it measured instead, run python -m mrk conform --consumer … --corpus kb/ --out mrk-evidence.json against your retriever, then python -m mrk ladder --evidence mrk-evidence.json kb/. The ladder checks the sealed evidence against each article's current digest, so L4 rests on a measurement rather than an attestation.
Two axes: trust × structure
The ladder is not the only ladder. Contextkeeping's Content Graduation Model already moves content up in trust: a forum answer earns its way to official documentation. The Structure Graduation Ladder is the orthogonal axis: it moves content right in machine-readiness, from prose to a SHACL-valid graph node. Every article is a point on both.
They are independent and composable. A brand-new knowledge-base article can be L3 on day one if it is authored with roles, relations, and concepts; a trusted five-year-old official doc can still be L1 until someone adds section roles. A mature operation drives both: high-trust content that is also graph-ready is what grounds an AI answer that is at once correct and deterministically retrievable.
From L1, two rungs up, the graph is real. See how an MRK corpus projects to RDF, and what a conforming reader must do with it in clause §R.