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/31-trello-powerup-implementation-guide.md (7608B)

# Trello Power-Up Implementation Guide

Status: living guide
Current version: 0.4.5
Last updated: July 7, 2026

This guide records the Trello Power-Up work completed so far. Keep this file updated as new features are added, then use it as the final documentation guide when the build is complete.

## Goal

The Power-Up applies the COSMIC AI-Risk methodology directly inside Trello. It lets a team assess AI project risk from a card, save assessment history, review score trends, see board-level analytics, export evidence, and triage cards that need risk review.

## Main Files

| Area | Files |
| --- | --- |
| API server | `src/server.js` |
| Risk scoring | `src/riskEngine.js` |
| Assessment analytics, trends, exports, review queue | `src/assessmentAnalytics.js` |
| JSON persistence | `src/store.js` |
| Trello Power-Up capabilities | `public/powerup.js` |
| Assessment modal | `public/risk-modal.js`, `public/risk-modal.html` |
| Card back section | `public/card-section.js`, `public/card-section.html` |
| Board dashboard | `public/board-dashboard.js`, `public/board-dashboard.html` |
| Settings | `public/settings.js`, `public/settings.html` |
| Shared frontend helpers/styles | `public/client-utils.js`, `public/styles.css` |
| API contract | `openapi.yaml` |
| Tests and smoke test | `test/*.test.mjs`, `scripts/smoke-test.mjs` |

## Features Completed

### 1. Edit Existing Assessment and Risk History

- Latest assessment is loaded back into the assessment modal.
- Each save creates a new assessment history entry.
- Card history is returned newest first.
- Score trend metadata is calculated for each assessment:
  - `previousScore`
  - `scoreDelta`
  - `trend`: `new`, `improved`, `worse`, or `unchanged`
- Card back section shows an expandable assessment history timeline.

### 2. JSON-Backed Local Persistence

- Replaced in-memory-only storage with JSON file persistence.
- Default store path is `./data/store.json`.
- Store path can be overridden with `COSMIC_STORE_FILE`.
- Health endpoint reports store mode, file path, and object counts.
- `data/` is ignored because it contains local runtime data.

### 3. Board Dashboard and Exports

- Board dashboard summarizes latest assessment per card.
- Dashboard includes risk distribution, average score, deployment blocked count, trend snapshot, last assessed context, and review-needed count.
- Filters support search, risk status, gate status, trend, and review state.
- Board exports are available as JSON and CSV:
  - `/api/boards/{boardId}/export.json`
  - `/api/boards/{boardId}/export.csv`

### 4. Review Queue Workflow

- Review signal is generated from latest assessment state.
- A card needs review when:
  - deployment gate is blocked
  - risk score worsened
  - assessment is stale
- Stale threshold is configured with `COSMIC_REVIEW_STALE_DAYS` and defaults to `30`.
- Review signal includes:
  - `needed`
  - `reasons`
  - `actions`
  - `stale`
  - `ageDays`
  - `staleAfterDays`
- Recommended actions are generated from review reasons.
- Dedicated review queue endpoint returns only cards needing review:
  - `/api/boards/{boardId}/review-queue`
- Focused review queue CSV export:
  - `/api/boards/{boardId}/review-queue.csv`
- Dashboard includes a Review Queue panel with a queue export button.
- Trello card badges and card-detail badges show review-needed status.
- Card back and modal show review reasons and next actions.

### 5. Trello Workflow Integrations

- Trello Power-Up supports board button, card button, card badges, card-detail badges, settings, and card back section.
- Assessment modal saves COSMIC assessment data to the API.
- Optional Trello label synchronization adds COSMIC labels for risk status and gate status.
- Mitigation checklist can be created on a card.
- Mitigation completeness can be synced from the `COSMIC Risk Mitigation` checklist.
- Assessment summary comments can be posted to Trello cards.

### 6. Templates and Defaults

- Board settings support default typology, lifecycle phase, and measurement maturity.
- New assessments use board defaults when no saved assessment exists.
- Risk templates are available for common AI risks:
  - data quality
  - model drift
  - bias/fairness
  - deployment rollback
  - legal/ethical review

## API Endpoints

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/api/health` | Service status and store metadata |
| GET | `/api/taxonomy` | COSMIC reference taxonomy |
| POST | `/api/risks/score` | Score without saving |
| POST | `/api/boards/{boardId}` | Upsert board metadata |
| POST | `/api/cards/{cardId}` | Upsert card metadata |
| POST | `/api/boards/{boardId}/cards/{cardId}/assessments` | Save card assessment |
| DELETE | `/api/boards/{boardId}/cards/{cardId}/assessments` | Remove a card assessment history and clear it from dashboard results |
| GET | `/api/boards/{boardId}/cards/{cardId}/assessments/latest` | Read latest card assessment scoped to the active board |
| GET | `/api/cards/{cardId}/assessments/latest` | Read latest card assessment |
| GET | `/api/cards/{cardId}/assessments` | Read card assessment history |
| GET | `/api/boards/{boardId}/summary` | Board analytics summary |
| GET | `/api/boards/{boardId}/review-queue` | Review-needed card queue |
| GET | `/api/boards/{boardId}/review-queue.csv` | Focused review queue CSV |
| GET | `/api/boards/{boardId}/export.json` | Board evidence package JSON |
| GET | `/api/boards/{boardId}/export.csv` | Board evidence package CSV |

## Configuration

```env
PORT=3000
PUBLIC_BASE_URL=https://your-public-powerup-domain.example.com
TRELLO_API_KEY=replace_with_power_up_api_key
TRELLO_APP_NAME=COSMIC AI-Risk Management
ALLOWED_ORIGINS=https://trello.com,https://*.trello.com,http://localhost:3000
COSMIC_STORE_FILE=./data/store.json
COSMIC_REVIEW_STALE_DAYS=30
```

## Validation Commands

Run static checks:

```bash
npm run lint
```

Run unit tests:

```bash
npm test
```

Run smoke test while the server is running:

```bash
npm run smoke
```

Current validation status:

- `npm run lint` passes.
- `npm test` passes with 9 tests.
- `npm run smoke` passes with version `0.4.5`.
- Smoke test verifies health, scoring, save assessment, board summary, review queue, review queue CSV, JSON export, and CSV export.

## Test Coverage Added

- Risk engine scoring and gate behavior.
- Assessment history ordering.
- Review signal generation for blocked, worsened, and stale assessments.
- Board summary review counts.
- Board CSV review fields.
- Review queue filtering and urgency ordering.
- Review queue CSV export.

## VPS Deployment

A VPS deployment guide is available at docs/32-vps-deployment-guide.md. It covers Docker Compose, .env, Nginx, HTTPS, and Trello Power-Up admin setup.

## Current Known Constraints

- JSON file storage is suitable for local prototype validation, not multi-user production.
- Production should replace JSON storage with a database such as PostgreSQL.
- Trello live behavior requires public HTTPS hosting and a real Power-Up API key.
- Automated tests do not call live Trello APIs.
- Review stale-age calculation depends on assessment `createdAt` timestamps.

## Final Documentation Checklist

Before calling the project done, update this guide with:

- Final version number.
- Final feature list.
- Final validation output.
- Screens or demo notes if needed.
- Any production deployment notes.
- Any known limitations and future work.

cmd: