/home/techb158/balavpn.abdallabala.com/docs
Edit: /home/techb158/balavpn.abdallabala.com/docs/10-step-4-mitigation-workflow.md (3996B)
# Step 4: Mitigation Workflow Management
## Purpose
Step 4 turns mitigation actions into a first-class workflow. Earlier versions allowed a mitigation to be added from the risk register. This step adds a dedicated mitigation page and backend support for managing mitigation progress, effectiveness, evidence, and residual-risk impact.
## Source alignment
The source deck defines COSMIC-Risk as a measurable AI project risk framework. It also identifies the need for ISO-style indicators, risk analysis software, API architecture, and integration with project-management tools. The detailed mitigation workflow implemented here is a software design extension that operationalizes those concepts.
## Implemented use cases
| Use case | Status |
|---|---|
| View mitigation dashboard | Implemented |
| Search mitigation actions | Implemented |
| Filter mitigation actions by status | Implemented |
| Create mitigation action | Implemented |
| Edit mitigation action | Implemented |
| Mark mitigation as done | Implemented |
| Delete mitigation action | Implemented |
| Link evidence to mitigation | Implemented |
| Recalculate residual risk after mitigation change | Implemented |
| Reflect mitigation progress in deployment gate | Implemented |
## UI changes
New navigation item:
```text
Mitigations
```
New dashboard section:
```text
viewMitigations
```
The page includes:
- Mitigation actions summary.
- Average mitigation progress.
- Average mitigation effectiveness.
- Overdue mitigation count.
- Mitigation table with linked risk, owner, due date, progress, effectiveness, evidence, and residual-risk impact.
## Backend changes
New or extended repository methods:
| Method | Purpose |
|---|---|
| listMitigations(projectId) | Return enriched project mitigation list |
| getMitigation(mitigationId) | Read one mitigation action |
| createMitigation(riskId, payload) | Create mitigation and optional evidence |
| updateMitigation(mitigationId, payload) | Update mitigation and optional evidence |
| deleteMitigation(mitigationId) | Delete mitigation and linked mitigation evidence |
| addEvidenceToMitigation(mitigationId, payload) | Add evidence to a mitigation action |
## API changes
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/projects/{projectId}/mitigations | List project mitigations |
| POST | /api/risks/{riskId}/mitigations | Create mitigation action |
| GET | /api/mitigations/{mitigationId} | Read one mitigation action |
| PATCH | /api/mitigations/{mitigationId} | Update mitigation action |
| DELETE | /api/mitigations/{mitigationId} | Delete mitigation action |
| POST | /api/mitigations/{mitigationId}/evidence | Add mitigation evidence |
## Database model change
The `evidence_artifacts` entity now supports an optional mitigation link:
```sql
mitigation_id TEXT REFERENCES mitigation_actions(id) ON DELETE SET NULL
```
This keeps evidence usable at both levels:
1. Risk-level evidence.
2. Mitigation-level evidence.
## Residual-risk logic
The mitigation workflow feeds the existing residual-risk calculation:
```text
Residual score = normalized score x (1 - mitigation progress x mitigation effectiveness)
```
The project dashboard recalculates after each mitigation create, update, mark done, or delete action.
## Validation
Added test file:
```text
tests/mitigation-workflow.test.js
```
The test verifies:
- Mitigation creation.
- Evidence creation.
- Mitigation update.
- Residual-risk reduction.
- Mitigation list enrichment.
- Mitigation deletion.
Run:
```bash
npm test
```
Expected output:
```text
All COSMIC AI-Risk engine tests passed.
All COSMIC AI-Risk storage layer tests passed.
All COSMIC AI-Risk mitigation workflow tests passed.
All COSMIC AI-Risk API workflow tests passed.
```
## Next recommended step
Step 5 should implement deployment gate workflow controls:
- Reviewer decision form.
- Gate history page.
- Gate criteria override notes.
- Approval, rejection, or acceptance workflow.
- Audit trail view.
