Close the runbook-tutorials workplans: statuses, backlog with qualified tasks, documents refreshed (RBT-WP-0009-T03, T07)
Some checks are pending
CI Smoke / host-smoke (push) Waiting to run
CI Smoke / container-smoke (push) Waiting to run
Tests / tests (push) Waiting to run
Work Records / validate (push) Waiting to run

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
This commit is contained in:
tegwick 2026-09-29 21:45:24 +02:00
parent 2967ebb929
commit 1398b8f95a
15 changed files with 119 additions and 37 deletions

View file

@ -4,7 +4,7 @@ A user interface specialized to present runbook tutorials that with parameters
can guide through actual IT administration and operation tasks.
- **Intent:** `INTENT.md` · **Scope:** `SCOPE.md`
- **Pack specification:** `docs/pack-spec.md` (v0.1, runnable) and `docs/pack-spec-v0.2.md` (v0.2: stages, gates, datapoints, actors, modes; validates, not yet runnable). Schemas in `rtut/schema/`. UX findings: `docs/ux-review-2026-09-29.md`
- **Documents:** `docs/README.md` (index). **Pack specification:** `docs/pack-spec-v0.2.md` (current: stages, gates, datapoints, actors, modes) and `docs/pack-spec.md` (v0.1, still supported). Schemas in `rtut/schema/`.
- **Packs live where the procedure lives:** `runbooks/<pack>/pack.yaml` in the owning repo.
Examples: `net-kingdom/runbooks/`, and here `runbooks/example-hello/` and
`runbooks/showcase-lighthouse/` (a harmless story to try the UI on).

View file

@ -18,6 +18,7 @@ bootstrap console) working unchanged.
## In Scope
- Runbook pack specification, JSON Schema, and versioning rules
- Attribute sets, projects and project templates, and runs of whole projects
- Pack discovery, loading, validation and conformance tests
- The local UI and CLI that present a pack and record progress
- Evidence records (non-secret), run outcomes and scores, and maturity derived from run history
@ -34,12 +35,19 @@ bootstrap console) working unchanged.
## Current State
- Status: bootstrap. Specification and workplans are being written; extraction of the
console from `net-kingdom` (`tools/security-bootstrap-console/`) is planned in
`workplans/`.
- **Engine and UI: working.** Pack specifications v0.1 and v0.2 with validators; runs with verification, evidence, captures, overrides,
waivers and deviations; manual and auto-confirm modes; locked and sealed closed runs with exportable, verifiable records; scores and
durations; maturity derived from run history; attribute sets, projects, project templates and whole-project runs; a local web UI with a
guided flow, a data view and an overview; CLI (`rtut`), packaging and tests.
- **Not built, by decision:** executing a step's command (auto-pilot, opt-in and audited), a cross-repository pack index, a runbook-aware
feedback assistant, dependencies between runbooks, and a terminal walk-through. They are in `workplans/RBT-WP-0006`.
- **The NetKingdom security bootstrap console** stays a permanent legacy pack, launched unchanged. `docs/console-mapping.md` records why
(seven gaps that a v0.3 would close first).
- **Real content** lives in the owning repositories: `net-kingdom/runbooks/` has three v0.2 packs awaiting their first attended run.
## Getting Oriented
- Direction: `INTENT.md`
- Pack specification: `docs/pack-spec.md`
- Documents: `docs/README.md`
- Pack specification: `docs/pack-spec-v0.2.md` (current) and `docs/pack-spec.md` (v0.1)
- Work state: `.custodian-brief.md` and `workplans/`

View file

@ -16,6 +16,7 @@
| workplan | RBT-WP-0006 | active | — | workplans/RBT-WP-0006-execution-mode-and-pack-index.md |
| workplan | RBT-WP-0007 | active | — | workplans/RBT-WP-0007-engine-v0-2-graph-datapoints-and-gates.md |
| workplan | RBT-WP-0008 | active | — | workplans/RBT-WP-0008-runbook-maturity-projects-and-idempotency.md |
| workplan | RBT-WP-0009 | active | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0001-T01 | done | — | workplans/RBT-WP-0001-statehub-bootstrap.md |
| task | RBT-WP-0001-T02 | done | — | workplans/RBT-WP-0001-statehub-bootstrap.md |
| task | RBT-WP-0001-T03 | done | — | workplans/RBT-WP-0001-statehub-bootstrap.md |
@ -24,8 +25,8 @@
| task | RBT-WP-0002-T03 | done | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0002-T04 | done | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0002-T05 | done | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0002-T06 | wait | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0002-T07 | progress | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0002-T06 | done | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0002-T07 | done | — | workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md |
| task | RBT-WP-0003-T01 | done | — | workplans/RBT-WP-0003-engine-core-run-state-and-evidence.md |
| task | RBT-WP-0003-T02 | done | — | workplans/RBT-WP-0003-engine-core-run-state-and-evidence.md |
| task | RBT-WP-0003-T03 | done | — | workplans/RBT-WP-0003-engine-core-run-state-and-evidence.md |
@ -33,7 +34,7 @@
| task | RBT-WP-0004-T01 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T02 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T03 | todo | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T04 | todo | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T04 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T05 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T06 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0004-T07 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
@ -49,9 +50,9 @@
| task | RBT-WP-0004-T17 | done | — | workplans/RBT-WP-0004-local-runbook-ui.md |
| task | RBT-WP-0005-T01 | done | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T02 | done | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T03 | todo | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T04 | todo | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T05 | todo | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T03 | done | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T04 | cancel | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0005-T05 | done | — | workplans/RBT-WP-0005-legacy-adapter-and-console-migration.md |
| task | RBT-WP-0006-T01 | wait | — | workplans/RBT-WP-0006-execution-mode-and-pack-index.md |
| task | RBT-WP-0006-T02 | wait | — | workplans/RBT-WP-0006-execution-mode-and-pack-index.md |
| task | RBT-WP-0006-T03 | wait | — | workplans/RBT-WP-0006-execution-mode-and-pack-index.md |
@ -73,3 +74,10 @@
| task | RBT-WP-0008-T08 | done | — | workplans/RBT-WP-0008-runbook-maturity-projects-and-idempotency.md |
| task | RBT-WP-0008-T09 | todo | — | workplans/RBT-WP-0008-runbook-maturity-projects-and-idempotency.md |
| task | RBT-WP-0008-T10 | done | — | workplans/RBT-WP-0008-runbook-maturity-projects-and-idempotency.md |
| task | RBT-WP-0009-T01 | done | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0009-T02 | done | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0009-T03 | todo | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0009-T04 | done | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0009-T05 | done | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0009-T06 | done | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |
| task | RBT-WP-0009-T07 | todo | — | workplans/RBT-WP-0009-finalize-the-runbook-tutorials-workplans.md |

12
docs/README.md Normal file
View file

@ -0,0 +1,12 @@
# Documents
| Document | What it is |
| --- | --- |
| [`pack-spec-v0.2.md`](pack-spec-v0.2.md) | The current runbook pack specification: stages, steps, alternatives, gates, actors, datapoints, artefacts, modes, deviations |
| [`pack-spec.md`](pack-spec.md) | The v0.1 specification, still supported |
| [`run-spec.md`](run-spec.md) | What a run records and the rules the engine enforces: outcomes and scores, locked and sealed records, exports, captures, timestamps, v0.2 runs |
| [`maturity-and-projects.md`](maturity-and-projects.md) | Maturity, attribute sets, projects, templates, project runs, and the retirement of `exercise_status` |
| [`console-mapping.md`](console-mapping.md) | The security bootstrap console mapped onto v0.2, and the seven gaps a v0.3 would close |
| [`ux-review-2026-09-29.md`](ux-review-2026-09-29.md) | The first hands-on review that shaped v0.2 and the UI |
Direction is in [`../INTENT.md`](../INTENT.md), scope and current state in [`../SCOPE.md`](../SCOPE.md), work in [`../workplans/`](../workplans/).

View file

@ -3,7 +3,9 @@
Status: **adopted 2026-09-29** (Bernd's review answers are in the Decisions section).
Derived from `docs/ux-review-2026-09-29.md`. v0.1 stays valid; v0.2 is a superset.
Machine-checkable form: `rtut/schema/runbook-pack-v0.2.schema.json` plus the semantic
checks in `rtut/v2.py`. The engine and UI do not run v0.2 packs yet (RBT-WP-0007).
checks in `rtut/v2.py`. The engine (`rtut/run2.py`) and the UI run v0.2 packs. This is the
current version for new packs; a change that would invalidate existing v0.2 packs becomes v0.3
(candidates: `docs/console-mapping.md`, gaps G1 to G7).
## Principle

View file

@ -1,5 +1,7 @@
# Runbook pack specification v0.1
Status: supported, no longer extended. New packs use v0.2 (`docs/pack-spec-v0.2.md`); v0.1 packs keep running unchanged.
A **runbook pack** is a directory `runbooks/<pack-dir>/` in the repository that
owns the procedure. It contains `pack.yaml`, validated by
`rtut/schema/runbook-pack.schema.json`, plus optional supporting files. The engine

View file

@ -1,9 +1,9 @@
---
id: capability.infotech.runbook-tutorials
name: Runbook-tutorial engine
summary: Pack specification, validator and launcher for guided, parameterized operator runbooks; packs live in the repos that own the procedure.
summary: Engine, local UI and CLI for guided, parameterized operator runbooks: pack specification and validators, runs with evidence and locked records, maturity, attribute sets, projects and whole-project runs. Packs live in the repos that own the procedure.
owner: runbook-tutorials
status: draft
status: active
domain: infotech
tags:
- runbook
@ -12,6 +12,7 @@ tags:
- guided
---
Draft. Specification `runbook-pack/v0.1`, validator and legacy launcher exist; run
state, evidence and UI are planned (RBT-WP-0003, RBT-WP-0004). Maturity vector to be
assessed after the spec is frozen (RBT-WP-0002-T04).
Working: specifications `runbook-pack/v0.1` and `v0.2` with validators, the engine and local UI, projects and project templates, and the `rtut`
CLI (see `SCOPE.md`). Not built by decision: execution of steps, a cross-repository pack index, a feedback assistant (`workplans/RBT-WP-0006`).
Only the NetKingdom repository provides packs so far, and its three v0.2 packs have not had their first attended run, so this capability is
`active` but has no operational evidence yet. The fleet maturity vector is not assessed here: it needs the fleet's assessment method.

View file

@ -4,9 +4,9 @@ domain: infotech
capabilities:
- id: capability.infotech.runbook-tutorials
name: Runbook-tutorial engine
summary: Pack specification, validator and launcher for guided, parameterized operator runbooks.
summary: Engine, local UI and CLI for guided, parameterized operator runbooks; packs live in the repos that own the procedure.
domain: infotech
status: draft
status: active
owner: runbook-tutorials
path: registry/capabilities/capability.infotech.runbook-tutorials.md
tags: [runbook, tutorial, operator, guided]

View file

@ -4,7 +4,7 @@ type: workplan
title: "Runbook pack specification and validator"
domain: infotech
repo: runbook-tutorials
status: active
status: finished
flavor: implementation
owner: claude
topic_slug: stack

View file

@ -4,7 +4,7 @@ type: workplan
title: "Local runbook UI"
domain: infotech
repo: runbook-tutorials
status: active
status: finished
flavor: implementation
owner: claude
topic_slug: stack
@ -49,12 +49,13 @@ posture, works without JavaScript frameworks.
```task
id: RBT-WP-0004-T03
status: todo
status: cancel
priority: medium
state_hub_task_id: "a33cbd52-8759-583f-a2f0-8ab926569346"
```
`rtut run <pack>` walking the same run record in the terminal, for hosts
Cancelled 2026-09-29 (RBT-WP-0009): the run records are usable from the CLI for v0.1 packs (`rtut run ...`), and a terminal walk-through for v0.2 is not
needed to close this workplan. It is kept as RBT-WP-0006-T05. Original scope: `rtut run <pack>` walking the same run record in the terminal, for hosts
without a browser.
## Evidence view and export

View file

@ -4,7 +4,7 @@ type: workplan
title: "Legacy adapter and console migration"
domain: infotech
repo: runbook-tutorials
status: active
status: finished
flavor: implementation
owner: claude
topic_slug: stack

View file

@ -4,7 +4,7 @@ type: workplan
title: "Execution mode and multi-repo pack index"
domain: infotech
repo: runbook-tutorials
status: active
status: backlog
flavor: implementation
owner: claude
topic_slug: stack
@ -16,8 +16,9 @@ state_hub_workstream_id: "35196f02-7cb9-5706-9529-1cba9c736058"
## Goal
Later capabilities, deliberately not started: opt-in execution of steps, and
discovery of packs across the estate.
**Backlog (2026-09-29).** Later capabilities, deliberately not started, each waiting for a decision from Bernd: opt-in execution of steps (auto-pilot),
discovery of packs across the estate, a runbook-aware feedback assistant, dependencies between runbooks, a terminal walk-through, the v0.3 design
that closes the gaps in `docs/console-mapping.md`, and an optional security and code review. Nothing here blocks the finished runbook-tutorials workplans.
## Opt-in, audited step execution
@ -77,3 +78,41 @@ state_hub_task_id: "acd969c3-3bd4-5953-9f9a-8ad8c5d8e380"
Packs declare `requires_packs` with a required result (exercised, or a named gate
passed), instead of deeper nesting (v0.2 caps nesting at three levels). Needs a decision
on how a pack in another repo is identified and trusted.
## Terminal walk-through
```task
id: RBT-WP-0006-T05
status: wait
needs_human: true
blocking_reason: "Needs a decision whether hosts without a browser justify it; the CLI already covers v0.1 runs (moved from RBT-WP-0004-T03)."
priority: low
```
`rtut run <pack>` walking a run in the terminal, for hosts without a browser. v0.2 runs can be driven from the engine and the UI, not yet from a terminal.
## v0.3: close the console gaps
```task
id: RBT-WP-0006-T06
status: wait
needs_human: true
blocking_reason: "Needs a decision to start a v0.3 design: conditional applicability (G1), longer horizons (G2), gate recheck (G3), value predicates (G4), local-only attributes (G5), outputs feeding later members (G7). G6 is T01."
priority: medium
```
The gaps in `docs/console-mapping.md`. Closing G1, G3 and G7 is also the precondition for extracting the console's engine parts and for modeling the
security bootstrap as a project (the cancelled RBT-WP-0005-T04).
## Security and code review
```task
id: RBT-WP-0006-T07
status: wait
needs_human: true
blocking_reason: "Optional follow-up agreed with Bernd on 2026-09-29: the workplans close without it. Needs a decision when to run it."
priority: medium
```
Run the security review and the code review over the engine and the UI: it serves files (artefacts, records), writes YAML (projects, attribute sets),
uses `shell=True` for operator-confirmed verify commands, and takes form input on localhost. Also first execution of `.forgejo/workflows/tests.yaml` on a real runner.

View file

@ -4,7 +4,7 @@ type: workplan
title: "Engine v0.2: graph, datapoint states and gates"
domain: infotech
repo: runbook-tutorials
status: active
status: finished
flavor: implementation
owner: claude
topic_slug: stack

View file

@ -4,7 +4,7 @@ type: workplan
title: "Runbook maturity, projects and idempotency"
domain: infotech
repo: runbook-tutorials
status: active
status: finished
flavor: implementation
owner: claude
topic_slug: stack
@ -130,12 +130,13 @@ template picker that instantiates a project.
```task
id: RBT-WP-0008-T09
status: todo
status: done
priority: medium
state_hub_task_id: "54749c4e-69d8-54ee-a1f7-5e9f781a9053"
```
Replace the "Record pack as exercised" click and the `exercise_status` field with derived maturity; migrate the packs.
Done 2026-09-29 (RBT-WP-0009-T01): the click, `apply_exercise` and `exercise_update` are removed, the field is deprecated and ignored, and the shipped packs no longer carry it.
Original scope: replace the "Record pack as exercised" click and the `exercise_status` field with derived maturity; migrate the packs.
## Templates as products: auto-confirm and auto-pilot on a project

View file

@ -4,13 +4,14 @@ type: workplan
title: "Finalize the runbook-tutorials workplans"
domain: infotech
repo: runbook-tutorials
status: active
status: finished
flavor: implementation
owner: claude
topic_slug: stack
created: "2026-09-29"
updated: "2026-09-29"
depends_on: [RBT-WP-0002, RBT-WP-0004, RBT-WP-0005, RBT-WP-0006, RBT-WP-0007, RBT-WP-0008]
depends_on: [RBT-WP-0002, RBT-WP-0004, RBT-WP-0005, RBT-WP-0007, RBT-WP-0008]
state_hub_workstream_id: "53103733-880f-58cc-a330-4b86375b20ad"
---
## Goal
@ -29,6 +30,7 @@ backlog and do only a small JSON export.
id: RBT-WP-0009-T01
status: done
priority: high
state_hub_task_id: "298ba5c8-cd8c-5d0c-afdc-cd2c41b67774"
```
Done 2026-09-29. `exercise_status` mixed three things (RBT-WP-0008). Maturity, derived from run history, replaces it. Remove the "Record pack as
@ -42,6 +44,7 @@ Also found and fixed while doing it: the CLI had no tests, and `rtut list` crash
id: RBT-WP-0009-T02
status: done
priority: high
state_hub_task_id: "14b17a9b-c3a3-5291-9328-e90c99caea49"
```
Done 2026-09-29. Declare the dependencies (`pyproject.toml`: PyYAML, jsonschema, pytest) so a fresh checkout can run; add `rtut check` (packs, attribute
@ -54,11 +57,12 @@ runner** (no way to trigger one from here); check its first execution.
```task
id: RBT-WP-0009-T03
status: todo
status: done
priority: medium
state_hub_task_id: "fec1fc82-c686-524f-861f-ba0881f9408b"
```
Refresh `SCOPE.md` (it still says "bootstrap"), add a `docs/README.md` index, note in the specs that v0.1 and v0.2 changes from here on
Done 2026-09-29. Refresh `SCOPE.md` (it still says "bootstrap"), add a `docs/README.md` index, note in the specs that v0.1 and v0.2 changes from here on
become a new version, update the capability entry, and make the workplan statuses true (RBT-WP-0007 finished, RBT-WP-0002-T07 done,
RBT-WP-0006 and NK-WP-0011 to backlog).
@ -68,6 +72,7 @@ RBT-WP-0006 and NK-WP-0011 to backlog).
id: RBT-WP-0009-T04
status: done
priority: medium
state_hub_task_id: "f6f2e2b2-7872-5565-9960-609a790b5356"
```
Done 2026-09-29, closing RBT-WP-0004-T04: a closed run's (and project run's) record can be downloaded as JSON from its page; an open run is
@ -79,6 +84,7 @@ refused (409). Added `rtut seal <file>` so an exported record can be verified an
id: RBT-WP-0009-T05
status: done
priority: high
state_hub_task_id: "d90789fc-0497-5caa-979e-53289d20afc4"
```
Done 2026-09-29. Verdict: the structure maps, the behaviour does not fully; seven gaps (G1 to G7) are the v0.3 candidates. `docs/console-mapping.md`: map the security bootstrap console's 6 stages, 14 gates, roles, subsystems, integrations, 12 artefacts
@ -91,6 +97,7 @@ RBT-WP-0005-T03, records the decision to keep the console as a permanent legacy
id: RBT-WP-0009-T06
status: done
priority: high
state_hub_task_id: "ca96aae8-bac5-5170-971f-d4b06e1ff252"
```
Done 2026-09-29 (net-kingdom commit 90112f3). `nk.ssh-certificates`, `nk.openbao-operating-path` and `nk.protected-system-flex-auth` become v0.2 packs with actors, datapoints,
@ -104,11 +111,12 @@ Bernd's (NK-WP-0044-T05).
```task
id: RBT-WP-0009-T07
status: todo
status: done
priority: high
state_hub_task_id: "32408947-03bc-58cb-b57b-cb2ee097a3bc"
```
Set every status to what is true, move terminal mode and the evidence work that is not done to the backlog with the decisions written
Done 2026-09-29. Set every status to what is true, move terminal mode and the evidence work that is not done to the backlog with the decisions written
down, archive the finished workplans, sync State Hub, and record a progress event. Work that needs Bernd's own environment
(NK-WP-0044-T05 attended runs, NK-WP-0009 T03-T05, the external STS issuer for T02) stays in net-kingdom and is named there.