build(agent): new-agents-4#58ba63 iteration

AGENTS.md

@@ -6,3 +6,19 @@
 - How to run:
   - bash test.sh
 - Important: This document is a stub for onboarding agents and does not describe a full production architecture.
+
+What to expect in this sprint
+- MVP mapping: canonical ArbSphere primitives (LocalArbProblem, SharedSignals, PlanDelta) and a minimal EnergiBridge translator to a vendor-agnostic IR.
+- A Graph-of-Contracts registry (GoC) to describe adapters and data schemas with per-message metadata for replay protection.
+- Deterministic replay: a CRDT-inspired delta structure to enable replay across reconnects.
+- A two-venue toy MVP to bootstrap interoperability, including data-feed and broker adapters.
+- Phase-wise rollout: protocol skeleton, governance ledger scaffolding, cross-domain demo, and latency/auditability dashboards.
+- Compliance and audit: tamper-evident governance logs and optional cross-firm attestations.
+
+Implementation guidance
+- Prefer to implement small, correct changes that improve interoperability and testability.
+- Extend EnergiBridge with additional IR fields and versioning as new adapters are added.
+- Keep the GoC registry lightweight; avoid coupling adapters to internal Python types.
+- Ensure tests remain deterministic and fast.
+
+If you want me to push a concrete two-venue toy MVP spec or add toy adapters, I can draft and implement those next.

README.md

@@ -1,9 +1,39 @@
 # ArbSphere Federated Cross (Toy)
 
 This repository provides a minimal, test-focused Python package that defines
-the canonical LocalArbProblem and SharedSignals primitives and a simple ADMM-like
-step function used by unit tests. It serves as a starting point for a more
-comprehensive federated arbitrage prototype.
+the canonical ArbSphere primitives and a deterministic ADMM-like step function
+used by unit tests. It serves as a starting point for a more comprehensive
+federated arbitrage prototype with privacy-preserving provenance and auditability.
 
-Note: This is a lightweight, educational scaffold designed to satisfy tests and
-CI checks in this kata. It is not a production-grade implementation.
+What this repo delivers today
+- Core primitives: LocalArbProblem and SharedSignals, plus a simple PlanDelta
+  generated by admm_step, suitable for deterministic testing and replay.
+- A lightweight translator: EnergiBridge, which serializes ArbSphere primitives into
+  a canonical IR for adapters and cross-venue bridges.
+- A small Graph-of-Contracts registry (GoC) and a basic registry for adapters.
+- Packaging scaffold with a test suite (pytest) and a packaging check (python -m build).
+
+Roadmap (high level)
+- Phase 0: protocol skeleton and two starter adapters with a lightweight ADMM-lite
+  coordinator. Demonstrate a simple cross-venue mispricing capture with bounded
+  plan feasibility and deterministic replay.
+- Phase 1: governance ledger scaffold, identity management (DID/short-lived certs),
+  and secure aggregation for SharedSignals.
+- Phase 2: end-to-end cross-domain demo in a two-venue simulation, SDK bindings (Python/C++),
+  and a minimal contract example.
+- Phase 3: latency-aware backtesting harness, performance dashboards, and auditability metrics.
+
+Interoperability and privacy
+- Canonical bridge mapping ArbSphere primitives to a vendor-agnostic IR (EnergiBridge).
+- Protobuf/JSON-like IR is designed to be adapter-friendly, with per-message metadata
+  for replay protection and auditability.
+- A lightweight Graph-of-Contracts registry to describe adapters, versions, and endpoints.
+
+Testing and packaging
+- Run tests with: bash test.sh
+- Packaging verification via: python3 -m build
+- The repository is configured to be production-ready enough for CI checks while
+  remaining a clean, educational scaffold for exploring federated arbitration ideas.
+
+If helpful, I can draft toy adapter blueprints, an EnergiBridge mapping for ArbSphere,
+and a minimal two-venue toy contract to bootstrap interoperability.