How the Affected-Package Tier Gate Determines Which Packages Get Clippy-Linted Before Push in OpenLogi

The Affected-Package Tier Gate determines which packages receive Clippy linting by verifying no workspace-wide files were modified and no commits were rebased, then using cargo tree --invert to compute the transitive reverse-dependency set of all changed crates.

The AprilNEA/OpenLogi repository optimizes developer feedback loops through a tiered pre-push validation system. Instead of running Clippy and tests across the entire workspace for every commit, the Affected-Package Tier Gate intelligently scopes validation to only those crates transitively impacted by local changes, dramatically reducing iteration time while preserving code quality guarantees.

Prerequisites for Enabling the Affected-Package Tier

The gate selects the affected-package tier only when two strict safety conditions are met. If either condition fails, the system defaults to the full-workspace tier.

Condition 1: Clean Commit History

No Rust-bearing commit has been rebased or had merge-conflicts resolved since the last full-gate run. This prerequisite prevents the gate from operating on stale analysis results derived from rewritten Git history, ensuring the affected-package set accurately reflects the current state.

Condition 2: No Workspace-Wide Changes

The diff must not modify any global build or validation inputs. According to the AGENTS.md specification, the gate checks for changes to:

• Cargo.toml, Cargo.lock, or rust-toolchain.toml
• build.rs scripts and .cargo/** configuration
• Lint, format, or hook configuration files
• Devenv settings and CI workflows
• The local CI runner implementation

Any modification to these files invalidates the affected-package optimization, triggering a full-workspace lint instead.

Deriving the Affected Package Set

Once the prerequisites pass, the gate calculates the minimal set of crates requiring validation. This process leverages Cargo's dependency graph to identify all reverse dependencies.

For each changed crate, the gate executes:

cargo tree --workspace --target all --invert <changed-crate>

This command lists every workspace package that depends—directly or transitively—on the modified crate. The gate unions these results across all changed crates to produce the affected package set. For example, editing openlogi-core would automatically include all higher-level crates that consume it, even if their individual source files remain untouched.

Running Clippy on the Filtered Package Set

With the affected package set determined, the gate executes validation commands scoped exclusively to those crates. As documented in AGENTS.md, the sequence is:

export RUSTFLAGS="-D warnings"
cargo fmt --all -- --check
cargo clippy -p <crate-1> -p <crate-2> … --all-targets -- -D warnings
cargo test -p <crate-1> -p <crate-2> …

The -p (package) flags restrict Clippy, formatting, and tests to the derived affected set. If any command fails, the developer must fix the issues and rerun the tier. Only after this scoped validation passes is the push allowed; otherwise, the full-workspace tier is required.

Manual Reproduction Steps

Developers can manually reproduce the gate's logic locally before pushing:

# 1. Identify changed crates

git diff --name-only HEAD~1 HEAD | grep '^crates/' | cut -d/ -f2 | sort -u

# => openlogi-core  openlogi-agent

# 2. Build the affected package set

affected=$(for c in openlogi-core openlogi-agent; do
    cargo tree --workspace --target all --invert $c |
    cut -d' ' -f1
done | sort -u)

# 3. Run the gate for those packages

export RUSTFLAGS="-D warnings"
cargo fmt --all -- --check
cargo clippy $(printf -- '-p %s ' $affected) --all-targets -- -D warnings
cargo test $(printf -- '-p %s ' $affected)

These commands mirror the automated gate logic described in the repository's AGENTS.md file.

Configuration Files Defining the Gate Logic

Several files in the AprilNEA/OpenLogi repository codify this behavior:

• AGENTS.md: Contains the canonical description of the gate workflow, including the affected-package tier logic under the sections "Local gate (hard stop before push…)" and "Affected‑package tier".
• xtask/AGENTS.md: Documents the cargo xtask ci helper used to run CI jobs locally.
• .claude/rules/ci.md: Maps CI jobs to the specific commands the gate executes.
• .claude/rules/rust.md: Defines workspace-wide Rust standards that influence when the full gate is required.

Together, these files implement the logic that determines which packages receive Clippy linting in the affected-package tier.

Summary

• The Affected-Package Tier Gate optimizes pre-push validation by linting only transitively affected crates rather than the full workspace.
• It activates only when no Rust commits were rebased and no workspace-wide configuration files changed.
• The gate uses cargo tree --invert to calculate reverse dependencies, creating the affected package set.
• Clippy, formatting, and tests run with -p flags targeting only the derived set, enforced by RUSTFLAGS="-D warnings".
• Configuration and authoritative documentation reside in AGENTS.md and supporting files under .claude/rules/.

Frequently Asked Questions

What triggers the full-workspace tier instead of the affected-package tier?

The gate falls back to the full-workspace tier if any Rust-bearing commit was rebased since the last full run, or if the diff touches workspace-wide files like Cargo.toml, Cargo.lock, rust-toolchain.toml, build.rs, or CI configuration files. These changes potentially impact the entire workspace graph, making a scoped check insufficient for safety.

How does the gate determine which packages depend on my changes?

For each modified crate, the gate runs cargo tree --workspace --target all --invert <crate>. This lists all workspace packages that transitively depend on the changed crate. The gate unions these lists across all changed crates to form the complete affected package set that requires validation.

Can I run the affected-package tier locally before pushing?

Yes. Extract your changed crates from git diff, compute the affected set using cargo tree --invert, then run cargo clippy -p <crate> … and cargo test -p <crate> … with the resulting package list. The repository's AGENTS.md file documents this exact workflow for manual verification.

Where is the Affected-Package Tier Gate logic documented?

The authoritative documentation lives in AGENTS.md at the repository root, specifically under the sections "Local gate (hard stop before push…)" and "Affected‑package tier". Additional implementation details appear in xtask/AGENTS.md and .claude/rules/ci.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}