@qvac/harness 0.2.7 → 0.2.8

package/.claude/skills/pr-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-review
-description: Deep-dive review of a pull request in @qvac/harness, or of local uncommitted/branch changes when invoked with `local`. Checks CI, the commit type and title, code quality against the house style, contract and API mismatches, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
+description: Deep-dive review of a pull request in @qvac/harness, or of local uncommitted/branch changes when invoked with `local`. Checks CI and the base branch, the commit type and title, correctness and state/derived-data bugs, contract and API mismatches, security, code quality against the house style, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
 ---
 
 # PR review
@@ -41,14 +41,18 @@ PR mode:
 
 ```bash
 gh pr view <num> --repo tetherto/qvac-harness \
-  --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable
+  --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable,statusCheckRollup \
+  > /tmp/pr-<num>.json
 gh pr diff <num> --repo tetherto/qvac-harness --patch > /tmp/pr-<num>.patch
 ```
 
-Read the patch from the file with Read/Grep rather than re-running `gh` — it is
-the same bytes every time and the file is greppable.
+Two calls, then read both files with Read/Grep rather than re-running `gh` — it
+is the same bytes every time and the files are greppable. `statusCheckRollup`
+already carries every check, so **do not run `gh pr checks`**; it buys nothing
+the JSON does not have.
 
-Local mode:
+Local mode. The default scope is everything uncommitted — staged, unstaged and
+untracked:
 
 ```bash
 git diff --staged > /tmp/local-staged.patch
@@ -57,8 +61,17 @@ git status --porcelain=v1
 git ls-files --others --exclude-standard    # untracked, easy to miss
 ```
 
-For a branch rather than a working tree: `git diff main...HEAD` (three dots —
-the merge base, not the tip).
+Scope overrides, when the user asks for one: `--staged` is `git diff --staged`
+alone, `--unstaged` is `git diff` plus untracked, and `--branch [<base>]` is
+`git diff <base>...HEAD` (three dots — the merge base, not the tip), with
+`<base>` defaulting to `main`.
+
+Untracked files are reviewed as wholly new content: read them from the working
+tree, they appear in no patch.
+
+**If the requested scope is empty, say so and stop.** An empty `--staged` is
+not an invitation to review something else, and it is certainly not an
+invitation to invent findings.
 
 ## CI
 
@@ -79,8 +92,10 @@ local `bun run test` does not:
 A PR that touches `schema/` and leaves `spec/` stale is the most common red
 here, and it looks nothing like a test failure.
 
+Read the result from `statusCheckRollup` in `/tmp/pr-<num>.json`, and pull logs
+only for a job that actually failed:
+
 ```bash
-gh pr checks <num> --repo tetherto/qvac-harness
 gh run view --repo tetherto/qvac-harness --log-failed --job <id> > /tmp/pr-<num>-<id>.log
 ```
 
@@ -88,6 +103,18 @@ A red `Integrate` is a blocking finding on its own. Read the failing job's log
 before writing a single line of review — half of what looks like a design
 problem is a lint rule.
 
+### Base branch
+
+`baseRefName` is in the JSON you already fetched. Per CLAUDE.md a PR targets
+`main`; the one exception is a stacked PR, which branches from the PR below it
+and targets that branch.
+
+So a base other than `main` is only a finding when the PR is **not** part of a
+stack — check whether the base branch is itself an open PR before raising it.
+If it is, the stack is correct and there is nothing to say. If it is not, that
+is a `[P2]`: the diff will contain the base branch's commits and the PR cannot
+merge as it stands.
+
 ## What to check, in order
 
 Stop at the first tier that produces findings worth the author's time; a review
@@ -98,7 +125,38 @@ end to end, including the error path. Look for: a promise not awaited, a
 listener never removed, a resource opened on one path and closed on another, an
 error swallowed into a default.
 
-**2. Contract and API.** This is a published package, so an exported signature
+A **regression** belongs here too: a change that reads as additive but alters
+what existing callers get — a signature widened, a default flipped, a branch
+removed, a return value that is semantically different at the same type.
+
+**2. State and derived data.** The class of bug a linter cannot see and a diff
+skim misses. Walk any new stateful or arithmetic code against these four.
+
+- **Two sources of truth.** The same value in two fields, or the same
+  expression computed twice, in one payload. Before writing the comment, read
+  the type declaration **and** the consumer: if the fields have distinct
+  documented meanings (per-item vs aggregate, raw vs normalised) and a reader
+  prefers one, this is a value written to the wrong channel — a contract
+  violation — not duplication. Say that, and cite the contract. Only call it
+  duplication when nothing distinguishes the fields. The two look identical in
+  a diff and have opposite fixes: one keeps both fields and moves a value, the
+  other deletes a field. Backwards, and you send the author to delete a channel
+  something depends on. `[P2]` either way.
+- **Incremental accumulation.** A running total or offset advanced inside a
+  loop, where computing the whole table once would be correct by construction.
+  `[P2]` when a later edit could desynchronise it — and the fix shrinks the
+  code.
+- **Closure over mutated state.** A callback capturing a variable a later step
+  reassigns, especially across an `await`. `[P1]` if a late or reordered
+  invocation yields a wrong value; say so plainly, because it will not
+  reproduce locally.
+- **Laundered values.** `?? 0`, `|| 0`, `Math.max(x, 0)` turning an impossible
+  input into a plausible number instead of letting it fail. `[P2]` unless the
+  clamp buys a stated presentational guarantee. Watch an optional `uint` in
+  `schema/`: it decodes to `0`, not `null`, so `??` never sees the absent
+  value.
+
+**3. Contract and API.** This is a published package, so an exported signature
 is a promise to a consumer.
 
 - Anything added to or changed in the export map, `index.ts`, `types/`, or
@@ -108,27 +166,45 @@ is a promise to a consumer.
 - Does the change match its own type declarations, and do callers in this repo
   still typecheck?
 
-**3. House style.** Run the changed files against **js-house-style** — that
-document, not your own taste. Layering, composition on primitives, module size
-and shape, no defensive programming, comment density.
+**4. House style.** Load **js-house-style** and run the changed files against
+it — that document, not your own taste or your memory of it. Layering,
+composition on primitives, module size and shape, no defensive programming,
+comment density. A style point the document does not back is not a finding.
 
-**4. Tests.** A behaviour change with no test is a finding. Name the missing
+**5. Tests.** A behaviour change with no test is a finding. Name the missing
 case rather than asking for "more tests": the tests live under `test/`, run on
 both the node and bare lanes, and a fix without a regression guard will come
 back.
 
-**5. Commit type and title.** Per **pr-create**: is this really a `fix` (a
+**6. Commit type and title.** Per **pr-create**: is this really a `fix` (a
 defect a consumer of a released version could hit), or is it `chore` on code
 that never shipped? Is the title imperative and specific? Does the branch name
 avoid `codex` / `cursor` / `claude`?
 
-**6. Scope.** Does the PR do one thing? A behaviour change mixed with an
+**7. Scope.** Does the PR do one thing? A behaviour change mixed with an
 unrelated rename is two PRs — say so, and say which commit to split out.
 
-**7. Decision records.** Does the change contradict something in
-`docs/decisions/`? If it does, the record is updated or superseded in the same
-PR, not left to rot. Does it settle something non-obvious with no record at all?
-Say which, and what the record would have to state.
+**8. Security.** Not a sweep of the file — only what this diff introduces. An
+API key, token or secret in code, a log line or an error message; a tool result,
+a fetched page or a model completion treated as an instruction rather than as
+data; a path or command assembled from something the model produced; unsafe
+deserialization of an hrpc payload; a new dependency pulled in for something
+small.
+
+This package runs untrusted content by design — web fetches, Python in Pyodide,
+MCP servers, the filesystem tool — so the question is never "could input be
+hostile" but "what does this change let hostile input reach". Where it matters,
+`[P1]`.
+
+**9. Decision records.** Only when the diff **contradicts** a record in
+`docs/decisions/` that you have actually read — then the record is updated or
+superseded in the same PR rather than left to rot, and that is a `[P2]`.
+
+A missing record is not a finding. Do not open `docs/decisions/INDEX.md`
+looking for something to say, do not ask for an ADR because a change "feels
+architectural", and never make "no decision record" the only thing a review
+found. If you genuinely think a lasting choice went unrecorded, say it once in
+the chat overview as a question, never inline.
 
 ### Do not over-engineer the review
 
@@ -156,17 +232,38 @@ corner nobody chose.
 Each finding: the file and line, what breaks, and the concrete scenario that
 breaks it. No finding without a failure mode you can state.
 
-Drop anything you cannot defend as changing the code, the reviewer's decision,
-or a consumer's experience. Style opinions the house style does not back are
-noise. Say so plainly when the diff is clean: "no `[P1]` or `[P2]`
-findings" is a complete review.
-
 Lead with the findings, ordered by severity.
 
+### Only raise what is worth the author's time
+
+A review is not required to produce findings. **"Nothing to flag — the diff is
+clean" is a complete, successful review**, and a good PR reviewed honestly is
+the expected outcome most of the time. Never go hunting for something to say
+because the output looks empty; an invented finding costs the author more than
+a silent review ever could.
+
+Every finding passes this bar before it is written down:
+
+- You can name **what breaks**, and the concrete path that reaches it.
+- Acting on it **changes the code, the reviewer's decision, or a consumer's
+  experience**.
+- It is backed by the house style or a real contract, not your taste.
+
+Drop everything else. Not "mention it as a `[P3]`" — **drop it**. A finding you
+cannot defend at `[P2]` is not thereby a `[P3]`; it is noise wearing a smaller
+tag. `[P3]` is for a real, small, correct observation, not a holding pen for
+weak `[P1]`/`[P2]`s.
+
+The failure mode this repo has actually seen: a clean PR comes back with four
+`[P3]`s about naming, a speculative race nobody can reach, and a request for a
+decision record. That review is worse than no review — it trains the author to
+skim the next one, and the real finding gets skimmed with it.
+
 ### Severity tags
 
-Tag every finding `[P1]`, `[P2]` or `[P3]`. Use the tag, not a word, so two
-reviews of the same repo rank things the same way.
+Tag every finding `[P1]`, `[P2]` or `[P3]` **in the chat overview**, using the
+tag rather than a word, so two reviews of the same repo rank things the same
+way. The tag never appears on the PR — see "Comment style".
 
 - `[P1]` — almost-certain bug, data corruption, security issue, CI breaker, or a
   break of behaviour a consumer relies on. In the overview, and **proposed inline
@@ -183,35 +280,135 @@ nits inline teaches the author to skim the next one.
 
 **Severity is what the code does today, not what it might do.** A finding whose
 only support is a scenario nobody has hit is not a `[P2]`: either find the path
-that reaches it, or drop it. Zero findings is a legitimate result.
+that reaches it, or drop it — do not park it at `[P3]` instead. Zero findings is
+a legitimate result.
 
 If the user says this is a re-review, say explicitly which earlier concerns are
 resolved and which still stand.
 
+### The overview
+
+The user's checkout is usually on a different branch or commit than the PR, so
+a bare line number is worth nothing to them. Every `[P1]` and `[P2]` in the
+overview therefore carries two things: a **3–8 line excerpt read at the head
+SHA**, and a **link to that line on the PR**.
+
+The excerpt comes from
+`gh api -H "Accept: application/vnd.github.raw" repos/tetherto/qvac-harness/contents/<path>?ref=<headRefOid>`,
+never from the local tree. The link is the file-diff anchor:
+
+`https://github.com/tetherto/qvac-harness/pull/<num>/files#diff-<sha256(path)>R<line>`
+
+```bash
+printf '%s' 'lib/chat/compact.js' | shasum -a 256 | awk '{print $1}'
+```
+
+If the anchor will not compute, fall back to
+`https://github.com/tetherto/qvac-harness/blob/<headRefOid>/<path>#L<line>`.
+
+````markdown
+## PR #<num> — review overview
+
+<one line: what this PR does>
+
+### CI / base
+
+<one line; omit entirely when both are clean>
+
+### Findings
+
+- **[P1]** <short title> — [`<path>:<line>`](link)
+
+  <one sentence, plus the repro when there is one>
+
+  ```js
+  <3-8 line excerpt at the head SHA>
+  ```
+
+- **[P3]** <short title> — [`<path>:<line>`](link) — <one sentence, no excerpt>
+
+### Re-review delta
+
+<only when the user said this is a re-review>
+
+- Resolved: <…>
+- Still open: <…>
+````
+
+One sentence per finding here; the inline comment carries the reasoning. A
+clean review is this same block with `Findings` reading "nothing to flag".
+
+Local mode uses the same shape, headed `## Local review — <scope>`, with plain
+`path:line` instead of links and the excerpt read from the working tree.
+
+## Comment style
+
+Write like a colleague leaving a note, not a static analyser filing a report.
+If a human reviewer would not say it out loud, do not write it.
+
+- **Brief.** A few lines, one point per comment. If it takes three paragraphs
+  to justify, it probably is not a finding.
+- **Ask, don't lecture.** "Can this reuse the existing helper?" beats a
+  paragraph on why the new one duplicates knowledge the store already owns.
+- **Link what you refer to.** An existing function, type or rule you want
+  reused gets a line link — `[name](<url>#L120)`. A reference the author has to
+  hunt for is one they skip.
+- **Show the change in code.** A short before/after, or a `suggestion` block
+  whenever the fix is mechanical enough to apply as-is.
+- **Never put a severity marker in a comment body.** No `[P1]`/`[P2]`/`[P3]`,
+  no "blocker", no "nit:". Severity is how _you_ decided what to raise; it
+  lives in the chat overview and nowhere else. On the PR it reads as grading
+  the author and it ages badly once the code moves. If something is minor, say
+  it in plain words — "not urgent", "while you're in there".
+- One concrete repro line for a `[P1]`/`[P2]` when one exists. Not a test plan.
+- No praise padding, no "LGTM but…", no restating what the diff does.
+- **Sign off every comment with 🤖 on its own last line**, so it is
+  unmistakable that the review came from an AI. Every inline comment, no
+  exceptions — the emoji alone, nothing else on the line.
+
 ## Posting (PR mode only)
 
-1. Print every proposed comment in chat first: file, line, severity, body.
-   The default set is the `[P1]` and `[P2]` findings; name any `[P3]` you are
-   holding back so the user can pull it in.
+1. Print every proposed comment in chat first, as it will be posted: file,
+   line, then the verbatim body. Carry the severity in the chat line **outside**
+   the body. The default set is the `[P1]` and `[P2]` findings; name any `[P3]`
+   you are holding back so the user can pull it in. If there is nothing at
+   `[P1]`/`[P2]`, say so and stop — never assemble a payload out of `[P3]`s to
+   have something to post.
 2. Ask the user to confirm the exact set. Wait for a clear yes.
-3. Create the review as **PENDING**, with no event:
+3. Write `/tmp/pr-<num>-review.json` from the confirmed set **only**. If the
+   confirmed set is empty, stop — never post an empty review.
+4. Pre-flight, before the POST:
+   - The comment count matches the confirmed set **exactly**. If it does not,
+     stop and reconcile; do not post the larger set and mention it after.
+   - Every `line` is a **post-PR line** — the `+` side of the patch, as
+     numbered in the file at the head SHA. A line the patch does not touch is a
+     `422` that rejects the whole review, so anchor to a touched line or move
+     the point to the chat overview.
+   - Every body ends with a `🤖` line, and none contains `[P1]`, `[P2]`, `[P3]`,
+     "nit" or "blocker". Fix the bodies yourself; do not ask the user.
+   - Show the bodies as **rendered Markdown**, one per `file:line`, never raw
+     JSON — the user is approving what the author will read.
+5. Create the review as **PENDING**, with no event:
 
 ```bash
 gh api repos/tetherto/qvac-harness/pulls/<num>/reviews \
-  --method POST --input /tmp/review.json
+  --method POST --input /tmp/pr-<num>-review.json
 ```
 
-where `review.json` has `commit_id` (the `headRefOid` you fetched) and a
-`comments` array of `{path, line, side, body}`, and **no `event` field**. A body
-with `event` submits the review; leaving it out is what makes it pending.
+where the payload has `commit_id` (the `headRefOid` you fetched) and a
+`comments` array of `{path, line, side, body}`, and **no `event` field**. A
+payload with `event` submits the review; leaving it out is what makes it
+pending. No top-level `body` either, unless the user asks for one — the inline
+comments are the review.
 
-4. Hand the user the link and stop:
-   `https://github.com/tetherto/qvac-harness/pull/<num>#pullrequestreview-<id>`
+If the user edits the selection after the preview, rewrite the file before
+running the command.
 
-If a line is not in the diff, GitHub rejects the comment. Anchor to a line the
-patch actually touches, or raise it in the chat overview instead.
+6. Hand the user the link and stop:
+   `https://github.com/tetherto/qvac-harness/pull/<num>#pullrequestreview-<id>`
 
 ## Sibling skills
 
 - Writing the PR being reviewed → **pr-create**.
-- The rules tier 3 reviews against → **js-house-style**.
+- The rules tier 4 reviews against → **js-house-style**. Load it; do not review
+  from memory of it.