score_governance

Instructions

Implementation Reference

• src/mcp/tools/score-governance.ts:17-86 (handler)

  Main handler for the score_governance tool. Registers the tool via server.tool() with a Zod schema (operation, integrity, accuracy, compliance as inputs). The async handler calls engine.scorer.score() to compute a weighted composite score, records to the forensic ledger, emits telemetry, and returns composite/weights/threshold results.

  export function registerScoreGovernanceTool(server: McpServer, engine: GovernanceEngine): void {
    server.tool(
      'score_governance',
      'Compute weighted governance score from caller-provided Integrity, Accuracy, and Compliance values (0-1). Returns weighted composite and pass/fail against configured thresholds. Scores are caller-assessed — this tool applies weights and thresholds, not independent evaluation.',
      {
        operation: z.string().describe('Name of the operation being scored'),
        integrity: z.number().min(0).max(1).describe('Data integrity score (0.0-1.0)'),
        accuracy: z.number().min(0).max(1).describe('Factual accuracy score (0.0-1.0)'),
        compliance: z.number().min(0).max(1).describe('Regulatory compliance score (0.0-1.0)'),
      },
      { title: 'Score Governance', readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
      async (input) => {
        // Begin forensic ledger entry
        const entry = engine.ledger.begin(
          'score-governance',
          MaiClassification.ADVISORY,
          GiaLayer.MCP,
          'SYSTEM'
        );
        entry.addMetadata('operation', input.operation);
  
        try {
          const auditId = generateAuditId();
          const score = engine.scorer.score(
            { integrity: input.integrity, accuracy: input.accuracy, compliance: input.compliance },
            input.operation,
            auditId
          );
  
          // Record to forensic ledger
          entry.addMetadata('composite', score.composite);
          entry.addMetadata('meetsThreshold', engine.scorer.meetsThreshold(score));
          const completedEntry = entry.complete(score, {
            classification: MaiClassification.ADVISORY,
            confidence: score.composite >= 0.7 ? 0.95 : 0.70,
            rationale: `Governance score computed: ${score.composite.toFixed(3)}`,
            requiresGate: false,
          });
          engine.ledger.record(completedEntry);
  
          // Auto-emit governance telemetry
          engine.telemetryService.emitScoring(entry.id, input.operation, score.composite, engine.scorer.meetsThreshold(score));
          engine.telemetryService.emitToolCall('score_governance', entry.id, 'ADVISORY', true);
  
          return {
            content: [{ type: 'text' as const, text: JSON.stringify({
              composite: score.composite,
              integrity: score.integrity,
              accuracy: score.accuracy,
              compliance: score.compliance,
              weights: score.weights,
              meetsThreshold: engine.scorer.meetsThreshold(score),
              minimumThreshold: 0.70,
              auditId: entry.id,
            }, null, 2) }],
          };
        } catch (error) {
          // Record failure to forensic ledger
          engine.telemetryService.emitToolCall('score_governance', entry.id, 'MANDATORY', false);
          const failedEntry = entry.fail(error instanceof Error ? error : new Error('Scoring failed'), MaiClassification.MANDATORY);
          engine.ledger.record(failedEntry);
  
          if (error instanceof GovernedError) {
            return { content: [{ type: 'text' as const, text: JSON.stringify(error.toPublicResponse()) }], isError: true };
          }
          return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'SCORING_FAILED' }) }], isError: true };
        }
      }
    );
  }

• src/mcp/tools/score-governance.ts:21-26 (schema)

  Input schema for score_governance: operation (string), integrity (0-1), accuracy (0-1), compliance (0-1). Uses Zod validation.

  {
    operation: z.string().describe('Name of the operation being scored'),
    integrity: z.number().min(0).max(1).describe('Data integrity score (0.0-1.0)'),
    accuracy: z.number().min(0).max(1).describe('Factual accuracy score (0.0-1.0)'),
    compliance: z.number().min(0).max(1).describe('Regulatory compliance score (0.0-1.0)'),
  },

• src/mcp/server.ts:94-94 (registration)

  Registration entry in TOOL_REGISTRY array, mapping this tool to the 'public' visibility tier with description 'score_governance'.

  { tier: 'public', register: registerScoreGovernanceTool, description: 'score_governance' },

• src/core/telemetry/governance-telemetry-service.ts:114-168 (helper)

  Telemetry service emits scoring and tool call events for score_governance (lines 58-59 in the handler).

   * Emit after score_governance completes.
   */
  emitScoring(
    auditId: string,
    operation: string,
    composite: number,
    meetsThreshold: boolean
  ): void {
    this.emit({
      eventType: 'scoring_executed',
      sourceTool: 'score_governance',
      sourceAuditId: auditId,
      maiLevel: 'ADVISORY',
      details: `Governance score: ${composite.toFixed(3)} for "${operation}" (${meetsThreshold ? 'PASS' : 'FAIL'})`,
      metadata: { operation, composite, meetsThreshold },
    });
  }
  
  /**
   * Emit after SRT watchdog/diagnose completes.
   */
  emitProbeResult(
    auditId: string,
    category: string,
    passed: boolean,
    probeCount: number
  ): void {
    this.emit({
      eventType: 'probe_completed',
      sourceTool: 'srt_run_watchdog',
      sourceAuditId: auditId,
      maiLevel: 'INFORMATIONAL',
      details: `SRT probe: ${category} — ${passed ? 'PASS' : 'FAIL'} (${probeCount} checks)`,
      metadata: { category, passed, probeCount },
    });
  }
  
  /**
   * Emit a generic governance event (used by record_governance_event tool).
   */
  emitGeneric(
    eventType: string,
    details: string,
    sourceTool?: string,
    sourceAuditId?: string,
    maiLevel?: string,
    metadata?: Record<string, unknown>
  ): void {
    this.emit({
      eventType,
      sourceTool: sourceTool || 'record_governance_event',
      sourceAuditId,
      maiLevel,
      details,
      metadata,

• src/core/audit/telemetry.ts:163-166 (helper)

  Telemetry audit configuration defines score_governance as toolClass 'read', riskTier 'moderate', maiDefault 'ADVISOR'.

  { toolName: 'score_governance',    toolClass: 'read',     riskTier: 'moderate', maiDefault: 'ADVISORY',       requiresHumanApproval: false, category: 'governance' },
  { toolName: 'evaluate_threshold',  toolClass: 'read',     riskTier: 'low',      maiDefault: 'INFORMATIONAL',  requiresHumanApproval: false, category: 'governance' },
  { toolName: 'assess_risk_tier',    toolClass: 'read',     riskTier: 'moderate', maiDefault: 'ADVISORY',       requiresHumanApproval: false, category: 'governance' },
  { toolName: 'map_compliance',      toolClass: 'read',     riskTier: 'low',      maiDefault: 'INFORMATIONAL',  requiresHumanApproval: false, category: 'governance' },