generated from coulomb/repo-seed
Archive closed workplans to workplans/archived/ (ADR-001)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,214 +0,0 @@
|
||||
---
|
||||
id: NK-WP-0013
|
||||
type: workplan
|
||||
title: "Playbook Capability Contract"
|
||||
domain: infotech
|
||||
repo: net-kingdom
|
||||
status: finished
|
||||
owner: worsch
|
||||
topic_slug: netkingdom
|
||||
planning_priority: high
|
||||
planning_order: 13
|
||||
created: "2026-05-21"
|
||||
updated: "2026-05-22"
|
||||
depends_on:
|
||||
- NK-WP-0006
|
||||
state_hub_workstream_id: 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
|
||||
|
||||
```task
|
||||
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**.
|
||||
|
||||
```task
|
||||
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.
|
||||
|
||||
```task
|
||||
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.
|
||||
|
||||
```task
|
||||
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.
|
||||
|
||||
```task
|
||||
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).
|
||||
|
||||
```task
|
||||
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.
|
||||
Reference in New Issue
Block a user