Set up Core Hub framework planning

docs/specs/contract-ir.md

@@ -0,0 +1,39 @@
+# Contract and IR Spec
+
+## Purpose
+
+The Contract/IR layer is the canonical source of truth for Core Hub behavior. Runtime code, UI adapters, generated clients, and migration tools consume this layer.
+
+## Initial Contract Artifacts
+
+- OpenAPI document for HTTP APIs
+- JSON Schemas for manifests, widgets, events, annotations, decisions, deployments, outcomes, and registry facts
+- Alembic migrations and SQL schema snapshots
+- fixture datasets for compatibility tests
+- event type catalog
+- widget type catalog
+- capability manifest schema
+- API auth and error envelope conventions
+
+## Adapter Rule
+
+Adapters may scaffold code or validate drift, but they must not become the contract. A field exists because it is in the Contract/IR, not because a runtime class happens to expose it.
+
+## Compatibility Rule
+
+When migrating from Inter-Hub, capture every preserved route with:
+
+- route and method
+- auth requirement
+- request schema
+- response schema
+- error semantics
+- known consumers
+- fixture examples
+- migration status
+
+## Open Questions
+
+- Whether Core Hub should keep SDK download endpoints or move generated clients to package artifacts.
+- Which admin UI routes from Inter-Hub need API-compatible successors vs. product redesign.
+- Whether State Hub file sync remains external or becomes a first-class Core Hub ingestion mode.