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.

text

OpenSpec   â†’ what must remain true
Weavatrix  â†’ what changed and what it can affect
Runners    â†’ smallest safe protection set
WVQ        â†’ same-revision Proof + composite verdict

Surface	Package
npm (primary)	`@weavatrix/wvq`
MCP Registry	`io.github.Weavatrix/weavatrix-quality`
crates.io	`wvq-cli` Â· `wvq-mcp` Â· `wvq-bench`
Release	v0.1.0-alpha.3

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

config.json

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

Claude Desktop

config.json

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

Default tools (coding agents)

text

quality_context   quality_plan   quality_run   quality_status
quality_verify    quality_explain   quality_evidence

Example agent workflow:

quality_context â€” what obligations exist for this change
quality_plan â€” gaps vs existing proofs (no execution)
quality_run â€” execute impacted protection
quality_verify â€” composite verdict
quality_explain / quality_evidence â€” drill into a handle or id

Authoring profile (TestProgram draft â†’ preview â†’ promote)

Terminal

npx @weavatrix/wvq@0.1.0-alpha.3 mcp --repo . \
  --profile authoring \
  --change checkout-fix \
  --base origin/main \
  --head WORKTREE

text

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

Terminal

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

Plan â†’ run â†’ verify

server.ts

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

server.ts

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)

server.ts

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)

yaml

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

yaml

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:

Terminal

npm install --save-dev playwright
npx playwright install chromium

What WVQ is / is not

Is	Is not
Spec-to-Proof over existing runners	A second test framework
Weavatrix-backed impact + selection	A browser engine (Playwright stays)
CLI + MCP + typed JS boundary	An OpenSpec fork
0 LLM tokens on the green path	Automatic silent oracle healing
Fail-closed on unknown schemas	A single global â€œquality %â€

Place in the ecosystem:

text

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

Doc	Use when
examples/	Copy-paste CLI / MCP / JS
CHANGELOG	What alpha ships
docs/STATUS.md	Maturity matrix + next task
docs/adr/0003-â€¦	Alpha vs deferred v1
docs/CANONICAL-MASTER-SPEC.md	Normative product design

License

MIT. See LICENSE.

Weavatrix Quality (wvq)

Install

5-minute quickstart

CLI cookbook

Day-to-day cycle

Spec / seal / debt

Observe-only CI (Stage A)

Browser record â†’ promote later via MCP/Studio

Shadow selected-vs-full (bench)

Exit codes

MCP cookbook

Cursor (mcp.json)

Claude Desktop

Default tools (coding agents)

Authoring profile (TestProgram draft â†’ preview â†’ promote)

JavaScript library cookbook

Plan â†’ run â†’ verify

Spec / select / debt / explain

MCP client from Node (default + authoring)

CI snippet (GitHub Actions)

Repository policy

What WVQ is / is not

Build from source

Docs map

License

Weavatrix Quality (`wvq`)

Cursor (`mcp.json`)