[jacksonsr451]

Summary

Closes #6

Implements task proposal management for EventFlow's Work Management bounded context, allowing a single triaged Consultation to generate zero, one, or multiple independent Proposals.

Each Proposal has its own identity, lifecycle, revision history, checklist, evidence associations, and review workflow.

This implementation builds on Issues #4 and #5 and preserves the architectural separation between consultations, proposals, approvals, executable tasks, and board cards.

Changes

Proposal Domain

• Reworked models/proposal.py to support multiple independent proposals per Consultation.
• Removed consultation-scoped proposal version uniqueness.
• Added structured checklist support.
• Added duplicated_from and superseded_by self-referencing relationships.
• Preserved Proposal identity independently from its revision number.
• Introduced immutable Proposal revision snapshots.
• Added Proposal evidence associations.

Proposal Management API

Implemented ProposalService and api/proposal_routes.py, registered in the Work Management application.

Supported operations:

• Preview a Proposal.
• Create a Proposal from a triaged Consultation.
• List Proposals.
• Retrieve a Proposal.
• Retrieve Proposal revision history.
• Edit an existing Proposal.
• Submit a Proposal for review.
• Duplicate a Proposal.

The implementation reuses the established /v1/ API conventions.

Multiple Proposals per Consultation

A single Consultation can now produce multiple independently managed Proposals.

Example:

Consultation C1
├── Proposal P1
│   ├── Revision 1
│   └── Revision 2
├── Proposal P2
│   └── Revision 1
└── Proposal P3
    ├── Revision 1
    └── Revision 2

Each Proposal maintains its own:

• Unique identifier.
• Version sequence.
• Lifecycle state.
• Scope and technical description.
• Estimated effort.
• Suggested priority.
• Dependencies.
• Checklist.
• Acceptance criteria.
• Evidence references.

Creating or editing one Proposal does not replace another Proposal associated with the same Consultation.

Immutable Revision History

Introduced:

• models/proposal_revision.py
• Immutable Proposal revision snapshots.
• Revision history retrieval.
• Database-level revision mutation protection.

The migration creates the PostgreSQL trigger:

eventflow_proposal_revisions_block_mutation

This prevents updates and deletions of persisted revision snapshots.

Evidence Associations

Introduced:

models/proposal_evidence.py

Proposals can reference supporting evidence associated with their originating Consultation.

The implementation reuses existing Consultation evidence infrastructure rather than duplicating attachment storage.

Controlled Duplication

Added explicit Proposal duplication support.

A duplicated Proposal:

• Receives a new Proposal identity.
• Starts an independent revision history.
• Retains source provenance through duplicated_from.
• Remains separate from the original Proposal.
• Does not inherit authorization to create executable work.

Proposal Lifecycle

The existing workflow remains:

Consultation
    ↓
Manual Triage
    ↓
Proposal
    ↓
Review
    ↓
Approval
    ↓
WorkItem
    ↓
BoardCard

Proposal creation, preview, editing, and duplication do not automatically create:

• Approval records.
• WorkItems.
• BoardCards.
• GitHub issues.
• GitLab issues.

Formal approval remains the authoritative boundary for executable work creation.

Persistence

Migration

Added:

0007_proposal_task_proposals

The migration:

• Drops uq_proposals_consultation_version.
• Extends the Proposal persistence model.
• Adds Proposal revision storage.
• Adds Proposal evidence association storage.
• Adds duplication and supersession relationships.
• Creates the immutable revision protection trigger.

This resolves the previous conflict between consultation-scoped version uniqueness and the requirement for multiple independent proposals.

Authorization and Security

Extended the existing authorization policy with:

• proposal:update
• proposal:duplicate

The implementation integrates with existing:

• OAuth/OIDC authentication.
• Workspace membership and RBAC.
• Tenant isolation.
• Proposal lifecycle restrictions.
• ETag/If-Match concurrency controls.
• Optional Idempotency-Key support.
• RFC 9457 Problem Details responses.

No separate authentication or authorization subsystem was introduced.

API Contracts

Updated:

• contracts/openapi/work-management.yaml
• contracts/schemas/work_management.yaml

Changes include:

• New and updated Proposal DTOs.
• Six additional API operations.
• Proposal revision representations.
• Proposal management request/response contracts.
• Authorization requirements.
• ETag/If-Match handling.
• Optional Idempotency-Key support.
• RFC 9457 error responses.

The contracts remain compatible with the existing OpenAPI 3.1 validation infrastructure.

Architecture and Documentation

Updated:

• Work Management API documentation.
• Work Management workflow documentation.
• Persistence architecture documentation.
• Security traceability.
• Open decisions.
• Risk register.
• ADR-008.

ADR-008 Amendment A-01

Documents the architectural amendment separating:

1. Independent Proposal identities associated with a Consultation.
2. Independent revision sequences associated with each Proposal.

Also records the revised persistence model required for the one-to-many Consultation-to-Proposal relationship.

Open Decision OD-16

Updated the architectural decision tracking associated with Proposal management.

Testing

Local Test Results

Suite	Passed	Failed	Skipped
Work Management	147	0	1
Repository regression	114	0	0
Total	261	0	1

The skipped test requires a live Keycloak integration environment.

New Tests

Added:

• test_proposal_api_integration.py — 7 integration tests.
• test_proposal_unit.py — 9 unit tests.

Existing tests that depended on consultation-scoped version uniqueness were updated to reflect the new one-to-many model.

Validation

• Work Management tests: 147 passed, 1 skipped.
• Repository tests: 114 passed.
• Contract validation: passed.
• OpenAPI specification validation: passed.
• git diff --check: clean.
• Pre-commit hooks: passed.
• Working tree: clean.

Commands

testrunner services/work-management/tests -v --disable-plugin-autoload
testrunner tests -v --disable-plugin-autoload
python scripts/validate_contracts.py
git diff --check

Review Focus

The following scenarios deserve particular attention during review:

• Concurrent Proposal creation and editing.
• Idempotent duplication requests.
• Cross-workspace evidence access.
• Immutable revision enforcement.
• Transaction rollback behavior.
• Authorization for proposal updates and duplication.

The reported test totals do not independently establish that every one of these scenarios has dedicated coverage.

Backward Compatibility

• Existing Consultation intake is preserved.
• Existing manual triage is preserved.
• Existing differentiated Bug, Feature, Chore, Docs, and Security criteria remain supported.
• Existing workspace authorization infrastructure is reused.
• Existing authentication remains unchanged.
• Proposal versioning now supports multiple independent Proposals per Consultation.
• The database schema change is documented in ADR-008 Amendment A-01.
• The Approval → WorkItem → BoardCard boundary remains unchanged.

Scope Exclusions

This PR does not implement:

• Automatic Proposal approval.
• Automatic WorkItem creation.
• Automatic BoardCard creation.
• GitHub issue creation.
• GitLab issue creation.
• Web application Proposal forms.
• VS Code extension Proposal forms.
• Desktop application Proposal forms.

These capabilities belong to separate workflow stages or client implementations.

Review Checklist

• Multiple Proposals per Consultation.
• Independent Proposal identity.
• Independent Proposal versioning.
• Proposal creation.
• Proposal retrieval.
• Proposal listing.
• Proposal preview.
• Proposal editing.
• Proposal revision history.
• Immutable revision snapshots.
• Controlled Proposal duplication.
• Checklist support.
• Evidence associations.
• Proposal submission for review.
• Authorization policy updates.
• ETag/If-Match integration.
• Optional Idempotency-Key support.
• Alembic migration.
• OpenAPI and JSON Schema updates.
• ADR-008 amendment.
• Architecture documentation.
• Unit and integration tests.
• Repository regression tests.
• Local contract validation.
• Pre-commit validation.
• Remote CI verification.
• Final code review.

Commit

9425a35 — feat(work-management): implement consultation task proposals (#6)

Base:

7347e02 — feat(work-management): add differentiated consultation triage and reclassification (#5) (#68)

Change Statistics

• 29 files changed.
• 3,712 insertions.
• 93 deletions.

Outcome

Issue #6 introduces complete backend Proposal management for the EventFlow consultation workflow.

A single triaged Consultation can now produce multiple independently versioned Proposals with preview, editing, immutable revision history, controlled duplication, checklists, evidence associations, and authenticated API operations.

The implementation preserves the separation between proposed work and approved executable tasks.

Local verification: 261 passed, 0 failed, 1 skipped.

Status: Ready for review, pending remote CI verification.