Policy to Harness Lifecycle

한눈에 보기

Policy to Harness Lifecycle은 문서 규칙이 실제 차단 장치로 승격되는 과정을 설명합니다. 처음에는 policy로 시작하더라도, 반복되는 실수나 위험이 확인되면 soft guide, hard gate, eval, runtime verdict로 단계가 올라갑니다.

• 핵심 질문: 어떤 규칙은 문서로 충분하고, 어떤 규칙은 hook이나 eval로 강제해야 하는가?
• 읽는 대상: AI 운영 규칙을 실행 가능한 하네스로 바꾸려는 사람
• 연결 문서: Harness — Hooks & Gates, Evidence Dashboard, Retrospective Loop

이 문서에서 확인할 것

• policy, soft guide, hard gate, eval, runtime verdict의 승격 기준
• 위험도와 승인 강도를 함께 보는 방식
• PROMOTE, RETRY, ROLLBACK, HUMAN_REVIEW 판정의 의미

Policy는 설명하고, Harness는 막는다

ai-rules의 핵심 판단은 문서에서 시작합니다. 하지만 위험한 작업을 실제로 줄이려면 문서만으로는 부족합니다. 반복되는 실수는 keystone-hub의 hook, eval, doctor, replay fixture 같은 실행 장치로 승격해야 합니다.

stateDiagram-v2
  [*] --> Policy: 원칙 작성
  Policy --> SoftGuide: 경고와 체크리스트
  SoftGuide --> HardGate: 반복 위반
  HardGate --> Eval: 자동 검증 필요
  Eval --> RuntimeVerdict: PROMOTE / RETRY / ROLLBACK / HUMAN_REVIEW
  RuntimeVerdict --> DecisionLog: 판단 기록
  DecisionLog --> Policy: 규칙 보강

승격 기준

단계	형태	사용 시점	예시
Policy	Markdown rule	처음 원칙을 설명할 때	”시크릿은 커밋하지 않는다”
Soft Guide	warning, reminder	실수 가능성이 있지만 차단은 이른 때	계획 누락, 증거 부족 알림
Hard Gate	PreToolUse hook, commit hook	반복되거나 피해가 큰 위반	.env 커밋, force push, 보호 브랜치 직접 변경
Eval	golden set, replay fixture	품질을 수치로 비교해야 할 때	QA 회귀, hook bypass 재현 테스트
Runtime Verdict	structured event	push, deploy, rollback 판단	PROMOTE, RETRY, HUMAN_REVIEW

Risk와 Approval 매핑

quadrantChart
  title 작업 위험도와 승인 강도
  x-axis "낮은 외부 영향" --> "높은 외부 영향"
  y-axis "높은 가역성" --> "낮은 가역성"
  quadrant-1 "P3 명시 승인"
  quadrant-2 "P1 범위 자동"
  quadrant-3 "P0 자동 실행"
  quadrant-4 "P2 배치 승인"
  "문서 읽기": [0.12, 0.18]
  "lint 실행": [0.25, 0.28]
  "docs 수정": [0.32, 0.38]
  "소규모 버그 수정": [0.45, 0.46]
  "의존성 변경": [0.67, 0.67]
  "DB 스키마 변경": [0.82, 0.82]
  "force push": [0.94, 0.93]

등급	의미	기본 처리
R0	즉시 되돌릴 수 있음	자동 실행 가능
R1	되돌릴 수 있지만 비용이 큼	사람 승인 필요
R2	데이터 손실이나 외부 상태 변경	명시 확인 또는 사람 직접 실행
P0	관찰과 조회	승인 없음
P1	승인된 범위 안의 저위험 수정	실행 후 보고
P2	티켓/브랜치/스프린트 단위	배치 승인
P3	배포, push, 인증, DB, 결제	명시 승인

Hook 분류

분류	역할	대표 패턴
Safety	위험 명령 차단	force push, .env, 보호 브랜치, 비가역 DB
Evidence	완료 선언 검증	build, QA, console, network, test evidence
Quality	코드와 UI 품질 검사	formatter, type, API contract, visual QA
Session	컨텍스트와 handoff 유지	recap, state save, pending work
Automation	반복 작업 자동화	sync, doctor, self-improve, trend harvest

Runtime Verdict

flowchart LR
  A["hook / eval 실행"] --> B{"결과 판정"}
  B -->|통과| C["PROMOTE<br/>다음 단계 허용"]
  B -->|고칠 수 있음| D["RETRY<br/>수정 후 재실행"]
  B -->|회귀 증가| E["ROLLBACK<br/>복구 경로 필요"]
  B -->|증거 부족 / 위험 초과| F["HUMAN_REVIEW<br/>사람 판단"]

PROMOTE는 성공 신호이고, HUMAN_REVIEW는 실패가 아닙니다. 증거가 부족하거나 위험이 큰 작업을 사람 판단으로 돌리는 것은 하네스의 정상 동작입니다.

운영 체크리스트

• 같은 실수가 2회 이상 반복되면 문서가 아니라 hook 후보로 분류한다.
• hook은 패턴명보다 차단하려는 피해를 기준으로 이름 붙인다.
• 새 gate를 만들면 replay fixture나 dry-run 방법을 같이 둔다.
• 위험한 예외는 “우회법”이 아니라 “승인 경로”로 문서화한다.
• 완료 보고에는 실행한 검증과 남은 리스크를 분리해서 적는다.

Source Notes

이 문서는 ai-rules의 Harness Engineering, AI Risk Tiers, Runtime Contract와 keystone-hub의 hook registry, eval bridge, replay fixture 구조를 공개용으로 요약했습니다.