Skip to content

Governance, workflow tags, and the prerelease shape - #1

Merged
lessevv merged 3 commits into
mainfrom
chore/ai-is-just-a-tool
Jul 27, 2026
Merged

Governance, workflow tags, and the prerelease shape#1
lessevv merged 3 commits into
mainfrom
chore/ai-is-just-a-tool

Conversation

@lessevv

@lessevv lessevv commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Three related changes to the rules the organisation enforces, ahead of the
product repository adopting them.

AI disclosure is dropped

An AI is a tool. A pull request is judged on whether it satisfies the
requirement it cites, passes the gates, and is code somebody can maintain —
none of which is a fact about what produced it. The rule was also
unenforceable, so the field it produced meant nothing either way.

GOV-R24 is removed and the two identifiers after it are renumbered. That
contradicts GOV-R8/GOV-R10, which say identifiers are never renumbered —
a deliberate one-off, taken while nothing outside this repository cited them,
and not a precedent.

Shared workflows move to a major-version tag

ADR-0012 said first-party reusables are called on @main. The organisation
never did it: this repository and the website pinned to commits while the
product repository used @main. Three repositories, two behaviours, and a rule
contradicted in the tree.

ADR-0021 records the resolution and supersedes only ADR-0012's second rule —
full-SHA pinning for third-party actions is untouched. v1 moves forward as
fixes merge, so propagation is unchanged; a breaking change to a calling
interface cuts v2 so consumers migrate deliberately. Every move is also an
immutable v1.x.y tag.

This is not the mutable-tag attack ADR-0012 warned about, and the record says
why rather than assuming it: there the tag mover is a third party; here it is
this protected repository, and anyone who can move v1 can already push to
main, which @main would have executed anyway.

Any prerelease identifier is a preview tag

The tag table named two shapes while the pipeline has always keyed on a hyphen
anywhere in the ref name. -beta and -develop already worked; the
specification described a narrower system than the one that exists. Widened,
because a snapshot off the integration branch is a legitimate preview and
making it call itself a release candidate would make the label lie.

ADR-0019 is untouched — its decision is unchanged, only its examples were
narrow.

After merge

This PR must merge and be tagged before the beatrax and website PRs can go
green
— their callers already reference @v1.

git tag -s v1.0.0 -m "shared workflows v1.0.0"
git tag -s v1     -m "shared workflows v1 → v1.0.0"
git push origin v1.0.0 && git push origin v1

spec integrity: clean.

lessevv added 3 commits July 27, 2026 19:55
An AI is a tool. A pull request is judged on whether it satisfies the
requirement it cites, passes the gates, and is code somebody can
maintain — none of which is a fact about what produced it.

A disclosure rule also implies the code needs a different kind of
scrutiny because of its provenance, which is the wrong signal to send
about the scrutiny everything else gets. And it was unenforceable:
obeyed by the careful, ignored by everyone else, leaving a field
reviewers could not trust either way. Review is there for a reason.

The remaining rules on the page are the ones that were never about
disclosure — you are the author, the judgment rules bind identically,
no invented citations, no invented facts, no secrets — and they are
renumbered to close the gap.

Signed-off-by: Wessel Verheij <info@nightworks.io>
ADR-0012 said first-party reusables are called on @main. The org never
did it: this repo and the website pinned them to commits, deliberately,
while the product repo's callers used @main. Three repos, two behaviours,
and a rule contradicted in the tree — which teaches contributors the
specification describes intentions rather than facts.

Both positions were right about something. @main is right that a shared
fix should propagate in one merge rather than needing a bump in every
consumer. Pinning is right that @main lets a change to this repo's
default branch reach every sibling's merge gate immediately, with no
mechanism for a breaking one.

A moving major tag keeps both. v1 moves forward as fixes merge, so
propagation is unchanged; a breaking change to a calling interface cuts
v2, so consumers migrate one at a time instead of failing at once. Every
move is also an immutable v1.x.y tag, so what v1 pointed at on a given
day stays recoverable.

This is not the mutable-tag risk ADR-0012 warned about, and the new
record says why rather than assuming it: there the tag mover is a
third party, here it is this protected repository. Anyone who can move
v1 can already push to main, which @main would have executed anyway.

ADR-0021 records it and supersedes ADR-0012's second rule; the first,
full-SHA pinning for third-party actions, is untouched. REPO-R7 and the
two quality pages that restated the old rule are brought in line, and
cross-repo-ci.md now states what breaks a workflow contract and how to
move the tag.

Signed-off-by: Wessel Verheij <info@nightworks.io>
The tag table named exactly two shapes, vX.Y.Z and vX.Y.Z-rc.N, while
the pipeline has always keyed on something broader: a hyphen anywhere in
the ref name. So -beta and -develop already worked and were already
correct, and the specification described a narrower system than the one
that exists.

Widened rather than narrowed, because the broader behaviour is the one
worth having: a snapshot off the integration branch is a legitimate
preview, and forcing it to call itself a release candidate would make
the label lie.

The identifier now carries no meaning to the pipeline and says so — it
is for the humans reading the release list. REPO-R31, OPS-R4 and the
pipeline diagram move from "release candidate" to "prerelease tag" to
match, and the staged-versus-releasable rule the preview channel depends
on is stated here rather than left to staging.md alone.

ADR-0019 is untouched: its decision — stable drafts, previews publish
immediately — is unchanged, and only its examples were narrow.

Signed-off-by: Wessel Verheij <info@nightworks.io>
@github-actions github-actions Bot added documentation Docs only ci Pipelines, workflows, and release engineering governance The rules of change architecture operations labels Jul 27, 2026
@lessevv
lessevv merged commit bdb371a into main Jul 27, 2026
12 checks passed
@lessevv
lessevv deleted the chore/ai-is-just-a-tool branch July 27, 2026 18:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

architecture ci Pipelines, workflows, and release engineering documentation Docs only governance The rules of change operations

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant