FM / docs

/home/techb158/trellopowerup.abdallabala.com/docs/

/home/techb158/trellopowerup.abdallabala.com/docs

Name	Size	Mode	Actions
00-design-study.md	3678	0644	edit dl rm
01-uml-class-diagram.puml	11869	0644	edit dl rm
02-use-case-diagram.puml	3763	0644	edit dl rm
03-sequence-diagrams.puml	9732	0644	edit dl rm
04-database-entity-model.mmd	7051	0644	edit dl rm
05-database-schema.sql	13372	0644	edit dl rm
06-diagram-preview.html	5021	0644	edit dl rm
07-design-checklist.md	3256	0644	edit dl rm
08-step-2-storage-layer.md	5325	0644	edit dl rm
09-step-3-risk-crud-ui.md	3380	0644	edit dl rm
10-step-4-mitigation-workflow.md	3996	0644	edit dl rm
11-step-5-deployment-gate-workflow.md	2292	0644	edit dl rm
12-step-6-multi-pm-integration.md	3770	0644	edit dl rm
13-step-6-1-microsoft-planner-integration.md	2335	0644	edit dl rm
14-step-7-reporting-export.md	4158	0644	edit dl rm
15-step-7-1-oauth-live-connectors.md	4545	0644	edit dl rm
16-step-8-user-roles-access-control.md	3297	0644	edit dl rm
17-step-9-production-deployment-security.md	4228	0644	edit dl rm
18-step-10-final-academic-submission.md	3199	0644	edit dl rm
19-final-report-draft.md	6814	0644	edit dl rm
20-instructor-submission-checklist.md	3639	0644	edit dl rm
21-demo-script.md	3948	0644	edit dl rm
22-traceability-matrix.md	4847	0644	edit dl rm
23-testing-evidence.md	2961	0644	edit dl rm
24-evaluation-rubric-mapping.md	2910	0644	edit dl rm
25-final-deployment-runbook.md	3214	0644	edit dl rm
26-known-limitations-and-future-work.md	2632	0644	edit dl rm
27-final-qa-checklist.md	2893	0644	edit dl rm
28-demo-rehearsal-script.md	3618	0644	edit dl rm
29-submission-freeze-report.md	2769	0644	edit dl rm
30-final-known-issues.md	1876	0644	edit dl rm
31-trello-powerup-implementation-guide.md	7608	0644	edit dl rm
32-vps-deployment-guide.md	3697	0644	edit dl rm
dashboard-spec.md	3691	0644	edit dl rm
methodology-mapping.md	2471	0644	edit dl rm
next-implementation-step.md	1304	0644	edit dl rm
trello-admin-setup.md	2175	0644	edit dl rm

Edit: /home/techb158/trellopowerup.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.

cmd: