diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index 7c2a645..31cbd85 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -1,8 +1,18 @@ ## Architecture - +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. + +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 -`~/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 diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index 368ae12..1528363 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -1,38 +1,26 @@ ## First Session Protocol -Triggered when `get_domain_summary("infotech")` shows **no workstreams**. -The project is registered but work has not yet been structured. +Triggered when State Hub shows no workstreams for `core-hub`. -**Step 1 — Read, don't write** -- `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope -- `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases -- Scan repo root: README, directory structure, existing code or docs +**Step 1 - Read, do not write yet** +- `INTENT.md` +- `SCOPE.md` +- `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** -Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. +**Step 2 - Survey in-progress work** +Look for untracked files, open workplans, and half-finished specs. Note done vs. started but incomplete. -**Step 3 — Propose workstreams to Bernd** -Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a -roadmap phase. **Wait for approval before creating.** +**Step 3 - Structure work in files first** +Create or update `workplans/CORE-WP-NNNN-.md` before relying on State Hub records. -**Step 4 — Create workplan file first, then DB record (ADR-001)** -``` -workplans/REPO-WP-NNNN-.md ← write this first -``` -Then register in the hub: -``` -create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...") -create_task(workstream_id="", title="...", priority="high|medium|low") +**Step 4 - Sync the read model** +After workplan changes, run from `~/state-hub`: + +```bash +make fix-consistency REPO=core-hub ``` -**Step 5 — Record the setup** -``` -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} -) -``` - - +**Step 5 - Record progress** +Post a non-secret progress note to State Hub summarizing the setup or implementation work. diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 3ccf329..c1cddfc 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -1,5 +1,6 @@ -**Purpose:** Git repository template to bootstrap coulomb projects. +**Purpose:** 3rd-generation production interaction framework for Coulomb / Helixforge. **Domain:** infotech -**Repo slug:** repo-seed +**Repo slug:** core-hub **Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a +**Workplan prefix:** CORE-WP- diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 800d2b2..13586e2 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -1,85 +1,48 @@ ## Session Protocol 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 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: -``` -get_domain_summary("infotech") -``` -If MCP tools are unavailable in the current agent session, use the REST API: + +Use REST when MCP tools are unavailable: + ```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** -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. +**Step 2 - Check inbox** -Without MCP tools: ```bash -curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \ - | python3 -m json.tool -curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ - -H "Content-Type: application/json" -d '{}' +curl -s "http://127.0.0.1:8000/messages/?to_agent=core-hub&unread_only=true" | python3 -m json.tool ``` -**Step 3 — Scan workplans** +Mark read when handled. + +**Step 3 - Scan workplans** + ```bash 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 -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 +**Step 4 - Work file-first** -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="") -``` -Without MCP tools: ```bash +cd ~/state-hub +make fix-consistency REPO=core-hub curl -s -X POST http://127.0.0.1:8000/progress/ \ -H "Content-Type: application/json" \ - -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"","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 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. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index ca469c0..b3fa31f 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,27 +1,36 @@ ## Stack -- **Language:** Markdown-first registry and planning repo (no application runtime yet) -- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml` +Current repo state: Markdown/specification-first planning repo. Implementation workplans target the following stack once source code is added: + +- 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 ```bash -# Orient (offline-safe) +# Orient cat .custodian-brief.md -cat README.md +cat INTENT.md cat SCOPE.md ls workplans/ -# Consumer bootstrap docs -cat docs/statehub-register.md -cat docs/template-validation-checklist.md +# Review core docs +cat docs/specs/README.md +cat docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md -# After workplan or registry edits — from ~/state-hub -make fix-consistency REPO=repo-seed +# After workplan edits, from ~/state-hub +make fix-consistency REPO=core-hub -# Validate registry entries (from reuse-surface checkout) -reuse-surface validate --root . - -# Sanity-check markdown / registry edits +# Sanity-check markdown/registry edits 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. diff --git a/.repo-classification.yaml b/.repo-classification.yaml index ea7b5f4..ea93e82 100644 --- a/.repo-classification.yaml +++ b/.repo-classification.yaml @@ -1,18 +1,23 @@ repo_classification: standard: Repo Classification Standard version: '1.0' - classified_at: '2026-06-22' + classified_at: '2026-06-27' classified_by: agent - category: tooling + category: project domain: infotech secondary_domains: [] capability_tags: + - interaction-framework + - state-coordination + - agent-coordination - platform - - configuration - - documentation + - api + - registry business_stake: - technology - execution business_mechanics: - 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. diff --git a/AGENTS.md b/AGENTS.md index d61b5dd..c0a2e06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,20 +1,19 @@ -# Repo Seed — Agent Instructions +# Core Hub - Agent Instructions ## 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 -**Repo slug:** repo-seed +**Repo slug:** core-hub **Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` -**Workplan prefix:** `REPO-WP-` +**Workplan prefix:** `CORE-WP-` --- ## State Hub Integration -The Custodian State Hub tracks work across all domains. Interact via HTTP REST — -there is no MCP server for Codex agents. +The Custodian State Hub tracks work across all domains. Interact via HTTP REST - there is no MCP server for Codex agents. | Context | URL | |---------|-----| @@ -24,25 +23,19 @@ there is no MCP server for Codex agents. ### Orient at session start ```bash -# Offline brief — works without hub connection cat .custodian-brief.md - -# Active workstreams for this domain -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 +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" | python3 -m json.tool +curl -s "http://127.0.0.1:8000/messages/?to_agent=core-hub&unread_only=true" | python3 -m json.tool ``` Mark a message read: + ```bash curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ -H "Content-Type: application/json" -d '{}' ``` -### Log progress (required at session close) +### Log progress at session close ```bash 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/" \ -H "Content-Type: application/json" \ -d '{"status": "progress"}' -# values: wait | todo | progress | done | cancel ``` -### Flag a task for human review - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"needs_human": true, "intervention_note": "reason"}' -``` +Status values: `wait | todo | progress | done | cancel`. --- ## Session Protocol **Start:** -1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) -2. Check inbox: `GET /messages/?to_agent=repo-seed&unread_only=true`; mark read -3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks -4. Check human-needed tasks: `GET /tasks/?needs_human=true` +1. `cat .custodian-brief.md` - domain goal and open workstreams. +2. Check inbox: `GET /messages/?to_agent=core-hub&unread_only=true`; mark read when acted on. +3. Scan workplans: `ls workplans/` and inspect `ready`, `active`, or `blocked` files. +4. Check human-needed tasks: `GET /tasks/?needs_human=true` when the work may touch operational gates. **During work:** -- Update task statuses in workplan files as tasks progress -- Record significant decisions via `POST /decisions/` +- Update workplan files first; State Hub is the read/cache/index layer. +- Record significant decisions via `POST /decisions/` when available. +- Keep secrets out of Git, State Hub, workplans, logs, and chat. **Close:** -1. Update workplan file task statuses to reflect progress -2. Log: `POST /progress/` with a summary of what changed -3. Note for the custodian operator: after workplan file changes, run from - `~/state-hub`: - ```bash - make fix-consistency REPO=repo-seed - ``` - This syncs task status from files into the hub DB. +1. Update workplan statuses. +2. From `~/state-hub`, run `make fix-consistency REPO=core-hub` after workplan changes. +3. Log progress with `POST /progress/`. --- -## Credential and access routing +## Credential and Access Routing -**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** -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) +Before requesting secrets, API keys, SSH access, login tokens, or database passwords, route the need through ops-warden/OpenBao/key-cape ownership. ```bash warden route find "" --json warden route show --json ``` -Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). - -| 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` - - - +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. --- ## Workplan Convention (ADR-001) -Work items originate as files in this repo — not in the hub. The hub is a -read/cache/index layer that rebuilds from files. +Work items originate as files in this repo, not in the hub. The hub rebuilds from files. -**File location:** `workplans/REPO-WP-NNNN-.md` +**File location:** `workplans/CORE-WP-NNNN-.md` -**Archived location:** finished workplans may move to -`workplans/archived/YYMMDD-REPO-WP-NNNN-.md`. The `YYMMDD` prefix is -the completion/archive date; the frontmatter `id` does not change. +**Archived location:** finished workplans may move to `workplans/archived/YYMMDD-CORE-WP-NNNN-.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 -`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. +**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. **Frontmatter:** ```yaml --- -id: REPO-WP-NNNN +id: CORE-WP-NNNN type: workplan title: "..." domain: infotech -repo: repo-seed +repo: core-hub status: proposed | ready | active | blocked | backlog | finished | archived owner: codex -topic_slug: ... +topic_slug: custodian created: "YYYY-MM-DD" updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # written by fix-consistency — do not edit +state_hub_workstream_id: "" # written by fix-consistency - do not edit --- ``` -Use `proposed` for a new draft, `ready` after review against current repo -state, and `finished` after implementation. `stalled` and `needs_review` are -derived health labels, not frontmatter statuses. +Task block format: -**Task block format** (one per `##` section): - -``` +````markdown ## Task Title -` ` `task -id: REPO-WP-NNNN-T01 +```task +id: CORE-WP-NNNN-T01 status: wait | todo | progress | done | cancel priority: high | medium | low -state_hub_task_id: "" # written by fix-consistency — do not edit -` ` ` - -Task description text. +state_hub_task_id: "" # written by fix-consistency - do not edit ``` -Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. +Task description text. +```` -To create a new workplan: -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/`) +Status progression: `todo` -> `progress` -> `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. diff --git a/CLAUDE.md b/CLAUDE.md index a01c656..5da3ca4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# Repo Seed — Claude Code Instructions +# Core Hub - Claude Code Instructions @SCOPE.md @.claude/rules/repo-identity.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..ba906fe --- /dev/null +++ b/INTENT.md @@ -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. diff --git a/README.md b/README.md index 0c2b9a1..160159c 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,37 @@ # Core Hub -This 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. +Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge. +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. -2. Run `statehub register` from the new repo root (see [docs/statehub-register.md](docs/statehub-register.md)). -3. Complete the generated bootstrap workplan (`*-0001-statehub-bootstrap.md`). -4. Sync workplans: `cd ~/state-hub && make fix-consistency REPO=`. -5. Validate with [docs/template-validation-checklist.md](docs/template-validation-checklist.md). +- Python 3.12 +- FastAPI and Pydantic v2 +- SQLAlchemy async, Alembic, asyncpg, Postgres +- pytest and contract fixtures +- 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 -`registry/capabilities/capability.infotech.repo-template.md`. \ No newline at end of file +- [INTENT.md](INTENT.md) - purpose, lineage, principles, and platform direction +- [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. diff --git a/SCOPE.md b/SCOPE.md index 802fd33..39e236f 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,31 +1,35 @@ # SCOPE -> Lightweight boundary for agents and contributors. +> Boundary for agents and contributors working in Core Hub. ---- +## One-Liner -## One-liner - -Git repository template to bootstrap coulomb projects. - ---- +Core Hub is the 3rd-generation production interaction framework for Coulomb / Helixforge. ## 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 -- Template files for new repo bootstrap -- Documentation for statehub_register usage -- Registry capability entry for template capability - ---- +- Core Hub intent, research, specs, and implementation workplans +- Contract/IR definition for hubs, manifests, widgets, events, tasks, progress, messages, decisions, and registry facts +- 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 -- Application runtime code -- Owning downstream project implementations +- Continuing to act as a generic repo template +- 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 diff --git a/docs/statehub-register.md b/docs/archive/repo-seed/statehub-register.md similarity index 100% rename from docs/statehub-register.md rename to docs/archive/repo-seed/statehub-register.md diff --git a/docs/template-validation-checklist.md b/docs/archive/repo-seed/template-validation-checklist.md similarity index 100% rename from docs/template-validation-checklist.md rename to docs/archive/repo-seed/template-validation-checklist.md diff --git a/docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md b/docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md new file mode 100644 index 0000000..4736367 --- /dev/null +++ b/docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md @@ -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. diff --git a/docs/specs/README.md b/docs/specs/README.md new file mode 100644 index 0000000..48c4e8d --- /dev/null +++ b/docs/specs/README.md @@ -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. diff --git a/docs/specs/api-v2-compatibility.md b/docs/specs/api-v2-compatibility.md new file mode 100644 index 0000000..5d6e1db --- /dev/null +++ b/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. diff --git a/docs/specs/auth-access-and-custody.md b/docs/specs/auth-access-and-custody.md new file mode 100644 index 0000000..c1869b0 --- /dev/null +++ b/docs/specs/auth-access-and-custody.md @@ -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. diff --git a/docs/specs/contract-ir.md b/docs/specs/contract-ir.md new file mode 100644 index 0000000..83e2b87 --- /dev/null +++ b/docs/specs/contract-ir.md @@ -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. diff --git a/docs/specs/core-hub-architecture.md b/docs/specs/core-hub-architecture.md new file mode 100644 index 0000000..ec2053b --- /dev/null +++ b/docs/specs/core-hub-architecture.md @@ -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. diff --git a/docs/specs/data-model.md b/docs/specs/data-model.md new file mode 100644 index 0000000..89e422e --- /dev/null +++ b/docs/specs/data-model.md @@ -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. diff --git a/docs/specs/event-and-registry-model.md b/docs/specs/event-and-registry-model.md new file mode 100644 index 0000000..a9545b9 --- /dev/null +++ b/docs/specs/event-and-registry-model.md @@ -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. diff --git a/docs/specs/testing-release-and-migration.md b/docs/specs/testing-release-and-migration.md new file mode 100644 index 0000000..e09e901 --- /dev/null +++ b/docs/specs/testing-release-and-migration.md @@ -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. diff --git a/docs/specs/ui-operator-console.md b/docs/specs/ui-operator-console.md new file mode 100644 index 0000000..b0a40d2 --- /dev/null +++ b/docs/specs/ui-operator-console.md @@ -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. diff --git a/docs/specs/workplan-coordination.md b/docs/specs/workplan-coordination.md new file mode 100644 index 0000000..3371c6a --- /dev/null +++ b/docs/specs/workplan-coordination.md @@ -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. diff --git a/registry/README.md b/registry/README.md index 569abe9..fc15bd5 100644 --- a/registry/README.md +++ b/registry/README.md @@ -1,12 +1,12 @@ # 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 -1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`). -2. Add the row to `indexes/capabilities.yaml`. -3. Run `reuse-surface validate` from a checkout with the CLI installed. -4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`. - -Federation contract: reuse-surface `docs/RegistryFederation.md`. +1. Add or update a capability entry under `registry/capabilities/`. +2. Add the row to `registry/indexes/capabilities.yaml`. +3. Run `reuse-surface validate --root .` from a checkout with the CLI installed. +4. Keep capability docs aligned with `INTENT.md`, `SCOPE.md`, and `docs/specs/`. diff --git a/registry/capabilities/capability.infotech.repo-template.md b/registry/capabilities/archived/260627-capability.infotech.repo-template.md similarity index 100% rename from registry/capabilities/capability.infotech.repo-template.md rename to registry/capabilities/archived/260627-capability.infotech.repo-template.md diff --git a/registry/capabilities/capability.infotech.core-hub.md b/registry/capabilities/capability.infotech.core-hub.md new file mode 100644 index 0000000..75ddd06 --- /dev/null +++ b/registry/capabilities/capability.infotech.core-hub.md @@ -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. diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml index 359c385..890ae3a 100644 --- a/registry/indexes/capabilities.yaml +++ b/registry/indexes/capabilities.yaml @@ -1,14 +1,14 @@ version: 1 -updated: '2026-06-24' +updated: '2026-06-27' domain: infotech capabilities: - - id: capability.infotech.repo-template - name: Coulomb Repository Template - summary: Bootstrap new git repositories with agent instructions, registry scaffold, and State Hub onboarding conventions. - vector: D3 / A3 / C2 / R2 + - 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. + vector: D3 / A1 / C1 / R1 domain: infotech status: draft - owner: repo-seed - path: registry/capabilities/capability.infotech.repo-template.md - tags: [template, bootstrap, state-hub, onboarding] - consumption_modes: [git clone, informational] \ No newline at end of file + owner: core-hub + path: registry/capabilities/capability.infotech.core-hub.md + tags: [interaction-framework, state-hub, inter-hub-successor, agent-coordination, registry, api] + consumption_modes: [informational, planning] diff --git a/workplans/CORE-WP-0001-statehub-bootstrap.md b/workplans/CORE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..d6d420f --- /dev/null +++ b/workplans/CORE-WP-0001-statehub-bootstrap.md @@ -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. diff --git a/workplans/CORE-WP-0002-contract-ir-freeze.md b/workplans/CORE-WP-0002-contract-ir-freeze.md new file mode 100644 index 0000000..1e23ff0 --- /dev/null +++ b/workplans/CORE-WP-0002-contract-ir-freeze.md @@ -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. diff --git a/workplans/CORE-WP-0003-fastapi-postgres-foundation.md b/workplans/CORE-WP-0003-fastapi-postgres-foundation.md new file mode 100644 index 0000000..48e0edf --- /dev/null +++ b/workplans/CORE-WP-0003-fastapi-postgres-foundation.md @@ -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. diff --git a/workplans/REPO-WP-0001-statehub-bootstrap.md b/workplans/archived/260627-REPO-WP-0001-statehub-bootstrap.md similarity index 100% rename from workplans/REPO-WP-0001-statehub-bootstrap.md rename to workplans/archived/260627-REPO-WP-0001-statehub-bootstrap.md diff --git a/workplans/REPO-WP-0002-template-validation-checklist.md b/workplans/archived/260627-REPO-WP-0002-template-validation-checklist.md similarity index 100% rename from workplans/REPO-WP-0002-template-validation-checklist.md rename to workplans/archived/260627-REPO-WP-0002-template-validation-checklist.md