runbook-tutorials/workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	state_hub_workstream_id
RBT-WP-0002	workplan	Runbook pack specification and validator	infotech	runbook-tutorials	active	implementation	claude	stack	2026-09-29	2026-09-29	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

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

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

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

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

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

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

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.