Start Core Hub FastAPI replacement foundation

docs/specs/README.md

@@ -7,6 +7,8 @@ This directory is the specification map for Core Hub. The specs are intentionall
 - [Architecture](core-hub-architecture.md) - component model and boundaries
 - [Contract and IR](contract-ir.md) - canonical framework contract, schemas, fixtures, and adapter rules
 - [API v2 Compatibility](api-v2-compatibility.md) - Inter-Hub compatibility surface to preserve during transition
+- [Inter-Hub Legacy Inventory](interhub-legacy-inventory.md) - initial route/data/consumer inventory for migration
+- [Contract Governance](contract-governance.md) - how contract changes are reviewed and recorded
 - [Data Model](data-model.md) - initial entity model and migration posture
 - [Event and Registry Model](event-and-registry-model.md) - event catalogs, manifests, widgets, and capability registries
 - [Auth, Access, and Custody](auth-access-and-custody.md) - API auth semantics and secret routing rules
@@ -14,6 +16,15 @@ This directory is the specification map for Core Hub. The specs are intentionall
 - [UI and Operator Console](ui-operator-console.md) - whynot-design aligned UI direction
 - [Testing, Release, and Migration](testing-release-and-migration.md) - verification, deployment, and cutover gates
 
+## Contract Artifacts
+
+Implementation-neutral artifacts live in `contracts/`:
+
+- `contracts/schemas/`
+- `contracts/catalogs/`
+- `contracts/fixtures/`
+- `contracts/openapi/`
+
 ## Contract Rule
 
 The implementation may change. The contract changes only through a workplan and a compatibility note.

docs/specs/contract-governance.md

@@ -0,0 +1,21 @@
+# Contract Governance
+
+Core Hub contracts change through workplans, not incidental implementation edits.
+
+## Change Rule
+
+Any change to a route, schema, event type, manifest field, fixture, or catalog entry must record:
+
+- affected contract artifact;
+- compatibility impact;
+- known consumers;
+- migration or cancellation path;
+- test or smoke evidence.
+
+## Compatibility Notes
+
+Compatibility notes belong beside the relevant spec or fixture. A compatibility note must say whether behavior is preserved, replaced, deprecated, or intentionally cancelled.
+
+## Review Rhythm
+
+Regular self-optimization reviews should look for recurring error states, workarounds that should become product behavior, redundant information passing, overly complex handoffs, and slow validation loops. Findings become workplans when they need code, contract, or operational changes.

docs/specs/interhub-legacy-inventory.md

@@ -0,0 +1,48 @@
+# Inter-Hub Legacy Inventory
+
+Status: initial inventory for Core Hub compatibility work.
+
+## Production Role
+
+`inter-hub` is the Haskell/IHP implementation that currently represents the second-generation interaction framework idea. Core Hub should preserve consumer-visible behavior before retiring it.
+
+## Public API v2 Routes To Preserve
+
+- `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 API v2 Routes To Preserve
+
+- `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`
+
+## Current Consumers
+
+- `ops-hub` bootstrap and gate probes use hub, manifest, API consumer, widget, interaction-event, token, and hub-registry surfaces.
+- `activity-core` can emit through an Inter-Hub sink but has a State Hub fallback during transition.
+- Custodian workplans and operator smokes depend on public route evidence and protected smoke evidence.
+
+## Data Sources For Migration
+
+- Inter-Hub SQL migrations and schema snapshots.
+- API consumer and key-prefix rows, with raw keys treated as non-recoverable.
+- Hub manifests, widgets, registries, event rows, annotations, decisions, deployments, outcomes, and request logs where historically useful.
+
+## Compatibility Risk
+
+The first Core Hub implementation preserves route presence and auth-before-business behavior with seed data. Full compatibility still requires fixture capture from legacy Inter-Hub and consumer smokes against ops-hub and activity-core.