refs #739: formalize game query plan contract

docs/design/739-game-target-contract/README.md

@@ -20,22 +20,64 @@
 
 ## 3. 계약
 
-`game_query_plan`은 다음 필드를 반환한다.
+`game_query_plan`은 ReAct가 판단에 사용할 고정 JSON 계약을 반환한다. 자연어
+설명, 후보 검색 원문, 기존 호환 필드는 진단 영역으로 분리하며 실행 판단은 아래
+권위 필드만 사용한다.
+
+```json
+{
+  "contractVersion": "1.0",
+  "scopeType": "MULTI",
+  "targets": [
+    {
+      "mention": "사용자가 언급한 게임명",
+      "matchStatus": "MATCHED",
+      "dataStatus": "AVAILABLE",
+      "gameKey": "카탈로그 키 또는 null",
+      "gameId": "카탈로그 식별자 또는 null",
+      "userMasterObjectName": "승인 객체 또는 null"
+    }
+  ],
+  "dataEligibleTargets": [],
+  "unresolvedTargets": []
+}
+```
+
+고정 enum은 다음과 같다.
+
+- `scopeType`: `NONE`, `SINGLE`, `MULTI`, `ALL`
+- `matchStatus`: `NOT_APPLICABLE`, `MATCHED`, `UNMATCHED`
+- `dataStatus`: `NOT_APPLICABLE`, `AVAILABLE`, `UNAVAILABLE`
+
+`scopeType`은 질문에 언급된 범위만 나타낸다. 실행 가능성이나 SQL 조립 방식을
+암시하지 않는다. `targets`는 언급 순서를 유지하고, `dataEligibleTargets`는 현재
+질의에 사용할 수 있는 카탈로그 대상만, `unresolvedTargets`는 미매칭 또는 데이터
+객체가 없는 대상을 보존한다. ReAct는 이 계약 전체를 관찰한 뒤 공통 팩트 단일
+호출, 대상별 호출, 또는 빈 결과 응답을 선택한다.
+
+기존 API 호환 기간에는 아래 필드도 반환할 수 있지만 ReAct의 실행 판단에 사용하지
+않는다: `targetType`, `status`, `matchedGames`, `supportedGames`,
+`mentionResults`, `dataIneligibleTargets`, `unmatchedGames`, `nextAction`,
+`executionMode`.
+
+기존 필드의 의미는 다음과 같다.
 
 | 필드 | 내용 |
 |---|---|
-| `targetType` | `NONE`, `SINGLE`, `MULTI`, `ALL` |
-| `status` | `NO_TARGET`, `SUPPORTED`, `PARTIAL`, `UNMATCHED` |
+| `targetType` | 호환용 `scopeType` 별칭 |
+| `status` | 호환용 요약 상태. ReAct 실행 분기에 사용하지 않음 |
 | `targets` | 언급 순서를 보존한 게임 대상 배열 |
-| `nextAction` | 항상 `CALL_FEWSHOT` |
-| `executionMode` | `UNSCOPED`, `SINGLE`, `COMBINED`, `ALL` |
+| `nextAction` | 호환용 안내. 실행을 강제하지 않음 |
+| `executionMode` | 호환용 안내. 실행을 강제하지 않음 |
 
 각 `targets` 항목은 다음 값을 가진다.
 
 | 필드 | 내용 |
 |---|---|
 | `mention` | 질문에서 추출한 게임명. `NONE`은 `null` |
-| `status` | `NONE`, `MATCHED`, `UNMATCHED`, `CATALOG` |
+| `status` | 호환용 대상 상태 |
+| `matchStatus` | `NOT_APPLICABLE`, `MATCHED`, `UNMATCHED` |
+| `dataStatus` | `NOT_APPLICABLE`, `AVAILABLE`, `UNAVAILABLE` |
 | `gameKey`, `gameId` | DB 카탈로그가 반환한 게임 식별자 |
 | `gamePrefix` | DB 카탈로그가 반환한 prefix |
 | `gameName`, `aliases` | 표시명과 별칭 |
@@ -193,3 +235,8 @@ read-only·객체 범위 검증만 담당한다.
   답변 이력 `422`는 `PASS`로 기록됐다. 직접 정답 실행 분기는 두지 않는다.
 - 2026-07-28: `NONE`을 질의 차단으로 해석하지 않도록 경계 예제에 논리 객체 역할을
   부여하고, 공통 객체 질의에는 경계 SQL을 일반화하지 않는 프롬프트 규칙을 추가했다.
+- 2026-07-29: ReAct가 자유 설명문이나 중복 요약 필드를 해석하지 않도록, 게임 범위
+  계획의 권위 JSON 계약을 `contractVersion`, `scopeType`, `targets[*].matchStatus`,
+  `targets[*].dataStatus`, `dataEligibleTargets`, `unresolvedTargets`로 정리했다.
+  이 계약은 게임명·prefix·물리 객체를 애플리케이션에 고정하지 않으며, 다음 도구 호출
+  횟수와 방식은 ReAct가 현재 질문과 계획 결과로 판단한다.