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

Complete DISCTL-WP-0001: bootstrap State Hub integration

Browse source 
Replace repo-seed template identity with disaster-control across
AGENTS.md, SCOPE.md, and .claude/rules. Archive REPO-WP template
workplans. Document dev workflow and classification. Mark WP-0001 finished.
This commit is contained in:
tegwick 2026-07-07 21:26:42 +02:00
parent a94dfec7bd
commit a290584ed1
10 changed files with 113 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

14
.claude/rules/repo-boundary.md
View file

@ -1,8 +1,12 @@
## Repo boundary
This repo owns **Repo Seed** only. It does not own:
This repo owns **disaster-control** (Resilience Control Plane) only.
<!-- TODO: List what belongs in adjacent repos, e.g.:
- SSH key management → railiance-infra/
- State hub code → state-hub/
-->
| Concern | Owner repo |
| --- | --- |
| Backup scripts (`railiance-backup`, `forgejo-backup`, `-s1`, `-s2`) | `railiance-platform`, `railiance-cluster`, `railiance-infra` |
| Forgejo restore orchestration | `railiance-infra` |
| State Hub code | `state-hub` |
| SSH certificates | `ops-warden` |
| Application runtime | `railiance-apps`, product repos |
| Repo template / `statehub register` | `repo-seed` |

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

@ -1,5 +1,6 @@
**Purpose:** Git repository template to bootstrap coulomb projects.
**Purpose:** Resilience Control Plane for Coulomb Social / Helix Forge.
**Domain:** infotech
**Repo slug:** repo-seed
**Repo slug:** disaster-control
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
**Workplan prefix:** DISCTL-WP-

10
.claude/rules/session-protocol.md
View file

@ -22,14 +22,14 @@ If the hub is offline: `cd ~/state-hub && make api`
**Step 2 — Check inbox**
With MCP tools:
```
get_messages(to_agent="repo-seed", unread_only=True)
get_messages(to_agent="disaster-control", 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=repo-seed&unread_only=true" \
curl -s "http://127.0.0.1:8000/messages/?to_agent=disaster-control&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 '{}'
@ -45,7 +45,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
**Step 4 — Present brief**
1. **Active workstreams** for `infotech` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:repo-seed]` hub tasks
2. **Pending tasks** from `workplans/` + any `[repo:disaster-control]` 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
@ -73,12 +73,12 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
If workplan files were modified, ensure the local copy is up to date first:
```bash
git -C <repo_path> pull --ff-only
cd ~/state-hub && make fix-consistency REPO=repo-seed
cd ~/state-hub && make fix-consistency REPO=disaster-control
```
For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the combined target which pulls before fixing:
```bash
cd ~/state-hub && make fix-consistency-remote REPO=repo-seed
cd ~/state-hub && make fix-consistency-remote REPO=disaster-control
```
**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

40
.claude/rules/stack-and-commands.md
View file

@ -1,27 +1,39 @@
## Stack
- **Language:** Markdown-first registry and planning repo (no application runtime yet)
- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml`
- **Language:** Markdown-first governance repo (YAML registers, policies, runbooks)
- **Key deps:** State Hub ADR-001 workplans, YAML registers, cross-repo backup tooling
## Dev Commands
```bash
# Orient (offline-safe)
cat .custodian-brief.md
cat README.md
cat SCOPE.md
cat INTENT.md
cat PanicSheet.md
ls workplans/
# Consumer bootstrap docs
cat docs/statehub-register.md
cat docs/template-validation-checklist.md
# Validate register YAML
python3 -c "import yaml; yaml.safe_load(open('AssetRegister.yaml')); yaml.safe_load(open('DataRegister.yaml'))"
# After workplan or registry edits — from ~/state-hub
make fix-consistency REPO=repo-seed
# Validate registry entries (from reuse-surface checkout)
reuse-surface validate --root .
# Sanity-check markdown / registry edits
# Sanity-check markdown / YAML edits
git diff --check
# Push to primary + off-Gitea mirror
git push origin main
./tools/sync-mirror.sh
# After workplan edits — from ~/state-hub
make fix-consistency REPO=disaster-control
# State Hub API (if hub offline: cd ~/state-hub && make api)
curl -s "http://127.0.0.1:8000/messages/?to_agent=disaster-control&unread_only=true" | python3 -m json.tool
```
## Key paths
| Path | Purpose |
| --- | --- |
| `AssetRegister.yaml` / `DataRegister.yaml` | Stack inventory |
| `BackupPickupQueue.md` | Cross-repo backup closure tracker |
| `TestEvidence/` | Restore drill reports |
| `docs/mirror-sync.md` | Off-Gitea mirror procedure |

17
.repo-classification.yaml
View file

@ -1,18 +1,21 @@
repo_classification:
standard: Repo Classification Standard
version: '1.0'
classified_at: '2026-06-22'
classified_by: agent
category: tooling
classified_at: '2026-07-07'
classified_by: grok
category: documentation
domain: infotech
secondary_domains: []
capability_tags:
- platform
- configuration
- resilience
- disaster-recovery
- business-continuity
- documentation
- governance
business_stake:
- technology
- execution
- operations
business_mechanics:
- operation
notes: Git template for bootstrapping coulomb projects.
- compliance
notes: Resilience Control Plane for Coulomb Social / Helix Forge.

48
AGENTS.md
View file

@ -1,13 +1,13 @@
# Repo Seed — Agent Instructions
# disaster-control — Agent Instructions
## Repo Identity
**Purpose:** Git repository template to bootstrap coulomb projects.
**Purpose:** Resilience Control Plane for Coulomb Social / Helix Forge.
**Domain:** infotech
**Repo slug:** repo-seed
**Repo slug:** disaster-control
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `REPO-WP-`
**Workplan prefix:** `DISCTL-WP-`
---
@ -32,7 +32,7 @@ curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \
curl -s "http://127.0.0.1:8000/messages/?to_agent=disaster-control&unread_only=true" \
| python3 -m json.tool
```
@ -81,7 +81,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
2. Check inbox: `GET /messages/?to_agent=repo-seed&unread_only=true`; mark read
2. Check inbox: `GET /messages/?to_agent=disaster-control&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`
@ -95,7 +95,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`:
```bash
make fix-consistency REPO=repo-seed
make fix-consistency REPO=disaster-control
```
This syncs task status from files into the hub DB.
@ -122,7 +122,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
| Agent runtime | How to orient |
| --- | --- |
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=repo-seed` is for coordination, not secret vending |
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=disaster-control` is for coordination, not secret vending |
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **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` |
@ -156,6 +156,26 @@ get wrong.
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
## disaster-control workflow
Markdown-first repo — no application build. Verify changes with:
```bash
# YAML registers parse
python3 -c "import yaml; yaml.safe_load(open('AssetRegister.yaml')); yaml.safe_load(open('DataRegister.yaml'))"
# Whitespace / conflict markers
git diff --check
# Mirror after push to Gitea
./tools/sync-mirror.sh
```
**Primary remote:** `gitea-remote:coulomb/disaster-control.git`
**Mirror remote:** `forgejo-remote:coulomb/disaster-control.git` — see `docs/mirror-sync.md`
**Active workplans:** `DISCTL-WP-*` only. Template `REPO-WP-*` files archived under `workplans/archived/`.
---
## Workplan Convention (ADR-001)
@ -163,10 +183,10 @@ get wrong.
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/REPO-WP-NNNN-<slug>.md`
**File location:** `workplans/DISCTL-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-REPO-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
`workplans/archived/YYMMDD-DISCTL-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
@ -178,11 +198,11 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
```yaml
---
id: REPO-WP-NNNN
id: DISCTL-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: repo-seed
repo: disaster-control
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
@ -202,7 +222,7 @@ derived health labels, not frontmatter statuses.
## Task Title
` ` `task
id: REPO-WP-NNNN-T01
id: DISCTL-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
@ -215,5 +235,5 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo
To create a new workplan:
1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=repo-seed`
2. Notify the custodian operator to run `make fix-consistency REPO=disaster-control`
(or send a message to the hub agent via `POST /messages/`)

21
SCOPE.md
View file

@ -6,26 +6,33 @@
## One-liner
Git repository template to bootstrap coulomb projects.
Resilience Control Plane for Coulomb Social / Helix Forge — recovery governance, evidence, and registers.
---
## Core Idea
repo-seed is the canonical template for new repos: agent instructions, registry scaffold, and onboarding conventions.
`disaster-control` is the single source of truth for business continuity, disaster
recovery, cyber recovery, and restore-test evidence. It documents what exists,
what must survive, how it is rebuilt, and whether restore actually works.
---
## In Scope
- Template files for new repo bootstrap
- Documentation for statehub_register usage
- Registry capability entry for template capability
- Asset and data registers (`AssetRegister.yaml`, `DataRegister.yaml`)
- Resilience and backup policy (`ResiliencePolicy.md`, `BackupPolicy.md`, `RTO-RPO-Matrix.md`)
- Restore runbooks and incident playbooks
- Test evidence from restore drills (`TestEvidence/`)
- Cross-repo backup pickup tracking (`BackupPickupQueue.md`)
- Panic sheet and operator recovery documentation
- State Hub workplans (ADR-001) for resilience work
---
## Out of Scope
- Application runtime code
- Owning downstream project implementations
- Backup script implementation (lives in `railiance-cluster`, `railiance-platform`, `railiance-infra`)
- Owning infrastructure remediation — this repo tracks and evidences; owner repos implement
- `registry/` capability publish (inherited template scaffold; canonical template is `repo-seed`)

17
workplans/DISCTL-WP-0001-statehub-bootstrap.md
View file

@ -4,11 +4,11 @@ type: workplan
title: "Bootstrap State Hub integration"
domain: infotech
repo: disaster-control
status: ready
owner: codex
status: finished
owner: grok
topic_slug: custodian
created: "2026-07-04"
updated: "2026-07-04"
updated: "2026-07-07"
state_hub_workstream_id: "e7e1ad29-1c50-40cf-9e1c-b6e43111ff17"
---
@ -20,7 +20,7 @@ Resilience control plane for Coulomb Social / Helix Forge: the single source of
```task
id: DISCTL-WP-0001-T01
status: todo
status: done
priority: high
state_hub_task_id: "af1cee45-7172-478a-8df4-3cda0e161a45"
```
@ -28,11 +28,15 @@ state_hub_task_id: "af1cee45-7172-478a-8df4-3cda0e161a45"
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed.
Result 2026-07-07: Updated identity across `AGENTS.md`, `SCOPE.md`,
`.claude/rules/`, `.repo-classification.yaml`; archived template `REPO-WP-*`
workplans to `workplans/archived/`.
## Verify Local Developer Workflow
```task
id: DISCTL-WP-0001-T02
status: todo
status: done
priority: high
state_hub_task_id: "7a96f4ee-a491-4f37-9dbb-8f1c033aa042"
```
@ -41,6 +45,9 @@ Identify the repo's install, test, lint, build, and run commands. Add or refine
those commands in the agent instructions so future coding sessions can verify
changes confidently.
Result 2026-07-07: Documented YAML validation, `git diff --check`, mirror sync,
and `fix-consistency` in `AGENTS.md` and `.claude/rules/stack-and-commands.md`.
## Seed First Real Workplan
```task

0
workplans/REPO-WP-0001-statehub-bootstrap.md → workplans/archived/260707-REPO-WP-0001-statehub-bootstrap.md
View file

0
workplans/REPO-WP-0002-template-validation-checklist.md → workplans/archived/260707-REPO-WP-0002-template-validation-checklist.md
View file