# 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

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