# HARNESS_LIVE_ACTIVATION_ROLLBACK_PLAN (task-2647)

- version: v1
- recorded_at: 2026-05-24
- live_change_count: 0
- chair_signature_required: true (per-axis 분리 서명 가능)
- rollback_confidence: HIGH (3축 모두 L1 30초~5분 무중단 경로 확보)

## 1. Rollback Layer 정의

| Layer | 시간 | 방법 | 영향 |
|---|---|---|---|
| L1 | ~30초 | ENV gate / hook entry unset | 즉시 무중단 |
| L2 | ~5분 | settings.json git restore + 봇 재시작 0 (settings reload 자동) | 짧은 영향 |
| L3 | ~15분 | PR revert + main rollback | 전체 재배포 |

## 2. Per-axis Rollback

### 2.1 축 1 (task-2646 helper)
- **트리거**: helper import 실패 / contract regression FAIL / authority marker 오인식
- **L1 (불가)**: helper는 ENV gate가 없으므로 L1 즉시 무중단 불가능
- **L2 (~5분)**: 영향 최소 — 신규 파일 6개만 추가됨. 기존 코드는 import 안 함. 
  - 명령: `git revert <axis1-merge-sha>` → 신규 파일 6 삭제
  - 단, 축 2가 이미 머지된 상태라면 cross-axis L2 발동 (§3.1)
- **L3 (~15분)**: PR 단위 revert + main rollback
- **검증**: `pytest tests/test_callback_registration_helper_selftest.py` 6/6 PASS 부재 확인 (helper 삭제됨)

### 2.2 축 2 (task-2644+1 control plane v2)
- **트리거**: hook timeout > 10초 / SessionStart 발화 실패 / Stop verifier가 정상 종료 차단 / next_action_runner_v2 무한 루프
- **L1 (~30초)**: settings.json에서 3 hook entry만 제거 (파일 자체는 main에 보존). 
  - 명령: `python3 -c "import json; p='~/.claude/settings.json'; d=json.load(open(p)); d['hooks']={}; json.dump(d, open(p,'w'),indent=2)"` 또는 hooks 키에서 SessionStart/Stop/UserPromptSubmit 3 entry 제거
  - claude-code 다음 세션부터 hook 발화 0
- **L2 (~5분)**: settings.json 전체 git restore + 봇 재시작
  - 명령: `git -C ~/.claude restore settings.json` (단 ~/.claude이 git repo인 경우만)
  - 또는 backup 파일 복원: `cp ~/.claude/settings.json.backup-{ts} ~/.claude/settings.json`
- **L3 (~15분)**: axis 2 머지 commit revert + 신규 파일 32 제거. 
  - 명령: `git revert <axis2-merge-sha>`
  - cross-axis 영향: 축 1 helper는 보존 (축 2 v2만 제거)

### 2.3 축 3 (task-2643 PreToolUse)
- **트리거**: false positive (정상 Bash가 deny 됨) / hook timeout > 5초 / 봇 전체 차단
- **L1 (~30초, BEST)**: ENV gate 즉시 비활성화 
  - 명령: `unset CLAUDE_PRE_TOOL_USE_HOOK_ENABLED` (현재 셸) 또는 `~/.bashrc`/`~/.zshrc`에서 제거
  - hook은 등록 상태 유지하지만 ENV gate가 unset → hook 내부 첫 줄에서 즉시 allow 반환 (코드 검증 필요: pre_tool_use_anu_guard.py에 ENV 체크 존재 확인)
- **L2 (~5분)**: settings.json에서 PreToolUse hook entry 제거
  - 명령: hooks/PreToolUse[0] 키만 삭제 → 다음 세션부터 hook 발화 0
- **L3 (~15분)**: PR #146 git revert (49 file)
  - 명령: `gh pr list --search "Revert task-2643"` 확인 후 `git revert <axis3-merge-sha>` PR 생성
- **추가 안전망**: backup `cp ~/.claude/settings.json ~/.claude/settings.json.backup.$(date +%s)` (axis 3 활성화 전 필수)

## 3. Cross-axis Rollback

### 3.1 축 1 rollback 시 축 2 영향 (cross-axis L2)
- **위험**: 축 2 staged 코드가 축 1 helper 3개 import → 축 1 revert 시 축 2 fail-closed
- **차단 정책**: 축 2가 live merge된 상태에서 축 1만 단독 revert 금지
- **올바른 순서**: 축 2를 먼저 rollback → 그 다음 축 1 rollback
- **자동화**: `python3 -m utils.callback_collector_helper_integration --require-helpers` 명령으로 helper 부재 시 fail-closed (이미 helper_integration.py에 구현됨)

### 3.2 축 3 rollback 시 축 1/2 영향 (없음)
- 축 3는 stdlib only · 축 1/2와 import 의존 0
- 축 3 rollback이 축 1/2 동작에 영향 0
- 단, 축 3가 settings.json을 공유 수정하므로 axis 2 entry와 axis 3 entry가 같은 파일에 공존. axis 3만 제거 시 axis 2는 보존됨 (JSON key 분리)

### 3.3 동시 rollback (모든 축)
- 시나리오: 봇 전체 차단 / settings.json 손상
- 절차: 
  1. ENV `CLAUDE_PRE_TOOL_USE_HOOK_ENABLED=0` 또는 unset (L1 즉시)
  2. settings.json 복원 (backup 또는 PR pre-merge 상태)
  3. git revert axis 2 → axis 1 (순서 중요)
  4. helper.selftest + integration.selftest 모두 부재 확인

## 4. Backup 의무 (live activation 전 필수)

각 Phase 직전 회장 서명 후 dispatch에서 다음을 자동 수행:
- `cp ~/.claude/settings.json ~/.claude/settings.json.backup.task-{axis_id}-{ts}`
- git tag `pre-axis-{axis_id}-live-activation-{ts}` (main HEAD 기준)
- 본 task에서 backup 0 (실 활성화 0이므로)

## 5. Rollback Trigger 명세

각 axis chair signature에 다음 trigger를 명시한다 (chair signature template §rollback_triggers):

- **축 1**: helper.selftest FAIL / pytest tests/regression/callback_authority_gate/ FAIL / authority marker 오인식 1건 이상
- **축 2**: integration.selftest FAIL / SessionStart hook timeout > 10초 / Stop verifier가 정상 세션 차단 / regression 66 test 중 1건 이상 FAIL
- **축 3**: PreToolUse false positive 1건 이상 (정상 Bash가 deny) / hook timeout > 5초 / fail-closed exception 발생률 > 0.1%

## 6. Rollback Confidence Matrix

| 축 | L1 | L2 | L3 | confidence |
|---|---|---|---|---|
| 1 | N/A | ~5min | ~15min | MEDIUM |
| 2 | ~30sec | ~5min | ~15min | HIGH |
| 3 | ~30sec | ~5min | ~15min | HIGH |

축 1은 L1 (ENV gate) 부재 → MEDIUM. 단, 영향 자체가 additive이므로 부담 낮음.

끝