@jphutchins/code-review 0.1.0-alpha.51 → 0.1.0-alpha.53

package/README.md

@@ -37,7 +37,7 @@ 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 |
+| `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 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) |
@@ -96,8 +96,10 @@ 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. The shared serializer is
@@ -152,7 +154,7 @@ links to:
   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 only links the sticky — so the **sticky is the sole documented decode surface** for
+  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