Intent cards

The map states what the system is. What the system is for can't be derived from code, and that's what intent cards carry: purpose, invariants, decisions with their rejected alternatives, non-goals. One small file per context, in cohere/intent/.

---
context: MyApp.Deals
surface: df8be63a83b8
functions: approve_deal/1 create_deal/1 ...
---

## Purpose
One sentence a new engineer reads first.

## Invariants
- INV-DEA-001: a posted deal is immutable; corrections go
  through reversal, never edit.

## Decisions
- DEC-DEA-002 (2026-03-11): fee math uses integer cents.
  Rejected: Decimal (rounding at the boundaries leaked).

## Non-goals
- Commission forecasting. See MyApp.Insights.

Invariants are the constraints an agent must not violate; decisions carry the rejected alternatives, the half of institutional memory that otherwise dies in chat scrollback. The next actor learns what was chosen and what was tried.

The binding

The frontmatter is machine-managed: cohere stamps the card with the context's current surface hash and its full function list. When the code's public surface moves, the card is drifted and mix cohere.check fails the build with an exact delta:

✗ cohere/intent/deals.md
  surface drifted: +approve_deal/1 −legacy_approve/2
  → re-review the card, then `mix cohere.check --accept deals`

Storing the function list alongside the hash costs one machine-managed line and buys those exact +fun/1 −fun/2 deltas without depending on git state.

Accepting drift

Accepting is a review action, not a bypass. mix cohere.check --accept deals rebinds the card to the new surface and appends a dated line to the card's Accepted drift section; silent rebinding is not a supported path. The build fails until a human has looked, and the look leaves a dated trace.

What cards are not

Cards are not documentation of the API; the map already carries the API, and restating it would create a second truth to keep honest. A card holds only what reflection cannot reach. If a card ever disagrees with the map, the map wins, because the map cannot lie. Cards cite design docs by slug for the fuller story of any decision.