# task-2729+20 — FILE_TOUCH_RATIO_CHECK_CODE_ROOT_RECOGNITION (QC/evidence-root hardening, production activation 아님)

## 레벨
Lv.3 (QC verifier evidence-root hardening. production activation 아님)

## 발번 주석
task-2729+19 dogfood 에서 file_touch_ratio_check = SKIP(canonical task-2716 diff 기준 ratio 0.00 false-negative) 관측 → 구조적 root 인식 fix. 회장 2026-06-08 dispatch 승인 + expected_files (a) 10-카피 일괄 승인.

## ★ FRESH BASE
1. worktree 는 **origin/main `571a4ce3`(또는 이후 최신 main)** 분기. canonical(task-2716 계열) 분기 금지.
2. `git worktree add -b task/task-2729+20-<bot> <path> origin/main`. commit 전 `merge-base --is-ancestor 571a4ce3 HEAD == YES` + task-2716 divergence 0 검증, 실패 시 HOLD.
3. diff `origin/main..HEAD` = expected_files 만. 오염 diff → HOLD.

## 근본 원인 (audit 확정 — 단일 소스)
1. `qc_verify.py:563` 이 `file_touch_ratio_check.verify(task_id)` 를 **workspace_root 미전달**로 호출 → param 기본값 `/home/jay/workspace`(canonical).
2. `verify(task_id, workspace_root='/home/jay/workspace')` 가 `PROJECT_PATH`/`WORKTREE_PATH`/`QC_EVIDENCE_ROOT` env **미인식**. report_path + `git -C <root> diff HEAD~5` 둘 다 canonical.
3. finish-task.sh(#190 L644)가 env 전파해도 canonical(task-2716 무관커밋) diff → ratio 0.00 → SKIP.
4. 대조: `git_evidence.verify`(#190)는 `_resolve_project_dir_with_source`(L119)로 env 인식 — **file_touch_ratio_check 만 격차**.
5. 카피: shared 1 + per-team 9 = **10 파일 전부 sha 동일(cf8f2cf3f91d, drift 0)**.

## 목표 (회장 verbatim)
1. file_touch_ratio_check 가 **selected CODE_ROOT 인식**.
2. `PROJECT_PATH` / `WORKTREE_PATH` / `QC_EVIDENCE_ROOT`(또는 동등 env) 인식하되 **유효한 git dir 일 때만 사용**.
3. ★ **report read root 와 diff/evidence root 가 섞이지 않도록** 주의.
4. **report 는 canonical `memory/reports` 에서 읽을 수 있고, diff 는 selected CODE_ROOT 에서 계산**될 수 있어야 함.
5. canonical task-2716 diff 로 인한 **ratio 0.00 / SKIP false-negative 제거**.
6. 기존 canonical-path task **backward compatibility 유지**.
7. worktree 기준 changed files ↔ report changed files 일치 시 **ratio PASS**.
8. env 없거나 invalid git dir 이면 **기존 canonical fallback 또는 fail-safe 동작 명확히**.
9. raw key 0 / ACTIVE=false / systemd enable 0 / activation_epoch absent / real spawn 0 유지.

## 설계 (Locus B — verifier 내부 env 인식, git_evidence 선례 미러링)
- `verify` 진입 시 **diff/evidence root** 해석: `PROJECT_PATH` → `WORKTREE_PATH` → `QC_EVIDENCE_ROOT` env 순, 값 존재 + 유효 git dir 이면 사용. 아니면 `workspace_root` param/기본값 fallback.
- **report_path** 는 **canonical(workspace_root) 우선 read 가능** + selected root 에도 있으면 인식(섞임 방지: report read root 와 diff root 분리 변수로 관리).
- `git -C <diff_root> diff` 는 **selected CODE_ROOT** 기준.
- 명시적 workspace_root override 시 그 값 우선(하위호환). git_evidence `_resolve_project_dir_with_source` 패턴 미러링.
- **10 카피 동일 수정**(shared + 9 per-team), parity(동일 sha) 유지.

## expected_files (회장 승인 — (a) 10-카피, 총 12 내외)
1. `teams/shared/verifiers/file_touch_ratio_check.py`
2~10. `teams/{dev1..dev8,design}/qc/verifiers/file_touch_ratio_check.py` (9개)
11. `tests/regression/test_file_touch_ratio_root_recognition_2729p20.py`
12. `memory/reports/task-2729+20.md`
- (선택) `memory/plans/p0b-pickup/file_touch_ratio_check_code_root_recognition_*_260608.md` (design/result)
- ★ 이 범위 초과 또는 디듀프 리팩터 필요 시 즉시 **HOLD_FOR_CHAIR**.

## 필수 regression (회장 verbatim 11, isolated temp)
1. canonical root 기본 동작 backward-compat PASS. 2. PROJECT_PATH valid git worktree → diff/evidence root 사용. 3. WORKTREE_PATH valid → diff/evidence root. 4. QC_EVIDENCE_ROOT valid → diff/evidence root. 5. env root invalid → fail-safe 또는 canonical fallback 명확 동작. 6. report canonical + diff worktree 조합 PASS. 7. worktree changed 4/4 매칭 시 ratio 1.00 PASS. 8. canonical task-2716 dirty/diff 가 selected CODE_ROOT clean finalize 를 false-block 안 함. 9. per-team 9카피 ↔ shared 1카피 동일 로직 확인. 10. raw key 0. 11. ACTIVE=false / systemd enable 0 / activation_epoch absent / real spawn 0.

## 금지 (회장 verbatim 12)
1. production ACTIVE 전환  2. systemctl enable  3. ACTIVE=true 선언  4. activation_epoch 생성  5. real ANU spawn  6. callback prereg Phase B 착수  7. **git_evidence.py 수정**  8. **dispatch.py 수정**  9. canonical reset/clean/stash -u/checkout -f  10. task-2716 branch 수정  11. live memory artifacts 이동·삭제  12. **디듀프 리팩터 착수**.
- 모든 검증 isolated temp. canonical 무손상.

## 완료 판정
- 회귀 11 PASS + report-root/code-root 분리 명확 + false-negative 제거 + backward-compat + 10카피 parity + raw key 0 + ACTIVE=false → **`PR_READY_CANDIDATE_FILE_TOUCH_RATIO_ROOT_RECOGNITION_ACTIVE_FALSE`**(로컬 verify, PR 미생성).
- expected_files 초과 / report-root·code-root 분리 불가 / git_evidence·dispatch·callback prereg 수정 필요 / production activation·real spawn 필요 / 디듀프 필요 / task-2716 수정 → **`HOLD_FOR_CHAIR`**.
- ★ PR 생성·merge·activation = 별도 회장 승인 전까지 0.

## 완료 후 callback
- 봇 완료 시 ANU(c119085addb0f8b7)로 normal callback cron 발사(envelope only, UTF-8 ≤3900 bytes, collector=ANU): task_id/result_path/report_path/terminal_state/sha256/one-line summary. raw key literal 출력 0(.env.keys COKACDIR_KEY_ANU sealed).

## doctrine
직접 코딩 금지(ANU)/봇 위임 / fresh origin/main 571a4ce3 / git_evidence env-인식 선례 미러링 / report-root와 diff-root 분리 / backward-compat 필수(env 미설정 시 기존 동작) / FAIL 오발 방지 / 10-카피 parity / git_evidence·dispatch·callback prereg 무수정 / 디듀프 금지 / activation 0 / raw key 0 / same-PR push 금지.
```yaml
callback_envelope_byte_limit: 3900
callback_collector_role: ANU
callback_owner_key_source: ".env.keys COKACDIR_KEY_ANU (sealed, literal 출력 0)"
```