harness: RUN_STATE·CLAIMS·3계층 문서화 (BIOP01-67·68·69)

CLAIMS.yaml

@@ -0,0 +1,131 @@
+# CLAIMS.yaml — claim provenance ledger (BIOP01-69)
+# ---------------------------------------------------------------------------
+# 왜: "숫자는 결과 파일에서만" 규칙(package_validation)만으로는 다음 4가지를
+#     못 막는다.
+#       (1) headline claim ↔ 근거 파일의 연결이 문서화되지 않음
+#       (2) 본문이 근거보다 세게 주장(과장)
+#       (3) 결과가 바뀐 뒤에도 남아 있는 낡은 문장
+#       (4) reviewer 반영으로 claim 강도가 바뀌는 것
+#
+# 무엇: 각 headline claim 을 원문 근거·검증 스크립트·한계·원고 위치와 함께
+#       한 곳에 등록한다. claim_defensibility 게이트와 package_validation 이
+#       이 ledger 를 참조해, 등록된 claim 만 원고에 남고 강도가 근거를 넘지
+#       않는지 대조한다.
+#
+# 계층: project profile 계층의 산출물이다(도메인 claim). core harness 는
+#       이 파일의 "스키마"만 안다. → docs/HARNESS-LAYERS.md
+#
+# 필드:
+#   id                    : C1, C2 … 안정 식별자(원고·리뷰에서 참조)
+#   text                  : claim 한 문장. 원고 표현과 같은 강도로 적는다
+#   status               : supported | provisional | withdrawn | hypothesis_only
+#   claim_level           : 주장 강도. 원고 claim_level 정책과 일치해야 한다
+#   evidence              : 근거 결과 파일(경로). 여기 없는 숫자는 원고 금지
+#   validation            : 이 claim 을 재계산하는 결정론적 스크립트(게이트)
+#   limitations           : 이 claim 을 세게 못 쓰게 막는 한정. 원문 표현 보존
+#   manuscript_locations  : 이 claim 이 등장하는 원고 위치(abstract/results/…)
+# ===========================================================================
+
+schema_version: 1
+project: biop01
+findings_source: pipeline/hspc-velocity-benchmark/results/FINDINGS.md   # canonical 종합본
+updated: 2026-08-04
+
+claims:
+  - id: C1
+    text: >-
+      chromatin→transcription lag 은 gene 수준에서 method-robust 한 양이 아니다
+      (크기·방향 모두 method 간 일치도가 낮다).
+    status: supported
+    claim_level: primary_negative
+    evidence:
+      - pipeline/hspc-velocity-benchmark/results/clean_concordance_gate.md   # CRAK-비의존 clean headline
+      - pipeline/hspc-velocity-benchmark/results/concordance.md
+    validation:
+      - "pipeline/hspc-velocity-benchmark/scripts/p3_concordance.py"
+    key_numbers:
+      magnitude_concordance: "|rho|<=0.08 (mv×moflow -0.04, mv×mvvae -0.01, moflow×mvvae +0.08)"
+      sign_agreement: "54.6% ~= chance (방향 미정 lag=0 76개 제외 기준)"
+    limitations:
+      - "permutation-FDR agreement-set 0/598 은 부호 가변 method 3개(=CRAK 포함)에서만 정의 → 대표 결과에서 제외, CRAK 민감도 분석(보조)으로만."
+      - "sign-agreement 수치는 lag=0(방향 미정) 76개 제외 규약에 의존(미제외 np.sign 규약이면 48%)."
+    manuscript_locations: [abstract, results, discussion]
+
+  - id: C2
+    text: >-
+      lag 과 달리 (a) 전사율 alpha, (b) 집단 수준 방향 균형, (c) canonical priming
+      marker 방향 — 이 셋만 method 간 robust 하다.
+    status: supported
+    claim_level: primary_positive
+    evidence:
+      - pipeline/hspc-velocity-benchmark/results/clean_concordance_gate.md
+      - pipeline/hspc-velocity-benchmark/results/concordance.md
+    key_numbers:
+      alpha_concordance: "method 간 rho=0.88"
+      population_direction: "~50/50 (두 method 수렴)"
+    limitations:
+      - "robust 한 것은 alpha·집단방향·priming marker 방향에 한정. gene별 lag 값 자체는 아니다."
+    manuscript_locations: [abstract, results]
+
+  - id: C3
+    text: >-
+      음성대조(scrambled-chromatin)는 MultiVelo 의 lag 가 chromatin 신호가 아니라
+      모델 구조에서 나옴을 입증했다.
+    status: supported
+    claim_level: supporting
+    evidence:
+      - pipeline/hspc-velocity-benchmark/results/scrambled_null.md
+    validation:
+      - "pipeline/hspc-velocity-benchmark/scripts/p3_scrambled_null.py"
+    limitations:
+      - "한 method(MultiVelo)에 대한 구조 기인 입증. 다른 method로의 일반화는 별도 근거로."
+    manuscript_locations: [results]
+
+  - id: C4
+    text: >-
+      'alpha > lag' 식별성 순서는 다섯 외부 데이터셋에서 보존되며, 다섯 번째
+      (mouse gastrulation)는 fit 도착 전 봉인한 6개 예측을 사후구제 없이 6/0 통과했다.
+    status: supported
+    claim_level: primary_generalization
+    evidence:
+      - pipeline/hspc-velocity-benchmark/results/prereg_gse205117_scorecard.md   # 사전등록 6/0
+      - pipeline/hspc-velocity-benchmark/results/concordance_human_brain.md
+      - pipeline/hspc-velocity-benchmark/results/concordance_e18_mouse_brain.md
+      - pipeline/hspc-velocity-benchmark/results/concordance_GSE194122_bmmc.md
+      - pipeline/hspc-velocity-benchmark/results/concordance_macrophage.md
+    validation:
+      - "pipeline/hspc-velocity-benchmark/scripts/p3_crossdataset_concordance.py"
+    key_numbers:
+      alpha_monotone: "macrophage +0.643 > BMMC +0.55 > human_brain +0.475 > gastrulation +0.415 > E18 +0.32"
+      lag_signal: "어디서도 무신호 (+0.03~+0.19)"
+    limitations:
+      - "cross-dataset alpha 는 조직이 멀수록 단조 감소 — 보존되는 것은 'alpha>lag 순서'이지 alpha 절대값이 아니다."
+    manuscript_locations: [results, discussion]
+
+  - id: C5
+    text: >-
+      lag 이 method 간 재현되지 않는 것은 잡음이 아니라 MultiVelo 목적함수가 lag 을
+      데이터로 잘 결정하지 못하기 때문이다(관찰이 메커니즘으로 설명됨).
+    status: supported
+    claim_level: mechanism
+    evidence:
+      - pipeline/hspc-velocity-benchmark/results/profile_likelihood_identifiability.md   # §8
+    key_numbers:
+      alpha_vs_lag_sensitivity: "유전자별 alpha쪽 민감도가 lag쪽보다 중앙값 3.53x"
+      genes_alpha_more_sensitive: "94.57%"
+    limitations:
+      - "MultiVelo 목적함수에 대한 실질(practical) 비식별성. 완전(structural) 비식별성으로 과장 금지."
+    manuscript_locations: [results, discussion]
+
+  - id: C6
+    text: >-
+      따라서 drug-timing 모델은 lag 을 단일 method 값으로 쓰면 안 되고 method
+      불확실성을 명시적으로 반영해야 한다.
+    status: provisional
+    claim_level: downstream_implication
+    evidence:
+      - pipeline/hspc-velocity-benchmark/results/lag_model.md          # prototype
+      - pipeline/hspc-velocity-benchmark/results/lag_model_atac.md
+    limitations:
+      - "P5 baseline→timing 모델은 prototype(held-out lineage, Mc proxy). drug perturbation arm 은 데이터 대기."
+    manuscript_locations: [discussion]

CLAUDE.md

@@ -55,7 +55,7 @@ SKILL(지침)을 실제로 돌리는 코드:
 
 ## Agent routing & artifact contract (논문 생산 하네스)
 
-> 논문 집필·발표 단계용. 재사용 스캐폴드(Designed by Ka-Kyung Kim, CC BY 4.0) 설치본. 전체 랩 지도·멤버 JD = **`docs/HARNESS.md`**. 도메인 분석 슬롯 = **`hspc-velocity-analyst`**(팀이 채운 유일한 슬롯). 이 브랜치(`kkkim-pipeline`)에 project-scope로 설치.
+> 논문 집필·발표 단계용. 재사용 스캐폴드(Designed by Ka-Kyung Kim, CC BY 4.0) 설치본. 전체 랩 지도·멤버 JD = **`docs/HARNESS.md`**. 도메인 분석 슬롯 = **`hspc-velocity-analyst`**(project profile 의 analyst 슬롯 — 이식 시 검증 게이트 스크립트·paper direction·CLAIMS 도 함께 교체해야 한다. 경계: **`docs/HARNESS-LAYERS.md`**, BIOP01-67). 이 브랜치(`kkkim-pipeline`)에 project-scope로 설치.
 
 ### 자연어 라우팅
 요청에 agent 이름이 없어도 아래 표로 배정한다. 프로젝트 agent는 `.claude/agents/`. 그림 작업은 `manuscript-writer`가 `pipeline/hspc-velocity-benchmark/figures/figNN_*.py`를 실행해 소유.

RUN_STATE.yaml

@@ -0,0 +1,74 @@
+# RUN_STATE.yaml — 논문 생산 하네스 실행 상태 (BIOP01-68)
+# ---------------------------------------------------------------------------
+# 목적: orchestrator(→ runner)를 "프롬프트 묶음"이 아니라 "상태를 가진 생산
+#       시스템"으로 만든다. 세션이 끊기거나 사람이 개입해도 다음에 무엇을
+#       해야 하는지를 대화 기록이 아니라 이 파일에서 판단한다.
+#
+# 계층: 이 파일은 harness 3계층(BIOP01-67) 중 "run instance" 계층이다.
+#       core harness / project profile 는 코드·문서로 고정, run instance 만
+#       실행마다 바뀐다. → docs/HARNESS-LAYERS.md
+#
+# 읽는 주체: paper_planner(계획) 는 읽기만, paper_runner(실행) 만 갱신한다
+#            (BIOP01-70 권한 분리). runner 는 매 단계 시작 전 이 파일을 읽어
+#            이미 통과한 게이트를 건너뛰고, 실패·재시작 이력을 남긴다.
+#
+# 갱신 규칙:
+#   - 한 stage 를 끝내면 stages[].status 와 관련 gate 를 함께 갱신한다.
+#   - artifact 를 새로 쓰면 sha256 을 다시 계산해 넣는다(내용 변경 감지용).
+#   - source_commit 이 바뀌면(코드/데이터 수정) 어떤 게이트를 다시 통과해야
+#     하는지는 gates[].source_commit 과 현재 커밋을 비교해 판단한다:
+#     현재 커밋 != 통과 당시 커밋이면 그 게이트는 stale → 재실행 대상.
+# ===========================================================================
+
+schema_version: 1
+
+# --- 실행 식별 ---
+run_id: null                 # 예: "20260804-hspc-v2" — runner 가 새 실행 시작 시 채운다
+source_commit: null          # 이 실행이 근거한 리포 커밋(HEAD). 게이트 stale 판정 기준
+source_data_pin: null        # 데이터셋 버전/체크섬 핀(있으면). 재현성 기준
+started_at: null             # ISO8601. runner 가 채운다
+updated_at: null             # ISO8601. 갱신마다 runner 가 채운다
+
+# --- 현재 위치 ---
+# stage 는 아래 stages[] 의 name 중 하나. runner 는 이 값 다음 단계만 진행한다.
+stage: not_started
+
+# --- 파이프라인 단계 ---
+# status: pending | running | done | failed | skipped
+# gate: 이 단계 완료가 통과시켜야 하는 게이트(gates[] 의 key). 없으면 null.
+stages:
+  - { name: analysis,            status: pending, gate: null }
+  - { name: result_validation,   status: pending, gate: result_validation }   # 자동 무결성(분석 직후)
+  - { name: writing,             status: pending, gate: null }
+  - { name: figures,             status: pending, gate: null }
+  - { name: review,              status: pending, gate: null }                 # (선택) venue-reviewer. 게이트 앞에 온다
+  - { name: package_validation,  status: pending, gate: package_validation }   # 자동 무결성(공개 직전)
+  - { name: claim_defensibility, status: pending, gate: claim_defensibility }  # 과학 판단(사람)
+  - { name: release,             status: pending, gate: release }              # 거버넌스(사람)
+
+# --- 게이트 통과 기록 ---
+# harness.yaml 의 gates 와 key 가 일치해야 한다(doctor 대조 대상).
+# status: not_run | pass | fail | approved | rejected
+# commit: 이 게이트를 통과시킨 시점의 source_commit. 현재 커밋과 다르면 stale.
+# approved_by: 사람 승인 게이트(claim_defensibility/release)만. 자동 게이트는 null.
+gates:
+  result_validation:   { status: not_run, commit: null, approved_by: null }
+  package_validation:  { status: not_run, commit: null, approved_by: null }
+  claim_defensibility: { status: not_run, commit: null, approved_by: null }   # advisor 판단 필요
+  release:             { status: not_run, commit: null, approved_by: null }   # 저자·소속·IP·corresponding·data_release
+
+# --- 산출물 상태 ---
+# path 는 harness.yaml 의 artifacts 와 일치. sha256 은 내용 변경 감지용.
+# runner 가 산출물을 쓸 때마다 sha256 을 재계산해 넣는다. null = 아직 없음.
+artifacts:
+  findings:        { path: pipeline/hspc-velocity-benchmark/results/FINDINGS.md,          sha256: null }
+  manuscript:      { path: pipeline/hspc-velocity-benchmark/manuscript/draft_v2.md,        sha256: null }
+  manuscript_ko:   { path: pipeline/hspc-velocity-benchmark/manuscript/draft_v2_ko.md,     sha256: null }
+  paper_direction: { path: pipeline/hspc-velocity-benchmark/manuscript/PAPER_DIRECTION.md, sha256: null }
+  claims_ledger:   { path: CLAIMS.yaml,                                                    sha256: null }  # BIOP01-69
+
+# --- 실패·재시작 이력 (append-only) ---
+# runner 가 게이트 실패나 세션 재개마다 한 줄씩 append 한다. 지우지 않는다.
+# 예: { at: "2026-08-04T10:00:00+09:00", event: gate_fail, gate: result_validation,
+#       detail: "p3_concordance diff !=0", commit: abc1234 }
+history: []

docs/HARNESS-LAYERS.md

@@ -0,0 +1,94 @@
+# 하네스 3계층 — core / project profile / run instance (BIOP01-67)
+
+> 이 문서는 "재사용 하네스"라는 주장을 실제 구조와 일치시킨다. 결론부터:
+> **"도메인 슬롯 하나만 바꾸면 된다"는 과소진술이다.** core harness 는 재사용
+> 가능하되, 각 프로젝트는 domain agent·검증 명령·paper direction·산출물 경로·
+> claim별 과학 정책을 담은 **project profile** 을 제공해야 한다.
+
+관련: `harness.yaml`(SSST manifest) · [HARNESS.md](HARNESS.md) · BIOP01-68(RUN_STATE.yaml) · BIOP01-69(CLAIMS.yaml).
+
+---
+
+## 왜 이 문서가 필요한가
+
+`harness.yaml` 의 `roles` 는 재사용 코어 멤버와 도메인 슬롯을 한 파일에 섞어
+둔다. 게이트도 마찬가지로 도메인 무관한 것(무결성 재계산)과 도메인 특화한 것
+(`p3_concordance.py` 같은 HSPC velocity 전용 재계산)이 섞여 있다. 이 때문에
+"도메인 슬롯 하나만 교체"라는 문장이 실제보다 이식을 쉬워 보이게 만든다.
+새 분야로 옮기려면 아래 **project profile** 전체를 새로 써야 한다.
+
+---
+
+## 세 계층
+
+### 1. Core harness — 도메인 무관 (리포·문서로 고정, 프로젝트 간 재사용)
+
+바꾸지 않고 그대로 가져가는 부분:
+
+- **agent 호출 규약** — 자연어 요청 → 역할 라우팅, 전문 agent 실패를 general
+  로 대체 금지(`execution.forbid_generic_fallback`).
+- **artifact contract** — 각 단계 산출물을 파일로 남긴다는 계약.
+- **stage transition** — analysis → result_validation → writing → figures →
+  review → package_validation → claim_defensibility → release 순서.
+- **실패 정책** — 자동 게이트 실패 시 `stop_and_report`, 커밋·발행 금지.
+- **run state** — RUN_STATE.yaml 스키마(BIOP01-68). 값은 run instance.
+- **reviewer 격리 규칙** — venue-reviewer 는 검증 통과 원고만 입력받는다.
+- **release gate** — 저자·소속·IP·corresponding·data_release 사람 승인.
+- **self-check** — harness_doctor 정합성 게이트(BIOP01-66).
+
+코어 멤버(재사용 agent): literature_scout · novelty_strategist ·
+research_methodologist · manuscript_writer · presenter · paper_critic ·
+design · manuscript_condenser · paper_planner · venue_reviewer ·
+production_runner.
+
+### 2. Project profile — 프로젝트별 (프로젝트마다 새로 제공)
+
+`harness.yaml` 의 `project_profile:` 가 가리키는 도메인 특화 묶음. **여기가
+이식 비용의 대부분이다.**
+
+| 구성요소 | BIOP01(현재) 실체 | 새 프로젝트가 제공해야 하는 것 |
+|---|---|---|
+| domain analyst | `hspc-velocity-analyst` | 그 분야 분석 실행 agent |
+| 검증 명령(result_validation) | `p3_concordance.py` · `p3_crossdataset_concordance.py` · `p3_scrambled_null.py` | headline 숫자를 결정론적으로 재계산하는 스크립트 |
+| 데이터셋/결과 경로 | `pipeline/hspc-velocity-benchmark/{results,manuscript,figures}` | 그 프로젝트의 artifact 경로 |
+| paper direction | `manuscript/PAPER_DIRECTION.md` | 연구 질문·서사·차별화 |
+| claim별 과학 정책 | CLAIMS.yaml 의 limitations(예: "실질 비식별성을 완전 비식별성으로 과장 금지") | claim별 금지·한정 규칙 |
+| 필수 그림/표 | figures 스크립트 | 그 논문의 필수 도표 |
+| 평가 지표 | concordance ρ · sign-agreement · profile-likelihood 민감도 | 그 분야 지표 |
+
+### 3. Run instance — 실행마다 (RUN_STATE.yaml 한 파일)
+
+한 번의 생산 실행 상태. run_id · source_commit · stage · 게이트별 통과 기록 ·
+산출물 sha256 · 실패·재시작 이력. 코드가 아니라 상태다. → `RUN_STATE.yaml`
+(BIOP01-68). runner 만 갱신, planner 는 읽기만(BIOP01-70).
+
+---
+
+## 경계 판정 규칙 (어디에 넣을지)
+
+새 구성요소를 추가할 때:
+
+1. **분야가 바뀌어도 그대로 쓰는가?** → core harness.
+2. **분야가 바뀌면 새로 써야 하는가?** → project profile.
+3. **실행마다 값이 바뀌는가?** → run instance(RUN_STATE.yaml).
+
+`p3_*` 스크립트가 core 처럼 보이지만 HSPC velocity 지표를 재계산하므로
+project profile 이다. 반대로 "숫자는 결과 파일에서만"이라는 규칙은 분야와
+무관하므로 core 다.
+
+---
+
+## project profile 스펙 (새 프로젝트 체크리스트)
+
+새 분야로 하네스를 이식할 때 아래를 모두 채워야 "이식 완료"다. 하나라도
+비면 harness_doctor 가 팬텀으로 잡거나(경로/역할) 게이트가 도메인 숫자를
+재계산하지 못한다.
+
+- [ ] `harness.yaml` 의 `project_profile:` 값을 새 프로젝트 키로 교체
+- [ ] domain analyst agent 1개(`roles.domain_analyst.path`)
+- [ ] `gates.result_validation.commands` — headline 숫자 재계산 스크립트
+- [ ] `artifacts.*` — findings·manuscript·figures_dir·paper_direction 경로
+- [ ] `PAPER_DIRECTION.md` — 연구 질문·차별화
+- [ ] `CLAIMS.yaml` — headline claim + claim별 limitations(BIOP01-69)
+- [ ] 필수 그림/표 생성 스크립트
+- [ ] harness_doctor PASS(팬텀 0)로 정합 확인

docs/HARNESS.md

@@ -82,5 +82,6 @@ research-methodologist / literature-scout / novelty-strategist   (기획·근거
 | 산출물 계약 | ✅ 경로 검증(results/, manuscript/, figures/) |
 | 입구(Orchestrator **Skill**) | ✅ `.claude/skills/paper-production-orchestrator/SKILL.md` |
 | 검증 게이트 | ✅ `p3_concordance.py` + `p3_crossdataset_concordance.py` + `p3_scrambled_null.py` 재계산 |
+| 재사용 경계(3계층) | ✅ core / project profile / run instance 분리 — 타 분야 이식은 "슬롯 1개"가 아니라 project profile 전체(analyst·게이트 스크립트·paper direction·CLAIMS) 교체. → [`docs/HARNESS-LAYERS.md`](HARNESS-LAYERS.md) (BIOP01-67) |
 | 개선 루프 | `SESSION-LOG.md`(세션별 회고 누적) |
 | 미결(사람 확정) | 저자·소속·corresponding email·공개 정책 — manuscript-writer의 `<FILL>` |