tegwick
4cde4e489a
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
215 lines
9 KiB
Markdown
215 lines
9 KiB
Markdown
# 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.
|