diff --git a/docs/v04/README.md b/docs/v04/README.md deleted file mode 100644 index e06efe7..0000000 --- a/docs/v04/README.md +++ /dev/null @@ -1,143 +0,0 @@ -# Rune v0.4.0 — Go 전환 설계 문서 - -2026-04 기준 Python MCP → Go MCP 포팅 설계 문서. Python 코드베이스(`mcp/`, `agents/`)를 기반으로 Go 구현을 위한 계약·결정·흐름을 정리한다. - -**이 디렉토리가 단일 진실 소스**. 이전 `docs/migration/` · `docs/runed/` 문서는 히스토리·배경 자료로만 참조. - -## 핵심 아키텍처 - -Python의 "세션당 MCP 프로세스에 embedding model까지 포함" 구조가 갖는 **모델 메모리 중복 문제**만 제거하고 나머지는 Python 구조에 가깝게 유지: - -- **`rune-mcp`** (이 프로젝트): 세션당 1개. stdio JSON-RPC. Python MCP를 Go로 포팅 (임베딩 제외) -- **`embedder`** (별도 프로세스, 가칭): 머신당 1개 상주. 임베딩 모델 전담. gRPC over unix socket -- **Vault · envector**: 각 MCP가 독립적으로 gRPC 연결 - -`embedder`는 외부 컴포넌트. rune-mcp는 **gRPC 클라이언트로만** 사용. - -> **네이밍 히스토리**: 초기 설계에서 "runed" (Python MCP 대체 + 임베딩 내장 통합 데몬)을 구상했으나 폐기. 현재는 **rune-mcp (Go 포팅) + embedder (임베딩 별도)** 구조. - -## 디렉토리 구조 - -``` -docs/v04/ -├── README.md # 이 파일 (index · role별 reading order) -│ -├── overview/ # 사람용 — Why & What -│ ├── architecture.md # 3-프로세스 구조 · 메모리 모델 · 원칙 · 상태머신 -│ ├── decisions.md # D1-D30 결정 트래커 (배경·선택지·근거·재평가) -│ └── open-questions.md # Q1-Q9 미결 사항 -│ -├── spec/ # 개발자용 — How (구현 계약) -│ ├── types.md # 🔑 DecisionRecord v2.1 · 8 enum · I/O schemas (단일 진실 소스) -│ ├── flows/ # Phase 단위 end-to-end 로직 + Go pseudocode -│ │ ├── capture.md # 7-phase capture -│ │ ├── recall.md # 7-phase recall -│ │ └── lifecycle.md # 6 tool (vault_status · diagnostics · batch_capture · …) -│ ├── components/ # 컴포넌트 계약 · 패키지 구조 · gRPC client 구현 -│ │ ├── rune-mcp.md # 세션별 MCP 바이너리 (메인) -│ │ ├── embedder.md # 외부 embedder gRPC 클라이언트 -│ │ ├── vault.md # Vault gRPC 클라이언트 -│ │ └── envector.md # envector-go SDK -│ └── python-mapping.md # Python 파일/LoC → Go 구조 매핑 -│ -├── notes/ # 내부 작업 노트 (참고용) -│ ├── verification-matrix.md # Python↔Go bit-identical 대조 검증 로그 -│ ├── implementability-report.md # Go 개발자 진입 가능성 검증 리포트 -│ └── flow-matrix.md # 10 flow × 파일 매트릭스 + Tier S/A/B 공통 모듈 -│ -└── progress/ # 실제 개발 진행 추적 (vertical slice 단위) - ├── README.md # 인덱스 + 마일스톤별 상태표 - └── phase-a-mcp-boot.md # MCP handshake + tools/list (`19b7bf6`) -``` - -## 읽는 순서 - -### 🧑‍💼 **처음 보는 사람 / 리뷰어** (overview만 읽어도 충분) - -1. 이 README → 전체 요약 -2. `overview/architecture.md` → 왜·무엇을·어떻게 (narrative) -3. `overview/decisions.md` → 결정 히스토리·대안 근거 -4. `overview/open-questions.md` → 아직 결정 안 된 것들 - -### 👨‍💻 **Go로 구현할 개발자** - -**새 개발자라면 먼저 [`onboarding.md`](onboarding.md)** — 10분 안에 첫 PR 위치까지 안내 (환경 셋업 · 읽기 순서 · Phase별 starter task · 컨벤션 · FAQ). - -그 다음 (필요 시점에): - -1. `overview/architecture.md` → 맥락 + **§Scope** (agent-delegated only 전제가 프로젝트 전반을 좌우) -2. [`../../internal/README.md`](../../internal/README.md) → 패키지 지도 (Go 파일 ↔ spec ↔ Python 원본 매핑표) -3. `spec/types.md` → 모든 도메인 타입·enum·I/O schema (항상 옆에 두기) -4. `spec/python-mapping.md` → Python 파일 → Go 패키지 LoC 매핑 -5. `spec/flows/{capture,recall,lifecycle}.md` → 담당 Phase에 해당하는 7-phase 흐름 -6. `spec/components/*.md` → 각 컴포넌트 gRPC 계약·패키지 구조 -7. 헷갈리면 `overview/decisions.md` D_N 참조 (spec 문서들이 D_N으로 link) - -### 🔍 **검증 상태 확인하고 싶은 사람** - -- `notes/verification-matrix.md` — 28 상수 · Phase 순서 · 함수 라인 전수 대조 결과 -- `notes/implementability-report.md` — "docs만으로 Go 구현 가능한가" 검증 - -## overview vs spec vs notes - -| 유형 | 누가 읽나 | 성격 | -|---|---|---| -| **overview/** | PM, 아키텍트, 신규 참여자 | narrative prose, "왜"에 집중, 결정 히스토리 | -| **spec/** | Go 개발자 | 구체 인터페이스·pseudocode·상수·에러 매핑, "어떻게"에 집중 | -| **notes/** | 작성자·검증자 | 작업 중 발견·검증 로그, 참고용 | - -**`overview/decisions.md` vs `overview/open-questions.md` 구분**: -- `decisions.md` — 모든 결정 트래커 (가벼운 구현 선택부터 중대 결정까지). 상태 마커 (Blocking/Pending/Deferred/Decided/Archived)로 무게 구분 -- `open-questions.md` — 아직 "결정 후보"로 정리 안 된 조사 중 항목 - -## 상태 (2026-04-22) - -| 영역 | 상태 | -|---|---| -| 아키텍처 방향 | ✅ 결정됨 (세션별 rune-mcp + 외부 embedder) | -| rune-mcp 설계 (7-phase) | 🟢 완료 (`spec/flows/*.md`) | -| embedder gRPC 통합 | ✅ 확정 (D30) | -| Vault 연동 | ✅ 기존 Python 구조 유지 | -| envector 연동 | 🟡 SDK 조건 완화 PR 대기 (Q4) | -| AES-MAC envelope | 🔵 Deferred Post-MVP (Q1) | -| Python↔Go 대조 검증 | ✅ 완료 (`notes/verification-matrix.md`) | -| Go 구현 진입 가능성 | 🟢 Ready (`notes/implementability-report.md`, P0 blocker 0건) | -| Go skeleton | ✅ 완료 (`2eb167d`, 37 파일, stdlib-only compile) | -| 개발자 onboarding 가이드 | ✅ 완료 (`onboarding.md` · `internal/README.md`) | - -## 구현 로드맵 - -Skeleton(`2eb167d`) 이후 단계. 각 Phase는 **별도 PR** 단위이며, 이전 Phase가 완료되기 전에 다음 Phase로 진입하지 않는다 (하위 → 상위 build-order 존중). - -| Phase | 범위 | 비고 | -|---|---|---| -| 1 | 외부 의존성 추가 | `modelcontextprotocol/go-sdk` v1.5+, `google.golang.org/grpc`, `google.golang.org/protobuf`, envector-go SDK(Q4 PR 머지 후 연결), embedder proto stub import | -| 2 | `internal/domain/` + `internal/policy/` 순수 로직 | `ParseDomain` 19-enum map + `customer_escalation` alias · 상수·regex 이식 (81 stopwords · 31 intent · 16 time · 4 tech) · `GenerateRecordID` unicode slug · `ClassifyNovelty` · `ApplyRecencyWeighting` · `FilterByTime` · golden fixture 테스트 harness | -| 3 | `record_builder` (703 LoC) + `payload_text` (364 LoC) 라인 단위 포팅 | D13 Option A · D15 canonical. 5 SENSITIVE + 4 QUOTE + 5 RATIONALE regex, `_parse_domain` 19-map + alias, `ensure_evidence_certainty_consistency` → `render_payload_text` 순서. `testdata/` 50+ 샘플로 byte-identical 검증 (Python 원본이 canonical source) | -| 4 | `internal/adapters/` 실제 클라이언트 | Vault gRPC (3 RPC + keepalive + 256MB msg + TLS + health 2-tier + endpoint 4-form 정규화) · envector SDK + AES envelope Seal/Open (AES-256-CTR, 16B IV) · embedder gRPC + Info `sync.Once` 캐시 + D7 retry · capture_log `flock` append + 역순 `Tail` | -| 5 | `internal/service/` orchestration | 7-phase capture (novelty non-fatal, D17 atomicity probe) · 7-phase recall (D25 순차, D26 Vault 위임 decrypt, D27 phase_chain expansion) · 6 lifecycle tools · Vault/envector 실패 시 `state=dormant` 전환 side-effect | -| 6 | `internal/mcp/` SDK 연결 | 공식 Go SDK로 8 tool 등록 · stdio transport · `Deps` 주입 · adapter error → `domain.RuneError` → MCP response wrap · state-specific recovery hints | -| 7 | 검증 | policy unit (golden fixture byte-identical) · bufconn Vault integration · libevi/mock backend envector contract tests · `synctest` (Go 1.25) boot retry 결정적 테스트 · Python ↔ Go shadow run (cutover 리스크 완화) | - -**우선순위 결정 팁**: -- Phase 2·3 완료 전에는 외부 의존성(Phase 1) 없이도 순수 로직 테스트 가능 → 빠른 confidence 구축 -- ~~Phase 4 envector SDK 조건 완화 PR(Q4) 블로킹~~: ✅ Resolved — SDK가 `WithKeyParts(KeyPartEnc, KeyPartEval)`로 정식 지원 -- Phase 5·6는 adapter interface 확정 후 진입. 미리 시작하면 signature 변경 비용 큼 -- Phase 7 shadow run은 Post-MVP에도 유지 — 장기 품질 보증 수단 - -## 이전 문서와의 관계 - -- 기존 `docs/migration/python-go-comparison.html` — 이전 방향(단일 데몬) 기준. 일부 충돌 -- 기존 `docs/runed/` — 폐기된 "runed" **통합 데몬** 설계. 히스토리 보존 (현재 `runed`는 임베딩 전담 데몬의 정식 이름으로 의미 좁혀져 부활 — `github.com/CryptoLabInc/runed`) -- 이 `docs/v04/`가 권위 있는 설계 문서 - -## 용어 - -- **rune-mcp**: Python MCP를 Go로 포팅한 세션별 바이너리 (임베딩 제외). **본 프로젝트 산출물** -- **embedder**: 임베딩 모델 호스팅 외부 gRPC 프로세스의 **역할명**. rune-mcp는 gRPC 클라이언트로만 사용. 구체 구현은 `runed` (아래) -- **runed**: 임베딩 전담 데몬의 **정식 프로젝트 이름** (`github.com/CryptoLabInc/runed`). gRPC over UDS (`~/.runed/embedding.sock`). ⚠️ 초기 설계의 "통합 데몬" 의미는 폐기, 임베딩 전담 의미로 부활 -- **Vault**: `rune-Vault` gRPC 서비스. FHE 키 관리 + 복호화 (`GetPublicKey`/`DecryptScores`/`DecryptMetadata`) -- **envector**: enVector Cloud. FHE 벡터 저장·검색 (`Insert`/`Score`/`GetMetadata`) -- **agent_dek**: 에이전트별 AES-256 DEK. metadata envelope 암호화용. Vault가 배포, rune-mcp 메모리에만 -- **Vault-delegated 보안 모델**: SecKey는 Vault만 보유. rune-mcp는 EncKey + EvalKey만 로컬. 복호화는 Vault RPC 경유 -- **agent-delegated**: 에이전트(Claude Code 등)가 extraction·판정을 수행하고 rune-mcp는 저장·검색 파이프라인만 담당 (D14/D21/D28) diff --git a/docs/v04/onboarding.md b/docs/v04/onboarding.md deleted file mode 100644 index 47cd0b3..0000000 --- a/docs/v04/onboarding.md +++ /dev/null @@ -1,234 +0,0 @@ -# Onboarding — rune-mcp Go 개발자 진입 가이드 - -**목표**: 이 문서를 10분 읽으면, 어디를 보고 어디를 고쳐야 할지 판단하고 첫 PR 위치까지 도달. - -이 문서는 `docs/v04/`의 모든 세부 문서를 대체하지 않는다. **네비게이션 맵**이다. - ---- - -## 사전 조건 - -- Go 1.24+ (`go version`로 확인) -- Git + 이 repo 접근 권한 -- Python rune 코드베이스에 대한 최소한의 친숙함 (or 의지) — **Python이 canonical source**라 계속 참조 - ---- - -## 10분 루트 - -### 0~3분: 컨텍스트 - -1. **[docs/v04/README.md](README.md)** — 핵심 아키텍처(3-프로세스 모델 rune-mcp / embedder / Vault+envector) + 현재 상태 (1분) -2. **[docs/v04/overview/architecture.md §Scope](overview/architecture.md#scope-sot--agent-delegated-only)** — 가장 중요. **agent-delegated path only**가 프로젝트 전제다. legacy LLM 경로(detector/tier2_filter/llm_extractor/synthesizer/auto-provider) 전부 **scope 밖** (2분) - -### 3~7분: 네비게이션 - -3. **[internal/README.md](../../internal/README.md)** — 패키지 지도. 어느 Go 파일이 어느 spec / Python 원본에 매핑되는지 (2분) -4. **`go build ./...`** — 로컬에서 컴파일 확인 (stdlib-only 상태, 외부 deps 없이 통과) (1분) -5. **[docs/v04/README.md §구현 로드맵](README.md#구현-로드맵)** — 7 Phase 중 본인이 시작할 Phase 선택 (1분) - -### 7~10분: 첫 target 선택 - -6. 아래 [§첫 PR 추천](#첫-pr-추천-phase별-starter-task)에서 작은 task 하나 집기 -7. 해당 파일 열어 TODO 주석 확인 → Python 원본 파일 라인 확인 → 브랜치 생성 - -이 시점에 **어디를 고치면 되는지 명확**해야 한다. 그렇지 않으면 본 가이드의 § 중 놓친 링크가 있는 것. 뒤로 돌아가서 재확인. - ---- - -## 환경 셋업 - -### IDE - -- **VS Code + Go extension** (권장): `gopls` 자동 설치 -- **GoLand**: 상용, 풀 기능 -- 공통: `golangci-lint` 설치 권장 (`brew install golangci-lint` 또는 `go install`) - -### Python 참조용 - -Python rune 코드는 같은 repo 안에 있다 (`./mcp/`, `./agents/`). 별도 checkout 불필요. -- IDE에서 Python 파일을 옆 탭에 열어두고 같이 보는 습관 -- Go 파일 주석에 `Python: file.py:L` 라인 참조가 있음 → 바로 점프 - -### 빌드·검사 명령 - -```bash -go build ./... # 모든 패키지 빌드. Phase 0 baseline -go vet ./... # 표준 정적 분석 -gofmt -l . # 포맷 체크 (출력 없으면 OK) -golangci-lint run # 린터 (설치됐다면) -go test ./... # 테스트 (Phase 2 이후부터 실효성) -``` - ---- - -## 문서 읽기 순서 - -### 반드시 먼저 (진입 순서) - -1. [docs/v04/README.md](README.md) — 아키텍처 · 상태 · 구현 로드맵 -2. [docs/v04/overview/architecture.md §Scope](overview/architecture.md#scope-sot--agent-delegated-only) — **agent-delegated only** 전제 -3. [internal/README.md](../../internal/README.md) — 패키지 지도 - -### Phase 시작 전 (해당 Phase만 읽어도 됨) - -| Phase | 필수 읽기 | -|---|---| -| **2** (domain/policy 구현) | [spec/types.md](spec/types.md) · [decisions.md](overview/decisions.md) D11 / D21 / D22 / D23 | -| **3** (record_builder + payload_text 포팅) | [spec/flows/capture.md](spec/flows/capture.md) Phase 3 canonical section · [decisions.md](overview/decisions.md) D13 / D14 / D15 · `agents/common/schemas/templates.py` (**canonical**) · `agents/scribe/record_builder.py` | -| **4** (adapter 실 클라이언트) | [spec/components/vault.md](spec/components/vault.md) · [envector.md](spec/components/envector.md) · [embedder.md](spec/components/embedder.md) · [decisions.md](overview/decisions.md) D26 / D30 | -| **5** (service orchestration) | [spec/flows/capture.md](spec/flows/capture.md) · [recall.md](spec/flows/recall.md) · [lifecycle.md](spec/flows/lifecycle.md) | -| **6** (MCP SDK 연결) | [spec/components/rune-mcp.md §MCP 서버 구현](spec/components/rune-mcp.md) · [decisions.md](overview/decisions.md) D2 | - -### 필요할 때 참조 (lookup 용도) - -- 결정 근거: [overview/decisions.md](overview/decisions.md) — D1-D32. 왜 이렇게 했는지 의심될 때 -- 미결 사항: [overview/open-questions.md](overview/open-questions.md) — Q1 (AES-MAC) · Q4 (envector-go SDK PR) -- 검증 로그: [notes/verification-matrix.md](notes/verification-matrix.md) · [python-parity-final.md](notes/python-parity-final.md) -- Python 파일 매핑: [spec/python-mapping.md](spec/python-mapping.md) - ---- - -## 첫 PR 추천 (Phase별 starter task) - -**원칙**: 파일 1-2개, 50-150줄 변경, 테스트 포함. 첫 PR로 patterns 익히기. - -### Phase 2 — 가장 쉬움 - -**🟢 추천 A**: `internal/domain/schema.go:ParseDomain` 19-enum map 구현 -- 현재 상태: stub (`return DomainGeneral`) -- Python 참조: `agents/scribe/record_builder.py:L621-655 _parse_domain` (+ L646 `customer_escalation → CUSTOMER_SUCCESS` alias) -- 작업량: ~30줄 Go + 20줄 테이블 테스트 -- 학습 포인트: Python bit-identical 포팅 패턴 첫 체험 - -**🟢 추천 B**: `internal/policy/novelty.go:ClassifyNovelty` 구현 -- 현재 상태: stub (`return NoveltyClassNovel, 1.0`) -- Python 참조: `agents/common/schemas/embedding.py:L33-56 classify_novelty` -- 작업량: ~20줄 + 테이블 테스트 (4 class boundary) -- 학습 포인트: **score inverted** (1.0 - max_sim) + round(4) 주의 - -**🟢 추천 C**: `internal/domain/schema.go:GenerateRecordID` 테스트 추가 -- 현재 상태: **구현 완료** (테스트 없음) -- 테스트 케이스: unicode (한글) · alphanumeric only · empty title · punctuation mixed -- 작업량: ~40줄 테스트 (Python bit-identical 결과와 비교) -- 학습 포인트: `isPyIsalnum` unicode 동작 확인 — Python 결과 golden으로 비교 - -**🟢 추천 D**: `internal/domain/errors.go:MakeError` 구현 -- 현재 상태: stub (`return nil`) -- Python 참조: `mcp/server/errors.py:L93-118 make_error` -- 작업량: ~30줄 + 테스트 -- 학습 포인트: `errors.As` type assertion 패턴 - -### Phase 3 — regex 포팅 입문 - -**🟡 추천**: `internal/policy/pii.go:RedactSensitive` 구현 -- 현재 상태: stub (truncate만 함) -- Python 참조: `agents/scribe/record_builder.py:L89-95` (5 regex) + `L406-418 _redact_sensitive` + `L227 MAX_INPUT_CHARS=12_000` -- 작업량: ~50줄 Go (5 regex 컴파일 + 치환) + golden fixture 테스트 (redact 전후 텍스트 쌍) -- 학습 포인트: `regexp.MustCompile` + `ReplaceAllString` + unicode 고려 - -### Phase 4 — adapter 부분 완성 - -**🟡 추천**: `internal/adapters/vault/endpoint.go:NormalizeEndpoint` 테스트 + 엣지 케이스 -- 현재 상태: **부분 구현** (4 형식 basic 처리) -- Python 참조: `mcp/adapter/vault_client.py:L116-140 _derive_grpc_target` -- 작업량: ~40줄 테스트 (env var override · trailing slash · IPv6 brackets 등) -- 학습 포인트: URL parsing edge case + Python 동작 정확 매칭 - -### 큰 task (Phase 3 본격 진입) - -**🔴 heavy**: `internal/policy/payload_text.go:RenderPayloadText` 전체 포팅 -- Python 참조: `agents/common/schemas/templates.py` (364 LoC, **canonical**) -- 작업량: ~250줄 Go + 50+ golden fixture -- **주의 사항**: phase_line post-insertion + blank line collapse + `_format_alternatives` bug 유지 (bit-identical) — [decisions.md D15 포팅 주의사항](overview/decisions.md) 참조 -- 학습 포인트: 대형 canonical port. 본격 들어가기 전에 팀과 먼저 논의 - ---- - -## 코드 컨벤션 - -### Python bit-identical 원칙 - -- 포팅 대상 함수 위에 `// Python: .py:L-` 형식 주석 (skeleton에 이미 들어가 있음) -- 상수값은 Python 동일 (novelty `0.3/0.7/0.95` · half-life `90일` · title `60자` · `MAX_INPUT_CHARS=12_000` 등) -- 검증은 `testdata/golden/` 의 JSON/MD 파일로 byte-identical 비교 - -### TODO 관리 - -- 스켈레톤의 기존 TODO는 구현 시 **제거** -- 새 TODO 포맷: `// TODO(): <무엇> — <참조>` - - 예: `// TODO(Phase 3): implement _extract_evidence — record_builder.py:L498-531` -- 장기 유보 항목은 TODO 대신 decisions.md에 D_N 항목으로 - -### 테스트 - -- 순수 함수(domain/, policy/)는 Go 표준 `_test.go` + 테이블 테스트 -- Python ↔ Go bit-identical이 필요한 경우 `testdata/golden/` 고정 후 byte-compare -- Python 측 골든 생성 스크립트는 향후 `scripts/gen_golden.py` 추가 예정 (없으면 해당 PR에서 같이 추가) - -### 디렉토리 간 경계 (internal/README.md §패키지 의존 방향 참조) - -- `internal/domain`은 leaf. 다른 `internal/*` 패키지 import 금지 (stdlib만) -- `internal/policy`는 I/O 없음. `adapters/` 호출 금지 -- Adapter error는 service 레이어에서만 `domain.RuneError` 로 wrap - -### 커밋 메시지 - -Conventional Commits 스타일: -- `feat(go): ...` — 새 기능 -- `fix(go): ...` — 버그 수정 -- `test(go): ...` — 테스트만 추가 -- `docs(v04): ...` — 문서 변경 -- `refactor(go): ...` — 동작 변경 없이 구조만 - -본문에 **Python 원본 파일:라인 참조** + **영향 받는 spec 문서** 언급 권장. - -### PR 단위 - -- Phase 단위로 크게 묶지 말고, 하나의 파일 / 하나의 함수 단위로 작게 -- 골든 픽스처 추가/변경은 별도 PR -- `go build ./...` · `go test ./...` · `golangci-lint run` 통과 확인 후 PR - ---- - -## FAQ - -**Q. Python 코드를 꼭 읽어야 하나?** -예. 모든 포팅은 Python이 canonical. Go 주석에 라인 번호 있으니 점프하기 쉬움. 읽지 않고 구현하면 bit-identical 실패 가능성 큼. - -**Q. 결정을 바꾸고 싶다 (예: novelty threshold 조정)** -PR 전에 [decisions.md](overview/decisions.md)에 새 `D` 항목 추가 → 근거 기록 → 리뷰 승인 후 코드 변경. 갑자기 코드에서 상수 바꾸기 금지. - -**Q. 외부 의존성을 직접 추가해도 되나?** -Phase 1이 이 역할. 임의 추가 금지. `go.mod require` 변경은 팀 리뷰 필요. - -**Q. 테스트가 Python과 float 오차로 실패한다** -`math.Floor` 적용 확인 (예: `searcher.py:L291` `(now-ts).days`는 integer truncation. Go에서는 float 연산 후 Floor 필수). 자세한 bit-identical 주의사항은 [recall.md Phase 6](spec/flows/recall.md) 참조. - -**Q. agent-delegated가 아닌 경로를 구현해야 하나?** -아니오. Python에 남아있는 legacy LLM 경로(detector/tier2_filter/llm_extractor/synthesizer/_legacy_standard_capture)는 **Go scope 밖**. 자세한 drop 목록은 [architecture.md §Scope 표](overview/architecture.md#scope-sot--agent-delegated-only). - -**Q. 에이전트가 `extracted.tier2`를 안 보내면?** -D14에 따라 `EXTRACTION_MISSING` 에러. agent-delegated 전제이므로 `pre_extraction` 필수. legacy regex fallback은 포팅 안 함. - -**Q. envector SDK가 아직 없으면 Phase 4를 어떻게 진행?** -Mock backend + stub 구현으로 Phase 4 starting 가능. Q4 envector-go SDK `OpenKeysFromFile` 조건 완화 PR 머지 전까지는 libevi 통합 불가, mock으로만 테스트. [open-questions.md Q4](overview/open-questions.md) 참조. - -**Q. Python과 완전히 같은 동작이 맞는지 어떻게 검증?** -Golden fixture (Python에서 생성한 JSON/MD를 `testdata/golden/`에 고정) + Go 출력과 byte-compare. 대형 포팅(record_builder/payload_text)은 이게 유일한 신뢰 보증 수단. - -**Q. 어디서 막히면?** -1. Python 원본 파일 + 해당 spec 문서를 옆에 놓고 다시 읽기 -2. [open-questions.md](overview/open-questions.md) 확인 — 이미 논의된 미결 사항일 수도 -3. [decisions.md D1-D32](overview/decisions.md) 관련 결정 확인 -4. 그래도 안 풀리면 team channel 질문 - ---- - -## 다음 단계 - -- Phase 선택 후 이 가이드의 §첫 PR 추천 에서 starter 골라서 브랜치 생성 -- 첫 PR 리뷰 후 배운 점 팀 Slack에 공유 (다음 사람 도움) -- 전체 로드맵은 [docs/v04/README.md §구현 로드맵](README.md#구현-로드맵) 에서 추적 - -환영합니다. 🚀