generated from coulomb/repo-seed
registered repo with state hub
This commit is contained in:
189
AGENTS.md
Normal file
189
AGENTS.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# helix-forge — Agent Instructions
|
||||
|
||||
## Repo Identity
|
||||
|
||||
**Purpose:** HelixForge turns natural-language intent into governed, reusable software capabilities through architecture-aware discovery, validation, implementation, feedback, and reuse.
|
||||
|
||||
**Domain:** helix_forge
|
||||
**Repo slug:** helix-forge
|
||||
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
|
||||
**Workplan prefix:** `HF-WP-`
|
||||
|
||||
---
|
||||
|
||||
## Repo Orientation
|
||||
|
||||
This repository is currently documentation-first. Treat `INTENT.md` as the
|
||||
primary source of truth, with `wiki/HelixForgeVision.md` carrying the compact
|
||||
vision statement and `wiki/OrthogonalArchitectureSchema.md` preserving the
|
||||
current Orthogonal Architecture Standard schema reference.
|
||||
|
||||
Current responsibilities:
|
||||
- Define HelixForge as a capability-first development ecosystem.
|
||||
- Preserve the Orthogonal Architecture Dimensions and VSM-inspired vocabulary
|
||||
that future implementation artifacts must follow.
|
||||
- Track near-term work in `workplans/`, currently focused on using `ops-hub`
|
||||
as the first Inter-Hub extension pattern.
|
||||
|
||||
Current state:
|
||||
- No application/runtime source code exists yet.
|
||||
- No build, test, or package commands are defined yet.
|
||||
- The repo already uses `HF-WP-` workplan IDs; keep that prefix unless the
|
||||
existing workplan files are deliberately migrated.
|
||||
|
||||
Useful orientation commands:
|
||||
|
||||
```bash
|
||||
sed -n '1,220p' INTENT.md
|
||||
sed -n '1,160p' workplans/HF-WP-0001-establish-ops-hub-first-extension.md
|
||||
sed -n '1,120p' wiki/HelixForgeVision.md
|
||||
```
|
||||
|
||||
When adding executable artifacts later, update this file with the real stack,
|
||||
dependency, build, test, and validation commands.
|
||||
|
||||
## State Hub Integration
|
||||
|
||||
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
|
||||
there is no MCP server for Codex agents.
|
||||
|
||||
| Context | URL |
|
||||
|---------|-----|
|
||||
| Local workstation | `http://127.0.0.1:8000` |
|
||||
| Remote via tunnel | `http://127.0.0.1:18000` |
|
||||
|
||||
### Orient at session start
|
||||
|
||||
```bash
|
||||
# Offline brief, if generated by StateHub consistency sync
|
||||
test -f .custodian-brief.md && cat .custodian-brief.md || sed -n '1,120p' SCOPE.md
|
||||
|
||||
# Active workstreams for this domain
|
||||
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
# Check inbox
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=helix-forge&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
```
|
||||
|
||||
Mark a message read:
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
### Log progress (required at session close)
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"summary": "what was done",
|
||||
"event_type": "note",
|
||||
"author": "codex",
|
||||
"workstream_id": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
Omit `workstream_id` / `task_id` when not applicable.
|
||||
|
||||
### Update task status
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"status": "in_progress"}'
|
||||
# values: todo | in_progress | done | blocked
|
||||
```
|
||||
|
||||
### Flag a task for human review
|
||||
|
||||
```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
|
||||
|
||||
**Start:**
|
||||
1. Read `.custodian-brief.md` when present; otherwise read `SCOPE.md` and `INTENT.md`
|
||||
2. Check inbox: `GET /messages/?to_agent=helix-forge&unread_only=true`; mark read
|
||||
3. Scan workplans: `ls workplans/` — note `status: active` files and open tasks
|
||||
4. Check blocked tasks: `GET /tasks/?needs_human=true`
|
||||
|
||||
**During work:**
|
||||
- Update task statuses in workplan files as tasks progress
|
||||
- Record significant decisions via `POST /decisions/`
|
||||
|
||||
**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
|
||||
`~/the-custodian/state-hub`:
|
||||
```bash
|
||||
make fix-consistency REPO=helix-forge
|
||||
```
|
||||
This syncs task status from files into the hub DB.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
**File location:** `workplans/HF-WP-NNNN-<slug>.md`
|
||||
|
||||
**Archived location:** completed workplans may move to
|
||||
`workplans/archived/YYMMDD-HF-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
|
||||
`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:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: HF-WP-NNNN
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: helix_forge
|
||||
repo: helix-forge
|
||||
status: active | done
|
||||
owner: codex
|
||||
topic_slug: ...
|
||||
created: "YYYY-MM-DD"
|
||||
updated: "YYYY-MM-DD"
|
||||
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
---
|
||||
```
|
||||
|
||||
**Task block format** (one per `##` section):
|
||||
|
||||
```
|
||||
## Task Title
|
||||
|
||||
` ` `task
|
||||
id: HF-WP-NNNN-T01
|
||||
status: todo | in_progress | done | blocked
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
` ` `
|
||||
|
||||
Task description text.
|
||||
```
|
||||
|
||||
Status progression: `todo` → `in_progress` → `done` (or `blocked`)
|
||||
|
||||
To create a new workplan:
|
||||
1. Write the file following the format above
|
||||
2. Notify the custodian operator to run `make fix-consistency REPO=helix-forge`
|
||||
(or send a message to the hub agent via `POST /messages/`)
|
||||
147
SCOPE.md
Normal file
147
SCOPE.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# SCOPE
|
||||
|
||||
> This file helps you quickly understand what this repository is about,
|
||||
> when it is relevant, and when it is not.
|
||||
> It is intentionally lightweight and may be incomplete.
|
||||
|
||||
---
|
||||
|
||||
## One-liner
|
||||
|
||||
HelixForge defines a capability-first development ecosystem for turning human intent into governed, reusable software capabilities.
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
|
||||
HelixForge joins discovery and delivery into one continuous loop: real-world
|
||||
demands are explored in natural language, shaped into stable capabilities,
|
||||
placed in an orthogonal architecture model, validated structurally and
|
||||
semantically, implemented, and improved through feedback.
|
||||
|
||||
The repo is the early home for that intent, vocabulary, architecture schema,
|
||||
and operating model. It is not yet an application implementation.
|
||||
|
||||
---
|
||||
|
||||
## In Scope
|
||||
|
||||
- HelixForge product intent, vision, and architectural commitments.
|
||||
- Orthogonal Architecture Dimensions and OAS-compatible schema references.
|
||||
- VSM-inspired vocabulary for classifying capabilities, relations, validation
|
||||
rules, repository concerns, and future system elements.
|
||||
- Workplans that shape HelixForge's first practical extensions and integrations.
|
||||
- Guidance for future capability discovery, modeling, realization, validation,
|
||||
and evolution artifacts.
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Running production services or hosting operational infrastructure directly.
|
||||
- Owning Railiance infrastructure, cluster, platform, enablement, or app code.
|
||||
- Replacing State Hub as the cross-repository memory and coordination surface.
|
||||
- Replacing Inter-Hub as the interaction substrate for hub-based systems.
|
||||
- Providing a stable SDK, API, CLI, UI, or runtime before implementation work
|
||||
is explicitly scoped.
|
||||
|
||||
---
|
||||
|
||||
## Relevant When
|
||||
|
||||
- You need the HelixForge product thesis or capability-first operating model.
|
||||
- You are modeling reusable capabilities from natural-language demand.
|
||||
- You are checking how HelixForge maps Orthogonal Architecture Dimensions to
|
||||
capability, service, platform, policy, automation, or intelligence elements.
|
||||
- You are shaping an Inter-Hub extension pattern, such as the initial ops-hub
|
||||
workplan.
|
||||
|
||||
---
|
||||
|
||||
## Not Relevant When
|
||||
|
||||
- You need deployable infrastructure code; use the relevant Railiance repos.
|
||||
- You need State Hub implementation details; use `the-custodian/state-hub`.
|
||||
- You need Inter-Hub API or UI implementation details; use `inter-hub`.
|
||||
- You need a production-ready HelixForge runtime; this repo is not there yet.
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
- Status: draft/concept
|
||||
- Implementation: documentation and workplanning only
|
||||
- Stability: evolving
|
||||
- Usage: internal product and architecture shaping
|
||||
|
||||
The repository currently has no executable source tree, dependency manifest, or
|
||||
test suite. `INTENT.md` is the main source of truth.
|
||||
|
||||
---
|
||||
|
||||
## How It Fits
|
||||
|
||||
- Upstream dependencies: Orthogonal Architecture Standard vocabulary and the
|
||||
State Hub workplan/coordination model.
|
||||
- Downstream consumers: future HelixForge implementation repos, Inter-Hub
|
||||
extension work, and capability catalog/tooling efforts.
|
||||
- Often used with: `inter-hub`, `the-custodian/state-hub`, Railiance ops repos,
|
||||
and future `ops-hub` artifacts.
|
||||
|
||||
---
|
||||
|
||||
## Terminology
|
||||
|
||||
- Preferred terms: capability, capability model, capability contract,
|
||||
realization, validation, Orthogonal Architecture Dimensions, VSM-inspired
|
||||
functions.
|
||||
- Also known as: capability-first development ecosystem; intent-to-capability
|
||||
forge.
|
||||
- Potentially confusing terms: OAS means Orthogonal Architecture Standard here,
|
||||
not OpenAPI Specification. Stack `S1`-`S5` placements are separate from VSM
|
||||
System 1-5 tags.
|
||||
|
||||
---
|
||||
|
||||
## Related / Overlapping Repositories
|
||||
|
||||
- `inter-hub` - governed interaction substrate that HelixForge may extend.
|
||||
- `the-custodian/state-hub` - cross-repo state, workstream, capability, and
|
||||
progress index.
|
||||
- `railiance-infra`, `railiance-cluster`, `railiance-platform`,
|
||||
`railiance-enablement`, `railiance-apps` - operational stack referenced by
|
||||
the first ops-hub workplan.
|
||||
|
||||
---
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
- Start with: `INTENT.md`
|
||||
- Key files / directories: `wiki/HelixForgeVision.md`,
|
||||
`wiki/OrthogonalArchitectureSchema.md`, `workplans/`
|
||||
- Entry points: `workplans/HF-WP-0001-establish-ops-hub-first-extension.md`
|
||||
|
||||
---
|
||||
|
||||
## Provided Capabilities
|
||||
|
||||
```capability
|
||||
type: documentation
|
||||
title: Capability-first architecture vocabulary
|
||||
description: Defines the HelixForge vocabulary for capability discovery, modeling, contracts, realization, validation, and evolution across Orthogonal Architecture Dimensions.
|
||||
keywords: [capability, architecture, OAS, VSM, validation]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: other
|
||||
title: Intent-to-capability operating model
|
||||
description: Provides the product and process thesis for maturing natural-language demands into reusable, validated software capabilities.
|
||||
keywords: [intent, discovery, delivery, reusable-capabilities, product-model]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
The existing workplan prefix is `HF-WP-`. Keep future workplans aligned with
|
||||
that prefix unless the repository intentionally migrates its workplan naming.
|
||||
499
workplans/HF-WP-0001-establish-ops-hub-first-extension.md
Normal file
499
workplans/HF-WP-0001-establish-ops-hub-first-extension.md
Normal file
@@ -0,0 +1,499 @@
|
||||
---
|
||||
id: HF-WP-0001
|
||||
type: workplan
|
||||
title: "Establish ops-hub as the First Inter-Hub Extension"
|
||||
domain: helix_forge
|
||||
repo: helix-forge
|
||||
status: active
|
||||
owner: worsch
|
||||
created: "2026-05-16"
|
||||
updated: "2026-05-16"
|
||||
planning_priority: high
|
||||
planning_order: 1
|
||||
related_repos:
|
||||
- inter-hub
|
||||
- railiance-infra
|
||||
- railiance-cluster
|
||||
- railiance-platform
|
||||
- railiance-apps
|
||||
state_hub_workstream_id: "48d91935-197e-4ad4-be07-7bbcd535847c"
|
||||
---
|
||||
|
||||
# Establish ops-hub as the First Inter-Hub Extension
|
||||
|
||||
## Goal
|
||||
|
||||
Create `ops-hub` as the first practical domain extension of the Interaction Hub
|
||||
Framework, focused on professionalizing Railiance operations while the current
|
||||
CoulombCore environment transitions toward the future ThreePhoenix production
|
||||
setup.
|
||||
|
||||
The first increment should not replace State Hub or require a separate
|
||||
`ops-hub` repository immediately. It should establish the operational model,
|
||||
the hub vocabulary, and the smallest governed integration with Inter-Hub. A
|
||||
separate implementation repository can be created once the shape of the hub is
|
||||
stable and the Inter-Hub extension bootstrap API is less manual.
|
||||
|
||||
## Context
|
||||
|
||||
Current operational reality:
|
||||
|
||||
- `coulombcore` / `92.205.130.254` is the live production-like server. It runs
|
||||
the current Gitea deployment and other hands-on experimental services.
|
||||
- The local workstation still hosts important services such as State Hub and
|
||||
local build/runtime pieces.
|
||||
- `railiance01` / `92.205.62.239` is the first server of the intended future
|
||||
ThreePhoenix production environment.
|
||||
- The Railiance repo stack already separates operational responsibility:
|
||||
`railiance-infra` (S1), `railiance-cluster` (S2), `railiance-platform` (S3),
|
||||
`railiance-enablement` (S4), and `railiance-apps` (S5).
|
||||
|
||||
`ops-hub` should become the operational truth surface across those realities:
|
||||
environments, hosts, clusters, services, releases, endpoints, backups,
|
||||
readiness gates, incidents, risks, and migration waves.
|
||||
|
||||
## Inter-Hub API Findings
|
||||
|
||||
Checked live and local Inter-Hub evidence on 2026-05-16.
|
||||
|
||||
Live API:
|
||||
|
||||
- `https://hub.coulomb.social/api/v2/openapi.json` is available.
|
||||
- `https://hub.coulomb.social/api/v2/docs` is available.
|
||||
- Public UI route `https://hub.coulomb.social/Hubs` redirects to
|
||||
`/NewSession`, so hub creation is currently an authenticated UI flow.
|
||||
|
||||
Live OpenAPI paths:
|
||||
|
||||
- `/widgets`, `/widgets/{id}`
|
||||
- `/interaction-events`
|
||||
- `/annotations`
|
||||
- `/requirement-candidates`, `/requirement-candidates/{id}`
|
||||
- `/decision-records`, `/decision-records/{id}`
|
||||
- `/deployment-records`, `/deployment-records/{id}`
|
||||
- `/outcome-signals`, `/outcome-signals/{id}`
|
||||
- `/widget-types`, `/event-types`, `/annotation-categories`
|
||||
- `/hub-registry`, `/hub-registry/{hubId}`
|
||||
- `/widget-patterns`, `/widget-patterns/{id}`, `/widget-patterns/{id}/adopt`
|
||||
- `/token`
|
||||
|
||||
Useful local Inter-Hub docs:
|
||||
|
||||
- `inter-hub/docs/domain-hub-extension-guide.md`
|
||||
- `inter-hub/docs/new-hub-quickstart.md`
|
||||
- `inter-hub/contracts/extensions/hub-capability-manifest-v1.md`
|
||||
- `inter-hub/contracts/functional/interaction-reporting-v1.md`
|
||||
|
||||
Assessment:
|
||||
|
||||
- Inter-Hub provides enough guidance to start `ops-hub` as an API consumer
|
||||
pattern or as a manually registered domain hub.
|
||||
- Inter-Hub does not yet provide enough API surface to fully automate first hub
|
||||
bootstrap. Hub creation, capability manifest creation/activation, API
|
||||
consumer creation, API key issuance, and widget creation are primarily UI or
|
||||
internal-controller workflows.
|
||||
- The quickstart mentions `POST /api/v2/hubs` and `POST /api/v2/widgets`, but
|
||||
the live OpenAPI and local routes do not expose those create endpoints. Treat
|
||||
the quickstart as aspirational for bootstrap automation until Inter-Hub is
|
||||
hardened.
|
||||
|
||||
## Architectural Decision
|
||||
|
||||
Start with **Pattern A: API Consumer Hub**, plus a manual or migration-backed
|
||||
Inter-Hub registration:
|
||||
|
||||
1. Register `ops-hub` as a domain hub in Inter-Hub.
|
||||
2. Activate a `HubCapabilityManifest` for its operational vocabulary.
|
||||
3. Create an `ApiConsumer` and API key for `ops-hub`.
|
||||
4. Seed a small set of governed widgets representing operational surfaces.
|
||||
5. Emit interaction events and annotations from lightweight scripts or a
|
||||
prototype UI.
|
||||
|
||||
Do not create a separate `ops-hub` repository until the first inventory,
|
||||
readiness, and migration workflows have proven their data model.
|
||||
|
||||
## Initial ops-hub Vocabulary
|
||||
|
||||
Suggested manifest values:
|
||||
|
||||
### Widget Types
|
||||
|
||||
```json
|
||||
[
|
||||
"ops-environment",
|
||||
"ops-host",
|
||||
"ops-cluster",
|
||||
"ops-service",
|
||||
"ops-endpoint",
|
||||
"ops-release",
|
||||
"ops-backup-set",
|
||||
"ops-runbook",
|
||||
"ops-incident",
|
||||
"ops-readiness-gate",
|
||||
"ops-migration-wave",
|
||||
"ops-risk"
|
||||
]
|
||||
```
|
||||
|
||||
### Event Types
|
||||
|
||||
```json
|
||||
[
|
||||
"ops-inventory-registered",
|
||||
"ops-health-checked",
|
||||
"ops-release-observed",
|
||||
"ops-endpoint-verified",
|
||||
"ops-backup-verified",
|
||||
"ops-restore-tested",
|
||||
"ops-runbook-executed",
|
||||
"ops-risk-raised",
|
||||
"ops-risk-accepted",
|
||||
"ops-migration-gate-passed",
|
||||
"ops-migration-gate-failed"
|
||||
]
|
||||
```
|
||||
|
||||
### Annotation Categories
|
||||
|
||||
```json
|
||||
[
|
||||
"ops-drift",
|
||||
"ops-backup-gap",
|
||||
"ops-security-gap",
|
||||
"ops-routing-gap",
|
||||
"ops-secret-gap",
|
||||
"ops-readiness-blocker",
|
||||
"ops-migration-risk",
|
||||
"ops-observability-gap",
|
||||
"ops-recovery-gap"
|
||||
]
|
||||
```
|
||||
|
||||
### Policy Scopes
|
||||
|
||||
```json
|
||||
[
|
||||
"ops-local",
|
||||
"ops-transitional-prod",
|
||||
"ops-production",
|
||||
"ops-threephoenix",
|
||||
"ops-registry",
|
||||
"ops-secrets",
|
||||
"ops-backup-retention"
|
||||
]
|
||||
```
|
||||
|
||||
## Initial Operational Inventory
|
||||
|
||||
The first ops-hub inventory should cover:
|
||||
|
||||
| Environment | Role | Current notes |
|
||||
|---|---|---|
|
||||
| `local` | Workstation services and development runtime | State Hub and local build/runtime pieces currently live here. |
|
||||
| `coulombcore` | Live transitional production | Public IP `92.205.130.254`; hosts current Gitea and hand-built experimental production services. |
|
||||
| `railiance01` | Future production foundation | Public IP `92.205.62.239`; first server of the intended ThreePhoenix setup. |
|
||||
| `threephoenix-prod` | Target production topology | Future three-node Railiance production environment. |
|
||||
|
||||
The first services to model:
|
||||
|
||||
- Gitea / container registry
|
||||
- State Hub and underlying services
|
||||
- Inter-Hub itself
|
||||
- PostgreSQL/CNPG services used by Gitea and State Hub
|
||||
- Ingress/DNS/TLS endpoints for the above
|
||||
- Backup and restore coverage for each persistent data store
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 — Confirm Inter-Hub extension bootstrap path
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "2587a3b8-3b9b-4948-acaf-1547644e4563"
|
||||
```
|
||||
|
||||
Confirm whether `ops-hub` should be registered through the Inter-Hub UI,
|
||||
through a migration, or through new API endpoints.
|
||||
|
||||
Checks:
|
||||
|
||||
- Confirm the active Inter-Hub deployment URL and authentication path.
|
||||
- Confirm whether `/Hubs/new`, `/HubCapabilityManifests`, `/ApiConsumers`, and
|
||||
`/ApiKeys` are accessible to the operator.
|
||||
- Confirm whether direct DB migration is acceptable for initial bootstrap.
|
||||
- Record the chosen bootstrap path in this workplan.
|
||||
|
||||
Done when: there is a concrete, repeatable path to create the `ops-hub` row,
|
||||
manifest, API consumer, and API key.
|
||||
|
||||
---
|
||||
|
||||
### T02 — Register ops-hub in Inter-Hub
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "8e9bd9b2-54fc-49a4-8bb8-11c8577be48d"
|
||||
```
|
||||
|
||||
Create the Hub row:
|
||||
|
||||
- `name`: `Ops Hub`
|
||||
- `slug`: `ops-hub`
|
||||
- `domain`: `ops.coulomb.social` or another explicit domain chosen by the
|
||||
operator
|
||||
- `hub_kind`: `domain`
|
||||
|
||||
Done when: `ops-hub` appears in `/Hubs` and `/api/v2/hub-registry` after
|
||||
authentication.
|
||||
|
||||
---
|
||||
|
||||
### T03 — Activate the ops-hub capability manifest
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "55f5aeed-21c3-4a83-bc78-f90f92c7d597"
|
||||
```
|
||||
|
||||
Create and activate a `HubCapabilityManifest` for `ops-hub` using the
|
||||
vocabulary in this workplan.
|
||||
|
||||
Validation:
|
||||
|
||||
- Declared widget types appear in `/api/v2/widget-types`.
|
||||
- Declared event types appear in `/api/v2/event-types`.
|
||||
- Declared annotation categories appear in `/api/v2/annotation-categories`.
|
||||
- Policy scopes are visible in the Inter-Hub registry UI or DB, even though the
|
||||
public v2 API currently lacks `/policy-scopes`.
|
||||
|
||||
Done when: the manifest status is `active` and no type conflicts remain.
|
||||
|
||||
---
|
||||
|
||||
### T04 — Create ops-hub API consumer and key
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "ad08e729-8562-4a02-8bf6-dcdfebe430c8"
|
||||
```
|
||||
|
||||
Create an `ApiConsumer` associated with the active `ops-hub` manifest, then
|
||||
create a static API key with at least:
|
||||
|
||||
- `framework:read`
|
||||
- `hub:ops-hub:read`
|
||||
- `hub:ops-hub:write`
|
||||
|
||||
Store the key only in the operator secret store or local env file, never in Git.
|
||||
|
||||
Done when: `POST /api/v2/token` can exchange the static key for a short-lived
|
||||
access token and `GET /api/v2/hub-registry` works with that token.
|
||||
|
||||
---
|
||||
|
||||
### T05 — Seed first governed ops widgets
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T05
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "d303884d-d1f6-4fd0-a4ec-97afe6162164"
|
||||
```
|
||||
|
||||
Create initial widgets for the operational surfaces:
|
||||
|
||||
- `ops-env-local`
|
||||
- `ops-env-coulombcore`
|
||||
- `ops-env-railiance01`
|
||||
- `ops-env-threephoenix-prod`
|
||||
- `ops-service-gitea`
|
||||
- `ops-service-state-hub`
|
||||
- `ops-service-inter-hub`
|
||||
- `ops-readiness-gitea-registry`
|
||||
- `ops-readiness-state-hub-cluster-deploy`
|
||||
- `ops-migration-coulombcore-to-threephoenix`
|
||||
|
||||
If Inter-Hub still lacks a widget creation API, seed these through the UI or a
|
||||
migration and record that as an API gap.
|
||||
|
||||
Done when: the widgets appear under `ops-hub` and can accept interaction events
|
||||
and annotations.
|
||||
|
||||
---
|
||||
|
||||
### T06 — Build the first ops inventory artifact
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T06
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "2a0b2f69-5a3d-433c-9cbd-85fd868b63d8"
|
||||
```
|
||||
|
||||
Create an ops inventory document in `helix-forge` that expresses the current
|
||||
state of:
|
||||
|
||||
- environments
|
||||
- hosts
|
||||
- clusters
|
||||
- services
|
||||
- endpoints
|
||||
- storage and backup coverage
|
||||
- migration readiness gates
|
||||
|
||||
Use this as the working model before creating a separate `ops-hub` repository.
|
||||
|
||||
Done when: a human can see the CoulombCore, local, railiance01, and
|
||||
ThreePhoenix relationship without reading multiple repo workplans.
|
||||
|
||||
---
|
||||
|
||||
### T07 — Instrument the current Gitea registry work as the first ops-hub signal
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "ed3e0396-b16d-40c2-9519-e755ad6241eb"
|
||||
```
|
||||
|
||||
Use the recently fixed Gitea `/v2` route as the first real operational signal.
|
||||
|
||||
Suggested event:
|
||||
|
||||
```json
|
||||
{
|
||||
"widgetId": "<ops-readiness-gitea-registry-widget-id>",
|
||||
"eventType": "ops-endpoint-verified",
|
||||
"viewContext": "railiance-apps/workplans/RAIL-AP-WP-0001",
|
||||
"metadata": {
|
||||
"endpoint": "https://gitea.coulomb.social/v2/",
|
||||
"expectedStatus": 401,
|
||||
"observedHeader": "Docker-Distribution-Api-Version: registry/2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Done when: the Gitea registry readiness event is visible in Inter-Hub and
|
||||
traceable back to the Railiance workplan.
|
||||
|
||||
---
|
||||
|
||||
### T08 — Define the ops-hub readiness gate model for ThreePhoenix migration
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T08
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "72a58622-c3ac-4765-8026-5c2489af2058"
|
||||
```
|
||||
|
||||
Define readiness gates that must be green before moving production
|
||||
responsibility from CoulombCore to ThreePhoenix:
|
||||
|
||||
- DNS and TLS are codified.
|
||||
- Git hosting and container registry are reproducible.
|
||||
- Persistent data stores have backup and restore evidence.
|
||||
- Secrets and SOPS/age keys are available through governed operator paths.
|
||||
- Cluster runtime and platform services are recreated through Railiance repos.
|
||||
- Rollback path is documented.
|
||||
- Operator runbooks exist for deploy, restore, rotate, and incident response.
|
||||
|
||||
Done when: each gate has an owner repo, evidence requirement, and status.
|
||||
|
||||
---
|
||||
|
||||
### T09 — Decide whether to create a separate ops-hub repository
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T09
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "0e5842fd-1d33-4e2a-9701-07f623a2b901"
|
||||
```
|
||||
|
||||
Make the repository decision after T05-T08.
|
||||
|
||||
Create a separate repo when at least one of these is true:
|
||||
|
||||
- `ops-hub` needs its own UI beyond Inter-Hub's generic hub dashboards.
|
||||
- `ops-hub` needs collectors, adapters, or scheduled probes.
|
||||
- `ops-hub` needs its own release lifecycle.
|
||||
- The ops vocabulary stabilizes enough to deserve reusable code.
|
||||
|
||||
Until then, keep the model in `helix-forge` and register state in Inter-Hub.
|
||||
|
||||
Done when: the decision is recorded with rationale and a repo boundary if
|
||||
needed.
|
||||
|
||||
---
|
||||
|
||||
### T10 — Inter-Hub API hardening for extension bootstrap
|
||||
|
||||
```task
|
||||
id: HF-WP-0001-T10
|
||||
status: todo
|
||||
priority: high
|
||||
target_repo: inter-hub
|
||||
state_hub_task_id: "7fa54508-7add-4885-8913-12edaadc4d92"
|
||||
```
|
||||
|
||||
Create or link an `inter-hub` workplan to make domain hub bootstrapping
|
||||
machine-repeatable.
|
||||
|
||||
Recommended Inter-Hub improvements:
|
||||
|
||||
1. Add `POST /api/v2/hubs` and include it in OpenAPI.
|
||||
2. Add `POST /api/v2/widgets` and include it in OpenAPI.
|
||||
3. Add API endpoints for `HubCapabilityManifest` draft creation, update, and
|
||||
activation.
|
||||
4. Add API endpoints for `ApiConsumer` and API key creation, or a clearly
|
||||
documented admin-only bootstrap command if API key creation remains UI-only.
|
||||
5. Add `/api/v2/policy-scopes` to match the policy scope registry already used
|
||||
by manifests.
|
||||
6. Add distinct OpenAPI request schemas for create requests instead of reusing
|
||||
response schemas.
|
||||
7. Align `docs/new-hub-quickstart.md` with the actual live API until the create
|
||||
endpoints exist.
|
||||
8. Fix `Web.Controller.Api.V2.InteractionEvents` so manifest-declared event
|
||||
types are actually decoded and enforced.
|
||||
9. Fix webhook dispatch so it uses the submitted event type instead of the
|
||||
hard-coded `"clicked"` event name.
|
||||
10. Decide whether event `metadata` is part of the v2 create contract; if yes,
|
||||
persist it in the controller and test it.
|
||||
|
||||
Done when: the next domain hub can be created from a script using documented
|
||||
API calls and without direct DB access.
|
||||
|
||||
## Initial Acceptance Criteria
|
||||
|
||||
This workplan is complete when:
|
||||
|
||||
1. `ops-hub` is registered in Inter-Hub.
|
||||
2. Its capability manifest is active.
|
||||
3. It has an API consumer and key.
|
||||
4. Initial ops widgets exist for environments, services, readiness gates, and
|
||||
migration waves.
|
||||
5. At least one real operational event has been submitted.
|
||||
6. The CoulombCore-to-ThreePhoenix readiness model is documented.
|
||||
7. A decision has been made whether to create a separate `ops-hub` repository.
|
||||
8. Inter-Hub bootstrap API gaps are either fixed or tracked in an Inter-Hub
|
||||
workplan.
|
||||
|
||||
## Notes
|
||||
|
||||
`ops-hub` should complement State Hub during the transition:
|
||||
|
||||
- State Hub continues to track workstreams, decisions, and progress events.
|
||||
- `ops-hub` tracks operational reality and readiness evidence.
|
||||
- `coo-hub` can later become the coordination/workstream successor once the
|
||||
broader hub constellation is established.
|
||||
|
||||
Reference in New Issue
Block a user