@qvac/harness 0.2.6 → 0.2.7

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

@@ -15,6 +15,26 @@ 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:
@@ -48,13 +68,13 @@ 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.
@@ -105,6 +125,32 @@ avoid `codex` / `cursor` / `claude`?
 **6. 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.
+
+### 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
@@ -112,18 +158,41 @@ 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.
+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.
+
+### 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.
+
+- `[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.
 
-Distinguish clearly:
+**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.
 
-- **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.
+If the user says this is a re-review, say explicitly which earlier concerns are
+resolved and which still stand.
 
 ## Posting (PR mode only)
 
-1. Print every proposed comment in chat first: file, line, body.
+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.
 2. Ask the user to confirm the exact set. Wait for a clear yes.
 3. Create the review as **PENDING**, with no event:
 

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
 
 ```