integration-contract.md

상태: 이 문서는 현재 구현을 기술한다.

통합 계약

외부 시스템(CI/CD 파이프라인, 다른 도구)이 Momos를 호출할 때 지켜야 할 계약이다.

원칙

• 통합은 API를 통해서만 이뤄진다. Momos는 대상 리포에 어떤 파일도 요구하지 않는다(비침습성).
• 프로젝트 선언(목적·비전·범위)은 Host의 Projects 엔티티에 API로 등록한다.
• 검사는 신청서 제출로 트리거되며, 결과는 검사 결과서로 돌아온다.
• 후속 조치가 필요한 지적은 Momos 내부에서 추적되지 않는다 — 호출하는 쪽이 docket 또는 GitHub Issues 등 자신의 이슈 관리 도구로 가져가야 한다.

엔드포인트

Method	Path	설명
POST	/projects	프로젝트를 등록한다(이름·목적·비전·범위 등 선언 정보 포함).
GET	/projects/{id}	등록된 프로젝트를 조회한다.
POST	/projects/{id}/inspection-requests	해당 프로젝트에 대한 검사를 신청한다.
GET	/inspection-requests/{id}	검사 신청서와 그 현재 상태(대기/실행 중/완료/실패)를 조회한다.
GET	/inspection-requests/{id}/report	검사 신청서에 대한 검사 결과서를 조회한다.

검사 신청서 제출은 실행 노드(Worker)에 의해 실제로 처리된다 — 신청서는 대기 → 실행 중 → 완료(또는 실패)로 전환되며, 완료되면 결과서 조회가 실제 내용을 반환한다. Worker는 대상 리포를 체크아웃하고 실행 샌드박스 안에서 명령을 실제로 실행하며 재현한 결함만 보고한다 — 아무것도 재현하지 못하면 결과서는 정직하게 지적 0건으로 완료된다(근거 없는 지적을 내놓지 않는다는 원칙에 따른 결과이지, 검사 도구가 미연결된 상태의 placeholder가 아니다).

안정성 약속

Momos는 아직 0.x 단계이며, 공개 API의 하위 호환성을 아직 약속하지 않는다. 호환성보다 안정성·단순함을 우선한다(CLAUDE.md/AGENTS.md의 트레이드오프 서열 참고).