docs(agents): scope verification for local and stacked work (#27299)

Running `just ready` after every commit repeats expensive workspace checks for small edits and successive PRs in a stack.

Keep the core rules in `AGENTS.md` and move the detailed workflow to `.agents/verification.md`, with an explicit instruction to read it before selecting checks. Scope verification to changed code and affected consumers, reuse results while inputs stay unchanged, and keep Cargo build settings consistent to avoid unnecessary rebuilds. For stacks, use each PR's diff against its parent and reserve broad integration checks for a stable tip.

This reduces repeated work during local and stacked development while retaining required subsystem checks and CI for each mergeable PR. It uses existing commands, with no additional verification scripts to maintain.

Exercised on local changes and a ten-PR stack; a fresh agent checked discovery and verification decisions after the split.

AI-assisted with Codex.

.agents/verification.md

@@ -0,0 +1,10 @@
+# Verification for local and stacked development
+
+- For Rust implementation or test changes, run `just lint -p <crate>` for affected crates and, where unit/integration tests exist, unfiltered `just test -p <crate>` when the change is ready. Use filtered regressions such as `just test -p <crate> --tests <filter>` while reproducing or debugging. If the complete affected suite already covers the regression on current inputs, do not add a separate filtered run. Treat unexpected zero-test results as incomplete, even if Cargo exits successfully.
+- Prose-only documentation needs formatting and typo checks. For Rustdoc-only changes, use `just doc -p <crate>` and, when executable examples change, `cargo test -p <crate> --all-features --doc`; do not add runtime crate tests or lint solely for documentation edits. For implementation changes that affect documentation, scope Rustdoc checks to affected crates; use whole-workspace documentation only when the affected scope requires it.
+- Select checks from each change, or each PR's diff against its parent. Include affected consumers when changing shared AST, string, syntax, or other common APIs.
+- Run the owning subsystem's required generators, conformance, and bindings checks in the root [AGENTS.md](../AGENTS.md#testing); crate tests alone do not cover them. Build and test affected NAPI packages with their package-specific commands; use all-package binding builds and tests when the affected consumers require that scope. For conformance-only crates such as the parser, use the prescribed conformance suite instead of repeating empty crate-test runs.
+- Rerun checks when their tested code, dependencies, generated inputs, toolchain, or build configuration changes. A commit alone does not require repeating unchanged checks. Report the commands, scope, and results, including any skipped or incomplete checks.
+- Reuse Cargo build artifacts and keep toolchains, profiles, and features consistent. When both filtered and unfiltered tests are needed, keep the selected package group consistent too: changing `-p` selections can change dependency features even with `--all-features`. Preserve required standalone and feature-configuration checks; grouped builds can mask feature-wiring errors. Run Cargo commands serially when sharing a target directory.
+- At a stable integration checkpoint, use `just ready` when broad local validation is still needed, especially after shared API, dependency, or workspace changes. Choose it or the relevant individual checks before running them; do not repeat equivalent checks on unchanged inputs. For a stack, use one run on the stable tip instead of repeating it for every intermediate commit. It requires a clean tracked worktree; review any changes it produces.
+- When the affected scope is unclear or spans the workspace, broaden tests and lint with `just test` and `just lint`, plus relevant subsystem checks. Each independently mergeable PR still needs its required CI; a passing stack tip does not establish that intermediate PRs pass.

AGENTS.md

@@ -55,7 +55,7 @@ Prerequisites: Rust (MSRV: 1.97), Node.js, pnpm, just
 - All tools already installed (`cargo-insta`, `typos-cli`, `cargo-shear`, `ast-grep`)
 - Rust components already installed (`clippy`, `rust-docs`, `rustfmt`)
 - Use Conventional Commits for commit messages; `.github/workflows/pr.yml` requires a scoped title like `fix(parser): handle trailing comma`
-- Run `just ready` after commits for final checks
+- Choose verification from the changed code; reserve `just ready` for an optional broad integration checkpoint as described below.
 - You run in an environment where `ast-grep` is available; whenever a search requires syntax-aware or structural matching, default to `ast-grep --lang rust -p '<pattern>'` (or set `--lang` appropriately) and avoid falling back to text-only tools like `rg` or `grep` unless I explicitly request a plain-text search.
 
 ### Essential Commands
@@ -64,7 +64,7 @@ Prerequisites: Rust (MSRV: 1.97), Node.js, pnpm, just
 just fmt             # Format code (run after modifications)
 just test            # Run unit/integration tests
 just conformance     # Run conformance tests
-just ready           # Run all checks (use after commits)
+just ready           # Optional broad integration checkpoint (see below)
 cargo lintgen        # Regenerate linter rules enum and impls after adding/modifying rules
 cargo lint-timings   # Update linter timing data after changing linter rule codegen
 
@@ -80,6 +80,14 @@ just example tool    # Run tool example (e.g., just example linter)
 
 More commands can be found in `justfile`.
 
+### Local and stacked development
+
+Before selecting verification checks, read the [verification guidance](.agents/verification.md).
+
+- Select checks from changed code and affected consumers; for a stack, use each PR's diff against its parent.
+- Reuse passing results while tested inputs remain unchanged. Reserve `just ready` for stable integration checkpoints when broad validation is needed.
+- Preserve required subsystem checks and per-PR CI; a passing stack tip does not establish that intermediate PRs pass.
+
 ## Manual Testing & Examples
 
 Run crate examples for quick testing and debugging:

crates/oxc_minifier/docs/AGENTS.md

@@ -43,9 +43,11 @@ just minsize        # Size benchmarks (PRIMARY METRIC)
 cargo coverage      # Conformance tests
 pnpm --filter "./napi/minify" --filter "./napi/transform" run build-test
 pnpm --dir tasks/e2e test # End-to-end tests
-just ready         # Run before committing
+just ready         # Optional broad integration checkpoint
 ```
 
+Before selecting verification checks, read the [verification guidance](../../../.agents/verification.md).
+
 ### Common Patterns
 
 #### Optimization Structure