경고만 하던 AKM lint를 실제로 멈추는 Gate로 바꿨다

한 줄 요약

AKM 처리 과정에서 필수 항목 하나를 일부러 빼고, Gate가 실제로 작업 완료를 막는지 확인했다. 이후 빠진 부분만 고쳐 다시 검사했고 정상적으로 통과했다. 즉, 문제를 알려주기만 하던 검사기를 문제가 있으면 완료되지 않도록 막는 Gate로 바꿨다.

이런 분들께 도움돼요

• lint나 검증 보고서가 있지만 자동화가 실제로 멈추는지는 확인하고 싶은 분

• 에이전트 하네스의 Gate를 안전하게 시험해 보고 싶은 분

• 전체 시스템을 다시 만들지 않고 최소 수리와 재평가를 적용하고 싶은 분

• PASS 결과뿐 아니라 실패 전후 Proof도 남기고 싶은 분

1. 무슨 업무인가

앞선 기본과제에서 my-akm의 인박스 처리를 하네스 계약으로 정리했다. 사용자가 분류를 요청하면 SAF이 자료를 읽고, 원본을 보존하고, 정리본과 작업 로그를 만들고, lint와 인벤토리를 갱신한다. C-SAF이 계약 기준과 Proof를 대조해 완료 여부를 판정한다.
(여기서 SAF와 C-SAF는 각 실행과 검증을 담당하는 분리된 역할자를 칭함)

첫 번째 사례글에서는 WEEK3 강의 PDF 한 건을 실제로 분류하고 기본 실행 영수증을 발행했다. 하지만 정상 실행 한 번으로는 Gate가 정말 잘못된 입력을 막는지 알 수 없었다.

이번 임무는 실제 AKM을 망가뜨리지 않고 다음 질문에 답하는 것이었다.

필수 조건을 하나 일부러 어기면 Gate가 실제로 멈추고, 가장 작은 부분만 고친 뒤 같은 기준으로 다시 통과할 수 있는가?

2. 설계 계약

확장 과제의 범위와 성공 조건을 먼저 정리했다.

실험 공간은 Obsidian 검색에서 제외된 tmp/harness-break-test/로 제한했다. 실험용으로 선정한 결함 있는 자료 처리과정이 전체 AKM에 미치는 영향을 최소화하기 위함이었다. 상시 자동화나 외부 서비스 변경 없이도, 작은 시뮬레이션으로 Gate의 행동을 확인할 수 있다.

3. 어디서 막혔나

모의 10-sources/personal 문서에 메타데이터와 근거 상태를 넣고 ## 요약만 일부러 뺐다. 그 상태로 실제 AKM과 같은 lint를 실행했다.

Errors: 0
Warnings: 1
missing-section:summary
Exit code: 0

경고 내용은 정확했으나, 문제는 종료 코드였다. 사람은 보고서를 읽고 멈출 수 있지만, 자동 워크플로는 보통 종료 코드 0을 성공으로 해석한다. 즉, 기존 lint는 문제를 탐지했지만 종료 코드 0을 회신해서 다음 단계 진행을 차단하지는 못했다.

경고 발견 = 검사기 작동
종료 코드 0 = 자동 Gate 차단 실패

강의에서 말한 “게이트가 막지 못했다면 그 자리는 아직 하네스가 아니다”가 정확히 이 상황이었다. 문서의 오류보다 Gate 자체의 경계가 먼저 깨져 있었다.

4. 무엇을 바꿨나

기존 lint의 일반 진단 동작을 바꾸지는 않았다. 경고를 참고용으로 보고 싶은 사용자도 있을 것이므로, 기존 사용법까지 모두 실패 처리하면 영향 범위가 커지기 때문이다.

대신 완료 Gate에서 선택적으로 사용할 --fail-on-warn 엄격 모드 옵션만 추가했다.

python tools\akm_lint.py `
  --root E:\Projects_Codex\my-akm `
  --fail-on-warn

엄격 모드에서는 오류나 경고가 하나라도 있으면 종료 코드 1을 반환한다. 같은 불완전 문서를 엄격 모드로 다시 검사하자 다음처럼 실제 차단이 일어났다.

Warnings: 1
Exit code: 1
Verdict: REPAIR

그다음 SAF가 최소 수리를 위해 테스트 문서의 누락된 ## 요약만 추가했다. 메타데이터와 본문을 다시 쓰지 않았고, 통과시키기 위해 lint 기준을 낮추지도 않았다.

5. 실행 영수증

실행 영수증에 실패부터 재평가까지 모두 저장했다.

Trace

모의 AKM 생성, 요약 누락, 일반 lint 실행, 종료 코드 결함 발견, 엄격 Gate 추가, 불완전 입력 차단, 최소 수리, 동일 기준 재평가 순서를 기록했다.

Proof

• 실패 입력 스냅샷

• 경고 1건과 일반 모드 종료 코드 0

• 엄격 모드 종료 코드 1

• ## 요약만 추가된 수리본

• 재평가 오류 0건, 경고 0건, 종료 코드 0

• 변경된 lint 구현과 실행 절차

Verdict

최종 판정은 PASS였다. 실패를 숨기거나 삭제하지 않고, 실패 입력과 출력도 수리 후 결과와 함께 보존했다.

Repair

수리는 두 책임으로 나눴다.

• Gate 수리: 경고에도 종료 코드 0을 반환하던 lint에 선택적 엄격 모드를 추가했다.

• 입력 수리: 테스트 source note에 누락된 ## 요약만 추가했다.

Gate와 입력을 구분하지 않았다면 문서만 고치고 “테스트 성공”이라고 끝냈을 것이다. 이번에는 왜 차단되지 않았는지까지 확인하면서 Gate 자체도 검증 대상이 됐다.

6. 무엇이 달라졌나

이전 lint는 문제를 발견해 경고로 알려주는 진단 도구에 가까웠다. 경고가 있어도 종료 코드가 0이었기 때문에, 자동 처리 과정에서는 검사를 통과한 것으로 판단하고 다음 단계로 넘어갈 수 있었다.

이제는 목적에 따라 두 가지 방식으로 사용할 수 있다.

일반 진단 모드
→ 오류와 경고를 확인
→ 경고가 있어도 작업을 계속할 수 있음

엄격 완료 Gate
→ 오류나 경고가 하나라도 있으면 종료 코드 1
→ 완료 처리를 중단하고 REPAIR로 이동
→ 수리 후 같은 기준으로 다시 검사

가장 큰 변화는 “문제를 발견했다”와 “문제가 해결될 때까지 완료를 막았다”를 구분하게 된 것이다. 이제 엄격 Gate를 사용하는 작업은 필수 항목이 빠진 상태로 완료 처리되지 않는다. 경고가 발생하면 REPAIR로 보내고, 빠진 부분을 고친 뒤 같은 명령과 기준으로 다시 통과해야 한다.