feat(standards): introduce six new standards (release, templates-gitlab, posture-claims, workflow-rules, examples-dir, patches-dir)
What does this MR do and why?
Introduce six new reference standards at status: introduced. Each is an advisory signal — the convention is written down so a human or LLM grepping standards/ for a topic finds it. None of the six carry a check.sh in this MR; enforcement is opt-in via separate downstream MRs once each standard has at least two consumer implementations.
The goal is discoverability, not enforcement. The estate has at least one project (kaniko) and at least one half-shipped pattern (the v0.1 posture evidence loop) where the convention exists but is not written down anywhere in the reference. This MR closes that gap.
What each standard introduces
| Standard | Rule, in one sentence |
|---|---|
release |
Every public release is created by pipeline/release-create on a tag pipeline, with an annotated tag whose body is the release notes verbatim and a release page that links the artifact, the docs, and the CHANGELOG anchor. |
templates-gitlab |
Every project ships .gitlab/issue_templates/{Default.md,Bug.md} and .gitlab/merge_request_templates/Default.md; reference itself ships two extras (Deviation.md, Standard-Proposal.md) because it owns the standards estate. |
posture-claims |
Signed-binary or signed-image projects ship .gitlab/posture-claims.yaml self-declaring supply-chain and crypto-posture claims with per-claim evidence URLs and a runnable verifier, with the report appended to the release notes. |
workflow-rules |
Every .gitlab-ci.yml carries a top-level workflow: block firing on three sources (MR event, default-branch push, tag push) and a default: block with interruptible: true plus a two-attempt retry on infrastructure failures. |
examples-dir |
Build-tooling and CLI projects ship examples/ with consumer-pasteable starter files, one per primary use mode, each independently runnable and referenced from README. Applicability is explicit: not universal. |
patches-dir |
Projects that maintain a downstream patch series against an upstream OCI source ship patches/<series-name>/NNNN-<slug>.patch with per-tag refresh discipline and a build-arg selector; patches/none/ is the empty default. |
Why introduced, not enforcing
The reference's status ladder is introduced -> enforcing -> archived. introduced means the convention exists in writing, can be cited, and consumers SHOULD adopt it; enforcing means the catalog's reference-check component asserts it on every consumer pipeline.
Three reasons to ship at introduced:
- No second consumer yet. Several of these standards codify a pattern that exists in exactly one Public Sector project today.
patches-dirships at kaniko;posture-claimsships at half of one project. Without a second consumer, the bash assertions cannot be tested against real diversity, and an enforcement gate would either pass trivially or fail false-positive on the diversity that does exist. - No check.sh in this MR. Even where two consumers exist, writing the assertion is a separate concern from writing the prose. Splitting the two MRs lets reviewers focus on the convention (this MR) and the assertion (the follow-up) without entangling them.
- Downstream MRs land separately. The
pipeline/release-createcatalog component (forrelease), thepipeline/posture-verifycatalog component (forposture-claims), the kaniko conformance MR (forpatches-dir), the per-project templates lift (fortemplates-gitlab) — each lands in its own MR with its own review. This MR sets the convention; downstream MRs make it real.
Sister-to relationships
The six standards slot into the existing estate as siblings:
releaseis sister tochangelog(a CHANGELOG anchor link is one of the three required release assets) and toprovenance(which appends signature, SBOM, and SLSA assets to the release page).templates-gitlabis sister torepository(on-disk shape) andcodeowners(routing layer).posture-claimsis sister toprovenance(which owns the artifacts the claims point at) andposture(the controls matrix that names the canonical claim vocabulary).workflow-rulesis sister topipeline(catalog include conventions for the rest of.gitlab-ci.yml).examples-diris sister torepository(additive directory when applicable).patches-diris sister toprovenance(chain-of-custody for the divergence point) and cross-refsposture-claims(adownstream-patchesclaim) andrelease(active series in artifact metadata).
What is NOT yet enforced
No check.sh files land in this MR. Specifically:
- No bash assertion that a
.gitlab-ci.ymlcarries the three workflow rules. - No assertion that
.gitlab/posture-claims.yamlexists or that its verifier runs. - No assertion that a project ships the three GitLab templates.
- No assertion that an annotated tag exists on the latest release.
- No assertion that
examples/exists for projects to which the applicability gate applies. - No assertion that
patches/<series-name>/carries the per-patch header.
The closed primitive set in _lib.sh is sufficient to write each of these checks; the deferral is intentional, not technical.
Where downstream MRs land
| Downstream | Where |
|---|---|
pipeline/release-create catalog component |
gitlab-com/public-sector/pipeline, new MR |
pipeline/posture-verify catalog component |
gitlab-com/public-sector/pipeline, new MR |
Kaniko conformance to patches-dir (it already ships the shape; explicit conformance MR formalizes it) |
gitlab-com/public-sector/kaniko, new MR |
| Per-project lift of the GitLab templates | per-project, MR per consumer |
Each standard's check.sh |
this repo, one MR per check (after the standard has two consumers) |
Test plan
-
make guardpasses locally -
make checkpasses locally (self-conformance; no new assertions in this MR so behavior unchanged) -
make build && make agentsucceeds (Astro site picks up the six new standards directories) - Six new directories under
standards/are linked from the rendered site (sidebar plus the standards table) - Vale lints the six new SKILL.md files without findings
Reviewer checklist
- Voice matches the existing estate (terse, customer-readable, no marketing, no decorative essays)
- No em-dashes in customer-facing prose
- No filler words ("comprehensive", "robust", "leverage", "seamless")
- DCO sign-off on every commit;
Co-Authored-By: Claude Opus 4.7 (1M context)trailer present - Each standard's frontmatter is
status: introducedwith noenforced_since:field - Templates under
standards/<name>/templates/follow the shape of existingtemplates/directories (placeholders, not real values) - Applicability gates on
examples-dirandpatches-dirread clearly (not universal) - Cross-references between new standards and existing ones (provenance, posture, repository, codeowners, changelog, pipeline) resolve to real anchors