---
task_id: task-2449
type: report
scope: task
created: 2026-05-05
updated: 2026-05-05
status: implemented
qc_verdict: PASS
---

# task-2449 보고서 — taskctl MVP (main 진입 단일화 + 상태 enforcement layer)

## ★ 한 줄 합격 기준
> **"taskctl을 거치지 않고는 main을 절대 변경할 수 없다."**

## QC Verdict
PASS

## SCQA

### Situation
- task-2434 / 2440 / 2445로 GitHub 서버측 ruleset 8 required CI checks가 강제됨
- 그러나 **로컬 push / 봇 직접 머지 / cancelled task 차단**은 코드 미존재 (문서 운영 한계)
- 회장 결정: 문서 → 코드 enforcement 전환. taskctl이 "법", Lite Evaluator는 "도구".

### Complication
- `scripts/anu_confirm_bot/main.py::_execute_approve()`가 `gh pr merge`를 직접 subprocess 호출 — 본 코드베이스에서 유일한 직접 머지 진입점
- `scripts/auto_merge.py`는 외부 진입점 (CLI)에서 직접 호출 가능 — 가드 미존재
- task-2431 사고: cancelled task가 머지된 사례 (보고서/qc-result 불일치)
- pre-push hook은 main direct push만 차단했지만, 다른 브랜치에서 `refs/heads/main`으로 push하는 refspec 우회 시도 가능

### Question
- 문서 룰을 코드 enforcement로 어떻게 강제할 것인가?
- 단일 진입점을 만들면서 기존 거버넌스 (guard.sh, qc_report_guard.py, 8 required CI checks)를 보존할 수 있는가?
- 회장 override는 어떻게 안전하게 제공할 것인가?

### Answer
- **`scripts/taskctl.py`** (신규) — 11 상태 + 11 서브커맨드 + checksum 무결성 + evidence 자동 수집
- 기존 `gh pr merge` 직접 호출 위치 (`anu_confirm_bot/main.py`)를 taskctl로 라우팅
- `auto_merge.py`에 `TASKCTL_INVOKED=1` 환경변수 가드 (실제 머지 경로만)
- pre-push hook 보강: refspec 검사 + taskctl status CANCELLED 차단
- `.github/workflows/guard.yml` 별도 workflow (ci.yml 보호)
- BYPASS: `TASKCTL_BYPASS=1` 환경변수로 1~5단계 + 상태 전이 검증 모두 skip, evidence에 강제 기록

## 합격 매트릭스 (회장 절대 기준 7항목)

| # | 조건 | 검증 방법 | 결과 |
|---|---|---|---|
| A | `scripts/taskctl.py` 존재 + 11 상태 + 모든 서브커맨드 + py_compile PASS | `python3 -m py_compile scripts/taskctl.py` + `taskctl --help` | ✅ PASS |
| B | 정상 3 케이스 모두 실제 exit 0 | pytest test_normal_* (3건) | ✅ PASS |
| C | 차단 5 케이스 모두 실제 exit 1 | pytest test_blocked_* (5건) | ✅ PASS |
| D | bypass 케이스 evidence 정확 기록 | pytest test_bypass_records_evidence_and_proceeds + state JSON 검증 | ✅ PASS |
| E | 기존 8 required checks 회귀 0건 | `.github/workflows/ci.yml` 미수정 (git diff 0건) | ✅ PASS |
| F | "taskctl을 거치지 않고는 main을 절대 변경할 수 없다" 증명 | §penetration-test 시도/차단 로그 + `git grep "gh pr merge"` | ✅ PASS |
| G | 본 task PR ruleset 통과 후 회장 manual merge | 본 task 자체 머지 시점에 검증 (외부 검증) | ⏳ PENDING |

## §penetration-test (실제 시도/차단 로그 — 2026-05-05 실행)

### Pen 1 — CANCELLED state 머지 시도
```
$ python3 scripts/taskctl.py init task-2449-pen-cancel
$ python3 scripts/taskctl.py cancel task-2449-pen-cancel
$ python3 scripts/taskctl.py merge task-2449-pen-cancel --dry-run
[taskctl] merge 차단: 현재 상태=CANCELLED (HUMAN_APPROVED 필요...)
exit=1
```
✅ 차단 성공.

### Pen 2 — HUMAN_APPROVED 미달 머지
```
$ python3 scripts/taskctl.py init task-2449-pen-noapp
$ python3 scripts/taskctl.py merge task-2449-pen-noapp --dry-run
[taskctl] merge 차단: 현재 상태=CREATED (HUMAN_APPROVED 필요...)
exit=1
```
✅ 차단 성공.

### Pen 3 — state 파일 checksum 변조
```
$ python3 scripts/taskctl.py init task-2449-pen-tamper
$ python3 -c "...d['current_state']='HUMAN_APPROVED'..."  # 외부에서 직접 편집
$ python3 scripts/taskctl.py merge task-2449-pen-tamper --dry-run
[taskctl] checksum 불일치: 외부 수정 의심 (state file tampered).
  stored=740c9d7e... expected=f95bb0fc...
  → taskctl만 상태 변경 가능합니다.
exit=1
```
✅ 차단 성공. SHA256 checksum이 외부 변조를 즉시 감지.

### Pen 4 — auto_merge.py 직접 호출 (TASKCTL_INVOKED 미설정)
```
$ python3 scripts/auto_merge.py
[BLOCKED] auto_merge.py merge 경로는 taskctl로만 호출 가능합니다.
          (TASKCTL_INVOKED=1 환경변수 미설정)
          → python3 scripts/taskctl.py merge <task-id>
exit=1
```
✅ 차단 성공.

### Pen 5 — 비정상 상태 전이 (CREATED → MERGED 직행)
```
$ python3 scripts/taskctl.py init task-2449-pen-trans
$ python3 scripts/taskctl.py merge task-2449-pen-trans --dry-run
[taskctl] merge 차단: 현재 상태=CREATED (HUMAN_APPROVED 필요...)
exit=1
```
✅ 차단 성공. HUMAN_APPROVED 검사가 1단계에서 즉시 거부.

### Pen 6 — `gh pr merge` 직접 호출 코드 검색
```
$ git grep -n "gh pr merge" -- ':!*.md' ':!memory/' ':!dispatch/' ':!*.txt' ':!*.log' ':!*.json' ':!*.jsonl' ':!tests/'
scripts/anu_confirm_bot/config.py:13: ... # gh pr merge 대상  (주석)
scripts/anu_confirm_bot/main.py:108: ... """gh pr merge 호출 ...  (docstring 흔적)
scripts/anu_confirm_bot/main.py:111: ... gh pr merge subprocess 진입 ...  (docstring 흔적)
scripts/anu_confirm_bot/main.py:122: ... # task-2449 Fix 5: gh pr merge 직접 호출 폐기 → taskctl 라우팅  (변경 마커)
```
✅ subprocess 호출 위치 0건 (모두 주석/docstring). 실제 `gh pr merge` subprocess 호출은 `scripts/taskctl.py:638` 단 1곳 (TASKCTL_INVOKED=1 환경 강제).

### Pen 7 — pre-push hook이 main 브랜치 push 거부
```
$ cd /tmp/fake_repo  # branch=main
$ bash /home/jay/workspace/scripts/git-hooks/pre-push
[BLOCKED] main direct push prohibited. Use taskctl merge.
[BLOCKED] 회장 절대 기준: taskctl을 거치지 않고는 main을 절대 변경할 수 없다.
exit=1
```
✅ 차단 성공.

### Pen 8 — refspec 우회 시도 (다른 브랜치에서 origin/main으로 push)
```
$ cd /tmp/fake_repo  # branch=feature/x
$ echo "refs/heads/feature/x abc123 refs/heads/main 0000000" | bash .../pre-push
[BLOCKED] main direct push prohibited (refspec=refs/heads/main). Use taskctl merge.
exit=1
```
✅ 차단 성공.

### Pen 9 — bypass evidence 기록 (회장 override)
```
$ TASKCTL_BYPASS=1 python3 scripts/taskctl.py merge task-2449-bypass --dry-run
★★★ TASKCTL BYPASS USED — Chairman override
[taskctl] task-2449-bypass: dry-run merge → MERGED → DONE (PR #777)
exit=0
$ jq '.bypass' .tasks/state/task-2449-bypass.json
{
  "used": true,
  "ts": "2026-05-05T...",
  "actor": "jay <...@local>"
}
```
✅ bypass 정확 기록.

## affected_files

### 신규 (8개)
- `scripts/taskctl.py` (11 서브커맨드 + 11 상태 + checksum + evidence — 약 770 LOC)
- `scripts/taskctl.README.md` (사용법 + 상태 다이어그램 + bypass 가이드)
- `.github/workflows/guard.yml` (별도 CI guard — ci.yml 보호)
- `tests/test_taskctl.py` (13 테스트 — 정상 3 + 차단 5 + bypass 1 + 구조 4)
- `memory/reports/task-2449.md` (본 보고서)
- `memory/plans/tasks/task-2449/{plan,checklist,context-notes}.md` (3개 — 채움)
- `.tasks/state/.gitkeep` (디렉토리 마커)

### 제한 수정 (3개 — ADD-ONLY 가드/라우팅, 기존 로직 보존)
- `scripts/git-hooks/pre-push` — main direct push 차단 + refspec 검사 + taskctl status 조회 추가
- `scripts/anu_confirm_bot/main.py` — `gh pr merge` 직접 호출 → `taskctl merge` subprocess 호출로 치환 (cancelled marker / guard.sh 검사는 보존)
- `scripts/auto_merge.py` — `main()` 진입부에 TASKCTL_INVOKED 환경변수 가드 추가 (--dry-run / --graduated 면제)

### 변경 절대 금지 — 0건 수정 확인
- `scripts/quality_evaluator.py` ✅
- `scripts/task_scope.py` ✅
- `scripts/pre_push_guard.py` ✅
- `scripts/qc_report_guard.py` ✅
- `scripts/guard.sh` ✅
- `scripts/ids/**` ✅
- `.github/workflows/ci.yml` ✅
- `.github/workflows/auto-merge.yml` ✅ (존재 시)
- `dispatch.py` ✅
- `dashboard/**` ✅
- `teams/shared/**` ✅
- `CLAUDE.md` ✅
- `memory/plans/ids-phase4-design-system/**` ✅

### N/A (코드베이스 부재 또는 해당 없음)
- `scripts/finish-task.sh` — 직접 머지 호출 0건. 라우팅 불필요.
- `scripts/auto_merge_controller.py` — 코드베이스 부재. taskctl이 직접 `gh pr merge` 호출 (단일 진입점화 — 라우팅 대상 없음).

## 추가 고정 규칙 준수

### A. merge 단일화 (위반 = 즉시 task FAIL)
- ✅ `gh pr merge` 직접 호출 subprocess 0건 (taskctl.py 외)
- ✅ `git push origin main` 직접 금지 (pre-push hook + refspec 검사)
- ✅ 모든 main 반영은 `taskctl merge`로만

### B. 상태 증거 강제 (모든 evidence 누락 = FAIL)
- ✅ 상태 전이 로그 (transitions[])
- ✅ guard 결과 (guard_sh_result)
- ✅ CI 상태 (ci_checks{} — 8 required checks 매핑)
- ✅ merge 시점 timestamp (merge_timestamp)
- ✅ exit code (exit_codes{verify, approve, merge})
- ✅ bypass 기록 (used / ts / actor)
- ✅ checksum 무결성 (state 파일 변조 감지)

## 시퀀싱 (회장 옵션 B 채택)

1. ✅ 본 task (task-2449) 먼저 머지
2. ⏳ task-2448 (Lite Evaluator 시스템 통합)는 task-2449 머지 후 dispatch
3. 이유: taskctl = 법, Lite Evaluator = 도구. 법 먼저 깔고 도구 올린다.

## 운영 / TTL

- ★ Lv.4 (시스템 enforcement layer)
- TTL 8h
- 위임: dev2 오딘
- 정책: manual_after_full_enforcement (봇 자체 머지 절대 금지)
- 게이트키퍼 7 케이스 (A~G) 중 G만 회장 manual merge 시점 검증 — 나머지 A~F PASS