backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

docs/internal/agents/doc-hygiene.md

@@ -0,0 +1,29 @@
+# Documentation Hygiene & Spec Rules
+
+Purpose: keep `docs/internal` lean, discoverable, and aligned with active work. Use this when creating or updating any internal spec/plan.
+
+## Canonical sources first
+- Check existing coverage: update an existing spec before adding a new file. Search `docs/internal` for keywords and reuse templates.
+- One source of truth per initiative: tie work to a board entry and, if multi-day, a single spec (e.g., `initiative-*.md` or a plan under `docs/internal/plans/`).
+- Ephemeral task lists live in `z3ed agent todo` or the coordination board, not new Markdown stubs.
+
+## Spec & plan shape
+- Header block: `Status (ACTIVE/IN_PROGRESS/ARCHIVE)`, `Owner (Agent ID)`, `Created`, `Last Reviewed`, `Next Review` (≤14 days by default), and link to the coordination-board entry.
+- Keep the front page tight: Summary, Decisions/Constraints, Deliverables, and explicit Exit Criteria. Push deep design notes into appendices.
+- Use the templates: `initiative-template.md` for multi-day efforts, `release-checklist-template.md` for releases. Avoid custom one-off formats.
+
+## Lifecycle & archiving
+- Archive on completion/abandonment: move finished or idle (>14 days without update) specs to `docs/internal/agents/archive/` (or the relevant sub-archive). Add the date to the filename when moving.
+- Consolidate duplicates: if multiple docs cover the same area, merge into the newest spec and drop redirects into the archive with a short pointer.
+- Weekly sweep: during board maintenance, prune outdated docs referenced on the board and archive any that no longer have an active entry.
+
+## Coordination hygiene
+- Every spec links back to the coordination board entry; every board entry points to its canonical spec. No parallel shadow docs.
+- Release/initiative docs must include a test/validation section instead of ad-hoc checklists scattered across files.
+- When adding references in other docs, point to the canonical spec instead of copying sections.
+
+## Anti-spam guardrails
+- No gamified/leaderboard or duplicative status pages in `agents/`—keep status in the board and the canonical spec.
+- Prefer updating `docs/internal/README.md` or the nearest index with short summaries instead of creating new directories.
+- Cap new doc creation per initiative to one spec + one handoff; everything else belongs in comments/PRs or the board.
+- Filenames: avoid ALL-CAPS except established anchors (README, AGENTS, GEMINI, CLAUDE, CONTRIBUTING, etc.); use kebab-case for new docs.