P0-2: Control Assessment Agent — Readiness Scoring

[haJ1t]

P0-2: Control Assessment Agent — Readiness Scoring

AI agent that continuously evaluates how ready an organization is for compliance audits. Calculates per-control scores, aggregates to framework/project level, identifies weaknesses, and generates improvement recommendations.

Dependencies

• Phase 0 — Shared Infrastructure (DB Tables, Types, Agent Base) #3596 (Shared Infrastructure) — DB tables, interfaces
• P0-1: Evidence Agent — Document Intelligence #3597 (Evidence Agent) — Quality scores feed into readiness calculation

Tasks

Backend — Scoring Algorithm

• Create Servers/advisor/scoring/readinessCalculator.ts — Deterministic weighted formula:
  • evidence_quality (30%) + evidence_count (20%) + evidence_recency (15%) + task_completion (20%) + risk_mitigation (15%)
• Implement readiness level classification: ready (>=80), needs_work (60-79), at_risk (30-59), not_started (<30)
• Implement framework-level aggregation (avg scores, counts by level, weakest controls)

Backend — Agent and AI Logic

• Create Servers/advisor/agents/controlAssessment.agent.ts — Control Assessment Agent definition
• Create Servers/advisor/tools/readinessTools.ts — Tool schemas
• Create Servers/advisor/functions/readinessFunctions.ts — Tool implementations
• Implement evidence evaluator — per-control evidence count, avg quality, freshness
• Implement task completion checker — linked tasks, completion rate per control
• Implement risk status analyzer — linked risks, mitigation status per control
• Implement recommendation generator — actionable improvement suggestions

Backend — Route / Controller / Utils

• Create Servers/utils/readiness.utils.ts — DB queries (insert/get scores, aggregations, history)
• Create Servers/controllers/readiness.ctrl.ts — Request handling
• Create Servers/routes/readiness.route.ts — 8 endpoints:
  • POST /api/readiness/calculate — Trigger calculation (all frameworks)
  • POST /api/readiness/calculate/:frameworkType — Trigger for specific framework
  • GET /api/readiness/scores — All framework readiness scores
  • GET /api/readiness/scores/:frameworkType — Scores for specific framework
  • GET /api/readiness/controls/:frameworkType — Per-control scores
  • GET /api/readiness/weakest — Weakest controls across all frameworks
  • GET /api/readiness/recommendations — Top improvement recommendations
  • GET /api/readiness/history — Historical readiness scores (trend)
• Register routes in Servers/index.ts
• Add unique constraints migration for upsert support

Frontend — Components

• Create ReadinessScoreCard/ — Score card with overall score, level badge, component breakdown
• Create ReadinessHeatmap/ — Framework heatmap (controls colored by readiness level)
• Create ReadinessTrend/ — Historical trend chart (line chart over time)
• Create WeakControlsList/ — Top weakest controls with recommendations

Frontend — Pages, Hooks, and Integration

• Create Clients/src/presentation/pages/ReadinessDashboard/ — New page at /readiness
• Create Clients/src/application/hooks/useReadiness.ts — React Query hooks
• Create Clients/src/application/repository/readiness.repository.ts — Axios calls
• Add route /readiness in Clients/src/application/config/routes.tsx
• Add readiness score badge to framework pages
• Add control readiness score to control detail pages
• Add overall readiness widget to main dashboard

Scoring Formula

overall = evidence_quality * 0.30
        + evidence_count   * 0.20
        + evidence_recency * 0.15
        + task_completion  * 0.20
        + risk_mitigation  * 0.15

Levels: ready (>=80) | needs_work (60-79) | at_risk (30-59) | not_started (<30)

API Endpoints

Route	Method	Purpose
/api/readiness/calculate	POST	Trigger calculation (all)
/api/readiness/calculate/:frameworkType	POST	Trigger for framework
/api/readiness/scores	GET	All framework scores
/api/readiness/scores/:frameworkType	GET	Framework scores
/api/readiness/controls/:frameworkType	GET	Per-control scores
/api/readiness/weakest	GET	Weakest controls
/api/readiness/recommendations	GET	Top recommendations
/api/readiness/history	GET	Historical trend

Branch

feat/ai-foundation-infra

Assignees

@haJ1t @HarshP4585

---

Part of Phase 0 — Immediate Priority AI Features

[haJ1t]

Control Assessment Agent implemented: readiness calculator, scoring algorithm, recommendation generator, 8 API endpoints, ReadinessDashboard page, frontend components.