kld-sdd 2.6.12 → 2.6.13

package/skywalk-sdd/metrics-v3.cjs

@@ -0,0 +1,1153 @@
+'use strict';
+
+const REPORT_SCHEMA_VERSION = 'sdd-efficiency-report/v3';
+const METRICS_CONTRACT_VERSION = '3.0';
+const CHANGE_TYPES = ['config', 'document', 'report', 'composite', 'other'];
+const MINIMUM_METRICS = ['e1', 'q3', 'p4', 'p_r', 'p_h'];
+
+const ALERT_THRESHOLDS = {
+  q3: { red: 70, yellow: 85, direction: 'higher_better' },
+  p4: { red: 0.4, yellow: 0.6, direction: 'higher_better' },
+  p_h: { red: 60, yellow: 80, direction: 'higher_better' },
+  p_c: { red: 0.75, yellow: 0.85, direction: 'higher_better' },
+};
+
+const DEVELOPMENT_ACTIVITY_TYPES = new Set([
+  'task_update',
+  'build_result',
+  'test_result',
+  'ai_adoption_review',
+  'doc_update',
+]);
+
+const DETERMINISTIC_REWORK_REASONS = new Set([
+  'incomplete',
+  'prev-failed',
+  'pre-archive-recheck',
+]);
+
+const AGENT_OVERRIDE_REASONS = new Set([
+  'incomplete',
+  'prev-failed',
+  'pre-archive-recheck',
+  'code-changed-after-pass',
+  'recheck-no-change',
+  'unspecified',
+]);
+
+const SCENARIO_HEADING_RE = /^#####\s+(场景|Scenario)\s*[：:]/gm;
+
+function createInvalidArgError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function clamp(n, min, max) {
+  if (!Number.isFinite(n)) return n;
+  return Math.min(max, Math.max(min, n));
+}
+
+function round(n, digits = 4) {
+  if (!Number.isFinite(n)) return n;
+  const factor = 10 ** digits;
+  return Math.round(n * factor) / factor;
+}
+
+function percentile(sortedOrUnsortedValues, p) {
+  if (!Array.isArray(sortedOrUnsortedValues)) {
+    throw createInvalidArgError('invalid-arg', 'percentile expects an array');
+  }
+  const finite = sortedOrUnsortedValues.filter(v => Number.isFinite(v));
+  if (finite.length === 0) return null;
+  const sorted = [...finite].sort((a, b) => a - b);
+  if (p <= 0) return sorted[0];
+  if (p >= 100) return sorted[sorted.length - 1];
+  const rank = (p / 100) * (sorted.length - 1);
+  const lower = Math.floor(rank);
+  const upper = Math.ceil(rank);
+  if (lower === upper) return sorted[lower];
+  const weight = rank - lower;
+  return sorted[lower] + weight * (sorted[upper] - sorted[lower]);
+}
+
+function mean(values) {
+  if (!values.length) return null;
+  return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+
+function detectIqrOutliers(values) {
+  const finite = (values || []).filter(v => Number.isFinite(v));
+  if (finite.length < 4) return [];
+  const q1 = percentile(finite, 25);
+  const q3 = percentile(finite, 75);
+  const iqr = q3 - q1;
+  const lower = q1 - 1.5 * iqr;
+  const upper = q3 + 1.5 * iqr;
+  return finite.filter(v => v < lower || v > upper);
+}
+
+function summarizeDistribution(values) {
+  const finite = (values || []).filter(v => Number.isFinite(v));
+  const count = finite.length;
+  const meanRaw = count > 0 ? round(mean(finite)) : null;
+  if (count < 4) {
+    return {
+      count,
+      p50: count > 0 ? round(percentile(finite, 50)) : null,
+      p75: count > 0 ? round(percentile(finite, 75)) : null,
+      p90: count > 0 ? round(percentile(finite, 90)) : null,
+      mean_raw: meanRaw,
+      mean_adjusted: meanRaw,
+      outliers: [],
+    };
+  }
+  const outliers = detectIqrOutliers(finite);
+  const outlierSet = new Set(outliers);
+  const adjusted = finite.filter(v => !outlierSet.has(v));
+  return {
+    count,
+    p50: round(percentile(finite, 50)),
+    p75: round(percentile(finite, 75)),
+    p90: round(percentile(finite, 90)),
+    mean_raw: meanRaw,
+    mean_adjusted: adjusted.length > 0 ? round(mean(adjusted)) : meanRaw,
+    outliers: outliers.map(v => round(v)),
+  };
+}
+
+function countScenariosInMarkdown(text) {
+  if (typeof text !== 'string' || !text) return 0;
+  const normalized = text.replace(/\r\n/g, '\n');
+  const matches = normalized.match(SCENARIO_HEADING_RE);
+  return matches ? matches.length : 0;
+}
+
+function validateChangeType(value) {
+  if (typeof value !== 'string') return 'unknown';
+  const normalized = value.trim().toLowerCase();
+  return CHANGE_TYPES.includes(normalized) ? normalized : 'unknown';
+}
+
+function resolveReviewerIndependence(meta = {}) {
+  if (meta.reviewer_independence === 'independent-review'
+    || meta.reviewer_independence === 'self-review'
+    || meta.reviewer_independence === 'unknown') {
+    return meta.reviewer_independence;
+  }
+  if (meta.reviewer_independence) return 'unknown';
+  if (meta.reviewer && meta.author && meta.reviewer !== meta.author) {
+    return 'independent-review';
+  }
+  if (meta.reviewer && meta.author && meta.reviewer === meta.author) {
+    return 'self-review';
+  }
+  return 'unknown';
+}
+
+function resolveScoreStatus(reviewerIndependence, meta = {}) {
+  if (reviewerIndependence !== 'independent-review') return 'provisional';
+  const reviewSession = meta.review_session_id || meta.reviewer_session_id || null;
+  const authorSession = meta.author_session_id || null;
+  if (reviewSession && authorSession && reviewSession !== authorSession) {
+    return 'verified';
+  }
+  return 'provisional';
+}
+
+function computeSpecQualityScore(checkResults, meta = {}) {
+  if (!checkResults || typeof checkResults !== 'object') {
+    return {
+      q3_spec_quality_score: null,
+      category_scores: {},
+      reviewer_independence: resolveReviewerIndependence(meta),
+      score_status: 'provisional',
+      availability: false,
+      availability_reason: 'invalid-total',
+      warnings: 0,
+      suggestions: 0,
+    };
+  }
+
+  const total = Number.isFinite(checkResults.total) ? checkResults.total : null;
+  const errors = Number.isFinite(checkResults.errors) ? checkResults.errors : 0;
+  const warnings = Number.isFinite(checkResults.warnings) ? checkResults.warnings : 0;
+  const suggestions = Number.isFinite(checkResults.suggestions) ? checkResults.suggestions : 0;
+
+  if (total === null || total <= 0) {
+    const reviewerIndependence = resolveReviewerIndependence(meta);
+    return {
+      q3_spec_quality_score: null,
+      category_scores: {},
+      reviewer_independence: reviewerIndependence,
+      score_status: resolveScoreStatus(reviewerIndependence, meta),
+      availability: false,
+      availability_reason: 'invalid-total',
+      warnings,
+      suggestions,
+    };
+  }
+
+  const categoryScores = {};
+  const categories = checkResults.categories && typeof checkResults.categories === 'object'
+    ? checkResults.categories
+    : {};
+  for (const [name, entry] of Object.entries(categories)) {
+    if (!entry || typeof entry !== 'object') continue;
+    const catTotal = Number.isFinite(entry.total) ? entry.total : null;
+    const passed = Number.isFinite(entry.passed) ? entry.passed : null;
+    if (catTotal === null || catTotal <= 0 || passed === null) continue;
+    categoryScores[name] = round(clamp((passed / catTotal) * 100, 0, 100));
+  }
+
+  const reviewerIndependence = resolveReviewerIndependence(meta);
+  const scoreStatus = resolveScoreStatus(reviewerIndependence, meta);
+  const q3 = round(clamp(((total - errors) / total) * 100, 0, 100));
+
+  return {
+    q3_spec_quality_score: q3,
+    category_scores: categoryScores,
+    reviewer_independence: reviewerIndependence,
+    score_status: scoreStatus,
+    availability: true,
+    availability_reason: null,
+    warnings,
+    suggestions,
+    total,
+    errors,
+  };
+}
+
+function computeScenarioDeliveryEfficiency({ total_stage_duration_ms, scenario_count, scenario_sources }) {
+  const total = Number.isFinite(total_stage_duration_ms) ? total_stage_duration_ms : null;
+  const count = Number.isFinite(scenario_count) ? scenario_count : 0;
+
+  if (count <= 0) {
+    return {
+      e1_scenario_delivery_efficiency_ms: null,
+      scenario_count: count,
+      total_stage_duration_ms: total,
+      scenario_sources: scenario_sources || [],
+      availability: false,
+      availability_reason: 'no-scenarios',
+    };
+  }
+
+  if (total === null || total < 0) {
+    return {
+      e1_scenario_delivery_efficiency_ms: null,
+      scenario_count: count,
+      total_stage_duration_ms: total,
+      scenario_sources: scenario_sources || [],
+      availability: false,
+      availability_reason: 'invalid-duration',
+    };
+  }
+
+  return {
+    e1_scenario_delivery_efficiency_ms: round(total / count),
+    scenario_count: count,
+    total_stage_duration_ms: total,
+    scenario_sources: scenario_sources || [],
+    availability: true,
+    availability_reason: null,
+  };
+}
+
+function metricAvailable(value) {
+  return Number.isFinite(value);
+}
+
+function buildPendingUpstreamMetric(value, source) {
+  if (metricAvailable(value)) {
+    return { value: round(value), status: 'available', source: source || null };
+  }
+  return { value: null, status: 'pending-upstream', source: source || null };
+}
+
+function computeV3ChangeMetrics(context = {}) {
+  if (!context || typeof context !== 'object') {
+    throw createInvalidArgError('invalid-arg', 'computeV3ChangeMetrics expects a context object');
+  }
+
+  const changeType = validateChangeType(context.change_type);
+  const e1 = computeScenarioDeliveryEfficiency({
+    total_stage_duration_ms: context.total_stage_duration_ms,
+    scenario_count: context.scenario_count,
+    scenario_sources: context.scenario_sources,
+  });
+
+  const q3Result = context.q3 && typeof context.q3 === 'object' && 'q3_spec_quality_score' in context.q3
+    ? context.q3
+    : computeSpecQualityScore(context.check_results, context.check_meta);
+
+  const totalStageDuration = Number.isFinite(context.total_stage_duration_ms)
+    ? context.total_stage_duration_ms
+    : null;
+  const codingDuration = Number.isFinite(context.coding_duration_ms) ? context.coding_duration_ms : 0;
+  const specDuration = Number.isFinite(context.spec_duration_ms) ? context.spec_duration_ms : 0;
+  const reworkCodingDuration = Number.isFinite(context.rework_coding_duration_ms)
+    ? context.rework_coding_duration_ms
+    : 0;
+  const reworkSpecDuration = Number.isFinite(context.rework_spec_duration_ms)
+    ? context.rework_spec_duration_ms
+    : 0;
+
+  const ratio = (numerator) => (
+    totalStageDuration > 0 ? round(numerator / totalStageDuration) : null
+  );
+
+  const p4 = Number.isFinite(context.p4_quality_gate_enforcement_rate)
+    ? context.p4_quality_gate_enforcement_rate
+    : null;
+  const pC = Number.isFinite(context.p_c_stage_closure_rate)
+    ? context.p_c_stage_closure_rate
+    : null;
+  const pH = Number.isFinite(context.p_h_telemetry_health_score)
+    ? context.p_h_telemetry_health_score
+    : null;
+
+  const reworkSummary = context.rework_summary && typeof context.rework_summary === 'object'
+    ? context.rework_summary
+    : {};
+  const pRAvg = Number.isFinite(reworkSummary.avg_rework_count)
+    ? reworkSummary.avg_rework_count
+    : (Number.isFinite(reworkSummary.total_rework_attempts) ? reworkSummary.total_rework_attempts : null);
+
+  return {
+    change_name: context.change_name || null,
+    change_type: changeType,
+    efficiency: {
+      e1_scenario_delivery_efficiency_ms: e1.e1_scenario_delivery_efficiency_ms,
+      scenario_count: e1.scenario_count,
+      total_stage_duration_ms: e1.total_stage_duration_ms,
+      canonical_stage_duration_ms: context.canonical_stage_duration_ms ?? null,
+      rework_stage_duration_ms: context.rework_stage_duration_ms ?? null,
+      scenario_sources: e1.scenario_sources,
+      e1_availability: e1.availability,
+      e1_availability_reason: e1.availability_reason,
+      e2_coding_time_ratio: context.e2_coding_time_ratio ?? ratio(codingDuration),
+      e3_spec_time_ratio: context.e3_spec_time_ratio ?? ratio(specDuration),
+      e2_coding_time_ratio_including_rework: context.e2_coding_time_ratio_including_rework
+        ?? ratio(codingDuration + reworkCodingDuration),
+      e3_spec_time_ratio_including_rework: context.e3_spec_time_ratio_including_rework
+        ?? ratio(specDuration + reworkSpecDuration),
+    },
+    quality: {
+      q3_spec_quality_score: q3Result.q3_spec_quality_score,
+      q3_category_scores: q3Result.category_scores,
+      q3_reviewer_independence: q3Result.reviewer_independence,
+      q3_score_status: q3Result.score_status,
+      q3_availability: q3Result.availability,
+      q3_availability_reason: q3Result.availability_reason,
+      q1_spec_conformance: buildPendingUpstreamMetric(context.q1_spec_conformance, context.q1_source),
+      q4_tdd_coverage: buildPendingUpstreamMetric(context.q4_tdd_coverage, context.q4_source),
+    },
+    process: {
+      p4_quality_gate_enforcement_rate: p4,
+      p_c_stage_closure_rate: pC,
+      rework_summary: {
+        total_rework_attempts: reworkSummary.total_rework_attempts ?? null,
+        avg_rework_count: pRAvg,
+        reasons: reworkSummary.reasons || reworkSummary.by_category || {},
+      },
+    },
+    telemetry_health: {
+      p_h_telemetry_health_score: pH,
+    },
+  };
+}
+
+function pickMetricValue(changeMetric, metricKey) {
+  if (!changeMetric || typeof changeMetric !== 'object') return null;
+  switch (metricKey) {
+    case 'e1':
+      return changeMetric.efficiency?.e1_scenario_delivery_efficiency_ms ?? null;
+    case 'q3':
+      return changeMetric.quality?.q3_spec_quality_score ?? null;
+    case 'p4':
+      return changeMetric.process?.p4_quality_gate_enforcement_rate ?? null;
+    case 'p_r':
+      return changeMetric.process?.rework_summary?.avg_rework_count
+        ?? changeMetric.process?.rework_summary?.total_rework_attempts
+        ?? null;
+    case 'p_h':
+      return changeMetric.telemetry_health?.p_h_telemetry_health_score ?? null;
+    case 'p_c':
+      return changeMetric.process?.p_c_stage_closure_rate ?? null;
+    default:
+      return null;
+  }
+}
+
+function aggregateByChangeType(changeMetrics, metricSelector, options = {}) {
+  if (!Array.isArray(changeMetrics)) {
+    throw createInvalidArgError('invalid-arg', 'aggregateByChangeType expects changeMetrics array');
+  }
+  const selector = typeof metricSelector === 'function'
+    ? metricSelector
+    : (metric) => pickMetricValue(metric, metricSelector);
+
+  const includeUnknown = options.includeUnknown !== false;
+  const grouped = new Map();
+
+  for (const metric of changeMetrics) {
+    const changeType = validateChangeType(metric.change_type);
+    if (!includeUnknown && changeType === 'unknown') continue;
+    if (!grouped.has(changeType)) grouped.set(changeType, []);
+    const value = selector(metric);
+    if (Number.isFinite(value)) grouped.get(changeType).push(value);
+  }
+
+  const result = {};
+  for (const [changeType, values] of grouped.entries()) {
+    result[changeType] = summarizeDistribution(values);
+  }
+  return result;
+}
+
+function aggregateV3Metrics(changeMetrics, options = {}) {
+  if (!Array.isArray(changeMetrics)) {
+    throw createInvalidArgError('invalid-arg', 'aggregateV3Metrics expects changeMetrics array');
+  }
+
+  const metricKeys = options.metricKeys || ['e1', 'q3', 'p4', 'p_r', 'p_h', 'p_c'];
+  const byChangeType = {};
+  const distribution = {};
+
+  for (const key of metricKeys) {
+    byChangeType[key] = aggregateByChangeType(changeMetrics, key, options);
+    const allValues = changeMetrics
+      .map(m => pickMetricValue(m, key))
+      .filter(v => Number.isFinite(v));
+    distribution[key] = summarizeDistribution(allValues);
+  }
+
+  const unknownCount = changeMetrics.filter(m => validateChangeType(m.change_type) === 'unknown').length;
+
+  return {
+    by_change: changeMetrics,
+    by_change_type: byChangeType,
+    distribution,
+    unknown_change_type_count: unknownCount,
+    change_count: changeMetrics.length,
+  };
+}
+
+function parseIsoDate(dateStr) {
+  if (typeof dateStr !== 'string') return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr.trim());
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  const day = Number(match[3]);
+  const date = new Date(Date.UTC(year, month, day));
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month || date.getUTCDate() !== day) {
+    return null;
+  }
+  return date;
+}
+
+function formatIsoDate(date) {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(date.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function addDaysUtc(date, days) {
+  const copy = new Date(date.getTime());
+  copy.setUTCDate(copy.getUTCDate() + days);
+  return copy;
+}
+
+function buildBiweeklyPeriods(dateFrom, dateTo) {
+  const start = parseIsoDate(dateFrom);
+  const end = parseIsoDate(dateTo);
+  if (!start || !end) {
+    throw createInvalidArgError('invalid-date', 'biweekly window requires valid dateFrom/dateTo');
+  }
+  const diffDays = Math.round((end.getTime() - start.getTime()) / 86400000) + 1;
+  if (diffDays !== 14) {
+    throw createInvalidArgError('invalid-window', 'biweekly window must span exactly 14 days');
+  }
+  if (end.getTime() < start.getTime()) {
+    throw createInvalidArgError('invalid-window', 'dateFrom must not be after dateTo');
+  }
+
+  const periods = [];
+  for (let i = 0; i < 3; i += 1) {
+    const periodStart = addDaysUtc(start, -14 * i);
+    const periodEnd = addDaysUtc(end, -14 * i);
+    periods.push({
+      period: 'biweekly',
+      index: i,
+      label: i === 0 ? 'current' : `prior-${i}`,
+      date_from: formatIsoDate(periodStart),
+      date_to: formatIsoDate(periodEnd),
+      length_days: 14,
+    });
+  }
+  return periods;
+}
+
+function buildMonthlyPeriods(dateFrom, dateTo) {
+  const start = parseIsoDate(dateFrom);
+  const end = parseIsoDate(dateTo);
+  if (!start || !end) {
+    throw createInvalidArgError('invalid-date', 'monthly window requires valid dateFrom/dateTo');
+  }
+  if (end.getTime() < start.getTime()) {
+    throw createInvalidArgError('invalid-window', 'dateFrom must not be after dateTo');
+  }
+
+  const monthStart = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), 1));
+  const monthEnd = new Date(Date.UTC(end.getUTCFullYear(), end.getUTCMonth() + 1, 0));
+  const sameNaturalMonth = start.getUTCFullYear() === end.getUTCFullYear()
+    && start.getUTCMonth() === end.getUTCMonth();
+  if (!sameNaturalMonth
+    || formatIsoDate(monthStart) !== formatIsoDate(start)
+    || formatIsoDate(monthEnd) !== formatIsoDate(end)) {
+    throw createInvalidArgError('invalid-window', 'monthly window must cover a full natural month');
+  }
+
+  const periods = [];
+  for (let i = 0; i < 3; i += 1) {
+    const year = start.getUTCFullYear();
+    const month = start.getUTCMonth() - i;
+    const periodStart = new Date(Date.UTC(year, month, 1));
+    const periodEnd = new Date(Date.UTC(year, month + 1, 0));
+    periods.push({
+      period: 'monthly',
+      index: i,
+      label: i === 0 ? 'current' : `prior-${i}`,
+      date_from: formatIsoDate(periodStart),
+      date_to: formatIsoDate(periodEnd),
+      length_days: periodEnd.getUTCDate(),
+    });
+  }
+  return periods;
+}
+
+function buildTrackingPeriods(window = {}) {
+  if (!window || typeof window !== 'object') {
+    throw createInvalidArgError('invalid-arg', 'buildTrackingPeriods expects a window object');
+  }
+  if (window.period === 'biweekly') {
+    return buildBiweeklyPeriods(window.dateFrom, window.dateTo);
+  }
+  if (window.period === 'monthly') {
+    return buildMonthlyPeriods(window.dateFrom, window.dateTo);
+  }
+  throw createInvalidArgError('invalid-period', `unsupported period: ${window.period}`);
+}
+
+function readPeriodMetric(period, metricKey) {
+  if (!period || typeof period !== 'object') return null;
+  const metrics = period.metrics || period;
+  if (metrics[metricKey] !== undefined) {
+    const entry = metrics[metricKey];
+    if (entry && typeof entry === 'object' && 'value' in entry) {
+      return Number.isFinite(entry.value) ? entry.value : null;
+    }
+    return Number.isFinite(entry) ? entry : null;
+  }
+  return null;
+}
+
+function metricHasData(period, metricKey) {
+  const value = readPeriodMetric(period, metricKey);
+  return Number.isFinite(value);
+}
+
+function isHigherBetter(metricKey, thresholds = ALERT_THRESHOLDS) {
+  return thresholds[metricKey]?.direction !== 'lower_better';
+}
+
+function isDeterioration(prev, current, metricKey, thresholds = ALERT_THRESHOLDS) {
+  if (!Number.isFinite(prev) || !Number.isFinite(current)) return false;
+  return isHigherBetter(metricKey, thresholds) ? current < prev : current > prev;
+}
+
+function evaluateAlerts(periods, thresholds = ALERT_THRESHOLDS) {
+  if (!Array.isArray(periods)) {
+    throw createInvalidArgError('invalid-arg', 'evaluateAlerts expects periods array');
+  }
+
+  const alerts = [];
+  const alertKeys = ['q3', 'p4', 'p_h', 'p_c'];
+
+  for (const metricKey of alertKeys) {
+    const cfg = thresholds[metricKey];
+    if (!cfg) continue;
+
+    const values = periods.map(p => readPeriodMetric(p, metricKey));
+    const hasAny = values.some(v => Number.isFinite(v));
+    const hasMissing = periods.some(p => !metricHasData(p, metricKey));
+
+    if (!hasAny) {
+      alerts.push({
+        level: 'data-gap',
+        metric: metricKey,
+        reason: 'missing-data',
+        periods: periods.map(p => p.label || p.date_from),
+      });
+      continue;
+    }
+
+    if (hasMissing) {
+      alerts.push({
+        level: 'data-gap',
+        metric: metricKey,
+        reason: 'partial-data',
+        periods: periods.map(p => p.label || p.date_from),
+      });
+    }
+
+    const current = values[0];
+    const prior = values[1];
+    const prior2 = values[2];
+
+    if (Number.isFinite(current)) {
+      if (current < cfg.red) {
+        alerts.push({
+          level: 'red',
+          metric: metricKey,
+          reason: 'below-red-threshold',
+          value: current,
+          threshold: cfg.red,
+        });
+      } else if (current < cfg.yellow) {
+        alerts.push({
+          level: 'yellow',
+          metric: metricKey,
+          reason: 'below-yellow-threshold',
+          value: current,
+          threshold: cfg.yellow,
+        });
+      }
+    }
+
+    if (metricKey === 'q3' || metricKey === 'p4') {
+      if (Number.isFinite(current) && Number.isFinite(prior) && isDeterioration(prior, current, metricKey, thresholds)) {
+        alerts.push({
+          level: 'yellow',
+          metric: metricKey,
+          reason: 'single-period-deterioration',
+          current,
+          prior,
+        });
+      }
+      if (Number.isFinite(current) && Number.isFinite(prior) && Number.isFinite(prior2)
+        && isDeterioration(prior, current, metricKey, thresholds)
+        && isDeterioration(prior2, prior, metricKey, thresholds)) {
+        alerts.push({
+          level: 'red',
+          metric: metricKey,
+          reason: 'consecutive-deterioration',
+          values: [current, prior, prior2],
+        });
+      }
+    }
+
+    if (metricKey === 'p_h' && Number.isFinite(current) && Number.isFinite(prior)) {
+      const drop = prior - current;
+      if (drop > 20) {
+        alerts.push({
+          level: 'yellow',
+          metric: metricKey,
+          reason: 'ph-drop-over-20-points',
+          current,
+          prior,
+          drop,
+        });
+      }
+    }
+  }
+
+  const q1Current = readPeriodMetric(periods[0], 'q1');
+  const q1PriorValues = periods.slice(1).map(p => readPeriodMetric(p, 'q1'));
+  const q1HadDataBefore = q1PriorValues.some(v => Number.isFinite(v));
+  if (!q1HadDataBefore && (q1Current === 0 || q1Current === 1 || q1Current === 100)) {
+    alerts.push({
+      level: 'blue',
+      metric: 'q1',
+      reason: 'first-boundary-value',
+      value: q1Current,
+    });
+  }
+
+  return alerts;
+}
+
+function evaluateMaturity(metrics = {}, evidence = {}) {
+  const hasSddFlow = Boolean(evidence.has_sdd_flow ?? metrics.has_sdd_flow);
+  const met = [];
+  const unmet = [];
+  const missingEvidence = [];
+
+  const p4 = metrics.p4_quality_gate_enforcement_rate ?? metrics.p4 ?? null;
+  const pC = metrics.p_c_stage_closure_rate ?? metrics.p_c ?? null;
+  const q1 = metrics.q1_spec_conformance ?? metrics.q1 ?? null;
+  const q3 = metrics.q3_spec_quality_score ?? metrics.q3 ?? null;
+  const pR = metrics.p_r_avg_rework_count ?? metrics.p_r ?? null;
+  const e1TargetMet = evidence.e1_type_target_met === true;
+
+  const criteria = [];
+
+  if (!hasSddFlow) {
+    return {
+      current_level: 'L0',
+      eligible_max_level: evidence.code_fully_spec_generated === true ? 'L4' : 'L3',
+      met_criteria: [],
+      unmet_criteria: ['has_sdd_flow'],
+      missing_evidence: ['has_sdd_flow'],
+    };
+  }
+
+  criteria.push({ id: 'l1_flow', level: 'L1', met: true });
+  met.push('l1_flow');
+
+  const l2Checks = [
+    { id: 'l2_p4', met: Number.isFinite(p4) && p4 >= 0.8 },
+    { id: 'l2_p_c', met: Number.isFinite(pC) && pC >= 0.95 },
+    { id: 'l2_q1', met: Number.isFinite(q1) && q1 >= 0.8 },
+  ];
+  const l2Met = l2Checks.every(c => c.met);
+  for (const check of l2Checks) {
+    (check.met ? met : unmet).push(check.id);
+    if (!check.met && !Number.isFinite(
+      check.id === 'l2_p4' ? p4 : check.id === 'l2_p_c' ? pC : q1,
+    )) {
+      missingEvidence.push(check.id);
+    }
+  }
+  if (l2Met) criteria.push({ id: 'l2', level: 'L2', met: true });
+
+  const l3Checks = [
+    { id: 'l3_q3', met: Number.isFinite(q3) && q3 >= 95 },
+    { id: 'l3_e1', met: e1TargetMet },
+    { id: 'l3_p4', met: Number.isFinite(p4) && p4 >= 0.95 },
+    { id: 'l3_p_r', met: Number.isFinite(pR) && pR <= 1 },
+    { id: 'l3_q1', met: Number.isFinite(q1) && q1 >= 0.9 },
+  ];
+  const l3Met = l3Checks.every(c => c.met);
+  for (const check of l3Checks) {
+    (check.met ? met : unmet).push(check.id);
+    if (!check.met) {
+      if (check.id === 'l3_e1' && evidence.e1_type_target_met !== true) {
+        missingEvidence.push('e1_type_target');
+      } else if (!Number.isFinite(
+        check.id === 'l3_q3' ? q3
+          : check.id === 'l3_p4' ? p4
+            : check.id === 'l3_p_r' ? pR
+              : q1,
+      )) {
+        missingEvidence.push(check.id);
+      }
+    }
+  }
+  if (l3Met) criteria.push({ id: 'l3', level: 'L3', met: true });
+
+  let currentLevel = 'L1';
+  if (l3Met) currentLevel = 'L3';
+  else if (l2Met) currentLevel = 'L2';
+
+  let eligibleMaxLevel = 'L3';
+  if (evidence.code_fully_spec_generated === true) {
+    eligibleMaxLevel = 'L4';
+    if (currentLevel === 'L3') currentLevel = 'L4';
+  }
+
+  return {
+    current_level: currentLevel,
+    eligible_max_level: eligibleMaxLevel,
+    met_criteria: met,
+    unmet_criteria: unmet,
+    missing_evidence: [...new Set(missingEvidence)],
+  };
+}
+
+function buildMinimumMetricStatus(metrics = {}) {
+  const efficiency = metrics.efficiency || metrics;
+  const quality = metrics.quality || metrics;
+  const processMetrics = metrics.process || metrics;
+  const telemetry = metrics.telemetry_health || metrics;
+  const metricEvidence = metrics.metric_evidence && typeof metrics.metric_evidence === 'object'
+    ? metrics.metric_evidence
+    : {};
+
+  const entries = {
+    e1: efficiency.e1_scenario_delivery_efficiency_ms ?? efficiency.e1 ?? null,
+    q3: quality.q3_spec_quality_score ?? quality.q3 ?? null,
+    p4: processMetrics.p4_quality_gate_enforcement_rate ?? processMetrics.p4 ?? null,
+    p_r: processMetrics.rework_summary?.avg_rework_count
+      ?? processMetrics.rework_summary?.total_rework_attempts
+      ?? processMetrics.p_r
+      ?? null,
+    p_h: telemetry.p_h_telemetry_health_score ?? telemetry.p_h ?? null,
+  };
+
+  const available = [];
+  const missing = [];
+  const evidenceStatus = {};
+
+  for (const key of MINIMUM_METRICS) {
+    if (!Number.isFinite(entries[key])) {
+      missing.push(key);
+      evidenceStatus[key] = 'missing';
+      continue;
+    }
+    available.push(key);
+    const declaredStatus = metricEvidence[key]?.status;
+    if (declaredStatus === 'trusted' || declaredStatus === 'provisional') {
+      evidenceStatus[key] = declaredStatus;
+    } else if (key === 'q3') {
+      evidenceStatus[key] = quality.q3_score_status === 'verified'
+        && quality.q3_reviewer_independence === 'independent-review'
+        ? 'trusted'
+        : 'provisional';
+    } else {
+      evidenceStatus[key] = 'provisional';
+    }
+  }
+
+  const trustedMetrics = MINIMUM_METRICS.filter(key => evidenceStatus[key] === 'trusted');
+  const provisionalMetrics = MINIMUM_METRICS.filter(key => evidenceStatus[key] === 'provisional');
+  return {
+    minimum_metrics: MINIMUM_METRICS,
+    available,
+    missing,
+    coverage_rate: MINIMUM_METRICS.length > 0
+      ? round(available.length / MINIMUM_METRICS.length)
+      : 0,
+    numeric_available: available.length,
+    numeric_total: MINIMUM_METRICS.length,
+    numeric_coverage_rate: MINIMUM_METRICS.length > 0
+      ? round(available.length / MINIMUM_METRICS.length)
+      : 0,
+    trusted_available: trustedMetrics.length,
+    trusted_metrics: trustedMetrics,
+    provisional: provisionalMetrics.length,
+    provisional_metrics: provisionalMetrics,
+    missing_count: missing.length,
+    trusted_coverage_rate: MINIMUM_METRICS.length > 0
+      ? round(trustedMetrics.length / MINIMUM_METRICS.length)
+      : 0,
+    evidence_status: evidenceStatus,
+    evidence: metricEvidence,
+    entries,
+  };
+}
+
+function buildSchemeCompliance(input = {}) {
+  const minimum = input.minimum_metric_set || {};
+  const reportMetrics = input.metrics || {};
+  const efficiency = reportMetrics.efficiency || {};
+  const quality = reportMetrics.quality || {};
+  const processMetrics = reportMetrics.process || {};
+  const formats = Array.isArray(input.formats) ? input.formats : [];
+  const minimumStatus = minimum.numeric_available === minimum.numeric_total
+    ? (minimum.trusted_available === minimum.numeric_total ? 'implemented' : 'provisional')
+    : 'provisional';
+  const q1Status = quality.q1_status || quality.q1_spec_conformance?.status || 'pending-upstream';
+  const q4Status = quality.q4_status || quality.q4_tdd_coverage?.status || 'pending-upstream';
+  const q3Status = quality.q3_score_status === 'verified' ? 'implemented' : 'provisional';
+  const statusLabel = status => ({
+    implemented: '已实现',
+    provisional: '部分可用',
+    'pending-upstream': '待补数据',
+    'not-applicable': '本报告不适用',
+    verified: '已验证',
+    trusted: '可信',
+    missing: '缺失',
+    unknown: '未知',
+    'independent-review': '独立复核',
+    'self-review': '自评',
+  }[status] || status || '未知');
+
+  const items = [
+    {
+      requirement: 'minimum-verifiable-metrics',
+      label: '最小可验证指标（E1、Q3、P4、P-R、P-H）',
+      status: minimumStatus,
+      evidence: `数值覆盖 ${minimum.numeric_available ?? minimum.available?.length ?? 0}/${minimum.numeric_total ?? MINIMUM_METRICS.length}；可信覆盖 ${minimum.trusted_available ?? 0}/${minimum.numeric_total ?? MINIMUM_METRICS.length}`,
+    },
+    {
+      requirement: 'e2-e3-assist',
+      label: '辅助效率指标（E2、E3）',
+      status: Number.isFinite(efficiency.e2_coding_time_ratio) && Number.isFinite(efficiency.e3_spec_time_ratio)
+        ? 'implemented'
+        : 'provisional',
+      evidence: '报告模型中的效率数据',
+    },
+    {
+      requirement: 'q1-q4-conditional',
+      label: '条件指标（Q1、Q4）',
+      status: q1Status === 'pending-upstream' || q4Status === 'pending-upstream'
+        ? 'pending-upstream'
+        : 'implemented',
+      evidence: `Q1：${statusLabel(q1Status)}；Q4：${statusLabel(q4Status)}`,
+    },
+    {
+      requirement: 'stage-closure',
+      label: '步骤闭环率（P-C）',
+      status: Number.isFinite(processMetrics.p_c_stage_closure_rate) ? 'implemented' : 'provisional',
+      evidence: '步骤开始记录与结束记录配对',
+    },
+    {
+      requirement: 'independent-reviewer',
+      label: '独立复核',
+      status: q3Status,
+      evidence: `Q3：${statusLabel(quality.q3_score_status || 'provisional')}；复核方式：${statusLabel(quality.q3_reviewer_independence || 'unknown')}`,
+    },
+    {
+      requirement: 'tracking-periods',
+      label: input.level === 'change' ? '本次变更独立统计' : '双周、月度追踪',
+      status: input.level === 'change'
+        ? 'implemented'
+        : (['biweekly', 'monthly'].includes(input.period) ? 'implemented' : 'not-applicable'),
+      evidence: input.level === 'change'
+        ? '只包含当前 change 的阶段、任务、测试、证据和产物；不混入跨变更趋势'
+        : (input.period
+          ? `当前统计周期：${input.period === 'biweekly' ? '双周' : '月度'}`
+          : '当前报告未请求周期聚合'),
+    },
+    {
+      requirement: 'change-type-percentiles',
+      label: '按变更类型与 P50/P75/P90 聚合',
+      status: input.level === 'project' ? 'implemented' : 'not-applicable',
+      evidence: input.level === 'project' ? '项目级聚合模型' : '单变更报告不展示分位数',
+    },
+    {
+      requirement: 'alert-feedback-loop',
+      label: '指标与证据告警闭环',
+      status: input.evidence_alerts ? 'implemented' : 'provisional',
+      evidence: input.evidence_alerts ? '稳定问题编号、未解决/已解决状态和历史记录' : '当前模型未提供告警生命周期',
+    },
+    {
+      requirement: 'multi-format-same-model',
+      label: 'Markdown、HTML、JSON 同源',
+      status: ['md', 'html', 'json'].every(format => formats.includes(format)) ? 'implemented' : 'provisional',
+      evidence: formats.length > 0 ? formats.map(format => ({ md: 'Markdown', html: 'HTML', json: 'JSON' }[format] || format)).join(' / ') : '格式信息未提供',
+    },
+    {
+      requirement: 'reproducible-auditable',
+      label: '可复算、可审计',
+      status: input.event_count > 0 ? 'implemented' : 'provisional',
+      evidence: input.event_count > 0 ? `${input.event_count} 条 JSONL 事件` : '未提供事件数量',
+    },
+  ];
+  const counts = {};
+  for (const item of items) counts[item.status] = (counts[item.status] || 0) + 1;
+  return {
+    scheme: '3.3.4.2_SDD赋能提效评估与追踪方案',
+    version: 'V3.0',
+    items,
+    counts,
+  };
+}
+
+function evidenceAlertKey(event, warning, subject) {
+  return `${warning}:${subject || event.capability || event.command || event.change || 'change'}`;
+}
+
+function buildEvidenceAlerts(events = []) {
+  const byKey = new Map();
+  const ordered = events.slice().sort((a, b) => (
+    new Date(a.timestamp || 0).getTime() - new Date(b.timestamp || 0).getTime()
+  ));
+  for (const event of ordered) {
+    if (event?.type !== 'telemetry_warning') continue;
+    const warning = event.details?.warning || event.warning;
+    if (!warning) continue;
+    const subjects = Array.isArray(event.details?.task_ids) && event.details.task_ids.length > 0
+      ? event.details.task_ids
+      : [event.details?.task_id || event.task_id || event.capability || event.command || event.change];
+    for (const subject of subjects) {
+      const key = event.details?.key || evidenceAlertKey(event, warning, subject);
+      const existing = byKey.get(key);
+      if (existing) {
+        existing.occurrences += 1;
+        existing.last_seen_event_id = event.event_id || existing.last_seen_event_id;
+        existing.last_seen_at = event.timestamp || existing.last_seen_at;
+        continue;
+      }
+      const severity = warning === 'apply_test_missing' ? 'error' : 'warning';
+      byKey.set(key, {
+        key,
+        category: 'evidence',
+        warning,
+        subject: subject || null,
+        severity,
+        status: 'open',
+        occurrences: 1,
+        opened_by_event_id: event.event_id || null,
+        first_seen_at: event.timestamp || null,
+        last_seen_event_id: event.event_id || null,
+        last_seen_at: event.timestamp || null,
+        resolved_by_event_id: null,
+        resolved_at: null,
+      });
+    }
+  }
+
+  for (const event of ordered) {
+    const resolutionKeys = [
+      event?.details?.resolves_warning_key,
+      event?.details?.resolved_warning_key,
+      ...(Array.isArray(event?.details?.resolves_warning_keys) ? event.details.resolves_warning_keys : []),
+    ].filter(Boolean);
+    for (const key of resolutionKeys) {
+      const alert = byKey.get(key);
+      if (!alert || alert.status === 'resolved') continue;
+      alert.status = 'resolved';
+      alert.resolved_by_event_id = event.event_id || null;
+      alert.resolved_at = event.timestamp || null;
+    }
+  }
+
+  const history = Array.from(byKey.values());
+  const open = history.filter(alert => alert.status === 'open');
+  const resolved = history.filter(alert => alert.status === 'resolved');
+  return {
+    open,
+    resolved,
+    history,
+    counts: {
+      open: open.length,
+      resolved: resolved.length,
+      total: history.length,
+    },
+  };
+}
+
+function isDevelopmentActivity(event) {
+  if (!event || typeof event !== 'object') return false;
+  const type = event.type || event.event_type || null;
+  if (type === 'telemetry_warning') return false;
+  if (DEVELOPMENT_ACTIVITY_TYPES.has(type)) return true;
+  if (type === 'process_note') {
+    const kind = event.details?.kind || event.kind || null;
+    return kind === 'fix' || kind === 'manual-action';
+  }
+  return false;
+}
+
+function findDevelopmentActivities(events, startMs, endMs) {
+  if (!Array.isArray(events)) return [];
+  const start = Number.isFinite(startMs) ? startMs : null;
+  const end = Number.isFinite(endMs) ? endMs : null;
+  return events.filter((event) => {
+    if (!isDevelopmentActivity(event)) return false;
+    const ts = Date.parse(event.timestamp || event.ts || '');
+    if (!Number.isFinite(ts)) return false;
+    if (start !== null && ts < start) return false;
+    if (end !== null && ts > end) return false;
+    return true;
+  });
+}
+
+function deriveSuccessfulReworkReason(attemptContext = {}) {
+  const baseReason = attemptContext.base_reason || attemptContext.rework_reason || null;
+  const agentOverride = attemptContext.agent_override_reason || null;
+
+  if (baseReason === 'incomplete') {
+    return {
+      reason: 'incomplete',
+      reason_source: 'deterministic',
+      evidence_event_ids: [],
+    };
+  }
+  if (baseReason === 'prev-failed') {
+    return {
+      reason: 'prev-failed',
+      reason_source: 'deterministic',
+      evidence_event_ids: [],
+    };
+  }
+  if (attemptContext.is_pre_archive_recheck === true || baseReason === 'pre-archive-recheck') {
+    return {
+      reason: 'pre-archive-recheck',
+      reason_source: 'deterministic',
+      evidence_event_ids: [],
+    };
+  }
+  if (agentOverride && AGENT_OVERRIDE_REASONS.has(agentOverride)) {
+    return {
+      reason: agentOverride,
+      reason_source: 'agent-override',
+      evidence_event_ids: attemptContext.evidence_event_ids || [],
+    };
+  }
+
+  if (attemptContext.git_has_commit_in_window === true) {
+    return {
+      reason: 'code-changed-after-pass',
+      reason_source: 'git',
+      evidence_event_ids: attemptContext.evidence_event_ids || [],
+      window: attemptContext.window || null,
+    };
+  }
+
+  const devActivities = attemptContext.dev_activities
+    || findDevelopmentActivities(
+      attemptContext.events || [],
+      attemptContext.window_start_ms,
+      attemptContext.window_end_ms,
+    );
+
+  if (devActivities.length > 0) {
+    return {
+      reason: 'code-changed-after-pass',
+      reason_source: 'telemetry',
+      evidence_event_ids: devActivities.map(e => e.event_id).filter(Boolean),
+      window: attemptContext.window || null,
+    };
+  }
+
+  if (baseReason === 'completed_rework_success' || baseReason === 'recheck-no-change' || baseReason === 'unspecified') {
+    return {
+      reason: 'recheck-no-change',
+      reason_source: 'telemetry-no-activity',
+      evidence_event_ids: [],
+      window: attemptContext.window || null,
+    };
+  }
+
+  return {
+    reason: 'unspecified',
+    reason_source: 'unknown',
+    evidence_event_ids: [],
+  };
+}
+
+module.exports = {
+  REPORT_SCHEMA_VERSION,
+  METRICS_CONTRACT_VERSION,
+  CHANGE_TYPES,
+  ALERT_THRESHOLDS,
+  MINIMUM_METRICS,
+  clamp,
+  round,
+  percentile,
+  summarizeDistribution,
+  detectIqrOutliers,
+  computeSpecQualityScore,
+  computeScenarioDeliveryEfficiency,
+  computeV3ChangeMetrics,
+  aggregateV3Metrics,
+  aggregateByChangeType,
+  buildTrackingPeriods,
+  evaluateAlerts,
+  evaluateMaturity,
+  buildMinimumMetricStatus,
+  buildSchemeCompliance,
+  buildEvidenceAlerts,
+  isDevelopmentActivity,
+  findDevelopmentActivities,
+  deriveSuccessfulReworkReason,
+  validateChangeType,
+  createInvalidArgError,
+  countScenariosInMarkdown,
+};