tegwick
8eaf0c77b0
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
116 lines
3.9 KiB
Markdown
116 lines
3.9 KiB
Markdown
---
|
|
id: RBT-WP-0002
|
|
type: workplan
|
|
title: "Runbook pack specification and validator"
|
|
domain: infotech
|
|
repo: runbook-tutorials
|
|
status: finished
|
|
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: done
|
|
priority: high
|
|
```
|
|
|
|
`docs/pack-spec-v0.2.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).
|
|
Done 2026-09-29: Bernd answered the five questions; v0.2 adopted as `docs/pack-spec-v0.2.md` (with operating modes, overrides, deviations); v0.1 stays as shipped. Supersedes the earlier plan to freeze v0.1 alone.
|
|
|
|
## Write the v0.2 schema and validator
|
|
|
|
```task
|
|
id: RBT-WP-0002-T05
|
|
status: done
|
|
priority: high
|
|
```
|
|
|
|
Done 2026-09-29: `schema/runbook-pack-v0.2.schema.json` and `rtut/v2.py` (acyclic requires, references resolve, nesting depth 3, irreversible steps need a confirm phrase, no secret datapoints). v0.1 packs still load. 61 tests including one negative test per rule.
|
|
|
|
## Port the in-repo and NetKingdom packs
|
|
|
|
```task
|
|
id: RBT-WP-0002-T06
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "dae5a6fe-9f1f-553a-8b73-f47ab6d91b59"
|
|
```
|
|
2026-09-29 (CUST-WP-0074-T05 backfill): this task was `wait` with no external dependency or human gate stated, which Task Wait Qualifiers v0.1 treats as unqualified; set to `todo`. Re-add `wait` with a qualifier if a real gate exists.
|
|
|
|
|
|
Done 2026-09-29 (RBT-WP-0009-T06): the three NetKingdom packs are v0.2 (the console stays a legacy pack); the lighthouse v0.2 showcase and the test packs cover
|
|
alternatives, gates and actors.
|
|
|
|
## Showcase pack as acceptance test
|
|
|
|
```task
|
|
id: RBT-WP-0002-T07
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "6740457f-81a7-5761-a768-b9b0faee7552"
|
|
```
|
|
|
|
`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. `runbooks/showcase-lighthouse-v2/pack.yaml` expresses the same story in the proposed v0.2 model
|
|
(stages, parallel steps, alternatives, gates, actors, datapoints, artefacts, irreversible
|
|
confirmation). It validates against the v0.2 schema and semantic checks and can be run by the v0.2 engine (`rtut/run2.py`); a UI for it is RBT-WP-0004.
|
|
|
|
## 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.
|