docs: audit docs, comments, and the validate gate

[lesnik512]

Sweep of architecture/, README.md, and in-code comments against actual behavior, hunting inconsistencies, redundancies, bugs, and compaction candidates. Every finding was reproduced or grepped against the code, not read off the prose.

Full findings: planning/audits/2026-07-13-docs-and-gate-audit.md.

Headline

decisions/2026-07-10-reject-parse-dont-validate.md argues against a typed model on the grounds that validate() already owns every shape emit reads, so a malformed document "fails with UnsupportedComposeError, not a raw crash." That premise is false. environment, env_file, and volumes are structural keys with no KeySpec and no hand-written validator, so emit walks them raw:

Input	Today
environment: "FOO=bar"	AttributeError: 'str' object has no attribute 'items'
env_file: 5	TypeError: 'int' object is not iterable
volumes: "/data:/data"	destructured character-wise; reports anonymous volume 'd' must be an absolute path
--artifact nocolon	ValueError: not enough values to unpack out of emit.py:209

volumes also has a silent-corruption face: volumes: "/" is accepted and emits -v "/". Restoring the invariant makes the decision true again rather than reopening it, and needs no structural-key registry, so decisions/2026-07-12 also stands.

Also

• --add-host scope seam. Hosts are seeded document-wide (graph.hostnames) but extra_hosts is layered closure-scoped, and the two are conflict-checked against each other, so a service that never runs can veto a valid config. Every other emit-path aggregate (dns, sysctls, stores) is closure-scoped.
• Doc drift: a dead _MAP_FLAGS citation; glossary.md and supported-subset.md contradicting each other on KeySpec's arity (triple vs pair); 19 supported keys missing from the supported list; the README subset paragraph predating extends, secrets, configs, and resource limits.
• Compaction: Secrets and Configs are 123 lines of near-verbatim twins differing in exactly four ways. supported-subset.md goes 537 → ~300 lines with nothing lost.

Spawns four changes (two Full, two Lightweight). This PR is planning-only: no code changes.

🤖 Generated with Claude Code