tegwick
b47c948a7e
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: sonnet Assistant-Process: 295952@bnt-lap001 Assistant-Session: e93f64ad-516c-46eb-9666-aad8d300c477
117 lines
3.4 KiB
Markdown
117 lines
3.4 KiB
Markdown
---
|
|
id: RBT-WP-0002
|
|
type: workplan
|
|
title: "Runbook pack specification and validator"
|
|
domain: infotech
|
|
repo: runbook-tutorials
|
|
status: active
|
|
flavor: implementation
|
|
owner: claude
|
|
topic_slug: stack
|
|
created: "2026-09-29"
|
|
updated: "2026-09-29"
|
|
state_hub_workstream_id: "f72323f4-4ef8-5bcd-9662-09df1c20290e"
|
|
---
|
|
|
|
## Goal
|
|
|
|
Define what a runbook pack is, so packs can live in the repos that own them and
|
|
the engine can load, validate and present them. The pack spec is the contract
|
|
between this repo and every pack owner.
|
|
|
|
## Publish the pack specification
|
|
|
|
```task
|
|
id: RBT-WP-0002-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "f9e466d2-9fd1-502e-b2b8-e737068c12d2"
|
|
```
|
|
|
|
`docs/pack-spec.md` v0.1: manifest fields, parameters (never secret), steps with
|
|
mandatory verification, rollback for state-changing steps, exercise status per the
|
|
attended-procedure standard, and the legacy-command engine.
|
|
|
|
## Encode the specification as a JSON Schema
|
|
|
|
```task
|
|
id: RBT-WP-0002-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "84c0496f-57c1-547a-b831-f4a20b75c0e9"
|
|
```
|
|
|
|
`schema/runbook-pack.schema.json` with conditional requirements per engine.
|
|
|
|
## Implement discovery, validation and rendering
|
|
|
|
```task
|
|
id: RBT-WP-0002-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "2760f95a-5016-5a2e-b25c-b8b67847061c"
|
|
```
|
|
|
|
`rtut/pack.py` and the CLI (`python -m rtut list|validate|show|render`), with
|
|
semantic checks the schema cannot express (placeholders, duplicates, rollback,
|
|
secret markers, parameter defaults) and 16 tests. Parameter rendering rejects
|
|
unsafe characters.
|
|
|
|
## Review the v0.2 proposal and decide
|
|
|
|
```task
|
|
id: RBT-WP-0002-T04
|
|
status: progress
|
|
priority: high
|
|
```
|
|
|
|
`docs/pack-spec-v0.2-proposal.md` (stages and hierarchy, dependency graph with a
|
|
recommended serialization, datapoints with `nil/set/err/ok`, QA gates tied to stages
|
|
and goals, actors and roles, artefacts, reversibility-based confirmation, framing).
|
|
Review with Bernd, resolve the five open questions, and decide: freeze v0.1 as
|
|
shipped and adopt v0.2. Supersedes the earlier plan to freeze v0.1 alone.
|
|
|
|
## Write the v0.2 schema and validator
|
|
|
|
```task
|
|
id: RBT-WP-0002-T05
|
|
status: wait
|
|
priority: high
|
|
```
|
|
|
|
After T04: `schema/runbook-pack-v0.2.schema.json`, semantic checks (acyclic
|
|
requires, gate and datapoint references resolve, one stage per gate, no secret
|
|
datapoints), v0.1 packs still load, tests.
|
|
|
|
## Port the in-repo and NetKingdom packs
|
|
|
|
```task
|
|
id: RBT-WP-0002-T06
|
|
status: wait
|
|
priority: medium
|
|
state_hub_task_id: "dae5a6fe-9f1f-553a-8b73-f47ab6d91b59"
|
|
```
|
|
|
|
Port the four validating packs to v0.2 where it helps, and add v0.2 test packs with
|
|
alternatives, gates and actors.
|
|
|
|
## Showcase pack as acceptance test
|
|
|
|
```task
|
|
id: RBT-WP-0002-T07
|
|
status: progress
|
|
priority: medium
|
|
```
|
|
|
|
`runbooks/showcase-lighthouse/` is a harmless interactive-fiction runbook (poem, story,
|
|
scratch logbook under /tmp/rtut-*). `pack.yaml` (v0.1) runs today and is the test bed for
|
|
UI refinement. `pack.v0.2.draft.yaml` expresses the same story in the proposed v0.2 model
|
|
(stages, parallel steps, alternatives, gates, actors, datapoints, artefacts, irreversible
|
|
confirmation). The draft is checked for internal consistency by tests. When v0.2 is adopted
|
|
the validator must accept it unchanged, or the proposal changes.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Every pack in this repo and in `net-kingdom` validates.
|
|
- Invalid packs fail with a clear error; tests cover each rule.
|
|
- The spec names how the pre-existing console stays working.
|