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

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