diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md index b534f31..3bc4c40 100644 --- 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=adaptive-pricing` 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 diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index a94c809..177e2d1 100644 --- 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/ADAPTIVE-WP-NNNN-.md ← write this first +workplans/ADAPTIVE-WP-NNNN-.md ← write this, commit it ``` -Then register in the hub: -``` -create_workstream(topic_id="f39fa2a3-c491-414c-a91b-b4c5fcc6139c", title="...", owner="...", description="...") -create_task(workstream_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 adaptive-pricing ``` +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 financials into N workstreams, M tasks", + summary="First session: structured financials into N workplans, M tasks", event_type="milestone", topic_id="f39fa2a3-c491-414c-a91b-b4c5fcc6139c", - detail={"workstreams": [...], "tasks_created": M} + detail={"workplans": [...], "tasks_created": M} ) ``` diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 09483dc..34f4f63 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -2,9 +2,4 @@ **Domain:** financials **Repo slug:** adaptive-pricing -**State Hub topic:** helix-forge **Topic ID:** f39fa2a3-c491-414c-a91b-b4c5fcc6139c - -Repo classification and hub topic are intentionally separate here: -- Repo/business domain: `financials` -- Shared hub topic: `helix-forge` in the hub's `infotech` domain diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 182d158..d39f52d 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -13,8 +13,6 @@ Then call the MCP tool for richer cross-domain context when MCP tools are expose ``` get_domain_summary("financials") ``` -Repo-specific work tracking still syncs through topic -`f39fa2a3-c491-414c-a91b-b4c5fcc6139c` (`helix-forge`). If MCP tools are unavailable in the current agent session, use the REST API: ```bash curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool @@ -46,7 +44,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending **Step 4 — Present brief** -1. **Repo-relevant workstreams** under topic `helix-forge` — title, task counts, blocking decisions +1. **Active workplans** for `financials` — title, task counts, blocking decisions 2. **Pending tasks** from `workplans/` + any `[repo:adaptive-pricing]` hub tasks 3. **Goal guidance** — if `goal_guidance` in summary: - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* @@ -54,37 +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="f39fa2a3-c491-414c-a91b-b4c5fcc6139c", workstream_id="") +add_progress_event(summary="...", topic_id="f39fa2a3-c491-414c-a91b-b4c5fcc6139c", workplan_id="") ``` Without MCP tools: ```bash curl -s -X POST http://127.0.0.1:8000/progress/ \ -H "Content-Type: application/json" \ - -d '{"topic_id":"f39fa2a3-c491-414c-a91b-b4c5fcc6139c","workstream_id":"","event_type":"note","summary":"what changed","author":"codex"}' + -d '{"topic_id":"f39fa2a3-c491-414c-a91b-b4c5fcc6139c","workplan_id":"","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 pull --ff-only +git pull --ff-only statehub fix-consistency ``` -Fallback when the CLI is unavailable: +For repos where implementation runs on a remote machine (e.g. CoulombCore), +use the pull-before-fix mode from any shell with the State Hub CLI: ```bash -/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \ - fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing -``` -Legacy wrapper: -```bash -cd ~/state-hub && make fix-consistency REPO=adaptive-pricing +statehub fix-consistency --repo adaptive-pricing --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 diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index 7a35a1d..3cb5cad 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -5,7 +5,7 @@ ID prefix: `ADAPTIVE-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-ADAPTIVE-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**: -`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:adaptive-pricing]` 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: "" # 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. + diff --git a/AGENTS.md b/AGENTS.md index 0527490..7e350ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,17 +4,11 @@ **Purpose:** Auto-regulating market value exploring price engine. -**Primary repo domain:** financials +**Domain:** financials **Repo slug:** adaptive-pricing -**State Hub topic:** `helix-forge` **Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c` **Workplan prefix:** `ADAPTIVE-WP-` -`adaptive-pricing` is classified as a `financials` repo in -`.repo-classification.yaml`, but State Hub coordination currently runs through -the shared `helix-forge` topic in the hub's `infotech` domain. Keep repo-domain -fields (`domain`) and hub-topic fields (`topic_slug`, `topic_id`) distinct. - --- ## State Hub Integration @@ -26,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 @@ -33,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 repo's hub topic -curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \ +# Active workplans for this domain +curl -s "http://127.0.0.1:8000/workplans/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \ | python3 -m json.tool # Check inbox @@ -57,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": "", + "workplan_id": "", "task_id": "" }' ``` -Omit `workstream_id` / `task_id` when not applicable. +Omit `workplan_id` / `task_id` when not applicable. ### Update task status @@ -86,7 +86,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ ## Session Protocol **Start:** -1. `cat .custodian-brief.md` — hub-topic 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=adaptive-pricing&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` @@ -102,18 +102,8 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ ```bash statehub fix-consistency ``` - Fallback when the CLI is unavailable: - ```bash - /home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \ - fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing - ``` - Legacy wrapper: - ```bash - cd ~/state-hub - make fix-consistency REPO=adaptive-pricing - ``` - Coding agents should run the direct CLI when available. 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. --- @@ -139,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=adaptive-pricing` 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