STATUS.md: a plain-language operator page, and today's four decisions recorded

Documentation only — no code, no box, no build.

STATUS.md (repo root, 652 words / 67 lines): what works · what's broken ·
what we're working on · waiting on you · changed since. A VIEW of
OPEN-ITEMS.md, holding nothing of its own; not CONTEXT.md, and both files
now say why they stay separate. No R-n is the subject of a sentence —
identifiers are bracketed pointers only.

CONTEXT.md S-5 records the four operator decisions taken 2026-08-02
(D-a … D-d), none of them implemented:
  D-a merge mp1 into mp0 rather than resize it — before any external
      install, and D-c ships in the same step        → R-165
  D-b desired/observed app state in its own store, with the state-store
      safety rule verbatim                           → R-166 (BLOCKED)
  D-c customer fill warning + operator backup-failure alert → R-167
  D-d only DooPlex and Peti's box are protected      → target-selection.md

R-163 RE-FRAMED, not closed: the sizing question is withdrawn rather than
answered; the row survives as the record of the constraint until R-165
lands. R-156's papra referral RESOLVED — deployed nowhere, so the template
fix strands nothing; the docker ps evidence is recorded with its
provenance and its scope limit.

target-selection.md: two protected machines, everything else disposable.
ep0 is no longer Tier 2 but is not scratch (it holds the only off-premises
copy of real customer data) — flagged for explicit operator confirmation.
The demo-box backup-target fence drops from prohibition to stated cost,
because D-d spends that reference anyway.

CLAUDE.md gains an End-of-session checklist carrying the STATUS.md
maintenance rule and "a finding goes in OPEN-ITEMS.md first".
This commit is contained in:
2026-08-02 14:20:29 +02:00
parent 260a8f6e58
commit e994bf35d2
6 changed files with 314 additions and 146 deletions
+52
View File
@@ -7,6 +7,14 @@
> Read it first; `ROADMAP.md` holds the full history and reasoning behind each item. **`REPORT.md` is
> per-session and overwritten — nothing durable may live only there.**
> **This file is NOT `STATUS.md`, and the two must not be consolidated** (2026-08-02). `CONTEXT.md`
> is technical working state written for Claude Code: rulings with their mechanisms, file paths,
> version numbers, the reasoning a session needs before it touches code. Root `STATUS.md` is written
> for the **operator** — technical, but not in the code and not a reader of the audits — in plain
> language, one screen, no identifiers in the prose. Same subjects, different readers; merging them
> would make one of the two audiences stop reading. `STATUS.md` is also a **view of `OPEN-ITEMS.md`**
> and holds nothing of its own; this file does hold its own content, namely the standing rulings below.
## Standing rulings
**S-1 — N.5 gains a third leg: architecture docs are same-session coupled (2026-07-26, R-81).**
@@ -79,6 +87,50 @@ Five decisions were deliberately **left open for the operator** and are recorded
stated**) · Hetzner as a single failure domain · and `local` vzdump sharing a physical device with
the guest it backs up. Gaps minted the same session: **R-102 … R-108**.
**S-5 — four operator decisions taken in discussion on 2026-08-02, recorded before anything is
built.** They existed only in conversation, which is the condition the standing rules were written
against. Labels are the ones used in the discussion (**D-a … D-d**) and are deliberately kept
distinct from S-3's `D1…D6`. **None of a, b or c is implemented by the session that recorded them**;
their work is carried as backlog rows (**R-165, R-166, R-167**), not as prose here.
- **D-a — the dedicated backup partition is MERGED AWAY, not resized.** The appliance's system drive
carries the OS, a **50 G** docker area (`mp0`) and a separate **20 G** area holding local recovery
units (`mp1`; demo-hp's guest 9201 ships exactly that). The decision is to **merge the backup area
into the large data area** so local backups share space with app data and the ceiling stops
existing — deliberately *not* to pick a larger number, because a larger number is the same wall
further away. **Two conditions, recorded with the decision, not as commentary:** (1) it changes the
**disk layout**, so it must land **before any external install** — after that, every deployed box
is a migration; (2) it **removes a wall that currently fails safely**, so the storage monitoring of
**D-c** must ship **with** it, never after. Closes the sizing question in **R-163**, which is
**re-framed rather than answered with a ratio** and is not closed until the merge lands. Work:
**R-165**.
- **D-b — app state gets a desired/observed model with its own store.** Three kinds of information,
deliberately separated: **desired** (running, or stopped because the customer said so) stays in
`app.yaml` with that app's other settings; **in-flight operations** ("a backup started and has not
reported finishing") are **persisted**, written before the operation starts and after it ends, so
an interruption is visible after a reboot; **observed** (unhealthy, restarting, drive gone) is
**not** persisted and is rebuilt by looking. The last two live in a **state store separate from
`app.yaml`**, so frequent writes never touch a file holding deploy settings and secrets.
**Binding safety rule, verbatim:** *losing the state store must never cause an app to be deleted,
restarted wrongly, or reported healthy when it is not — the worst acceptable outcome is re-running
a backup that already ran.* The controller must also check **every container of an app**, so a
partly-dead app cannot read as healthy (F-CRIT-1's shape). **Two things to establish before this is
specced, not now:** whether the crash-safe journal already in the backup code covers the in-flight
case — *it may already exist and merely be unwired, which has been the answer four times* — and
whether the existing SQLite store is reachable from this code path. Work: **R-166**.
- **D-c — storage monitoring and backup alerts.** Two pieces: a warning to the **customer** as a
drive fills, **before** anything fails; and a failure alert to the **hub/operator** when any backup
fails for any reason, lack of space included. **Prerequisite for D-a** — see that decision's
condition (2). Subsumes and widens **R-158**, which is the same alert one tier down; R-158 stays as
the named seam and is not duplicated. Work: **R-167**.
- **D-d — which machines are protected: DooPlex and Peti's box, and nothing else.** DooPlex because
it holds Gitea, the hub, the backups and the registry — everything else rebuilds from it. Peti's
box because there is a real person behind it. **Every other box, both demo boxes included, is
disposable and may be broken or reinstalled freely.** The earlier caution was costing sessions and
pushing work onto DooPlex — the one machine that should never host it — so the ruling is a
correction, not a relaxation. `documentation/runbooks/target-selection.md` updated the same session
(2026-08-02); no backlog row, the decision *is* the change.
- **2026-07-27 — R-85: the DR tier is restore-tested UNATTENDED, and its failure is HEARD.** agent
v0.104.0 + hub v0.77.0. R-82 proved a PBS restore round-trip **by hand**; three defects kept the
unattended path from covering it. (a) `buildRestoreTestScheduler` built ONE runner on