docs: add UCS and ECL alignment spec

Author: AvaPrime

docs/codessa/ucs-ecl-alignment-v0.1.md

@@ -0,0 +1,141 @@
+# UCS + ECL Alignment Spec v0.1
+
+**Version**: 0.1  
+**Date**: 27 March 2026  
+**Status**: Alignment layer draft
+
+This document defines how the **Unified Conversation Schema (UCS)** and the **Epistemic Confidence Layer (ECL)** integrate with Codessa's Observation, Evaluation, and Synthesis pipeline.
+
+---
+
+## 1. Why This Layer Exists
+
+Conversation capture alone is insufficient.
+
+Codessa needs to know:
+- what happened,
+- what was claimed,
+- what evidence exists,
+- how trustworthy each signal is,
+- and whether synthesis may rely on it.
+
+UCS provides the structural record.
+ECL provides the trust overlay.
+
+---
+
+## 2. UCS as Observation Contract
+
+UCS is the canonical provider-agnostic conversation event format.
+
+Minimum event families:
+- `session_start`
+- `message`
+- `tool_call`
+- `tool_result`
+- `file`
+- `artifact`
+- `decision`
+- `session_end`
+
+Each event should preserve:
+- provider,
+- model,
+- actor role,
+- timestamps,
+- raw content,
+- content type,
+- artifact references,
+- hashes where relevant.
+
+Codessa then maps UCS events into observation artifacts.
+
+---
+
+## 3. ECL as Confidence Overlay
+
+ECL sits on top of UCS-derived observations.
+
+Responsibilities:
+- extract atomic claims,
+- compare claims across models or sources,
+- identify contradiction or consensus,
+- generate confidence and calibration signals,
+- flag weak evidence for human review.
+
+ECL should not mutate raw observations. It augments them.
+
+---
+
+## 4. Observation Enrichment Model
+
+For every observation derived from UCS, Codessa should attach:
+- `evidence_strength`: direct | derived | speculative
+- `confidence`: 0.0–1.0
+- `claim_refs`
+- `contradiction_refs`
+- `consensus_refs`
+- `human_review_flag`
+
+This becomes the minimal bridge between Conversation Ops and CER.
+
+---
+
+## 5. Claim Handling Rules
+
+### Rule A — Direct evidence first
+If something is directly observed from the transcript, tool result, file hash, or package manifest, it is stored as direct evidence.
+
+### Rule B — Derived claims must name their basis
+Any claim inferred from multiple signals must cite the specific observation IDs or event IDs that support it.
+
+### Rule C — Speculative claims cannot silently enter synthesis
+They must carry `human_review_flag = true` and cannot bypass CER without explicit review.
+
+### Rule D — Contradictions lower admissibility confidence
+When ECL detects unresolved contradictions across sources, CER should either:
+- require redesign,
+- or require explicit constraints and review.
+
+---
+
+## 6. CER Inputs from ECL
+
+CER should consume at least these ECL signals:
+- `claim_confidence`
+- `calibration_band`
+- `contradiction_count`
+- `consensus_count`
+- `evidence_quality_score`
+- `review_required`
+
+This allows constitutional decisions to account for epistemic reliability, not just architectural attractiveness.
+
+---
+
+## 7. Synthesis Implications
+
+SBE may only use pattern candidates that satisfy one of the following:
+- direct evidence with acceptable constitutional score,
+- derived evidence with acceptable constitutional score and no unresolved contradiction,
+- speculative evidence only after human review and explicit admissibility.
+
+This keeps the synthesis layer from hallucinating design truths from thin signals.
+
+---
+
+## 8. P0 Practical Use
+
+In P0, ECL can remain lightweight:
+- simple claim extraction,
+- contradiction tagging,
+- confidence labels,
+- human review escalation.
+
+Full calibration science can expand later.
+
+---
+
+## Final Thesis
+
+**UCS gives Codessa a common language for conversational evidence. ECL gives Codessa the discipline to decide how much that evidence deserves to influence synthesis.**