From d50d014572232228ca21091b5db4b39bf7d18f49 Mon Sep 17 00:00:00 2001 From: jenkins Date: Mon, 24 Aug 2026 04:45:38 -0300 Subject: [PATCH] docs(hux): record completion increments and staged release runbook Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BvMSXH8VH2tMWXanb8SJdf --- docs/hux/HANDOFF.md | 76 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/docs/hux/HANDOFF.md b/docs/hux/HANDOFF.md index 05e57d64..72386a58 100644 --- a/docs/hux/HANDOFF.md +++ b/docs/hux/HANDOFF.md @@ -297,3 +297,79 @@ and plugin/vendored-hook render parity. UI card model suites: in-repo with the chain above. - Open item "SO-53 rate limits" — implemented in `hux/http.py`; SO-46 and SO-48 remain open (see the threat model amendment). + + +## Completion increments (2026-08-24, later — local chain, staged, not deployed) + +Everything below is committed locally on top of the integrated topology and +verified by the full gate (826 passed / 0 failed across +`test_hermes_hux_*.py`, `test_hermes_webui_hux_*.py`, image-automation, +webui-release, auto-router and chat-quality suites, after one fieldRef +tolerance fix in the voice gate). + +- **Topology gates are all-or-nothing adaptive** (`test_hermes_hux_delivery.py`, + `test_hermes_image_automation.py`): with no `hux` sidecar the manifests must + contain zero partial HUX wiring; with it, the full strict boundary applies. + This lets the source chain merge and build before activation. +- **HUX-06 adoption** (`services/hermes/plugins/auto-router/hux_mode.py`): + the auto-router consults the loopback HUX service (worker trust, the same + `hux.context.id.v1` HMAC derivation) for the conversation's selected + friendly mode: fast→auto/fast, thoughtful/research→auto/deep, + create→auto/balanced, private→the local route only. Explicit UI picks win; + every failure falls through to previous behaviour. Delivered through the + auto-router ConfigMap with a degrade-to-noop import shim. +- **Private mode is enforced upstream** (`hux/policy.py`, `hux/budgets.py`): + network, web_search, send_message, shell and delegate are refused by the + approval resolver and re-refused by the gate for a conversation whose + stored mode is `private`, regardless of autonomy level. +- **HUX-04/08 emitters** (`plugins/hux-runtime/emitters.py`): after a + successful `write_files` tool the plugin registers the written file as an + artifact (create or immutable version, ≤1 MiB, deterministic idempotency); + after successful `network`/`web_search` tools it records up to three + deduplicated `web` sources from the real output. Fail-open by construction. +- **HUX-03 message-text search** (`hux/organization.py`): + `GET /hux/v1/search?include=message_text` scans stored message events of + the 100 most recently active candidates; forgotten, private, restricted + and fully-redacted content never matches; deterministic cursor pagination. + The default search response is unchanged (the shipped UI requires + `message_text` in `not_indexed`). +- **HUX-12 producer** (`dockerfiles/hermes-hux-foundation/hux_producer/`, + 100% line+branch, 71 tests): pure verifier binding review URL prefix → + Jenkins SUCCESS/revision → immutable Harbor tag/digest → Flux + `main@sha1:` revision with pin containment → desired workload image → + every Ready pod imageID → bounded-age health receipt → rollback target; + HTTPS-only injectable collectors (SA token for the API); evidence-trust + driver posts exactly one If-Match transition. Cluster layer staged in + `chat-statefulset.yaml` (sidecar + tolerant key init), + `hux-evidence-policy.json`, `hux-evidence-rbac.yaml` (read-only pods/ + statefulset + the single named Kustomization), tenant egress to the API + ClusterIP and traefik. The key reaches only the `hux` and + `hux-evidence-producer` containers. + +### HUX-12 enablement runbook (fail-closed until every step is done) + +1. `vault kv put kv/atlas/hermes/hux-evidence evidence_key="$(openssl rand -hex 32)"` +2. Add to the chat tenant pod annotations (Flux commit): + `vault.hashicorp.com/agent-inject-secret-hux-evidence-key: kv/data/atlas/hermes/hux-evidence` + plus the matching template emitting `.Data.data.evidence_key`. +3. Create ConfigMap `hermes-hux-evidence-scope` with + `HUX_PRODUCER_PROJECT_ID` / `HUX_PRODUCER_CONVERSATION_ID` for the release + conversation (visible in the UI once a reviewed proposal exists). +4. Only then does `release_security.configured` turn HUX-12 on; the sidecar + loop starts posting verified transitions. + +### Staged release sequence (agreed) + +1. Push the source tip to main: the full local chain plus a hold commit that + restores `services/hermes/{chat-statefulset,chat-pvcs,chat-configmap,kustomization,networkpolicy}.yaml` + to the live state (keeping only the auto-router `hux_mode.py` ConfigMap + key) and removes the evidence policy/RBAC files — so Flux applies nothing + and CI builds the reviewed WebUI image. +2. Trigger the WebUI build at that exact SHA; wait for Flux digest + convergence. +3. Re-apply the activation topology pinned to the new tag/digest with + `HUX_FLAGS=hux.foundation`, `HUX_TOOL_ENFORCEMENT=0`, and a RollingUpdate + partition canarying ordinal 3 first. +4. HUX-11 live gates → card-by-card flag enablement with lifecycle + acceptance → enforcement after park/resume + stop receipts pass live → + HUX-12 after the runbook above → Worker separately.