chore(agents): per-category generators must prune their output and guard on empty input

Author: ChipWolf

home/dot_agents/AGENTS.md

@@ -21,6 +21,7 @@ These constraints are unconditional. Apply them without being asked.
 - **When a project's prose and its enforcement disagree, the enforcement wins.** A skill, README, or comment can drift from the CI gate, linter, or schema that actually rejects your change (e.g. a documented file layout that a CI guard now forbids adding). Before following a documented process that touches generated or tool-owned files, confirm it against the mechanism that will gate the PR; if they conflict, satisfy the gate and fix the stale doc in the same effort.
 - **Make the failure reproduce without a human before iterating on fixes.** When verification needs a human round-trip (someone wearing a headset, clicking a UI, plugging in hardware), build an autonomous repro first: a self-test that runs the failing path at startup, auto-dismissal of interactive gates, retry loops around known-flaky launches, and a streamed log capture started before launch so rotation can't eat the evidence. Each fix-then-ask-the-human cycle costs minutes and goodwill; the harness pays for itself by the second iteration.
 - **Stub APIs permissively, capture narrowly.** When a loopback or mock server intercepts an API client to capture requests, return a permissive default (`200 {}` or a minimal valid response object) for unhandled paths, and only persist the body for the specific path you care about. Real clients often probe other endpoints (capability checks, model lookups, version handshakes) before sending the request you want to intercept; a 404 on a pre-flight probe makes them bail before reaching the target path. Reserve 404 for paths that genuinely must not exist.
+- **A generator that writes one file per category must own and prune its whole output set.** Codegen that emits `<category>.tf` / `<category>.json` from live data typically writes only the files it has content for, so deleting the last item of a category means nothing rewrites that file and the stale one survives, still declaring things that no longer exist. In an IaC round-trip that silently reverses the deletion: the config still declares the resources while their import blocks are gone, so the next plan recreates exactly what you just deleted. Track the filenames written each run and remove the ones the generator owns but did not emit. Pruning then makes an empty input destructive (zero items of every category reads as every category emptied, so every file gets deleted), so guard the entry point on the input actually being present. Verify by running the generator against a second, unrelated target whose input you did not refresh: if that target's files vanish, the guard is missing.
 - **A test suite must survive a fresh clone.** When adding tests that read committed fixtures or goldens, confirm the inputs are actually tracked (`git ls-files <fixture-path>`), then run the suite from a fresh clone or worktree before declaring it done. Broad ignore patterns (`dumps/`, `build/`, `*.json`) silently swallow fixture inputs, leaving a suite that only passes on the authoring machine where the untracked files linger; every other checkout fails with a misleading "input missing" error. If fixture inputs must stay untracked (secrets, size), the test itself must regenerate them, and that regeneration must be code, not a docstring claim.
 - **One sample isn't a measurement.** A single run, repro, or test pass doesn't characterise a noisy phenomenon. Before claiming X differs from Y (faster, more reliable, fixed, broken), gather enough samples to see variance, then report it. Applies anywhere outcomes vary: perf benchmarks, flaky tests, network calls, CI on managed infra, A/B comparisons. If you've only got one data point, mark the conclusion provisional, do not open a PR or change production on it.
 - **Clone, don't curl.** When reading another repository's source, `git clone` first and read locally. Never `curl` GitHub API endpoints or `curl` raw file URLs to read source, even when docs don't render. (Using `WebFetch` for public documentation pages is fine.)