diff --git a/ai_scientist/01_two_layer_architecture.md b/ai_scientist/01_two_layer_architecture.md index c0f4c76..b483dc4 100644 --- a/ai_scientist/01_two_layer_architecture.md +++ b/ai_scientist/01_two_layer_architecture.md @@ -29,7 +29,11 @@ AI Scientist를 **하나의 거대한 자율 에이전트로 만들지 않았다 1. **재사용성.** 레이어 B(문헌·집필·검수·발표)는 도메인과 무관한 **연결조직(connective tissue)** 이다. `docs/HARNESS.md`의 로스터에서 대부분 멤버가 "재사용"으로 표시된다. 다른 논문/프로젝트(BIOP01 등)에 그대로 복사 가능. 도메인 특수성은 **단 하나의 슬롯** `spatialpatho-analyst`에 격리된다. 2. **관심사 분리.** 분석 레이어는 "숫자가 맞나"(누수·baseline·재현성)를 책임지고, 생산 레이어는 "그 숫자를 정직하게 논문으로 쓰나"를 책임진다. 검증 게이트가 두 레이어 경계에 놓인다(아래). -3. **성숙도 차이 흡수.** 프로젝트는 분석 진행 단계라 집필-단계 산출물(manuscript/figures)이 아직 없다. 생산 레이어는 `` 플레이스홀더로 **미리 배선만 해두고**, 실제 경로는 첫 write-up-ready 결과가 나오면 팀이 채운다 (`docs/HARNESS.md` §4 "현재 하네스 상태"). +3. **성숙도 차이 흡수.** 집필-단계 산출물이 없던 시기에도 생산 레이어를 `` 플레이스홀더로 **미리 배선만 해둘 수 있었다** — 없는 것을 없다고 표시해두면 구조가 먼저 서고 값은 나중에 들어온다. + +> 🔴 **정정(2026-08-04): "집필-단계 산출물이 아직 없다"는 더 이상 사실이 아니다.** +> 초판은 *"분석 진행 단계라 manuscript/figures가 아직 없다"* 고 적었으나, 현재 `manuscript/sections/`에 **5개 섹션이 존재**하고 Discussion 한계 절까지 실물로 작성돼 있다(`04_discussion.md` §한계, Critic 승인조건 1 충족 판정 완료). +> ⚠️ 다만 **`SKILL.md`는 아직 이 사실을 반영하지 못했다** — L10이 *"집필 이전 단계 산출물이 아직 없다"*, L18이 ``라고 말한다. 실제 원고 경로는 **`manuscript/sections/`** 다. 하네스 문서가 현실보다 뒤처진 상태이며, 이 설계서는 그것을 **감추지 않고 표시**한다([03](03_routing_and_artifact_contract.md) 참조). ## 레이어 A — 도메인 분석 파이프라인 diff --git a/ai_scientist/03_routing_and_artifact_contract.md b/ai_scientist/03_routing_and_artifact_contract.md index aa04046..7aa8ded 100644 --- a/ai_scientist/03_routing_and_artifact_contract.md +++ b/ai_scientist/03_routing_and_artifact_contract.md @@ -24,6 +24,16 @@ 핵심: **단일 단계 요청은 해당 에이전트로 직행**하지만, **여러 단계를 엮는 요청은 오케스트레이터 스킬로 모여** 정해진 순서로 실행된다. +### 실행 모드 분기 — 오케스트레이터가 먼저 확인하는 3가지 + +스킬은 요청을 받자마자 **무엇을 돌릴지부터 정한다**(`SKILL.md` *실행 모드 분기*): + +1. **산출물이 있는가·최신인가** — result 파일 / manuscript / figures 존재 확인 +2. **분기** — 없음·"풀 파이프라인"·"제출 준비" → **전체** · 있음 + 부분요청 → **해당 단계만** · "지적 반영"·"최신 결과로 갱신" → **하류 단계만** +3. ⭐ **mock 여부 확인** — `spatialpatho-analyst`의 LLM 기반 sub-분석이 **offline mock**으로 돌았는지 보고, mock이면 산출물에 **"실 결과 아님 / 데모"를 명시**한다 + +> 3번이 이 하네스의 성격을 잘 보여준다. **데모로 돌린 것을 실 결과처럼 넘기지 않는 장치**이고, "없는 것을 없다고 표시한다"(아래 §"지어내지 않기")의 실행 시점 버전이다. + ## (B) 산출물 계약 — 단계 간에 무엇을 넘기나 각 단계는 **다음 단계가 읽을 파일**을 산출물로 남긴다. 근거: `CLAUDE.md` *산출물 계약* 표, `docs/HARNESS.md` §2. @@ -45,6 +55,40 @@ 이 계약 덕분에 **부분 재실행**이 가능하다 — "그림만 다시"는 figure 스크립트만, "critic 지적 반영"은 하류 집필 단계만 돌린다. 오케스트레이터의 실행 모드 분기가 이를 처리한다 (`SKILL.md` "실행 모드 분기"). +## 품질 기준선 — 계약 위에 얹히는 공통 규율 + +산출물 계약이 *무엇을 넘기나*라면, 품질 기준선은 *어떤 상태로 넘기나*다 (`SKILL.md` *품질 기준선*). + +| 규율 | 내용 | +|---|---| +| **스코프** | **NOT drug-response prediction** — 약물 구조 입력 없음, 가설 출력. 통계 뒷받침 없는 우월 주장 금지, 단 **weak ≠ zero**(약한 신호를 없는 것으로 만들지도 않는다) | +| **숫자 출처** | **결과 파일에서만.** *메모리에서 재유도 금지* — 기억으로 숫자를 되살리지 않는다 | +| **지표** | class imbalance → **AUPRC + AUC 병기** | +| **분할** | leakage-controlled(환자 단위) split을 **명시** | +| **그림** | 결과 파일에서 **생성**(하드코딩 금지) · **95% CI + paired test 표시** · **번호는 첫 언급 순** | +| **감사** | GPU 제공처를 Acknowledgments에 명시 | + +> **"숫자는 결과 파일에서만, 메모리 재유도 금지"** 와 **"그림 하드코딩 금지"** 는 같은 실패를 두 자리에서 막는다 — +> *검증된 적 없는 숫자가 조용히 문서로 들어오는 것.* 검증 게이트 ①·②와 CI 숫자 드리프트 검사가 그 마지막 방어선이다([04](04_automated_review_and_governance.md)). + +## 실행·보고 계약 — 실패했을 때와 끝났을 때 + +계약은 성공 경로만 규정하지 않는다 (`SKILL.md` *실패 처리* · *마무리*). + +**멈춤 조건** +- **검증 게이트 실패 → 멈춘다.** 무엇이 왜 실패했는지 보고하고 **커밋·발행하지 않는다** +- **mock 경로로 돌았으면 → "데모"임을 명시**한다 +- **산출 파일이 안 만들어지면 → 재시도 1회 후 보고**한다 (무한 재시도로 시간을 태우지 않는다) + +**마무리 보고에 반드시 들어갈 것** +- 무엇을 **어떤 순서로** 돌렸나 +- 어떤 **파일이 갱신**됐나 +- **verify 통과 여부** +- 남은 일을 **done / in-progress / blocked** 로 구분 +- **부분 재실행이면 안 건드린 단계도 명시** ← 빠뜨리면 "전부 최신"으로 오해된다 + +> 마지막 항목이 중요하다. 부분 재실행 후 무엇을 **안** 돌렸는지 말하지 않으면, 읽는 사람은 파이프라인 전체가 갱신됐다고 믿는다. 이것도 "없는 것을 있는 척하지 않는다"의 한 형태다. + ## 스키마로 굳힌 계약 산출물 중 일부는 자연어가 아니라 **JSON 스키마**로 강제된다: @@ -55,6 +99,9 @@ ## "지어내지 않기"를 계약에 박았다 -산출물 계약 곳곳에 `` 플레이스홀더가 있다(예: ``). 이는 **아직 없는 것을 없다고 표시**하는 장치다. `CLAUDE.md`와 `SKILL.md` L10은 반복해서 **"headline 숫자·주장을 지어내지 말 것"** 을 명령한다. 즉 계약은 "무엇을 넘길지"뿐 아니라 **"없는 것을 있는 척 넘기지 마라"** 까지 규정한다. 이 원칙은 `CLAUDE.md` *완료의 정의* #6과 *Absolute Prohibitions*(발표자료 숫자를 기준값으로 쓰기 금지, 도구의 "못 찾겠다"를 통과로 처리 금지)로 강화된다. +산출물 계약 곳곳에 `` 플레이스홀더가 있다(예: `SKILL.md:18`의 ``). 이는 **아직 없는 것을 없다고 표시**하는 장치다. + +> ⚠️ **다만 ``은 스스로 갱신되지 않는다.** 위 플레이스홀더는 **이미 낡았다** — 원고는 존재하고 경로도 `manuscript/sections/`다(`SKILL.md` L10·L18은 아직 "미존재"라고 말한다). +> **"없는 것을 없다고 표시하는 장치"가 "생긴 뒤에도 없다고 말하는" 상태**가 되면, 그 표시는 보호가 아니라 **오정보**가 된다. ` 이 구분이 루프의 핵심이다. 사람이 리뷰 **노동**을 하면 몇 주가 걸리고 그동안 프로젝트가 멈춘다. +> 사람이 리뷰 **판단**만 하면 분 단위로 끝난다. 자동화가 줄이는 것은 판단의 수가 아니라 **판단에 도달하기까지의 노동**이다. + ### 🔴 판정 어휘의 빈칸 — "더 해도 pass가 안 되는 것"을 적을 자리가 없다 판정 어휘는 두 축이다(`schemas/critic_report.schema.json` 실측): 종합 `critic_status` = `pass · caution · reject`, 개별 항목 `check.status` = 여기에 `not_applicable` 추가. 티어 처리(`blocked · provisional · needs_human`)는 **누가 확인하느냐**를 정하는 별개 축이다. diff --git a/ai_scientist/README.md b/ai_scientist/README.md index 0d70482..8f7f5d3 100644 --- a/ai_scientist/README.md +++ b/ai_scientist/README.md @@ -68,11 +68,24 @@ | 2026-07-27 | 금지 항목 신설 — **티켓·파일을 열지 않고 상태 단정 금지**(JIRA 조회 시 `comment` 필수) | `9963b08` | [04](04_automated_review_and_governance.md) | | 2026-08-03 | **CI 검증 레이어 신설** — PR/push에서 결정론 검증기 3종 blocking 실행. 검수가 **3층**(CI 기계 → AI 적대 → 사람 게이트)이 됨 | BIOP02-106/107 · `.github/workflows/critic-validators.yml` | [04](04_automated_review_and_governance.md) | +### 2026-08-04 — 스킬(`SKILL.md`) 대조 동기화 + +설계가 바뀐 게 아니라 **설계서가 스킬을 덜 기술하고 있었다.** 대조 결과 누락 8건을 보강하고 낡은 서술 1건을 정정했다(설계 변경이 아니므로 위 표에는 넣지 않는다). + +| 보강 | 어디에 | +|---|---| +| 실행 모드 분기 3단계 + ⭐ **offline mock 확인 → "데모" 명시** | [03](03_routing_and_artifact_contract.md) | +| **품질 기준선** — 숫자는 결과 파일에서만(메모리 재유도 금지) · 그림 하드코딩 금지 · 95% CI + paired test · 번호는 첫 언급 순 · **weak ≠ zero** | [03](03_routing_and_artifact_contract.md) | +| **실행·보고 계약** — 멈춤 조건(재시도 1회 후 보고 등) · 마무리 보고 `done/in-progress/blocked` · **부분 재실행 시 안 건드린 단계도 명시** | [03](03_routing_and_artifact_contract.md) | +| `required_followups` — 사람에게 넘기는 것은 **노동이 아니라 판단** | [04](04_automated_review_and_governance.md) | +| 🔴 **정정**: "집필-단계 산출물이 아직 없다" → 원고는 **존재**(`manuscript/sections/` 5섹션 + Discussion 한계) | [01](01_two_layer_architecture.md) | + **미해결로 남은 것 (설계서가 기록하는 미완성 지점):** - 🔴 **검증 게이트 ①의 실행 명령이 없다** — BIOP02용 결정론 재계산 스크립트가 리포에 부재. `auto_review_gate.py`는 문서 규칙 검사이지 수치 재계산이 아니다. 채워질 때까지 사람이 수동 대조. - 🔴 **`auto_review_config.json`의 `ai_review.agents`가 아직 `["paper-critic", "reviewer"]`** — `SKILL.md`는 5단계를 `paper-critic` 단독으로 고쳤는데 config가 따라오지 않았다. `enabled=false`(dry-run)라 실害는 없으나 **활성화 전 정리 필요**. - 🔴 **게이트 ① 이후의 "수정"에 권한 제약이 없다** — `manuscript-writer`가 `Write`를 보유해 리뷰 반영 중 검증된 숫자를 다시 쓸 수 있고, 방어는 게이트 ②의 **사후 재대조**뿐이다. 같은 규율이 `paper-critic`에는 **도구 수준으로**(쓰기 권한 없음) 걸려 있어, 하네스 안에 *권한으로 막은 곳*과 *말로만 막은 곳*이 섞여 있다. 부수로 `venue-reviewer`는 `tools:` **미선언 → 전체 도구 상속**이라 격리가 프롬프트로만 강제된다. → [01](01_two_layer_architecture.md), [02](02_agents_and_roster.md), [03](03_routing_and_artifact_contract.md) - 🔴 **판정 어휘에 "더 해도 pass가 안 되는 것"을 적을 칸이 없다** — `critic_status`(`pass·caution·reject`)에 *"현재 데이터로는 식별 불가"* 가 없어 그런 항목이 `caution`으로 뭉뚱그려진다. BIOP02-75가 이 빈칸 때문에 **티켓 성공 기준 자체를 재정의**해 우회했다. → [04](04_automated_review_and_governance.md) - 🔴 **비판 자체를 검증하는 층이 없다** — 루프가 비판을 생산(③)한 뒤 곧바로 확인 주체 배정(④)으로 넘어가, **Critic의 산출물만은 Critic을 거치지 않는다.** 2026-07-27 하루에 Critic 코멘트 4건이 작성자 본인에게 사후 정정된 것이 그 비용이다. → [04](04_automated_review_and_governance.md) +- 🔴 **`SKILL.md` 자체가 현실보다 뒤처져 있다** — L10 *"집필 이전 단계 산출물이 아직 없다"* · L18 ``. 실제로는 `manuscript/sections/`에 5개 섹션이 있고 Discussion 한계까지 작성됐다. **` ⚠️ 위 3건은 **관찰된 갭이지 채택된 설계 변경이 아니다.** 따라서 위 "변경 이력"에는 넣지 않았다. 셋 다 고치려면 `.claude/agents/*`·`schemas/*`·`auto_review_config.json`을 건드려야 하고, 그것은 **Critic이 자기 검수 기준을 스스로 정하는 일**이라 `CLAUDE.md`의 `❌ anti-self-reference`에 걸린다 → **Leader 승인 사안.** 특히 판정 어휘는 기존 `critic_report.json`의 유효성에 영향을 주므로 **BIOP02-75 최종 서명 이후**가 맞다.