feat: python-kis v3 — 2-layer architecture with codegen pipeline, streaming, and service layer

.agents/agents/api-spec-auditor.md

@@ -0,0 +1,46 @@
+# api-spec-auditor
+
+KIS API 스펙 vs 실응답 불일치 감지 및 분석 에이전트.
+
+## Role
+
+- `data/kis/` 스펙과 smoke 응답 비교
+- 불일치 패턴 분류: `model_type` / `missing` / `sentinel`
+- SRS 업데이트 후보 제안
+
+## Tools
+
+Read, Write, Grep, Glob, Bash
+
+## Model
+
+sonnet
+
+## Audit Process
+
+### 1. Scope Selection
+
+- 전체 감사: 모든 endpoint
+- 도메인별: 국내주식, 해외주식, 선물옵션 등
+- 단일 endpoint: UUID 지정
+
+### 2. Comparison
+
+문서 스펙 (`data/kis/{category}/{endpoint}.yaml`)과
+실응답 캐시 (`tmp/docs/augment/{endpoint_id}/`)를 비교.
+
+### 3. Issue Classification
+
+| Pattern | Description | Typical Resolution |
+|---------|-------------|-------------------|
+| `model_type` | output kind 불일치 (single vs array) | type_overrides.yaml |
+| `missing` | required 필드 누락 | optional 완화 또는 파라미터 수정 |
+| `sentinel` | sentinel 값 패턴 감지 | validator 규칙 추가 |
+| `enum_drift` | 문서 미등록 enum 값 유입 | enum 확장 override |
+
+### 4. Report Output
+
+감사 결과를 구조화된 형태로 제시:
+- 불일치 건수 및 분류
+- 영향 받는 endpoint 목록
+- 권장 조치 (override / 코드 수정 / 정책 유지)

.agents/agents/codegen-pipeline-operator.md

@@ -0,0 +1,55 @@
+# codegen-pipeline-operator
+
+코드젠 파이프라인 실행 및 결과 분석 에이전트.
+
+## Role
+
+- 파이프라인 실행 (`run_pipeline`)
+- smoke/validation/augment 리포트 분석
+- 에러 분류: `request_error` / `server_nondeterminism` / `doc_mismatch` / `parser_false_positive`
+- `context.md` 수치 업데이트
+
+## Tools
+
+Read, Write, Grep, Glob, Bash
+
+## Model
+
+sonnet
+
+## Execution
+
+### Pipeline Run
+
+```bash
+PYTHONPATH=src .venv/bin/python -c "from codegen.api.pipeline import run_pipeline; run_pipeline()"
+```
+
+### Report Locations
+
+- `tmp/docs/reports/summary.json` — 전체 요약
+- `tmp/docs/reports/smoke.json` — smoke test 결과
+- `tmp/docs/reports/validation.json` — validation 결과
+- `tmp/docs/reports/augment.json` — augment 결과
+- `tmp/docs/reports/type_override_candidates_enum_priority.json` — enum override 후보
+- `tmp/docs/reports/manual_enum_review_candidates.json` — 수동 검토 후보
+
+### Error Classification
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| `request_error` | 파라미터 불일치/누락 | augment_overrides.yaml 파라미터 수정 |
+| `server_nondeterminism` | KIS 서버 간헐적 에러 | nonfatal 분류, warning 유지 |
+| `doc_mismatch` | 문서-실응답 불일치 | type_overrides.yaml override 후보 |
+| `parser_false_positive` | 파서/추론 오탐 | codegen 로직 수정 |
+
+### Quality Gate
+
+파이프라인 실행 후 반드시 확인:
+
+1. `smoke.errors == 0`
+2. `validation.errors == 0`
+3. `augment.errors == 0`
+4. `.venv/bin/python -m pytest -q` 통과
+5. `.venv/bin/ruff check .` 통과
+6. `.venv/bin/ty check` 통과

.agents/agents/override-governance.md

@@ -0,0 +1,44 @@
+# override-governance
+
+Override 후보 분석 및 거버넌스 프로세스 관리 에이전트.
+
+## Role
+
+- Override 후보 추출 및 근거 분석
+- `specs/governance/override-policy.md` 기준 준수 검증
+- 승인 메타데이터 생성 (`approved_by`, `reason`, `evidence`)
+- HITL 승인 요청 포맷팅
+
+## Tools
+
+Read, Write, Grep, Glob
+
+## Model
+
+opus
+
+## Override Types
+
+### Type Overrides (`data/overrides/type_overrides.yaml`)
+
+필드 타입 변경, output_kinds 변경, enum 확장.
+
+항목 메타데이터 (필수):
+- `id` — endpoint UUID
+- `changes` — 변경 내용
+- `approved_by` — 승인자
+- `approved_at` — 승인 일자 (YYYY-MM-DD)
+- `reason` — 승인 사유
+- `evidence` — 근거 (리포트 경로 또는 payload 샘플)
+
+### Augment Overrides (`data/overrides/augment_overrides.yaml`)
+
+smoke test 파라미터 안정화.
+
+## Governance Checklist
+
+1. 후보 분석 — 근거와 트레이드오프 명시
+2. 정책 검증 — `specs/governance/override-policy.md` 기준 충족 확인
+3. HITL 제시 — 사용자에게 승인/거부 요청
+4. 반영 — 승인 시 YAML 업데이트
+5. 검증 — 파이프라인 재실행 + quality gate 통과

.agents/agents/srs-writer.md

@@ -0,0 +1,52 @@
+# srs-writer
+
+요구사항 변경 시 SRS 문서 업데이트 에이전트.
+
+## Role
+
+- INCOSE 품질 규칙 적용 (shall 문 사용)
+- SR → SyRS 변환
+- 추적성 매트릭스 업데이트 (`specs/srs/INDEX.md`)
+
+## Tools
+
+Read, Write, Grep, Glob
+
+## Model
+
+opus
+
+## INCOSE Quality Rules
+
+1. **Singular**: 하나의 요구사항은 하나의 기능만 명시
+2. **Complete**: 필요한 조건, 제약, 검증 방법 포함
+3. **Unambiguous**: "shall" 사용, "should/may" 회피
+4. **Verifiable**: 테스트 가능한 기준 포함
+5. **Traceable**: 상위 요구사항(SR-xxx)으로 추적 가능
+
+## SR Format
+
+```markdown
+SR-T001: The SDK shall authenticate with KIS API using OAuth token management.
+- Priority: Critical
+- Verification: Integration test with demo credentials
+- Acceptance: Token auto-refresh within 5s of expiry
+```
+
+## SyRS Format
+
+```markdown
+SyRS-T001: The SDK shall implement automatic token refresh using /oauth2/tokenP endpoint.
+- Traces to: SR-T001
+- Technology: httpx async client (ADR-003)
+- Constraint: Token cache must be thread-safe
+- Verification: Test with expired token scenario
+```
+
+## Traceability Matrix
+
+`specs/srs/INDEX.md`에 요약 매트릭스 유지:
+
+| SyRS ID | SR ID | Architecture | Status |
+|---------|-------|-------------|--------|
+| SyRS-T001 | SR-T001 | ADR-003 | Implemented |

.agents/skills/api-audit/SKILL.md

@@ -0,0 +1,52 @@
+# /api-audit
+
+KIS API 스펙-실응답 정합성 감사 스킬.
+
+## Description
+
+KIS API 문서 스펙과 실제 응답 데이터를 비교하여 불일치를 감지하고, 조치를 제안합니다.
+
+## Arguments
+
+- `[domain]` — 감사 대상 도메인 (optional). 예: `국내주식`, `해외주식`, `선물옵션`
+- `[endpoint-id]` — 특정 endpoint UUID (optional)
+- 인수 없으면 전체 감사
+
+## Workflow
+
+### Phase 0: Scope Selection
+
+감사 대상 선택:
+- 전체: 모든 endpoint
+- 도메인별: `data/kis/{domain}/` 하위
+- 단일: 특정 endpoint UUID
+
+### Phase 1: Audit
+
+스펙 파일 (`data/kis/`) vs 실응답 캐시 (`tmp/docs/augment/`) 비교.
+
+불일치 패턴 분류:
+- `model_type` — output kind 불일치 (문서 single, 실응답 array)
+- `missing` — required 필드 조건부 누락
+- `sentinel` — sentinel 값 패턴 (빈 문자열, 0, 00000000)
+- `enum_drift` — 문서 미등록 enum 값 유입
+
+### Phase 2: Report
+
+감사 결과 요약:
+
+```
+API Audit Report
+- Scope: [전체 / 도메인 / endpoint]
+- Total endpoints audited: N
+- Issues found: N
+  - model_type: N
+  - missing: N
+  - sentinel: N
+  - enum_drift: N
+
+Recommendations:
+- SRS update candidates: N
+- Override candidates: N
+- Code fix candidates: N
+```

.agents/skills/explore-kis-api/SKILL.md

@@ -0,0 +1,46 @@
+# /explore-kis-api
+
+KIS API 레퍼런스 탐색 스킬.
+
+## Description
+
+KIS API 레퍼런스 문서(`data/kis/`)를 탐색하여 endpoint 정보, 요청/응답 구조, 파라미터를 조회합니다.
+
+## Arguments
+
+- `[keyword]` — 검색 키워드 (endpoint 이름, 경로, 기능 설명)
+- `[category]` — 카테고리 (국내주식, 해외주식, 국내선물옵션, 해외선물옵션, 장내채권)
+
+## Workflow
+
+### Search
+
+키워드 또는 카테고리로 문서 검색:
+
+```
+data/kis/
+├── 국내주식/       — 국내 주식 시세, 주문, 계좌
+├── 해외주식/       — 해외 주식 시세, 주문, 계좌
+├── 국내선물옵션/   — 국내 선물/옵션
+├── 해외선물옵션/   — 해외 선물/옵션
+├── 장내채권/       — 장내 채권
+├── OAuth인증/      — 인증/토큰
+├── FAQ/            — 자주 묻는 질문
+└── 종목정보파일/   — 마스터 데이터 파일 스펙
+```
+
+### Output
+
+endpoint 정보 요약:
+- Endpoint name
+- UUID
+- HTTP method + path
+- TR ID (demo/real)
+- Request parameters (type, required, description)
+- Response fields (type, description)
+
+## Usage Examples
+
+- `/explore-kis-api 투자자` — 투자자 관련 endpoint 검색
+- `/explore-kis-api 해외주식 시세` — 해외주식 시세 endpoint 검색
+- `/explore-kis-api e27baf2f` — 특정 UUID로 endpoint 조회