silent-failure-catalog

# 조용한 실패 카탈로그(Silent Failure Catalog) 이것은 **검증이 통과한 것처럼 보이지만 실제로는 아무것도 확인하지 않은** 실패 패턴을 체계적으로 정리한 카탈로그다. CI 게이트, 테스트 스위트, 데이터 파이프라인, AI 에이전트 도구 체인에서의 '가짜 초록' 또는 '검증 공백' 문제에 초점을 맞춘다. ## 핵심 문제 > "항상 통과하는 테스트는 테스트가 없는 것보다 더 나쁘다. 커버리지가 있는 것처럼 보이지만 실질적인 보장은 전혀 없다." 크래시는 스스로를 알리지만, 조용한 실패는 그렇지 않다. 페이지는 평소처럼 로드되고, DOI는 평소처럼 해석되며, 파이프라인은 평소처럼 `PASS`를 출력하고, 에이전트는 평소처럼 진행 상황을 보고한다. **빨간 곳은 하나도 없지만, 맞는 곳도 하나도 없다.** 이러한 실패의 공통된 특징은 시스템에 '마땅히 일어나야 할 일이 일어나지 않았다'는 신호가 없다는 점이다. 누락, 비어 있음, 건너뜀, 미집계, 잘못된 귀속 상태는 결국 모두 **성공**으로 나타난다. ## 카탈로그 구조 이 카탈로그는 **14개의 이름 붙은 조용한 실패 패턴**을 다섯 개의 계열로 나누어 담고 있다. - **A · 공허한 검증(Vacuous Verification)**: 검사는 실행되었지만 판별력이 없음(SF-001~SF-004) - **B · 집계되지 않은 부재(Uncounted Absence)**: 필수 항목이 빠졌지만 부재가 실패로 계산되지 않음(SF-005~SF-007) - **C · 잘못된 증거(Wrong Evidence)**: 사용된 신호가 도출된 결론을 입증할 수 없음(SF-008~SF-010) - **D · 표류하는 오라클(Drifting Oracle)**: 검사 자체가 퇴화함 — 면제, 부분 문자열 일치, 잘못된 귀속(SF-011~SF-012) - **E · 프로세스와 환경(Process & Environment)**: 실패가 로직 밖에 존재함 — 오래된 산출물, 좀비 프로세스(SF-013~SF-014) 각 항목은 통일된 여섯 부분 구조를 따른다: **증상 → 왜 조용한가 → 최소 재현 → 자체 점검 → 수정 → 관련 항목**. ## 공통 근본 원인 모든 계열은 본질적으로 동일한 결함이 서로 다른 층위에서 나타난 것이다. > **'증거 없음'을 '문제 없음'의 증거로 착각하는 것.** 여기서 가장 실용적인 두 가지 규칙이 나온다. 1. **부재는 반드시 종료 코드에 들어가야 한다** — '있어야 할 것이 없다'가 로그, 중립 표시, 건너뜀으로만 기록되면 그것은 영원히 `exit 0`을 산출하며, 게이트는 가장 중요한 지점에서 정확히 눈이 먼다. 2. **음성 대조 없이는 증거도 없다** — 한 번도 실패하는 것이 관찰된 적 없는 검사는 실패할 수 있음이 입증된 적이 없다. 모든 부정적 결론에는 양성 대조가 필요하다. ## 빠른 시작 ```bash git clone https://github.com/zhaoxinghua09-cell/silent-failure-catalog.git cd silent-failure-catalog # 당신이 신뢰하는 게이트/검증기/감사 스크립트를 점검 python tools/gate-lint.py path/to/your_gate.py # 카탈로그 자체의 내부 일관성 검증 python tools/check-catalog.py ``` 두 스크립트 모두 **순수 표준 라이브러리**로 구현되었다 — 설치도, 네트워크 연결도 필요 없으며 Python 3.9+면 충분하다. ## 자체 검진기(gate-lint.py) 이 도구는 당신의 게이트 스크립트를 스캔하여 이러한 조용한 실패 패턴을 식별한다. 예를 들어: - `SFL-001 no-nonzero-exit`: 파일 내에 `exit()`/`raise`/`assert`가 전혀 없어 실패할 수 없음 - `SFL-002 swallow-exception`: `except` 블록이 `pass`만 실행함 - `SFL-003 unchecked-empty`: 비어 있음/거짓 값이 정상으로 처리됨 - `SFL-004 counter-does-not-gate-exit`: 카운터가 종료 코드에 전혀 영향을 주지 않음 - `SFL-005 zero-item-pass`: 테스트 실행기를 호출하지만 '0개 항목 수집'을 방어하지 않음 - `SFL-006 no-negative-control`: 음성 대조 샘플이 발견되지 않아 검사가 실패할 수 있음을 입증할 수 없음 낮은 심각도의 발견 사항은 **출력에서 명시적으로 강등 표시**되며, 조용히 버려지지 않는다 — 조용한 폐기가 바로 이 카탈로그가 기록하는 실패이기 때문이다. `--strict`를 사용하면 낮은 등급의 발견 사항을 비영(非零) 종료로 승격할 수 있다. ## 내용 무결성 `INTEGRITY.md`와 `manifest.sha256`은 각 파일의 SHA-256 다이제스트를 기록하고 집합 다이제스트를 제공하여, 독자가 이 페이지에 설명된 것과 정확히 동일한 바이트를 보유하고 있는지 확인할 수 있게 한다. `tools/make-manifest.py --check`는 어떤 표류가 발생해도 종료 코드 1을 반환한다. CI는 내용 파일을 수정할 때 매니페스트를 재생성하도록 강제하며, 의도적으로 1바이트를 손상시켜 검사가 실제로 실패할 수 있음을 검증한다. ## 기여 **재현**과 **음성 대조**를 제공할 수 있을 때 새로운 항목 제출을 환영한다 — 사건 보고만으로는 충분하지 않은데, 이는 기계적으로 점검할 수 없기 때문이다. ## 라이선스 이 저장소는 계층적 라이선스를 채택한다: **코드는 MIT**, **내용은 모든 권리 보유**(출처를 밝히면 인용 가능).