coulomb/coulomb-social
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Bootstrap coulomb-social: INTENT, SCOPE, TRSL, agent files, State Hub

Browse source 
Prepare the greenfield rebuild of coulomb.social (bubble.io exit) with
orientation docs, TRSL license, Claude/Codex agent integration, and repo
classification under domain communication / topic coulomb-social. Workplan
CSOC-WP-0001 (exit assessment) is already registered via fix-consistency.
This commit is contained in:
tegwick 2026-08-09 00:35:12 +02:00
parent c0189118b4
commit 0da8d36a73
19 changed files with 961 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

20
.claude/rules/agents.md Normal file
View file

@ -0,0 +1,20 @@
## Kaizen Agents
Specialized agent personas available on demand via the state-hub MCP.
**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
Common agents:
| Agent | Category | When to use |
|-------|----------|-------------|
| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
| `code-refactoring` | quality | Code quality analysis and safe refactoring |
| `test-maintenance` | testing | Diagnose and fix failing tests |
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
| `keepaTodofile` | process | Maintain TODO.md during work |
| `project-management` | process | Track status, determine next steps |
| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
All 17 agents: call `list_kaizen_agents()` for the full list.

19
.claude/rules/architecture.md Normal file
View file

@ -0,0 +1,19 @@
## Architecture
**Target shape:** standalone business application (DR-2 B).
| Layer | Direction |
|-------|-----------|
| Product UI | Code-owned UI replacing bubble.io pages (stack TBD after feature cut) |
| Domain model | Relational, tenant-keyed from migration one |
| Identity | App-local member accounts (DR-3 A); single auth module for later OIDC |
| Delivery | commit-SHA images → `gitea.coulomb.social/coulomb/coulomb-social` → `railiance-apps` → railiance01 |
| Contract | business-app service contract v0.1 §§1–6 |
Reference implementation for the delivery lane: `vergabe-teilnahme`.
Current maturity: orientation and assessment only — no application runtime yet.
## Quick Reference
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

50
.claude/rules/credential-routing.md Normal file
View file

@ -0,0 +1,50 @@
## 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)
```bash
warden route find "<describe your need>" --json
warden route show <catalog-id> --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=coulomb-social` is for coordination, not secret vending |
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **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`

42
.claude/rules/first-session.md Normal file
View file

@ -0,0 +1,42 @@
## First Session Protocol
Triggered when `get_domain_summary("communication")` shows **no workplans**.
The project is registered but work has not yet been structured.
**Step 1 — Read, don't write**
- `~/the-custodian/canon/projects/communication/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/communication/roadmap_v0.1.md` — planned phases
- Scan repo root: README, directory structure, existing code or docs
**Step 2 — Survey in-progress work**
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
**Step 3 — Propose workplans to Bernd**
Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
roadmap phase. **Wait for approval before creating.**
**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
```
workplans/CSOC-WP-NNNN-<slug>.md ← write this, commit it
```
Then register by running the consistency check — do **not** call
`create_workplan`/`create_task` yourself; manual registration duplicates what
C-06 creates from the file:
```bash
statehub fix-consistency --repo coulomb-social
```
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
back into the file.
**Step 5 — Record the setup**
```
add_progress_event(
summary="First session: structured communication into N workplans, M tasks",
event_type="milestone",
topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc",
detail={"workplans": [...], "tasks_created": M}
)
```
<!-- Delete or archive this file once past first session -->

10
.claude/rules/repo-boundary.md Normal file
View file

@ -0,0 +1,10 @@
## Repo boundary
This repo owns **coulomb.social product rebuild** only. It does not own:
- Railiance cluster / mesh / app-chart infrastructure → `railiance-*`
- Platform identity / OpenBao custody → `net-kingdom`
- HelixForge standards and capability vocabulary → `helix-forge`
- State Hub / Custodian coordination service → `state-hub` / `the-custodian`
- Fleet self-improvement loops → `coulomb-loop`
- ops-hub / fin-hub platform services (only consume registration and cost keys)

5
.claude/rules/repo-identity.md Normal file
View file

@ -0,0 +1,5 @@
**Purpose:** Reimplementation of the coulomb.social co-creation platform on Railiance/NetKingdom/HelixForge, exiting stalled bubble.io.
**Domain:** communication
**Repo slug:** coulomb-social
**Topic ID:** 36c7421b-c537-4723-bf75-42a3ebc6a1dc

100
.claude/rules/session-protocol.md Normal file
View file

@ -0,0 +1,100 @@
## Session Protocol
Dev Hub (State Hub API): http://127.0.0.1:8000
MCP server name in `~/.claude.json`: `dev-hub`
**Step 1 — Orient**
Read the offline-safe brief first — it works without a live hub connection:
```bash
cat .custodian-brief.md
```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
```
get_domain_summary("communication")
```
If MCP tools are unavailable in the current agent session, use the REST API:
```bash
curl -s "http://127.0.0.1:8000/state/summary" | 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="coulomb-social", unread_only=True)
```
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
requests before proceeding.
Without MCP tools:
```bash
curl -s "http://127.0.0.1:8000/messages/?to_agent=coulomb-social&unread_only=true" \
| python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
**Step 3 — Scan workplans**
```bash
ls workplans/
```
For each file with `status: ready`, `active`, or `blocked`, note pending
`wait`/`todo`/`progress` tasks.
**Step 4 — Present brief**
1. **Active workplans** for `communication` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:coulomb-social]` hub tasks
3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
- `alignment_warnings`: flag if active work is not aligned with current goal
4. **Suggested next action** — highest-priority open item
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
If no workplans: follow First Session Protocol (`first-session.md`).
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
> State Hub is a *read model*. **Never register workplans or tasks by hand**
> (`create_workplan`, `create_task`) — write the workplan file in `workplans/`
> and run `fix-consistency`; C-06 registers the workplan and tasks and writes
> IDs back into the file. Manual registration creates duplicates when
> fix-consistency runs. Work structure belongs in repo files (ADR-001).
>
> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
> see `workplan-convention.md` (compatibility footnote).
**Session close:**
1. Update workplan/task statuses in repo files.
2. If marking a workplan **finished**: hand off residuals as **live work
records** first (intake with `origin: residual` + `origin_ref: <WP-id>`, or
a child workplan / decision / engagement). Do not leave actionable leftovers
only as prose or in `SCOPE.md`. See work-record-types § Residuals.
3. Log progress (below).
4. `statehub fix-consistency` when workplan/queue files changed.
With MCP tools:
```
add_progress_event(summary="...", topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", workplan_id="<uuid>")
```
Without MCP tools:
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{"topic_id":"36c7421b-c537-4723-bf75-42a3ebc6a1dc","workplan_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
```
If workplan files were modified, ensure the local copy is up to date first,
then sync from the repo checkout:
```bash
git pull --ff-only
statehub fix-consistency
```
For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the pull-before-fix mode from any shell with the State Hub CLI:
```bash
statehub fix-consistency --repo coulomb-social --remote
```
**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.

24
.claude/rules/stack-and-commands.md Normal file
View file

@ -0,0 +1,24 @@
## Stack
Greenfield rebuild. Application stack is **not yet chosen**; expect alignment
with the business delivery lane (`vergabe-teilnahme` is Django + Vite today).
Decide stack only after CSOC-WP-0001 feature cut if it affects export/schema.
- **Language:** TBD (implementation starts in CSOC-WP-0002)
- **Hosting:** Railiance (railiance01) via `railiance-apps` release values
- **Registry:** `gitea.coulomb.social/coulomb/coulomb-social`
- **License:** TRSL V1C1 (`LICENSE`)
## Dev Commands
```bash
# Orientation (always available)
cat INTENT.md SCOPE.md .custodian-brief.md
ls workplans/
# State Hub
curl -s http://127.0.0.1:8000/state/health
statehub fix-consistency
# After application scaffold exists, add install / test / lint / build here.
```

71
.claude/rules/workplan-convention.md Normal file
View file

@ -0,0 +1,71 @@
## Workplan Convention (ADR-001)
File location: `workplans/CSOC-WP-NNNN-<slug>.md`
ID prefix: `CSOC-WP-`
Work items originate as files in this repo **before** being registered in the hub.
Canonical workplan frontmatter statuses are:
`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
Use `proposed` for a newly drafted plan, `ready` after review against current
repo state, and `finished` when implementation is complete. `stalled` and
`needs_review` are derived health labels, not stored statuses.
Closed workplans may be moved to `workplans/archived/` with a completion-date
prefix: `YYMMDD-CSOC-WP-NNNN-<slug>.md`. The frontmatter id remains
unchanged; the prefix is only for quick visual reference.
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
`workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids
`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
directly. Promote anything requiring analysis, design, approval, dependencies, or
multiple planned phases into a normal workplan.
Ecosystem todos from other agents arrive as `[repo:coulomb-social]` hub tasks —
visible at session start. Pick one up by creating the workplan file, committing,
and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).
Task blocks use this shape:
```task
id: CSOC-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
```
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
blocked work and `cancel` for stopped work.
### Residuals (role, not kind)
When finishing a workplan, **actionable leftovers must become live work
records** before `status: finished`. Residual is not a registered kind and
must not be parked only in `SCOPE.md` or finished-file prose.
| Shape | Capture as | Links |
| --- | --- | --- |
| Small Green/Blue parkable | intake (queue YAML / `*-IN-*`) | `origin: residual`, `origin_ref: CSOC-WP-NNNN` |
| Multi-step | next workplan | name parent WP; optional promote from residual intake |
| Founder gate / time | decision / engagement | same origin fields when from residual intake |
Fleet listing of residuals is a State Hub concern (`list_intakes` + origin
filters; planned `statehub residuals`). Canon:
`the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
kept for compatibility; it holds the hub workplan UUID and is written by
fix-consistency. Do not edit or rename it.
### Legacy terminology (compatibility footnote)
**Workplan** is the fleet term — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Workstream** is legacy only: some API routes (`/workstreams/`), params
(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
examples and scripts.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

5
.gitignore vendored Normal file
View file

@ -0,0 +1,5 @@
# state-hub: track .claude/rules
# Claude Code local state (track shared rules; ignore machine-specific files)
.claude/*
!.claude/rules/
!.claude/rules/*.md

19
.repo-classification.yaml Normal file
View file

@ -0,0 +1,19 @@
repo_classification:
standard: Repo Classification Standard
version: '1.0'
classified_at: '2026-08-09'
classified_by: agent
category: experimental
domain: communication
secondary_domains: []
capability_tags:
- marketplace
- collaboration
- tenancy
- user-management
business_stake:
- product
- sales
business_mechanics:
- coordination
- operation

199
AGENTS.md Normal file
View file

@ -0,0 +1,199 @@
# coulomb-social — Agent Instructions
## Repo Identity
**Purpose:** Reimplementation of the coulomb.social co-creation platform on Railiance/NetKingdom/HelixForge, exiting stalled bubble.io.
**Domain:** communication
**Repo slug:** coulomb-social
**Topic ID:** `36c7421b-c537-4723-bf75-42a3ebc6a1dc`
**Workplan prefix:** `CSOC-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and
the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge
adds severe call latency; the full administrative MCP surface remains available
to clients that need it.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
| Optional local edge relay | http://127.0.0.1:18080 |
When an operator has enabled the edge relay, set API_BASE to the relay URL.
Queueable writes return an explicit queued receipt if the central hub is
unreachable. Treat that as pending local evidence, then ask the operator to run
statehub outbox status/replay after connectivity returns.
Codex workspace-write sandboxes need network access enabled to reach the host's
loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex`
and restart Codex. The canonical REST health endpoint is `/state/health`, not
`/health`. If a sandboxed loopback probe fails, retry it with escalated execution
before declaring State Hub unavailable; a managed Codex permission profile may
still enforce isolated networking. Experimental MCP can be enabled explicitly
with `make -C ~/state-hub configure-codex WITH_MCP=1`.
### Orient at session start
```bash
# Offline brief — works without hub connection
cat .custodian-brief.md
# Active workplans for this domain
curl -s "http://127.0.0.1:8000/workplans/?topic_id=36c7421b-c537-4723-bf75-42a3ebc6a1dc&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=coulomb-social&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",
"workplan_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workplan_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": "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/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
2. Check inbox: `GET /messages/?to_agent=coulomb-social&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`
**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. If finishing a workplan: hand off **residuals** as live work records first
(intake with `origin: residual` + `origin_ref: <WP-id>`, or a next workplan /
decision / engagement). Do not park leftovers only in prose or `SCOPE.md`.
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
3. Log: `POST /progress/` with a summary of what changed (name handoff ids)
4. After workplan file changes, run:
```bash
statehub fix-consistency
```
Coding agents should run this directly; ask the operator only if the CLI or
State Hub API is unavailable. This syncs task status from files into the hub DB.
---
{CREDENTIAL_ROUTING}
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention (ADR-001)
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/CSOC-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-CSOC-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: CSOC-WP-NNNN
type: workplan
title: "..."
domain: communication
repo: coulomb-social
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # fix-consistency — do not edit (legacy field name; workplan UUID)
---
```
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.
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: CSOC-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
**Residuals when finishing:** actionable leftovers become live work records
before `status: finished` — usually an intake (`origin: residual`,
`origin_ref: CSOC-WP-NNNN`) or a spawned workplan. Residual is a *role*,
not a kind. Fleet list lives on State Hub, not in `SCOPE.md`.
To create a new workplan:
1. Write the file following the format above
2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or
State Hub API is unavailable.

12
CLAUDE.md Normal file
View file

@ -0,0 +1,12 @@
# coulomb-social — Claude Code Instructions
@SCOPE.md
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/credential-routing.md
@.claude/rules/agents.md

7
GOAL.md Normal file
View file

@ -0,0 +1,7 @@
This repository should reimplement the coulomb.social platform that is currently based on bubble.io
as a railiance, netkingdom, helixforge based infrastructure. I want the project to duplicate all
the userinterface, all the content in order to switch from the stalled lowcode development to our
much more dynamic agentic coding approach.
We will start with setting up INTENT.md and SCOPE.md the License should be TRSL as the other repos.
Prepare this repo and register it with statehub please.

74
INTENT.md Normal file
View file

@ -0,0 +1,74 @@
---
repo: coulomb-social
updated: "2026-08-09"
status: bootstrap
---
# INTENT — coulomb-social
## Project Name
`coulomb-social`
## One-Line Intent
`coulomb-social` reimplements the **coulomb.social** co-creation platform — currently stuck on bubble.io — as a first-class application on the Railiance / NetKingdom / HelixForge stack, so product evolution can move at agentic coding speed instead of low-code stall.
## Purpose
coulomb.social is Coulomb's co-creation marketplace: people and teams find each other around shared projects and complementary capabilities. The live product still runs on bubble.io. That path is **stalled**: low-code velocity no longer matches the rest of the Coulomb fleet, content and UI are hard to evolve with agents, and the platform cannot meet the business-app service contract (tenancy, backup, cost attribution, image provenance).
This repository is the **owning home** for the rebuild:
1. **Parity capture** — inventory and export everything that matters in the bubble.io app (UI surfaces, workflows, data types, content, integrations).
2. **Cut decisions** — decide rebuild-as-is vs reduced v1 with an explicit human gate.
3. **Implementation** — deliver a standalone service on the proven business delivery lane (`vergabe-teilnahme` evidence), under the business-app service contract.
4. **Cutover** — migrate members and content off bubble.io when the new stack is ready.
Binky Hedgehog GmbH is **client #1** of its own platform (DR-2 B). The app is not a Core Hub extension; it is a normal client-facing business application.
## Core Idea
> Exit bubble.io by duplicating the product surface into an agentic, code-owned stack — not by bolting more low-code onto a stalled base.
The rebuild is deliberately **product-faithful first**: UI and content parity matter so the community does not experience a feature cliff at cutover. Scope reductions, if any, are explicit decisions (CSOC-WP-0001-T03), not accidental omissions.
## Platform Shape (decided)
| Concern | Decision |
|---------|----------|
| Shape | Standalone service — own repo, own DB, own release values (DR-2 B) |
| Tenancy | Instance-per-client deployment; tenant-keyed data model from migration one (DR-1 C) |
| Identity | App-local member accounts in v1; auth behind a single module for later OIDC (DR-3 A) |
| Delivery lane | commit-SHA images → `gitea.coulomb.social/coulomb/coulomb-social` → `railiance-apps` values → railiance01 |
| Contract | `the-custodian` `canon/standards/business-app-service-contract_v0.1.md` §§1–6 |
## What Success Looks Like
1. Full inventory of the bubble.io product (pages, workflows, data, integrations) is recorded in this repo.
2. Exportable data is mapped to a relational, tenant-keyed model and rehearsal-imported at least once.
3. A human-gated feature cut (rebuild-as-is vs reduced v1) is decided and recorded.
4. v1 implementation satisfies the business-app service contract before serving members.
5. Members and content can cut over from bubble.io without relying on the low-code platform for further development.
## Design Principles
1. **Own the product in code** — UI, domain model, and content pipelines live in git so agents can change them safely.
2. **Parity before cleverness** — match the existing product surface before inventing net-new platform features.
3. **Contract first** — tenancy keying, backup/restore path, ops-hub registration, and cost attribution keys are not afterthoughts.
4. **Reuse the delivery lane** — follow `vergabe-teilnahme` patterns for build, image, and railiance-apps release; do not invent a second path.
5. **Stack boundaries** — Railiance owns runtime hosting, NetKingdom owns platform identity/secrets direction, HelixForge owns capability vocabulary; this repo owns the coulomb.social product.
## Scope Summary
**In:** product rebuild, bubble exit assessment, data migration, UI/content parity, app-local auth, railiance delivery packaging.
**Out:** owning Railiance/NetKingdom/HelixForge platform code; remaining on bubble.io as the long-term development surface; Core Hub embedding.
## Related Documents
- `GOAL.md` — operator bootstrap note for this repo
- `SCOPE.md` — in/out boundaries and orientation
- `the-custodian/docs/coulomb-social-rebuild-seed.md` — original workplan seed (CUST-WP-0058-T08)
- `the-custodian/canon/standards/business-app-service-contract_v0.1.md`
- Reference delivery lane: `vergabe-teilnahme`

151
LICENSE Normal file
View file

@ -0,0 +1,151 @@
# Target Revenue Source License
**Version 1.0, Candidate 1 (V1C1)**
---
> **PRELIMINARY CANDIDATE — SUBJECT TO CHANGE — NOT FINAL**
>
> This repository is governed by the Target Revenue Source License
> (TRSL), Version 1, Candidate 1. This is the framework's first working
> candidate, adopted as the org's preliminary operating license across
> all repos (maintainer decision, 2026-07-29) during the build/alpha
> stage — see `SCOPE.md` §1 and Appendix A of the canonical text (link
> below) for the alpha/beta risk-acceptance decision this reflects and
> what it does and does not mean. Full specialist legal review is
> explicitly deferred until the framework moves out of beta.
>
> **Canonical source, full candidate-status banner, and Appendix A
> (non-normative candidate notes tracking every open item):** the
> `coulomb` org's `target-revenue` repository,
> `specs/TargetRevenueSourceLicense-V1C1.md` — this file is the operative
> legal text (Preamble through Section 11) only; the canonical document
> is authoritative if this copy and that document ever diverge.
---
## Preamble
This Target Revenue Source License ("**License**") governs the Software identified in the applicable Phase Manifest. It implements the Target Revenue Framework: a defined development Phase accumulates Development Credit and Remission Credit against an immutable Initial Target until the Milestone Release automatically and irrevocably converts to a declared permissive Future License.
Commercial beneficiaries fund the creation and early availability of a software improvement; once the declared target is satisfied, the governed release becomes permissively open source.
## 1. Definitions
Capitalized terms used in this License have the meanings given below. Where a term is also defined in the Phase Manifest or Target Ledger for a specific Phase, the Phase Manifest and Target Ledger govern the *values* (amounts, dates, identifiers) and this License governs the *legal effect* of those values — the two must not be read as conflicting definitions of the same concept.
**"Commercial Entitlement"** means a right, purchased or otherwise granted under a Commercial Use Agreement, to make Commercial Use of the Software during a Phase.
**"Commercial Use"** means billing, invoicing, or otherwise charging any customer a fee, subscription, license fee, or other consideration for or in connection with use of the Software, at any time before the Conversion Event for the applicable Phase, regardless of whether the person or organization billed would otherwise qualify for Noncommercial Use. Commercial Use occurs by virtue of such billing alone, whether or not the resulting payment is registered with the Trust Service; in particular, billing a customer for pre-conversion use of the Software without recording the corresponding payment in the applicable Phase's Target Ledger is Commercial Use without a valid Commercial Entitlement — a violation of Section 3, addressed under Section 7 and, where applicable, the Enforcement Network described in the canonical repository's `specs/EnforcementNetworkConcept.md`.
**"Commercial Use Agreement"** means the separate agreement, referenced by the applicable Phase Manifest, under which a Commercial Entitlement is purchased or granted. This License does not itself set pricing, metering, or payment terms — those are governed by the Commercial Use Agreement.
**"Conversion Event"** means the moment the Outstanding Target for a Phase reaches zero, as computed from the Phase Manifest and Target Ledger per the Target Ledger Specification. The Conversion Event occurs automatically and is not conditioned on any declaration, attestation, or other act by the Licensor or any Trust Service.
**"Development Credit"** means the portion of a collected and settled payment explicitly allocated toward satisfying the Initial Target of a specific Phase, as recorded in that Phase's Target Ledger.
**"Future License"** means the permissive license identified in the applicable Phase Manifest, being either the MIT License or the Apache License, Version 2.0, which applies to the Milestone Release upon the Conversion Event.
**"Initial Target"** means the immutable monetary target declared for a Phase in its Phase Manifest.
**"Licensor"** means **Binky Hedgehog GmbH**, the party that publishes the Phase Manifest and holds the rights necessary to grant this License and the Future License for the Milestone Release.
**"Milestone Release"** means the precisely identified software release designated in the applicable Phase Manifest, identified by an immutable source revision, release artifact, or cryptographic digest.
**"Noncommercial Use"** means use of the Software for personal purposes, private study, hobby or amateur projects; use by any charitable organization, educational institution, public research organization, or government institution acting in a non-revenue-generating capacity; or other use of a materially similar character.
**"Outstanding Target"** means, at any time, `max(0, Initial Target − cumulative Development Credit − cumulative Remission Credit)` for a Phase, as computed from that Phase's Target Ledger.
**"Phase"** means a bounded development undertaking governed by one Initial Target, one Milestone Release, one degeneration policy, and one Future License declaration, as declared in a Phase Manifest.
**"Phase Manifest"** means the published, immutable declaration identifying a Phase, its Milestone Release, Initial Target, Future License, degeneration policy, and Target Ledger location, as specified in the Phase Manifest Specification.
**"Remission Credit"** means a transparent, non-revenue reduction of a Phase's Outstanding Target, generated under that Phase's published degeneration policy and recorded in the Target Ledger.
**"Settled Payment"** means a payment that has cleared through its payment processor and is no longer subject to reversal in the ordinary course (chargeback, dispute, or equivalent), as further specified by the applicable Commercial Use Agreement or monetization extension.
**"Software"** means the source code, object code, and associated documentation of the Milestone Release identified in the applicable Phase Manifest.
**"Target Ledger"** means the append-only record of Development Credit, Remission Credit, and correction entries for a Phase, as specified in the Target Ledger Specification.
**"You"** or **"Licensee"** means the individual or entity exercising rights under this License.
## 2. Grant of Rights for Noncommercial Use
Subject to the terms of this License, the Licensor grants You a worldwide, royalty-free, non-exclusive license, during the applicable Phase, to:
(a) use, reproduce, and study the Software for any Noncommercial Use;
(b) modify the Software and create derivative works of it for any Noncommercial Use; and
(c) redistribute the Software and Your modifications, in source or object form, for any Noncommercial Use, provided that You include this License, unmodified, with any such redistribution, and that You do not remove or alter any copyright, patent, trademark, or attribution notices contained in the Software.
This grant does not extend to Commercial Use. Commercial Use requires a Commercial Entitlement under Section 3.
## 3. Commercial Use
You may not make Commercial Use of the Software during the applicable Phase unless You hold a valid, current Commercial Entitlement under a Commercial Use Agreement with the Licensor covering the applicable Phase. A Commercial Entitlement granted under one Phase's Commercial Use Agreement does not extend to a later Phase's Milestone Release unless the Commercial Use Agreement expressly says so.
This Section 3 states the existence and boundary of the commercial-use restriction. It does not itself set pricing, invoicing, metering, audit rights, or payment terms — those are governed exclusively by the applicable Commercial Use Agreement.
## 4. Patent License
Subject to the terms of this License, each contributor to the Software grants You, during the applicable Phase and solely to the extent of rights granted under Sections 2 and 3, a perpetual (subject to the termination below), worldwide, non-exclusive, no-charge, royalty-free patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Software, limited to those patent claims licensable by that contributor that are necessarily infringed by their contribution(s) alone or by combination of their contribution(s) with the Software.
If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Software or a contribution incorporated within it constitutes direct or contributory patent infringement, then any patent licenses granted to You under this Section 4 for the Software shall terminate as of the date such litigation is filed.
## 5. Automatic Conversion to the Future License
**5.1 Automatic effect.** Upon the Conversion Event for a Phase, the rights and restrictions in Sections 3 (Commercial Use) of this License, as they apply to that Phase's Milestone Release, terminate automatically. In their place, the Milestone Release is licensed under the Future License identified in that Phase's Phase Manifest, effective as of the Conversion Event, without any further act, declaration, or attestation required by the Licensor, any Trust Service, or any other party.
**5.2 Irrevocability.** Once a valid Conversion Event has occurred for a Phase, no subsequent refund, chargeback, accounting correction, dispute, or termination of this License for an unrelated breach shall revoke, suspend, or otherwise impair the Future License grant for that Phase's Milestone Release. Any shortfall or dispute arising after a Conversion Event is a commercial or accounting matter between the relevant parties and does not reinstate a commercial-use restriction over already-converted Software.
**5.3 Prior freedom preserved.** A later Phase covering subsequent improvements to the Software does not restrict, withdraw, or otherwise affect the rights granted under the Future License for an earlier Phase's already-converted Milestone Release.
**5.4 Evidence, not cause.** A Trust Service may publish a Conversion Attestation documenting a Conversion Event. Such an attestation is evidence that the Conversion Event occurred; it is not a condition of, and its absence or delay does not postpone, the automatic effect described in Section 5.1. Any person may independently verify whether a Conversion Event has occurred directly from the Phase Manifest and Target Ledger.
## 6. Successive Phases
The Licensor may declare a new Phase covering subsequent improvements to the Software following a Milestone Release's Conversion Event. Each Phase is independently governed by its own Phase Manifest, Initial Target, degeneration policy, and Target Ledger. Nothing in a later Phase's Phase Manifest may be construed to reduce or withdraw rights already granted under Section 5 for an earlier Phase's Milestone Release.
## 7. Term and Termination
**7.1 Term.** This License applies to the Software for the duration of the applicable Phase, and, for the Milestone Release, indefinitely following that Phase's Conversion Event under the Future License.
**7.2 Termination for breach.** If You breach Section 3 (Commercial Use) or Section 2(c) (redistribution notice requirement), the Licensor may terminate this License as to You. Before such termination becomes effective, the Licensor shall provide You written notice of the breach; if You cure the breach within thirty (30) days of that notice, this License continues in effect. A second breach of the same provision within twelve (12) months may be terminated immediately without a further cure opportunity.
**7.3 Effect of termination.** Termination under this Section 7 affects only Your rights under Sections 2 and 3 for the Phase in which the breach occurred. It does not affect any rights already vested under Section 5 (Automatic Conversion) for a Milestone Release whose Conversion Event has already occurred, per Section 5.2.
**7.4 Public record of breach and resolution.** The Licensor shall cause the Trust Service to publish, as part of the public record for the affected Phase, notice of: (a) any breach notice issued under Section 7.2, stating the general nature of the breach and the date of notice; (b) whether the breach was cured within the applicable cure period, and the date of cure; and (c) any termination determination made under this Section 7, including its effective date and scope. This public record exists to give the ecosystem a transparent, verifiable conformity signal for the Phase, distinct from and in addition to the Development Credit and Remission Credit facts already published under Section 5.4 and the Target Ledger Specification.
A breach that You dispute, and that has not been finally determined, shall be recorded as **alleged**; it shall be recorded as **determined** only once the cure period has run without cure, or the dispute has been resolved against You under the applicable Commercial Use Agreement's dispute process, if any. The Trust Service shall update the record promptly upon resolution in either direction. Recording an alleged or determined breach under this Section 7.4 is a ministerial act of publishing the Licensor's determination (or a dispute process's outcome); it does not give the Trust Service discretionary authority to decide whether a breach occurred, consistent with Section 5.4's evidence-not-cause principle.
Whether, and under what conditions, the public record identifies a Commercial Entitlement holder by name is governed exclusively by the applicable Commercial Use Agreement, which the Licensor and that Commercial Entitlement holder negotiate and agree to directly. This License does not itself set a naming default. Where no Commercial Use Agreement addresses the question, or where the affected party has no Commercial Use Agreement at all (for example, a Section 2(c) breach by a Noncommercial Use licensee), the public record states the Phase and breach category only, without naming the party.
## 8. Disclaimer of Warranty
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR THAT ANY PHASE WILL REACH ITS CONVERSION EVENT.
## 9. Limitation of Liability
IN NO EVENT SHALL THE LICENSOR OR ANY CONTRIBUTOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE, EXCEPT TO THE EXTENT SUCH LIMITATION IS PROHIBITED BY APPLICABLE LAW.
## 10. Trademarks
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary attribution.
## 11. General Provisions
**11.1 Governing law and venue.** Adopted for alpha/beta 2026-07-29: disputes arising under this License shall be resolved by binding arbitration, seated at a neutral, arbitration-mature venue (Singapore or London are the two candidates concretely supported by current research), rather than by litigation in a national court. The specific arbitral institution and substantive governing law remain a per-deployment blank pending final selection; they are not fixed by this candidate. See the canonical repository's `history/260729-TRSL-Jurisdiction-Synthesis.md` §2.
**11.2 Severability.** If any provision of this License is held unenforceable, the remaining provisions remain in full force, and the unenforceable provision shall be reformed to the minimum extent necessary to make it enforceable.
**11.3 No waiver.** Failure to enforce any provision of this License is not a waiver of future enforcement of that or any other provision.
**11.4 Entire agreement (as to licensing).** This License, together with the applicable Phase Manifest and, where applicable, the Commercial Use Agreement, constitutes the entire agreement between You and the Licensor regarding the Software's licensing terms. Operations, service, and consulting arrangements are governed by separate agreements, if any, and are not part of this License.
**11.5 Definitions control.** Marketing materials, documentation, or other non-normative communications about the Software must not describe pre-Conversion-Event Software as "Open Source," "free software," or "open core." Pre-conversion Noncommercial Use is **source-available**; pre-conversion Commercial Use requires a **Commercial Entitlement**; only post-conversion Software may be described as Open Source, under the Future License.
---
**No Phase is currently declared for this repository under this License.** Until a Phase Manifest is published and registered with the Trust Service for a Milestone Release in this repository, Sections 2–7 above have no operative subject matter here — this License establishes the governing framework in advance of that declaration, consistent with the org-wide rollout decision recorded in `target-revenue`'s `workplans/TREV-WP-0008-governance-and-pilot-rollout.md`.

36
README.md
View file

@ -1,3 +1,37 @@
# coulomb-social
Coulomb social cocreation platform
Reimplementation of the **coulomb.social** co-creation platform on the
Railiance / NetKingdom / HelixForge stack — exiting the stalled bubble.io
low-code product.
## Orientation
| Doc | Role |
|-----|------|
| [`INTENT.md`](INTENT.md) | Why this repo exists and what success means |
| [`SCOPE.md`](SCOPE.md) | In/out boundaries and when to use this repo |
| [`GOAL.md`](GOAL.md) | Bootstrap note that started this setup |
| [`LICENSE`](LICENSE) | Target Revenue Source License (TRSL V1C1) |
| [`AGENTS.md`](AGENTS.md) | Agent / State Hub session protocol |
| [`workplans/`](workplans/) | Active work (`CSOC-WP-*`) |
## Platform shape
Standalone business application (not a Core Hub extension):
- own database, tenant-keyed from migration one
- app-local member accounts (OIDC switch later)
- commit-SHA images → `gitea.coulomb.social/coulomb/coulomb-social`
- release values in `railiance-apps` → railiance01
Contract: business-app service contract v0.1 in `the-custodian`.
## Status
Bootstrap. Application code not yet scaffolded. First workstream is the
bubble.io exit assessment (`CSOC-WP-0001`).
## License
Target Revenue Source License (TRSL), Version 1 Candidate 1. See [`LICENSE`](LICENSE).
No Phase Manifest is declared yet.

103
SCOPE.md Normal file
View file

@ -0,0 +1,103 @@
# 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
Reimplementation of the coulomb.social co-creation platform as a standalone Railiance / NetKingdom / HelixForge application, exiting the stalled bubble.io stack.
---
## Core Idea
coulomb.social connects people around shared projects and complementary capabilities. Development on bubble.io has stalled. This repo owns the full product rebuild — UI, content, data model, and migration — so the platform can evolve with the rest of the Coulomb agentic fleet under the business-app service contract.
---
## In Scope
- Product intent, scope, workplans, and ADRs for the coulomb.social rebuild
- Inventory of the existing bubble.io app (pages, workflows, data types, integrations, content)
- Data export, relational schema mapping, and migration rehearsal
- Feature-cut decisions (rebuild-as-is vs reduced v1) and acceptance criteria
- Application implementation: UI parity, domain model, app-local accounts, APIs
- Packaging for the business delivery lane (commit-SHA images, railiance-apps release values)
- Tenant-keyed data model from the first migration; member account export/delete
- Ops/runbook stubs required by the business-app service contract (§§3–6)
- State Hub workplans, progress events, and classification for this repo
---
## Out of Scope
- Remaining on bubble.io as the primary development platform
- Owning Railiance cluster, platform, or app-chart infrastructure code (`railiance-*`)
- Owning NetKingdom identity platform implementation (Keycloak/OpenBao) — only the app-local auth boundary and future OIDC switch point live here
- Owning HelixForge standards or capability registry implementation
- Core Hub embedding or treating coulomb.social as a hub extension
- Fleet self-improvement loops (owner: `coulomb-loop`)
- Serving paying external multi-tenant SaaS before the service-contract preconditions are met
---
## Relevant When
- Planning or implementing the bubble.io exit and product rebuild
- Mapping coulomb.social features, content, or data into code-owned artifacts
- Packaging or deploying the coulomb.social app via the business delivery lane
- Checking tenancy, identity, backup, or cost-attribution obligations for this app
---
## Not Relevant When
- You need cluster or mesh infrastructure changes → use the relevant `railiance-*` repo
- You need platform SSO/secret custody work → use `net-kingdom` / OpenBao workplans
- You need fleet kaizen loop operation → use `coulomb-loop`
- You need a reference business-app implementation pattern → start with `vergabe-teilnahme`
- You only need the historical seed note → `the-custodian/docs/coulomb-social-rebuild-seed.md` (pointer; work originates here)
---
## Current State
- Status: bootstrap / greenfield
- Implementation: orientation docs only; no application code yet
- Stability: evolving
- Usage: internal — product rebuild not yet serving members from this stack
- Prior art: rebuild seed from CUST-WP-0058-T08; topic `coulomb-social` already exists in State Hub under domain `communication`
---
## How It Fits
- **Upstream decisions:** business-app service contract; DR-1 C / DR-2 B / DR-3 A
- **Delivery lane:** `vergabe-teilnahme` (pattern) → this repo (product) → `railiance-apps` (release values) → railiance01
- **Platform peers:** `railiance-*`, `net-kingdom`, `helix-forge`, `ops-hub`, `fin-hub`
- **Coordination:** State Hub topic `coulomb-social` (domain `communication`); related engagement repo `coulomb-loop`
---
## Getting Oriented
- Start with: `INTENT.md`, `GOAL.md`, `.custodian-brief.md`
- Key paths: `workplans/`, `docs/` (as they appear), application source (once scaffolded)
- First workplan: `workplans/CSOC-WP-0001-bubble-io-exit-assessment.md`
- Contract: `the-custodian/canon/standards/business-app-service-contract_v0.1.md`
---
## Related Repositories
| Repo | Relationship |
|------|----------------|
| `vergabe-teilnahme` | Reference business-app delivery lane |
| `railiance-apps` | Helm/release values for deploy |
| `railiance-forge` / `helix-forge` | Forge and capability patterns |
| `net-kingdom` | Future OIDC / platform identity |
| `coulomb-loop` | Fleet improvement loops (same State Hub topic) |
| `the-custodian` / `state-hub` | Coordination, standards, seed history |

15
WORK-RECORDS.md Normal file
View file

@ -0,0 +1,15 @@
# Work Records — coulomb-social
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
> stage 3). Do not edit by hand — edit the source file/block listed for
> each record and re-run fix-consistency to refresh this index. Archived
> workplans are omitted; closed decisions/intakes/engagements stay listed
> so recently-resolved work is still visible. [auto]
| Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- |
| workplan | CSOC-WP-0001 | ready | — | workplans/CSOC-WP-0001-bubble-io-exit-assessment.md |
| task | CSOC-WP-0001-T01 | todo | — | workplans/CSOC-WP-0001-bubble-io-exit-assessment.md |
| task | CSOC-WP-0001-T02 | todo | — | workplans/CSOC-WP-0001-bubble-io-exit-assessment.md |
| task | CSOC-WP-0001-T03 | wait | — | workplans/CSOC-WP-0001-bubble-io-exit-assessment.md |
| task | CSOC-WP-0001-T04 | todo | — | workplans/CSOC-WP-0001-bubble-io-exit-assessment.md |