@verevoir/review 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,438 @@
-# Temporary Holding Version
+# @verevoir/review
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The review panel: lens-based diff review, fanned out across every declared
+lens with a shared cached prefix, aggregated into one verdict with a
+fail-closed outcome rule. One implementation, consumed by pump-internal
+review, the local preflight gate, eval-review, and CI -- rather than four
+independent reviewers drifting apart.
+
+## Status: PR 1 (the seed)
+
+This is a **behaviour-preserving move** of aigency-runtime-v2's reviewer
+(`src/review-node.ts` + `src/review/*.ts`) into this standalone library,
+as-is: same exported names (`runReviewNode`, `ReviewNodeInput`,
+`ReviewNodeResult`), same logic, same fail-closed rules. Import paths were
+flattened (no `src/review/` subdirectory -- this package has nothing to
+separate the reviewer from), and two v5-only imports were replaced with
+small library-owned shims (`model.ts`, `raw-call.ts`) -- see each file's
+own header, and the seed commit message, for exactly what moved and why.
+
+**Known gaps in this PR**, named rather than silently absorbed:
+
+- The CLI (`aigency-review`, below) is a port of governance's; see "Command
+  line" for what was deliberately not ported.
+
+All nine of v5's review test suites are ported (see "Tests" below, not
+two), and the ported-file doc debt (stale README/ownership references) is
+fixed as of this commit.
+
+## Roadmap (confirmed sequence)
+
+1. **This PR** -- the seed. No ratchet run is needed for this PR itself:
+   it is a mechanical, behaviour-preserving move, proven by v5's own nine
+   test suites passing unchanged against the moved code (see "Tests"
+   below). The ratchet equivalence check (detection + agreement, same
+   harness and fixtures, v5's ports vs. this library) is the acceptance
+   test of the CONSUMER CUTOVER PR in runtime-v2 instead: run `eval-review`
+   on `main` (v5's ports), cut over to `@verevoir/review`, run
+   `eval-review` again on the cutover branch, and record both runs'
+   numbers in that PR's body.
+2. The change-context assembler (tree-sitter via `@verevoir/context`),
+   with the two-channel API (`guardrails` vs `subjectContext`).
+3. Diff anchors (every finding must cite a diff hunk) and the
+   `PRE_EXISTING` channel.
+4. Relational finding kinds (`breaks` / `duplicates` / `deviates`).
+5. Bounded read-only tools (`find_symbol`/`read_range`/`find_references`/
+   `list`), behind a flag, off by default until the ratchet measures
+   tools-on vs tools-off.
+
+Each of 2-5 lands as its own PR, measured with the ratchet before vs
+after, numbers recorded in that PR's body.
+
+## Tests
+
+All nine of v5's review test suites, ported verbatim (import paths only
+adjusted for this package's flat layout):
+
+| Suite                                | Cases  |
+| ------------------------------------ | ------ |
+| `review-conformance.test.ts`         | 14     |
+| `review-node-planted-defect.test.ts` | 1      |
+| `reviewer-selection.test.ts`         | 10     |
+| `review-scope-contradiction.test.ts` | 9      |
+| `reviewer-anthropic.test.ts`         | 15     |
+| `reviewer-claude-cli.test.ts`        | 18     |
+| `review-prompt-requirement.test.ts`  | 7      |
+| `verdict-precedence-bl144.test.ts`   | 4      |
+| `review-shared-prefix.test.ts`       | 7      |
+| `model-resolution-real.test.ts`      | 4      |
+| **Total**                            | **89** |
+
+These passing unchanged against the moved code is the proof that this
+extraction changed nothing -- not a separate acceptance step.
+`model-resolution-real.test.ts` is the one exception: it is NEW, added
+after the seed, to close a governance finding -- see "Dependency surface"
+below and `src/model.ts`'s own header.
+
+## Dependency surface
+
+`@verevoir/llm` plus `@anthropic-ai/sdk`, plus node built-ins. Enforced by
+`scripts/check-deps.mjs`, run in CI on every PR. Any addition needs a
+justification paragraph in that PR's description.
+
+`@anthropic-ai/sdk` was added after the seed: `@verevoir/llm`'s own
+MODEL_CATALOG starts empty and is populated only as the import side
+effect of its `./anthropic` subpath -- without importing it, this
+library's `resolvedModelId('opus')` silently returned the bare, unresolved
+alias instead of the catalog's current id, a governance finding fixed in
+`src/model.ts`. That subpath imports `@anthropic-ai/sdk` at module scope,
+and `@verevoir/llm` declares it only as an optional peer -- npm does not
+install an optional peer automatically, so it is declared here directly.
+Proven by `tests/model-resolution-real.test.ts`, the one test in this
+suite that mocks nothing.
+
+## Claude CLI reviewer: idle timeout
+
+`reviewer-claude-cli.ts`'s `chat()` call carries `@verevoir/llm` 0.35.0's
+idle-output timeout (`ClaudeCliChatOptions.idleTimeoutMs`): an explicit
+`ClaudeCliReviewerOptions.idleTimeoutMs` on this reviewer wins when set;
+otherwise llm's own `CLAUDE_CLI_IDLE_TIMEOUT_MS` env var and its built-in
+default apply. A `claude -p` child killed for going idle is reported as
+that lens's own named `could_not_run` outcome -- never an approval, and
+never folded into a generic failure.
+
+## Consuming this library
+
+This is a **private** repository, consumed as a pinned git dependency --
+never via npm's registry, and never floating on a branch or tag.
+
+1. **Pin the full commit sha**, in `git+https://` form, never the
+   `github:owner/repo#sha` shorthand (npm's resolution of that
+   shorthand's own transport -- ssh vs https -- isn't guaranteed, and
+   the CI step below only works if npm goes over https):
+
+   ```json
+   "@verevoir/review": "git+https://github.com/verevoir/review.git#<full-sha>"
+   ```
+
+   A branch or tag is never acceptable here: this repo merges on green
+   (see "Merge policy" below), with no human gate between a PR and
+   `main` moving -- a consumer floating on `main` would pick up a change
+   with no review of its own on this side of the boundary. Pin the exact
+   sha you have actually run the ratchet against (or, for a mechanical
+   bump with no behaviour change, the exact sha you have confirmed
+   carries one).
+
+2. **Add `REVIEW_READ_TOKEN` as a repository secret** in the consumer's
+   own CI -- a fine-grained PAT scoped to `contents: read` on
+   `verevoir/review` ONLY. This repository is private, and a consumer's
+   ambient `GITHUB_TOKEN` cannot see a different private repository.
+   `REVIEW_READ_TOKEN` is the operator's standing secret name for every
+   consumer of this library -- used for nothing else, so it can stay
+   scoped this narrowly without colliding with any other credential a
+   consumer's CI might hold.
+
+3. **Before `npm ci` (or equivalent), rewrite git URLs for this
+   dependency's exact URL only** -- never every `https://github.com/`
+   URL -- then run the install with NO lifecycle scripts, remove the
+   rewrite immediately, and only then run the scripts that were skipped:
+
+   ```yaml
+   - run: |
+       if [ -z "${{ secrets.REVIEW_READ_TOKEN }}" ]; then
+         echo "::error::REVIEW_READ_TOKEN is not set (or is blank) -- required to install the private @verevoir/review git dependency over https."
+         exit 1
+       fi
+   - run: git config --global url."https://x-access-token:${{ secrets.REVIEW_READ_TOKEN }}@github.com/verevoir/review.git".insteadOf "https://github.com/verevoir/review.git"
+   - run: npm ci --ignore-scripts
+   - run: git config --global --unset url."https://x-access-token:${{ secrets.REVIEW_READ_TOKEN }}@github.com/verevoir/review.git".insteadOf
+     if: always()
+   - run: npm rebuild
+   - run: npm run build --prefix node_modules/@verevoir/review
+   ```
+
+   **Why `--ignore-scripts` plus the two steps after, not just the scoped
+   rewrite and an unset** -- an earlier version of this guidance claimed
+   scoping the rewrite to one URL meant the token was never exposed to
+   "any other dependency's install script". That was wrong, caught by a
+   lens-review round on a real consumer's cutover branch, scored
+   blocking: URL scoping only limits which git operations the rewrite
+   applies to. It does nothing to stop a DIFFERENT package's own
+   install/postinstall script from reading `~/.gitconfig` directly, as a
+   file -- any process in the job can do that regardless of which URL
+   the rewrite names. `--ignore-scripts` is what actually closes this:
+   no package's lifecycle script runs while the token is present. The
+   rewrite is then unset (`if: always()`, so a failed `npm ci` does not
+   leave it behind either), and only then do the deferred scripts run --
+   `npm rebuild` for every other dependency's own install/postinstall
+   (native modules among them, if your consumer has any), and an
+   explicit build of **this package's own** `dist/` specifically,
+   because it is gitignored here and normally produced by this
+   package's `prepare` script -- which `--ignore-scripts` also skipped,
+   and which `npm rebuild` does not run (rebuild covers preinstall/
+   install/postinstall only, never prepare).
+
+   **The precise claim this now supports**: the token exists in
+   `~/.gitconfig` only across the url.insteadOf write and
+   `npm ci --ignore-scripts` itself -- an install that runs no package
+   script. Nothing after that point can read it. The one residual,
+   accepted exposure is whatever npm does internally to fetch the git
+   dependency during that one command -- unavoidable, since that is the
+   minimum npm needs to resolve a private git dependency at all.
+
+   Run this on every CI leg/matrix entry that installs dependencies -- a
+   leg that skips it fails `npm ci` outright and loudly (a missing
+   credential), never silently.
+
+This is the exact mechanism in place on `aigency-runtime-v2`'s own
+`verify.yml`, on its consumer-cutover branch (held for operator review,
+per that repository's own protected-paths rule).
+
+## Round-aware review (opt-in)
+
+A stateless reviewer re-reviews the whole cumulative diff every round with
+no memory of what it found last time, and that can lose a real finding: a
+finding round 1 raised can simply go unmentioned in round 2's reply and
+vanish, unresolved, with nobody having ruled on it. Round-aware review
+fixes this without changing anything for a caller that does not ask for
+it.
+
+**Opt in** by setting `Subject.priorFindings` -- absent, or an empty
+array, is "no prior round" and this library behaves exactly as it always
+has; every prompt it builds and every reply it parses is byte-identical
+to before this feature existed (pinned in
+`tests/review-round-aware.test.ts`, which independently reconstructs the
+pre-feature `buildPrompt` template and asserts equality against it).
+
+```ts
+interface PriorFinding {
+  id: string;
+  lens: string;
+  severity: 'blocking'; // only a blocking finding is worth carrying forward
+  summary: string;
+  round: number;
+}
+
+interface Subject {
+  // ...title, description, diff, citedContext, requirement, as before...
+  priorFindings?: ReadonlyArray<PriorFinding>;
+}
+```
+
+**What a lens is shown.** When `priorFindings` is non-empty, every lens's
+prompt gains a `## Prior round` section in its own `perLens` half (never
+in the shared, cached prefix -- which findings a lens rules on differs by
+lens, so it cannot live in the block that must stay byte-identical across
+all of them), split into two clearly separated parts:
+
+- **Part A -- rule on each prior blocking finding for this lens.** Only
+  the findings whose own `lens` field names this lens are listed. The
+  lens is asked to judge each one against the **current** diff -- never
+  against whether it was ever a valid finding -- and answer with
+  `RULING: <id> resolved -- <reason>` or
+  `RULING: <id> unresolved -- <reason>`.
+- **Part B -- independent review.** The lens reviews the change as it
+  would today, in full. New blocking findings are explicitly allowed
+  anywhere a real defect exists -- Part A is never phrased as a ceiling on
+  what else may be reported, and the prompt says plainly that a real
+  defect must never be suppressed to avoid reopening old ground. For every
+  new blocking finding, the lens is asked to say whether it sits in code
+  changed since the prior round, is a regression, or -- if neither -- why
+  it wasn't raised in the prior round. This is anchoring protection, not
+  suppression: it exists to stop the SAME old findings being the only
+  thing found round after round, never to cap what a lens may raise.
+
+**The verdict gains `priorRulings`**, per lens:
+
+```ts
+interface PriorRuling {
+  priorId: string;
+  ruling: 'resolved' | 'unresolved';
+  reason: string;
+}
+
+interface Verdict {
+  // ...outcome, results, findings, unran, outOfScope, as before...
+  priorRulings?: ReadonlyArray<{ lens: string; rulings: ReadonlyArray<PriorRuling> }>;
+}
+```
+
+`priorRulings` is **optional, never `[]`**: it is a new field on an
+already-exported interface, so a `Verdict` literal a consumer already
+builds by hand (a test fake, a fixture) must keep compiling against a new
+version of this library without it. `aggregate` omits the field entirely
+-- never sets it to an empty array -- whenever nothing round-aware
+happened in this run; it is present only when at least one lens actually
+carried a ruling.
+
+**The outcome rules:**
+
+- Any prior blocking finding ruled `unresolved` sinks the verdict to
+  `rejected` -- it stays blocking, exactly as a brand-new blocking finding
+  would.
+- A prior finding the reply never mentions at all is treated as
+  `unresolved` and named `'no ruling returned'` -- fail-safe, never
+  silently dropped the way a stateless re-review could lose it.
+- All prior findings resolved, and no new blocking finding anywhere in
+  the panel, is `approved`.
+- A malformed `RULING:` line -- the wrong shape, a ruling for an id this
+  lens was never asked about, two rulings for the same id -- makes that
+  lens's own result `could_not_run`, the same fail-closed treatment every
+  other unreadable reply gets in this library.
+- A lens whose own reply is unreadable at the base level (empty, no
+  `VERDICT:` line, two of them) never gets a prior ruling attached at
+  all, even if it was owed one -- that lens's result stays `could_not_run`
+  (an unran lens), never a substantiated rejection manufactured out of
+  its silence.
+- A prior finding whose own `lens` field names a lens that is not on the
+  panel at all (a stale or mistyped id, or a lens dropped between rounds)
+  is folded in as unresolved and named `'lens not on panel'` -- it can
+  never simply vanish just because no lens was ever asked to rule on it.
+- The `RULING:` separator accepts an em dash (`—`) or en dash (`–`) as
+  well as the literal `--` the prompt itself always demonstrates, in case
+  a model's own formatting substitutes one.
+
+**Who sets this.** This library only reads `priorFindings`; nothing here
+computes it. A caller carrying its own round history (e.g.
+aigency-runtime-v2, from round 2 of an implement↔review loop onward) is
+responsible for assembling the array from its own prior verdict's
+blocking findings before calling `runPanel`/`runReviewNode` again.
+
+## Command line
+
+`aigency-review` runs the panel over a diff from any repository, including a
+public one that cannot call governance's private reusable workflow:
+
+```sh
+npx -y @verevoir/review aigency-review --base origin/main --title "My change"
+git diff origin/main...HEAD | npx -y @verevoir/review aigency-review
+```
+
+**Flags**
+
+- `--base <ref>` -- review `git diff --merge-base <ref> HEAD` (run via
+  `execFile`, no shell). Needs full history. Without it, the diff is read from
+  stdin.
+- `--title <text>` -- shown at the top of the report (default `this change`).
+- `--lenses <path>` -- a lens set JSON file. Else `AIGENCY_REVIEW_LENSES`, else
+  the bundled default.
+- `--description-file <path>` -- the PR description, shown under `## The change`.
+  Unreadable or blank is `could_not_run`. Without it the prompt says, in one
+  line, that no description was supplied and not to judge it.
+- `--checks-file <path>` -- CI check results, rendered verbatim in the shared prompt under
+  `## Checks on this change` (after `## The change`, before `## The diff`). Unreadable or
+  blank is `could_not_run`. Without it the prompt says, in one line, that no check results
+  were supplied and not to assume the tests pass.
+- References in added lines (automatic with a context root) -- ADR citations (`ADR 009`,
+  `ADR-009`, `ADR 9`) and repo-relative file paths in the diff's ADDED lines are resolved
+  deterministically (no model call) and rendered under `## References in added lines`, after
+  `## Changed files in full`. An ADR is looked up in directories named `adrs` or `adr` (depth
+  4, skipping `node_modules`, `.git`, `dist`) and shown with its path and first heading, or
+  "not found in this repository"; a path is reported as existing or not. At most 40 are
+  resolved. `..`, absolute paths and root-escaping symlinks are refused.
+- With `--practices`, every lens also gets a tier anchor (tag `[blocking]` only when quoting
+  the signal failed) and is asked for a `REASON:` line; the report shows every lens as
+  `#### <lens>: <verdict>: <reason>`, approving lenses included.
+- With `--practices`, the tier is enforced in code. After each lens's reply is parsed, every
+  `[blocking]` finding must contain a verbatim quote of one of THAT lens's practices'
+  `_Reject:_` / `_Expect:_` lines: after lower-casing and removing markdown emphasis, quote
+  marks and extra whitespace on both sides, a contiguous run of at least 24 characters of the
+  signal line (or all of a shorter line). Otherwise it becomes `[smell]` with
+  " (downgraded: no signal quoted)", and a lens left with no blocking finding counts as
+  approved. Bundled lenses are unchanged.
+- De-duplication: after the panel, ONE extra call through the same reviewer asks which findings
+  (ids `lens:index`) describe the same defect. The reply must put every id in exactly one
+  group; otherwise (or if the call fails) the un-merged report is kept with a line saying
+  de-duplication was skipped and why. Each group is shown once, at its highest tier, with its
+  first member's text and `raised by: <lens> (<practices>), ...`. Per-lens verdict lines are
+  unchanged, and the call's usage appears in the footer as `dedup`. `--no-dedup` skips it. It is
+  also skipped when fewer than two findings were raised.
+- With `--checks-file`, the checks section ends with: "If a check fails, report it once, then
+  review the rest of the change on its own merits, as if that failure were fixed."
+- `--warm-first` / `--no-warm-first` -- run the first lens alone, then fan out
+  the rest, so they read the prompt cache the first wrote instead of every lens
+  writing the same prefix. On by default with 2 or more lenses; costs roughly one
+  extra lens-latency of wall time. A first lens that fails does not stop the rest.
+- `--context-root <dir>` -- a tree at the change's head. Each file the diff
+  touches (paths from the `+++` headers) that still exists there is shown in
+  full, post-change, if it is 16 KB or smaller, in a shared
+  `## Changed files in full` section after `## The diff`; skipped files are listed with the reason
+  (too large, deleted, not present, binary). Paths with `..` or absolute paths
+  are refused, and so is any file whose resolved real path (symlinks followed)
+  leaves the root. With `--base` it defaults to the current directory (run from
+  the repo root); with stdin and no `--context-root` the prompt says in one line
+  that there is no file context.
+- `-h`, `--help`.
+
+**Environment**
+
+- `ANTHROPIC_API_KEY` -- billed route. Else `ANTHROPIC_API_KEY_FILE`, else
+  `$XDG_CONFIG_HOME/verevoir/anthropic.key` (or `~/.config/verevoir/anthropic.key`).
+  With no key anywhere the logged-in `claude` CLI is used. A key file that is
+  unreadable or blank, or a named `ANTHROPIC_API_KEY_FILE` that does not exist,
+  blocks the run rather than silently falling back.
+- `AIGENCY_REVIEW_LENSES` -- lens set path (see above).
+- `AIGENCY_REVIEW_MODEL` -- default `claude-opus-5-5`.
+- `AIGENCY_REVIEW_MAX_TOKENS` -- positive integer, default `65536`.
+- `GITHUB_STEP_SUMMARY` -- when set, the report is appended to that file.
+
+**Report footer.** The report ends with what judged it: the model (the id the
+transport reported, else the requested one, said as such), the reviewer route by
+name only (`env`, `key-file` or `claude-cli` -- never a key or a path), and one
+per-lens line with input/output tokens (and cache tokens when non-zero) and wall
+time. The same per-lens lines go to stderr. A route that reports no usage says
+`usage not reported`.
+
+**Output.** The markdown report goes to stdout; `RESULT: approved|out_of_scope|rejected|could_not_run`
+goes to stderr.
+
+**Exit codes** (from `exitCodeFor`, as in governance): `approved` and
+`out_of_scope` exit `0`; `rejected` and `could_not_run` exit `1`. Anything
+that stops a verdict (bad config, no diff, empty diff, unreadable lens set, a
+bad flag) is `could_not_run`: red, never a pass.
+
+**Bundled lenses.** `lenses.default.json` is a copy of
+`verevoir/aigency-governance` `review/lenses.json` at commit `de238aa`. It is a
+snapshot, refreshed deliberately.
+
+**Not ported from governance's CLI**: fetching the lens set over HTTP
+(`AIGENCY_REVIEW_LENSES_TOKEN`/`GITHUB_TOKEN`; paths only here), the
+cited-file context built from the checkout (`citations`/`readers`), and
+governance's `practices` fetch. The title is `--title`, not `argv[2]`.
+
+**Derived lenses (trial, BL-424).** `--practices <dir>` reads the `*.md`
+files directly under `<dir>` (a guardrails checkout's `corpus/practices`),
+groups them by their front-matter `lens:` value, and makes one lens per value
+(id and title are the value; focus is a fixed adversarial sentence plus the
+group's `**Sensor**` / `**Look for**` text). Practices with no `lens:` are
+warned about on stderr, reviewed by nothing, and counted in the report. A
+tagged practice with no sensor text is `could_not_run`. It cannot be combined
+with `--lenses`. `--print-lenses` (needs `--practices`) prints each lens's id,
+practice ids and focus length as JSON and exits 0 with no diff and no model
+call. `<dir>/README.md` must exist: its "Signals: reject / accept / expect" section and
+the "keyed to different tiers" provenance paragraph are sent to every lens as the
+bar (missing or without those headings is `could_not_run`). Each practice's sensor
+is headed `### <id>: <title>`. `--print-prompt <lens-id>` prints the exact prompt
+that lens would be sent for the diff and exits 0 with no model call.
+Front-matter is parsed by a minimal reader (only the `lens:` line, as in
+v2); no YAML library.
+
+**GitHub Actions**
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- run: npx -y @verevoir/review@<next> aigency-review --base origin/${{ github.base_ref }} --title "${{ github.event.pull_request.title }}"
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## Merge policy
+
+Merges on green, same as this organisation's other rebuild repos. "Green"
+here means: typecheck, lint, the deterministic test suite, and the
+forbidden-deps guard. The model-call ratchet (detection rate per sensor,
+agreement) cannot run in CI -- it needs real model calls -- and runs
+locally, on the operator's subscription, via the eval harness; its
+results belong in the PR body of any PR touching review _behaviour_.

package/dist/cli/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};