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.