@tienne/gestalt 0.37.0 → 0.39.0

package/skills/review/SKILL.md

@@ -29,13 +29,14 @@ outputs:
   - changeContext
   - reviewReport
   - verdict
+  - continuityVerdict
   - postedReview
 ---
 
 # Review Skill
 
 execute 세션 없이 PR·브랜치·커밋의 변경사항을 직접 리뷰 파이프라인에 주입해 검토합니다.
-변경 파일을 수집하고, 3종 리뷰 에이전트(보안·성능·품질)로 다각도 리뷰한 뒤, Pass/Block 판정과 마크다운 리포트를 생성합니다. 리뷰 대상이 GitHub PR이면 `code-review-writer` 에이전트가 작성한 인라인 코멘트로 PR에 게시까지 이어집니다.
+변경 파일을 수집하고, 3종 리뷰 에이전트(보안·성능·품질)로 다각도 리뷰한 뒤(**결함 심급**), `continuity-judge`가 변경 전체의 목표 정합성과 일관성을 감독하고(**정합 심급**), Pass/Block 판정과 마크다운 리포트를 생성합니다. 리뷰 대상이 GitHub PR이면 `code-review-writer` 에이전트가 작성한 인라인 코멘트로 PR에 게시까지 이어집니다.
 
 ## 사용 방법
 
@@ -155,9 +156,34 @@ ges_execute {
 
 `systemPrompt`가 요구하는 JSON 스키마(severity·category·file·line·message·suggestion)를 준수합니다.
 
+### 3.5단계: 정합 심급 판단 (continuity-judge)
+
+`review_consensus`를 호출하기 **전에** 정합 심급을 먼저 판단합니다. 결함 심급(3단계 리뷰 에이전트)이 "부분에 결함이 있나"를 봤다면, 정합 심급은 "부분의 합이 목표를 이루나"를 봅니다 — 국소 결함으로는 안 잡히는 **목표 이탈(drift)과 전체 일관성**입니다.
+
+`ges_agent { action: "get", name: "continuity-judge" }`로 에이전트 시스템 프롬프트를 가져온 뒤(원리 에이전트라도 `get`으로 조회됩니다), 그 관점에서 **개별 이슈가 아니라 변경 전체**를 아래 세 축으로 판단합니다. 판단 기준은 `reviewIntent.purpose`(0단계에서 수집), 없으면 `spec.goal`, 그것도 없으면 변경 파일에서 추론한 목표입니다.
+
+- **목표 정합(goal)**: 이 변경(전체 diff)이 명시된 목적을 향해 가는가? 목적과 무관하거나 반하는 변경이 섞여 있지 않은가?
+- **일관성(consistency)**: 변경 파일 간 네이밍·API·패턴이 일관된가? 주변 코드의 기존 컨벤션과 이어지는가?
+- **이탈(drift)**: 스펙 제약(`reviewContext.spec.constraints`)이나 원래 의도와 모순되는 지점이 있는가?
+
+판단 결과를 `continuityVerdict`로 만들어 4단계로 넘깁니다:
+
+```
+continuityVerdict = {
+  coherent: true | false,        // 정합 심급 통과 여부 (false면 결함이 없어도 Block)
+  driftFindings: [               // 목표 이탈·불일치 항목 (없으면 빈 배열)
+    { axis: "goal" | "consistency" | "drift", file?, message }
+  ],
+  escalate: true | false,        // 라인 수정으로 해결 불가 → 재설계 필요 신호
+  summary: "..."
+}
+```
+
+정합 심급에 아무 이탈도 없으면 `{ coherent: true, driftFindings: [], escalate: false, summary: "..." }`로 넘기면 됩니다.
+
 ### 4단계: 합의 및 판정 (review_consensus)
 
-모든 에이전트의 리뷰를 병합해 Pass/Block을 판정합니다:
+모든 에이전트의 리뷰(결함 심급)와 3.5단계의 `continuityVerdict`(정합 심급)를 함께 넘겨 Pass/Block을 판정합니다:
 
 ```
 ges_execute {
@@ -169,11 +195,20 @@ ges_execute {
     blockedBy: [...],
     summary: "...",
     overallApproved: true | false
-  }
+  },
+  continuityVerdict: { ...3.5단계 산출물... }
 }
 ```
 
-응답의 `report`(마크다운)를 4.5단계로 넘깁니다.
+엔진이 두 심급을 합쳐 판정합니다 — **결함(critical/high)이 없고 `coherent: true`여야 통과**입니다. `continuityVerdict`를 생략하면 결함 심급만으로 판정하는 기존 동작 그대로입니다.
+
+응답 해석:
+
+- `status: "review_passed"` → 두 심급 모두 통과.
+- `status: "review_blocked"` → 결함이 남아 Block. `canFix`가 true면 6단계 `review_fix`로 자동 수정 루프.
+- `status: "review_escalated"` (`escalate: true`, 결함은 없음) → 정합 심급이 목표 이탈을 감지. **`review_fix`로 보내지 않습니다.** 라인 수정이 아니라 스펙·설계 이탈이므로, 사용자에게 **"이 변경은 목표에서 벗어나는 부분이 있어 라인 수정으로는 부족합니다. 스펙 재정리(similarity-crystallizer) 또는 결정 재확인이 필요해 보여요"** 라고 알리고 판단을 넘깁니다.
+
+정합 심급의 `driftFindings`는 엔진이 리포트에 **"Continuity Instance (정합 심급)" 섹션**으로 렌더링하므로, 4.5단계 humanize에서 함께 다듬어집니다.
 
 ### 4.5단계: 리포트 워싱 (humanize-monolith)
 
@@ -182,7 +217,7 @@ ges_execute {
 `ges_agent { action: "get", name: "humanize-monolith" }`로 에이전트 시스템 프롬프트를 가져온 뒤, 해당 관점에서 리포트를 윤문합니다. 이슈 내용(severity·file·line·message)은 수정하지 않고, 설명 문장의 어투만 자연스럽게 다듬습니다.
 
 humanize-monolith는 두 룰북을 함께 적용합니다.
-- **어투**: `../../role-agents/technical-writer/references/author-voice.md` — 제안형("~하는 게 좋을 것 같아요/어떨까요?"), 온기·물결·이모지(코멘트당 1개 안팎)는 보존하고, `c:`/`r:` 접두어·`[출처]` 태깅·"…권장." 체언 종지(Claude artifact)는 쓰지 않습니다.
+- **어투**: `../../role-agents/technical-writer/references/author-voice.md` — 제안형("~하는 게 좋을 것 같아요/어떨까요?"), 온기·물결·이모지(코멘트당 1개 안팎)는 보존하고, `[출처]` 태깅·"…권장." 체언 종지(Claude artifact)는 쓰지 않습니다. (파이프라인 리포트는 severity 섹션 구조라 `r:`/`c:`/`a:` 접두어를 붙이지 않습니다 — 접두어는 4.7단계 PR 인라인 코멘트에만 씁니다.)
 - **음차·AI-tell**: `../../role-agents/technical-writer/references/ai-tell-quick-rules.md` — 안 굳어진 음차("소스 오브 트루스" 등)는 한글 의역하되, 굳어진 화이트리스트(컴포넌트·토큰·렌더링·트레이드오프 등)는 그대로 둡니다.
 
 즉 리뷰 파이프라인 리포트도 인라인 코멘트와 동일하게 voice + 음차가 함께 처리됩니다.
@@ -229,14 +264,25 @@ gh pr view <target> --json number,headRefName,baseRefName,url 2>/dev/null
 **코멘트 본문 작성 (code-review-writer).** `ges_agent { action: "get", name: "code-review-writer" }`로 에이전트 시스템 프롬프트를 가져온 뒤, 그 관점에서 4단계 `mergedIssues`의 각 이슈를 인라인 코멘트 본문으로 작성합니다. 이슈의 `file`·`line`·`severity`는 그대로 두고, `message`·`suggestion`을 에이전트 voice로 다듬어 코멘트 본문을 만듭니다.
 
 - code-review-writer는 `author-voice.md`(제안형·온기·물결·이모지)와 `ai-tell-quick-rules.md`(음차 교정)를 이미 내장하므로 **별도 humanize-monolith 패스를 거치지 않습니다.**
-- 에이전트 룰에 따라 `c:`/`r:` 접두어, `[출처]` 태깅, "…권장." 체언 종지는 쓰지 않습니다. 이건 Claude artifact이지 실제 리뷰어 어투가 아닙니다.
-- severity는 본문 첫 줄에 `[critical]`처럼 대괄호 라벨로만 표기합니다.
+- 에이전트 룰에 따라 `[출처]` 태깅, "…권장." 체언 종지는 쓰지 않습니다. 이건 Claude artifact이지 실제 리뷰어 어투가 아닙니다.
+- **강제성은 `r:`/`c:`/`a:` 접두어로 표기합니다** (레포에 자체 리뷰 컨벤션이 없을 때의 기본값). 코멘트 본문 맨 앞에 severity에 따라 붙입니다 — `r:` 꼭 반영(critical/high), `c:` 웬만하면 반영(warning), `a:` 사소한 의견(suggestion). 접두어는 강제성 라벨이고 본문 어투는 그대로 제안형입니다.
+- **개행은 GitHub 렌더링 기준으로 조립합니다.** GitHub GFM은 한 줄 개행(`\n`)을 무시하고 같은 문단으로 이어 붙이므로, 줄을 실제로 나누려면 **빈 줄(`\n\n`)로 블록을 분리**해야 합니다. severity 라벨 → 문제 설명 → 제안 → 코드 스니펫을 각각 빈 줄로 띄우고, 여러 줄 코드는 fenced code block(` ```lang ``` `)으로 감쌉니다. 한 줄 개행으로 이어 붙이면 PR에서 한 덩어리로 뭉쳐 읽기 어렵습니다 (code-review-writer의 Output Format 개행 규칙과 동일).
+
+**리뷰 이벤트 결정.** 코멘트 접두어의 조합으로 리뷰 전체의 `event`를 정합니다 (r/c/a → GitHub 리뷰 이벤트 대응).
 
-**게시 (gh api).** 작성한 코멘트를 한 번의 리뷰로 묶어 게시합니다. 이슈마다 개별 호출하지 않고 `comments` 배열로 모읍니다.
+- 이슈 중 하나라도 `r:`(critical/high)가 있으면 → `REQUEST_CHANGES`
+- `r:`은 없고 `c:`(warning)만 있으면 → `COMMENT`
+- `a:`(suggestion)만 있거나 이슈가 없으면 → `APPROVE`
+
+이는 4단계 `overallApproved`(결함 심급 blocking 여부)와도 일치합니다 — blocking 이슈가 있으면 `r:`이 존재하므로 `REQUEST_CHANGES`가 됩니다. 단 `APPROVE`/`REQUEST_CHANGES`는 리뷰 상태를 바꾸는 행위이므로, 위 **"게시 확인"**에서 사용자 동의를 받은 뒤에만 게시합니다.
+
+> **본인 PR 예외**: GitHub는 PR 작성자 본인이 자기 PR을 `APPROVE`/`REQUEST_CHANGES`하는 걸 막습니다(422). `gh pr view --json author`와 `gh api user`로 작성자가 현재 사용자와 같은지 확인하고, 같으면 `event=COMMENT`로 폴백해 게시합니다 (접두어 r/c/a는 본문에 그대로 유지). 이때 사용자에게 "본인 PR이라 승인/변경요청 상태는 못 걸어서 코멘트로 남겼어요"라고 한 줄 알립니다.
+
+**게시 (gh api).** 작성한 코멘트를 한 번의 리뷰로 묶어 게시합니다. 이슈마다 개별 호출하지 않고 `comments` 배열로 모읍니다. `event`는 바로 위에서 결정한 값을 넣습니다.
 
 ```bash
 gh api repos/{owner}/{repo}/pulls/{number}/reviews \
-  -f event=COMMENT \
+  -f event=<REQUEST_CHANGES|COMMENT|APPROVE> \
   -f body="<요약 한 줄 — code-review-writer가 작성한 overall summary>" \
   --input <(jq -n '{ comments: [ { path: "...", line: 42, side: "RIGHT", body: "..." } ] }')
 ```
@@ -260,7 +306,10 @@ ges_execute {
 }
 ```
 
-`fixContext.fixPrompt`에 따라 파일을 수정하고 구조 검사(lint·build·test)를 실행한 뒤, 2단계의 `review_start`부터 다시 반복해 재리뷰합니다.
+`fixContext.fixPrompt`에 따라 파일을 수정하고 구조 검사(lint·build·test)를 실행한 뒤, 2단계의 `review_start`부터 다시 반복해 재리뷰합니다. **재리뷰는 3단계(결함)와 3.5단계(정합)를 모두 다시 돌립니다** — 수정으로 결함과 정합성이 함께 해소됐는지 두 심급으로 새로 판정합니다.
+
+`fixContext`에는 결함 이슈(`issues`) 외에 **`driftFindings`** 가 실릴 수 있습니다. 정합 심급이 Block했지만 escalate는 아닌, 즉 라인 수정으로 해소 가능한 정합성 항목(네이밍·패턴 불일치 등)입니다. 결함과 함께 이 항목도 반영해야 재리뷰의 정합 심급을 통과합니다. (escalate 항목은 fixContext에 실리지 않습니다 — 재설계 경로입니다.)
+
 `review_exhausted` 응답이 오면 최대 시도 횟수를 초과한 것이므로 리포트를 보여주고 남은 이슈는 수동 수정하도록 안내합니다.
 
 ## 결과 표시