[playbook-phase-8] Feature flags and dependency hygiene

[githubrobbi]

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

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)

Verify the 3 feature-using crates (uffs-cli, uffs-client, uffs-mcp) have minimal feature surfaces. cargo-hack already exercises the feature matrix in Tier-2 CI.

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

Estimated cost: ~2 hours

Recommended entry points: uffs-cli (default=[], mcp-http-probe) · uffs-client (default=["async"]) · uffs-mcp (default=["streamable-http"])

Acceptance criteria

• Read playbook § Phase 8 Check / Refactor / Validate subsections
• Open a tracking branch (refactor/phase-8-...) 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 8 closeout

Closes via PRs #292 / #293 / #294 (all merged 2026-05-19).

Starting SHA: 33f22b572 (post-Phase-7).
Closing SHA: b867f3395 (post-PR #294).
Wall-clock: 2026-05-19 (single-day execution).

Delta summary

The audit at SHA 33f22b572 found the workspace already textbook-clean by construction against the playbook §926-1004 contract:

• 3 feature flags total across the 14-crate workspace (the other 11 crates are intentionally feature-less).
• 0 unused direct deps (cargo machete already green).
• 0 orphan optional deps (every optional = true already reaches a dep:<name> activation + a #[cfg(feature)] use-site).
• 12 cross-version duplicate-version dep groups — 4 already in deny.toml [bans].skip-tree with explicit rationale + 8 accepted by the workspace-wide multiple-versions = "warn" posture (RustCrypto family + polars-transitive rand_*).

Phase 8 therefore landed as 3 documentation + tooling PRs, zero refactors:

PR	Sub-phase	What
#292	8a	scripts/dev/feature_dep_audit.sh (723 LOC)
#293	8b	# Features rustdoc sections + Cargo.toml [features] block comments per playbook §988 contract in the 3 feature-using crates
#294	8c	docs/architecture/code-quality/dependency_policy.md (334 LOC) + CONTRIBUTING.md cross-link (15 LOC)

What changed

• uffs-cli, uffs-client, uffs-mcp each gained a # Features rustdoc section.
• docs/architecture/code-quality/dependency_policy.md is the fourth tracked code-quality policy doc (joining panic_policy.md from Phase 5e, allocation_policy.md from Phase 6f, trait_policy.md from Phase 7g).
• CONTRIBUTING.md gained a ## Feature flag and dependency policy section.
• scripts/dev/feature_dep_audit.sh is the third workspace inventory tool (joining clone_alloc_audit.sh from Phase 6 and trait_generic_audit.sh from Phase 7).

What didn't change

• Zero source-code changes beyond rustdoc //! additions in 3 crate roots.
• Zero Cargo.toml content changes \u2014 only feature-block comments were rewritten (block contents byte-identical).
• Zero new clippy lints.
• Zero deny.toml changes.
• Zero new #[allow(\u2026)] or #[expect(\u2026)] annotations \u2014 Phase-8 rule 1 ("no suppression hacks") satisfied.

Verification highlights

• cargo check --workspace --all-features \u2014 green on every Phase-8 PR.
• cargo nextest run --workspace \u2014 1,833 / 1,833 tests preserved.
• cargo machete \u2014 0 unused deps.
• cargo deny check \u2014 all 4 categories green.
• Pre-push gate green on every PR: chore(scripts): add feature_dep_audit.sh — Phase 8a baseline tool (refs #195) #292 95 s, docs(features): document feature contracts per playbook §988 (Phase 8b, refs #195) #293 91 s, docs(architecture): add dependency_policy.md and CONTRIBUTING.md cross-link (Phase 8c, refs #195) #294 4 s (docs-only fast path).

Wall-clock

Sub-phase	Plan	Actual
8a	~30 min	~50 min
8b	~1 h	~25 min
8c	~45 min	~30 min
8d	~30 min	~20 min
Total	~2.5\u20133 h	~2\u20132.5 h

Follow-ups (out of scope; not blocking Phase 9)

1. Backfill PR chore(lints): activate 4 Phase-7 trait/generic/dispatch lints (Phase 7f, refs #287) #291 reference for the Phase-7f "TBD" row in trait_policy.md:193.
2. Re-run feature_dep_audit.sh --with-cargo after the next polars commit-pin bump; refresh dependency_policy.md §5.1 if a new dup group surfaces.
3. Phase 9 \u2014 Builds, tests, and CI hygiene (playbook §1006-1102).
4. Annual workspace-wide feature/dep audit re-run.

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