generated from coulomb/repo-seed
Compare commits
12 Commits
fe2e98e2a4
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| cbfb3d0f74 | |||
| 20316c533f | |||
| 58a2cfac5c | |||
| 7312ed3767 | |||
| f9e661ec69 | |||
| f57a5c1dce | |||
| 757770b42f | |||
| 635521406f | |||
| 2afeb86ed2 | |||
| caa1e4100d | |||
| dae9e3409a | |||
| e23ed0c06b |
50
.claude/rules/credential-routing.md
Normal file
50
.claude/rules/credential-routing.md
Normal 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=railiance-fabric` 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`
|
||||
@@ -1,37 +1,41 @@
|
||||
## First Session Protocol
|
||||
|
||||
Triggered when `get_domain_summary("railiance")` shows **no workstreams**.
|
||||
Triggered when `get_domain_summary("financials")` shows **no workplans**.
|
||||
The project is registered but work has not yet been structured.
|
||||
|
||||
**Step 1 — Read, don't write**
|
||||
- `~/the-custodian/canon/projects/railiance/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/railiance/roadmap_v0.1.md` — planned phases
|
||||
- `~/the-custodian/canon/projects/financials/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/financials/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 workstreams to Bernd**
|
||||
Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
|
||||
**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 — Create workplan file first, then DB record (ADR-001)**
|
||||
**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
|
||||
```
|
||||
workplans/railiance-fabric-WP-NNNN-<slug>.md ← write this first
|
||||
workplans/RAILIANCE-WP-NNNN-<slug>.md ← write this, commit it
|
||||
```
|
||||
Then register in the hub:
|
||||
```
|
||||
create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", title="...", owner="...", description="...")
|
||||
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
|
||||
Then register by running the consistency check — do **not** call
|
||||
`create_workplan`/`create_task` (or legacy `create_workstream`) yourself;
|
||||
manual registration duplicates what C-06 creates from the file:
|
||||
```bash
|
||||
statehub fix-consistency --repo railiance-fabric
|
||||
```
|
||||
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` /
|
||||
`state_hub_task_id` back into the file (legacy field names, kept for
|
||||
compatibility — they hold workplan/task IDs).
|
||||
|
||||
**Step 5 — Record the setup**
|
||||
```
|
||||
add_progress_event(
|
||||
summary="First session: structured railiance into N workstreams, M tasks",
|
||||
summary="First session: structured financials into N workplans, M tasks",
|
||||
event_type="milestone",
|
||||
topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38",
|
||||
detail={"workstreams": [...], "tasks_created": M}
|
||||
detail={"workplans": [...], "tasks_created": M}
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
**Purpose:** railiance-fabric - (fill in purpose)
|
||||
|
||||
**Domain:** railiance
|
||||
**Domain:** financials
|
||||
**Repo slug:** railiance-fabric
|
||||
**Topic ID:** ca369340-a64e-442e-98f1-a4fa7dc74a38
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
## Session Protocol
|
||||
|
||||
State Hub: http://127.0.0.1:8000
|
||||
Dev Hub (State Hub API): http://127.0.0.1:8000
|
||||
MCP server name in `~/.claude.json`: `dev-hub`
|
||||
|
||||
**Step 1 — Orient**
|
||||
|
||||
@@ -10,7 +11,7 @@ cat .custodian-brief.md
|
||||
```
|
||||
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
|
||||
```
|
||||
get_domain_summary("railiance")
|
||||
get_domain_summary("financials")
|
||||
```
|
||||
If MCP tools are unavailable in the current agent session, use the REST API:
|
||||
```bash
|
||||
@@ -39,11 +40,11 @@ curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
ls workplans/
|
||||
```
|
||||
For each file with `status: ready`, `active`, or `blocked`, note pending
|
||||
`todo`/`in_progress` tasks.
|
||||
`wait`/`todo`/`progress` tasks.
|
||||
|
||||
**Step 4 — Present brief**
|
||||
|
||||
1. **Active workstreams** for `railiance` — title, task counts, blocking decisions
|
||||
1. **Active workplans** for `financials` — title, task counts, blocking decisions
|
||||
2. **Pending tasks** from `workplans/` + any `[repo:railiance-fabric]` hub tasks
|
||||
3. **Goal guidance** — if `goal_guidance` in summary:
|
||||
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
|
||||
@@ -51,33 +52,42 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
|
||||
4. **Suggested next action** — highest-priority open item
|
||||
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
|
||||
|
||||
If no workstreams: follow First Session Protocol (`first-session.md`).
|
||||
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*. Bootstrap tools (`create_workstream`, `create_task`)
|
||||
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
|
||||
> State Hub is a *read model*. **Never register workplans or tasks by hand**
|
||||
> (`create_workplan`, `create_task`, or the legacy `create_workstream`) — write
|
||||
> the workplan file in `workplans/` and run `fix-consistency`; its C-06 check
|
||||
> registers the workplan and its tasks in the hub and writes the IDs back into
|
||||
> the file. Manual registration creates duplicates the moment fix-consistency
|
||||
> runs. Work structure belongs in repo files (ADR-001).
|
||||
>
|
||||
> Terminology: "workstream" is the legacy name for workplan. Some API/frontmatter
|
||||
> field names keep it for compatibility (`state_hub_workstream_id`,
|
||||
> `workstream_id` params) — treat them as workplan IDs.
|
||||
|
||||
**Session close:**
|
||||
With MCP tools:
|
||||
```
|
||||
add_progress_event(summary="...", topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", workstream_id="<uuid>")
|
||||
add_progress_event(summary="...", topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", 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":"ca369340-a64e-442e-98f1-a4fa7dc74a38","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
|
||||
-d '{"topic_id":"ca369340-a64e-442e-98f1-a4fa7dc74a38","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:
|
||||
If workplan files were modified, ensure the local copy is up to date first,
|
||||
then sync from the repo checkout:
|
||||
```bash
|
||||
git -C <repo_path> pull --ff-only
|
||||
cd ~/state-hub && make fix-consistency REPO=railiance-fabric
|
||||
git pull --ff-only
|
||||
statehub fix-consistency
|
||||
```
|
||||
For repos where implementation runs on a remote machine (e.g. CoulombCore),
|
||||
use the combined target which pulls before fixing:
|
||||
use the pull-before-fix mode from any shell with the State Hub CLI:
|
||||
```bash
|
||||
cd ~/state-hub && make fix-consistency-remote REPO=railiance-fabric
|
||||
statehub fix-consistency --repo railiance-fabric --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
|
||||
|
||||
@@ -1,19 +1,14 @@
|
||||
## Stack
|
||||
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **Language:**
|
||||
- **Key deps:**
|
||||
- **Language:** Python ≥3.12 (`railiance_fabric` package)
|
||||
- **Key deps:** jsonschema, PyYAML; SQLite registry at `.railiance-fabric/registry.sqlite3`
|
||||
|
||||
## Dev Commands
|
||||
|
||||
```bash
|
||||
# TODO: Fill in the standard commands for this repo
|
||||
|
||||
# Install dependencies
|
||||
|
||||
# Run tests
|
||||
|
||||
# Lint / type check
|
||||
|
||||
# Build / package (if applicable)
|
||||
python3 -m pytest tests/ # run the test suite
|
||||
make graph-explorer # registry-backed graph explorer (HOST/PORT/REGISTRY_DB overridable)
|
||||
python3 -m railiance_fabric.server --db .railiance-fabric/registry.sqlite3
|
||||
```
|
||||
|
||||
Local-only tooling — no production deploy surface in this repo.
|
||||
|
||||
@@ -1,28 +1,45 @@
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/railiance-fabric-WP-NNNN-<slug>.md`
|
||||
ID prefix: `RAILIANCE-WP`
|
||||
File location: `workplans/RAILIANCE-WP-NNNN-<slug>.md`
|
||||
ID prefix: `RAILIANCE-WP-`
|
||||
|
||||
Work items originate as files in this repo **before** being registered in the hub.
|
||||
|
||||
Canonical workplan/workstream frontmatter statuses are:
|
||||
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-railiance-fabric-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
prefix: `YYMMDD-RAILIANCE-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`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
|
||||
`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:railiance-fabric]` hub tasks —
|
||||
visible at session start. Pick one up by creating the workplan file, then registering
|
||||
the workstream.
|
||||
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`/`create_workstream`.
|
||||
|
||||
Task blocks use this shape:
|
||||
|
||||
```task
|
||||
id: RAILIANCE-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.
|
||||
|
||||
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
|
||||
kept for compatibility ("workstream" is the old term for workplan); it holds
|
||||
the hub workplan id and is written by fix-consistency. Do not edit or rename it.
|
||||
|
||||
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
<!-- custodian-brief: generated by fix-consistency — do not edit manually -->
|
||||
# Custodian Brief — railiance-fabric
|
||||
|
||||
**Domain:** railiance
|
||||
**Last synced:** 2026-06-05 19:36 UTC
|
||||
**Domain:** financials
|
||||
**Last synced:** 2026-07-01 22:24 UTC
|
||||
**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
|
||||
|
||||
## Active Workstreams
|
||||
@@ -13,6 +13,6 @@
|
||||
## MCP Orientation (when available)
|
||||
|
||||
If the state-hub MCP server is reachable, call:
|
||||
`get_domain_summary("railiance")`
|
||||
`get_domain_summary("financials")`
|
||||
This provides richer cross-domain context.
|
||||
If the MCP call fails, use this file as your orientation source.
|
||||
|
||||
17
.repo-classification.yaml
Normal file
17
.repo-classification.yaml
Normal file
@@ -0,0 +1,17 @@
|
||||
repo_classification:
|
||||
standard: Repo Classification Standard
|
||||
version: '1.0'
|
||||
classified_at: '2026-06-22'
|
||||
classified_by: agent
|
||||
category: project
|
||||
domain: financials
|
||||
secondary_domains: []
|
||||
capability_tags:
|
||||
- platform
|
||||
- operations
|
||||
business_stake:
|
||||
- technology
|
||||
- operations
|
||||
business_mechanics:
|
||||
- coordination
|
||||
- operation
|
||||
95
AGENTS.md
95
AGENTS.md
@@ -4,7 +4,7 @@
|
||||
|
||||
**Purpose:** railiance-fabric - (fill in purpose)
|
||||
|
||||
**Domain:** railiance
|
||||
**Domain:** financials
|
||||
**Repo slug:** railiance-fabric
|
||||
**Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38`
|
||||
**Workplan prefix:** `RAILIANCE-WP-`
|
||||
@@ -20,6 +20,12 @@ there is no MCP server for Codex agents.
|
||||
|---------|-----|
|
||||
| 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.
|
||||
|
||||
### Orient at session start
|
||||
|
||||
@@ -27,8 +33,8 @@ there is no MCP server for Codex agents.
|
||||
# Offline brief — works without hub connection
|
||||
cat .custodian-brief.md
|
||||
|
||||
# Active workstreams for this domain
|
||||
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \
|
||||
# Active workplans for this domain
|
||||
curl -s "http://127.0.0.1:8000/workplans/?topic_id=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
# Check inbox
|
||||
@@ -51,20 +57,20 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||
"summary": "what was done",
|
||||
"event_type": "note",
|
||||
"author": "codex",
|
||||
"workstream_id": "<uuid>",
|
||||
"workplan_id": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
Omit `workstream_id` / `task_id` when not applicable.
|
||||
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": "in_progress"}'
|
||||
# values: todo | in_progress | done | blocked
|
||||
-d '{"status": "progress"}'
|
||||
# values: wait | todo | progress | done | cancel
|
||||
```
|
||||
|
||||
### Flag a task for human review
|
||||
@@ -80,10 +86,10 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
## Session Protocol
|
||||
|
||||
**Start:**
|
||||
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
|
||||
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
|
||||
2. Check inbox: `GET /messages/?to_agent=railiance-fabric&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
|
||||
@@ -92,12 +98,69 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
**Close:**
|
||||
1. Update workplan file task statuses to reflect progress
|
||||
2. Log: `POST /progress/` with a summary of what changed
|
||||
3. Note for the custodian operator: after workplan file changes, run from
|
||||
`~/state-hub`:
|
||||
3. After workplan file changes, run:
|
||||
```bash
|
||||
make fix-consistency REPO=railiance-fabric
|
||||
statehub fix-consistency
|
||||
```
|
||||
This syncs task status from files into the hub DB.
|
||||
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 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=railiance-fabric` 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`
|
||||
|
||||
<!-- REPO-AGENTS-EXTENSIONS -->
|
||||
<!-- Append repo-specific agent instructions below this marker.
|
||||
The state-hub template sync preserves content after this line. -->
|
||||
|
||||
---
|
||||
|
||||
@@ -124,7 +187,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
|
||||
id: RAILIANCE-WP-NNNN
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: proposed | ready | active | blocked | backlog | finished | archived
|
||||
owner: codex
|
||||
@@ -146,7 +209,7 @@ derived health labels, not frontmatter statuses.
|
||||
|
||||
` ` `task
|
||||
id: RAILIANCE-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 +217,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,4 +8,5 @@
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
@.claude/rules/repo-boundary.md
|
||||
@.claude/rules/credential-routing.md
|
||||
@.claude/rules/agents.md
|
||||
|
||||
72
DECISIONS.md
72
DECISIONS.md
@@ -19,3 +19,75 @@ Superseded by WP-0004 T09 cancellation and CUST-WP-0038 ownership of State Hub H
|
||||
Superseded by completed WP-0004 outcome: activity-core was deployed as a K3s production service on railiance01 on 2026-05-22; the packaging architecture question is no longer blocking this workplan.
|
||||
|
||||
---
|
||||
|
||||
## Review CCR-2026-0001 whynot-design npm publish token lane
|
||||
|
||||
**Date:** 2026-06-27
|
||||
**Decided by:** human
|
||||
|
||||
APPROVE: scoped path and confirmed binding are acceptable
|
||||
|
||||
---
|
||||
|
||||
## Review CCR-2026-0001 corrected whynot-design npm publish token lane
|
||||
|
||||
**Date:** 2026-06-27
|
||||
**Decided by:** human
|
||||
|
||||
APPROVE: We fixed the path using coulomb as the org/tenant.
|
||||
|
||||
---
|
||||
|
||||
## Forgejo hostname and exposure model
|
||||
|
||||
**Date:** 2026-07-02
|
||||
**Decided by:** human
|
||||
|
||||
the hostname shall be forgejo.coulomb.social. The exposure model is private repos by default. We will use the transition from gitea to forgejo for closing down public access and establishing credential handling to have convenience when working with the repos. Gitea can and should remain reachable during transition.
|
||||
|
||||
---
|
||||
|
||||
## Forgejo SMTP and sender identity
|
||||
|
||||
**Date:** 2026-07-02
|
||||
**Decided by:** human
|
||||
|
||||
We will use forgejo@coulomb.social
|
||||
|
||||
---
|
||||
|
||||
## Forgejo package registry scope
|
||||
|
||||
**Date:** 2026-07-02
|
||||
**Decided by:** human
|
||||
|
||||
We should support the full range from the start.
|
||||
|
||||
---
|
||||
|
||||
## Forgejo Actions runner isolation model
|
||||
|
||||
**Date:** 2026-07-02
|
||||
**Decided by:** human
|
||||
|
||||
we will try to go with isolated host runners, with least-privilege credential boundaries.
|
||||
|
||||
---
|
||||
|
||||
## Forgejo backup target and restore cadence
|
||||
|
||||
**Date:** 2026-07-02
|
||||
**Decided by:** human
|
||||
|
||||
We will need to figure out the details, but i want to use backup.coulomb.social as the hostname with a backend we need to figure out yet.
|
||||
|
||||
---
|
||||
|
||||
## Forgejo cutover and rollback strategy
|
||||
|
||||
**Date:** 2026-07-02
|
||||
**Decided by:** human
|
||||
|
||||
We will do a staged migration and lock the gitea repos of transitioned repos but keep gitea until everything has been transfered and just then start a 14day trial phase and after that retire gitea to the backup.
|
||||
|
||||
---
|
||||
|
||||
@@ -151,5 +151,6 @@ loop.
|
||||
The graph explorer export is the first executable slice of the interactive
|
||||
Fabric map. See `docs/graph-explorer-transfer-review.md` for the repo-scoping
|
||||
transfer review, `docs/graph-explorer-contract.md` for the shared manifest and
|
||||
payload contract, and `docs/graph-explorer-operations.md` for launch, refresh,
|
||||
verification, and extraction guidance.
|
||||
payload contract, `docs/semantic-attractors.md` for the attractor-based layout
|
||||
orientation concept, and `docs/graph-explorer-operations.md` for launch,
|
||||
refresh, verification, and extraction guidance.
|
||||
|
||||
@@ -104,6 +104,32 @@ edges are intentionally shortest and most elastic; deployment-to-repo edges are
|
||||
longer and looser so infrastructure placement does not collapse into the repo
|
||||
node.
|
||||
|
||||
## Semantic Attractor Modes
|
||||
|
||||
Semantic attractors are view-only topic poles that can pull graph entities
|
||||
toward conceptual neighborhoods in spring-based layouts. For repository maps,
|
||||
an operator might choose attractors such as `security`, `development`, and
|
||||
`operations`; Fabric can then score each repository's semantic closeness to
|
||||
those attractors from repo-owned `SCOPE.md` evidence and map the score to
|
||||
layout strength.
|
||||
|
||||
Attractors are not domain edges and do not change Fabric graph data. They may
|
||||
be materialized as synthetic display-only nodes and `semantic_attraction`
|
||||
edges, or carried as top-level view metadata that the renderer turns into
|
||||
layout forces. Attraction scores should remain inspectable, with source
|
||||
references and confidence, so the operator can understand why a repository was
|
||||
pulled toward a topic.
|
||||
|
||||
Unlike zones, attractors may overlap. A repository can be close to both
|
||||
`development` and `operations`, and the layout should place it between those
|
||||
poles. Zone resolvers, boundary diagnostics, dependency queries, blast-radius
|
||||
queries, and collapsed-zone boundary edges should ignore semantic attraction
|
||||
edges unless a host explicitly promotes an attractor relation into canonical
|
||||
graph data.
|
||||
|
||||
See `docs/semantic-attractors.md` for the concept model, scoring semantics,
|
||||
payload direction, and implementation path.
|
||||
|
||||
## Display State Ownership
|
||||
|
||||
The contract allows either the host service or the engine to evaluate display
|
||||
|
||||
340
docs/semantic-attractors.md
Normal file
340
docs/semantic-attractors.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# Semantic Attractors
|
||||
|
||||
## Intent
|
||||
|
||||
Semantic attractors are view entities that help an operator orient inside a
|
||||
medium or large graph. An attractor represents a topic, concern, capability
|
||||
area, operating mode, or other conceptual pole such as `security`,
|
||||
`development`, `operations`, `identity`, `data`, or `delivery`.
|
||||
|
||||
The graph explorer can place attractors on the canvas and connect graph
|
||||
entities to them with view-only relationship strength. The stronger an
|
||||
entity's semantic closeness to an attractor, the more that attractor should
|
||||
pull the entity in force-directed or spring-based layouts.
|
||||
|
||||
The first motivating use case is repository orientation. Given a set of
|
||||
repositories, the operator defines attractors such as `security`,
|
||||
`development`, and `operations`. Railiance Fabric reads each repository's
|
||||
`SCOPE.md`, estimates semantic closeness to those attractors, and maps that
|
||||
score to layout force. The resulting map becomes a navigational surface: repos
|
||||
with similar purpose drift toward the same conceptual pole without replacing
|
||||
the underlying dependency or responsibility graph.
|
||||
|
||||
## What Attractors Are
|
||||
|
||||
An attractor is not a fabric node in the source graph. It is a graph-view
|
||||
artifact with these responsibilities:
|
||||
|
||||
- name a topic or concern that is useful for orientation;
|
||||
- define how closeness to that topic is measured;
|
||||
- expose a score for each eligible entity;
|
||||
- translate that score into layout hints and optional visual edges;
|
||||
- keep the scoring evidence inspectable so the map does not become mysterious.
|
||||
|
||||
Attractors should be saved as view/profile configuration, operator presets, or
|
||||
host-provided explorer configuration. They should not mutate repo-owned Fabric
|
||||
declarations, and they should not imply that a repository provides or consumes
|
||||
a capability.
|
||||
|
||||
## Why This Helps
|
||||
|
||||
Dependency edges answer "what depends on what?" Ownership and deployment
|
||||
metadata answer "who owns this?" and "where does this run?" Those questions are
|
||||
necessary, but they can still leave a large repo collection hard to scan.
|
||||
|
||||
Attractors answer a softer question: "what is this near, conceptually?"
|
||||
|
||||
This gives operators a fast way to discover clusters such as:
|
||||
|
||||
- repos that are security-heavy but not obvious from their names;
|
||||
- operations tooling that depends on development systems;
|
||||
- application repos that are unexpectedly close to platform/runtime concerns;
|
||||
- thin adapter repos that sit between two conceptual poles;
|
||||
- orphaned or ambiguous repos that have weak attraction to every known topic.
|
||||
|
||||
## Core Model
|
||||
|
||||
An attractor definition should be serializable and stable:
|
||||
|
||||
```yaml
|
||||
id: security
|
||||
label: Security
|
||||
description: Identity, authorization, secrets, MFA, audit, policy, and trust boundaries.
|
||||
applies_to:
|
||||
layers: [repository]
|
||||
evidence:
|
||||
sources:
|
||||
- type: scope_markdown
|
||||
path: SCOPE.md
|
||||
scoring:
|
||||
method: lexical_semantic_profile
|
||||
anchors:
|
||||
- security
|
||||
- identity
|
||||
- authorization
|
||||
- secrets
|
||||
- audit
|
||||
- policy
|
||||
- mfa
|
||||
negative_anchors:
|
||||
- unrelated
|
||||
normalization:
|
||||
mode: per_entity_softmax
|
||||
layout:
|
||||
min_score: 0.15
|
||||
max_score: 1.0
|
||||
strength_scale: 0.8
|
||||
ideal_length:
|
||||
min: 80
|
||||
max: 420
|
||||
presentation:
|
||||
color: "#be123c"
|
||||
edge_style: dashed
|
||||
```
|
||||
|
||||
The exact schema can evolve, but the responsibilities should remain separate:
|
||||
|
||||
- `applies_to` chooses which graph elements can be scored.
|
||||
- `evidence` declares which text or metadata is used.
|
||||
- `scoring` defines the semantic metric.
|
||||
- `normalization` turns raw scores into comparable view weights.
|
||||
- `layout` maps weights to graph layout hints.
|
||||
- `presentation` controls the optional visual attractor node and edges.
|
||||
|
||||
## Scoring From SCOPE.md
|
||||
|
||||
`SCOPE.md` is a useful first evidence source because it is intentionally short,
|
||||
repo-owned, and written to explain when a repository is relevant. For repository
|
||||
attraction, the scorer should use sections such as:
|
||||
|
||||
- `One-liner`
|
||||
- `Core Idea`
|
||||
- `In Scope`
|
||||
- `Relevant When`
|
||||
- `Provided Capabilities`
|
||||
- `Related / Overlapping Repositories`
|
||||
- `Terminology`
|
||||
|
||||
Sections such as `Out of Scope` and `Not Relevant When` should be used
|
||||
carefully. They can reduce false positives, but they should not erase a topic
|
||||
just because the repo mentions a boundary. For example, a repo can say it is
|
||||
not an authorization engine while still being semantically near security
|
||||
because it models secrets, policy, or trust boundaries.
|
||||
|
||||
The first implementation can use a transparent lexical profile:
|
||||
|
||||
1. Parse `SCOPE.md` into sections.
|
||||
2. Tokenize section text and provided capability keywords.
|
||||
3. Weight section matches, with `One-liner`, `Core Idea`, `In Scope`, and
|
||||
capability keywords carrying more weight than incidental notes.
|
||||
4. Score each attractor by matching configured anchors and related terms.
|
||||
5. Normalize scores per entity so one verbose `SCOPE.md` does not dominate.
|
||||
6. Store the score, confidence, and top evidence snippets in the view payload.
|
||||
|
||||
Later implementations can replace or augment lexical scoring with embeddings,
|
||||
LLM-assisted classification, or operator-reviewed labels. The contract should
|
||||
not depend on a particular scorer.
|
||||
|
||||
## Score Semantics
|
||||
|
||||
Attractor scores should be continuous values in `[0, 1]`.
|
||||
|
||||
Suggested interpretation:
|
||||
|
||||
| Score | Meaning |
|
||||
|-------|---------|
|
||||
| `0.00` | no useful evidence of semantic closeness |
|
||||
| `0.10` to `0.30` | weak signal; useful only as a faint layout hint |
|
||||
| `0.30` to `0.60` | moderate closeness; entity should visibly lean toward the attractor |
|
||||
| `0.60` to `0.85` | strong closeness; entity likely belongs near the attractor cluster |
|
||||
| `0.85` to `1.00` | primary semantic identity or explicit operator label |
|
||||
|
||||
Every score should carry a confidence separate from closeness. A repo with a
|
||||
thin or missing `SCOPE.md` may have low confidence even if a few terms match.
|
||||
|
||||
Attractors should also support multi-attraction. A repository can be close to
|
||||
both `development` and `operations`; the layout should then place it between
|
||||
those poles instead of forcing a single category. This is the main difference
|
||||
from zones: zones preserve a single-surface invariant, while attractors are
|
||||
allowed to overlap because they are layout forces, not containers.
|
||||
|
||||
## Layout Mapping
|
||||
|
||||
Attraction scores become layout hints. They should not become domain edges.
|
||||
|
||||
A graph explorer can map scores to synthetic view edges:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": "attractor:security->repo:flex-auth",
|
||||
"source": "attractor:security",
|
||||
"target": "repo:flex-auth",
|
||||
"edgeType": "semantic_attraction",
|
||||
"displayOnly": true,
|
||||
"score": 0.82,
|
||||
"confidence": 0.74,
|
||||
"strength": "strong",
|
||||
"layoutAffinity": 0.82,
|
||||
"layoutIdealLength": 110,
|
||||
"layoutElasticity": 0.9,
|
||||
"sourceReferences": [
|
||||
{
|
||||
"type": "scope_markdown",
|
||||
"path": "SCOPE.md",
|
||||
"section": "In Scope"
|
||||
}
|
||||
]
|
||||
},
|
||||
"classes": "semantic-attraction"
|
||||
}
|
||||
```
|
||||
|
||||
For force-directed layouts:
|
||||
|
||||
- stronger scores should increase spring strength or edge weight;
|
||||
- stronger scores should shorten ideal length;
|
||||
- weak scores may be hidden visually while still applying a small force;
|
||||
- edges below a configured threshold should not affect layout;
|
||||
- display-only attraction edges should be excluded from dependency, boundary,
|
||||
blast-radius, and zone-connectivity diagnostics.
|
||||
|
||||
Attractor nodes can be pinned, arranged on a ring, placed by the operator, or
|
||||
computed from the current profile. For first use, a stable radial placement is
|
||||
usually enough: place three to eight attractors around the graph, then let
|
||||
repositories find their balance.
|
||||
|
||||
## View Payload Shape
|
||||
|
||||
The graph explorer payload should be able to carry attractor metadata without
|
||||
changing the canonical Fabric graph.
|
||||
|
||||
Recommended top-level view extension:
|
||||
|
||||
```json
|
||||
{
|
||||
"view": {
|
||||
"attractors": {
|
||||
"enabled": true,
|
||||
"definitionSet": "repo-concerns-v1",
|
||||
"definitions": [
|
||||
{
|
||||
"id": "security",
|
||||
"label": "Security",
|
||||
"description": "Identity, authorization, secrets, audit, and policy.",
|
||||
"color": "#be123c"
|
||||
}
|
||||
],
|
||||
"scores": [
|
||||
{
|
||||
"attractor_id": "security",
|
||||
"element_id": "repo:flex-auth",
|
||||
"score": 0.82,
|
||||
"confidence": 0.74,
|
||||
"method": "lexical_semantic_profile",
|
||||
"evidence": [
|
||||
{
|
||||
"source": "SCOPE.md",
|
||||
"section": "Core Idea",
|
||||
"terms": ["authorization", "policy"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The renderer may choose to materialize these into synthetic nodes and edges at
|
||||
runtime. A host may also emit synthetic display-only elements directly if that
|
||||
is easier for the current engine.
|
||||
|
||||
## Operator Workflow
|
||||
|
||||
A useful attractor workflow should feel like mapmaking:
|
||||
|
||||
1. Choose a preset such as `Security / Development / Operations`.
|
||||
2. Review the generated scores and evidence for a few known repos.
|
||||
3. Hide or pin attractors that are not useful for the current question.
|
||||
4. Save the attractor definition set in the graph profile.
|
||||
5. Use the resulting layout to discover ambiguous, central, or misplaced repos.
|
||||
|
||||
The UI should expose:
|
||||
|
||||
- a toggle for semantic attractors;
|
||||
- a definition-set selector;
|
||||
- score threshold controls;
|
||||
- optional visual attraction edges;
|
||||
- pinned/unpinned attractor placement;
|
||||
- detail panels explaining why a repo is close to an attractor;
|
||||
- diagnostics for missing evidence, low confidence, and overly broad
|
||||
attractors.
|
||||
|
||||
## Relationship To Zones
|
||||
|
||||
Zones and attractors solve different orientation problems.
|
||||
|
||||
Zones are bounded drawing surfaces. A visible node belongs to zero or one zone
|
||||
in a given view. They are useful for deployment environments, access zones,
|
||||
ownership surfaces, and other container-like questions.
|
||||
|
||||
Attractors are semantic force points. A visible node can be pulled by multiple
|
||||
attractors at once. They are useful for topical orientation, concern mapping,
|
||||
and discovering conceptual neighborhoods.
|
||||
|
||||
The two concepts can combine cleanly:
|
||||
|
||||
- zones can show where entities run;
|
||||
- attractors can pull repos inside or outside those zones based on semantic
|
||||
concern;
|
||||
- zone diagnostics should ignore semantic attraction edges unless explicitly
|
||||
configured otherwise;
|
||||
- attractor scores can be summarized inside zone details.
|
||||
|
||||
## Initial Presets
|
||||
|
||||
A first repository-orientation preset should keep the set small:
|
||||
|
||||
| Attractor | Topic Signal |
|
||||
|-----------|--------------|
|
||||
| `security` | identity, secrets, authorization, policy, audit, MFA, trust boundaries |
|
||||
| `development` | source code, build, CI/CD, package publishing, scaffolding, developer workflows |
|
||||
| `operations` | deployment, runtime, monitoring, backups, incidents, infrastructure lifecycle |
|
||||
|
||||
Useful follow-up presets:
|
||||
|
||||
- `data`, `identity`, `delivery`, `governance`
|
||||
- `platform`, `application`, `tooling`
|
||||
- `financial`, `runtime`, `coordination`
|
||||
|
||||
Attractors should start as operator-chosen presets rather than global truth.
|
||||
The same repository can be viewed through different conceptual lenses.
|
||||
|
||||
## Implementation Path
|
||||
|
||||
The concept can be implemented incrementally:
|
||||
|
||||
1. Add an attractor definition format for graph explorer profiles.
|
||||
2. Parse repo `SCOPE.md` files during registry sync or graph export.
|
||||
3. Compute transparent lexical scores for repositories.
|
||||
4. Include attractor scores and evidence in the graph explorer payload.
|
||||
5. Add synthetic attractor nodes and display-only attraction edges in the UI.
|
||||
6. Map attraction scores to layout hints for the force-directed layout.
|
||||
7. Add detail-panel evidence and low-confidence diagnostics.
|
||||
8. Support saved attractor presets and operator score overrides.
|
||||
|
||||
This keeps attractors as a view concern until the scoring model proves useful.
|
||||
If a semantic relation becomes durable domain knowledge, it can later be
|
||||
promoted into a proper Fabric declaration with separate evidence and review.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should attractor definitions live in graph profiles, repo config, or a shared
|
||||
registry preset file?
|
||||
- Should scoring run during registry sync, export, or entirely in the browser?
|
||||
- How much operator override should be allowed before scores become maintained
|
||||
labels rather than computed evidence?
|
||||
- What is the right default for missing or stale `SCOPE.md` evidence?
|
||||
- Should the first implementation use only lexical scoring, or should it also
|
||||
prepare a pluggable embedding scorer interface?
|
||||
0
registry/capabilities/.gitkeep
Normal file
0
registry/capabilities/.gitkeep
Normal file
122
registry/capabilities/capability.railiance.fabric-graph.md
Normal file
122
registry/capabilities/capability.railiance.fabric-graph.md
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
id: capability.railiance.fabric-graph
|
||||
name: Railiance Fabric Ecosystem Graph
|
||||
summary: 'Models the durable infrastructure-responsibility graph of the Railiance netkingdom: schemas,
|
||||
discovery tools, registry services, graph queries, and State Hub export contracts for services, machines,
|
||||
repos, deployables, endpoints, ownership, dependencies, and bindings.'
|
||||
owner: railiance-fabric
|
||||
status: draft
|
||||
domain: financials
|
||||
tags:
|
||||
- railiance
|
||||
- graph
|
||||
- ownership
|
||||
- discovery
|
||||
maturity:
|
||||
discovery:
|
||||
current: D3
|
||||
target: D5
|
||||
confidence: medium
|
||||
rationale: README and SCOPE.md document the ecosystem graph model bounded by financial/operational
|
||||
accountability (who pays, who is accountable), with king/lord/tenant ownership concepts referenced
|
||||
in docs/FabricDiscoveryAndUpdate.md.
|
||||
availability:
|
||||
current: A1
|
||||
target: A3
|
||||
confidence: medium
|
||||
rationale: Python package (`railiance-fabric`) providing a declaration loader and validator; consumed
|
||||
as a library, no hosted service documented yet.
|
||||
external_evidence:
|
||||
completeness:
|
||||
level: C1
|
||||
confidence: low
|
||||
basis: scope_vs_intent_and_consumer_expectations
|
||||
satisfied_expectations:
|
||||
- ecosystem graph declaration loader and validator
|
||||
- schemas for services/machines/repos/deployables/endpoints/ownership/dependencies/bindings
|
||||
broken_expectations: []
|
||||
out_of_scope_expectations: []
|
||||
reliability:
|
||||
level: R0
|
||||
confidence: low
|
||||
basis: consumer_quality_signals
|
||||
known_reliability_risks:
|
||||
- discovery/rebuild/update-loop architecture documented as still evolving per docs/FabricDiscoveryAndUpdate.md
|
||||
discovery:
|
||||
intent: Let repos declare services, capabilities, interfaces, dependencies, and bindings in source-controlled
|
||||
files, and model the resulting durable infrastructure-responsibility graph across the Railiance ecosystem.
|
||||
includes:
|
||||
- ecosystem graph schema and declaration loader/validator
|
||||
- State Hub export contracts for the graph
|
||||
excludes:
|
||||
- actual infrastructure provisioning (see railiance-infra, railiance-cluster)
|
||||
assumptions: []
|
||||
use_cases: []
|
||||
research_memos: []
|
||||
availability:
|
||||
current_level: A1
|
||||
target_level: A3
|
||||
current_artifacts:
|
||||
- Python package (`railiance-fabric`)
|
||||
target_artifacts: []
|
||||
consumption_modes:
|
||||
- library import
|
||||
- cli (validation)
|
||||
relations:
|
||||
depends_on: []
|
||||
supports: []
|
||||
related_to: []
|
||||
evidence:
|
||||
documentation:
|
||||
- README.md
|
||||
- SCOPE.md
|
||||
- docs/FabricDiscoveryAndUpdate.md
|
||||
tests:
|
||||
- tests/
|
||||
consumer_feedback: []
|
||||
bug_reports: []
|
||||
incidents: []
|
||||
consumer_guidance:
|
||||
recommended_for:
|
||||
- Railiance repos wanting to declare their place in the ecosystem ownership/dependency graph
|
||||
not_recommended_for:
|
||||
- needs for actual infrastructure provisioning (see railiance-infra/-cluster)
|
||||
known_limitations:
|
||||
- discovery/rebuild/update-loop architecture still evolving
|
||||
promotion_history: []
|
||||
---
|
||||
|
||||
# Railiance Fabric Ecosystem Graph
|
||||
|
||||
## Overview
|
||||
|
||||
`railiance-fabric` models the durable infrastructure-responsibility graph of the Railiance netkingdom — who pays for infrastructure, who is accountable for it, and which durable interfaces create value across boundaries — via schemas, a declaration loader/validator, and State Hub export contracts.
|
||||
|
||||
## Assessment notes
|
||||
|
||||
### Discovery
|
||||
|
||||
README and SCOPE.md document the ecosystem graph model bounded by financial/operational accountability (who pays, who is accountable), with king/lord/tenant ownership concepts referenced in docs/FabricDiscoveryAndUpdate.md.
|
||||
|
||||
### Availability
|
||||
|
||||
Python package (`railiance-fabric`) providing a declaration loader and validator; consumed as a library, no hosted service documented yet.
|
||||
|
||||
### Completeness
|
||||
|
||||
First-pass honest assessment from the REUSE-WP-0017 coverage campaign
|
||||
(reuse-surface). No external consumer feedback exists yet; levels reflect
|
||||
scope-vs-intent documentation quality, not internal code quality.
|
||||
|
||||
### Reliability
|
||||
|
||||
No production consumer telemetry exists yet; reliability level is
|
||||
intentionally conservative pending REUSE-WP-0019 reuse-telemetry evidence.
|
||||
|
||||
## Promotion checklist
|
||||
|
||||
- [x] ID follows `capability.<domain>.<name>` pattern
|
||||
- [x] Maturity enums match `specs/CapabilityMaturityStandard.md`
|
||||
- [x] `external_evidence` is populated separately from `maturity`
|
||||
- [ ] Relations reference valid capability IDs (none yet)
|
||||
- [x] Index entry added in `registry/indexes/capabilities.yaml`
|
||||
22
registry/indexes/capabilities.yaml
Normal file
22
registry/indexes/capabilities.yaml
Normal file
@@ -0,0 +1,22 @@
|
||||
version: 1
|
||||
updated: '2026-07-06'
|
||||
domain: helix_forge
|
||||
capabilities:
|
||||
- id: capability.railiance.fabric-graph
|
||||
name: Railiance Fabric Ecosystem Graph
|
||||
summary: 'Models the durable infrastructure-responsibility graph of the Railiance netkingdom: schemas,
|
||||
discovery tools, registry services, graph queries, and State Hub export contracts for services, machines,
|
||||
repos, deployables, endpoints, ownership, dependencies, and bindings.'
|
||||
vector: D3 / A1 / C1 / R0
|
||||
domain: financials
|
||||
status: draft
|
||||
owner: railiance-fabric
|
||||
path: registry/capabilities/capability.railiance.fabric-graph.md
|
||||
tags:
|
||||
- railiance
|
||||
- graph
|
||||
- ownership
|
||||
- discovery
|
||||
consumption_modes:
|
||||
- library import
|
||||
- cli (validation)
|
||||
34
workplans/archived/260702-ADHOC-2026-06-06.md
Normal file
34
workplans/archived/260702-ADHOC-2026-06-06.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
id: ADHOC-2026-06-06
|
||||
type: workplan
|
||||
title: "Ad Hoc Fixes 2026-06-06"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-06-06"
|
||||
updated: "2026-06-06"
|
||||
state_hub_workstream_id: "02426929-e247-4fbf-8072-ea05cac41e93"
|
||||
---
|
||||
|
||||
# ADHOC-2026-06-06 - Ad Hoc Fixes
|
||||
|
||||
## Document Semantic Attractors
|
||||
|
||||
```task
|
||||
id: ADHOC-2026-06-06-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "982d1571-128c-40de-bedf-5d70b2ffd586"
|
||||
```
|
||||
|
||||
Refine the concept of semantic attractors for the graph explorer: topic-like
|
||||
view entities such as `security`, `development`, and `operations` that pull
|
||||
repositories or other entities based on semantic closeness, initially scored
|
||||
from repo `SCOPE.md` files and mapped into spring-layout strength.
|
||||
|
||||
Result: Added `docs/semantic-attractors.md` with the concept model, SCOPE.md
|
||||
scoring approach, score semantics, layout mapping, payload shape, operator
|
||||
workflow, relationship to zones, initial presets, implementation path, and open
|
||||
questions. Linked the concept from the README and graph explorer contract.
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0001
|
||||
type: workplan
|
||||
title: "Railiance Ecosystem Graph Model"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0002
|
||||
type: workplan
|
||||
title: "Railiance Ecosystem Registry Service"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0003
|
||||
type: workplan
|
||||
title: "Registry Feed And Library Inventory"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0004
|
||||
type: workplan
|
||||
title: "Registry Inventory And Drift Views"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0005
|
||||
type: workplan
|
||||
title: "Registry Hardening"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: medium
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0006
|
||||
type: workplan
|
||||
title: "Multi-Repo Registry Onboarding"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
@@ -2,9 +2,9 @@
|
||||
id: RAIL-FAB-WP-0007
|
||||
type: workplan
|
||||
title: "All Local Repo Onboarding"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: medium
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0008
|
||||
type: workplan
|
||||
title: "Interactive Fabric Map"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0009
|
||||
type: workplan
|
||||
title: "Graph Explorer UI Refinement"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0010
|
||||
type: workplan
|
||||
title: "Repo Reality Scanner"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0011
|
||||
type: workplan
|
||||
title: "Operational Rescan Loops"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0012
|
||||
type: workplan
|
||||
title: "Baseline Rollout And Conflict Review"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0013
|
||||
type: workplan
|
||||
title: "Path Scoped Duplicate Identity"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0014
|
||||
type: workplan
|
||||
title: "Runtime Topology Discovery"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0015
|
||||
type: workplan
|
||||
title: "Runtime Entity Taxonomy Refinement"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0016
|
||||
type: workplan
|
||||
title: "Canon-Aligned Graph Model Reset And Reingest"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0017
|
||||
type: workplan
|
||||
title: "Financial Fabric Model Reset"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0018
|
||||
type: workplan
|
||||
title: "Accountability Root Discovery And Update Loop"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0019
|
||||
type: workplan
|
||||
title: "Duplicate Repository Identity Review"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0020
|
||||
type: workplan
|
||||
title: "Deployment Zone Discovery And Visualization"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,7 +2,7 @@
|
||||
id: RAIL-FAB-WP-0021
|
||||
type: workplan
|
||||
title: "Zone Boundary Overlays"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
@@ -2,11 +2,11 @@
|
||||
id: RAIL-FAB-WP-0022
|
||||
type: workplan
|
||||
title: "Promote graph zones to first-class visualization entities"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance-fabric
|
||||
topic_slug: railiance
|
||||
created: "2026-05-24"
|
||||
updated: "2026-05-24"
|
||||
state_hub_workstream_id: "343f8383-ba5e-4d60-b55e-81611954d9b9"
|
||||
@@ -2,11 +2,11 @@
|
||||
id: RAIL-FAB-WP-0023
|
||||
type: workplan
|
||||
title: "Improve zone labels and dragging"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance-fabric
|
||||
topic_slug: railiance
|
||||
created: "2026-05-25"
|
||||
updated: "2026-06-05"
|
||||
state_hub_workstream_id: "f02e14c5-e60f-4950-b1a2-682c38b30431"
|
||||
@@ -2,11 +2,11 @@
|
||||
id: RAIL-FAB-WP-0024
|
||||
type: workplan
|
||||
title: "Stabilize zone containers and layout zone subgraphs"
|
||||
domain: railiance
|
||||
domain: financials
|
||||
repo: railiance-fabric
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: railiance-fabric
|
||||
topic_slug: railiance
|
||||
created: "2026-05-25"
|
||||
updated: "2026-05-25"
|
||||
state_hub_workstream_id: "63202459-2f73-409a-8881-307a5fc1835a"
|
||||
Reference in New Issue
Block a user