@flextudio/scenario 0.1.0

package/skill/patterns/molecule/input-pair.json

@@ -0,0 +1,284 @@
+{
+  "tier": "molecule",
+  "name": "input-pair",
+  "path": "schema/v1/patterns/molecule/input-pair.schema.json",
+  "schema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://flextudio.local/meta-contract/v1/patterns/molecule/input-pair.schema.json",
+    "title": "pattern.molecule.input-pair",
+    "description": "두 개의 입력 컨트롤이 가로로 나란히 50%/50% 로 배치되는 페어 (molecule). 쿼리/필터 행에 자주 쓰이는 'duo' 구조 — 예: 부서(inputCombo) + 담당자(inputSearch), 시작일(inputDate) + 종료일(inputDate), 기간(inputCombo) + 상태(inputCombo). 두 입력은 서로 다른 inputType 을 가질 수 있다 (per-item). 각 입력은 Caption(입력 위 라벨) 을 옵션으로 가질 수 있으며 Caption 유무에 따라 Height 가 68px(라벨 포함) / 44px(라벨 없음) 로 자동 결정.\n\nbgColor 가 있으면 'carded' 모드 — wrapper 에 라이트 톤 배경 + 상하 20px Margin + (8/10) Padding 이 깔리고, 두 입력은 columnGap 8px 로 모이고 border 는 radius-only(시각 hairline 없음) 가 되어 카드 안에 잠긴다. bgColor 가 없으면 'open' 모드 — wrapper 는 투명, columnGap 16px 로 더 여유 있고, 두 입력은 1px Gray4 hairline 으로 페이지 위에 또렷이 선다.\n\n[naming] inputType 식별자 + per-type 옵션 키 prefix — `inputCombo / inputSearch / inputDate`, `comboItems`, `comboDataSourceName`, `comboTitle`, `searchDataSourceName`, `searchTitle`, `searchSubTitle`, `searchKeywordCkey`, `dateFormat`, `dateSelectType`. 공통 키(`name`, `caption`, `placeholder`) 는 접두사 없음.",
+    "x-tier": "molecule",
+    "x-tags": [
+      "input",
+      "pair",
+      "duo",
+      "horizontal",
+      "filter",
+      "query-row",
+      "combo",
+      "search",
+      "date",
+      "mixed"
+    ],
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "inputOptions"
+    ],
+    "properties": {
+      "inputOptions": {
+        "type": "array",
+        "minItems": 2,
+        "maxItems": 2,
+        "description": "두 입력 컨트롤의 옵션 (배열 인덱스 0=왼쪽, 1=오른쪽). 각 항목이 자신의 inputType 을 가지며 서로 달라도 된다.",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "inputType"
+          ],
+          "properties": {
+            "inputType": {
+              "type": "string",
+              "enum": [
+                "inputCombo",
+                "inputSearch",
+                "inputDate"
+              ],
+              "description": "입력 컨트롤 종류. inputCombo=Combo(고정 Items 또는 DataSource ComboList), inputSearch=Search(DataSource 기반 Lookup List), inputDate=InputDate(Calendar Dialog)."
+            },
+            "caption": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 30,
+              "description": "입력 컨트롤 위에 표시되는 라벨 텍스트. 지정 시 Height 68px(라벨 포함), 미지정 시 44px. CaptionStyle 은 고정 (SemiBold 13 left). 다국어/바인딩 토큰 가능."
+            },
+            "placeholder": {
+              "type": "string",
+              "maxLength": 80,
+              "description": "Placeholder 텍스트. 미지정 시 빈 문자열."
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40,
+              "description": "ControlName / ControlName2 (스튜디오 explorer 식별자 + 데이터 키). 미지정 시 inputType + 인덱스 기반 기본값 (ComboLeft / ComboRight, DateLeft / DateRight, SearchLeft / SearchRight)."
+            },
+            "comboItems": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 8,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 30
+              },
+              "description": "inputType=inputCombo 의 고정 항목 모드. 각 문자열이 ComboList Items[].ItemName + ItemValue 로 매핑. 8개 초과 / 동적 데이터는 comboDataSourceName 사용."
+            },
+            "comboDataSourceName": {
+              "type": "string",
+              "minLength": 1,
+              "description": "inputType=inputCombo 의 DataSource ComboList 모드. comboItems 와 둘 중 하나 필수."
+            },
+            "comboTitle": {
+              "type": "string",
+              "minLength": 1,
+              "description": "inputType=inputCombo + comboDataSourceName 모드의 ComboList 항목 Title 필드 (선택)."
+            },
+            "searchDataSourceName": {
+              "type": "string",
+              "minLength": 1,
+              "description": "inputType=inputSearch 일 때 필수. Dialog 내 List 의 DataSourceName."
+            },
+            "searchTitle": {
+              "type": "string",
+              "minLength": 1,
+              "description": "inputType=inputSearch 일 때 필수. List 의 항목 Title 필드 (보통 검색 결과의 표시 컬럼명)."
+            },
+            "searchSubTitle": {
+              "type": "string",
+              "description": "inputType=inputSearch 일 때 선택. List 의 SubTitle 필드."
+            },
+            "searchKeywordCkey": {
+              "type": "string",
+              "description": "inputType=inputSearch 일 때 선택. 키워드 검색 컬럼키. 지정 시 UseKeywordSearch=true 활성."
+            },
+            "dateFormat": {
+              "type": "string",
+              "enum": [
+                "YYYY-MM-DD",
+                "YYYY.MM.DD",
+                "YYYY/MM/DD",
+                "YYYY-MM"
+              ],
+              "description": "inputType=inputDate 일 때. 기본 'YYYY-MM-DD'."
+            },
+            "dateSelectType": {
+              "type": "string",
+              "enum": [
+                "SingleDate",
+                "FromTo"
+              ],
+              "description": "inputType=inputDate 의 캘린더 선택 모드. 기본 'SingleDate'. 시작일/종료일 페어는 두 입력 모두 SingleDate."
+            }
+          },
+          "allOf": [
+            {
+              "$comment": "inputCombo 는 comboItems 또는 comboDataSourceName 중 하나 필요.",
+              "if": {
+                "properties": {
+                  "inputType": {
+                    "const": "inputCombo"
+                  }
+                },
+                "required": [
+                  "inputType"
+                ]
+              },
+              "then": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "comboItems"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "comboDataSourceName"
+                    ]
+                  }
+                ]
+              }
+            },
+            {
+              "$comment": "inputSearch 는 searchDataSourceName + searchTitle 필수.",
+              "if": {
+                "properties": {
+                  "inputType": {
+                    "const": "inputSearch"
+                  }
+                },
+                "required": [
+                  "inputType"
+                ]
+              },
+              "then": {
+                "required": [
+                  "searchDataSourceName",
+                  "searchTitle"
+                ]
+              }
+            }
+          ]
+        }
+      },
+      "bgColor": {
+        "type": "string",
+        "enum": [
+          "surface",
+          "surface.subtle",
+          "surface.tag",
+          "surface.brand-soft"
+        ],
+        "description": "컨테이너 wrapper 배경 토큰 (_base.style.mjs COLOR 가족 중 surface 톤). 지정 시 wrapper 가 라이트 톤 카드형 쿼리 영역이 되며: 상하 20px Margin + (좌우 10 / 상하 8) Padding 적용, 두 입력 사이 8px gap, 입력 border 는 radius-only(시각 hairline 없음). 미지정 시 wrapper 는 투명, 입력 사이 16px gap, 입력 border 는 1px Gray4 hairline. 일반적 선택: surface.tag (Gray10), surface.subtle (Gray9)."
+      },
+      "override": {
+        "type": "object",
+        "propertyNames": {
+          "enum": [
+            "root",
+            "left",
+            "right"
+          ]
+        },
+        "additionalProperties": {
+          "type": "object"
+        },
+        "description": "(L1 escape hatch) 패턴이 노출하지 않는 raw 엔진 메타데이터를 materialized 트리의 특정 노드에 deep-merge 로 주입한다. anchor 로 위치 지정 — root=외부 Group, left=좌측 입력(inputOptions[0]), right=우측 입력(inputOptions[1]). 값은 엔진 필드 패치 객체이며, 어떤 엔진 스키마에든 정의된 필드명만 검증을 통과한다(예: UseDataConnection, UseMove). 배열 필드는 deep-merge 가 아니라 통째 교체된다. 일반 케이스는 props 로 충분하므로 props 로 표현 못 하는 필드가 필요할 때만 사용.",
+        "examples": [
+          {
+            "left": {
+              "UseDataConnection": true
+            }
+          },
+          {
+            "root": {
+              "UseDataConnection": true
+            }
+          }
+        ]
+      }
+    },
+    "examples": [
+      {
+        "inputOptions": [
+          {
+            "inputType": "inputCombo",
+            "name": "duration",
+            "placeholder": "최근 3개월",
+            "comboItems": [
+              "최근 3개월",
+              "최근 6개월"
+            ]
+          },
+          {
+            "inputType": "inputCombo",
+            "name": "status",
+            "placeholder": "전체",
+            "comboItems": [
+              "전체",
+              "신청",
+              "승인",
+              "완료"
+            ]
+          }
+        ],
+        "bgColor": "surface.tag"
+      },
+      {
+        "inputOptions": [
+          {
+            "inputType": "inputCombo",
+            "name": "replyDept",
+            "caption": "부서선택",
+            "comboItems": [
+              "경영기획팀",
+              "IT전략팀",
+              "시설안전관리팀",
+              "영업팀",
+              "생산팀",
+              "공정개선팀",
+              "제조팀"
+            ]
+          },
+          {
+            "inputType": "inputSearch",
+            "name": "replyUser",
+            "caption": "담당자명",
+            "searchDataSourceName": "UserQuery",
+            "searchTitle": "UserName",
+            "searchKeywordCkey": "UserName"
+          }
+        ]
+      },
+      {
+        "inputOptions": [
+          {
+            "inputType": "inputDate",
+            "caption": "시작일",
+            "placeholder": "YYYY.MM.DD",
+            "dateFormat": "YYYY.MM.DD",
+            "dateSelectType": "SingleDate"
+          },
+          {
+            "inputType": "inputDate",
+            "caption": "종료일",
+            "placeholder": "YYYY.MM.DD",
+            "dateFormat": "YYYY.MM.DD",
+            "dateSelectType": "SingleDate"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skill/references/build-sequence.md

@@ -0,0 +1,55 @@
+# build-sequence — 빌드 시퀀스 상세 (CLI 모드)
+
+SKILL.md §9 만으론 막힐 때 본다. 이 Skill 에는 강제 stage / build_id 개념이 없다 — 본 문서는 **빌드 작업의 자연스러운 순서**를 정리한 것.
+
+## 작업 순서 (강제 stage 없음)
+
+| # | 작업 | 도구 |
+|---|---|---|
+| 1 | 화면 종류 식별 | 사고만 (요청 텍스트 읽기) |
+| 2 | 가장 가까운 example 결정 | `flex-scenario examples list` → `flex-scenario examples cat <name>` (또는 `Read`) |
+| 3 | 적용 패턴 결정 | `patterns-cheatsheet.md` `Read` |
+| 4 | enum 카탈로그 확인 (필요 시) | `flex-scenario catalog --section controlTypes` 등 |
+| 5 | 시나리오 초안 작성 | `Write` (또는 직접 출력) |
+| 6 | 단편 검증 (선택) | `flex-scenario validate --schema <name> <fragment-file>` |
+| 7 | 전체 검증 | `flex-scenario validate <scenario-file>` |
+| 8 | 통과까지 4~7 반복 | — |
+
+강제 stage 가 없으므로 6번은 생략 가능. 7번이 통과하면 끝.
+
+## CLI 인자 요약
+
+```bash
+flex-scenario catalog --section <name>
+   sections: controlTypes / dataUsages / dataSourceTypes / stepTypes / stepDialogTypes /
+             controlKeys / sectorStatuses / conditionOperators / colorTokens /
+             inputTextTypes / inputNumberTypes / inputMaskMaskTypes / controlEvents /
+             stepEvents / calendarSelectTypes (catalog.json 의 키들)
+
+flex-scenario examples list
+flex-scenario examples cat <relative-path>
+
+flex-scenario validate <scenario.json>                # 전체 검증
+flex-scenario validate --schema <name> <fragment.json> # 단편 검증
+   schema names: scenario / step / group / control / data-source / ...
+```
+
+## 검증 실패 시 회복
+
+- `validate --schema=<x>` fragment 단위로 단축 — 큰 시나리오에서 한 위치만 빠르게 점검.
+- `errors[*].kind`:
+  - `schema` / `strict-fields` — JSON Schema 위반 (정의되지 않은 필드 또는 enum/type 불일치). 같은 instancePath 위치를 schema 정의에 맞게 수정.
+  - 그 외 (`step-nav`/`mock-init`/`no-inner-block`/`v1-only`/`no-service`/...) — cross-check 룰. SKILL.md `§금지` 절의 동일 분류명 확인.
+- 같은 에러가 두 번 = 가장 가까운 example 의 해당 영역 다시 본다 (`flex-scenario examples cat`).
+- `errors` 가 가짜로 늘어난다고 느끼면 노이즈 가능성 — 처음 1~2 건만 고치고 재검증.
+
+## 자주 빠뜨리는 부분 (cross-check 관점)
+
+- `Step.Next` 적었으면 트리거 (BottomButton MoveTo:"Next" 또는 Group/Control UseMove:true + MoveSteps) 필수 (`[step-nav]`).
+- 시작 Step.Init 에 사용 카테고리 mock 섹터 (`f.Collection.addSector(..., '<카테고리>')`) 강제 (`[mock-init]`).
+- 카테고리명 `Ctg` 접두 + PascalCase (`[category-name]`).
+- Script Action 본문 화이트리스트 위반 (`[script-allow]`).
+- v1 컨트롤 외 사용 — `catalog.json` 의 `controlTypes` 가 진실원본 (`[v1-only]`).
+- `Service`/`API`/`Collection` DataSourceType 또는 `EmbedScenarioPrefix` 키 등장 (`[no-service]`).
+- `UseInnerBlock`/`InnerBlockKey`/`RepeatStyle` 등장 (`[no-inner-block]`).
+- 같은 ID 가 두 군데 — Dialog 안 Control 까지 합쳐서 (`[id]`).

package/skill/references/patterns-cheatsheet.md

@@ -0,0 +1,87 @@
+# patterns-cheatsheet — 자주 쓰는 패턴 치트시트
+
+SKILL.md 빌드 절차 중 catalog 조회 ~ `flex-scenario validate` 사이에서 막힐 때 본다.
+
+## DataUsage 분기 (Group 의 DataConnection)
+
+| 값 | 동작 | 필수 추가 필드 |
+|---|---|---|
+| `query` | 그룹 자체가 카테고리 섹터 수만큼 복제 — 리스트 카드 1장의 Group 에 박는다 | `Group.ScrollType:"ScrollY"` + `Height.MatchText:true` |
+| `new` | 진입 시 빈 섹터 자동 생성 + 바인딩 — 신규 폼 | `UseNewSector:true` |
+| `update` | activeSector 직접 바인딩 (읽기+쓰기) — 수정 폼 | `UseTargetSector:true` + `TargetSector.Status:["active"]` |
+| `detail` | activeSector 읽기 전용 — 상세 화면 | `UseTargetSector:true` + `TargetSector.Status:["active"]` |
+| `default` | 섹터 없으면 생성, 있으면 기존 | `UseNewSector:true` + `OnlyIfNoSector:true` |
+
+`UseNewSector` / `OnlyIfNoSector` / `UseTargetSector` 는 boolean `true` — 문자열 금지.
+
+## query 그룹 강제 (반복 카드)
+
+리스트 카드 1장을 표현하는 Group:
+```jsonc
+{
+  "ContentsType": "Group",
+  "Id": "f_100",
+  "UseDataConnection": true,
+  "DataConnection": { "DataUsage": "query", "CategoryName": "items" },
+  "ScrollType": "ScrollY",
+  "Height": { "MatchText": true, "SizeValue": "", "SizeUnit": "text" },
+  "Width":  { "MatchText": false, "SizeValue": "100", "SizeUnit": "%" },
+  "Contents": [ /* 카드 내부 컨트롤들 */ ]
+}
+```
+헤더/필터/추가 버튼처럼 1번만 표시할 요소는 **query 그룹 바깥** 비연결 래퍼 Group 에 둔다.
+
+`UseInnerBlock` / `InnerBlockKey` / `RepeatStyle` 절대 등장 금지 — `[no-inner-block]` 후검증에서 차단.
+
+## list-detail 2-step 패턴
+
+- `Step1` (목록): `Contents[]` 안에 헤더 Group(비연결) + 카드 Group(`DataUsage:"query"`). 카드 Group 에 `UseMove:true` + `MoveSteps.MoveStepOrder:["Step2"]` + `MoveSteps.Step2:{}` 옵션 객체.
+- `Step2` (상세): `Contents[]` 안에 `DataUsage:"detail"` (또는 `update`) Group. `BackButton.Next:"None"`.
+- `Step.Next:["Step2"]` (Step1) — `MoveSteps` 가 트리거 역할. `[step-nav]` 후검증 통과.
+
+`MoveSteps` 는 배열이 아니라 **순서 배열 + StepId 별 옵션 객체** 가 같은 레벨에 공존하는 구조:
+```jsonc
+"MoveSteps": { "MoveStepOrder": ["Step2"], "Step2": { /* options */ } }
+```
+옵션 객체 누락 시 런타임 TypeError.
+
+## 단순 입력 폼 (1-step)
+
+`StartSteps:["Step1"]`. `Step1` 안 `Contents[]` 에 `DataUsage:"new"` Group 1개. 그 안에 InputText/InputDate/Combo/MultiInputBox 등. `Step.BottomButtons:[{ MoveTo:"Save", ... }]` 또는 `MoveTo:"Next"` + 다음 Step 으로 이동.
+
+폼 컨트롤은 자신의 상위 Group 어딘가에 `UseDataConnection:true + DataConnection` 이 있어야 동작 (직계 부모 아니어도 됨, rules.md §5.1).
+
+## 다이얼로그형 컨트롤 (InputDate / Combo / Search)
+
+`isLeaf:false` 라 자식 트리를 가진다 — `Dialog.Layouts[0].Controls[0]` 위치에 sub-control:
+
+- `InputDate.Dialog.Layouts[0].Controls[0]` = `Calendar` (CalendarType: day/month/year, SelectType: SingleDate/FromTo)
+- `Combo.Dialog.Layouts[0].Controls[0]` = `ComboList` (8개 이하 고정 목록은 Items[], 그 이상이면 DataSource)
+- `Search.Dialog.Layouts[0].Controls[0]` = `List` (키워드 검색 + DataSource 필수)
+
+세 컨트롤 모두 `DisplayType` 미지정 시 `CtrlDisplayCkey` 모드. `DisplayValue` 모드를 쓰려면 명시 + 표현식 등록.
+
+## ID·Caption·이벤트 자주 빠뜨리는 것
+
+- Control `Caption` 은 빈 문자열 허용 (`Embed` 는 반드시 `""`).
+- `BottomButton.MoveTo:"Prev"` = 캐시 복원 (Init/Loaded 안 돔), `"Prev_ReStart"` = 재시작. Chart/Map/Timer 가 있으면 `Prev_ReStart`.
+- Step Events 호스트별 EventOrder 키:
+  - Step: `StepEventOrder` — `Init`/`Loaded`/`OnBackLoaded`/`OnLeave`/`OnForeground`/`ScrollEnd`
+  - Group: `ContentEvent` — `Click`/`ScrollEnd`
+  - InputText/MultiInputBox: `InputEventOrder` — `change`/`input`/`focusin`/`focusout` (소문자)
+  - InputNumber/InputMask: `InputEventOrder` — `change` 만
+  - Combo: `ComboOrder` — `change`/`DialogClose`
+  - Search: `SearchOrder` — `change`/`Delete`/`DialogClose`
+  - InputDate: `DateOrder` — `DialogClose`
+- 이벤트 핸들러 이름은 `scenario.Events` 의 키와 일치 (`[event-ref]` 후검증). 사용 안 하는 핸들러는 키 자체를 안 만든다.
+
+## ServiceBinding / DataSource
+
+- `scenario.ServiceBinding: {}` 빈 객체. `SystemID`/`ModuleID`/`ServiceName` 등 어떤 키도 추가 금지.
+- `DataSources[*].DataSourceType` 은 `Fixed` 또는 `Grid` 만. `Service`/`API` 는 `[no-service]` 차단.
+
+## Tab / Tree / Embed 짧은 가이드
+
+- `Tab` (`hasDialog:null`): `Items[].LinkedStepId` 로 다른 Step 의 화면을 내부에 렌더. `Height:"100%"` 필수, 자기 Step 자기 참조 금지. LinkedStep 내부 Step Event 는 실행 안 됨 — 초기화는 부모 Step `Init` 에 통합.
+- `Tree` (`UseMultiData:true` 면 다중 체크): NodeId/ParentId/Title 로 flat array. 이벤트는 `TreeOrder` + `Selected`/`Checked`, `Click:""` 빈 문자열 필수.
+- `Embed`: `Caption:""`. raw HTML 만 — `<script>` 직접 삽입 금지. 외부 라이브러리는 Step `Loaded` 에서 `f.Script.load()` + 유니크 id 의 div/canvas.

package/skill/references/spec-evolve/README.md

@@ -0,0 +1,43 @@
+# spec-evolve — 스펙 진화 하네스 (명시 호출 경로의 Phase 1)
+
+> **이 하네스는 기본 경로가 아니다.** scenario-gen 의 기본은 스펙 없이 바로 생성이고(SKILL.md "진입 분기"), 이 하네스는 사용자가 **`/flex-spec` 슬래시 커맨드로 진입했거나 명시적으로 스펙 단계를 요청한 경우에만** 탄다. 막연한 입력이라는 이유만으로 여기로 강제되지 않는다.
+
+raw 입력(화면정의서 엑셀/표/텍스트/캡처, 데이터구조 동봉 요청, 막연한 한 줄 요청)을 **곧바로 시나리오로 만들지 않고**, 먼저 구체화된 중간 스펙 `<name>.spec.md` 으로 "진화"시킨다. 그 스펙이 SKILL.md "시퀀스 3. 요청 분석"의 입력이 된다.
+
+목적: 추론(마스터-디테일·키·데이터연결·조회조건 분리)을 **생성 본문과 분리**해, 사람이 검토 가능한 중간 산출물로 남기고 재현성을 높인다.
+
+## 세 Phase
+
+- **Phase 1 — 스펙 진화** (이 폴더): raw 입력 → `<name>.spec.md` (frontmatter + Step별 본문). 절차는 아래.
+- **Phase 2 — 시나리오 생성** (SKILL.md 본문 시퀀스): `.spec.md` 본문을 "요청"으로 보고 평소대로 노드 빌드 + `flex-scenario validate`. 별도 hand-off 도구 없음 — **같은 스킬 안에서 그대로 이어서 진행**한다.
+- **Phase 3 — 데이터연결 보장 게이트** (`data-connection.md` "★ 생성 후 데이터연결 보장 게이트"): 산출 시나리오에 데이터연결이 빠졌으면(목록·조회·반복·M-D 화면인데 `DataConnection`/`intent.mock` 0건) **통과시키지 말고**, `ok:true` 가 보증된 유사 구조 `design/` 샘플과 key-diff 해 **추가 수정으로 주입**한 뒤 재검증한다. 이건 `lint.md`(비블로킹 보고)와 달리 **블로킹**이다 — 스펙 경로의 핵심 보장.
+
+## Phase 1 절차 (이 순서)
+
+1. **인테이크** — 입력 모달리티 식별 → 모달리티 무관 필드 목록으로 정규화. 캡처면 `Read` 로 이미지 직접 판독. → `intake.md`
+2. **라우팅** — "데이터 구조 신호" 유무로 A(정적)/B(데이터연결) 결정. 구조 제공 시 그대로 따르고 부가정보는 보조 병합, 미제공 시 코퍼스 추론. → `routing.md`
+3. **필드 플랜 + keyRole** — 각 필드에 `keyRole`(master/detail/link/none/provisional). 카디널리티로 판정, 불확실하면 `provisional`+flag 하고 멈추지 않는다. → `key-roles.md`
+4. **데이터연결 설계 (B 경로)** — 마스터-디테일을 부모 query + 자식 query(Parent 필터+조인키) + detail 로 매핑. → `data-connection.md`
+5. **목업데이터 추정·세팅** — 구조 제공이든 미제공이든 화면을 현실적 목업으로 채운다(빈 화면 금지). 미제공이면 카테고리·필드·값을 추정. → `mockup.md`
+6. **조회 화면 분해** — 조회조건이 많으면(≥5) 별도 Step 으로 분리. → `query-screens.md`
+7. **컨벤션 적용** — 의도→컨트롤 매핑, 날짜 등 기본값, 마스터-디테일 레이아웃 골격. → `conventions.md`
+8. **스펙 작성** — `<name>.spec.md` 를 `spec-format.md` 형식으로 쓴다. 추론 가정·provisional·mock 을 frontmatter/본문에 명시. 템플릿은 `templates/` 참조. → `spec-format.md`
+
+이후 Phase 2(SKILL.md 시퀀스로 생성) → **Phase 3 데이터연결 보장 게이트** 로 이어진다.
+
+9. **데이터연결 보장 게이트** (Phase 2 생성 직후, 블로킹) — 산출 시나리오에 데이터연결이 빠졌으면 유사 구조 `design/` 샘플(validate `ok:true` 확인)과 key-diff 해 `Edit` 로 주입 후 재검증. → `data-connection.md` "★ 생성 후 데이터연결 보장 게이트"
+
+## 산출 위치
+
+- 중간 스펙: `./<name>.spec.md` (현재 작업 폴더 cwd)
+- 이후 시나리오: `./<name>-scenario.json` (현재 작업 폴더 cwd · SKILL.md 산출 규칙과 동일)
+
+## 자기완결 원칙
+
+이 하네스가 참조하는 모든 정본(스펙 형식·예시·컨벤션)은 **이 폴더 안에 번들**되어 있다. 레포 전용 경로(`bench/cases`, `sample_spec` 등)를 런타임에 참조하지 않는다 — 배포 환경엔 없다. 시나리오 형식/스키마/검증은 같은 스킬에 동봉된 `docs/`·`schemas/`·`flex-scenario validate` 를 쓴다.
+
+## 비블로킹 원칙 (게이트와 구분)
+
+불확실한 키·추론 가정 때문에 진행을 멈추지 않는다. `provisional` 로 두고 Phase 2 까지 흘린 뒤, 최종 응답에서 lint 가 "미해결"로 보고한다. → `lint.md`
+
+> 단, **Phase 3 데이터연결 보장 게이트는 비블로킹이 아니다.** keyRole 추론의 불확실성은 `provisional` 로 흘려보내도 되지만, 목록·조회·반복 화면에 데이터연결 자체가 0건인 것은 보고만 하고 넘기지 않고 **샘플 참조로 주입해 고친 뒤** 통과시킨다(`data-connection.md`).

package/skill/references/spec-evolve/conventions.md

@@ -0,0 +1,92 @@
+# conventions — 코퍼스에서 증류한 컨벤션 (자기완결)
+
+실무 화면정의서/시나리오 코퍼스에서 뽑은 규칙. 배포 환경에 원본이 없으므로 여기 본문에 박는다. 이는 **기본값/힌트**이지 화면정의서가 있어야만 작동하는 강제 규칙이 아니다 — 일반 요청에도 적용한다.
+
+## 1. 의도 → v1 ControlType 매핑
+
+| 의도 (어떤 입력에서든 추론) | v1 ControlType | 비고 |
+|---|---|---|
+| 정적 표시·단건 라벨 | `Label` (`LabelType:"labeltext"` + `labeltext`) | 정적(A). 반복/선택 아님 |
+| 선택지(콤보/드롭다운) | `Combo` (+ Dialog `ComboList`) | Dialog host 필수 |
+| 날짜/기간 | `InputDate` (+ Dialog `Calendar`) | Dialog host 필수 |
+| 코드도움/검색 팝업 | `Search` (+ Dialog `List`) | Dialog host 필수 |
+| 숫자/수량 | `InputNumber` (`InputType:"number"`) | 천단위 콤마는 옵션 |
+| 자유 텍스트 | `InputText` | |
+| 멀티라인 텍스트 | `MultiInputBox` | 사유/목적/비고 |
+| 반복 목록(디테일) | B: `DataUsage:"query"` 반복 Group / A: 행 복제 | `data-connection.md` |
+
+### ★ 컨트롤타입이 명시되면 직역(고정 매핑). 의도 추론으로 흔들지 말 것
+
+화면정의서/표에 **컨트롤타입 컬럼이 명시**되면 아래대로 **직역**한다. 항목설명의 "조회/원천/참조" 같은 단어에 휘둘려 다른 컨트롤로 바꾸지 않는다(이게 대표 오매핑이다).
+
+| 명시 표기 | → v1 | 절대 금지 오매핑 |
+|---|---|---|
+| `label` | **`Label`** (읽기전용 표시) | ❌ label 을 `Search`/`InputText`/`Combo` 로 만들지 말 것. "원천 ~조회" 는 데이터 출처 설명일 뿐, 컨트롤은 Label |
+| `Codehelp` / 코드도움 | **`Search`** (+Dialog `List`, `CtrlDisplayCkey` 필수) | ❌ `InputText` 로 떨어뜨리지 말 것 — 키 연결(코드도움 표시키)이 끊긴다 |
+| `ComboBox` / 콤보 | **`Combo`** (+Dialog `ComboList`) | |
+| `DateBox` / 날짜·기간 | **`InputDate`** (+Dialog `Calendar`) | |
+| `FloatBox`·`NumberBox` / 숫자 | **`InputNumber`** | |
+| `TextBox` / 텍스트 | **`InputText`** | |
+
+- 표기가 **없을 때만** 위 "의도 → 컨트롤" 표로 추론한다.
+- **읽기전용 표시 필드(label)는 화면에 그대로 다 Label 로 만든다** — 표시 항목이 10개면 Label 10개(S-03 실패: label 다수를 Search 로 띄워 입력 천지가 됨).
+- **코드도움 조회조건은 반드시 `Search` + `CtrlDisplayCkey`**(선택값 표시키, 예 `customerName`) — `InputText` 금지(S-05 실패: 키 연결 끊김). `display-key` cross-check 와 동일 원칙.
+- **콜렉션키 명명**: `Ckeys`/`LabelCKey`/`CtrlDisplayCkey` 값에 **`f` 접두 금지**.
+  - **스펙(화면정의서)에 키/필드명이 명시되면 그 대소문자·표기를 그대로 사용**한다 — 임의로 camelCase 로 바꾸지 말 것. 식별자로 못 쓰는 공백/특수문자만 제거하고 대소문자는 보존 (예: `Lot No`→`LotNo`, `B/L NO`→`BLNO`, `품번`은 영문 키가 없으면 의미있는 영문으로).
+  - 구조 미제공(추론)일 때만 의미있는 camelCase (예: `customerName`·`scanQty`). ❌ `fCustomer`·`fLotNo`.
+  - 예약어 금지는 `naming-objects.schema.json`.
+> Combo/Search/InputDate 는 본체에 Dialog host(`Dialog.Layouts[0].Controls[0]` = ComboList/List/Calendar)가 없으면 런타임 TypeError. 정본 `docs/control/*.md`.
+
+### ★ 고정 선택지(Combo/Search 고정모드) — CtrlDisplayCkey ↔ SaveNameKey/SaveValueKey 매칭
+
+`UseDataSource:false` + 고정 옵션(`Items`)으로 만드는 Combo/Search 는 본체 표시키와 자식 옵션키가 **반드시 같은 이름**이어야 선택값이 본체에 보인다(안 맞으면 선택해도 빈칸 — S-05/S-09 실패):
+
+- 자식 ComboList/List: `SaveNameKey`(표시키) / `SaveValueKey`(저장키). 옵션 `Items` 가 그 두 필드를 보유.
+- 본체 `CtrlDisplayCkey` = 자식 **`SaveNameKey` 와 동일한 이름**으로 둔다(표시는 이름키).
+- 표준: `Items:[{ItemName, ItemValue}, ...]` → `SaveNameKey:"ItemName"`, `SaveValueKey:"ItemValue"`, **`CtrlDisplayCkey:"ItemName"`**.
+- ❌ `CtrlDisplayCkey:"BizUnit"`(도메인 키)인데 `SaveNameKey:"ItemName"` 처럼 어긋나게 두지 말 것. 도메인 의미를 키 이름에 담고 싶으면 SaveNameKey/SaveValueKey/CtrlDisplayCkey 를 **셋 다 같은 체계**로(예 `SaveNameKey:"bizUnitName"`, `CtrlDisplayCkey:"bizUnitName"`, Items 필드도 `bizUnitName`). `[combo-fixed]` cross-check.
+
+## 2. 표시 등급 (항목사용여부)
+
+- `숨김` → **노드 생성 제외.** 보통 저장 시 시스템이 채우는 키(자동채번·현재일·로그인 부서/사원·사업단위 디폴트).
+- `중요` → 강조 스타일(굵게/색).
+- `표시` → 일반.
+
+## 3. 기본값 패턴 (항목설명 단서 → 기본값)
+
+| 단서 | 해석 |
+|---|---|
+| `현재일`, 시스템 현재일 저장 | 오늘 날짜 |
+| `From: 현재일 -1month, To: 현재일` | InputDate 기간 기본값 (한 달 전 ~ 오늘) |
+| `From: 현재일 -1week, To: 현재일 +1week` | 기간 기본값 (1주 전 ~ 1주 후) |
+| `"<고정값>" 디폴트` 등 고정 선택값 | Combo 기본 선택 |
+| `자동채번` | 숨김 + 저장 시 채움 (노드 X) |
+
+프로토타입이므로 날짜는 **현실적 리터럴**로 박아도 된다(예: 오늘이 기준이면 그 근방). B 경로 mock 도 현실적 값으로.
+
+## 4. 마스터-디테일 레이아웃 골격 (그룹을 한두 겹 더 감싼다)
+
+- **마스터** = 헤더/요약 Group (식별자 + 합계/상태). 단건. 표시 라벨은 가능하면 마스터 mock 섹터에 `LabelCKey` 바인딩(정적은 진짜 고정 문구만).
+- **디테일** = 반복 영역. B 면 부모 query Group 안 자식 query Group(Parent 필터), A 면 같은 행 Group 을 복제(`row`, `row_copy`).
+- **중첩 래핑(중요)**: 정답은 반복 영역을 여러 겹 감싼다(깊이 6~8). 얕으면 실패.
+  - 조회: `스크롤 Group(ScrollY) > 리스트 Group(query) > row Group > [마스터섹션 + 디테일섹션]`
+  - 입력: `마스터 Group(흰 배경) + graybg Group(회색,ScrollY) > contentsWrap(흰 박스) > 리스트 Group > row`
+  - `UseDataConnection:true` 는 반복이 일어나는 그 Group 에만, 바깥 스크롤 래퍼는 false. 상세는 `data-connection.md`.
+- 디테일 행에 행삭제(입력), 펼치기/상세(조회)를 둘 수 있다.
+
+## 5. 입력 화면 vs 조회 화면 + 네비 규칙
+
+| | 입력 | 조회 |
+|---|---|---|
+| 마스터 | 읽기전용 표시(Label, 가능하면 바인딩) + 일부 입력(Combo/InputNumber). 종속 선택은 `data-connection.md` | **조회조건은 상단 `FixedContentsTop`** (Combo/InputDate/Search) — 많으면 별도 Step (`query-screens.md`) |
+| 디테일 | 스캔/추가로 쌓이는 품목(키+수량), 행삭제 | 결과 리스트 반복(스크롤 래핑) + 펼치기 상세 |
+| 이벤트 | 저장/삭제/신규 (하단 BottomButtons) | 조회 |
+| 네비 | BottomButtons MoveTo:Next/Prev, 결과/확인 Step | 상단에서 조건 Step 진입(UseMove), 복귀는 UseBackButton 표준 |
+
+- **네비 채널은 4개만**(`skill-guides/step-navigation.md` 정본): StartSteps / 하단 `BottomButtons.MoveTo` / 리스트 카드 `UseMove`+`MoveSteps` / 헤더 `UseBackButton`. 스크립트 흐름제어(`Current.step.moveToPrev/Next`)는 **금지**.
+- 첫 입력화면 `UseBackButton:false`, 상세/결과화면 `true`.
+- **부가 네비 버튼 금지(★)**: `바로가기` · `메인메뉴` · `조회조건 펼치기/접기` 같은 라벨 버튼을 **만들지 않는다**. 화면정의서 '추가공유내용'에 그런 문구가 있어도 버튼으로 옮기지 말 것 — 이동은 Step 전환 채널로만 표현한다. 숨겨야 할 부가 액션은 `BottomButtons` 의 `ControlKey:"Hide"` 로.
+
+## 6. 정적 vs 동적 (A vs B) 노드별 판정
+
+SKILL.md "데이터 표시 결정"과 동일: 고정 문구·캡션·단건 = 정적 Label, 반복 렌더·선택지·Calendar 데이터 = 동적 DataConnection + Init mock. 한 화면에서 혼재 가능.