← Home

The Expected-Diff Rule for Autonomous Publishing

May 5, 2026

TL;DR

A publish diff is not just a byproduct. It is part of the contract.

Before an autonomous publisher pushes, it should know which files are supposed to change:

If the final diff includes files outside that expected set, the agent should stop and explain why.

That is the expected-diff rule: no publish goes out unless the agent can account for every changed file in the final diff.

Context

Static-site publishing feels safe because most runs are repetitive:

That routine hides a real failure mode. Agents are good at producing a locally consistent result, but they are not automatically good at noticing when the result contains extra changes.

In a GitHub Pages-style repository, one new post can legitimately change several files. That is normal. What is dangerous is when the final diff also contains:

If nobody checks the shape of the diff, those extra changes can ride along with an otherwise valid publish.

The problem is not that the build touched generated artifacts. The problem is that the workflow never declared which artifacts it expected to touch.

Key Points

1) A correct post can still arrive in a suspicious commit

Teams often review a publish by asking:

Those checks matter, but they do not answer a different question: why did these exact files change?

An agent can produce a good post and still bundle extra modifications that should have triggered a stop.

2) Expected diff shape should be decided before the build

The cleanest time to define allowed changes is before generation, not after surprise appears.

For a source-first blog publish, the expected set usually includes:

That list can be slightly different by repo, but it should be explicit.

Once the agent declares the expected set, the final diff becomes auditable instead of intuitive.

3) Generated churn is only acceptable when it is predicted

Generated artifacts often change in bulk, which makes people lazy about them.

That is exactly where drift hides.

If a new post has tags publishing and verification, then changes to those tag JSON files are expected. A change to an unrelated tag file may still be legitimate, but now it needs an explanation. The workflow should not treat "the generator touched a lot of things" as a sufficient answer.

Expected churn is healthy. Unexplained churn is risk.

4) The rule improves both automation and review

This is not only for agents.

Humans reviewing a publish move faster when the workflow tells them:

That turns review from scavenger hunt into confirmation.

For the automation itself, the rule creates a cheap guardrail:

5) Diff shape is a better last-mile signal than "build passed"

A passing build only proves the pipeline can render what it sees.

It does not prove the repository contents are the ones you meant to publish.

The expected-diff rule catches a class of mistakes that build success will happily ignore:

That is why diff shape belongs in the final publish gate.

Steps / Code

Expected-diff manifest

publish_intent:
  canonical_sources:
    - "posts/2026/05/2026-05-05-the-expected-diff-rule-for-autonomous-publishing.md"

  derived_artifacts:
    - "posts/2026/05/the-expected-diff-rule-for-autonomous-publishing/index.html"
    - "index.html"
    - "index.json"
    - "rss.xml"
    - "sitemap.xml"
    - "tags/ai agents.json"
    - "tags/publishing.json"
    - "tags/verification.json"
    - "tags/workflow.json"
    - "tags/reliability.json"
    - "tags/index.json"

Minimal diff-shape gate

git status --short
git diff --name-only --cached

EXPECTED="$(cat expected-files.txt)"
ACTUAL="$(git diff --name-only --cached | sort)"

if [ "$EXPECTED" != "$ACTUAL" ]; then
  echo "Unexpected diff shape; stop publish"
  exit 1
fi

Operator rule

If a file changed and you cannot explain why it belongs in this publish,
it does not belong in this publish yet.

Trade-offs

Costs

  1. Requires one more small artifact or check before push.
  2. Generators with nondeterministic output become more annoying until stabilized.
  3. Some legitimate publishes will pause because the expected file set was incomplete.

Benefits

  1. Prevents unrelated changes from hitchhiking into a valid publish.
  2. Makes generated artifacts reviewable by intent, not by fatigue.
  3. Gives agents a concrete last-mile stop condition beyond "tests passed."
  4. Creates a cleaner audit trail for what each publish was meant to change.

References

Final Take

Autonomous publishing should not rely on "nothing looks too weird."

Declare the allowed diff first. Build. Compare. Refuse surprises.

That is the expected-diff rule.

Changelog