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

- 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
2026-06-22 23:16:27 +02:00
parent 46cb1a5f0c
commit 2207dc6b00
12 changed files with 49 additions and 153 deletions
--- a/.claude/rules/architecture.md
+++ b/.claude/rules/architecture.md
@@ -1,63 +1,8 @@
 ## Architecture

-ops-warden owns **credential issuance only** — CA signing, actor inventory, TTL
-policy, and cert-side compliance checks. It does not manage tunnels, host SSH
-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`.
+<!-- TODO: Describe the key design decisions and component structure.
+     Key modules, data flows, external integrations, state machines, etc. -->

 ## Quick Reference

-`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
+`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
--- a/.claude/rules/first-session.md
+++ b/.claude/rules/first-session.md
@@ -1,11 +1,11 @@
 ## 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.

 **Step 1 — Read, don't write**
- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases
+- `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope
+- `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases
 - Scan repo root: README, directory structure, existing code or docs

 **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)**
 ```
-workplans/ops-warden-WP-NNNN-<slug>.md   ← write this first
+workplans/WARDEN-WP-NNNN-<slug>.md   ← write this first
 ```
 Then register in the hub:
 ```
@@ -28,7 +28,7 @@ create_task(workstream_id="<id>", title="...", priority="high|medium|low")
 **Step 5 — Record the setup**
 ```
 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",
    topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
    detail={"workstreams": [...], "tasks_created": M}
--- a/.claude/rules/repo-boundary.md
+++ b/.claude/rules/repo-boundary.md
@@ -2,35 +2,7 @@

 This repo owns **ops-warden** only. It does not own:

-| Concern | Owner |
-|---------|-------|
-| Tunnel lifecycle, `cert_command` wiring in tunnels | `ops-bridge` |
-| 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.
+<!-- TODO: List what belongs in adjacent repos, e.g.:
+- SSH key management → railiance-infra/
+- State hub code     → state-hub/
+-->
--- a/.claude/rules/repo-identity.md
+++ b/.claude/rules/repo-identity.md
@@ -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.

-**Domain:** custodian
+**Domain:** infotech
 **Repo slug:** ops-warden
 **Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
--- a/.claude/rules/session-protocol.md
+++ b/.claude/rules/session-protocol.md
@@ -1,6 +1,7 @@
 ## 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**

@@ -10,7 +11,7 @@ cat .custodian-brief.md
 ```
 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:
 ```bash
@@ -39,11 +40,11 @@ curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
 ls workplans/
 ```
 For each file with `status: ready`, `active`, or `blocked`, note pending
-`todo`/`in_progress` tasks.
+`wait`/`todo`/`progress` tasks.

 **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
 3. **Goal guidance** — if `goal_guidance` in summary:
   - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
--- a/.claude/rules/stack-and-commands.md
+++ b/.claude/rules/stack-and-commands.md
@@ -1,35 +1,19 @@
 ## Stack

- **Language:** Python 3.11+
- **CLI:** Typer + Rich
- **Key deps:** pyyaml, httpx (Vault/OpenBao API); ssh-keygen subprocess (local CA)
- **Packaging:** hatchling + uv
+<!-- TODO: Fill in language, frameworks, and key dependencies -->
+- **Language:**
+- **Key deps:**

 ## Dev Commands

 ```bash
+# TODO: Fill in the standard commands for this repo
+
 # Install dependencies
-uv sync

-# Run unit tests (integration tests excluded by default)
-uv run pytest
+# Run tests

-# Run real ssh-keygen integration tests
-uv run pytest -m integration
+# Lint / type check

-# Lint
-uv run ruff check .
-
-# Install CLI locally
-uv tool install .
-
-# CLI help
-warden --help
-ops-ssh-wrapper --help   # after install
+# Build / package (if applicable)
 ```
-
-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`
--- a/.claude/rules/workplan-convention.md
+++ b/.claude/rules/workplan-convention.md
@@ -1,7 +1,7 @@
 ## Workplan Convention (ADR-001)

-File location: `workplans/ops-warden-WP-NNNN-<slug>.md`
-ID prefix: `OPS-WP`
+File location: `workplans/WARDEN-WP-NNNN-<slug>.md`
+ID prefix: `WARDEN-WP-`

 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.

 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.

 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
 the workstream.

-**Task block format** (one per `##` section in workplan files):
-
-```
-## Task Title
+Task blocks use this shape:

 ```task
 id: WARDEN-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
+state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
 ```

-Task description text.
-```
-
-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`.
+Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
+blocked work and `cancel` for stopped work.

 <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,12 +2,12 @@

 ## 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
 **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>" \
  -H "Content-Type: application/json" \
  -d '{"status": "progress"}'
-# canonical values: wait | todo | progress | done | cancel
-# migration aliases (accepted during transition): blocked→wait, in_progress→progress
+# values: wait | todo | progress | done | cancel
 ```

 ### 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)
 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
-4. Check blocked tasks: `GET /tasks/?needs_human=true`
+4. Check human-needed tasks: `GET /tasks/?needs_human=true`

 **During work:**
 - 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.

 **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)
@@ -177,7 +181,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
 id: OPS-WP-NNNN
 type: workplan
 title: "..."
-domain: custodian
+domain: infotech
 repo: ops-warden
 status: proposed | ready | active | blocked | backlog | finished | archived
 owner: codex
@@ -207,9 +211,7 @@ state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
 Task description text.
 ```

-Task status progression: `todo` → `progress` → `done` (or `wait` when blocked on
-external dependency, `cancel` when dropped). Workplan/workstream frontmatter
-statuses are separate and still include `blocked`.
+Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.

 To create a new workplan:
 1. Write the file following the format above
--- a/workplans/WARDEN-WP-0009-flex-auth-policy-gate-production.md
+++ b/workplans/WARDEN-WP-0009-flex-auth-policy-gate-production.md
@@ -2,7 +2,7 @@
 id: WARDEN-WP-0009
 type: workplan
 title: "flex-auth Policy Gate Production Readiness"
-domain: custodian
+domain: infotech
 repo: ops-warden
 status: blocked
 owner: codex
--- a/workplans/WARDEN-WP-0010-access-routing-charter.md
+++ b/workplans/WARDEN-WP-0010-access-routing-charter.md
@@ -2,7 +2,7 @@
 id: WARDEN-WP-0010
 type: workplan
 title: "Access Routing — Charter and Pointer Catalog"
-domain: custodian
+domain: infotech
 repo: ops-warden
 status: done
 owner: codex
--- a/workplans/WARDEN-WP-0011-routing-guide-cli.md
+++ b/workplans/WARDEN-WP-0011-routing-guide-cli.md
@@ -2,7 +2,7 @@
 id: WARDEN-WP-0011
 type: workplan
 title: "Routing Lookup CLI"
-domain: custodian
+domain: infotech
 repo: ops-warden
 status: done
 owner: codex
--- a/workplans/WARDEN-WP-0012-routing-scenario-playbooks.md
+++ b/workplans/WARDEN-WP-0012-routing-scenario-playbooks.md
@@ -2,7 +2,7 @@
 id: WARDEN-WP-0012
 type: workplan
 title: "Routing Scenario Playbooks"
-domain: custodian
+domain: infotech
 repo: ops-warden
 status: backlog
 owner: codex