railiance-cluster/CLAUDE.md

railiance-cluster — Claude Code Instructions

Custodian State Hub Integration

This project is tracked as the railiance domain in the Custodian State Hub. Hub topic ID: ca369340-a64e-442e-98f1-a4fa7dc74a38

The State Hub runs locally at http://127.0.0.1:8000. The MCP server (state-hub) exposes tools for reading and writing state without touching the API directly.

---

Session Protocol

On receiving your first message — before writing any response text — execute this orientation sequence. Do not greet, do not ask what to do first.

Step 1 — Call the State Hub

get_state_summary()   # orientation: workstreams, decisions, recent progress
get_next_steps()      # contextual suggestions from resolved decisions

If the call fails, the API is offline: cd ~/the-custodian/state-hub && make api

Step 2 — Scan local workplans

Read every .md file under workplans/. Use Glob(pattern="**/*.md", path="workplans/") or Bash ls workplans/ to discover them. For each file with status: active, extract and note:

• The workplan title and ID
• All tasks whose status is todo or in_progress

Step 3 — Present orientation to the user

Output a concise brief covering:

1. Active workstreams for the railiance domain — title, task counts, any blocking decisions
2. Pending tasks for this repo — from local workplans/ files (Step 2) plus any state hub tasks with [repo:railiance-cluster] in their title
3. Goal guidance — if the summary contains a goal_guidance key, act on it:
   • needs_workplan entries: for each active repo goal with no linked workstream, surface it as the top suggested action — "Repo goal '{title}' has no workplan yet. Suggest: create workplans/RAIL-BS-WP-NNNN-.md and register a workstream with repo_goal_id='{goal_id}'". Treat this as higher priority than continuing existing work unless Bernd says otherwise.
   • alignment_warnings entries: if active workstreams exist but are not linked to the current repo goal, name the most recently active one and note: "Current work on '{recent_workstream_title}' may not be aligned with the active goal '{active_goal_title}'. Continue unless you hear otherwise — but flag it."
4. Suggested next action — the highest-priority open item across all sources, with goal alignment taken into account
5. SBOM status — last_sbom_at for railiance-cluster is currently null (gap: no lockfile yet — see workplans/RAIL-BS-WP-0001-dependency-management.md)

During work:

• Use record_decision() for any decision that affects direction or dependencies.
• Use add_progress_event() for notable events (milestones, blockers, insights).
• Use resolve_decision() to close a decision once the choice is made.

Design boundary: The State Hub is a read model. Two write operations are permanently sanctioned: Resolving Decisions and Suggesting Next Steps. Bootstrap tools are only for First Session Protocol. Work structure belongs in the domain repo as files (ADR-001).

At the end of every session:

• Call add_progress_event() with a summary of what was accomplished. Include topic_id: ca369340-a64e-442e-98f1-a4fa7dc74a38 and workstream_id.

---

Known Pending Tasks (as of 2026-03-01)

RAIL-BS-WP-0001 — Dependency Management (workplans/RAIL-BS-WP-0001-dependency-management.md)

The SBOM scanner finds nothing to ingest because Ansible and control-node pip dependencies are not declared in any lockfile. This is the top-priority open task for this repo.

Task	Priority	Status
T01: Audit control-node pip deps	medium	todo
T02: Create pyproject.toml + uv.lock	medium	todo
T03: Ingest SBOM into State Hub	medium	todo
T04: Create ansible/requirements.yml	low	todo

State Hub task ID: 5f8cade5-119c-42e8-ba93-e9d0478650e4

---

First Session Protocol

Triggered when get_state_summary() shows no workstreams for railiance.

Step 1 — Read ~/the-custodian/canon/projects/railiance/project_charter_v0.1.md and roadmap_v0.1.md, then scan this repo root.

Step 2 — Survey in-progress work (TODOs, open branches, half-finished files).

Step 3 — Propose 1–3 workstreams. Wait for approval before creating anything.

Step 4 — Create workplan file first (workplans/RAIL-WP-NNNN-<slug>.md), then register in hub:

create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", ...)
create_task(workstream_id="<id>", ...)

Step 5 — Record setup with add_progress_event().

---

Workplan Convention (ADR-001)

Work items originate as files in workplans/ before being registered in the hub. When the custodian creates a task for this repo, it places a workplan file here AND creates a state hub task with [repo:railiance-cluster] in the title. Both appear at session start via the orientation above.

---

Contribution Tracking

contrib/
  bug-reports/       # br-YYYY-MM-DD--org--repo--slug.md
  feature-requests/  # fr-YYYY-MM-DD--org--repo--slug.md
  extension-points/  # EP-RAIL-NNN--org--repo--slug.md
  upstream-prs/      # upr-YYYY-MM-DD--org--repo--slug.md

Templates: ~/the-custodian/canon/standards/contrib-templates/

---

SBOM

After creating and committing the lockfile (see RAIL-BS-WP-0001), ingest:

cd ~/the-custodian/state-hub
make ingest-sbom REPO=railiance-cluster SCAN=1 REPO_PATH=/home/worsch/railiance-cluster

---

Remote Execution & State Hub Tunnel

This repo is designed to be worked on from the HostEurope server. The State Hub runs on Bernd's local workstation at 127.0.0.1:8000 and is not publicly reachable — a reverse SSH tunnel must be open before starting a remote session.

On your local machine, before SSHing to the server:

cd ~/the-custodian/state-hub
make tunnel HOST=tegwick@92.205.130.254

Keep that terminal open. Then SSH in normally from a second terminal.

Verify the tunnel is live from the remote:

curl http://127.0.0.1:8000/state/health
# expected: {"status":"ok"}

If the tunnel is not up (degraded mode):

• The get_domain_summary call in Step 1 will fail
• Skip Step 1 — proceed from local workplans only (Step 2)
• Log any progress events manually from the local machine after the session

---

Quick Reference

~/the-custodian/state-hub/mcp_server/TOOLS.md — compact MCP tool reference