---
task_id: task-2517
type: plan
scope: task
created: 2026-05-09
updated: 2026-05-09
status: completed
---

# 계획서: task-2517 — canonical_workspace_resolver

**task**: task-2517 (P0 — runtime determinism 핵심)
**목표**: 6 hook(scope-guard / finish-task / guard / smoke / qc / merge_execution)이 동일한 deterministic CanonicalWorkspace 인스턴스를 공유하도록 단일 entrypoint resolver 모듈 신규 작성. task-2516+1 4 ambiguity 구조적 제거.
**승인**: 회장 2026-05-09 "현재 전체 시스템의 highest-priority runtime hardening task"
**근거**: memory/tasks/task-2517.md, memory/feedback/feedback_critical_escalation_only_260508.md

---

## 목표

1. `utils/canonical_workspace_resolver.py` 신규 (CanonicalWorkspace dataclass + resolver + 5 assert/evaluate 함수)
2. `tests/regression/test_canonical_workspace_resolver_2517.py` 신규 (14 tests PASS)
3. task-2516+1 §4 ambiguity (wrong cwd / stale main / dirty workspace false detection / finish-task context mismatch) 회귀 fixture로 직접 해소
4. CLI entrypoint (`--task-id`, `--json`, `--assert-cwd`, `--assert-fresh`, `--scope`, `--no-fetch`)
5. Goal assertions PASS:
   - `python3 utils/canonical_workspace_resolver.py --task-id task-2517 --json`
   - `pytest tests/regression/test_canonical_workspace_resolver_2517.py -q` → 14/14 PASS

## 범위

### 포함
- 신규 파일 2건만 (expected_files 정확 매칭)
- CanonicalWorkspace dataclass(frozen=True)
- 7 함수: resolve_canonical_workspace / assert_cwd_matches_workspace / assert_main_fresh / evaluate_scope_dirty / assert_finish_task_context / 6 hook 통합 인터페이스 / CLI main
- 14 회귀 테스트 (정상 4 + 4 ambiguity 4 + edge 3 + 6 hook 3)

### 제외 (다음 페이즈 이후)
- 6 hook 실제 wiring → task-2518/2519 별도
- 5 모듈 본체 수정 (READ ONLY)
- automation_contracts.py 변경 (READ ONLY)
- dispatch.py 변경
- policy md 보강
- replacement_pr_runner.py 수정 (task-2516+1 영역)

## 위임 계획

- **Phase 1** (설계): **오딘** — Codex 사전 검증 + 3 Step Why
- **Phase 2** (구현): **토르(백엔드)** — utils/canonical_workspace_resolver.py 작성
- **Phase 3** (테스트): **헤임달(테스터)** — 14 회귀 테스트 작성, pytest 14/14 PASS
- **Phase 4** (검증): **오딘 + 마아트** — Gemini PR 리뷰 + G3 독립 검증

## 검증 기준

- 빌드: `python3 -c "from utils.canonical_workspace_resolver import CanonicalWorkspace, resolve_canonical_workspace; print('import ok')"` → "import ok"
- 회귀: `pytest tests/regression/test_canonical_workspace_resolver_2517.py -q` → 14/14 PASS
- CLI: `python3 utils/canonical_workspace_resolver.py --task-id task-2517 --json` → CanonicalWorkspace JSON
- forbidden path 0 (expected_files 정확히 2 파일)
- Codex 사전 검증 PASS