open-standards/wai/wai-quantum-cli/skills/wai-quantum/reference/workflow.md

A project, its intent, and its test

wai-quantum new DIR --template NAME makes:

File	What it is
NAME.qasm	the program
reference.qasm	the program it is checked against (ghz and grover)
intent.json	what the program must do
test.sh	the test: lint, check every intent, run, verify both receipts
ci/check.sh	the test for CI: installs the version the project was made with if the runner has none
ci/workflow.yml	an example workflow that runs ci/check.sh
mcp.json	the local MCP server's entry, for an agent's client
AGENTS.md	instructions for coding agents

Nothing is written when a file it would make is already there. An AGENTS.md already there keeps its text: the block is added after it.

intent.json

{
  "program": "grover.qasm",
  "run": { "shots": 1000 },
  "intent": [
    { "equivalent": "reference.qasm" },
    { "distribution": { "11": 1.0 } }
  ]
}

• program: the program's file, beside intent.json.
• run: what a run asks, as a job does: shots, seed, method, observables, amplitudes, noise, options. Any other field is refused, never ignored.
• intent: a list. Each entry is one of these:
  • {"distribution": {"00": 0.5, "11": 0.5}, "tolerance": 1e-9}: the exact distribution of the measured bits, keyed by the classical bits with the highest bit first. The engine computes it by the state vector, or under the run's noise by the density matrix, in double precision. It holds when the total variation distance is within tolerance (default 1e-9).
  • {"equivalent": "reference.qasm"}: the same circuit as the reference, up to a global phase. The engine's ladder decides it: tableaus for Clifford circuits, every basis state to 8 qubits, checked rewrites at any width (all proofs), then random product states to 22 qubits (evidence, not proof).
  • {"prepares": "reference.qasm"}: the same state from |0…0⟩, with the same qubits measured into the same bits.
  • {"sampled": {"00": 0.5, "11": 0.5}, "test": "chi_squared", "alpha": 0.01, "shots": 4000}: the program run as run asks for that many shots (at seed, or the run's), and its counts held to the distribution by the stated test, chi_squared (Pearson's) or g_test (the likelihood ratio), at the significance level alpha. All three are required. It holds when the test does not reject: evidence, not proof. An outcome of probability 0 that was sampled fails it outright.
  • Any entry may carry a note, and "require": "proof", which counts evidence as unchecked.

wai-quantum test

wai-quantum test DIR (or sh DIR/test.sh):

• runs the program as run asks, with its intents, so the engine's verdict is in the run's result, sealed by its receipt;
• prints each intent's outcome (holds, fails or unchecked), how the engine decided it, and, for a distribution, its distance, or for a sampled one, its p-value; then the verdict's level (proof, evidence, executed, parsed, refused) and its statement;
• writes receipts/NAME.run.json, the run sealed with the user's key, and receipts/NAME.intent.json, the check sealed with it. The check binds the program, every reference's text, the verdict and the run's receipt;
• exits 0 when every intent holds, 1 when one fails, and 2 when one is unchecked.

--json prints the check's record, and --junit FILE writes the verdict as a JUnit report, one test case for each intent. A program that measures in the middle has no single final distribution: its distribution intent is unchecked.

One run with an intent, and a repair

• wai-quantum run FILE --intent ref.qasm checks that the program is the same circuit as ref.qasm; --intent dist.json takes a distribution ({"00": 0.5, "11": 0.5}), an intent (a sampled one too), a list of intents, or a project's intent.json. The result carries the verdict; the command exits 0 when it holds, 1 when it fails, 2 when it is unchecked. On the MCP server, run_quantum_circuit takes intent with each reference's text.
• wai-quantum repair FILE makes the fixes that are mechanical, each on the lines its diagnostic flags (a missing ;, an undeclared register's size, a measurement with no target, an unbounded while given --max-iterations N, an angle the bit-exact method refuses rounded with --dyadic-bits K), prints the program and lists every changed line. --proposed FILE checks a fix you wrote: it is rejected if it changes any other line. What needs a person comes with the reader's advice. run --repair repairs before running, and the verdict lists each repair.