tegwick
8eaf0c77b0
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
161 lines
6.3 KiB
Markdown
161 lines
6.3 KiB
Markdown
---
|
|
id: RBT-WP-0008
|
|
type: workplan
|
|
title: "Runbook maturity, projects and idempotency"
|
|
domain: infotech
|
|
repo: runbook-tutorials
|
|
status: finished
|
|
flavor: implementation
|
|
owner: claude
|
|
topic_slug: stack
|
|
created: "2026-09-29"
|
|
updated: "2026-09-29"
|
|
depends_on: [RBT-WP-0007]
|
|
state_hub_workstream_id: "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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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.
|