kings-guard/workplans/KG-WP-0002-canonical-immune-contracts-and-posture-pilot.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	quality_dor	quality_dor_at	quality_dor_by	state_hub_workstream_id
KG-WP-0002	workplan	Canonical immune contracts and first posture pilot	infotech	kings-guard	finished	codex	netkingdom	2026-07-23	2026-07-23	DoR-Ok	2026-07-23	codex	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:

/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

T01 canonical contracts
  -> T02 adjacent-system boundary
    -> T03 minimal posture loop scaffold
      -> T04 first pilot-lane specification

Task: Define canonical immune contracts

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

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

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

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