coulomb/ops-warden
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Normalize agent instructions and workplan frontmatter (STATE-WP-0067)

Browse Source 
- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
This commit is contained in:
Bernd Worsch
2026-06-22 23:16:27 +02:00
parent 46cb1a5f0c
commit 2207dc6b00
12 changed files with 49 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
.claude/rules/architecture.md
View File

@@ -1,63 +1,8 @@
## Architecture ## Architecture
ops-warden owns **credential issuance only** — CA signing, actor inventory, TTL <!-- TODO: Describe the key design decisions and component structure.
policy, and cert-side compliance checks. It does not manage tunnels, host SSH Key modules, data flows, external integrations, state machines, etc. -->
config, or long-lived API keys.
### Module layout
```
src/warden/
├── cli.py # Typer commands: sign, issue, status, scorecard, cleanup, log, inventory
├── models.py # ActorType, CertSpec, CertRecord, TTL policy
├── config.py # ~/.config/warden/warden.yaml loader
├── ca.py # LocalCA (ssh-keygen -s), CABackend base, signatures log, eviction
├── vault.py # VaultCA — Vault/OpenBao SSH secrets engine API
├── inventory.py # inventory.yaml load/save
├── scorecard.py # §5 cert-side compliance checks
└── scripts/
└── ops_ssh_wrapper.py # WARDEN_ACTOR + ssh-add + exec wrapper
```
### Backend selection
Config key `backend: local | vault` selects the CA implementation. Both expose the
same CLI and `cert_command` contract — callers (principally `ops-bridge`) never
branch on backend.
### Signing flow
```
warden sign <actor> --pubkey <path>
→ load_config() + load_inventory()
→ validate actor name prefix (adm-/agt-/atm-)
→ enforce_ttl() against ActorType max
→ CABackend.sign(CertSpec)
→ evict previous cert for actor
→ sign (ssh-keygen -s or Vault API)
→ write cert to state_dir (mode 600)
→ append signatures.log (JSONL)
→ cert text on stdout (cert_command contract)
```
### External integrations
| Integration | Role |
|-------------|------|
| `ssh-keygen` | Local CA signing and cert metadata parsing |
| Vault/OpenBao SSH engine | Production signing via HTTP API (`vault.py`) |
| `ops-bridge` | Primary consumer of `warden sign` via `cert_command` |
| `railiance-infra` | Host-side `/etc/ssh/auth_principals/` deployment (out of scope here) |
### cert_command contract
```
warden sign <actor-name> --pubkey <path>
```
Writes signed certificate to stdout. Non-zero exit on failure. Documented in
`wiki/CertCommandInterface.md`.
## Quick Reference ## Quick Reference
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference `~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

10
.claude/rules/first-session.md
View File

@@ -1,11 +1,11 @@
## First Session Protocol ## First Session Protocol
Triggered when `get_domain_summary("custodian")` shows **no workstreams**. Triggered when `get_domain_summary("infotech")` shows **no workstreams**.
The project is registered but work has not yet been structured. The project is registered but work has not yet been structured.
**Step 1 — Read, don't write** **Step 1 — Read, don't write**
- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope - `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases - `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases
- Scan repo root: README, directory structure, existing code or docs - Scan repo root: README, directory structure, existing code or docs
**Step 2 — Survey in-progress work** **Step 2 — Survey in-progress work**
@@ -17,7 +17,7 @@ roadmap phase. **Wait for approval before creating.**
**Step 4 — Create workplan file first, then DB record (ADR-001)** **Step 4 — Create workplan file first, then DB record (ADR-001)**
``` ```
workplans/ops-warden-WP-NNNN-<slug>.md ← write this first workplans/WARDEN-WP-NNNN-<slug>.md ← write this first
``` ```
Then register in the hub: Then register in the hub:
``` ```
@@ -28,7 +28,7 @@ create_task(workstream_id="<id>", title="...", priority="high|medium|low")
**Step 5 — Record the setup** **Step 5 — Record the setup**
``` ```
add_progress_event( add_progress_event(
summary="First session: structured custodian into N workstreams, M tasks", summary="First session: structured infotech into N workstreams, M tasks",
event_type="milestone", event_type="milestone",
topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
detail={"workstreams": [...], "tasks_created": M} detail={"workstreams": [...], "tasks_created": M}

36
.claude/rules/repo-boundary.md
View File

@@ -2,35 +2,7 @@
This repo owns **ops-warden** only. It does not own: This repo owns **ops-warden** only. It does not own:
| Concern | Owner | <!-- TODO: List what belongs in adjacent repos, e.g.:
|---------|-------| - SSH key management → railiance-infra/
| Tunnel lifecycle, `cert_command` wiring in tunnels | `ops-bridge` | - State hub code → state-hub/
| Host SSH principal files, force-command wrappers | `railiance-infra` | -->
| Vault/OpenBao cluster deployment and unseal ceremony | `railiance-platform` |
| Inter-Hub operator API keys, provider API keys (e.g. OpenRouter) | OpenBao / operator secret store |
| State Hub service code and consistency tooling | `state-hub` |
| Workstream coordination across custodian domain | `the-custodian` |
| Human admin SSH key generation | self-service (`ssh-keygen`) |
| Identity / OIDC / MFA | `key-cape`, Keycloak |
| Authorization policy | `flex-auth` |
| Runtime secrets (non-SSH) | OpenBao |
## NetKingdom credential routing (quick reference)
| Worker need | Route to | ops-warden |
|-------------|----------|------------|
| SSH cert for host/ops access | ops-warden | Issue (`warden sign`) |
| API key / DB cred / lease | OpenBao | Document only — `wiki/CredentialRouting.md` |
| May I perform action X? | flex-auth | Design: `wiki/PolicyGatedSigning.md` |
| Login / MFA / OIDC | key-cape / Keycloak | Document only |
| SSH tunnel | ops-bridge | cert_command consumer |
| Host principals | railiance-infra | Document only |
Full map: `wiki/NetKingdomSecurityMap.md`. Role and boundary: `wiki/AccessRouting.md`.
Machine-readable pointer catalog: `registry/routing/catalog.yaml`.
ops-warden **issues short-lived SSH certificates** (the one lane it executes) and
**routes every other credential need to its owner** via stewardship docs and the
pointer catalog. It is not a general secrets manager and must not store long-lived
API keys in Git, State Hub, workplans, logs, or chat. Routing material **points at**
the owner's docs — it never restates or forks another subsystem's procedure.

2
.claude/rules/repo-identity.md
View File

@@ -1,5 +1,5 @@
**Purpose:** SSH CA and certificate lifecycle manager — signs short-lived certs for adm/agt/atm actors; provides the cert_command interface consumed by ops-bridge. **Purpose:** SSH CA and certificate lifecycle manager — signs short-lived certs for adm/agt/atm actors; provides the cert_command interface consumed by ops-bridge.
**Domain:** custodian **Domain:** infotech
**Repo slug:** ops-warden **Repo slug:** ops-warden
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a **Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a

9
.claude/rules/session-protocol.md
View File

@@ -1,6 +1,7 @@
## Session Protocol ## Session Protocol
State Hub: http://127.0.0.1:8000 Dev Hub (State Hub API): http://127.0.0.1:8000
MCP server name in `~/.claude.json`: `dev-hub`
**Step 1 — Orient** **Step 1 — Orient**
@@ -10,7 +11,7 @@ cat .custodian-brief.md
``` ```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed: Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
``` ```
get_domain_summary("custodian") get_domain_summary("infotech")
``` ```
If MCP tools are unavailable in the current agent session, use the REST API: If MCP tools are unavailable in the current agent session, use the REST API:
```bash ```bash
@@ -39,11 +40,11 @@ curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
ls workplans/ ls workplans/
``` ```
For each file with `status: ready`, `active`, or `blocked`, note pending For each file with `status: ready`, `active`, or `blocked`, note pending
`todo`/`in_progress` tasks. `wait`/`todo`/`progress` tasks.
**Step 4 — Present brief** **Step 4 — Present brief**
1. **Active workstreams** for `custodian` — title, task counts, blocking decisions 1. **Active workstreams** for `infotech` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:ops-warden]` hub tasks 2. **Pending tasks** from `workplans/` + any `[repo:ops-warden]` 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"*

32
.claude/rules/stack-and-commands.md
View File

@@ -1,35 +1,19 @@
## Stack ## Stack
- **Language:** Python 3.11+ <!-- TODO: Fill in language, frameworks, and key dependencies -->
- **CLI:** Typer + Rich - **Language:**
- **Key deps:** pyyaml, httpx (Vault/OpenBao API); ssh-keygen subprocess (local CA) - **Key deps:**
- **Packaging:** hatchling + uv
## Dev Commands ## Dev Commands
```bash ```bash
# TODO: Fill in the standard commands for this repo
# Install dependencies # Install dependencies
uv sync
# Run unit tests (integration tests excluded by default) # Run tests
uv run pytest
# Run real ssh-keygen integration tests # Lint / type check
uv run pytest -m integration
# Lint # Build / package (if applicable)
uv run ruff check .
# Install CLI locally
uv tool install .
# CLI help
warden --help
ops-ssh-wrapper --help # after install
``` ```
Config and state paths:
- `~/.config/warden/warden.yaml` — backend selection (`local` | `vault`)
- `~/.config/warden/inventory.yaml` — actor registry
- `~/.local/state/warden/` — certs, keys, `signatures.log`

22
.claude/rules/workplan-convention.md
View File

@@ -1,7 +1,7 @@
## Workplan Convention (ADR-001) ## Workplan Convention (ADR-001)
File location: `workplans/ops-warden-WP-NNNN-<slug>.md` File location: `workplans/WARDEN-WP-NNNN-<slug>.md`
ID prefix: `OPS-WP` ID prefix: `WARDEN-WP-`
Work items originate as files in this repo **before** being registered in the hub. Work items originate as files in this repo **before** being registered in the hub.
@@ -12,7 +12,7 @@ repo state, and `finished` when implementation is complete. `stalled` and
`needs_review` are derived health labels, not stored statuses. `needs_review` are derived health labels, not stored statuses.
Closed workplans may be moved to `workplans/archived/` with a completion-date Closed workplans may be moved to `workplans/archived/` with a completion-date
prefix: `YYMMDD-ops-warden-WP-NNNN-<slug>.md`. The frontmatter id remains prefix: `YYMMDD-WARDEN-WP-NNNN-<slug>.md`. The frontmatter id remains
unchanged; the prefix is only for quick visual reference. unchanged; the prefix is only for quick visual reference.
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
@@ -25,24 +25,16 @@ Ecosystem todos from other agents arrive as `[repo:ops-warden]` hub tasks —
visible at session start. Pick one up by creating the workplan file, then registering visible at session start. Pick one up by creating the workplan file, then registering
the workstream. the workstream.
**Task block format** (one per `##` section in workplan files): Task blocks use this shape:
```
## Task Title
```task ```task
id: WARDEN-WP-NNNN-T01 id: WARDEN-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
``` ```
Task description text. Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
``` blocked work and `cancel` for stopped work.
Canonical task statuses (State Hub InfoTechCanon): `wait`, `todo`, `progress`,
`done`, `cancel`. Use `wait` for tasks blocked on external dependencies (not
`blocked` — that alias maps to `wait` during migration). Progression:
`todo` → `progress` → `done`.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here --> <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

22
AGENTS.md
View File

@@ -2,12 +2,12 @@
## Repo Identity ## Repo Identity
**Purpose:** Issues short-lived SSH certs for adm/agt/atm actors (the one lane it executes) and routes every other credential need to its owner; provides the cert_command interface consumed by ops-bridge. **Purpose:** SSH CA and certificate lifecycle manager — signs short-lived certs for adm/agt/atm actors; provides the cert_command interface consumed by ops-bridge.
**Domain:** custodian **Domain:** infotech
**Repo slug:** ops-warden **Repo slug:** ops-warden
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` **Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `OPS-WP-` **Workplan prefix:** `WARDEN-WP-`
--- ---
@@ -64,8 +64,7 @@ Omit `workstream_id` / `task_id` when not applicable.
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"status": "progress"}' -d '{"status": "progress"}'
# canonical values: wait | todo | progress | done | cancel # values: wait | todo | progress | done | cancel
# migration aliases (accepted during transition): blocked→wait, in_progress→progress
``` ```
### Flag a task for human review ### Flag a task for human review
@@ -84,7 +83,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
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=ops-warden&unread_only=true`; mark read 2. Check inbox: `GET /messages/?to_agent=ops-warden&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 blocked tasks: `GET /tasks/?needs_human=true` 4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:** **During work:**
- Update task statuses in workplan files as tasks progress - Update task statuses in workplan files as tasks progress
@@ -152,6 +151,11 @@ every repo's agent instructions because it is high-frequency, high-risk, and eas
get wrong. get wrong.
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` **Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
--- ---
## Workplan Convention (ADR-001) ## Workplan Convention (ADR-001)
@@ -177,7 +181,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
id: OPS-WP-NNNN id: OPS-WP-NNNN
type: workplan type: workplan
title: "..." title: "..."
domain: custodian domain: infotech
repo: ops-warden repo: ops-warden
status: proposed | ready | active | blocked | backlog | finished | archived status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex owner: codex
@@ -207,9 +211,7 @@ state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
Task description text. Task description text.
``` ```
Task status progression: `todo` → `progress` → `done` (or `wait` when blocked on Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
external dependency, `cancel` when dropped). Workplan/workstream frontmatter
statuses are separate and still include `blocked`.
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
workplans/WARDEN-WP-0009-flex-auth-policy-gate-production.md
View File

@@ -2,7 +2,7 @@
id: WARDEN-WP-0009 id: WARDEN-WP-0009
type: workplan type: workplan
title: "flex-auth Policy Gate Production Readiness" title: "flex-auth Policy Gate Production Readiness"
domain: custodian domain: infotech
repo: ops-warden repo: ops-warden
status: blocked status: blocked
owner: codex owner: codex

2
workplans/WARDEN-WP-0010-access-routing-charter.md
View File

@@ -2,7 +2,7 @@
id: WARDEN-WP-0010 id: WARDEN-WP-0010
type: workplan type: workplan
title: "Access Routing — Charter and Pointer Catalog" title: "Access Routing — Charter and Pointer Catalog"
domain: custodian domain: infotech
repo: ops-warden repo: ops-warden
status: done status: done
owner: codex owner: codex

2
workplans/WARDEN-WP-0011-routing-guide-cli.md
View File

@@ -2,7 +2,7 @@
id: WARDEN-WP-0011 id: WARDEN-WP-0011
type: workplan type: workplan
title: "Routing Lookup CLI" title: "Routing Lookup CLI"
domain: custodian domain: infotech
repo: ops-warden repo: ops-warden
status: done status: done
owner: codex owner: codex

2
workplans/WARDEN-WP-0012-routing-scenario-playbooks.md
View File

@@ -2,7 +2,7 @@
id: WARDEN-WP-0012 id: WARDEN-WP-0012
type: workplan type: workplan
title: "Routing Scenario Playbooks" title: "Routing Scenario Playbooks"
domain: custodian domain: infotech
repo: ops-warden repo: ops-warden
status: backlog status: backlog
owner: codex owner: codex