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>

synthesis/contract.md

@@ -0,0 +1,123 @@
+# Synthesis Interface Contract
+
+The synthesis module is the final stage. It reads resolved WorldState and produces a natural language answer plus a derivation trace. The answer must be derivable from resolved constraints — not generated from surface token patterns.
+
+---
+
+## Design principle
+
+Synthesis is translation, not reasoning. All reasoning was done by specialists and the resolver. Synthesis converts the stabilized structured state into human-readable output.
+
+If the answer cannot be derived from resolved constraints, synthesis should say so rather than confabulate.
+
+---
+
+## Input
+
+```
+SynthesisInput {
+  world_state:     WorldState     -- must have stage = "resolved"
+  original_query:  string         -- the user's original input text
+  synthesis_mode:  string         -- "direct" | "explain" | "trace"
+}
+```
+
+**Synthesis modes:**
+
+- `direct`: produce the answer as a natural sentence. Minimal explanation.
+- `explain`: produce the answer with a short explanation of how it was derived.
+- `trace`: produce the answer plus a full derivation trace listing every constraint and resolver operation used.
+
+---
+
+## Output
+
+```
+SynthesisOutput {
+  answer:              string
+  confidence:          float [0, 1]
+  derivation_trace:    string[]     -- ordered list of constraint_ids / operations used
+  open_questions:      string[]?    -- aspects the system could not resolve
+  synthesis_mode:      string       -- echoes input mode
+}
+```
+
+---
+
+## Derivation trace
+
+The `derivation_trace` must list, in order:
+1. The objects and facts the answer is based on
+2. The constraints that were applied
+3. The resolver operations that stabilized the relevant values
+
+The trace must be sufficient for a reader to reconstruct the answer without the system.
+
+---
+
+## Invariants
+
+1. **Grounded answer.** Every factual claim in the answer must correspond to a resolved constraint or a confirmed object in WorldState. Synthesis does not add new facts.
+
+2. **Uncertainty acknowledgment.** If a relevant constraint has `status: contradicted` or is in `open_contradictions`, the answer must acknowledge the uncertainty rather than silently pick a side.
+
+3. **Trace completeness.** `derivation_trace` must list all constraints used. If a claim appears in the answer, the constraint supporting it must appear in the trace.
+
+4. **Stage check.** Synthesis must reject WorldState where `stage ≠ "resolved"` with an error, not a guess.
+
+---
+
+## Answer generation patterns
+
+### Simple factual answer
+
+When WorldState contains a single resolved quantity or state that directly answers the query:
+
+```
+Template: "{Subject} {verb} {value} {unit}."
+Example: "Alice has 3 apples."
+
+Derivation:
+  1. E1 (Alice) — active entity
+  2. Q_alice_final — quantity, value=3, unit="apples"
+  3. C1: owns(Alice, apples, count=5) at t0 — resolved
+  4. C2: transfers(Alice, Bob, apples, count=2) at t1 — resolved
+  5. C3: quantity_difference(Q_alice_final, Q1, Q2) — resolved, computed 5-2=3
+  6. Resolver Op: merge_coreference (she → Alice)
+  7. Resolver Op: resolve_arithmetic (Q_alice_final.value = 3)
+```
+
+### Uncertain answer
+
+When `open_contradictions` is non-empty or relevant objects are low-confidence:
+
+```
+Template: "{Subject} likely {verb} {value}, though {uncertainty description}."
+```
+
+### No answer available
+
+When the query asks for something not covered by any resolved constraint:
+
+```
+Template: "The available information does not determine {query_topic}."
+```
+
+---
+
+## Synthesis does not do
+
+- Infer new facts beyond resolved constraints
+- Choose between contradicted constraints without flagging the contradiction
+- Generate fluent text that goes beyond what WorldState supports
+- Add caveats, hedges, or stylistic embellishments not grounded in confidence values
+
+---
+
+## Contract test requirements
+
+- Given resolved WorldState with Q_alice_final.value=3 and owns constraint resolved: answer must contain "3" and "Alice"
+- Given WorldState with `open_contradictions` non-empty: answer must not state a definitive value for the contradicted quantity
+- `derivation_trace` must be non-empty for any non-trivial answer
+- `stage` check: must raise error given WorldState where stage = "post_specialist"
+- All emitted `derivation_trace` entries must reference valid IDs in WorldState