--- 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.