felhom-controller/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 @ d0c70a7da6f4060422a545cea2396f9df5f7d61f (v0.98.3)

What was done

• REUSE.md created at the repo root (210 lines): the curated reuse map — canonical helpers (62 rows across 9 domains), canonical patterns (10), dangerous lookalikes (8), test seams + cross-repo edges, extension points, and observed duplication (12 clusters, recorded NOT fixed).
• Sourced from a full code sweep (1174 non-test func declarations scanned; call-site counts + body reads per candidate; mandatory trap sweep over --delete/os.RemoveAll/mkfs/etc.). Every entry cites file + symbol, verified in code — not copied from README/docs.
• CLAUDE.md: two hook lines added — "See REUSE.md before writing new code" (read-first pointers) and end-of-session checklist item 7 (update REUSE.md in the same commit as a shared helper change). 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-controller → OK [felhom-controller]: 65 cited paths, all exist (the check caught and fixed one wrong citation: the template/emoji gate scripts live at controller/scripts/, not scripts/).

Notable traps recorded (§3 highlights)

rsyncMirror (--delete, tier-2 only) vs rsyncCopy; raw os.RemoveAll vs the ProtectedHDDPaths-gated delete path; fresh agentapi.New per request (the v0.74.0 conn-leak incident); timeAgo on string timestamps; DumpAppVolumes on a running DB app; no-timeout composeExec for new long-running calls.

Observations (NOT acted on)

• Atomic-write helper exists ×4 (+1 inline) with differing semantics; two of them have a deliberate NON-atomic bind-mount fallback — a convergence candidate needs care.
• util.TruncateStr (rune-safe) has 1 caller while the byte-based stacks.truncateStr twin is the widely used one.
• 5 JSON writers / 3 envelope shapes; 6 dir-size implementations; 2 CSRF implementations (intentional but unlabeled). Full list in REUSE.md §6.
• CLAUDE.md "Workspace layout" lists ~7 internal packages; code has ~30. Its bare-metal /opt/docker deploy steps are superseded by the 9201 bootstrap mechanism (already flagged in-file). A CLAUDE.md refresh is a separate task.

Cross-repo summary + full sweep counts: felhom.eu/REPORT.md.