Close multi-agent plan and add router shadow reporting

This commit is contained in:
dahyeon committed 2026-05-18 19:34:11 -07:00
1 parent f1b30d716d
commit 8156e8c07e
15 files changed
+1303 -204

No files matched your search

+101
View File
@@ -0,0 +1,101 @@
# 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의 전체 회귀가 통과한다.
권장 점검:
```bash
npm run review:stats
npm run review:list -- --include-resolved --limit=20
npm run typecheck
npm test
```
필요하면 별도 consistency script를 만든다.
```text
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는 유지한다.
검증:
```bash
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으로만 상태를 계산한다.
검증:
```bash
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도 갱신한다.
검증:
```bash
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 가능해야 한다.