# 아누 시스템 구조 설명서 (외부 조언자용)

> **목적**: 외부 조언자가 "이 시스템에서 자동화 제어 메커니즘을 어디에, 어떤 방식으로 넣어야 하는지"를 판단할 수 있게 하는 실제 구조 설명서.
> **원칙**: 환각 금지. 실제 파일/코드/디렉터리에서 확인한 사실만 기재. 모르는 항목은 "**확인 불가**"로 명시.
> **작성**: 2026-05-05 V1 / 아누 (Claude Opus 4.7) + Explore 서브에이전트 4명 병렬 조사 기반.
> **갱신**: 2026-05-05 V2 — task-2440/2449/2451(완전자동 머지 시스템 enforcement) 누락분 반영 + 회장 직접 처리(org 전환·Rulesets 등록) 사실 추가. 변경 부위에 **[V2 정정]** 마커.
> **갱신**: 2026-05-05 V3 — task-2452 (회장 직접 진단). `auto_merge.py` 공식 폐기 + 신호등 sync 정정. 변경 부위에 **[V3 정정]** 마커.
> **루트 경로**: `/home/jay/workspace/`

---

## 0. V3 정정 요약 (외부 조언자가 먼저 읽을 것 — 2026-05-05 task-2452)

V2 본문에서 `auto_merge.py classify_tier()`가 "Tier 1 자동 머지"를 수행하는 것으로 표현했으나, **회장 직접 진단 + 아누 raw 검증 결과 사실상 폐기 상태**였음. 본 V3에서 다음 4가지 정정:

1. **`auto_merge.py`는 사실상 폐기 — 머지 0건**:
   - `logs/auto_merge.log` (24MB, 2026-05-05 14:05) 최근 1000줄 = **227건 모두 `[BLOCKED] auto_merge.py merge 경로는 taskctl로만 호출 가능합니다.`**
   - cron이 매분 돌리지만 머지 성공 흔적 0건. TASKCTL_INVOKED 가드(L2325-2332)로 자기 자신을 차단.
   - **task-2452 Phase 1**: cron 라인 제거 + 헤더 DEPRECATED 마커 + 30일 유예(2026-06-04 삭제 예정).

2. **머지의 진짜 경로는 3개 (auto_merge 거치지 않음)**:
   - **A) `finish-task.sh` Step 2** → `worktree_manager.py finish --action auto` → 자체 머지 (현재 모든 정상 머지의 hot path).
   - **B) `taskctl.py merge`** → `gh pr merge` 직접 호출 (taskctl.py L614-641; `env={"TASKCTL_INVOKED":"1"}` 설정은 자기 자신 마커일 뿐 auto_merge.py 호출 X).
   - **C) GitHub `merge_group` + Ruleset(active, id=15896715)** → 7개 required checks + server-side 직렬 머지 (V2 §0 §6.10 참조).

3. **신호등 끄는 단일 책임 = `finish-task.sh` 끝부분 (Step 2.99)**:
   - 회장 원칙: "오토 머지까지 다 되어야 작업이 정말 완성된 거고, 그 이후 finish-task.sh가 진행되니, 마지막에 신호등이 꺼지는 로직이어야 정상."
   - **task-2452 Phase 2**: `member-status.json` (팀원) + `bot-activity.json` (팀 봇) 두 source를 `.done` 생성 직전 마지막 Step에서 동시 idle 전환.
   - composite 작업 `team_id=""` 케이스: `task-timers.json[task_id].affected_teams` / `composite_teams` fallback.
   - **task-2452 Phase 3**: `done-watcher.py`의 자동 idle은 fallback-only로 강등 (30분 grace + `.merge-done` 부재 조건).

4. **`.done.escalated` 마커 생성자 미상**:
   - V2 §10/부록에서 "auto_merge가 .done.escalated/.done.merging/.done.clear 마커를 만든다"고 표현했으나, **`auto_merge.py` 코드 grep 결과 마커 생성 코드 없음**.
     - `escalate()`: cokacdir 메시지만 발송.
     - `_finalize_done_file()`: `log_result()` 호출만.
   - task-2451의 0byte `.done.escalated` (2026-05-05 13:56 생성) 출처 불명 — 본 task에서는 부록 B에 추적 권고 항목으로만 기록.

V3 정정 부위는 본문 섹션별 **[V3 정정]** 마커로 표시함.

---

## 0. V2 정정 요약 (외부 조언자가 먼저 읽을 것)

V1 작성 시 **task-2440/2449/2451 enforcement 시스템 정보가 누락**되어 외부 조언자가 "이 시스템은 server-side enforcement 없음"이라고 잘못 판단할 수 있었음. 직접 GitHub API 호출로 확인한 V2 사실:

1. **저장소 소유권 전환 완료** (raw API): `JonghyukJeon` (개인, free) → **`Jeon-Jonghyuk` Organization** (team plan, private_repos 999,999, seats 1).
2. **Ruleset 등록 완료** (raw API):
   ```
   gh api repos/Jeon-Jonghyuk/dev_workspace/rulesets
   → [{"id":15896715, "name":"main-protection",
       "target":"branch", "enforcement":"active",
       "created_at":"2026-05-04T09:18:09+09:00"}]
   ```
   → **server-side enforcement = ACTIVE** (2026-05-04 회장 직접 처리).
   주의: legacy `branches/main/protection` API는 404가 나오지만, 이는 GitHub 신규 시스템(Rulesets)으로 대체된 결과이지 게이트가 없는 게 아님.
3. **task-2440 (PR #14, 머지 완료)에서 구현된 enforcement 자산**:
   - 7개 CI required checks: `cancel-kill-switch`, `qc-check`, `hidden-path-audit`, `lock-in-check`, `merge-safety-check`, `gemini-review-gate`, `ci/guard`
   - `merge_group` 트리거 (GitHub Merge Queue가 직렬 처리)
   - `scripts/lock_in_verify.py` (AST 기반)
   - `scripts/gemini_review_gate.py`, `scripts/gemini_feedback_loop.py` (3회 초과 시 `human_review_required` 라벨)
4. **task-2449 침투 테스트 9건 PASS**: cancelled state 머지 시도, HUMAN_APPROVED 미달, state checksum 변조, auto_merge 직접 호출(TASKCTL_INVOKED 미설정), 비정상 상태 전이, `gh pr merge` 직접 호출 검색, pre-push hook의 main 거부, refspec 우회, bypass evidence 기록 — 모두 차단/검증.
5. **V1의 "merge_policy=manual 기본" 표현은 부정확**: dispatch.py가 task 메타에 적는 **기본값 라벨**일 뿐, 실제 머지 게이트가 아님. **[V3 정정] 실제 게이트는 Ruleset(server-side) + CI 7-step + taskctl 상태 모델 + finish-task.sh의 worktree_manager finish — `auto_merge.py` Tier 분류는 폐기 (사실상 머지 0건)**.

V2 정정 부위는 본문 섹션별 **[V2 정정]** 마커로 표시함.

---

## 1. 시스템 개요

### 1.1 시스템이 해결하려는 문제

- **개인 1인이 다수의 LLM 봇(개발팀+조연팀)을 운영**하여 InsuWiki, InsuRo, MediScan, ThreadAuto, MktingAuto 등 5개 프로젝트를 동시 진행하는 **1인 멀티봇 SaaS 운영 환경**.
- **목표**: 회장(사람) 1명이 8개 개발팀 + 마케팅/디자인/컨설팅 등 논리팀을 지휘하여 코드/콘텐츠/디자인을 동시에 산출.
- **핵심 통제 변수**: 충돌 방지(병렬 작업), 환각/거짓보고 방지, 회장 의사결정 병목 최소화.

### 1.2 아누의 정체

- 아누는 **단순 봇이 아닌 "개발실장(상위 오케스트레이터)"** 역할.
- 위치: 사용자(회장)와 8개 팀장 봇 사이의 "지휘 레이어".
- **핵심 제약**: 아누는 **직접 코딩하지 않는다**. 설계/판단/위임/검증/보고만 수행.
- 모델: claude-opus-4-7 (이 챗 세션이 아누 본체).

### 1.3 다른 봇과의 관계

봇은 **신화 이름**으로 명명되며, **모두 LLM agent**(OS 프로세스/데몬 아님). 각각 **별도 Telegram 챗방** + **cokacdir 세션**으로 동작.

| 신화 | 역할 | 모델 | 비고 |
|------|------|------|------|
| **아누 (Anu)** | 개발실장 (이 세션) | claude-opus-4-7 | 메소포타미아 최고신 |
| **헤르메스 (dev1팀장)** | 개발1팀 오케스트레이션 | claude-sonnet-4-6 | 그리스 |
| **오딘 (dev2팀장)** | 시스템 아키텍처 | claude-sonnet-4-6 | 북유럽 |
| **다그다 (dev3팀장)** | 시스템 설계/태스크 분배 | claude-sonnet-4-6 | 켈트 |
| **비슈누 (dev4팀장)** | 시스템 설계 | claude-sonnet-4-6 | 힌두 |
| **마르둑 (dev5팀장)** | 시스템 설계 | claude-sonnet-4-6 | 메소포타미아 |
| **페룬 (dev6팀장)** | 시스템 설계 | claude-sonnet-4-6 | 슬라브 |
| **이참나 (dev7팀장)** | 시스템 설계 | claude-sonnet-4-6 | 마야 |
| **라 (dev8팀장)** | 콘텐츠 플랫폼 | claude-sonnet-4-6 (팀장), **glm-5** (팀원 4명) | **유일한 비-Anthropic 팀** |
| **로키 (Loki)** | 보안총괄 (CR) | claude-opus-4-6 | 횡단 조직, 모든 미팅 필수 참석 |
| **마아트 (Ma'at)** | QC 센터 (CR) | claude-sonnet-4-6 | 독립 품질 검증 |
| **야누스 (Janus)** | DevOps (CR) | claude-sonnet-4-6 | 인프라 |
| **비너스 (Venus)** | Gemini 센터 (CR) | gemini | 세컨드오피니언 + 디자인 |
| **아틀라스 (Atlas)** | Codex 센터 (CR) | gpt | GPT 세컨드오피니언 |
| **헤임달 (dev2팀 테스터)** | 테스트 | claude-sonnet-4-6 | dev2팀 멤버 (팀장 아님) |

전체 봇/팀 정의: `/home/jay/workspace/memory/organization-structure.json` (56KB, 1485줄, 마지막 갱신 2026-03-15).

### 1.4 사람 개입 vs 자동 진행 [V2 정정]

| 영역 | 결정자 |
|------|--------|
| 신규 dispatch 위임 결정 | 회장 (아누는 제안만, 독단 위임 금지) |
| Phase 간 전환 | 회장 |
| **merge 최종 (Tier 1 자동 / Tier 2 1-tap / Tier 3 manual)** | **혼합** — Tier 분류 + Ruleset enforcement(active) |
| critical/security 승인 | 회장 |
| 에스컬레이션 처리 | 회장 + 아누 분석 |
| `.done` 감지 | **자동** (cron 매분 `auto_merge.py`) |
| QC 검증 (mode: fail gate) | **자동** (코드 차단) |
| **CI 7-step + Gemini Gate** | **자동** (server-side, GitHub Actions + Ruleset enforcement=active) |
| **direct push to main** | **자동 차단** (client pre-push hook + Ruleset) |
| `.done` → `.done.clear` 전이 | **자동** + 아누 명령 (혼합) |
| 봇 내부 코드 작성 | 봇 자율 (팀장이 팀원 지시) |

→ **자동화 수준 재평가 (V2)**: V1에서 "30~40%"라 적은 건 enforcement 시스템(task-2440/2449/2451)을 빼고 본 수치. **server-side Ruleset + CI 7-step까지 포함하면 약 60~70% (Tier 1 자동 + 차단 게이트 자동)**. Tier 2/3, Phase 전환, 신규 dispatch는 여전히 사람 결정.

---

## 2. 현재 end-to-end 작업 흐름

### 2.1 표준 흐름

```text
[회장 요청 수신]
    ↓
[아누: 작업 레벨 판정 (Lv.0~4)]
    ↓
  Lv.0 → 픽셀(haiku) 직할 처리 / 위임 안 함
  Lv.1+ → 위임 절차
    ↓
[3문서 작성 (Lv.3+ 신규 프로젝트만)]
    memory/plans/<project>/ — 계획서/맥락노트/체크리스트
    ↓
[brainstorming 스킬 (Lv.3-4 + UX 영향 시)]
    ↓
[배치안 회장 보고]
    ↓
[회장 승인]
    ↓
[task 파일 작성]
    memory/tasks/dispatch-<설명>.md
    ↓
[dispatch.py 실행]
    python3 /home/jay/workspace/dispatch.py --team <team> --task-file <path> --level <normal|critical|security>
    ↓
[dispatch 내부 처리]
    ├─ _check_memory_before_dispatch() — 메모리/리소스 검증
    ├─ _select_and_reserve_bot() — 봇 풀에서 가용 봇 선택 (fcntl 락)
    ├─ build_prompt() — prompts/team_prompts.py로 팀별 프롬프트 생성
    ├─ atomic_json_write — memory/task-timers.json 갱신
    ├─ subprocess.run(["cokacdir","--cron",...]) — 봇 세션 cron 등록 → schedule_id 반환
    └─ memory/capabilities/<task_id>_capability.json snapshot
    ↓
[봇 세션 시작 (cokacdir이 cron 시각에 봇을 깨움)]
    팀장 봇이 자기 챗방에서 task 수행
    ↓
[봇 작업: worktree 생성 → 코드 작성 → 커밋]
    scripts/worktree_manager.py create <project> <task_id> <team_id>
    (봇은 LLM이라 직접 git 호출 — 인프라 스크립트 경유 추정)
    ↓
[봇 보고서 생성]
    memory/reports/<task_id>.md (SCQA 형식)
    ↓
[봇이 .done 파일 생성]
    memory/events/<task_id>.done (JSON, qc_result 포함)
    ↓
[verify_done.py — 완료 시그니처 검증]
    PASS → .done 유지
    FAIL → .done → .done.rejected (rename)
    ↓
[V3 정정 2026-05-05 task-2452 — cron auto_merge.py는 폐기]
    실제 머지 경로 3개:
      A) finish-task.sh → worktree_manager.py finish --action auto (현재 hot path)
      B) taskctl.py merge → gh pr merge
      C) GitHub merge_group + Ruleset(active) — server-side 직렬 머지
    ↓
[taskctl.py로 상태 전이] (taskctl 사용 시)
    CREATED → DISPATCHED → ACKED → RUNNING → PR_OPEN 
    → GUARD_PASS → HUMAN_APPROVED → MERGED → DONE
    ↓
[.done.clear 생성 — 처리 완료 마커]
    ↓
[todo_sync.py — todo.json 동기화]
    sub_item.done=True (단방향, 되돌리기 불가)
    ↓
[아누가 회장에 결과 보고]
```

### 2.2 단계별 상세 (요약)

| 단계 | 실행 주체 | 명령/스크립트 | 읽음 | 씀 | 성공 판단 | 다음 단계 결정 |
|------|----------|------------|------|-----|----------|----------|
| 위임 결정 | 아누 | (대화) | task 요청 | task 파일 | 회장 승인 | 회장 |
| dispatch | 아누 | `dispatch.py` | task 파일, organization-structure.json | task-timers.json, capabilities/, cron | exit code 0 + cron 등록 | 자동 (cron 시각) |
| 봇 세션 시작 | cokacdir | `cokacdir --cron` | cron 큐 | 봇 채팅 메시지 | Telegram 메시지 도착 | 봇 |
| 작업 수행 | 팀장 봇 | (LLM 자체) | task 파일, 코드 | 코드, 보고서, .done | .done 생성 | auto_merge cron |
| 검증 | verify_done.py | `verify_done.py` | task.md 시그니처, .done | .done.rejected (실패 시) | PASS | auto_merge / 아누 |
| 머지 | auto_merge.py | `scripts/auto_merge.py` | .done, 보고서, merge_needed | git merge, .done.clear | git exit 0 | 아누 |
| 최종 동기 | todo_sync.py | `utils/todo_sync.py` | task-timers.json, todo.json | todo.json | 단방향 갱신 | 종료 |

---

## 3. 핵심 스크립트와 책임

> 모든 경로는 `/home/jay/workspace/` 기준.

### 3.1 dispatch.py (위임 진입점)

- **경로**: `dispatch.py` (32줄, shim) + `dispatch/` 패키지 (`__init__.py` 4346줄, core.py, task_id.py, retry.py, prompt.py, audit.py, _state.py)
- **역할**: 모든 위임의 단일 진입점. 봇 풀 관리, task-timers.json 원자적 갱신, cokacdir cron 등록, 프롬프트 생성, 취소(`--cancel`).
- **호출 주체**: 아누(CLI). chain.py, chain_manager.py, orchestrator.py에서도 함수 호출.
- **입력**: `--team`, `--composite`, `--task / --task-file`, `--level normal|critical|security`, `--cancel`, `--check-sessions`, `--project`, `--chain`, `--phases`, `--model`, `--resume-from`
- **출력**: stdout JSON `{"status":"success","task_id":"..."}`. 파일: `memory/tasks/<id>.md`, `memory/task-timers.json`, `memory/chains/<id>.json`, `memory/events/<id>.cancelled`, `memory/capabilities/<id>_capability.json`.
- **exit code**: 0 성공, 1 검증 실패/에러.
- **의존성**: `prompts.team_prompts`, `utils.env_loader`, `utils.atomic_write`, `utils.composite_constants`, `utils.injection_guard`(선택), `subprocess.run(["cokacdir",...])`.
- **자동화 후크 위치**: `_select_and_reserve_bot()` (fcntl 락 내 원자적 봇 예약), `_check_memory_before_dispatch()` (메모리 검증).

### 3.2 chain.py (병렬 Phase)

- **경로**: `chain.py` (553줄)
- **역할**: 여러 팀이 동일 Phase에서 병렬 작업, 모두 완료 시 다음 Phase 자동 dispatch.
- **저장**: `memory/chains/{chain_id}.json`
- **명령**: `create / add-phase / task-done / status / list`

### 3.3 chain_manager.py (순차 체이닝)

- **경로**: `chain_manager.py` (851줄)
- **역할**: 한정승인(scoped delegation)에서 단일팀 Phase 순차 실행.
- **저장**: `memory/chains/chain-{chain_id}.json` (`chain-` 접두어)
- **명령**: `create / next / update / check / check-stalled / list`

### 3.4 orchestrator.py (실시간 폴링)

- **경로**: `orchestrator.py` (678줄)
- **역할**: 3개 팀에 동시 배치, task-timers.json 폴링으로 완료 감지 후 다음 작업 즉시 배치.
- **로그**: `memory/orchestrator.log` (현재 6MB)

### 3.5 scripts/taskctl.py (상태 게이트)

- **원칙**: "taskctl을 거치지 않고는 main을 절대 변경할 수 없다" (코드 주석)
- **상태 모델 (11개)**: CREATED → DISPATCHED → ACKED → RUNNING → PR_OPEN → GUARD_PASS → HUMAN_APPROVED → MERGED → DONE / CANCELLED / FAILED
- **저장**: `.tasks/state/<task_id>.json`
- **필수 CI 체크 (8개)**: `cancel-kill-switch`, `qc-check`, `hidden-path-audit`, `lock-in-check`, `merge-safety-check`, `gemini-review-gate`, `ci/guard`, `guard`
- **명령**: `init / dispatch / ack / run / pr-open / verify / approve / merge / done / cancel / fail / status`
- **bypass**: `TASKCTL_BYPASS=1` (회장 전용, evidence 강제 기록)
- **exit code**: 0 PASS, 1 FAIL(가드 차단/잘못된 전이), 2 internal error.

### 3.6 scripts/worktree_manager.py

- **역할**: 멀티봇 안전 격리를 위한 git worktree 관리.
- **명령**: `create / finish / list / status`
- **부가**: `detect_main_branch()`, Gemini 무료 한도 추적(33건/일).

### 3.7 scripts/g3_independent_verifier.py

- **역할**: `.done` 생성 전 독립 검증. 보고서의 "수정 파일별 검증 상태" 표 파싱, grep으로 변경 키워드 확인, 파일 경로 유효성 검증.
- **함수**: `check_gemini_review()` (466-530행) — Gemini PR 리뷰와 보고서 일치 교차검증.
- **결과**: `checks` dict의 `gemini_review` 키.

### 3.8 scripts/verify_done.py (.done 시그니처 검증)

- **경로**: `scripts/verify_done.py` (81줄)
- **동작**: `.done` 감지 → task 파일의 "## 완료 시그니처" 섹션 grep/pytest 검증
  - PASS → `.done` 유지
  - FAIL → `.done` → `.done.rejected` rename + 사유 기록
  - SKIP → 시그니처 없는 기존 task
- **위임**: `teams/shared/verifiers/signature_check.py`

### 3.9 scripts/auto_merge.py — **[V3 정정] DEPRECATED (2026-05-05, task-2452)**

- **상태**: ⚠️ **사실상 폐기** (코드 자체는 30일 유예 후 2026-06-04 삭제).
- **이유 (raw 증거)**: `logs/auto_merge.log` 24MB 최근 1000줄 = 227건 모두 `[BLOCKED]`. TASKCTL_INVOKED 가드(L2325-2332)가 자기 자신을 차단. 머지 성공 흔적 0건.
- **cron 라인 제거됨**: task-2452 Phase 1에서 `* * * * * /usr/bin/python3 scripts/auto_merge.py …` 삭제 (2026-05-05).
- **legacy 명령** (호출 금지): `scripts/auto_merge.py [--task-id <id>] [--dry-run] [--force-merge <id>]`
- **의존**: `report_parser.py` (테스트/lock_in_verify.py가 First-line guard 추적용으로 참조 — 이들 정리 후 코드 삭제 예정).
- **머지의 진짜 경로 3개**:
  - **A) finish-task.sh → worktree_manager.py finish --action auto** (현재 hot path).
  - **B) taskctl.py merge → gh pr merge** (server-side enforcement, taskctl.py L614-641).
  - **C) GitHub merge_group + Ruleset(active, id=15896715)** (V2 §0 §6.10 참조).

### 3.10 memory/task-timer.py

- **역할**: task-timers.json 직접 관리 (start/end/status/list/progress/log/cleanup/cross-start/cross-end).
- **호출**: dispatch.py가 subprocess로, 또는 수동.
- **부가**: cleanup으로 좀비 task 정리, cross-* 명령으로 외부 agent(Loki, Venus, Maat, Janus) 추적.

### 3.11 utils/todo_sync.py

- **역할**: task 완료 → todo.json sub_item.done 동기화 (단방향).
- **함수**: `sync_task_completion(task_id)`, `retroactive_sync()`, `link_task_to_issue(...)`
- **안전장치**: .bak 백업, fcntl 락, done=True → False 불가.

### 3.12 utils/sanitize_gate.py

- **역할**: 외부 모델(Codex/Gemini) 전송 전 한국 PII 마스킹.
- **대상**: 주민번호, 전화, 이메일, API 키, 계좌번호, 보험 증권번호.
- **동작**: 감지 → 마스킹 → markdown 리포트 생성 → 마스킹된 텍스트만 외부 전달. 차단 없음(경고만).

### 3.13 prompts/team_prompts.py

- **경로**: `prompts/team_prompts.py` (54534 토큰)
- **역할**: 팀별 프롬프트 단일 소스. `TEAM_INFO`, `build_prompt(team_id, task_id, task_desc, level, project_id, chain_id, task_type)`.

### 3.14 utils/worktree_resolver.py

- **역할**: task_id로부터 활성 worktree 디렉터리 탐지 (codex_gate_check 등 외부 verifier 지원).

### 3.15 확인 불가 스크립트

- **PR 생성 자동화 코드** — `gh pr create` 래퍼/subprocess 호출이 dispatch에서 미발견. taskctl.py에 PR_OPEN 상태는 있음. **추정**: 팀 봇이 자기 세션에서 직접 `gh pr create` 실행.
- **CI 8+1 체크의 8개 개별 구현** — taskctl.py에 상수만, 실제 검증 코드 위치 미확인. (예상: `scripts/guard.sh`, `scripts/qc_report_guard.py`)
- **dummy PR 검증 스크립트** — 명시적 dummy PR 검증 코드 미발견.
- **activity-watcher.py** — done-state-machine.md에서 언급되나 실제 파일/구현 미발견.

---

## 4. 상태 저장과 memory 구조

### 4.1 전체 트리

```text
/home/jay/workspace/memory/  (43 디렉터리 + 28 1단계 파일)
├── 1단계 JSON
│   ├── task-timers.json (1.3MB, 37,642줄) ............. 모든 task 중앙 레지스트리
│   ├── organization-structure.json (56KB, 1485줄) ..... 팀/봇 정의 (matrix 조직)
│   ├── memory-check-log.json (24MB, 287,788줄) ........ 무결성 로그
│   ├── token-ledger.json (433KB) ...................... 토큰 사용 추적
│   ├── merge-log.json (111KB) ......................... git 머지 로그
│   ├── todo.json (54KB) ............................... TODO 리스트
│   ├── pipeline-status.json ........................... 파이프라인 상태
│   ├── progress-tracker.json .......................... 진행도
│   └── 20+ 기타
│
├── reports/ (2134개 .md) .............................. 태스크별 SCQA 보고서
├── events/ (4122개) ................................... .done/.done.clear/.codex-gate/.heartbeat 등
├── tasks/ (4314개) .................................... 태스크 메타데이터
├── daily/ (68개) ...................................... 일별 기록
├── plans/ (270 서브디렉터리) ......................... 프로젝트/팀별 계획
├── specs/ (136개 .md) ................................. 기술 스펙
├── heartbeats/ (661개) ................................ 봇 생존 신호
├── meetings/ (500+ .md) ............................... 회의록
├── projects/ (5 서브디렉터리) ........................ 프로젝트 컨텍스트
├── logs/ (17개 + rollback-snapshots/) ................. 시스템 로그
├── archive/, backups/, capabilities/, chains/,
│   checkpoints/, content/, debates/, docs/,
│   drive-changes/, escalations/, experiments/,
│   groupchat/, kickoff/, learnings/, org-details/,
│   orchestrator-snapshots/, outputs/, project-maps/,
│   red_team/, research/, retrospectives/, screenshots/,
│   security/, sessions/, skill-learning/, templates/,
│   tests/, whisper/
```

### 4.2 회장이 질문한 디렉터리 존재 여부

| 요청 항목 | 존재 | 실제 위치 / 대체 |
|----------|------|----------------|
| `memory/reports/` | ✓ | 2134개 .md |
| `memory/context-notes/` | ✗ | `memory/projects/<name>/context.md`로 분산 |
| `memory/gates/` | ✗ | `memory/events/task-*.codex-gate`로 통합 |
| `memory/approvals/` | ✗ | todo.json + .done.clear 통합 추적 |
| `memory/tasks/` | ✓ | 4314개 |
| `memory/task_logs/` | ✗ | `memory/logs/` |
| `memory/bot_logs/` | ✗ | `memory/events/bot-activity.json` + logs/ |

### 4.3 핵심 파일 스키마

#### task-timers.json (단일 중앙 레지스트리, fcntl 락)

```json
{
  "tasks": {
    "task-4.4": {
      "task_id": "task-4.4",
      "team_id": "dev1-team",
      "description": "프로젝트별 라우팅 시스템",
      "start_time": "2026-XX-XXT...",
      "end_time": "2026-XX-XXT...",
      "duration_seconds": 222.8,
      "status": "completed",  // reserved | running | completed | failed
      "duration_human": "3분 42초",
      "token_usage": {
        "input_tokens": ...,
        "output_tokens": ...,
        "total_tokens": ...,
        "cost_estimate_usd": ...
      },
      "worktree_path": "...",
      "schedule_id": "..."
    }
  }
}
```

#### .done.clear (완료 마커, JSON)

실제 샘플 (`memory/events/task-2149.done.clear`):

```json
{
  "task_id": "task-2149",
  "team_id": "dev5-team",
  "end_time": "2026-04-24T09:14:31.418550",
  "duration_seconds": 1415.13602,
  "qc_result": "WARN"   // PASS | WARN | FAIL
}
```

#### bot-activity.json (실시간 봇 상태)

```json
{
  "bots": {
    "anu":         {"status": "processing", "since": "2026-05-05T04:18:24Z"},
    "dev1":        {"status": "processing", "since": "..."},
    "anu-direct":  {"status": "idle",       "since": "..."},
    "marketing":   {"status": "idle",       "since": "..."},
    "publishing":  {"status": "idle",       "since": "..."}
  }
}
```

#### member-status.json (개별 에이전트 추적)

```json
{
  "members": {
    "anu":   {"status": "working", "since": "...", "task": "..."},
    "freya": {"status": "working", "since": "...", "task": "..."}
  }
}
```

### 4.4 신뢰도 분류

| Tier | 파일/디렉터리 | 신뢰도 근거 |
|------|------------|-----------|
| **Tier 1 (자동검증·구조화)** | task-timers.json, .done.clear, bot-activity.json, member-status.json, heartbeats/ | Python 스크립트 자동 생성·갱신, ISO 8601 타임스탬프, fcntl 락 |
| **Tier 2 (자동생성+자연어)** | reports/ | SCQA 형식, 검증 표 포함, grep/pytest 결과 인용. 단 자연어 보고이므로 **외부 검증 필요** |
| **Tier 3 (수동기록)** | organization-structure.json (3-15 갱신), daily/, plans/ | 자동 검증 없음 |

### 4.5 .done 프로토콜

```
[봇 작업 완료]
   ↓
memory/events/task-<id>.done       (생성: 팀장 봇)
   ↓
[verify_done.py 검증]
   PASS → 유지
   FAIL → task-<id>.done.rejected (rename)
   ↓
[auto_merge.py cron 매분]
   merge_needed=true → 머지
   ↓
memory/events/task-<id>.done.clear (생성: auto_merge 또는 아누)
   ↓
memory/events/archive/             (장기 보존)
```

**중요**: `.done` = 미처리 완료, `.done.clear` = 처리 완료. 삭제 금지(히스토리 보존). 회장 주기적 점검: `ls /home/jay/workspace/memory/events/*.done 2>/dev/null`.

---

## 5. 봇 역할과 권한

### 5.1 권한 매트릭스

> ⚠️ "봇이 할 수 있다"는 것은 **LLM 세션이 도구 호출로 명령을 발화**할 수 있다는 의미. 실제 git/PR/merge는 **인프라 스크립트**(worktree_manager, auto_merge)가 수행. 봇이 직접 git 호출하는 코드 패턴은 dispatch/team_prompts에서 미발견.

| 봇 | commit | PR 생성 | merge | task.md 수정 | 위임 | waiver |
|---|--------|--------|-------|------------|------|--------|
| **아누** | ✗ (직접 코딩 금지) | ✗ | ✗ (회장 권한) | ✗ (작성만, 수정은 위임) | ✓ (dispatch.py) | 확인 불가 |
| **dev팀장(헤르메스/오딘/...)** | ✓ (worktree 경유, 추정) | ✓ (gh CLI, 추정) | ✗ (manual policy 기본) | 자기 task만 | 자기 팀원에게만 | ✗ |
| **dev팀원(불칸/이리스/...)** | ✓ (팀장 지시 하) | △ | ✗ | ✗ | ✗ | ✗ |
| **로키 (Loki)** | ✗ | ✗ | ✗ | ✗ | △ (보안 인시던트 시) | ✓ (보안 waiver) |
| **마아트 (Ma'at)** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ (검증만) |
| **회장(사람)** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

### 5.2 핵심 정책 [V2 정정]

- **merge_policy 필드는 task 메타 기본값일 뿐 실제 머지 게이트가 아님** (V1 표현 정정):
  - `dispatch/__init__.py` L891-893에서 task YAML 파싱 시 기본값 `"manual"` 채움
  - 그러나 `scripts/auto_merge.py`에서 `merge_policy`는 **사용되지 않음** (`grep merge_policy scripts/auto_merge.py` = 0건)
  - 실제 게이트는 (a) `merge_needed` 플래그, (b) `auto_merge.py` Tier 분류, (c) **GitHub Ruleset `main-protection` (active)**, (d) CI 7-step + Gemini Gate, (e) `taskctl` 상태 모델 — 다층 구조
- **Tier 분류** (`auto_merge.py:1026~1058`):
  - **Tier 1** (Lv.0~1 + diff < 300 LOC) → 자동 머지 진행
  - **Tier 2** (Lv.2 / 파일 >5 / 의존성 변경) → 1-tap Telegram inline button 승인 큐 + escalate (자동 머지 차단)
  - **Tier 3** (보호 경로 / Lv.3+) → manual approval required + escalate (자동 머지 차단)
  - 기본 fallback = Tier 2
- **GitHub Ruleset `main-protection`** (raw API 확인, id=15896715, enforcement=active, 2026-05-04 회장 직접 등록): Organization 전환(`Jeon-Jonghyuk`) + team plan 후 server-side 강제. 7개 required checks + `merge_group` 트리거.
- **critical/security level**: dispatch 시 approval check 통과 필요 (`dispatch/__init__.py` L2532, L3170, `_APPROVAL_AVAILABLE`).
- **independent waiver/예외처리 메커니즘**: `TASKCTL_BYPASS=1` (회장 전용, evidence 강제 기록)이 가장 가까움. 그 외 명시적 waiver 코드 미발견.
- **봇은 OS 프로세스 아님**: 모두 Telegram 챗방 + cokacdir 세션의 LLM agent. 데몬/서비스 아님.

### 5.3 위임 규칙

- **아누 → 팀장**: dispatch.py로만. 직접 메시지 금지.
- **팀장 → 팀원**: 자기 챗방 내에서 LLM 자율 (Task tool 등).
- **팀장 → 다른 팀**: 금지. 회장 승인 후 아누가 dispatch로 재위임.
- **composite 위임**: `--composite team1,team2`로 2~3개 논리팀 동시 위임 (예: design+marketing).

---

## 6. 검증/Gate 체계

> 게이트 설정 중앙: `/home/jay/workspace/config/gate-config.json`. 로더: `utils/gate_config_loader.py`.

### 6.1 게이트 목록

| 게이트 | 위치/구현 | 모드 | 실행 시점 | FAIL 시 |
|--------|----------|------|---------|--------|
| **impact_scanner** | gate-config.json | warn | dispatch 전후 | 경고만 (15초 타임아웃, 차단 임계 6) |
| **ci_preflight** | gate-config.json | warn | task 시작 전 | 경고만 (300초 전체 타임아웃) |
| **l1_smoketest** | gate-config.json | **fail** | 작업 후 | **차단** (기본 기능 검증) |
| **goal_assertions** | gate-config.json | **fail** | 작업 후 | **차단** (최대 5개 단위 assertion) |
| **unresolved_gate** | gate-config.json | warn | 작업 후 | 경고만 (미해결 ≤3개) |
| **Codex 사전 검증** | `memory/events/<task>.codex-gate` (JSON) | (강제 X) | 작업 중 | 조언/제안만, **차단 없음** |
| **g3_independent_verifier** | `scripts/g3_independent_verifier.py` | fail (추정) | .done 전 | QC FAIL 반환 |
| **verify_done.py 시그니처** | `scripts/verify_done.py` | fail | .done 직후 | `.done` → `.done.rejected` |
| **sanitize_gate** | `utils/sanitize_gate.py` | (마스킹만) | 외부 모델 호출 전 | 차단 없음, 자동 마스킹 |
| **gemini_review_check** | `teams/shared/verifiers/gemini_review_check.py` | fail (추정) | PR 검토 후 | High severity 미반영 시 FAIL |
| **CI (GitHub Actions)** | `.github/workflows/ci.yml` (프로젝트별) | **fail** | PR/push to main | branch protection으로 머지 차단 |

### 6.2 taskctl 8개 필수 CI 체크 [V2 정정 — 실구현 확인됨]

`scripts/taskctl.py` 상수 + `.github/workflows/ci.yml` (task-2440 PR #14 머지 완료) + `Ruleset id=15896715` 모두에서 동일하게 정의:

1. `cancel-kill-switch` — 취소된 task의 머지 시도 차단
2. `qc-check` — QC 보고서/시그니처 검증
3. `hidden-path-audit` — 숨김 경로(스코프 외) 변경 감지
4. `lock-in-check` — `scripts/lock_in_verify.py` (AST 기반 First-line 가드)
5. `merge-safety-check` — 머지 안전성 검증
6. `gemini-review-gate` — `scripts/gemini_review_gate.py` (Gemini Review를 GitHub check run으로 강제)
7. `ci/guard` — 통합 가드
8. `guard` (taskctl 상수, ci/guard와 별개일 가능성)

→ **8번째 `guard`의 실제 구현은 확인 불가**. 7개는 task-2440 보고서로 확인됨.
→ **server-side enforcement**: `Ruleset main-protection (active)` + `merge_group` 트리거로 GitHub이 직렬 처리.

### 6.3 게이트 흐름 [V2 정정 — 실측 기반]

```
Task Dispatch (dispatch.py)
    ↓
[impact_scanner] (warn)
[ci_preflight]   (warn)
    ↓
봇 작업 수행 (worktree 격리, pre-push hook이 main 직접 push 차단)
    ↓
[Codex 사전 검증] → memory/events/<id>.codex-gate (조언/제안)
[Gemini PR 리뷰] (PR 코멘트, 3회 실패 시 human_review_required 라벨)
    ↓
[goal_assertions / l1_smoketest] (fail mode → 차단)
    ↓
.done 생성
[verify_done.py] — 시그니처 검증, FAIL 시 .done.rejected
[g3_independent_verifier] — 보고서/PR 교차검증
[gemini_review_check] — High severity 누락 검증
    ↓
PR 생성 → merge_group 트리거 (GitHub Merge Queue 직렬 처리)
    ↓
[CI 7-step required checks] (server-side, Ruleset 강제):
   cancel-kill-switch / qc-check / hidden-path-audit /
   lock-in-check / merge-safety-check / gemini-review-gate / ci/guard
    ↓
[Ruleset main-protection (active)] — 7개 통과해야 머지 가능
    ↓
[auto_merge.py Tier 분류]:
   Tier 1 → 자동 머지 / Tier 2 → 1-tap 승인 큐 / Tier 3 → manual
    ↓
[taskctl 상태] PR_OPEN → GUARD_PASS → HUMAN_APPROVED → MERGED → DONE
    ↓
.done.clear 생성 + audit log
```

### 6.4 "룰셋 8"의 정의 [V2 정정 — 부분 해소]

- 발견된 후보 두 가지:
  - **(a) task-2440 enforcement 7-step + 1**: `cancel-kill-switch`, `qc-check`, `hidden-path-audit`, `lock-in-check`, `merge-safety-check`, `gemini-review-gate`, `ci/guard` (+ taskctl 상수의 `guard`). **이쪽이 현재 시스템 enforcement의 본체**로 확인됨.
  - (b) 보험 도메인 3-Layer 컴플라이언스(`blog_quality_gate_design.py`) — 별개 도메인.
- **외부 조언자에게**: "룰셋 8"을 자동화 게이트 맥락에서 보면 (a)가 정답. 회장 확인 권고는 유지(8번째 `guard`가 `ci/guard`와 동일한지).

---

## 7. 자동 진행/차단 메커니즘 [V2 정정]

### 7.1 활성 자동 실행 (cron / systemd / GitHub server-side)

```cron
# [V3 정정 2026-05-05 task-2452] auto_merge.py 매분 cron 라인 제거됨 (사실상 폐기, 머지 0건).
#  실제 머지는: A) finish-task.sh → worktree_manager.py finish, B) taskctl.py merge, C) merge_group + Ruleset.
# (legacy, 더 이상 등록되지 않음) * * * * * cd /home/jay/workspace && /usr/bin/python3 scripts/auto_merge.py >> logs/auto_merge.log 2>&1

# 매시간 — 좀비 task 정리
0 * * * * bash /home/jay/workspace/scripts/cleanup-stale-tasks.sh
```

```
# systemd
cokacdir.service — Telegram 봇 통합 + 세션 관리 (active running)
```

```
# GitHub server-side (raw API 확인, 2026-05-04 회장 등록)
Repository: Jeon-Jonghyuk/dev_workspace (Organization, team plan)
Ruleset:    id=15896715, name="main-protection",
            target=branch, enforcement=ACTIVE
            → 7개 required checks + merge_group 트리거 강제
```

```
# Client-side hook
.git/hooks/pre-push — main branch direct push 차단 (BLOCKED, exit 1)
```

### 7.2 다음 단계 결정 주체

| 트리거 | 자동/수동 | 결정자 |
|--------|---------|--------|
| dispatch 후 봇 세션 시작 | **자동** | cokacdir cron (등록된 schedule_id) |
| 봇 작업 완료 → .done | 봇 자율 | 팀장 봇 |
| .done → 머지 시도 | **자동** (cron) | auto_merge.py |
| merge_needed 판단 | 수동 (보고서 텍스트) | 팀장 봇이 보고서에 명시 → auto_merge가 파싱 |
| merge_policy 적용 | **자동** (정적 규칙) | task 파일 YAML or default=manual |
| 다음 phase 위임 | 수동 | 회장 (아누가 제안) |
| critical/security 진행 | 수동 (approval check) | 회장 |
| 에스컬레이션 처리 | 수동 | 회장 + 아누 |

### 7.3 "보고만 있고 명시적 실행 지시 없으면 보류" 규칙 위치

- **CLAUDE.md** (이 파일): "직접 코딩 금지. 반드시 팀에 위임", "독단 행동 금지: 클론, 삭제, 구조 변경 등 되돌리기 어려운 행동은 반드시 사전 승인", "위임 완결성 4대 규칙".
- **memory/MEMORY.md** 참조 메모리: `feedback_no_unilateral_action.md`, `feedback_premature_dispatch.md`, `feedback_dispatch_no_mid_correction.md`(★★★ 격상).
- **dispatch-rules.md**: "절대 독단으로 위임하지 않는다", "Phase 분리 원칙".
- **코드 강제는 거의 없음**: 대부분 메모리/문서 차원의 규칙. taskctl.py의 상태 전이 강제는 예외.

### 7.4 슬래시 명령

| 명령 | 의미 |
|------|------|
| `/brainstorming` | Lv.3-4 + UX 영향 시 사전 설계 (위임 전 필수) |
| `/dispatch-rules` | 위임 규칙 상세 (skills-lock.json) |
| `/loop` | 반복 실행 |
| `/schedule` | cron 등록 |
| `/config` | 설정 변경 |
| `/work-level` | 작업 레벨 판정 (Lv.0~4) |
| `/insane-design` | URL 디자인 벤치마킹 |
| `/diary`, `/reflect` | 다이어리/회고 |
| **`/B`** | **회장 표현. 단일 정의 파일은 본 조사에서 확인 불가**. 컨텍스트로는 "다음 진행 OK" 류로 추정되나 **단정 금지**. |

### 7.5 worktree 선택

`scripts/finish-task.sh` L65-109 + `utils/worktree_resolver.py` 패턴:

1. `task-timers.json[task_id].worktree_path` 우선
2. task 파일 상단 `## worktree: /path` 파싱
3. fallback: `{projects_root}/*/.worktrees/{task_id}-*` glob (최근 수정)
4. 모두 실패 시 None

---

## 8. 실패/예외 처리

| 실패 케이스 | 판단자 | 기록 위치 | 자동 차단 | 차단 지점 | 진행 조건 |
|-----------|--------|----------|---------|---------|----------|
| CLI case 일부 실패 | goal_assertions gate | stderr/logs | ✓ (mode: fail) | goal 검증 | `.done` 미생성 |
| stash 복원 실패 | 확인 불가 | 확인 불가 | 확인 불가 | 확인 불가 | 확인 불가 |
| main branch에서 작업 감지 | worktree_manager.detect_main_branch() | logs | △ (추정 가드) | worktree create | 새 worktree 강제 |
| task.md ↔ 구현 불일치 | g3_independent_verifier | QC FAIL record | ✓ (추정) | QC 레이어 | 재작업 |
| critical/high 위반 | Codex companion | `.codex-gate` | **✗ (조언만)** | 차단 없음 | 회장 판단 |
| CI 일부 실패 | GitHub Actions | workflow logs | ✓ | branch protection | 재커밋 후 재실행 |
| dummy fixture 부족 | 확인 불가 (스크립트 미발견) | - | - | - | - |
| dead code 발견 | feedback_no_dead_code_skills 메모리 룰 | (코드 강제 없음) | ✗ | - | 메모리/문서 차원 |
| Gemini High 미해결 | gemini_review_check.py | QC FAIL record | ✓ | QC | 기각 사유 작성 |
| 좀비 봇 작업 (취소 후 무시) | bug_zombie_bot_pr_101 학습 | - | **✗** (가드 코드 없음, 미해결) | - | 회장 수동 정리 |

### 8.1 사람 승인 표현

- **Telegram 메시지**: "위임", "승인", "/B" 등 회장 발화. 별도 파일 마커 없음.
- **task 파일 YAML**: `merge_policy: auto` 명시 시 자동.
- **환경변수**: `COKACDIR_KEY_ANU` 존재 시 critical/security approval 가능. 구체 트리거 메커니즘 **확인 불가**.
- **`.done` 직접 처리 클리어**: 회장이 보고 받고 OK하면 아누가 `.done` → `.done.clear` rename.

### 8.2 핵심 미해결 (회장 정립 사고)

- **★★★ "위임 후 중간 정정 = 100% 무효"** (2026-05-04 격상): task.md/cron/메모리 어떤 수정도 봇 미도달. 정정은 새 task ID(`+1`)로 재위임만 허용.
- **★ 좀비 봇 PR #101**: cancel 후 봇이 무시하고 PR 생성 (2026-05-04). 가드 코드로만 차단 가능, 현재 미구현.

---

## 9. 실제 task 사례 — task-1970

> 시스템 흐름 이해용. 해결책 아님.

| 항목 | 값 |
|------|-----|
| **Task ID** | task-1970 |
| **목적** | Gemini PR 리뷰 강제 적용 시스템 수정 (task-1968 허점 보강) |
| **작업 디렉터리** | `/home/jay/.cokacdir/workspace/4CB20CDC/` (memory 포함) |
| **브랜치명** | (보고서 미명시) |
| **관련 파일** | 보고서: `memory/reports/task-1970.md`. 참조: `prompts/DIRECT-WORKFLOW.md`, `scripts/worktree_manager.py` |

### 실행 순서 (보고서 재구성)

| # | 단계 | 파일/명령 | 결과 |
|---|------|---------|------|
| 1 | task-1968 허점 분석 | (LLM 분석) | 6건 구조적 결함 도출 |
| 2 | 수정 1 | `scripts/worktree_manager.py:452` | Gemini 이미지 패턴 추가 |
| 3 | 수정 2 | `scripts/worktree_manager.py:930` | 타임아웃 차단 로직 |
| 4 | 신규 verifier | `teams/shared/verifiers/gemini_review_check.py` | Gemini 교차검증 |
| 5 | 수정 3 | `scripts/worktree_manager.py:656` | collect_mode 기본값 |
| 6 | 수정 4 | `prompts/DIRECT-WORKFLOW.md` | 기각 사유 필수 규칙 |
| 7 | 수정 5 | `scripts/g3_independent_verifier.py:466` | check_gemini_review() 함수 |
| 8 | 단위 테스트 | `tests/test_gemini_parser_1970.py` | **20 passed in 0.10s** |
| 9 | 회귀 테스트 | (기존 35건) | PASS |

| 항목 | 값 |
|------|-----|
| **stdout/stderr/exit code 저장** | 보고서 본문에 결과 인용. 별도 파일 저장 여부 **확인 불가** |
| **생성된 reports** | `memory/reports/task-1970.md` (SCQA + 검증표 + 셀프 QC 체크리스트) |
| **생성된 commits** | 보고서 미명시 |
| **PR 여부** | 보고서 미명시 |
| **CI 여부** | pytest 20+35건 PASS (CI 워크플로우 호출 여부 미명시) |
| **최종 상태** | `.done` 추정 (verification-before-completion 통과) |
| **문제 발생 지점** | 없음 (6건 모두 수정 완료) |

→ **시사점**: 보고서는 자연어 + 검증표 형식. PR/CI/머지 단계는 **보고서에 명시 안 됨** = 시스템적 evidence 추적이 보고서 외부에 존재하거나 누락. 외부 조언자가 자동화 제어를 넣을 때 "evidence 표준 스키마"가 약점일 수 있음.

### 9.1 [V2 추가] enforcement 시스템 사례 — task-2440 / 2449 / 2451

V1의 task-1970 사례는 단일 task 흐름이지만, 본 시스템의 자동화 제어 핵심은 **task-2440 → 회장 직접 처리(2026-05-04 09:18) → task-2449 → task-2451**의 4단 시퀀스. 외부 조언자는 이쪽을 먼저 봐야 함.

**task-2440 (2026-05-04, dev1팀 헤르메스, PR #14 머지)**:
- 목적: GitHub repo 보호 규칙 + Required Checks + Gemini Gate + Merge Queue로 cancelled 작업이 main에 들어가는 것을 영구 차단.
- 구현: `scripts/lock_in_verify.py` (AST 기반), `scripts/gemini_review_gate.py`, `scripts/gemini_feedback_loop.py`, `.github/workflows/ci.yml` (7-step + merge_group), 회귀 테스트 21건 PASS.
- 한계 시점: `JonghyukJeon` 개인 free private repo 제약으로 server-side enforcement 등록 불가 — 봇 권한으로는 4/7만 PASS, A/B/E는 **회장 직접 처리 필요**로 보고.
- evidence: `memory/reports/task-2440-enforce/` 11개 raw GitHub API 응답 캡처(`00-repo-meta.json` ~ `10-md-bypass-test.txt`).

**회장 직접 처리 (2026-05-04 09:18:09 KST)**:
- `JonghyukJeon` (개인) → **`Jeon-Jonghyuk` Organization** 전환.
- Plan: free → **team** (private_repos 999,999, seats 1).
- **Ruleset 등록**: `id=15896715, name="main-protection", target=branch, enforcement=active`.
- 결과: task-2440 [11].A/B/E 항목이 server-side에서 enforce됨.

**task-2449 (2026-05-05)**:
- 회장 절대 기준 7항목 + 9건 침투 테스트:
  1. CANCELLED state 머지 시도 → 차단
  2. HUMAN_APPROVED 미달 머지 → 차단
  3. state 파일 checksum 변조 → 검출
  4. `auto_merge.py` 직접 호출 (TASKCTL_INVOKED 미설정) → 차단
  5. 비정상 상태 전이 (CREATED → MERGED 직행) → 차단
  6. `gh pr merge` 직접 호출 코드 검색 → 0건
  7. pre-push hook의 main 거부 → 동작
  8. refspec 우회 (다른 브랜치 → origin/main) → 차단
  9. bypass evidence 기록 (회장 override) → 강제 기록 동작
- 모두 raw 실행 로그로 증명.

**task-2451 (2026-05-05, 본 V2 작성 시점 .done 미처리)**:
- 9 케이스 매트릭스 + 합격 A~G 판정.
- gate_results: `impact_scanner=PASS, ci_preflight=PASS, l1_smoketest=PASS, goal_assertions=PASS, unresolved_gate=PASS`, qc_result=`WARN`.
- 본 V2 정정 후 회장 추가 검증 예정 → `.done.acked` 처리 보류.

→ **시사점**: 외부 조언자가 "자동화 제어를 어디에 넣을지" 판단할 때, 이 4단 시퀀스가 **현재 시스템의 본질적 enforcement**임을 인지해야 함. V1에서 이 부분이 누락된 게 가장 큰 결함.

---

## 10. 변경 가능 영역과 제약

### 10.1 바꿀 수 있는 것

- 게이트 설정값 (`config/gate-config.json` mode/threshold).
- 신규 게이트 추가 (gate_config_loader.py 인터페이스 따라).
- 신규 cron job 추가.
- 신규 verifier 모듈 (`teams/shared/verifiers/`).
- task 파일 YAML 필드 (merge_policy, allowed_resources 등).
- 프롬프트 (`prompts/team_prompts.py` TEAM_INFO).

### 10.2 바꾸면 안 되는 것 (운영 안전)

- **task-timers.json 직접 편집 금지** — 반드시 `task-timer.py` 또는 dispatch 경유 (fcntl 락).
- **memory/events/*.done 직접 삭제 금지** — `.done.clear`로 rename만(히스토리 보존).
- **bot_settings.json 모델 설정** — 회장 권한 (CLAUDE.md 명시).
- **organization-structure.json 무단 변경 금지** — 봇/팀 정의는 회장 승인.
- **git stash/reset --hard 전체 대상 금지** (메모리 룰 `system_principles.md`): 프로젝트 단위만.

### 10.3 이미 정해진 룰

- **직접 코딩 절대 금지** (아누) — 한 줄도 예외 없음.
- **위임은 dispatch.py로만**.
- **위임 후 중간 정정 100% 무효** — 새 task로 재위임.
- **3 Step Why** — 모든 설계 결정은 1st Why → A답 → 2nd Why → B답 → 3rd Why → C답 일관성 검증.
- **3문서**: 시스템(아키텍처) vs 작업(Lv.3+ 개별) — 2유형.
- **Phase 분리**: 1 Phase = 1 세션.
- **모듈화 = 사고방식**: 모든 설계에서 "단일 소스 어디?" 먼저.
- **수치 환각 금지**: fact_db에 없는 수치 생성 = 금소법 위반.

### 10.4 사람이 반드시 해야 하는 것

- merge 최종 결정 (manual policy 기본).
- critical/security 작업 승인.
- Phase 간 전환 명령.
- 신규 dispatch 승인 ("배치안 보고 → 회장 승인 → 위임" 강제).
- 에스컬레이션 처리.
- bot_settings.json 모델 변경.
- `.done` 보고 확인 후 `.done.clear` 처리 (보고 없는 자동 클리어 금지).

### 10.5 봇이 절대 하면 안 되는 것

- 회장 미승인 dispatch (아누).
- 직접 코딩 (아누).
- 다른 팀 위임 (팀장).
- main branch 직접 작업 (`detect_main_branch()` 가드).
- task-timers.json 비원자적 갱신.
- 외부 모델 호출 시 PII 미마스킹 (sanitize_gate 우회).
- waiver/예외 자가 승인 (회장 권한).

### 10.6 운영상 인터페이스 호환 요구

- 신규 자동화는 **dispatch.py 인터페이스 + task-timers.json 스키마**와 호환되어야 함.
- worktree는 **`<project>/.worktrees/<task_id>-<team>` 패턴** 유지.
- `.done`/`.done.clear` JSON 스키마 유지 (qc_result 필드 필수).
- 회장은 **Telegram 챗방**이 단일 통제 인터페이스 — 별도 UI 추가 시 chat_id/key 인증 필요.

---

## 11. 개선 요구사항 (회장 관점에서 추정 — 본 조사 한계 명시)

> ⚠️ 이 섹션은 회장의 명시적 요구가 아닌, 메모리/CLAUDE.md/최근 사고에서 **추론한 개선 방향**. 회장 확인 필요.

### 11.1 추정 우선순위 (높음)

1. **위임 후 중간 정정 봇 도달 메커니즘 부재** (★★★ 사고).
   - 현재: task.md/cron/메모리 수정해도 봇 미도달.
   - 필요: 봇 세션 진행 중 task 변경을 안전하게 전달하거나, 변경 시 강제 재시작.
2. **좀비 봇 가드 미구현** (PR #101 사고).
   - 현재: cancel 후에도 봇이 PR 생성 가능.
   - 필요: `.cancelled` 마커 봇 세션 측 강제 인지 (worktree git hook? PR 생성 전 cancel 체크?).
3. **PR 생성/CI/finish 자동 제어 부재**.
   - 현재: PR 생성 코드 위치 미확인. CI 8개 체크 구현 미확인. taskctl.py가 상태만 추적.
   - 필요: PR ↔ taskctl ↔ auto_merge 일관 자동화.

### 11.2 추정 우선순위 (중간)

4. **evidence 표준 스키마**: 보고서가 자연어 + 임의 표 형식. 자동 검증이 grep/parser에 의존.
5. **자동 재시도 + 자동 에스컬레이션**: 현재 retry-escalation-protocol.md만 문서화.
6. **Phase 간 자동 위임**: 조건식 기반 자동 dispatch (개발 완료 → QC 위임).

### 11.3 추정 우선순위 (낮음, 신중)

7. UX 변경 자동 감지 → /brainstorming 자동 트리거.
8. 보고서 품질 자동 검증 (merge_needed 판단 보조).
9. waiver 명시적 승인 워크플로우 추가.

### 11.4 변경 폭에 대한 회장 입장 (추정)

- 메모리에서 강한 신호: **"최소 변경으로 보완"** 선호.
- 근거: "Surgical Changes" 코딩 4원칙, "위임 후 중간 정정 무효" 사고로 인한 변경 비용 인식.
- **외부 조언자 권고**: 기존 `gate-config.json` + `dispatch.py` 인터페이스를 유지하면서 게이트/verifier만 추가하는 방향이 안전.

---

## 12. 외부자가 오해하면 안 되는 점

1. **아누는 일반 오케스트레이터(Airflow/Temporal 류)가 아니다.**
   - 아누는 **Telegram 챗방의 LLM 세션**이다. 워크플로우 엔진의 코드 노드가 아님.
   - "아누가 결정한다" = "아누 챗 세션이 결정 발화하고, 인프라 스크립트가 그것을 실행한다."

2. **봇들은 OS 프로세스가 아니다.**
   - 모두 LLM agent (Telegram + cokacdir 세션). systemd unit/데몬 아님.
   - "봇이 작업한다" = "해당 챗방의 LLM 세션이 cron 시각에 활성화되어 도구 호출을 발화한다."

3. **`memory/reports/`는 evidence가 아니라 자연어 보고서다.**
   - SCQA + 검증표 형식이지만 본질은 LLM이 작성한 자연어.
   - 자동 검증은 grep/parser 의존. 진정한 evidence는 git diff, pytest output, .done.clear의 qc_result.
   - **신뢰도 Tier 2** (자동검증 가능한 task-timers.json/.done.clear는 Tier 1).

4. **merge 게이트는 다층이다 — `merge_policy=manual` 단일 게이트가 아니다. [V2 정정]**
   - `merge_policy` 필드는 task 메타 라벨일 뿐 실제 머지 게이트가 아님(`auto_merge.py`에서 0건 사용).
   - 실제 게이트: (a) `merge_needed` 플래그 → (b) `auto_merge.py` Tier 분류 → (c) GitHub Ruleset(active, server-side) + CI 7-step → (d) `taskctl` 상태 모델.
   - **Tier 1만 자동 머지**, Tier 2는 1-tap Telegram 승인, Tier 3는 manual.
   - server-side enforcement는 2026-05-04부터 active(Ruleset id=15896715).

5. **worktree_manager가 이미 일부 게이트 역할을 한다.**
   - main branch 가드, Gemini 일 한도 추적, worktree 격리.
   - 새 게이트를 도입할 때 worktree_manager 흐름과 중복되지 않게 주의.

6. **특정 명령은 사람이 명시해야만 실행된다.**
   - dispatch는 회장 승인 후에만.
   - Phase 전환은 회장 명령 후에만.
   - critical/security는 회장 approval 후에만.
   - "보고는 있고 명시 지시 없으면 보류"가 시스템 기본 정책.

7. **`.done`과 `.done.clear`는 다르다.**
   - `.done` = 미처리 완료 (회장/아누 검토 대기).
   - `.done.clear` = 처리 완료 (히스토리 보존).
   - 자동 클리어 금지 — 회장 보고 후 클리어.

8. **"룰셋 8"의 단일 정의 파일은 (본 조사에서) 미확인이다.**
   - taskctl 8개 CI 체크일 가능성 높음. 또는 보험 도메인 3-Layer.
   - 외부 조언자 작업 시 회장에게 정확한 정의 확인 권고.

9. **dev8팀(라)만 비-Anthropic이다.**
   - 팀원 4명이 GLM-5(Z.AI). 다른 모든 봇은 Claude (Opus 4.6/4.7 또는 Sonnet 4.6).
   - Codex/Gemini는 횡단 CR (아틀라스/비너스).

10. **task-timers.json은 단일 SoT(Source of Truth)다.**
    - 1.3MB, fcntl 락. 직접 편집 절대 금지.
    - 자동화 제어 추가 시 이 파일을 통해야 다른 컴포넌트와 일관 유지.

11. **자동화 수준은 약 60~70%다 (V1의 30~40%는 enforcement 누락분 미반영). [V2 정정]**
    - server-side Ruleset + CI 7-step + Tier 1 자동 머지 + 차단 게이트 자동 → 일상 흐름의 다수가 자동.
    - 단 Tier 2/3 승인, Phase 전환, 신규 dispatch는 여전히 회장 결정.
    - 외부 조언자가 "전체 자동화"를 제안할 때는 회장 결정 영역(전략/우선순위)과 자동화 영역(머지/검증/차단)을 분리해서 제안할 것.

12. **위임 후 중간 정정은 100% 무효다 (★★★).**
    - 2026-05-04 회장 격상. 시스템 설계 결함으로 명시.
    - 외부 조언자가 "task 진행 중 동적 변경"을 제안하면 신중히 검토 필요.

---

## 부록 A. 자동화 제어 후보 지점 요약 [V2 정정]

| 위치 | 파일/경로 | 현재 역할 | 자동화 후크 가능성 |
|------|---------|---------|-----------------|
| 위임 진입 | `dispatch/__init__.py` `dispatch()` | 모든 위임 시작점 | 사전 게이트 추가 용이 |
| 봇 예약 | `dispatch/__init__.py` `_select_and_reserve_bot()` | fcntl 락 내 원자 예약 | 정책 기반 봇 라우팅 |
| 메모리 사전검증 | `_check_memory_before_dispatch()` | allowed_resources snapshot | 정책 검증 강화 |
| Phase 체이닝 | `chain.py`(병렬) / `chain_manager.py`(순차) | Phase 자동 전환 | 조건식 기반 자동 진행 |
| 상태 게이트 | `scripts/taskctl.py` | 11상태/8 CI 체크 | **가장 유력한 자동화 허브** |
| 완료 검증 | `scripts/verify_done.py` + `g3_independent_verifier.py` | 시그니처/교차검증 | 검증 룰 추가 용이 |
| 자동 머지 + Tier 분류 | `scripts/auto_merge.py` (cron) | .done → Tier 분류 → 머지/escalate | 정책 강화 가능 |
| **CI 7-step + Gemini Gate** | `.github/workflows/ci.yml` + `scripts/gemini_review_gate.py` + `scripts/gemini_feedback_loop.py` + `scripts/lock_in_verify.py` | server-side 차단(merge_group) | task-2440에서 본체 구현. 추가 check 등록 시 Ruleset 갱신 필요 |
| **Ruleset (server-side)** | GitHub Repository Ruleset id=15896715 (main-protection, active) | 7개 required checks + merge_group 강제 | 회장 권한(GitHub Settings). 봇은 등록 불가, 검증만 가능 |
| **Client pre-push hook** | `.git/hooks/pre-push` | main 직접 push 차단 | 추가 가드 가능 |
| 1-tap 승인 | `scripts/anu_confirm_bot/main.py` `send_approval_card` | Tier 2 inline button | 승인 정책 추가 |
| 게이트 설정 | `config/gate-config.json` | 5개 게이트 mode/threshold | 추가 게이트 정의 |
| 외부 모델 가드 | `utils/sanitize_gate.py` | PII 마스킹 | 차단 모드 추가 가능 |
| 메모리 동기 | `utils/todo_sync.py` | task ↔ todo 단방향 | 정책 단순 |

---

## 부록 B. 본 문서에서 "확인 불가" 항목 모음 [V2 정정 — 일부 해소]

1. ~~**PR 생성 자동화 코드 위치**~~ → **[V2 해소]** task-2440에서 PR 생성/머지가 anu_confirm_bot + auto_merge 경유로 동작 (raw 로그 확인). 단 CLI 진입점 단일 코드 위치는 별도 grep 필요.
2. ~~**CI 8+1 체크 8개의 실제 구현 위치**~~ → **[V2 해소]** `.github/workflows/ci.yml` (task-2440 머지 완료)에 7개 구현. 8번째 `guard`는 taskctl 상수, 별개 여부 미확정.
3. **dummy PR 검증 스크립트** — 명시적 구현 미발견.
4. **activity-watcher.py** — done-state-machine.md 언급, 실제 파일 미발견.
5. **stash 복원 실패 처리** — 흐름 미확인.
6. **waiver/예외처리 메커니즘** — `TASKCTL_BYPASS=1`(회장 전용) 외 명시적 코드 미발견. task-2449 침투 테스트 9에서 bypass evidence 강제 기록은 동작 확인.
7. **COKACDIR_KEY_ANU approval 트리거** — 환경변수 인식만, 실제 트리거 메커니즘 미확인.
8. **개별 .done 파일 권한(600)** — 일부 읽기 불가.
9. **`.codex-gate` 상세 포맷** — 일부 권한 제한.
10. **각 슬래시 명령(`/B` 등) 정확한 정의** — skill registry만 확인.
11. ~~**"룰셋 8"의 단일 정의 파일**~~ → **[V2 부분 해소]** task-2440 7-step + taskctl `guard` 상수가 본체. 8번째 항목 단일성만 미확정.
12. **봇이 직접 git commit 하는 코드 패턴** — dispatch/team_prompts에서 미발견. **추정**: worktree_manager.py 경유 또는 봇 세션 내 LLM 도구 호출.
13. **task-1970의 PR/commit/CI 정확한 흐름** — 보고서 미명시 (task-2440 이전 사례).
14. **stash 복원, dummy fixture 부족, dead code 발견 시 정확한 처리** — 코드 강제 메커니즘 미확인.
15. **[V2 신규] Ruleset 8번째 `guard`** — taskctl 상수의 `guard`가 ci.yml의 `ci/guard`와 동일 체크인지, 별개 체크인지 미확정.
16. **[V2 신규] org `Jeon-Jonghyuk` plan 변경 이력** — 회장 직접 처리 시점(2026-05-04 09:18) 외 상세 미확인.
17. **[V3 신규 — task-2452] `.done.escalated` 마커 생성자 미상**:
    - V2 §10 / 신호등 분석 보고서에서 "auto_merge가 .done.escalated/.done.merging/.done.clear 마커를 만든다"고 추정했으나, **`scripts/auto_merge.py` 코드 grep 결과 마커 생성 코드 0건**.
      - `escalate()` 메서드 (L400-444): cokacdir Telegram 메시지만 보냄. 파일 생성 없음.
      - `_finalize_done_file()` (L1095-1107): `log_result()` 호출만. .done 파일 삭제도 안 함.
      - try_claim() (L131-153): `.done.merging`만 생성 (선점 마커, escalated 아님).
    - 실제로 task-2451의 0byte `.done.escalated` (2026-05-05 13:56 생성) 출처 불명. 본 task에서 추가 추적 권고.
    - 의심 후보: cokacdir 외부 스크립트, anu_confirm_bot, 또는 회장 수동 생성. 별도 추적 task 필요.

---

## 부록 C. 본 문서 작성 메타데이터

- **V1 조사 방법**: Explore 서브에이전트 4명 병렬 (코어 스크립트 / memory 구조 / 봇·자동진행 / 검증·task사례).
- **V2 정정 방법**: 회장 지적 → task-2440/2447/2449/2451 보고서 직접 정독 + GitHub raw API 직접 호출(`gh api repos/Jeon-Jonghyuk/dev_workspace/rulesets`, `branches/main/protection`, `repos/...`).
- **조사 범위**: `/home/jay/workspace/` 기준. `.openclaw` 별도 시스템은 범위 외.
- **인용 원칙**: 파일 경로 + 줄번호 + 실제 내용. 추론은 "추정"으로 명시.
- **갱신 주기**: 본 문서는 외부 조언자용 스냅샷. 시스템 변경 시 재작성 필요.
- **단일 소스**:
  - 봇/팀 정의: `memory/organization-structure.json`
  - 게이트 설정: `config/gate-config.json`
  - task 상태: `memory/task-timers.json`
  - **enforcement 게이트**: `.github/workflows/ci.yml` + GitHub Ruleset id=15896715
  - **[V3 정정] 머지 hot path**: `scripts/finish-task.sh` Step 2 → `scripts/worktree_manager.py finish --action auto` (auto_merge.py는 폐기, 30일 유예).
  - **[V3 정정] 신호등 단일 책임**: `scripts/finish-task.sh` Step 2.99 (.done 생성 직전) — `member-status.json` + `bot-activity.json` 동시 idle 전환.

### 향후 검증 대기 항목 (V3에서 일부 반영, 추가는 V4 예정)

- ~~회장이 "추가로 검증할 게 더 남아있다"고 지시 (2026-05-05 V2 시점)~~ → **[V3 일부 반영]** task-2452에서 신호등 sync + auto_merge 폐기 정정.
- V4 작성 시 다음 후보 점검:
  - Ruleset 7개 required check가 실제 GitHub Actions에서 모두 fail-fast로 동작하는지 raw run 로그 검증
  - taskctl 8번째 `guard` 상수의 정체
  - `merge_group` 트리거의 직렬 처리가 race 0건을 보장하는지(task-2449 Pen 9 외)
  - `human_review_required` 라벨 부착 시 이후 흐름(에스컬레이션 라우팅)
  - **[V3 신규]** `.done.escalated` 마커 생성자 추적 (부록 B 17번 참조)
  - **[V3 신규]** `done-watcher.py` fallback grace (30분) 실측 적정성 (회장 운영 5일 후 측정)

---

**V1 끝 / V2 갱신 완료 / V3 갱신 완료 (task-2452, 2026-05-05).**