validate_schema_change does not walk allOf/$ref — document limitation or extend

[mgoldsborough]

Context

validate_schema_change() compares only top-level properties and required. It does not resolve $ref or walk allOf sub-schemas. This is documented in the docstring.

Problem

If someone passes a composed schema (with allOf + $ref to the base entity schema), changes in referenced sub-schemas won't be detected. This is fine for the current add_field use case (which operates on app-level schemas only), but could surprise callers using it for broader schema comparisons in the future.

Options

1. Document only — add a note in CLAUDE.md or a code comment making the limitation more visible
2. Extend — optionally resolve $ref via _REF_MAP and flatten allOf before comparing, gated by a parameter like resolve_refs=False

Current recommendation: option 1, unless a use case arises that requires full resolution.