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: 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

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

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
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. pack.v0.2.yaml expresses the same story in the proposed v0.2 model (stages, parallel steps, alternatives, gates, actors, datapoints, artefacts, irreversible confirmation). It now validates against the v0.2 schema and semantic checks. It cannot be run until RBT-WP-0007 lands.

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.