docs(architecture): add trait_policy.md and CONTRIBUTING.md cross-link (Phase 7g, refs #287)#290
Merged
Merged
Conversation
…k (Phase 7g, refs #287) Add `docs/architecture/code-quality/trait_policy.md` documenting the trait / generic / dispatch discipline for the UFFS workspace. Companion to `panic_policy.md` (Phase 5e) and `allocation_policy.md` (Phase 6f). Sections: 1. The one-line rule 2. The lint posture (5 lints: type_complexity carried over from Phase 6; too_many_arguments / trait_duplication_in_bounds / wrong_self_convention deny + multiple_bound_locations warn added in Phase 7f) 3. Four-criterion trait justification taxonomy (J1/J2/J3/J4) 4. Generic-function taxonomy (G1-LOCAL / G2-USEFUL / G3-SPREAD / G4-CASCADING / G5-CLOSURE) 5. Dispatch matrix (D1-PLUGIN / D2-HETERO / D3-NOOP / D4-VTBL-COST + S1-MONOMORPH / S2-OVER-MONOMORPH / S3-CLOSED-SET) 6. Seal/open decision tree — including structural sealing for `RuntimeDir` (private fields on `RuntimeFile` make external impls structurally impossible without an explicit `Sealed` marker) 7. Per-trait registry — 12 active traits + 1 demoted (`DirCacheExt`) 8. Anti-patterns 9. Audit cadence 10. Cross-references 11. Decisions log (append-only, 7 entries through 7g) The four Phase-7 sub-phase findings docs are local-only under `docs/dev/baseline/2026-05-19/`: * phase_7_trait_justification_findings.md (7b) * phase_7_generic_audit_findings.md (7c) * phase_7_dispatch_findings.md (7d) * phase_7_sealing_findings.md (7e) CONTRIBUTING.md gains a §"Trait, generic, and dispatch policy" section linking to the full doc. Refs: #287
githubrobbi
added a commit
that referenced
this pull request
May 19, 2026
…7f, refs #287) (#291) Promote 4 clippy lints to active enforcement in `Cargo.toml [workspace.lints.clippy]`: * `too_many_arguments = "deny"` (default threshold=7) * `trait_duplication_in_bounds = "deny"` * `wrong_self_convention = "deny"` * `multiple_bound_locations = "warn"` Each gets a trailing-comment cross-reference to the relevant section of `docs/architecture/code-quality/trait_policy.md` (added in Phase 7g — PR #290). The new lints are grouped under a banner comment delineating the Phase-7f cluster from the surrounding complexity / clone-family lints. `clippy.toml` gains a paragraph in the test-relaxations comment block explaining that the four new lints follow the same "prod stays strict, tests are exempt" pattern as the Phase 5 panic-family and Phase 6 clone/alloc-family lints, with cross-references to `trait_policy.md` and the `scripts/dev/trait_generic_audit.sh` audit script. Workspace clippy run before promotion: zero diagnostics from any of the 4 lints (already at default warn or allow with zero hits). This commit only changes the **lint level**; workspace remains green. Existing per-site annotations carry forward: * 19 `#[expect(clippy::too_many_arguments, reason = "…")]` sites in uffs-cli (3), uffs-core (8), uffs-daemon (1), uffs-mft (7), all already justified before the promotion. API impact: zero. Behavior change: zero. Refs: #287
This was referenced May 19, 2026
githubrobbi
added a commit
that referenced
this pull request
May 19, 2026
The Phase 7g decisions-log row in `trait_policy.md:194` read 'this PR' at the time of authoring (when PR #290 was open). After PR #290 merged the placeholder needed backfilling to '#290' to match the surrounding rows (#288/#289/#291). Companion to Phase 8e (PR #296), which already backfilled the sibling 'TBD' placeholder on row 193 (Phase 7f -> #291). This 1-line edit completes the decisions-log hygiene pass for Phase 7.
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
1 participant
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.
Phase 7g — the workspace-tracked policy doc that frames all of 7b/7c/7d/7e/7f as one contract.
Companion to
panic_policy.md(Phase 5e — PR chore(broker-protocol): add #[non_exhaustive] to ProtocolError (Phase 5b, refs #192) #266)allocation_policy.md(Phase 6f — PR docs(architecture): add allocation_policy.md and CONTRIBUTING.md cross-link (Phase 6f, refs #193) #285)lint-posture.md(workspace-wide lint overview)What lands
docs/architecture/code-quality/trait_policy.md(194 LOC) — the trait / generic / dispatch policy doc.CONTRIBUTING.md§Trait, generic, and dispatch policy (17 LOC) — short summary + link to the full doc, mirroring §Allocation policy.Sections in trait_policy.md
type_complexity(carried over from Phase 6) + 4 new lints landing in 7f.RuntimeDir.DirCacheExt).Phase 7 audit summary embedded in §7
DirCacheExtdemoted to free fn (PR refactor(uffs-core): demote DirCacheExt to free fn dir_cache_with_capacity (Phase 7b, refs #287) #289, in CI auto-merge).pub traits — all OPEN (FileReaderJ3,FormatRowJ3,RuntimeDirstructurally sealed by privateRuntimeFilefields).Findings docs (local-only, gitignored under
/docs/dev/)phase_7_trait_justification_findings.md(7b)phase_7_generic_audit_findings.md(7c)phase_7_dispatch_findings.md(7d)phase_7_sealing_findings.md(7e)Verification
lint-pre-pushpassed (4 s — docs-only PR).panic_policy.md,allocation_policy.md,lint-posture.mdall exist.3628BD817A687030E83025A8E406D32B4736D09F.Next: 7f — add the 4 new clippy lints to
Cargo.tomlwith cross-references to this doc.Refs: #287