@jphutchins/code-review 0.1.0-alpha.4 → 0.1.0-alpha.41

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
@@ -37,11 +38,16 @@ 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 |
+| `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 workspace for the agent |
+| `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 |
+| `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) |
@@ -62,19 +68,97 @@ 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.
 
+## Artifacts
+
+The review job uploads two artifacts, each visible from the workflow run the sticky's disclosure
+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.
+  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 (the linked `findings.json` is the
+  agent's draft and lacks the surfaced fields below) — the shared serializer is
+  [`src/surface.ts`](src/surface.ts).
+
+  The embedded document is the **surfaced** findings document: the agent's findings
+  (`schema_version` 0.6.0 contract, which is what the review agent is held to and what
+  [`schema/findings.schema.json`](schema/findings.schema.json) validates) stamped with the
+  `0.8.0` surface version, the pipeline-computed convergence state of the **last completed
+  full-review round**, and the advisory `scope_metastasis` entry (issue #150):
+
+  ```json
+  {
+    "schema_version": "0.8.0",
+    "verdict": "comment",
+    "summary": "...",
+    "convergence": { "score": 1, "threshold": 1, "converged": true },
+    "round": 4,
+    "scope_metastasis": {
+      "decision_prompt": "Findings keep recurring in the same mechanism across consecutive rounds — each fix keeps enabling the next finding in that machinery. This is a decision, not a directive: state in your summary whether you are committing to the expanding scope (plan the remaining facets of the recurring mechanism(s) above as one unit) or narrowing the scope so the recurrence stops.",
+      "recurring": [
+        { "code": "mixin-field-guard-gap", "consecutive_rounds": 4, "start_round": 1 }
+      ]
+    },
+    "findings": []
+  }
+  ```
+
+  `convergence` (`score` = critical·4 + major·2 + minor·1 + nit·0, `threshold` default 1, `converged`
+  = score ≤ threshold, as a literal boolean) and `round` (the count of completed full-review rounds)
+  are the deterministic **stop signal** for an iterating author-agent: `converged: true` means the
+  last completed round is at or below the convergence tolerance, so another iteration round is not
+  warranted. The agent never writes these fields — the commenter computes them from the review's own
+  severities at render time — and they are omitted until at least one full-review round has
+  completed. They survive the "review in progress" banner: the banner replaces only the sticky's
+  prose and carries the embedded marker forward verbatim. `scope_metastasis` is the structured
+  counterpart of the sticky's "Scope metastasis" warning — per-code consecutive-round counts plus a
+  decision prompt — computed from the same rounds history and omitted when no mechanism recurred. It
+  is deliberately NOT stripped when a surfaced blob feeds the re-review seed: a decoding agent — and
+  the next-round reviewer — must see the recurrence data to answer the scope decision. The 0.8.0
+  surfaced contract applies to the **whole-document** marker only; each inline comment embeds a
+  per-finding fragment (`schema_version` + one finding) at the draft's own version, since the
+  fragment carries no stop signal.
+
+  Semantics on non-round posts: a mechanic (CI-fix) pass or an envelope-loss post embeds the
+  **last completed round's stored signal** (round + its own threshold — never re-derived, so an
+  operator changing `convergence_threshold` mid-PR cannot flip a stored `converged`) beside its own
+  findings, so the signal always describes the last completed full-review round, not the findings
+  that happen to sit beside it. A notice — a post whose verdict is `error` or whose run did not
+  complete (empty diff, corrupt output, did-not-complete) — embeds **no** signal in its own blob:
+  its document already says no review was produced this run, and a carried `converged` beside that
+  would read as a stop signal for a run that produced none; the last completed round's signal still
+  survives on the sticky in the compact `<!-- code-review:signal;base64 <base64> -->` marker, so
+  the next post reads it back. The same compact marker is emitted when the embedded payload is too
+  large and the whole-document marker falls back to the artifact link — an oversized review's stop
+  signal stays readable and can be carried forward.
+- **`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.
+
 ## What's here
 
 - **[SPEC.md](SPEC.md)** — the normative, provider-agnostic specification.