Example Spec: The Spec System Checks Itself

A worked example of a *.spec.md file, co-located with the spec runner and its documentation. Each assertion below checks that the spec system's own docs and runner stay honest as they change. Run it with:

node skills/testing/spec.js skills/testing/specs.spec.md

The topic doc and the runner agree on the verdict vocabulary

specs.md describes the three judge verdicts (pass, fail, refused) and their meanings. The set of verdicts the runner (spec.js) actually accepts must match that description exactly — no verdict documented but unhandled, and none handled but undocumented.

The documented CLI flags match the runner's flags

Every flag specs.md documents for spec.js must be a flag the runner actually parses, and every flag the runner parses must be documented. A flag that appears in one but not the other is drift.

The runner keeps orchestration in code and only judging in the LLM

The runner discovers spec files, parses them into assertions, and formats output using ordinary code; the only LLM call is the per-assertion judge. The runner must not delegate discovery, parsing, or reporting to an LLM.

One judge call is made per assertion, not per file

The runner must invoke the judge once per assertion (times the consensus sample count), never batching multiple assertions from a file into a single judge call. Per-assertion isolation is a stated reliability requirement.