maturity-engine/INTENT.md

layer	role	standard	standard_version	companion
Engine	PIP	netkingdom-security-layer-model	0.7	net-kingdom/SECURITY-COMPANION.md

INTENT

This file captures why this repository exists and the kind of system it is meant to become. It is aspirational and stable, not a description of current implementation.

Layer: Engine. Role: PIP. This is the declaration required by NetKingdom Security Layer Model v0.7 §11 and the working companion v0.2. It is this repository's own voice, not a catalog row about us. The statute is net-kingdom/canon/standards/security-layer-model_v0.7.md; the companion is net-kingdom/SECURITY-COMPANION.md. On disagreement the statute governs, and a disagreement is a finding for gate-house.

One test decides the layer: given the same authoritative inputs, do we always return the same result? Yes — same criteria, same evidence, same level. That property is what makes this an Engine rather than an opinion. Companion §1: a new engine is a PIP unless the statute is amended, and statute §6 means it can never be a second PDP. We supply facts a decision consumes as claims.

Catalog entry (v0.7 §4): graded progression against declared criteria and evidence; the gap register; capability readiness (§9.5).

The machine-readable form required by §11 is layer.yaml, checked by scripts/check_layer_conformance.py. INTENT.md frontmatter must agree. Prose cannot distinguish a declaration from a transcribed review; the file is the surface.

Contest this layer if it is wrong — companion §2 asks for that correction rather than a polite label.

Purpose

maturity-engine computes, deterministically, how far a thing has progressed against declared criteria and submitted evidence — and keeps the history of that progression.

Given the same criteria and the same evidence, it returns the same level. That property is what makes it an Engine rather than an opinion.

Statute §12's self-healing loop has four verbs: observe, evaluate, decide, actuate. This repository is evaluate. Observation is kings-guard and is unstaffed. Decision is access-engine. Actuation has no surface and is held at zero estate-wide. Companion §10: do not plan around observation-in-production or automatic containment. Neither is this engine's gap to close.

Why This Exists

NetKingdom is full of maturity that nothing owns.

• The Active Secrets Management Canon defines ASM-0 … ASM-6, a seven-level ladder from Embedded to Closed-Loop Authority, assessed by hand or not at all.
• The security layer model has four conformance states — conforming, blocked-clean, declared gap, undeclared violation — and a gap register carrying intended_owner, blocked_on, review, state, and owner-status. Statute §13 still holds that table as a snapshot; the snapshot moves here as soon as this engine can store state.
• ops-warden tracks 27 delegated lanes queryable through warden route gaps.
• kings-guard holds posture lanes "advisory and fixture-driven until the engine gaps close" — a capability at a known level, waiting to climb.
• PEP-shaped consumers owe a published unreachable-engine stance map. Until this engine can hold the inventory, statute §13.1 is a one-row register with one absence, which is itself the finding.
• The State Hub carries DoR/DoD/DoC quality debt.

Every one of those is graded progress against criteria with evidence. Each was built separately because there was no engine for the concept.

There is also a structural reason. gate-house is catalogued as owning conformance review, and had no engine to act through — the same defect kings-guard found when the catalog assigned it containment while no engine exposed a containment surface (statute §9.1). Staff acts only through Engine APIs; conformance review is Staff work that needs an Engine underneath it.

The split:

gate-house judges and proposes. maturity-engine computes and remembers.

Judgment is inference and belongs to Staff. Computing a level from declared criteria and submitted evidence is deterministic and belongs here.

The Concept

A maturity model is a named, versioned ladder: ordered levels, each with criteria, each criterion satisfiable by evidence of a declared kind.

An assessment binds a subject — a repository, a capability, a lane, a tenant, an estate — to a model, a set of submitted evidence, and a computed level, at a point in time.

Maturity here is explicitly not a lifecycle. It is graded, evidence-based, open-ended, and revisable: levels and criteria may be added without breaking consumers, and a subject may move down as well as up when evidence expires. That adaptability is the point, and it is why the approval object — which needs a closed, binary, replay-proof state machine — belongs to approval-engine instead. The two engines are deliberate opposites and neither may drift toward the other (statute §9.5).

What maturity-engine Owns

• model registration — named, versioned ladders with ordered levels and criteria;
• evidence submission and validity — what was submitted, by whom, when, and when it goes stale;
• level computation — deterministic, explainable, reproducible from the recorded inputs;
• the gap register — declared gaps and unowned capabilities with capability, intended_owner, blocked_on, review, state, and owner-status, and the distinction among conforming, blocked-clean, declared gap, and undeclared violation. Statute §13's table is a snapshot that moves here; the state and owner-status columns MUST survive the migration. The three rules that stay in the statute are the two marks (pending / declared-gap), the owner-status rule (proposed ≠ assigned), and the scoring rule below;
• the PEP stance-map inventory — every PEP-shaped consumer's published unreachable-engine map, currently parked in statute §13.1 until this engine can hold it;
• capability readiness — whether a catalogued capability has the engine surface it needs, so a "pending" mark is a queryable fact rather than a footnote in a standard;
• progression history — how a subject moved, when, and on what evidence;
• the claim shape access-engine consumes for a maturity level — a PIP fact, never a decision.

The gap-record schema itself is Taxonomy's (statute §17). This engine holds the register and computes from records that conform to that schema; it does not author the schema.

What maturity-engine Does Not Own

• The content of the criteria. A ladder's levels are authored by whoever owns that doctrine — ASM-0…ASM-6 is gate-house's, workload posture is ops-warden's. This engine registers and computes; it does not legislate.
• Discretionary judgment. Where deciding whether evidence is adequate needs interpretation rather than a rule, that is Staff's call, submitted here as a finding. If a criterion cannot be evaluated by rule, it is not yet a criterion.
• Work structure. Workplans and tasks belong to the repository doing the work (ADR-007); repo-manager and the State Hub own that. A level is not a task list.
• The evidence archive. audit-core holds the tamper-evident record; this engine holds the operative assessment.
• Any authorization decision. See the guardrail. We are a PIP, never a PDP.
• Observation in production. kings-guard's, and currently at zero.
• Actuation / containment. An Engine concept held at zero; not this PIP's surface and not Staff's to own (statute §9.2).
• The layering constitution. gate-house authors it; net-kingdom publishes it. We consume it and hold the register the constitution points at.
• PEP shape. Computing a level is not a protected side effect. Stance maps belong to the repositories that cause those effects; we inventory them.

The Guardrail

A maturity level MUST NOT gate a decision directly.

Statute §6.1 / §9.5: compiled data that determines an outcome is still deciding, it just decided earlier. If a level determines whether an action is permitted, it must reach access-engine as an input claim or a versioned policy rule (statute §6.2) — never by a consumer branching on a level it fetched.

A maturity level MUST NOT be compiled into registry content.

Until access-engine's decision provenance carries a registry-snapshot digest — a gap it self-declared in §13 — a level reaching a decision through the registry is not reconstructable from the decision record. Same constraint, and same reason, as zone stance.

This is written on day one because the failure would arrive as a convenience: "we only gate on level ≥ 3, and only for this one lane." That is the second decision point the estate has already ruled against twice.

Scoring Rule

Statute §11, raised by kings-guard: blocked-clean MUST NOT rank below conforming. A repository that declined a shortcut and left a capability at zero has complied at cost. A repository that quietly opened a client and declared nothing has not. Any scoring this engine produces — conformance review included — MUST keep that order. Ranking restraint as if it were non-conformance would punish the repositories that took the standard seriously.

The four states, and they are not a ladder of shame:

State	Meaning
Conforming	no Tooling contact, or only declared diagnostic/conduit shapes
Blocked-clean	the capability does not exist because no engine exposes it, and there is no Tooling contact
Declared gap	a declared Tooling contact — tracked non-conformance
Undeclared violation	anything else

Blocked-clean is not a lesser state than conforming. Declared gap is tracked non-conformance, never conformance. An intended_owner is a proposal to the named repository, not an assignment onto it.

Evidence Bound

An append-only archive with a verified chain proves records were not altered or truncated after arrival. It proves nothing about an event never sent (statute §9.6 / companion §6). This engine will emit assessment and gap-register mutations to audit-core.

If a control's soundness depends on a level or a gap-register fact being present — because access-engine consumes it as a claim — that evidence is load-bearing: emission MUST be atomic with the state change, queued locally in this engine's own store, with no synchronous dependency on audit-core inside the state-change transaction, and a reconciliation or heartbeat rather than a rate for rare classes. Otherwise it is attributive: seek atomicity, declare the trade if it is given away, and never describe the trail as complete.

Absence of a record is not evidence of non-occurrence. Do not cite "observed in operation" as evidence while companion §10 holds.

This engine is a PIP. Persistence of models, evidence, assessments, and the register is our own store, not Lifecycle over catalogued Tooling (OpenBao, key-cape). Uncatalogued clients (State Hub, a future database) MUST be listed in the layer declaration so the check is total. The §5 Staff binding rule does not apply to an Engine API over state it owns; it does apply to any Staff caller of ours.

Design Principles

1. Deterministic or it is not a level. Same criteria, same evidence, same answer, every time.
2. Explainable by construction. Every level comes with the criteria met, the evidence used, and what the next level requires.
3. Ladders are data, not code. A new model is a registration, not a release.
4. Levels can fall. Evidence expires; maturity is not a ratchet, and a model that only climbs is measuring paperwork.
5. A tracked gap is not conformance. Declaring a gap makes it visible; it never makes it satisfied.
6. Blocked-clean is compliance at cost. Never score it below a silent violation.
7. Measure subjects, not people. Assessments attach to repositories, capabilities, and lanes.
8. Facts as claims, never as gates. A consumer that branches on a fetched level has built a second decision point.
9. Evaluate; do not observe, decide, or actuate.

Non-Goals

• Not a policy decision point, and never one.
• Not a work tracker, planner, or roadmap.
• Not a CI gate in itself — it publishes a level; whether anything blocks on it is the consumer's decision, subject to the guardrail.
• Not a scorecard for teams or individuals.
• Not an audit archive.
• Not an observation plane, and not an actuation surface.
• Not PEP-shaped, and not a publisher of unreachable-engine stance maps.

What Would Make This Repository Wrong

• A consumer branches on a level in the request path. The guardrail failed and the estate has a second decision point.
• A level is compiled into registry content while decision provenance has no snapshot digest. Same failure, earlier.
• It starts deciding. Any endpoint that answers "may this actor do X" rather than "what level is this subject at" is the failure statute §6 names.
• Criteria become unevaluable prose. If levels need a human to interpret them, the engine is a database with opinions and the determinism claim is false.
• It only ratchets up. If no subject ever loses a level, the evidence has no expiry and the model is measuring documents.
• Nobody submits evidence. If assessments are entered by hand rather than fed by the systems being assessed, this is a spreadsheet.
• It absorbs work structure. Gap register entries start growing owners, estimates, and due dates until it competes with the State Hub.
• Blocked-clean ranks below conforming. The scoring rule failed, and restraint is punished.
• The register loses state or owner-status in the migration. Proposed becomes assigned by omission.
• It claims observation or containment. Both are estate-wide zeros; citing them as if they worked is a finding.

Success Criteria

1. gate-house performs conformance review through this engine rather than by reading files, closing the §9.1 defect in its own catalog claim;
2. ASM-0…ASM-6 is assessable against a real estate, and the result is reproducible from recorded evidence;
3. the security layer model's gap register lives here, with state and owner-status intact, and kings-guard's pending containment claim is a queryable fact rather than a footnote;
4. PEP stance maps are inventoried here, so §13.1 is no longer the estate's real unpublished policy;
5. at least two ladders owned by different repositories are registered — the minimum evidence of a model rather than a preference;
6. a subject demonstrably loses a level when its evidence expires;
7. blocked-clean is never scored below conforming, demonstrated by a test, not by inspection;
8. a maturity level reaches access-engine only as a claim or a versioned policy rule — demonstrated by the absence of a consumer branch and by the claim contract, not by a comment.