@qvac/harness 0.2.6 → 0.2.8

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

@@ -37,17 +37,17 @@ build  chore  ci  docs  style  refactor  perf  test  fix  feat
 It is the line someone reads to decide whether to upgrade, so it claims real
 breakage in something already published.
 
-| The change | Type |
-| --- | --- |
-| Breaks a consumer on a published version | `fix` |
-| Repairs code that has never shipped (same release cycle) | `chore` |
+| The change                                                  | Type                                               |
+| ----------------------------------------------------------- | -------------------------------------------------- |
+| Breaks a consumer on a published version                    | `fix`                                              |
+| Repairs code that has never shipped (same release cycle)    | `chore`                                            |
 | Repairs the build, the bundle, or what lands in the tarball | `build` or `fix` if a published artifact was wrong |
-| Repairs CI, a workflow, an action pin | `ci` |
-| Repairs or adds a test | `test` |
-| Repairs a lint/type error | `chore` |
-| Pure move or rename, no behaviour change | `refactor` |
-| New capability, new export, new flag | `feat` |
-| README, comments, docs | `docs` |
+| Repairs CI, a workflow, an action pin                       | `ci`                                               |
+| Repairs or adds a test                                      | `test`                                             |
+| Repairs a lint/type error                                   | `chore`                                            |
+| Pure move or rename, no behaviour change                    | `refactor`                                         |
+| New capability, new export, new flag                        | `feat`                                             |
+| README, comments, docs                                      | `docs`                                             |
 
 When a repair is on unreleased code, check the last release tag: if the bug was
 never in a published version, it is `chore`, not `fix`.
@@ -61,6 +61,45 @@ Optional, and taken from what the diff actually touches — `lib`, `worker`, `sc
 A scope that restates the type (`fix(fix)`) or names the whole repo adds
 nothing; leave it off.
 
+## Decision records
+
+`docs/decisions/` holds the durable, non-obvious choices — why a boundary is
+where it is, why an approach was rejected. They are reference for a future
+reader, **not rules, and not to be loaded by default**.
+
+Add one when this PR settles something a later reader would otherwise have to
+reverse-engineer from the diff: a runtime or storage boundary, a wire-format or
+schema choice, a build or publish constraint, a rejected alternative that will
+look obvious later. Do not add one for a bug fix, a rename, or anything the code
+already says plainly.
+
+Copy `docs/decisions/TEMPLATE.md`, give it a `status`, list it once in
+`INDEX.md`, and name it in the PR's Decisions section. `node
+scripts/docs-audit.cjs` checks all of that, and CI runs it.
+
+An **active** record may cite only paths that exist here; a path in another
+repository is written `@qvac/harness → lib/x.ts` so the audit treats it as
+context rather than a local file. A superseded record is exempt — it describes
+how things used to be.
+
+### One PR, one type
+
+The commits carry conventional-commit types, so the mix of types _is_ the scope
+statement. `feat:`, `fix:` and `chore:` on one branch is not a well-rounded
+change, it is three changes sharing a branch, and a reviewer has to hold all
+three while judging any one of them.
+
+List them before writing the body:
+
+```bash
+git log --format='%s' main..HEAD | grep -oE '^[a-z]+' | sort -u
+```
+
+- **One type** is the PR's type.
+- **A dominant type plus its own tests or docs** (`feat` + `test`, `fix` +
+  `docs`) is fine; the dominant one wins.
+- **Unrelated types** means split the PR, or stack it.
+
 ## Small PRs, stacked
 
 A PR is read by a human, so it has to fit in one head. Default to one concern.
@@ -71,7 +110,7 @@ stack them, so each step is reviewable alone and lands in order.
 - **Refactor commits never live inside a non-refactor branch.** A `feat/` branch
   that also reshuffles unrelated code is two PRs. Behaviour changes and pure
   moves are reviewed differently, and mixing them hides both.
-- A pure rename or move lands *before* the change that depends on it, as its own
+- A pure rename or move lands _before_ the change that depends on it, as its own
   commit or its own PR in the stack.
 
 Branch names must never contain `codex`, `cursor`, or `claude` (case
@@ -79,8 +118,10 @@ insensitive). Use a neutral name before committing or pushing.
 
 ## Body
 
-No template is enforced. Use these four headings and drop any that would be
-empty — an absent section says more than a section saying "n/a".
+`.github/pull_request_template.md` pre-fills the headings. Keep its shape, fill
+what applies, and delete the sections that would be empty — an absent section
+says more than one saying "n/a". The template's own order is Why, What, Testing,
+Decisions; the expanded form below is what each should contain.
 
 ```markdown
 ## What
@@ -111,8 +152,10 @@ this is the only warning they get.
 
 1. Check the branch is not `main` and the name is neutral.
 2. `git log --oneline main..HEAD` — every commit is a conventional commit, and
-   each one is a change you would defend on its own.
-3. ``bun run lint`` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
+   each one is a change you would defend on its own. A trail of `wip`,
+   `fixup` or `address review` commits is not history; reshape it before
+   opening.
+3. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
    red PR wastes a reviewer's round trip.
 4. Rebase on `main` rather than merging it in. A merge commit in the branch
    makes the diff unreadable.

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
@@ -15,20 +15,44 @@ Reviews changes in `@qvac/harness`. Two modes.
 - **Local mode** (`local`, or "review my changes") — the overview in chat only.
   Posts nothing, anywhere.
 
+## Reviewing is read-only
+
+This skill never writes to the working tree. Against the user's repo these are
+forbidden, whatever the reason:
+
+- `git switch`, `git checkout`, `git reset`, `git restore`, `git clean`
+- `git stash`, in any form
+- `git pull`, `git merge`, `git rebase`, `git cherry-pick`
+- `gh pr checkout`
+- any edit to a file
+
+Local mode reads the diff with `git diff`, `git status` and `git ls-files`, and
+nothing else. If the tree is dirty in a way that makes the diff hard to read, say
+so and let the user decide; never tidy it yourself. A review that loses
+uncommitted work is worse than no review.
+
+PR mode needs no checkout at all: `gh pr diff` gives the patch, and
+`gh api repos/{owner}/{repo}/contents/{path}?ref={sha}` gives any file at the PR
+head.
+
 ## Gather
 
 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
@@ -37,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
 
@@ -48,19 +81,21 @@ single `Lint & Tests` job. `publish.yml` runs on release, not on PRs.
 Its steps are each a separate way to fail, and the last three catch what a
 local `bun run test` does not:
 
-| Step | Command | Fails when |
-| --- | --- | --- |
-| Lint | `bun run lint` | prettier, lunte or `tsc --noEmit` |
-| Schema is regenerated | `bun run build:schema` | `spec/` is dirty after codegen — someone hand-edited it, or forgot to commit the regeneration |
-| Tests | `bun run test` | the node, bare and addon lanes |
-| Library surface compiles | `bun run build:lib` | the compiled export surface breaks |
-| Sidecar bundle builds | `bun run build:bundle` | the stowed bundle no longer assembles — a new bare import, or a missing addon external |
+| Step                     | Command                | Fails when                                                                                    |
+| ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
+| Lint                     | `bun run lint`         | prettier, lunte or `tsc --noEmit`                                                             |
+| Schema is regenerated    | `bun run build:schema` | `spec/` is dirty after codegen — someone hand-edited it, or forgot to commit the regeneration |
+| Tests                    | `bun run test`         | the node, bare and addon lanes                                                                |
+| Library surface compiles | `bun run build:lib`    | the compiled export surface breaks                                                            |
+| Sidecar bundle builds    | `bun run build:bundle` | the stowed bundle no longer assembles — a new bare import, or a missing addon external        |
 
 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
 ```
 
@@ -68,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
@@ -78,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
@@ -88,61 +166,249 @@ 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.
 
+**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
+
+The most damaging thing a review can do is talk a good PR into a worse one. AI
+review skews defensive: a guard here, an abstraction there, a layer to absorb a
+hypothetical, each one permanent debt bolted to a problem that never happened.
+That runs directly against the house style, which does not program defensively.
+
+It compounds. Successive reviews each add a layer against a different
+speculative case, one review's fix undoes another's, and the code ends up in a
+corner nobody chose.
+
+- **Only raise what is wrong now**, or has a concrete path to being wrong.
+  "Someone could later..." is not a finding.
+- **Never propose a guard, wrapper, fallback or abstraction** whose only job is
+  to make a hypothetical safe. Let caller bugs crash; that is the contract.
+- **Prefer the fix that deletes code.** If your suggestion makes the diff
+  bigger, be sure it earns it.
+- **Simplification is a valid finding; speculative hardening is not.**
+- When you cannot tell whether something is real, ask instead of requesting a
+  change, and be willing to land zero findings.
+
 ## Write the findings
 
 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 blocking 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]` **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
+  by default**.
+- `[P2]` — likely bug, non-obvious caveat, contract or API mismatch, subtle
+  behaviour change, missing test on a risky path. In the overview, and **proposed
+  inline by default**.
+- `[P3]` — minor: a stale comment or doc, an ergonomic improvement, an optional
+  cleanup. In the overview when material, and **not proposed inline** unless the
+  user asks for them.
+
+**Never silently put a `[P3]` in the inline payload.** A review that posts ten
+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 — 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
 
-Distinguish clearly:
+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**.
 
-- **Blocking** — wrong behaviour, a broken contract, a missing test for a fix.
-- **Non-blocking** — a simplification, a naming improvement, a follow-up.
-- **Question** — you could not tell from the diff, and the author can.
+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, body.
+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.

package/CLAUDE.md

@@ -31,6 +31,9 @@ Runs on both Bare and Node. Anything that only works on one is a bug.
   never more. Most code needs none — do not narrate it.
 - **Commits read as if a human wrote them.** No `Co-Authored-By` trailer and no
   AI or agent attribution, in a commit message or a PR.
+- **Durable decisions are in `docs/decisions/`.** Read `INDEX.md` when touching an
+  area it lists, and open a record only on a path or keyword match — they are
+  reference, not rules. Add one when a change makes a non-obvious lasting choice.
 - **Branch from `main`, and open the PR against `main`.** The one exception is a
   stacked PR, which branches from the PR below it and targets that branch.
 - **Branch names never contain `codex`, `cursor` or `claude`**, in any case.

package/README.md

@@ -10,7 +10,7 @@ spawns and talks to over hrpc — crash isolation for free, death is the exit
 itself. See [bare-supervisor](https://github.com/tetherto/bare-supervisor) for
 the supervision contract.
 
-## The npm artifact spawns; it does not import
+## The published package
 
 The published package ships the prebuilt engine and its runtime content, not
 the library source:
@@ -28,9 +28,9 @@ The `@qvac` inference addons and `pyodide` resolve from the host's real
 installs those alongside.
 
 The host-side library surface — `spawnHarness`/`harnessChild`, the transport,
-the model catalogs, the skill helpers — is consumed from this repository (git
-dependency) until a compiled surface ships. The tarball's export map points at
-files it intentionally omits: importing the npm artifact is an error by design.
+model catalogs, skill helpers and DOCX extractor — ships as compiled JavaScript
+and declarations in `dist-lib/`. The package exports resolve to that surface;
+the TypeScript source stays in the repository.
 
 ## Spawning
 
@@ -48,6 +48,28 @@ dir, ...) are the ones `worker/harness-sidecar.mjs` documents in this repo. The
 in-house hosts don't call this directly — they use the repo's library surface
 (`harnessChild` under bare-supervisor), which owns that argv contract.
 
+## DOCX extraction
+
+Hosts can supply the bundled Python extractor to their document pipeline:
+
+Set `QVAC_PYODIDE_CACHE_DIR` to a writable directory before calling the API,
+including from source and compiled-package consumers. The worker seeds this
+cache from shipped wheels; without it, Pyodide can try downloading packages.
+
+```js
+import { extractDocxText, closeDocxWorker } from '@qvac/harness/docx'
+
+const text = await extractDocxText(bytes, 'notes.docx', { signal })
+// At host shutdown, after outstanding extractions have settled:
+await closeDocxWorker()
+```
+
+The extractor preserves paragraph and table order, accepts up to 20 MiB, and
+requires the shipped Python wheels. With the cache configured, extraction uses
+those wheels offline. Bundled hosts also set `QVAC_PYODIDE_WORKER_ENTRY` and
+`QVAC_PYTHON_WHEELS_DIR` to their staged worker and wheels paths.
+Source checkouts prepare wheels with `bun run vendor:wheels`.
+
 ## Development
 
 ```