# task-2779_b 작업 보고서 — Axis B: Stop hook terminal enforcer (dry-run)

- 작업 ID: task-2779_b
- 팀: dev2-team (오딘)
- 완료 후보 상태명: `TERMINAL_CALLBACK_ENFORCEMENT_AXIS_B_STOP_HOOK_DRYRUN_IMPLEMENTATION_DONE_ACTIVE_FALSE`
- 작성일: 2026-06-29
- 승인 범위: dry-run enforcer 코드 + 격리 fixture 테스트 + **PR 후보 작성까지만** (회장 2026-06-29 한정승인)
- merge_policy: **none — 봇 merge 금지.** ANU 독립검증 → fresh Gemini → CI → 회장 승인 별도

---

## S (Situation, 상황)

축 A(`task-2779_a`, pre-push terminal guard, PR #259 머지 완료)에 이어, 터미널 콜백 강제(terminal callback enforcement) 설계 §D·§E의 **축 B**를 구현한다. 봇 **종료(Stop) 시점**에 terminal artifact(report/.done/callback envelope)가 존재하는지 감지하고, 부재 시 어떤 artifact를 남겨야 하는지 marker/manifest로 보고하는 enforcer가 필요하다. 기존 surfacing 레이어(`dispatch/terminal_artifact_index.py`)는 이미 존재하므로 이를 재사용한다.

## C (Complication, 문제)

종료 시점 강제는 잘못 만들면 **봇의 정상 종료를 차단**하거나 **실제 운영 canonical(`/home/jay/workspace`)에 마커를 오염**시킬 수 있다. 회장 한정승인은 매우 좁다: 실제 Stop hook 설치 0 / 실제 종료 차단 0 / strict·blocking 0 / 실제 canonical marker 0. 즉 **코드는 작성하되 결선·차단·운영 쓰기는 전부 금지**된 dry-run 전용이어야 하며, 검증조차 운영 경로를 건드리면 안 된다.

## Q (Question, 핵심 질문)

종료를 절대 차단하지 않고, 운영 canonical을 절대 건드리지 않으면서, terminal artifact 부재를 격리 환경에서 감지·기록하는 enforcer를 어떻게 안전하게 구현·검증하는가?

## A (Answer, 해결)

`dispatch/terminal_artifact_index.py`의 `build_manifest`/`surface_manifest`를 재사용하는 얇은 dry-run enforcer를 작성하고, **운영 canonical 쓰기를 코드 레벨에서 차단**하는 안전장치를 추가했다. 모든 검증은 tmp 격리 root에서만 수행한다.

### 핵심 설계
1. **dry-run 불변식**: `run_enforcer`/`main`의 모든 경로에서 `exit_code=0`, `blocked=False`. 종료 차단 코드 자체가 없음.
2. **운영 canonical 거부 안전장치** (요구 6/9 강화): `_is_production_canonical()`이 canonical_root를 `Path.resolve(strict=False)`로 비교하여 `/home/jay/workspace`로 해석되면 surface를 **수행하지 않고** `DRYRUN_PRODUCTION_CANONICAL_REFUSED` 마커만 반환. resolve 실패 시 보수적으로 운영으로 간주(거부). CLI `--canonical-root`는 **required=True**(기본값 없음)로 실수 방지.
3. **artifact 부재 판정**: build_manifest가 `TERMINAL_CALLBACK_MISSING` 반환 시 `STOP_HOOK_ENFORCED_TERMINAL_RESULT`로 승격 + `TERMINAL_CALLBACK_MISSING` 동반 기록.
4. **fail-open**: 내부 예외 시 crash·traceback 없이 `ENFORCER_INTERNAL_ERROR_FAIL_OPEN` 마커 + exit 0.
5. **경로 방어 재사용**: 외부 path input은 별도 처리 없이 build_manifest 내부 `_safe_artifact_path`(resolved containment) 통과 → traversal 무회귀.

---

## 생성/수정 파일 목록

생성 (2건, origin/main 대비 diff = 정확히 이 2개만):
- `scripts/stop_hook_terminal_enforcer.py` (+299) — dry-run Stop hook terminal enforcer
- `tests/regression/test_stop_hook_terminal_enforcer_2779.py` (+469) — 격리 회귀 테스트 10건

forbidden_paths 변경 0 (finish-task.sh / pre_push_terminal_guard.py / terminal_artifact_index.py / dispatch.py / .git/hooks / .claude / .github 전부 무변경).

## 모델 사용 기록
- 토르(백엔드, enforcer 스크립트): **sonnet** — 일반 로직 구현
- 헤임달(테스터, 격리 회귀 테스트): **sonnet** — 테스트 설계/검증 (haiku 미사용)
- 미미르(UX/UI)·프레이야(프론트): 미활성 (백엔드/테스트 전용 작업으로 해당 역할 없음)
- 팀장(오딘, Opus): 설계/분배/검토/통합/검증만 수행 (직접 코딩 없음)

## 테스트 결과

`pytest` 통합 결과: **49 passed** (0.34s)
- 신규 `test_stop_hook_terminal_enforcer_2779.py`: **10 passed**
  1. present fixture → terminal_missing=False + WORKTREE_LOCAL_PRESENT + tmp index 생성
  2. absent fixture → STOP_HOOK_ENFORCED_TERMINAL_RESULT + TERMINAL_CALLBACK_MISSING 마커
  3. interrupted partial(.done.tmp만) → 부재 감지 + 마커
  4. dry-run 비차단(present/absent 모두 exit 0, blocked False)
  5. 내부 오류 주입 → fail-open(ENFORCER_INTERNAL_ERROR_FAIL_OPEN, crash 없음)
  6. malicious rel path(../../etc/passwd, /etc/passwd) → containment 거부(부재 취급)
  7. marker tmp root에만 생성 + 운영 canonical 지정 시 거부·운영 미생성 구조 검증
  8. self-key/raw key/cokacdir/16자리 hex 정적 부재 + subprocess/os.system/.git/hooks 정적 부재
  9. 2778/축A build_manifest·surface_manifest 무회귀 스모크
- 무회귀: `test_pre_push_terminal_guard_2779.py` 8 passed, `test_terminal_artifact_visibility_2778.py` 31 passed

## L1 스모크테스트 결과 (실제 CLI 실행)

- **서버 재시작**: 해당없음 (subprocess/스크립트 작업 — 서버 없음)
- **API 응답 확인**: 해당없음. 대신 실제 CLI 2회 실행으로 실동작 검증:
  - L1-A (격리 tmp root, artifact 부재): `exit_code=0`, `status=STOP_HOOK_ENFORCED_TERMINAL_RESULT`, `refused_production=false`, marker가 `/tmp/.../canonical/memory/events/terminal_artifact_index/task-2779b-smoke.json`에 실제 생성됨 (MARKER_IN_TMP_OK).
  - L1-B (canonical=`/home/jay/workspace`): `exit_code=0`, `refused_production=true`, `surfaced_index_path=""`, statuses에 `DRYRUN_PRODUCTION_CANONICAL_REFUSED` 포함. **운영 경로에 json 미생성 확인(PROD_UNTOUCHED_OK)** — before=0/after=0.
- **스크린샷**: 해당없음 (CLI/백엔드 작업, JSON stdout으로 대체 첨부)

pytest PASS에 더해 실제 프로세스 실행으로 dry-run 비차단·운영 미접촉을 관측 검증함.

## 발견 이슈 및 해결

- **이슈**: 브랜치명 `task/task-2779_b-dev2`의 underscore(`_b`)가 pre-commit/pre-push 가드 정규식(`^task/(task-[0-9]+([.+][0-9]+)?)-`)에 매칭되지 않아 차단됨.
  - **분류**: task 문서에 명시된 **알려진 deviation B** (branch underscore).
  - **해결**: task에서 승인한 공식 `TASKCTL_BYPASS=1` + `TASKCTL_BYPASS_REASON`(evidence atomic 기록)으로 commit/push 수행. branch-pattern 사유 1건만 사용. 다른 가드 우회 없음.

## 게이트 결과

- **G1 설계**: affected_files(스크립트+테스트 2건)가 allowed_resources와 일치, 다른 팀 겹침 없음. PASS.
- **G2 구현**: 헤임달(테스터) 기능 테스트 10건 + 무회귀 39건 PASS, L1 실동작 검증. PASS.
- **G3 머지**: PR #260 후보 생성. **merge_policy=none이므로 봇 머지 미수행** — ANU 독립검증 → fresh Gemini → CI → 회장 승인 경로로 위임.

## 머지 판단

- **머지 필요**: No (봇 merge 금지. PR 후보까지만)
- **브랜치**: task/task-2779_b-dev2
- **워크트리 경로**: /home/jay/workspace/.worktrees/task-2779_b-dev2
- **PR**: https://github.com/Jeon-Jonghyuk/dev_workspace/pull/260
- **머지 의견**: 코드/테스트 격리 검증 완료, diff 2파일로 한정, 운영 경로 미접촉 코드 차단 확인. dry-run 불변식(종료차단 0)·운영 marker 0 충족. 실제 결선/머지는 후속 승인(ANU 독립검증→fresh Gemini→CI→회장) 대상.

## 승인 경계 준수 체크 (요구/검증 대조)

- 실제 Stop hook 설치 0 ✓ / 실제 종료 차단 0 ✓ / strict·blocking 0 ✓ / 실제 pre-push hook 설치 0 ✓
- 실제 canonical(`/home/jay/workspace`)에 dry-run marker 0 ✓ (코드 차단 + L1 관측)
- finish-task.sh 본체 변경 0 ✓ / P0c·축A 산출물 무변경 ✓
- callback fire 0 / real fire 0 / driver 0 / systemd·cron 0 ✓
- raw key·ANU key literal 0 ✓ (정적 테스트 통과) / dev self-key callback fire 0 ✓
- ACTIVE=false 유지 ✓ / 새 PR 후보 생성(머지 0) ✓
- expected_files 밖 수정 0 ✓ / forbidden paths 변경 0 ✓

## 비고

- callback_schedule_created: false (executor는 callback cron 직접 등록 안 함 — OS-level pickup runner가 owner-proof 후 결정론 closeout 소유, task-2730 OS-LEVEL PICKUP CLOSEOUT CONTRACT).
- relay_hints: 없음 (4필드 전부 false → deterministic green closeout).
- report_path: memory/reports/task-2779_b.md (allowed_resources의 task-2779b-r1.md와 동일 내용 사본 제공).

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회