Adopt spec v0.2: schema, semantic validator, operating modes; workplans updated

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

docs/pack-spec-v0.2.md

@@ -1,7 +1,9 @@
-# Runbook pack specification v0.2 - proposal
+# Runbook pack specification v0.2
 
-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.
+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: `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).
 
 ## Principle
 
@@ -141,23 +143,65 @@ things to keep in mind, shown before the work starts. They are not gates. v0.1
 - No embedded scripting, and no execution mode (still RBT-WP-0006).
 - No secret values anywhere.
 
-## Recommendation
+## Operating modes, overrides and deviations
 
-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.
+A **run** has a mode. The mode belongs to the run, not to the pack.
 
-## Open questions
+| Mode | Who confirms | Checks, gates, preconditions |
+| --- | --- | --- |
+| **manual** | the operator | shown with their state; the operator confirms each |
+| **autopilot** | the engine, when every precondition is met | evaluated by the engine; confirmation is applied automatically |
 
-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.
+### Manual mode: override
+
+If preconditions are not met the operator may **override** and continue anyway.
+Doing so must (1) show a dialog that names the unmet preconditions and the
+downstream risk (`downstream_risk` text declared on the step or gate, else a
+generic warning), (2) require an explicit confirmation, and (3) record a
+**deviation** in the run.
+
+### Autopilot mode: timeout and push-through
+
+- A step or gate may declare `timeout: {seconds: N, on_timeout: stop|push-through}`;
+  a run may set a default. Without a timeout, autopilot waits.
+- `stop` (default): on timeout the run stops and reports.
+- `push-through`: on timeout the engine confirms the item, records a deviation,
+  and moves on, ignoring the problem. This gathers the most information about
+  problems in one run and reduces refinement runs.
+- Irreversible steps are never confirmed automatically unless the run was started
+  with an explicit, recorded pre-authorization naming those steps (and the pack's
+  `confirm_phrase`). Push-through does not bypass that rule. This is a safety
+  default, open to review.
+- A step may declare `autopilot: manual-only` to forbid automation entirely.
+
+### Deviations
+
+Every override, waiver and push-through is a **deviation** in the run record:
+`kind` (`override|waiver|push-through`), `item` (step or gate id), `mode`,
+`unmet` (what was not satisfied), `risk_acknowledged`, `reason` (required for
+overrides and waivers; automatic text for push-through), `who`, `at`. A run with
+deviations is marked so in the overview and can never exercise a pack. A **waiver** is
+declared in advance (`waivable` on a gate); an **override** is not.
+
+## Decisions (2026-09-29, Bernd)
+
+1. **Waivers:** allowed only where a gate declares `waivable`, always with a reason.
+   Undeclared departures are overrides (above), also recorded.
+2. **Gate checks:** a gate may run a command (operator-confirmed in manual mode) or
+   read datapoint states and step results.
+3. **Dimension vocabulary:** free tags first; a shared registry may be promoted to canon.
+4. **Nesting:** at most three levels. If procedures grow beyond that, dependencies
+   between runbooks are needed (see below), not deeper nesting.
+5. **Datapoint `ok`:** reached by a check, or by a recorded manual confirmation.
+   Handling of missing preconditions is defined by the operating modes above.
+
+## Later: dependencies between runbooks
+
+Not in v0.2. When a procedure needs another runbook (for example "OpenBao operating
+path requires the SSH access pack"), packs will declare `requires_packs` with a
+required result (exercised, or a named gate passed). Tracked in RBT-WP-0006.
+
+## Recommendation (carried out)
+
+Keep `runbook-pack/v0.1` as shipped (three NetKingdom packs use it). Use the old
+console's seven runbooks and 14 gates as the first real v0.2 test.