chore: register with Custodian State Hub

Add CLAUDE.md (session protocol, tool boundary, workplan prefix BRIDGE-WP)
and workplans/ directory. Repo registered as ops-bridge under custodian
domain (id: 1bf99f56).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-11 21:34:37 +01:00
parent dc1422fcaa
commit 482edcd7eb

81
CLAUDE.md Normal file
View File

@@ -0,0 +1,81 @@
# ops-bridge — Claude Code Instructions
**Purpose:** SSH reverse tunnel lifecycle manager. Keeps remote execution
environments (COULOMBCORE, Railiance nodes) connected to the local Custodian
State Hub so Claude Code sessions on those machines have full MCP connectivity.
**Domain:** custodian
**Repo slug:** ops-bridge
**Repo ID:** 1bf99f56-6e94-4379-a9ea-295a4c181889
## Custodian State Hub Integration
State Hub: http://127.0.0.1:8000
### Session Protocol
**Step 1 — Orient**
```
get_domain_summary("custodian")
```
**Step 2 — Scan workplans**
```
ls workplans/
```
**During work:** use `record_decision()`, `add_progress_event()`, `resolve_decision()`.
**Session close:** `add_progress_event()` with workstream_id.
If workplan files were modified, run from `~/the-custodian/state-hub/`:
```bash
make fix-consistency REPO=ops-bridge
```
### Workplan Convention (ADR-001)
File location: `workplans/BRIDGE-WP-NNNN-<slug>.md`
Prefix: `BRIDGE-WP`
## What this repo builds
A CLI tool (`bridge`) that manages named SSH reverse tunnels:
```
bridge up [TUNNEL] # start tunnel(s)
bridge down [TUNNEL] # stop tunnel(s)
bridge restart [TUNNEL] # restart tunnel(s)
bridge status # show all tunnels: state, uptime, last health check
bridge logs [TUNNEL] # tail reconnect log
```
Config file: `~/.config/bridge/tunnels.yaml`
Each tunnel:
- Named (e.g. `state-hub-coulombcore`)
- Reverse SSH port-forward: `ssh -R remote_port:127.0.0.1:local_port host`
- Auto-reconnects on drop (backoff loop)
- Optional HTTP health check to confirm the forwarded service is reachable
PRD: `workplans/BRIDGE-WP-0001-initial-implementation.md`
## Stack
- **Language:** Python 3.11+
- **CLI framework:** Typer
- **Dependencies:** typer, pyyaml, httpx
- **Packaging:** `uv tool install` (single command install, no venv activation)
- **No system daemons** — process management is internal, PID tracked in
`~/.local/state/bridge/`
## Repo boundary
This repo owns **tunnel lifecycle management only**. It does not own:
- State hub code → `the-custodian/state-hub/`
- SSH key management → `railiance-infra/` (S1) or user dotfiles
- Ansible/provisioning → `railiance-infra/`
## Quick Reference
`~/the-custodian/state-hub/mcp_server/TOOLS.md`