Use this file to define the project-specific evidence contract for a real pack. The reusable default is the shape of the contract below; the actual authorities and routing always come from the project owner.
Purpose
This brief answers four questions for the project:
- What source material is authoritative?
- What material is only informative or orientation-only?
- What evidence shapes are acceptable for normative claims?
- Where should a drafter look first for each major section or topic?
references.md stays the pack's curated reference pool. This file explains why a source counts as authority and where evidence should be routed.
Authoritative sources
Record the surfaces that actually govern the document content.
| Source surface | Role in the pack | Notes |
|---|---|---|
[replace: primary specification corpus or standards text] |
Primary authority | [replace: why it governs] |
[replace: reference implementation repo / module / code path] |
Primary or corroborating authority | [replace: when implementation wins or when it only confirms] |
[replace: protocol traces / observed bytes / fixtures / exported artifacts] |
Ground-truth evidence | [replace: what it proves] |
[replace: secondary implementation or validation tooling] |
Additional authority or corroboration | [replace: where it is weaker or stronger] |
Authority rule when sources disagree
[replace: explicit rule such as "implemented behavior wins over lagging prose" or "the standards corpus wins over convenience tooling output"]
If there is any hierarchy within the authoritative sources, spell it out here instead of forcing a later drafter to guess.
Informative sources
These materials help orientation, history, or explanation but should not silently override the authoritative corpus.
[replace: design notes, wiki pages, architecture docs, historical drafts, issue threads, blog posts][replace: explanatory papers, vendor docs, internal notes, presentations]
For each informative source family, note whether it is likely to lag the implementation or canonical specification.
Claim basis and acceptable evidence shapes
Normative claims in the project should resolve to one or more of these evidence forms:
- file:function, section anchor, standards clause, or API definition
- observed byte sequence, packet capture, exported artifact, or sample repository object
- concrete command or validation tool invocation plus the verdict it demonstrates
- rendered public example that was re-validated from rendered text
Non-authoritative material can help locate evidence, but it is not the final claim basis.
Runtime, observed-output, or fixture surfaces
List the concrete places where a drafter or reviewer can inspect live behavior.
[replace: CLI or API used to inspect raw artifacts or payloads][replace: capture repository, fixture directory, packet dump, or sample export][replace: validation tool or parser used to confirm edge cases][replace: cautions about chatty commands, blocking stdin, network dependence, or transient output]
Section-to-source routing
Fill in this table so a reader knows where to look first instead of searching the whole project.
| Draft section or topic | Read here first | Why |
|---|---|---|
| Introduction / orientation | [replace: canonical source for project purpose and scope] |
[replace: reason] |
| Terminology / model | [replace: canonical source] |
[replace: reason] |
| Protocol / format / data-model core | [replace: canonical source] |
[replace: reason] |
| Validation / error handling | [replace: canonical source] |
[replace: reason] |
| Examples / observed behavior | [replace: canonical source] |
[replace: reason] |
| Security or operational considerations | [replace: canonical source] |
[replace: reason] |
Boundaries and exclusions
This corpus brief should explicitly exclude material that is easy to confuse with authority.
- environment bootstrap commands
- local build or packaging recipes
- harness-specific controller behavior
- speculative notes or future design ideas not yet implemented or standardized
[replace: any project-specific non-authoritative source family that is easy to over-trust]
Maintenance rule
When a copied excerpt, exported bundle, or local staged note under references/ becomes the only place where an important conclusion is recorded, promote that conclusion into this file or references.md. The canonical pack docs, not the staged support files, must carry the lasting project decisions.