From 8545e229eb251081524ea503a1c97cd2fd4728a3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 28 Aug 2026 22:34:02 +0200 Subject: [PATCH] Seed INTENT and README maturity-engine computes a level deterministically from declared criteria and submitted evidence, and keeps the progression history. It owns model registration, evidence validity, level computation, the gap register, and capability readiness. It closes a defect in gate-house's own catalog claim: gate-house is catalogued as owning conformance review with no engine to act through, which is the standard section 9.1 problem kings-guard raised for containment. Staff acts only through Engine APIs. Carries one guardrail from day one: a maturity level must never gate a decision directly, or the estate acquires a second decision point by the graded back door. Co-Authored-By: Claude Opus 5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 2564823@bnt-lap001 Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9 --- INTENT.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 27 +++++++++- 2 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..1b09bd5 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,158 @@ +# 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. diff --git a/README.md b/README.md index c20aa7e..14eb069 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,28 @@ # maturity-engine -Modelling, tracking and enabling maturity \ No newline at end of file +**Computes, deterministically, how far a thing has progressed against declared +criteria and submitted evidence — and keeps the history of that progression.** + +An Engine in the NetKingdom security layer model. 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. + +> **gate-house judges and proposes. maturity-engine computes and remembers.** + +It exists because NetKingdom is full of maturity that nothing owns — the Canon's +ASM-0…ASM-6 ladder, the layer model's conformance states and gap register, +ops-warden's delegated lanes, kings-guard's advisory-until-gaps-close posture, +the State Hub's DoX quality debt — and because `gate-house` was catalogued as +owning conformance review with no engine to act through, the same defect +kings-guard found for containment. + +**Guardrail:** a maturity level must never gate a decision directly. If a level +determines an outcome it reaches `access-engine` as an input claim, never by a +consumer branching on a fetched level. Compiled data that determines an outcome +is still deciding. + +Maturity here is graded, evidence-based, open-ended, and revisable — levels can +fall when evidence expires. The closed, binary, replay-proof state machine of an +approval belongs to `approval-engine`; the two engines are deliberate opposites. + +See [INTENT.md](INTENT.md).