WARDEN-WP-0004: repo hygiene and hub sync

Update SCOPE and README to reflect the shipped warden CLI, fill agent
rules for stack/architecture/boundary, archive finished workplans
0001–0003, and register WP-0004 in State Hub.

.claude/rules/architecture.md

@@ -1,7 +1,62 @@
 ## Architecture
 
-<!-- TODO: Describe the key design decisions and component structure.
+ops-warden owns **credential issuance only** — CA signing, actor inventory, TTL
-     Key modules, data flows, external integrations, state machines, etc. -->
+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`.
 
 ## Quick Reference
 

.claude/rules/repo-boundary.md

@@ -2,7 +2,16 @@
 
 This repo owns **ops-warden** only. It does not own:
 
-<!-- TODO: List what belongs in adjacent repos, e.g.:
+| Concern | Owner |
-- SSH key management → railiance-infra/
+|---------|-------|
-- State hub code     → state-hub/
+| 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`) |
+
+ops-warden issues **short-lived SSH certificates** only. It is not a general
+secrets manager and must not store long-lived API keys in Git, State Hub, or
+workplans.

.claude/rules/stack-and-commands.md

@@ -1,19 +1,35 @@
 ## Stack
 
-<!-- TODO: Fill in language, frameworks, and key dependencies -->
+- **Language:** Python 3.11+
-- **Language:**
+- **CLI:** Typer + Rich
-- **Key deps:**
+- **Key deps:** pyyaml, httpx (Vault/OpenBao API); ssh-keygen subprocess (local CA)
+- **Packaging:** hatchling + uv
 
 ## Dev Commands
 
 ```bash
-# TODO: Fill in the standard commands for this repo
-
 # Install dependencies
+uv sync
 
-# Run tests
+# Run unit tests (integration tests excluded by default)
+uv run pytest
 
-# Lint / type check
+# Run real ssh-keygen integration tests
+uv run pytest -m integration
 
-# Build / package (if applicable)
+# Lint
+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`

README.md

@@ -1,3 +1,64 @@
-# repo-seed
+# ops-warden
 
-A git repository template to bootstrap coulomb projects from.
+SSH Certificate Authority and certificate lifecycle manager for the ops fleet.
+Signs short-lived certs for `adm` / `agt` / `atm` actors and exposes the
+`cert_command` interface consumed by `ops-bridge` and other tooling.
+
+See `SCOPE.md` for boundaries and `wiki/AccessManagementDirective.md` for policy.
+
+## Install
+
+```bash
+uv sync
+uv tool install .
+```
+
+Or run without installing:
+
+```bash
+uv run warden --help
+```
+
+## Quick start (local backend)
+
+```bash
+# One-time: generate a CA key (keep mode 600, never commit)
+ssh-keygen -t ed25519 -f ~/.ssh/ops-ca-user -C "Ops SSH User CA" -N ""
+
+# Configure warden (~/.config/warden/warden.yaml) — see wiki/OpsWardenConfig.md
+warden inventory add agt-example --type agt --principal agt-example
+warden sign agt-example --pubkey ~/.ssh/id_ed25519.pub
+warden status agt-example
+warden scorecard
+```
+
+Production uses the `vault` backend against OpenBao or HashiCorp Vault (Vault-compatible
+SSH secrets engine API). See `wiki/OpsWardenConfig.md`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest              # unit tests (integration excluded)
+uv run pytest -m integration   # requires ssh-keygen in PATH
+uv run ruff check .
+```
+
+## Key paths
+
+| Path | Purpose |
+|------|---------|
+| `~/.config/warden/warden.yaml` | Backend and CA/Vault settings |
+| `~/.config/warden/inventory.yaml` | Actor → principals registry |
+| `~/.local/state/warden/` | Signed certs, keys, `signatures.log` |
+
+## Documentation
+
+- `wiki/OpsWardenConfig.md` — configuration reference
+- `wiki/CertCommandInterface.md` — `cert_command` contract for callers
+- `wiki/InterHubBootstrapAccessLane.md` — short-lived cert envelope for bootstrap tasks
+
+## Workplans
+
+Active and proposed work lives in `workplans/`. Finished plans are archived under
+`workplans/archived/`.

SCOPE.md

@@ -73,8 +73,11 @@ backend is in use.
 
 ## Current State
 
-- Status: planned — WARDEN-WP-0001 not yet started
+- Status: shipped — WARDEN-WP-0001 through WARDEN-WP-0003 complete (v0.1.0)
-- Implementation: scaffolding only (models, config, CA, inventory, scorecard, CLI stubs)
+- Implementation: full `warden` CLI with `local` and `vault` backends, inventory,
+  scorecard, cleanup, signatures log, and `ops-ssh-wrapper`
+- Active maintenance: WARDEN-WP-0004 (repo hygiene); follow-ups tracked separately
+  for OpenBao doc alignment and capability registry publish
 
 ---
 
@@ -129,4 +132,4 @@ keywords: [ssh, certificate, ca, credential, warden, ops-warden, pki, vault]
 - Config files: `~/.config/warden/warden.yaml`, `~/.config/warden/inventory.yaml`
 - State: `~/.local/state/warden/` (certs, generated keypairs)
 - Entry point: `warden --help`
-- Workplan: `workplans/WARDEN-WP-0001-initial-implementation.md`
+- Workplans: `workplans/` (active); `workplans/archived/` (finished)

workplans/WARDEN-WP-0004-repo-hygiene-and-hub-sync.md

@@ -0,0 +1,93 @@
+---
+id: WARDEN-WP-0004
+type: workplan
+title: "OpsWarden Repo Hygiene and Hub Sync"
+domain: custodian
+repo: ops-warden
+status: finished
+owner: codex
+topic_slug: custodian
+created: "2026-06-17"
+updated: "2026-06-17"
+state_hub_workstream_id: "3c4b6e68-550a-4fc6-a804-95f1f68936c3"
+---
+
+# WARDEN-WP-0004 — Repo Hygiene and Hub Sync
+
+**Scope:** Bring repo orientation docs and agent rules in line with the shipped
+`warden` CLI (WARDEN-WP-0001 through 0003 complete). Archive finished workplans
+and sync State Hub.
+
+**Out of scope:** OpenBao doc alignment (WARDEN-WP-0005), capability registry
+publish, task-status canon migration in AGENTS.md.
+
+---
+
+## Goal
+
+After this workplan, a new agent session can orient from accurate local files
+without reading stale "planned / scaffolding only" language, and State Hub
+reflects archived workplan status.
+
+---
+
+## Tasks
+
+### T1 — Update orientation docs
+
+```task
+id: WARDEN-WP-0004-T01
+status: done
+priority: high
+state_hub_task_id: "f9d3926c-8637-411c-a477-2960b754704c"
+```
+
+- [x] `SCOPE.md` Current State reflects shipped CLI (v0.1.0, workplans 0001–0003 done)
+- [x] `README.md` replaces repo-seed template with install, config, and dev commands
+
+### T2 — Fill agent rules
+
+```task
+id: WARDEN-WP-0004-T02
+status: done
+priority: medium
+state_hub_task_id: "86c764a5-62fc-45fe-a8d2-332d6554a976"
+```
+
+- [x] `.claude/rules/stack-and-commands.md` — stack and `uv` dev commands
+- [x] `.claude/rules/architecture.md` — module layout and data flow
+- [x] `.claude/rules/repo-boundary.md` — adjacent repo ownership
+
+### T3 — Archive finished workplans
+
+```task
+id: WARDEN-WP-0004-T03
+status: done
+priority: medium
+state_hub_task_id: "d3e54e63-ce98-4632-bc08-0e2667f19f12"
+```
+
+- [x] Move WARDEN-WP-0001/0002/0003 to `workplans/archived/` with date prefix
+- [x] Set frontmatter `status: archived` on moved files
+
+### T4 — Sync State Hub
+
+```task
+id: WARDEN-WP-0004-T04
+status: done
+priority: medium
+state_hub_task_id: "51729695-262f-4fe4-9c38-f99ee046d32a"
+```
+
+- [x] Run `make fix-consistency REPO=ops-warden` from state-hub
+- [x] Verify `.custodian-brief.md` reflects archived workstreams
+
+---
+
+## Acceptance Criteria
+
+- [x] `SCOPE.md` no longer says "planned" or "scaffolding only"
+- [x] `README.md` documents `uv sync`, `uv run pytest`, and `warden --help`
+- [x] Agent rules have no empty TODO blocks for stack, architecture, or boundary
+- [x] Only WARDEN-WP-0004 remains in `workplans/` root (archived plans moved)
+- [x] `make fix-consistency REPO=ops-warden` completes without error

workplans/archived/260515-WARDEN-WP-0001-initial-implementation.md

@@ -4,7 +4,7 @@ type: workplan
 title: "OpsWarden Initial Implementation"
 domain: custodian
 repo: ops-warden
-status: done
+status: archived
 owner: Bernd
 topic_slug: custodian
 created: "2026-03-28"

workplans/archived/260515-WARDEN-WP-0002-correctness-and-completeness.md

@@ -4,7 +4,7 @@ type: workplan
 title: "OpsWarden Correctness and Operational Completeness"
 domain: custodian
 repo: ops-warden
-status: done
+status: archived
 owner: Bernd
 topic_slug: custodian
 planning_priority: high

workplans/archived/260515-WARDEN-WP-0003-test-coverage-and-quality.md

@@ -4,7 +4,7 @@ type: workplan
 title: "OpsWarden Test Coverage and Code Quality"
 domain: custodian
 repo: ops-warden
-status: done
+status: archived
 owner: Bernd
 topic_slug: custodian
 planning_priority: medium