Sprint 1: project skeleton, type system, and all architecture specs

- src/types.hpp: complete UCWM type system in C++20 — 19 enums, 11 facet
  data types, all core structs (CanonicalObject, Constraint, Facet,
  GateSignal, WorldState, etc.) with full JSON round-trip serialization
- src/main.cpp: smoke test — constructs apple-problem WorldState by hand,
  serializes to JSON
- tests/test_types.cpp: 19 tests, 123 assertions, all passing
- CMakeLists.txt: CMake + CPM build with nlohmann/json, spdlog, Catch2
- schemas/: JSON Schema contracts for all UCWM data types
- gates/, specialists/, resolver/, synthesis/: language-agnostic interface
  contracts and domain specs for all pipeline layers
- docs/: architecture, vocabulary, decision matrices, roadmap (6 phases,
  28 sprints), sprint_001, implementation_constraints

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

specialists/entity.md

@@ -0,0 +1,146 @@
+# Entity Specialist
+
+**specialist_id:** `entity`  
+**trigger_gates:** `has_entity_reference`, `has_coreference`
+
+---
+
+## Responsibility
+
+The entity specialist finds named and implied entities, proposes CanonicalObjects for them, resolves aliases, and detects coreference chains. It upgrades `proposed` objects to `active` when evidence is sufficient, and emits `same_entity` or `not_same_entity` constraints when coreference is resolved.
+
+---
+
+## Manifest
+
+```
+declared_facet_kinds:
+  - syntactic
+  - semantic
+
+declared_constraint_types:
+  - same_entity
+  - not_same_entity
+  - has_role
+
+budget_caps:
+  max_objects_proposed:    10
+  max_facets_emitted:       8
+  max_constraints_emitted: 12
+  max_merges:               4
+  max_splits:               0
+```
+
+---
+
+## Input focus
+
+Given `target_refs`, the entity specialist inspects:
+- Surface text spans that evidence each target object
+- Pronouns and alias spans in the same context window
+- Prior objects already in WorldState with overlapping spans or labels
+
+---
+
+## Output: CanonicalObject proposals
+
+The entity specialist may propose new objects of kind `entity`. New entity proposals use `status: proposed`. Proposals are confirmed (`active`) only if confidence exceeds 0.75.
+
+Required fields on all proposed entities:
+- `surface_span`
+- `canonical_label`
+- `aliases` (may be empty)
+- `confidence`
+- `source_module: entity`
+
+---
+
+## Output: SyntacticFacet
+
+For each confirmed entity, emit a `SyntacticFacet` describing its grammatical role in the input.
+
+```
+SyntacticFacet fields used by entity specialist:
+  - grammatical_role: "subject" | "object" | "indirect_object" | "adjunct" | "other"
+  - head_token: string
+```
+
+---
+
+## Output: Constraints
+
+### `same_entity`
+
+Emit when two object proposals likely refer to the same real-world entity. Common cases:
+- Pronoun resolution: `she` → `Alice`
+- Alias resolution: `the company` → `Acme Corp`
+- Repeated reference: `Alice ... Alice` (same span, different positions)
+
+```
+Constraint example:
+{
+  "constraint_type": "same_entity",
+  "argument_refs": ["E1", "E3"],
+  "polarity": "positive",
+  "strength": "hard",
+  "expression": "same_entity(E1, E3)"
+}
+```
+
+### `not_same_entity`
+
+Emit when two object proposals are clearly different entities that might otherwise be confused.
+
+```
+Constraint example:
+{
+  "constraint_type": "not_same_entity",
+  "argument_refs": ["E1", "E2"],
+  "polarity": "positive",
+  "strength": "hard",
+  "expression": "not_same_entity(Alice, Bob)"
+}
+```
+
+### `has_role`
+
+Emit when an entity is playing a specific functional role in the input context (giver, receiver, buyer, seller, etc.).
+
+```
+Constraint example:
+{
+  "constraint_type": "has_role",
+  "argument_refs": ["E1", "EV_transfer"],
+  "polarity": "positive",
+  "strength": "soft",
+  "expression": "has_role(Alice, giver, EV_transfer)"
+}
+```
+
+---
+
+## Coreference resolution algorithm (rule-based baseline)
+
+```
+for each pronoun P in input:
+  candidates = all active entity objects in WorldState
+  rank candidates by:
+    1. recency (closest preceding entity)
+    2. gender agreement (he/she/they match)
+    3. number agreement (they/them = plural)
+    4. animacy (personal pronouns prefer animate entities)
+  if top candidate confidence > 0.7:
+    emit same_entity(pronoun_object, top_candidate)
+  else:
+    propose new entity with surface_span = P, status = proposed
+```
+
+---
+
+## Contract test requirements
+
+- Given `Alice gave Bob 2 apples`, must emit at least two distinct entity objects (Alice, Bob)
+- Must emit `not_same_entity(Alice, Bob)`
+- Given `She gave him 2 apples` with prior context establishing Alice and Bob, must resolve `she → Alice` and `him → Bob`
+- Must not emit quantity or temporal constraints
+- All emitted objects must have `source_module: entity`