api-and-interface-design

# API and interface design ## Contract | Field | Bound contract | |---|---| | Trigger | Designing or changing a public API, route, CLI flag, or module boundary. | | Authority | Reversible local: writes only named local interface definitions and contract docs, edits consumer files onto the new contract, and deletes legacy paths (old signatures, aliases, re-exports, deprecated entry points) during cutover; rollback is undo (discard the uncommitted draft) or version control. No remote mutation. No credential, paid, published, or deployed change, and no VCS history rewrite. | | Side effect | Interface definitions and contract docs written before implementation; consumer files edited onto the new contract and legacy paths (old signatures, aliases, re-exports, deprecated entry points) deleted during cutover; no build, publish, or remote mutation. | | Done | Contract is documented with semantics and errors, every consumer is migrated, and no legacy path remains. | ## Inputs The interface being designed or changed: its name and kind (API endpoint, route, CLI flag, or module boundary), and whether it is new or a change to an existing interface. The current contract text, when changing an existing interface. The list of known consumers, found by search over the codebase. Optional: target language or runtime conventions for type and error spelling. ## Procedure 1. Bound scope before any mutation: name the exact interface and whether it is new or a change. Search the codebase for e...