AI-SDLC
AI-SDLC
API Reference

Metric

Metrics

Metric collection, storage, querying, and instrumentation wrappers for AI-SDLC operations.

Import

import {
  // Store
  createMetricStore,
  STANDARD_METRICS,
  type MetricStore,
  type MetricDefinition,
  type MetricDataPoint,
  type MetricQuery,
  type MetricSummary,
  type MetricCategory,

  // Instrumentation
  instrumentEnforcement,
  instrumentExecutor,
  instrumentReconciler,
  instrumentAutonomy,
  type InstrumentationConfig,
} from '@ai-sdlc/reference';

Types

MetricCategory

type MetricCategory =
  | 'task-effectiveness'
  | 'human-in-loop'
  | 'code-quality'
  | 'economic-efficiency'
  | 'autonomy-trajectory';

MetricDefinition

interface MetricDefinition {
  name: string;
  category: MetricCategory;
  description: string;
  unit: string;
}

MetricDataPoint

interface MetricDataPoint {
  metric: string;
  value: number;
  timestamp: string;          // ISO-8601
  labels?: Record<string, string>;
}

MetricStore

interface MetricStore {
  register(definition: MetricDefinition): void;
  record(point: Omit<MetricDataPoint, 'timestamp'> & { timestamp?: string }): MetricDataPoint;
  current(metric: string, labels?: Record<string, string>): number | undefined;
  query(query: MetricQuery): readonly MetricDataPoint[];
  summarize(metric: string, labels?: Record<string, string>): MetricSummary | undefined;
  snapshot(labels?: Record<string, string>): Record<string, number>;
  definitions(): readonly MetricDefinition[];
}

Functions

createMetricStore()

Create an in-memory metric store with per-label tracking.

function createMetricStore(): MetricStore;
import { createMetricStore, STANDARD_METRICS } from '@ai-sdlc/reference';

const store = createMetricStore();

// Register standard metrics
for (const def of STANDARD_METRICS) {
  store.register(def);
}

// Record data points
store.record({ metric: 'test-coverage', value: 87.5, labels: { agent: 'code-agent' } });
store.record({ metric: 'approval-rate', value: 0.95, labels: { agent: 'code-agent' } });
store.record({ metric: 'cost-per-task', value: 0.42 });

// Query current values
const coverage = store.current('test-coverage', { agent: 'code-agent' });
console.log(`Coverage: ${coverage}%`);

// Get a summary
const summary = store.summarize('test-coverage');
// { metric: 'test-coverage', count: 1, min: 87.5, max: 87.5, avg: 87.5, latest: 87.5 }

// Snapshot all latest values
const snapshot = store.snapshot();
// { 'test-coverage': 87.5, 'approval-rate': 0.95, 'cost-per-task': 0.42 }

Constants

STANDARD_METRICS

Pre-defined metric definitions from the PRD covering all five categories:

MetricCategoryUnit
task-completion-ratetask-effectivenesspercent
first-pass-success-ratetask-effectivenesspercent
mean-time-to-completiontask-effectivenessseconds
handoff-counttask-effectivenesscount
handoff-failure-ratetask-effectivenesspercent
adapter-health-ratetask-effectivenesspercent
agent-discovery-counttask-effectivenesscount
approval-ratehuman-in-looppercent
revision-counthuman-in-loopcount
human-intervention-ratehuman-in-looppercent
approval-wait-timehuman-in-loopmilliseconds
test-coveragecode-qualitypercent
lint-pass-ratecode-qualitypercent
security-finding-ratecode-qualityper-kloc
sandbox-violation-countcode-qualitycount
compliance-coveragecode-qualitypercent
cost-per-taskeconomic-efficiencyusd
time-saved-ratioeconomic-efficiencyratio
autonomy-levelautonomy-trajectorylevel
promotion-velocityautonomy-trajectorylevels-per-month
demotion-frequencyautonomy-trajectoryper-month
kill-switch-activation-countautonomy-trajectorycount

Instrumentation

Wrappers that automatically record metrics when operations occur.

instrumentEnforcement(store)

Wrap enforcement operations to record gate pass/fail metrics.

instrumentExecutor(store)

Wrap orchestration execution to record step durations and outcomes.

instrumentReconciler(store)

Wrap reconciliation cycles to record timing and error rates.

instrumentAutonomy(store)

Wrap autonomy evaluation to record promotion/demotion events.