Imported from metacraft-labs/test-certificates-spec (
AGENTS.md). Install upstream withnpx skills add metacraft-labs/test-certificates-spec. Copyright stays with the author.
AGENTS.md
This repository is the Test Certificate Standard: a vendor-neutral contract specification and its conformance suite. It holds no implementation. Producers and verifiers live in the projects that adopt the standard.
Repository class and branches
- A contract specification repository. Its mainline is
latest, and changes land on it by a fast-forward push. There are no feature branches and no pull requests. - It is public. Commit messages, file content and links must never name or cite private repositories, private plans or milestones, internal issue ids, internal infrastructure, operators or people's decisions, or local paths. Write for an outside implementer: state the rule and the reason for it, not the internal history that led to it.
- Plans and milestones for this standard are not kept here. A document whose work is unfinished says so in its own status line, without linking to a plan.
Layout
| Path | Contents |
|---|---|
Standard.md, Content-Id.md, Canonical-Payload.md, Verification.md, Transport.md |
The normative specification. |
Tooling.md |
The non-normative reference helper tool (implemented in a separate repository). |
Conformance.md |
What the conformance suite contains, and the rules for maintaining it. |
vectors/ |
The suite: plain data, no runner. vectors/README.md is the directory contract. Byte-exact; .gitattributes marks it -text. |
vectors/signature/keys/ |
Deliberately published, worthless test keys. Never use them for anything else. |
tools/ |
Non-normative authoring and checking tools (Python 3.11+, POSIX shell, jq, ssh-keygen, git, sha256sum). |
Checks
Run all of these before pushing any change to the prose or the vectors:
python3 tools/check.py # reference checks, all groups
python3 tools/regenerate.py --check # signatures and index are current
sh tools/walk-vectors.sh # language-agnostic walk
sh tools/corruption-demo.sh # the suite detects its own corruptionRules that are easy to break
- A vector is never edited to match an implementation. Deciding which of the two is wrong is what the vector is for (Conformance.md).
- Prose and vectors change together. A clarification of a normative rule
arrives with the vector that pins it, and a resolved ambiguity is recorded
in
vectors/README.md. - Expected bytes are derived by hand, then checked against the tools in
tools/, never generated by them. - Never let an editor or a checkout rewrite line endings or whitespace under
vectors/; a single changed byte invalidates signatures.
