docs(workplans): add CUST-WP-0005 — dynamic domains & multi-repo
First workplan file following ADR-001 convention. Canonical source for the v0.5 workplan previously recorded DB-first in the state-hub. Embeds all 11 tasks with state_hub_task_id cross-references for future sync reconciliation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
305
workplans/CUST-WP-0005-dynamic-domains.md
Normal file
305
workplans/CUST-WP-0005-dynamic-domains.md
Normal file
@@ -0,0 +1,305 @@
|
||||
---
|
||||
id: CUST-WP-0005
|
||||
type: workplan
|
||||
title: "State Hub v0.5 — Dynamic Domains & Multi-Repo"
|
||||
domain: custodian
|
||||
status: active
|
||||
owner: custodian
|
||||
topic_slug: custodian
|
||||
state_hub_workstream_id: 2271eb55-62ca-4bcc-8d9f-f9aacd6922d6
|
||||
created: "2026-02-28"
|
||||
updated: "2026-02-28"
|
||||
---
|
||||
|
||||
# State Hub v0.5 — Dynamic Domains & Multi-Repo
|
||||
|
||||
## Summary
|
||||
|
||||
Replace the hardcoded 6-domain Python enum with a first-class `domains` DB
|
||||
table, enabling new domains to be added and existing ones to be renamed
|
||||
without schema migrations. Alongside: introduce a `managed_repos` table so
|
||||
multiple git repositories can be registered per domain, with a corresponding
|
||||
registration workflow update.
|
||||
|
||||
## Context
|
||||
|
||||
Domains are currently baked into a PostgreSQL ENUM type (`domain` with 6
|
||||
fixed values). Adding a domain requires a schema migration; renaming is
|
||||
impossible at runtime. The registration workflow (`make register-project`)
|
||||
assumes one repository per domain. Neither constraint fits the actual project
|
||||
structure, where a domain may span multiple repos and the domain set itself
|
||||
should be open.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Blocks: `CUST-WP-0003` (v0.3 Contribution Tracking) — `managed_repos`
|
||||
table, `/repos/` router, `register_repo` MCP tool, and base registration
|
||||
workflow in v0.3 are superseded by P2.1–P2.3 here.
|
||||
- state_hub_dependency_id: 2033172d-2462-4253-acb7-cb64c7432480
|
||||
|
||||
## Phase 1 — Domain as a DB Entity
|
||||
|
||||
### P1.1 — Create `domains` table + Alembic migration
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T01
|
||||
state_hub_task_id: 456a0252-9a34-43a6-8244-c3a2caf95d51
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
New table: `domains` (id UUID PK, slug VARCHAR(50) UNIQUE NOT NULL,
|
||||
name VARCHAR(200) NOT NULL, description TEXT, status VARCHAR(20) DEFAULT
|
||||
'active' CHECK IN ('active','archived'), created_at, updated_at).
|
||||
|
||||
Migration (down_revision: a3f1c2d4e5b6):
|
||||
1. Create `domains` table.
|
||||
2. INSERT the 6 canonical rows from the existing enum values.
|
||||
3. ADD COLUMN `domain_id UUID REFERENCES domains(id)` to `topics`.
|
||||
4. UPDATE topics SET domain_id = (SELECT id FROM domains WHERE slug = domain::text).
|
||||
5. ALTER TABLE topics ALTER COLUMN domain_id SET NOT NULL.
|
||||
6. DROP COLUMN `domain` (old enum column) from topics.
|
||||
7. DROP TYPE `domain` (the PostgreSQL enum type).
|
||||
8. Leave EP and TD `domain` columns as String(50) — validated at API layer
|
||||
against live domains list, not via FK. Document as acceptable loose
|
||||
coupling (avoids cascading complexity).
|
||||
|
||||
Downgrade: reverse all steps (recreate enum, repopulate, drop domain_id).
|
||||
|
||||
### P1.2 — Domain ORM model + Pydantic schemas
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T02
|
||||
state_hub_task_id: eddff1ae-b263-4d3e-af95-91b4c3c2ecea
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
New file: `state-hub/api/models/domain.py`
|
||||
- `Domain(Base)`: id, slug, name, description, status, created_at, updated_at
|
||||
- Relationship: `topics: list[Topic]`
|
||||
|
||||
Update `state-hub/api/models/topic.py`:
|
||||
- Remove `Domain(str, enum.Enum)` class
|
||||
- Change `domain` column → `domain_id: Mapped[uuid.UUID]` (FK to domains.id)
|
||||
- Add `domain: relationship(Domain)` backref
|
||||
|
||||
New file: `state-hub/api/schemas/domain.py`
|
||||
- `DomainCreate`: slug, name, description?
|
||||
- `DomainRead`: id, slug, name, description, status, created_at, updated_at
|
||||
- `DomainUpdate`: name?, description?, status?
|
||||
- `DomainRename`: new_slug, new_name (cascades EP/TD string columns)
|
||||
|
||||
### P1.3 — Domain API router: list, get, create, rename, archive
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T03
|
||||
state_hub_task_id: b91cd0b5-c647-41e5-abf5-98f6f5eb3333
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
New file: `state-hub/api/routers/domains.py`
|
||||
|
||||
Endpoints:
|
||||
- `GET /domains/` — list all (filter: ?status=active|archived|all)
|
||||
- `GET /domains/{slug}/` — get by slug with counts (topics, workstreams, EPs, TDs, repos)
|
||||
- `POST /domains/` — create new (slug: unique, lowercase, underscored)
|
||||
- `PATCH /domains/{slug}/rename` — update slug + name; cascade EP/TD string columns
|
||||
- `PATCH /domains/{slug}/archive` — soft-delete; 409 if active topics exist
|
||||
|
||||
Register in `state-hub/api/main.py`.
|
||||
|
||||
### P1.4 — Update seed.py + TopicCreate schema for new domain model
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T04
|
||||
state_hub_task_id: 0825fa45-ec3a-43b5-8482-4a819db75c6a
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Update `state-hub/scripts/seed.py`:
|
||||
- Insert 6 domains before topics (idempotent: ON CONFLICT DO NOTHING).
|
||||
- Topic insertion uses `domain_id` FK (lookup by slug) instead of enum.
|
||||
- Remove Domain enum import.
|
||||
|
||||
Update `state-hub/api/schemas/topic.py`:
|
||||
- `TopicCreate.domain`: `Domain` enum → `str` (validated at router via DB lookup).
|
||||
- `TopicRead`: expose `domain_slug: str` from FK relationship.
|
||||
|
||||
Update state router: any `Domain.custodian` etc. references → slug string.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Multi-Repo Support
|
||||
|
||||
### P2.1 — Create `managed_repos` table + migration
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T05
|
||||
state_hub_task_id: 50dc7eec-2b45-4a0d-b99e-27aca8a55a67
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
New table: `managed_repos`
|
||||
Columns: id UUID PK, domain_id UUID FK domains(id) NOT NULL, slug
|
||||
VARCHAR(100) UNIQUE NOT NULL, name VARCHAR(200) NOT NULL, local_path TEXT,
|
||||
remote_url TEXT, description TEXT, status VARCHAR(20) DEFAULT 'active',
|
||||
topic_id UUID FK topics(id) NULLABLE, created_at, updated_at.
|
||||
|
||||
Design: `domain_id` is the primary association (not `topic_id`) — a domain
|
||||
can have multiple repos without a topic for each. `topic_id` is optional,
|
||||
for workstream-level linkage.
|
||||
|
||||
Coordinate with v0.3 P2.2: if v0.3 runs first, extend rather than replace.
|
||||
Add to `models/__init__.py` and register router.
|
||||
|
||||
### P2.2 — Repo API router: register, list, update, archive
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T06
|
||||
state_hub_task_id: daca1636-0187-4fb7-a515-8a2cf84f89d9
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
New file: `state-hub/api/routers/repos.py`
|
||||
|
||||
Endpoints:
|
||||
- `GET /repos/` — list all (filter: ?domain=slug)
|
||||
- `GET /repos/{slug}/` — get detail
|
||||
- `POST /repos/` — register (domain_slug or domain_id required)
|
||||
- `PATCH /repos/{slug}/` — update (name, local_path, remote_url, description, topic_id)
|
||||
- `PATCH /repos/{slug}/archive` — soft-delete
|
||||
|
||||
Include repos list in `GET /domains/{slug}/` response.
|
||||
|
||||
Schemas: `RepoCreate`, `RepoRead`, `RepoUpdate`.
|
||||
|
||||
### P2.3 — Update registration workflow: multi-repo + dynamic domains
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T07
|
||||
state_hub_task_id: 930fd3fa-2e1d-401c-9e33-0378f33cb14d
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Update `state-hub/scripts/register_project.sh`:
|
||||
- Verify domain via `GET /domains/{slug}/` (not just topic lookup).
|
||||
- POST to `/repos/` after writing CLAUDE.md.
|
||||
- Support second repo for existing domain without overwriting CLAUDE.md
|
||||
(`--force` flag or existence check).
|
||||
|
||||
Update `state-hub/Makefile`:
|
||||
- `make add-domain DOMAIN=<slug> NAME=<name>` — POST /domains/
|
||||
- `make rename-domain DOMAIN=<old> NEW_SLUG=<s> NEW_NAME=<n>` — PATCH rename
|
||||
- `make add-repo DOMAIN=<slug> REPO_PATH=<path>` — POST /repos/ + CLAUDE.md
|
||||
- `make list-repos DOMAIN=<slug>` — GET /repos/?domain=slug
|
||||
|
||||
Update `state-hub/scripts/project_claude_md.template`:
|
||||
- Add section listing other known repos in the same domain.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — MCP & Validation
|
||||
|
||||
### P3.1 — MCP tools: domain lifecycle + repo registration
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T08
|
||||
state_hub_task_id: e99e6bd7-f6f2-496f-acbf-d2b013f37c73
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Add to `state-hub/mcp_server/server.py`:
|
||||
|
||||
1. `list_domains(status="active")` — GET /domains/?status=…
|
||||
2. `create_domain(slug, name, description?)` — POST /domains/
|
||||
3. `rename_domain(slug, new_slug, new_name)` — PATCH /domains/{slug}/rename
|
||||
4. `archive_domain(slug)` — PATCH /domains/{slug}/archive
|
||||
5. `list_domain_repos(domain_slug)` — GET /repos/?domain=…
|
||||
6. `register_repo(domain_slug, name, local_path?, remote_url?, description?)` — POST /repos/
|
||||
|
||||
Update `state-hub/mcp_server/TOOLS.md` to document all 6 new tools.
|
||||
|
||||
### P3.2 — Live domain validation for EP/TD + domain stats in state summary
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T09
|
||||
state_hub_task_id: f2b352b6-4b9e-47b3-b629-48485245390e
|
||||
status: todo
|
||||
priority: low
|
||||
```
|
||||
|
||||
Replace hardcoded `VALID_DOMAINS` set in EP/TD routers with a per-request
|
||||
DB lookup: `get_valid_domain_slugs(db: AsyncSession) -> set[str]`. Return
|
||||
422 with a helpful message for unknown domains.
|
||||
|
||||
Add to `/state/summary` response:
|
||||
- `domains: list[DomainSummary]` — slug, name, repo_count,
|
||||
active_workstream_count, ep_count, td_count.
|
||||
|
||||
Update global CLAUDE.md and project CLAUDE.md template to note
|
||||
`list_domains()` is now available.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Dashboard
|
||||
|
||||
### P4.1 — Dashboard: domains.md page
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T10
|
||||
state_hub_task_id: ddb91669-5297-45d9-8b5e-10213135a96d
|
||||
status: todo
|
||||
priority: low
|
||||
```
|
||||
|
||||
New file: `state-hub/dashboard/src/domains.md`
|
||||
|
||||
Layout:
|
||||
- KPI row: total domains, total repos, newest domain.
|
||||
- Domain cards: name, slug, status badge, repo count, workstream count,
|
||||
EP count, TD count.
|
||||
- Repos sub-list per card: name, local_path, remote_url (linked), date.
|
||||
- Click → entity modal (extend `entity-modal.js` for domain type).
|
||||
|
||||
Data loaders:
|
||||
- `src/data/domains.json.py` — GET /domains/?status=all
|
||||
- `src/data/repos.json.py` — GET /repos/
|
||||
|
||||
Add to `observablehq.config.js` nav.
|
||||
|
||||
### P4.2 — Dashboard: domain filter on workstreams, EP, TD pages
|
||||
|
||||
```task
|
||||
id: CUST-WP-0005-T11
|
||||
state_hub_task_id: 3fec152c-00e1-4cdb-b6e5-26136c8cb6c1
|
||||
status: todo
|
||||
priority: low
|
||||
```
|
||||
|
||||
Add `Inputs.select` domain filter to:
|
||||
- `workstreams.md` — filter by domain via topic.domain_slug
|
||||
- `extensions.md` — wire existing API domain filter to UI
|
||||
- `techdept.md` — wire existing API domain filter to UI
|
||||
|
||||
Each filter: load domain list from `/domains/?status=active`, default "All",
|
||||
client-side reactive re-filter, URL hash persistence (`?domain=railiance`).
|
||||
|
||||
Check if `WorkstreamRead` already exposes `domain_slug`; add if missing.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- v0.5 P2.1 supersedes the `managed_repos` design in v0.3 P2.2.
|
||||
v0.3 is annotated accordingly and depends on this workplan.
|
||||
- EP/TD `domain` columns remain `String(50)` (not FK) for simplicity.
|
||||
The rename endpoint cascades updates to these columns.
|
||||
- `sync_workplans.py` (future, v0.3 Phase 4) will be able to ingest this
|
||||
file and reconcile it with the DB rows created during the planning session.
|
||||
Reference in New Issue
Block a user