189 lines
6.7 KiB
Markdown
189 lines
6.7 KiB
Markdown
---
|
|
id: KG-WP-0002
|
|
type: workplan
|
|
title: "Canonical immune contracts and first posture pilot"
|
|
domain: infotech
|
|
repo: kings-guard
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: netkingdom
|
|
created: "2026-07-23"
|
|
updated: "2026-07-23"
|
|
quality_dor: DoR-Ok
|
|
quality_dor_at: "2026-07-23"
|
|
quality_dor_by: "codex"
|
|
state_hub_workstream_id: "5c5c5a26-dfca-4d42-86a7-b87877677207"
|
|
---
|
|
|
|
# Canonical immune contracts and first posture pilot
|
|
|
|
Establish `kings-guard` as the adaptive security layer that sits beside the
|
|
existing NetKingdom security lanes instead of competing with them. The first
|
|
strand should produce stable contracts and one narrow posture pilot before any
|
|
broader implementation or automation claims.
|
|
|
|
This workplan deliberately keeps authority boundaries clear:
|
|
|
|
- `key-cape` remains identity and attestation input.
|
|
- `flex-auth` remains authorization policy and final allow/deny owner.
|
|
- `railiance-platform` and `secrets-engine` remain secret-custody and delivery
|
|
owners.
|
|
- `ops-warden` remains the operational SSH certificate lane.
|
|
- `kings-guard` evaluates health/posture, emits signals, and requests bounded
|
|
response.
|
|
|
|
## Ralph Execution
|
|
|
|
Recommended invocation in Claude Code:
|
|
|
|
```text
|
|
/ralph-workplan workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md --max-iterations 12
|
|
```
|
|
|
|
Expected done condition:
|
|
|
|
- all tasks below are `done`;
|
|
- frontmatter status is updated to `finished`;
|
|
- State Hub task/workplan statuses and progress note are synced.
|
|
|
|
## Dependency Order
|
|
|
|
```text
|
|
T01 canonical contracts
|
|
-> T02 adjacent-system boundary
|
|
-> T03 minimal posture loop scaffold
|
|
-> T04 first pilot-lane specification
|
|
```
|
|
|
|
## Task: Define canonical immune contracts
|
|
|
|
```task
|
|
id: KG-WP-0002-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "9982a3b4-1e65-493a-9b61-322f23d4fd2d"
|
|
```
|
|
|
|
Write the first repo-owned canonical contract for the core vocabulary:
|
|
`security_genome`, `security_phenotype`, `immune_observation`,
|
|
`immune_signal`, `effector_request`, `tolerance`, `inflammation`, and
|
|
`immune_memory`.
|
|
|
|
Done when:
|
|
|
|
- each term has a concise, non-overlapping definition;
|
|
- producer/consumer expectations are named for each contract;
|
|
- the contracts are usable without requiring one particular product stack.
|
|
|
|
**Done 2026-07-23:** Added [ImmuneContracts.md](/home/worsch/kings-guard/specs/ImmuneContracts.md),
|
|
which defines the v0.1 contract layer for `security_genome`,
|
|
`immune_observation`, `security_phenotype`, `posture_assessment`,
|
|
`immune_signal`, `effector_request`, `tolerance`, `inflammation`, and
|
|
`immune_memory_entry`. The doc names producer/consumer expectations for every
|
|
contract and keeps the field set intentionally implementation-neutral. The
|
|
matching reference dataclasses live in `src/kings_guard/contracts.py`.
|
|
|
|
## Task: Write adjacent-system boundary contract
|
|
|
|
```task
|
|
id: KG-WP-0002-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "0c44035e-b1b8-4f5d-8a6c-e6514b4bc897"
|
|
```
|
|
|
|
Author a boundary document that shows how `kings-guard` consumes evidence from
|
|
`key-cape`, `flex-auth`, `secrets-engine`, `ops-warden`, and Railiance runtime
|
|
layers without taking over their responsibilities.
|
|
|
|
Done when:
|
|
|
|
- each adjacent system's primary authority is stated explicitly;
|
|
- `kings-guard` inputs, outputs, and non-goals are named per system;
|
|
- tenant-isolation and non-secret evidence rules are captured.
|
|
|
|
**Done 2026-07-23:** Added
|
|
[AdjacentSystemBoundary.md](/home/worsch/kings-guard/docs/AdjacentSystemBoundary.md),
|
|
which records the primary authority, evidence inputs, bounded outputs, and
|
|
non-goals for `key-cape`, `flex-auth`, `secrets-engine`,
|
|
`railiance-platform` / OpenBao, `ops-warden`, Railiance runtime layers,
|
|
`state-hub`, and the governed domain-assistant pattern represented by
|
|
`qonto-assistant`. The document also names the cross-system rules for
|
|
tenant isolation and metadata-only evidence handling.
|
|
|
|
## Task: Scaffold a minimal posture loop
|
|
|
|
```task
|
|
id: KG-WP-0002-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "c88a7da6-a9ff-4bd9-ba47-7c199321666b"
|
|
```
|
|
|
|
Create the initial repository structure for a minimal posture engine or schema
|
|
package that can ingest normalized observations, compare them against declared
|
|
intent, and emit typed posture/signal results.
|
|
|
|
Done when:
|
|
|
|
- the repo has a clear implementation layout rather than only prose;
|
|
- one sample input/output path exists end-to-end for observation -> posture ->
|
|
signal;
|
|
- tests or fixture-driven validation prove the contract shape is stable.
|
|
|
|
**Done 2026-07-23:** Added the first executable scaffold:
|
|
|
|
- `pyproject.toml`, `Makefile`, `README.md`, `AGENTS.md`, and `.gitignore`
|
|
updates;
|
|
- `src/kings_guard/` with contract dataclasses, a qonto audit-event adapter,
|
|
fixture loader, posture evaluator, and CLI demo runner;
|
|
- `tests/` with fixture-driven tests for normalization, JSON-safe contract
|
|
serialization, posture assessment, and bounded signal emission.
|
|
|
|
The sample end-to-end path is: qonto audit event fixture ->
|
|
`observation_from_audit_event()` -> `PostureEvaluator.evaluate()` ->
|
|
advisory `posture_hint` signal. Verified in this shell with:
|
|
|
|
- `git diff --check`
|
|
- `python3 -m pytest -q` -> 5 passed
|
|
- `python3 -m compileall src tests`
|
|
- `PYTHONPATH=src python3 -m kings_guard.main --pilot qonto-assistant`
|
|
|
|
`ruff` is declared in the repo's dev dependencies and lint command, but the
|
|
current shell lacked both `pip` and the `ruff` module, so source verification
|
|
in this session used tests + compile + demo execution rather than the lint
|
|
step.
|
|
|
|
## Task: Choose and specify the first pilot lane
|
|
|
|
```task
|
|
id: KG-WP-0002-T04
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "77e1dc69-9902-4381-8028-ce1cfac7e9d5"
|
|
```
|
|
|
|
Pick one narrow pilot integration lane and specify it precisely. Preferred
|
|
pilot order:
|
|
|
|
1. `ops-warden` sign-request posture hinting
|
|
2. `secrets-engine` exec-delivery posture hinting
|
|
3. Railiance workload reconstitution signal generation
|
|
|
|
Done when:
|
|
|
|
- the chosen lane has a concrete request/response flow;
|
|
- the pilot can run without granting `kings-guard` secret, identity, or final
|
|
authorization authority;
|
|
- bounded-response and rollback expectations are documented.
|
|
|
|
**Done 2026-07-23:** Selected `qonto-assistant` as the first pilot lane and
|
|
documented it in
|
|
[QontoAssistantPosturePilot.md](/home/worsch/kings-guard/docs/pilots/QontoAssistantPosturePilot.md).
|
|
This deliberately overrides the original preference order because
|
|
`qonto-assistant` already exposes all three things the first pilot needs: a
|
|
real genome record, a real audit stream, and a real local fast loop. The pilot
|
|
flow is concrete and bounded: `kings-guard` consumes normalized observation
|
|
evidence, emits an advisory-only posture hint, and may request metadata-only
|
|
incident evidence in `state-hub`; it does not gain final authorization,
|
|
identity, or secret-custody authority.
|