These examples show the expected shape of an Agent-Operable Architecture finding. They are deliberately small. The point is not to prove that a pattern is good or bad, but to connect evidence to a likely future failure.
The same order-state decision appears in domain logic, an API serializer, and UI copy. Each surface handles the state transition separately.
Adding a new state such as suspended, refunded, or requires_review may update the domain model but leave API output, UI messaging, analytics, or permissions behind.
An agent may patch the file mentioned in the user request, miss the other copies, and then add another conditional branch that makes the split harder to see.
The diff can look correct inside one layer. Reviewers need cross-surface knowledge to notice that the same business decision is repeated elsewhere.
Name the authoritative owner for the decision. Make boundary mappings exhaustive or generated, and keep presentation labels separate from policy.
Add a test or type/schema check that fails when a state is added without updating required mappings.
Higher risk when the state affects billing, permissions, persisted data, external APIs, or user-visible workflow. Lower risk when the duplicated decision is temporary display-only copy.
The README or top-level agent instructions describe an old configuration file as authoritative, while the current implementation reads from a schema, generated client, or different module.
Changing configuration, data shape, or public behavior may update the current source of truth while documentation leads future work back to the obsolete one.
An agent may follow the stale README because it is top-level, trusted, and written as a rule. It may then modify the old file or reintroduce an obsolete pattern.
The code diff may be plausible, and the stale documentation may not appear in the changed files. Reviewers may assume the agent read the right context.
Update the README to point to the current source of truth, or mark the old document as historical. Remove instructions that name obsolete files as active policy.
Run the relevant test or config/schema check, and include a documentation check in review: top-level instructions name the current authoritative file.
Higher risk when the stale context controls agent behavior, onboarding, release steps, migrations, security, or production configuration.
Generated clients, types, routes, or ORM files are not marked as generated, and nearby handwritten code copies their structure.
Regenerating the source artifact may overwrite local edits or leave copied handwritten code inconsistent with the generated surface.
An agent may edit generated files directly, imitate generated structure in handwritten code, or treat duplicated generated output as a source-of-truth split.
Generated code often looks regular and intentional. Without headers, generator commands, or ownership notes, reviewers must infer what may be edited.
Mark generated files clearly, document the generator and source schema, and route handwritten extension points away from generated output.
Regenerate the artifacts and confirm the working tree is clean, or run a generated-code check in CI.
Higher risk when generated artifacts define API contracts, database clients, SDKs, or cross-language types. Lower risk when generated files are local fixtures with no downstream commitment.
A migration changes persisted data shape or semantics, but there is no rollback path, restore procedure, backfill verification, or compatibility test for old and new readers.
A deployment may partially apply the migration, require rollback, or run mixed app versions against incompatible data.
An agent may add only the forward migration because the request says "add a column" or "rename this state", then claim completion after unit tests pass.
The migration can be syntactically valid and locally tested. The missing proof lives in deployment order, data volume, backups, readers, and rollback assumptions.
Match the migration plan to the actual commitment: add a reversible migration, phased reader/writer compatibility, a restore plan, or an explicit "no rollback required" decision with evidence.
Run migrate-forward and rollback/restore verification where relevant. For high-risk data, test mixed-version behavior or backfill idempotency.
Higher risk with customer data, payments, auth, compliance, external clients, long-lived workflows, or large datasets. Lower risk for disposable prototype data with no compatibility commitment.