diff --git a/docs/pack-spec-v0.2-proposal.md b/docs/pack-spec-v0.2-proposal.md new file mode 100644 index 0000000..f0b33a6 --- /dev/null +++ b/docs/pack-spec-v0.2-proposal.md @@ -0,0 +1,163 @@ +# 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 + +```text +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. + +```yaml +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 + +```yaml +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 + +```yaml +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. diff --git a/docs/ux-review-2026-09-29.md b/docs/ux-review-2026-09-29.md new file mode 100644 index 0000000..38cccca --- /dev/null +++ b/docs/ux-review-2026-09-29.md @@ -0,0 +1,44 @@ +# UX review: old console vs first native UI (2026-09-29) + +Reviewer: Bernd. Recorded by Claude. Compared `security-bootstrap-console` +(NetKingdom, `:8876`) with the first `rtut ui` (`:8877`) on the NetKingdom packs. + +## The comparison is unequal + +The old console is more accessible and more professional on first impression, and +it models a far more complicated procedure. Each of its stages is about the size +of one of the new example runbooks. The new UI was built for flat sequences and +looks like a config form with comments as content. Design polish (spacing, dark +mode, visual guidance) is a renderer job. **The specification must not be +complicated to enable eye-candy**; a clear specification should render well. + +## Findings + +| # | Finding | Consequence | +| --- | --- | --- | +| 1 | The new flows are the basic element only: simple sequences with no hierarchy, no alternatives. The old console's stages give progress feedback and structure | The spec needs stages, hierarchy, alternatives and parallelism | +| 2 | Two different states are needed: `nil/set/err/ok` is about **setting the parameter** (a datapoint); `todo/running/done/failed` is about **applying** it (a step) | Datapoints get their own state, separate from step state | +| 3 | Next-action guidance is necessary. Several actions may be available once their prerequisites are met, but exactly one is *recommended* | The pack captures parallelism; a canonical, optional serialization gives a single operator one path | +| 4 | An overview with very clear state transparency, in several views by dimension (from canon standards where available), is a core feature. Hierarchical organization of complex runbooks is how orientation and learning happen | Overview and hierarchy are first-class | +| 5 | The pack must define and explain actors, roles, privileges; otherwise nothing says what is relevant | Actors and roles are part of the pack | +| 6 | Showing what a run produced and where it lives is what makes the UI more valuable than a wizard, script or config files | Artefacts (non-secret references) are part of the pack | +| 7 | Both confirmation styles are needed: a confirm button for reversible actions, a typed phrase for irreversible ones | Derive the style from reversibility; default confirm | +| 8 | Layout: the new UI is unpolished and gives too little visual guidance | Renderer work, after the spec | +| 9 | **Two views, two use cases.** A serial guided questionnaire is the main interface. A dimension/tag organized, random-access view of the collected datapoints is a second interface, independent of the flow. In the old console the two are intermingled | Separate the flow from the data view | +| 10 | Gates are not clearly tied to stages or to quality-assurance goals in the old console, and gates are missing from the new UI entirely | QA gates become a first-class concept, attached to stages and goals | +| 11 | Threat checks in the footer are misplaced: they are framing to keep in mind, not a final gate to pass | Show framing at the start; keep gates separate | + +## Usability defects in the first UI (to fix in the renderer) + +- Ticking the manual confirm box shows "passed" but the step stays `running` + until "Mark done" is pressed. Unticking then changes nothing. The + check, record and lock-in cycle is not visible. +- Steps after the first show no Start button and no reason. A blocked step must + say what it is waiting for. +- The good part, to keep: parameter form, then a run view with copy command, + run in terminal, feedback, confirm. + +## Later extension (noted, not scheduled) + +Operator feedback on a step feeds a runbook-aware assistant that may diagnose +the deployment, giving a feedback, retry, feedback, confirm loop. diff --git a/workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md b/workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md index 31fe348..e1e9d26 100644 --- a/workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md +++ b/workplans/RBT-WP-0002-runbook-pack-spec-and-validator.md @@ -57,20 +57,42 @@ semantic checks the schema cannot express (placeholders, duplicates, rollback, secret markers, parameter defaults) and 16 tests. Parameter rendering rejects unsafe characters. -## Review the specification with the operator and freeze v0.1 +## Review the v0.2 proposal and decide ```task id: RBT-WP-0002-T04 -status: todo +status: progress priority: high -state_hub_task_id: "1e1bdfdd-2482-5280-a870-5d823dfa1d34" ``` -Walk through the spec with Bernd against the real NetKingdom packs and the -legacy console. Open questions: step branching and conditional steps; whether -`verify` may run a command automatically; how packs declare dependencies on -other packs; signed packs. Record decisions and freeze `runbook-pack/v0.1`, or -raise v0.2 with a migration note. +`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 + +```task +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 + +```task +id: RBT-WP-0002-T06 +status: wait +priority: medium +``` + +Port the four validating packs to v0.2 where it helps, and add v0.2 test packs with +alternatives, gates and actors. ## Acceptance Criteria diff --git a/workplans/RBT-WP-0004-local-runbook-ui.md b/workplans/RBT-WP-0004-local-runbook-ui.md index 472e04a..8924ac6 100644 --- a/workplans/RBT-WP-0004-local-runbook-ui.md +++ b/workplans/RBT-WP-0004-local-runbook-ui.md @@ -24,14 +24,12 @@ what you have proven. ```task id: RBT-WP-0004-T01 -status: todo +status: done priority: high state_hub_task_id: "8309d778-3688-5cb3-bb34-18f87b66dbf3" ``` -Run `make security-bootstrap-ui` in `net-kingdom` with Bernd and record what to keep -(state chips `nil/set/err/ok`, next safe action, copyable command blocks, -approval phrase) and what to change. Output: a short UX note in `docs/`. +Done 2026-09-29 with Bernd. Findings and consequences are in `docs/ux-review-2026-09-29.md`; the model they imply is proposed in `docs/pack-spec-v0.2-proposal.md`. ## Build the step view @@ -71,7 +69,79 @@ state_hub_task_id: "616255c2-091c-5948-8160-abd9dc69907f" Show the run record, export it as non-secret JSON, and produce the exercise-status diff from RBT-WP-0003-T04. +## Fix the check, record and lock-in cycle + +```task +id: RBT-WP-0004-T05 +status: todo +priority: high +``` + +Defects found in review: a ticked manual check shows "passed" while the step stays +`running`, and unticking changes nothing; blocked steps show no Start button and no +reason. Make the cycle explicit (check, record, mark done), and show what a blocked +step is waiting for. + +## Questionnaire flow on the v0.2 model + +```task +id: RBT-WP-0004-T06 +status: wait +priority: high +``` + +Depends on RBT-WP-0007. The serial guided flow is the main interface: stages with +progress, the recommended next action, other ready actions, framing shown at the +start of each stage, and gates shown at stage exit. + +## Dimension view + +```task +id: RBT-WP-0004-T07 +status: wait +priority: high +``` + +Depends on RBT-WP-0007. A random-access table of datapoints (with `nil/set/err/ok` +state) grouped or filtered by dimension (actor, role, privilege, subsystem, kind), +editable independently of the flow, plus the artefacts view. + +## Overview + +```task +id: RBT-WP-0004-T08 +status: wait +priority: high +``` + +Depends on RBT-WP-0007. State transparency at a glance: stage progress, gate states +and waivers, datapoint completeness by dimension. + +## Visual design + +```task +id: RBT-WP-0004-T09 +status: wait +priority: medium +``` + +Theme and layout at the quality of the old console or better: spacing, hierarchy, +dark mode, visual guidance. Implemented in the renderer only; no presentation fields +in the pack spec. + +## Typed-phrase confirmation + +```task +id: RBT-WP-0004-T10 +status: wait +priority: medium +``` + +Confirm button for reversible steps, typed phrase for irreversible ones, per the v0.2 +`reversible` field. + ## Acceptance Criteria - Bernd can complete the SSH tutorial pack in the UI without pasting outputs to an agent. +- The old console's seven runbooks can be walked in the new UI at equal or better clarity. - The UI refuses to display or store anything matching the secret markers. diff --git a/workplans/RBT-WP-0006-execution-mode-and-pack-index.md b/workplans/RBT-WP-0006-execution-mode-and-pack-index.md index 8d7fd71..633b974 100644 --- a/workplans/RBT-WP-0006-execution-mode-and-pack-index.md +++ b/workplans/RBT-WP-0006-execution-mode-and-pack-index.md @@ -43,3 +43,15 @@ state_hub_task_id: "0cfb69bc-dc7e-5960-8359-64c49a742a6e" `rtut list --estate` scans registered repos for `runbooks/*/pack.yaml` and publishes a capability entry in the registry. Needs a decision on scan scope. + +## Runbook-aware feedback assistant + +```task +id: RBT-WP-0006-T03 +status: wait +priority: low +``` + +Operator feedback on a step feeds an assistant that knows the runbook and may +diagnose the deployment (read-only access first), giving a feedback, retry, +feedback, confirm loop. Needs decisions on access, identity and what is sent where. diff --git a/workplans/RBT-WP-0007-engine-v0-2-graph-datapoints-and-gates.md b/workplans/RBT-WP-0007-engine-v0-2-graph-datapoints-and-gates.md new file mode 100644 index 0000000..fcad524 --- /dev/null +++ b/workplans/RBT-WP-0007-engine-v0-2-graph-datapoints-and-gates.md @@ -0,0 +1,79 @@ +--- +id: RBT-WP-0007 +type: workplan +title: "Engine v0.2: graph, datapoint states and gates" +domain: infotech +repo: runbook-tutorials +status: backlog +flavor: implementation +owner: claude +topic_slug: stack +created: "2026-09-29" +updated: "2026-09-29" +depends_on: [RBT-WP-0002] +--- + +## Goal + +Make the engine understand the v0.2 model so a renderer can show a questionnaire flow, +a dimension view and an overview from the same run data. + +## Dependency graph and recommended next action + +```task +id: RBT-WP-0007-T01 +status: wait +priority: high +``` + +Compute ready items from `requires` and `one_of`; recommended next = first ready in +canonical order; explain what a blocked item waits for. + +## Datapoint states + +```task +id: RBT-WP-0007-T02 +status: wait +priority: high +``` + +`nil/set/err/ok` per datapoint in the run record, with validation, dimension tags, and +how `ok` is reached (check or recorded manual confirmation). + +## Gates and waivers + +```task +id: RBT-WP-0007-T03 +status: wait +priority: high +``` + +Evaluate gate checks (same confirmation rule as step verify), block dependents and stage +exit, record waivers with who, when and why. + +## Run record v0.2 + +```task +id: RBT-WP-0007-T04 +status: wait +priority: medium +``` + +`runbook-run/v0.2` with datapoints, gates, waivers; v0.1 records still load. + +## Confirmation policy + +```task +id: RBT-WP-0007-T05 +status: wait +priority: medium +``` + +Derive confirm button versus typed phrase from `reversible`; enforce the phrase in the +engine so no renderer can skip it. + +## Acceptance Criteria + +- The old console's stages, gates and datapoints can be expressed and computed + without special cases. +- A v0.1 pack behaves exactly as before.