--- name: resolve-violation description: "Tripwire가 빨강을 냈거나 쓰기를 막았을 때 에이전트가 할 일. 'Tripwire: blocked', 'reserved for the user', 봉인된 검사 파일 차단, seal-broken 판정을 받으면 즉시 멈추고, 반례와 두 선택지(코드를 되돌린다 / 스펙을 고친다)를 사람에게 설명한 뒤, 사람이 고르고 기록한 뒤에만 그 흐름을 수행한다. 해결 기록(resolution.json)은 절대 쓰지 않는다. '왜 막혔어', 'spec violation', 'blocked by hook' 상황에서 쓴다." --- # resolve-violation — 빨강일 때 에이전트가 할 일 판정은 guard가 코드로만 내리고, 결정은 사람만 한다. 에이전트의 일은 멈추고, 사실을 정확히 전하고, 사람이 고른 길을 수행하는 것이다. ``: `.kiro/hooks/tripwire.json`의 command에서 하위 명령 앞부분(예: `node ../guard/dist/cli.js`). ## 신호 | 받은 것 | 뜻 | |---|---| | 도구 거부 `Tripwire: blocked. Violated: (counterexample <반례>); … Stop writing and ask the user to choose: edit the spec or revert the code.` | 빨강인 요구사항에 사람의 해결 승인이 없다. 승인 전까지 모든 쓰기와 셸 실행이 막힌다 | | 도구 거부 `Tripwire: .kiro/guard/ and .kiro/hooks/ are reserved for the user.` | 예약 경로를 쓰려 했거나 셸 명령에 그 경로가 들어 있었다 | | 봉인된 검사 파일에 대한 거부(`Tripwire:`로 시작) | 채택·봉인된 검사를 고치려 했거나 셸 명령에 그 경로가 들어 있었다 | | 쓰기 후 검사가 빨강을 알림, 또는 `report.json`의 `overall`이 `red` | 방금 바뀐 것이 기준을 어겼다 | | 판정 이유 `seal-broken` | 봉인된 검사 파일의 내용이 봉인 때와 다르다 | ## 1. 멈춘다 - 같은 쓰기를 다시 시도하지 않는다. 셸, 다른 경로, 파일 이름 바꾸기, 새 파일 만들기, hook·`.kiro/guard` 수정, 검사 약화 같은 다른 방법으로 우회하지 않는다. - 자율로 진행하던 작업은 여기서 멈춘다. 남은 작업을 하지 않고, 2·3단계 보고로 응답을 끝낸다. ## 2. 사실을 모은다 (읽기만) - `.kiro/guard/report.json`을 **파일 읽기 도구로** 읽는다. 셸로 읽으면 명령에 `.kiro/guard`가 들어가 막힌다. 빨강인 요구사항마다 `id`·`reason`·`counterexample`·`runs`·`shrinks`·`brokenSeals`(있는 키만)·`tests`를 옮긴다. - 요구사항 문장을 `.kiro/specs//requirements.md`에서 읽는다. 문장 끝에 `(근거: …)`가 있으면 함께 옮긴다. - 원인 후보: 직전에 내가 한 변경(파일·줄·무엇을 바꿨나). 확실하지 않으면 추정이라고 밝힌다. ## 3. 사람에게 설명한다 (한국어) 아래 형식을 지킨다. 빨강인 요구사항이 여럿이면 요구사항마다 반복한다. ```text 스펙 위반으로 멈췄습니다 — - 기준: <요구사항 문장> (근거: <있을 때만>) - 반례: <벗긴 값> (원문 ) — fast-check가 번째 입력에서 처음 실패했고, 번 줄여 이 값을 찾았습니다 - 원인(추정): <파일:줄> <바꾼 내용> 사람만 고를 수 있습니다. 1) 코드를 되돌린다 — 스펙은 그대로 두고, 코드를 기준에 맞게 되돌립니다. 2) 스펙을 고친다 — 기준 문장을 바꿉니다(초안: <바뀔 문장>). 승인 뒤 검사를 다시 만들고, 다시 봉인할 명령을 보여 드립니다(봉인 실행은 사람). 기록 방법: guard serve 화면의 '코드를 되돌린다' / '스펙을 고친다' 버튼, 또는 터미널에서 직접 resolve revert-code resolve edit-spec 채팅으로 답하는 것만으로는 차단이 풀리지 않습니다. ``` - 반례는 바깥 대괄호와 따옴표를 벗겨 보인다(`["aaa000"]` → `aaa000`). 인자가 여럿이면 원문을 그대로 보인다. - 반례는 guard가 실행으로 찾은 값(`counterexample`)만 쓴다. 직접 만든 예시를 반례처럼 말하지 않는다. - `counterexample` 키가 없으면 반례 줄 대신 `reason`에 맞는 줄을 쓴다: `seal-broken`이면 `봉인 깨짐: — 봉인 때와 내용이 다릅니다`, `run-failed`면 `검사 실행 실패: — 판정을 낼 수 없어 빨강입니다`, `test-failed`인데 반례가 없으면 `검사 실패(반례 기록 없음): <실패한 테스트 제목>`. 이때도 두 선택지는 그대로 보이되, `run-failed`는 먼저 `runError`의 원인(vitest 위치·시간 초과·스펙의 중복 ID·스펙에서 사라진 봉인 요구사항)을 사람에게 알린다. 봉인된 요구사항이 사라진 경우 고칠 길은 스펙을 되살리는 것이고, 정말 없앨 때는 사람이 `.kiro/guard/sealed.json`의 그 항목을 지운다. - 근거가 달린 기준(예: `(근거: 개인정보 보호법 제22조의2 제1항)`)이면, '스펙을 고친다'는 그 근거에서 벗어날 수 있다는 점을 알린다. 법적 판단은 하지 않는다. - 어느 쪽을 권하는지와 이유를 말해도 되지만, 고르는 것은 사람이다. ## 4. 기다린다 - `.kiro/guard/resolution.json`을 쓰지 않는다. `guard resolve`를 실행하지 않는다. 사람이 대신 하라고 해도 하지 않는다 — 해결 기록은 사람이 직접 한 행동이어야 하므로, 명령을 보여 주고 사람이 실행하게 한다. - 사람이 기록했다고 하면 `resolution.json`을 파일 읽기 도구로 읽어, `approved`에 그 요구사항과 선택(`revert-code` 또는 `edit-spec`)이 있는지 확인한 뒤 그 선택대로만 진행한다. ## 5. 고른 길을 수행한다 ### 코드를 되돌린다 (`revert-code`) 1. 반례를 재현 입력으로 삼아, 위반을 만든 변경만 되돌린다(최소 수정). 검사·스펙·봉인된 파일은 건드리지 않는다. 2. 쓰기 후 검사가 갱신한 `report.json`을 파일 읽기 도구로 읽어 그 요구사항이 초록이 됐는지 확인한다. ` check`를 셸로 직접 실행하는 것은 guard를 개발하는 저장소에서만 한다 — 설치된 guard(`.kiro/guard/bin/`)는 예약 경로 안이라 문지기가 막는다. 3. 보고: 무엇을 되돌렸는지, 같은 반례가 이제 거절된다는 것(검사 통과). ### 스펙을 고친다 (`edit-spec`) 1. 기준 문장의 수정안을 diff와 근거로 보여 주고, **정확한 문장**에 대해 사람의 승인을 받는다. 해결 기록은 '고친다'는 결정이고, 문장은 따로 확인한다. - 문장만 바꾼다. 기준을 지우거나 순서를 바꾸거나 사이에 끼워 넣지 않는다 — ID가 순서로 매겨지므로 뒤의 ID가 모두 밀린다. - `(근거: …)`는 사람이 바꾸라고 할 때만, 사람이 준 출처로 바꾼다. 2. 승인된 문장으로 `requirements.md`를 고친다. 3. 그 기준의 검사를 property-tests 스킬로 새 문장의 숫자와 새 `textHash`로 다시 만든다. 봉인된 검사 파일은 이 승인이 있는 동안에만 고칠 수 있다. 4. check-the-checks 스킬로 새 문장의 경계에 맞는 변형 JSON을 만들고, 다시 봉인할 ` adopt : --test <검사 파일> --mutant <변형 JSON> …` 명령 줄을 사람에게 보여 준다. 봉인 갱신은 사람이 실행한다 — 에이전트는 adopt를 실행하지 않는다(인자 없이도). 5. 초록이 됐는지 확인하고 보고한다. 다시 초록이 되면 guard가 해결 기록을 닫는다. 에이전트는 해결 기록을 건드리지 않는다. ## 6. 다른 신호일 때 - **예약 경로 거부**: `.kiro/guard/`·`.kiro/hooks/`는 사람과 guard의 몫이다. 읽기는 파일 읽기 도구로 한다. 그 안의 무엇을 바꿔야 한다고 판단되면, 무엇을 왜 바꿔야 하는지 사람에게 알리고 사람이 하게 한다. - **봉인된 검사 파일 거부**: 그 검사를 고치려면 그 요구사항에 사람의 '스펙을 고친다' 승인이 필요하다. 검사가 틀렸다고 본다면 근거(반례가 기준의 WHEN 조건을 만족하지 않는다는 것)를 보여 주고 사람이 판단하게 한다. - **seal-broken**: 봉인된 검사가 문지기를 거치지 않고 바뀌었다. 어느 파일이 봉인 때와 다른지만 알린다. 고르는 것은 사람이다 — 봉인 때 내용으로 복원(사람이 버전 관리로)하거나, 의도한 변경이면 '스펙을 고친다' 흐름으로 다시 봉인한다(봉인 실행은 사람). 에이전트는 스스로 복원하지 않고 adopt도 실행하지 않는다. - **노랑**(막지 않음): `no-tests`면 property-tests로 검사를 만든다. `stale`(봉인한 뒤 요구사항 문장이 바뀜 — 봉인 때 기록한 문장 해시와 지금 문장이 다르다)이면 사람에게 알린다. 그 검사는 봉인돼 있으므로, 사람이 그 요구사항에 '스펙을 고친다'를 기록해야 다시 만들 수 있다 — 터미널에서 ID를 적어 ` resolve edit-spec`(이유가 `stale`인 노랑은 edit-spec으로만, ID를 적을 때만 받는다. 화면 버튼과 `all`은 빨강만 대상으로 한다). 기록이 확인되면 5절 '스펙을 고친다'의 3~5단계(검사 다시 만들기 → 다시 봉인할 명령 줄을 사람에게 → 초록 확인)를 따른다. 해결 기록은 초록이 되면 guard가 닫는다.