Document and tool the model-evolution loop (day-2 flows)

[aaylward]

What

Implements the incremental-development follow-up from PLAN Phase 6, closing #28: document and tool the day-2 loop for consumers who evolve a Smithy model after the initial integration.

• docs/model-evolution.md (new): the workflow for both consumption modes — in-graph generation via the Bazel rules (no drift possible; compile errors guide handler updates) and vendored/checked-in output (regenerate → review the diff → commit model + output together). Includes how to read a regeneration diff (types.h = API surface, serde.cc/server.cc = wire behavior), CI drift-detection recipes (this repo's gradle generateFixtures … && git diff --exit-code job plus a consumer-side CLI equivalent), a worked example adding chanceOfSnow to the weather fixture with its actual 22-line diff, and a wire/source compatibility cheat sheet (optional members, @default, new operations, @required promotion via the evolution leniency, enum values, renames, constraint tightening).
• examples/bazel-consumer/model-evolution-check.sh (new): scripted evolve-and-rebuild against the out-of-tree consumer module, pinning the two properties the doc promises — stage 1 adds an optional member and requires bazel test //... to pass with handlers and tests untouched; stage 2 adds a ListTasks operation and requires the integration test to fail compilation naming the new handler method. Restores the model on exit.
• .github/workflows/ci.yml: the consumer job now runs the script (ubuntu leg only — the properties are platform-independent).
• Cross-links: quickstart gets a "Day 2: evolving the model" pointer, development.md documents the goldens-regeneration convention, README's Phase 6 row and PLAN's follow-up entry reflect the delivered state.

Testing

• examples/bazel-consumer/model-evolution-check.sh run end-to-end locally: stage 1 rebuilds green with the evolved model; stage 2 fails compilation with the error naming ListTasks; the model is restored afterward (clean tree).
• The worked example was executed for real: evolved weather.smithy, ran gradle generateWeatherFixture, captured the diff shown in the doc, and verified bazel test //examples/weather/... passes with no hand-written code touched — then reverted (nothing generated changes in this PR).
• .github/workflows/ci.yml parses cleanly; the new step reuses the existing consumer-job setup.
• Docs-only otherwise: no generator, runtime, or generated-code changes, so the golden drift check is unaffected.

Checklist

• Tests added/updated for the change (scripted evolve-and-rebuild check in the consumer CI job)
• bazel test //... and (cd codegen && gradle build spotlessCheck) pass locally (Beast/benchmark targets excluded per docs — sandbox proxy blocks their archive fetches)
• Formatting clean (no C++/Java/Starlark changes; workflow YAML validated)
• Architectural decisions recorded as an ADR (not applicable — docs and CI tooling only)

🤖 Generated with Claude Code

https://claude.ai/code/session_01SyQAo21Pv6GYhHrkbQj8xQ

---

Generated by Claude Code