felhom-agent/REPORT.md

REPORT — docs: REUSE.md introduced (cross-repo reuse map)

Date: 2026-07-03 · Class: docs-only (no code change, no version bump, no deploy) Baseline: main @ 0db09bf34fe2eff4b80ac77ed19afa18aef7675f (v0.61.0)

What was done

• 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.