docs(architecture): add dependency_policy.md and CONTRIBUTING.md cross-link (Phase 8c, refs #195)#294
Merged
Merged
Conversation
…s-link (Phase 8c, refs #195) Adds the fourth code-quality policy doc for the workspace, mirroring the shape of panic_policy.md (Phase 5e), allocation_policy.md (Phase 6f), and trait_policy.md (Phase 7g). dependency_policy.md sections: * §1 The rule — every feature is additive; every default has a written justification; every optional dep is reachable via `dep:<name>` + at least one `cfg(feature)` use-site; every cross-version duplicate is either in skip-tree with a one-line reason or accepted by `multiple-versions = "warn"" and inventoried in §5.1. * §2 The lint posture — no new clippy lints; `cargo deny`, `cargo machete`, `cargo vet`, `cargo tree -d`, and `cargo doc --all-features" together enforce the contract. * §3 Feature flag contract (playbook §988) — the four-line contract every feature must document in both rustdoc and Cargo.toml. * §4 Dependency hygiene rules — direct deps, workspace pinning, optional deps, consumer-side `default-features = false" overrides, default features on internal crates. * §5 Cross-version duplicate acceptance criteria — three reasons the workspace runs `multiple-versions = "warn"" not "deny"; inventory of 12 distinct duplicate groups (4 listed, 8 warn-only) at SHA `4c6ffcff4". * §6 Per-crate feature registry — 3 features across 3 of 14 crates; 11 crates intentionally feature-less. * §7 Anti-patterns — subtractive features, default-on without justification, orphan optional deps, feature-on-feature without rustdoc cascade, unlisted cross-version duplicate, direct dep without use-site. * §8 Audit cadence — per-phase rerun + polars-bump rerun + annual workspace-health review. * §9 Cross-references — workspace deps, deny.toml, supply-chain/, audit script, companion policies, playbook, baseline. * §10 Decisions log — append-only entries for 8a, 8b, 8c. CONTRIBUTING.md gains a 15-LOC "Feature flag and dependency policy" section mirroring the existing 3 policy sections (panic, allocation, trait): one-line rule, four-line §988 contract, taxonomy summary, cross-link to dependency_policy.md. All cross-link paths verified to resolve. No behavior change; pure documentation. Pre-commit `lint-fast" gate green (4 s). Refs #195.
This was referenced May 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 8c — fourth code-quality policy doc. Mirrors
panic_policy.md(Phase 5e),allocation_policy.md(Phase 6f), andtrait_policy.md(Phase 7g) in shape and rigor.No behavior change. Pure documentation.
What it adds
docs/architecture/code-quality/dependency_policy.md(334 LOC)dep:<name>+ at least onecfg(feature)use-site; every cross-version duplicate is either indeny.toml [bans].skip-treewith a one-line reason or accepted bymultiple-versions = \"warn\"and inventoried in §5.1.cargo deny,cargo machete,cargo vet,cargo tree -d, andcargo doc --all-featurestogether enforce the contract.default-features = falseoverrides, default features on internal crates.multiple-versions = \"warn\"not "deny"; inventory of 12 distinct duplicate groups (4 listed, 8 warn-only) at SHA4c6ffcff4.deny.toml,supply-chain/, audit script, companion policies, playbook, baseline.CONTRIBUTING.md— new## Feature flag and dependency policysection (15 LOC)Mirrors the existing 3 policy sections in CONTRIBUTING (panic, allocation, trait): one-line rule, four-line §988 contract, taxonomy summary (F1/F2/F3/F4/F5), cross-link to
dependency_policy.md.Verifications
dependency_policy.mdverified to resolve (panic_policy.md, allocation_policy.md, trait_policy.md, lint-posture.md, ../../../clippy.toml, ../../dev/architecture/code_clean/phase_8_...md, ../../../deny.toml, ../../../supply-chain/config.toml).lint-fastgate green (3 s).Phase-8 rules adherence
#[allow]or lint-config changes.Refs #195.