[jacksonsr451]

Summary

Implements Issue #5 by introducing differentiated manual consultation triage for Bug, Feature, and Chore, while preserving existing Docs and Security classifications.

This PR adds authoritative Pydantic discriminated-union validation, category-specific triage templates, explicit manual reclassification, append-only audit history, and consistent authorization enforcement.

The implementation extends the existing Consultation domain delivered by Issue #4 without introducing a separate triage engine or changing downstream approval workflows.

Changes

• Implement category-specific triage validation for Bug, Feature, Chore, Docs, and Security.
• Introduce Pydantic discriminated unions for triage requests.
• Extend BugCriteria with impact.
• Extend FeatureCriteria with scope.
• Extend ChoreCriteria with expected_technical_effect.
• Preserve existing DocsCriteria and SecurityCriteria.
• Implement explicit manual consultation reclassification.
• Require justification for reclassification.
• Preserve previous and new classification snapshots in append-only audit history.
• Add reusable category-specific triage templates.
• Expose triage template metadata through an authenticated API endpoint.
• Enforce consultation lifecycle restrictions.
• Reuse existing workspace RBAC and tenant isolation.
• Preserve idempotency and concurrency guarantees.
• Extend OpenAPI 3.1 and JSON Schema contracts.
• Add unit and PostgreSQL integration tests.
• Update architecture, workflow, and traceability documentation.

Motivation

Consultations may represent fundamentally different types of work.

A Bug requires reproduction information, expected and observed behavior, environment details, impact, and severity.

A Feature requires a problem statement, expected value, scope, functional requirements, and acceptance criteria.

A Chore requires maintenance context, technical debt classification, justification, risk of inaction, and expected technical effect.

Applying a single generic validation model to all categories would allow incomplete or semantically inconsistent triage records.

This implementation introduces category-specific validation while keeping classification and reclassification explicitly manual.

It also ensures that consultation triage remains separate from Proposal approval and WorkItem/BoardCard creation.

Type of Change

• Bug fix
• New feature
• Refactoring
• Performance improvement
• Security improvement
• Documentation
• CI/CD or infrastructure
• Dependency update
• Breaking change

Related Issues

Closes #5

Depends on:

• [FEAT] Implementar domínio de consultas e intake multiorigem #4 — Consultation domain and multi-source intake.
• [FEAT] Implementar workspaces, projetos, membros e permissões #9 — Workspace administration, membership, and RBAC.
• [FEAT] Implementar autenticação e gestão segura de sessão dos três clientes #10 — OAuth/OIDC authentication and secure sessions.
• [FEAT] Criar API pública versionada e contratos de workflow #11 — Versioned Work Management API contracts.
• [FEAT] Criar backend persistente e migrations para gestão de trabalho #12 — Work Management persistence.

Implementation Details

Architecture

The implementation extends the existing Work Management Consultation domain.

It reuses:

• Consultation persistence.
• Consultation lifecycle management.
• Existing triage HTTP operations.
• SQLAlchemy and PostgreSQL infrastructure.
• Workspace authorization services.
• Action-level RBAC.
• Idempotency mechanisms.
• Concurrency controls.
• Append-only audit infrastructure.
• OpenAPI 3.1 contracts.
• RFC 9457 error handling.

The established workflow remains:

Consultation → Triage → Proposal → Review → Approval → WorkItem → BoardCard

Manual triage does not automatically create a Proposal, Approval, WorkItem, or BoardCard.

Discriminated Union Validation

Introduces authoritative category-specific Pydantic validation in:

services/triage_criteria.py

The implementation supports:

• BugTriageRequest.
• FeatureTriageRequest.
• ChoreTriageRequest.
• DocsTriageRequest.
• SecurityTriageRequest.

The HTTP request model uses a discriminated union based on the category field.

Annotated[
    Union[
        BugTriageRequest,
        FeatureTriageRequest,
        ChoreTriageRequest,
        DocsTriageRequest,
        SecurityTriageRequest,
    ],
    Field(discriminator="category"),
]

This ensures that category-specific criteria are validated against the corresponding request model rather than accepting arbitrary unstructured data.

The authoritative validation logic is shared with the application service layer.

Bug Triage

Bug classification requires structured defect information.

The criteria include:

• Expected behavior.
• Observed behavior.
• Reproduction steps.
• Environment.
• Severity.
• Regression information.
• Impact.

The new impact field captures the consequences of the defect separately from severity.

Feature Triage

Feature classification requires:

• Problem statement.
• Expected value.
• Functional requirements.
• Acceptance criteria.
• Scope.

The new scope field explicitly describes the functional boundaries of the proposed capability.

Chore Triage

Chore classification requires:

• Maintenance need.
• Technical debt type.
• Justification.
• Risk of inaction.
• Expected technical effect.

The new expected_technical_effect field describes the intended technical outcome of the maintenance work.

Docs and Security Compatibility

Existing DocsCriteria and SecurityCriteria remain supported.

The implementation preserves the established category vocabulary and integrates these categories into the same discriminated-union validation architecture.

No existing category was removed.

Manual Classification

Consultation triage remains an explicit, authenticated user action.

The backend validates:

1. Authenticated principal.
2. Active workspace membership.
3. Required triage permission.
4. Consultation ownership and workspace scope.
5. Valid consultation lifecycle state.
6. Category-specific criteria.
7. Transactional persistence.
8. Audit recording.

No automatic AI classification is introduced.

An initial category provided during intake does not bypass the manual triage workflow.

Manual Reclassification

Adds explicit consultation reclassification.

The operation supports:

• Changing an existing consultation category.
• Validating criteria for the new category.
• Requiring a reclassification justification.
• Enforcing authorized lifecycle transitions.
• Protecting concurrent modifications.
• Preserving previous classification information.
• Recording an append-only audit event.

The audit event is identified as:

consultation.reclassified

The audit payload records the previous and new classification snapshots, preserving traceability.

Reclassification does not bypass downstream Proposal or Approval invariants.

Category-Specific Triage Templates

Adds reusable triage template metadata through:

triage_templates

Templates provide category-specific field definitions for client applications.

This allows future Web, VS Code, and Desktop interfaces to build differentiated forms using consistent backend definitions.

The PR delivers backend template metadata, not frontend form implementations.

HTTP API

Extends:

services/work-management/src/eventflow_work_management/api/consultation_routes.py

The implementation includes:

• Existing manual consultation triage.
• Explicit consultation reclassification.
• Triage template metadata retrieval.

New OpenAPI operations:

• reclassifyConsultation
• listConsultationTriageTemplates

The existing triageConsultation operation remains supported.

All operations use the established /v1/ API conventions.

Authorization

The triage, reclassification, and template operations declare the following authorized roles:

Operation	Authorized roles
Manual triage	owner, admin, triager
Reclassification	owner, admin, triager
Triage template retrieval	owner, admin, triager

Authorization behavior:

• Unauthorized workspace membership: 404.
• Cross-workspace resource access: 404.
• Active member without required permission: 403.

The implementation reuses the existing authorization services rather than introducing a parallel permission model.

Persistence

No new Alembic migration was required.

The existing Consultation persistence model already contains the triage_criteria JSONB field.

The implementation reuses that field for validated category-specific criteria.

This avoids unnecessary schema changes and preserves existing migration history.

Idempotency and Concurrency

Manual triage and reclassification integrate with existing idempotency and concurrency mechanisms.

The implementation protects against:

• Duplicate classification effects.
• Conflicting requests.
• Unauthorized reclassification.
• Invalid lifecycle transitions.
• Inconsistent concurrent updates.
• Duplicate effective audit operations.

Classification changes and corresponding audit records are handled within the established persistence boundaries.

API Contracts

Updated:

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

Changes include:

• Category-specific criteria requirements.
• Bug impact.
• Feature scope.
• Chore expected technical effect.
• Discriminated-union request validation.
• OpenAPI oneOf and discriminator mapping.
• ReclassifyConsultationRequest.
• TriageTemplate.
• TriageTemplates.
• Reclassification operation.
• Template metadata operation.

The OpenAPI specification remains compatible with OpenAPI 3.1 validation.

Validation Response Semantics

Malformed or mismatched discriminated-union request payloads are rejected with HTTP 400.

Previously, some equivalent validation failures were handled at the application service layer with HTTP 422.

The existing tests were updated to reflect request-shape validation at the HTTP boundary.

Both 400 and 422 responses remain documented.

This response-status change should be considered during client compatibility review.

Security Considerations

Authentication

All protected operations reuse the existing OAuth/OIDC authentication infrastructure.

No alternative authentication mechanism is introduced.

RBAC

Only authorized workspace roles can perform manual triage and reclassification.

Authorization is enforced through the existing application services.

Tenant Isolation

Consultation operations remain workspace-scoped.

Cross-workspace resource identifiers cannot grant access to consultations belonging to another tenant.

Auditability

Reclassification produces an append-only audit event.

Previous classification information remains available for traceability.

Workflow Integrity

Triage cannot directly create:

• Proposals.
• Approvals.
• WorkItems.
• BoardCards.

The existing approval workflow remains authoritative.

Testing

Local Verification Results

Test suite	Passed	Failed	Skipped
Work Management	130	0	1
Repository regression suite	114	0	0
Total	244	0	1

The single skipped test is:

test_authentication_keycloak_integration.py

It requires a live Keycloak environment and is unrelated to the new triage functionality.

Verified Coverage

• Pydantic discriminated-union validation.
• OpenAPI oneOf and discriminator mapping.
• Bug-specific criteria.
• Feature-specific criteria.
• Chore-specific criteria.
• Docs and Security compatibility.
• Manual triage.
• Reclassification.
• Reclassification justification.
• Lifecycle restrictions.
• Concurrency protection.
• Idempotency.
• Append-only audit.
• Template metadata.
• Workspace RBAC.
• Tenant isolation.
• PostgreSQL integration.
• Negative validation.
• Contract validation.
• Repository regression tests.

Validation Commands

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

Additional validation:

• openapi-spec-validator: passed.
• Pre-commit hooks: passed.
• Working tree: clean.

Documentation

Updated:

• docs/architecture/work-management-api.md
• docs/architecture/work-management-workflow.md
• docs/security/traceability.md

The documentation now covers:

• Category-specific criteria.
• Manual triage.
• Reclassification.
• Audit semantics.
• Template metadata.
• API contracts.
• Authorization behavior.

Backward Compatibility

• Existing consultation intake is preserved.
• Existing draft lifecycle is preserved.
• Existing Docs and Security categories remain supported.
• Existing workspace RBAC is reused.
• Existing authentication is unchanged.
• No database migration is required.
• Existing downstream approval invariants are preserved.

Compatibility note: Discriminated-union request-shape violations now return HTTP 400 instead of the previous service-level 422 in affected cases. Clients relying on the old validation status should be reviewed.

Known Limitations and Reservations

Live Keycloak Test

One existing Keycloak integration test was skipped locally because the required live authentication stack was unavailable.

Client-Side Forms

This PR provides reusable backend triage templates and API contracts.

The actual Web, VS Code, and Desktop user interfaces are not implemented in this backend issue.

Remote CI

Remote GitHub Actions verification has not yet been executed for this branch.

The PR must pass the required CI checks before merging.

Review Checklist

• Bug triage implemented.
• Feature triage implemented.
• Chore triage implemented.
• Docs and Security preserved.
• Pydantic discriminated union implemented.
• OpenAPI discriminator contract implemented.
• Manual classification enforced.
• Manual reclassification implemented.
• Reclassification justification required.
• Reclassification audit implemented.
• Category-specific templates implemented.
• Template metadata endpoint implemented.
• Workspace RBAC enforced.
• Tenant isolation validated.
• Idempotency and concurrency covered.
• PostgreSQL integration tests passed.
• Negative validation tests passed.
• Contract validation passed.
• Repository regression tests passed.
• Documentation updated.
• Pre-commit checks passed.
• Local working tree clean.
• Remote CI verification.
• Final code review.

Commit

6473ed2 — feat(work-management): add differentiated consultation triage and reclassification (#5)

Base commit:

5041109 — Feat/4 consultation multisource intake (#67)

Outcome

This PR completes Issue #5 by introducing differentiated, validated, and auditable manual triage for EventFlow consultations.

The implementation establishes consistent category-specific criteria for Bug, Feature, and Chore while preserving Docs and Security compatibility, enforcing workspace authorization, and protecting the existing approval workflow.

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

Status: Ready for PR review, pending remote CI verification.