runbook-tutorials/workplans/RBT-WP-0004-local-runbook-ui.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
RBT-WP-0004	workplan	Local runbook UI	infotech	runbook-tutorials	active	implementation	claude	stack	2026-09-29	2026-09-29	RBT-WP-0003	bbd03473-fcf7-5b20-a295-e9ff45fb7ecc

Goal

The interface that made the operator ask for this: a local web UI (and a terminal fallback) that shows where you are in a runbook, what to do next, and what you have proven.

Review the existing console's interaction model

id: RBT-WP-0004-T01
status: done
priority: high
state_hub_task_id: "8309d778-3688-5cb3-bb34-18f87b66dbf3"

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

Build the step view

id: RBT-WP-0004-T02
status: done
priority: high
state_hub_task_id: "e15c22b6-60eb-5a54-9d22-b268897fcf4d"

Parameter form, ordered steps with owner tags, rendered copyable commands, "done when" with confirm/verify, rollback shown beside each step, progress overview, resume after restart. Localhost only, no external calls, whynot-design posture, works without JavaScript frameworks.

Terminal mode

id: RBT-WP-0004-T03
status: todo
priority: medium
state_hub_task_id: "a33cbd52-8759-583f-a2f0-8ab926569346"

rtut run <pack> walking the same run record in the terminal, for hosts without a browser.

Evidence view and export

id: RBT-WP-0004-T04
status: done
priority: medium
state_hub_task_id: "616255c2-091c-5948-8160-abd9dc69907f"

Done 2026-09-29 (RBT-WP-0009-T04): the run view is the evidence view; a closed run's record downloads as JSON and rtut seal verifies it. The exercise-status diff no longer exists (retired, RBT-WP-0009-T01).

Fix the check, record and lock-in cycle

id: RBT-WP-0004-T05
status: done
priority: high
state_hub_task_id: "d635f972-0377-5581-a8fe-c01ef89559cd"

Done 2026-09-29 against the lighthouse showcase (tested over HTTP; a browser pass by Bernd is still the real check). 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. Follow-up done 2026-09-29 from Bernd's first hands-on: the command and Copy button appear only once a step is started (done steps keep the command as a record); "Mark done" and "Mark failed" sit left of the comment field; a first "Mark failed" without a comment only warns, a second click fails without one; every action returns to the current step instead of the top of the page.

Questionnaire flow on the v0.2 model

id: RBT-WP-0004-T06
status: done
priority: high
state_hub_task_id: "261bf74f-f5cd-55bb-9a96-12767418c980"

Unblocked: RBT-WP-0007 (engine) is finished. 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

id: RBT-WP-0004-T07
status: done
priority: high
state_hub_task_id: "16db09c7-7707-5d17-aab3-5d8eab2c1fce"

Unblocked: RBT-WP-0007 (engine) is finished. 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

id: RBT-WP-0004-T08
status: done
priority: high
state_hub_task_id: "23d3f5cc-e844-5077-9a4a-0435c189d98b"

Unblocked: RBT-WP-0007 (engine) is finished. State transparency at a glance: stage progress, gate states and waivers, datapoint completeness by dimension.

Visual design

id: RBT-WP-0004-T09
status: done
priority: medium
state_hub_task_id: "53c74197-4747-5bdd-9b7c-8bdc42b7c1f5"

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

id: RBT-WP-0004-T10
status: done
priority: medium
state_hub_task_id: "ddbca5e1-dcf6-5c2a-b3e2-497d2a82ba23"

Confirm button for reversible steps, typed phrase for irreversible ones, per the v0.2 reversible field.

Mode switch and override dialog

id: RBT-WP-0004-T11
status: done
priority: high
state_hub_task_id: "99320417-8261-556b-8932-4947cfd8ce11"

Unblocked: RBT-WP-0007 T06-T07 are finished. Choose manual or auto-confirm per run (with timeout and push-through controls). In manual mode, an override dialog lists unmet preconditions and the downstream risk before continuing; deviations show in the overview.

Feedback collector

id: RBT-WP-0004-T12
status: done
priority: medium
state_hub_task_id: "483e7472-ff22-5611-8010-9cf96ac34ec9"

Done 2026-09-29: after "All steps done." the run view offers three smileys and a comment (what felt strange or unclear, ideas to optimize). Stored in the run record (history kept, latest wins, secrets refused); rtut feedback <pack.yaml> lists the latest per run. Follow-up: fold feedback into the overview and use it to prioritize pack refinements.

Run outcome, score, exercise recording and captures

id: RBT-WP-0004-T13
status: done
priority: high
state_hub_task_id: "d35e129c-cfcc-538f-a4bf-76761d13a28a"

Done 2026-09-29 from Bernd's review: runs are finalized as succeeded, failed or abandoned (stale open runs count as abandoned after 7 days); a runbook's score (tried, succeeded, failed, abandoned, open, feedback tally) is shown in the list and on the pack page, with a list of its runs; finalizing a succeeded run offers an explicit "Record pack as exercised" that shows the change before writing it to pack.yaml; steps can capture the command run and its output, and output-contains checks can be verified against pasted output. Documented in docs/run-spec.md. Open: run histories are per machine (.local/), so a shared or committed history is still to be decided.

Delivered 2026-09-29: the v0.2 walk-through UI

rtut/ui_v2.py (tested over HTTP with 19 tests; rendering checked in headless Chromium screenshots of the flow, data and overview views on a mid-run state). Three views of one run:

• Guided flow (main): framing shown first; a banner with the recommended next action and the other items possible in parallel; nested stages with goals, per-stage questions (datapoints saved with validation), numbered steps with owner and actor, idempotency, irreversible and manual-only marks; alternatives with the recommended one preselected; typed confirmation phrase for irreversible steps; override dialog (reason, acknowledged downstream risk, recorded as a deviation) for blocked steps and gates in manual mode; gates with per-check controls and waivers; retry that asks for the partial-application confirmation on non-idempotent steps; captures and pasted-output checks; feedback and closing as before.
• Data: every datapoint editable independently of the flow, grouped or filtered by dimension (click a tag), with provenance, plus artefacts (resolved locations) and actors.
• Overview: progress, per-stage state, gates, datapoint states, deviations, mode changes.
• Modes: manual, and auto-confirm with "check once", "run until it waits" and "take over"; a stop or push-through is shown. Projects can start v0.2 members in either mode.
• Visual design: a restrained stylesheet (hairlines, state pills that never rely on colour alone, highlighter accent for the recommended action, print rules). Dark theme is written but not verified in a browser.

Feedback round after the first v0.2 hands-on (2026-09-29)

id: RBT-WP-0004-T14
status: done
priority: high
state_hub_task_id: "28582e62-335c-57d5-9adc-6b9050268139"

Bernd's remarks, each handled and tested: (a) forms no longer ask for a name; the active user (user-attributes, app-level and reusable by projects; RTUT_USER, saved settings or the OS login; /user page); (b) the showcase's irreversible step is now genuinely irreversible (the logbook entry carries the exact time it was written); (c) a "Latest activities" section on the main page; (d) values that steps already used can only be changed with an override and are recorded as changed-after-use, saves are all-or-nothing; (e) artefacts on the Data tab can be opened and downloaded, with safety rules; (f) run start, finish and duration, per-step duration, and the average duration of successful runs next to the score. Documented in docs/run-spec.md and docs/maturity-and-projects.md.

App shell, theme, attribute-set management and project editing

id: RBT-WP-0004-T15
status: done
priority: high
state_hub_task_id: "a6bf64b5-4432-5fc9-bdbe-5631b65e8343"

Done 2026-09-29 from Bernd's feedback (no way to switch theme, no navigation to user settings or attribute sets): a sidebar shell on every page (Home, Projects, Runbooks, Attribute sets, Activity; you and a theme switch at the bottom; a top bar on narrow screens); a theme switch that cycles system, light and dark and remembers the choice (?theme=dark also sets it); dedicated Projects, Runbooks and Activity pages; attribute sets listed, inspected with their resolved values and sources, created and edited (values, requirement, note, extends; secrets, bad names, unknown and circular extends refused, a refused save changes nothing); the project name, description and goal editable from the project page. Bernd confirmed the theme and navigation. Not done: deleting an attribute set, editing templates.

Closed runs locked; Home headlines as shortcuts

id: RBT-WP-0004-T16
status: done
priority: high
state_hub_task_id: "2622084d-b5f7-5442-962f-2f7b1e87cd8d"

Done 2026-09-29 from Bernd's feedback: Home headlines link to their sidebar sections; the "Back to the runbook list" link is gone; closed runs are locked (engine refuses changes, feedback included), sealed with a hash and made read-only, tampering is shown and disqualifies the run as maturity evidence; the closing form takes optional feedback so abandoned runs are not silent; a closed run shows its feedback read-only (no "Change my feedback"), or no feedback section at all. See docs/run-spec.md.

Project runs in the UI

id: RBT-WP-0004-T17
status: done
priority: high
state_hub_task_id: "1394fb8f-a24e-5516-a7c3-e31ca1a3a40e"

Done 2026-09-29: the project page has "Run the whole project" (mode choice, history of project runs); a project run page shows progress, the next or open member, the member table with status, progress and links, an override for out-of-order starts, auto-confirm controls (check once, run until it waits, take over or hand over), a log, and the closing form. Member run pages link back to their project run; the activity feed includes project run events. Tested over HTTP; visual check pending.

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.