@qvac/harness 0.2.8 → 0.2.9

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

@@ -1,414 +0,0 @@
----
-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 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
-
-Reviews changes in `@qvac/harness`. Two modes.
-
-- **PR mode** (a PR number or URL) — a short overview in chat, then a **pending**
-  GitHub review of per-file inline comments. The pending review is created only
-  after the user confirms the exact set of comments. **Never submit the review
-  event** (`COMMENT`, `REQUEST_CHANGES`, `APPROVE`) — that is the user's call,
-  from the GitHub UI.
-- **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,statusCheckRollup \
-  > /tmp/pr-<num>.json
-gh pr diff <num> --repo tetherto/qvac-harness --patch > /tmp/pr-<num>.patch
-```
-
-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. The default scope is everything uncommitted — staged, unstaged and
-untracked:
-
-```bash
-git diff --staged > /tmp/local-staged.patch
-git diff > /tmp/local-unstaged.patch
-git status --porcelain=v1
-git ls-files --others --exclude-standard    # untracked, easy to miss
-```
-
-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
-
-One workflow gates this repo: **Integrate** (`.github/workflows/ci.yml`), a
-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        |
-
-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 run view --repo tetherto/qvac-harness --log-failed --job <id> > /tmp/pr-<num>-<id>.log
-```
-
-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
-that lists twelve nits under a broken contract has buried the real thing.
-
-**1. Correctness.** Does it do what the title claims? Trace the changed path
-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.
-
-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
-  `package.json#exports` — is it intentional, and is it a breaking change?
-- `schema/` or `spec/` changes: is the wire format still compatible, and was the
-  baseline regenerated (`bun run build:schema`) rather than hand-edited?
-- Does the change match its own type declarations, and do callers in this repo
-  still typecheck?
-
-**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.
-
-**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.
-
-**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`?
-
-**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.
-
-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
-
-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, 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. 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/pr-<num>-review.json
-```
-
-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.
-
-If the user edits the selection after the preview, rewrite the file before
-running the command.
-
-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 4 reviews against → **js-house-style**. Load it; do not review
-  from memory of it.

package/CLAUDE.md

@@ -1,39 +0,0 @@
-# @qvac/harness
-
-The QV.AC inference engine: `generate(context)` over the QVAC SDK, plus the tool
-runtime skills execute in. **Inference in, events out** — it knows nothing about
-the app, hyperdb or sync. It runs as a supervised child process (or a Bare thread
-on mobile) that a host spawns and talks to over hrpc.
-
-Runs on both Bare and Node. Anything that only works on one is a bug.
-
-## Durable invariants
-
-- **The published package spawns; it does not import.** The tarball ships the
-  prebuilt bundle and its runtime content, and its export map deliberately points
-  at files it omits. That map is not broken — do not "fix" it.
-- **`spec/` is generated** by `bun run build:schema`. Never hand-edit it; CI fails
-  when it is dirty after regeneration.
-- **Dependency `overrides` pin the resolutions the engine is validated against.**
-  Keep them aligned with the direct specs — npm refuses a mismatch on publish.
-- **The cache is the SDK's.** Do not add caller-side history eviction or
-  chars-per-token estimation.
-
-## Working here
-
-- `bun run lint` (prettier + lunte + tsc) and `bun run test` (node, bare and
-  addon lanes) before considering a change done.
-- Tests live in `test/` and run under brittle. A non-trivial change ships tests.
-
-## Always
-
-- **Comment only what the code cannot say.** Why, not what. One or two lines,
-  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/docs/decisions/2026-05-29-kvcache-tool-turns.md

@@ -1,75 +0,0 @@
----
-id: ADR-2026-05-29-kvcache-tool-turns
-status: superseded
-introduced_by: PR-228
-supersedes: []
-superseded_by: [ADR-2026-06-02-kvcache-tool-turns-reenabled]
----
-
-# KV-cache session is disabled for tool-using completions
-
-> **Superseded** by
-> [ADR-2026-06-02-kvcache-tool-turns-reenabled](./2026-06-02-kvcache-tool-turns-reenabled.md):
-> the cache is re-enabled for tool turns now that models load with
-> `toolsMode: "dynamic"` (the SDK's DYNAMIC path is coherent, including across
-> reload). Kept for history.
-
-## Decision
-
-The `@qvac/sdk` session prompt cache (`completion({ kvCache })`) is passed
-**only for tool-free completions** — `kvCache` is set only when
-`tools.length === 0`. Agentic / tool-using turns always run without the session
-cache.
-
-## Context
-
-The SDK session cache has two paths (see
-`@qvac/sdk → server/bare/plugins/llamacpp-completion/ops/completion-stream.ts` in the SDK):
-
-- **STATIC** (no `tools`): on a cache hit it sends `history.slice(savedCount)`
-  and self-heals a stale boundary by re-sending the full history. Robust against
-  our reconstructed history.
-- **DYNAMIC** (`tools` present): on a cache hit it sends only a role-based
-  _fragment_ of the history and trusts the SDK's own tool-chain flow to have
-  anchored the rest of the cache.
-
-Our agentic loop builds (and on reload reconstructs from a persisted transcript)
-the full history its own way. That does not satisfy the DYNAMIC path's
-assumptions, so on a tool-cache hit the model receives an incoherent prompt and
-emits `<tool_call>` markup as plain text instead of a parseable tool call —
-silently breaking tool calling (no parse, no approval, no execution). Tools are
-text-parsed (`toolCalling: "textParse"`), so a corrupted prompt degrades to a
-plain assistant message rather than erroring.
-
-## Alternatives Considered
-
-- **Always-on per-chat `kvCache`** (the state that introduced the regression):
-  breaks tool calling as above.
-- **Auto-cache (`kvCache: true`)**: tool-call turns are never cached, and a
-  verbatim `cacheableAssistantContent` echo is required for a hit —
-  incompatible with our thinking-stripped reconstruction.
-- **Conform to the SDK's tool-chain contract** (collapse consecutive messages +
-  `deleteCache` on divergence, like the legacy desktop worker): viable but a
-  separate project, tracked in `.ai/cursor/plans/kvcache-tool-turn-reuse.md`.
-
-## Consequences
-
-- Tool turns re-prefill the full history each call (no session-cache reuse).
-  Tool calling stays correct; this is the prior known-good behavior.
-- Tool-free turns (plain chat / title / summary) still benefit from the STATIC
-  cache path.
-- Regression guards are GPU-free and mock-based:
-  `qvac-app → core/src/services/message/agentic-completion.test.ts` (argument-contract:
-  never send `kvCache` with `tools`) and the spec-fake
-  `qvac-app → core/src/services/message/__fixtures__/fake-completion-sdk.ts` (reproduces the
-  cache-hit tool-parse failure).
-- Revisit if the SDK adds a "send full history, you slice it" mode for tools, or
-  when the conformance project lands.
-
-## When Agents Should Read This
-
-Read this before changing how `kvCache` is passed to `sdk.completion`, the
-agentic loop's history construction, or transcript reconstruction —
-`qvac-app → core/src/services/message/agentic-completion.ts`,
-`qvac-app → core/src/services/message/agentic-loop.ts`,
-`qvac-app → core/src/services/common/transcript.ts`.

package/docs/decisions/2026-06-02-kvcache-tool-turns-reenabled.md

@@ -1,127 +0,0 @@
----
-id: ADR-2026-06-02-kvcache-tool-turns-reenabled
-status: superseded
-introduced_by: PR-QVAC-19770
-supersedes: [ADR-2026-05-29-kvcache-tool-turns]
-superseded_by: [ADR-2026-08-20-kvcache-static-placement]
----
-
-# KV-cache session is re-enabled for tool-using completions
-
-> **Superseded** by
-> [ADR-2026-08-20-kvcache-static-placement](./2026-08-20-kvcache-static-placement.md):
-> the half of this record that still holds is that `kvCache: 'chat-<id>'` rides
-> every completion. The dynamic-mode half was built on a false premise — the
-> addon's compact-tools anchoring never ran on any shipped model (its arch gate
-> is exact `qwen3`; ours are `qwen35`/`qwen36`), so the coherence this record
-> credits to dynamic mode was never exercised, and the "static never surfaced
-> the tool-call format" claim did not survive re-testing. core-v2 loads static
-> with no sliding window since 2026-08-20; mechanics in
-> `docs/kvcache-reference.md`. The `QVAC_PROMPT_CACHE` kill-switch and
-> `deleteChatPromptCache` described below were core-v1 machinery and do not
-> exist in the current runtime.
-
-## Decision
-
-The `@qvac/sdk` session prompt cache (`completion({ kvCache: "chat-<id>" })`) is
-passed for **all** completions with a chatId — tool-using and tool-free alike —
-gated only by the `QVAC_PROMPT_CACHE` kill-switch. This reverses
-ADR-2026-05-29, which disabled the cache whenever tools were present.
-
-## Context
-
-The prior decision disabled tool-turn caching because the SDK's DYNAMIC cache
-path broke tool-call parsing: it ships a role-based history fragment and trusts
-the addon's tool-chain anchoring, which our reconstructed history did not
-satisfy → `<tool_call>` markup leaked as text. Two things changed:
-
-- Models loaded with `modelConfig.toolsMode: "dynamic"` (QVAC-19660). In
-  dynamic mode the addon anchors tools per-turn (compact-tools), excludes the
-  tool set from the cache config hash, and the fragment slicing keeps
-  multi-round tool turns coherent — including across a model evict/reload.
-  **No longer true as of `@qvac/sdk` 0.18 (QVAC-23936):** the key was removed
-  and the parser rejects it, so static is the only placement. Dynamic was in
-  any case a silent no-op on every arch we ship — the addon gates
-  `tools_compact` on exact-arch `qwen3` while our catalog is `qwen35`/`qwen36` —
-  and the SDK still sliced as-if-dynamic, which made the cache the chat's
-  _memory_ rather than an accelerator: after any cache reset it sent only the
-  last exchange. Under static placement the tool block sits in the addon's
-  protected prefix instead, and 0.18 keeps it out of the primed prefix
-  (QVAC-23251) so the qwen3.5 template no longer raises 'No user query found in
-  messages.'
-- An SDK e2e guard (`kv-cache-tools-dynamic-reuse`, plus a qwen35-dialect
-  variant) verifies a custom-key multi-round tool chain reuses the on-disk cache
-  (`cacheTokens > 0`) and keeps tool calls parseable across an evict/reload.
-
-With the DYNAMIC path proven coherent across reload, the heavyweight
-"reconstruction invalidation / byte-identical history" work the prior ADR
-deferred is unnecessary; divergence is handled with targeted invalidation.
-
-## Consequences
-
-- **Do not pass `toolsMode` at model load.** SDK 0.18 removed the key and its
-  parser rejects an unrecognised one, so passing it fails the load outright and
-  the app parks on the splash. Static placement is the default and the only mode.
-- Dropping a key from `modelConfig` re-keys `modelId`, which is identity-by-config,
-  so expect one cold prime per chat on the first run after such a change.
-- Tool turns reuse the session KV cache: lower TTFT/prefill on multi-round tool
-  turns and follow-ups (manually: round-2 TTFT ~1.1s → ~0.3s; cacheTokens grows
-  monotonically across a conversation).
-- `QVAC_PROMPT_CACHE` (default on; `0`/`false`/`off`) disables all
-  prompt caching as a kill-switch.
-- The per-chat cache is explicitly invalidated on chat delete and agent delete
-  (which cascades to its chats) via `deleteChatPromptCache`, plus a defensive
-  drop on retry (see below). Edit / branch / truncate flows do not exist yet and
-  need no hook.
-- **Why stop / failed / new-message-after-failure need no invalidation.** The
-  cache only ever holds _successful_ turns: the SDK rolls back uncommitted turns
-  on abort (the custom-key path commits only when not aborted and tokens were
-  produced), and failed / canceled / not_delivered replies are excluded from
-  model-visible history (`isModelVisibleMessage`, `qvac-app → core/src/services/common/history.ts`).
-  So a stopped or failed turn leaves neither a committed cache entry nor a
-  visible history row — the reconstructed history and the cached prefix stay
-  aligned, and the next turn (new message or retry) does not slice against a
-  stale prefix. The SDK's own `kv-cache-cancel-then-new-prompt` e2e covers this
-  cancel-then-continue coherence. The **retry** `deleteChatPromptCache` is
-  therefore belt-and-suspenders, not load-bearing: it costs one re-prime on a
-  rare, user-initiated path and removes any dependence on the rollback timing.
-- **Mobile scope.** Mobile now runs the same assistant and harness completion path
-  inside its supervised Bare worklets, so the per-chat cache key reaches the SDK
-  without the retired worker-to-host SDK bridge.
-- `chatPromptCacheKey` is the single source of truth for the `chat-<id>` key
-  shared by the completion path and the invalidation callers.
-- Known SDK limitation: on a multimodal (M-RoPE, `n_pos_per_embd > 1`) model such
-  as Qwen3.5, the SDK's KV sliding-window position shift (`seq_add`/`seq_div` via
-  `trySlidePrefill`) GGML_ASSERT-crashes the worker when the context fills. A
-  standalone SDK repro confirmed this is **independent of `toolsMode` (static and
-  dynamic both crash) and of whether tools are passed**, and is not caused by the
-  prompt cache — it is the sliding window itself, unsupported for multi-pos
-  models. Interim mitigation (separate from the kill-switch): we temporarily
-  stopped setting `n_discarded` at model load so on overflow the SDK took the
-  catchable `CONTEXT_OVERFLOW` path instead of the crashing slide.
-  **Resolved (2026-06-23):** `@qvac/sdk` 0.13.5 (llm-llamacpp 0.24.0) ships
-  M-RoPE/iM-RoPE sliding-context support, so `n_discarded` is set again in
-  `@qvac/sdk → model/model-load-config.ts` and the workbench no longer trims history. See
-  [`2026-06-23-append-only-history.md`](./2026-06-23-append-only-history.md).
-- Regression guards updated: the contract test now asserts `kvCache` IS sent
-  with tools; the spec-fake models dynamic mode (healthy on a tools cache hit);
-  invalidation hooks are covered.
-- **The in-repo suite cannot prove real dynamic-mode coherence.** The spec-fake
-  (`@qvac/sdk → __fixtures__/fake-completion-sdk.ts`) is parameterized to treat dynamic mode
-  as healthy, so the in-repo tests guard against regressing the model load back
-  to static mode and against dropping the `kvCache` key — but they do not prove
-  the SDK's real DYNAMIC path stays coherent against our reconstructed history.
-  That proof lives in the out-of-repo SDK e2e (`kv-cache-tools-dynamic-reuse`
-  and its qwen35 variant), which this repo's CI cannot run.
-
-## When Agents Should Read This
-
-Read this before changing how `kvCache` is passed to `sdk.completion`,
-`toolsMode` at model load, the agentic loop's history construction, transcript
-reconstruction, or the cache invalidation hooks —
-`qvac-app → core/src/services/message/agentic-completion.ts`,
-`qvac-app → core/src/services/model/service.ts`,
-`qvac-app → core/src/services/execution/service.ts`,
-`qvac-app → core/src/services/api/domain-apis.ts`,
-`@qvac/core → lib/assistant.ts`, and
-`lib/capabilities/completion.ts`.