chore: 2026-11-09 audit plan (commands, modules, docs, specs) #98

Context

Audit of rootfiles on 2026-11-09 (v0.18.1, main at 949d449): command surface, internal packages, docs and specs. Findings were cross-checked against the code; items marked inferred in each issue are re-verified at implementation. Each child issue body is its spec. Implementation starts only on the owner's go-ahead, per issue.

Plan

Phase 1: safety and correctness (small, independent, ship first)

• fix(cli): redact secrets from audit logs and let update --check run without root #88 redact secrets from audit logs; update --check without root
• fix(firewall): block SSH and UFW changes when firewall state is unknown #89 block SSH/UFW changes on unknown firewall state; one firewall parser
• fix(profiles): remove site-specific and no-op values from embedded profiles #90 remove the site-specific address and no-op keys from embedded profiles (breaking, owner decision inside)

Phase 2: specs and docs foundation (docs only, can run beside phase 1)

• docs(specs): per-feature design specs covering every source file #97 per-feature specs covering every source file (later PRs update the owning spec)
• docs: restructure README and docs into an entry point and a reference set #96 README as entry point, reference set under docs/, drift tests for commands and config keys

Phase 3: CLI and module correctness

• fix(cli): reject ignored root flags and validate capabilities on every mutating command #91 reject ignored root flags; capability gate on every mutating command
• fix(module): route writes through Runner, align Check with Apply, keep tests off the host #93 writes through Runner, Check/Apply agreement, host-free tests
• feat(cli): consistent flags, deduplicated commands and accurate help #92 consistent flags, duplicate commands, help text (deprecation aliases)

Phase 4: cleanup

• refactor: share duplicated helpers and route output through ui #94 shared helpers, single status collector, output through ui
• chore: remove dead code and update outdated defaults #95 dead code and outdated defaults (owner decisions inside)

Related: #87 (done) (Go toolchain and CI pinning) is not repeated in these issues.

Order and overlap

• fix(firewall): block SSH and UFW changes when firewall state is unknown #89 before fix(cli): reject ignored root flags and validate capabilities on every mutating command #91 and refactor: share duplicated helpers and route output through ui #94 (all touch firewall/runtime code). fix(module): route writes through Runner, align Check with Apply, keep tests off the host #93 before refactor: share duplicated helpers and route output through ui #94 (helpers build on the Runner-only writes).
• docs: restructure README and docs into an entry point and a reference set #96 and docs(specs): per-feature design specs covering every source file #97 touch only docs; code PRs after them update the affected doc and spec in the same PR.
• Releases: group phase 1 into one minor release; fix(profiles): remove site-specific and no-op values from embedded profiles #90, feat(cli): consistent flags, deduplicated commands and accurate help #92 and chore: remove dead code and update outdated defaults #95 need ### Action needed lines.

Open owner decisions

• fix(profiles): remove site-specific and no-op values from embedded profiles #90: drop the dgx VLAN address now (breaking) or after one deprecation release.
• fix(cli): redact secrets from audit logs and let update --check run without root #88: exit 2 from update --check when an update exists.
• feat(cli): consistent flags, deduplicated commands and accurate help #92: remove user passwd --suffix after deprecation; tunnel install as an alias of setup.
• chore: remove dead code and update outdated defaults #95: rename the rootfiles-v2 header (one-time drift); drop the docker-compose v1 symlink.

Out of scope

• New features beyond what the audit found missing (schedule status, fleet selection gaps are in feat(cli): consistent flags, deduplicated commands and accurate help #92).

Status 2026-11-10

• Merged: ci: improvement plan from the 2026-11-07 CI survey (toolchain pinning and required checks) #87 (PR ci: pin Go toolchain and require aggregate validation #99), fix(cli): redact secrets from audit logs and let update --check run without root #88 (fix(cli): redact credentials and allow unprivileged update checks #100), fix(cli): reject ignored root flags and validate capabilities on every mutating command #91 (fix(cli): scope flags and validate native mutation capabilities #102), fix(profiles): remove site-specific and no-op values from embedded profiles #90 (fix(profiles)!: keep site-specific and no-op values out of the embedded profiles #101), fix(firewall): block SSH and UFW changes when firewall state is unknown #89 (fix(firewall): block reachability changes on unknown firewall state #103), fix(ssh): run the Rocky SSH firewall check only when the port changes #104 (fix(ssh): scope Rocky firewall checks to effective port changes #106), docs(specs): per-feature design specs covering every source file #97 (docs(specs): per-feature design specs covering every source file #107), fix(module): route writes through Runner, align Check with Apply, keep tests off the host #93 (fix(modules): preserve dry runs and align Check with Apply #114), chore: remove dead code and update outdated defaults #95 (refactor: remove dead code without managed-file churn #118), feat(cli): consistent flags, deduplicated commands and accurate help #92 (feat(cli): consistent flags, deduplicated commands and accurate help #105), docs: restructure README and docs into an entry point and a reference set #96 (docs: restructure README and docs into an entry point and a reference set #116), refactor: share duplicated helpers and route output through ui #94 (refactor(module): share managed-file and systemd primitives #120, refactor: share module metadata and common value helpers #121, refactor(cli): share report collection and version helpers #122, refactor: route command output through explicit writers #123).
• ci-ok is now the required status check on main.
• Open: chore(release): staged fleet rollout of the epic #98 release without disruption #115 (release and staged fleet rollout, needs the owner's go-ahead), follow-ups test(tenant): diagnose data mount visibility after mount-unit restart #117 (tenant remount test flake) and security: harden existing destinations for config init captures #119 (config init existing-destination hardening).