From 700d6fc3261a6132101e0bc77af7372cb25d5d49 Mon Sep 17 00:00:00 2001 From: jenkins Date: Mon, 24 Aug 2026 00:12:49 -0300 Subject: [PATCH] docs(hux): start the hermes-next handoff ledger with HUX-11 --- docs/hux/HANDOFF.md | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/hux/HANDOFF.md diff --git a/docs/hux/HANDOFF.md b/docs/hux/HANDOFF.md new file mode 100644 index 00000000..7827b27a --- /dev/null +++ b/docs/hux/HANDOFF.md @@ -0,0 +1,48 @@ +# hermes-next: Claude backend handoff ledger + +Branch `feature/hermes-next-hux` (origin, pushed after every card). Board +`hermes-next` on the operator Hermes Kanban; cards HUX-01..HUX-12 are parked +(`blocked`) on purpose so the CLI lane runner never auto-claims them — the +Claude coordinator and the Codex root session are the only implementers. +Contract: `hux.v1` 1.0.0 (`services/hermes/contracts/hux/VERSION`, +`docs/hux/ADR-0001-hux-v1-contract-freeze.md`). Threat model: +`docs/hux/THREAT-MODEL.md` (SO-01..SO-54). Data model: `docs/hux/DATA-MODEL.md`. + +Run everything with the CI interpreter: +`python -m pytest testing/tests/test_hermes_hux_*.py -q` and +`python -m coverage run --branch --source=dockerfiles/hermes-hux-foundation -m pytest testing/tests/test_hermes_hux_*.py`. + +## Codex integration requirements common to every card + +- Package `dockerfiles/hermes-hux-foundation/hux/` runs as `python -m hux.server` + inside each `hermes-chat-tenant` pod (and the Worker) on `127.0.0.1:8790`. + Image, manifest, NetworkPolicy and Flux wiring are Codex's (SO-01, SO-02, + SO-45: separate uid, `/opt/data/hux` mode 0700). +- Env: `HUX_DATA_ROOT` (tenant PVC, default `/opt/data`), `HUX_TENANT_SLOT` + (pin, SO-03), `HUX_FLAGS` (comma list, default empty = everything off), + `HUX_RELAY_KEY` (Telegram relay), `HUX_WORKER_KEY` (Worker), + `HUX_BUILD_COMMIT`, `HUX_IMAGE_DIGEST`, `HUX_CONTRACT_DIR` (schemas path in + the image; default resolves relative to the repo layout). +- Router → service headers (SO-04): `X-Hermes-Tenant-Identity: slot-N`, + `X-Hux-Subject: usr_`, `X-Hux-Surface: chat|telegram|voice|api|worker`, + optional `X-Hux-Trust: relay|worker` + `X-Hux-Relay-Key`. The router must + strip any inbound `X-Hux-*` before setting its own. +- First client call: `GET /hux/v1/capabilities` → which cards/routes are on. + Disabled or unknown → `404` (`flag_off` vs `not_found` only in the body). +- Mutations: `If-Match: ` on revisioned records (409 on mismatch); + `Idempotency-Key` on creates. Errors are `hux.error.v1`. +- Fixtures Codex codes against: `services/hermes/contracts/hux/examples/*.json` + (validated in CI by `test_hermes_hux_contract_schemas.py`). + +## HUX-11 shared foundation — DONE (backend) + +| | | +|---|---| +| Commits | `47a9fd83` (contract freeze 1.0.0), `7cf9a714` (service core) | +| Files | `services/hermes/contracts/hux/{common,identity}.schema.json` + examples, `VERSION`; `dockerfiles/hermes-hux-foundation/hux/{__init__,errors,identity,flags,store,audit,http,foundation,server,contracts,rules}.py`; `docs/hux/ADR-0001-*.md`, `THREAT-MODEL.md`, `DATA-MODEL.md` | +| Tests | `testing/tests/test_hermes_hux_contract_schemas.py` (61), `test_hermes_hux_contract_foundation.py` (30): identity header rejection matrix, relay/worker keys, slot pinning, fail-closed flag chains, capabilities record validity, tenant-scoped paths + traversal rejection, revisions/conflicts, torn-ledger recovery, blobs, manifest, concurrent writers, audit rows, flag-off == not-found, 401 never touches storage, real HTTP server JSON + SSE, loopback-only bind, all errors validate, ≤500 LOC guard | +| Coverage | 99% line / 98% branch over the package | +| Contract | 1.0.0 | +| Flag | `hux.foundation` (root of every dependency chain) | +| Risks | Rate limiting (SO-53) and hash-chained audit (SO-46) not yet implemented — tracked for the Wave A review; relay callers still carry `X-Hux-Subject` (deviates from SO-06; the slot→owner mapping lives in the router, so the header is redundant but harmless and lets the service pin the subject) | +| Codex needs | Wire the service into the tenant pod + Worker, NetworkPolicy, router header contract above, `HUX_FLAGS=hux.foundation` for the first canary; `testing/quality_contract.json` may add `dockerfiles/hermes-hux-foundation/**/*.py` to `line_limit_globs` and the two moved modules to `managed_modules` (Claude does not edit that file) |