@atmin.ai/review 0.1.0-alpha.2 → 0.1.0-alpha.4

package/DEPENDENCIES.md

@@ -13,3 +13,23 @@ Runtime and development dependencies from the lockfile. Each retains its license
 | require-from-string | 2.0.2 | MIT | Runtime |
 | typescript | 5.9.3 | Apache-2.0 | Development |
 | undici-types | 7.18.2 | MIT | Development |
+
+## Dashboard (`web/`, served by the GitHub worker, not in the npm package)
+
+Direct dependencies from `web/package-lock.json`. The bundle also includes the atmin
+brand kit's customized shadcn/ui components (`web/LICENSE.shadcn`) and the Geist fonts
+(`web/fonts/OFL.txt`).
+
+| Package | Version | License | Use |
+|---|---|---|---|
+| class-variance-authority | 0.7.1 | Apache-2.0 | Runtime |
+| clsx | 2.1.1 | MIT | Runtime |
+| lucide-react | 1.45.0 | ISC | Runtime |
+| radix-ui | 1.6.7 | MIT | Runtime |
+| react | 19.2.4 | MIT | Runtime |
+| react-dom | 19.2.4 | MIT | Runtime |
+| tailwind-merge | 3.6.0 | MIT | Runtime |
+| @tailwindcss/cli | 4.3.3 | MIT | Build |
+| esbuild | 0.28.2 | MIT | Build |
+| tailwindcss | 4.3.3 | MIT | Build |
+| tw-animate-css | 1.4.0 | MIT | Build |

package/README.md

@@ -6,11 +6,37 @@ alpha: model quality and severity calibration are still being measured.
 
 ## Install the alpha
 
+### Homebrew
+
+On macOS or Linux:
+
+```sh
+brew install atmin-inc/tap/atmin-review
+gh auth login
+cp "$(brew --prefix atmin-inc/tap/atmin-review)/share/atmin-review/profiles/smoke-openrouter-free.json" ./review-profile.json
+```
+
+Set `OPENROUTER_API_KEY` in your environment, then run:
+
+```sh
+atmin review https://github.com/OWNER/REPO/pull/123 \
+  --profile ./review-profile.json --out ./private-review
+```
+
+Homebrew installs Node, Git, the GitHub CLI and the `atmin` command. `atmin <tool>`
+runs the installed `atmin-<tool>` binary, so other atmin tools sit beside this one:
+`atmin review …` runs `atmin-review`, and `atmin code-review-runner …` runs your own
+review runner. All commands below are available as `atmin review` (or
+`atmin-review`) without the `npx` prefix. If you installed the older
+`atmin-inc/tap/atmin` formula, run `brew uninstall atmin` first.
+
+### npm
+
 Requires Node 24 or newer, Git, and an authenticated GitHub CLI (`gh auth login`).
 Install the versioned release in a fresh directory:
 
 ```sh
-npm install @atmin.ai/review@0.1.0-alpha.2
+npm install @atmin.ai/review@0.1.0-alpha.4
 npx atmin-review --help
 cp node_modules/@atmin.ai/review/profiles/smoke-openrouter-free.json ./review-profile.json
 ```
@@ -28,6 +54,18 @@ availability and rate limits depend on the provider. The bundled paid DeepSeek
 profile caps a run at $2; copying it is an explicit choice to use paid inference.
 Direct OpenAI support uses `OPENAI_API_KEY` and an explicit profile.
 
+`review` runs the claim pipeline described under [Current review direction](#current-review-direction)
+below, the same run the GitHub worker publishes. Use `profiles/review-luna-openrouter.json`
+(GPT-6 Luna through OpenRouter, capped at $2 a run, about $0.035 a run measured on benchmark
+PRs). It is the measured `martian-luna-openrouter.json` with a larger input cap, so diffs up
+to 512 KB fit with room to read; the benchmark profile keeps the cap it was measured with. Set `TYPESAFE_API_KEY` as well to turn on
+the Jev rung, which is how it was measured; without it the report says the rung was off.
+`profiles/review-luna-openai.json` runs the same model directly on OpenAI with
+`OPENAI_API_KEY`. It has not been measured on a real review yet. Its cost is priced from
+OpenAI's usage, including prompt tokens written to the cache (1.25x input) and the higher
+rate for prompts over 272K tokens.
+Confirmed findings the reviewer rated P3 are listed by location, not shown.
+
 Each run captures immutable commits, reads changed files and relevant callers,
 records anchored findings, and renders a report. It never executes repository
 scripts. Keep snapshot directories private: they contain repository source.
@@ -64,7 +102,8 @@ headline. A numerical average cannot cancel out a serious defect.
 Priority depends on a concrete trigger, impact, reachability and counterevidence.
 Findings cite immutable source. A model's reasoning is not proof of execution.
 The target commit's `.atmin/review.json` may enable optional suggestions and name
-required validation checks; a PR cannot weaken its own policy:
+required validation checks; a PR cannot weaken its own policy. Without the file no
+check is required, and the `atmin review` check reflects the review alone:
 
 ```json
 {"schemaVersion":1,"rubricVersion":"1","includeOptional":false,"requiredChecks":["change-validation"]}
@@ -72,13 +111,37 @@ required validation checks; a PR cannot weaken its own policy:
 
 ## GitHub App worker
 
+The current source adds automatic CI refresh and inline findings. These changes
+are not yet in the npm/Homebrew `0.1.0-alpha.2` package; use a source checkout
+to operate this worker until the next packaged release.
+
 The worker receives signed webhooks, stores jobs in SQLite, updates one bot
-summary per PR, and publishes an `atmin review` check. Maintainers can comment
-`/atmin review` to rerun. Use a dedicated host user; the pilot worker is not a
-sandbox for executing repository code or an isolation boundary for many tenants.
+summary per PR, and publishes an `atmin review` check. Each review is a claim-pipeline run
+(see `review` above); point `profile` at `profiles/review-luna-openrouter.json` and set
+`OPENROUTER_API_KEY` and, for the Jev rung, `TYPESAFE_API_KEY`. The first review of a PR
+reads the whole change. Each later push is reviewed incrementally: only the commits since
+the last completed review are read for new findings, and that review's findings are
+re-checked against the new head. A force-push or a merge from the target branch gets a full
+review. Automatic reviews pause after five reviewed heads of one PR; comment
+`/atmin review` for a full review, which also restarts the count. Reviews are bounded by
+`maxReviewsPerDay`. Diffs over 512 KB are not reviewed. Maintainers can comment
+`/atmin review` to rerun. Use a dedicated host user. Source review does not execute repository code.
+Optional [isolated checks](docs/isolated-checks.md) run selected commands and
+verify proposed patches on a configured Linux worker. This private pilot is not
+a hardened isolation boundary for many tenants. Each connected repository has its own
+state directory, database and shared copy of its history. A repository over 2 GB on GitHub
+does not connect; no review starts while the state disk has less than `minFreeDiskMb`
+(default 2048) free; a shared copy over 3 GB is wiped before the next capture; and run
+records older than 90 days are deleted, except each PR's latest completed review. Each
+organization's run records and shared copies together are held to `maxInstallationDiskMb`
+(default 5120), checked before each review, so one review can go past it. Over the limit,
+the organization's shared copies are wiped first, since the next review fetches its own
+again; if its run records alone are still over, the review does not start, the PR comment
+says why, and nothing counts against the plan. `/admin` shows each organization's use.
 
-Register an App with repository Contents read, Pull requests write and Checks
-write. Subscribe to Pull request, Push and Issue comment events. Install it only
+Register an App with repository Contents read, Issues read, Pull requests write and
+Checks write. Issues read is what makes GitHub offer the Issue comment event, which carries
+`/atmin review`. Subscribe to Pull request, Push, Issue comment and Check run events. Install it only
 on the intended repository. Set its webhook to your HTTPS proxy's
 `/webhooks/github`, forwarding to the worker on loopback port 8787.
 
@@ -100,18 +163,44 @@ and installation IDs in a local configuration:
 }
 ```
 
-`trustedChecks` is optional. Use the actual check name and producer App ID you
+`trustedChecks`, `minFreeDiskMb` and `maxInstallationDiskMb` are optional. Use the actual check name and producer App ID you
 trust; check names must match the target policy's required checks. App 15368 is
 an illustrative configuration; verify the producer in your repository before
-using it. The worker queries GitHub on the exact reviewed head. Only a unique
-completed success counts as a pass. Missing, skipped, ambiguous, cancelled or
-unavailable checks remain unverified. A check on a different merge commit is
-not automatically treated as evidence for the head.
+using it. The worker queries GitHub on the exact reviewed head. CI that runs on
+both push and pull_request leaves one run per event there; a pass needs every run
+of the check from that App completed and successful, and any failed run fails it.
+Missing, skipped, cancelled, still-running or unavailable checks remain unverified. A check on a different merge commit is
+not automatically treated as evidence for the head. The review does not wait for CI: while
+unverified required checks are all that stand between a clean review and a pass, the
+`atmin review` check stays pending (in progress) instead of failing, and a required check
+that never passes keeps it pending.
 
 Protect CI workflow changes according to your repository's policy: trusting an
-App and check name is not verification of the workflow's code. This alpha reads
-CI at publication and explicit reconciliation; it does not subscribe to CI
-completion events or poll after publication.
+App and check name is not verification of the workflow's code. Trusted Check run
+creation and completion events refresh the saved report and check, including
+events arriving during publication. Events are only wakeups: results are fetched
+from GitHub again. Stale commits, unrelated checks and duplicate deliveries do
+not start reviews. There is no background polling; use explicit reconciliation
+if GitHub cannot deliver an event.
+
+Findings also appear in one commit-bound advisory review per run, with up to 20
+inline comments. Only anchors present in GitHub's diff are attached; the summary
+retains every visible finding. Optional P4 findings follow target-branch policy.
+CI refreshes reuse the batch; an explicit model rerun creates a new review run.
+Unknown publication outcomes require reconciliation and never blindly repeat a
+POST. Historical inline findings retain their original commits and run identity.
+
+When a PR closes, the worker records what became of each finding the PR's completed
+reviews published, first publication counted once. `changed` means the flagged line or a
+line next to it was edited or removed by the PR's last head; `unchanged` means those three
+lines are still in the file, ignoring indentation, wherever they moved to. An unrelated
+edit to the same lines also counts as changed, so the changed share is at most the share of
+findings acted on. It also records whether the PR merged, and the thumbs up, thumbs down
+and human replies on the finding's inline comments (each carries a hidden
+`<!-- atmin-finding:... -->` marker; comments posted before 2026-09-30 have none, so their
+reactions are not read). Resolved conversations are not read, since GitHub reports them
+only through GraphQL. A read that fails is recorded as `unknown` with its cause, and one
+log line per closed PR gives the counts. `/admin` shows the totals per repository.
 
 ```sh
 npx atmin-review-github check ./pilot.json
@@ -126,9 +215,60 @@ npx atmin-review-github pause ./pilot.json
 Reconciliation refreshes the saved report and CI without new inference. Pausing
 cancels active work. Failed and cancelled starts count toward the rolling daily
 limit. Stop the service before backups; retain the database and spending receipts.
-Provide snapshot retention and disk limits before widening access. Capture
-fetches repository history, so large repositories can exceed the pilot's capacity.
-No hosted signup, billing, inline comments, or repository execution is included.
+The worker keeps one copy of each connected repository's history in its state directory
+(`source-cache.git`) and fetches only the commits it lacks. Each run's snapshot borrows
+that copy and is deleted when the run ends; the JSON records stay. Disk limits per account
+are still needed before widening access.
+No repository execution is included.
+
+With `REVIEW_DASHBOARD_CONFIG` pointing at a JSON file (`origin`, `clientId`, `models`,
+and optionally `operators` and `appSlug`) and `GITHUB_OAUTH_CLIENT_SECRET` set, `serve`
+also hosts the dashboard: the API, and the pages built into `web/dist` by
+`npm run build:web` (pages answer 503 until that build exists). Anyone can install the
+App and sign in with GitHub. Repository administrators connect up to ten repositories
+per installation and pause or configure each one. Each installation is held to a
+monthly plan: 20 free reviews per UTC calendar month by default. A review counts
+once inference starts, failed runs included. Past the limit the PR gets a "review not
+run" comment with the reason and no model call is made. The daily `maxReviewsPerDay`
+cap still applies to every installation together.
+
+With `STRIPE_SECRET_KEY` set, reviews past the free ones are paid from prepaid credit. An
+administrator of a connected repository buys credit on the Billing page through Stripe
+Checkout, $10, $25, $50 or $100 in US dollars, and it does not expire. Each review past the
+free ones takes its price from the credit once its cost settles: one row per review in the
+`credit` table, written once, so a later plan change never prices it again. Once the free
+reviews are used, a review starts only while credit is above zero, so the last one can take it
+slightly below and the next purchase covers that. At zero the PR comment says so and links to
+the Billing page; each paid review's comment says what credit is left and warns below $2.
+Without a key nobody can buy credit, and past the free reviews only credit an operator adds
+pays. Reviews that started before 2026-10-01 are never charged.
+
+A purchase is credited when the browser comes back from Checkout, once the worker has checked
+with Stripe that this organization's customer paid the amount sold; if the buyer closes the
+page first, the hourly check credits it. Paying saves the card. With auto top-up on, the
+worker charges that card the chosen amount off-session whenever credit falls below $5,
+checked after each review and hourly. A top-up's PaymentIntent is created unconfirmed under
+an idempotency key, recorded in the `payments` table, then confirmed, so an interrupted
+top-up is finished by reading it back, never by charging again. A card that declines, or
+whose bank wants the card holder to approve the charge, stops auto top-up until an admin buys
+credit or turns it on again. Stripe emails receipts to the address entered in Checkout when
+Settings > Emails > Successful payments is on in the Stripe dashboard. The `invoices` table
+of the earlier monthly-invoice release is left as it is.
+
+`operators` lists GitHub user IDs, not logins, because a login can be renamed and taken
+by someone else. Operators get `/admin`, which lists every installation of the App (read
+with the App's credentials) with its repositories, reviews this month, model cost,
+billing and margin, and changes a plan: `freeReviews`, `monthlyReviews` (0 turns
+reviews off), `multiplier` and `minimumUsd`. Billing for each review past the free ones
+is the larger of its cost times the multiplier and the minimum. An operator-set plan
+applies as set; past its free reviews it is paid from credit like any other. Operators also
+add credit to an organization, or take it away, with a note the organization does not see.
+On OpenRouter, cost is the amount OpenRouter reports billing for each call, not a rate
+card estimate; on OpenAI directly, it is priced from the call's usage, cache writes
+included. A call whose charge or cache writes are not reported stays unsettled and is left
+out of billing. OpenRouter's fee on credit purchases is not included. With
+`appSlug` set, the dashboard offers the App's install link; set the App's Setup URL to
+the dashboard origin so GitHub returns people there after installing.
 
 ## Develop
 
@@ -142,3 +282,91 @@ Tests use local repositories, fake provider responses and temporary databases;
 they do not consume model credits or establish model quality. Package verification
 installs the actual tarball in a clean directory and exercises both CLI entry
 points and snapshot rendering. Apache-2.0; see LICENSE and NOTICE.
+
+## Rating presets (current source)
+
+Set `rating` inside target-branch `.atmin/review.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "rubricVersion": "1",
+  "includeOptional": true,
+  "requiredChecks": ["change-validation"],
+  "rating": {
+    "preset": "strict-conventions",
+    "perfectRequires": { "noP3": true }
+  }
+}
+```
+
+Presets: `balanced` (default: fit, simplicity, appropriate verification and required
+checks), `correctness-first` (5/5 for a complete current review without P0–P2), and
+`strict-conventions` (Balanced plus documented rules). Overrides are booleans:
+`codebaseFit`, `simplicity`, `verification`, `documentedConventions`, `passingChecks`,
+`noP3`. A concern in a required criterion caps the score at 4; an assessed criterion
+left unknown makes it unrated. P0/P1 cap at 1 and P2 at 3. A review with no quality
+assessment, which is every claim-pipeline review, is scored by its findings alone, so a
+clean one earns 5/5. Missing required check results are noted and do not withhold the
+score; a failed one caps it at 4. No average, test-count quota,
+or automatic penalty for optional P4 suggestions or unavailable patches.
+
+Ratings are subjective and independent from finding severity and GitHub check
+conclusions. An incomplete or stale review cannot be rated. Repository policy is
+captured from the target branch; a PR cannot relax its own rules. These additions
+are available in current source and await the next versioned package release.
+
+## Current review direction
+
+The current design centres review on the **claim**: one falsifiable assertion
+about one location, carried through investigation, verification and disposition.
+Read the [claim-lifecycle design](docs/claim-lifecycle-design-2026-09-17.md) for
+the claim schema, the ordered evidence ladder and the eval methodology.
+
+The earlier [repository-state direction](docs/repository-state-direction.md)
+stays published for context. Its versioned per-branch artifact is deferred by the
+claim-lifecycle design in favour of a thin human-knowledge file, and one review
+agent with separate investigation and verification phases carries forward. Both
+are proposals, not claims about the current engine.
+
+That lifecycle now runs end to end:
+
+```sh
+npx atmin-review claim-review https://github.com/OWNER/REPO/pull/123 \
+  --profile ./review-profile.json
+```
+
+A wide pass emits falsifiable claims, a separate pass settles each claim's
+propositions against the frozen revision with none of the first pass's reasoning
+in scope, and the verdict is composed from what survived. The report shows the
+claims that died alongside the findings that lived: emitting widely is only
+trustworthy when the discarding is visible. It accepts a prepared snapshot
+directory in place of a URL, and writes `claims.json` and `verification.json`
+beside the snapshot.
+
+Whether a rung earns its place is a measurement, not an assumption:
+
+```sh
+npx atmin-review claim-ablate ./private-review --rung cross_family_llm
+npx atmin-review claim-ablate ./private-review --rung symbolic
+```
+
+That re-verifies a finished run with one rung switched off, replaying recorded
+model answers on both sides, so the difference between the two is that rung and
+nothing else. It spends nothing and changes nothing. The report
+counts what the rung added, what it took away, what it raised and what it called
+into question, because a rung that only removes findings is still earning its
+place when those findings were wrong.
+
+Two limits are current, not permanent. The cross-family rung does not run, so no
+claim reaches high confidence through agreement, and the report says so. Rung 1
+knows three assertions — what a declaration contains, what a body contains, and
+whether a symbol is referenced outside a file — each askable of the head or the
+merge base.
+
+The specs a v1 implementation targets are the [claim schema](spec/claim-schema.md),
+the [evidence chain](spec/evidence-chain.md) and the
+[verdict policy constraints](spec/verdict-policy.md). The
+[regression harness layout](harness/README.md) and the
+[pre-registered paired benchmark](bench/PLAN.md) describe how it gets measured.
+Ship bar: 70% precision on the 15 Martian development cases.

package/dist/ablation.d.ts

@@ -0,0 +1,30 @@
+import { type CrossFamilyAnswer, type CrossFamilyRung, type Verification } from './lifecycle.js';
+import type { Revisions } from './symbolic.js';
+import type { Claim } from './claim.js';
+import type { Confidence, Rung, Verdict } from './evidence.js';
+import type { Policy, ReviewVerdict } from './policy.js';
+export declare function recordedRung(log: CrossFamilyAnswer[]): CrossFamilyRung;
+export interface Tally {
+    claims: number;
+    verdicts: Record<Verdict, number>;
+    confidence: Record<Confidence, number>;
+    propositions: Record<Rung | 'unsettled', number>;
+    suspectChecks: number;
+    decision: ReviewVerdict;
+    rule: string;
+}
+export declare function tally(verification: Verification): Tally;
+export interface RungContribution {
+    rung: Rung;
+    without: Tally;
+    with: Tally;
+    gained: string[];
+    lost: string[];
+    raised: string[];
+    refuted: string[];
+    suppressed: string[];
+    decisionChanged: boolean;
+}
+export declare function contributionOf(rung: Rung, claims: Claim[], revisions: Revisions, policy: Policy, log: CrossFamilyAnswer[]): RungContribution;
+export declare function renderContribution(contribution: RungContribution): string;
+export declare const contributionOfCrossFamily: (claims: Claim[], revisions: Revisions, policy: Policy, log: CrossFamilyAnswer[]) => RungContribution;

package/dist/ablation.js

@@ -0,0 +1,90 @@
+import { verifyClaims } from './lifecycle.js';
+// Whether a rung earns its place is a measurement, not an assumption. Verification is
+// deterministic and free once the claims exist, so the same claim set can be verified
+// again with a rung switched off and the difference read directly. The expensive half —
+// emission — is not repeated, and the model answers are replayed rather than re-asked,
+// so the comparison is exact rather than a second sample of a noisy process.
+// Replays what the cross-family rung answered in a recorded run. Questions outside the
+// log return nothing, which is what a rung that cannot reach a proposition looks like.
+// Keyed on the claim and the proposition's text, deliberately not on its revision. The
+// revision is part of the question now, but two propositions of one claim that read
+// identically are the same question written twice, not two questions — and leaving the
+// key alone keeps recorded runs from before the revision was carried replayable exactly,
+// which is what makes a past run a measurement rather than an anecdote.
+export function recordedRung(log) {
+    const answers = new Map(log.map(entry => [`${entry.claimId}\u0000${entry.proposition}`, entry.evidence]));
+    return { settle: (proposition, claim) => answers.get(`${claim.claimId}\u0000${proposition}`) ?? [] };
+}
+const zero = (keys) => Object.fromEntries(keys.map(key => [key, 0]));
+export function tally(verification) {
+    const counts = {
+        claims: verification.chains.length,
+        verdicts: zero(['confirmed', 'refuted', 'inconclusive', 'withheld']),
+        confidence: zero(['low', 'moderate', 'high']),
+        propositions: zero(['symbolic', 'ci_output', 'cross_family_llm', 'unsettled']),
+        suspectChecks: 0,
+        decision: verification.decision.verdict,
+        rule: verification.decision.rule,
+    };
+    for (const chain of verification.chains) {
+        counts.verdicts[chain.verdict]++;
+        if (chain.verdict === 'confirmed')
+            counts.confidence[chain.verifierConfidence]++;
+        counts.suspectChecks += chain.suspectChecks.length;
+        for (const record of chain.propositions)
+            counts.propositions[record.settledBy ?? 'unsettled']++;
+    }
+    return counts;
+}
+const shipped = (chains) => new Map(chains.filter(chain => chain.verdict === 'confirmed')
+    .map(chain => [chain.claimId, chain.verifierConfidence]));
+const RANK = ['low', 'moderate', 'high'];
+// A claim with its checks removed: every proposition survives, and none of them can be
+// settled symbolically. That is what rung 1 being switched off looks like from the
+// claim's side, and it leaves the claim itself untouched so the comparison stays paired.
+const withoutChecks = (claim) => ({ ...claim, evidenceToCheck: claim.evidenceToCheck.map(({ proposition }) => ({ proposition })) });
+// One rung's contribution over one claim set, measured against the same claims verified
+// without it. Every other rung is held fixed — the model answers are replayed on both
+// sides — so the difference is this rung and nothing else.
+export function contributionOf(rung, claims, revisions, policy, log) {
+    if (rung === 'ci_output')
+        throw new Error('Rung 2 does not run in v1, so there is nothing to measure');
+    const replay = recordedRung(log);
+    const without = rung === 'symbolic'
+        ? verifyClaims(claims.map(withoutChecks), revisions, policy, replay)
+        : verifyClaims(claims, revisions, policy);
+    const withRung = verifyClaims(claims, revisions, policy, replay);
+    const before = shipped(without.chains);
+    const after = shipped(withRung.chains);
+    const verdictOf = (verification) => new Map(verification.chains.map(chain => [chain.claimId, chain.verdict]));
+    const priorVerdict = verdictOf(without);
+    return {
+        rung,
+        without: tally(without), with: tally(withRung),
+        gained: [...after.keys()].filter(id => !before.has(id)),
+        lost: [...before.keys()].filter(id => !after.has(id)),
+        raised: [...after].filter(([id, level]) => before.has(id)
+            && RANK.indexOf(level) > RANK.indexOf(before.get(id))).map(([id]) => id),
+        refuted: withRung.chains.filter(chain => chain.verdict === 'refuted'
+            && priorVerdict.get(chain.claimId) !== 'refuted').map(chain => chain.claimId),
+        suppressed: withRung.chains.filter(chain => chain.suspectChecks.length).map(chain => chain.claimId),
+        decisionChanged: without.decision.verdict !== withRung.decision.verdict,
+    };
+}
+export function renderContribution(contribution) {
+    const { without: a, with: b } = contribution;
+    const row = (label, left, right) => `| ${label} | ${left} | ${right} |`;
+    return ['| | without | with |', '| --- | --- | --- |',
+        row('confirmed', a.verdicts.confirmed, b.verdicts.confirmed),
+        row('refuted', a.verdicts.refuted, b.verdicts.refuted),
+        row('inconclusive', a.verdicts.inconclusive, b.verdicts.inconclusive),
+        row('propositions settled symbolically', a.propositions.symbolic, b.propositions.symbolic),
+        row('propositions settled by the model', a.propositions.cross_family_llm, b.propositions.cross_family_llm),
+        row('propositions unsettled', a.propositions.unsettled, b.propositions.unsettled),
+        row('findings at high confidence', a.confidence.high, b.confidence.high),
+        row('verdict', a.decision, b.decision), '',
+        `Claims that ship only with the rung: ${contribution.gained.length}. Claims it takes away: ${contribution.lost.length}.`,
+        `Claims it refuted outright: ${contribution.refuted.length}. Checks it called into question: ${b.suspectChecks}.`,
+        contribution.decisionChanged ? 'The rung changed the verdict.' : 'The rung did not change the verdict.', ''].join('\n');
+}
+export const contributionOfCrossFamily = (claims, revisions, policy, log) => contributionOf('cross_family_llm', claims, revisions, policy, log);

package/dist/assessment.d.ts

@@ -1,4 +1,6 @@
 import { type Packet, type Result, type Finding } from './contracts.js';
+import { type Rating } from './rating.js';
+export declare function validateFix(finding: Finding): void;
 export type Freshness = {
     status: 'current' | 'superseded' | 'unverified';
     reason: string;
@@ -12,6 +14,7 @@ export type ValidationCheck = {
     url?: string;
 };
 export interface Assessment {
+    rating: Rating;
     outcome: 'Changes needed' | 'Review incomplete' | 'Validation needed' | 'Superseded' | 'Unverified' | 'Suggestions' | 'No issues found';
     findingsVerdict: 'Changes needed' | 'Review incomplete' | 'Suggestions' | 'No issues found';
     scope: 'complete' | 'partial' | 'unavailable';
@@ -22,5 +25,6 @@ export interface Assessment {
     hiddenOptionalCount: number;
     reasons: string[];
 }
+export declare function reviewSummary(assessment: Assessment): string;
 export declare function validateEvidence(packet: Packet, result: Result): void;
 export declare function assess(packet: Packet, result: Result, freshness?: Freshness, ci?: ValidationCheck[]): Assessment;

package/dist/assessment.js

@@ -1,5 +1,28 @@
-import { parsePacket, parseResult, PRIORITIES } from './contracts.js';
+import { ReviewInputError, parsePacket, parseResult, PRIORITIES } from './contracts.js';
+import { rate } from './rating.js';
+export function validateFix(finding) {
+    const fix = finding.fix;
+    if (!fix)
+        return;
+    if (finding.anchor.side !== 'head')
+        throw new ReviewInputError('Fixes must replace source in the head version of the finding file');
+    if (fix.endLine < fix.startLine || fix.endLine - fix.startLine >= 20
+        || fix.original.split('\n').length !== fix.endLine - fix.startLine + 1)
+        throw new ReviewInputError('The fix range must contain 1–20 existing source lines');
+    if (fix.replacement.split('\n').length > 20)
+        throw new ReviewInputError('The replacement must contain at most 20 lines');
+    if (fix.original === fix.replacement)
+        throw new ReviewInputError('The replacement is identical to the original source; no change was proposed');
+    if (fix.replacement.endsWith('\n'))
+        throw new ReviewInputError('Omit the terminating newline from replacement; GitHub adds the line ending');
+    if ([fix.original, fix.replacement].some(text => /[\u0000-\u0008\u000b-\u001f\u007f\u202a-\u202e\u2066-\u2069]|`{3}/.test(text))) {
+        throw new ReviewInputError('Control characters, CRLF and Markdown code fences are unsupported in a fix');
+    }
+}
 export const unverified = () => ({ status: 'unverified', reason: 'Live PR state has not been checked for this rendering.', checkedAt: null });
+export function reviewSummary(assessment) {
+    return `${assessment.outcome}. ${assessment.findings.length} finding(s) recorded. Review scope: ${assessment.scope}. Required validation: ${assessment.validation}. ${assessment.rating.score === null ? 'Not rated.' : `Rating: ${assessment.rating.score}/5.`} This is not merge approval.`;
+}
 function unique(values, label) {
     if (new Set(values).size !== values.length)
         throw new Error(`Duplicate ${label}`);
@@ -28,6 +51,20 @@ export function validateEvidence(packet, result) {
         if (refs.some(id => !evidence.has(id)))
             throw new Error('Unknown evidence reference');
     };
+    if (result.quality) {
+        if (result.status === 'not-started')
+            throw new ReviewInputError('A not-started investigation cannot contain a quality assessment');
+        for (const criterion of Object.values(result.quality.criteria)) {
+            checkRefs(criterion.evidenceIds);
+            if (criterion.status !== 'unknown' && (!criterion.evidenceIds.length
+                || criterion.evidenceIds.some(id => evidence.get(id)?.provenance !== 'controller-captured'))) {
+                throw new ReviewInputError('Quality judgments must cite captured source reads; use unknown when evidence is missing');
+            }
+        }
+        if (result.quality.criteria.documentedConventions.status === 'concern' && !result.quality.conventionRules.length) {
+            throw new ReviewInputError('A documented-convention violation must quote an explicit target-branch rule');
+        }
+    }
     for (const coverage of result.coverage) {
         checkRefs(coverage.evidenceIds);
         if (coverage.status === 'reviewed') {
@@ -45,20 +82,38 @@ export function validateEvidence(packet, result) {
         }
     }
     for (const finding of result.findings) {
+        validateFix(finding);
         checkRefs(finding.evidenceIds);
-        if (!inventory.has(finding.anchor.path))
-            throw new Error('Finding must anchor to a changed path; callers belong in supporting evidence');
+        // A change can break code it did not touch: a caller left calling a function whose
+        // contract changed. Seen live 2026-09-24, seven confirmed P1s on callers that this rule
+        // could only report as limitations, under a check that read "no issues". Such a finding
+        // anchors to the head revision, where the broken caller is; loadReview checks the line.
+        if (!inventory.has(finding.anchor.path) && finding.anchor.side !== 'head')
+            throw new Error('A finding outside the changed paths must anchor to the head revision');
         if ((finding.priority === 'P4') !== (finding.kind === 'improvement'))
             throw new Error('P4 is an optional improvement; P0–P3 are defects');
         if (!finding.evidenceIds.some(id => evidence.get(id)?.anchors.some(a => a.path === finding.anchor.path && a.side === finding.anchor.side))) {
             throw new Error('Finding needs evidence anchored to its changed path and side');
         }
+        if (finding.fix && !finding.evidenceIds.some(id => {
+            const item = evidence.get(id);
+            return item?.provenance === 'controller-captured' && item.anchors[0]?.path === finding.anchor.path
+                && item.anchors[0]?.side === 'head' && item.capture.revision === packet.headSha
+                && item.capture.startLine <= finding.fix.startLine && item.capture.endLine >= finding.fix.endLine;
+        }))
+            throw new ReviewInputError('A fix must cite a captured head source read covering its entire replacement range');
     }
 }
 export function assess(packet, result, freshness = unverified(), ci = []) {
     validateEvidence(packet, result);
+    // Binary files are listed as not reviewed but do not hold the scope open: the model reads
+    // text, so a PR adding an icon or a font could never be rated (Lors chose this on
+    // 2026-09-28). A change made only of binary files had nothing reviewed, so it stays partial.
+    const kinds = new Map(packet.changedFiles.map(file => [file.path, file.kind]));
+    const readable = result.coverage.filter(c => kinds.get(c.path) !== 'binary');
     const scope = result.status === 'not-started' ? 'unavailable'
-        : result.status === 'completed' && result.coverage.every(c => c.status === 'reviewed') ? 'complete' : 'partial';
+        : result.status === 'completed' && readable.every(c => c.status === 'reviewed')
+            && (readable.length > 0 || result.coverage.length === 0) ? 'complete' : 'partial';
     unique(ci.map(c => c.name), 'CI check name');
     const checks = packet.policy.requiredChecks.map(name => ci.find(c => c.name === name)
         ?? result.validation.find(c => c.name === name)
@@ -84,5 +139,6 @@ export function assess(packet, result, freshness = unverified(), ci = []) {
         reasons.push('Investigation is not complete across the captured changed-file inventory.');
     if (validation === 'failed' || validation === 'missing')
         reasons.push(`Required validation is ${validation}.`);
-    return { outcome, findingsVerdict, scope, validation, freshness, validationChecks: checks, findings, hiddenOptionalCount: result.findings.length - findings.length, reasons };
+    return { outcome, findingsVerdict, scope, validation, freshness, validationChecks: checks, findings, hiddenOptionalCount: result.findings.length - findings.length, reasons,
+        rating: rate(packet, result, { scope, freshness, validation }) };
 }

package/dist/callees.d.ts

@@ -0,0 +1,14 @@
+import { type Revision } from './symbolic.js';
+export declare const MAX_CALLED_CODE_BYTES: number;
+export interface CalledCode {
+    symbol: string;
+    path: string;
+    line: number;
+    text: string;
+    capped: boolean;
+}
+export declare const TEST: RegExp;
+export declare function calledCode(diff: string, head: Revision): {
+    called: CalledCode[];
+    omitted: string[];
+};