Regenerate agent instructions: workstream -> workplan terminology

Registration guidance now prescribes file-first + fix-consistency (C-06) instead of manual create_workplan/create_workstream calls; progress-event examples use workplan_id; legacy field names annotated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 01:47:45 +02:00
parent 5ac713641d
commit 84c005254d
5 changed files with 61 additions and 37 deletions
--- a/.claude/rules/credential-routing.md
+++ b/.claude/rules/credential-routing.md
@@ -20,7 +20,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=railiance-cluster` 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
--- a/.claude/rules/first-session.md
+++ b/.claude/rules/first-session.md
@@ -1,6 +1,6 @@
 ## First Session Protocol

-Triggered when `get_domain_summary("financials")` shows **no workstreams**.
+Triggered when `get_domain_summary("financials")` 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/RAIL-BS-WP-NNNN-<slug>.md   ← write this first
+workplans/RAIL-BS-WP-NNNN-<slug>.md   ← write this, commit it
 ```
-Then register in the hub:
-```
-create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", 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` (or legacy `create_workstream`) yourself;
+manual registration duplicates what C-06 creates from the file:
+```bash
+statehub fix-consistency --repo railiance-cluster
 ```
+C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` /
+`state_hub_task_id` back into the file (legacy field names, kept for
+compatibility — they hold workplan/task IDs).

 **Step 5 — Record the setup**
 ```
 add_progress_event(
-    summary="First session: structured financials into N workstreams, M tasks",
+    summary="First session: structured financials into N workplans, M tasks",
    event_type="milestone",
    topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38",
-    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 `financials` — title, task counts, blocking decisions
+1. **Active workplans** for `financials` — title, task counts, blocking decisions
 2. **Pending tasks** from `workplans/` + any `[repo:railiance-cluster]` 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,42 @@ 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`, or the legacy `create_workstream`) — write
+> the workplan file in `workplans/` and run `fix-consistency`; its C-06 check
+> registers the workplan and its tasks in the hub and writes the IDs back into
+> the file. Manual registration creates duplicates the moment fix-consistency
+> runs. Work structure belongs in repo files (ADR-001).
+>
+> Terminology: "workstream" is the legacy name for workplan. Some API/frontmatter
+> field names keep it for compatibility (`state_hub_workstream_id`,
+> `workstream_id` params) — treat them as workplan IDs.

 **Session close:**
 With MCP tools:
 ```
-add_progress_event(summary="...", topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", workstream_id="<uuid>")
+add_progress_event(summary="...", topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", 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":"ca369340-a64e-442e-98f1-a4fa7dc74a38","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
+  -d '{"topic_id":"ca369340-a64e-442e-98f1-a4fa7dc74a38","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=railiance-cluster
+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=railiance-cluster
+statehub fix-consistency --repo railiance-cluster --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: `RAIL-BS-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-RAIL-BS-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:railiance-cluster]` 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`/`create_workstream`.

 Task blocks use this shape:

@@ -37,4 +38,8 @@ 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 ("workstream" is the old term for workplan); it holds
+the hub workplan id and is written by fix-consistency. Do not edit or rename it.
+
 <!-- 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=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \
+# Active workplans for this domain
+curl -s "http://127.0.0.1:8000/workplans/?topic_id=ca369340-a64e-442e-98f1-a4fa7dc74a38&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=railiance-cluster&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=railiance-cluster
+   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=railiance-cluster` 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