diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md index e50f4c8..f3df4c5 100644 --- a/.claude/rules/credential-routing.md +++ b/.claude/rules/credential-routing.md @@ -19,8 +19,8 @@ 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=repo-seed` is for coordination, not secret vending | -| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=core-hub` is for coordination, not secret vending | +| **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 1528363..212653f 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -1,26 +1,42 @@ ## First Session Protocol -Triggered when State Hub shows no workstreams for `core-hub`. +Triggered when `get_domain_summary("infotech")` shows **no workplans**. +The project is registered but work has not yet been structured. -**Step 1 - Read, do not write yet** -- `INTENT.md` -- `SCOPE.md` -- `docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md` -- `docs/specs/README.md` -- Existing files under `workplans/` +**Step 1 — Read, don't write** +- `~/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** -Look for untracked files, open workplans, and half-finished specs. Note done vs. started but incomplete. +**Step 2 — Survey in-progress work** +Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. -**Step 3 - Structure work in files first** -Create or update `workplans/CORE-WP-NNNN-.md` before relying on State Hub records. - -**Step 4 - Sync the read model** -After workplan changes, run from `~/state-hub`: +**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 — Write the workplan file; fix-consistency registers it (ADR-001)** +``` +workplans/CORE-WP-NNNN-.md ← write this, commit it +``` +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 -make fix-consistency REPO=core-hub +statehub fix-consistency --repo core-hub +``` +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 workplans, M tasks", + event_type="milestone", + topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", + detail={"workplans": [...], "tasks_created": M} +) ``` -**Step 5 - Record progress** -Post a non-secret progress note to State Hub summarizing the setup or implementation work. + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index eef78f4..44d751f 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -1,6 +1,6 @@ ## Repo boundary -This repo owns **Repo Seed** only. It does not own: +This repo owns **core-hub** only. It does not own: diff --git a/AGENTS.md b/AGENTS.md index c0a2e06..443572c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ -# Core Hub - Agent Instructions +# core-hub — Agent Instructions ## Repo Identity -**Purpose:** 3rd-generation production interaction framework for Coulomb / Helixforge. Reimagines and replaces the 2nd-generation Inter-Hub framework goals on a practical contract-first Python/FastAPI/Postgres platform. +**Purpose:** Core Hub is the 3rd-generation production interaction and coordination framework for Coulomb / Helixforge, intended to supersede the 1st-generation state-hub and 2nd-generation inter-hub infrastructure. **Domain:** infotech **Repo slug:** core-hub @@ -13,29 +13,42 @@ ## State Hub Integration -The Custodian State Hub tracks work across all domains. Interact via HTTP REST - there is no MCP server for Codex agents. +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. | Context | URL | |---------|-----| | 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 ```bash +# Offline brief — works without hub connection cat .custodian-brief.md -curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" | python3 -m json.tool -curl -s "http://127.0.0.1:8000/messages/?to_agent=core-hub&unread_only=true" | python3 -m json.tool + +# 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 +curl -s "http://127.0.0.1:8000/messages/?to_agent=core-hub&unread_only=true" \ + | python3 -m json.tool ``` Mark a message read: - ```bash curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ -H "Content-Type: application/json" -d '{}' ``` -### Log progress at session close +### Log progress (required at session close) ```bash curl -s -X POST http://127.0.0.1:8000/progress/ \ @@ -44,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 @@ -57,54 +70,115 @@ 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"}' +# values: wait | todo | progress | done | cancel ``` -Status values: `wait | todo | progress | done | cancel`. +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` --- ## Session Protocol **Start:** -1. `cat .custodian-brief.md` - domain goal and open workstreams. -2. Check inbox: `GET /messages/?to_agent=core-hub&unread_only=true`; mark read when acted on. -3. Scan workplans: `ls workplans/` and inspect `ready`, `active`, or `blocked` files. -4. Check human-needed tasks: `GET /tasks/?needs_human=true` when the work may touch operational gates. +1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) +2. Check inbox: `GET /messages/?to_agent=core-hub&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` **During work:** -- Update workplan files first; State Hub is the read/cache/index layer. -- Record significant decisions via `POST /decisions/` when available. -- Keep secrets out of Git, State Hub, workplans, logs, and chat. +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` **Close:** -1. Update workplan statuses. -2. From `~/state-hub`, run `make fix-consistency REPO=core-hub` after workplan changes. -3. Log progress with `POST /progress/`. +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. After workplan file changes, run: + ```bash + statehub fix-consistency + ``` + 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. --- -## Credential and Access Routing +## Credential and access routing -Before requesting secrets, API keys, SSH access, login tokens, or database passwords, route the need through ops-warden/OpenBao/key-cape ownership. +**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** +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 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 "" --json warden route show --json ``` -ops-warden issues SSH certificates only. API keys, DB passwords, provider tokens, login/OIDC/MFA, authorization decisions, and OpenBao leases belong to their owning subsystems. Do not paste secrets into Git, State Hub, workplans, logs, or chat. +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=core-hub` is for coordination, not secret vending | +| **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 executes? | +| --- | --- | --- | +| 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 + +### Other capabilities (reuse-surface) + +Non-credential capabilities are usually discovered through **reuse-surface** federation +(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in +every repo's agent instructions because it is high-frequency, high-risk, and easy to +get wrong. + +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` + + + --- ## Workplan Convention (ADR-001) -Work items originate as files in this repo, not in the hub. The hub rebuilds from files. +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. **File location:** `workplans/CORE-WP-NNNN-.md` -**Archived location:** finished workplans may move to `workplans/archived/YYMMDD-CORE-WP-NNNN-.md`. The `YYMMDD` prefix is the completion/archive date; the frontmatter `id` does not change. +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-CORE-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. -**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use `workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use this only for low-risk work completed directly. +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. **Frontmatter:** @@ -117,26 +191,39 @@ domain: infotech repo: core-hub status: proposed | ready | active | blocked | backlog | finished | archived owner: codex -topic_slug: custodian +topic_slug: ... created: "YYYY-MM-DD" updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # written by fix-consistency - do not edit +state_hub_workstream_id: "" # fix-consistency — do not edit (legacy field name; workplan UUID) --- ``` -Task block format: +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. -````markdown +**Terminology:** workplan is the fleet term; `workstream` appears only in legacy +API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see +`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. + +**Task block format** (one per `##` section): + +``` ## Task Title -```task +` ` `task id: CORE-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. -```` +``` -Status progression: `todo` -> `progress` -> `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. +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 +2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or + State Hub API is unavailable. diff --git a/CLAUDE.md b/CLAUDE.md index 5da3ca4..746ab2f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# Core Hub - Claude Code Instructions +# core-hub — Claude Code Instructions @SCOPE.md @.claude/rules/repo-identity.md