[hartsock]

Summary

Makes ponytail and the UNIX philosophy the standard a change is judged against in this repo, rather than background reading.

CLAUDE.md → AGENTS.md, with CLAUDE.md symlinked back to it — the convention in herdr/ and the workspace root. One file, not two that drift. All existing content is preserved.

The two sources answer this project's two recurring questions: ponytail — how much code should exist; UNIX — what shape it takes.

What's in it

The ladder, with a worked example from this repo's own design work. "The monitor should clean up full disks" stops at rung 2: ~/bin/cleanup-stale-targets.sh already encodes the "is this safe to delete" judgement and has been exercised. The correct change is to invoke the existing reaper — one implementation of a destructive decision, never two.

Four UNIX rules named, because they settle most arguments in a daemon like this:

• Silence — a monitor that chatters trains its operator to ignore it, and an ignored monitor is worse than none, because it also consumes the belief that something is watching.
• Composition — alerts are structured events another tool can consume, not prose reachable only from a dashboard.
• Separation — thresholds live in config; one compiled into a collector is a bug. Already the shape here (Collector / AlertDispatcher + TOML).
• Repair — a collector that cannot reach its source says so, loudly.

Carve-outs made concrete, not generic:

• Anything that deletes is never brief and never autonomous.
• Detecting absence is first-class. In the 2026-09-09 dgx1 incident the kernel OOM-killed promtail, and the signature was nvidia-smi returning N/A plus a scrape gap — a rule that fires above 90% never fires when the exporter is already dead.
• A dispatcher that silently drops an alert manufactures the appearance of health.

One monitoring-specific corollary to ponytail's leave-a-check rule: a rule that cannot fire is worse than no rule, because it is a promise of coverage that will be believed.

The one real tension, named and resolved. UNIX says "build afresh rather than complicate old programs by adding new features"; ponytail's rung 2 says "already in this codebase? reuse it." Resolution: reuse a component; never widen something that does a different job until it covers yours. Adding a tenth responsibility to monitor-core because it is already there violates "one thing well" and produces more code than a new crate would.

Also corrects the crate listing — it said five crates; there are ten. Each name is already a sentence about one responsibility, which is the evidence this is understood rather than aspirational.

Test plan

Documentation only, no code change. The pre-push hook's full just check (fmt + clippy -D warnings + workspace tests) ran green.

CLAUDE.md verified as a symlink resolving to AGENTS.md.

🤖 Generated with Claude Code