# AGENTS.md

## Purpose
CivicPulse is an offline-first coalition coordination core for organizers who need auditability, privacy controls, and deterministic sync across unreliable networks.

## Stack
- Python 3.11+
- `pydantic` for schema validation
- SQLite via the standard library for local event storage
- `pytest` for tests
- `build` for packaging verification

## Architecture
- `models.py`: domain objects for organizations, proposals, endorsements, briefs, shifts, tasks, and provenance records.
- `ledger.py`: SQLite event ledger with immutable provenance records and audit-chain retrieval.
- `sync.py`: deterministic merge and replay helpers for offline reconciliation.
- `privacy.py`: role-based redaction and minimal-signal sharing.
- `registry.py`: graph-of-contracts schema and adapter registry.
- `service.py`: high-level orchestration API used by tests and CLI.
- `cli.py`: small command-line entry point.

## Rules
- Keep changes deterministic and auditable.
- Prefer small, explicit data transformations over hidden magic.
- Do not remove provenance records; add new records instead.
- Preserve privacy defaults when adding new shareable fields.
- Update tests whenever behavior changes.

## Verification
- `bash test.sh`
- `python3 -m pytest -q`
- `python3 -m build`