MEASUREMENT / HARNESS EFFECTIVENESS
가드레일이 실제로
효과가 있었나
TraceLog 이벤트를 읽는 결정론적 reducer입니다. 아래 weight와 계산식은 현재 lib/harness_effectiveness.py 구현 기준입니다.
WEIGHTS
왜 이 weight인가
통계적으로 학습된 중요도나 업계 표준이 아니라, 현재 하네스의 운영 우선순위를 반영한 설계값입니다.
- Recovery 0.31: 실패 후 안전한 복구와 재발 방지를 가장 큰 운영 위험으로 봅니다.
- Prevention 0.25 / First pass 0.25: 사전 차단과 첫 검증 통과를 동등하게 봅니다.
- Measurement integrity 0.19: 모든 결과의 신뢰성을 지키는 기반 축입니다.
- Learning 0.00: control cohort가 아직 없어 인과 효과를 overall에 넣지 않습니다.
기존 0.20/0.20/0.25/0.15를 learning 제외 후 합계 1.00이 되도록 재배분한 값입니다. 데이터와 cohort가 쌓이면 버전업해 재검토해야 합니다.
COMPONENTS
무엇을, 어떻게 측정하는가
0.25prevention_quality
가드가 위험한 동작을 막고 정상 동작은 통과시키는지
- 입력
- guard.blocked / guard.allowed 이벤트. ground_truth, policy_id, reason이 필요합니다.
- 계산
- precision × 0.50 + recall × 0.30 + evidence quality × 0.20
- 결과
- unsafe 차단 정밀도, unsafe 탐지 재현율, evidence 완비율
- 한계
- ground_truth 라벨이 없으면 계산하지 않습니다. 라벨 품질이 낮으면 결과도 낮은 신뢰도를 가집니다.
0.25first_pass_quality
write 직후 첫 검증에서 통과하는지
- 입력
- subject별 write.observed 이후 첫 verify.passed / verify.failed 이벤트
- 계산
- first-pass rate × 0.70 + evidence completeness × 0.20 + no-hidden-retry × 0.10
- 결과
- 첫 검증 통과율, evidence 완비율, 실패·heal 없는 첫 검증 비율
- 한계
- 검증 이벤트가 없는 write는 제외됩니다. 빠른 통과가 장기 품질을 증명하지는 않습니다.
0.31recovery_quality
검증 실패 후 안전하게 복구하는지
- 입력
- verify.failed 이후 heal.attempted와 verify.passed 이벤트. parent_id, independent, retry_count가 필요합니다.
- 계산
- verified recovery × 0.45 + independent verification × 0.25 + ≤3-cycle × 0.20 + no-regression × 0.10
- 결과
- 복구 성공률, 독립 검증률, 3 cycle 이내 복구율, 복구 후 재실패가 없는 비율
- 한계
- 실패가 관측된 사례만 평가합니다. 실패가 없다는 것은 복구력이 아니라 관측 부족일 수 있습니다.
0.00learning_quality
가드 개입이 다음 결과를 개선하는지
- 입력
- learning.outcome 이벤트의 treatment / control cohort와 verified_recovery
- 계산
- delta = treatment recovery − control recovery; score = clamp(50 + delta × 10)
- 결과
- cohort 간 회복률 차이와 learning yield를 표시하지만 overall에는 기여하지 않습니다.
- 한계
- 비교 가능한 control cohort가 없으면 INSUFFICIENT_EVIDENCE입니다. 인과 효과에는 충분한 표본과 cohort 설계가 필요합니다.
0.19measurement_integrity
측정 데이터 자체를 믿을 수 있는지
- 입력
- `.dev-kit/trace/events.jsonl`의 raw line과 검증된 이벤트
- 계산
- schema × 0.30 + attribution × 0.25 + dedupe × 0.20 + lifecycle coverage × 0.25
- 결과
- 파싱률, parent 연결률, event_id 중복 없는 비율, started→terminal 완료율
- 한계
- 무결성이 낮으면 다른 점수도 신뢰하기 어렵습니다. 형식이 맞아도 대표성은 보장하지 않습니다.
AGGREGATION
overall score와 status
각 score는 0–100으로 clamp됩니다. 현재 reducer는 score가 계산된 component만 weight 합계에 포함해 weighted mean을 냅니다. score가 없는 축은 분자와 분모에서 제외하고, weight가 0인 learning_quality도 overall에 기여하지 않습니다.
OK는 80 이상, DRIFT_WARNING은 60–79.9, ROT은 60 미만입니다. score가 없거나 coverage가 0.90 미만이면 INSUFFICIENT_EVIDENCE입니다.
overall = Σ(score × weight) / Σ(scored weights)
status: OK >= 80 · DRIFT_WARNING >= 60 · ROT < 60
LIMITATIONS
이 점수가 말해주지 않는 것
- 코드 정확성·보안·사용자 가치를 하나의 숫자로 증명하지 않습니다.
- TraceLog 밖의 작업과 기록되지 않은 실패는 측정하지 못합니다.
- 표본이 작으면 변동성이 큽니다. coverage와 event_count를 함께 봐야 합니다.
- learning_quality가 0인 동안 하네스의 인과적 학습 효과를 주장할 수 없습니다.
- agent 교체 안정성은 현재 직접 측정하지 않습니다. contract replay와 gate portability를 stability submetric으로 추가해야 합니다.
USAGE
실행
/dev-kit:harness-effectiveness
# deterministic reducer; no LLM spend
/dev-kit:evaluate
# 12-case judge + same five-component report