Weavatrix Quality

io.github.WeavatrixPublished by GitHub account Weavatrixv0.1.0-alpha.5Updated Nov 3, 2026

Revision-bound quality planning, execution, evidence, proof, and Playwright authoring.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper Tools

Overview

AI-generated overview

Weavatrix Quality turns an OpenSpec change plus a Git diff into revision-bound test proof, exposing plan, run, verify and evidence tools to coding agents.

What you can do
  • Inspect a change's obligations and gaps against existing proofs without executing anything
  • Run the smallest impacted protection set and publish coverage evidence
  • Read status and a composite verify verdict, then drill into a proof or finding by id
  • Author Playwright test programs in an optional authoring profile: draft, validate, preview, promote, record and heal
When to use it
Use it when you want an assistant to check whether a code change is still covered by tests and to produce a same-revision proof, rather than just running a test suite. Suited to repos that already have OpenSpec changes, Git history and existing test runners.
Requirements
Runs locally over stdio via npx of the npm package, with a repo path passed on the command line. Needs Node.js and a Git repository; the README's CI example uses Node 24. Browser preview needs Playwright installed in the target repo. No API keys or environment variables are declared.
Before you install
The project is an alpha release with an unstable API. Commands such as init, run and spec seal write into the repository, and the authoring profile can promote and heal test programs. A green suite without test bindings in the config stays unproven, so results depend on correct policy configuration.

Installation

In SourceWeft

  1. Open Weavatrix Quality in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Weavatrix Quality (wvq)

[CI] [npm] [MCP] [MIT]

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 trueWeavatrix  → what changed and what it can affectRunners    → smallest safe protection setWVQ        → same-revision Proof + composite verdict
SurfacePackage
npm (primary)@weavatrix/wvq
MCP Registryio.github.Weavatrix/weavatrix-quality
crates.iowvq-cli · wvq-mcp · wvq-bench
Releasev0.1.0-alpha.5

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

sh
# primary distribution (ships wvq + wvq-mcp + wvq-bench for 6 platforms)npm install --save-dev @weavatrix/[email protected]
# one-shot without adding a dependencynpx @weavatrix/[email protected] --help
# Rust binaries (alpha crates; API unstable)cargo install wvq-cli --version 0.1.0-alpha.5cargo install wvq-mcp --version 0.1.0-alpha.5cargo 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

sh
cd your-repo
# 1) read-only discovery (never writes, never seals)npx @weavatrix/[email protected] doctor
# 2) write fail-closed policy (first time only)npx @weavatrix/[email protected] init
# 3) compile OpenSpec obligations for a change foldernpx @weavatrix/[email protected] spec validate --change current
# 4) run the smallest safe protection set (also builds measured coverage)npx @weavatrix/[email protected] 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 evidencenpx @weavatrix/[email protected] 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

sh
alias wvq='npx @weavatrix/[email protected]'
wvq doctorwvq plan --change checkout-fixwvq select --change checkout-fix --base origin/main --head WORKTREEwvq run --change checkout-fix --base origin/main --head WORKTREE --scope impactedwvq statuswvq verify --change checkout-fixwvq explain <proof-or-finding-id>

Spec / seal / debt

sh
wvq spec validate --change checkout-fixwvq spec seal --change checkout-fix          # fail-closed; needs valid obligationswvq debt --change checkout-fix --base origin/main --head HEADwvq baseline --change checkout-fix --decision observed_only   # CLI-only, not MCP

Observe-only CI (Stage A)

sh
# facts stay honest (UNPROVEN / NOT_ENOUGH_EVIDENCE), process exit stays 0wvq verify --change checkout-fix --observe-only true

Browser record → promote later via MCP/Studio

sh
wvq record --change checkout-fix --route /checkoutwvq ingest-journal --file .weavatrix-quality/journals/session.jsonwvq ingest-cassette --file captures/checkout.har --origin https://app.example.test

Shadow selected-vs-full (bench)

sh
wvq bench --repo . --change checkout-fix --base origin/main --head WORKTREE# or: npx @weavatrix/[email protected] bench --repo . ...

Exit codes

CodeMeaning
0success / observe-only (even when verdict is unresolved)
1unresolved evidence / ordinary failure
2blocking 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)

json
{  "mcpServers": {    "weavatrix-quality": {      "command": "npx",      "args": [        "-y",        "@weavatrix/[email protected]",        "mcp",        "--repo",        "C:/path/to/your-repo"      ]    }  }}

Claude Desktop

json
{  "mcpServers": {    "weavatrix-quality": {      "command": "npx",      "args": ["-y", "@weavatrix/[email protected]", "mcp", "--repo", "/Users/you/src/app"]    }  }}

Default tools (coding agents)

text
quality_context   quality_plan   quality_run   quality_statusquality_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)

sh
npx @weavatrix/[email protected] mcp --repo . \  --profile authoring \  --change checkout-fix \  --base origin/main \  --head WORKTREE
text
quality_test_draft    quality_test_validate   quality_test_previewquality_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

sh
npm install --save-dev @weavatrix/[email protected]

Plan → run → verify

js
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

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

js
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/[email protected] doctor- run: >    npx @weavatrix/[email protected] run    --change current --base origin/${{ github.base_ref }} --head HEAD    --scope impacted --evidence-policy minimal- run: npx @weavatrix/[email protected] 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:

sh
npm install --save-dev playwrightnpx playwright install chromium

What WVQ is / is not

IsIs not
Spec-to-Proof over existing runnersA second test framework
Weavatrix-backed impact + selectionA browser engine (Playwright stays)
CLI + MCP + typed JS boundaryAn OpenSpec fork
0 LLM tokens on the green pathAutomatic silent oracle healing
Fail-closed on unknown schemasA single global “quality %”

Place in the ecosystem:

text
Weavatrix          UNDERSTAND   what exists in sourceWeavatrix Quality  PROVE        what must still be true after this changeWeavatrix Loom     COMPOSE      capabilities into ordinary Rust

Build from source

Requires Rust 1.89+.

sh
cargo test --workspace --lockedcargo clippy --workspace --all-targets --locked -- -D warnings

Docs map

DocUse when
examples/Copy-paste CLI / MCP / JS
CHANGELOGWhat alpha ships
docs/STATUS.mdMaturity matrix + next task
docs/adr/0003-…Alpha vs deferred v1
docs/CANONICAL-MASTER-SPEC.mdNormative product design

License

MIT. See LICENSE.

Source: README.md at commit 3e07414

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.1.0-alpha.5LatestSep 19, 2026
  2. v0.1.0-alpha.4Sep 19, 2026
  3. v0.1.0-alpha.3Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts