standard

Part of HeepX. New here? Start at workspace — what the organization is, why it is shaped this way, and what needs doing. This repository answers only what must a repository contain.

The rules every HeepX repository follows, and the tool that checks them.

HeepX repositories are capabilities: text and evaluation suites that make an AI system measurably better at one thing. Hundreds of them are only useful if they are consistent — same layout, same metadata, same evidence standard, so a consumer can discover, load, and trust any of them without reading each one first.

This repository defines that consistency as HXS-1, and ships conform.py to enforce the mechanizable part of it. A standard nothing checks is a blog post.

Start here

git clone https://github.com/HeepX/standard
python3 standard/conform.py path/to/your/repo

Output is violations by rule ID, exit 1 on any MUST:

HXS-1 conformance: warrant  (type: capability)
rules evaluated: 57

  MUST   DOC-06  README does not link https://github.com/HeepX/standard

Then read SPEC.md — every rule, defined once, with a stable identifier. Everything else in this repository explains or operationalizes it.

To start a new capability repository, copy templates/ and work through CHECKLIST.md.

Layout

SPEC.md                    HXS-1 — every normative rule  ← the single source
conform.py                 mechanizable enforcement, stdlib only, self-tested
CHECKLIST.md               pre-publication checklist for authors
REVIEW.md                  what a human reviewer checks that the tool cannot

NAMING.md                  HXS-NAME    repository names as public API
REPOSITORY_STRUCTURE.md    HXS-LAYOUT  the tree, and why each entry exists
METADATA.md                HXS-META    CAPABILITY.yaml field reference
VERSIONING.md              HXS-VER     semver, deprecation, compatibility
EVALUATION.md              HXS-EVAL    what makes a suite trustworthy
BENCHMARKS.md              HXS-BENCH   comparative claims, honestly made
QUALITY.md                 HXS-DOC / HXS-QUAL  README standard, quality bar
CI.md                      HXS-CI      required checks
SECURITY.md                HXS-SEC     threat model, incl. this repo's own

schema/capability.schema.json   machine-readable CAPABILITY.yaml schema
templates/                      starting files for a new repository

Documents never restate a rule. They reference it by ID (HXS-EVAL-03) and explain why it exists. If a document and SPEC.md disagree, SPEC.md wins.

Evaluate

python3 conform.py --self-check              # the checker's own fixtures
python3 conform.py . --type infrastructure   # this repository against itself

conform.py builds fixture repositories in a temp directory and asserts that each rule fires when violated and stays quiet when satisfied — including that an empty directory produces findings rather than a traceback, since the tool runs against half-built repositories by definition.

Both run in CI, along with a check that every rule ID cited anywhere in this repository exists in SPEC.md. Cross-references cannot silently rot.

What this does not do

• It does not make a repository good. conform.py covers the mechanizable subset — roughly half the rules. Naming something well, scoping one capability, or writing an evaluation that measures the real thing are judgment, which is why conformance requires human sign-off against REVIEW.md and not just a green check.
• It does not parse YAML. CAPABILITY.yaml is read line-wise to stay dependency-free: required keys, value formats, and referenced paths. Full validation is available via schema/capability.schema.json to anyone with a YAML loader.
• It is calibrated against two repositories. HXS-1 was derived from building HeepX/warrant and generalized from it; HeepX/reasoning was then built against the standard and conformed on its first conform.py run without a rule change. That is weak evidence the rules generalize — two repositories by one author, with similar shape — and it is not evidence they generalize to capabilities that look nothing like these. Amendments driven by repositories of a different shape are expected; see CONTRIBUTING.md.
• It has not been tested at scale. No claim is made about how HXS-1 holds up across hundreds of repositories, because that has not happened yet.

Conformant repositories

Repository	Type	Capability
warrant	capability	Naming a claim's warrant before asserting it
reasoning	capability	Naming a commitment's defeater before building on it

License

MIT. Copy it, fork it, derive from it.