docs: design spec for phase 0.7 → 1.0 batch (autonomous superpowers run)

per superpowers:brainstorming — explore context, propose approaches, write
spec, self-review. user-approval gates inside the skill skipped per
operator's "yes to all autonomous" directive on 2026-05-09.

scope of the batch:
  - 0.7  kotlin gradle CI job (catches kotlin module regressions)
  - 0.8  cloudflared install + live tunnel verification
  - 0.9  multi-AI council example (showcase bidirectional)
  - 1.0a signed manifests (ed25519, backwards-compat)
  - 1.0b lightweight federation (read-only, one-hop) — stretch

self-review surfaced + fixed inline:
  - "hand-test" → must include real curl round-trip for 0.8
  - "federation" → clarified read-only / one-hop / no shared state
  - "key pinning" → explicit test added for 1.0a

next: writing-plans skill for implementation plan.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Zawwarsami16

docs/superpowers/specs/2026-05-09-zhub-phase-0.7-to-1.0-design.md

@@ -0,0 +1,171 @@
+# zhub Phase 0.7 — 1.0 design
+
+> Autonomous batch authorized by operator on 2026-05-09 ("use super power plugin plan and do everything autonomously, yes to all"). User-approval gates inside the brainstorming skill are skipped per that instruction; the rest of the discipline (explore context, propose approaches, written design, self-review, plan, TDD, verification) is preserved.
+
+## 1. Where zhub stands today (2026-05-09)
+
+Phase 0+1 through 0.6 shipped. Latest commit `d8affa8`. CI green on Python 3.10/3.11/3.12. 17/17 pytest. Hand-tested live by Claude on a local hub: bidirectional invoke, SSE streaming, persistence + re-registration with stored key, registry HTML page, all working. Two real bugs fixed during that hand-test (invoke double-wrap; generator-vs-non-streaming timeout). Two regression tests committed.
+
+Roadmap remaining (per `/root/zhub/CLAUDE.md` §5):
+
+> **Phase 1.0** — Signed manifests, hub federation.
+
+Production-readiness gaps not on the roadmap but worth closing in this batch:
+
+- **Kotlin module isn't tested in CI.** Today only Python tests run. The kotlin/ subproject has unit tests for the protocol round-trip (`kotlin/src/test/kotlin/com/zawwar/zhub/ProtocolTest.kt`) — Loki will rely on this code, so silent regressions there ship to phones.
+- **Cloudflare Tunnel path is code-correct but un-exercised live** (no `cloudflared` binary in proot). One unverified moving piece between Father and a real public URL.
+- **Multi-AI orchestration (council pattern) has no example.** zhub's bidirectional design literally enables it but nothing in `examples/` demonstrates more than one AI at a time.
+
+## 2. Scope of this batch
+
+Four sub-projects, each with its own deliverable. Sequential because each builds on what's there.
+
+### Phase 0.7 — Kotlin gradle CI job
+
+**Goal:** parallel CI job that compiles `kotlin/` and runs its unit tests on every push to `main`. If the protocol envelope schema drifts (Python vs Kotlin) or a Kotlin compile error sneaks in, CI fails.
+
+**Approach:** add a `kotlin-test` job to `.github/workflows/ci.yml` using `actions/setup-java@v4` (Temurin 17) and `gradle/actions/setup-gradle@v3`. Run `./gradlew test`. Cache dependencies. Job runs in parallel with the Python matrix; fails the workflow if either side breaks.
+
+**Stretch:** also run `./gradlew build` to catch packaging issues. Likely free given setup-gradle's caching.
+
+**Out of scope:** publishing the Kotlin artifact to Maven Central. That's Phase 0.10+ and requires repository credentials Father will set up when there's a downstream consumer.
+
+### Phase 0.8 — Cloudflare Tunnel live verification
+
+**Goal:** prove `zhub-server --public-tunnel` actually produces a working public URL end-to-end, on the same machine where Father will run it (Linux/proot).
+
+**Approach:** install `cloudflared` in this proot via the official `.deb` (Cloudflare's recommended distribution method). Start the hub with `--public-tunnel`. Verify:
+
+1. `cloudflared` spawns and reaches a "Your tunnel is at https://*.trycloudflare.com" line within 30s.
+2. `tunnel.start()` parses that URL correctly.
+3. `curl <public-url>/healthz` from the same proot returns 200 (proves egress + ingress through CF works).
+4. Publish a stub AI through the tunnel; hit it with curl; verify the round-trip.
+5. Clean shutdown — `cloudflared` exits when hub exits.
+
+**Document install + caveats** in `docs/CLOUDFLARED.md` so Father has the same path.
+
+**Out of scope:** named tunnels with stable subdomains. Ephemeral trycloudflare.com is fine for development; named tunnels are operator-side configuration, not a code concern.
+
+### Phase 0.9 — Multi-AI council example
+
+**Goal:** demonstrate bidirectional power that no other tool in this space has — three AIs published, one orchestrates the other two through the hub.
+
+**Approach:** new `examples/council_demo.py`:
+
+- Publishes 3 AIs:
+  - `claude-stub` — pretends to be Claude, returns thoughtful-toned replies
+  - `gpt-stub` — pretends to be GPT, returns concise-toned replies
+  - `gemini-stub` — pretends to be Gemini, returns analytical-toned replies
+- A 4th publisher, `coordinator`, is the council itself. Its chat handler:
+  1. Receives operator's question
+  2. Connects (via `zhub.connect`) to each of the 3 AIs and asks them in parallel
+  3. Synthesizes a single response that quotes each
+  4. Returns the synthesis as its own chat-response
+
+**Why this matters:** ZAI's existing `zai-council` plugin uses bespoke OpenRouter routing. With zhub, this pattern works for any published AIs uniformly. Demonstrates the substrate's value beyond "expose one AI."
+
+**Out of scope:** real LLM calls in the example (operator-side keys, costs). Stubs make the orchestration shape visible without spending on tokens.
+
+### Phase 1.0 — Signed manifests + lightweight federation
+
+This is the biggest piece. Honest scope first.
+
+**Goal:** publishers cryptographically sign their manifests; consumers can verify identity without trusting the hub. Hubs can advertise registries to each other so a global directory is possible.
+
+**Two-part decomposition:**
+
+**1.0a — Signed manifests (must-have):**
+
+- Each publisher generates an ed25519 keypair on first publish (or supplies an existing private key)
+- The manifest published to the hub includes a `signature` field — Ed25519 signature over `name + canonical_json(manifest_minus_signature)`
+- The publisher also publishes its public key as part of the manifest
+- A separate verification path: any consumer can fetch `/<name>/manifest.json`, verify the signature, and confirm the manifest hasn't been tampered with by the hub
+- Store the key fingerprint in `pyproject` and pin it across re-registrations (so re-using `api_key=...` validates that the same private key is signing — prevents key takeover via stolen api_key alone)
+
+**1.0b — Federation (stretch):**
+
+- A hub can declare peer hubs in config: `peers: ["https://hub-b.example.com", ...]`
+- Federated `/registry` returns local listings + a `peers` block linking to peer hubs' `/registry` endpoints
+- A new `/registry/global` endpoint walks one hop of peers and returns the union (with origin annotations)
+- Federation is **read-only / discovery-only** in 1.0b — no cross-hub call routing, no shared registry state. That's 1.1+.
+
+**Approach:**
+
+For 1.0a:
+- Add `cryptography` (already common dep) to optional `[crypto]` extras
+- New `zhub/signing.py`: `generate_keypair()`, `sign_manifest(manifest, private_key)`, `verify_manifest(signed_manifest)` — small surface
+- Modify `register_publisher` envelope to carry `signed_manifest` instead of bare `manifest`. Hub validates signature before accepting registration. Hub stores the public key alongside the manifest (already in storage; just an extra field).
+- `manifest.json` HTTP endpoint returns the signed form; consumers can verify
+- New test: `tests/test_signing.py` covering happy path + tamper detection
+
+For 1.0b:
+- New `zhub/federation.py`: `PeerRegistry` class, periodic refresh of peer registries
+- Hub config gains `peers: list[str]` (CLI flag or env var: `ZHUB_PEERS=url1,url2`)
+- `/registry/global` aggregator
+- Test: spin up two hubs, register one publisher on each, verify global view
+
+**Honest expectation:** 1.0a will land. 1.0b may land if context permits; if not, it gets a written plan and is the obvious next session. Federation is a bigger design surface (TLS verification, peer trust, refresh cadence) than signing.
+
+**Out of scope:**
+- Cross-hub call routing (call AI on hub-b through hub-a) — Phase 1.1.
+- Private peering (signed peer relationships) — Phase 1.2.
+- Anchored identities (DNS-bound or DID-bound publisher names) — Phase 2.0.
+
+## 3. Architecture impact summary
+
+Most of this batch is additive — new files, new tests, new examples. Three things change existing code paths:
+
+1. **CI workflow** gains a parallel job (Phase 0.7).
+2. **`server.py` register-publisher path** validates signature when present, falls back to legacy unsigned for backwards compatibility (Phase 1.0a). Existing tests keep passing because they don't sign.
+3. **`client.py` `publish()`** gains a `private_key` parameter (None means unsigned, opt-in). When present, signs the manifest before send.
+
+No breaking changes to v0 callers. v0.1 manifests remain valid alongside v0.2 signed manifests.
+
+## 4. Test plan (TDD throughout)
+
+Per the test-driven-development skill — every change writes a failing test first, then makes it pass.
+
+**0.7:** the CI job itself is the test. Verify by pushing and watching the new job appear, pass, and gate the workflow. Optional: a `kotlin/src/test/kotlin/.../ManifestSerializationTest.kt` that round-trips a Manifest through Python's wire format (regression for Python ↔ Kotlin schema drift).
+
+**0.8:** a real curl-against-tunnel test, manually verified. No CI test (CF tunnels aren't a CI runner concern).
+
+**0.9:** `tests/test_council.py` — the council coordinator's chat handler is exercised end-to-end. Stub AIs respond; coordinator synthesizes; assertion: synthesized output mentions each stub.
+
+**1.0a:** `tests/test_signing.py`:
+- happy-path sign + verify round-trip
+- tamper detection (mutate manifest after sign → verify fails)
+- public-key extraction matches generated key
+- legacy unsigned manifest still accepted (backwards compatibility)
+- re-registration with `api_key=` and a different private key is rejected (key pinning)
+
+**1.0b:** `tests/test_federation.py`:
+- two hubs in-process, each with one publisher, peering enabled
+- `GET /registry/global` on hub A includes hub B's listing
+- non-peered hub returns only its own
+- offline peer is gracefully omitted
+
+## 5. Verification before completion
+
+For every phase: actual tests pass, actual CI green, hand-test the changed code path before claiming done. The verification-before-completion skill says: evidence before assertions always. The two bugs caught in last session's hand-test prove this rule's value.
+
+For Phase 0.8 specifically — must include a real `curl https://*.trycloudflare.com/...` round trip succeeding. Just installing `cloudflared` and reading the URL doesn't count.
+
+## 6. Self-review (fresh eyes)
+
+**Placeholder scan:** none. All four phases have concrete deliverables.
+
+**Internal consistency:** Phase 1.0a backwards-compat claim cross-checks: "v0 unsigned manifests remain valid" + "test: legacy unsigned manifest still accepted." Consistent.
+
+**Scope check:** four sub-projects in one design doc is acceptable here because each is small (0.7, 0.8, 0.9 are < 1 day each) and 1.0 is decomposed into 1.0a + 1.0b with a stop-line. If 1.0a alone is going to take a full day, that's fine — it ships before 1.0b is touched.
+
+**Ambiguity check:**
+
+- "Hand-test" in §5 was vague — added: must include a real curl round-trip for 0.8.
+- "Federation discovery" in §2 was vague — clarified: read-only, one-hop, no shared state, no cross-hub call routing.
+- "Key pinning" in §4 was unstated — added explicit test: re-register with same api_key but different private key → reject.
+
+Fixed inline; nothing else surfaces.
+
+## 7. Transition
+
+This design doc proceeds directly to writing-plans for an implementation plan, then executing-plans / subagent-driven-development for the actual work. Per "yes to all" the user-review gate (brainstorming step 8) is skipped.