Complete DISCTL-WP-0001: bootstrap State Hub integration

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

View file

@ -1,8 +1,12 @@
## Repo boundary ## 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.: | Concern | Owner repo |
- SSH key management → railiance-infra/ | --- | --- |
- State hub code → state-hub/ | 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` |

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 **Domain:** infotech
**Repo slug:** repo-seed **Repo slug:** disaster-control
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a **Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
**Workplan prefix:** DISCTL-WP-

View file

@ -22,14 +22,14 @@ If the hub is offline: `cd ~/state-hub && make api`
**Step 2 — Check inbox** **Step 2 — Check inbox**
With MCP tools: 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 Mark read with `mark_message_read(message_id)`. Reply or act on coordination
requests before proceeding. requests before proceeding.
Without MCP tools: Without MCP tools:
```bash ```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 | python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \ curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}' -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** **Step 4 — Present brief**
1. **Active workstreams** for `infotech` — title, task counts, blocking decisions 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: 3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* - `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 - `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: If workplan files were modified, ensure the local copy is up to date first:
```bash ```bash
git -C <repo_path> pull --ff-only 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), For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the combined target which pulls before fixing: use the combined target which pulls before fixing:
```bash ```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 **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 will sync the file to match DB. **C-16** (repo behind remote) blocks all writes

View file

@ -1,27 +1,39 @@
## Stack ## Stack
- **Language:** Markdown-first registry and planning repo (no application runtime yet) - **Language:** Markdown-first governance repo (YAML registers, policies, runbooks)
- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml` - **Key deps:** State Hub ADR-001 workplans, YAML registers, cross-repo backup tooling
## Dev Commands ## Dev Commands
```bash ```bash
# Orient (offline-safe) # Orient (offline-safe)
cat .custodian-brief.md cat .custodian-brief.md
cat README.md cat INTENT.md
cat SCOPE.md cat PanicSheet.md
ls workplans/ ls workplans/
# Consumer bootstrap docs # Validate register YAML
cat docs/statehub-register.md python3 -c "import yaml; yaml.safe_load(open('AssetRegister.yaml')); yaml.safe_load(open('DataRegister.yaml'))"
cat docs/template-validation-checklist.md
# After workplan or registry edits — from ~/state-hub # Sanity-check markdown / YAML edits
make fix-consistency REPO=repo-seed
# Validate registry entries (from reuse-surface checkout)
reuse-surface validate --root .
# Sanity-check markdown / registry edits
git diff --check 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 |

View file

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

View file

@ -1,13 +1,13 @@
# Repo Seed — Agent Instructions # disaster-control — Agent Instructions
## Repo Identity ## Repo Identity
**Purpose:** Git repository template to bootstrap coulomb projects. **Purpose:** Resilience Control Plane for Coulomb Social / Helix Forge.
**Domain:** infotech **Domain:** infotech
**Repo slug:** repo-seed **Repo slug:** disaster-control
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` **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 | python3 -m json.tool
# Check inbox # 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 | python3 -m json.tool
``` ```
@ -81,7 +81,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
**Start:** **Start:**
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) 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 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` 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 3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`: `~/state-hub`:
```bash ```bash
make fix-consistency REPO=repo-seed make fix-consistency REPO=disaster-control
``` ```
This syncs task status from files into the hub DB. 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 | | 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 | | **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` | | **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. <!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. --> 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) ## 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 Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files. 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 **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. the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use **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 ```yaml
--- ---
id: REPO-WP-NNNN id: DISCTL-WP-NNNN
type: workplan type: workplan
title: "..." title: "..."
domain: infotech domain: infotech
repo: repo-seed repo: disaster-control
status: proposed | ready | active | blocked | backlog | finished | archived status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex owner: codex
topic_slug: ... topic_slug: ...
@ -202,7 +222,7 @@ derived health labels, not frontmatter statuses.
## Task Title ## Task Title
` ` `task ` ` `task
id: REPO-WP-NNNN-T01 id: DISCTL-WP-NNNN-T01
status: wait | todo | progress | done | cancel status: wait | todo | progress | done | cancel
priority: high | medium | low priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit 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: To create a new workplan:
1. Write the file following the format above 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/`) (or send a message to the hub agent via `POST /messages/`)

View file

@ -6,26 +6,33 @@
## One-liner ## One-liner
Git repository template to bootstrap coulomb projects. Resilience Control Plane for Coulomb Social / Helix Forge — recovery governance, evidence, and registers.
--- ---
## Core Idea ## 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 ## In Scope
- Template files for new repo bootstrap - Asset and data registers (`AssetRegister.yaml`, `DataRegister.yaml`)
- Documentation for statehub_register usage - Resilience and backup policy (`ResiliencePolicy.md`, `BackupPolicy.md`, `RTO-RPO-Matrix.md`)
- Registry capability entry for template capability - 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 ## Out of Scope
- Application runtime code - 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`)

View file

@ -4,11 +4,11 @@ type: workplan
title: "Bootstrap State Hub integration" title: "Bootstrap State Hub integration"
domain: infotech domain: infotech
repo: disaster-control repo: disaster-control
status: ready status: finished
owner: codex owner: grok
topic_slug: custodian topic_slug: custodian
created: "2026-07-04" created: "2026-07-04"
updated: "2026-07-04" updated: "2026-07-07"
state_hub_workstream_id: "e7e1ad29-1c50-40cf-9e1c-b6e43111ff17" 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 ```task
id: DISCTL-WP-0001-T01 id: DISCTL-WP-0001-T01
status: todo status: done
priority: high priority: high
state_hub_task_id: "af1cee45-7172-478a-8df4-3cda0e161a45" 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`. Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed. 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 ## Verify Local Developer Workflow
```task ```task
id: DISCTL-WP-0001-T02 id: DISCTL-WP-0001-T02
status: todo status: done
priority: high priority: high
state_hub_task_id: "7a96f4ee-a491-4f37-9dbb-8f1c033aa042" 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 those commands in the agent instructions so future coding sessions can verify
changes confidently. 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 ## Seed First Real Workplan
```task ```task