[Senate] Schema proposal system via Senate governance

Goal

Enable agents to propose schema changes through the Senate governance process. A proposal
specifies what to change (add field, modify type, add new artifact type), why it's needed,
and what the migration looks like. Other agents can debate the proposal before it's voted on.

Acceptance Criteria

- target_artifact_type — which type to modify (or "new_type" for new types)
- change_type — add_field, modify_field, remove_field, add_type, rename_field
- field_spec — JSON Schema snippet for the proposed change
- rationale — why this change is needed (must reference specific use cases)
- migration_plan — SQL migration and backfill strategy
- backward_compatible — boolean, does this break existing artifacts?

Dependencies

• sen-sg-01-SREG — Registry must exist for proposals to reference

Dependents

• sen-sg-04-MIGR — Approved proposals trigger migration generation
• sen-sg-05-SCOP — Scope enforcement evaluates proposals

Approach

Verify existing infrastructure: senate_proposals and senate_votes tables confirmed in PostgreSQL; scidex/senate/schema_governance.py already implements create_schema_proposal(), vote_on_proposal(), get_proposal_status(), and _check_and_finalize_proposal() with all business logic (2/3 majority, unanimous for breaking changes, scope evaluation).

Add two missing API routes to api_routes/senate.py:

- POST /api/senate/schema-proposal — accepts SchemaProposalRequest body, calls create_schema_proposal(), returns proposal_id + status + voting threshold
- GET /api/senate/schema-proposal/{proposal_id} — returns full proposal status for verification
- POST /api/senate/schema-proposal/{proposal_id}/vote — accepts SchemaProposalVoteRequest, calls vote_on_proposal(), returns updated vote tallies

Enhance _check_and_finalize_proposal() in schema_governance.py to emit a schema_proposal_approved event via event_bus.publish when a schema_change proposal is approved, enabling sen-sg-04-MIGR to consume it.

Work Log

2026-04-25 — Slot claude-auto:40

• Read AGENTS.md, task spec, and quest context
• Verified senate_proposals (25 columns) and senate_votes tables exist in PostgreSQL
• Confirmed schema_governance.py has full business logic; only API surface was missing
• Added SchemaProposalRequest, SchemaProposalVoteRequest Pydantic models to api_routes/senate.py
• Implemented POST /api/senate/schema-proposal, GET /api/senate/schema-proposal/{id}, POST /api/senate/schema-proposal/{id}/vote routes
• Updated _check_and_finalize_proposal() to emit schema_proposal_approved event on approval
• Verified Python syntax passes for both modified files; router inspection confirms all 5 schema-proposal routes registered
• Committed and pushed

Tasks using this spec (1)

[Senate] Schema proposal system via Senate governance

File: sen-sg-02-PROP_schema_proposal_system_spec.md

Modified: 2026-05-01 20:13

Size: 3.5 KB