coulomb/maturity-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
maturity-engine/SCOPE.md
tegwick 4cde4e489a Stand up the Engine/PIP surface for MAT-WP-0001 
Declare layer.yaml, add a Python engine over a local SQLite store,
and cover deterministic assessment, the §13 gap register, stance-map
inventory, claim guardrails, and the gate-house review path with tests.

Assistant: grok
Assistant-Session: 01a04ceb-150e-7e80-a542-ec8b1372e164
2026-08-29 12:54:37 +02:00

9 KiB
Raw Permalink Blame History

SCOPE

This file describes the repository's current, evidenced responsibility. It is deliberately distinct from the direction in INTENT.md and from unreviewed consumer demand.

One-liner

NetKingdom Engine (PIP) that computes a maturity level from declared criteria and submitted evidence, holds the estate gap register and PEP stance-map inventory, and emits levels only as claims.

Current Responsibility

maturity-engine owns the Engine/PIP surface assigned by NetKingdom Security Layer Model v0.7 §4: graded progression, the gap register, and capability readiness. It declares that layer in INTENT.md frontmatter and in layer.yaml.

The current implementation is an in-process Python library and CLI over this PIP's own SQLite store. It registers ladders as data, accepts evidence with validity windows, computes a deterministic explainable level, records progression history (including demotion on expiry), serves the §13 gap-register snapshot, inventories PEP stance maps, answers readiness as pending / declared-gap / surface-exists, and emits a maturity-level claim. Assessment and register mutations are queued in a local outbox in the same transaction; nothing calls audit-core inside that transaction.

It does not decide whether an actor may act. It does not compile a level into a registry. It does not author ladder criteria, observation, or actuation.

In Scope

  • Declaring this repository's NetKingdom layer and PIP role
  • Named, versioned maturity models (ladders, levels, criteria, evidence kinds)
  • Evidence submission, validity windows, and expiry
  • Deterministic, explainable level computation and progression history
  • The estate gap register (declared contacts and unowned capabilities), including state and owner-status
  • Four conformance states and the scoring rule that blocked-clean MUST NOT rank below conforming
  • PEP stance-map inventory
  • Capability-readiness queries (pending / declared-gap / surface exists)
  • The PIP claim shape for a maturity level, consumed by access-engine
  • Emission of assessment and register mutations to audit-core under the alteration/truncation bound
  • Workplans that close the gap from this seed to the engine INTENT.md describes

Out of Scope

  • Authorization decisions — access-engine (the only PDP)
  • Approval objects — approval-engine
  • Credential materialization — secrets-engine
  • Evidence custody and integrity verification — audit-core
  • Security doctrine, ladder content, and conformance judgment — gate-house (Staff acts through this engine; it does not move here)
  • Observation in production — kings-guard; currently at zero
  • Actuation / containment — unowned Engine concept held at zero
  • Work structure (workplans, tasks, estimates) of other repositories — those repositories and the State Hub
  • Compiling a level into registry content, or gating a request path on a fetched level
  • PEP stance maps themselves — owned by the PEP-shaped consumer; this engine inventories them
  • The gap-record schema — Taxonomy (statute §17)
  • The layering constitution — gate-house / net-kingdom canon
  • Lifecycle over catalogued Tooling (OpenBao, key-cape)
  • Scorecards for teams or individuals

Authority and Publication Boundaries

Concern Authority Relationship to maturity-engine
Layers, one PDP, Staff/Engine binding, evidence bounds gate-house / net-kingdom canon, security-layer-model v0.7 Consumed as the constitution; not redefined here
Operative form of those rules net-kingdom/SECURITY-COMPANION.md v0.2 Start here; statute governs on disagreement
What this repository owns within Engine/PIP this repository's INTENT.md Declared; not yet discharged
Whether a request is permitted access-engine Maturity arrives as a claim or a versioned policy rule
Ladder content (e.g. ASM-0…ASM-6) the doctrine owner (gate-house, ops-warden, …) Registered and computed, not authored
Gap-record schema Taxonomy (statute §17) Held as records, not authored
Gap-register snapshot (until we store state) statute §13 Migrates here once a store exists
Stance-map inventory (until we store state) statute §13.1 Migrates here once a store exists
Evidence archive audit-core Operative assessment here; archive there
Work indexing State Hub Non-catalogued client, listed when used

Relevant When

  • Declaring or changing this repository's security layer or PIP role
  • Registering a maturity model or submitting evidence against one
  • Computing or explaining a level for a subject
  • Recording, querying, or reviewing a declared gap or unowned capability
  • Asking whether a catalogued capability has an engine surface
  • Inventorying PEP stance maps
  • Consuming a maturity level as an access-engine claim
  • Closing the seed-to-engine gap recorded in history/260829-demand-netkingdom-security-layer-alignment.md

Not Relevant When

  • Asking whether an actor may act — that is access-engine
  • Asking whether an approval is valid — that is approval-engine
  • Writing doctrine or inventing ladder criteria that belong to Staff
  • Assuming observation-in-production or automatic containment exists
  • Tracking work, estimates, or due dates
  • Branching on a fetched level in a request path
  • The request is raw demand that has not yet been reviewed for purpose and scope fit

Current State

  • Status: engine surface present; production deploy is not claimed
  • Layer declaration: INTENT.md frontmatter and layer.yaml declare layer: Engine / role: PIP against security-layer-model v0.7; scripts/check_layer_conformance.py checks them
  • Runtime: Python package maturity_engine over SQLite (make test is the documented command)
  • Assessment: named versioned ladders, evidence with expiry, deterministic compute, explainability, progression history
  • Gap register: statute §13 snapshot is queryable here, with state and owner-status intact; blocked-clean is not scored below conforming
  • Stance-map inventory: ops-warden published, ops-mason unpublished
  • Readiness: pending / declared-gap / surface-exists; actuation stays pending and is not owned here
  • Claim contract: docs/claim-contract.md; guardrail tests reject a registry compile and a consumer branch
  • Evidence emission: local outbox; load-bearing assessments; heartbeat for rare classes; no synchronous audit-core dependency
  • Registered ladders: asm v0.3 (owner gate-house) and pep-stance-publication v0.1 (owner ops-warden)
  • Review path: Engine.review / maturity-engine review computes and remembers; it does not judge
  • Layout conformance (ITC-REPO-LAYOUT 0.1.0-RC1): minimal; docs/, history/, and workplans/ are in use; demand/ is not claimed

InfoTechCanon Repository-Layout Alignment

Declared conformance: minimal under ITC-REPO-LAYOUT 0.1.0-RC1.

  • INTENT.md contains stable aspiration and boundaries.
  • SCOPE.md contains current evidenced responsibility and explicit gaps.
  • workplans/ contains committed work and remains authoritative for State Hub.
  • history/ contains dated, inactive reviews.

Intentional omissions:

  • docs/ holds the claim contract. demand/, research/, spec/, wiki/, and issues/ are not currently claimed.
  • Finished workplan archival, when it exists, will follow the Custodian ADR-001 convention at workplans/archived/YYMMDD-... so State Hub discovery remains deterministic.

How It Fits

  • Upstream constitution: NetKingdom security-layer-model v0.7 and SECURITY-COMPANION.md v0.2 (consumed, not authored)
  • Doctrine and conformance judgment: gate-house
  • Decision point: access-engine (consumes our claims)
  • Opposite engine: approval-engine (closed binary object)
  • Evidence archive: audit-core
  • Observation (unstaffed): kings-guard
  • Coordination/index: State Hub
  • Layout convention: InfoTechCanon repository-layout, level minimal

Getting Oriented

  • Start with: README.md, INTENT.md, SCOPE.md
  • Constitution: net-kingdom/canon/standards/security-layer-model_v0.7.md
  • Operative form: net-kingdom/SECURITY-COMPANION.md
  • Alignment review: history/260829-demand-netkingdom-security-layer-alignment.md
  • Claim contract: docs/claim-contract.md
  • Layer declaration: layer.yaml
  • Active work: workplans/
  • Tests: make test

Gap to Intent

MAT-WP-0001 closed the seed-to-engine gap: a queryable Engine/PIP exists. Remaining aspiration, not a hole in this surface:

  • gate-house actually performing live conformance review through the CLI rather than in tests;
  • ASM-0…ASM-6 assessed against a real estate with evidence fed by the systems being assessed, not fixtures;
  • access-engine consuming the claim in a live decision record;
  • draining the local outbox into audit-core (the queue is here; the drain adapter is not);
  • a production SQLite (or later catalogued) deployment.

Do not host a PDP, compile a level into a registry, score blocked-clean below conforming, or treat observation or containment as available.