AI Policy

Follow AI_POLICY.md. In particular:

• Do not use AI to author issue/PR comments or replies to maintainers.
• Do not autonomously open issues or pull requests.
• Do not author code for issues labeled both E-easy and E-has-instructions.
• The human contributor must understand the changes and disclose AI use as required by the policy.

Repository Guides

• Architecture and crate ownership: docs/book/src/contributing/architecture.md
• Rust style: docs/book/src/contributing/style.md
• Testing conventions and fixture syntax: docs/book/src/contributing/testing.md
• Contributor workflows: docs/book/src/contributing/README.md
• AI restrictions: AI_POLICY.md

Read the relevant sections before making architectural, generated-code, protocol, or test-harness changes.

Change Workflow

• Find the nearest existing implementation and its tests before adding new code.
• Extend existing helpers and test harnesses instead of creating parallel abstractions.
• Keep changes focused and prefer the smallest change that fits the existing design.
• When fixing a bug, add the smallest fixture that reproduces it and test the behavior through the existing interface.

Scope and Dependencies

• Treat new pub items, public re-exports, and Cargo dependencies as architectural changes, not routine implementation details.
• Prefer keeping functionality inside the crate that owns the relevant data.
• Be conservative with crates.io dependencies. Reuse existing dependencies or stdx; do not add small helper crates without strong justification.

Key Invariants

• User-provided Rust code, malformed syntax, broken builds, and proc-macro failures must not cause ordinary IDE features to panic.
• Assert invariants liberally. For impossible conditions from which the server can recover, prefer stdx::never! or stdx::always! and return a safe fallback instead of panicking.

Testing

• Many feature tests use Rust-code fixtures and expect-test snapshots. Follow the nearest existing test helper and fixture convention rather than introducing a new test harness.
• Before planning or writing fixture-based tests, review docs/book/src/contributing/testing.md for fixture annotations, minicore, and multi-file/multi-crate syntax.
• Keep Rust fixtures minimal; remove syntax unrelated to the behavior under test.
• Use unindented multiline raw strings, matching nearby tests.
• For regressions, first reproduce the failure with a focused test, then implement the fix.

Generated Code

• Generated files are committed. Edit the generator rather than generated output.
• Run cargo xtask codegen after changing grammar, generated AST definitions, configuration schemas, or other codegen inputs.
• After adding parser inline tests (// test name), run cargo test -p xtask, update the relevant expectations, and inspect the generated diff.

Validation

• Start with the narrowest relevant test: cargo test -p <crate> <test-name> or cargo test -p <crate>.
• After Rust changes, run the affected crate's tests and cargo clippy -p <crate> --all-targets -- --cap-lints warn; broaden validation when the change crosses crates.
• Use cargo lint to run Clippy on all workspace targets.
• Run cargo xtask tidy for repository-wide structural or generated-code changes.
• When updating snapshots with UPDATE_EXPECT=1, inspect the expectation diff rather than accepting it blindly.
• Use RUN_SLOW_TESTS=1 cargo test when the affected area has slow tests.