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.3. 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.3
# one-shot without adding a dependency
npx @weavatrix/wvq@0.1.0-alpha.3 --help
# Rust binaries (alpha crates; API unstable)
cargo install wvq-cli --version 0.1.0-alpha.3
cargo install wvq-mcp --version 0.1.0-alpha.3
cargo install wvq-bench --version 0.1.0-alpha.3
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.3 doctor
# 2) write fail-closed policy (first time only)
npx @weavatrix/wvq@0.1.0-alpha.3 init
# 3) compile OpenSpec obligations for a change folder
npx @weavatrix/wvq@0.1.0-alpha.3 spec validate --change current
# 4) run the smallest safe protection set
npx @weavatrix/wvq@0.1.0-alpha.3 run \
--change current \
--base origin/main \
--head HEAD \
--scope impacted \
--evidence-policy minimal
# 5) read-only composite verdict from stored evidence
npx @weavatrix/wvq@0.1.0-alpha.3 verify --change current
Need bindings before proofs can seal? Start from .weavatrix-quality/config.yaml
and the examples.
CLI cookbook
All commands take --repo <path> (default: .). Prefer absolute paths in CI.
Day-to-day cycle
alias wvq='npx @weavatrix/wvq@0.1.0-alpha.3'
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 <proof-or-finding-id>
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.3 bench --repo . ...
Exit codes
| Code | Meaning |
|---|
0 | success / observe-only (even when verdict is unresolved) |
1 | unresolved evidence / ordinary failure |
2 | blocking CONTRADICTED verify |
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.3",
"mcp",
"--repo",
"C:/path/to/your-repo"
]
}
}
}
Claude Desktop
{
"mcpServers": {
"weavatrix-quality": {
"command": "npx",
"args": ["-y", "@weavatrix/wvq@0.1.0-alpha.3", "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:
quality_context — what obligations exist for this changequality_plan — gaps vs existing proofs (no execution)quality_run — execute impacted protectionquality_verify — composite verdictquality_explain / quality_evidence — drill into a handle or id
Authoring profile (TestProgram draft → preview → promote)
npx @weavatrix/wvq@0.1.0-alpha.3 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.3
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.3 doctor
- run: >
npx @weavatrix/wvq@0.1.0-alpha.3 run
--change current --base origin/${{ github.base_ref }} --head HEAD
--scope impacted --evidence-policy minimal
- run: npx @weavatrix/wvq@0.1.0-alpha.3 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
