coulomb/core-hub
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Set up Core Hub framework planning

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-27 11:00:12 +02:00
parent 8ed13623e5
commit a69df288b7
33 changed files with 1058 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.claude/rules/architecture.md
View File

@@ -1,8 +1,18 @@
## Architecture ## Architecture
<!-- TODO: Describe the key design decisions and component structure. Core Hub is contract-first. The stable framework surface is defined by specs, schemas, OpenAPI, event catalogs, manifests, fixtures, and compatibility tests before implementation details harden.
Key modules, data flows, external integrations, state machines, etc. -->
Initial component model:
- Contract/IR layer: documented schemas for hubs, capabilities, manifests, widgets, events, workplans, tasks, progress, messages, decisions, and registry facts.
- Service layer: Python/FastAPI application with Pydantic v2 DTOs, SQLAlchemy async models, Alembic migrations, asyncpg/Postgres persistence, and httpx integrations.
- Compatibility layer: Inter-Hub `/api/v2` endpoint preservation where ops-hub, activity-core, and existing consumers depend on it.
- UI layer: operator console and component surfaces aligned with whynot-design patterns; prefer framework-neutral contracts and Lit/custom-element adapters where useful.
- Migration layer: data import, row-count checks, fixture replay, dual-run smokes, and production cutover gates.
## Quick Reference ## Quick Reference
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference - `INTENT.md` - purpose and lineage
- `docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md` - research artifact
- `docs/specs/README.md` - spec map
- `workplans/` - ADR-001 workplans

48
.claude/rules/first-session.md
View File

@@ -1,38 +1,26 @@
## First Session Protocol ## First Session Protocol
Triggered when `get_domain_summary("infotech")` shows **no workstreams**. Triggered when State Hub shows no workstreams for `core-hub`.
The project is registered but work has not yet been structured.
**Step 1 — Read, don't write** **Step 1 - Read, do not write yet**
- `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope - `INTENT.md`
- `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases - `SCOPE.md`
- Scan repo root: README, directory structure, existing code or docs - `docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md`
- `docs/specs/README.md`
- Existing files under `workplans/`
**Step 2 — Survey in-progress work** **Step 2 - Survey in-progress work**
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. Look for untracked files, open workplans, and half-finished specs. Note done vs. started but incomplete.
**Step 3 — Propose workstreams to Bernd** **Step 3 - Structure work in files first**
Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a Create or update `workplans/CORE-WP-NNNN-<slug>.md` before relying on State Hub records.
roadmap phase. **Wait for approval before creating.**
**Step 4 — Create workplan file first, then DB record (ADR-001)** **Step 4 - Sync the read model**
``` After workplan changes, run from `~/state-hub`:
workplans/REPO-WP-NNNN-<slug>.md ← write this first
``` ```bash
Then register in the hub: make fix-consistency REPO=core-hub
```
create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
``` ```
**Step 5 — Record the setup** **Step 5 - Record progress**
``` Post a non-secret progress note to State Hub summarizing the setup or implementation work.
add_progress_event(
summary="First session: structured infotech into N workstreams, M tasks",
event_type="milestone",
topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
detail={"workstreams": [...], "tasks_created": M}
)
```
<!-- Delete or archive this file once past first session -->

5
.claude/rules/repo-identity.md
View File

@@ -1,5 +1,6 @@
**Purpose:** Git repository template to bootstrap coulomb projects. **Purpose:** 3rd-generation production interaction framework for Coulomb / Helixforge.
**Domain:** infotech **Domain:** infotech
**Repo slug:** repo-seed **Repo slug:** core-hub
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a **Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
**Workplan prefix:** CORE-WP-

79
.claude/rules/session-protocol.md
View File

@@ -1,85 +1,48 @@
## Session Protocol ## Session Protocol
Dev Hub (State Hub API): http://127.0.0.1:8000 Dev Hub (State Hub API): http://127.0.0.1:8000
MCP server name in `~/.claude.json`: `dev-hub`
**Step 1 — Orient** **Step 1 - Orient**
Read the offline-safe brief first — it works without a live hub connection:
```bash ```bash
cat .custodian-brief.md cat .custodian-brief.md
cat INTENT.md
cat SCOPE.md
ls workplans/
``` ```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
``` Use REST when MCP tools are unavailable:
get_domain_summary("infotech")
```
If MCP tools are unavailable in the current agent session, use the REST API:
```bash ```bash
curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" | python3 -m json.tool
``` ```
If the hub is offline: `cd ~/state-hub && make api`
**Step 2 — Check inbox** **Step 2 - Check inbox**
With MCP tools:
```
get_messages(to_agent="repo-seed", unread_only=True)
```
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
requests before proceeding.
Without MCP tools:
```bash ```bash
curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \ curl -s "http://127.0.0.1:8000/messages/?to_agent=core-hub&unread_only=true" | python3 -m json.tool
| python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
``` ```
**Step 3 — Scan workplans** Mark read when handled.
**Step 3 - Scan workplans**
```bash ```bash
ls workplans/ ls workplans/
``` ```
For each file with `status: ready`, `active`, or `blocked`, note pending
`wait`/`todo`/`progress` tasks.
**Step 4 — Present brief** For each file with `status: ready`, `active`, or `blocked`, note pending `wait`/`todo`/`progress` tasks.
1. **Active workstreams** for `infotech` — title, task counts, blocking decisions **Step 4 - Work file-first**
2. **Pending tasks** from `workplans/` + any `[repo:repo-seed]` hub tasks
3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
- `alignment_warnings`: flag if active work is not aligned with current goal
4. **Suggested next action** — highest-priority open item
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
If no workstreams: follow First Session Protocol (`first-session.md`). State Hub is a read/cache/index layer. Work structure belongs in repo files under ADR-001.
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` **Session close**
> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
**Session close:**
With MCP tools:
```
add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
```
Without MCP tools:
```bash ```bash
cd ~/state-hub
make fix-consistency REPO=core-hub
curl -s -X POST http://127.0.0.1:8000/progress/ \ curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}' -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","event_type":"note","summary":"what changed","author":"codex"}'
``` ```
If workplan files were modified, ensure the local copy is up to date first:
```bash
git -C <repo_path> pull --ff-only
cd ~/state-hub && make fix-consistency REPO=repo-seed
```
For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the combined target which pulls before fixing:
```bash
cd ~/state-hub && make fix-consistency-remote REPO=repo-seed
```
**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
will sync the file to match DB. **C-16** (repo behind remote) blocks all writes
until you pull — intentional to prevent clobbering remote progress.

35
.claude/rules/stack-and-commands.md
View File

@@ -1,27 +1,36 @@
## Stack ## Stack
- **Language:** Markdown-first registry and planning repo (no application runtime yet) Current repo state: Markdown/specification-first planning repo. Implementation workplans target the following stack once source code is added:
- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml`
- Python 3.12
- FastAPI, Pydantic v2
- SQLAlchemy async, Alembic, asyncpg, Postgres
- httpx for service clients
- pytest for unit, API, contract, and migration tests
- OpenAPI and JSON Schema for public contracts
- whynot-design aligned UI components/adapters where operator UI is needed
## Dev Commands ## Dev Commands
```bash ```bash
# Orient (offline-safe) # Orient
cat .custodian-brief.md cat .custodian-brief.md
cat README.md cat INTENT.md
cat SCOPE.md cat SCOPE.md
ls workplans/ ls workplans/
# Consumer bootstrap docs # Review core docs
cat docs/statehub-register.md cat docs/specs/README.md
cat docs/template-validation-checklist.md cat docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md
# After workplan or registry edits — from ~/state-hub # After workplan edits, from ~/state-hub
make fix-consistency REPO=repo-seed make fix-consistency REPO=core-hub
# Validate registry entries (from reuse-surface checkout) # Sanity-check markdown/registry edits
reuse-surface validate --root .
# Sanity-check markdown / registry edits
git diff --check git diff --check
# Registry validation, from a checkout with reuse-surface CLI available
reuse-surface validate --root .
``` ```
Add concrete `install`, `test`, `lint`, `build`, and `run` commands in this file when the FastAPI implementation lands.

15
.repo-classification.yaml
View File

@@ -1,18 +1,23 @@
repo_classification: repo_classification:
standard: Repo Classification Standard standard: Repo Classification Standard
version: '1.0' version: '1.0'
classified_at: '2026-06-22' classified_at: '2026-06-27'
classified_by: agent classified_by: agent
category: tooling category: project
domain: infotech domain: infotech
secondary_domains: [] secondary_domains: []
capability_tags: capability_tags:
- interaction-framework
- state-coordination
- agent-coordination
- platform - platform
- configuration - api
- documentation - registry
business_stake: business_stake:
- technology - technology
- execution - execution
business_mechanics: business_mechanics:
- operation - operation
notes: Git template for bootstrapping coulomb projects. - coordination
- control
notes: Third-generation production interaction framework replacing Inter-Hub goals on the natural Coulomb stack.

155
AGENTS.md
View File

@@ -1,20 +1,19 @@
# Repo Seed — Agent Instructions # Core Hub - Agent Instructions
## Repo Identity ## Repo Identity
**Purpose:** Git repository template to bootstrap coulomb projects. **Purpose:** 3rd-generation production interaction framework for Coulomb / Helixforge. Reimagines and replaces the 2nd-generation Inter-Hub framework goals on a practical contract-first Python/FastAPI/Postgres platform.
**Domain:** infotech **Domain:** infotech
**Repo slug:** repo-seed **Repo slug:** core-hub
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` **Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `REPO-WP-` **Workplan prefix:** `CORE-WP-`
--- ---
## State Hub Integration ## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST — The Custodian State Hub tracks work across all domains. Interact via HTTP REST - there is no MCP server for Codex agents.
there is no MCP server for Codex agents.
| Context | URL | | Context | URL |
|---------|-----| |---------|-----|
@@ -24,25 +23,19 @@ there is no MCP server for Codex agents.
### Orient at session start ### Orient at session start
```bash ```bash
# Offline brief — works without hub connection
cat .custodian-brief.md cat .custodian-brief.md
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" | python3 -m json.tool
# Active workstreams for this domain curl -s "http://127.0.0.1:8000/messages/?to_agent=core-hub&unread_only=true" | python3 -m json.tool
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \
| python3 -m json.tool
``` ```
Mark a message read: Mark a message read:
```bash ```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \ curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}' -H "Content-Type: application/json" -d '{}'
``` ```
### Log progress (required at session close) ### Log progress at session close
```bash ```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \ curl -s -X POST http://127.0.0.1:8000/progress/ \
@@ -64,156 +57,86 @@ Omit `workstream_id` / `task_id` when not applicable.
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"status": "progress"}' -d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
``` ```
### Flag a task for human review Status values: `wait | todo | progress | done | cancel`.
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
--- ---
## Session Protocol ## Session Protocol
**Start:** **Start:**
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) 1. `cat .custodian-brief.md` - domain goal and open workstreams.
2. Check inbox: `GET /messages/?to_agent=repo-seed&unread_only=true`; mark read 2. Check inbox: `GET /messages/?to_agent=core-hub&unread_only=true`; mark read when acted on.
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks 3. Scan workplans: `ls workplans/` and inspect `ready`, `active`, or `blocked` files.
4. Check human-needed tasks: `GET /tasks/?needs_human=true` 4. Check human-needed tasks: `GET /tasks/?needs_human=true` when the work may touch operational gates.
**During work:** **During work:**
- Update task statuses in workplan files as tasks progress - Update workplan files first; State Hub is the read/cache/index layer.
- Record significant decisions via `POST /decisions/` - Record significant decisions via `POST /decisions/` when available.
- Keep secrets out of Git, State Hub, workplans, logs, and chat.
**Close:** **Close:**
1. Update workplan file task statuses to reflect progress 1. Update workplan statuses.
2. Log: `POST /progress/` with a summary of what changed 2. From `~/state-hub`, run `make fix-consistency REPO=core-hub` after workplan changes.
3. Note for the custodian operator: after workplan file changes, run from 3. Log progress with `POST /progress/`.
`~/state-hub`:
```bash
make fix-consistency REPO=repo-seed
```
This syncs task status from files into the hub DB.
--- ---
## Credential and access routing ## Credential and Access Routing
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** Before requesting secrets, API keys, SSH access, login tokens, or database passwords, route the need through ops-warden/OpenBao/key-cape ownership.
for inference. Run this check **before** requesting secrets, API keys, SSH access,
login tokens, or database passwords — in any repo, not only `ops-warden`.
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
other credential need belongs to another subsystem. **Do not** message
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
### Lookup (do this first)
```bash ```bash
warden route find "<describe your need>" --json warden route find "<describe your need>" --json
warden route show <catalog-id> --json warden route show <catalog-id> --json
``` ```
Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). ops-warden issues SSH certificates only. API keys, DB passwords, provider tokens, login/OIDC/MFA, authorization decisions, and OpenBao leases belong to their owning subsystems. Do not paste secrets into Git, State Hub, workplans, logs, or chat.
| Agent runtime | How to orient |
| --- | --- |
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=repo-seed` is for coordination, not secret vending |
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
### Quick routing table
| I need… | Owner | ops-warden executes? |
| --- | --- | --- |
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
| Authorization decision | flex-auth | No — route only |
| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
### Anti-patterns (do not do these)
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
- Pasting secrets into Git, State Hub, workplans, logs, or chat
### Other capabilities (reuse-surface)
Non-credential capabilities are usually discovered through **reuse-surface** federation
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
every repo's agent instructions because it is high-frequency, high-risk, and easy to
get wrong.
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
--- ---
## Workplan Convention (ADR-001) ## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a Work items originate as files in this repo, not in the hub. The hub rebuilds from files.
read/cache/index layer that rebuilds from files.
**File location:** `workplans/REPO-WP-NNNN-<slug>.md` **File location:** `workplans/CORE-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to **Archived location:** finished workplans may move to `workplans/archived/YYMMDD-CORE-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is the completion/archive date; the frontmatter `id` does not change.
`workplans/archived/YYMMDD-REPO-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use **Ad Hoc Tasks:** small opportunistic fixes discovered during a session use `workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use this only for low-risk work completed directly.
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
**Frontmatter:** **Frontmatter:**
```yaml ```yaml
--- ---
id: REPO-WP-NNNN id: CORE-WP-NNNN
type: workplan type: workplan
title: "..." title: "..."
domain: infotech domain: infotech
repo: repo-seed repo: core-hub
status: proposed | ready | active | blocked | backlog | finished | archived status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex owner: codex
topic_slug: ... topic_slug: custodian
created: "YYYY-MM-DD" created: "YYYY-MM-DD"
updated: "YYYY-MM-DD" updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit state_hub_workstream_id: "<uuid>" # written by fix-consistency - do not edit
--- ---
``` ```
Use `proposed` for a new draft, `ready` after review against current repo Task block format:
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Task block format** (one per `##` section): ````markdown
```
## Task Title ## Task Title
` ` `task ```task
id: REPO-WP-NNNN-T01 id: CORE-WP-NNNN-T01
status: wait | todo | progress | done | cancel status: wait | todo | progress | done | cancel
priority: high | medium | low priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit state_hub_task_id: "<uuid>" # written by fix-consistency - do not edit
` ` `
Task description text.
``` ```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. Task description text.
````
To create a new workplan: Status progression: `todo` -> `progress` -> `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=repo-seed`
(or send a message to the hub agent via `POST /messages/`)

2
CLAUDE.md
View File

@@ -1,4 +1,4 @@
# Repo Seed — Claude Code Instructions # Core Hub - Claude Code Instructions
@SCOPE.md @SCOPE.md
@.claude/rules/repo-identity.md @.claude/rules/repo-identity.md

40
INTENT.md Normal file
View File

@@ -0,0 +1,40 @@
# INTENT - Core Hub
## Purpose
Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.
It rebuilds the goals of the 2nd-generation Inter-Hub idea on a practical production stack: contract-first, Python/FastAPI/Postgres at the service layer, explicit compatibility tests, and UI patterns that can flow from the whynot-design process without binding the system to one framework or one agent runtime.
## Lineage
- Generation 1: `state-hub` proved file-backed workplans, State Hub read models, progress events, messages, tasks, and agent coordination.
- Generation 2: `inter-hub` introduced the broader hub framework idea: separate domain hubs, shared manifests, widgets, registries, events, and a unified operator surface. The idea was right, but the Haskell/IHP/Nix path was too heavy for the available infrastructure.
- Generation 3: `core-hub` keeps the Inter-Hub ambition but makes it operationally ordinary: simple local development, fast tests, visible contracts, migration discipline, and deployment through the existing Railiance platform rather than a bespoke Haskell build lane.
## Product Intent
Core Hub should become the production interaction substrate where domains publish state, capabilities, evidence, decisions, workplans, agent messages, registry facts, and operator UI components through one coherent framework.
The framework must be usable by humans and agents. Human operators need a stable console and clear audit trail. Agents need typed APIs, predictable workflows, and durable contract documentation. Downstream hubs need a way to integrate without inheriting Core Hub internals.
## Core Principles
1. Contract first: schemas, OpenAPI, event catalogs, capability manifests, and compatibility tests precede implementation convenience.
2. Adapter friendly: the core model is independent from any one UI or service framework. Implementations consume the contract, they do not become the contract.
3. Operationally light: local setup, tests, and deployment must fit the natural Coulomb stack and avoid special-purpose Haskell/Nix build paths.
4. Migration honest: Core Hub preserves the useful Inter-Hub semantics while making incompatibilities explicit and testable.
5. Credential-safe: no secrets in Git, State Hub, workplans, logs, or chat. Credential ownership follows the ops-warden/OpenBao/key-cape routing model.
6. Agent-native: workplans remain file-first, State Hub remains a read/cache/index layer until Core Hub intentionally replaces or absorbs that role.
## Initial Platform Direction
- Backend: Python 3.12, FastAPI, Pydantic v2, SQLAlchemy async, Alembic, asyncpg/Postgres, httpx.
- Contracts: OpenAPI, JSON Schema, SQL/Alembic migrations, registry YAML/Markdown where appropriate.
- Tests: pytest, contract fixtures, API compatibility tests, migration checks.
- UI: whynot-design aligned tokens and Lit/custom-element adapters where UI components are needed; avoid locking the framework to React.
- Deployment: Docker/Kubernetes/ArgoCD/Gitea or Forgejo workflows on the normal platform path; no GHC/IHP/Nix build dependency for the new framework.
## Current State
This repo has been re-bound from the `repo-seed` template into the Core Hub planning and specification home. The first implementation work is organized around contract extraction, FastAPI/Postgres foundation, Inter-Hub compatibility, data migration, operator UI, and retirement of the Haskell build lane after cutover.

41
README.md
View File

@@ -1,22 +1,37 @@
# Core Hub # Core Hub
This is the 3rd Generation Production Interaction Framework for Coulomb / Helixforge Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.
- It is to superseeds and replace 1st Generation state-hub and 2nd Generation inter-hub with state-hub and others infrastructure.
It carries forward the lessons from State Hub and Inter-Hub: workplans and progress need to be durable, domains need typed ways to publish state and evidence, operators need a coherent console, and agents need APIs that are predictable enough to automate against. The rebuild moves that intent onto a lighter production platform.
# repo-seed ## Generations
A git repository template to bootstrap coulomb projects from. - Gen 1: `state-hub` - file-backed workplans, tasks, progress, messages, and read-model synchronization.
- Gen 2: `inter-hub` - the integrated hub framework idea: manifests, widgets, registries, events, API consumers, and a shared UI, implemented in Haskell/IHP.
- Gen 3: `core-hub` - the same framework ambition rebuilt contract-first on the natural Coulomb stack.
## Bootstrap a new repo ## Initial Stack Direction
1. Clone or copy this template into a new repository. - Python 3.12
2. Run `statehub register` from the new repo root (see [docs/statehub-register.md](docs/statehub-register.md)). - FastAPI and Pydantic v2
3. Complete the generated bootstrap workplan (`*-0001-statehub-bootstrap.md`). - SQLAlchemy async, Alembic, asyncpg, Postgres
4. Sync workplans: `cd ~/state-hub && make fix-consistency REPO=<slug>`. - pytest and contract fixtures
5. Validate with [docs/template-validation-checklist.md](docs/template-validation-checklist.md). - OpenAPI and JSON Schema for public contracts
- whynot-design aligned UI components/adapters where operator UI is needed
- Docker/Kubernetes/ArgoCD on the normal Railiance platform path
## Registry ## Key Documentation
This repo publishes `capability.infotech.repo-template` — see - [INTENT.md](INTENT.md) - purpose, lineage, principles, and platform direction
`registry/capabilities/capability.infotech.repo-template.md`. - [SCOPE.md](SCOPE.md) - repo boundary
- [Research artifact](docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md) - what we learned from State Hub, Inter-Hub, Haskell/IHP, and whynot-design
- [Specs index](docs/specs/README.md) - contract and implementation specification map
- [Workplans](workplans/) - staged implementation plan using ADR-001 workplan files
## Immediate Work
1. Freeze the Core Hub contract and IR.
2. Build the FastAPI/Postgres foundation.
3. Preserve critical Inter-Hub `/api/v2` compatibility for current consumers.
4. Migrate data and cut over production traffic.
5. Retire the Haskell/IHP build lane only after replacement evidence exists.

38
SCOPE.md
View File

@@ -1,31 +1,35 @@
# SCOPE # SCOPE
> Lightweight boundary for agents and contributors. > Boundary for agents and contributors working in Core Hub.
--- ## One-Liner
## One-liner Core Hub is the 3rd-generation production interaction framework for Coulomb / Helixforge.
Git repository template to bootstrap coulomb projects.
---
## Core Idea ## Core Idea
repo-seed is the canonical template for new repos: agent instructions, registry scaffold, and onboarding conventions. Core Hub replaces the Haskell/IHP Inter-Hub implementation with a contract-first Python/FastAPI/Postgres framework for cross-domain state, agent coordination, evidence, registry facts, workplans, and operator interaction surfaces.
---
## In Scope ## In Scope
- Template files for new repo bootstrap - Core Hub intent, research, specs, and implementation workplans
- Documentation for statehub_register usage - Contract/IR definition for hubs, manifests, widgets, events, tasks, progress, messages, decisions, and registry facts
- Registry capability entry for template capability - FastAPI/Postgres implementation planning and eventual service code
- Inter-Hub `/api/v2` compatibility where existing consumers depend on it
--- - Data migration and production cutover planning from Inter-Hub
- Operator UI and whynot-design aligned component/adaptor planning
- Haskell/IHP retirement planning after replacement evidence exists
## Out of Scope ## Out of Scope
- Application runtime code - Continuing to act as a generic repo template
- Owning downstream project implementations - Owning every downstream domain hub implementation
- Storing or vending secrets directly
- Rewriting unrelated consumers before the Core Hub compatibility contract exists
- Retiring production Inter-Hub before migration and smoke evidence exists
## Non-Goals
- Recreate IHP abstractions in Python
- Bind the UI contract to React or any single frontend framework
- Make State Hub disappear before Core Hub proves a compatible replacement path

0
docs/statehub-register.md → docs/archive/repo-seed/statehub-register.md
View File

0
docs/template-validation-checklist.md → docs/archive/repo-seed/template-validation-checklist.md
View File

133
docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md Normal file
View File

@@ -0,0 +1,133 @@
# Core Hub Lineage and Platform Reset Research
Date: 2026-06-27
Author: codex
Status: seed research artifact
## Question
How should Core Hub rebuild the intent of Inter-Hub while retiring Haskell/IHP dependencies and preserving the working infrastructure lessons from State Hub?
## Summary
Core Hub should not be a direct port of the Haskell Inter-Hub codebase. It should be a contract-first rebuild of the production interaction framework idea. The important asset is the framework intent: shared hub manifests, typed events, widgets, registries, API consumers, evidence, and operator surfaces. The costly part was the implementation substrate: Haskell/IHP/Nix/GHC/devenv and the special haskelseed build path.
The recommended posture is to extract the contract, preserve compatibility where current consumers depend on `/api/v2`, then rebuild on the natural Coulomb platform: Python, FastAPI, Pydantic, SQLAlchemy, Alembic, Postgres, pytest, OpenAPI, Docker/Kubernetes, and whynot-design-aligned UI adapters.
## Generation 1: State Hub
State Hub proved several durable ideas:
- Workplans should live in repository files first.
- The hub can act as a read/cache/index layer over files.
- Progress events, tasks, messages, and decisions give agents shared operational memory.
- Simple HTTP/REST plus Postgres is enough to make the coordination loop useful.
- File-first synchronization makes agent work inspectable and recoverable.
Limits observed:
- State Hub is coordination infrastructure, not a full interaction framework.
- It does not naturally model rich domain hub manifests, widgets, registry federation, or UI composition.
- The read-model role should be preserved until a replacement proves compatibility.
## Generation 2: Inter-Hub
Inter-Hub introduced the right higher-level idea: separate domain hubs should publish into a shared framework with manifests, widgets, interaction events, annotations, registries, API consumers, and an integrated operator UI.
Useful surfaces to preserve:
- `/api/v2/hubs`
- `/api/v2/hub-capability-manifests`
- `/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/widget-types`
- `/api/v2/event-types`
- `/api/v2/annotation-categories`
- `/api/v2/policy-scopes`
- `/api/v2/token`
- `/api/v2/openapi.json`
- `/api/v2/openapi.yaml`
- `/api/v2/docs`
- SDK endpoints if existing consumers still use them
Operational blockers observed:
- Haskell/IHP demanded too much local and CI infrastructure.
- Nix/GHC/devenv builds were slow and fragile for this environment.
- The haskelseed path became a production gate instead of an implementation detail.
- Basic API issues, such as Postgres `COUNT(*)` bigint decoding, became hard to prove live because the build/deploy loop was expensive.
- UI ambition was tied to a monolithic framework rather than a neutral component contract.
## Haskell Dependency Boundary
Actual Haskell implementations:
1. `inter-hub`: production framework and API service. High-impact. Retire only after Core Hub compatibility, migration, and cutover evidence.
2. `ihp-railiance-probe`: small IHP/GHC/Nix probe. Low-impact. Can be renamed or archived early.
Haskell support infrastructure:
- haskelseed runner labels and Gitea workflow paths
- `haskell-build` VM and build-agent capability
- IHP/GHC/Nix/devenv setup
- production image build path for Inter-Hub
Protocol consumers that are not Haskell:
- `ops-hub`: Python tooling that calls Inter-Hub `/api/v2` bootstrap endpoints.
- `activity-core`: Python/FastAPI/Temporal stack with optional Inter-Hub sink and State Hub fallback.
- `the-custodian`: planning and workplan gates.
- Other repos mostly reference Inter-Hub protocols, docs, or concepts rather than depending on Haskell directly.
## whynot-design Lesson
The whynot-design direction suggests the right architecture pattern:
- Maintain a canonical design or interaction contract.
- Derive implementation adapters from that contract.
- Keep generated or derived layers distinct from hand-authored behavior.
- Use parity and drift checks rather than assuming codegen solves design.
- Avoid binding the core model to React, IHP, or any single UI framework.
For Core Hub, the equivalent is:
- Contract/IR: schema, OpenAPI, JSON Schema, event catalogs, capability manifests, fixtures, and compatibility tests.
- Runtime adapters: FastAPI service, Python clients, UI component adapters, import/export tools.
- Drift checks: contract tests against legacy Inter-Hub fixtures and known consumers.
## Recommended Core Hub Architecture
Core Hub should be layered:
1. Contract and IR layer: OpenAPI, JSON Schema, SQL/Alembic schema, catalogs, fixtures, and compatibility examples.
2. Service layer: FastAPI, Pydantic v2 DTOs, SQLAlchemy async models, Alembic migrations, asyncpg/Postgres, and httpx clients.
3. Compatibility layer: `/api/v2` routes, response-shape tests, and auth/error semantics.
4. UI layer: operator console, whynot-design tokens/components, and Lit/custom-element adapters where useful.
5. Migration layer: Inter-Hub schema import/export, row-count checks, fixture replay, and dual-run smokes.
## Key Risks
- Accidentally breaking ops-hub bootstrap endpoints.
- Losing Inter-Hub data history during migration.
- Treating API key hashes/prefixes as recoverable secrets. Runtime keys may need approved regeneration.
- Retiring Haskell repos before production traffic has moved.
- Recreating framework coupling by making the UI or service implementation the contract.
## Decision Recommendation
Create Core Hub as the new third-generation repo and proceed in stages:
1. Freeze contract and compatibility scope.
2. Build FastAPI/Postgres baseline.
3. Implement `/api/v2` compatibility for current consumers.
4. Migrate data and run side-by-side smokes.
5. Cut over production DNS/service path.
6. Rename/archive Haskell repos and retire the build infrastructure.
The IHP probe can be retired first. Production Inter-Hub should be renamed to `inter-hub-haskell` only after Core Hub passes compatibility and migration gates.

25
docs/specs/README.md Normal file
View File

@@ -0,0 +1,25 @@
# Core Hub Specs
This directory is the specification map for Core Hub. The specs are intentionally ahead of implementation so the framework contract stays stable while the runtime is rebuilt.
## Spec Set
- [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
- [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
- [Workplan Coordination](workplan-coordination.md) - file-first workplans, tasks, progress, messages, decisions
- [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 Rule
The implementation may change. The contract changes only through a workplan and a compatibility note.
Any route, schema, event type, or manifest field used by existing consumers must have one of:
- preserved behavior;
- documented replacement and migration path;
- explicit cancellation decision with affected consumers listed.

59
docs/specs/api-v2-compatibility.md Normal file
View File

@@ -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.

27
docs/specs/auth-access-and-custody.md Normal file
View File

@@ -0,0 +1,27 @@
# Auth, Access, and Custody Spec
## Purpose
Define Core Hub authentication behavior and credential boundaries without turning Core Hub into a secret-vending system.
## Rules
- Core Hub may authenticate API clients and record non-secret access metadata.
- Core Hub must not store raw provider tokens, database passwords, OpenBao tokens, SSH private keys, or login secrets.
- API key full values are shown only at creation time if Core Hub owns key issuance.
- Stored API key material must be hashed; logs and progress notes must use prefixes or opaque ids only.
- Secret retrieval and custody follow ops-warden/OpenBao/key-cape routing.
## Inter-Hub Compatibility
Core Hub should preserve protected-route behavior expected by existing consumers:
- public registry reads should remain public where they are public today;
- protected write routes should return authorization errors before executing business logic;
- bootstrap flows should support operator-created or approved API consumers;
- rate limiting and request logs should use database types compatible with Postgres.
## Open Questions
- Whether token exchange should remain `/api/v2/token` compatible or become a Core Hub-native auth grant endpoint with compatibility alias.
- Whether API consumers are global, per-hub, or scoped by registry capability.

39
docs/specs/contract-ir.md Normal file
View File

@@ -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.

46
docs/specs/core-hub-architecture.md Normal file
View File

@@ -0,0 +1,46 @@
# Core Hub Architecture Spec
## Goal
Build the production interaction framework as a small set of explicit layers rather than a monolith.
## Layers
1. Contract/IR layer
- OpenAPI
- JSON Schema
- Alembic/SQL schema
- event, widget, and capability catalogs
- fixtures and compatibility examples
2. Runtime service layer
- FastAPI app
- Pydantic v2 request/response DTOs
- SQLAlchemy async persistence
- Alembic migrations
- asyncpg/Postgres
- httpx clients for integration probes
3. Compatibility layer
- Inter-Hub `/api/v2` routes required by current consumers
- auth/error compatibility
- response-shape fixtures
- smoke scripts for ops-hub and activity-core
4. Operator UI layer
- dashboard/console surfaces
- whynot-design aligned tokens/components
- adapter-friendly component model
5. Migration and operations layer
- import/export tools
- row-count and referential checks
- dual-run smokes
- release/cutover runbook
## Boundary Decisions
- Core Hub owns the framework contract and primary implementation.
- Domain hubs own their domain data and domain-specific runtime logic.
- Credential systems keep owning secrets; Core Hub records non-secret evidence and routing metadata only.
- State Hub remains active until Core Hub has a proven compatibility and migration path.

55
docs/specs/data-model.md Normal file
View File

@@ -0,0 +1,55 @@
# Data Model Spec
## Purpose
Define the initial Core Hub entity model and the migration stance from State Hub and Inter-Hub.
## Initial Entity Families
Coordination:
- repositories
- workstreams
- workplans
- tasks
- progress events
- messages
- decisions
Framework:
- hubs
- hub capability manifests
- API consumers
- API keys or key references
- widgets
- widget types
- interaction events
- annotations and annotation threads
- requirements
- decision records
- deployment records
- outcome signals
- policy scopes
- registry facts
Operations:
- request logs
- auth audit metadata
- migration batches
- compatibility fixtures
- import/export runs
## Migration Posture
- Import Inter-Hub schema facts through explicit migrations or import tools, not ad hoc SQL editing.
- Preserve identifiers where consumers or historical references depend on them.
- Treat API key full values as non-recoverable unless an approved custody path says otherwise.
- Store only hashes, prefixes, labels, and non-secret lifecycle metadata.
- Record row counts, relationship checks, and fixture replays for every migration batch.
## Open Questions
- Whether Core Hub owns the canonical workplan task tables or continues reading from State Hub until cutover.
- Whether Inter-Hub admin-only entities should be migrated as historical records or redesigned as Core Hub-native resources.

43
docs/specs/event-and-registry-model.md Normal file
View File

@@ -0,0 +1,43 @@
# Event and Registry Model Spec
## Purpose
Define how domain hubs publish structured facts and interaction evidence into Core Hub.
## Event Principles
- Event types are cataloged.
- Payload schemas are versioned.
- Producers identify hub, repo, actor, source system, and correlation identifiers where available.
- Events are append-oriented; derived read models can be rebuilt.
- Event payloads must not contain secrets.
## Registry Principles
- Capability and manifest records are discoverable.
- Domain hubs publish what they provide, what they consume, and how operators or agents can interact with them.
- Registry entries link to source docs and tests when possible.
- Drift between repo files and Core Hub records is detectable.
## Initial Catalog Families
- hub capability manifests
- widget types and widget instances
- interaction event types
- annotation categories
- policy scopes
- API consumers
- outcome correlations
- capability registry entries
## Acceptance Standard
A registry family is ready when it has:
- schema;
- fixture;
- read endpoint;
- write/upsert path if needed;
- validation errors;
- consumer guidance;
- at least one compatibility or integration test.

35
docs/specs/testing-release-and-migration.md Normal file
View File

@@ -0,0 +1,35 @@
# Testing, Release, and Migration Spec
## Test Layers
- unit tests for models, validators, and services
- API tests for route behavior and auth semantics
- contract tests from fixtures
- migration tests for Alembic revisions and imports
- consumer smokes for ops-hub and activity-core
- optional Playwright visual checks once UI exists
## Release Gates
A Core Hub release cannot replace Inter-Hub until:
- public `/api/v2` compatibility smokes pass;
- protected route auth behavior is proven without exposing secrets;
- ops-hub bootstrap smoke passes;
- activity-core sink smoke passes or is explicitly deferred to State Hub fallback;
- data import row counts and relationship checks pass;
- rollback path is documented;
- production operator approves cutover.
## Migration Gates
- Extract Inter-Hub schema and route inventory.
- Build fixture set from representative production-safe records.
- Import data into Core Hub staging.
- Compare row counts and key relationships.
- Run dual-read or shadow smokes.
- Switch traffic only after smoke evidence is recorded.
## Haskell Retirement Gate
Do not retire production Inter-Hub or the haskelseed/Haskell build lane until Core Hub serves the required compatibility surface and production traffic has moved.

31
docs/specs/ui-operator-console.md Normal file
View File

@@ -0,0 +1,31 @@
# UI and Operator Console Spec
## Purpose
Define the Core Hub operator interface without coupling the framework to one UI runtime.
## UI Direction
- Use whynot-design tokens and component semantics where possible.
- Prefer custom-element/Lit adapters for framework-neutral surfaces.
- Keep the canonical UI contract separate from generated or hand-authored implementation code.
- Use Playwright visual checks once UI components exist.
## Initial Console Areas
- hub registry and health
- active workplans and blocked tasks
- progress/event stream
- messages and agent coordination
- decisions and deployment records
- API consumers and non-secret access metadata
- compatibility/migration dashboard
## Design Constraint
The operator console is an operational tool. It should be dense, readable, and stable, not a marketing surface.
## Open Questions
- Whether initial UI is server-rendered, Lit/custom-element, or a thin static frontend consuming FastAPI.
- Which Inter-Hub admin screens should be preserved as compatibility views vs. redesigned.

33
docs/specs/workplan-coordination.md Normal file
View File

@@ -0,0 +1,33 @@
# Workplan Coordination Spec
## Purpose
Preserve the productive State Hub pattern while Core Hub evolves beyond it.
## File-First Rule
Workplans originate in repo files. Core Hub may index, cache, validate, and display them, but the repo file remains the source of truth until a recorded migration decision changes that rule.
## Core Resources
- workplan files
- workstreams
- tasks
- progress events
- messages
- decisions
- human-needed gates
- blocking reasons
- repo briefs
## Agent Requirements
- Agents can orient offline from repo files.
- Agents can sync to the hub read model after edits.
- Tasks expose status, priority, and blocking notes.
- Progress events are non-secret and audit-friendly.
- Human-needed gates are visible without leaking credentials.
## Compatibility Goal
Core Hub should be able to ingest existing ADR-001 workplans and State Hub records before it attempts to replace State Hub operations.

14
registry/README.md
View File

@@ -1,12 +1,12 @@
# Capability Registry # Capability Registry
Markdown-first capability index for federation and reuse planning. Markdown-first capability index for Core Hub federation and reuse planning.
Core Hub publishes its framework capability here so reuse-surface and related discovery tools can understand what this repo is meant to provide.
## Authoring ## Authoring
1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`). 1. Add or update a capability entry under `registry/capabilities/`.
2. Add the row to `indexes/capabilities.yaml`. 2. Add the row to `registry/indexes/capabilities.yaml`.
3. Run `reuse-surface validate` from a checkout with the CLI installed. 3. Run `reuse-surface validate --root .` from a checkout with the CLI installed.
4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`. 4. Keep capability docs aligned with `INTENT.md`, `SCOPE.md`, and `docs/specs/`.
Federation contract: reuse-surface `docs/RegistryFederation.md`.

0
registry/capabilities/capability.infotech.repo-template.md → registry/capabilities/archived/260627-capability.infotech.repo-template.md
View File

128
registry/capabilities/capability.infotech.core-hub.md Normal file
View File

@@ -0,0 +1,128 @@
---
id: capability.infotech.core-hub
name: Core Hub Production Interaction Framework
summary: Contract-first framework for cross-domain state, agent coordination, evidence, registries, workplans, and operator interaction surfaces.
owner: core-hub
status: draft
domain: infotech
tags:
- interaction-framework
- state-hub
- inter-hub-successor
- agent-coordination
- registry
- api
maturity:
discovery:
current: D3
target: D5
confidence: medium
rationale: >
Intent, scope, lineage research, and initial specs are documented. Detailed
API and data contracts are planned but not yet implemented.
availability:
current: A1
target: A5
confidence: medium
rationale: >
The repo is currently a planning/specification home. Production availability
starts after the FastAPI/Postgres implementation, migration, and cutover workplans land.
external_evidence:
completeness:
level: C1
confidence: medium
basis: initial_spec_seed
satisfied_expectations:
- intent and scope documents
- lineage and platform reset research artifact
- specification map
- staged workplans
broken_expectations:
- runtime implementation is not yet present
- compatibility test harness is not yet present
out_of_scope_expectations:
- direct secret custody
- owning every downstream domain hub implementation
reliability:
level: R1
confidence: medium
basis: no_runtime_yet
known_reliability_risks:
- Inter-Hub compatibility must be proven before cutover
- data migration and API auth semantics require careful operator evidence
- Haskell retirement must wait until replacement runtime is live
discovery:
intent: >
Provide the third-generation production interaction substrate for Coulomb,
preserving the valuable State Hub and Inter-Hub semantics while replacing the
Haskell/IHP implementation path with a lighter contract-first platform.
includes:
- framework contract and IR documentation
- API and event model specs
- workplan, progress, task, message, and decision coordination model
- operator UI and component surface planning
- migration and compatibility planning
excludes:
- direct credential vending
- unrelated downstream app runtimes
- retiring Inter-Hub before compatible replacement evidence exists
assumptions:
- existing consumers can tolerate stable `/api/v2` compatibility during transition
- State Hub remains available while Core Hub is built
- workplans remain canonical in repo files until Core Hub intentionally changes that model
use_cases:
- publish domain hub manifests and capabilities
- emit interaction and evidence events
- coordinate agent-visible workplans and progress
- expose operator console surfaces
research_memos:
- docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md
availability:
current_level: A1
target_level: A5
current_artifacts:
- INTENT.md
- SCOPE.md
- docs/specs/README.md
- workplans/
consumption_modes:
- informational
- planning
relations:
depends_on:
- capability.statehub.workstream-coordinate
supports:
- capability.registry.register
related_to:
- capability.inter-hub.framework
- capability.whynot-design.system
evidence:
documentation:
- INTENT.md
- SCOPE.md
- docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md
- docs/specs/README.md
tests: []
consumer_guidance:
recommended_for:
- planning new domain hub integrations
- replacing Inter-Hub Haskell/IHP consumers through a compatibility layer
- centralizing agent/operator interaction contracts
not_recommended_for:
- production cutover before compatibility and migration evidence exists
- secret custody or credential handoff flows
known_limitations:
- implementation is not yet present
- compatibility contract is seeded but not frozen
---
# Core Hub Production Interaction Framework
Core Hub is the third-generation interaction framework for Coulomb / Helixforge. It keeps the State Hub and Inter-Hub lessons while moving the implementation path to a practical contract-first platform.

18
registry/indexes/capabilities.yaml
View File

@@ -1,14 +1,14 @@
version: 1 version: 1
updated: '2026-06-24' updated: '2026-06-27'
domain: infotech domain: infotech
capabilities: capabilities:
- id: capability.infotech.repo-template - id: capability.infotech.core-hub
name: Coulomb Repository Template name: Core Hub Production Interaction Framework
summary: Bootstrap new git repositories with agent instructions, registry scaffold, and State Hub onboarding conventions. summary: Contract-first framework for cross-domain state, agent coordination, evidence, registries, workplans, and operator interaction surfaces.
vector: D3 / A3 / C2 / R2 vector: D3 / A1 / C1 / R1
domain: infotech domain: infotech
status: draft status: draft
owner: repo-seed owner: core-hub
path: registry/capabilities/capability.infotech.repo-template.md path: registry/capabilities/capability.infotech.core-hub.md
tags: [template, bootstrap, state-hub, onboarding] tags: [interaction-framework, state-hub, inter-hub-successor, agent-coordination, registry, api]
consumption_modes: [git clone, informational] consumption_modes: [informational, planning]

50
workplans/CORE-WP-0001-statehub-bootstrap.md Normal file
View File

@@ -0,0 +1,50 @@
---
id: CORE-WP-0001
type: workplan
title: "Bootstrap Core Hub repository identity"
domain: infotech
repo: core-hub
status: finished
owner: codex
topic_slug: custodian
created: "2026-06-27"
updated: "2026-06-27"
state_hub_workstream_id: "f20d57e6-6b3f-49d0-81d6-75325a869599"
---
# Bootstrap Core Hub repository identity
Core Hub is the 3rd-generation production interaction and coordination framework for Coulomb / Helixforge, intended to rebuild the useful goals of State Hub and Inter-Hub on a practical production stack.
## Review Generated Integration Files
```task
id: CORE-WP-0001-T01
status: done
priority: high
state_hub_task_id: "25445710-84c1-4f19-8003-c0bfbd349154"
```
Result 2026-06-27: Rebound `INTENT.md`, `SCOPE.md`, `README.md`, `AGENTS.md`, Claude rules, registry metadata, and capability index from repo-seed identity to Core Hub identity.
## Verify Local Developer Workflow
```task
id: CORE-WP-0001-T02
status: done
priority: high
state_hub_task_id: "ae7cb4ba-c6d9-466b-834f-d349900eca09"
```
Result 2026-06-27: Documented the current markdown/specification workflow and the intended implementation stack in `.claude/rules/stack-and-commands.md`. Concrete install/test/lint/build/run commands will be added by the FastAPI foundation workplan once runtime code exists.
## Seed First Real Workplan
```task
id: CORE-WP-0001-T03
status: done
priority: medium
state_hub_task_id: "09ee5a5a-e754-4217-9850-d07179562a75"
```
Result 2026-06-27: Seeded Core Hub implementation workplans for contract extraction, FastAPI/Postgres foundation, Inter-Hub compatibility, data migration/cutover, operator UI, and Haskell retirement.

61
workplans/CORE-WP-0002-contract-ir-freeze.md Normal file
View File

@@ -0,0 +1,61 @@
---
id: CORE-WP-0002
type: workplan
title: "Freeze Core Hub contract and IR"
domain: infotech
repo: core-hub
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-27"
updated: "2026-06-27"
state_hub_workstream_id: "d3f0f41e-5029-4064-8f0b-26f2f36d883b"
---
# Freeze Core Hub contract and IR
Extract the canonical framework contract from State Hub, Inter-Hub, ops-hub, activity-core, and whynot-design lessons before implementing runtime code.
## Inventory Legacy Contracts
```task
id: CORE-WP-0002-T01
status: todo
priority: high
state_hub_task_id: "20b45f1d-76af-4dde-903c-76be97e33169"
```
Inventory Inter-Hub routes, schemas, migrations, fixtures, registries, auth behavior, and current consumer expectations. Record the inventory under `docs/specs/` with links to source repos.
## Define Core Hub IR Artifacts
```task
id: CORE-WP-0002-T02
status: todo
priority: high
state_hub_task_id: "010604c8-b71e-4611-bd48-07eaaec50651"
```
Create initial OpenAPI, JSON Schema, event catalog, widget catalog, hub manifest schema, and fixture structure. The IR must be implementation-neutral and adapter-friendly.
## Capture Compatibility Fixtures
```task
id: CORE-WP-0002-T03
status: todo
priority: high
state_hub_task_id: "819c2d8e-c232-4390-98b6-ff37df592c4c"
```
Create production-safe request/response fixtures for public and protected `/api/v2` surfaces used by ops-hub and activity-core. Include auth/error fixtures without secrets.
## Record Contract Governance
```task
id: CORE-WP-0002-T04
status: todo
priority: medium
state_hub_task_id: "327e086d-5d56-4f72-bfdf-ce3b66fff15e"
```
Document how contracts change, how compatibility notes are written, and how consumers are notified.

61
workplans/CORE-WP-0003-fastapi-postgres-foundation.md Normal file
View File

@@ -0,0 +1,61 @@
---
id: CORE-WP-0003
type: workplan
title: "Build FastAPI/Postgres foundation"
domain: infotech
repo: core-hub
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-27"
updated: "2026-06-27"
state_hub_workstream_id: "ef913c8c-2a50-4970-9a9d-0cb65dc996cd"
---
# Build FastAPI/Postgres foundation
Create the first Core Hub runtime on the natural Coulomb stack.
## Scaffold Python Project
```task
id: CORE-WP-0003-T01
status: todo
priority: high
state_hub_task_id: "3db032d8-7ac6-424e-8bbe-3debd332241b"
```
Add Python packaging, app layout, dependency declaration, local dev commands, and test runner. Target Python 3.12, FastAPI, Pydantic v2, SQLAlchemy async, Alembic, asyncpg, httpx, and pytest.
## Add Health and OpenAPI Baseline
```task
id: CORE-WP-0003-T02
status: todo
priority: high
state_hub_task_id: "d01d6169-a0c6-4689-b986-49ea6cd218b9"
```
Implement health/readiness endpoints and generated OpenAPI. Ensure local run/test commands are documented in agent rules.
## Add Database Foundation
```task
id: CORE-WP-0003-T03
status: todo
priority: high
state_hub_task_id: "23c57f3e-425e-47d8-9fb5-9cc6366f2167"
```
Create SQLAlchemy base models, Alembic configuration, initial migrations, async database session wiring, and test database fixtures.
## Add CI-Ready Checks
```task
id: CORE-WP-0003-T04
status: todo
priority: medium
state_hub_task_id: "a1790376-3f63-4eed-8f2f-c059eb1304db"
```
Add formatting/lint/test commands suitable for the normal platform workflow. Avoid Haskell/Nix/devenv dependencies.

0
workplans/REPO-WP-0001-statehub-bootstrap.md → workplans/archived/260627-REPO-WP-0001-statehub-bootstrap.md
View File

0
workplans/REPO-WP-0002-template-validation-checklist.md → workplans/archived/260627-REPO-WP-0002-template-validation-checklist.md
View File