docs: CLAUDE.md refresh — version narrative removed, layout completed (17 pkgs + opsign), skill pointers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
2026-07-03 11:25:56 +02:00
parent 2a024b6039
commit 3e760a559a
4 changed files with 116 additions and 115 deletions
@@ -1,44 +1,19 @@
-# REPORT — docs: REUSE.md introduced (cross-repo reuse map)
+# REPORT — docs: CLAUDE.md refresh (stable orientation, complete layout)

-**Date:** 2026-07-03 · **Class:** docs-only (no code change, no version bump, no deploy)
-**Baseline:** `main` @ `0db09bf34fe2eff4b80ac77ed19afa18aef7675f` (v0.61.0)
+**Date:** 2026-07-03 · **Class:** docs-only (no code, no version bump, no deploy)
+**Baseline:** `main` @ `2a024b6039` (v0.61.0 live on felhom-pve — unchanged)

-## What was done
+CLAUDE.md rewritten (diffstat: +86/−71):
+- Deleted the "Current: v0.31.0" narrative + per-slice history (stale by 30 versions; current state
+  lives in CONTEXT.md + CHANGELOG top — standing rule: no version-pinned state in CLAUDE.md).
+- Layout completed: all 17 `internal/` packages + `cmd/felhom-opsign` (old file listed 9; verified
+  against the tree). Missing were: capability, desired, escrow, guesthook, lanresolver, localapi,
+  provision, signedjobs.
+- Build/deploy compressed to a summary table + `felhom-build-deploy` skill pointer. Facts re-verified
+  live on felhom-pve: non-root `felhom-agent` service user, `ExecStart=/usr/local/bin/felhom-agent
+  --config /etc/felhom-agent/agent.json`, sudoers at `/etc/sudoers.d/felhom-agent`, live `--version`
+  = 0.61.0.
+- Kept verbatim: the Proxmox-model load-bearing rules (API-first, 3-exception root-CLI fence, UPID
+  WaitTask, TLS pinning, privsep gotcha), demo-host section, trunk-based + RUNBOOK conventions.

- **`REUSE.md`** created at the repo root (160 lines): canonical helpers (48 rows — allowlisted
-  exec/sudoers surface, disk/format safety with each guard named, durable-id seams, atomic stores,
-  local-API plumbing, proxmox/hub/PBS/provisioning), canonical patterns (12), dangerous lookalikes
-  (10), test seams + cross-repo edges, extension points, observed duplication (7 clusters, NOT fixed).
- Sourced from a full code sweep (702 non-test `func` declarations scanned; mandatory trap sweep).
-  Trap-sweep result: the only `--delete` in Go code is `pct set --delete mpN` (DetachBind, itself a
-  §3 trap vs `DetachDrive`); `os.RemoveAll` only on escrow temp workdirs; no wipefs/sfdisk/dd.
- **`CLAUDE.md`**: two hook lines — "See `REUSE.md` before writing new code" and the same-commit
-  maintenance rule. No other CLAUDE.md edits.
- `CHANGELOG.md` entry (no version number) + `CONTEXT.md` note.
-
-## Verification
-
-`python felhom.eu/scripts/reuse_refs_check.py e:/git/felhom-agent` →
-`OK [felhom-agent]: 57 cited paths, all exist`.
-
-## Notable traps recorded (§3 highlights)
-
-Acting on `req.Device` after inspection (AGENT-001 TOCTOU) vs the re-resolve seams; raw `mkfs.*`
-(no longer sudoers-allowlisted) vs `SudoHostOps.Format`; `uuid:` vs `byid:`/`byuuid:` durable-id
-scheme confusion (F20-BUG2); `MemoryNonceStore` on a real host; adding methods to
-`proxmox.Privileged` (breaks the 3-exception fence); mutating outside gate/queue/journal; copying
-the pool-blind stale-lock scan (open audit A1).
-
-## Observations (NOT acted on)
-
- **CLAUDE.md is badly stale**: says "Current: v0.31.0" and its Layout omits `localapi`,
-  `signedjobs`, `escrow`, `capability`, `guesthook`, `lanresolver`, `desired`, `provision` — all
-  live at v0.61.0. A CLAUDE.md refresh is a separate task.
- Dead config knobs: `storage.Binaries.MkfsExt4/MkfsXfs` defined+defaulted but never executed by
-  non-test code (`Format` only execs `MkfsGuarded`).
- Acknowledged mirror: `antiRetargetResolveExpect` re-implements `WipeExecutor.Execute` steps 1–3
-  ("mirrors" comments in both) — a change to one must touch both.
- Duplication clusters (2× lsblk parsers, 2× smartctl paths, 3× atomic JSON store, 4× run() helper,
-  several /proc mount readers) recorded in REUSE.md §6.
-
-Cross-repo summary + full sweep counts: `felhom.eu/REPORT.md`.
+Consolidated cross-repo report: `felhom.eu/REPORT.md`.