Merge pull request #43 from SourceOS-Linux/spec/hygiene-changelog-ci-wrapper-20260419

Author: mdheller

CHANGELOG.md

@@ -11,7 +11,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ### Added
 - Truth Plane: `TruthSurface` and `DeltaSurface` schemas + canonical examples (`examples/truth_surface.json`, `examples/delta_surface.json`)
 - Control-plane: `IncidentEvent` schema for incident lifecycle events
+- Control-plane: canonical wrapper `$id` model for legacy schemas (`schemas/control-plane/*.json` wrappers)
 - Truth Plane: OpenAPI/AsyncAPI patch fragments (`openapi.truth-plane.patch.yaml`, `asyncapi.truth-plane.patch.yaml`)
+- CI/spec integrity: schema identity guardrails (duplicate `$id` detection + control-plane wrapper `$id` resolution tests)
 - `description` fields on all 54 schemas and all properties (non-breaking documentation improvement)
 - `ARCHITECTURE.md` — two-plane architecture, schema families, governance lifecycle, URN table
 - `CONTRIBUTING.md` — schema authoring conventions, URN naming guide, PR checklist

docs/adr/0009-truth-surfaces-b11-delta-appendix-a-reuse-map.md

@@ -20,7 +20,7 @@ This appendix makes ADR-0009 actionable by:
 |---|---|---|
 | Signed “truth summary” per plane | Reuse **URN + `type` discriminator + `specVersion`** conventions (e.g., `TelemetryEvent`). Reuse existing evidence references (PolicyDecision/CapabilityToken/RunRecord/ProvenanceRecord) as *refs*, not embedded duplicates. | `schemas/TruthSurface.json` + `examples/truth_surface.json` |
 | Typed diff between two truth summaries | Reuse existing “risk + evidence + human approval” posture expressed in `policies/skills/default-policy-pack.rego` as the canonical gate style; DeltaSurface records the gate results, it does not *re-decide* policy. | `schemas/DeltaSurface.json` + `examples/delta_surface.json` |
-| Incident semantics (Freeze/Fork/Kill) | Reuse control-plane event structure conventions: `event_id`, `event_name`, `occurred_at`, `actor`, `run`, `refs`, `payload` as in the existing skill execution lifecycle schema and samples. | `schemas/control-plane/incident-events.schema.json` + `examples/control-plane/incident.freeze.sample.json` |
+| Incident semantics (Freeze/Fork/Kill) | Reuse control-plane event structure conventions: `event_id`, `event_name`, `occurred_at`, `actor`, `run`, `refs`, `payload` as in the existing skill execution lifecycle schema and samples. | `schemas/control-plane/IncidentEvent.json` (canonical wrapper) + `schemas/control-plane/incident-events.schema.json` (legacy) + `examples/control-plane/incident.freeze.sample.json` |
 
 ---
 
@@ -30,7 +30,11 @@ New schema files:
 
 1) `schemas/TruthSurface.json`
 2) `schemas/DeltaSurface.json`
-3) `schemas/control-plane/incident-events.schema.json`
+3) `schemas/control-plane/IncidentEvent.json` (canonical wrapper)
+
+Legacy schema retained for compatibility:
+
+- `schemas/control-plane/incident-events.schema.json`
 
 New example payloads: