@agentskit/code-review 0.1.0 → 0.4.1

package/docs/OPERATIONS.md

@@ -0,0 +1,358 @@
+# 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`](./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`](../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 `bounded` when `thresholds.maxPerFile` is set and `best-effort` otherwise, because model output volume is variable. The preflight refuses before the provider starts; `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`](../CHANGELOG.md), [`ROADMAP.md`](../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`](../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`](../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`](../llms.txt), escalate to [`llms-full.txt`](../llms-full.txt) only when the complete corpus is required, and use [`docs/for-agents`](./for-agents/index.md) before changing an owned module.

package/docs/assets/agentskit-mark.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 64" fill="none">
+  <g stroke="#0f766e" stroke-width="2" stroke-linecap="round">
+    <line x1="12" y1="52" x2="36" y2="12"/>
+    <line x1="36" y1="12" x2="60" y2="52"/>
+    <line x1="12" y1="52" x2="60" y2="52"/>
+  </g>
+  <circle cx="36" cy="12" r="6" fill="#0f766e"/>
+  <circle cx="12" cy="52" r="6" fill="#0f766e"/>
+  <circle cx="60" cy="52" r="6" fill="#0f766e"/>
+</svg>

package/docs/continuous-improvement.md

@@ -0,0 +1,35 @@
+# Continuous improvement cycles
+
+Each cycle improves one measurable review-process hypothesis. A cycle is not a request to remove every model suggestion from the repository.
+
+## Cycle contract
+
+Before changing behavior, record one hypothesis, its acceptance criteria, a fixed benchmark set, and the decision rule. A confirmed high-severity finding in the cycle scope, incomplete coverage, or a failed gate blocks publication. Medium and low findings outside the hypothesis enter the backlog.
+
+## Baseline benchmark
+
+Run these deterministic, credential-free cases before and after every process change:
+
+| Case | Fixture | Expected evidence |
+| --- | --- | --- |
+| Clean review | `test/fixtures/review/good.ts` | Complete `APPROVE`, all enabled lenses succeed. |
+| Lens failure | `CODEX_FIXTURE_FAIL_CATEGORY=security` | Incomplete, fail-closed result with missing required-lens evidence. |
+| Deadline | `CODEX_FIXTURE_HANG=1` | Incomplete, blocking result artifact; no candidate finding is accepted without skeptical verification. |
+
+The benchmark records elapsed time, provider calls, failed/skipped calls, execution coverage, verdict, incomplete state, and deadline state. It is run with the fixture provider; representative live runs are a separate acceptance check, never a replacement for this baseline.
+
+Run it with `npm run benchmark:cycle`. It emits a versioned JSON report and exits non-zero when any of the three cases stops preserving its stated fail-closed behavior.
+
+## Closed cycle
+
+1. Run and store the baseline benchmark.
+2. Diagnose one root cause and define the smallest change set.
+3. Implement the change with a regression test.
+4. Re-run the same benchmark and compare the listed evidence.
+5. Run `npm run check`, `npm pack --dry-run`, and `ak-verify run --config .codex/verification.json --json`; record its run ID and require its current state to be `COMPLETE`.
+6. Review only the cycle diff. Confirmed highs in scope block; unrelated medium/low findings enter backlog.
+7. Add a Changeset for public behavior, open/merge the version PR, then let trusted publishing create the npm package and GitHub release.
+
+## Release boundary
+
+A cycle can be locally validated without publishing. Publishing requires the repository workflow to be pushed, GitHub Actions to be allowed to create the Changesets version PR, npm Trusted Publishing to be configured, and the version PR to merge. These are external prerequisites; they are reported separately from benchmark evidence.

package/docs/for-agents/code-review-cli.md

@@ -0,0 +1,70 @@
+---
+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

package/docs/for-agents/index.md

@@ -0,0 +1,5 @@
+# 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

package/docs/plans/ecosystem-doc-quality-code-review.md

@@ -0,0 +1,61 @@
+# Ecosystem documentation — Code Review tracer
+
+## Objective
+
+Make Code Review a complete, repository-native member of the seven-product AgentsKit ecosystem without adding Fumadocs or an embedded chat surface.
+
+## Acceptance criteria
+
+- The canonical ecosystem manifest lists AgentsKit, Registry, Chat, Playbook, Doc Bridge, Code Review, and AKOS with stable public URLs.
+- The README remains concise, keeps its verified examples and maturity contract, and presents all six sibling products as contextual next steps.
+- Documentation-related guidance points to Doc Bridge, conversational UI guidance points to AgentsKit Chat, and enterprise operation guidance points to AKOS.
+- `llms.txt` is a compact discovery map with human, agent, raw-source, and ecosystem routes.
+- `llms-full.txt` exposes the complete repository documentation corpus without bloating `llms.txt`.
+- `docs/for-agents/` identifies ownership, change routes, ecosystem hooks, and required checks.
+- Doc Bridge remains exactly 100/100 with fresh committed artifacts.
+
+## Test plan
+
+### Unit and contract tests
+
+- Verify the canonical manifest contains seven unique products in the expected order.
+- Verify Code Review resolves exactly six siblings and that every public URL is HTTPS.
+- Verify `llms.txt` stays concise and links `llms-full.txt`, raw sources, for-agents, and all six siblings.
+- Verify `llms-full.txt` contains the README, operations guide, and agent handoffs.
+- Verify the README contains the six-peer continuation table and the three strategic hooks.
+
+### Integration and regression
+
+- Run TypeScript typecheck, build, offline CLI review, Action/documentation contract tests, and README Standard v1.
+- Run Doc Bridge index, gate, and doctor; require 100/100 and fresh artifacts.
+- Run `npm pack --dry-run` and confirm the two LLM surfaces, ecosystem manifest, and agent handoffs ship.
+- Preserve provider neutrality, advisory-by-default behavior, and the repository-native no-Fumadocs/no-AgentsChat-runtime boundary.
+
+### Edge cases
+
+- Reject duplicate or missing ecosystem product identifiers.
+- Keep secrets and provider keys out of generated machine-readable docs.
+- Avoid claims of stable npm or `v1` Action distribution while the project remains pre-v1.
+- Ensure GitHub raw-source links are pinned to the public `main` path and do not expose local filesystem paths.
+
+## Documentation impact
+
+- `README.md`
+- `llms.txt` and `llms-full.txt`
+- `docs/for-agents/`
+- `docs/OPERATIONS.md`
+- `ecosystem.json`
+- Doc Bridge generated artifacts and README freshness hash
+
+## Definition of Done
+
+- All acceptance criteria are implemented.
+- `npm run check` passes.
+- `npm pack --dry-run` passes with the required documentation payload.
+- Doc Bridge reports 100/100 A with all gates passing.
+- No commit, push, release, or PR is created without explicit user authorization.
+
+## Upstream adoption record
+
+- Reuse the approved seven-product ecosystem manifest and documentation-quality language from the central AgentsKit documentation contract.
+- Keep review primitives on AgentsKit adapters/runtime and the Registry-sourced review agent; no local model or agent abstraction is introduced.

package/docs/provider-compatibility.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "envelope": "schemaVersion: 1",
+  "requiredLenses": ["correctness", "security", "tests"],
+  "providers": [
+    {
+      "id": "grok-cli",
+      "support": "stable",
+      "executable": "grok",
+      "minimumVersion": "0.1.0",
+      "trustModes": ["isolated", "trusted-local"],
+      "transports": {
+        "acp": { "status": "supported", "fixture": "test/grok-cli-adapter.test.mjs" },
+        "headless": { "status": "supported", "fixture": "test/headless-cli-adapter.test.mjs" },
+        "auto": { "status": "local-only", "fixture": "test/headless-cli-adapter.test.mjs" }
+      },
+      "auth": "isolated: XAI_API_KEY or --api-key; trusted-local: provider login",
+      "failureSemantics": ["strict-envelope", "one-invalid-output-retry", "bounded-timeout", "cancel", "redacted-diagnostics"]
+    },
+    {
+      "id": "opencode-cli",
+      "support": "stable",
+      "executable": "opencode",
+      "minimumVersion": "0.1.0",
+      "trustModes": ["isolated", "trusted-local"],
+      "transports": {
+        "acp": { "status": "supported", "fixture": "test/opencode-cli-adapter.test.mjs" },
+        "headless": { "status": "supported", "fixture": "test/headless-cli-adapter.test.mjs" },
+        "auto": { "status": "local-only", "fixture": "test/headless-cli-adapter.test.mjs" }
+      },
+      "auth": "isolated: OPENCODE_API_KEY or --api-key; trusted-local: provider login/configuration",
+      "failureSemantics": ["strict-envelope", "one-invalid-output-retry", "bounded-timeout", "cancel", "redacted-diagnostics"]
+    }
+  ]
+}