diff --git a/.agents/rules/code-style.md b/.agents/rules/code-style.md index 90cd037ddf..63eac42deb 100644 --- a/.agents/rules/code-style.md +++ b/.agents/rules/code-style.md @@ -69,3 +69,8 @@ Order definitions within a file as: ## Bulk Logging * In bulk operations, log a single summary line on success; on failure, list each failing item sorted, one per line, with its location and reason. + +## Porting & Rewrites +* When porting or rewriting code across languages or subsystems, cross-check + every original test case and non-obvious invariant or spec comment against the + new implementation and tests to preserve edge-case coverage and rationale. diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index eab15774eb..e583c8ef1d 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md @@ -1,6 +1,6 @@ --- trigger: model_decision -description: rules to apply to pull request descriptions +description: Pull request titles, descriptions, commits, comments, and replies --- @CONTRIBUTING.md @@ -35,8 +35,9 @@ Before drafting any pull request description, strictly adhere to the rules in * **NEVER** amend or rebase commits on an active PR branch to avoid breaking code review threads. * **PR Metadata Discrepancies**: If a PR title or description diverges from - the branch's actual scope, notify the user of the discrepancy and ask for - confirmation before updating GitHub. + the branch's actual scope (including stale benchmark numbers after follow-up + commits), notify the user of the discrepancy and ask for confirmation before + updating GitHub. * **NEVER** include a list of per-file edits, changelog bullet points of individual file modifications, test execution logs/checklists, or AI disclosure metadata in PR descriptions or commit messages. @@ -55,6 +56,8 @@ Before drafting any pull request description, strictly adhere to the rules in conceptual level. Link related issues (e.g. `Work towards #`). * **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear, active, and direct phrasing for *why* and *how*. +* **Benchmark Summaries**: Format performance comparisons as a brief 3-5 bullet + list by workload dimension (speedup range, wall time, RSS) rather than prose. * **Preserve Existing Descriptions**: Preserve the author's wording unless instructed to change it. Wrap bodies at 72 columns. * **Open Questions & Follow-Up Items**: @@ -76,7 +79,15 @@ Before drafting any pull request description, strictly adhere to the rules in * Only if the user was shown the exact comment text and explicitly approved posting it: `*This is an agent-generated comment reviewed and approved by the user.*` -* After fixing an inline PR review thread, reply with the commit hash and - explanation (`addPullRequestReviewThreadReply`) and resolve the thread - (`resolveReviewThread`) via `gh api graphql`, batching at most 3-4 threads per - request to avoid `502 Bad Gateway` timeouts. +* **Reply Style (`arXiv:2610.29162v1`)**: Keep review replies to 1-3 short + sentences (~15-60 words) leading with the commit hash or direct answer. Pair + direct subjects with concrete verbs (`"I replaced X in "`, `"str::lines + strips \r\n"`); avoid inanimate subjects with agentive verbs (`"This commit + facilitates..."`), denominal verbs, 3+ stacked nouns, center-embedded relative + clauses, and excessive inline backticks. Critically evaluate each comment + against source/specs first and push back concisely when a premise does not + hold. +* **Thread Resolution**: Reply via `addPullRequestReviewThreadReply` (`gh api + graphql`, batching at most 3-4 mutations per request to avoid `502 Bad + Gateway` timeouts), and **do not** resolve review threads + (`resolveReviewThread`) unless explicitly instructed. diff --git a/.agents/rules/rust.md b/.agents/rules/rust.md index 8e60c0f457..05e0af9623 100644 --- a/.agents/rules/rust.md +++ b/.agents/rules/rust.md @@ -33,15 +33,27 @@ When adding or updating a Rust crate dependency: C `-sys` libraries (breaking hermetic cross-compiled and static `musl` builds), platform-incompatible OS crates, or heavy unused subsystems, and document the reason in a comment. +* **Compression backends**: For `zip`/`flate2` DEFLATE workloads, prefer + pure-Rust `zlib-rs` (`flate2` features `["zlib-rs", "runtime_detection"]`, + plus `zip` feature `deflate-flate2-zlib-rs` when using `zip`, both with + `default-features = false`) over `miniz_oxide` so throughput matches or + exceeds C `zlib` while preserving pure-Rust `musl` cross-compilation and + deterministic bitstreams. * **Regenerate lockfiles**: Update `Cargo.lock` and `Cargo.Bazel.lock` with `CARGO_BAZEL_REPIN=1`; never hand-edit generated lockfiles. ## Idiomatic Rust, CLI Design & Crate Layout * **Edition & control flow**: Use `edition = "2024"`. Flatten nested conditionals with early `continue`/`return` guards and `let`-chains - (`if let Some(p) = out.parent() && !p.as_os_str().is_empty()`). Prefer `str` - pattern methods (`split_once`, `rsplit_once`, `strip_prefix`, `strip_suffix`) - over manual index slicing. + (`if let Some(ext) = path.extension() && ext == "whl"`). +* **String & line processing**: Prefer `str` pattern methods (`split_once`, + `rsplit_once`, `strip_prefix`, `strip_suffix`) over manual index slicing. + Iterate lines directly with `str::lines()` (`.map(str::trim).filter(...)`) + instead of pre-allocating `.replace("\r\n", "\n")` (`str::lines()` strips both + `\n` and `\r\n`). +* **Filesystem parent directories**: Pass `parent` directly to + `fs::create_dir_all(parent)` without `!parent.as_os_str().is_empty()` (`""` is + already a no-op). * **Parse, don't validate**: Parse CLI flags and raw inputs into strong types (`bool`, enums, validated `PathBuf`, pre-compiled `Regex`) in `parse_args` rather than storing stringly-typed `String` fields or deferring validation to @@ -95,6 +107,8 @@ When adding or updating a Rust crate dependency: `std::error::Error` with `#[from]`/`#[source]`) so callers can match on variants and errors compose across crate boundaries; such a type still converts into `anyhow::Error` for free at the CLI layer. +* **Document `# Errors`**: Add `# Errors` rustdoc sections on fallible `pub fn` + library items stating when they return `Err`. * **Tests may panic**: `unwrap()`, `expect()`, `panic!`, and indexing are allowed in test code (`.clippy.toml` sets `allow-*-in-tests`). When using `expect()`, write the message in std's recommended style, stating why the diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index a5682bb9e0..36f4f3effd 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -89,7 +89,7 @@ file from `.agents/skills/review-code/`: no unrequested knobs/aliases, no speculative validation or defensive `None` checks, no nested comprehensions, naming precision, simplification, `keep-sorted` markers, `LINT.IfChange` / - `LINT.ThenChange` directives, and CLI safety annotations. + `LINT.ThenChange` directives, porting parity, and CLI safety annotations. 11. Shell Script Sub-Agent (`Role: "Shell Script Auditor"`): - Prompt file: @@ -117,8 +117,9 @@ file from `.agents/skills/review-code/`: - Focus: Audits Rust code (`*.rs`, `crates/**`) and crate dependencies in `MODULE.bazel` / `Cargo.*` against `.agents/rules/rust.md` (standard ecosystem crates over custom subsystems such as regex or ZIP handling, - crate legitimacy and latest `crates.io` versions, feature pruning for - cross-compilation, library crate structure, and `rustfmt`). + crate legitimacy and latest `crates.io` versions, feature pruning and + `zlib-rs` DEFLATE selection, idiomatic `str::lines()`/`create_dir_all`, + `# Errors` rustdocs, library crate structure, and `rustfmt`). 14. Comment Readability Sub-Agent (`Role: "Comment Readability Editor"`): - Prompt file: @@ -223,7 +224,7 @@ file from `.agents/skills/review-code/`: 6. Also push fixes to PR - When fixing and pushing open issues that also had non-draft review comments posted, reply to each fixed review thread with the commit SHA (and disclosure - line) and resolve the thread. + line) without resolving the thread unless explicitly instructed. - If reviewing or re-reviewing a PR belonging to another user and the verdict is `PASS` (0 open issues and 0 net-new candidate comments) while the PR is not yet approved by the user, prompt the user via `ask_question` (including a diff --git a/.agents/skills/review-code/review-code-style-prompt.md b/.agents/skills/review-code/review-code-style-prompt.md index 5a45f553de..35849d5f24 100644 --- a/.agents/skills/review-code/review-code-style-prompt.md +++ b/.agents/skills/review-code/review-code-style-prompt.md @@ -21,5 +21,9 @@ cross-language code style, control flow, refactoring, and CLI conventions: verify comments or docstrings document what those paths are relative to. 7. Synchronized Sections: Flag plain `# Keep in sync` comments for paired code or config blocks and require `LINT.IfChange` / `LINT.ThenChange` directives. +8. Porting & Rewrites: When porting or rewriting code across languages or + subsystems (even if the original files are unchanged in `git diff`), inspect + the original source and test files and verify the new implementation and + tests preserve every test case and non-obvious invariant or spec comment. @.agents/skills/review-code/review-report-format.md diff --git a/.agents/skills/review-code/review-comment-readability-prompt.md b/.agents/skills/review-code/review-comment-readability-prompt.md index 78826f38e7..521aac7414 100644 --- a/.agents/skills/review-code/review-comment-readability-prompt.md +++ b/.agents/skills/review-code/review-comment-readability-prompt.md @@ -47,10 +47,13 @@ in Markdown (`code-review-results.md`) and GitHub pull request comments. - Include `Where:` only when more than just the commented location is affected; omit `Where:` for single-location issues. -4. No "AI Slop" Walls of Text (1–2 Direct Sentences): - - Keep `Draft Comment` and `Draft Reply` prose to 1–2 short, direct - sentences (~40 words max of prose) stating the core problem and what to - change. +4. No "AI Slop" Walls of Text (`arXiv:2610.29162v1`): + - Keep `Draft Comment` prose to 1–2 short, direct sentences (~40 words max) + and `Draft Reply` prose to 1–3 short sentences (~15–60 words) leading with + the commit hash or direct answer. + - Pair direct subjects with concrete verbs; avoid inanimate subjects with + agentive verbs (`"This commit facilitates..."`), denominal verbs, 3+ + stacked nouns, and center-embedded relative clauses. - Cut parenthetical `e.g.` scenario lists, semicolon-chained `"conversely..."` contrasts, and restated context that is already obvious from the anchored file and line. diff --git a/.agents/skills/review-code/review-rust-prompt.md b/.agents/skills/review-code/review-rust-prompt.md index 6842f34ce5..ae894a4907 100644 --- a/.agents/skills/review-code/review-rust-prompt.md +++ b/.agents/skills/review-code/review-rust-prompt.md @@ -24,12 +24,19 @@ in `git diff`: - Check feature selection: default features should remain enabled unless defaults pull in C `-sys` libraries, target-incompatible OS crates, or heavy unused subsystems (with a comment explaining why - `default_features = False` is set). + `default_features = False` is set). For `zip`/`flate2` DEFLATE workloads, + verify crate specs select pure-Rust `zlib-rs` (`flate2` features + `["zlib-rs", "runtime_detection"]` and `zip` `deflate-flate2-zlib-rs` + with `default-features = false`) over `miniz_oxide`. 4. Idiomatic Rust, CLI & Crate Design: - Verify workspace crates use `edition = "2024"`, flatten nested conditionals - with early guards and `let`-chains, and use `str` pattern methods + with early guards and `let`-chains, prefer `str` pattern methods (`split_once`, `rsplit_once`, `strip_prefix`/`strip_suffix`) over manual - index slicing. + index slicing, iterate lines with `str::lines()` instead of + `.replace("\r\n", "\n")`, and pass `parent` directly to + `fs::create_dir_all(parent)` without `!parent.as_os_str().is_empty()`. + - Verify fallible `pub fn` library items include `# Errors` rustdoc + sections stating when they return `Err`. - Verify "parse, don't validate": flag stringly-typed `String` options where `bool`, enums, validated `PathBuf`, or pre-compiled `Regex` belong in `parse_args`.