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

# 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

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

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>

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

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

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/wvq@0.1.0-alpha.3 bench --repo . ...

{
  "mcpServers": {
    "weavatrix-quality": {
      "command": "npx",
      "args": [
        "-y",
        "@weavatrix/wvq@0.1.0-alpha.3",
        "mcp",
        "--repo",
        "C:/path/to/your-repo"
      ]
    }
  }
}

{
  "mcpServers": {
    "weavatrix-quality": {
      "command": "npx",
      "args": ["-y", "@weavatrix/wvq@0.1.0-alpha.3", "mcp", "--repo", "/Users/you/src/app"]
    }
  }
}

quality_context   quality_plan   quality_run   quality_status
quality_verify    quality_explain   quality_evidence

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

npm install --save-dev @weavatrix/wvq@0.1.0-alpha.3

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)

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

- 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

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: .

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

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

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