Regenerate agent instructions from state-hub templates (CUST-WP-0055 T01)

Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules templates: workplan-first session protocol, legacy terminology footnote, and GET /workplans/ examples.
2026-07-08 14:50:32 +02:00 · 2026-07-08 14:50:32 +02:00 · 07b564309e
commit 07b564309e
parent 7906a731fc
5 changed files with 81 additions and 70 deletions
--- a/.claude/rules/credential-routing.md
+++ b/.claude/rules/credential-routing.md
@ -4,62 +4,41 @@
 for inference. Run this check **before** requesting secrets, API keys, SSH access,
 login tokens, or database passwords — in any repo, not only `ops-warden`.

-ops-warden **issues SSH certificates** (`warden sign`, `cert_command`) **and is the
-operator access front door** for every other credential need. For `exec_capable` lanes
-(OpenBao reads, key-cape login) `warden access <need> --fetch/--exec` **proxies the fetch
-as you** — it runs the owner's tool with your identity and streams the value to you;
-ops-warden holds, caches, and logs nothing. For non-exec lanes it points you at the owner.
-
-**Do not** `POST /messages/` to `ops-warden` expecting a secret *value* — a State Hub
-reply is always a pointer. The **value comes from the CLI front door** (`warden access`),
-run with **your** identity, never from the inbox.
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.

 ### Lookup (do this first)

 ```bash
-warden route find "<describe your need>" --json     # who owns it (pointer)
-warden access "<describe your need>" --json          # how to get it (handoff)
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
 ```

-`warden access` is the operator front door (WARDEN-WP-0014): it renders the owner,
-auth method, path template, command skeleton, and policy-gate status for any need.
-For `exec_capable` lanes it can **proxy the fetch as you** (`--fetch`/`--exec`) — it
-runs the owner's tool with **your** identity and streams the value to you; ops-warden
-never holds, caches, or logs the value. See `wiki/OperatorAccessAssist.md`.
-
 Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).

 | Agent runtime | How to orient |
 | --- | --- |
 | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=ops-warden` is for coordination, not secret vending |
-| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
 | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |

 ### Quick routing table

-| I need… | Owner | ops-warden role |
+| I need… | Owner | ops-warden executes? |
 | --- | --- | --- |
-| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Issue** — `warden sign` |
-| Provisioned secret-exec lane (e.g. npm publish) | **secrets-engine** | **Route** — primary is `secrets-engine exec --catalog <id> -- <cmd>`; `warden access <id> --exec` is the transparent fallback |
-| Generic API key / DB password / provider token | OpenBao (`railiance-platform`) | **Assist** — `warden access <need> --fetch/--exec` proxies as you; OpenBao keeps custody |
-| Login / OIDC / MFA | key-cape / Keycloak | **Assist** — `warden access <need> --fetch` runs the login as you |
-| Authorization decision | flex-auth | Route only |
-| activity-core → issue-core emission | activity-core + issue-core | Route — `warden route show activity-core-issue-sink` |
-| SSH tunnel | ops-bridge (+ `cert_command` from warden) | Route only |
-
-For an owned lane, `warden route find <need> --json` / `warden access <id>` surface
-`exec_owner`, the `secrets-engine exec` command, and the `resolvable` flag. Run the
-secrets-engine command; ops-warden routes to it and requests/holds no token.
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |

 ### Anti-patterns (do not do these)

 - `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
 - Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
 - Pasting secrets into Git, State Hub, workplans, logs, or chat
- Treating `warden access --fetch` as a *secret store*. It is a transparent conduit
-  using **your** identity — it holds nothing. ops-warden as a **standing broker**
-  (its own secret-read token, a cache of fetched values) is forbidden; runtime secret
-  custody stays in OpenBao, authorization in flex-auth.

 ### Other capabilities (reuse-surface)

--- a/.claude/rules/first-session.md
+++ b/.claude/rules/first-session.md
@ -1,6 +1,6 @@
 ## First Session Protocol

-Triggered when `get_domain_summary("infotech")` shows **no workstreams**.
+Triggered when `get_domain_summary("infotech")` shows **no workplans**.
 The project is registered but work has not yet been structured.

 **Step 1 — Read, don't write**
@ -11,27 +11,31 @@ The project is registered but work has not yet been structured.
 **Step 2 — Survey in-progress work**
 Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.

-**Step 3 — Propose workstreams to Bernd**
-Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
+**Step 3 — Propose workplans to Bernd**
+Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
 roadmap phase. **Wait for approval before creating.**

-**Step 4 — Create workplan file first, then DB record (ADR-001)**
+**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
 ```
-workplans/WARDEN-WP-NNNN-<slug>.md   ← write this first
+workplans/WARDEN-WP-NNNN-<slug>.md   ← write this, commit it
 ```
-Then register in the hub:
-```
-create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
-create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+Then register by running the consistency check — do **not** call
+`create_workplan`/`create_task` yourself; manual registration duplicates what
+C-06 creates from the file:
+```bash
+statehub fix-consistency --repo ops-warden
 ```
+C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
+(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
+back into the file.

 **Step 5 — Record the setup**
 ```
 add_progress_event(
-    summary="First session: structured infotech into N workstreams, M tasks",
+    summary="First session: structured infotech into N workplans, M tasks",
    event_type="milestone",
    topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
-    detail={"workstreams": [...], "tasks_created": M}
+    detail={"workplans": [...], "tasks_created": M}
 )
 ```

--- a/.claude/rules/session-protocol.md
+++ b/.claude/rules/session-protocol.md
@ -44,7 +44,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending

 **Step 4 — Present brief**

-1. **Active workstreams** for `infotech` — title, task counts, blocking decisions
+1. **Active workplans** 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"*
@ -52,33 +52,40 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
 4. **Suggested next action** — highest-priority open item
 5. **SBOM status** — flag if `last_sbom_at` is unset for this repo

-If no workstreams: follow First Session Protocol (`first-session.md`).
+If no workplans: follow First Session Protocol (`first-session.md`).

 **During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`

-> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
-> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
+> State Hub is a *read model*. **Never register workplans or tasks by hand**
+> (`create_workplan`, `create_task`) — write the workplan file in `workplans/`
+> and run `fix-consistency`; C-06 registers the workplan and tasks and writes
+> IDs back into the file. Manual registration creates duplicates when
+> fix-consistency runs. Work structure belongs in repo files (ADR-001).
+>
+> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
+> see `workplan-convention.md` (compatibility footnote).

 **Session close:**
 With MCP tools:
 ```
-add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
+add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workplan_id="<uuid>")
 ```
 Without MCP tools:
 ```bash
 curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
-  -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
+  -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workplan_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
 ```
-If workplan files were modified, ensure the local copy is up to date first:
+If workplan files were modified, ensure the local copy is up to date first,
+then sync from the repo checkout:
 ```bash
-git -C <repo_path> pull --ff-only
-cd ~/state-hub && make fix-consistency REPO=ops-warden
+git pull --ff-only
+statehub fix-consistency
 ```
 For repos where implementation runs on a remote machine (e.g. CoulombCore),
-use the combined target which pulls before fixing:
+use the pull-before-fix mode from any shell with the State Hub CLI:
 ```bash
-cd ~/state-hub && make fix-consistency-remote REPO=ops-warden
+statehub fix-consistency --repo ops-warden --remote
 ```
 **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
 will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes
--- a/.claude/rules/workplan-convention.md
+++ b/.claude/rules/workplan-convention.md
@ -5,7 +5,7 @@ ID prefix: `WARDEN-WP-`

 Work items originate as files in this repo **before** being registered in the hub.

-Canonical workplan/workstream frontmatter statuses are:
+Canonical workplan frontmatter statuses are:
 `proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
 Use `proposed` for a newly drafted plan, `ready` after review against current
 repo state, and `finished` when implementation is complete. `stalled` and
@ -16,14 +16,15 @@ 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**:
-`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
+`workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids
 `ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
 directly. Promote anything requiring analysis, design, approval, dependencies, or
 multiple planned phases into a normal workplan.

 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.
+visible at session start. Pick one up by creating the workplan file, committing,
+and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
+Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).

 Task blocks use this shape:

@ -37,4 +38,18 @@ state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
 Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
 blocked work and `cancel` for stopped work.

+Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
+kept for compatibility; it holds the hub workplan UUID and is written by
+fix-consistency. Do not edit or rename it.
+
+### Legacy terminology (compatibility footnote)
+
+**Workplan** is the fleet term — see
+`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
+**Workstream** is legacy only: some API routes (`/workstreams/`), params
+(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
+above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
+identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
+examples and scripts.
+
 <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
--- a/AGENTS.md
+++ b/AGENTS.md
@ -20,6 +20,12 @@ there is no MCP server for Codex agents.
 |---------|-----|
 | 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.

 ### Orient at session start

@ -27,8 +33,8 @@ there is no MCP server for Codex agents.
 # Offline brief — works without hub connection
 cat .custodian-brief.md

-# Active workstreams for this domain
-curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
+# Active workplans for this domain
+curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
  | python3 -m json.tool

 # Check inbox
@ -51,12 +57,12 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
    "summary": "what was done",
    "event_type": "note",
    "author": "codex",
-    "workstream_id": "<uuid>",
+    "workplan_id": "<uuid>",
    "task_id": "<uuid>"
  }'
 ```

-Omit `workstream_id` / `task_id` when not applicable.
+Omit `workplan_id` / `task_id` when not applicable.

 ### Update task status

@ -80,7 +86,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 ## Session Protocol

 **Start:**
-1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
+1. `cat .custodian-brief.md` — domain goal and open workplans (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 human-needed tasks: `GET /tasks/?needs_human=true`
@ -92,12 +98,12 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 **Close:**
 1. Update workplan file task statuses to reflect progress
 2. Log: `POST /progress/` with a summary of what changed
-3. Note for the custodian operator: after workplan file changes, run from
-   `~/state-hub`:
+3. After workplan file changes, run:
   ```bash
-   make fix-consistency REPO=ops-warden
+   statehub fix-consistency
   ```
-   This syncs task status from files into the hub DB.
+   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.

 ---

@ -123,7 +129,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
 | Agent runtime | How to orient |
 | --- | --- |
 | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=ops-warden` is for coordination, not secret vending |
-| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
 | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |

 ### Quick routing table