From f0f60416ab7de9084c8964adfe1a2f57f3ffcaae Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 10 Aug 2026 17:46:39 +0200 Subject: [PATCH] Seed resource control and backup procurement plan --- .gitignore | 5 + .repo-classification.yaml | 29 +++ AGENTS.md | 199 ++++++++++++++++++ INTENT.md | 87 ++++++++ SCOPE.md | 45 ++++ WORK-RECORDS.md | 22 ++ .../RESOURCE-WP-0001-statehub-bootstrap.md | 71 +++++++ 7 files changed, 458 insertions(+) create mode 100644 .gitignore create mode 100644 .repo-classification.yaml create mode 100644 AGENTS.md create mode 100644 INTENT.md create mode 100644 SCOPE.md create mode 100644 WORK-RECORDS.md create mode 100644 workplans/RESOURCE-WP-0001-statehub-bootstrap.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e4e0199 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +# state-hub: track .claude/rules +# Claude Code local state (track shared rules; ignore machine-specific files) +.claude/* +!.claude/rules/ +!.claude/rules/*.md diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..310c941 --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,29 @@ +# Repo Classification Standard v1.0 +repo_classification: + standard: Repo Classification Standard + version: "1.0" + classified_at: "2026-08-10" + classified_by: human + category: tooling + domain: financials + secondary_domains: + - infotech + capability_tags: + - platform + - observability + - decision-support + - pricing + - control + business_stake: + - finance + - procurement + - operations + - technology + - sustainability + business_mechanics: + - control + - operation + - adaptation + notes: >- + Provider-neutral resource inventory, procurement research, total-cost and + utilization control loop; publishes allocation evidence to fin-hub. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7304ede --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,199 @@ +# resource-control — Agent Instructions + +## Repo Identity + +**Purpose:** Provider-neutral infrastructure resource inventory, procurement, cost, utilization, and optimization control plane. + +**Domain:** financials +**Repo slug:** resource-control +**Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38` +**Workplan prefix:** `RESOURCE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and +the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge +adds severe call latency; the full administrative MCP surface remains available +to clients that need it. + +| Context | URL | +|---------|-----| +| 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. + +Codex workspace-write sandboxes need network access enabled to reach the host's +loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex` +and restart Codex. The canonical REST health endpoint is `/state/health`, not +`/health`. If a sandboxed loopback probe fails, retry it with escalated execution +before declaring State Hub unavailable; a managed Codex permission profile may +still enforce isolated networking. Experimental MCP can be enabled explicitly +with `make -C ~/state-hub configure-codex WITH_MCP=1`. + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# 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 +curl -s "http://127.0.0.1:8000/messages/?to_agent=resource-control&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workplan_id": "", + "task_id": "" + }' +``` + +Omit `workplan_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) +2. Check inbox: `GET /messages/?to_agent=resource-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` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. If finishing a workplan: hand off **residuals** as live work records first + (intake with `origin: residual` + `origin_ref: `, or a next workplan / + decision / engagement). Do not park leftovers only in prose or `SCOPE.md`. + Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. +3. Log: `POST /progress/` with a summary of what changed (name handoff ids) +4. After workplan file changes, run: + ```bash + statehub fix-consistency + ``` + 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_ROUTING} + + + + +--- + +## Workplan Convention (ADR-001) + +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/RESOURCE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-RESOURCE-WP-NNNN-.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 +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: RESOURCE-WP-NNNN +type: workplan +title: "..." +domain: financials +repo: resource-control +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # fix-consistency — do not edit (legacy field name; workplan UUID) +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Terminology:** workplan is the fleet term; `workstream` appears only in legacy +API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see +`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: RESOURCE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +**Residuals when finishing:** actionable leftovers become live work records +before `status: finished` — usually an intake (`origin: residual`, +`origin_ref: RESOURCE-WP-NNNN`) or a spawned workplan. Residual is a *role*, +not a kind. Fleet list lives on State Hub, not in `SCOPE.md`. + +To create a new workplan: +1. Write the file following the format above +2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or + State Hub API is unavailable. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..1f0a9e1 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,87 @@ +# INTENT — resource-control + +## Why this repository exists + +Railiance consumes compute, storage, network, and managed services from +external providers. Those resources create recurring cost, operational +dependencies, capacity limits, and switching decisions that cannot be managed +reliably from invoices, provider consoles, or deployment repositories alone. + +`resource-control` is the control plane for that portfolio. It records what we +consume, why we consume it, who owns it, what it costs, how fully it is used, +and which procurement alternatives could provide a better combination of +cost, resilience, sovereignty, and operational fit. + +The initial provider set is: + +- **A — Host Europe** +- **B — Scaleway** +- **C — Hetzner** + +The set is a comparison baseline, not a permanent allow-list. Adding a +provider requires evidence; retaining one requires continuing value. + +## What it owns + +- A provider-neutral inventory of purchased and proposed resources. +- Resource identity, provider, region, service class, capacity, lifecycle, + contract term, renewal/cancellation window, owner, workload, environment, + and cost-attribution key. +- Normalized recurring and usage-based cost, including storage, ingress, + egress, requests, support, taxes, minimum commitments, and switching cost. +- Demand forecasts and procurement research for new compute and storage. +- Utilization and saturation evidence linked to each resource. +- Budget-versus-actual reporting inputs for `fin-hub`. +- Periodic rightsizing, consolidation, commitment, migration, and provider + switching recommendations. +- Decision records and exit plans for material provider commitments. + +## Relationship with fin-hub + +`resource-control` answers **what concrete resources are bought, used, and +replaceable**. `fin-hub` answers **what the federation can afford, what its burn +rate and runway are, and when resource pressure must change priorities**. + +This repo publishes normalized inventory, allocation, forecast, and realized +cost evidence to fin-hub. It does not create a competing budget ledger or +financial allocator. + +## Operating principles + +1. **Provider-neutral requirements first.** Define durability, recovery, + residency, performance, capacity, and exit requirements before comparing + product names. +2. **Total cost, not headline price.** Include traffic, requests, minimum + charges, tax, support, labor, migration, and recovery-test cost. +3. **No unowned spend.** Every resource has an accountable owner, workload, + environment, purpose, and cost-attribution key. +4. **No untested resilience claims.** Backup resources are accepted only after + a restore; compute failover is accepted only after a failover exercise. +5. **Exit is part of procurement.** Record data export, migration path, + cancellation window, and credential revocation before commitment. +6. **Avoid correlated failure silently.** Same-provider placement may be + intentional, but the shared failure domain and compensating control must be + explicit. +7. **Measure before optimizing.** Recommendations distinguish observed + utilization from estimates and assumptions. +8. **Credentials stay elsewhere.** Provider keys and billing credentials live + in the approved OpenBao/credential-broker lanes, never in this repository. + +## What it does not own + +- Budget authority, runway policy, or financial transactions (`fin-hub` and + human financial authority). +- Workload manifests and service-specific backup procedures (owning `rapp-*` + or workload repositories). +- Provider credentials or payment instruments. +- Cluster-wide deployment governance (`railiance-platform`). +- Application data retention policy, except to verify that procured resources + can satisfy it. + +## Initial outcome + +Procure and operationalize off-host object storage for `rapp-postgres` +continuous WAL archiving and physical base backups, while retaining a separate +logical-backup copy. The chosen resource must support a verified full restore +and point-in-time recovery, expose its real monthly cost and utilization to +fin-hub, and retain a tested provider-exit path. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..1abf84c --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,45 @@ +# SCOPE + +> This file was generated by `statehub register`. Refine it as the repository +> boundaries become clearer. + +## One-liner + +Provider-neutral infrastructure resource inventory, procurement, cost, utilization, and optimization control plane. + +## Core Idea + +resource-control exists to provide the capability described in INTENT.md. + +## In Scope + +- Inventory purchased and proposed compute, storage, network, and managed + resources across Host Europe, Scaleway, Hetzner, and future providers. +- Normalize price, commitment, utilization, capacity, ownership, workload, + location, failure domain, renewal, and exit data. +- Research and compare procurement options against provider-neutral + requirements. +- Publish resource allocation, forecast, realized-cost, and optimization + evidence to fin-hub. +- Track procurement decisions, renewal/cancellation windows, rightsizing, + consolidation, and provider-switch opportunities. +- Verify that acquired resources satisfy their operational requirement. + +## Out of Scope + +- Execute payments or approve financial commitments. +- Store provider, billing, or workload credentials. +- Own workload manifests, application retention policy, or backup procedures. +- Replace fin-hub's budget, burn-rate, runway, and viability authority. +- Make irreversible procurement or cancellation decisions without human + approval. + +## Current State + +- Status: active; implementation and stability should be verified by the repo agent. + +## Getting Oriented + +- Start with: INTENT.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..9d4d21a --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,22 @@ +# Work Records — resource-control + +> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record +> stage 3). Do not edit by hand — edit the source file/block listed for +> each record and re-run fix-consistency to refresh this index. Archived +> workplans are omitted; closed decisions/intakes/engagements stay listed +> so recently-resolved work is still visible. [auto] + +| Kind | ID | Status | Lane | Source | +| --- | --- | --- | --- | --- | +| workplan | RESOURCE-WP-0001 | finished | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md | +| workplan | RESOURCE-WP-0002 | ready | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0001-T01 | done | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md | +| task | RESOURCE-WP-0001-T02 | done | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md | +| task | RESOURCE-WP-0001-T03 | done | — | workplans/RESOURCE-WP-0001-statehub-bootstrap.md | +| task | RESOURCE-WP-0002-T01 | todo | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0002-T02 | todo | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0002-T03 | wait | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0002-T04 | wait | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0002-T05 | wait | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0002-T06 | todo | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | +| task | RESOURCE-WP-0002-T07 | todo | — | workplans/RESOURCE-WP-0002-procure-postgres-backup-storage.md | diff --git a/workplans/RESOURCE-WP-0001-statehub-bootstrap.md b/workplans/RESOURCE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..d7547e4 --- /dev/null +++ b/workplans/RESOURCE-WP-0001-statehub-bootstrap.md @@ -0,0 +1,71 @@ +--- +id: RESOURCE-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: financials +repo: resource-control +status: finished +owner: codex +topic_slug: railiance +created: "2026-08-10" +updated: "2026-08-10" +state_hub_workstream_id: "e17a3b82-f380-447d-a95d-baac97c3a555" +--- + +# Bootstrap State Hub integration + +Provider-neutral infrastructure resource inventory, procurement, cost, utilization, and optimization control plane. + +## Review Generated Integration Files + +```task +id: RESOURCE-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "d2514ee4-f991-463f-9565-72d5ea401f61" +``` + +Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. +Replace generated placeholders with repo-specific facts where needed. + +Completed 2026-08-10: reviewed generated files and refined `SCOPE.md` around +inventory, procurement, cost/utilization evidence, fin-hub handoff, credential +custody, and human purchasing authority. + +## Verify Local Developer Workflow + +```task +id: RESOURCE-WP-0001-T02 +status: done +priority: high +state_hub_task_id: "7baeab45-b0a3-418c-a1b0-e157ca359ec6" +``` + +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. + +Completed for the seed stage 2026-08-10: the repository is currently a +file-backed control plane with no executable package. Validation is +`statehub fix-consistency`, `git diff --check`, and YAML/Markdown parsing as +schemas are introduced. A future implementation workplan must add first-class +validation commands with the resource declaration schema. + +## Seed First Real Workplan + +```task +id: RESOURCE-WP-0001-T03 +status: done +priority: medium +state_hub_task_id: "86ba2e50-8524-4cdc-bcd2-e7d5d66da869" +``` + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run the sync locally from this repo +checkout: + +```bash +statehub fix-consistency +``` + +Completed 2026-08-10 with `RESOURCE-WP-0002`.