# Agent 미팅 기록: 3문서 2유형 체계 설계

**일시**: 2026-04-16
**소집자**: 페룬 (6팀장)
**모드**: hybrid / thorough
**관련 작업**: task-1872
**근거**: 제이회장님 결정 (2026-04-16) — 3문서를 "시스템 3문서"와 "작업 3문서" 2유형으로 구분

---

## 참가자

| 역할 | 이름 | 소속 |
|------|------|------|
| 진행/팀장 | 페룬 | 6팀 |
| 백엔드 | 스바로그 | 6팀 |
| 프론트엔드 | 라다 | 6팀 |
| UX/UI | 모코시 | 6팀 |
| 테스터 | 벨레스 | 6팀 |
| DA/보안 | 로키 | 횡단조직 |
| QC | 마아트 | 횡단조직 |

---

## 사이클 기록

### 사이클 1: 개별 의견 수집 (병렬)

모든 참가자가 A(문서 체계 설계) + B(코드 실행단 설계) 양쪽에 대해 의견 제출.

### 사이클 2: 쟁점 식별 및 합의

#### 쟁점 1: 경로 분리 방식

- **로키 제안**: `memory/system/<프로젝트명>/` vs `memory/tasks/<태스크ID>/`
- **라다/모코시 제안**: `memory/plans/system/` vs `memory/plans/tasks/<프로젝트>/`
- **논점**: 기존 `memory/plans/` 경로를 유지하면서 하위에 분기할 것인가, 최상위에서 분리할 것인가

**합의**: 기존 `memory/plans/` 구조를 유지하되, 하위에 분기하는 방식 채택.
```
memory/plans/<프로젝트명>/          ← 시스템 3문서 (기존 유지, 변경 없음)
memory/plans/tasks/<작업명>/        ← 작업 3문서 (신규)
memory/plans/tasks/archived/<작업명>/  ← 아카이브 (신규)
```

**사유**:
1. 기존 시스템 3문서 경로(`memory/plans/anu-guide-system/` 등)를 마이그레이션하지 않아도 됨 (하위호환)
2. 신규 작업 3문서만 `tasks/` 하위에 생성하면 되므로 도입 비용 최소
3. 로키 동의: 물리적 분리가 핵심이며, 최상위 vs 하위 분기는 운영 편의 문제
4. 라다 동의: 대시보드에서 `memory/plans/tasks/` prefix로 필터링 가능

---

#### 쟁점 2: YAML frontmatter 필드명

- **로키 제안**: `doc_class: system | task` + `sensitivity` + `retention`
- **마아트 제안**: `scope: system | task`
- **논점**: 필드명을 `doc_class`로 할지 `scope`로 할지, 추가 필드 범위

**합의**: `scope: system | task` 채택 + 향후 확장 필드 정의.
```yaml
---
task_id: task-XX.X
type: plan | context | checklist    # 기존 유지
scope: system | task                # 신규 필수 필드
project: (프로젝트 ID 또는 null)
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft | approved | in-progress | done
---
```

**사유**:
1. `scope`가 기존 3docs-schema.md의 네이밍 컨벤션(`type`, `status` 등 단일 영단어)과 일관됨
2. `doc_class`는 2단어 합성이라 기존 패턴과 불일치
3. `sensitivity`와 `retention`은 v2.0에서 추가 (현 단계에서는 과도한 복잡성)
4. 로키 동의 (조건부): security 레벨 작업에서만 `sensitivity` 필드를 선택 추가하는 것으로 합의

---

#### 쟁점 3: 워크플로우 삽입 위치

- **라다/모코시 제안**: Step 2.3 (작업 분해 후, 마이크로태스크 분해 전)
- **스바로그 제안**: Step 3.5 (실행 완료 후, .done 생성 전)
- **논점**: 3문서 작성 시점이 설계 단계인가, 완료 검증 단계인가

**합의**: 2단계 접근 — **초기화는 Step 2.3, 완성 검증은 Step 4 내 qc_verify.py 게이트**

```
Step 2.3: [3문서 초기화] (Lv.3+ 작업에만 적용)
  - dispatch.py가 자동 생성한 템플릿 확인
  - plan.md 초안 작성 (목표, 범위, 위임 계획)
  - context-notes.md 핵심 결정사항 기록 시작
  - checklist.md Phase별 항목 생성

Step 6 (QC 자동 검증): qc_verify.py --gate 실행 시
  - three_docs_check verifier가 3문서 완성도 검증
  - FAIL 시 .done 생성 불가
```

**사유**:
1. 3문서는 설계 단계에서 초기화되고, 작업 진행 중 점진적으로 채워지는 문서
2. 완료 시점에 한 번에 작성하면 형식적 기록이 될 위험 (마아트 지적)
3. 초기화(Step 2.3) + 완성 검증(Step 6 게이트) 2단계가 품질 보장에 효과적 (전원 동의)

---

#### 쟁점 4: 작업명(디렉토리명) 자동 결정 규칙

- **스바로그 제안**: task 파일 title slug화 → task_id fallback
- **논점**: task 파일에 title 필드가 없는 경우가 많음

**합의**: task_id 기반으로 단순화
```
memory/plans/tasks/{task_id}/    ← 예: memory/plans/tasks/task-1872/
```

**사유**:
1. task_id는 항상 존재하고 유일함 (slug 충돌 위험 없음)
2. task 파일에 title 필드가 없는 기존 파일과의 호환성
3. 디렉토리명에서 task_id로 역추적이 즉시 가능

---

## 합의안: 종합 설계서

### A. 문서 체계 설계

#### A-1. 경로 구조
```
memory/plans/
├── <프로젝트명>/               # 시스템 3문서 (기존 유지)
│   ├── plan.md
│   ├── context-notes.md
│   └── checklist.md
└── tasks/                      # 작업 3문서 (신규)
    ├── <task-id>/              # 활성 작업
    │   ├── plan.md
    │   ├── context-notes.md
    │   └── checklist.md
    └── archived/               # 완료 후 아카이브
        └── <task-id>/
```

#### A-2. YAML frontmatter (작업 3문서)
```yaml
---
task_id: task-1872
type: plan                    # plan | context | checklist
scope: task                   # system | task (신규)
project: null                 # 프로젝트 연관 시 지정
created: 2026-04-16
updated: 2026-04-16
status: draft                 # draft | in-progress | done
---
```

#### A-3. 아카이브 규칙
1. 작업 완료(.done 생성) 후, 3문서를 `tasks/archived/{task_id}/`로 이동
2. 이동 시 frontmatter에 `archived_at: YYYY-MM-DD` 필드 자동 추가
3. 아카이브는 자동화 스크립트로 처리 (수동 이동 금지)
4. 보존 기간: 90일 (v2.0에서 `retention` 필드로 커스터마이즈 가능)

#### A-4. 3docs-schema.md 업데이트 범위
1. `scope` 필드 추가 (필수, 허용값: system | task)
2. scope별 필수/선택 필드 매트릭스 추가
3. 작업 3문서 경로 규약 추가 (`memory/plans/tasks/{task_id}/`)
4. 아카이브 규약 추가

---

### B. 코드 실행단 설계

#### B-1. dispatch.py 변경

**함수**: `_create_task_docs(task_id: str, level: int) -> Optional[Path]`
**삽입 위치**: `delegate_to_team()` 함수 내, cokacdir 호출 직전
**조건**: `level >= 3`일 때만 실행
**동작**:
1. `memory/plans/tasks/{task_id}/` 디렉토리 생성
2. plan.md, context-notes.md, checklist.md 템플릿 배치
3. YAML frontmatter 자동 채움 (task_id, type, scope=task, created, status=draft)
4. 이미 존재하면 스킵 (덮어쓰기 금지)

**보안** (로키 합의):
- task_id를 `^task-\d+(\.\d+)?$` 정규식으로 검증
- `os.path.realpath()`로 path traversal 방어
- 디렉토리 권한 `0o755`

**템플릿 파일 위치**: `prompts/templates/task-docs/` (신규 디렉토리)
```
prompts/templates/task-docs/
├── plan.template.md
├── context-notes.template.md
└── checklist.template.md
```

**예상 변경**: dispatch.py +45 라인, 템플릿 파일 3개 신규

#### B-2. team_prompts.py 변경

**삽입 위치**: 프롬프트 `## 워크플로우` 섹션 직전
**조건**: `level >= 3`이고 `memory/plans/tasks/{task_id}/` 존재 시
**삽입 내용**:
```
## 작업 3문서 (Lv.3+ 필수)
경로: memory/plans/tasks/{task_id}/
- plan.md: 목표/범위/위임 계획/검증 기준 → Step 2.3에서 초안 작성
- context-notes.md: 결정 근거/참조 자료/주의사항 → 작업 중 점진적 기록
- checklist.md: Phase별 체크리스트 → 모든 항목 [x] 완료 후 작업 종료

★ 3문서 미완성 시 .done 생성 불가 (qc_verify.py 게이트)
```

**예상 변경**: team_prompts.py +20 라인

#### B-3. DIRECT-WORKFLOW.md 변경

**Step 2.3 삽입** (Step 2와 Step 2.5 사이):
```markdown
2.3. **[작업 3문서 초기화]** (Lv.3+ 작업에만 적용, Lv.1-2는 스킵)
   - dispatch.py가 자동 생성한 `memory/plans/tasks/{task_id}/` 확인
   - plan.md 초안 작성: 목표, 범위, 위임 계획, 검증 기준
   - context-notes.md: 핵심 결정사항 기록 시작 (리서치 결과, 아키텍처 선택 등)
   - checklist.md: Phase별 항목 생성 (최소 3개 Phase + 검증 섹션)
   - 3문서는 작업 진행 중 점진적으로 업데이트 (최종 완성은 Step 6 검증 시)
```

**예상 변경**: DIRECT-WORKFLOW.md +12 라인

#### B-4. qc_verify.py — three_docs_check verifier 추가

**파일**: 각 팀 `qc/verifiers/three_docs_check.py` (공통 모듈화 가능)
**등록**: `qc_verify.py`의 `ALL_CHECKS`에 추가, `level >= 3`일 때 `MANDATORY_CHECKS`에 추가

**FAIL 조건**:
| # | 조건 | FAIL |
|---|------|------|
| TD-1 | plan.md / context-notes.md / checklist.md 중 하나라도 미존재 | FAIL |
| TD-2 | YAML frontmatter 없거나 필수 필드(task_id, type, scope, status) 누락 | FAIL |
| TD-3 | `type` 값이 허용값 외 | FAIL |
| TD-4 | `scope: task`인데 checklist.md에 `- [ ]` 잔존 (미완료 항목) | FAIL |
| TD-5 | 3문서 중 0바이트 파일 존재 | FAIL |

**WARN 조건**:
| # | 조건 | WARN |
|---|------|------|
| TD-W1 | `status: draft`인 채 완료 시도 | WARN |
| TD-W2 | `updated` 날짜가 30일 이상 과거 | WARN |
| TD-W3 | 3문서 간 `task_id` 불일치 | WARN |

**TRUST 5 매핑**: `T`rackable 차원에 포함

**예상 변경**: three_docs_check.py 신규 ~80 라인, qc_verify.py +15 라인

#### B-5. verification-before-completion 변경

**추가 검증 항목**:
1. `memory/plans/tasks/{task_id}/` 디렉토리 존재 확인
2. 3개 파일 존재 확인
3. checklist.md 전체 `[x]` 확인 (정규식 `r'- \[ \]'` 패턴 없음 검증)
4. YAML frontmatter 필수 필드 유효성

**예상 변경**: +25 라인

#### B-6. nuclear-approval 변경

**기존 검증**:
- 3문서 파일 경로 존재 여부
- YAML frontmatter 유효성
- 계획서 근거 인용 여부

**추가 검증** (작업 3문서, `scope: task`):
- 경로가 `memory/plans/tasks/{task_id}/`인지 확인
- checklist.md 전체 `[x]` 확인
- `status`가 `done`인지 확인

**예상 변경**: +10 라인

---

### C. 전체 변경 범위 요약

| 파일 | 변경 유형 | 예상 라인 |
|------|----------|----------|
| `dispatch.py` | 수정 (함수 추가) | +45 |
| `prompts/team_prompts.py` | 수정 (섹션 삽입) | +20 |
| `prompts/DIRECT-WORKFLOW.md` | 수정 (Step 2.3 삽입) | +12 |
| `prompts/templates/task-docs/plan.template.md` | 신규 | ~30 |
| `prompts/templates/task-docs/context-notes.template.md` | 신규 | ~25 |
| `prompts/templates/task-docs/checklist.template.md` | 신규 | ~20 |
| `teams/*/qc/verifiers/three_docs_check.py` | 신규 | ~80 |
| `teams/*/qc/qc_verify.py` | 수정 (verifier 등록) | +15 |
| `memory/specs/3docs-schema.md` | 수정 (scope 필드, 경로 추가) | +40 |
| verification-before-completion 스킬 | 수정 | +25 |
| nuclear-approval 스킬 | 수정 | +10 |
| `prompts/gate_instructions.py` | 수정 (3문서 경로 참조) | +5 |
| **합계** | | **~327 라인** |

### D. 구현 순서 (권장)

1. **Phase 1**: 3docs-schema.md 업데이트 (스키마 확정 선행 필수)
2. **Phase 2**: 템플릿 파일 생성 + dispatch.py 자동 생성 로직
3. **Phase 3**: team_prompts.py 삽입 + DIRECT-WORKFLOW.md Step 2.3
4. **Phase 4**: three_docs_check verifier + qc_verify.py 등록
5. **Phase 5**: verification-before-completion + nuclear-approval 연동
6. **Phase 6**: 테스트 (벨레스 테스트 매트릭스 기준) + 통합 검증

### E. 테스트 계획 (벨레스 합의)

| 테스트 카테고리 | 케이스 수 | 우선순위 |
|----------------|----------|---------|
| dispatch.py 디렉토리 생성 | 3 (신규/중복/에러) | P1 |
| team_prompts.py 경로 삽입 | 2 (Lv3+/Lv2) | P1 |
| three_docs_check FAIL 조건 | 5 (TD-1~TD-5) | P1 |
| three_docs_check WARN 조건 | 3 (TD-W1~W3) | P2 |
| 엣지케이스 (깨진 YAML 등) | 5 | P2 |
| 아카이브 이동 | 2 | P3 |

---

## 합의 서명

- [x] 페룬 (팀장/진행) — 전체 합의안 승인
- [x] 스바로그 (백엔드) — 코드 실행단 설계 동의
- [x] 라다 (프론트엔드) — 대시보드 연동 방안 동의
- [x] 모코시 (UX/UI) — 워크플로우 삽입 위치 동의
- [x] 벨레스 (테스터) — 테스트 계획 동의
- [x] 로키 (DA/보안) — 보안 고려사항 반영 확인 (sensitivity는 v2.0 이연 동의)
- [x] 마아트 (QC) — 검증 체계 설계 동의

**합의 상태**: 전원동의 (사이클 2에서 달성)

---

## ★ 주의: 이 미팅은 설계만 합의. 코드 수정은 별도 태스크로 진행.