# CrisisPulse – Agent Contribution Guide

Overview
- A federated resource orchestration framework for disaster-relief networks. This repository provides a production-ready MVP with a local ledger, delta-sync, contract registry, adapters, governance ledger, and privacy-preserving components.

Tech Stack
- Language: Python 3.11+
- Core packages: standard library, typing_extensions
- Optional (for future expansion): FastAPI for services, SQLAlchemy or SQLite for persistence

Project Architecture
- core modules
  - ledger.py: Local ledger with delta-sync capabilities
  - contract_registry.py: Graph-of-Contracts registry for versioned schemas
  - adapters.py: Base adapter API and two sample adapters (Solar, WaterPurifier)
  - governance.py: Tamper-evident governance log with signing
  - privacy.py: Simple privacy-preserving summarize/aggregation placeholder
  - sim.py: Lightweight co-simulation helpers
- tests/: unit tests ensuring correctness of core primitives
- AGENTS.md: this file
- README.md, test.sh, READY_TO_PUBLISH: publishing scaffolding

Testing & Validation
- Run tests locally: bash test.sh
- Ensure all tests pass before publishing
- Use pytest for unit tests and python -m build for packaging validation

Contribution Rules
- Add small, well-scoped features; prefer minimal, correct changes
- Update tests to cover new behavior
- Do not push to remote without explicit user request
- Keep interfaces simple and well-documented

Publishing Readiness
- When ready, ensure READY_TO_PUBLISH exists in repo root
- package name in pyproject.toml follows the community naming convention