Set up Core Hub framework planning

docs/specs/api-v2-compatibility.md

@@ -0,0 +1,59 @@
+# API v2 Compatibility Spec
+
+## Purpose
+
+Core Hub must preserve the Inter-Hub API surfaces that existing consumers rely on until each consumer has moved to a new explicit Core Hub contract.
+
+## Initial Compatibility Surface
+
+Public/read surfaces:
+
+- `GET /api/v2/hubs`
+- `GET /api/v2/hub-capability-manifests`
+- `GET /api/v2/widget-types`
+- `GET /api/v2/event-types`
+- `GET /api/v2/annotation-categories`
+- `GET /api/v2/policy-scopes`
+- `GET /api/v2/openapi.json`
+- `GET /api/v2/openapi.yaml`
+- `GET /api/v2/docs`
+
+Protected/write or authenticated surfaces:
+
+- `POST /api/v2/token`
+- `/api/v2/api-consumers`
+- `/api/v2/widgets`
+- `/api/v2/interaction-events`
+- `/api/v2/annotations`
+- `/api/v2/requirement-candidates`
+- `/api/v2/decision-records`
+- `/api/v2/deployment-records`
+- `/api/v2/outcome-signals`
+- `/api/v2/hub-registry`
+
+Potentially preserved SDK endpoints:
+
+- `/api/v2/sdk`
+- `/api/v2/sdk/ihf-client.ts`
+- `/api/v2/sdk/ihf-client.py`
+
+## Known Consumers
+
+- `ops-hub` bootstrap and Inter-Hub gate probes
+- `activity-core` optional Inter-Hub sink
+- Custodian workplans and operator smokes
+- Downstream docs or probes that check the public hub registry
+
+## Acceptance Standard
+
+A route is compatible when:
+
+- method and path match;
+- auth behavior matches public/protected expectations;
+- success status and response shape satisfy captured fixtures;
+- error shape is documented;
+- at least one consumer smoke passes against Core Hub.
+
+## Transition Rule
+
+Do not remove an Inter-Hub-compatible route until every known consumer either passes against the new Core Hub-native route or has a recorded cancellation decision.