net-kingdom/workplans/NK-WP-0013-playbook-capability-contract.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id
NK-WP-0013	workplan	Playbook Capability Contract	netkingdom	net-kingdom	finished	worsch	netkingdom	high	13	2026-05-21	2026-05-22	NK-WP-0006	32a54d8e-8633-42a6-8ec1-104842c581c1

NK-WP-0013 — Playbook Capability Contract

The orchestration-layer analog of the IAM Profile. ADR-0007's meta-orchestration refinement named this as a prerequisite: for NetKingdom to select and parametrize playbooks reliably, each Railiance playbook must publish a declared interface — the capability it provisions, its parameters (with defaults and constraints), and the responsibility it claims. Without it, meta-orchestration composes against implicit behavior and breaks silently when a playbook changes. This workplan defines that contract.

Goal

Define the Playbook Capability Contract — the schema and vocabulary by which a playbook declares:

1. what capability it provisions (controlled vocabulary, aligned to the capability ladder and the responsibility-map resource kinds),
2. its parameters — name, type, default, constraints, required/optional, and which are security-sensitive, and
3. the responsibility it claims — which element owns which resources, and which trust state(s) / readiness checks it satisfies or requires.

…plus the catalog/consumption model NetKingdom meta-orchestration uses to select, parametrize, and build a responsibility map for a scenario, and a conformance validator for declarations.

Ownership (the boundary this realizes)

By symmetry with the IAM Profile, the consumer that needs a stable interface defines the contract; the provider conforms:

	Contract owner	Publishes conformant declarations	Consumer
Identity	NetKingdom (IAM Profile)	key-cape / Keycloak	apps, flex-auth
Orchestration	NetKingdom (this contract)	Railiance playbooks	NetKingdom meta-orchestration

NetKingdom owns the contract schema; Railiance owns the playbooks and publishes one declaration per playbook; execution stays in Railiance (ADR-0007 unchanged). The contract makes a playbook change a versioned event rather than a silent break.

Scope

In scope:

• ownership & boundary decision (ADR) and contract versioning governance
• the capability vocabulary a declaration draws from
• the parameter declaration format (defaults, constraints, sensitivity)
• the responsibility-claim and trust-state/readiness format
• the catalog and the meta-orchestration consumption model
• a conformance validator for declarations
• coordinated adoption proof with one reference Railiance playbook

Out of scope:

• authoring the playbooks themselves (Railiance owns execution)
• writing declarations for every existing playbook (Railiance work; this workplan proves the contract with one reference declaration)
• a dedicated execution-orchestration repo (deferred per ADR-0007)

Tasks

id: NK-WP-0013-T1
state_hub_task_id: d40f8b29-e983-4d52-bc1f-5f1c51709e7d
status: done
priority: high

Ownership & boundary decision (ADR-0012). Record that NetKingdom owns the Playbook Capability Contract schema (consumer-defines-contract, IAM Profile precedent), Railiance authors playbooks and publishes conformant declarations, and execution stays in Railiance (ADR-0007). Decide whether the contract is NetKingdom-owned outright or NetKingdom-owned with Railiance co-design. Define contract versioning and breaking-change governance.

id: NK-WP-0013-T2
state_hub_task_id: ece4b5b1-e1c2-449d-b0f4-83b7010bc838
status: done
priority: high

Capability vocabulary. Define the controlled vocabulary of capabilities a playbook can declare it provisions, aligned to the capability ladder (C0–C6) and the responsibility-map resource kinds (identities, roles/scopes/policies, secrets/credentials, infrastructure resources). This is what "capability" means in a declaration, so two playbooks providing the same capability are comparable.

id: NK-WP-0013-T3
state_hub_task_id: c956f4a8-b9fa-44ab-8174-31999b98e3b1
status: done
priority: high

Parameter declaration format. Define how a playbook declares its parameters: name, type, default, constraints (allowed values / ranges), required vs optional, and a security-sensitivity marker so NetKingdom knows which parameters it may tune versus which are security-critical and constrained. This is what makes "parametrize where adequate" safe rather than guesswork.

id: NK-WP-0013-T4
state_hub_task_id: e7de05a6-528a-4213-b6db-2c2e90353996
status: done
priority: high

Responsibility-claim & trust-state format. Define how a declaration states which element owns which resources (feeding the responsibility map) and which trust state(s) / readiness checks (ADR-0007 model) it satisfies or requires. This lets NetKingdom assemble a coherent responsibility map and sequence for a scenario from the declarations.

id: NK-WP-0013-T5
state_hub_task_id: 05a2ff7d-86c4-4de9-9ea8-39a9ad5352a8
status: done
priority: high

Catalog, consumption model, and conformance validator. Define how declarations are published and discovered (the catalog), how meta-orchestration consumes them to select, parametrize, and build a responsibility map for a scenario, and a conformance validator that checks a declaration against the contract (the orchestration-layer analog of the IAM Profile conformance check, NK-WP-0012-T5).

id: NK-WP-0013-T6
state_hub_task_id: 769ed490-c091-41c1-b2e2-e8e378470b6b
status: done
priority: medium

Reference adoption with Railiance. Coordinate with Railiance to have one reference playbook publish a conformant declaration end-to-end, and demonstrate NetKingdom selecting + parametrizing it from the declaration alone. Proves the contract is sufficient and is the template for adopting the rest. Cross-repo coordination item for the Railiance domain.

Acceptance Criteria

• An ADR records contract ownership, the Railiance-publishes/NetKingdom- consumes split, and ADR-0007 is confirmed unchanged.
• The contract specifies capability vocabulary, parameter format (defaults, constraints, sensitivity), and responsibility/trust-state claims.
• A catalog/consumption model and a declaration conformance validator exist.
• At least one Railiance playbook publishes a conformant declaration, and NetKingdom composes and parametrizes it from that declaration alone.
• Contract versioning and breaking-change governance is documented.

Completion Notes

• ADR: docs/adr/ADR-0012-playbook-capability-contract-ownership.md
• Canonical contract: canon/standards/playbook-capability-contract_v0.1.md
• Machine-readable schema: canon/schemas/playbook-capability-declaration_v0.1.schema.json
• Validator and composition demo: tools/playbook-capability-contract/playbook_contract_validator.py
• Reference Railiance declaration: ../railiance-infra/capabilities/playbooks/railiance-infra.bootstrap-host.yaml
• Sample scenario: examples/playbook-capability-contract/scenario-s1-host-bootstrap.yaml
• Fixture tests cover valid declarations, controlled vocabulary failures, forbidden tenant overrides, missing required parameters, and successful selection/parameter composition.

Dependencies & Sequencing

• Realizes the playbook-contract dependency from ADR-0007's meta-orchestration refinement; does not change ADR-0007.
• Depends on NK-WP-0006 for the trust-state model and the responsibility-map resource kinds the declarations reference.
• Coordinates with the Railiance domain — NetKingdom defines the contract; Railiance publishes declarations (T6) and continues to own execution.
• Parallels NK-WP-0012: same consumer-defines-contract pattern, same conformance-check shape, applied to orchestration instead of identity.

Resolved Questions

• Contract format and home: NetKingdom canon standard plus a machine-readable JSON schema and standalone validator.
• Catalog mechanism: v0.1 uses file convention capabilities/playbooks/*.yaml; a registry can be layered on later.
• Parameter sensitivity: tenant scenarios cannot override platform_only, forbidden, playbook_default, security_sensitive, or secret_reference parameters.
• Validator form: standalone NetKingdom tool for v0.1, mirroring NK-WP-0012's executable-contract pattern.