@jphutchins/code-review 0.1.0-alpha.6 → 0.1.0-alpha.61

package/README.md

@@ -25,8 +25,9 @@ the security boundary, and the cost.
 ## The CLI
 
 The npm package is the **deterministic commenter** — the presentation and posting layer that no
-model should do, plus the adapter glue between an agent CLI's native output and the spec's abstract
-envelope ([SPEC §6.1](SPEC.md#61-result-envelope)).
+model should do, plus the adapter glue between an agent CLI's native output and the abstract result
+envelope defined in [`src/schema.ts`](src/schema.ts) (the deliverable of
+[SPEC §3.2](SPEC.md#32-the-deliverable)).
 
 ```sh
 npm install -g @jphutchins/code-review
@@ -36,13 +37,17 @@ npx @jphutchins/code-review <subcommand>
 
 | Subcommand | What it does |
 | --- | --- |
-| `post` | Post a complete review (inline comments + sticky summary) from findings + envelope + diff — the one-call path |
-| `gather` | Resolve the PR from the CI head SHA and gather the review inputs (diff with git-diff fallback, PR context, prior bot review, failing-job logs) into the workspace for the agent |
+| `post` | Post a complete review from findings + envelope + diff — the one-call path. The findings are listed in the sticky summary; `--inline` renders the in-diff ones as comments on the diff instead. Also renders the review into `$GITHUB_STEP_SUMMARY`: the sticky is overwritten each round, the run summary keeps each round as it stood |
+| `gather` | Resolve the PR from the CI head SHA and gather the review inputs (diff with git-diff fallback, PR context, prior bot review, the prior review's answered-findings registry, failing-job logs) into the directory named by `--out-dir` (default: the current directory; the shipped workflows use `$RUNNER_TEMP/gather`) |
+| `parse-command` | Resolve a PR's head from its number and parse a ChatOps trigger comment (`/code-review [24m] [$1.00] <instructions>`) into review overrides — the on-demand comment trigger |
+| `react` | Add/remove a GitHub comment reaction — the ChatOps acknowledgement (👀 on receipt, 🚀 on completion) |
+| `await-ci` | Wait for a PR head's CI run to conclude and emit its real conclusion + run id — so an on-demand comment review routes on the CI result (success → full, failure → mechanic) instead of reviewing blind |
+| `check-scope` | Validate + normalize the workflow's `scope` input (the languages/inputs the project accepts) and print the normalized list for the review prompt, or nothing when empty (the reviewer then infers scope from the README's first paragraph); a structurally malformed value is rejected rather than spliced in as-is |
 | `render` | Render the sticky-comment markdown from findings + usage + prices |
 | `inline` | Build the GitHub reviews `comments[]` payload from findings + diff (in-diff validation; strays demote to the summary) |
-| `adapt` | Map a native agent-CLI result envelope onto the abstract SPEC §6.1 envelope |
+| `adapt` | Map a native agent-CLI result envelope onto the abstract result envelope (`src/schema.ts`) |
 | `extract` | Recover findings/triage JSON from a native envelope via the deterministic extraction ladder |
-| `lower-suggestions` | Validate each finding's `patch` against the real PR-head file and lower it to an exact `suggestion` + line range, or drop it |
+| `validate-patches` | Validate each finding's `patch` against the real PR-head file, aligning the finding's line range to it and keeping the patch (projected into a suggestion at render time), or dropping the patch |
 | `cost` | Recompute USD cost from the envelope's per-model token counts + a price map |
 | `validate` | Validate findings JSON against the published schema |
 | `print-schema` | Print a bundled schema (findings, triage, prices) |
@@ -63,16 +68,24 @@ in [templates/](templates/). See [docs/adapters.md](docs/adapters.md) for the ad
    letting the CLI pick where your key gets sent.
 3. Commit `.github/prices.json` (fork [schema/prices.example.json](schema/prices.example.json) and
    fill in your provider's per-token rates) — without it the cost footer renders **$0**
-   ([SPEC §6.2](SPEC.md#62-price-map)).
+   ([SPEC §4.4](SPEC.md#44-required-controls-conformance)).
 4. Merge to your default branch first — `workflow_run` only fires from the default branch, so the
    introducing PR won't review itself — then open a test PR.
 5. First run: consider `egress-policy: audit` to discover the real allowlist, then switch to `block`
-   ([SPEC §8.4](SPEC.md#84-egress-allowlist)).
+   ([SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
+6. Optional — add on-demand reviews too: copy
+   [examples/workflows/review-on-comment.yaml](examples/workflows/review-on-comment.yaml) so a
+   write-access user can comment `/code-review [24m] [$1.00] <instructions>` on a PR to review it
+   now, with an optional per-run budget and focus. Comment before CI finishes and it waits for CI and
+   routes on the real result (success → full review, failure → mechanic), same as the CI trigger. See the
+   [ChatOps section](examples/workflows/README.md#comment--chatops-trigger-on-demand-reviews) for the
+   security model.
 
 Every model knob is committed step `env` on the workflow's triage and review steps — models,
 efforts, the subagent model, and the tier aliases, right where each is consumed — edited and
-PR-reviewed like the rest of the file ([SPEC §8.5](SPEC.md#85-model-backend-env)). Only the backend
-endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no default); pointing it at
+PR-reviewed like the rest of the file (implementation detail the spec deliberately leaves to this
+repo — see [SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
+Only the backend endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no default); pointing it at
 another provider requires adding that provider's API host to the workflow's egress allowlist in the
 same reviewed PR.
 
@@ -83,12 +96,67 @@ links to:
 
 - **`code-review-findings`** — the findings JSON + result envelope the comment job renders. The
   sticky comment embeds this same JSON directly, base64-encoded, in an
-  `<!-- code-review:findings-json;base64 <base64> -->` HTML comment — a reviewing agent (or any
-  downstream tool) SHOULD base64-decode and parse that marker rather than parse the comment's prose.
+  `<!-- code-review:findings-json;base64 <base64> -->` HTML comment. The comment usually renders that
+  same review as prose, which is the cheaper read; decode the marker where the prose is not the
+  review, where the prose carries only part of it, or where the prose omits a field you need. The directive that rides ahead of the
+  marker states that rule.
   Embedding in the comment (rather than only linking the artifact) keeps the pointer from expiring
   with artifact retention; when the encoded findings are too large to embed, the sticky falls back to
-  a `<!-- code-review:findings-json <url> -->` link marker instead
-  ([SPEC §5.1 item 7](SPEC.md#51-sticky-summary-comment)).
+  a `<!-- code-review:findings-json <url> -->` link marker instead. The shared serializer is
+  [`src/surface.ts`](src/surface.ts).
+
+  The embedded document is the agent's **complete** findings document — the same `schema_version`
+  0.10.0 contract the review agent is held to and
+  [`schema/findings.schema.json`](schema/findings.schema.json) validates, and the same object the
+  comment is rendered from. The agent's fields are embedded verbatim; the pipeline stamps one field the
+  agent never writes — `convergence` (below) — so the whole review, findings and convergence signal
+  alike, travels as one JSON document with no side marker to drift from.
+
+  ```json
+  {
+    "schema_version": "0.10.0",
+    "verdict": "comment",
+    "summary": "...",
+    "findings": [],
+    "convergence": {
+      "score": 0.42,
+      "threshold": 1,
+      "converged": true,
+      "rounds": [
+        { "round": 1, "score": 2.4 },
+        { "round": 2, "score": 1.1 },
+        { "round": 3, "score": 0.42 }
+      ]
+    }
+  }
+  ```
+
+  The **`convergence`** field is the deterministic stop signal AND the per-round trajectory for an
+  iterating author-agent, carried in the JSON document itself so a decoder reads one object.
+  `convergence.score` sums each finding and systemic problem's
+  `floor(severity) + max(0, ceiling − floor) × confidence × likelihood` (ceilings critical 4 · major 2
+  · minor 1 · nit 0; floors critical `threshold + 0.01` · major 0.5 · minor 0.1 · nit 0), rounded to 2
+  decimals. A **systemic problem is scored with `likelihood` = 1** — a structural observation has no
+  single triggering input, so it is never discounted by likelihood. `threshold` defaults to 1, and
+  `converged` = score ≤ threshold as a literal boolean — `converged: true` means the last completed
+  round is at or below the tolerance, so another iteration is not warranted. `score` and `threshold`
+  are both carried so the number is interpretable on its own. `convergence.rounds` is the trajectory,
+  oldest first: each entry's `score` is a historical snapshot carried **verbatim**, so changing
+  `convergence_threshold` mid-PR never rewrites a past round's number. The commenter computes
+  `convergence` from the review's own severities (the agent never writes it) and stamps it, overwriting
+  any value the agent echoed; it appears once at least one full-review round has completed and is carried
+  forward afterward — a mechanic (CI-fix) pass or an envelope-loss notice carries the last completed
+  round's convergence unchanged rather than re-deriving it, and a notice never fabricates a signal for a
+  run that produced no review. The convergence survives the "review in progress" banner, which replaces
+  only the sticky's prose and carries the blob forward verbatim.
+
+  Cross-round recurrence (the sticky's "Scope metastasis" warning) is derived from the per-round
+  mechanism frequencies carried in `convergence.rounds` (each entry's `codes` map), from which the
+  re-review seed re-derives the advisory `scope_metastasis` entry it hands the next-round agent. Each
+  inline review comment embeds only its own finding (a `schema_version` + one-finding fragment), and the
+  review-object body links the sticky and the workflow run — so the **sticky is the sole documented decode surface** for
+  the whole-document marker; a decoding agent reads it there. The review body is written only after the
+  sticky exists (a failed sticky write aborts the run first), so it never carries the blob itself.
 - **`code-review-transcript`** — the full Claude Code session transcripts for the triage and review
   phases. This is advisory/auditability only: it is never read by the comment job and never affects
   what gets posted.