maturity-engine/INTENT.md

INTENT

Layer: Engine. NetKingdom Security Layer Model §4 catalog — a deterministic API for a modeled concept, where the same authoritative input state yields the same result. Standard: net-kingdom/canon/standards/security-layer-model_v0.3.md.

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.

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.

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 three conformance states — conforming, declared gap, undeclared violation — and a gap register carrying intended_owner, blocked_on, and review dates.
• 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.
• 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 (standard §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.

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 with intended_owner, blocked_on, and review dates, and the distinction between a tracked gap and an undeclared violation;
• 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.

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.

The Guardrail

A maturity level MUST NOT gate a decision directly.

Standard §6.1: 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 (standard §6.2) — never by a consumer branching on a level it fetched.

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.

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. Measure subjects, not people. Assessments attach to repositories, capabilities, and lanes.

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.

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.
• 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.

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, and kings-guard's pending containment claim is a queryable fact;
4. at least two ladders owned by different repositories are registered — the minimum evidence of a model rather than a preference;
5. a subject demonstrably loses a level when its evidence expires.