admin
eda33400da
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
# 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`.
|