Weavatrix Quality

Weavatrix Quality（wvq）

了解你的更改可能破坏什么，以及它是否仍受到保护。

Weavatrix Quality（WVQ）使用你现有的运行器，将 OpenSpec 意图与 Git 更改转化为绑定到修订版本的 证明。常规的绿色路径消耗 0 个运行时大模型令牌。Rust 负责策略、选择、证据和证明；npm/JS 则是围绕相同二进制文件的类型化边界。

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

面向	包
npm（主要）	@weavatrix/wvq
MCP Registry	io.github.Weavatrix/weavatrix-quality
crates.io	wvq-cli · wvq-mcp · wvq-bench
发布版本	v0.1.0-alpha.5

Alpha 0.1.0-alpha.5。 实用的首个产品闭环（一个计划 → 一次执行 → 一份报告）。尚未达到完整的 v1 DoD —— 请参阅 CHANGELOG 和 ADR 0003。

---

安装

# primary distribution (ships wvq + wvq-mcp + wvq-bench for 6 platforms)
npm install --save-dev @weavatrix/[email protected]

# one-shot without adding a dependency
npx @weavatrix/[email protected] --help

# Rust binaries (alpha crates; API unstable)
cargo install wvq-cli --version 0.1.0-alpha.5
cargo install wvq-mcp --version 0.1.0-alpha.5
cargo install wvq-bench --version 0.1.0-alpha.5

由于 npm 名称相似性规则，未加作用域的 wvq 无法使用 —— 请始终使用 @weavatrix/wvq。

---

5 分钟快速入门

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 folder
npx @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 evidence
npx @weavatrix/[email protected] verify --change current

需要先配置绑定才能封存证明？请从 .weavatrix-quality/config.yaml 和示例开始。

---

CLI 操作手册

所有命令都接受 --repo <path>（默认值：.）。在 CI 中优先使用绝对路径。

日常周期

alias wvq='npx @weavatrix/[email protected]'

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>

规范 / 封存 / 债务

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

仅观察 CI（Stage A）

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

浏览器记录 → 稍后通过 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

对比选定项与全部项（基准测试）

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

退出码

代码	含义
0	成功 / 仅观察（即使判定尚未解决）
1	证据未解决 / 普通失败
2	阻止性 CONTRADICTED 验证

完整 CLI 功能：wvq --help。详细的产品规则请参阅 docs/STATUS.md。

---

MCP 操作手册

WVQ 以 mcport MCP 主机形式提供。默认配置 = 7 个工具，不提供 shell， 大型工件仅以句柄形式提供。

Cursor（mcp.json）

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

Claude Desktop

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

默认工具（编码 Agent）

quality_context   quality_plan   quality_run   quality_status
quality_verify    quality_explain   quality_evidence

Agent 工作流示例：

1. quality_context —— 此更改有哪些义务
2. quality_plan —— 与现有证明相比有哪些缺口（不执行）
3. quality_run — 执行受影响的保护，并发布 .weavatrix/coverage/lcov.info，供 Weavatrix coverage_map 使用
4. quality_verify —— 综合判定
5. quality_explain / quality_evidence —— 深入查看某个句柄或 ID

创作配置（TestProgram 草稿 → 预览 → 提升）

npx @weavatrix/[email protected] 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 保持为仅限 CLI，以防 Agent 将发现结果 或观察到的基线视为权威。

更多配置和 JSON-RPC 示例：examples/mcp/。

---

JavaScript 库操作手册

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

计划 → 运行 → 验证

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

规范 / 选择 / 债务 / 解释

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)

在 Node 中使用 MCP 客户端（默认配置 + 创作配置）

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 片段（GitHub Actions）

- 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

可运行的副本：examples/js/ · examples/cli/。

---

仓库策略

.weavatrix-quality/config.yaml 将具体测试绑定到义务 ID。 如果没有此映射，即使测试套件全部通过，状态仍为 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 会写入一个默认拒绝的起始配置。本仓库通过变更 wvq-invariants 来实践这一策略——参见 examples/cli/dogfood.sh。

浏览器预览需要在目标仓库中安装 Playwright：

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

---

WVQ 是什么 / 不是什么

是什么	不是什么
基于现有运行器的规范到证明	第二个测试框架
由 Weavatrix 支持的影响分析 + 测试选择	浏览器引擎（Playwright 仍会保留）
CLI + MCP + 类型化 JS 边界	OpenSpec 分支
绿色路径上不消耗 LLM 令牌	自动静默修复 oracle
对未知 schema 默认拒绝	单一的全局“质量百分比”

在生态系统中的定位：

Weavatrix          UNDERSTAND   what exists in source
Weavatrix Quality  PROVE        what must still be true after this change
Weavatrix Loom     COMPOSE      capabilities into ordinary Rust

---

从源代码构建

需要 Rust 1.89+。

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

---

文档索引

文档	适用场景
examples/	复制粘贴 CLI / MCP / JS 示例
CHANGELOG	Alpha 版本包含的内容
docs/STATUS.md	成熟度矩阵 + 下一项任务
docs/adr/0003-…	Alpha 与延后至 v1 的内容
docs/CANONICAL-MASTER-SPEC.md	规范性产品设计

许可证

MIT。参见 LICENSE。