runbook-tutorials/workplans/RBT-WP-0008-runbook-maturity-projects-and-idempotency.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
RBT-WP-0008	workplan	Runbook maturity, projects and idempotency	infotech	runbook-tutorials	finished	implementation	claude	stack	2026-09-29	2026-09-29	RBT-WP-0007	8f11966b-1e6c-5b12-8bc4-a13c52307c4c

Goal

Separate what a runbook is (characteristics), how far it can be trusted (maturity, earned and bound to a pack revision), and what state an environment is in (projects). Replaces the environment-dependent exercise_status. Model and candidate terminology: docs/maturity-and-projects.md.

Decide the terminology and model

id: RBT-WP-0008-T01
status: done
priority: high
state_hub_task_id: "904939c5-ed69-53a0-8fe1-2a0ae6d5337d"

Decided 2026-09-29 (Bernd: go with the suggestions, keep project): docs/maturity-and-projects.md.

Idempotency as a declared characteristic

id: RBT-WP-0008-T02
status: done
priority: high
state_hub_task_id: "911ef051-ee55-5c65-b134-57fa9f1fddce"

Done 2026-09-29: idempotent: idempotent | non-idempotent | conditional (+ idempotent_note) per step in the v0.2 schema, validator rule for conditional, derived runbook value (flow.pack_idempotency), declared honestly in the showcase. Values are words because YAML reads unquoted yes/no as booleans. Follow-ups: show it in the UI, and use it for the retry policy (T07).

Bind runs to a pack revision

id: RBT-WP-0008-T03
status: done
priority: high
state_hub_task_id: "a79e5b3d-221b-5ac6-a7a1-44737139c8f3"

Done 2026-09-29: pack.digest(); every run records pack_digest and context (project, target, environment class).

Derive maturity from run history

id: RBT-WP-0008-T04
status: done
priority: high
state_hub_task_id: "53fe81cd-6b67-5508-bdbd-38073a0d77e7"

Done 2026-09-29: rtut/maturity.py, review records (REVIEWS.yaml, bound to a revision), rtut maturity, rtut review. proven = reviewed + rehearsed + clean in two environments by two operators. Not yet done: retiring exercise_status and the "Record pack as exercised" click in the UI (T09).

Project specification and shared datapoints

id: RBT-WP-0008-T05
status: done
priority: high
state_hub_task_id: "d022c7fb-1421-5738-a00f-5b18593fb1a2"

Done 2026-09-29: attribute sets (attribute-set/v0.1: composition with extends, requirement, derived state, provenance, modified flag), projects with targets and members (project/v0.1), project templates (project-template/v0.1), rtut/attrs.py, rtut/project.py, schemas, CLI (rtut project ...), examples under attribute-sets/ and project-templates/. Runs started from a project take the resolved attributes as defaults and record the project as context.

Project state

id: RBT-WP-0008-T06
status: done
priority: medium
state_hub_task_id: "41f2b781-3699-5d21-bdfd-4ff3c2c0b777"

Done 2026-09-29: project.state(): member status not-applied | applying | applied | stale | failed, project state planned | applying | applied | stale, plus the members that can start next (after) and the attributes still needed.

Retry policy for non-idempotent steps

id: RBT-WP-0008-T07
status: done
priority: medium
state_hub_task_id: "8b34c57b-3380-5f7b-aaf5-6227a47dcf60"

Done 2026-09-29: run2.retry(..., acknowledge_partial=True) is required unless the step is declared idempotent (undeclared counts as not idempotent); the UI asks with a checkbox; the acknowledgement is recorded on the step. v0.1 runs have no idempotency declaration and keep their free retry.

UI for projects, maturity and attributes

id: RBT-WP-0008-T08
status: done
priority: high
state_hub_task_id: "913c46fa-7790-5d32-ada1-8dec430d4ff5"

Done 2026-09-29 (tested over HTTP, not yet reviewed in a browser): the runbook list shows maturity per runbook; the front page lists projects (environment, state, goal) and templates; a template page shows every attribute with requirement, note and source and creates a project; the project page shows goal, state, still-needed attributes (fillable, validated against the runbooks that consume them), members with status, maturity, next member and a Start run button, and per-member attribute tables with state, source, modified mark and problems; runs started from a project take its attributes and link back to it; the pack page shows maturity evidence, idempotency and a review form. Not covered: walking v0.2 runs (RBT-WP-0004). Original scope: show maturity and idempotency next to each runbook; a project view (goal, targets, member status, next member, needed attributes with state, source and modified marks); start a run from a project so its attributes fill the form; a template picker that instantiates a project.

Retire exercise_status

id: RBT-WP-0008-T09
status: done
priority: medium
state_hub_task_id: "54749c4e-69d8-54ee-a1f7-5e9f781a9053"

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

id: RBT-WP-0008-T10
status: done
priority: medium
state_hub_task_id: "917961d5-1571-52a5-b138-a15163176ed4"

Done 2026-09-29: rtut/projectrun.py and rtut/ui_projectrun.py. A project run snapshots the resolved attributes, then runs the members member by member in after order. Manual: you start each member (out of order needs a recorded override). Auto-confirm: the engine starts the next ready member, ticks its run, closes it when it finishes cleanly, continues through push-through, and stops wherever a person is needed (v0.1 member, manual-only or irreversible step, failed check). Closing locks and seals it, and abandons an open member run. Auto-pilot with execution remains RBT-WP-0006. Attribute states to explore in use: needed, optional, modified, checked; add what real use shows.

Acceptance Criteria

• "Exercised" has a precise, environment-aware meaning; a production project is never called "exercised".
• Maturity is derived from runs, bound to a revision, and expires when the pack changes.
• A value shared by several runbooks is entered once, in the project.