schema_version: agents_rule.v1
rule_id: NO_DIRECT_API_TRADING_V1
title: API를 통한 매수/매도 직접 실행 절대 금지 — 최상위 안전 규칙
priority: CRITICAL
origin: "사용자 직접 지시 (2026-06-21): '반드시 지침에 가장 중요한 하네스인 매수/매도는
  API를 통해서 직접하지 않는다가 원칙이다. 이걸 지키지 않는다면 엔진으로서 의미는 없다.'"
has_code_implementation: true
code_path:
  - "src/quant_engine/kis_api_client_v1.py"
  - "tools/validate_no_direct_api_trading_v1.py"

summary:
  - "이 엔진(은퇴자산포트폴리오 퀀트엔진)은 어떤 외부 API를 통해서도 매수/매도 주문을
    직접 실행하지 않는다. 한국투자증권 KIS Open API를 포함해, 향후 연동되는 모든
    브로커/거래소 API에 동일하게 적용된다."
  - "이 엔진의 모든 산출물(final_decision_packet, sell_priority, rebalance orders 등)은
    '제안(proposal)'이지 '주문 실행(execution)'이 아니다. 실제 매수/매도 주문은 반드시
    사람이 HTS(홈트레이딩시스템)에서 직접 확인 후 수동으로 입력한다."
  - "이 원칙은 데이터 수집(read-only) API 사용을 금지하지 않는다 — 시세/호가/공매도/
    투자자별 매매동향 등 조회성 데이터 수집은 허용된다. 금지 대상은 주문 제출
    (order placement), 정정(modify), 취소(cancel) API 호출뿐이다."

scope:
  applies_to:
    - "한국투자증권(KIS) Open API — https://apiportal.koreainvestment.com"
    - "향후 추가되는 모든 브로커/거래소 Open API 연동"
  prohibited_actions:
    - "주문 제출(매수/매도 주문 전송) API 호출"
    - "기존 주문 정정/취소 API 호출"
    - "잔고를 변경시키는 모든 쓰기성(write) API 호출"
  allowed_actions:
    - "시세 조회(현재가, 호가, 일자별 시세)"
    - "공매도 일별추이 조회"
    - "투자자별 매매동향 조회"
    - "계좌 잔고/평가 조회(읽기 전용)"

enforcement:
  code_level:
    rule: "KIS API 클라이언트 모듈(src/quant_engine/kis_api_client_v1.py)의 모든 HTTP 요청은
      단일 공유 함수를 통해서만 전송되며, 그 함수는 차단 목록(FORBIDDEN_TR_ID_PREFIXES,
      FORBIDDEN_PATH_SUBSTRINGS)에 해당하는 TR_ID/경로를 만나면 즉시 RuntimeError를
      발생시켜 요청을 중단한다. 주문 제출/정정/취소 함수는 이 코드베이스에 일체 작성하지
      않는다(함수 자체가 존재하지 않음 — 가드는 방어적 2차 안전장치)."
    test: "tests/unit/test_kis_api_client_v1.py — 차단 목록에 있는 TR_ID/경로로 요청 시
      RuntimeError가 발생하는지 검증 + 소스코드 전체에 주문 제출 엔드포인트 경로
      문자열(/uapi/domestic-stock/v1/trading/order-cash 등)이 한 글자도 존재하지 않는지
      정적 grep 검증."
  review_level:
    rule: "이 모듈에 새 함수를 추가할 때마다 반드시 KIS Open API 공식 문서에서 해당
      TR_ID가 조회(quotations)/순위(ranking)/계좌조회(read-only) 카테고리인지 확인하고,
      trading(주문) 카테고리 함수는 어떤 이유로도 추가하지 않는다."

violation_consequence: "이 규칙을 어기면 엔진 전체가 '제안 시스템'에서 '자동매매 시스템'으로
  변질되어 프로젝트의 핵심 전제(사람이 최종 승인·입력)가 깨진다. 사용자가 명시적으로
  '엔진으로서 의미는 없다'고 표현한 절대 우선 규칙이다."