Skip to content

docs: cite the conformance test that exists, and record three rules where they are looked up - #506

Merged
JArmandoAnaya merged 1 commit into
mainfrom
docs/inference-line-crumbs
Aug 10, 2026
Merged

docs: cite the conformance test that exists, and record three rules where they are looked up#506
JArmandoAnaya merged 1 commit into
mainfrom
docs/inference-line-crumbs

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

Three rules that were written down somewhere other than where they get looked up, and two
comments pointing at a file that does not exist.

What changed

check.ts and check.test.ts cite a test that exists. Both pointed at
tests/scripts/checks_conformance.test.mjs. There is no such file, and there is no record of
one having been deleted — the job it describes belongs to
frontend/ui-core/src/data/conformance.test.ts, whose own header states the same contract
from the other side ("a second, deliberately naive validator", "the two failure modes tsc
provably cannot catch"). Both comments now name it.

While there, the unknown-key rule in check.ts said "a test pins it" without saying which.
It is pinned twice — check.test.ts:63 on the combinators, conformance.test.ts:281 across
every generated check — so it now names both. A reader who wants to know whether the rule is
really held can now get to the proof.

refactor-protocol gains the two cleanup-phase quirks. Both have the same shape: the
command reports failure while having succeeded, so a session that reads the exit code
re-does work that is already done. gh pr merge from a worktree exits non-zero on
fatal: 'main' is already used by worktree after squashing and deleting the branch, and
git ls-remote --heads can be read before GitHub's asynchronous deletion has landed. The
rule in both cases is to confirm the state rather than the exit code.

refactor-protocol gains the test-double fidelity rule. Stated as one rule because the
two halves fail together: a double built from a remembered signature does not run the code
under test, and what then passes is nearly always an absence assertion, which a double that
raises on entry satisfies for free. Two occurrences paid for it — the fake-producer migration
(cf. #491) and an IntegrityReport fake whose field name differed from the real model
(cf. #496), where a check that never ran was indistinguishable from a check that found
nothing.

DESIGN.md gains the indeterminate-progress rule. It lived only in a comment inside
InferenceScreen.tsx, which is the one place a person deciding how a new progress surface
should look will not read. Progress draws an indeterminate value as an empty track and an
empty track reads as 0%, so a run with no known total gets prose and no bar. Filed under
### Components, beside the other per-component contracts.

Verified against HEAD, then dropped

Two items were on the list for this pass and are not in the diff, because both are already
correct at 5b623e3#502 fixed them:

  • README.md quickstart was said to invoke visionset ui; it invokes visionset server
    (README.md:38). The PyPI wording is also already accurate and already non-announcing
    (README.md:34, docs/install.md:19).
  • docs/install.md was said to claim four export formats. It states no count at all; it tells
    the reader to run visionset format list "rather than trusting a list written down
    somewhere" (docs/install.md:50-54), which is the durable form of the fix.

Found, not fixed

  • Nothing new.

Test plan

No behaviour changes and no new tests — every edit is a comment, a skill, or a design
document. The claim under test is therefore that nothing broke, and the full gate was run in
stages (harness kills a single invocation at ~10 minutes). Every stage's exit code, verbatim:

Stage Command Exit
Python uv run pytest per directory from ls tests/: architecture cli examples formats inference jobs kernel mcp packaging scripts server test_versioning.py 0 each
Lint uv run ruff check .All checks passed! 0
Format uv run ruff format --check .364 files already formatted 0
Imports uv run lint-importsContracts: 4 kept, 0 broken. 0
Types uv run mypy src/visionset/kernelSuccess: no issues found in 63 source files 0
Script gates pnpm test:scriptstests 77, pass 76, fail 0, skipped 1 0
Frontend build pnpm -r build 0
Frontend test pnpm -r testTest Files 48 passed (48), Tests 903 passed (903) 0
Frontend lint pnpm -r lint 0
Generated bash scripts/check.sh generatedPASSED 0
Browser bash scripts/check.sh browserAll checks passed; e2e 95s, real-server cycle 22s, 1 passed (20.9s) 0

This PR closes nothing. #438, #466 and #417 are untouched.

…here they are looked up

- `check.ts` and `check.test.ts` both pointed at `tests/scripts/checks_conformance.test.mjs`,
  which is not a file in this repo. The generated checks are compared against a second reader
  of the spec by `frontend/ui-core/src/data/conformance.test.ts`; both comments now name it.
- `refactor-protocol` gains the two cleanup-phase quirks whose shared property is that the
  command reports failure while having succeeded, and the test-double fidelity rule.
- `DESIGN.md` gains the indeterminate-progress rule, which lived only in a screen comment.
@JArmandoAnaya
JArmandoAnaya merged commit 7bc4097 into main Aug 10, 2026
14 checks passed
@JArmandoAnaya
JArmandoAnaya deleted the docs/inference-line-crumbs branch August 10, 2026 10:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant