Keep Free-Lane Diffs Off the Schema Lock

The situation detailed below is an example of a staging failure that often originates from unsigned schema diffs. Recently, checkout webhooks have been rejecting signed order payloads in the staging environment. This issue began after a late cleanup from an agent branch was merged into the free-lane draft, which marked the tax_id field as optional.

However, production clients continue to treat that field as required. As a result, billing pipelines have been stalled while operators search for the unsigned diff. Despite the agent's local parse appearing clean, the same model was responsible for both writing and grading the patch. This scenario serves as a guide on what not to do when it comes to contract-class edits, rather than focusing on comment changes.

While free-lane drafts may exist, they must not have control over the lock. A contract is considered any file that other systems must adhere to. Shared schemas persist beyond the initial discussions that created them, and the disappearance of required fields can lead to multi-service incidents. Specific artifacts should be treated as contract-class changes, including OpenAPI files, JSON Schema documents under version control, agent tool parameter schemas, database migrations, ORM model files, Protobuf, Avro, or GraphQL schema definitions, webhook payload contracts consumed by external partners, IAM condition documents for destructive writes, and README tweaks.

A required field being dropped is always considered a contract-class change. The failure pattern typically involves a free-tier draft appearing locally correct, with the agent displaying a green self-check beside the diff. This check usually utilizes the same model that authored it. However, grading cycles can hide missing consumer constraints, causing callers outside the repository to send the previous shape, leading to breakage without version or deprecation windows.

Support then encounters invalid payload errors with no clear owner. The schema lock was never assigned to a human reviewer, leading to rollbacks becoming another generation instead of a pinned revert. Red flags indicate when promotion should be refused, such as when the diff touches contracts, migrations, or tool schema paths, if the origin label is free-tier or scratch-server, if the same model authored the patch and tests, or if a required key becomes optional without a version bump.

The change altering authentication, money, or deletion semantics, as well as tests that only assert parse success and skip consumer fixtures, are also considered red flags. A fail-closed apply gate, which refuses contract paths from free or unknown origins and compares file digests against a committed lockfile, is proposed to prevent unsigned bytes from reaching the apply job.