A relation is validated by its basis. Which bases make it current:
| Type | Validated by |
|---|---|
implements | evidence or a review only, never by hand |
verifies | evidence of the failing run, a review, or a judgement |
excuses, depends_on | a judgement |
tests, refines | nothing: structural facts read from the source |
Evidence: mix test && mix surfex.confirm --evidence. It records every relation the
test runs show: verifies on a test's failing run; tests and implements once a test
has gone red against one version of the code and green against another (or is
baselined under adoption, mix surfex.info adoption).
Review: mix surfex.validate TEST SPEC_UNIT --note N. Read the unit's claims and the
test; judge whether the test checks them (cases, boundaries, what must not change); fix
the test where it falls short. It needs the verifies relation and green evidence at the
current test and code versions. The unit may be a section whose hint the test already
verifies: the review then records the section's implements for the code the test
exercises. The note says which assertion checks which claim.
Many at once: --file PATH on confirm or validate records a file of relations in one
run, one per line, tab-separated, each line ending with its own note (FROM TO TYPE NOTE,
or TEST UNIT NOTE). The notes must be distinct; write each line after judging that
relation.
Evidence from CI: --merge PATH (once per file) on confirm --evidence, validate,
relate and suggest --accept reads CI jobs' evidence files beside the local run, so a
test excluded locally (it needs a service you don't run) counts from CI's run.
Docstrings aren't covered. A function's version leaves out its @doc, so a docstring
that states a contract can drift from the spec unnoticed. Read them together.
Judgement: mix surfex.confirm FROM TO --type T --note N. For a spec reworded with
no change in behaviour (verifies), or an excuse. It refuses implements.
--validated on status fails on current implements/verifies relations without one of
these (unvalidated: recorded before validation existed, or a baseline no longer trusted).