Close FLUID-WP-0001: fill bootstrap files and document the toolchain
Some checks are pending
ci / build (push) Waiting to run
Some checks are pending
ci / build (push) Waiting to run
Replace the generated credential-routing placeholder and generic purpose text with repo facts, record the install/test/lint/build/run commands in AGENTS.md, and point T03 at the existing FLUID-WP-0002…0009 sequence instead of seeding a duplicate workplan. Assistant: grok Assistant-Session: 01a09dc6-3f0e-78f1-a884-c8b2daa3e2b6
This commit is contained in:
parent
f2330e68e0
commit
8516c6bb13
5 changed files with 159 additions and 17 deletions
97
AGENTS.md
97
AGENTS.md
|
|
@ -2,13 +2,19 @@
|
|||
|
||||
## Repo Identity
|
||||
|
||||
**Purpose:** Core framework for fluid interfaces to provide adaptive robust systems capability integration.
|
||||
**Purpose:** Reference implementation of FLUID — the deterministic data plane, observation plane, and evolution control plane through Blueprint Phase C — attached to any API out of process, through a wire contract.
|
||||
|
||||
**Domain:** infotech
|
||||
**Repo slug:** fluid-core
|
||||
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
|
||||
**Repo ID:** `0f681685-7bc0-41b9-97fb-50073ebf6cf4`
|
||||
**Topic:** helix-forge (`f39fa2a3-c491-414c-a91b-b4c5fcc6139c`)
|
||||
**Workplan prefix:** `FLUID-WP-`
|
||||
|
||||
Workplan files currently index in the hub under the custodian topic
|
||||
(`cee7bedf-2b48-46ef-8601-006474f2ad7a`), not the repo topic. Query by
|
||||
`repo_id` (or `ls workplans/`) rather than by helix-forge, or this repo's
|
||||
workplans will not show up.
|
||||
|
||||
---
|
||||
|
||||
## State Hub Integration
|
||||
|
|
@ -43,8 +49,8 @@ with `make -C ~/state-hub configure-codex WITH_MCP=1`.
|
|||
# Offline brief — works without hub connection
|
||||
cat .custodian-brief.md
|
||||
|
||||
# Active workplans for this domain
|
||||
curl -s "http://127.0.0.1:8000/workplans/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \
|
||||
# Active workplans for this repo (not the helix-forge topic)
|
||||
curl -s "http://127.0.0.1:8000/workplans/?repo_id=0f681685-7bc0-41b9-97fb-50073ebf6cf4&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
# Check inbox
|
||||
|
|
@ -123,7 +129,56 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
|||
|
||||
---
|
||||
|
||||
{CREDENTIAL_ROUTING}
|
||||
## Credential and access routing
|
||||
|
||||
**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 "<describe your need>" --json
|
||||
warden route show <catalog-id> --json
|
||||
```
|
||||
|
||||
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=fluid-core` 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`
|
||||
|
||||
<!-- REPO-AGENTS-EXTENSIONS -->
|
||||
<!-- Append repo-specific agent instructions below this marker.
|
||||
|
|
@ -203,3 +258,35 @@ To create a new workplan:
|
|||
1. Write the file following the format above
|
||||
2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`.
|
||||
3. Run `statehub fix-consistency` only when a separate deep audit is needed.
|
||||
|
||||
---
|
||||
|
||||
## Local developer workflow
|
||||
|
||||
Go 1.22 (`go.mod`) and Python 3.12 with `jsonschema` and `pyyaml` (schema
|
||||
fixture validation only). There is no `golangci-lint` config; lint is `go vet`
|
||||
plus `gofmt` on generated types. This repo has no `CLAUDE.md` or
|
||||
`.claude/rules/stack-and-commands.md` — commands live here.
|
||||
|
||||
| Step | Command |
|
||||
| --- | --- |
|
||||
| Install | `go mod download` · `python3 -m pip install jsonschema pyyaml` |
|
||||
| Generate | `make generate` — regenerates `internal/contract` from `schemas/`. Never edit `*_gen.go` by hand. |
|
||||
| Validate | `make validate` — fixtures in `conformance/fixtures/` against `schemas/` |
|
||||
| Build | `make build` (`go build ./...`) |
|
||||
| Vet | `make vet` (`go vet ./...`) |
|
||||
| Test | `make test` — runs `validate` first, then `go test ./...` |
|
||||
| Conformance | `make conformance` — `go test -count=1 ./conformance/...` (no test cache) |
|
||||
| Generated stale? | `make check-generated` |
|
||||
| Full local CI | `make all` then `make conformance` (matches `.github/workflows/ci.yml`) |
|
||||
| Operator CLI | `go run ./cmd/fluid --help` |
|
||||
| Control plane | `go run ./cmd/fluid-control --interface <id> --ephemeral-key` (default `127.0.0.1:8081`) |
|
||||
|
||||
The gateway is a library (`internal/runtime.Gateway`); `cmd/fluid-gateway` is
|
||||
an empty reserved directory, not a binary. The echo fixture under
|
||||
`examples/echo-interface` is an `http.Handler` used by the conformance suite,
|
||||
not a standalone process.
|
||||
|
||||
After a schema change: `make generate` and commit `internal/contract`. After
|
||||
any code change: `make all && make conformance`. After workplan file changes:
|
||||
`statehub fix-consistency`.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
project: fluid-core
|
||||
product: FLUID
|
||||
status: draft
|
||||
status: active
|
||||
intent_version: 0.1.0
|
||||
date: 2026-09-04
|
||||
date: 2026-09-14
|
||||
standard: FluidAPIStandards
|
||||
standard_version: 0.1.0
|
||||
---
|
||||
|
|
|
|||
16
README.md
16
README.md
|
|
@ -1,3 +1,17 @@
|
|||
# fluid-core
|
||||
|
||||
Core framework for fluid interfaces to provide adaptive robust systems capability integration.
|
||||
The reference implementation of FLUID: the deterministic data plane, the
|
||||
observation plane, and the evolution control plane through Blueprint Phase C —
|
||||
attached to any API out of process, through a wire contract.
|
||||
|
||||
- Why it exists, and the invariants it defends: `INTENT.md`
|
||||
- What belongs here: `SCOPE.md`
|
||||
- Attaching an API: `docs/integration-guide.md`
|
||||
- Agent instructions and commands: `AGENTS.md`
|
||||
|
||||
```bash
|
||||
make all # generate, build, vet, test (includes schema validation)
|
||||
make conformance # architectural invariants, no test cache
|
||||
```
|
||||
|
||||
Requires Go 1.22 and Python 3.12 with `jsonschema` and `pyyaml`.
|
||||
|
|
|
|||
10
SCOPE.md
10
SCOPE.md
|
|
@ -23,8 +23,8 @@ no library, and may be written in any stack.
|
|||
|
||||
**The deterministic data plane** — gateway, revision resolver, revision router,
|
||||
contract validation, backend connectors, response policy, telemetry emission.
|
||||
`cmd/fluid-gateway`, `internal/runtime`, `internal/contract`, `internal/validate`,
|
||||
`internal/policy`.
|
||||
`internal/runtime` (the gateway is a library; `cmd/fluid-gateway` is reserved
|
||||
and empty), `internal/contract`, `internal/validate`, `internal/policy`.
|
||||
|
||||
**The observation plane** — telemetry ingest, redaction, cohorts, interaction
|
||||
topology, pressure classification. `internal/observation`.
|
||||
|
|
@ -103,8 +103,10 @@ second interface goes from empty capability canon to a published R-1
|
|||
(`FLUID-WP-0009` T05), claims of generality are untested. That test is the point
|
||||
of the workplan, and its findings are expected to be uncomfortable.
|
||||
|
||||
Registered with the Custodian State Hub: domain `infotech`, topic `helix-forge`,
|
||||
workplan prefix `FLUID-WP-`.
|
||||
Registered with the Custodian State Hub: domain `infotech`, repo topic
|
||||
`helix-forge`, workplan prefix `FLUID-WP-`. Workplan records currently index
|
||||
under the custodian topic; query by repo (`0f681685-7bc0-41b9-97fb-50073ebf6cf4`)
|
||||
rather than by helix-forge.
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
|
|
|
|||
|
|
@ -4,11 +4,15 @@ type: workplan
|
|||
title: "Bootstrap State Hub integration"
|
||||
domain: infotech
|
||||
repo: fluid-core
|
||||
status: ready
|
||||
status: finished
|
||||
owner: worsch
|
||||
topic_slug: fluid-core
|
||||
created: "2026-09-04"
|
||||
updated: "2026-09-04"
|
||||
updated: "2026-09-14"
|
||||
related:
|
||||
- FLUID-WP-0002
|
||||
- FLUID-WP-0008
|
||||
- FLUID-WP-0009
|
||||
state_hub_workstream_id: "b5c231e1-9d06-5772-95a7-01cc0bf62051"
|
||||
---
|
||||
|
||||
|
|
@ -16,11 +20,19 @@ state_hub_workstream_id: "b5c231e1-9d06-5772-95a7-01cc0bf62051"
|
|||
|
||||
Core framework for fluid interfaces to provide adaptive robust systems capability integration.
|
||||
|
||||
**Outcome:** generated integration files reviewed against the implemented repo;
|
||||
developer commands documented in `AGENTS.md`; first implementation work already
|
||||
exists as `FLUID-WP-0002` … `FLUID-WP-0009` (no duplicate seeded).
|
||||
|
||||
**Residuals:** none open from this bootstrap. Live follow-on work is
|
||||
`FLUID-WP-0008` (Telegram handover; remaining tasks are human-blocked) and
|
||||
`FLUID-WP-0009` (campaign-repo pattern and a second interface).
|
||||
|
||||
## Review Generated Integration Files
|
||||
|
||||
```task
|
||||
id: FLUID-WP-0001-T01
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "f106ac45-c90b-5115-a0de-e986839b19f9"
|
||||
```
|
||||
|
|
@ -28,11 +40,24 @@ state_hub_task_id: "f106ac45-c90b-5115-a0de-e986839b19f9"
|
|||
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
|
||||
Replace generated placeholders with repo-specific facts where needed.
|
||||
|
||||
Done 2026-09-14:
|
||||
|
||||
- Replaced the unresolved `{CREDENTIAL_ROUTING}` token in `AGENTS.md` with the
|
||||
fleet credential-routing section (`to_agent=fluid-core`).
|
||||
- Replaced the generated repo-description purpose in `AGENTS.md` and `README.md`
|
||||
with the SCOPE one-liner.
|
||||
- Recorded that the repo topic is helix-forge but workplans currently index
|
||||
under the custodian topic; session-start query is now by `repo_id`.
|
||||
- Set `INTENT.md` `status: active` (was `draft`).
|
||||
- Noted in `SCOPE.md` that the gateway is a library in `internal/runtime` and
|
||||
`cmd/fluid-gateway` is reserved and empty.
|
||||
- `.custodian-brief.md` is generated by `fix-consistency` — not edited by hand.
|
||||
|
||||
## Verify Local Developer Workflow
|
||||
|
||||
```task
|
||||
id: FLUID-WP-0001-T02
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "1e3f26fe-4a1a-5f96-8dd6-962dd844402e"
|
||||
```
|
||||
|
|
@ -41,11 +66,17 @@ Identify the repo's install, test, lint, build, and run commands. Add or refine
|
|||
those commands in the agent instructions so future coding sessions can verify
|
||||
changes confidently.
|
||||
|
||||
Done 2026-09-14. This repo has no `CLAUDE.md` / `stack-and-commands.md`; the
|
||||
commands are in `AGENTS.md` (Local developer workflow) and mirrored in
|
||||
`README.md`. Verified locally: `make validate`, `make vet`, `make build`,
|
||||
`make test`, `make conformance`, and `go run ./cmd/fluid --help`. Full check
|
||||
is `make all && make conformance`, matching `.github/workflows/ci.yml`.
|
||||
|
||||
## Seed First Real Workplan
|
||||
|
||||
```task
|
||||
id: FLUID-WP-0001-T03
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "2428db4a-c6ad-547d-acf3-9163ea17ae20"
|
||||
```
|
||||
|
|
@ -57,3 +88,11 @@ checkout:
|
|||
```bash
|
||||
statehub fix-consistency
|
||||
```
|
||||
|
||||
Done 2026-09-14 by pointing at existing work, not creating a duplicate.
|
||||
|
||||
The first implementation workplan is `FLUID-WP-0002` (foundations and the wire
|
||||
contract), already `status: done`. The sequence through conformance is
|
||||
`FLUID-WP-0003` … `FLUID-WP-0007` (all done). The live next work is
|
||||
`FLUID-WP-0008` (Telegram handover) and `FLUID-WP-0009` (campaign repos and a
|
||||
second interface).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue