# Contract: MIGRATION GUIDE format (producer side)

<!-- VENDORED TWIN: adia-factory ships references/contracts/migration-guide-format.md
     (consumer side). Cross-plugin imports are forbidden, so changes here must be
     reconciled in BOTH copies. -->

`{repo}/.claude/docs/MIGRATION GUIDE.md` is the artifact the forge PRODUCES
(via `package-release`, on every breaking cut) and the factory CONSUMES (via
`app-migration`, to drive consumer sweeps). This is the shared shape.

## Producer obligations (package-release, per breaking cut)

1. **Version-scope bullet** in the top index: `**\`X.Y.Z\`**, <MINOR/PATCH>
   lockstep cut. <BREAKING: one-line summary | No breaking changes.> See
   [§ vX.Y.Z section below](#anchor).` Every cut gets a bullet, breaking or not, the consumer sweep walks this index to find its version span.
2. **Per-cut section** for breaking cuts, containing, in order:
   - the breaking-change list, each item with: the old form, the new form, and
     a **greppable pattern** (`git grep -n '<old>'`) a consumer can sweep;
   - mechanical vs **judgment items** separated, judgment items (semantic
     flips, behavioral defaults) are explicitly marked *never auto-sweep*;
   - the verify command(s) that prove the sweep landed.
3. **Anchors are stable**, section headings are linked from release notes and
   consumer tooling; never retitle an existing section.
4. Soft-API graduations (`_debug.*` → top-level) are documented even though
   non-breaking, consumers key on them.

## Consumer expectations (app-migration)

The sweep discipline reads: index bullet(s) for the span → per-cut sections →
grep audit with the given patterns → mechanical sweeps → judgment items
surfaced to the operator → verify gates. A guide entry missing a greppable
pattern or a verify command is a producer defect, report it upstream, do not
improvise a sweep.