Skip to content
DHF Engineering Notes

Governing compaction & deployment.

A first-principles account of how durable state, fail-closed transitions, version direction, and executable documentation keep long-running agentic systems recoverable.

First principles

Why compaction becomes control flow

The policy follows from four axioms. It does not assume that an agent can reliably judge its own remaining context or reconstruct detail after it has been compressed.

1 · Context is finite

Long-running work eventually exceeds the active reasoning window, even when the task itself is healthy.

2 · Compression is lossy

A summary can preserve intent while dropping exact constraints, provenance, or the state of an in-flight step.

3 · The host observes the boundary

The environment, not the agent's confidence, is the authoritative observer of a confirmed compaction event.

4 · Continuity must be durable

Anchors, evidence, and the next safe task must survive outside conversational memory, with one successor per boundary.

Derived rule: after a second confirmed boundary, succession is mandatory. A session may finish only its current in-flight step when a fidelity gate proves five prerequisites: the repository and work mode are exact and still match; the active step is reconstructible; its constraints are durable; its verification evidence is recoverable; and the boundary count is trustworthy. Any unknown fails closed. A third confirmed boundary forces immediate succession.
Transition matrix

Six verdicts, one direction

Every deployment compares the running version, the requested version, and the freshly observed published tip. The result is a finite verdict, never a best guess.

Deployment transition matrix SAME + CURRENTNo-opNothing is rewritten. SAME + PUBLISHED TIP MOVEDStop as staleA lagging view is not a no-op. NEWER + PUBLISHEDMove forwardDeploy, verify, then record. OLDER + EXPLICIT APPROVALNamed rollbackOnly a present operator may approve it. PUBLISHED TIP CHANGES MID-CHECKStop or reconcileNever publish from an unstable read. MISSING / DIVERGED / UNKNOWNFail closedThere is no normal or forced fallback. older / uncertainnewer / verifiedThe default path advances only toward a freshly observed, published version.
Direction is a property of the deployment relationship, not an operator's intention. Unknown ancestry or unstable observations stop the transition.
Sanitized incident review

How an outdated scheduled task overwrote a newer runtime

The lesson was not “be more careful.” It was to remove the unsafe transition from the system and make unattended automation read-only.

Incident remediation timelineNew runtime activeimprovement not yet publishedScheduled overwriteold source copied without comparisonDrift detectedruntime restored and automation stoppedWithin 24 hoursstructural safeguards in place
Root cause had two halves: the newer change had not reached the published source, and unattended synchronization copied without checking version direction.

Layer 1 · Version guard

Every transition compares versions and accepts only a current no-op, a verified forward move, or a separately approved rollback.

Layer 2 · Recoverable backups

Files displaced by a deployment are retained, so recovery does not depend on recreating the previous runtime from memory.

Layer 3 · Report-only automation

Scheduled checks may observe and report drift. They cannot repair, synchronize, publish, or change the live environment.

Operational boundary

A human remains responsible for publishing, approving a rollback, restoring state, and accepting post-deployment evidence.

Documentation as code

Policy text is protected by contract tests

When prose governs behavior, wording, links, and cross-language alignment become interfaces. A casual edit can be a policy regression even when the page still looks correct.

Lock the public contract

  • Required status markers and truth-boundary phrases remain literal.
  • Canonical links stay language-specific and reachable.
  • Paired pages keep the same structural coverage.
  • A rendered specification retains the source document's heading set.

Test behavior, not decoration

Contract tests protect the policy surface that readers and automation rely on. Visual checks separately cover dark mode, mobile layout, and diagram overflow. Together they make documentation executable without turning prose into an implementation detail.

literal contract + visual verification