---
task_id: task-2449
type: context
scope: task
created: 2026-05-05
updated: 2026-05-05
status: implemented
---

# 맥락 노트: task-2449 — taskctl MVP

**task**: task-2449

---

## 결정 근거

### 결정 1: 신규 진입점 `taskctl`을 단일 라우팅 허브로

- **이유**: task-2434/2440/2445의 ruleset은 GitHub 서버측 강제이지만, 로컬 push / 봇 직접 머지 / cancelled task push 차단은 코드 미존재였다. 회장이 "문서 → 코드 enforcement 전환"을 선언함.
- **대안과 기각**: ① 기존 `auto_merge.py`에 가드만 추가 (기각: gh pr merge 호출 분산 — anu_confirm_bot도 직접 호출). ② pre-push hook만 강화 (기각: 봇 코드 경로는 hook 우회). ③ 별도 진입점 + 모든 머지 경로 라우팅 (채택).

### 결정 2: state 파일 checksum

- **이유**: 외부 도구가 .json을 직접 편집해 상태를 임의로 HUMAN_APPROVED로 만들지 못하게 차단해야 한다. spec 명시: "외부에서 .json 직접 편집 시도 → checksum mismatch → 다음 명령에서 reject".
- **구현**: SHA256(canonical_json(state - _checksum)). 저장 시 계산, 로드 시 검증.
- **한계**: checksum 자체도 갱신해 위조하면 무력화됨 (signed-commits 수준은 아님). MVP 단계 신뢰 모델.

### 결정 3: BYPASS 동작 — 상태 전이도 force

- **이유**: 회장 override는 1~5단계 가드뿐 아니라 정규 상태 전이 규칙도 우회해야 한다 (예: PR_OPEN 상태에서도 강제 머지 가능). 단, evidence에는 정확히 기록.
- **구현**: `_transition()`에 `force=bool` 인자 추가. bypass 시 `force=True`로 호출하여 검증 skip. transitions 항목에는 `forced: true` 표시.

### 결정 4: anu_confirm_bot의 `gh pr merge` 직접 호출 → taskctl 라우팅

- **이유**: 코드베이스에서 `gh pr merge`를 호출하는 유일한 위치였음. 본 task의 핵심 합격 기준 ("taskctl을 거치지 않고는 main을 절대 변경할 수 없다") 위반.
- **변경**: `_execute_approve()` 내부의 `gh pr merge` subprocess 호출을 `python3 scripts/taskctl.py merge` 호출로 치환. 기존 cancelled/guard.sh 검사는 보존.

### 결정 5: `auto_merge.py`에 TASKCTL_INVOKED 가드

- **이유**: `auto_merge.py`는 `--dry-run` / `--graduated` 모드도 있고 실제로 머지 수행 가능. 직접 호출 차단을 위해 환경변수 가드 적용.
- **구현**: `--dry-run`과 `--graduated` 모드는 가드 면제 (분석/리포팅 용도). 실제 머지 경로만 `TASKCTL_INVOKED=1` 강제.

### 결정 6: 별도 CI workflow `.github/workflows/guard.yml`

- **이유**: spec 명시 — "ci.yml 수정 금지 (task-2440/2445 ruleset 보호)". 기존 8 required checks를 건드리지 않고 추가 가드만.
- **한계**: ruleset 등록은 회장이 직접 처리. 본 task는 workflow 파일만 작성.

## 참조 자료

- task spec: `memory/tasks/task-2449.md` (단일 payload — 수정 금지)
- 보호 대상: `.github/workflows/ci.yml`, `scripts/qc_report_guard.py`, `scripts/guard.sh`, `scripts/task_scope.py`, `scripts/pre_push_guard.py`
- 회장 거버넌스: `memory/system_governance_4layer.md` (참조)
- 시퀀싱: 본 task → task-2448 (Lite Evaluator 시스템 통합)

## 주의사항

- ★ task.md 수정 절대 금지 (회장 직접 명시 2026-05-05)
- ★ 기존 8 required CI checks (cancel-kill-switch / qc-check / hidden-path-audit / lock-in-check / merge-safety-check / gemini-review-gate / ci/guard / guard) 절대 수정 금지
- ★ scripts/quality_evaluator.py / task_scope.py / pre_push_guard.py / qc_report_guard.py / guard.sh / scripts/ids/** 절대 수정 금지
- ★ dispatch.py / dashboard/** / teams/shared/** / CLAUDE.md 절대 수정 금지
- 봇 자체 머지 절대 금지 (manual_after_full_enforcement 정책)
- finish-task.sh / auto_merge_controller.py 라우팅은 N/A — 현 코드베이스에 해당 머지 경로 부재 (보고서에 기록)