[playbook-phase-9] Build scripts, macros, and code generation

[githubrobbi]

Goal

Execute Phase 9 of world_class_rust_workspace_refactor_playbook.md (\u00a71013-1078, local-only): reduce hidden magic, keep builds deterministic and portable, isolate complicated compile-time behavior.

Recon (at SHA 8a672bba7, post-Phase-8e + #297 closeout)

• build.rs files: 1 (crates/uffs-cli/build.rs, 108 LOC, MSVC-gated /DELAYLOAD + winresource).
• Proc-macro crates: 0 (no proc-macro = true anywhere).
• Declarative macro_rules!: 6 across 2 files (5 in uffs-mft::index::storage::deserialize + 1 in uffs-mft::platform::drive_letter), all pub(crate)-scoped or function-local.
• Workspace-internal codegen binaries: 4 (scripts/ci/{gen-hooks, gen-workflow, manifest-audit} + scripts/ci-pipeline). 3 of 4 have drift detectors wired into pre-push + pr-fast.yml.
• Env vars consumed: ~26 distinct (4 Cargo build-time, ~7 standard runtime, ~16 UFFS_* knobs).
• include_bytes! / include_str!: 6 use-sites, all leaf-data (no codegen-pipeline magic).

Phase 9 is

A predominantly verification + documentation + audit-tool phase (mirroring Phase 6 / 7 / 8 patterns for UFFS). The existing posture is already textbook-clean by construction; Phase 9's value is the per-site justification record + the policy doc + the audit tool that catches future drift.

Sub-phase plan (~4-5 h total)

#	Sub-phase	Est.	Deliverable
9a	Plan doc + baseline tool (scripts/dev/build_codegen_audit.sh)	45 min	PR
9b	build.rs audit	30 min	Findings-only OR drift PR
9c	Proc-macro non-introduction policy	20 min	Folded into 9f
9d	Declarative macro audit	30 min	Findings-only OR drift PR
9e	Codegen binary inventory	20 min	Folded into 9f
9f	Env-var inventory + # Environment rustdoc + build_codegen_policy.md + CONTRIBUTING	1.5 h + 30 min	PR
9h	Final report + closeout	30 min	Doc-only (local) + issue closure

Acceptance (23 criteria, full table in local plan \u00a72)

Key ones:

• Every build.rs justifies itself per playbook \u00a71041-1046.
• Every macro_rules! justifies itself per playbook \u00a71062-1064.
• Every codegen step has a drift detector OR a documented one-shot rationale.
• Every env var carries a registry entry (name / scope / type / default / where read / semver class).
• All existing CI gates green: lint-ci, lint-ci-no-default (Phase 8e), tests, cargo-machete, cargo-deny.
• New build_codegen_policy.md landed in docs/architecture/code-quality/ + CONTRIBUTING.md cross-link.
• New scripts/dev/build_codegen_audit.sh landed.

Companion docs

• Plan: docs/dev/architecture/code_clean/phase_9_build_scripts_macros_codegen_implementation_plan.md (local-only \u2014 276 LOC).
• Playbook source: docs/dev/architecture/code_clean/world_class_rust_workspace_refactor_playbook.md \u00a71013-1078 (local-only).
• Predecessor: phase_8_* plan + final report (Phase 8e closeout 2026-05-19).
• Sibling policies: panic_policy.md (5e), allocation_policy.md (6f), trait_policy.md (7g), dependency_policy.md (8c).

Rule-1 adherence

Zero #[allow] introductions; zero suppression hacks. The single #[allow(clippy::expect_used)] in crates/uffs-cli/build.rs is the documented exception per panic_policy.md \u00a71 (build scripts are out of scope of the runtime panic policy). Phase 9 confirms the rationale is current; does not relax it.

[githubrobbi]

Phase 9 closeout (2026-05-19)

\u2705 CLOSED. All 23 acceptance criteria green. Final closing SHA: aeb9807ac (post-PR #300 merge).

PRs landed

• #299 (9a) \u2014 scripts/dev/build_codegen_audit.sh baseline inventory tool (572 LOC). MERGED 0433065c7.
• #300 (9c-9g) \u2014 docs/architecture/code-quality/build_codegen_policy.md (383 LOC) + CONTRIBUTING.md cross-link. MERGED aeb9807ac.

Findings-only sub-phases (local-only docs)

• 9b \u2192 phase_9_build_audit_findings.md: uffs-cli/build.rs is class B2 + B3 (PE resource embedding + /DELAYLOAD link args). No drift.
• 9d \u2192 phase_9_macro_audit_findings.md: all 6 macro_rules! sites justified (5\u00d7M1 + 1\u00d7M2+M3). No drift. 1 refactor candidate deferred.
• 9e \u2192 phase_9_codegen_inventory.md: all 4 codegen binaries audited (3\u00d7C1 drift-detected + 1\u00d7C2 orchestrator). No drift.

Concrete deltas

Surface	Count	Verdict
build.rs files	1	All justified
Proc-macro crates	0	Deliberate posture documented
macro_rules! declarations	6	All justified (0 M-X violations)
Codegen binaries	4	All drift-detected or C2-justified
Env vars consumed	36	All in policy doc \u00a75 registry
Source code changes	0	doc-only phase
Clippy lints added	0	identical posture to entry
Gates added	0	existing *-drift gates already cover the surface

Wall-clock

~3 h actual vs ~4-5 h plan estimate. Same pattern as Phase 5/6/7/8: the strict-lint + drift-detector posture established by earlier phases pre-validated ~95% of the audit surface.

Companion docs

• Plan: docs/dev/architecture/code_clean/phase_9_build_scripts_macros_codegen_implementation_plan.md (local-only \u2014 \u00a711 final outcome populated).
• Final report: docs/dev/baseline/2026-05-19/phase_9_final_report.md (local-only).
• Policy doc: docs/architecture/code-quality/build_codegen_policy.md (tracked, 383 LOC).
• Audit tool: scripts/dev/build_codegen_audit.sh (tracked, 572 LOC).

Follow-ups (out of Phase 9 scope)

1. Per-crate # Environment rustdoc sections (6 crates) \u2014 mirrors Phase 8b PR docs(features): document feature contracts per playbook §988 (Phase 8b, refs #195) #293 split; defer as 9-followup PR.
2. Optional read_uN! macros \u2192 Cursor struct refactor \u2014 deferred to next uffs-mft deserializer cleanup.
3. Annual audit re-run per build_codegen_policy.md \u00a78.
4. Phase 10 \u2014 Async, concurrency, and shared state discipline (playbook \u00a71082-1180) is next.