# maturity-engine — Agent Instructions

## Repo Identity

**Purpose:** Compute, deterministically, how far a subject has progressed
against declared criteria and submitted evidence, and remember that
progression. Gap register and capability readiness live here.

**Layer:** Engine (PIP). NetKingdom Security Layer Model v0.7. Never render
or cache an authorization decision. Never compile a level into registry
content. Never let a consumer branch on a fetched level — emit a claim.

**Domain:** infotech
**Repo slug:** maturity-engine
**Workplan prefix:** `MAT-WP-`

Machine-readable declaration: `layer.yaml`, checked by
`scripts/check_layer_conformance.py`. Frontmatter in `INTENT.md` must agree.

---

## Stack and commands

Python ≥ 3.12. Persistence is this PIP's own SQLite store, not OpenBao.

```bash
python3 -m pip install -e ".[dev]"
make test
make check-layer
make lint
PYTHONPATH=src python3 -m maturity_engine bootstrap --at 2026-08-29T12:00:00Z
```

Default database: `data/maturity-engine.sqlite` (gitignored) or
`MATURITY_ENGINE_DB`.

## Module boundaries

| Module | Owns |
| --- | --- |
| `models.py` | ladders, levels, criteria, evidence, assessments, gaps |
| `compute.py` | deterministic level computation |
| `store.py` | SQLite + local outbox |
| `scoring.py` | four conformance states; blocked-clean not below conforming |
| `claims.py` | PIP claim shape and guardrail rejections |
| `seed.py` | §13 snapshot, §13.1 inventory, first two ladders as data |
| `engine.py` | facade; no decide/authorize/may |
| `cli.py` | inspect and compute; does not decide |

Ladder *content* is registered data. ASM-0…ASM-6 is `gate-house`'s.
PEP-stance publication is `ops-warden`'s.

## State Hub

API: `http://127.0.0.1:8000`. Log progress at session close. Update task
status when closing a workplan task (`todo` / `progress` / `done`).