maturity-engine/INTENT.md

---
layer: Engine
role: PIP
standard: netkingdom-security-layer-model
standard_version: "0.7"
companion: 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.