@nomadamas/k-skill 0.9.2 → 0.10.0

package/skills/korean-bond-search/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "korean-bond-search",
+  "description": "GS Quant의 Instrument/Data 구조화 방식에서 영감을 받아 한국 채권을 표준 Bond Instrument 필드로 정리하고, 종목명·발행사·ISIN으로 발행조건·잔액·CALL/PUT·CB/EB/BW를 출처와 함께 검색·비교한다. Use for Korean bond lookup or comparison. Not for live quotes, YTM, credit opinions, or investment advice.",
+  "profiles": [
+    "lookup",
+    "browser"
+  ],
+  "frontmatter": "name: korean-bond-search\ndescription: GS Quant의 Instrument/Data 구조화 방식에서 영감을 받아 한국 채권을 표준 Bond Instrument 필드로 정리하고, 종목명·발행사·ISIN으로 발행조건·잔액·CALL/PUT·CB/EB/BW를 출처와 함께 검색·비교한다. Use for Korean bond lookup or comparison. Not for live quotes, YTM, credit opinions, or investment advice.\nlicense: MIT\nmetadata:\n  category: finance\n  locale: ko-KR\n  phase: v1"
+}

package/skills/market-event-impact/instruction.md

@@ -0,0 +1,150 @@
+# 사건별 시장반응 리서치
+
+## What this skill does
+
+한 사건이 **무엇이었고, 무엇이 달라졌으며, 왜 시장이 움직였는지**를 공식 발표·당시 보도·검증된 시장가격으로 재구성하는 한국어 대화형 리서치 스킬이다. 정례 경제지표와 통화정책 결정뿐 아니라 금융사고·신용등급 변경·관세·지정학 충격처럼 형식이 일정하지 않은 사건도 다룬다. 사건과 자산의 관측시각을 맞추고 금리·외환·주식 등 교차자산 전달경로를 증거등급으로 평가한다. GS Quant의 `event_study`·`event_impact_analysis`·`CalendarAlignment` 구조를 참고한 D-1/D0/D+1/D+5 측정은 서술을 검증하는 **보조 증거**이며 분석의 본체가 아니다. 검증 가능한 과거 유사사례와 해석을 바꿀 다음 촉매를 덧붙인다. 실시간 호가·예측·매매 추천은 다루지 않는다.
+
+## Architecture
+
+`Generic Event Engine + Specialized Adapter` 구조다. FOMC·금통위·ECB·물가·고용·실적은 추가 확인 항목을 제공하는 선택적 adapter일 뿐이다. adapter가 없는 SVB 파산, 신용등급 강등, 관세 발표, 군사충돌, OPEC 감산, 공급차질도 Generic Engine으로 분석한다.
+
+```text
+Event Resolver
+  → verified event name / type / date / time / source
+  → transmission-based asset selection
+  → calendar alignment and event window
+  → cross-asset response and transmission
+  → characteristic-based historical analogues
+  → next catalysts
+  + optional specialized adapter
+```
+
+## 1. Event Resolver
+
+사용자의 자유 문장을 whitelist와 대조하지 않는다. 먼저 사건명, 충격 분야(`event_type`), 진행 형태(`event_structure`), 기준일, 지역, 현지시각, 직접 출처를 구조화한다. `event_type`은 `financial_stress` 같은 분야이며 `point_event|scheduled_event|developing_event`와 혼용하지 않는다. 시간 정밀도는 A(정확 시각+시간대), B(날짜만)로 표시하고, C는 정밀도가 아니라 다일 진행 구조(`developing_event`)로 분리한다. 유형 분류와 입력 계약은 다음을 읽는다.
+
+```bash
+npx -y @nomadamas/k-skill@0 read market-event-impact references/event-taxonomy.md
+```
+
+검증된 사건 파일이 있으면 자유 문장으로 식별할 수 있다.
+
+```bash
+npx -y @nomadamas/k-skill@0 exec market-event-impact scripts/market_event.py -- \
+  resolve --query "SVB 파산" --events-file /path/to/verified-events.json
+```
+
+사건이 파일에 없으면 helper가 유형 후보만 제시하고 `verification_required`로 멈춘다. 날짜나 출처를 추측하지 않는다. browser/web로 규제기관·정부·거래소·기업 IR 등 직접 원천을 확인해 사건 파일에 추가한 뒤 다시 실행한다. 여러 날짜가 후보면 사용자 표현이나 공식 타임라인으로 기준 사건을 좁힌다. 다일 사건은 출처가 연결된 `event_sequence`에 사전 신호·최초 충격·정책 대응·시장 재개를 날짜순으로 기록한다. `developing_event`에는 2~20개 타임라인 단계와 기준 사건 날짜가 필요하다.
+
+## 2. Dynamic Asset Selection
+
+사용자가 자산을 지정하면 그대로 우선한다. 지정하지 않으면 지역 기본 바스켓이 아니라 사건의 예상 전달경로와 시계열의 `roles` 메타데이터로 최대 8개를 선택한다. 후보가 많으면 사건 유형에 적합한 자산군(금리·외환·주식·변동성 등)을 먼저 한 개씩 채운 뒤 세부 역할(단기·장기금리, 성장주·시장지수 등)을 보강한다. 같은 역할에서는 확인 시각까지 사건 전 기준값과 이벤트일 관측값을 모두 확보한 시계열을 우선한다. 프로필에 적합한 자산군이 없어도 무관한 종목을 억지로 채우지 않는다.
+
+- 통화정책: 단기금리·커브·FX·광범위 주식·변동성
+- 인플레이션·고용: 단기/장기금리·FX·성장주·광범위 주식·변동성
+- 금융스트레스: 단기금리·은행주·신용스프레드·VIX·안전자산
+- 무역정책: 단기·장기금리·커브·FX·영향 주식·원유/원자재·변동성
+- 지정학·공급충격: 원유·금·FX·금리·주식·변동성
+- 기업실적·규제: 해당 증권·업종·시장지수·변동성
+- 국가신용: 국채·통화·CDS·금·주식
+
+역할과 시계열 계약은 다음을 읽는다.
+
+```bash
+npx -y @nomadamas/k-skill@0 read market-event-impact references/methodology.md
+```
+
+관련 자산이 입력 파일에 없으면 다른 자산으로 의미를 바꾸지 말고 미확보로 표시한다.
+
+## 3. Research layer
+
+공식 타임라인과 발표, 당일 시장기사, 확정 시장가격을 교차한다. 가격만 보고 원인을 역으로 만들지 않는다. 재현 가능한 연구 계약은 다음을 읽는다.
+
+```bash
+npx -y @nomadamas/k-skill@0 read market-event-impact references/research-contract.md
+```
+
+완성형 분석에는 사건 개요, 무엇이 바뀌었는지, 시장 해석, 전달경로, 후속 촉매가 필요하다. research layer가 없으면 Event Study만 제공한다고 명시한다.
+
+## 4. Generic Event Study
+
+```bash
+npx -y @nomadamas/k-skill@0 exec market-event-impact scripts/market_event.py -- \
+  analyze --query "SVB 파산" \
+  --series-file /path/to/market-series.json \
+  --event-file /path/to/verified-events.json \
+  --research-file /path/to/verified-research.json \
+  --observed-at 2023-03-20T09:00:00+09:00
+```
+
+각 자산은 자기 관측 캘린더로 정렬한다. 사건 현지시각과 시계열 `observation_timezone + observation_time`을 UTC로 비교한다. 원천 시각이 없으면 확인된 `market_timezone` 마감시각, 이어서 지역 시장 마감 추정 또는 region 달력을 대리 기준으로 쓰고 결과에 명시한다. 서울·도쿄·상하이·프랑크푸르트·런던·뉴욕 시간대는 운영체제 tzdata가 없어도 일관되게 처리한다.
+
+`--observed-at`은 분석의 정보 컷오프다. 해당 시각 뒤의 일별·장중 관측을 제외하고, 원천 관측시각이 없는 일별 값은 같은 현지 날짜에 이미 확정됐다고 추정하지 않는다. 컷오프 뒤에 발생한 사건은 분석하지 않는다. 과거 시점 분석용 research에는 `observed_at`을 넣어 확인 시각을 고정하고, 그 시점에 아직 발표되지 않은 결과를 서술하지 않는다. 가격이 더 필요할 때는 원천에서 해당 시점에 실제로 공개된 자료만 보강한다.
+
+입력 시계열에 `observation_timezone`, `observation_time`, `market_timezone`, `price_type`을 원천 설명대로 기록한다. 예를 들어 FRED DEXKOUS는 뉴욕 정오 매입환율이지 서울 15:30 종가가 아니다. 한국 종가 반응을 분석할 때는 서울 현지 FX 종가를 우선하고, 해당 원천이 없으면 FRED 관측치를 별도 기준시각으로 표시한다.
+
+일별 자료의 D0는 D-1 기준값에서 D0 일별 관측값까지의 움직임이다. 정확한 사건 시각이 있어도 사건 전 장중 구간이 섞일 수 있으므로 인과효과라고 쓰지 않는다. 장중 자료가 검증되면 사건 직전 마지막 바, +1시간 이후 첫 바, 첫 후속 거래 세션의 마지막 제공 바를 표시한다. 거래소 마감 시각과 확인되지 않은 바는 공식 종가라 부르지 않는다. 다일 진행 사건의 D+1/D+5에는 후속 사건과 대응이 섞일 수 있다고 설명한다.
+
+원천 복구 규칙은 다음을 읽는다.
+
+```bash
+npx -y @nomadamas/k-skill@0 read market-event-impact references/source-priority.md
+```
+
+공식·거래소 시계열을 먼저 확인하고, 확정 종가가 비어 있을 때 Investing.com 역사적 데이터로 보강할 수 있다. 장중값을 종가로 쓰지 않는다. 아직 도래하지 않은 D+5는 결측이 아니라 관측 미도래로 표시한다.
+
+## 5. Specialized Adapter
+
+adapter가 있으면 Generic 결과 위에 사건별 세부 확인을 추가한다.
+
+- FOMC: 성명서 redline, SEP·점도표, 기자회견, 사전 정책금리 pricing
+- BOK MPC: 결정문, 소수의견, 총재 기자회견, 성장·물가 전망
+- ECB: 결정문, 경제전망, 기자회견, 사전 pricing
+- Inflation: Headline·Core·MoM·YoY·세부품목·컨센서스·수정치
+- Employment: 고용증감·실업률·임금·참가율·수정치
+- Earnings: 매출·이익·가이던스·사업부문·컨센서스·경영진 발언
+
+adapter 자료가 없다는 이유로 Generic 분석을 중단하지 않는다. 반대로 adapter 문구를 다른 사건에 강제로 적용하지 않는다.
+
+## 6. Transmission and analogues
+
+전달 단계 status는 `CONFIRMED`, `CONSISTENT`, `MIXED`, `CONTRADICTED`, `UNVERIFIED`로 표준화한다. `CONFIRMED`는 공식자료/신뢰도 높은 보도와 가격이 해당 연결을 직접 뒷받침할 때만 쓴다. 동시 움직임만으로는 인과를 단정하지 않는다. 일부 자산만 일치하면 `MIXED`, 반대면 `CONTRADICTED`, 근거 부족이면 `UNVERIFIED`다. 같은 날의 다른 대형 사건은 교란요인으로 표시한다.
+
+현재 이벤트와 과거 후보 양쪽에 사건유형, `shock_mechanisms`, `affected_channels`, 관측 `market_shock_pattern`을 구조화한다. 검증된 `historical_analogue_pool`을 이 속성과 실제 충격 방향으로 점수화해 상위 3~5개를 고른다. 충격 메커니즘 중복과 최소 한 개 시장 방향 일치가 없는 후보는 제외한다. 적격 후보가 3개 미만이면 비교를 억지로 채우지 말고 미생성 이유를 표시한다. 모든 후보에는 사건 전 날짜·출처·공통점·차이점이 필요하다.
+
+## Output contract
+
+helper 기본 출력은 사용자용 한국어 `chat`이다. JSON은 검증·자동화에만 사용한다.
+
+```text
+1. 무슨 일이 있었나 — 사건 식별 / 핵심 변화 / surprise / optional adapter
+2. 시장은 왜 반응했나
+3. 교차자산 반응 — 동적으로 선택한 자산과 선택 이유
+4. 전달경로
+5. 이벤트 스터디 — D-1 / D0 / D+1 / D+5와 실제 정렬일
+6. 과거 유사 사례 — 특성과 관측 충격 방향으로 선정한 3~5개 또는 비교 미생성 사유
+7. 앞으로 볼 것 — 현재 해석을 확인하거나 뒤집을 촉매
+8. 출처 및 재현 기준
+```
+
+## Failure rules
+
+| 상황 | 동작 |
+| --- | --- |
+| 자유 사건의 날짜·출처 미확보 | 유형 후보만 제시하고 `verification_required` |
+| 동일 이름의 사건이 여러 개 | 후보를 제시하고 날짜·지역을 추가로 식별 |
+| research layer 없음 | Event Study 전용 결과로 명시 |
+| 관련 자산 시계열 없음 | 해당 전달 단계를 미검증 처리 |
+| D0 휴장·시장 마감 후 발표 | 실제 다음 거래일로 정렬 |
+| D+5가 아직 미래 | 관측 미도래 표시 |
+| 전형적 경로와 가격이 반대 | 반대 반응 자체를 핵심 결과로 서술 |
+| adapter 없음 | Generic Engine을 계속 실행 |
+
+## Done when
+
+- 사건을 직접 출처로 식별하고 기준일·시간의 의미를 설명했다.
+- 고정 지역 바스켓이 아니라 전달경로로 자산을 선택했다.
+- 자산별 캘린더와 이벤트 윈도를 재현 가능하게 계산했다.
+- 실제 가격과 기사 근거를 분리해 전달경로를 판정했다.
+- 유사 사건을 이름이 아닌 충격 특성으로 비교했다.
+- 후속 촉매가 현재 해석을 어떻게 확인하거나 뒤집는지 설명했다.

package/skills/market-event-impact/references/event-taxonomy.md

@@ -0,0 +1,74 @@
+# Event Resolver 계약
+
+사건명은 whitelist가 아니다. 아래 `event_type`은 자산선정과 전달경로를 위한 넓은 분류이며, 개별 사건은 `event_id`와 직접 출처로 식별한다.
+
+| event_type | 대표 사건 | 우선 확인할 전달경로 |
+| --- | --- | --- |
+| `monetary_policy` | 금리 결정·QE/QT·YCC | 금리·커브 → FX → 주식 |
+| `inflation` | CPI·PPI·HICP | 정책금리 기대 → 금리·FX·성장주 |
+| `employment` | NFP·실업률·임금 | 정책금리 기대 → 금리·FX·주식 |
+| `growth` | GDP·PMI | 성장기대 → 장기금리·경기민감주·원자재 |
+| `financial_stress` | 은행 파산·예금유출·자금시장 경색 | 은행주·신용·변동성 → 단기금리 |
+| `sovereign_credit` | 국가신용등급·디폴트 | 국채·CDS·FX·금·주식 |
+| `geopolitics` | 전쟁·군사충돌·제재 | 에너지·금·FX·금리·변동성 |
+| `commodity_supply` | 감산·광산/항만 차질 | 원자재 → 기대인플레이션·관련주·FX |
+| `corporate_earnings` | 실적·가이던스 쇼크 | 해당 종목 → 업종 → 시장지수 |
+| `fiscal_policy` | 예산·감세·부양책 | 국채공급·성장기대 → 금리·FX·주식 |
+| `trade_policy` | 관세·수출통제 | 영향 업종·FX·원자재·변동성 |
+| `regulation` | 규제·소송·허가 | 해당 종목·업종·시장지수 |
+| `market_shock` | 급락·쇼트스퀴즈·시장기능 장애 | 원인 자산·변동성·신용·안전자산 |
+| `other` | 위 분류에 맞지 않는 사건 | 검증된 가설에 맞춰 사용자 지정 |
+
+## Event object
+
+```json
+{
+  "event_id": "svb-failure-2023-03-10",
+  "event_name": "Silicon Valley Bank failure",
+  "event_type": "financial_stress",
+  "event_structure": "developing_event",
+  "aliases": ["SVB 파산", "SVB 사태"],
+  "region": "US",
+  "event_date": "2023-03-10",
+  "event_time_local": "11:15",
+  "event_timezone": "America/New_York",
+  "event_sequence": [
+    {
+      "date": "2023-03-09",
+      "stage": "prelude",
+      "event": "채권매각 손실 및 자본조달 이슈 공개",
+      "source": {"name": "당시 원문 보도", "url": "https://..."}
+    },
+    {
+      "date": "2023-03-10",
+      "time_local": "11:15",
+      "timezone": "America/New_York",
+      "stage": "trigger",
+      "event": "캘리포니아 규제당국의 은행 폐쇄",
+      "source": {"name": "FDIC", "url": "https://..."}
+    },
+    {
+      "date": "2023-03-12",
+      "stage": "policy_response",
+      "event": "예금자 보호 및 BTFP 발표",
+      "source": {"name": "Federal Reserve", "url": "https://..."}
+    }
+  ],
+  "source": {"name": "직접 원천", "url": "https://..."}
+}
+```
+
+- `event_id + event_date`는 파일 안에서 유일해야 한다.
+- `event_type`은 금융스트레스·물가·정책 등 시장충격의 분야다. `event_structure`는 `point_event`, `scheduled_event`, `developing_event` 중 하나로 별도 기록한다. 두 분류를 혼용하지 않는다.
+- `event_structure=developing_event`면 출처가 연결된 `event_sequence`를 2~20개 제공하고, 기준일 사건을 그 안에 포함한다. 사전 경고·최초 충격·후속 대응·시장 재개를 순서대로 기록할 수 있다.
+- 날짜는 분석 기준이 된 최초 공식 발표·폐쇄·결정 시점 중 무엇인지 설명한다.
+- 사건이 며칠에 걸치면 최초 충격과 후속 정책대응을 별도 event로 나눌 수 있다.
+- `event_time_local`과 IANA `event_timezone`은 함께 쓰거나 함께 생략한다.
+- timestamp 품질은 정확 시각과 시간대가 있으면 `A · 정확 시각`, 날짜만 확인되면 `B · 날짜만 확인`이다. `C · 다일 진행 사건`은 시간 품질이 아니라 `event_structure=developing_event`를 뜻한다.
+- `event_date`와 정확 시각은 기준 충격(anchor)을 고르는 데 사용한다. 일별 데이터의 D0는 D-1 기준값부터 D0 일별 관측값까지의 변동이며 인과효과로 서술하지 않는다. 진행 사건의 D+1/D+5는 후속 충격·대응을 포함할 수 있다고 밝힌다.
+- 이름만으로 날짜가 확정되지 않으면 `verification_required`로 멈춘다.
+- 키워드가 여러 유형과 동시에 일치하면 임의로 하나를 고르지 않고 명시적 `event_type`을 요구한다.
+
+## Optional adapter
+
+`adapter`는 `FOMC`, `BOK_MPC`, `ECB`, `INFLATION`, `EMPLOYMENT`, `EARNINGS` 중 하나를 지정할 수 있다. 지정하지 않아도 Generic Engine은 동작한다.

package/skills/market-event-impact/references/methodology.md

@@ -0,0 +1,98 @@
+# 이벤트 스터디 방법론
+
+## Series input
+
+JSON은 `series` 배열을 받는다.
+
+```json
+{
+  "series": [
+    {
+      "symbol": "UST2Y",
+      "region": "US",
+      "asset_class": "rates",
+      "unit": "pct",
+      "observation_timezone": "America/New_York",
+      "observation_time": "16:00",
+      "market_timezone": "America/New_York",
+      "price_type": "market_close",
+      "roles": ["short_rates", "government_bond", "safe_haven"],
+      "selection_priority": 10,
+      "source": {"name": "U.S. Treasury", "url": "https://..."},
+      "observations": [
+        {"date": "2026-09-15", "value": 4.67},
+        {"date": "2026-09-16", "value": 4.73}
+      ]
+    }
+  ]
+}
+```
+
+일별 자료에서 관측 시점이 뉴욕 정오인 원/달러 원천의 예시는 다음과 같다. `region`은 자산의 시장/대상 지역이고, 관측 시각 필드는 실제 원천 기준시각이다.
+
+```json
+{
+  "symbol": "USDKRW",
+  "region": "KR",
+  "asset_class": "fx",
+  "unit": "krw_per_usd",
+  "observation_timezone": "America/New_York",
+  "observation_time": "12:00",
+  "market_timezone": "Asia/Seoul",
+  "price_type": "noon_buying_rate",
+  "source": {"name": "Federal Reserve H.10 via FRED", "url": "https://fred.stlouisfed.org/data/DEXKOUS"},
+  "observations": [{"date": "2023-03-10", "value": 1324.51}]
+}
+```
+
+시각 메타데이터가 없으면 region으로 대리 정렬하고 결과에서 해당 한계를 표시한다. `observation_timezone`과 `observation_time`은 함께 제공해야 한다. `market_timezone`은 해당 가격이 대표하는 현지 시장 시계이며, `price_type`은 `market_close`, `noon_buying_rate`, `settlement`, `adjusted_close`처럼 원천의 실제 기준을 짧게 기록한다.
+
+CSV는 `symbol,date,value,asset_class,unit,source_name,source_url`을 기본으로 받으며 `region,observation_timezone,observation_time,market_timezone,price_type`는 선택 열이다. 날짜는 `YYYY-MM-DD`, 값은 유한 숫자여야 한다. 같은 symbol/date가 두 번 나오면 입력 오류다. CSV에서 교차시장 정렬을 사용하려면 `region`을 넣는다. 모든 시리즈에는 `source.name`·`source.url`이 있어야 하며 symbol은 파일 전체에서 유일해야 한다.
+
+장중 자료는 별도 `intraday_observations`로 넣고, 각 timestamp에 UTC offset을 명시한다. 동일 순간 중복은 거부되고 입력 순서와 무관하게 시간순 정규화된다.
+
+```json
+"intraday_observations": [
+  {"timestamp": "2023-03-10T11:00:00-05:00", "value": 100.0},
+  {"timestamp": "2023-03-10T12:30:00-05:00", "value": 99.2},
+  {"timestamp": "2023-03-10T16:00:00-05:00", "value": 98.5}
+]
+```
+
+## Dynamic asset roles
+
+JSON 시계열의 `roles`는 사건 전달경로와 자산을 연결한다. 한 시리즈에 여러 역할을 줄 수 있다. 대표 역할은 `short_rates`, `long_rates`, `curve`, `government_bond`, `bank_equity`, `credit`, `volatility`, `safe_haven`, `oil`, `gold`, `fx`, `broad_equity`, `sector_equity`, `event_security`, `affected_equity`다. 무역정책 프로필은 금리·커브·FX·영향/광범위 주식·원유/원자재·변동성을 선택한다. 임의의 새 역할도 허용하지만 selector profile과 일치해야 자동 선택된다.
+
+`selection_priority`는 같은 역할 후보 사이의 정수 우선순위(-100~100)다. 사용자 `--symbols`가 있으면 역할과 우선순위보다 항상 우선한다. 자동 선택은 사건 유형에 적합한 자산군을 먼저 나눠 담고, 세부 역할을 채운다. 확인 시각까지 D-1과 D0를 모두 확보한 후보를 우선하며, 이 창을 만들 수 없는 시계열은 대체 후보가 없을 때만 사용한다. `roles`가 없거나 자산군명만 담은 입력은 `asset_class`를 보수적인 fallback으로 사용한다. `bank_equity`처럼 구체적이지만 사건 프로필과 맞지 않는 역할은 자산군이 주식이라는 이유만으로 넣지 않는다. 물가 사건의 주식 반응에는 `growth_equity`와 `broad_equity`를 구분하고 `volatility`도 별도 채널로 취급한다.
+
+## Alignment
+
+- `same`: 이벤트 날짜 관측이 없으면 해당 시리즈 실패
+- `next`: 이벤트 날짜 이상 첫 관측일
+- `next_strict`: 이벤트 날짜보다 뒤의 첫 관측일
+- `previous`: 이벤트 날짜 이하 마지막 관측일
+- cross-market에서는 우선 event timestamp와 시계열 `observation_timezone + observation_time`을 UTC로 비교한다. 제공되지 않으면 `market_timezone`의 마감시각, 이어서 `region` 시장 마감시각 추정 또는 거래일 달력을 대리 기준으로 사용하고 정렬 근거를 결과에 표시한다. 이벤트가 관측 시각 이전이면 `next`, 이후/동시이면 `next_strict`를 적용한다. IANA timezone과 DST를 반영하며 Windows에 tzdata가 없어도 KR·JP·CN·US·EU·UK 규칙을 자체 계산한다.
+- `--observed-at` 이후 관측은 계산에서 제거한다. 검증된 관측 시각이 있는 경우 현지 날짜·시각을 UTC로 변환해 비교한다. 시각이 없는 일별 값은 같은 현지 날짜에 공개됐다고 추측하지 않고 다음 날짜부터 이용 가능한 것으로 보수적으로 처리한다. 원천에서 그보다 빠른 확정 시각을 확인하면 `observation_timezone`·`observation_time`을 채운다.
+
+D-n/D+n은 달력일이 아니라 정렬된 시리즈의 유효 관측 순서다.
+
+요청한 D+n이 컷오프까지 확보한 시리즈의 마지막 관측일 뒤에 있으면 `pending_D+n`이다. 아직 형성 전인지 원천 범위 부족인지는 이 코드만으로 알 수 없다. 원천 범위가 짧은 경우에는 `source-priority.md`의 missing-window recovery를 수행한 뒤 다시 계산한다.
+
+## Measurement
+
+- `asset_class=rates|policy|spread|credit`, `unit=pct`: `(value - anchor) × 100` bp
+- `asset_class=rates|policy|spread|credit`, `unit=bp`: `value - anchor` bp
+- 그 외 가격/지수: `(value / anchor - 1) × 100` %
+- 기본 anchor는 D-1이다. 일별 데이터의 D0는 D-1→D0의 관측된 일별 변동이며 사건 이후 반응만 분리한 인과효과가 아니다. event timestamp가 있어도 같은 날짜 전체 수익률은 사건 전 구간을 포함할 수 있다.
+- 값이 0인 가격 시리즈는 % 수익률을 계산하지 않는다.
+- 정확한 event timestamp와 장중 바가 모두 있을 때는 사건 직전 마지막 바, 사건 1시간 후 이상 첫 바, 첫 후속 거래 세션의 마지막 제공 바를 계산한다. 마지막 바 시각이 시장 마감으로 확인되지 않으면 `공식 종가`가 아니라 제공 바라고 표시한다.
+- `developing_event`의 D+1/D+5에는 사전 경고·후속 사건·정책 대응이 들어갈 수 있으므로 단일 촉발 사건에 귀속하지 않는다.
+
+## Curve classification
+
+단기와 장기 금리가 모두 상승하면 bear, 모두 하락하면 bull이다. 장기 변화가 단기 변화보다 크면 steepening, 작으면 flattening이다. 방향이 서로 다르거나 하나가 0이면 `Mixed`로 두고 스프레드 bp만 표시한다.
+
+## Threshold
+
+`above`는 `metric >= threshold`, `below`는 `metric <= threshold`다. 첫 관측은 직전값이 없어 판정하지 않는다. 중복 이벤트 날짜는 한 번만 반환한다.
+`bp_change`는 rates·policy·spread 시리즈에만 허용한다.

package/skills/market-event-impact/references/research-contract.md

@@ -0,0 +1,120 @@
+# Generic Event Research 계약
+
+이벤트 스터디 숫자 위에 올라가는 재현 가능한 연구 계층이다. `event_id + event_date`는 파일 안에서 유일해야 한다.
+
+```json
+{
+  "research": [{
+    "event_id": "svb-failure-2023-03-10",
+    "event_name": "Silicon Valley Bank failure",
+  "event_type": "financial_stress",
+  "region": "US",
+    "event_date": "2023-03-10",
+    "observed_at": "2023-03-20T09:00:00+09:00",
+  "event_features": {
+    "shock_mechanisms": ["deposit_run", "duration_loss"],
+    "affected_channels": ["bank_equity", "credit", "short_rates", "volatility"],
+    "market_shock_pattern": {"bank_equity": "down", "credit": "wider", "short_rates": "down", "volatility": "up"}
+  },
+    "overview": {
+      "summary": "직접 확인된 사건과 배경",
+      "expected": false,
+      "surprise_assessment": "사전 기대와 달랐던 지점",
+      "classification": "충격 메커니즘 중심 분류",
+      "source": {"name": "직접 원천", "url": "https://..."}
+    },
+    "what_changed": [{
+      "channel": "사건별 변화 채널",
+      "finding": "확인된 변화",
+      "significance": "시장에 중요한 이유",
+      "source": {"name": "직접 원천", "url": "https://..."}
+    }],
+    "adapter_details": [],
+    "market_interpretation": [{
+      "channel": "금리·신용·성장·물가 등",
+      "finding": "당일 기사와 가격이 함께 지지한 해석",
+      "significance": "재가격과 연결되는 이유",
+      "source": {"name": "시장 반응 원천", "url": "https://..."}
+    }],
+    "transmission": [{
+      "from": "최초 충격",
+      "to": "첫 번째 시장 반응",
+      "status": "consistent",
+      "evidence": "실제 가격 근거",
+      "source": {"name": "가격 원천", "url": "https://..."}
+    }],
+    "catalysts": [{
+      "date": "2023-03-12",
+      "time_local": "18:00",
+      "timezone": "America/New_York",
+      "event": "후속 정책대응",
+      "why_it_matters": "현재 해석을 확인하거나 뒤집는 조건",
+      "source": {"name": "공식 일정", "url": "https://..."}
+    }],
+    "historical_context": {
+      "include": true,
+      "reason": "비교가 필요한 이유",
+      "comparisons": [{
+        "date": "2008-03-16",
+        "event": "과거 사건",
+        "matching_basis": "사건유형·전달경로·가격반응 중 선정 기준",
+        "similarity": "공통점",
+        "difference": "중요한 차이",
+        "source": {"name": "직접 원천", "url": "https://..."}
+      }]
+    },
+    "historical_analogue_pool": [{
+      "date": "2008-03-16",
+      "event": "Bear Stearns 구제",
+      "event_type": "financial_stress",
+      "shock_mechanisms": ["funding_stress", "liquidity_backstop"],
+      "affected_channels": ["bank_equity", "short_rates", "volatility"],
+      "market_shock_pattern": {"bank_equity": "down", "short_rates": "down", "volatility": "up"},
+      "similarity": "은행 유동성 충격과 정책 백스톱이 단기금리·변동성에 함께 반영됐다.",
+      "difference": "도매자금시장과 투자은행이 충격의 중심이었다.",
+      "source": {"name": "직접 원천", "url": "https://..."}
+    }]
+  }]
+}
+```
+
+## Evidence rules
+
+- 사건 정의와 기준일은 규제기관·정부·거래소·기업 IR 등 직접 원천을 우선한다.
+- `what_changed`는 직전 상태 또는 사건 직전 기대와 비교해 확인된 변화만 쓴다.
+- `market_interpretation`은 가격만 보고 역으로 만들지 않는다. 당일 시장기사와 가격 방향이 함께 지지해야 한다.
+- 모든 claim, transmission, catalyst, historical comparison에는 직접 연결되는 출처가 필요하다.
+- 과거 시점 분석에는 research `observed_at`을 적고 분석 CLI의 `--observed-at`보다 뒤에 확인된 연구를 넣지 않는다. helper가 research 시각이 분석 컷오프 이후이면 거부한다. 출처 URL만으로 보도·발표 시각을 증명할 수 없으므로 작성자가 개별 claim의 당시 공개 여부를 확인한다.
+- 검색결과 snippet만으로 사실이나 인과를 확정하지 않는다.
+- adapter가 있으면 `adapter_details`에 전용 확인 결과를 넣는다. adapter가 없으면 빈 배열이어도 된다.
+
+## Transmission status
+
+`status`는 다음 대문자 enum으로 표준화한다. 과거 입력의 소문자 `limited`는 `MIXED`로 정규화한다.
+
+| status | 의미 |
+| --- | --- |
+| `CONFIRMED` | 공식자료 또는 신뢰도 높은 시장보도와 관측가격이 이 연결을 직접 뒷받침한다. 단지 동시에 움직였다는 뜻은 아니다. |
+| `CONSISTENT` | 가격은 가설과 같은 방향이지만 인과는 확정하지 못했다. |
+| `MIXED` | 일부 자산·단계만 일치하거나 반응이 제한적이다. |
+| `CONTRADICTED` | 관측 결과가 제시한 전달방향과 반대다. |
+| `UNVERIFIED` | 필요한 원천·가격·연결 근거가 부족하다. |
+
+완성형 연구에는 최소 한 단계가 필요하다. 근거가 부족하면 생략하지 말고 `unverified`와 부족한 근거를 적는다.
+
+## Catalysts and analogues
+
+후속 촉매는 현재 해석을 확인하거나 뒤집을 일정이어야 하며 최소 2개, 최대 8개다. 같은 사건의 다음 날짜만 기계적으로 고르지 않는다.
+일정의 발표시각이 확인되면 `time_local`과 `timezone`을 함께 넣어 동일 날짜의 경과·예정 여부를 판정한다. 날짜만 확인되면 당일에는 `시각 미확인`으로 표시한다.
+
+과거 비교를 사용할 때는 3~5개를 쓴다. 이름이 같은 사건이 아니라 `matching_basis`에 사건유형, 충격 메커니즘, 핵심 가격반응 중 무엇이 일치하는지 명시한다. 현재 사건 이후 날짜나 중복 사례는 허용하지 않는다.
+
+## Historical analogue ranking
+
+범용 분석은 현재 사건과 과거 후보 양쪽에 `event_features`를 제공한다. 충격 메커니즘과 영향 채널은 짧고 표준화된 식별자 배열로, `market_shock_pattern`은 채널별 `up|down|mixed|flat|wider|tighter` 방향으로 기록한다. 후보마다 과거 날짜, event_type, similarity/difference 서술과 직접 출처가 필수다.
+
+검증된 `historical_analogue_pool`은 이름 유사도로 고르지 않는다. helper는 사건유형 일치(+2), shock_mechanisms Jaccard(+3 가중), affected_channels Jaccard(+2), 관측 시장충격 방향 겹침(+4)을 점수화해 정렬한다. mechanism 중복과 최소 한 개 시장 방향 일치가 모두 있어야 후보 자격이 있다. 적격 후보 3개 미만이면 억지로 채우지 않고 비교 미생성 사유를 출력한다. 3~5개이면 높은 순으로 표시하며 매칭 점수 근거를 남긴다. 수동 `historical_context`는 호환을 위해 지원하되 같은 날짜·출처 검증을 적용한다.
+
+일별 D0는 이벤트 이후 부분수익률이 아니라 일별 관측값의 변화다. exact event timestamp는 거래일 정렬을 개선하지만, 일별 종가만으로 인과효과를 분리하지 못한다. 다일 진행 사건의 후속 창에는 `event_sequence`에 기록된 후속 사건이 포함될 수 있으므로 하나의 촉발점에 귀속하지 않는다.
+
+기존 `decision` 필드는 하위 호환을 위해 `overview`로 읽을 수 있지만, 새 입력은 `overview`를 사용한다.

package/skills/market-event-impact/references/source-priority.md

@@ -0,0 +1,25 @@
+# Source priority
+
+1. 사건을 직접 다루는 규제기관·정부·거래소·기업 IR과 공식 시계열
+2. 공식 경제 캘린더와 공식 배포 일정
+3. Reuters·Bloomberg·주요 통신사: consensus와 시장의 당일 해석 보강
+4. Investing.com 역사적 데이터: 공식·거래소·재무부·중앙은행 시계열에 필요한 종가가 없을 때 시장가격 fallback
+5. 기타 금융사이트: 위 원천 부재 시 제한적 교차 확인
+
+검색결과 snippet만으로 수치·일정·인과를 확정하지 않는다. 각 수치에는 관측일, 단위, 원천 URL을 보존한다. 기사와 가격 반응이 충돌하면 가격 방향을 우선 사실로 기록하고 원인은 미확인으로 둔다.
+
+시계열 provenance에는 원천이 실제로 측정한 `observation_timezone`, `observation_time`, 대상 시장의 `market_timezone`, `price_type`을 보존한다. 원천의 관측시각을 거래소 종가로 바꾸어 부르지 않는다. 특히 FRED `DEXKOUS`는 뉴욕 정오 매입환율이므로 서울 15:30 USD/KRW 종가를 대신할 수 없다. 한국 거래일 기준 FX 반응은 서울 현지 종가 원천을 우선하고, 해당 자료가 없을 때에만 FRED를 별도 시간축의 보조 관측치로 표시한다.
+
+## Missing-window recovery
+
+Event Study의 D0·D+1·D+5가 비어 있으면 즉시 `미확인`으로 출력하지 않는다.
+
+1. 기존 원천의 날짜 범위가 필요한 거래일까지 포함되는지 확인한다.
+2. 거래소·재무부·중앙은행·공식 지수 제공자의 일별 종가를 먼저 조회한다.
+3. 공식 원천으로 보강할 수 없으면 Investing.com 역사적 데이터 화면에서 해당 날짜의 확정 종가를 확인한다.
+   - KOSPI: `https://www.investing.com/indices/kospi-historical-data`
+   - USD/KRW: `https://www.investing.com/currencies/usd-krw-historical-data`
+4. 브라우저에 표시된 날짜·종가·통화·시장 상태를 normalized series에 추가하고 source URL을 보존한 뒤 Event Study를 다시 실행한다.
+5. 장중값을 종가로 쓰지 않는다. 해당 시장의 다섯 번째 후속 거래일이 아직 끝나지 않았거나 역사적 데이터에 확정값이 없으면 `pending_D+n`으로 남긴다.
+
+Investing.com은 시장가격 보강용이다. 정책결정, 규제조치, 기업발표, 군사·외교 발표, 공식 일정 등 사건 자체의 원천으로 사용하지 않는다.

package/skills/market-event-impact/scripts/adapters.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Optional specialized adapters layered on the generic event engine."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+ADAPTERS = {
+    "FOMC": {"label": "FOMC", "channels": ("성명서", "SEP·점도표", "Powell 기자회견", "사전 정책금리 pricing")},
+    "BOK_MPC": {"label": "한국은행 금통위", "channels": ("통화정책방향 결정문", "소수의견", "총재 기자회견", "성장·물가 전망")},
+    "ECB": {"label": "ECB", "channels": ("결정문", "경제전망", "Lagarde 기자회견", "사전 정책금리 pricing")},
+    "INFLATION": {"label": "물가지표", "channels": ("Headline", "Core", "MoM·YoY", "세부 품목", "컨센서스·수정치")},
+    "EMPLOYMENT": {"label": "고용지표", "channels": ("고용증감", "실업률", "임금", "참가율", "수정치")},
+    "EARNINGS": {"label": "기업실적", "channels": ("매출·이익", "가이던스", "사업부문", "컨센서스", "경영진 발언")},
+}
+
+
+def adapter_for_event(event: dict[str, Any]) -> dict[str, Any] | None:
+    explicit = str(event.get("adapter") or "").strip().upper()
+    family = str(event.get("event_family") or "").strip().upper()
+    event_type = str(event.get("event_type") or "")
+    key = explicit or family
+    if key in ADAPTERS:
+        return {"key": key, **ADAPTERS[key]}
+    if event_type == "inflation":
+        return {"key": "INFLATION", **ADAPTERS["INFLATION"]}
+    if event_type == "employment":
+        return {"key": "EMPLOYMENT", **ADAPTERS["EMPLOYMENT"]}
+    if event_type == "corporate_earnings":
+        return {"key": "EARNINGS", **ADAPTERS["EARNINGS"]}
+    return None