@agentskit/code-review 0.1.0 → 0.4.2

package/llms-full.txt

@@ -0,0 +1,1055 @@
+# AgentsKit Code Review — full documentation corpus
+
+Generated from the public repository documentation. Prefer llms.txt for concise discovery and this file only when the full operating and ownership context is required.
+
+## AgentsKit ecosystem
+
+- AgentsKit: https://www.agentskit.io/docs
+- AgentsKit Registry: https://registry.agentskit.io/docs
+- AgentsKit Chat: https://chat.agentskit.io/docs
+- Agents Playbook: https://playbook.agentskit.io/docs
+- Doc Bridge: https://agentskit-io.github.io/doc-bridge/
+- AgentsKit Code Review: https://github.com/AgentsKit-io/code-review#readme
+- AgentsKit OS: https://akos.agentskit.io/docs
+
+## Public README
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/README.md
+
+<p align="center">
+  <img src="docs/assets/agentskit-mark.svg" width="64" height="57" alt="AgentsKit" />
+</p>
+
+# AgentsKit Code Review
+
+Profile: <code>top-level-repository</code>
+
+**Deep, low-noise AI code review with the model you already use.**
+
+It is intended for developers and teams who want focused review feedback without changing their model subscription, and without adopting a separate chat product surface.
+
+[![CI](https://github.com/AgentsKit-io/code-review/actions/workflows/ci.yml/badge.svg)](https://github.com/AgentsKit-io/code-review/actions/workflows/ci.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13866/baseline)](https://www.bestpractices.dev/projects/13866)
+[![License: MIT](https://img.shields.io/badge/License-MIT-0f766e.svg)](https://github.com/AgentsKit-io/code-review/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://github.com/AgentsKit-io/code-review/blob/main/package.json)
+
+**Tags:** `agentskit` · `ai-code-review` · `github-action` · `typescript` · `sarif` · `codex` · `claude` · `ollama`
+
+**Topics:** `ai-agents` · `code-review` · `developer-experience`
+
+**Ecosystem:** [AgentsKit](https://www.agentskit.io/docs) · [Registry](https://registry.agentskit.io/docs) · [Chat](https://chat.agentskit.io/docs) · [Playbook](https://playbook.agentskit.io/docs) · [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) · **Code Review** · [AKOS](https://akos.agentskit.io/docs)
+
+Run code review locally or on every pull request. Bring Claude, Codex, OpenAI, Gemini, Ollama, OpenRouter, or another supported AgentsKit adapter. Seven focused review lenses propose potential problems; adversarial verification filters weak findings before they reach your team.
+
+## Verified proof
+
+- Offline CLI discovery works without credentials (`--help`, `--list-providers`) — covered by `test/cli-smoke.test.mjs`.
+- A clean local Codex CLI fixture completes an offline stdin review — covered by the same smoke suite.
+- Documentation, Action contract, and Doc Bridge gates run through `npm run check`.
+- Machine-readable public map: [`llms.txt`](https://github.com/AgentsKit-io/code-review/blob/main/llms.txt) and [`docs/for-agents/code-review-cli.md`](https://github.com/AgentsKit-io/code-review/blob/main/docs/for-agents/code-review-cli.md).
+
+## Why this exists
+
+Most AI reviewers are easy to start and hard to trust: they produce long lists of stylistic opinions, repeat the same concern, and bury the issue that can actually break production.
+
+AgentsKit Code Review is built around a different contract:
+
+- **Bring your own model.** Use an existing CLI subscription, an API provider, a local model, or your own gateway.
+- **Low noise by design.** Findings are challenged by independent verification votes before they survive.
+- **Local first, CI ready.** Review a diff before pushing, inspect complete paths, read stdin, or comment directly on a GitHub PR.
+- **Control cost and policy.** Set file budgets, concurrency, thresholds, project conventions, and blocking severity.
+- **See the cost before execution.** Use `--plan --json` to inspect files, lenses, retries, concurrency, deadline, estimated provider calls, and every `UNREVIEWED` path with its reason without a model request. Estimates are always `best-effort` because primary lens demand is predictable but model output determines how many skeptical verification calls are needed; the runtime counter remains the hard ceiling.
+
+## Run your first review
+
+Open a terminal inside any Git repository and choose a provider you already use. You do not need to clone or install AgentsKit Code Review:
+
+<!-- readme-example:first-review -->
+```sh
+# Codex CLI — uses your existing login on a trusted local machine
+npx --yes github:AgentsKit-io/code-review --provider codex-cli --mode trusted-local
+
+# Claude CLI — uses your existing login
+npx --yes github:AgentsKit-io/code-review --provider claude-cli
+
+# OpenAI API
+OPENAI_API_KEY=... npx --yes github:AgentsKit-io/code-review \
+  --provider openai --model gpt-4o
+```
+
+The CLI reviews the current repository's diff against `origin/main` and prints the report in your terminal. Choose another base with `--base main`.
+
+For the Grok Build ACP worker, use `XAI_API_KEY` (or `--api-key`) in the default isolated mode. To reuse `grok login`, opt in explicitly with `--mode trusted-local`.
+
+Local `codex-cli` subprocesses have a 300-second deadline per model call; `claude-cli` and the other local workers use 120 seconds. Every run also has a global deadline (10 minutes for full, 2 minutes for `fast`) and a bounded Codex smoke check before fan-out. Set `--deadline-ms` for a smaller explicit budget; timed-out calls fail explicitly and cannot turn an unreviewed file into an approval.
+
+Terminal provider authentication failures stop the remaining lenses immediately; the review still exits incomplete and never converts a credential failure into approval.
+
+The default `isolated` mode does not inherit an interactive CLI login. Use `--mode trusted-local` only on a machine or runner you trust with the provider's local session and environment.
+
+`grok-cli` is stable and uses Grok Build's ACP transport (`grok agent stdio`) by default. In the default isolated mode, pass `XAI_API_KEY`/`--api-key`; the key is injected into the isolated worker environment, never into command arguments. Existing `grok login` state is available only with explicit local-only `--mode trusted-local`. Isolated workers grant no filesystem write, terminal, MCP, plugin, or subagent capability and use a temporary working directory. `--transport headless` is available for explicit non-interactive runs, while `--transport auto` is local-only and reports an ACP fallback before trying headless.
+
+`opencode-cli` is stable and uses OpenCode's ACP transport (`opencode acp`) by default. In the default isolated mode, pass `OPENCODE_API_KEY`/`--api-key`; the selected key is injected into the isolated worker environment, never into command arguments. Existing OpenCode login/configuration state is available only with explicit local-only `--mode trusted-local`. OpenCode is not installed automatically. `--transport headless` is available for explicit non-interactive runs, while `--transport auto` is local-only and reports an ACP fallback before trying headless.
+
+Preflight refuses an over-budget run before the first provider call. For GitHub PR sources, the CLI automatically caps the reviewed files to the safe call budget when `--max-files` is omitted; the remaining files are marked `UNREVIEWED`, so the result stays incomplete and cannot approve the PR. Use `--max-files` to choose a smaller explicit scope. `--dry-run` and `--plan` print the cap and concrete reductions; `--json` makes the plan machine-readable. CLI providers default to concurrency `1`, while API providers retain concurrency `4`. Required-lens or source coverage failures always exit `2`, even with `--no-fail`.
+Use `--profile fast` when latency and provider budget matter more than the optional lenses: correctness, security, and tests run in one structured batch with one verification vote and no retry. The result records provider calls, failures, skips, elapsed time, circuit state, and whether the deadline fired. Any incomplete evidence remains fail-closed.
+
+### Complete coverage for large PRs
+
+Do not silently cap a large PR and treat the partial result as clean. `--plan --json --batch-size <n>` exposes a stable, alphabetically ordered file manifest. With a GitHub PR, `--batch-manifest <private-file>` writes the immutable state that binds every batch to the exact head SHA and review-policy fingerprint. Run each batch with `--batch-index <n> --result <private-file>`; partial batches reject `--post` and their result files are private (`0600`). `--consolidate-manifest <manifest> --artifacts <comma-list> --result <private-file>` accepts only every planned batch with complete evidence. Its output is the only artifact accepted by `--publish-result <file> --pr owner/repo#N --post`; that command rechecks the current SHA and policy before creating one GitHub review. A new commit or policy change invalidates the artifacts and requires a new manifest.
+
+![AgentsKit Code Review showing an APPROVE result after seven review lenses complete](https://raw.githubusercontent.com/AgentsKit-io/code-review/main/docs/assets/code-review-terminal.png)
+
+The current command runs directly from GitHub. After the first npm release, the shorter form will be:
+
+```sh
+npx @agentskit/code-review --provider codex-cli
+```
+
+## Run through pre-commit
+
+The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter.
+
+Add this to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AgentsKit-io/code-review
+    rev: main # pre-release; pin a release tag when one contains the hook
+    hooks:
+      - id: agentskit-review
+        args: [--provider, codex-cli, --no-fail, --max-files, "20"]
+```
+
+Then run it when a change is ready for review:
+
+```sh
+pre-commit run --hook-stage manual agentskit-review
+```
+
+The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository.
+
+### Review locally with Ollama
+
+Use Ollama when repository policy requires model inference to stay on a machine or self-hosted runner. Pull a tool-capable coding model that fits the available memory, start Ollama, and review a small branch diff first:
+
+```sh
+ollama pull qwen2.5-coder:7b
+
+npx --yes github:AgentsKit-io/code-review \
+  --provider ollama \
+  --model qwen2.5-coder:7b \
+  --base main \
+  --base-url http://localhost:11434 \
+  --max-files 10 \
+  --concurrency 1 \
+  --no-fail
+```
+
+This reviews committed changes between `main` and `HEAD`; it is not a staged-files-only hook. The selected model must support Ollama tool calling because every review lens submits a structured result. Requests have a 30-second default deadline. `--no-fail` keeps findings advisory, but connection, source, and execution errors still exit nonzero. No provider key is required. Local inference reduces code disclosure, but logs, SARIF files, caches, optional gateways, and observability exporters still need their own access and retention policy.
+
+See the [operations guide](https://github.com/AgentsKit-io/code-review/blob/main/docs/OPERATIONS.md#local-ollama-review) for model sizing, health checks, failure handling, and self-hosted CI guidance.
+
+## Use the GitHub Action
+
+Add `.github/workflows/code-review.yml` to any repository:
+
+```yaml
+name: Code Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: AgentsKit-io/code-review@v0.4.0
+        with:
+          provider: openai
+          model: gpt-4o
+          api-key: ${{ secrets.LLM_API_KEY }}
+          # max-files: '17'
+          # max-calls: '1000'
+          # max-findings-per-file: '7'
+          # profile: 'full' # or fast for a bounded required-lens batch
+          # deadline-ms: '600000'
+          # fail-on-block: 'true' # advisory by default
+          # block: high
+```
+
+The Action fetches the PR diff and posts one batched inline review plus a compact, persistent walkthrough. The walkthrough reports outcome and review evidence; actionable detail appears only on the relevant diff lines. Its defaults review at most 17 files, 7 findings per file, and 1,000 provider calls. It is advisory by default. Advisory mode affects findings only: source, provider, or execution failures still fail the check, and any reviewable file with zero successful primary lenses prevents approval. `codex-cli` requires a pre-authenticated `trusted-local` self-hosted runner; use an API provider with a secret on GitHub-hosted runners. Enable `fail-on-block` and branch protection when you are ready to use findings as a merge gate.
+
+Building a conversational review experience? Use [AgentsKit Chat](https://chat.agentskit.io/docs) for the cross-framework application layer instead of embedding chat here. Looking for organization-wide orchestration, governance, and production controls? Continue with [AKOS](https://akos.agentskit.io/docs).
+
+Pin the Action to an immutable release tag such as `@v0.4.0`; use a full commit SHA when your policy requires the strongest reproducibility.
+
+## Choose how to run
+
+| Mode | Provider examples | Credentials | Best for |
+|---|---|---|---|
+| Local CLI | `codex-cli`, `claude-cli`, `grok-cli`, `opencode-cli` | Existing CLI login | Local development or self-hosted runners |
+| Hosted API | `openai`, `anthropic`, `gemini`, `mistral`, `groq` | Provider API key | Managed CI |
+| Local model | `ollama` | Usually none | Privacy and predictable cost |
+| Gateway | `openrouter` or a custom `--base-url` | Gateway-specific | Central routing and policy |
+
+`grok` is the xAI API provider; `grok-cli` is the separate Grok Build CLI entry. `opencode-cli` is the OpenCode CLI entry. API providers are discovered from factories exported by [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters). Run `npx --yes github:AgentsKit-io/code-review --list-providers` to see IDs, support levels, transports, and model requirements.
+
+Credentials resolve in this order:
+
+1. `--api-key`
+2. `LLM_API_KEY`
+3. `<PROVIDER>_API_KEY`, such as `OPENAI_API_KEY`
+
+Secrets passed to the GitHub Action are forwarded through the environment, not included in command-line arguments.
+
+## How review works
+
+```mermaid
+flowchart LR
+  A["Diff · PR · paths · stdin"] --> B["Normalize targets"]
+  B --> C["7 focused lenses"]
+  C --> D["Adversarial verification"]
+  D --> E["Thresholds + CI policy"]
+  E --> F["Markdown · GitHub · SARIF"]
+  D -. "weak finding" .-> G["Dropped with audit note"]
+```
+
+The review agent lives in `agents/code-review/` and is vendored from the [AgentsKit registry](https://github.com/AgentsKit-io/agentskit-registry/tree/main/registry/code-review). The CLI owns provider selection, input sources, policy, and reporting.
+
+## Common commands
+
+```sh
+# Tune verification and severity
+npx --yes github:AgentsKit-io/code-review --provider codex-cli \
+  --base main --votes 5 --min-severity high
+
+# Review a GitHub PR and post the result
+GITHUB_TOKEN=... OPENAI_API_KEY=... \
+  npx --yes github:AgentsKit-io/code-review --provider openai --model gpt-4o \
+  --pr owner/repo#42 --post
+
+# Review complete files or directories
+npx --yes github:AgentsKit-io/code-review --provider claude-cli \
+  --paths src --max-files 30
+
+# Review piped source and also write SARIF
+echo 'const x = a.b' | npx --yes github:AgentsKit-io/code-review \
+  --provider ollama --model llama3 \
+  --base-url http://localhost:11434 --stdin --lang ts --sarif out.sarif
+
+# After fetching the PR base and installing reviewdog, reuse its annotation transport
+REPORT_FILE="$(mktemp)"
+trap 'rm -f "${REPORT_FILE}"' EXIT
+npx --yes github:AgentsKit-io/code-review#3dfd7427640148281454d52846d369e5ddf85b11 \
+  --provider openai --model gpt-4o \
+  --base "origin/${BASE_REF}" --sarif "${REPORT_FILE}" --no-fail &&
+reviewdog -f=sarif -name=agentskit-review \
+  -reporter=github-pr-review -filter-mode=added -fail-level=error \
+  < "${REPORT_FILE}"
+```
+
+The reviewdog recipe needs no custom converter: Code Review emits SARIF 2.1.0 and reviewdog consumes SARIF natively. See the [complete GitHub Actions job](https://github.com/AgentsKit-io/code-review/blob/main/docs/OPERATIONS.md#route-findings-through-reviewdog) for pinned installation, base-branch checkout, permissions, severity mapping, and CI ownership of the failure threshold.
+
+## CLI reference
+
+### Providers
+
+Run these commands from the repository you want to review:
+
+| Provider | What you need | Model | Example |
+|---|---|---|---|
+| `codex-cli` | Codex CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review --provider codex-cli` |
+| `claude-cli` | Claude CLI logged in | Optional | `npx --yes github:AgentsKit-io/code-review --provider claude-cli` |
+| `grok-cli` | Grok Build CLI; stable ACP/headless | Optional | `... --provider grok-cli` |
+| `opencode-cli` | OpenCode CLI; stable ACP/headless | Optional | `... --provider opencode-cli` |
+| `openai` | `OPENAI_API_KEY` | Required | `... --provider openai --model gpt-4o` |
+| `anthropic` | `ANTHROPIC_API_KEY` | Required | `... --provider anthropic --model <model>` |
+| `gemini` | `GEMINI_API_KEY` | Required | `... --provider gemini --model <model>` |
+| `ollama` | Ollama running locally | Required | `... --provider ollama --model llama3 --base-url http://localhost:11434` |
+| `openrouter` | `OPENROUTER_API_KEY` | Required | `... --provider openrouter --model <model>` |
+| Other adapters | `<PROVIDER>_API_KEY` when applicable | Usually required | `... --provider <name> --model <model>` |
+
+In shortened examples, replace `...` with `npx --yes github:AgentsKit-io/code-review`.
+
+### Options
+
+| Flag | Meaning |
+|---|---|
+| `--provider <name>` | Required provider: local CLI or `@agentskit/adapters` factory |
+| `--model <id>` | Model id; required for API/local-server providers |
+| `--api-key <key>` | Provider key; environment variables are preferred |
+| `--base-url <url>` | Provider endpoint, local server, or gateway |
+| `--transport <name>` | Provider transport: `acp`, `headless`, or local-only `auto` where supported |
+| `--base <ref>` | Git diff base; default `origin/main` |
+| `--pr owner/repo#N` | GitHub PR source; requires `GITHUB_TOKEN` |
+| `--paths <p...>` | Complete files or directories |
+| `--stdin [--lang ts]` | Source read from stdin |
+| `--post` | Post a batched review when the source is a PR |
+| `--sarif <file>` | Also write SARIF |
+| `--votes <n>` | Adversarial verification votes; default `3` |
+| `--profile <full\|fast>` | Full review or one bounded required-lens batch |
+| `--min-severity <level>` | Minimum reported severity |
+| `--min-confidence <n>` | Minimum reported confidence |
+| `--max-files <n>` | Positive file budget; over-budget runs are refused before the provider |
+| `--max-calls <n>` | Provider-call budget; absolute ceiling `1000` |
+| `--max-findings-per-file <n>` | Maximum verified findings per file; bounds adversarial verification calls |
+| `--concurrency <n>` | Parallel model calls; default `1` for CLI providers, `4` for API providers |
+| `--deadline-ms <n>` | Global run deadline; defaults to `600000` (`120000` for `fast`) |
+| `--health-check <auto\|off>` | Bounded provider smoke check before model fan-out |
+| `--plan`, `--dry-run` | Print provider-free preflight; add `--json` for machine output |
+| `--validate-patch` | Run `git apply --check` on suggested patches |
+| `--block <severity>` | CI gate floor; default `blocker` |
+| `--no-fail` | Keep findings advisory |
+| `--conventions <path>` | Inject project conventions |
+| `--allow-incomplete` | Local-only exception for a config that declares incomplete lens coverage |
+| `--allow-unredacted` | Local-only exception; rejected in CI |
+| `--api` | Back-compatible alias for `--provider anthropic` |
+| `doctor --provider <name>` | Offline provider diagnostics; no model request |
+| `doctor --live` | Explicit provider smoke-test mode |
+| `doctor --json` | Stable machine-readable diagnostics |
+| `--mode <mode>` | `isolated` (default) or explicit local-only `trusted-local` |
+| `--help` | Full command help |
+
+When no conventions path is supplied, the CLI looks for `CONVENTIONS.md`, `CONTRIBUTING.md`, `.cursorrules`, or `AGENTS.md`.
+
+### Versioned configuration
+
+The repository may contain one strict `.agentskit-review.json` file. It must use
+`configVersion: 1`; unknown fields, secrets, unsupported values, and unsafe lens
+policies fail before provider execution with exit `2`. Every built-in lens is
+enabled by default, with `correctness`, `security`, and `tests` required. Flags
+override file values. A required lens may only be disabled in an explicitly
+declared `incompleteProfile`, which requires `--allow-incomplete` locally and is
+never accepted in CI.
+
+```json
+{
+  "configVersion": 1,
+  "profile": "full",
+  "lenses": {
+    "performance": { "enabled": false, "required": false }
+  },
+  "votes": 3,
+  "budget": { "maxFiles": 20, "maxCalls": 200, "concurrency": 1, "deadlineMs": 600000 },
+  "worker": { "timeoutMs": 120000, "maxOutputBytes": 20971520 },
+  "thresholds": { "minSeverity": "med", "minConfidence": 0.7 },
+  "context": { "mode": "prompt", "patterns": ["src/**"] }
+}
+```
+
+Provider, model, transport, context trust, redaction, and permissions are
+trusted execution inputs; a project config cannot set them in CI. Put provider
+credentials only in the environment or provider login, never in this file.
+Remote and unknown provider boundaries redact high-confidence credential
+patterns before the model sees source. Unsafe, oversized, binary, or excluded
+paths are reported as `UNREVIEWED`; content is never silently truncated.
+
+### Doctor
+
+Run `doctor` before a review to check a registered provider’s executable, version, transport, model requirement, configuration mode, and credential presence. It is offline by default; `doctor --live` and normal Codex reviews use a bounded smoke check to catch authentication or hangs before fan-out. API credentials are checked only for presence and values are never printed. Unknown local CLI versions warn locally and fail when `CI=true`. Exit `0` means healthy, `1` means a failed diagnostic, and `2` means invalid CLI usage.
+
+```sh
+npx --yes github:AgentsKit-io/code-review doctor --provider codex-cli
+npx --yes github:AgentsKit-io/code-review doctor --provider openai --model gpt-4o --json
+```
+
+## Cost and privacy
+
+A full review runs seven lenses across selected files and then verifies candidate findings. Control usage with `--profile fast`, `--max-files`, `--max-calls`, `--votes`, `--deadline-ms`, `--concurrency`, paths, and workflow triggers. For sensitive code, use a local model or an approved private gateway; provider data policies still apply to hosted APIs.
+
+## Operations and machine-readable docs
+
+- [Operations guide](https://github.com/AgentsKit-io/code-review/blob/main/docs/OPERATIONS.md) — providers, permissions, secrets, cost controls, SARIF, failures, releases, and incident-safe defaults.
+- [Provider compatibility matrix](https://github.com/AgentsKit-io/code-review/blob/main/docs/provider-compatibility.json) — stable CLI transports and their offline fixtures.
+- [Agent handoff](https://github.com/AgentsKit-io/code-review/blob/main/docs/for-agents/code-review-cli.md) — ownership, edit roots, verification commands, and change routes.
+- [`llms.txt`](https://github.com/AgentsKit-io/code-review/blob/main/llms.txt) — compact public source map for LLMs and coding agents.
+- [`llms-full.txt`](https://github.com/AgentsKit-io/code-review/blob/main/llms-full.txt) — complete README, operations, and agent-handoff corpus.
+- [`doc-bridge.config.json`](https://github.com/AgentsKit-io/code-review/blob/main/doc-bridge.config.json) — executable Doc Bridge corpus, ownership, and gate contract.
+
+`npm run check` builds the CLI, executes a full credential-free review fixture, validates the composite Action and documentation contract, runs Doc Bridge gates, checks CLI help, and enforces README Standard v1. Prove credential-free discovery with:
+
+```sh
+node examples/verify-readme.mjs
+```
+
+`npm pack --dry-run` verifies the release payload.
+
+## Maturity
+
+The repository is **pre-v1 (`0.4.x`)**. The CLI and Action are available for evaluation and advisory CI; use an exact release tag such as `@v0.4.0` or a commit SHA, and treat the future `v1` moving tag as a separate stability milestone. See [ROADMAP.md](https://github.com/AgentsKit-io/code-review/blob/main/ROADMAP.md) and the [release guidance](https://github.com/AgentsKit-io/code-review/blob/main/docs/OPERATIONS.md#releases-and-maturity).
+
+## Compatibility
+
+- **Node.js 20+** (see `engines` in `package.json`)
+- **TypeScript** source and compiled ESM distribution
+- **GitHub Actions** composite Action at repository root (`action.yml`)
+- Providers via local CLIs or [`@agentskit/adapters`](https://www.npmjs.com/package/@agentskit/adapters)
+
+## AgentsKit ecosystem
+
+Code Review is the verification step in the broader AgentsKit journey:
+
+| Need | Continue with |
+|---|---|
+| Build the agent or custom review adapter | [AgentsKit](https://www.agentskit.io/docs) |
+| Install the vendored review agent or explore ready agents | [Registry](https://registry.agentskit.io/docs) |
+| Deliver review through a conversational application | [AgentsKit Chat](https://chat.agentskit.io/docs) |
+| Apply engineering patterns before review | [Playbook](https://playbook.agentskit.io/docs) |
+| Generate ownership-aware documentation handoffs | [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) ([source](https://github.com/AgentsKit-io/doc-bridge)) |
+| Add enterprise orchestration and production governance | [AKOS](https://akos.agentskit.io/docs) |
+
+This repository intentionally has **no Fumadocs application and no embedded AgentsChat**. Its public product surface is the CLI, GitHub Action, repository documentation, and machine-readable handoffs.
+
+## Contributing
+
+Providers, review lenses, reporters, fixtures, documentation, and false-positive reductions are welcome. Start with [CONTRIBUTING.md](https://github.com/AgentsKit-io/code-review/blob/main/CONTRIBUTING.md), browse issues labeled `good first issue`, or propose a new provider/lens with the issue templates.
+
+Please report vulnerabilities privately as described in [SECURITY.md](https://github.com/AgentsKit-io/code-review/blob/main/SECURITY.md).
+Maintainer responsibilities, public decision-making, and the release process are
+documented in [GOVERNANCE.md](https://github.com/AgentsKit-io/code-review/blob/main/GOVERNANCE.md).
+
+## Roadmap
+
+The near-term roadmap focuses on a stable `v1` Action, npm distribution, provider smoke tests, better cost visibility, and more community-owned review lenses. See [ROADMAP.md](https://github.com/AgentsKit-io/code-review/blob/main/ROADMAP.md).
+
+## License
+
+[MIT](https://github.com/AgentsKit-io/code-review/blob/main/LICENSE) © AgentsKit contributors.
+## Operations guide
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/docs/OPERATIONS.md
+
+# Code Review operations guide
+
+This guide is the repository-native reference for running AgentsKit Code Review locally and in CI. The CLI is the source of truth for flags; run `agentskit-review --help` against the version or commit you use.
+
+## Provider and credential choices
+
+| Provider class | Examples | Secret or login | Network boundary |
+|---|---|---|---|
+| Logged-in local CLI | `codex-cli`, `claude-cli`, `grok-cli`, `opencode-cli` | Existing local login | Provider CLI policy |
+| Hosted API | `openai`, `anthropic`, `gemini`, `mistral`, `groq` | Repository/org secret | Selected code reaches provider |
+| Local model | `ollama` | Usually none | Host or runner network only |
+| Gateway | `openrouter`, custom `--base-url` | Gateway secret | Gateway policy and routing |
+
+Credential precedence is `--api-key`, `LLM_API_KEY`, then `<PROVIDER>_API_KEY`. Prefer environment variables and GitHub secrets: process arguments may be visible to other processes or captured by diagnostics. The composite Action forwards its secret through `LLM_API_KEY` and never adds it to CLI arguments.
+
+Do not run hosted review on code whose policy forbids external processing. A local model reduces external disclosure but does not remove the need to secure the runner, logs, cache, and generated SARIF.
+
+## Provider registry and doctor
+
+Provider IDs are versioned registry entries. `grok` is the xAI API adapter, while `grok-cli` and `opencode-cli` are stable local CLI providers. `--list-providers` prints registry metadata and dynamically discovered API factories, including each support level (`stable`, `experimental`, or `unsupported`), transport, and model requirement.
+
+Use the offline doctor before execution:
+
+```sh
+npx --yes github:AgentsKit-io/code-review doctor --provider codex-cli
+npx --yes github:AgentsKit-io/code-review doctor --provider openai --model gpt-4o --json
+```
+
+It checks the named executable and version, transport, model requirement, configuration mode, and credential presence without making a model request. API keys are represented only as `configured` or `missing`; they are never printed. Local CLI credentials are represented as login-managed because login storage is provider-specific. `doctor --live` is the explicit provider smoke-test path; normal Codex reviews run the same bounded smoke check before fan-out. Unknown local CLI versions warn during local runs and fail in CI. Doctor exits `0` when checks pass, `1` when a provider check fails, and `2` for invalid usage.
+
+## First local setup
+
+```sh
+git clone https://github.com/AgentsKit-io/code-review.git
+cd code-review
+npm install
+npm run check
+npx --yes github:AgentsKit-io/code-review --provider opencode-cli --transport acp --model openai/gpt-4o --no-fail
+```
+
+The last command requires an installed and authenticated OpenCode CLI. For a
+credential-free verification, `npm run check` uses only the committed offline
+fixtures. Precedence is explicit CLI flags, then the repository's
+`.agentskit-review.json` policy, then safe defaults; the project file never
+selects a trusted execution mode or carries credentials.
+
+## Grok Build CLI via ACP
+
+`grok-cli` is stable and uses `--transport acp` by default. It
+starts `grok agent stdio --no-auto-update`, performs the ACP initialize,
+authentication (when advertised), session, prompt, update, shutdown, and exit
+sequence, then emits one `submit_findings` tool call. The worker accepts only a
+`schemaVersion: 1` envelope with valid findings; malformed output gets one
+bounded retry.
+
+In the default `isolated` mode, provide `XAI_API_KEY` through the environment
+or `--api-key`; the selected key is copied only into the temporary worker
+environment. Existing `grok login` state is available only with explicit
+local-only `--mode trusted-local`. Filesystem writes, terminal, MCP, plugin,
+and subagent requests are denied, and the worker never uses the checkout as
+its working directory. `doctor --provider grok-cli` checks executable/version
+availability without making a model request. Headless mode is documented below
+and must be selected explicitly.
+
+## OpenCode CLI via ACP
+
+`opencode-cli` is stable and uses `--transport acp` by default.
+It starts `opencode acp`, performs the ACP initialize, session, prompt, update,
+shutdown, and exit sequence, then emits one validated `submit_findings` tool
+call. When `--model` is provided it is passed as OpenCode's `--model` option.
+The worker allows no filesystem writes, terminal, MCP, plugin, or subagent
+requests and retries malformed output once.
+
+In the default `isolated` mode, provide `OPENCODE_API_KEY` through the
+environment or `--api-key`; the selected key is copied only into the temporary
+worker environment. Existing OpenCode login/configuration state is available
+only with explicit local-only `--mode trusted-local`. The CLI does not install
+OpenCode automatically.
+`doctor --provider opencode-cli` checks executable/version availability without
+making a model request. Headless mode is documented below and must be selected
+explicitly.
+
+## Grok and OpenCode headless transport
+
+Headless mode is explicit with `--transport headless`. Grok uses
+`grok --no-auto-update -p <prompt> --output-format json`; OpenCode uses
+`opencode run --format json [--model provider/model] <prompt>`. Their output
+framings are parsed separately and normalized to the same strict
+`schemaVersion: 1` envelope. Surrounding logs are bounded and tolerated only
+when the validated envelope can still be recovered.
+
+`--transport auto` is a local convenience for these two providers:
+it tries ACP first, reports the reason on stderr, then tries the provider's
+headless command. It is rejected in CI so a pipeline cannot silently change
+transport. Both paths use the same isolated worker timeout, output cap,
+cancellation, temporary working directory, selected-credential injection, and
+redacted diagnostics. Neither path installs a provider CLI automatically.
+
+The executable compatibility source of truth is
+[`provider-compatibility.json`](https://github.com/AgentsKit-io/code-review/blob/main/docs/provider-compatibility.json). It lists the
+stable providers, every supported transport, required lenses, minimum version,
+and the offline fixture that proves each cell. A provider remains experimental
+until its registry entry, matrix, fixtures, and doctor checks are all green.
+
+## pre-commit integration
+
+The root `.pre-commit-hooks.yaml` exposes `agentskit-review` as a Node hook. It uses `pass_filenames: false` because the CLI reviews a Git diff, explicit paths, a pull request, or stdin rather than interpreting positional filenames. It is confined to the `manual` stage by default so cloning the hook does not silently add model calls to every commit.
+
+Consumer configuration must select a provider through `args`. Keep credentials in the provider login or environment; never place API keys in `.pre-commit-config.yaml`. Before overriding the hook to `stages: [pre-push]`, decide whether findings are advisory, set a file budget, and confirm that provider latency and data handling are appropriate for every contributor.
+
+The default diff base remains `origin/main`. A pre-commit invocation does not mean the input is limited to the Git staging area. Set `--base` explicitly when the repository uses another integration branch.
+
+## Versioned review configuration
+
+Use a strict `.agentskit-review.json` at the repository root for review policy.
+It requires `configVersion: 1` and supports a `full` or `fast` profile. The
+fast profile reviews correctness, security, and tests in one bounded batch with
+one vote and no retry. The config also supports lens policy (`enabled` and
+`required` per built-in lens), votes, retries, thresholds, file/byte/call,
+concurrency and global-deadline budgets, conventions, and context selection. All built-in lenses
+are enabled by default; correctness, security, and tests are required.
+The shared local worker also accepts bounded `timeoutMs` and `maxOutputBytes`
+settings; absolute ceilings are always enforced.
+
+Flags override file values. The file cannot contain credentials or executable
+plugins. Provider, model, transport, trust mode, redaction, permissions, and
+other execution inputs are rejected when supplied by the project config in CI.
+An intentionally incomplete profile must say `incompleteProfile: true` and be
+run locally with `--allow-incomplete`; it is rejected in CI and cannot become an
+approval. Malformed, unknown, or unsafe configuration exits `2` before a model
+request and diagnostics do not print config values.
+
+Keep policy-only configuration in the file. Use trusted workflow flags or the
+runner environment for provider selection, credentials, and execution mode.
+
+`prompt` is the default context mode. To review an explicit repository snapshot,
+set `context.mode` to `isolated-snapshot` and provide repository-relative
+patterns such as `src/**` or `!src/generated/**`. Sensitive directories/files,
+symlink escapes, binaries, and over-limit inputs are excluded and shown as
+`UNREVIEWED`. The default snapshot ceiling is 100 files/5 MiB; the absolute
+ceiling is 500 files/25 MiB. Prompt files default to 256 KiB with a 1 MiB
+absolute per-file ceiling.
+
+Remote and unknown provider boundaries receive high-confidence credential
+redaction while preserving file and line context. `--allow-unredacted` is a
+local-only escape hatch and is rejected in CI; never use it for untrusted code.
+
+## Local Ollama review
+
+Ollama serves its local API at `http://localhost:11434` by default. Verify the service without sending repository content:
+
+```sh
+curl --fail --silent http://localhost:11434/api/tags >/dev/null
+```
+
+Choose a tool-capable model that fits the host; tool calling is required because every lens submits a structured result. `qwen2.5-coder:7b` is a practical starting point for machines that cannot run the larger `qwen3-coder:30b`; model quality, context capacity, latency, and memory requirements vary. Pulling a model downloads several gigabytes and does not start a review:
+
+```sh
+ollama pull qwen2.5-coder:7b
+```
+
+Start with a bounded, advisory branch review:
+
+```sh
+npx --yes github:AgentsKit-io/code-review \
+  --provider ollama \
+  --model qwen2.5-coder:7b \
+  --base main \
+  --base-url http://localhost:11434 \
+  --max-files 10 \
+  --concurrency 1 \
+  --no-fail
+```
+
+The default source is the committed Git diff from `--base` to `HEAD`. It does not mean “only staged files,” even when invoked by a Git hook. Use `--paths` when complete files are the intended source. Avoid piping a unified Git patch through `--stdin`: stdin is treated as one source file rather than parsed into per-file changed ranges.
+
+Seven primary lenses plus adversarial votes can be expensive for a local model, and each structured result can require more than one model turn. Begin with `--max-files 10`, `--concurrency 1`, and the default three votes. Reduce the file set before reducing verification depth. `--no-fail` makes surviving findings advisory; it does not hide an unavailable model, malformed response, unreadable source, or failed lens coverage.
+
+For a self-hosted runner, bind Ollama only to the network interfaces required by the job, isolate the runner per repository trust boundary, and protect job logs and artifacts. Do not set a hosted gateway as `--base-url` and describe the run as local. Any optional telemetry or observability exporter creates a separate network boundary that must be approved explicitly.
+
+Troubleshooting:
+
+- **Connection refused:** start Ollama and repeat the `/api/tags` health check.
+- **Model not found:** run `ollama pull <exact-model-id>` and pass the same id to `--model`.
+- **Slow or out-of-memory:** choose a smaller model, reduce `--max-files`, and keep `--concurrency 1`.
+- **Context overflow:** review narrower paths or a smaller branch diff; unreviewed files must remain visibly outside the result.
+- **No findings with exit 0:** inspect the summary and successful/failed lens counts; advisory output is not proof that every file was reviewed.
+
+## GitHub Action permissions
+
+The copy-ready workflow in [`examples/pull-request.yml`](https://github.com/AgentsKit-io/code-review/blob/main/examples/pull-request.yml) requires:
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+`contents: read` loads the PR source. `pull-requests: write` posts the batched review. Do not grant repository administration, package write, or workflow write. Fork PRs do not receive normal repository secrets; do not switch to `pull_request_target` merely to expose a model key, because that can execute or process untrusted contributions with privileged context.
+
+The composite Action defaults to 17 files, 7 findings per file, 1,000 provider calls, and a 10-minute global deadline. `codex-cli` is accepted only with `mode: trusted-local` on a pre-authenticated self-hosted runner; use an API provider with a secret on GitHub-hosted runners.
+
+Use environment protection or organization secrets for sensitive providers. Rotate a secret after suspected exposure and review provider usage plus GitHub audit logs.
+
+When `--post` is used with `--pr`, the reviewer stores a hidden SHA and policy
+fingerprint marker in the summary comment. Re-running the same head SHA with
+the same policy skips provider calls and updates no comments. A new SHA uses
+GitHub compare scope only when the previous marked SHA is an ancestor; a
+missing marker, force-push, or changed fingerprint falls back to the full PR
+file list. Fork PRs are reported as `SKIPPED` with exit `2` on this workflow
+boundary; do not switch to `pull_request_target` to expose secrets. Summary
+comments are reconciled by marker, while POST/PATCH failures remain visible for
+manual retry.
+
+## Advisory and blocking behavior
+
+The Action is advisory by default: `fail-on-block: 'false'` adds `--no-fail`. Findings still post, but surviving blocker/high findings do not fail the job. `--no-fail` never suppresses provider, source, reporter, or review-execution errors. For enforcement:
+
+```yaml
+with:
+  block: high
+  fail-on-block: 'true'
+```
+
+Then require the workflow check in branch protection. CLI exit codes are:
+
+| Exit | Meaning | Operator action |
+|---:|---|---|
+| `0` | Review completed; no blocking finding, or advisory mode | Inspect posted/report output |
+| `1` | A finding at or above `--block` survived | Fix, dismiss with evidence, or change policy intentionally |
+| `2` | Configuration, provider, source, or reporter failure | Inspect stderr; do not interpret as a clean review |
+
+A model response that is malformed may drop one lens while other lenses continue; progress output and the final summary report successful and failed primary-lens counts. If any reviewable file cannot be ingested or has zero successful primary lenses, the pipeline stops before reporters run and exits `2`, including in advisory mode. Treat missing output or exit `2` as unavailable review, not approval.
+
+Use `--plan --json` (or `--dry-run`) to run the source and budget preflight without a model request. The plan reports profile, batching, files, bytes, enabled and required lenses, votes, retries, concurrency, deadline, estimated provider calls, every `UNREVIEWED` path with its reason, and concrete reductions when a limit would be exceeded. Estimates are always `best-effort`: primary lens demand is predictable, but model output determines how many skeptical verification calls are needed. The runtime counter remains the hard ceiling and fails closed if demand exceeds it. The preflight refuses before the provider starts when the predictable primary demand already exceeds the budget; `maxCalls` is capped at 1000 and unlimited mode is not supported. A required-lens failure is `INCOMPLETE` and exits `2`, including with `--no-fail`.
+
+For a PR that exceeds one review budget, use deterministic coverage batches instead of accepting an incomplete review. Run `--plan --json --batch-size <n> --batch-manifest <private-file>` to create a private manifest keyed by repository, PR, head SHA, and policy fingerprint. Each `--batch-index <n> --result <private-file>` run is deliberately incomplete by itself and rejects `--post`; its result artifact carries the same identity plus its exact file manifest. `--consolidate-manifest <manifest> --artifacts <comma-list> --result <private-file>` rejects a missing, duplicate, stale, mismatched, failed, deadline-exceeded, or required-lens-incomplete artifact. Only that consolidated artifact is accepted by `--publish-result <file> --pr owner/repo#N --post`, which rechecks current SHA and policy before creating the one GitHub review. Delete or replace the private state when the PR SHA or policy changes; never upload it as a CI artifact or commit it.
+
+## Cost and latency controls
+
+Seven lenses fan out over selected files; candidate findings then receive adversarial votes. The primary controls are:
+
+- `--max-files`: positive hard file budget;
+- `--max-calls`: bounded provider-call budget (absolute ceiling 1000);
+- `--max-findings-per-file`: positive verified-finding budget per file;
+- `--votes`: verification depth and cost;
+- `--concurrency`: simultaneous model/subprocess calls (default 1 for CLI providers, 4 for API providers);
+- `--profile fast`: one bounded correctness/security/tests batch per file, one vote, and no retry;
+- `--deadline-ms`: hard global deadline; active local workers receive the abort signal and queued calls do not start;
+- `--health-check`: bounded provider smoke check before fan-out (`auto` or `off`);
+- `--paths` or workflow path filters: narrow scope;
+- `--min-severity` and `--min-confidence`: output noise, not input-token cost.
+
+Start advisory with a small file budget, measure provider usage, and raise depth only where it improves signal. Never present an unmeasured cost estimate as a guaranteed price.
+
+Every completed report includes provider-call evidence: calls started, failed,
+skipped by the circuit/budget, elapsed time, deadline status, and circuit state.
+The circuit opens immediately for authentication, timeout, or cancellation
+failures and after repeated transient provider failures. Incomplete evidence is
+never an approval.
+
+## SARIF
+
+`--sarif out.sarif` writes SARIF 2.1.0 alongside Markdown. Each surviving finding includes a `code-review/<category>` rule, severity level, message, file, and line. Uploading SARIF to GitHub code scanning requires the separate `security-events: write` permission and `github/codeql-action/upload-sarif`; the bundled Action does not request that permission or upload automatically.
+
+SARIF can contain source paths and model-generated explanations. Apply the same retention and access policy as CI logs.
+
+### Route findings through reviewdog
+
+[reviewdog](https://github.com/reviewdog/reviewdog) accepts SARIF directly, so no AgentsKit-specific reporter or converter is required. This complete pull-request job installs reviewdog, fetches the base history, generates the report in advisory mode, and lets reviewdog own diff filtering, annotations, and the final CI threshold:
+
+```yaml
+name: AgentsKit reviewdog
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+      - uses: reviewdog/action-setup@d8edfce3dd5e1ec6978745e801f9c50b5ef80252 # v1.4.0
+        with:
+          reviewdog_version: v0.21.0
+      - name: Review changed code
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          REPORT_FILE="$(mktemp)"
+          trap 'rm -f "${REPORT_FILE}"' EXIT
+          npx --yes github:AgentsKit-io/code-review#3dfd7427640148281454d52846d369e5ddf85b11 \
+            --provider openai --model gpt-4o --base "origin/${BASE_REF}" \
+            --sarif "${REPORT_FILE}" --no-fail &&
+          reviewdog -f=sarif -name=agentskit-review \
+            -reporter=github-pr-review -filter-mode=added -fail-level=error \
+            < "${REPORT_FILE}"
+```
+
+The hosted-runner example uses an API provider because local CLI providers require their executable and an existing authenticated session. Replace the provider and model with your approved adapter. The base comes from the pull-request event rather than assuming `main`, and `fetch-depth: 0` makes its remote-tracking ref available to `git diff`. Pass the provider secret through `LLM_API_KEY`, pass the workflow token through `REVIEWDOG_GITHUB_API_TOKEN`, and grant only `contents: read` plus `pull-requests: write`.
+
+The temporary report and `&&` prevent reviewdog from reading stale output when the producer fails. Keep `--no-fail` on the producer so reviewdog receives the complete report when review succeeds; `-fail-level=error` then makes SARIF `error` findings fail the reviewdog step. AgentsKit maps blocker and high findings to SARIF `error`, medium to `warning`, and nit to `note`.
+
+The default `added` filter limits inline feedback to changed lines. Choose a broader reviewdog filter deliberately; broader modes can move findings outside the PR diff into checks, annotations, or console output depending on the reporter. Pin both Code Review and reviewdog to reviewed immutable versions in enforcement workflows.
+
+## Failure scenarios
+
+- **Unknown provider or missing model:** validate with `--list-providers`; API/local-server adapters require `--model`.
+- **Authentication failure:** verify only the provider-specific secret/login and avoid printing its value. A terminal authentication failure stops remaining lenses immediately and the review exits incomplete rather than spending one failed call per lens.
+- **Rate limit or timeout:** Codex calls stop after 300 seconds by default; other local CLI calls use 120 seconds. Set `AGENTSKIT_REVIEW_SUBPROCESS_TIMEOUT_MS` to a positive millisecond value when needed, reduce concurrency/file budget, or use an approved gateway; retry only when provider policy makes the operation safe.
+- **No PR comments:** confirm `pull-requests: write`, token availability, and fork restrictions. The Markdown report still appears in logs.
+- **Inline comment rejected:** the reporter falls back to a non-approving comment for GitHub 422 restrictions.
+- **Large diff:** GitHub PR reviews cap metadata at 500 files, select only the configured file budget before downloading contents, and stop content downloads at the byte budget. Set `--max-files`/`--max-calls` or split review by paths; truncated or unreviewed files must not be described as reviewed.
+- **Ollama timeout:** Requests stop after 30 seconds by default. Use a smaller scope or a responsive local model when the request is aborted; a stalled model must not hold the review indefinitely.
+- **Provider unavailable:** fail or mark the check unavailable according to team policy; never silently convert it to approval.
+
+## Releases and maturity
+
+The current package is `0.4.0` and the project is pre-v1:
+
+- GitHub-source CLI commands can pin a commit SHA after `github:AgentsKit-io/code-review#<sha>`;
+- Actions should pin `@v0.4.0` or a full commit SHA;
+- a moving `@main` reference is suitable only when that mutability is accepted;
+- the future `@v1` Action tag remains a separate stability milestone.
+
+Release work updates [`CHANGELOG.md`](https://github.com/AgentsKit-io/code-review/blob/main/CHANGELOG.md), [`ROADMAP.md`](https://github.com/AgentsKit-io/code-review/blob/main/ROADMAP.md), package version, immutable tag guidance, and signed/provenance evidence when available. Run `npm run check` and `npm pack --dry-run` before publishing.
+
+### Automated npm publishing
+
+Changesets is the release source of truth. A product-affecting pull request adds a small Markdown file in `.changeset/` that names `@agentskit/code-review`, selects `patch`, `minor`, or `major`, and explains the user-visible change. Documentation-only, test-only, and CI-only pull requests add `npx changeset --empty` when they intentionally require no release.
+
+Every merge to `main` runs `.github/workflows/release.yml`. When pending non-empty changesets exist, it creates or updates the `chore: version packages` pull request on the trusted `changeset-release/main` branch. That pull request contains the version bump, generated `CHANGELOG.md` entry, and consumed changesets. Merging this version pull request is the only automatic publish trigger. This extra review boundary is intentional: ordinary feature merges collect safely, while the versioned release has a concrete, reviewable diff. A maintainer-authored release PR may use the explicitly allowlisted `codex/release-0.4.1` recovery branch when repository rules prevent the bot PR from receiving required checks.
+
+`.github/workflows/publish.yml` runs only after that trusted version pull request is merged. It checks out that exact merge commit, verifies the package version and a clean release payload with `npm run check` and `npm pack --dry-run`, publishes `@agentskit/code-review` using [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC), then creates the immutable `v<version>` GitHub Release. If npm already has the exact version, it skips only the publish step and still creates a missing GitHub release; normal PR-triggered runs cannot publish a duplicate. No long-lived `NPM_TOKEN`, npm access token, or personal GitHub token is stored in this repository. GitHub's built-in workflow token is used only to create the version PR and GitHub release.
+
+Before the first release, configure the npm package's Trusted Publisher for GitHub Actions with:
+
+- Organization: `AgentsKit-io`
+- Repository: `code-review`
+- Workflow filename: `publish.yml`
+
+Enable GitHub Actions permission to create pull requests only when the repository setting requires it for Changesets. Keep branch protection configured to require human review: the workflow never approves or merges its own version PR. This repository-wide setting can also permit workflow approvals, so restrict `pull-requests: write` to the version workflow and do not count workflow approvals toward the required human review. The npm configuration is a one-time external prerequisite; the GitHub workflow cannot create it. Do not run `npm publish` locally.
+
+The publish workflow has no manual dispatch path: only a merged, title-matched Changesets version pull request from an explicitly allowlisted release branch can publish. If a release is interrupted, repair it through a new reviewed version PR rather than granting an arbitrary ref publishing authority.
+
+## Contribution and security
+
+Start with [`CONTRIBUTING.md`](https://github.com/AgentsKit-io/code-review/blob/main/CONTRIBUTING.md). Provider integrations must preserve the AgentsKit adapter contract and keep secrets out of arguments/logs. Review lenses need reproducible evidence and false-positive fixtures. Report vulnerabilities privately through [`SECURITY.md`](https://github.com/AgentsKit-io/code-review/blob/main/SECURITY.md).
+
+For adjacent work, use [AgentsKit](https://www.agentskit.io/docs) for runtime and adapters, [Registry](https://registry.agentskit.io/docs) for the vendored agent, [AgentsKit Chat](https://chat.agentskit.io/docs) when review belongs inside a conversational application, [Playbook](https://playbook.agentskit.io/docs) for engineering patterns, [Doc Bridge](https://agentskit-io.github.io/doc-bridge/) for documentation ownership handoffs, and [AKOS](https://akos.agentskit.io/docs) for enterprise orchestration and production governance.
+
+Machine readers should start with [`llms.txt`](https://github.com/AgentsKit-io/code-review/blob/main/llms.txt), escalate to [`llms-full.txt`](https://github.com/AgentsKit-io/code-review/blob/main/llms-full.txt) only when the complete corpus is required, and use [`docs/for-agents`](https://github.com/AgentsKit-io/code-review/blob/main/docs/for-agents/index.md) before changing an owned module.
+## Agent documentation index
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/docs/for-agents/index.md
+
+# Code Review agent docs
+
+- Code Review CLI handoff — ownership, change routes, security boundaries, and verification: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/docs/for-agents/code-review-cli.md
+- Concise machine map — discovery, raw sources, and all seven ecosystem products: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/llms.txt
+- Full machine corpus — public, operational, governance, maturity, and agent handoffs: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/llms-full.txt
+## Code Review agent handoff
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/docs/for-agents/code-review-cli.md
+
+---
+type: package
+package: code-review-cli
+editRoot: .
+checks: [npm run check, npm pack --dry-run]
+---
+
+# Code Review CLI handoff
+
+## Purpose
+
+Provider-neutral, low-noise AI code review for local Git diffs, files/stdin, and GitHub pull requests. Seven focused lenses propose findings; adversarial votes remove weak findings; reporters emit Markdown, GitHub reviews, and SARIF.
+
+## Ownership map
+
+- `src/cli.ts`: public flags, source selection, provider selection, exit policy.
+- `src/<provider>-adapter.ts`: logged-in local CLI adapters.
+- `agents/code-review/`: review pipeline, lenses, input normalization, reporters.
+- `action.yml`: composite GitHub Action contract.
+- `.github/workflows/release.yml`: Changesets version-pull-request workflow.
+- `.github/workflows/publish.yml`: version-PR-gated npm Trusted Publishing and GitHub Release workflow.
+- `examples/`: copy-ready Action workflows.
+- `README.md` and `docs/OPERATIONS.md`: public adoption and operations guidance.
+- `ecosystem.json`, `llms.txt`, and `llms-full.txt`: canonical product graph and machine-readable discovery/full-corpus surfaces.
+- `test/`: credential-free CLI, Action, and documentation contract proofs.
+
+## Boundaries
+
+- Depend on AgentsKit adapter/runtime/tool contracts; do not create a second model abstraction.
+- Preserve provider neutrality and advisory-by-default Action behavior.
+- Never expose provider keys in arguments, docs fixtures, logs, or PR output.
+- This product intentionally has no Fumadocs site and no embedded AgentsChat.
+- The vendored review agent tracks the AgentsKit Registry source; keep divergences explicit.
+
+## Change routes
+
+- CLI flag/provider behavior: start at `src/cli.ts`, then update README, operations docs, and tests.
+- Local CLI subprocess behavior: start at the matching `src/<provider>-adapter.ts` and add an offline fixture.
+- Review logic or noise reduction: start at `agents/code-review/agent.ts` and the relevant lens; prove both survival and rejection behavior.
+- GitHub comments/SARIF: start at `agents/code-review/reporters.ts` and verify permissions/failure docs.
+- Action input: update `action.yml`, `examples/pull-request.yml`, README, and contract tests together.
+- Release automation: update `.github/workflows/release.yml`, `.github/workflows/publish.yml`, Changesets configuration, and the automated publishing section in `docs/OPERATIONS.md` together.
+
+## Verification
+
+```bash
+npm ci
+npm run check
+npm pack --dry-run
+```
+
+`npm run check` includes typecheck, build, an end-to-end offline stdin review, Action/documentation tests, Doc Bridge gates, and CLI help.
+
+## Ecosystem routes
+
+- AgentsKit — runtime, adapters, and custom review agents: https://www.agentskit.io/docs
+- Registry — ready-made agent source: https://registry.agentskit.io/docs
+- AgentsKit Chat — conversational delivery; do not embed a chat runtime here: https://chat.agentskit.io/docs
+- Playbook — engineering discipline before verification: https://playbook.agentskit.io/docs
+- Doc Bridge — documentation ownership, freshness, and handoff generation: https://agentskit-io.github.io/doc-bridge/
+- AKOS — enterprise orchestration and production governance: https://akos.agentskit.io/docs
+
+Use `llms.txt` for discovery and `llms-full.txt` only when the complete public, operational, and agent-handoff context is required.
+
+## Human guide
+
+- README: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/README.md
+- Operations guide: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/docs/OPERATIONS.md
+- Contributing: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/CONTRIBUTING.md
+- Security: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/SECURITY.md
+## Security policy
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/SECURITY.md
+
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published release. Older releases may
+be asked to upgrade before receiving a fix.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/AgentsKit-io/code-review/security/advisories/new) with the affected version, impact, reproduction steps, and any suggested mitigation.
+
+Please do not include secrets or private source code beyond what is necessary to reproduce the issue. We aim to acknowledge a complete report within 14 days, investigate it, and coordinate disclosure and remediation with the reporter. If the report is accepted, we will keep the reporter informed as the fix progresses.
+
+## Scope reminders
+
+This tool sends selected code to the provider you configure. Review that provider's data handling policy before using a hosted API. Prefer a local model or approved private gateway for repositories whose policy prohibits external processing. Store GitHub tokens and provider keys as secrets; never commit them to workflow files.
+## Contributing guide
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/CONTRIBUTING.md
+
+# Contributing
+
+Thanks for helping make AI code review more useful and less noisy.
+
+## Start here
+
+1. Fork and clone the repository.
+2. Create a focused branch from `main`.
+3. Run `npm install`.
+4. Make the smallest change that solves the issue.
+5. Run `npm run check` before opening a pull request.
+
+Node.js 20 or newer is required.
+
+## Project map
+
+- `src/cli.ts` — arguments, providers, review policy, and reporters.
+- `src/*-adapter.ts` — adapters for logged-in local CLIs.
+- `agents/code-review/` — vendored review agent, lenses, sources, and reporters.
+- `action.yml` — GitHub Action interface.
+- `examples/` — copy-ready workflows.
+
+## Good contributions
+
+- Reduce a reproducible false positive.
+- Add a provider through the existing adapter contract.
+- Add a focused review lens with clear evidence requirements.
+- Improve a reporter or source without tying it to one model.
+- Add provider-neutral examples and documentation.
+
+Please open an issue before a large architectural change. Small fixes and documentation improvements can go straight to a pull request.
+
+## Pull requests
+
+- Keep one concern per PR.
+- Explain the user-visible behavior and how you tested it.
+- Add or update tests for behavior changes.
+- Preserve provider neutrality: provider-specific behavior belongs in its adapter.
+- Never commit API keys, model output containing private code, or review tokens.
+- Update README or examples when changing the public CLI or Action interface.
+
+Project decisions, maintainer responsibilities, and the release process are
+documented in [GOVERNANCE.md](https://github.com/AgentsKit-io/code-review/blob/main/GOVERNANCE.md).
+
+By participating, you agree to follow the [Code of Conduct](https://github.com/AgentsKit-io/code-review/blob/main/CODE_OF_CONDUCT.md).
+## Roadmap
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/ROADMAP.md
+
+# Roadmap
+
+This roadmap communicates direction, not a promise of dates.
+
+## Toward v1
+
+- [ ] Publish the calibrated `0.4.x` line of `@agentskit/code-review` and signed release artifacts.
+- [ ] Publish immutable GitHub Action releases with a moving `v1` tag.
+- [ ] Add credential-free adapter contract tests and opt-in provider smoke tests.
+- [ ] Document measured review cost and latency by configuration.
+- [ ] Expand fixtures for false-positive and multi-language regression testing.
+
+## Community tracks
+
+- Review lenses with precise evidence and low false-positive rates.
+- Additional local CLI and private-gateway adapters.
+- Reporters for other code-hosting and CI systems.
+- Better SARIF, monorepo, and large-diff workflows.
+
+Open an issue before starting a large item so maintainers and contributors can align on scope.
+## Changelog
+
+Canonical source: https://raw.githubusercontent.com/AgentsKit-io/code-review/main/CHANGELOG.md
+
+# Changelog
+
+## 0.4.2
+
+### Patch Changes
+
+- [#78](https://github.com/AgentsKit-io/code-review/pull/78) [`f50bb3d`](https://github.com/AgentsKit-io/code-review/commit/f50bb3daceb7e48c8cd1401e47352ebd33000a8f) Thanks [@EmersonBraun](https://github.com/EmersonBraun)! - Make provider-call preflight guidance consistent with demand-driven skeptical verification and document the best-effort estimate semantics.
+
+## 0.4.1
+
+### Patch Changes
+
+- [#73](https://github.com/AgentsKit-io/code-review/pull/73) [`f99c9a3`](https://github.com/AgentsKit-io/code-review/commit/f99c9a37478440b7030c33ac480746db4204d0ef) Thanks [@EmersonBraun](https://github.com/EmersonBraun)! - Add a deterministic continuous-improvement benchmark for clean, required-lens-failure, and deadline review behavior.
+
+- [#73](https://github.com/AgentsKit-io/code-review/pull/73) [`f99c9a3`](https://github.com/AgentsKit-io/code-review/commit/f99c9a37478440b7030c33ac480746db4204d0ef) Thanks [@EmersonBraun](https://github.com/EmersonBraun)! - Automate version pull requests, GitHub releases, and npm trusted publishing without a long-lived npm token. Stabilize OpenCode ACP protocol fixtures without weakening their timeout coverage.
+
+All notable changes will be documented here. This project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-05
+
+### Added
+
+- Added machine-readable preflight manifests for reviewable and unreviewed files, with stable file-batch planning for external orchestration.
+- Added private JSON review-result artifacts and SHA/policy-bound batch-coverage primitives for safe Orca aggregation.
+- Added fail-closed consolidation: every batch artifact must match the immutable PR/SHA/policy/file manifest and have complete lens evidence before a single review can be published.
+- Added CLI consolidation and publication gates so Orca can create exactly one review only from a current, complete consolidated artifact.
+
+### Changed
+
+- Expanded reviewable product files to include HTML, CSS, Markdown, and MDX.
+- Made GitHub inline findings agent-actionable with correction rationale, required change, acceptance check, and verification confidence.
+- Reworked the persistent PR walkthrough into a compact CodeRabbit-style status card; finding detail now lives only on the relevant inline review comments.
+
+### Security
+
+- Reject GitHub publication from a partial review batch; only a complete consolidated review may post.
+- Document the intentionally local, private batch-artifact writes so CodeQL does not misclassify serialized PR metadata as executable file access.
+
+## [0.3.0] - 2026-08-30
+
+### Added
+
+- Added global cancellation deadlines, provider health preflight, a circuit breaker, and bounded execution evidence.
+- Added the explicit `fast` profile with a single required-lens batch for lower latency and predictable calls.
+- Added CI Action inputs for profile, deadline, and health-check policy.
+
+## [0.2.3] - 2026-08-30
+
+### Fixed
+
+- Stop issuing additional provider calls after a terminal authentication failure; reviews still fail closed without spending one failed call per lens.
+
+## [0.2.2] - 2026-08-29
+
+### Added
+
+- Added a GitHub Release workflow for tag-verified npm Trusted Publishing with OIDC and provenance.
+
+### Fixed
+
+- Prevented Codex authentication, timeout, and process failures from being retried as output-schema compatibility failures.
+- Documented and exposed explicit trusted-local mode for logged-in Codex/Claude CLI workflows.
+- Raised the default Codex local-worker deadline to five minutes and made GitHub PR file budgets enforceable and fail-closed.
+- Bounded GitHub Action calls, propagated Claude OAuth credentials, made review fingerprints version-aware, paginated comment reconciliation with a fail-closed cap, and bounded GitHub API responses.
+
+## [0.2.1] - 2026-08-29
+
+### Fixed
+
+- Applied Codex timeout defaults in direct library usage, bounded GitHub PR metadata/content ingestion, and transient-only GitHub GET retries.
+- Added Ollama request deadlines and integration coverage for rate limits, posting failures, stalled requests, and large PR limits.
+
+## [0.2.0] - 2026-08-29
+
+### Changed
+
+- Added strict versioned `.agentskit-review.json` policy with lens coverage, budgets, thresholds, context, and safe CI precedence; incomplete profiles require explicit local opt-in.
+- Hardened the shared local CLI worker with cancellation, process-tree cleanup, isolated temporary environments, bounded output, and redacted diagnostics.
+- Added bounded source snapshots with infrastructure/configuration file support, denylisted sensitive paths, symlink checks, input limits, and data-boundary-aware secret redaction.
+- Added provider-free `--plan`/`--dry-run` preflight with explicit file/byte/call budgets, bounded retries, CLI concurrency defaults, and fail-closed required-lens coverage.
+- Made reviews fail closed when any reviewable file has no successful primary lens or cannot be ingested; advisory mode now suppresses finding-based failures only, never source/provider/execution failures.
+- Added primary-lens execution coverage to review summaries so partial provider degradation is visible.
+- Repositioned the CLI and GitHub Action as provider-neutral.
+- Made provider selection explicit and removed provider-specific model defaults.
+- Added bounded GitHub review reconciliation with SHA/policy fingerprints, incremental compare scope when the prior SHA is an ancestor, fork-safe skip behavior, and idempotent summary updates.
+- Added experimental Grok Build CLI ACP support with isolated capability denial, versioned output validation, bounded invalid-output retry, and offline lifecycle fixtures.
+- Added experimental OpenCode CLI ACP support with the same isolated, versioned, bounded worker contract and offline lifecycle fixtures.
+- Added provider-specific Grok/OpenCode headless transports with explicit local-only ACP fallback via `--transport auto`.
+- Added package metadata, CLI help, open-source governance, and contribution guidance.