Skip to content

docs(lints): cross-reference allocation_policy.md from Cargo.toml + clippy.toml (Phase 6 follow-up, refs #193)#286

Merged
githubrobbi merged 1 commit into
mainfrom
chore/phase-6-followup-cross-refs
May 19, 2026
Merged

docs(lints): cross-reference allocation_policy.md from Cargo.toml + clippy.toml (Phase 6 follow-up, refs #193)#286
githubrobbi merged 1 commit into
mainfrom
chore/phase-6-followup-cross-refs

Conversation

@githubrobbi
Copy link
Copy Markdown
Collaborator

Phase 6 §11.9 follow-up: parity with the Phase-5e panic_policy.md cross-reference precedent (PR #278).

The gap this closes

Cargo.toml and clippy.toml already point at panic_policy.md so a contributor running grep panic_policy Cargo.toml immediately finds the contract for the deny-level unwrap_used / expect_used / panic lints.

The same shape was missing for the allocation contract — a grep for allocation_policy Cargo.toml returned nothing before this change, defeating the discoverability that docs/architecture/code-quality/allocation_policy.md (PR #285) was designed to provide.

What this changes

Doc-comment-only edits. The [workspace.lints] block remains byte-identical at the TOML-value level — only trailing comments and the doc-block above # ───── Memory & allocation ───── gained content.

Cargo.toml (4 edits, 11 lines net)

  1. New 5-line doc block above # ───── Memory & allocation ───── (line 460) mirroring the panic-policy block at line 322-326. Points at allocation_policy.md, the five-category taxonomy (α/β/γ/δ/ε), and the scripts/dev/clone_alloc_audit.sh script.

  2. Per-lint trailing comments added to the relevant deny-level clone-family lints with section refs back into allocation_policy.md:

Lint Section ref
clone_on_ref_ptr §3.1 (category α — Arc clone)
redundant_clone §3.4 (category δ — anti-pattern)
inefficient_to_string §2 (lint posture)
str_to_string §2
implicit_clone §2
cloned_instead_of_copied §2
map_clone §2
assigning_clones §2
rc_buffer §3.1 (α)
rc_mutex §3.1 (α)

clippy.toml (1 edit)

Extended the existing "Test code relaxations" comment block (which already references panic_policy.md) with a parallel paragraph referencing allocation_policy.md for the eight clone- and allocation-family lints. Lists each family lint explicitly so future contributors can grep on either lint name and find the contract.

Verification

  • just lint-pre-push ✅ (86s) — every gate green: fmt-check, file-size, gates-drift, hooks-drift, workflow-drift, fast-drift, manifest-drift, commit-subjects, vet, vet-audit-discipline, machete, typos, reuse, cargo-check, lint-ci, lint-prod, lint-tests, rustdoc, doc-tests, tests, smoke, deny, lint-ci-windows.
  • cargo metadata parses cleanly — TOML structure unchanged at value level.
  • cargo clippy --workspace --all-targets emits zero diagnostics (lint values unchanged).
  • Test count unchanged: 1,833 / 1,833 passing.

Behavior & contracts

  • Zero functional change. The [workspace.lints] deny-set is byte-identical at the TOML value level.
  • Public API unchanged.
  • Doc-comments-only change.

Strict-lint posture

No suppression hacks. No new #[allow] / #[expect]. All edits are TOML doc comments.

Phase 6 closeout reference

Closes the only remaining Phase-6 follow-up item recorded in phase_6_final_report.md §11.9 #1 (local-only, gitignored under /docs/dev/). Plan §11.5 status moves from "Pending parity follow-up" to "Complete" after this PR lands.

refs #193

…lippy.toml (Phase 6 follow-up, refs #193)

Phase 6 \u00a711.9 follow-up: parity with the Phase-5e `panic_policy.md`
cross-reference precedent.

`Cargo.toml` and `clippy.toml` already point at
`docs/architecture/code-quality/panic_policy.md` (PR #278) so a
contributor running `grep panic_policy Cargo.toml` immediately finds
the contract for the deny-level `unwrap_used` / `expect_used` /
`panic` lints.  The same shape was missing for the allocation
contract \u2014 a grep for `allocation_policy Cargo.toml` returned
nothing before this change, defeating the discoverability the
`docs/architecture/code-quality/allocation_policy.md` doc was
designed to provide.

This is a doc-comments-only change.  The `[workspace.lints]` block
remains byte-identical at the TOML-value level: only trailing
comments and the doc-block above `# \u2500\u2500\u2500\u2500\u2500 Memory & allocation \u2500\u2500\u2500\u2500\u2500`
gained content.

What changed
------------

`Cargo.toml` (5 edits):

- **Doc block above `# \u2500\u2500\u2500\u2500\u2500 Memory & allocation \u2500\u2500\u2500\u2500\u2500` (line 460):**
  4-line cross-reference paragraph mirroring the panic-policy block at
  line 322-326.  Points at `allocation_policy.md`, the five-category
  taxonomy, and the `clone_alloc_audit.sh` script.

- **Per-lint trailing comments** added to seven existing deny-level
  clone-family lints (lines 353, 354, 372, 376, 377, 378, 379, 466,
  467, 468) referencing the corresponding `allocation_policy.md`
  section:

  - `clone_on_ref_ptr` \u2192 \u00a73.1 (category \u03b1)
  - `redundant_clone` \u2192 \u00a73.4 (category \u03b4)
  - `inefficient_to_string` \u2192 \u00a72
  - `str_to_string` \u2192 \u00a72
  - `implicit_clone` \u2192 \u00a72
  - `cloned_instead_of_copied` \u2192 \u00a72
  - `map_clone` \u2192 \u00a72
  - `assigning_clones` \u2192 \u00a72
  - `rc_buffer` \u2192 \u00a73.1 (\u03b1)
  - `rc_mutex` \u2192 \u00a73.1 (\u03b1)

`clippy.toml` (1 edit):

- Extended the existing "Test code relaxations" comment block (which
  already references `panic_policy.md`) with a parallel paragraph
  referencing `allocation_policy.md` for the clone- and allocation-
  family lints.  Lists the eight family lints explicitly so future
  contributors can grep on either lint name and find the contract.

Verification
------------

- `just lint-pre-push` \u2705 (86s): every gate green \u2014 fmt-check,
  file-size, gates-drift, hooks-drift, workflow-drift, fast-drift,
  manifest-drift, commit-subjects, vet, vet-audit-discipline,
  machete, typos, reuse, cargo-check, lint-ci, lint-prod, lint-tests,
  rustdoc, doc-tests, tests, smoke, deny, lint-ci-windows.
- `cargo metadata` parses cleanly (Cargo.toml structure unchanged at
  the TOML value level; only comments added).
- `cargo clippy --workspace --all-targets` emits zero diagnostics
  (lint values unchanged).
- Test count unchanged: 1,833 / 1,833 passing.

Behavior & contracts
--------------------

- Zero functional change.  The `[workspace.lints]` deny-set is
  byte-identical at the TOML-value level.
- Public API unchanged.
- Doc-comment-only change.

Strict-lint posture
-------------------

No suppression hacks introduced.  No new `#[allow]` / `#[expect]`
anywhere.  All edits are TOML doc comments.

Phase 6 closeout reference
--------------------------

This closes the only remaining Phase-6 follow-up item recorded in
`phase_6_final_report.md` \u00a711.9 #1.  Plan \u00a711.5 (Strict-lint posture)
gets a status update from "Pending parity follow-up" to "Complete"
after this PR lands.

refs #193
@githubrobbi githubrobbi enabled auto-merge (squash) May 19, 2026 16:02
@githubrobbi githubrobbi merged commit d2d5330 into main May 19, 2026
21 checks passed
@githubrobbi githubrobbi deleted the chore/phase-6-followup-cross-refs branch May 19, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant