feat: implement committee decision workspace

README.md

@@ -4,16 +4,34 @@
 **Repository type:** module (domain).
 <!-- govoplan-repository-type:end -->
 
-`govoplan-committee` is the GovOPlaN platform module seed for committee, board, council, and senate workflows for meetings, agendas, minutes, decisions, voting, and follow-up tasks.
+`govoplan-committee` is the GovOPlaN module for committee, board, council, and senate workflows for meetings, agendas, minutes, deliberation, voting, formal decision references, and follow-up tasks.
 
-This repository is initialized as a discoverable module seed. It exposes a module manifest, initial permissions, role templates, documentation metadata, Gitea workflow templates, and a focused manifest test. It intentionally does not yet add HTTP routes, database models, migrations, or WebUI navigation.
+The backend now exposes versioned `committee.workspace` and
+`committee.decision_path` capabilities. The workspace persists immutable,
+OCC-guarded revisions for bodies, meetings, agenda items, governed vote
+results, and minutes, with replay-safe lifecycle events. The decision path
+combines that committee context with an effective Mandate,
+including organization, function, and jurisdiction coverage, with approval,
+legal bases, evidence, reasoning, and effects to create the shared
+formal Decision contract. Mandate resolution and Decision persistence remain
+optional providers. If Decisions is absent, Committee retains a bounded,
+protected local Decision projection so the outcome remains reconstructable.
+The `/committee` WebUI provides the body, meeting, agenda, vote, and minutes
+workspace using the same immutable revisions and lifecycle guards as the API.
+
+`committee.ballot_finalizer` delegates provider-bound external or secret
+ballots to `committee.ballot_adapter.<provider>` capabilities. Committee
+validates the exact choices, eligible/cast totals, tenant evidence, receipt,
+and result hash, then stores only the verified aggregate. Individual ballots
+never enter Committee persistence, and a provider-bound vote cannot be closed
+through the generic workspace endpoint.
 
 ## Initial Ownership
 
 - committee bodies
 - meeting agendas
 - minutes
-- decision records
+- deliberation/vote context and formal decision references
 - votes
 - follow-up assignments
 
@@ -24,6 +42,8 @@ This module does not own:
 - generic task execution
 - document storage
 - calendar event storage
+- the generic formal decision lifecycle; a future Decisions provider owns
+  authority, facts/rules, reasoning, effects, review, correction, and revocation
 
 Detailed boundary notes are in [docs/COMMITTEE_DOMAIN_BOUNDARY.md](docs/COMMITTEE_DOMAIN_BOUNDARY.md).
 
@@ -54,6 +74,20 @@ cd /mnt/DATA/git/govoplan-committee
 PYTHONPATH=src:/mnt/DATA/git/govoplan-core/src /mnt/DATA/git/govoplan-core/.venv/bin/python -m unittest discover -s tests
 ```
 
+## API And Recovery
+
+`/api/v1/committee/workspace/{body|meeting|agenda_item|vote|minute}` supports
+bounded list/read/write and immutable history. Writes require an idempotency
+key and expected revision after creation. Protected local Decision projections
+use a separate read permission. Database restore is the semantic recovery unit;
+linked Calendar, Files, Records, Tasks, Approvals, and Decisions objects retain
+their own recovery responsibility.
+
+`POST /api/v1/committee/workspace/vote/{vote_id}/finalize-provider` is the
+separate effect boundary for an installed ballot adapter. It requires the
+`committee:ballot:finalize` permission and preserves provider receipt/hash and
+evidence without exposing or persisting individual votes.
+
 ## Gitea Workflow
 
 Issue templates are installed under `.gitea/`, and the shared label taxonomy is copied to `docs/gitea-labels.json` with the module label `module/committee`.