Scoring

Compute governance scores across 7 dimensions. L0-L4 maturity levels with per-dimension breakdown.

Quantify agent governance maturity across 7 dimensions. Returns a 0-100 score with L0-L4 level classification. Import from governance-sdk/scorer.

Signatures

Function	Signature	Description
`gov.score`	`gov.score(agentId: string) => GovernanceAssessment \| null`	Score a single registered agent by ID.
`gov.scoreFleet`	`gov.scoreFleet() => { assessments, summary }`	Score all registered agents and return fleet-wide summary.

Usage

import { assessAgent, getGovernanceLevel } from 'governance-sdk/scorer';

const assessment = assessAgent('research-agent', {
  name: 'research-agent',
  framework: 'mastra',
  owner: 'platform-team',
  tools: ['web_search', 'db_read'],
  hasAuth: true,
  hasGuardrails: true,
  hasObservability: true,
  hasAuditLog: true,
});

// assessment:
// {
//   compositeScore: 72,
//   level: { level: 3, label: 'Governed' },
//   status: 'approved',
//   dimensions: [
//     { dimension: 'identity', score: 85, weight: 1.5, evidence: {...} },
//     { dimension: 'permissions', score: 70, weight: 1.5, evidence: {...} },
//     { dimension: 'observability', score: 65, weight: 1.2, evidence: {...} },
//     { dimension: 'guardrails', score: 80, weight: 1.3, evidence: {...} },
//     { dimension: 'auditability', score: 60, weight: 1.0, evidence: {...} },
//     { dimension: 'compliance', score: 55, weight: 1.0, evidence: {...} },
//     { dimension: 'lifecycle', score: 40, weight: 0.8, evidence: {...} },
//   ],
// }

Maturity Levels

Level	Name	Score Range	Autonomy
L0	Unregistered	0-20	No autonomous operation
L1	Basic	21-40	Human-in-loop required
L2	Managed	41-60	Limited autonomous actions
L3	Governed	61-80	Full autonomous within policy
L4	Certified	81-100	Cross-team, regulatory-ready

7 Dimensions

Dimension	Max Score	Description
`identity`	100	Name, owner, description, version (weight: 1.5x)
`permissions`	100	Auth, tool scoping, PII access (weight: 1.5x)
`observability`	100	Logging, monitoring, channels (weight: 1.2x)
`guardrails`	100	Input/output guards, framework recognition (weight: 1.3x)
`auditability`	100	Audit logging, event trail (weight: 1.0x)
`compliance`	100	Compliance capabilities (weight: 1.0x)
`lifecycle`	100	Versioning, deprecation readiness (weight: 0.8x)

Note: Each dimension is scored 0-100 independently, then combined into a weighted composite (0-100). Weights range from 0.8x (lifecycle) to 1.5x (identity, permissions). Improving one dimension never decreases another.

Return Type

interface GovernanceAssessment {
  compositeScore: number;        // 0-100 weighted aggregate
  level: GovernanceLevel;        // { level: 0-4, label, autonomy, minScore, maxScore }
  status: AgentStatus;           // 'approved' | 'flagged' | 'registered'
  dimensions: DimensionResult[]; // 7 dimension scores with evidence
  recommendations: string[];     // Improvement suggestions
}

interface DimensionResult {
  dimension: ScoreDimension;     // 'identity' | 'permissions' | ... (7 total)
  score: number;                 // 0-100 for this dimension
  weight: number;                // 0.8-1.5 (contribution to composite)
  evidence: Record<string, boolean | number | string>;
}