the-custodian/workplans/CUST-WP-0006-gems-state-hub.md

id, type, title, domain, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	created	updated	state_hub_workstream_id
CUST-WP-0006	workplan	GEMS Analysis & State-Hub Migration Planning	custodian	done	custodian	the-custodian	2026-03-02	2026-03-12	7ce13282-d534-492a-8d42-b3a134028823

CUST-WP-0006 — GEMS Analysis & State-Hub Migration Planning

Purpose

Apply the Generic Entity Modelling System (GEMS) — documented in wiki/GenericEntityModellingSystem.md — to the state-hub data store.

This workplan covers:

1. A domain-specific GEMS implementation skeleton (type registry + hierarchy)
2. An audit of current model inconsistencies against GEMS principles
3. Escalation of all non-trivial structural decisions
4. A SWOT analysis of migrating the state-hub data store to the GEMS model
5. (Deferred) A refined migration workplan, once key decisions are resolved

Companion documents:

• wiki/GEMS-StateHub-TypeRegistry.md — canonical type registry
• wiki/GEMS-StateHub-SWOT.md — SWOT analysis

---

Phase 1 — GEMS Skeleton Definition

Task T01: Map current state-hub entities to GEMS types

id: T01
status: done
priority: high
assignee: custodian
state_hub_task_id: "b771f327-128e-4923-a7ad-2080b4e49eb9"

Deliverable: wiki/GEMS-StateHub-TypeRegistry.md

See companion document. Summary:

Current Table	GEMS Kind	GEMS Primary	Notes
Domain	Complex	Ecosystem (implicit root)	6 canonical domains
Topic	Complex	Domain	Focus area / active project
ManagedRepo	Complex	Domain	Managed git repo
Workstream	Complex	Repository (currently Topic)	Work package — ADR-001 mismatch
SBOMSnapshot	Complex	Repository	Does not yet exist as an entity
Task	Atom	Workstream	✓ correct
Decision	Atom	Repository (currently Topic or Workstream)	Dual-attach ambiguity
TechnicalDebt	Atom	Repository (currently domain: str)	String FK inconsistency
ExtensionPoint	Atom	Repository (currently domain: str)	String FK inconsistency
Contribution	Atom	Repository (no domain FK)	No domain affiliation
ProgressEvent	Atom	Workstream (or Topic)	Multi-attach ambiguity
SBOMEntry	Atom	SBOMSnapshot (currently ManagedRepo)	No container
WorkstreamDependency	Relation	Domain	Flat junction table

---

Task T02: Inconsistency audit — current model vs GEMS

id: T02
status: done
priority: high
assignee: custodian
state_hub_task_id: "2be639ea-a19e-4c80-bcde-c3da06ec5a49"

Identified inconsistencies:

I-1 — String domain field (high severity) ExtensionPoint.domain and TechnicalDebt.domain are String(50) columns, not FKs to domains.id. The rename_domain API patches these manually via string updates — there is no referential integrity. Dashboard filtering silently returns empty results when slugs drift.

I-2 — Workstream primary container is Topic, not Repository (critical severity) GEMS §7 places Workstream.primary = Repository. ADR-001 states that workplans (the file backing a workstream) must originate in a repository. However, the current schema has Workstream.topic_id NOT NULL — Topic is the enforced primary container. This is an ADR-001 violation embedded in the schema itself. There is currently no repo_id on Workstream.

I-3 — Decision dual attachment without clear hierarchy (medium severity) Decision has both topic_id and workstream_id FKs, with a CHECK constraint requiring at least one. GEMS requires exactly one primary attachment. The current model allows ambiguous "where does this Decision live" answers.

I-4 — ManagedRepo has a nullable topic_id FK (low-medium severity) ManagedRepo.topic_id is a nullable FK to topics. In GEMS, Repository is a Complex whose primary is Domain, not Topic. The topic_id on Repo suggests a second, conflicting hierarchy path.

I-5 — No SBOMSnapshot container entity (medium severity) SBOM entries are flat rows tagged with repo_id and snapshot_at. GEMS §7 defines SBOM (Complex, primary=Repository) as an organizer. Without this container, it is impossible to query "all packages in snapshot X" as a first-class concept, or to model snapshot-to-snapshot diffs.

I-6 — Contribution has no domain or repository FK (medium severity) Contribution has only optional related_topic_id and related_workstream_id. There is no direct link to Domain or Repository, making domain-scoped contribution queries fragile.

I-7 — No Ecosystem root entity (low severity) GEMS §3.2 requires at least one root Complex. The current model has no explicit root — Domain is the de-facto root but is not declared as such. This matters when you want to express cross-domain relations or system-level policies.

I-8 — WorkstreamDependency as flat junction table (low severity) GEMS §4 defines Relations as first-class entities whose primary is a Complex. The current WorkstreamDependency is a flat table. For the current usage this works, but it makes contextual queries (e.g. "all dependencies within domain X") less uniform.

---

Phase 2 — Decision Escalation

Task T03: Register non-trivial decisions in state-hub

id: T03
status: done
priority: critical
assignee: custodian
state_hub_task_id: "da639706-3b14-42b8-92de-b9de84dbb2be"

Six decisions were escalated (see state-hub records):

• DEC-GEMS-001: GEMS implementation architecture (typed tables vs. generic entity model)
• DEC-GEMS-002: Workstream primary container — Topic vs. Repository
• DEC-GEMS-003: Domain string → FK migration for ExtensionPoint and TechnicalDebt
• DEC-GEMS-004: SBOMSnapshot container entity
• DEC-GEMS-005: Ecosystem root entity
• DEC-GEMS-006: WorkstreamDependency as first-class Relation entity

---

Phase 3 — SWOT Analysis

Task T04: Produce SWOT analysis document

id: T04
status: done
priority: high
assignee: custodian
state_hub_task_id: "96dd379a-02b4-4629-8db7-3bef15b9639d"

Deliverable: wiki/GEMS-StateHub-SWOT.md

See companion document for the full analysis. Summary verdict:

The migration is worth pursuing incrementally (Pattern C from GEMS §9). The most impactful and least risky first move is:

1. Fix I-1: migrate domain string → FK on EP/TD (low risk, high consistency gain)
2. Fix I-2: add repo_id to Workstream (medium risk, fixes ADR-001 alignment)
3. Add SBOMSnapshot container (medium risk, enables snapshot diffing)

Full generic entity table architecture (Option A) is deferred until after the typed-table alignment is stable and validated.

---

Phase 4 — Migration Workplan Refinement (deferred)

Task T05: Write detailed migration workplan (CUST-WP-0007)

id: T05
status: done
priority: high
assignee: custodian
state_hub_task_id: "032649fb-2d21-44b7-9735-346405168d8e"

Once the six decisions are resolved, produce workplans/CUST-WP-0007-gems-migration.md covering:

• Schema migrations (Alembic versions)
• Data backfill scripts
• API router changes
• MCP tool changes
• Dashboard updates
• ADR-001 workplan file format updates