# Task Contract: Formal Investigation Escalation Approval

## Intent
When a case moves from Preliminary Review to Formal Investigation, the system must capture supervisor approval evidence and expose the escalation timestamp in audit-facing APIs.

## Current Behavior
- Cases can be escalated through the existing case state transition service.
- Escalation reason may exist as free-text transition metadata.
- Audit API currently exposes case status history but not escalation timestamp for Formal Investigation specifically.
- Notification behavior exists for some assignment changes but not confirmed for investigation team escalation.

## Target Behavior
- Formal Investigation transition requires supervisor approval record.
- Escalation reason must be preserved.
- Assigned investigation team must be notified.
- Case audit API must expose Formal Investigation escalation timestamp.

## In Scope
- Domain transition validation.
- Approval record persistence or association.
- Audit event creation.
- Notification trigger.
- API response field addition if backward-compatible.
- Unit/integration/contract tests.

## Out of Scope
- New UI workflow.
- Bulk migration of historical cases unless required by API contract.
- Changing unrelated case states.
- Replacing notification infrastructure.
- Rewriting state machine framework.

## Invariants
- A case cannot enter Formal Investigation without supervisor approval.
- Escalation reason must be immutable after transition.
- Audit event must be generated exactly once per successful transition.
- Failed transition must not send notification.
- API addition must be backward-compatible.

## Verification
- Unit tests for transition guard.
- Integration test for approval persistence + audit event.
- Test notification is emitted after successful transition only.
- Contract/API test for audit timestamp field.
- Regression test for other transitions.

## Stop Conditions
- Public API requires breaking change.
- Historical data migration is needed.
- Authorization model is unclear.
- Notification side effect cannot be made idempotent.
- Change touches more than expected bounded modules.

Analyze the task contract and propose implementation options.

Do not write code yet.

For each option, include:
1. Files/modules likely affected.
2. Domain model changes.
3. Persistence changes.
4. API compatibility impact.
5. Notification behavior.
6. Test strategy.
7. Failure modes.
8. Rollback/forward-fix implications.
9. Recommendation.

Separate confirmed facts from assumptions.
Ask questions only if the implementation would be unsafe without the answer.

# ADR: Formal Investigation Escalation Approval Policy

## Status
Accepted

## Context
Formal Investigation escalation is a regulatory-sensitive transition. The system must preserve supervisor approval evidence, escalation reason, audit timestamp, and notification behavior.

## Decision
Implement a dedicated FormalInvestigationEscalationPolicy invoked by the case transition service. On successful transition, persist approval evidence and escalation metadata in the transition/audit model. Publish a domain event after commit to notify the assigned investigation team. Extend the audit API with a backward-compatible field for formal investigation escalation timestamp.

## Consequences
- Transition invariants remain centralized through the transition service.
- Formal Investigation-specific rules are isolated in a policy component.
- Notification happens after successful persistence, reducing false notification risk.
- API consumers receive additional field without breaking existing clients.
- Future jurisdiction-specific escalation rules can be added behind the policy boundary.

## Alternatives Considered
- Put all logic directly inside transition service.
- Build a new orchestration workflow.
- Store approval only as free-text transition metadata.

Implement Slice 1 only.

Goal:
- Add FormalInvestigationEscalationPolicy.
- Enforce supervisor approval presence for transition into Formal Investigation.

Constraints:
- Do not change persistence schema.
- Do not send notifications.
- Do not change API responses.
- Keep diff small.

Tests:
- Missing approval rejects transition.
- Valid approval allows transition.
- Other transitions remain unaffected.

Stop:
- If transition service design requires broader rewrite.

You are implementing one bounded slice.

Task:
- <slice goal>

Relevant context:
- <files/classes/modules>

Constraints:
- Keep diff minimal.
- Preserve existing conventions.
- Do not alter unrelated behavior.
- Do not weaken tests.
- Do not disable checks.

Expected output:
1. Brief plan.
2. Files changed.
3. Implementation diff.
4. Tests added/updated.
5. Commands run.
6. Known limitations.

Stop if:
- You need to change public API outside the requested slice.
- You find conflicting domain behavior.
- The change spans unrelated modules.

Generate tests for the behavior matrix below.

Rules:
- Tests must assert externally observable behavior.
- Avoid brittle assertions on private implementation details.
- Include negative tests.
- Include regression tests for unrelated transitions.
- Do not add weak tests that only verify mocks were called unless the mock represents an external boundary.

Behavior matrix:
<paste matrix>

assertNotNull(result);

assertThat(result.status()).isEqualTo(CaseStatus.FORMAL_INVESTIGATION);
assertThat(result.escalationReason()).isEqualTo("Evidence threshold met");
assertThat(auditEvents).containsExactlyOnce(eventMatching("FORMAL_INVESTIGATION_ESCALATED"));

Review this diff as a senior engineer.

Focus:
- domain invariants;
- transaction boundary;
- idempotency;
- notification ordering;
- API backward compatibility;
- audit evidence;
- test sufficiency;
- unintended scope expansion;
- security/authorization risk.

Classify each finding:
- blocker;
- major;
- minor;
- suggestion.

Do not invent facts. If context is missing, say what needs inspection.

Analyze this CI failure.

Inputs:
- Branch diff summary: <summary>
- Failed command: <command>
- Error log: <log>
- Relevant tests: <test files>

Tasks:
1. Classify failure as related, unrelated, flaky, environment, or unknown.
2. Identify minimal failing behavior.
3. Propose smallest fix.
4. State whether test or implementation should change.
5. Do not weaken assertions or skip tests.

## Summary
Adds supervisor approval enforcement for Formal Investigation escalation, persists escalation evidence, emits notification after successful transition, and exposes escalation timestamp in audit API.

## Scope
- Formal Investigation transition policy
- Approval persistence/audit metadata
- Notification event after commit
- Audit API timestamp field
- Tests and documentation

## Out of Scope
- UI workflow
- Historical case migration
- State machine rewrite
- New notification provider

## Design Decision
See ADR: Formal Investigation Escalation Approval Policy.

## Test Evidence
- Unit: transition rejects missing approval
- Unit: other transitions unaffected
- Integration: approval + reason persisted
- Integration: audit event generated exactly once
- Integration: failed transition does not notify
- Contract/API: audit timestamp exposed backward-compatibly

Commands run:
- ./scripts/test-unit.sh
- ./scripts/test-integration.sh --module case-management
- ./scripts/verify-pr.sh

## Risk
Medium-high. Touches state transition, audit, notification, and API output.

## Rollout
Backward-compatible API addition. No destructive migration. Monitor escalation errors and notification failures.

## AI Assistance Disclosure
AI was used for design option exploration, test matrix drafting, implementation assistance for bounded slices, and pre-review checklist generation. Human author reviewed and accepted all changes.

Formal Investigation escalation now requires supervisor approval evidence. The system preserves the escalation reason, records the escalation timestamp for audit consumers, and notifies the assigned investigation team after successful escalation.

## Formal Investigation Escalation Failures

### Symptoms
- Case escalation request rejected.
- No notification sent to investigation team.
- Audit API missing Formal Investigation timestamp.

### Common Causes
- Supervisor approval missing.
- Supervisor approval actor lacks permission.
- Case not in a state eligible for Formal Investigation.
- Notification provider unavailable after successful transition.

### Checks
1. Verify case transition history.
2. Verify approval record exists.
3. Verify audit event was created.
4. Verify notification event was published.
5. Check retry/dead-letter queue for notification failure.

### Recovery
- Do not manually edit case status.
- If transition failed, resubmit with valid approval.
- If notification failed after successful transition, replay notification event if idempotency key is present.

# Governance Evidence Pack

## Change
Formal Investigation escalation approval enforcement.

## Risk Classification
Medium-high.

## Data Impact
No new customer data class introduced. Approval metadata stored as regulatory audit evidence.

## Security Impact
Requires supervisor approval. Authorization verified through existing approval/identity model.

## API Impact
Backward-compatible audit API field addition.

## Migration Impact
No destructive migration. Historical data behavior documented.

## Test Evidence
See PR test evidence.

## Rollback/Forward-Fix
Feature can be disabled only if policy is behind configuration. Otherwise forward-fix required because persisted audit behavior must remain consistent.

## Human Accountability
Author: <engineer>
Reviewer: <reviewer>
Approver: <approver>

## AI Usage
AI assisted design exploration, implementation drafting, test matrix, and pre-review checklist. Human engineer reviewed all outputs.

Analyze this AI-assisted delivery workflow.

Inputs:
- Task contract
- PR diff summary
- Review comments
- CI failures
- Test evidence
- Time spent

Output:
1. What AI accelerated.
2. What AI made worse.
3. Where context was missing.
4. Which prompt/template should be improved.
5. Which guardrail should be added.
6. Whether this task type is safe for future agentic delegation.