G7 평가 입력 안내 보강

scripts/prepare-g7-human-voice-gain-intake.py

@@ -524,10 +524,42 @@ def create_template(directory: Path) -> None:
             csv.writer(handle, lineterminator="\n").writerow(fields)
     (directory / README_NAME).write_text(
         "# G7 human voice-gain intake\n\n"
-        "이 디렉터리는 빈 입력 틀이지 증거가 아니다. `manifest.json`의 모든 provenance를 "
-        "실제 외부 연구 산출물 SHA-256으로 채우고 `template_only`를 `false`로 바꿔라. "
-        "CSV에는 비식별 키와 수치만 넣고 이름, 이메일, 원음, 축어록, 자유서술을 넣지 마라. "
-        "각 held-out 회기는 goal/task/bond 3축과 동일한 blind labeler panel을 가져야 한다.\n",
+        "## 이 폴더의 상태\n\n"
+        "이 디렉터리는 빈 입력 틀이지 증거가 아니다. 이름, 이메일, 원음, 축어록, "
+        "자유서술을 넣지 마라. 최종 pack도 임상 효과를 주장할 수 없다.\n\n"
+        "## 작성 순서\n\n"
+        "1. held-out 라벨을 열기 전에 protocol, consent, split, labeling, analysis plan을 "
+        "사전등록하고 각 산출물의 SHA-256을 고정한다.\n"
+        "2. `manifest.json`의 provenance, 두 모델 identity, reliability report를 실제 값으로 "
+        "채우고 `template_only`를 `false`로 바꾼다. `registered_at`은 "
+        "`held_out_labels_opened_at`보다 빨라야 한다.\n"
+        "3. 아래 CSV 계약에 맞춰 비식별 키와 수치만 입력한다.\n"
+        "4. compile 명령으로 production gate를 다시 계산한다. 성공한 경우에만 최종 pack이 "
+        "원자적으로 생성된다.\n"
+        "5. standalone checker로 최종 pack을 한 번 더 검증한 뒤 G7 runner에 전달한다.\n\n"
+        "## CSV 계약\n\n"
+        "- `participants.csv`: `split`은 `calibration` 또는 `held_out`이다. key는 각각 "
+        "`calibration-` 또는 `held-`로 시작하고 consent receipt SHA-256은 참가자마다 고유해야 한다.\n"
+        "- `labelers.csv`: 최소 2명의 독립 평가자를 선언한다. 세 blind/independent 열은 모두 "
+        "소문자 `true`여야 하고 attestation SHA-256을 넣는다.\n"
+        "- `observations.csv`: `axis`는 `goal`, `task`, `bond` 중 하나다. 각 held-out 회기는 "
+        "세 축을 모두 가져야 하며 모든 행에 동일한 blind labeler panel을 사용한다.\n"
+        "- prediction `status`는 `observed`, `missing`, `error` 중 하나다. `observed`일 때만 "
+        "0 이상 1 이하 score를 쓰고, `missing` 또는 `error`면 score 셀을 비운다.\n"
+        "- `label_score`는 0 이상 1 이하이고 `label_category`는 labeling protocol에 "
+        "사전 정의한 동일 taxonomy의 ASCII token을 사용한다.\n\n"
+        "## Production gate\n\n"
+        "최소 calibration 참가자 1명, held-out 참가자 30명, 완전 paired held-out 회기 50개, "
+        "paired 축 150개, blind labeler 2명이 필요하다. compiler는 ICC(A,1) 0.75 이상, "
+        "categorical kappa 0.70 이상, paired gain 0.01 이상, participant-cluster bootstrap "
+        "10,000회의 95% CI lower가 0보다 큰지 행에서 다시 계산한다. 한 조건이라도 결측이면 "
+        "양 조건을 최대오류로 처리해 gain 부풀림을 막는다.\n\n"
+        "## 실행\n\n"
+        "```powershell\n"
+        "python -X utf8 -B scripts/prepare-g7-human-voice-gain-intake.py "
+        "--compile <intake-dir> --out <pack.json>\n"
+        "python -X utf8 -B scripts/check-g7-human-voice-gain.py --input <pack.json>\n"
+        "```\n",
         encoding="utf-8",
         newline="\n",
     )

scripts/test_prepare_g7_human_voice_gain_intake.py

@@ -151,6 +151,17 @@ class G7HumanVoiceGainIntakeTests(unittest.TestCase):
             )
             self.assertIs(True, manifest["template_only"])
             self.assertFalse(json.loads(output.getvalue())["template_is_evidence"])
+            readme = (target / MODULE.README_NAME).read_text(encoding="utf-8")
+            for required_guidance in (
+                "## 작성 순서",
+                "`registered_at`은 `held_out_labels_opened_at`보다 빨라야 한다",
+                "`observed`, `missing`, `error`",
+                "ICC(A,1) 0.75 이상",
+                "categorical kappa 0.70 이상",
+                "bootstrap 10,000회",
+                "--compile <intake-dir> --out <pack.json>",
+            ):
+                self.assertIn(required_guidance, readme)
 
             report, pack = MODULE.compile_intake(target)
             self.assertIsNone(pack)