Weavatrix Quality

Weavatrix Quality（wvq）

変更によって何が壊れる可能性があるか、そしてその保護がまだ有効かを把握できます。

Weavatrix Quality（WVQ）は、OpenSpec の意図と Git の変更を、既存のランナーを使ったリビジョンに紐づく証明に変換します。通常の成功パスでは、実行時の LLM トークン消費は 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

アルファ版 0.1.0-alpha.5。 最初のプロダクトサイクル（1つの計画 → 1回の実行 → 1つのレポート）を実用的に回せます。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 と examples から始めてください。

---

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 個のツールで、シェルは使用せず、大きなアーティファクトはハンドルとしてのみ扱います。

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"]
    }
  }
}

デフォルトのツール（コーディングエージェント向け）

quality_context   quality_plan   quality_run   quality_status
quality_verify    quality_explain   quality_evidence

エージェントのワークフロー例：

1. quality_context — この変更に存在する義務を確認
2. quality_plan — 既存の証明に対する不足を確認（実行なし）
3. quality_run — 影響を受ける保護を実行し、Weavatrix の coverage_map 用に .weavatrix/coverage/lcov.info を公開
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 専用です。エージェントが検出結果や観測されたベースラインを権威あるものとして扱えないようにするためです。

その他の設定と 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 とは／WVQ ではないもの

とは	ではないもの
既存のランナーを使った仕様から証明への変換	2 つ目のテストフレームワーク
Weavatrix を活用した影響分析＋選択	ブラウザーエンジン（Playwright はそのまま使用）
CLI＋MCP＋型付き JS 境界	OpenSpec のフォーク
成功経路での LLM トークン消費量 0	オラクルの自動・無通知修復
未知のスキーマに対するフェイルクローズ	単一のグローバルな「品質％」

エコシステム内での位置付け：

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 をご覧ください。