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

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:

1. quality_context — what obligations exist for this change
2. quality_plan — gaps vs existing proofs (no execution)
3. quality_run — execute impacted protection
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.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

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.