reference

reference is the conformance contract for the projects under GitLab Public Sector’s gitlab-com/public-sector/ group. It holds a registered set of standards, a shared design system and a compliance matrix, published once as web pages and once as Markdown at a single URL. manifold, bulkhead and egress each carry a .reference.yaml naming the reference version they conform to.

A standard is one engineering decision as a directory: SKILL.md carries the prose and the front matter, check.sh carries the assertions, and templates/ carries files a project can lift and fill in. standards/registry.yaml orders the standards into two groups, and the group is read off the check rather than chosen: a check.sh that opens with a precondition gate is Conditional and skips a tree that does not meet it; one with no gate is Mandatory and runs everywhere.

• Three source directories feed one build: standards, design and compliance.
• just ship gates the build and emits human pages and a Markdown agent surface.
• A consumer project runs just check against the same checkout.
• Each assertion reads PASS, FAIL, ADVISE, SKIP or EXEMPT.

Every check.sh is written in a closed set of shell functions exported from _lib.sh: a file exists or is absent, contains or lacks a pattern, a JSON key holds a value, a GitLab project setting reads as expected, an XML file parses, plus the two precondition gates. scripts/guard-checks.sh parses every check and rejects any leading token outside that set. just check REPO=<path> runs every standard against a checkout and prints one line per assertion. A project’s .reference.yaml is one required value, the reference version, plus an exemptions list, and an entry there says the standard does not apply to this project, with the reason. Nothing in the reference runs the check against a consumer’s merge request; the project that wires the job into its own pipeline decides whether a FAIL blocks.

Severity and lifecycle are two separate axes. Tier is declared in the check and set per standard, not per assertion: a blocking standard’s tripped assertion exits non-zero, an advisory standard’s prints ADVISE and exits zero. Tier follows control backing: a standard some control in compliance/unified.yaml names blocks, and one no control names advises. Status (introduced, enforcing, archived) is lifecycle position in front matter, and no script reads it.

The site is Astro. An integration at the end of the build converts each page’s main column to Markdown and emits /llms.txt, /llms-full.txt, and each standard’s SKILL.md, check.sh and templates at stable paths. just ship is the pre-deploy gate and stops at the first failure: guard, the registry and matrix validators, the reference checked against its own standards, the build, then a check that the emitted agent surface is complete. The design system under design/ is CSS tokens, page chrome and two small scripts, linked from the Pages site or vendored into a repository with no route out. The compliance matrix is one file, a row per engineering decision citing the frameworks and sectors in compliance/registry.yaml.

The reference ships documentation and a static site and no binaries, so its own trust-manifest and provenance checks skip on their precondition rather than by declaration. Live audits of consumer releases belong to the GitLab Compliance product, not to this repository.

---