Add an optional branch_evidence field to posture-claims

Andrew Dunnrequested to merge
standards/posture-claims-branch-evidence into main

Standard

posture-claims

Change type

  • Add new standard
  • Modify existing standard (prose only)
  • Modify existing standard's check.sh (add, remove, or change an assertion)
  • Modify existing standard's templates
  • Status transition: introduced -> enforcing
  • Status transition: enforcing -> archived
  • Retire / archive

What does this MR do and why?

I want a claim to name what a branch pipeline checks, because a branch pipeline builds no release and a release-file claim fails there every time.

  • A claim may carry branch_evidence:, shaped like evidence:, which the verifier reads when $CI_COMMIT_TAG is unset.
  • A claim without it reports SKIP. Checking evidence: there fails predictably, and an advisory job that always warns gets ignored.
  • GitLab sets expiry per job, so the template splits into a tag job keeping its report forever, for the release link, and a branch job, on merge requests and default-branch pushes, keeping it a week.
  • The script keys on $CI_COMMIT_TAG. Keyed on $CI_COMMIT_BRANCH, which a merge request pipeline leaves unset, it would read evidence: there.
  • The template installs gettext-envsubst, without which every evidence URL expanded to an empty string.
flowchart LR
  A["claim"] --> B{"CI_COMMIT_TAG set?"}
  B -->|yes| C["EVIDENCE_URL from evidence:"]
  B -->|no| D{"branch_evidence: present?"}
  D -->|no| S["SKIP"]
  D -->|yes| E["EVIDENCE_URL from branch_evidence:"]
  C --> V["run verify:, PASS or FAIL"]
  E --> V

Failure mode this addresses

periscope's branch job passes all four claims on main with this field. Its earlier single job kept every report forever.

Assertion deltas

None. check.sh asserts the four keys and ignores any other.

Consumer impact

periscope still passes just check-one STANDARD=posture-claims. One private project has a claims file but no verifier job.

Status transition

None.

Test plan

  • just guard passes (assertions use only closed primitives)
  • just check-one STANDARD=<name> passes against this repo
  • Ran check.sh against at least one consumer repo of each applicable shape (binary-shipping, lab); results match expectations
  • CHANGELOG updated

just ship reports 21 standard(s) passed, 0 exempt, 0 failed. CI lint accepts the template once stages: lists verify. A since-deleted GitLab.com project ran it in branch and tag pipelines: URLs expanded, the branch run wrote SKIP, and reports expire in a week and never.

Reviewer checklist

  • SKILL.md frontmatter is valid YAML (name, description, status, [enforced_since])
  • check.sh sources ../../_lib.sh correctly
  • check.sh calls report at the end
  • Templates/ directory present where applicable
  • Standard appears in README's contracts table
  • Standard appears in the rendered site's /standards/ index

An AI tool wrote this change and ran the checks above.

Merge request reports