spec-case

An in-code, AI-native annotation system + multi-language toolchain: markers like @spec/@rule/@link live right on the code, distilled by per-language tools into a machine-readable asset for AI to consume. It is the shared source-of-truth for spec/case assets bound to code, used white-box by case-code-review (ccr) and black-box by test/eval/perf harnesses. ｜ 中文: README.zh-CN.md

What it is

A spec states the intent/contract of a code symbol (a function). A case is one reusable stimulus + per-face judgment criteria hanging off that spec. spec-case's distinct contribution is a stable code↔spec/case binding — the symbol-id — so the same asset can be:

• run black-box by a harness (case → verdict), and
• attached white-box by ccr to the changed review unit (spec/case as a per-function checklist).

A review unit is the review-side twin of a case: same "requirement/contract" asset, two consumers.

Layout (modeled on OpenSpec)

• docs/ — concepts.md, glossary.md
• specs/ — normative specs in OpenSpec's Requirement / Scenario style; specs/symbol-id/ is the core contract
• languages/ — per-language expression (go.md markers, python.md decorators) + examples
• schemas/ — case.schema.json, spec-json.schema.json (the generated artifact ccr ingests)
• python/ — the pip package: markers + specgen (dependency-free core), plus the canonical Case model (spec_case.model / spec_case.facets, install with the [model] extra) — the single Case/CaseSet type black-box runners such as case-harness load, validate and hash

pip install spec-case          # markers + specgen only, zero deps
pip install 'spec-case[model]' # + canonical Case model (pydantic, pyyaml)

Status

Early WIP. The case model and vocabulary are standard test/eval terms; the symbol-id binding is the new piece this project owns.