Group resolved entities and distinguish locally described behavior

docs/entity-resolution-v1.md

@@ -171,3 +171,48 @@ The second real Gemini reply from the schema trial is an offline regression
 fixture. It is accepted with its original response and citations under the new
 policy; the old rule continues to reproduce the recorded historical rejection.
 This does not overwrite or accept artifacts in the exhausted REVIEW case.
+
+## Grouped identities and descriptive behavior (interpretation protocol v3)
+
+Fresh resolution inputs freeze `interpretation_protocol_version = 3`. Historical
+v1/v2 inputs keep their original contexts, aliases, validation and prompts.
+The new final prompt is `case_interpretation_resolved_v3`; the two lookup prompts
+remain protocol v2. No additional model calls are introduced.
+
+Selected entities are grouped by exact `(type, id)` within the configured project
+and lookup snapshot. A known canonical entity keeps its alias and original
+provenance. Each group keeps every selected name, optional locale, role, reason,
+mention citation and exact captured row in `lookup_associations`. Technical lookup
+facts and raw captures are not removed. Different IDs or entity types are never
+merged merely because names are similar. Any matching group capture can establish
+identity in the final interpretation's citations.
+
+The new response contract `case-interpretation-quality-output-v1.schema.json`
+adds two explicitly labeled fields:
+
+- `described_behavior`: statements derived from readable `project_description`
+  facts, with `basis = local_description` and
+  `verification = not_independently_verified`.
+- `provisional_behavior_gap`: optional observation/description comparison, with
+  `basis = local_description`, `status = provisional`, and citations to both an
+  observation and a description actually included above.
+
+These are separate from `expected_behavior`: that field continues to require
+formal expectation sources, whose provenance distinguishes tester declarations
+from external research. The original completeness/provenance fields and Q0001
+are not promoted by a local description. `behavior_gap` and
+`first_known_divergence` still require formal expectation sources. Descriptions
+of prerequisites or a capture flow do not prove spawn behavior, correct runtime
+implementation, a defect, or an independently verified specification.
+
+The artifact schema binds the new response shape to the new prompt version.
+Markdown summaries show the descriptive flow and provisional gap with explicit
+verification labels. Hypothesis contexts retain these fields and their provenance
+as separate interpretation source kinds. Empty descriptions and a null provisional
+gap are valid when no applicable description or comparison is supported.
+
+Tests cover grouping/locale/provenance retention, canonical aliases, distinct
+IDs/types, valid alternative capture citations, a complete multi-query pipeline,
+formal/local source separation, two-sided provisional gaps, downstream context
+propagation, summaries, actual DB integration with fixture model replies, and
+historical protocol replay. No paid API call is required for these checks.