Weavatrix Quality

io.github.Weavatrix由 GitHub 帳號 Weavatrix 發布v0.1.0-alpha.5更新於 Nov 3, 2026

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

已驗證STDIO僅桌面瀏覽器自動化開發者工具

概覽

AI 產生的概覽

Weavatrix Quality 把 OpenSpec 變更與 Git 差異轉化為綁定同一版本的測試證明，並向編碼助理提供規劃、執行、驗證與證據工具。

可以做什麼
  • 檢視某個變更的義務清單以及與現有證明之間的缺口，不執行任何測試
  • 執行最小範圍的受影響測試集並產出覆蓋率證據
  • 讀取狀態與綜合驗證結論，並依 id 深入查看某條證明或發現
  • 在可選的撰寫設定下撰寫 Playwright 測試程式：草擬、校驗、預覽、提升、錄製與修復
適用情境
當你希望助理判斷某次程式碼變更是否仍受測試保護，並產生同一版本的證明，而不只是跑一遍測試套件時使用。適合已有 OpenSpec 變更、Git 歷史與現成測試執行器的儲存庫。
執行需求
透過 npx 執行 npm 套件，以 stdio 在本機啟動，並在命令列傳入儲存庫路徑。需要 Node.js 與 Git 儲存庫，README 的 CI 範例使用 Node 24。瀏覽器預覽需要在目標儲存庫中安裝 Playwright。未宣告任何 API 金鑰或環境變數。
安裝前請注意
專案處於 alpha 階段，API 不穩定。init、run、spec seal 等命令會寫入儲存庫，撰寫設定還能提升與修復測試程式。若設定中沒有測試綁定，即使測試全綠仍為未證明狀態，因此結果取決於策略設定是否正確。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Weavatrix Quality，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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.

來源：README.md，提交 3e07414

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

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

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分