Skip to content

docs: adopt narrowed design-principles directives (zackees/ci.yml#163) - #630

Merged
zackees merged 1 commit into
mainfrom
docs/design-principles
Oct 26, 2026
Merged

zackees merged 1 commit into
mainfrom
docs/design-principles

Conversation

@zackees

@zackees zackees commented Oct 26, 2026

Copy link
Copy Markdown
Owner

Adds the canonical narrowed design-principles block from zackees/ci.yml docs/policy-rust.md ("Design principles, narrowed", forge-ci/ci.yml#163) to CLAUDE.md, the repo's agent doc, placed after the hard rules and before "Repo facts". Agent/review guidance only: no rule ID, not enforced by ci-lint. Docs-only (CLAUDE.md); no workflows, no code. The head is stamped by ci-lint local-gate run (45/45 checks, Local-Gate: trailer).

Adopted / adapted / dropped (forge-ci/ci.yml#163)

The block is the canonical text; "Adapted" means the wording was changed or bound to something this repo already has.

# Baseline rule Decision Reason (this repo)
1 rg before adding a resolver/guard Adopted Applies to both the rust/ crates and the fork's src/profile*.c/memory-events files, where duplicating helpers next to upstream ones is the main drift risk.
2 Conflicts get a research issue Adopted Complements hard rule 7 ("escalate, don't improvise"): a design decision goes on an issue, not into an inline winner.
3 Behaviour and refactor in separate commits/PRs Adapted Cross-references hard rule 2 (never mix C-core and rust/ paths in one commit). Both rules apply.
4 Refactor first only past 50 lines into a >200-line function Adapted Adds that upstream mimalloc files are never restructured (hard rule 6: new logic in new files, a few guarded lines in upstream files). Without that, rule 4 could license extracting from an upstream function and break byte-identical overlay re-application.
5 Function/file size follow RUST-018 Adapted rust/ has no clippy too_many_lines/cognitive_complexity config, so there is no ratchet and no #[expect]s. The directive keeps the 100/25 ceilings for new functions, says nothing mechanical holds them yet, and keeps the include! ban (zero fragments today).
6 Fail fast; delete before abstracting; no single-impl trait Adapted Bound to hard rule 7 (escalate on the issue rather than improvise a fallback). Matches the owner rule that observability defaults are named explicitly rather than relied on.
7 Existing boundaries over generic DRY Adapted The boundaries here are the upstream overlay (hard rules 2 and 6) and the rust/ crate split. This repo has no Dylints, so the Dylint clause names none.
-- "HARD RULE refactor first", composition over inheritance, Open/Closed Dropped Dropped fleet-wide by #163: refactor-first is contradicted by soldr's regression history (soldr#2559, soldr#1490); the other two are not meaningful in Rust.

Local-Gate: v1 tree=2ed98eb013c07ca09e7aee35e62cfd331baf23d0 secs=66 lanes=lint:run
Ci-Attestation: {"at":1792984508,"gate":"python/all/lint","host":"linux-x86_64","key":"82a31011ce46ca7b34dcfe762e5c70f19a03110b83a12709c474e8dd03689640","lane":"lint","parents":["6dc92558f51544e152fdb634844fe873e837a749"],"secs":66,"stamp":"562ad5295078f735f1461778d2495525","tree":"2ed98eb013c07ca09e7aee35e62cfd331baf23d0","v":1,"via":"run"}
@zackees
zackees merged commit 259906b into main Oct 26, 2026
64 checks passed
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