generated from coulomb/repo-seed
Draft NK-WP-0013: Playbook Capability Contract
The orchestration-layer analog of the IAM Profile, realizing the playbook-contract dependency named in ADR-0007's meta-orchestration refinement. NetKingdom owns the contract schema (consumer-defines-contract, IAM Profile precedent); Railiance authors playbooks and publishes conformant declarations; execution stays in Railiance (ADR-0007 unchanged). Six tasks: ownership ADR + versioning; capability vocabulary (aligned to the C0-C6 ladder + responsibility-map resource kinds); parameter format (defaults, constraints, security-sensitivity); responsibility/trust-state claims; catalog + consumption model + conformance validator; reference adoption with one Railiance playbook. Status proposed; not yet registered. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
191
workplans/NK-WP-0013-playbook-capability-contract.md
Normal file
191
workplans/NK-WP-0013-playbook-capability-contract.md
Normal file
@@ -0,0 +1,191 @@
|
||||
---
|
||||
id: NK-WP-0013
|
||||
type: workplan
|
||||
title: "Playbook Capability Contract"
|
||||
domain: netkingdom
|
||||
repo: net-kingdom
|
||||
status: proposed
|
||||
owner: worsch
|
||||
topic_slug: netkingdom
|
||||
planning_priority: high
|
||||
planning_order: 13
|
||||
created: "2026-05-21"
|
||||
updated: "2026-05-21"
|
||||
depends_on:
|
||||
- NK-WP-0006
|
||||
state_hub_workstream_id: TBD
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
```task
|
||||
id: NK-WP-0013-T1
|
||||
status: todo
|
||||
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**.
|
||||
|
||||
```task
|
||||
id: NK-WP-0013-T2
|
||||
status: todo
|
||||
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.
|
||||
|
||||
```task
|
||||
id: NK-WP-0013-T3
|
||||
status: todo
|
||||
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.
|
||||
|
||||
```task
|
||||
id: NK-WP-0013-T4
|
||||
status: todo
|
||||
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.
|
||||
|
||||
```task
|
||||
id: NK-WP-0013-T5
|
||||
status: todo
|
||||
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).
|
||||
|
||||
```task
|
||||
id: NK-WP-0013-T6
|
||||
status: todo
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Contract format and home: a net-kingdom canon standard plus a
|
||||
machine-readable schema (e.g. JSON/YAML schema) the catalog validates
|
||||
against?
|
||||
- Catalog mechanism: a file convention in each playbook repo that NetKingdom
|
||||
aggregates, or a published registry?
|
||||
- How parameter sensitivity interacts with tenant boundaries (which
|
||||
parameters a tenant-scoped scenario may set vs. platform-only).
|
||||
- Whether the conformance validator is a standalone net-kingdom tool or a
|
||||
shared library, mirroring the same open question in NK-WP-0012.
|
||||
Reference in New Issue
Block a user