Start free

Running the report

In the Workshop, the Assurance lens shows this continuously — nothing to run. From a terminal, one command:

vishwakarma assure

It analyses the model, derives the obligation set, and writes three artifacts: a readable report, a machine-readable one, and an HTML version.

Nothing is executed. Every obligation comes back unverified, and that is the intended first run — the count alone sizes the testing problem your model poses, which is worth knowing before a single test exists.

Folding in evidence

To get a verification score, run the generated suite and hand the outcomes back:

go test ./gen/backend/testkit/          # produces the results file
vishwakarma assure --results <file>     # folds outcomes in, by obligation id

Now behavioural verification is computed, and an obligation a passing case discharges becomes verified — unless it needed a substrate the run did not have, in which case the reason is recorded instead of the tick. See Obligations for why that distinction is load-bearing.

Failing a build on it

Three independent gates. They answer different questions, and it is worth being deliberate about which you want:

# 1. Refuse a finding at or above a severity.
vishwakarma assure --fail-on critical

# 2. Refuse to drop below a level — globally, or per bounded context.
vishwakarma assure --min-level L2
vishwakarma assure --min-level payments.v1=L3 --min-level L1

# 3. Refuse a REGRESSION against an earlier report.
vishwakarma assure --no-regression previous-assurance.json

The third is the one to reach for first, and it is the least obvious.

An absolute threshold forces a decision you may not be ready to make: pick it too high and the build is red from day one, too low and it never catches anything. --no-regression asks a question you can always answer — is this worse than it was? — so you can adopt assurance on a project that is nowhere near L2 and still be protected against a guarantee quietly disappearing.

That is precisely the failure mode a passing test suite is worst at catching: nobody deletes a test, but someone removes the guard the test was standing behind, and the suite goes green because there is nothing left to check.

Waivers

vishwakarma assure --waivers waivers.yaml

A waiver names an obligation by id, states a reason, and expires. A permanent exception is indistinguishable from a forgotten one.

Reading the output first

Start with the binding constraint — it names the single thing between you and the next level. Then:

  • critical findings, which are security or readiness problems rather than coverage gaps;
  • falsified claims, if any: a capability claiming more than its evidence supports;
  • the obligation split, particularly how many need a real deployed stack, since those will never clear from a hermetic run however long you work at it.

A worked example of the shape, with commentary, is in The dimensions.

A sensible adoption path

  1. Run it once and read D1. Specification completeness needs no tests and is usually the biggest single gap. Fixing it is authoring.
  2. Add the testkit slot and run the generated suite. Now you have a real verification number rather than an estimate.
  3. Turn on --no-regression in CI. Cheap, and it protects what you have from here on.
  4. Claim alpha until the report says otherwise. It is accurate, it scores fine, and the day you have understated yourself the report will say so.
  5. Raise the floor per context, not globally. Put the strict level where the risk is.

The order matters. Reaching for a level gate before step 1 produces a red build that tells you to go and do step 1 anyway, with more noise.