init: document-haness 설계

tests/README.md

@@ -0,0 +1,36 @@
+# Core runtime test contract
+
+이 디렉터리는 LLM 문장 문자열을 정답으로 고정하지 않는다. Python 3.11+ 표준 라이브러리 런타임이 보장해야 할 불변식을 세 층으로 검사한다.
+
+- **unit**: route 판정, 상태 전이, Markdown·용어·무손실 규칙과 입력 오류 처리를 검사한다.
+- **golden**: `fixtures/good`은 finding 없이 통과하고 `fixtures/bad`은 `expected-rule-ids.json`의 실패 모드를 모두 재현해야 한다.
+- **offline E2E**: root 호환 CLI로 run을 만들고 산출물을 채운 뒤 lint와 verifier를 실행해 `verified` 상태까지 간다.
+- **live**: 명시적으로 켰을 때만 Claude CLI에 이 저장소의 실제 플러그인을 로드하고, 새 run이 verifier까지 통과하는지 확인한다.
+
+고정 계약:
+
+- runtime은 Python 표준 라이브러리만 사용한다.
+- `config/quality-rules.json`은 설치되는 canonical skill 내부 파일을 뜻한다.
+- write의 auto route는 최소 standard다. light는 기존 draft가 있고 모든 light 임계 안일 때만 자동 추천한다.
+- `00_run.json`과 `01_sources.json`의 input hash는 초기화 때 읽은 동일 byte snapshot을 기준으로 하며, run/lint의 `rules_sha256`은 실제 quality-rules byte를 고정한다.
+- lint exit은 pass=0, gate fail=1, input/schema error=2다.
+- review mode는 `final.md` 없이 두 독립 review, lint, final report로 완료할 수 있다.
+- 상태 checkpoint는 단계별 일반·비-symlink 산출물과 schema를 검사하고, review/lint의 현재 hash 및 mode verdict, final/draft byte 동일성을 확인한 뒤에만 전이한다.
+- `hold_for_review`, `failed`, `incomplete`는 terminal이며 서로 또는 진행 상태로 다시 전이할 수 없다.
+- verifier가 만든 canonical `09_final_report.json`만 최종 verdict의 기준이며, 일반 상태 CLI는 `verified`를 만들 수 없다.
+- lint/verifier output은 입력 alias와 다른 도구 소유 파일을 덮어쓰지 않는다.
+- verifier는 상태 전이 전후 snapshot과 stale lint/review provenance를 재검사한다.
+
+실행:
+
+```bash
+python3 -m pytest tests -q
+```
+
+기본 테스트는 외부 모델을 호출하지 않는다. 실제 스킬 회귀는 Claude CLI 인증과 비용·시간 사용을 이해한 상태에서 다음처럼 별도로 실행한다.
+
+```bash
+TECH_DOC_FLOW_RUN_LIVE=1 python3 -m pytest tests/test_live_skill.py -q -m live
+```
+
+Claude CLI가 없으면 live test는 skip한다. 문자열 전체를 정답으로 고정하지 않고, 실행 산출물·최종 verdict·보호 토큰·용어 first-use 계약을 검사한다. `TECH_DOC_FLOW_LIVE_TIMEOUT`으로 기본 300초 timeout을 바꿀 수 있다.