runbook-tutorials/docs/pack-spec-v0.2-proposal.md

Runbook pack specification v0.2 - proposal

Status: proposed (review with Bernd; RBT-WP-0002-T04). Derived from docs/ux-review-2026-09-29.md. v0.1 stays valid; v0.2 is a superset.

Principle

The spec describes what the procedure is: structure, data, actors, gates and order. It carries no presentation. Rendering (layout, theme, dark mode, the questionnaire and the dimension view) is the renderer's job and must follow from the semantics alone. If a UI feature needs a new spec field, that field has to be justified as meaning, not appearance.

The model

pack
 |- framing            what to keep in mind (shown first)
 |- actors             who does or approves what, with privileges
 |- datapoints         the non-secret facts collected and applied  -> state nil/set/err/ok
 |- stages             hierarchy of the procedure
 |   |- steps          the work                                 -> state todo/running/done/failed
 |   |- gates          QA checks tied to the stage and to goals -> state open/passed/failed/waived
 |- artefacts          what a run produces and where it lives (non-secret references)

Two states, two things

Thing	States	Meaning
Datapoint (parameter, role assignment, artefact location, custody reference)	nil no value, set value given, err invalid or rejected, ok confirmed in the real system	Is the data known and right?
Step	todo, running, done, failed (skipped for read-only)	Has it been applied?
Gate	open, passed, failed, waived	Is the quality condition met?

A v0.1 parameter is a datapoint that has a value type and is asked as a question. Steps uses: datapoints; steps may produces: datapoints (for example an artefact location).

Hierarchy and order

• stages nest to at most three levels. A stage has title, goal, steps, and optional child stages.
• Every step and stage may declare requires: (ids of steps, stages, gates, or datapoints in state ok). This forms a dependency graph, so alternatives and parallel work are expressible. one_of: groups declare alternatives: any one satisfies the group.
• Canonical serialization. The order in which the pack lists things is the recommended order. The engine computes: ready = every requirement met; recommended next = the first ready item in canonical order. Operators may take any other ready item. A pack that lists no requires behaves as a linear sequence, which is exactly a v0.1 pack.

Gates

A gate is a QA condition, not a step.

gates:
  - id: custody-approved
    title: Custody strategy approved
    stage: custody            # exit gate of this stage
    goal: platform-root-custody   # quality objective; canon standard id where one exists
    blocking: true            # blocks dependents and the stage exit
    checks:                   # same check shape as step verify
      - {done_when: "signed roster verifies", command: "...", expect: exit-0}
      - {datapoints_ok: [custody_mode, roster_location]}
    waivable: {by: king, needs_reason: true}   # omit if never waivable

• A gate is tied to exactly one stage (its exit or entry) and names the quality goal it protects, so gates are traceable to standards instead of floating.
• requires: [gate:custody-approved] makes a step wait for a gate.
• A waiver records who, when and why, and appears in the overview.

Actors, roles and privileges

actors:
  - id: king
    role: Platform-root custodian
    description: Holds platform-root recovery authority.
    privileges: [approve-custody, revoke-root-token]

Steps and gates name an actor (who acts or approves). owner stays the repository or tool that does the work. The pack thereby explains what is relevant and who is responsible; the overview can group by actor.

Datapoints and dimensions

datapoints:
  - id: custody_mode
    label: Custody mode
    type: enum
    values: [temporary-single-king, two-of-three-ready]
    dimensions: {actor: king, subsystem: openbao, kind: decision}
    ask_in: custody        # stage in which the questionnaire asks for it

dimensions are free key/value tags, using canon vocabulary where it exists (actor, role, privilege, subsystem, kind, assurance goal). They drive the dimension view: a random-access table of all datapoints grouped or filtered by any dimension, editable independently of the flow. Secrets are never datapoints; only references ("stored in the platform-root safe entry") are.

Artefacts

artefacts: lists what a run yields, each with a location datapoint (a reference, never a value) and the produced_by step. The artefacts view is what makes a run more than a script.

Confirmation

Each step declares reversible: true|false (default true).

• reversible: a confirm button;
• not reversible: the operator types the pack's confirm_phrase (default I understand this cannot be undone; a step may set its own).

This replaces v0.1's risk for the purpose of confirmation. v0.1 risk values map as: destructive gives reversible: false, all others true.

Framing

threat_checks becomes framing: (list of statements, optionally per stage): things to keep in mind, shown before the work starts. They are not gates. v0.1 threat_checks load as pack-level framing.

Compatibility

• The engine loads runbook-pack/v0.1 and v0.2. A v0.1 pack is interpreted as one stage, a linear requires chain, no gates, no actors, its parameters as datapoints.
• engine: legacy-command is unchanged.
• The run record gains datapoints, gates and waivers sections (runbook-run/v0.2); v0.1 records still load.

What this is not

• No layout, color, icon or copy-text fields.
• No embedded scripting, and no execution mode (still RBT-WP-0006).
• No secret values anywhere.

Recommendation

Keep runbook-pack/v0.1 as shipped (three NetKingdom packs use it). Adopt this proposal as v0.2 and port the four in-repo packs, then use the console's seven runbooks and 14 gates as the first real v0.2 test: if the model can express them without special cases, it is expressive enough.

Open questions

1. Waivers: allowed at all, and by whom? Proposal: only where the pack declares waivable, always with a recorded reason.
2. Gate checks against live systems: may a gate run a command (as steps' verify do, operator-confirmed), or only read datapoint states and step results? Proposal: both, with the same confirmation rule.
3. Dimension vocabulary: free tags first, or start from a canon list? Proposal: free tags, with a dimensions registry file that packs may reference, promoted to canon later.
4. Nesting depth: three levels enough?
5. Datapoint ok: who confirms it, the operator or a check? Proposal: either; a check makes it ok, a manual confirmation is recorded as such.