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:

  1. No second consumer yet. Several of these standards codify a pattern that exists in exactly one Public Sector project today. patches-dir ships at kaniko; posture-claims ships 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.
  2. 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.
  3. Downstream MRs land separately. The pipeline/release-create catalog component (for release), the pipeline/posture-verify catalog component (for posture-claims), the kaniko conformance MR (for patches-dir), the per-project templates lift (for templates-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:

  • release is sister to changelog (a CHANGELOG anchor link is one of the three required release assets) and to provenance (which appends signature, SBOM, and SLSA assets to the release page).
  • templates-gitlab is sister to repository (on-disk shape) and codeowners (routing layer).
  • posture-claims is sister to provenance (which owns the artifacts the claims point at) and posture (the controls matrix that names the canonical claim vocabulary).
  • workflow-rules is sister to pipeline (catalog include conventions for the rest of .gitlab-ci.yml).
  • examples-dir is sister to repository (additive directory when applicable).
  • patches-dir is sister to provenance (chain-of-custody for the divergence point) and cross-refs posture-claims (a downstream-patches claim) and release (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.yml carries the three workflow rules.
  • No assertion that .gitlab/posture-claims.yaml exists 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 guard passes locally
  • make check passes locally (self-conformance; no new assertions in this MR so behavior unchanged)
  • make build && make agent succeeds (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: introduced with no enforced_since: field
  • Templates under standards/<name>/templates/ follow the shape of existing templates/ directories (placeholders, not real values)
  • Applicability gates on examples-dir and patches-dir read clearly (not universal)
  • Cross-references between new standards and existing ones (provenance, posture, repository, codeowners, changelog, pipeline) resolve to real anchors

Merge request reports

Loading