verify-before-claiming-done · diff
git:20260915.1b5578d to git:20261013.f2be3c7
31 added, 36 removed. Audit A to A.
---
name: verify-before-claiming-done
- description: "Checks a completion claim against output from a command run just now, from the start, before saying done, fixed, passing, merged or ready, or before submitting a task for verification. Covers which command proves the claim, why a cached or partial green does not, how to read exit status instead of a summary line, and how keeper_lane_status shows whether the last Execute actually ran."
+ description: "Checks whether recorded evidence supports a completion claim and its exact scope. Use before saying done, fixed, passing, merged or ready, or submitting a task for verification. Reuse evidence whose source, inputs and conditions still match; inspect changed or missing evidence rather than restarting every check. Separates source review, process success, tests, merge, installed binary and visible runtime behavior. Read command exit status and identify any unverified scope. Follow the repository contract for required checks; ordinary MASC PR review does not require a build, while Release/Tag requires full CI for that head."
---
# 완료를 말하기 전에 검증
- **방금 돌린 검증 출력 없이는 완료를 말하지 않는다.** "될 것이다", "통과할 것이다",
- "고쳤으니 됐다"는 검증이 아니라 예측이다. 안 돌린 것을 됐다고 말하면 다음 사람이 그 말
- 위에 쌓고, 틀린 게 드러나는 시점이 늦을수록 되돌리는 값이 커진다.
-
- ## 다섯 단계
+ 주장하려는 범위와 그 범위를 확인한 증거를 맞춘다. 예상은 결과가 아니다.
+ 준비와 검증을 반복하는 대신, 이미 확인한 것과 아직 확인할 것을 구분한다.
- 말하기 전에 이 순서를 밟는다.
+ ## 확인 순서
- 1. **무엇이 증명하나.** 이 주장을 증명하는 명령을 짚는다. "테스트 통과"면 그 스위트,
- "빌드됨"이면 그 빌드, "머지해도 된다"면 머지할 커밋에서 돈 빌드와 스위트다.
- 2. **처음부터 돌린다.** 방금, 끝까지. 캐시가 성공을 재생하는 도구는 출력 없이 초록을
- 보여준다. 결과가 캐시에서 왔는지 모르겠으면 캐시를 우회해 다시 돌린다.
- 3. **출력을 읽는다.** 종료 코드, 실패 개수, 마지막 줄. 요약 문구가 아니라 종료 코드로
- 판정한다. 도중에 죽은 스위트는 절반짜리 합계를 전부인 것처럼 찍는다.
- 4. **출력이 주장을 덮나.** 초록인 검사가 말하려는 범위를 실제로 덮는지 본다. 컴파일
- 초록은 테스트 초록이 아니고, 한 스위트 초록은 전체 초록이 아니다.
- 5. **그다음에** 명령과 출력을 같이 적어 말한다.
+ 1. **주장의 범위를 정한다.** 소스 수정, 명령 성공, 테스트 통과, 머지, 설치,
+ 실제 화면 확인은 각각 다른 주장이다. Task의 완료 조건도 함께 읽는다.
+ 2. **기존 증거를 확인한다.** 대상 커밋, 입력, 환경, 검사 범위가 여전히 맞으면
+ 기록한 결과를 재사용한다. 바뀐 부분이나 증거가 없는 부분에 필요한 검사만 고른다.
+ exact-head 승인이 필요한 리뷰나 Release/Tag CI는 해당 head의 증거가 있어야 한다.
+ 3. **실행 결과를 읽는다.** 종료 코드와 실패 내용을 확인한다. 도구 호출의 완료가
+ 명령 성공을 뜻하지 않는다. 파이프라인은 앞 단계 실패를 보존하도록 실행한다.
+ 실행 중이거나 결과가 불확실하면 그 상태를 기록하고 먼저 결과를 조회한다.
+ 4. **저장소 계약을 따른다.** MASC 일반 PR은 현재 head의 독립 소스 리뷰가 기준이다.
+ 검증이 필요하면 변경에 맞는 검사를 고른다. Release/Tag는 해당 head의 full CI가
+ 필요하다. 캐시 사용 자체가 실패는 아니다. 입력 일치와 검사 범위를 확인한다.
+ 5. **확인한 만큼 말한다.** 증거의 위치와 아직 확인하지 않은 범위를 함께 적는다.
+ 화면 동작을 요구한 Task는 소스 리뷰나 빌드 성공만으로 끝내지 않는다.
- ## 마지막 Execute 가 실제로 돌았나
+ ## 마지막 Execute가 실제로 돌았나
- `keeper_lane_status` 는 실행 레인이 microvm·원격 SSH 일 때 그 엔드포인트로 마지막으로
- 나간 Execute 가 어떻게 끝났는지 `last_dispatch` 로 보여준다. `outcome` 이
- `payload_finished` 면 `status`(`exit=0` 등)가 명령의 종료 상태이고, `lane_failed` 면 명령이
- 아니라 레인이 실패한 것이다. `at_unix` 가 내가 돌린 시각보다 앞서거나 `status` 가 기억과
- 다르면, 돌리지 않은 것을 돌렸다고 믿고 있는 것이다. 이 기록은 엔드포인트마다 하나라서,
- 그 뒤에 다른 Execute 가 나갔으면 그 호출의 기록으로 바뀐다. 이것은 검증의 절반이다. 명령이
- 실제로 끝났다는 것만 알려주고, 그 출력이 주장을 덮는지는 위 3·4단계가 판정한다.
- docker 레인은 이 기록이 없어 `last_dispatch` 가 늘 `null` 이고, 서버가 재시작해도 비워진다.
- 그러니 `null` 을 "아무것도 안 돌았다"로 읽지 않는다.
+ `keeper_lane_status`의 `last_dispatch`는 microvm·원격 SSH 엔드포인트의 마지막
+ Execute 결과다. `outcome=payload_finished`면 `status`가 명령 종료 상태이고,
+ `lane_failed`면 실행 레인이 실패한 것이다. `at_unix`와 대상 엔드포인트를 확인한다.
+ 다른 Execute가 실행되면 이 기록은 바뀌므로 해당 작업의 출력 참조도 보존한다.
+ Docker 레인이나 서버 재시작 뒤에는 `last_dispatch=null`일 수 있다.
+ null만으로 미실행을 단정하지 않는다. 이 기록은 명령 실행 여부를 보여줄 뿐,
+ 출력이 완료 조건을 충족하는지는 따로 판단한다.
- ## 멈추는 신호
+ ## 자주 생기는 착각
- - "될 것이다 / 통과할 것이다 / 고쳤으니 됐다" 라고 쓰고 있다 → 아직 안 돌렸다.
- - 합성 데이터나 목업만으로 "완성"이라 부르고 있다 → 실제 입력으로 끝까지 한 번 돌린다.
- - 테스트를 돌린 트리와 올린 커밋이 다르다 → 올린 커밋에서 다시 확인한다.
- `git commit --amend` 는 스테이지된 변경만 얹는다.
- - CI 결과를 안 보고 "머지 완료"라 말하고 있다 → push 뒤 결과를 본다.
- - "이 오류는 안 난다"고 말하려는데, 지켜본 시간이 그 오류가 원래 나던 간격보다 짧다 →
- "없다"가 아니라 "아직 못 봤다"다.
- - 상태 코드나 목록 표시만 보고 판정하고 있다 → 실제 내용을 연다. HTTP 200 이 오류
- 화면을 그릴 수 있고, squash 병합은 원래 커밋 SHA 를 남기지 않는다.
+ - HTTP 200, 목록의 성공 표시, 마지막 요약 한 줄만으로 실제 내용을 확인했다고 한다.
+ - 소스 검사나 목업 결과를 설치된 제품의 동작 증거로 쓴다.
+ - head나 입력이 바뀌었는데 이전 결과를 그대로 현재 결과라고 쓴다.
+ - 증거가 하나 부족하다는 이유로 이미 인정된 다른 검사까지 모두 반복한다.
+ - push나 병합 요청의 접수를 머지 완료로 쓴다. PR의 merged 상태와 결과를 읽는다.