guardrail-space-verifiable-safety-contra/AGENTS.md

GuardRail.Space AGENTS.md

Architectural guidelines and contribution rules for GuardRail.Space MVP.

• Architecture overview
• Tech stack and interfaces
• Testing commands and CI hints
• Contribution and code style rules
• MVP scope for safety contracts, policy engine, guard module, and adapters

The goal is to provide a production-ready scaffold that can be progressively extended:

• MVP: DSL for SafetyContracts, runtime policy engine, guard module, shadow planner, and adapters.
• The MVP will also include a minimal Python package, unit tests, and a test runner script (test.sh).
• Additional adapters for Gazebo/ROS integration and offline reconciliation scaffolding will be implemented progressively.

If you add features, update this document to reflect schema changes and testing commands.

New modules added in this iteration:

• src/guardrail_space/belief.py: a compact particle-filter sketch that emits probability-of-violation (PoV) and an entropy summary. Includes serialize() for compact fingerprints. Unit tests in tests/test_belief.py exercise deterministic behavior and compact serialization.
• src/guardrail_space/capsule.py: Poetic Situation Capsule generator that emits a tiny 128-512B human+machine readable capsule (round,plan_hash,PoV, energy_gap,verdict,human_summary). Tests in tests/test_capsule.py cover deterministic generation and size constraints.
• src/guardrail_space/collision_oracle.py: deterministic pairwise plan-collision oracle useful for multi-agent custody-window checks and small sidecar conflict verdicts. Tests in tests/test_collision_oracle.py exercise basic conflict and compatibility scenarios.

Testing

• Run ./test.sh to execute unit tests and build a sdist/wheel with python3 -m build.