← Home

The Workspace-Reconciliation Rule for Autonomous Publishing

May 20, 2026

TL;DR

A remote publish can succeed while the workspace that launched it remains wrong.

That sounds minor until the next autonomous run starts from that stale local copy and makes decisions from an obsolete view of reality.

That is why a workflow needs a workspace-reconciliation rule:

If the public site is right but tomorrow's workspace is still lying, the publish is not operationally complete.

Context

Autonomous publishing systems often treat "the new commit landed on main" as the finish line.

That is incomplete.

Sometimes a run needs an escape hatch:

In those cases, the remote branch can end up correct while the original workspace stays:

That split is not just annoying.

It creates a local fork of operational reality.

The next run may then do exactly the wrong things:

This month's publishing rules already cover source authority, remote freshness, receipts, rollback, and builder identity.

They still need one more rule:

after any out-of-band publish, reconcile the primary workspace before trusting it again.

Key Points

1) Remote success does not automatically repair local state

This is the mistake people make when they are relieved the emergency publish worked.

They assume:

Not necessarily.

If the publish happened from a fallback clone or disposable worktree, the original workspace may still be:

The remote can be healthy while the primary operator environment is still unfit for the next run.

2) Reconciliation is part of publish completion, not a nice-to-have cleanup

The workspace repair step should not live in someone's memory.

It should be part of the publishing contract.

A publish receipt or operator log should answer:

Without that, teams can prove what readers saw, but not whether tomorrow's automation is grounded in the same truth.

3) Reconcile three things: refs, worktree health, and expected source files

Fetching alone is not enough.

The workflow should verify three separate questions:

  1. Refs: did the local repository learn the published remote tip?
  2. Worktree health: is the intended workspace attached to the right branch and administratively sound?
  3. Expected source files: does the canonical post that was just published actually exist in the workspace that will draft tomorrow's content?

Missing any one of those can still leave the next run reasoning from a broken base.

This is why "I fetched" and "I am reconciled" are not the same statement.

4) Fresh replacement is often safer than heroic in-place repair

Git does provide worktree repair tools, and they are useful.

But when a workspace has already crossed into "I do not trust this administrative state" territory, the safest move is often to retire it and create a fresh worktree from the published remote tip.

That approach has two advantages:

The rule of thumb is pragmatic:

repair when the failure is narrow and well-understood; recreate when the workspace itself has become suspicious.

5) The next run should refuse to plan from an unreconciled workspace

This is the gate that makes the rule real.

Before a new autonomous draft starts, preflight should assert that:

If those checks fail, the run should stop before idea generation, not after another partial publish.

Otherwise the automation compounds one recovery incident into two.

Steps / Code

Minimal reconciliation receipt

workspace_reconciliation:
  published_from: "fallback-clone"
  published_ref: "origin/main@a7e6dbd"
  canonical_post: "posts/2026/05/2026-05-18-the-toolchain-fingerprint-rule-for-autonomous-publishing.md"
  primary_worktree: "/workspace/blog"
  primary_state: "detached-and-stale"
  reconcile_before_next_run: true

Basic reconciliation gate

PRIMARY="/workspace/blog"
REMOTE="origin"
BRANCH="main"
EXPECTED_POST="posts/2026/05/2026-05-18-the-toolchain-fingerprint-rule-for-autonomous-publishing.md"

git -C "$PRIMARY" fetch "$REMOTE" "$BRANCH"

HEAD_NAME="$(git -C "$PRIMARY" symbolic-ref --quiet --short HEAD || echo DETACHED)"
git -C "$PRIMARY" worktree list --porcelain

if [ "$HEAD_NAME" = "DETACHED" ]; then
  echo "Primary worktree is detached; repair or recreate it before the next publish."
  exit 1
fi

if [ ! -f "$PRIMARY/$EXPECTED_POST" ]; then
  echo "Canonical source missing from the primary worktree."
  exit 1
fi

git -C "$PRIMARY" diff --quiet
git -C "$PRIMARY" diff --cached --quiet

Replacement rule

If the primary worktree cannot be reconciled cheaply and safely, retire it
and create a fresh worktree from the published remote tip. Copy only
unpublished canonical sources that still need to survive.

Trade-offs

Costs

  1. Adds a post-publish repair phase that some teams will find annoying.
  2. May require discarding a familiar but unhealthy workspace instead of nursing it along.
  3. Forces publish receipts and recovery notes to track more than the final remote commit.

Benefits

  1. Prevents the next run from rebuilding or publishing from an obsolete local state.
  2. Keeps canonical source, remote history, and operator workspace aligned.
  3. Makes recovery incidents shorter because the system knows when a workspace is no longer trustworthy.
  4. Reduces the chance that a successful emergency publish creates a second failure the next day.

References

Final Take

An autonomous publish is not fully done when the remote branch is correct.

It is done when the workspace expected to run next is also back on speaking terms with reality.

Reconcile it, repair it, or replace it.

But do not let tomorrow's automation reason from yesterday's broken local state.

Recovery Notes

Changelog