Step 21 session A: close step 17's paperwork

- PR-docs get their real numbers: bwrap-build-runtime -> PR#4, build-current-head-from-the-branches-view -> PR#3 (files and scenario IDs) - tools/remote: header note marking install's clone step and build as the self-build prototype, superseded by session D of step 21 (usage range grown) - ADR 0008: bubblewrap user-namespace sandbox as the third build runtime; step 17 and the plan README now point at 0008 (0007 was taken by build definitions before the step landed) - AGENTS.md: decisions list catches up with ADR 0007 and ADR 0008 - architecture skill: BwrapBuildRunner paragraph (rootfs unpack, uid mapping, mount ordering, pinned keys) and the dispatcher's three-way routing - plan README: step 21 entry now describes the werkdock/ subdirectory path Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-01 06:21:29 +02:00
parent 3e1085fa52
commit 89de3e0378
8 changed files with 86 additions and 16 deletions
@@ -31,7 +31,7 @@ Observed in production on 2026-08-31: a restart of master rebuilt a commit from
 - A row on `/` (Latest) and `/history` stands for a recorded build.
 - A build *name* is the pool: the branch itself for the default build, `<branch>@<build>` for a named one.

-#### Scenario#000.01: The Branches view builds the branch's current origin head
+#### Scenario#3.01: The Branches view builds the branch's current origin head

 So that a restart answers "build this branch as it is", which is what a branch row means.

@@ -45,7 +45,7 @@ So that a restart answers "build this branch as it is", which is what a branch r
 - [BuildsApiControllerTest: "restart with atOriginHead builds the branch as it is now, not the recorded commit"](../../src/test/kotlin/de/hoennig/werkator/server/BuildsApiControllerTest.kt)
 - [UiControllerTest: "the branches view restarts at the branch's origin head, the latest view repeats the run"](../../src/test/kotlin/de/hoennig/werkator/server/UiControllerTest.kt)

-#### Scenario#000.02: The row keeps its build definition and its real branch
+#### Scenario#3.02: The row keeps its build definition and its real branch

 So that restarting a named build does not silently turn it into a different build.

@@ -58,7 +58,7 @@ So that restarting a named build does not silently turn it into a different buil

 - [BuildsApiControllerTest: "restart with atOriginHead keeps the recorded build definition and its real branch"](../../src/test/kotlin/de/hoennig/werkator/server/BuildsApiControllerTest.kt)

-#### Scenario#000.03: A branch that is gone from origin is refused by name
+#### Scenario#3.03: A branch that is gone from origin is refused by name

 So that a restart cannot quietly fall back to a commit the user did not ask for.

@@ -71,7 +71,7 @@ So that a restart cannot quietly fall back to a commit the user did not ask for.

 - [BuildsApiControllerTest: "restart with atOriginHead of a branch gone from origin is refused by name"](../../src/test/kotlin/de/hoennig/werkator/server/BuildsApiControllerTest.kt)

-#### Scenario#000.04: Latest and History still repeat the recorded run
+#### Scenario#3.04: Latest and History still repeat the recorded run

 So that the one view whose rows are runs keeps the behavior that fits them.

@@ -28,7 +28,7 @@ Step 17 (docs/plan/17-bwrap-build-runtime.md) defines a third build runtime behi
 - `bwrap.enabled` and `bwrap.rootfs` are pinned (host-set), so a branch's committed config cannot switch its own sandbox off or substitute a foreign rootfs.
 - `docker.enabled` and `bwrap.enabled` are mutually exclusive per branch; enabling both is rejected, not silently picked.

-#### Scenario#000.01: A bwrap build runs the command inside the sandbox as root
+#### Scenario#4.01: A bwrap build runs the command inside the sandbox as root

 So that the build is isolated from the host exactly as the native and Docker runtimes intend.

@@ -43,7 +43,7 @@ So that the build is isolated from the host exactly as the native and Docker run

 - [BwrapBuildRunnerTest](../../src/test/kotlin/de/hoennig/werkator/build/BwrapBuildRunnerTest.kt)

-#### Scenario#000.02: Git metadata mounts keep secrets out of the sandbox
+#### Scenario#4.02: Git metadata mounts keep secrets out of the sandbox

 So that builds can run read-only git commands but never reach the machine config or the control token.

@@ -57,7 +57,7 @@ So that builds can run read-only git commands but never reach the machine config

 - [BwrapBuildRunnerTest](../../src/test/kotlin/de/hoennig/werkator/build/BwrapBuildRunnerTest.kt)

-#### Scenario#000.03: A branch cannot turn its sandbox off or swap its rootfs
+#### Scenario#4.03: A branch cannot turn its sandbox off or swap its rootfs

 So that the pinned sandbox policy holds for builds a branch invents as well as for ones the host already knows.

@@ -70,7 +70,7 @@ So that the pinned sandbox policy holds for builds a branch invents as well as f

 - [ConfigLoaderTest](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)

-#### Scenario#000.04: The dispatcher routes builds to the bwrap runtime
+#### Scenario#4.04: The dispatcher routes builds to the bwrap runtime

 So that a bwrap-explicit branch builds inside the sandbox rather than natively.

@@ -89,7 +89,7 @@ So that a bwrap-explicit branch builds inside the sandbox rather than natively.
 - Werkator's own build runs the full test suite, which includes `TestcontainersSmokeTest`.
 - On a Docker-less host (the webspace, and the bwrap sandbox that builds there), that test must not fail the self-build.

-#### Scenario#000.05: The Testcontainers smoke test is skipped, not failed, without Docker
+#### Scenario#4.05: The Testcontainers smoke test is skipped, not failed, without Docker

 So that a Docker-less build of Werkator itself stays green.