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

First extension struggles. Should I just drop the haskel approach?

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-14 19:49:20 +02:00
parent efa088ec8a
commit f718d17b26
6 changed files with 202 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
AGENTS.md
View File

@@ -63,8 +63,8 @@ Omit `workstream_id` / `task_id` when not applicable.
```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
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
@@ -83,7 +83,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
2. Check inbox: `GET /messages/?to_agent=helix-forge&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check blocked tasks: `GET /tasks/?needs_human=true`
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
@@ -146,7 +146,7 @@ derived health labels, not frontmatter statuses.
` ` `task
id: HELIX-WP-NNNN-T01
status: todo | in_progress | done | blocked
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
@@ -154,7 +154,7 @@ state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
Task description text.
```
Status progression: `todo` → `in_progress` → `done` (or `blocked`)
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
To create a new workplan:
1. Write the file following the format above

8
SCOPE.md
View File

@@ -63,6 +63,8 @@ and operating model. It is not yet an application implementation.
- 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 deployable `ops-hub` implementation work; use `/home/worsch/ops-hub`
(`gitea-remote:coulomb/ops-hub.git`).
- You need a production-ready HelixForge runtime; this repo is not there yet.
---
@@ -84,9 +86,9 @@ test suite. `INTENT.md` is the main source of truth.
- 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.
extension work, `ops-hub`, and capability catalog/tooling efforts.
- Often used with: `inter-hub`, `the-custodian/state-hub`, Railiance ops repos,
and future `ops-hub` artifacts.
and the `ops-hub` implementation repo.
---
@@ -106,6 +108,8 @@ test suite. `INTENT.md` is the main source of truth.
## Related / Overlapping Repositories
- `inter-hub` - governed interaction substrate that HelixForge may extend.
- `ops-hub` - VSM Operations / System 1 Inter-Hub extension implementation;
local path `/home/worsch/ops-hub`.
- `the-custodian/state-hub` - cross-repo state, workstream, capability, and
progress index.
- `railiance-infra`, `railiance-cluster`, `railiance-platform`,

36
wiki/OpsHubBootstrapRunbook.md
View File

@@ -1,6 +1,6 @@
# Ops Hub Bootstrap Runbook
Date: 2026-05-16
Date: 2026-06-14
## Purpose
@@ -11,17 +11,45 @@ Use this when an authenticated Inter-Hub admin session or deployment migration
is available. The current public v2 API is not sufficient to create the hub,
manifest, API consumer, API key, or seed widgets by itself.
As of 2026-06-06, implementation work for `ops-hub` belongs in the dedicated
repo at `/home/worsch/ops-hub` with remote `gitea-remote:coulomb/ops-hub.git`.
This runbook remains a HelixForge bootstrap handoff reference until the
implementation repo ports or supersedes it.
## Inputs
- Manifest draft: `wiki/ops-hub-manifest.draft.json`
- Widget seed: `wiki/ops-hub-widgets.seed.json`
- Migration fallback: `wiki/ops-hub-bootstrap.sql`
- Implementation repo: `/home/worsch/ops-hub`
## Current Bootstrap Decision
Use the authenticated Inter-Hub admin UI first. Use the SQL migration fallback
only when a repeatable deployment-side bootstrap is needed before the v2 API is
hardened.
Prefer the supported Inter-Hub bootstrap API once production exposes the
current API surface. Do not proceed with manual DB seeding unless the operator
explicitly chooses that fallback. Until the production API gate passes, the
authenticated Inter-Hub admin UI and SQL migration remain fallback paths for
attended operator use only.
Production API gate:
- `https://hub.coulomb.social/api/v2/hubs` returns `401` unauthenticated, not
`404`.
- OpenAPI lists `/hubs`, `/hub-capability-manifests`, `/api-consumers`, and
`/policy-scopes`.
- After the gate passes, run the supported bootstrap/smoke path from the
relevant `inter-hub` or `ops-hub` tooling with `IHUB_BASE` and an operator
key.
Latest check, 2026-06-14:
- `ops-hub/scripts/interhub-gate-probe.py` still reports the production gate
closed.
- `GET /api/v2/hubs` returns `404`.
- Live OpenAPI still omits `/hubs`, `/hub-capability-manifests`,
`/api-consumers`, and `/policy-scopes`.
- Do not run the preferred API bootstrap path until the current Inter-Hub API
is deployed, unless the operator explicitly chooses the SQL fallback.
VSM classification is stored in the manifest capability description for now:

20
wiki/OpsHubInventory.md
View File

@@ -1,18 +1,34 @@
# Ops Hub Initial Inventory
Date: 2026-05-16
Date: 2026-06-06
## Purpose
This document is the first structured inventory for `ops-hub`, the VSM
Operations / System 1 hub. It turns the current operations situation into a
catalogable model before `ops-hub` has its own repository, collectors, or UI.
catalogable model and now serves as a handoff reference for the dedicated
`ops-hub` implementation repository.
Source background:
- `wiki/CurrentOperationsSituation.md`
- `workplans/HF-WP-0001-establish-ops-hub-first-extension.md`
## Repository Boundary
As of 2026-06-06, `ops-hub` implementation belongs in `/home/worsch/ops-hub`
with remote `gitea-remote:coulomb/ops-hub.git`.
- `ops-hub` owns future collectors, adapters, scheduled probes, runtime
packaging, UI/extensions, tests, and Inter-Hub bootstrap/smoke clients.
- `inter-hub` remains the generic hub framework, manifest/registry substrate,
authentication surface, widget/event API, and bootstrap API owner.
- `helix-forge` keeps this initial inventory and readiness vocabulary as
architecture and handoff material until the implementation repo ports or
supersedes it.
- Railiance repos own deployable infrastructure/service state and the
operational evidence that `ops-hub` should surface.
## VSM Placement
| Field | Value |

23
wiki/OpsHubReadinessGates.md
View File

@@ -1,12 +1,13 @@
# Ops Hub Readiness Gates
Date: 2026-05-16
Date: 2026-06-14
## Purpose
These gates define what must be true before operational responsibility can move
from the current CoulombCore setup to the future ThreePhoenix production setup.
They are intended as the first `ops-hub` readiness model.
They are intended as the first `ops-hub` readiness model and should be ported
into the dedicated `ops-hub` implementation repo as that repo grows.
Statuses:
@@ -19,8 +20,8 @@ Statuses:
| ID | Gate | Owner repo | Evidence requirement | Current status |
|---|---|---|---|---|
| OPS-G01 | Environment inventory exists | `helix-forge` | `local`, `coulombcore`, `railiance01`, and `threephoenix-prod` are represented with role, lifecycle state, and owner notes. | `partial` |
| OPS-G02 | Service catalog exists | `helix-forge` then future `ops-hub` | Each live and target service has environment, owner repo, endpoint, backing stores, lifecycle state, and evidence links. | `partial` |
| OPS-G01 | Environment inventory exists | `helix-forge` handoff to `ops-hub` | `local`, `coulombcore`, `railiance01`, and `threephoenix-prod` are represented with role, lifecycle state, and owner notes. | `partial` |
| OPS-G02 | Service catalog exists | `ops-hub` | Each live and target service has environment, owner repo, endpoint, backing stores, lifecycle state, and evidence links. | `partial` |
| OPS-G03 | DNS and TLS are codified | `railiance-cluster` / `railiance-apps` | Public hostnames, ingress routes, certificate sources, and renewal paths are declared in repo files. | `unknown` |
| OPS-G04 | Git hosting is reproducible | `railiance-apps` / `railiance-platform` | Gitea or successor deployment can be recreated from repo state, including database and storage dependencies. | `partial` |
| OPS-G05 | Container registry publishing is proven | `railiance-apps` | `docker login`, push, and pull succeed against `https://gitea.coulomb.social/v2/` using governed secrets. | `partial` |
@@ -33,7 +34,14 @@ Statuses:
| OPS-G12 | Rollback path is documented | owning service repos | Each migration wave has rollback conditions, steps, and data safety notes. | `unknown` |
| OPS-G13 | Operator runbooks exist | owning service repos | Deploy, restore, rotate, incident response, and migration runbooks exist for each critical service. | `unknown` |
| OPS-G14 | Observability and health checks are explicit | `railiance-cluster` / `railiance-platform` / service repos | Health checks, logs, metrics, and endpoint probes are documented and tied to service catalog entries. | `unknown` |
| OPS-G15 | Inter-Hub ops bootstrap is available | `inter-hub` / `helix-forge` | `ops-hub` can be created through UI or migration, manifest activated, API consumer/key created, widgets seeded, and events accepted. | `partial` |
| OPS-G15 | Inter-Hub ops bootstrap is available | `inter-hub` / `ops-hub` / `helix-forge` | `ops-hub` can be created through UI, supported API, or explicit migration fallback, manifest activated, API consumer/key created, widgets seeded, and events accepted. | `partial` |
## Current Bootstrap Gate Evidence
2026-06-14: `ops-hub/scripts/interhub-gate-probe.py` reports the preferred
production API bootstrap gate still closed. Live `/api/v2/hubs` returns `404`,
and OpenAPI does not yet list `/hubs`, `/hub-capability-manifests`,
`/api-consumers`, or `/policy-scopes`.
## Initial Migration Waves
@@ -59,5 +67,6 @@ or widget family with events like:
- `ops-migration-gate-failed`
Until Inter-Hub can create all required records through API calls, the evidence
can be maintained in this repository and mirrored into Inter-Hub through the UI
or migrations.
can be maintained as HelixForge handoff material or in the `ops-hub`
implementation repo and mirrored into Inter-Hub through the UI or explicit
migrations.

152
workplans/HF-WP-0001-establish-ops-hub-first-extension.md
View File

@@ -7,11 +7,12 @@ repo: helix-forge
status: active
owner: worsch
created: "2026-05-16"
updated: "2026-05-16"
updated: "2026-06-14"
planning_priority: high
planning_order: 1
related_repos:
- inter-hub
- ops-hub
- railiance-infra
- railiance-cluster
- railiance-platform
@@ -39,11 +40,12 @@ for the later VSM hubs:
- `pol-hub` — Policy and Identity / System 5
- `env-hub` — Boundary and Environment
The first increment should not replace State Hub or require a separate
`ops-hub` repository immediately. It should establish the operational model,
the VSM 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.
The first increment should not replace State Hub. It establishes the
operational model, the VSM hub vocabulary, and the smallest governed
integration with Inter-Hub. As of 2026-06-06, `ops-hub` has its own repository
at `/home/worsch/ops-hub` with remote `gitea-remote:coulomb/ops-hub.git`; use
that repo for implementation from now on while treating it as an extension of
Inter-Hub rather than a fork of the generic hub framework.
## VSM Hub Extension Strategy
@@ -212,9 +214,12 @@ vocabularies:
syn-hub / ctl-hub / aud-hub / int-hub / pol-hub / env-hub
```
Do not create a separate `ops-hub` repository until the first inventory,
readiness, service catalog, and migration workflows have proven their data
model.
Use the separate `ops-hub` repository for implementation work from now on.
`inter-hub` remains the framework, registry, authentication, manifest, widget,
and event substrate. `helix-forge` remains the architecture/workplan home and
keeps these bootstrap artifacts as handoff references until they are ported or
superseded by `ops-hub` repo workplans. Railiance repos remain the desired
state and evidence owners for their operational systems.
## Initial ops-hub Vocabulary
@@ -365,7 +370,7 @@ Output: `Confirmed Bootstrap Path` section in this workplan.
```task
id: HF-WP-0001-T02
status: blocked
status: wait
priority: high
state_hub_task_id: "8e9bd9b2-54fc-49a4-8bb8-11c8577be48d"
```
@@ -403,7 +408,7 @@ Prepared artifacts:
```task
id: HF-WP-0001-T03
status: blocked
status: wait
priority: high
state_hub_task_id: "55f5aeed-21c3-4a83-bc78-f90f92c7d597"
```
@@ -441,7 +446,7 @@ Prepared artifact: `wiki/ops-hub-manifest.draft.json`.
```task
id: HF-WP-0001-T04
status: blocked
status: wait
priority: high
state_hub_task_id: "ad08e729-8562-4a02-8bf6-dcdfebe430c8"
```
@@ -468,7 +473,7 @@ consumer row, not the one-time visible secret.
```task
id: HF-WP-0001-T05
status: blocked
status: wait
priority: high
state_hub_task_id: "d303884d-d1f6-4fd0-a4ec-97afe6162164"
```
@@ -542,7 +547,7 @@ Output: `wiki/OpsHubInventory.md`.
```task
id: HF-WP-0001-T07
status: blocked
status: wait
priority: medium
state_hub_task_id: "ed3e0396-b16d-40c2-9519-e755ad6241eb"
```
@@ -606,26 +611,43 @@ Output: `wiki/OpsHubReadinessGates.md`.
```task
id: HF-WP-0001-T09
status: todo
status: done
priority: medium
state_hub_task_id: "0e5842fd-1d33-4e2a-9701-07f623a2b901"
```
Make the repository decision after T05-T08.
Decision recorded on 2026-06-06: create and use a separate `ops-hub`
repository. The repo is present locally at `/home/worsch/ops-hub` and tracks
`gitea-remote:coulomb/ops-hub.git`.
Create a separate repo when at least one of these is true:
Rationale:
- `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.
- The VSM hub extension template needs shared scaffolding that should not live
inside `inter-hub` itself.
- The operator has provided the repo and decided that `ops-hub` should live
outside `helix-forge`.
- `ops-hub` is expected to need implementation assets such as collectors,
adapters, scheduled probes, bootstrap smoke tooling, and possibly UI beyond
Inter-Hub's generic hub dashboards.
- `ops-hub` needs its own workplan prefix, release lifecycle, and repository
agent instructions once implementation begins.
- Keeping deployable/runtime code out of `inter-hub` preserves Inter-Hub as the
generic hub framework while still allowing `ops-hub` to be included as a
VSM Operations / System 1 extension.
Until then, keep the model in `helix-forge` and register state in Inter-Hub.
Repository boundary:
Done when: the decision is recorded with rationale and a repo boundary if
needed.
- `ops-hub`: implementation home for the Operations hub extension, including
collectors, adapters, scheduled probes, runtime packaging, UI/extensions,
tests, and Inter-Hub bootstrap/smoke clients.
- `inter-hub`: generic framework, extension registry, hub manifests, API
consumers, authentication, widgets, event persistence, and bootstrap API.
- `helix-forge`: product/architecture intent, VSM extension pattern,
coordination workplan, and current bootstrap handoff artifacts until they
are ported or retired.
- Railiance repos: desired state, deployment, backup/restore evidence, and
operational facts for their owned infrastructure and services.
Done: the decision is recorded with rationale and boundary; future
implementation should happen in `ops-hub`.
---
@@ -633,7 +655,7 @@ needed.
```task
id: HF-WP-0001-T10
status: in_progress
status: wait
priority: high
target_repo: inter-hub
state_hub_task_id: "7fa54508-7add-4885-8913-12edaadc4d92"
@@ -673,6 +695,39 @@ calls and without direct DB access.
Linked Inter-Hub workplan:
`inter-hub/workplans/IHUB-WP-0019-vsm-hub-bootstrap-api.md`.
Source implementation status as of 2026-06-14:
- `IHUB-WP-0019` is finished in the local `inter-hub` repo, and
`main` is aligned with `origin/main`.
- The documented smoke path exists at
`/home/worsch/inter-hub/scripts/ops-hub-bootstrap-smoke.py`.
- The `ops-hub` implementation repo has the handoff track
`workplans/OPS-WP-0002-interhub-extension-bootstrap.md`; its production gate
probe is `scripts/interhub-gate-probe.py`.
Current production gate as of 2026-06-06:
- Do not proceed with manual DB seeding unless the operator explicitly chooses
that fallback.
- Wait for `https://hub.coulomb.social/api/v2/hubs` to return `401`
unauthenticated instead of `404`.
- Confirm OpenAPI lists `/hubs`, `/hub-capability-manifests`,
`/api-consumers`, and `/policy-scopes`.
- After the gate passes, run the supported bootstrap/smoke path from the
relevant `inter-hub` or `ops-hub` tooling with `IHUB_BASE` and an operator
key.
Production gate recheck on 2026-06-14:
- `ops-hub/scripts/interhub-gate-probe.py` against
`https://hub.coulomb.social` still fails.
- `GET /api/v2/hubs` returns `404`, not `401`.
- The live OpenAPI still omits `/hubs`, `/hub-capability-manifests`,
`/api-consumers`, and `/policy-scopes`.
- Result: source-side API hardening is complete, but HF-WP-0001 remains gated
on deployment of the current Inter-Hub API or an explicit operator decision
to use the manual SQL fallback.
## Initial Acceptance Criteria
This workplan is complete when:
@@ -722,6 +777,49 @@ Next required operator action:
`wiki/ops-hub-bootstrap.sql` from a host that already has access to the
`net-kingdom-pg-1` pod in the `databases` namespace.
### 2026-06-06 — ops-hub repo decision
The operator decided that `ops-hub` should live in its own repository and be
included as an extension of Inter-Hub. The repo is available locally at
`/home/worsch/ops-hub` with remote `gitea-remote:coulomb/ops-hub.git`.
Result:
- HF-WP-0001 T09 is closed as `done`.
- `ops-hub` implementation work moves to the `ops-hub` repo.
- `helix-forge` keeps architecture, vocabulary, readiness, and bootstrap
handoff references.
- Inter-Hub remains the generic extension framework and still owns the
bootstrap API hardening tracked by T10.
- Live bootstrap remains gated on current Inter-Hub production API availability
unless the operator explicitly chooses the manual SQL fallback.
### 2026-06-14 — production API gate recheck
Rechecked the live Inter-Hub bootstrap gate from the dedicated `ops-hub`
implementation repo:
```text
python3 scripts/interhub-gate-probe.py
```
Result:
- `https://hub.coulomb.social/api/v2/hubs` returns `404`.
- `https://hub.coulomb.social/api/v2/openapi.json` returns `200`, but the
required bootstrap paths are absent.
- Missing paths: `/hubs`, `/hub-capability-manifests`, `/api-consumers`, and
`/policy-scopes`.
Interpretation:
- Inter-Hub source work for `IHUB-WP-0019` is complete and pushed to
`origin/main`.
- Production is still serving an older API surface, so the preferred
ops-hub bootstrap path cannot run yet.
- HF-WP-0001 T10 is moved to `wait` until the production API is deployed or the
operator explicitly chooses the manual SQL fallback.
## Notes
`ops-hub` should complement State Hub during the transition: