Implement NK-WP-0013 playbook capability contract

docs/adr/ADR-0012-playbook-capability-contract-ownership.md

@@ -0,0 +1,112 @@
+# ADR-0012 - Playbook Capability Contract Ownership
+
+**Status:** Accepted
+**Date:** 2026-05-22
+**Deciders:** Bernd Worsch, Codex
+
+## Context
+
+ADR-0007 refined NetKingdom's orchestration role into a
+meta-orchestration layer. NetKingdom selects the services and playbooks a
+scenario needs, decides which parameters may be tuned, and holds the
+responsibility map. Railiance remains the execution-orchestration layer:
+Railiance playbooks provision and converge the actual infrastructure,
+cluster, platform services, and application layers.
+
+That split requires a stable interface. If a Railiance playbook only
+describes behavior implicitly, NetKingdom cannot safely compose it into a
+scenario, compare it with another playbook, or know which parameter
+changes are safe. The IAM Profile provides the precedent: the consumer
+that needs a stable contract defines the contract, and providers conform
+to it.
+
+## Decision
+
+NetKingdom owns the Playbook Capability Contract schema and vocabulary.
+Railiance owns playbook implementation and publishes one conformant
+declaration per playbook.
+
+The first canonical contract is
+`canon/standards/playbook-capability-contract_v0.1.md`, backed by the
+machine-readable schema in
+`canon/schemas/playbook-capability-declaration_v0.1.schema.json` and the
+validator in `tools/playbook-capability-contract/`.
+
+The contract is NetKingdom-owned with Railiance co-design:
+
+- NetKingdom defines the schema, controlled vocabulary, trust-state
+  language, parameter-sensitivity rules, and conformance criteria.
+- Railiance authors and maintains declarations beside the playbooks they
+  describe.
+- Railiance execution stays unchanged. The declaration never becomes the
+  playbook runner.
+- NetKingdom meta-orchestration consumes declarations to select,
+  parametrize, sequence, and build responsibility maps for scenarios.
+
+ADR-0007 remains unchanged: execution stays in Railiance.
+
+## Versioning
+
+The contract uses explicit document versions:
+
+- Patch/editorial changes clarify wording or examples without changing
+  declaration semantics.
+- Minor versions add optional fields, vocabulary entries, or validator
+  warnings that existing declarations can ignore.
+- Breaking versions change required fields, field meanings, allowed
+  vocabulary, parameter-sensitivity semantics, trust-state semantics, or
+  catalog consumption rules.
+
+Declarations carry `metadata.contract_version`. A catalog may accept more
+than one contract version during a migration window, but must report the
+version used for each selected playbook.
+
+## Breaking-Change Governance
+
+A breaking change requires:
+
+1. an ADR or ADR refinement explaining the change and migration path;
+2. a new versioned standard and schema;
+3. an updated validator;
+4. a coexistence window for the previous supported version where
+   practical;
+5. notice to known declaration publishers, especially Railiance repos.
+
+Breaking changes include:
+
+- removing or renaming required fields;
+- changing capability ids or resource-kind vocabulary;
+- changing trust-state meanings;
+- changing which parameter sensitivities are tenant-tunable;
+- changing catalog selection or override semantics;
+- moving execution responsibility out of Railiance into NetKingdom.
+
+## Consequences
+
+- Playbook declaration files live beside Railiance playbooks, normally at
+  `capabilities/playbooks/*.yaml`.
+- NetKingdom can validate declarations before consuming them.
+- A playbook interface change becomes visible and versioned instead of an
+  implicit break.
+- The responsibility map can be assembled from declarations, while
+  Railiance keeps execution ownership.
+
+## Alternatives Considered
+
+### Put The Contract In Railiance
+
+Railiance owns execution, so this is tempting. But NetKingdom is the
+consumer that needs stable scenario composition and responsibility-map
+inputs. Keeping the contract in NetKingdom mirrors the IAM Profile
+pattern and keeps scenario semantics close to the responsibility map.
+
+### Make Declarations Free-Form Documentation
+
+Free-form docs are readable but not safely composable. NetKingdom needs a
+validator and controlled vocabulary so a playbook change cannot silently
+break a scenario.
+
+### Build A Dedicated Execution-Orchestration Repo Now
+
+ADR-0007 explicitly defers that. The contract is useful now and does not
+require a new runner or repo boundary.

docs/platform-identity-security-architecture.md

@@ -326,6 +326,13 @@ ADR-0007 records the current decision: keep orchestration in Railiance
 playbooks for now, with NetKingdom defining the trust-state model,
 readiness checks, OpenBao boundaries, and security semantics.
 
+The playbook interface for that split is the NetKingdom Playbook
+Capability Contract (`canon/standards/playbook-capability-contract_v0.1.md`).
+Railiance playbooks publish declarations beside the playbooks; NetKingdom
+validates and consumes those declarations to select capabilities,
+parametrize allowed inputs, and assemble responsibility/trust-state
+views without taking over execution.
+
 ## flex-auth And Topaz Implications
 
 flex-auth work must preserve the recursive boundary between platform

docs/responsibility-map.md

@@ -40,6 +40,10 @@ NetKingdom's role over orchestrated repos is **meta-orchestration**
 services/playbooks a scenario needs, (2) **parametrizes** them where
 tuning is warranted, and (3) holds **responsibility** for the resources
 and the security boundaries — leaving execution mechanics to the repo.
+The Playbook Capability Contract
+(`canon/standards/playbook-capability-contract_v0.1.md`) is the declared
+interface NetKingdom uses for playbook selection and safe
+parametrization.
 
 ---