# Contract: MIGRATION GUIDE format (consumer side)

<!-- VENDORED TWIN: adia-forge ships references/contracts/migration-guide-format.md
     (producer 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.

(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)

## 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.