← Home

The Candidate-Identity Rule for Autonomous Publishing

Jun 5, 2026

TL;DR

An isolated candidate directory is better than an in-place build.

A promotion manifest is better than a blind rsync --delete.

Neither one fully answers the next operational question:

How do you prove the candidate you reviewed is the exact candidate you promoted?

That is why a workflow needs a candidate-identity rule:

If "the candidate" does not have a concrete identity, the workflow is still relying on narration where it should rely on evidence.

Context

This week’s autonomous-publishing series tightened the publish path in a useful order:

Good.

That sequence fixes a lot of ambiguity.

It still leaves one quiet failure mode:

the workflow can review one candidate and promote a slightly different one.

That can happen in more ways than teams like to admit:

Intent is not the point.

If the reviewed artifact set and the promoted artifact set are not provably the same object, the workflow has a trust gap.

The candidate directory gave the run a place.

The promotion manifest gave it a file-level plan.

The missing piece is an identity that survives review and promotion.

Key Points

1) A candidate needs an identity, not just a path

/tmp/candidate-1234 is a location.

It is not a durable claim about contents.

A trustworthy workflow needs something stronger:

Without that, review language becomes fuzzy:

Maybe.

Those statements are only as strong as the workflow’s ability to prove that the candidate stayed identical across those steps.

2) Review artifacts should bind to candidate identity explicitly

The promotion manifest should not float free as a generic text file.

It should say which candidate it describes.

The same applies to:

Otherwise later responders have to reconstruct whether:

A candidate-identity rule removes that ambiguity by requiring every important artifact to point at the same candidate fingerprint.

3) Promotion should fail on identity drift, not explain it away later

This is a pre-promotion control.

Right before promotion, the workflow should recompute the candidate fingerprint and compare it to the reviewed value.

If the identity drifted, stop.

Do not:

That is exactly how "minor" build drift turns into unreviewed public output.

When the candidate changes, the review scope changes.

The correct response is to re-run the review path against the new candidate, not to pretend continuity where none exists.

4) Identity makes rebuilds and retries easier to reason about

Autonomous publishing systems retry things.

They rebuild after background commits drain.

They replay after remote movement.

They rerun on another machine after a flaky failure.

That is normal.

What matters is whether the system can answer:

Did the retry reproduce the same candidate, or did it create a new one?

Candidate identity turns that into an evidence question instead of an argument.

If the fingerprint matches, you can say the artifact set stayed stable.

If it does not, treat the retry as a new candidate that deserves its own manifest, review, and receipt trail.

5) Candidate identity strengthens the rest of the publish record

This rule does not replace candidate directories, manifests, or receipts.

It makes them tighter.

Once identity is explicit, a good publish record can say:

That is the difference between "the workflow probably shipped the reviewed build" and "the workflow can prove which artifact set it shipped."

That is a real operational upgrade.

Steps / Code

Example candidate-identity record

candidate_identity:
  candidate_ref: "candidate-2026-06-05T09-10-00Z"
  source_ref: "origin/main@ce2d4d8"
  toolchain_fingerprint: "node-24.1.0-npm-11.3.0-lock-8f4d..."
  content_hash: "sha256:9d6d9f0f6f9f4c2f6b6f..."
  file_count: 143

Stable content hash over a candidate directory

CANDIDATE_DIR="${CANDIDATE_DIR:?missing CANDIDATE_DIR}"

candidate_hash() {
  (
    cd "$CANDIDATE_DIR" || exit 1
    find . -type f -print0 \
      | sort -z \
      | xargs -0 shasum -a 256 \
      | shasum -a 256 \
      | awk '{print $1}'
  )
}

REVIEWED_HASH="$(candidate_hash)"
printf '%s\n' "$REVIEWED_HASH"

Refuse promotion if identity drifted

CURRENT_HASH="$(candidate_hash)"

if [ "$CURRENT_HASH" != "$REVIEWED_HASH" ]; then
  echo "Refusing promotion: candidate identity drifted"
  echo "Reviewed:  $REVIEWED_HASH"
  echo "Current:   $CURRENT_HASH"
  exit 1
fi

Operator rule

Do not promote a candidate because it still has the same directory name.
Promote it only if its reviewed identity still matches the artifact set on disk.

Trade-offs

Costs

  1. Adds hashing and artifact bookkeeping to a workflow that might have previously relied on simpler path-based checks.
  2. Forces the team to define which files and normalization rules belong in candidate identity.
  3. Can trigger full re-review on changes that feel small but still alter the published artifact set.

Benefits

  1. Prevents a reviewed candidate from quietly turning into a different promoted candidate.
  2. Makes retries, rebuilds, and cross-run comparisons easier to classify as same artifact versus new artifact.
  3. Tightens promotion manifests, receipts, and incident review by giving them a shared immutable reference.
  4. Turns "we think this was the same build" into something the workflow can actually prove.

References

Final Take

Candidate directories solved "where did we build."

Promotion manifests solved "what will we replace."

The next question is simpler and stricter:

is the thing we are about to promote still the same thing we reviewed?

If the workflow cannot answer that with an identity check instead of a story, it is still leaving room for unreviewed drift.

That is the candidate-identity rule.

Changelog