The Closure
field guide.

What the project owes. What the evidence supports. What still needs doing.

Closure Engine is an early-stage TypeScript CLI. The homepage report is an interactive illustration, not a hosted repository scanner. This guide explains the current model without assuming a public package, signup, or installation service.

The model

A coding agent can always produce one more change. Closure gives that work a boundary by separating the requirements, the evidence, and the implementation worker.

What’s owedExpanded requirements

What’s provenAdmissible evidence

What’s leftThe remaining plan

plan = closure(selected concepts, pinned catalog)
       − satisfied(observed system)

Select capabilities.
A versioned catalog supplies requirements, dependencies, policies, and invariants. A phrase such as “teams can invite people” has consequences beyond an invitation form.
Observe and reconcile.
Bindings connect obligations to evidence. The engine evaluates whether evidence is admissible and whether its input digest still matches the repository.
Schedule the difference.
Remaining obligations become bounded work. Capability targets define the intended depth; the scheduler prioritizes raising the floor.

The requirements and grading are deterministic. The code that satisfies them does not have to be.

What counts as evidence

A route existing and a route behaving correctly are different claims. Static evidence can establish structure; behavioral claims need evidence that supports behavior. Admissible fallback evidence is disclosed at its weaker strength.

PROVEN: Admissible evidence with a currently matching, independently recomputed digest.
CLAIMED: Evidence that has not been independently verified. It does not count toward a capability level.
STALE: The inputs changed, so the old proof no longer establishes the current state.
INADMISSIBLE: Evidence fails its obligation’s acceptance rules.
UNPROVEN: No supporting evidence, or the evidence records failure.

Proof has a shelf life.

The digest covers what the proof depended on: the files the test executed, the extractor that read the result, the wording of the obligation it answered, and the perturbation declared to check it. A mismatch reopens the obligation rather than preserving a misleading green status.

PROVENThe proof’s inputs match

STALEA covered input changes

Verify againReconcile fresh evidence

Changed inputs reopen the obligation. Yesterday’s proof is not today’s verdict.

Which languages and report formats work?

Evidence is language-neutral. The importer reads the Jest JSON shape and JUnit XML, which covers vitest, jest, node:test, pytest, go, gradle, dotnet and rspec. A test’s dependency set comes from the import graph for TypeScript and JavaScript and from a coverage trace for everything else, so a proof decays when the code the test executed changes, whatever language it is written in.

Negative controls

For critical and tier-4 test evidence, a passing test alone is insufficient. The engine requires a negative control for the behavior being claimed.

Prepare an isolated copy of the repository.
Run the unmodified test and establish that it passes.
Apply the declared perturbation to the mechanism under test.
Run the test again and observe whether it fails.

After the declared perturbation

The same test failsSensitivity demonstrated: The named test notices the chosen change. That is what this control establishes.
The same test still passesSensitivity not demonstrated: Investigate the control. The perturbation may have missed the intended protection.

A passing test after perturbation does not demonstrate sensitivity to that mechanism. A test that fails before perturbation establishes nothing about the control. A control that the worker merely reports is not equivalent to one the harness has verified. And the harness grades the one test the control names, not the file it lives in: a perturbation that breaks a neighbouring test is not a control for this one.

The CLI workflow

Closure Engine is not on a package registry yet. It builds and installs as a package from a checkout, and until it is published the commands below run from that checkout with pnpm.

pnpm install
pnpm closure --help

Point it at a repository in any language whose test runner can write a report:

pnpm closure init --repo ../subject

That detects the runner (vitest, jest, node:test, pytest, go, cargo, or says it could not) and writes two files into the subject’s own .closure/:

selection.yaml: Where you say what the product owes. Starts empty.
binding.yaml: How to run one test, how to run it under coverage, where the report lands, and how a test names the obligation it proves.

It never overwrites either.

From the first selection to the next task.

Say what is owed.
A verdict over nothing is refused.
```
$EDITOR ../subject/.closure/selection.yaml
```
Run the subject’s suite.
Write the report that init named. Use the command for your runner, such as pytest --junitxml=… or vitest --reporter=json ….

Observe, plan, and check the verdict.

pnpm closure observe --repo ../subject
pnpm closure plan    --repo ../subject
pnpm closure done    --repo ../subject

Get the next obligation.
A task envelope for the implementation worker.
```
pnpm closure next --repo ../subject
```
Trace the proof’s dependencies.
Dependency sets from coverage, so proofs decay with the code.
```
pnpm closure trace --repo ../subject
```

With the subject’s own files in place, --repo is the only flag any command needs. observe reads the report and the repository; it never runs a suite. trace, mutate and verify-control do run tests, always in an isolated copy.

Verifying a declared control

pnpm closure mutate         --repo ../subject <obligation> --write
pnpm closure verify-control --repo ../subject <obligation>

The search proposes a perturbation the named test notices, in JavaScript, Python or Go today; the harness applies it in a scratch copy and grades the one test the control names, not the file it lives in. Review a proposal against the obligation before accepting it: a kill in a large file is often incidental.

The website itself runs none of these commands. The browser example has no repository access.

The limits of done

DONE = TRUE means the executable completion conditions hold for the selected scope and observed repository state.

Something must be owed.
Required obligations must be proven.
Capabilities must meet their targets.
Nothing may rest on self-attestation alone.
Blocking gaps or ledger items must be resolved.

Fallback-strength evidence is an advisory, not a secret upgrade to full strength. The report should retain that distinction even when the completion gate passes.

The catalog can miss a requirement. An extractor can have limited coverage. Human review can discover something the current inputs do not capture. Closure provides an explicit, inspectable stopping condition—not a universal bug-free or security guarantee.

Read the science

Why a green suite stops meaning done, what the mechanisms above rest on, and which of Closure’s claims are tested rather than argued.

The science behind Closure
Return to the interactive example

The Closure field guide.

The model

Select capabilities.

Observe and reconcile.

Schedule the difference.