Weavatrix Quality

Weavatrix Quality (wvq)

Know what your change can break — and whether it is still protected.

Weavatrix Quality (WVQ) turns OpenSpec intent + a Git change into revision-bound proof using your existing runners. The ordinary green path spends 0 runtime LLM tokens. Rust owns policy, selection, evidence, and proof; npm/JS is a typed boundary around the same binaries.

OpenSpec   → what must remain true

Weavatrix → what changed and what it can affect Runners → smallest safe protection set WVQ → same-revision Proof + composite verdict

Alpha `0.1.0-alpha.5`. Useful first product loop (one plan → one execution → one report). Not the full v1 DoD — see CHANGELOG and ADR 0003.

---

Install

# primary distribution (ships wvq + wvq-mcp + wvq-bench for 6 platforms)

npm install --save-dev @weavatrix/wvq@0.1.0-alpha.5

one-shot without adding a dependency

npx @weavatrix/wvq@0.1.0-alpha.5 --help

Rust binaries (alpha crates; API unstable)

cargo install wvq-cli --version 0.1.0-alpha.5 cargo install wvq-mcp --version 0.1.0-alpha.5 cargo install wvq-bench --version 0.1.0-alpha.5

Unscoped wvq is blocked by npm name-similarity rules — always use @weavatrix/wvq.

---

5-minute quickstart

cd your-repo

1) read-only discovery (never writes, never seals)

npx @weavatrix/wvq@0.1.0-alpha.5 doctor

2) write fail-closed policy (first time only)

npx @weavatrix/wvq@0.1.0-alpha.5 init

3) compile OpenSpec obligations for a change folder

npx @weavatrix/wvq@0.1.0-alpha.5 spec validate --change current

4) run the smallest safe protection set (also builds measured coverage)

npx @weavatrix/wvq@0.1.0-alpha.5 run \ --change current \ --base origin/main \ --head HEAD \ --scope impacted \ --evidence-policy minimal

After a successful native coverage runner, Weavatrix coverage_map reads:

.weavatrix/coverage/lcov.info

Quality does not invent a second stack. Playwright is last-resort JS only.

5) read-only composite verdict from stored evidence

npx @weavatrix/wvq@0.1.0-alpha.5 verify --change current

Need bindings before proofs can seal? Start from .weavatrix-quality/config.yaml and the examples.

---

CLI cookbook

All commands take --repo (default: .). Prefer absolute paths in CI.

Day-to-day cycle

alias wvq='npx @weavatrix/wvq@0.1.0-alpha.5'

wvq doctor wvq plan --change checkout-fix wvq select --change checkout-fix --base origin/main --head WORKTREE wvq run --change checkout-fix --base origin/main --head WORKTREE --scope impacted wvq status wvq verify --change checkout-fix wvq explain

Spec / seal / debt

wvq spec validate --change checkout-fix

wvq spec seal --change checkout-fix # fail-closed; needs valid obligations wvq debt --change checkout-fix --base origin/main --head HEAD wvq baseline --change checkout-fix --decision observed_only # CLI-only, not MCP

Observe-only CI (Stage A)

# facts stay honest (UNPROVEN / NOT_ENOUGH_EVIDENCE), process exit stays 0

wvq verify --change checkout-fix --observe-only true

Browser record → promote later via MCP/Studio

wvq record --change checkout-fix --route /checkout

wvq ingest-journal --file .weavatrix-quality/journals/session.json wvq ingest-cassette --file captures/checkout.har --origin https://app.example.test

Shadow selected-vs-full (bench)

wvq bench --repo . --change checkout-fix --base origin/main --head WORKTREE

or: npx @weavatrix/wvq@0.1.0-alpha.5 bench --repo . ...

Exit codes

Full CLI surface: wvq --help. Deep product rules live in docs/STATUS.md.

---

MCP cookbook

WVQ ships as an mcport MCP host. Default profile = 7 tools, no shell, large artifacts as handles only.

Cursor (mcp.json)

{

"mcpServers": { "weavatrix-quality": { "command": "npx", "args": [ "-y", "@weavatrix/wvq@0.1.0-alpha.5", "mcp", "--repo", "C:/path/to/your-repo" ] } } }

Claude Desktop

{

"mcpServers": { "weavatrix-quality": { "command": "npx", "args": ["-y", "@weavatrix/wvq@0.1.0-alpha.5", "mcp", "--repo", "/Users/you/src/app"] } } }

Default tools (coding agents)

quality_context   quality_plan   quality_run   quality_status

quality_verify quality_explain quality_evidence

Example agent workflow:

1. quality_context — what obligations exist for this change
2. quality_plan — gaps vs existing proofs (no execution)
3. quality_run — execute impacted protection and publish .weavatrix/coverage/lcov.info for Weavatrix coverage_map
4. quality_verify — composite verdict
5. quality_explain / quality_evidence — drill into a handle or id

Authoring profile (TestProgram draft → preview → promote)

npx @weavatrix/wvq@0.1.0-alpha.5 mcp --repo . \

--profile authoring \ --change checkout-fix \ --base origin/main \ --head WORKTREE

quality_test_draft    quality_test_validate   quality_test_preview

quality_test_promote quality_test_record quality_test_heal

doctor / init / baseline stay CLI-only so agents cannot treat discovery or an observed baseline as authority.

More configs and JSON-RPC samples: examples/mcp/.

---

JavaScript library cookbook

npm install --save-dev @weavatrix/wvq@0.1.0-alpha.5

Plan → run → verify

import { WvqClient } from '@weavatrix/wvq'

const wvq = new WvqClient({ repo: process.cwd() })

const plan = await wvq.plan({ change: 'checkout-fix' }) console.log(plan.obligations, plan.gaps)

const run = await wvq.run({ change: 'checkout-fix', base: 'origin/main', head: 'WORKTREE', scope: 'impacted', evidencePolicy: 'minimal', }) console.log(run.run_id, run.outcome, run.scope_reason)

const verify = await wvq.verify({ change: 'checkout-fix' }) console.log(verify.state, verify.quality.proof, verify.base, verify.head)

if (verify.blocking) { for (const reason of verify.quality.blocking_reasons) { console.error(reason.code, reason.detail) } process.exit(2) }

Spec / select / debt / explain

await wvq.specValidate({ change: 'checkout-fix' })

const selected = await wvq.select({ change: 'checkout-fix', base: 'origin/main', head: 'HEAD', }) console.log(selected.selected, selected.uncovered_mandatory)

const debt = await wvq.debt({ change: 'checkout-fix', base: 'origin/main', head: 'HEAD', }) console.log({ new: debt.new, fixed: debt.fixed, returned: debt.returned })

const detail = await wvq.explain(verify.proofs[0]?.id) console.log(detail.summary, detail.provenance)

MCP client from Node (default + authoring)

import { WvqMcpClient } from '@weavatrix/wvq/mcp'

const mcp = new WvqMcpClient({ repo: process.cwd(), profile: 'default', change: 'checkout-fix', }) const status = await mcp.call('quality_status', { change: 'checkout-fix' }) const verdict = await mcp.call('quality_verify', { change: 'checkout-fix' })

const authoring = new WvqMcpClient({ repo: process.cwd(), profile: 'authoring', change: 'checkout-fix', base: 'origin/main', head: 'WORKTREE', }) const draft = await authoring.draft() const validated = await authoring.validate(candidateProgram) const preview = await authoring.preview(validated.program, { screenshot: true, trace: true, }) if (preview.passed) { await authoring.promote(preview.preview_id, validated.program) }

CI snippet (GitHub Actions)

- uses: actions/setup-node@v4

with: node-version: 24

• run: npx @weavatrix/wvq@0.1.0-alpha.5 doctor
• run: > npx @weavatrix/wvq@0.1.0-alpha.5 run --change current --base origin/${{ github.base_ref }} --head HEAD --scope impacted --evidence-policy minimal
• run: npx @weavatrix/wvq@0.1.0-alpha.5 verify --change current --observe-only true

Runnable copies: examples/js/ · examples/cli/.

---

Repository policy

.weavatrix-quality/config.yaml binds concrete tests to obligation IDs. A green suite without this mapping stays UNPROVEN.

quality_policy_v: 1

test_bindings:

• path: tests/permissions.spec.ts runner: playwright case: viewer cannot delete a widget obligations: [permissions-delete] cost: 10 flake_penalty: 0

browser: base_url: http://127.0.0.1:3000 engine: chromium headless: true module_root: .

wvq init writes a fail-closed starter. This repo dogfoods change wvq-invariants — see examples/cli/dogfood.sh.

Browser preview needs Playwright in the target repo:

npm install --save-dev playwright

npx playwright install chromium

---

What WVQ is / is not

Place in the ecosystem:

Weavatrix          UNDERSTAND   what exists in source

Weavatrix Quality PROVE what must still be true after this change Weavatrix Loom COMPOSE capabilities into ordinary Rust

---

Build from source

Requires Rust 1.89+.

cargo test --workspace --locked

cargo clippy --workspace --all-targets --locked -- -D warnings

---

Docs map

License

MIT. See LICENSE.