Turn engineering standards into agent execution contracts

We had 106 passing tests and an acceptance condition we should not implement.

The brief required an API to refuse an enable request when the caller omitted a manifest hash. Our existing service deliberately supported that omission: it derived the current package hash on the server and recorded that the caller had not presented one. A supplied stale hash was a different case and remained a conflict.

The new UI already had a narrower obligation. If it could not display the package hash, it should not send the configuration request. If it could display one, it should submit exactly that hash.

Those are two legitimate contracts at two boundaries. Treating them as one would have turned a consent requirement for a new UI into an unintended compatibility change for every API caller. The correction preserved the backend contract and requested the missing proof at the UI request boundary.

That is the problem I want engineering standards to solve in an agent system. A rule must retain its source, owner, boundary and decisive evidence as it moves from a product decision into a task, then into implementation, review and release. Otherwise an agent can diligently satisfy the wrong interpretation.

A standard needs an address in the execution graph

“Validate the manifest” sounds like a precise instruction until several components try to implement it. The package builder produces a manifest. The UI displays it. The API accepts a request. The service binds an approval record. A later execution checks whether the approved package still matches the current definition.

Each component has a different observation and a different opportunity to refuse. The UI can know what it showed. The server can know the current package. The execution path can know whether the stored approval is still current. None can replace the others merely by checking the same field name.

Our service makes the API distinction explicit:

if (input.enabled && input.manifestHash !== undefined && input.manifestHash !== pkg.manifestHash)
  throw manifestChanged(pkg.manifestHash, { revision: current.revision });

The omitted value is not treated as a supplied stale value. When approval is recorded, the service uses the server-derived package hash and separately records whether a hash was presented. The later execution path compares the approval hash with the current package again.

I want the task contract to name those behaviors individually. A reviewer should be able to ask what the UI displayed, what it submitted, what the server accepted and what execution revalidated. A broad statement that “hash validation passes” cannot answer that sequence.

This is also why a test count can be accurate and insufficient. The recovery receipt retained 106 passing checks across ten owning files: 29 frontend, 70 backend/manifest/isolation, six HTTP and one browser journey using the actual API and MCP path. That was substantial author evidence. It did not make an incompatible new backend requirement correct.

Preserve the original decision before translating it

Our decision-record mechanism is deliberately more specific than a task description. A record names its owner, creation date, validity window, rollback trigger, protected fixture, chosen tradeoff, decisive probe and probe result. It also lists alternatives and the predicted failure signature for each.

The alternatives matter because an implementation instruction usually preserves the winner and discards the reasoning. Six weeks later, a different agent can rediscover the rejected alternative, see a simpler patch and remove the property that justified the original design.

For this request-boundary example, the comparison is concrete. Requiring every API caller to present a hash would create a new refusal for previously compatible omission callers. Keeping the existing API contract while binding the new UI to displayed facts preserves compatibility, but requires a test at the UI request boundary. Those are different predicted failures and different probes.

A useful record can therefore say why we selected the second option without claiming that the first is universally bad. A new API version could legitimately require explicit presentation. That would be a separate compatibility decision with its own migration plan and acceptance criteria.

I want the source condition preserved alongside the choice. The rule exists because this UI represents a consent surface, while this existing API supports server-side binding for omission. Without those conditions, “always require a hash” and “a missing hash is fine” both become dangerous generalizations.

Machine-check the record, then respect what that check proves

Our validator rejects missing or placeholder fields. It requires at least two alternatives and a predicted failure signature for each. A protected fixture must exist at the repository's committed HEAD, rather than merely as an uncommitted file on one agent's disk.

That last detail is useful in distributed development. Another process can check out the cited revision and still lack a fixture that existed only in the author's worktree. Checking committed existence closes that particular gap.

It does not prove that the fixture is a good test. In the offline exercise accompanying this article, I committed a fixture that raises an assertion error. The decision record still passed its structural check because the path existed. That is the correct distinction: record validation locates the evidence; executing the owning behavior determines whether it passes.

The validator also treats an external probe-result URL as an offline-resolvable reference while explicitly recording that it did not fetch the URL. A source-link entry must be present, but the parser does not establish that its contents support the decision. Those are boundaries for a review system to honor, rather than reasons to discard a useful structural validator.

I divide the evidence into successive claims. The record is complete enough to inspect. Its references resolve in the stated scope. The referenced artifact belongs to the current implementation. The decisive probe actually ran. The probe demonstrates the intended behavior. Finally, the behavior was exercised at the route that can create the effect.

A green result at the first stage should help us reach the next stage. It should not be promoted into a claim about all six.

Expiry is a policy decision, not a date-shaped switch

The decision checker parses the validity date and flags expired records. Expiration alone does not make structural validation fail. An expired record can still be a complete, understandable account of a decision that needs renewal.

The exact implementation separates those states:

expired = days_left < 0
if expired:
    out["flags"].append("EXPIRED")
elif days_left <= 7:
    out["flags"].append("EXPIRING_WITHIN_7D")

The date's meaning has to survive the next integration boundary. If a supervisor looks only at the validator's overall success field, it can miss the expired flag. If it treats every expired document as an immediate global stop, it can turn administrative lag into an outage.

The integration needs an explicit policy. A proposed new architectural change might require a current decision before admission. An existing service might continue under its recorded contract while its owner receives a renewal task. A particularly sensitive exception might have a real execution expiry enforced by the component that admits effects.

Those policies should not be inferred from a Markdown date. Name the owner, the permitted behavior during renewal, the deadline and the condition that actually refuses work. A decision-review date and an authorization expiry serve different purposes even if both use timestamps.

Carry predicates into tasks, rather than copying paragraphs

The task should carry the decision's operational predicates. For the UI, the predicate is that no enable request leaves without a displayable hash and that a valid request contains the exact displayed value. For the API, omission retains its existing server-binding behavior while a supplied stale value remains a conflict.

A predicate names an input state, an expected result and an owning boundary. That makes it possible to build a negative control. Remove the payload hash and the exact-value assertion should fail. Remove the UI guard and a missing-hash scenario should observe an unwanted request. Neither control requires weakening the server to make the test easier.

Our recovery receipt authorized a narrow continuation: preserve the completed author evidence, add the missing UI assertions, remove the hash inclusion to demonstrate the assertion going red, then restore it. The historical NOT READY checkpoint was kept. A later READY result would mean the work could enter its configured outer review; it would not retroactively turn the stopped attempt into a pass.

That distinction is useful for agent efficiency. A failed acceptance interpretation does not necessarily invalidate every build, browser journey or backend test. Identify the changed predicate and reuse evidence whose subject and assumptions remain unchanged. Repeating the entire campaign can add time without addressing the actual disagreement.

The opposite shortcut is equally risky: editing the acceptance text until the current patch passes. The source decision must justify the revised predicate. Preserve who authorized the correction and why it belongs at this boundary. Otherwise “clarifying the contract” becomes a convenient name for lowering the bar.

Bind evidence to its subject and version

A passing test receipt needs a subject. At minimum, I want the code revision, relevant configuration, decision version, test identity and result. If one changes, the consumer needs to know which earlier evidence remains applicable.

The release-pipeline design in our source material applies this idea to exact candidate tips and base revisions. It also includes the gate version in the attempt identity. A gate change can alter what admission means even when candidate code remains identical.

The design's attempt key is based on repository, base SHA, sorted candidate identities and gate version. Its purpose is to avoid repeating the same qualification under indistinguishable conditions while allowing a changed input to receive a new attempt. A failed input can be quarantined with an attributed signature rather than becoming a fresh expensive surprise on every polling cycle.

I use that as a design pattern for task contracts too. Changing a sentence that alters accepted behavior should create a new contract identity. Changing only an editorial explanation should not automatically erase valid runtime evidence. The system needs a representation of the distinction; raw document modification time is too coarse.

A content hash can identify bytes, but it cannot decide semantic compatibility. That decision belongs to a versioned rule or an accountable owner. When evidence is reused, record the unchanged predicate and the reason the earlier probe still applies. When it is invalidated, say what changed.

Keep repair authority outside mechanical release

A standard that says “ship only passing work” does not authorize a release process to invent a new fix, launch a model, change the acceptance rule and retry until green. Those actions belong to different owners and budgets.

Our release design makes that separation explicit. Its mechanical path includes merging, building, checks, smoke, deployment under a lock and rollback. Model-driven repair, new review lanes and new follow-up work sit outside that path with the start authority or a person. The design includes a runtime guard against model commands on the ship path.

The important architectural property is the separation of permissions. A component allowed to deploy an already qualified artifact should not gain development authority merely because qualification failed. A component allowed to explain a failed decision record should not acquire permission to extend its own exception.

That also gives failure a useful destination. A rejected candidate needs a typed reason, retained evidence and the owner of the next step. A release loop should not respond to every refusal by creating more work with broader authority. The contract should identify whether the next action is repair, clarification, renewal or reconciliation.

These are source-backed design choices in this material. The release document explicitly distinguishes written components from installed and enabled units. I preserve that distinction because it determines what evidence an operator can ask for next: source review for a design, runtime canaries for activation, and accepted outcomes for operational improvement.

A practical packet for the next agent

The packet I want to hand to an implementer starts with the source condition and the selected tradeoff. It identifies the protected behavior, the precise layer that owns refusal and the compatibility surfaces that must remain stable.

Next come the alternatives and their predicted failures. They should be concrete enough that a fresh reviewer can propose a decisive probe. “Less safe” is too vague. “The UI sends a request without showing the package it binds” is an observable signature.

Then come the implementation subject and acceptance predicates. Name the files or interfaces where relevant, but keep the contract centered on behavior. Include the normal path and the deliberately broken input that demonstrates the check can fail for the right reason.

Finally, include evidence identity, current status and the next owner. Preserve failed attempts as failed. Preserve uncertainty as uncertainty. A local author result can be ready for independent review without being accepted for release. The receipt should make that progression understandable without reading the whole conversation.

This is not an argument for a longer prompt. It is an argument for fewer ambiguous transitions. A compact packet with an exact predicate and a resolving result can carry more operational value than pages of instructions that never identify who can refuse.

What I would measure

I would measure accepted outcomes per owner hour, alongside the cost of qualification and repair. Draft count and green test count are useful intermediate observations; neither describes how much complete work reached the intended result.

For this incident, the retained evidence supports the 106-test author checkpoint and the boundary correction. It does not support a causal claim that the revised brief saved a particular number of tokens, dollars or hours. The useful efficiency mechanism is narrower: reuse valid evidence, change the exact missing probe and avoid solving an incompatible requirement in the wrong layer.

For a follow-up experiment, I would compare tasks that receive a generic standards document with tasks that receive a source-linked decision packet. Hold the implementation scope and acceptance evaluator constant. Track boundary misinterpretations, invalidated evidence, repeated qualification, reviewer clarification and final accepted results. Price the whole workflow, including failed attempts and owner time.

I would also inspect the failure direction. A contract packet that produces faster acceptance by weakening a compatibility guarantee is not an improvement. The protected fixture and independent evaluator must remain outside the author's ability to redefine success silently.

Make the handoff state useful to the receiver

I would expose the next state as structured data rather than a cheerful completion sentence. A clarification result should name the disputed predicate and the decision owner. An implementation result should identify its source revision and retained evidence. A review result should name its evaluator and scope. A release result should identify the deployed artifact and its readback.

Those states let the receiving agent choose a bounded action. It can request a decision without restarting the author, reuse an unchanged test receipt without calling it a fresh review, or refuse a release whose artifact no longer matches the accepted subject. The narrative explanation still matters, but it accompanies a state transition that a program can check.

How this was verified

The article follows immutable snapshots of the decision-record validator, routine manifest service and tests, release-pipeline design, and the committed recovery receipt. The 106-test breakdown is retained author evidence, not a new independent run. The separate offline exercise executes the exact validator against 42 owned local-Git cases, expanded from the preserved 24-case baseline after independent review, including missing fields, uncommitted fixtures, flagged expiry, unverified URLs and a committed red fixture. Release activation, customer effects and causal cost savings are not inferred from these sources.