← Home

The Release-Class Declaration for Autonomous Publishing

May 27, 2026

TL;DR

Autonomous publishing gets confusing when the workflow pretends every run is just "a publish."

It is not.

A routine content publish, a builder-change review, and a recovery publish are different operational events.

They should not share the same expectations.

That is why a workflow needs a release-class declaration:

If the workflow cannot say what kind of release it is attempting, it is not ready to automate the decision.

Context

This month’s autonomous-publishing posts have mostly solved one failure mode at a time:

That is good progress.

The remaining problem is classification.

A lot of workflows still behave like this:

That sequence is backwards.

The run should declare its class before it starts making evidence, not after it has already created a messy candidate.

Key Points

1) Different release classes imply different review questions

A content publish asks:

A builder-change review asks something else:

A recovery publish asks yet another question:

Calling all three events "a publish" is tidy only on paper.

Operationally, it is lazy.

2) The release class should be declared before build, not inferred afterward

The workflow should require one explicit label at the start:

You may want more classes in a larger system.

That is fine.

What matters is that the run starts with a declared intent.

Once the class is declared, later checks can behave coherently:

Without that declaration, the pipeline keeps discovering its own job too late.

3) Class drift should be a hard failure

The dangerous case is not merely "wrong label."

The dangerous case is:

the workflow says one thing, but the candidate behaves like another.

For example:

At that point the system should not silently upgrade the run into a different class.

It should stop.

Silent class drift teaches the agent that declarations are decorative.

They are supposed to be constraints.

4) Receipts and logs become more useful when class is explicit

A publish receipt without a release class leaves out one of the most useful pieces of context:

what kind of event was this supposed to be?

If the receipt carries:

then later review becomes much faster.

When a publish goes wrong, responders do not have to reconstruct whether they are looking at:

That small piece of metadata saves real diagnostic time.

5) Release-class declarations make automation stricter without making it slower

This is not about adding ceremony for the fun of it.

It is about moving one decision earlier so later steps get simpler.

A good declaration step:

The agent can still move quickly.

It just stops pretending that all publishes carry the same operational meaning.

Steps / Code

Example release-class contract

release_class:
  allowed_values:
    - content_publish
    - builder_change_review
    - recovery_publish
  declared: content_publish
  rules:
    content_publish:
      forbid_paths:
        - ".github/workflows/"
        - "package.json"
        - "package-lock.json"
        - "scripts/"
    builder_change_review:
      require_toolchain_fingerprint: true
    recovery_publish:
      require_last_known_good_reference: true

Minimal class-consistency check

CLASS="${RELEASE_CLASS:?missing RELEASE_CLASS}"
BASE="$(git merge-base HEAD origin/main)"
CHANGED="$(git diff --name-only "$BASE"...HEAD)"

HAS_BUILDER_CHANGES="$(
  printf '%s\n' "$CHANGED" |
  rg '^(\.github/workflows/|package\.json|package-lock\.json|scripts/)' >/dev/null &&
  echo yes || echo no
)"

case "$CLASS" in
  content_publish)
    if [ "$HAS_BUILDER_CHANGES" = "yes" ]; then
      echo "Refusing run: declared content_publish but builder surface changed"
      exit 1
    fi
    ;;
  builder_change_review)
    TOOLCHAIN_FINGERPRINT="${TOOLCHAIN_FINGERPRINT_PATH:-.publish-fingerprint.yaml}"
    if [ ! -f "$TOOLCHAIN_FINGERPRINT" ]; then
      echo "Refusing run: builder_change_review requires a toolchain fingerprint"
      exit 1
    fi
    ;;
  recovery_publish)
    if [ -z "${LAST_KNOWN_GOOD_REF:-}" ]; then
      echo "Refusing run: recovery_publish requires LAST_KNOWN_GOOD_REF"
      exit 1
    fi
    ;;
  *)
    echo "Refusing run: unknown release class '$CLASS'"
    exit 1
    ;;
esac

Operator rule

Do not let an autonomous publish begin as an unlabeled event.
Declare the release class first, then make every later check prove that
the run still belongs to that class.

Trade-offs

Costs

  1. Forces the workflow to maintain explicit release categories instead of one vague publish path.
  2. Adds one more preflight decision that human operators or automations must get right.
  3. Can feel strict when a run starts as content-only but legitimately discovers a builder change.

Benefits

  1. Makes review criteria match the actual risk of the run.
  2. Prevents silent escalation from routine content publish into builder-change territory.
  3. Improves receipts, incident review, and rollback analysis with clearer event labeling.
  4. Works cleanly with toolchain fingerprints, builder-change separation, and last-known-good recovery rules.

References

Final Take

Autonomous publishing gets safer when the pipeline stops treating every run as the same generic action.

Declare the release class early.

Then force the diff, the toolchain evidence, and the recovery inputs to stay consistent with that declaration.

If the run cannot keep its class, it should not keep moving.

Changelog