/home/techb158/trellopowerup.abdallabala.com
Edit: /home/techb158/trellopowerup.abdallabala.com/README.md (5167B)
# COSMIC AI-Risk Management Trello Power-Up
Custom Trello Power-Up prototype for applying the COSMIC AI-Risk methodology inside Trello boards.
## Current milestone
Version `0.4.5` is ready for local validation and Trello registration.
It now includes:
- Runtime `/config.js` injection for the Trello API key and public API base URL.
- Trello REST API initialization on the connector page and iframe pages.
- Board button, card button, risk/review card badges, card-detail badges, settings, and card back section.
- COSMIC risk scoring API.
- JSON-backed local storage for boards, cards, and saved assessments.
- Saved card-level assessments with newest-first assessment history, score trend metadata, and an expandable card-back history view.
- Latest assessment prefill when updating a Trello card risk assessment.
- Remove Assessment action to clear a card's saved COSMIC history, dashboard entry, and Trello shared badge data.
- Board-level defaults for project typology, lifecycle phase, and measurement maturity on new assessments.
- Risk templates for common AI risks, including data quality, model drift, bias/fairness, deployment rollback, and legal/ethical review.
- Board summary API with risk distribution, dedicated review queue endpoint, dashboard panel, and focused queue CSV export, recommended review actions, stale-assessment detection, trend snapshot, last-assessed context, highest-risk ordering, dashboard filters/search, and JSON/CSV board exports.
- Optional Trello label synchronization for COSMIC risk and gate status.
- Mitigation checklist creation through Trello REST authorization.
- Mitigation completeness sync from the `COSMIC Risk Mitigation` checklist progress.
- One-click Trello card comments for assessment summary and review evidence.
- Unit tests for the risk engine, assessment history ordering, and review signal analytics.
- Smoke test for the local API, board summary, and export endpoints.
## Implementation guide
A running documentation guide is maintained at docs/31-trello-powerup-implementation-guide.md. Update it at the end of the build with the final feature list, validation results, and deployment notes.
## Methodology implemented
The prototype operationalizes these COSMIC AI-Risk concepts:
- AI lifecycle phases.
- AI project typology.
- Organizational, technical, and human governance dimensions.
- Strategic and organizational, technical, and legal and ethical risk categories.
- Risk scoring using probability, impact, detection difficulty, and mitigation completeness.
- Deployment gate status using risk status, approval state, mitigation completeness, model performance, data readiness, ethical review, and legal review.
The scoring formula is an implementation proposal for the prototype. It should be calibrated during empirical validation.
## Install
```bash
npm install
cp .env.example .env
npm run dev
```
Open:
```text
http://localhost:3000/index.html
```
## Storage
By default, the API stores runtime data in:
```text
./data/store.json
```
Override the storage file with:
```env
COSMIC_STORE_FILE=./data/store.json
```
The `data/` directory is ignored by Git because it contains local runtime data.
## Validate locally
Run static checks and unit tests:
```bash
npm run lint
npm test
```
In one terminal, start the server:
```bash
npm start
```
In a second terminal, run the API smoke test:
```bash
npm run smoke
```
Expected smoke-test result:
```text
health: { ok: true, service: 'cosmic-ai-risk-trello-powerup', version: '0.4.5', store: { mode: 'json-file', ... } }
score: 21 medium gate-blocked
saved assessment:
new
board summary: { cardCount: 1, averageScore: 21, deploymentBlocked: 1 }
json export: cosmic-board-risk-export 1
csv export: "board_id","card_id",...
```
## Trello setup
See `docs/trello-admin-setup.md`.
## API sample
Score an assessment without saving it:
```bash
curl -X POST http://localhost:3000/api/risks/score \
-H "Content-Type: application/json" \
--data @samples/risk-assessment.json
```
Save a card assessment:
```bash
curl -X POST http://localhost:3000/api/boards/demo-board/cards/demo-card/assessments \
-H "Content-Type: application/json" \
--data @samples/risk-assessment.json
```
Remove a card assessment history:
```bash
curl -X DELETE http://localhost:3000/api/boards/demo-board/cards/demo-card/assessments
```
Read a board summary:
```bash
curl http://localhost:3000/api/boards/demo-board/summary
```
Read card assessment history:
```bash
curl http://localhost:3000/api/cards/demo-card/assessments
```
Export board risk reports:
```bash
curl http://localhost:3000/api/boards/demo-board/export.json
curl http://localhost:3000/api/boards/demo-board/export.csv
```
## Important production work still required
- Replace JSON file storage with PostgreSQL or another managed database for multi-user production deployments.
- Add authentication for the COSMIC backend API.
- Add audit logs for governance approvals.
- Calibrate score thresholds with validation data.
- Add custom field synchronization if the board uses Trello Custom Fields.
- Add organization-level role and access controls.
