AGENTS.md@packages/review git:20261010.e7fb7acA

Immutable. This exact content never changes and is served at /api/v1/blob/bd3c35535bd3381e.

# @shadowclone/review

The pull request review engine. It collects the diff and standards, runs rules and toolchain checks, asks a model for findings, and publishes the result.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/review`
- Workspace dependencies: `@shadowclone/agents`, `@shadowclone/core`, `@shadowclone/redact`
- External dependencies: `smol-toml`, `zod`
- Export subpaths: `.`

<!-- package-facts:end -->

## Owns

- `src/collect/`: pull request and branch facts, the diff, history, and the standards at the base commit.
- `src/rules/` and `src/toolchain/`: built-in rules and the repository checks by language stack.
- `src/stages/` and `src/analyze.ts`: `prepareStage`, `checksStage`, `analyzeStage`, and the model call.
- `src/evidence/` and `src/dependencies/`: documentation quote checks and lockfile checks.
- `src/local.ts`, `markdown.ts`, and `publish/`: `reviewLocally`, `reviewBranch`, `reviewMarkdown`, and `publishReview`.

## Rules

- The model can use only the review tools of `agents`: `Read`, `Grep`, `Glob`, and `Agent`. Web tools need the network option.
- Toolchain checks get a fixed list of environment variables, with no token. JavaScript installs use `--ignore-scripts`. When pnpm or Yarn is missing, `toolchain/corepack.ts` runs them through Corepack. `toolchain/projects.ts` runs a stack in the nearest configured folder when the root does not configure it. `toolchain/cache.ts` sets the 10 minute budget and the shared Cargo build folder.
- `neutralizeText` redacts every posted text. It wraps mentions, cross-repository references, and GitHub thread links in code spans.
- `publishReview` posts a `COMMENT` review only. It never approves and never requests changes.
- `rank.ts` keeps 10 findings for each review part, and 25 at most. It keeps every high severity finding up to 25. `shards.ts` puts each changed file in exactly one part.
- A fetched documentation address must be public. `evidence/addresses.ts` refuses private, loopback, and metadata addresses.

## Tests

Run `bun test` in this folder, or `bun test packages/review` from the root. Several tests build temporary Git repositories, so `git` must be on the path. The model runner is a mock.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.