3.5 KiB
Supervisor Resolution Hash Sunset Procedure
Last verified: Iter8 implementation branch, 2026-05-18.
Supervisor resolution은 현재 두 곳에 기록된다.
- Audit stream:
lolympus-agent:review-resolutions - Compatibility hash:
lolympus-agent:review-resolved:{reviewId}
Hash는 기존 read path와 rollback을 위한 compatibility layer다. 실제 sunset은 최소 1-2개월 운영 후 아래 조건을 만족할 때만 진행한다.
선결 조건
- Dual-write 운영 기간이 2개월 이상이다.
- Stream과 hash의 resolution 데이터 일치율이 100%다.
review:list,review:show,review:resolve,review:stats가 stream 기반 확인으로 대체 가능한 상태다.- 최근 2주간 supervisor resolution 관련 incident가 없다.
- Sunset 실행 전 main branch의 전체 회귀가 통과한다.
권장 점검:
npm run review:stats
npm run review:list -- --include-resolved --limit=20
npm run typecheck
npm test
필요하면 별도 consistency script를 만든다.
scripts/verify-dual-write-consistency.ts
이 script는 lolympus-agent:review-resolutions의 최신 resolution과 lolympus-agent:review-resolved:{reviewId} hash를 비교해 divergence를 출력해야 한다.
Sunset 단계
Step 1. Hash write 중단
src/skills/supervisor/review-queue.ts의 resolveSupervisorReview()에서 setHash()와 expireKey() 호출을 제거한다. Stream append는 유지한다.
검증:
npm run typecheck
npm test -- src/skills/supervisor/review-queue.test.ts src/operations/cli.test.ts
Rollback: 해당 commit revert. 기존 hash TTL 동안 read fallback은 유지된다.
Step 2. Stream-only write로 1개월 운영
새 resolution은 stream에만 쌓이고, 기존 hash는 TTL까지 남는다. 이 기간 동안 review:list/show/stats가 정상 동작하는지 확인한다.
관찰 항목:
- unresolved item이 비정상적으로 늘지 않는가
- resolution history가 누락되지 않는가
- 운영자가
review:show에서 이전 resolution을 확인할 수 있는가
Rollback: setHash()와 expireKey()를 복구한다.
Step 3. Hash read fallback 제거
getSupervisorReview()와 listSupervisorReview()에서 hash lookup을 제거하고, resolution stream join으로만 상태를 계산한다.
검증:
npm run review:list -- --include-resolved --limit=5
npm run review:stats
npm test -- src/skills/supervisor/review-queue.test.ts src/operations/cli.test.ts
Rollback: hash lookup 코드를 복구한다. Step 1 이후 새 데이터는 hash에 없으므로 rollback 전에 stream 기반 backfill이 필요한지 판단한다.
Step 4. 기존 hash 정리
TTL이 짧으면 자연 만료를 기다린다. 운영상 즉시 정리가 필요하면 cleanup script를 별도 PR로 만든다.
주의: cleanup script는 반드시 dry-run을 기본값으로 둔다.
Step 5. 상수와 문서 정리
SUPERVISOR_RESOLVED_HASH_PREFIX 상수와 관련 env/문서 언급을 제거한다. docs/service-evaluation-operations.md의 Redis key schema도 갱신한다.
검증:
rg "review-resolved|SUPERVISOR_RESOLVED_HASH_PREFIX" src docs
npm run lint
npm test
Rollback 원칙
- Step 1-2는 단순 revert로 rollback 가능하다.
- Step 3 이후 rollback은 stream-to-hash backfill 필요 여부를 먼저 판단한다.
- Step 4 cleanup 이후에는 hash 데이터 복구를 기대하지 않는다.
- 모든 단계는 작은 PR로 나누고, 각 PR은 독립 revert 가능해야 한다.