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

[githubrobbi]

Playbook section: docs/dev/architecture/code_clean/world_class_rust_workspace_refactor_playbook.md § Phase 9.

Baseline anchor: Phase-0 final report docs/dev/baseline/2026-05-12/phase_0_final_report.md (local-only per .gitignore:135). Workspace commit at baseline: 710ca6044 (cast-cleanup, PR #186).

Goals (from playbook)

Audit the single build.rs site (uffs-cli) + the gen-hooks/gen-workflow codegen crates. Verify winresource RC_PATH workaround stays load-bearing on Linux cross-compile.

Current state (from Phase-0 baseline § 7 entry-point map)

Estimated cost: ~4 hours

Recommended entry points: uffs-cli/build.rs · scripts/ci/gen-hooks · scripts/ci/gen-workflow

Acceptance criteria

• Read playbook § Phase 9 Check / Refactor / Validate subsections
• Open a tracking branch (refactor/phase-9-...) and a draft PR
• Land work in surgical commits — preserve behavior and contracts (workspace rules: no suppression hacks, no relaxing tests, signed commits)
• Update tests where the refactor changes invariants
• Re-run just baseline-snapshot after merge and compare deltas against docs/dev/baseline/2026-05-12/
• Close this issue with a one-line summary of the LOC / API / risk-marker delta

Workspace policy reminders

1. No suppression hacks (#[allow] blankets, disabled lints, commented-out tests, cfg(any()) hiding)
2. Surgical correct fixes (root cause, not workaround)
3. Preserve behavior & contracts (public API stable unless CI proves it wrong)
4. Improve tests, do not dodge them

[githubrobbi]

Phase 9 closeout — Build scripts, macros, and code generation

Closes via PRs #299 / #300 (both merged 2026-05-19), with a post-closeout gap-closure PR #301.

Starting SHA: 8a672bba7 (post-PR #297 — Phase-8e + decisions-log backfill).
Closing SHA: aeb9807ac (post-PR #300 merge — original closeout).
Gap-closure SHA: ff8b897dd (post-PR #301 — 6 missed env vars + Set-by column + per-crate rustdoc).
Wall-clock: 2026-05-19 (single-day execution).

Delta summary

The audit at SHA 8a672bba7 found the workspace already textbook-clean by construction against the playbook §1013-1078 contract:

• 1 of 1 build.rs justified (class B2 + B3 — MSVC RC resource + Windows metadata embedding; load-bearing on Windows cross-compile).
• 0 proc-macro crates — deliberate non-introduction; documented as policy.
• 6 of 6 macro_rules! sites self-justified (5×M1 + 1×M2+M3) across uffs-mft.
• 4 of 4 codegen binaries have a drift detector (3×C1) or a documented one-shot rationale (1×C2).
• 36 distinct env vars across 7 scope categories — all inventoried.

Phase 9 therefore landed as 2 documentation + tooling PRs, zero source-code refactors:

PR	Sub-phase	What
#299	9a	scripts/dev/build_codegen_audit.sh — 572-LOC baseline inventory tool
#300	9c-9g	docs/architecture/code-quality/build_codegen_policy.md (383 LOC) + CONTRIBUTING.md §"Build, codegen, and env-var policy" (15 LOC)
#301	gap	6 missed env vars + Set-by column + per-crate # Environment rustdoc on 6 crate roots

What changed

• scripts/dev/build_codegen_audit.sh — 572-LOC inventory tool; mirrors clone_alloc_audit.sh (Phase 6) + trait_generic_audit.sh (Phase 7) + feature_dep_audit.sh (Phase 8). Reruns in < 5 s (no cargo invocation).
• docs/architecture/code-quality/build_codegen_policy.md — 383-LOC policy doc: B1-B3 build.rs taxonomy, M1-M3 macro taxonomy, C1-C2 codegen taxonomy, env-var registry (36 entries), per-crate registry, anti-patterns, audit cadence, decisions log.
• CONTRIBUTING.md — 15-LOC §"Build, codegen, and env-var policy" + link (mirrors the 4 existing policy cross-link sections).
• PR chore(build-codegen): Phase-9 gap closure — 6 missed env vars + Set-by column + per-crate rustdoc #301 (gap-closure): build_codegen_policy.md §5 env-var table gains a Set-by column; 6 env vars in uffs-mft and uffs-daemon that were missed in the initial audit added; # Environment rustdoc sections added to the 6 crate roots that read env vars.

What didn't change

• Zero source-code changes (beyond rustdoc //! additions in crate roots in PR chore(build-codegen): Phase-9 gap closure — 6 missed env vars + Set-by column + per-crate rustdoc #301).
• Zero clippy lints introduced.
• Zero deny.toml / Cargo.toml / Cargo.lock changes.
• Zero new #[allow(…)] or #[expect(…)] annotations.
• Zero CI gate additions (the existing manifest-drift, hooks-drift, fast-drift, workflow-drift gates already covered the Phase-9 surface; build_codegen_policy.md now cross-references them explicitly).

Verification highlights

• cargo check --workspace --all-features — green on every Phase-9 PR.
• cargo nextest run --workspace — 1,833 / 1,833 tests preserved (no regression from Phase 8).
• Pre-push gate green on every PR: chore(scripts): add build_codegen_audit.sh -- Phase 9a baseline tool (refs #298) #299 (102 s), docs(architecture): add build_codegen_policy.md + CONTRIBUTING cross-link (refs #298) #300 (4 s, docs-only fast path), chore(build-codegen): Phase-9 gap closure — 6 missed env vars + Set-by column + per-crate rustdoc #301 (91 s).

Wall-clock

Sub-phase	Plan	Actual
9a — Plan doc + baseline tool	~45 min	~50 min
9b — build.rs audit	~30 min	~15 min
9c — Proc-macro non-introduction policy	~20 min	~10 min
9d — Declarative macro audit	~30 min	~15 min
9e — Codegen binary inventory	~20 min	~15 min
9f — Env-var inventory	~1.5 h	~30 min
9g — build_codegen_policy.md + CONTRIBUTING	~30 min	~20 min
9h — Final report + closeout	~30 min	~20 min
Total	~4–5 h	~3 h

Follow-ups (out of Phase 9 scope)

1. Add # Environment rustdoc sections for the 6 crate roots that read env vars — done via PR chore(build-codegen): Phase-9 gap closure — 6 missed env vars + Set-by column + per-crate rustdoc #301 (gap-closure).
2. Optional: replace the 5 read_uN! macros in crates/uffs-mft/src/index/storage/deserialize.rs with a Cursor<&[u8]> struct + methods — deferred to next uffs-mft deserializer cleanup.
3. Annual workspace-wide build/macro/codegen/env-var audit re-run per build_codegen_policy.md §8.

Full report (local-only, gitignored): docs/dev/baseline/2026-05-19/phase_9_final_report.md.