diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index bb1748e..7c2a645 100644 --- 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 --pubkey - → 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 --pubkey -``` - -Writes signed certificate to stdout. Non-zero exit on failure. Documented in -`wiki/CertCommandInterface.md`. + ## Quick Reference -`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference \ No newline at end of file +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index 49ed8cb..af515f6 100644 --- 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-.md ← write this first +workplans/WARDEN-WP-NNNN-.md ← write this first ``` Then register in the hub: ``` @@ -28,7 +28,7 @@ create_task(workstream_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} diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index ff66c8d..aca5f69 100644 --- 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. \ No newline at end of file + diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 104df00..4fa0d32 100644 --- 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 diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index f74742b..7674470 100644 --- 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//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"* diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index a41d038..dc53ac6 100644 --- 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 + +- **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` \ No newline at end of file diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index eb48e85..065b4cc 100644 --- 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-.md` -ID prefix: `OPS-WP` +File location: `workplans/WARDEN-WP-NNNN-.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-.md`. The frontmatter id remains +prefix: `YYMMDD-WARDEN-WP-NNNN-.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: "" # written by fix-consistency — do not edit +state_hub_task_id: "" # 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. diff --git a/AGENTS.md b/AGENTS.md index 5988415..4ff0224 100644 --- 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/" \ -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/" \ 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` + + + + --- ## 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: "" # 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 diff --git a/workplans/WARDEN-WP-0009-flex-auth-policy-gate-production.md b/workplans/WARDEN-WP-0009-flex-auth-policy-gate-production.md index 8141f13..385fd07 100644 --- 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 diff --git a/workplans/WARDEN-WP-0010-access-routing-charter.md b/workplans/WARDEN-WP-0010-access-routing-charter.md index 22fceeb..d6cbbaf 100644 --- 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 diff --git a/workplans/WARDEN-WP-0011-routing-guide-cli.md b/workplans/WARDEN-WP-0011-routing-guide-cli.md index b31ef38..1d9c6b9 100644 --- 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 diff --git a/workplans/WARDEN-WP-0012-routing-scenario-playbooks.md b/workplans/WARDEN-WP-0012-routing-scenario-playbooks.md index 7a4b0a2..012bc9a 100644 --- 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