# 프로젝트 구조맵 Incremental 업데이트 시스템 — 에이전트 미팅 기록

## 미팅 참석자
- 토르 (백엔드 엔지니어)
- 프레이야 (프론트엔드 엔지니어)
- 발두르 (DevOps 엔지니어)
- 헤임달 (QA 엔지니어)
- 티르 (보안 엔지니어)

---

## Round 1: 요구사항 정의 + 검토사항 논의

### 합의 사항

**1. 구조맵 포맷: Markdown 유지 + JSON 내부 캐시**
- 프레이야: Markdown 유지 강력 주장. AI 에이전트(Claude Code)가 주 소비자이므로 자연어 포맷이 토큰 효율적
- 토르: JSON 이중 구조 제안 (JSON 데이터 + Markdown 렌더링)
- **합의**: 내부 데이터는 JSON으로 관리 (incremental patch 용이), 최종 출력은 Markdown으로 렌더링. JSON은 `.project-map-cache.json`, Markdown은 `{project_id}.md`

**2. 동시성 제어: fcntl flock**
- 토르/발두르 일치: 로컬 파일 시스템이므로 fcntl 기반 exclusive lock 충분
- 토르 추가: version 필드로 Optimistic Locking
- 발두르: lock timeout + 실패 시 재시도 상한
- **합의**: fcntl.LOCK_EX + version 기반 optimistic locking + 30초 timeout

**3. Incremental 알고리즘**
- 변경 파일 목록 수신 → 해당 파일만 재파싱 → JSON 노드 교체 → Markdown 재렌더링
- 프레이야: 섹션 헤더 기반 splice 업데이트 (변경된 섹션만)
- **합의**: 파일 hash 기반 diff → 변경 파일의 관련 섹션만 재생성

**4. 파일 삭제 감지**
- 토르: soft delete (7일 유예 후 정리)
- 헤임달: 즉시 삭제 + 검증 단계
- **합의**: 즉시 삭제 (구조맵은 참조용이므로 유예 불필요). 24시간 full scan이 정규화 역할

**5. 롤백**
- 토르: 증분 스냅샷 (최근 10버전 gzip 보관)
- 발두르: .bak 직전 버전만 유지 (단순)
- **합의**: 업데이트 전 직전 버전 .bak 자동 백업 + 24시간 full scan이 최종 정규화

**6. 구글드라이브 연동**
- 토르: 별도 네임스페이스로 격리
- **합의**: Phase 1에서는 로컬 파일만 처리. Drive 연동은 향후 확장으로 분리

**7. 보안**
- 티르: 경로 조작 방지 (realpath + prefix 검증), 민감 파일 제외 패턴 하드코딩
- **합의**: validate_path() 필수, 기존 EXCLUDE 패턴에 .env, .pem, credentials 추가

**8. 테스트 전략**
- 헤임달: Shadow Comparison (incremental 결과 vs full scan 결과 비교)
- **합의**: 테스트에 shadow comparison 포함

**9. 트리거 방식**
- 발두르: dispatch 보고서 생성 후 hook으로 비동기 호출
- **합의**: CLI `--incremental` 모드 추가. 보고서의 파일 목록을 인자로 전달

**10. 전체 재스캔과 공존**
- 발두르: incremental은 빠른 근사치, full scan이 source of truth
- **합의**: 24시간 full scan 유지 + incremental 보조

---

## Round 2: 아키텍처 설계 + 동시성/무결성 해결 방안

### 아키텍처 설계

**데이터 구조 (JSON 내부 캐시)**
```json
{
  "version": 1,
  "generated_at": "2026-03-03T15:00:00",
  "project_name": "insuwiki",
  "project_path": "/home/jay/projects/insuwiki",
  "sections": {
    "tree": { "content": "...", "updated_at": "..." },
    "types": {
      "files": {
        "src/types/firestore.ts": {
          "hash": "sha256:...",
          "items": ["UserRole", "User", "Document"],
          "updated_at": "..."
        }
      }
    },
    "routes": {
      "files": {
        "src/app/api/ai/query/route.ts": {
          "hash": "sha256:...",
          "methods": ["POST"],
          "url": "/api/ai/query",
          "updated_at": "..."
        }
      }
    },
    "components": {
      "files": {
        "src/components/SearchModal.tsx": {
          "hash": "sha256:...",
          "name": "SearchModal",
          "updated_at": "..."
        }
      }
    },
    "config": { "packages": [...], "tsconfig": [...] },
    "recent_files": [...]
  }
}
```

**CLI 인터페이스 확장**
```bash
# 기존 full scan (변경 없음)
python3 project-map.py /path/to/project --output /path/to/output.md

# incremental 모드 (신규)
python3 project-map.py /path/to/project --output /path/to/output.md \
  --incremental --changed-files "src/api/route.ts,src/components/Button.tsx" \
  --deleted-files "src/old-file.ts"
```

**업데이트 흐름**
1. Lock 획득 (fcntl.LOCK_EX, timeout 30s)
2. JSON 캐시 읽기 → version 확인
3. 변경 파일 각각: hash 비교 → 변경된 것만 재파싱
4. 삭제 파일: JSON에서 해당 노드 제거
5. Directory Tree 재생성 (경량)
6. Markdown 재렌더링
7. .bak 백업 → JSON 캐시 저장 → Markdown 저장
8. Lock 해제

**동시성 안전장치**
- fcntl.LOCK_EX: 단일 writer 보장
- atomic write: temp 파일 작성 → os.rename()
- version increment: 매 업데이트 시 +1

**보안 레이어**
- validate_path(): realpath + prefix 검증
- 파일명 화이트리스트: `^[\w\-./]+$`
- 민감 파일 deny 패턴 사후 검증

---

## Round 3: 최종 합의 + 구현 계획 확정

### 최종 합의 항목

1. **포맷**: JSON 캐시 (`.project-map-cache.json`) + Markdown 출력 (`{id}.md`) 이중 구조
2. **동시성**: fcntl flock + atomic write + version counter
3. **CLI**: `--incremental`, `--changed-files`, `--deleted-files` 플래그 추가
4. **트리거**: dispatch 완료 시 스크립트 직접 호출 (fire-and-forget)
5. **전체 스캔**: 기존 모드 유지, incremental과 공존
6. **롤백**: .bak 직전 버전 백업 (단순, 효과적)
7. **보안**: 경로 검증 + 민감 파일 제외 + 파일명 검증
8. **테스트**: shadow comparison + 엣지 케이스 커버
9. **Drive 연동**: 향후 과제로 분리

### 구현 계획

**Phase 3-A: project-map.py 확장**
- IncrementalUpdater 클래스 추가
- JSON 캐시 read/write with locking
- hash 기반 diff
- Markdown 렌더링 from JSON cache
- CLI argument 확장

**Phase 3-B: 테스트 작성**
- unit test: 각 함수별
- integration test: incremental vs full scan shadow comparison
- edge case test: 파일 삭제, 동시 업데이트, 경로 조작 방지

**Phase 3-C: 검증**
- insuwiki 구조맵으로 실제 동작 검증
- 기존 full scan 결과와 incremental 결과 비교