emergent-security/README.md

# emergent-security

Security guidance, delegation envelopes, and source-backed situational knowledge
for coding agents in the NetKingdom ecosystem. Root stays human-controlled.

## Agent knowledge

Start with [the orientation card](knowledge/cards/start.md) and the
[NetKingdom integration map](docs/netkingdom-integration-map.md). Install and use:

```bash
pip install -e '.[test]'
emergent-knowledge show start --audience codex
emergent-knowledge show access --audience claude --json
emergent-knowledge --repositories /path/to/checkouts check
```

The package serves reviewed estate-general summaries with source versions and
freshness receipts. It supports Codex, Claude, Grok, and generic adapters, offline
bundles, and changed/withdrawn-source withholding. It never retrieves credentials,
private tenant content, or operational grants. Source checks verify documented
bytes, not live health. See [loading and maintenance](docs/knowledge-maintenance.md)
and [operational seams](docs/operational-contracts.md).

Release status is **pilot**. Provider proof and owner adoption are tracked in
[EMERGENT-WP-0002](workplans/EMERGENT-WP-0002-agent-security-knowledge-and-netkingdom-integration.md).
Knowledge loading is separate from enforcement, identity isolation, and fleet
rollout. The [integration decision](docs/decisions/EMERGENT-DEC-2026-001-integration-profile.md)
keeps the reference model distinct from the estate's sole PDP, access-engine.

## Default envelope reference

The default delegation envelope of the Emergent Security canon v0.8 (A6) as policy data, the tenant envelopes (B10, B11) as examples, and a small reference decision function (A3) that the fixtures run against.

```
envelopes/
  scales.yaml                     ordinal risk scales shared by all envelopes
  default-envelope.yaml           A6: what an L0 agent decides alone in a HOT build estate
  examples/
    platform-tenant-acme.yaml     B10: platform-owned outer bound for one tenant
    tenant-governance-acme.yaml   B11: tenant-owned narrowing, self_governed mode
src/emergent_security/            one module per concern (see package docstring)
tests/fixtures/
  decisions/*.yaml                request → expected decision, data only
  tenants/governance-validation.yaml
```

## Run

```bash
pip install -e '.[test]'
pytest
```

## Semantics in one screen

- **Modes:** `autonomous`, `autonomous_with_obligations`, `escalate`, `deny`, `root_authorization_required`.
- **Variants** refine a row by request attributes; first match wins and may replace mode, rules, obligations and evidence.
- **`deny` and `root_authorization_required` are constitutional:** they apply in every scope, including tenants and COLD zones, and no delegation overrides them.
- **Every other row** applies only where `applies_when` matches (L0, HOT, build, no tenant).
- **`escalate` means "not delegated here".** A registry delegation can grant it (most specific scope wins, ties by id).
- **Inside a tenant** the default envelope never grants anything. Grants come from the platform tenant envelope or the registry, always bounded by the effective envelope: platform ∩ tenant governance.
- **Risk fails safe.** A dimension the envelope declares but the request leaves unclassified, or classifies with an unknown value, counts as exceeding.

## Changing the policy, test first

1. Add or change a case in `tests/fixtures/decisions/*.yaml` describing the request and the expected decision. Run `pytest`; it must fail.
2. Change `envelopes/default-envelope.yaml` (or an envelope example) until it passes. Touch code only if the canon's semantics changed.
3. Adding an A6 row also means updating `A6_CLASSES` in `tests/test_default_envelope.py` and the canon table.

The suite also enforces determinism, idempotency (inputs never mutated, registry order irrelevant), that `auto` mode equals no tenant configuration, and the G7 tenant invariants.

## Human decisions and guided procedures

[Decision/runbook integration](docs/decision-runbook-integration.md) links
`informed-decision` presentation and human binding to owner-held procedures
using `runbook-tutorials`. Retrieve the `decisions` and `runbooks` cards.
The native `runbooks/security-orientation/pack.yaml` prepares an evidence
handoff; the unsigned adoption memo in `docs/decisions/` is ready for review.
Neither submits a human answer or executes an infrastructure change.