@flextudio/scenario 0.1.0

package/commands/flex-spec.md

@@ -0,0 +1,28 @@
+---
+description: flextudio 시나리오를 스펙 기반으로 생성하는 커맨드. 곧바로 화면을 만들지 않고 먼저 중간 스펙(.spec.md)으로 마스터-디테일·키·데이터연결을 확정한 뒤, 그 스펙대로 시나리오를 생성하고 데이터연결 보장 게이트까지 거친다. 스펙 단계가 필요할 때만 명시 호출 (기본은 스펙 없이 직접 생성).
+argument-hint: <화면 요청 / 화면정의서 / 데이터구조>
+---
+
+# /flex-spec — 스펙 기반 생성 (명시 진입)
+
+이 커맨드는 **`scenario-gen` 스킬을 스펙 경로(spec-evolve 하네스)로 강제 진입**시키는 전용 입구다.
+평소(자동 트리거·`/scenario-gen`)의 **기본은 스펙 없이 직접 생성**이고, 사용자가 이 커맨드로 들어온 경우에만 **중간 스펙(`<name>.spec.md`)을 먼저 진화시킨 뒤** 생성한다. 절차의 정본은 scenario-gen 스킬의 `SKILL.md` 와 `references/spec-evolve/` 이며, 이 커맨드는 그 경로를 **켜는 신호 + 데이터연결 보장 게이트**만 더한다.
+
+사용자 요청:
+
+> $ARGUMENTS
+
+## 반드시 이 순서로
+
+1. **스펙 경로 강제** — 직접 생성 경로로 직행하지 말 것. `scenario-gen` 스킬을 사용하되, 먼저 `references/spec-evolve/README.md` 를 Read 하여 **Phase 1(스펙 진화)** 부터 시작한다.
+2. **Phase 1 — 스펙 진화** — `references/spec-evolve/` 절차(intake → routing → key-roles → data-connection → mockup → query-screens → conventions → spec-format)로 위 요청을 `./<name>.spec.md` (현재 작업 폴더 cwd) 로 진화시킨다. 추론한 마스터-디테일·키·목업은 frontmatter/본문에 기록하고, 불확실하면 `provisional` 로 둔 채 멈추지 않는다.
+3. **Phase 2 — 시나리오 생성** — `.spec.md` 본문을 SKILL.md "시퀀스 3. 요청 분석"의 입력으로 삼아 평소대로 노드를 빌드하고 `flex-scenario validate` 로 자가검증 루프를 통과시킨다.
+4. **★ 데이터연결 보장 게이트 (이 경로의 필수 추가 단계)** — Phase 2 산출 시나리오를 점검한다. 화면이 **목록·카드·"~별"·"~내역"·조회·반복·선택지(Combo/Search)** 성격인데 `UseDataConnection:true` + `DataConnection` + 시작 Step.Init `intent.mock` 이 **0건이면 통과시키지 말 것**:
+   - `examples/index.json` 에서 **구조(`stepCount`/`patterns`/`controlTypes`)가 유사한 `design/` 샘플 시나리오**를 고르고, **반드시 먼저 `flex-scenario validate --no-write <후보 example>` 로 `ok:true` 를 확인**한다 (★ example 검증엔 `--no-write` 필수 — 기본 validate 는 `ok:true` 시 본문을 입력 파일에 write-back 해 참조 예제를 변형시킨다).
+   - 그 샘플의 데이터연결 노드(부모 query → 자식 query(Parent 필터·조인키) → detail, `LabelCKey`/`Ckeys` 바인딩, named-handler `intent.mock`)와 내 산출물을 **key-diff** 한다.
+   - 빠진 데이터연결을 `Edit` 로 **추가 수정**해 주입한다 — 정적 `Label` 복제로 도망가지 않는다. 단건 마스터/헤더도 정적으로 두지 말고 `DataUsage:"default"` + `LabelCKey` 로 바인딩한다. 규칙 정본: `references/spec-evolve/data-connection.md`, `references/spec-evolve/mockup.md`.
+   - 진짜 단건 정적 표시(고정 문구뿐)거나 실제 `scenario.DataSources`(Fixed/Grid)가 채워진 경우만 예외로 데이터연결 없이 통과.
+   - 수정 후 `flex-scenario validate <scenario>` 를 다시 통과시킨다.
+5. **산출** — `flex-scenario session finish` 의 `artifact` 경로(`.spec.md` + `-scenario.json`)를 답에 명시한다. 추론 가정·provisional 미해결이 있으면 `references/spec-evolve/lint.md` 형식으로 1블록 보고(비블로킹).
+
+> 한 줄 요약: **기본은 `/flex-spec` 없이 바로 생성. 이 커맨드는 "스펙을 거쳐 + 데이터연결을 끝까지 보장해" 달라는 명시 요청이다.**

package/contract-data/README.md

@@ -0,0 +1,267 @@
+# meta-contract
+
+flextudio 화면 메타(`scenarioMeta`)의 **계약(Contract)** 정의. AI 메타 자동 생성(설치형 CLI + Claude Code Skill)에 컨텍스트로 사용된다.
+
+## 무엇인가
+
+flextudio 스튜디오와 런타임이 공유하는 화면 메타(JSON) 구조를 사람과 AI 양쪽이 읽을 수 있는 형식으로 명세한 것.
+
+본 컨트랙트는 self-contained — schema/md/catalog 안에 필요한 모든 규칙·카탈로그가 박혀 있어야 하며, 외부 문서로의 줄번호 참조는 두지 않는다 (외부 문서가 변경되면 깨지기 때문). 실제 시나리오 샘플과 런타임 코드의 변경 사항은 본 컨트랙트로 흡수해 반영한다.
+
+## 폴더 구조
+
+```
+meta-contract/
+├── README.md                              # 이 파일
+├── spec/                                  # 계약 데이터 (core 가 읽는 top-level + CONTRACT_ROOT 마커)
+│   ├── rules.md                           # 공통 규칙 (ID/명칭/discriminator/트리/데이터바인딩/스타일)
+│   └── catalog.json                       # 카탈로그 (stepTypes, controlTypes 등)
+├── schema/v1/
+│   ├── scenario.md  scenario.schema.json  # 루트 = scenarioMeta (Steps Map + 상위 메타데이터)
+│   ├── node.md      node.schema.json      # Group | Control 2-union (Group.Contents 자식)
+│   ├── step.md      step.schema.json      # StepType + StepDialogType 분기
+│   ├── group.md     group.schema.json     # ContentsType="Group" 단일
+│   ├── control.md   control.schema.json   # Control 디스패처 (oneOf → control/*)
+│   ├── control/                            # 컨트롤별 스키마/문서
+│   │   ├── _base.schema.json               #   controlBase / inputBase / dialogLayout / calendarControl 공통 $defs
+│   │   ├── input-text.{schema.json,md}
+│   │   ├── input-number.{schema.json,md}
+│   │   ├── input-mask.{schema.json,md}
+│   │   ├── input-date.{schema.json,md}
+│   │   ├── multi-input-box.{schema.json,md}
+│   │   ├── combo.{schema.json,md}
+│   │   ├── search.{schema.json,md}
+│   │   ├── check-box.{schema.json,md}
+│   │   ├── radio-box.{schema.json,md}
+│   │   ├── label.{schema.json,md}
+│   │   ├── image-box.{schema.json,md}
+│   │   ├── input-file.{schema.json,md}
+│   │   ├── calendar.{schema.json,md}             #   Calendar (InputDate 자식 또는 단독)
+│   │   ├── calendar-navigator.{schema.json,md}   #   CalendarNavigator (TimeTable 내부 또는 독립)
+│   │   ├── tab.{schema.json,md}                  #   Tab (Items[].LinkedStepId 로 Step 임베드)
+│   │   ├── tree.{schema.json,md}                 #   Tree (계층형 flat array, NodeId/ParentId/Title)
+│   │   ├── embed.{schema.json,md}                #   Embed (raw HTML, f.Script.load 외부 라이브러리 연동)
+│   │   └── other.schema.json               #   v1 외 ControlType fallback
+│   ├── style-objects.md  style-objects.schema.json   # 디자인/레이아웃 공통 카탈로그 (size/spacing/display/font/border/bg/caption/color)
+│   ├── data-objects.md   data-objects.schema.json    # 데이터 바인딩 카탈로그 (dataConnection/sectorFilter, DataUsage 5종, Filter 4종)
+│   ├── data-sources.md   data-sources.schema.json    # DataSources 카탈로그 (Fixed/Grid/Collection/Service/API 5종)
+│   ├── events.md         events.schema.json          # scenario.Events 핸들러 맵 (Script/LinkedEvent/Service/API 4분기 + ParamBlock/ResultBlock/InnerBlock + 호스트별 EventOrder)
+│   ├── service-binding.md service-binding.schema.json # scenario.ServiceBinding 관용 스키마 (AI 생성 시 비어있는 객체만 허용)
+│   ├── service/                                       # 서비스 종류별 분기 스키마 + API 연동 가이드 (운영 메타 검증용)
+│   │   ├── README.md                                  #   인덱스 + 6종 비교표 + 분기 결정 규칙
+│   │   ├── _base.schema.json                          #   commonBase $defs (모든 서비스 공통)
+│   │   ├── FlexSQL.{schema.json,md}                   #   SystemID='FlexSQL'        — 워크스페이스 SQL 호출 (SQLServiceName "시나리오:서비스")
+│   │   ├── FlexAutoQuery.{schema.json,md}             #   SystemID='FlexAutoQuery'  — FlexDB 자동 CRUD (ServiceType/TargetTable/OrderBy)
+│   │   ├── ksystem.{schema.json,md}                   #   SystemID='ksystem'        — 영림원 ksystem (FlexAPI/OpenAPI/Codehelp/Ksystem/Filehelp + UseTable/SPList)
+│   │   ├── Firestore.{schema.json,md}                 #   SystemID='Firestore'      — Google Firestore (Query/Save/Update/Delete + Collection)
+│   │   ├── GoogleSheet.{schema.json,md}               #   SystemID='GoogleSheet'    — Google Sheet (Query/Append/Update/Clear + SpreadsheetId/SheetName/BaseColumn)
+│   │   ├── Flextudio.{schema.json,md}                 #   SystemID='Flextudio'      — 워크스페이스 내장 (GetUserList/QueryMessage/SendMessage)
+│   │   ├── Flextudio API.{schema.json,md}             #   SystemID='Flextudio API'  — 사용자/메시지/그룹 REST API (flexApiKey + ModuleID + SubModuleID)
+│   │   └── CustomSystem.{schema.json,md}              #   SystemType='CustomSystem' (Action='API') — SystemID='New_NN' + GUID ModuleID + fEventKey/fEvent
+│   └── design-system/                                 # 디자인 시스템 (인덱스 + 가이드)
+│       ├── README.md                      # 인덱스 사용법 / 외부 가이드 차용 워크플로우
+│       └── assets.json                    # 평탄 인덱스 174항목 (color/typography/spacing/composition/naming/control/binding/policy/capability)
+├── examples/                              # 카테고리별 분류 — 13/16 검증 통과
+│   ├── README.md
+│   ├── minimal/                           # 골격(skeleton) — 디자인 토큰 없음. 구조/패턴 검증용
+│   │   ├── basic-list-detail.json         # 기본형태-0단계 (List → Input → Detail)
+│   │   ├── list-with-filters.json         # 기본형태-1단계 (Combo 필터)
+│   │   ├── search-period-popup.json       # 기본형태-조회강화형 (InputDate 기간 + Search + PopUp)
+│   │   └── fixedtop-floating-form.json    # 기본형태-혼합강화형 (FixedTop + Floating)
+│   ├── basic/                             # 단순 1~3 step + 디자인 적용
+│   │   └── delivery-address-popup.json    # 배송지 변경 PopUp (2 steps)
+│   ├── enhanced/                          # multi-step + dialog (PopUp/SlideUp) + 디자인
+│   │   ├── trade-statement-list.json      # 거래명세서 조회 (PopUp + SlideUp)
+│   │   ├── asset-management.json          # 자산관리 템플릿
+│   │   ├── appointment-booking.json       # 약속잡기 (5 steps)
+│   │   ├── work-report.json               # 구매 발주 관리
+│   │   ├── salary-contract.json           # 연봉계약 (Signature)
+│   │   └── fuel-cost-status.json          # 유류비 자동등록
+│   ├── complex/                           # 5+ steps + 깊은 중첩 (4~7 레벨)
+│   │   ├── trade-statement-input.json     # 거래명세서 입력 (PDA, 7 steps)
+│   │   ├── order-management.json          # 오더관리 (7 steps)
+│   │   ├── crm-main.json                  # CRM 메인 (4 steps, deep nest)
+│   │   └── field-work-register.json       # 외근등록 (13 steps + StepSub)
+│   └── tile/                              # 타일/그리드 카드 패턴
+│       └── second-hand-marketplace.json   # 중고거래 마이페이지 (9 steps)
+└── validate.mjs                           # ajv 셀프 검증 스크립트
+```
+
+## 핵심 구조 (요약)
+
+```
+scenarioMeta (root)
+├── modules, htmlkey, ScenarioTitle, fScenarioName, fConverterVersion
+├── StartSteps: ["Step1", ...]
+├── Steps: {                              ← 객체(Map). 키가 StepId.
+│     "Step1": Step,
+│     "Step2": Step,
+│     ...
+│   }
+├── Language, Events, ServiceBinding, Collections
+├── DataSources: { <name>: { DataSourceType, ... } }   ← Fixed/Grid (AI 샘플 가능) | Collection/Service/API (운영 전용)
+├── Scenario: { StyleURLs }
+└── Panel: { Collection, Category, ... }
+
+Step
+├── StepType: "StepView" | "StepSub"
+├── StepDialogType: "" | "SlideUp" | "PopUp"  (StepView 변종)
+├── StepName, StepTitle
+├── Contents: Group[]                     ← 메인 (스크롤 영역)
+├── FixedContentsTop: Group[]             ← 탭/검색/필터 전용
+├── FixedContentsBottom: Group[]          ← 액션바 전용
+├── BottomButtons: BottomButton[]         ← 하단 버튼 채널
+├── BackButton: { Next: "None", IsRestored }
+├── Next: ["StepN", ...]                  ← 배열, forward-only
+└── Events: { StepEventOrder, Init, Loaded, ... } | []
+
+Group
+├── Id: "f_xxx"
+├── ContentsType: "Group"                 ← 단일 (Layout 통합됨)
+├── ContentsName, ContentStyle
+├── Width, Height (sizeObject)
+├── UseDataConnection + DataConnection    ← 데이터 바인딩
+├── DisplayStyle, BgStyle, BorderStyle, Padding, Margin
+├── ScrollType, UseEmptyView, UseAbsoluteLayout, AbsolutePosition
+└── Contents: (Group | Control)[]
+
+Control
+├── Id: "f_xxx"
+├── ControlType: 10종 (catalog.json 참조)
+├── ControlDefaultName, ControlName2(필수), ControlName, Caption
+├── ControlKey: "" | "Required" | "ReadOnly" | "Hide" | "Disabled"
+├── Ckeys, DefaultValue, Placeholder, Maxlength
+├── isColumnCtrl: false
+├── Width, Height, FontStyle, BorderStyle, BgStyle, CaptionStyle, Padding, Margin
+├── Events, LoadScript
+└── Dialog: { Layouts: [{ Controls: [...] }] }   ← InputDate (Calendar) / Combo (ComboList) / Search (List)
+```
+
+## v1 컨트랙트 범위
+
+### 노드
+- **Step**: `StepView` (`""`/`SlideUp`/`PopUp`), `StepSub`
+- **Group**: 단일 (Layout 흡수). DataConnection 5종 (`default`/`new`/`update`/`detail`/`query`)
+- **Control 15종**: `InputText`, `InputNumber`, `InputMask`, `InputDate`, `MultiInputBox`, `Combo`, `Search`, `CheckBox`, `RadioBox`, `Label`, `ImageBox`, `InputFile`, `Tree`, `Tab`, `Embed`
+
+### 범위 외 (v2 후속)
+- 다른 ControlType (`InputBox`, `Button`, `Tab`, `Sheet`, `TimeTable`, `Approval`, `Tree`, `Image`, `Calendar`(단독), `ComboList`(단독), `List`(단독), `Embed`, `Signature`, `Line` 등) — `OtherControl` fallback 으로 통과만 시킴
+- ServiceBinding 상세 schema
+- Events 핸들러 상세 schema
+- DataSources Fixed/Grid/Service/Collection 상세
+- LoadScript / Event Script DSL 검증
+
+v1 컨트랙트는 위 범위 외 노드도 `additionalProperties: true` 로 받아넘기므로 **부분 검증**은 통과한다.
+
+## 사용
+
+```bash
+node meta-contract/validate.mjs                              # examples/*.json 자체 검증 (전체 시나리오 + 모든 cross-check)
+node meta-contract/validate.mjs path/to/scenario.json ...    # 임의 시나리오 메타 검증
+SAMPLE_DATA_STRICT=0 node meta-contract/validate.mjs ...     # 운영 메타 검증 모드 (Service/API DataSource 허용)
+node meta-contract/validate.mjs --list                       # 등록된 모든 schema 목록 (file key / shorthand / $id)
+node meta-contract/validate.mjs --schema=<ref> path.json     # 특정 schema 로 단편(fragment) 검증
+node meta-contract/validate.mjs -s <ref> path.json           # short flag
+```
+
+### `--schema=<ref>` 단편 검증
+
+AI 가 생성한 Group / Control / DataSource 같은 **단편 JSON** 을 전체 시나리오로 감싸지 않고도 빠르게 검증할 수 있다. cross-check 는 비활성화되고 JSON Schema 검증만 수행.
+
+`<ref>` 는 다음 4 형태 모두 가능:
+
+| 형태 | 예시 | 동작 |
+|---|---|---|
+| file key | `control/input-text.schema.json` | `addSchema()` 등록 키와 정확 일치 |
+| `$id` | `https://flextudio.local/meta-contract/v1/group.schema.json` | schema 의 `$id` 와 일치 |
+| shorthand (basename) | `input-text` / `group` / `data-sources` | `<x>.schema.json` 의 `<x>` |
+| 부분 문자열 | `combo` (단일 매칭일 때만) | 위 셋에 부분 포함 |
+
+`#/$defs/<name>` JSON Pointer 도 허용 — 부분 정의 검증.
+
+#### 예시
+
+```bash
+# InputText 단편 검증
+node validate.mjs -s input-text path/to/input-text-fragment.json
+
+# DataSource 한 개 정의 검증 ($defs/dataSource)
+node validate.mjs --schema='data-sources#/$defs/dataSource' path/to/ds-fragment.json
+
+# Group 단편 검증
+node validate.mjs --schema=group path/to/group-fragment.json
+
+# $id 로 검증
+node validate.mjs --schema='https://flextudio.local/meta-contract/v1/control/label.schema.json' label.json
+```
+
+매칭 실패 / 다중 매칭 시 후보 목록을 출력 (예: `--schema=input` → 5개 후보 안내).
+
+검증 단계:
+
+| # | Tag | 설명 |
+|---|---|---|
+| 1 | `[schema]` | JSON Schema 검증 — `Ajv2020` 로 모든 schema 재귀 등록 후 `scenario.schema.json` 적용 |
+| 2 | `[reach]`  | Step reachability — 각 Step 이 `StartSteps` 또는 `Step.Next` 에 정확히 1번 포함 (탭 내부 Step 도 host Step 의 `Next` 에 있어야 함 — 탭은 `Next` 요구 면제 안 함), BackButton.Next 자기참조 금지, 미정의 StepId 참조 차단 |
+| 3 | `[id]`     | Id 유일성 — Group / Control / BottomButton / Dialog 자식 Id 가 시나리오 전체에서 유일 |
+| 4 | `[date]`   | InputDate ↔ Calendar 정합 — `DateFormat="YYYY-MM"` ↔ `CalendarType="monthCalendar"` |
+| 5 | `[event]`  | Dialog 이벤트 위치 — Combo/Search/InputDate 본체에 `UseEvents`/`Events` 두지 않음 (자식 ComboList/List/Calendar 안에만) |
+| 6 | `[sample]` | Sample-data DataSource — AI 생성은 `Fixed`/`Grid` 만 (`SAMPLE_DATA_STRICT=0` 으로 비활성화 가능) |
+| 7 | `[dsref]`  | DataSourceName 참조 — 컨트롤이 사용하는 모든 `DataSourceName` 이 `scenario.DataSources` 에 정의되어 있어야 함 |
+| 8 | `[bind]`   | Ckey 바인딩 ↔ DataConnection 조상 — Ckeys/SaveValueKey/Label.LabelCKey 사용 컨트롤은 상위 Group 계층에 `UseDataConnection:true + DataConnection` 필요 |
+| 9 | `[move]`   | MoveSteps 타깃 Step — `UseMove:true` 의 `MoveSteps.MoveStepOrder` 항목이 실제 정의된 StepId 인지 |
+| 10 | `[ds-key]` | Combo/Search 본체 ↔ 자식 Ckeys 일치 — Combo.Ckeys === ComboList.Ckeys, Search.Ckeys === List.Ckeys |
+| 11 | `[inner]`  | InnerBlock 섹터 컨텍스트 — `UseInnerBlock:true` 그룹의 조상 중 하나는 `UseDataConnection:true + DataConnection` 필요 |
+| 12 | `[image]`  | ImageBox.{ViewGroup,DefaultViewGroup}.{ImgPath,BucketUrl} 비어있어야 함 — 샘플링/생성 시 외부 호스팅 URL/업로드 경로 미박. `IMAGE_PATH_STRICT=0` 으로 비활성. design-system.md §11 |
+| 13 | `[proto]`  | 프로토타이핑 모드 — **진짜 정적 UI 목업 전용**: DataSources 도 비어있고 시작 Step.Init 에 `f.Collection.addSector` mock 패턴도 없을 때만 발동. 이 경우 Ckeys / DataConnection / LabelCKey 사용 금지, 정적 텍스트는 `Label.labeltext` 로. **표준 흐름은 [mock-init] + DC 반복 렌더링** — 시작 Step.Init 에서 카테고리에 mock 섹터 N건 박고 그룹의 `UseDataConnection + DataConnection.CategoryName` 으로 연결하면 같은 컨트롤이 N번 자동 반복. 이 흐름이면 [proto] 는 자동 통과. `PROTO_STRICT=0` 으로 비활성. |
+| 14 | `[v1-only]`| v1 명시 본체 17종 (InputText/InputNumber/InputMask/InputDate/MultiInputBox/Combo/Search/CheckBox/RadioBox/Label/ImageBox/InputFile/Tree/Tab/Embed/Calendar/CalendarNavigator) (+ Dialog 자식 전용 ComboList/List) 만 허용 — `flex-scenario validate` 는 기본 strict (`strict_v1_controls:true`). 루트 `validate.mjs` 는 `V1_CONTROLS_STRICT=1` 일 때만 활성. design-system asset: policy.v1-controls-only |
+| 15 | `[no-service]` | **서비스 구성 금지 + 이벤트 액션 제한** — AI 생성 검증 시 (a) `scenario.ServiceBinding` 은 비어있는 객체 `{}` 만 허용, (b) `scenario.Events` 의 Action 은 `'Script'` / `'LinkedEvent'` 만 허용 (Service / API 차단), (c) `DataSources[*].DataSourceType:'Service'\|'API'` 차단. 기본 strict (`strict_no_service:true`). 운영 메타 검증은 `false` 로 통과. |
+| 16 | `[event-ref]` | **이벤트 핸들러 참조 정합** — `Step.Events` / `BottomButton.Events` / `Group.Events` / `Control.Events` 에서 핸들러 값으로 적은 이름 + `LinkedEvent.EventName` 은 모두 `scenario.Events` 의 키로 정의되어 있어야 함. 항상 활성. |
+| 17 | `[no-inner-block]` | **InnerBlock 패턴 사용 금지** — `UseInnerBlock` / `InnerBlockKey` / `RepeatStyle` 어떤 형태로도 메타에 박지 말 것. 데이터 반복 렌더링은 `DataConnection(DataUsage:'query')` 그룹으로 대체. |
+| 18 | `[step-nav]` | **N개 Step 흐름의 Step 간 이동 트리거 보장** — `Step.Next` 에 명시한 각 타깃 StepId 는 BottomButton 또는 하위 Group/Control 의 UseMove + MoveSteps 로 도달 가능해야 함. **타깃이 같은 Step 안의 `Tab.Items[].LinkedStepId` 로 연결돼 있으면 트리거 충족으로 인정**(탭 헤더 클릭이 트리거). `strict_step_nav=false` 로 비활성. |
+| 19 | `[strict-fields]` | **스키마에 정의되지 않은 필드 사용 금지** — 모든 `schema/v1/*.schema.json` 의 `additionalProperties:true` 를 `unevaluatedProperties:false` 로 뒤집은 strict Ajv 인스턴스로 추가 검증. |
+| 20 | `[script-allow]` | **이벤트 Script Action 화이트리스트** — `f.Collection.addSector` / `_c.*` / `Current.step.reload(WithAnimation)` / `f.Content(fid).reload(WithAnimation)` / `f.Date()` / `f.Script.load(...)` / `f.MessageBox(type).setTitle().setDescription().addButton/addBtn().show()` / `f.Event(name).runNext()/.break()` 만 통과. Init 핸들러는 추가로 reload/Event/MessageBox/Script.load 도 차단. **`intent:{...}` short-form 은 펼침 후의 raw 본문에 대해 동일하게 검사** (validate phase 순서: pattern+design → intent → script-allow). |
+| 21 | `[mock-init]` | **시작 Step 의 Init 이벤트에서 mock 섹터 강제** — 사용 카테고리(`DataConnection.CategoryName` 만 — `TargetSector.CategoryName` 은 schema 차단) 에 대해 `StartSteps[0]` Step 의 `Events.Init` 핸들러가 `f.Collection.addSector({...}, '<카테고리>')` 호출 포함. `LinkedEvent` 로 위임된 보조 핸들러도 추적. |
+| 22 | `[category-name]` | **카테고리명 명명 규칙** — `Ctg` 접두 + PascalCase + JS 식별자 (예: `CtgItemList`, `CtgFilter`). 안티패턴 `Ctg(New\|Edit\|Add\|Insert)*` 도 차단 (별도 카테고리 만들지 말고 `DataUsage:'new'\|'update'` 사용). 출처: [runtime/v1/collection/naming.md §2](runtime/v1/collection/naming.md). |
+| 23 | `[display-key]` | **Combo/Search 본체 표시 키 필수** — Search 본체, 그리고 자식 `ComboList.UseDataSource !== false` 인 Combo 본체는 `CtrlDisplayCkey` 또는 `DisplayValue` (비어있지 않은 값) 가 함께 채워져 있어야 함. 둘 다 비우면 선택 후 본체에 빈 칸. **생성 규칙: 고정데이터(`UseDataSource:false`)도 예외 없이 채운다** (`DisplayValue:""` fallback 컨벤션 폐기) — 다만 후검증은 고정 Combo 를 검사 대상 외로 둬 자동 차단하진 않음(관대). `DISPLAY_KEY_STRICT=0` 으로 비활성. |
+| 24 | `[tab-move]` | **탭 조상 Group UseMove 금지** — `Tab` 컨트롤의 조상 Group 에 `UseMove:true` 가 있으면 탭 헤더 클릭이 그 Group 의 Step 이동을 트리거해 탭 전환 대신 화면이 넘어가 버림. `strict_tab_move=false` 로 비활성. core `checkTabAncestorMove` / validate.mjs. |
+| 25 | `[tab-embed]` | **탭 내부 LinkedStep Embed 금지** — `Tab.Items[].LinkedStepId` 로 띄우는 Step 의 Contents 트리에 `Embed` 컨트롤 금지. 탭 내부 Step 은 Step 이벤트(Init/Loaded) 미실행이라 Embed 초기화 시점을 못 잡아 차트/지도/QR 이 안 뜸 → 별도 Step 으로 분리. `strict_tab_embed=false` 로 비활성. core `checkTabLinkedStepEmbed` / validate.mjs. |
+| 26 | `[group-dc]` | **모든 Group 에 UseDataConnection 명시 강제** — 키 누락 시 스튜디오(`convertTopLevelDataConnection`)가 `UseOldDataConnection:true` 를 자동 생성해 구버전 데이터연결 프로퍼티로 렌더. 비연결 그룹도 `"UseDataConnection": false` 명시. `strict_group_dc=false` 로 비활성. core `checkGroupUseDataConnection` / validate.mjs. |
+| 27 | `[embed-render]` | **Embed 렌더 누락 차단** — `<canvas>`/빈 id 컨테이너를 둔 Embed 는 host Step 의 `Loaded`/`Init` 핸들러에 `document.getElementById`/`querySelector` 등 실제 렌더 코드가 있어야 함. 라이브러리 로드(`StyleURLs`/`f.Script.load`)만으로는 안 그려져 빈 영역만 남음. `strict_embed_render=false` 로 비활성. core `checkEmbedRender` / validate.mjs. |
+| 28 | DataUsage 결합 규칙 | **schema allOf if/then 으로 강제** ([data-objects.schema.json](schema/v1/data-objects.schema.json)) — `default` → `UseNewSector:true + OnlyIfNoSector:true`, `new` → `UseNewSector:true`, `detail`/`update` → `UseTargetSector:true + TargetSector` 객체. property-data.js 스튜디오 프로퍼티 패널 동작과 동일. |
+
+## JSON Schema 버전
+
+모든 schema는 **JSON Schema 2020-12** (`https://json-schema.org/draft/2020-12/schema`) 를 따른다. `Ajv2020` (`ajv/dist/2020.js`) 로 컴파일.
+
+생성·검증은 **설치형 CLI + Claude Code Skill** (`@flextudio/scenario`) 로 한다.
+`schema/v1/*.schema.json` 은 `@flextudio/contract-core` (`core/schemas.mjs` `buildAjv`) 가 Ajv2020 로 로드하고,
+`*.md`·`catalog.json`·patterns 는 `build-skill-payload` 가 SKILL 자산으로 펼쳐 모델 컨텍스트에 주입한다.
+전체 구조: [ARCHITECTURE.md](ARCHITECTURE.md).
+
+**검증 정책:**
+- 검증 진입점 — 루트 `validate.mjs` / `flex-scenario validate <file>` / `bench/sanity-check.sh` — 은 모두 동일 core 를 호출한다 (단일 진실원본).
+- 4단계: materialize(pattern+design) → intent → ajv basic → ajv strict → cross-check.
+- 모든 `strict_*` cross-check 는 **항상 ON 으로 강제** (검증 우회로 legacy 필드/mock 누락 등이 박히는 사례 차단). 운영 메타 호환 검증은 strict 를 낮춘 별도 경로로 분리.
+
+## 호환 엔진
+
+- **현재 v1 컨트랙트 = flextudio 엔진 6.4.x 기준** (verified 2026-05-04, 45 시나리오 샘플 + `public/engine/` 소스 검증).
+- 메타데이터는 `scenario.schema.json` 의 `x-engineCompat` 객체에 박혀 있음:
+  ```json
+  "x-engineCompat": {
+    "minEngine": "6.4.0",
+    "testedAgainst": "6.4.x",
+    "verifiedSamples": "...",
+    "lastVerified": "2026-05-04"
+  }
+  ```
+- 엔진 메이저 변경(6→7) 시 → `schema/v2/` 신규 디렉토리.
+- 엔진 마이너 변경(6.4 → 6.5) 안에서 메타 변경이 발생하면 → `v1` 안에서 보강 + `x-engineCompat.testedAgainst` 갱신.
+
+## 버전 정책
+
+- **컨트랙트 버전 (v1, v2 …)** = 검증 정책 자체의 메이저 변경. 엔진 변경과 직교.
+- **엔진 호환 버전** = `x-engineCompat` 메타데이터로 표시. 같은 v1 안에서 여러 엔진 마이너를 지원할 수 있음.
+- 호환성 깨지는 변경(필드 제거/이름 변경, 타입 변경) → 신규 컨트랙트 메이저 (`v2`).
+- 호환 보강(필드 추가, 카탈로그 확장, const 완화) → `v1` 안에서.

package/contract-data/examples/README.md

@@ -0,0 +1,147 @@
+# examples
+
+flextudio scenarioMeta 검증 샘플 — **5 카테고리 / 16 파일 / 13개 검증 통과**.
+
+각 파일은 실제 운영 메타에서 추출한 패턴이거나, 운영 메타를 v1 컨트랙트 검증 통과 형태로 자동 보정한 것이다.
+
+검증 명령:
+
+```bash
+node ../validate.mjs                                  # 전체 검증 (cross-check 포함)
+node ../validate.mjs basic/delivery-address-popup.json # 단일 파일
+PROTO_STRICT=0 node ../validate.mjs ...               # 운영 메타 모드 (Ckeys/DC 허용)
+IMAGE_PATH_STRICT=0 node ../validate.mjs ...          # ImageBox path 채워진 운영 모드
+```
+
+## 카테고리
+
+| 카테고리 | 파일 수 | 의도 | 디자인 토큰 | 통과 |
+|---|---:|---|---|---:|
+| [minimal/](minimal/)   | 4 | **골격(skeleton)** — 구조/패턴 검증용. 디자인 토큰 0. AI 가 "단순한 화면" 만들 때 / 구조만 빠르게 확인할 때. | 없음 | 4/4 |
+| [basic/](basic/)       | 1 | 단순 1~3 step + 디자인 적용. PopUp 단독. | 풍부 | 1/1 |
+| [enhanced/](enhanced/) | 6 | multi-step + dialog (PopUp/SlideUp) + 디자인. | 풍부 | 5/6 |
+| [complex/](complex/)   | 4 | 5+ step + 깊은 그룹 중첩 (4~7 레벨). | 매우 풍부 | 3/4 |
+| [tile/](tile/)         | 1 | 그리드 카드 패턴 (FlexDirection:wrap). | 풍부 | 0/1 |
+| [tab/](tab/)           | 2 | Tab 컨트롤 + RadioBox styleTab 패턴 표본. 운영 메타 그대로 — 검증보다는 패턴 참조용. | 풍부 | — |
+| [tree/](tree/)         | 1 | Tree 컨트롤 표본 (단일/다중 선택 + 검색바). 운영 메타 그대로. | 보통 | — |
+
+---
+
+## minimal/ — 골격 표본
+
+디자인 토큰 (`BgStyle` / `BorderStyle` / `FontStyle` / `Padding` / `ContentStyle`) **모두 0**. v1 컨트랙트 구조와 패턴만 보여주는 최소 표본.
+
+| 파일 | 패턴 | 핵심 컨트롤 / 메타 |
+|---|---|---|
+| [minimal/basic-list-detail.json](minimal/basic-list-detail.json) | 기본형태-0단계 — List → Input → Detail | `Label` / `RadioBox` / `InputText` / `MultiInputBox` / `ImageBox` |
+| [minimal/list-with-filters.json](minimal/list-with-filters.json) | 기본형태-1단계 — Combo 필터 + List → Input | `Combo`(Dialog→`ComboList`) 필터, status 배지 카드 |
+| [minimal/search-period-popup.json](minimal/search-period-popup.json) | 기본형태-조회강화형 — InputDate 기간 + Search + PopUp 상세조건 | `InputDate`(`FromTo`/`SingleDate`) + `Search`(Dialog→`List`), `StepDialogType:"PopUp"` |
+| [minimal/fixedtop-floating-form.json](minimal/fixedtop-floating-form.json) | 기본형태-혼합강화형 — FixedTop 검색바 + 리스트 + Floating | `FixedContentsTop` 검색바, `UseAbsoluteLayout` Floating, `InputFile` 첨부, `monthCalendar` |
+
+---
+
+## basic/ — 디자인 적용 단순 화면
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [basic/delivery-address-popup.json](basic/delivery-address-popup.json) | 배송지 변경 PopUp (2 steps) | `BgStyle` 4, `BorderStyle` 14, `FontStyle` 29, `Padding` 8 |
+
+---
+
+## enhanced/ — multi-step + Dialog + 디자인
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [enhanced/trade-statement-list.json](enhanced/trade-statement-list.json) | 거래명세서 조회 (PDA, 3 steps) | StepView + PopUp + SlideUp 조합 |
+| [enhanced/asset-management.json](enhanced/asset-management.json) | 자산관리 템플릿 (3 steps) | Combo + Search + ImageBox |
+| [enhanced/appointment-booking.json](enhanced/appointment-booking.json) | 약속잡기 (5 steps) | Calendar + CheckBox 다중 |
+| [enhanced/work-report.json](enhanced/work-report.json) | 구매 발주 관리 (4 steps) | DataUsage `query`/`detail`/`new` 혼합, SlideUp/PopUp |
+| [enhanced/salary-contract.json](enhanced/salary-contract.json) | 연봉계약 (5 steps) | `Signature` + `Line` + 깊은 텍스트 |
+| [enhanced/fuel-cost-status.json](enhanced/fuel-cost-status.json) | 유류비 자동등록 (3 steps) | `InputDate` × 3 + `InputMask` |
+
+---
+
+## complex/ — 다중 step + 깊은 중첩
+
+운영급 시나리오. 그룹 중첩 4~7 레벨. **`composition.group-nesting` 가이드의 표본**.
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [complex/trade-statement-input.json](complex/trade-statement-input.json) | PDA 거래명세서 입력 (7 steps) | StepView × 4 + SlideUp × 3, `BgStyle` 26 / `BorderStyle` 41 / 중첩 7레벨 |
+| [complex/order-management.json](complex/order-management.json) | 오더관리 (7 steps) | Tab 컨트롤, FontStyle 176, 중첩 6레벨 |
+| [complex/crm-main.json](complex/crm-main.json) | CRM 메인 대시보드 (4 steps) | **★ ContentStyle:`styleRectangleShadow` 26회**, `BgStyle` 81 / `BorderStyle` 108 / 중첩 7레벨 |
+| [complex/field-work-register.json](complex/field-work-register.json) | 외근등록 (13 steps + StepSub) | Step 13개, `Embed`, `BgStyle` 72 / `BorderStyle` 132 / 중첩 6레벨 |
+
+---
+
+## tile/ — 그리드 카드 패턴
+
+| 파일 | 패턴 | 특징 |
+|---|---|---|
+| [tile/second-hand-marketplace.json](tile/second-hand-marketplace.json) | 중고거래 마이페이지 (9 steps) | **★ tileWrap > itemWrap > productInfoWrap > priceWrap** 깊은 카드 구조, `composition.list.card-tile-grid` 표본 |
+
+---
+
+## tab/ — 탭형 UI 표본
+
+탭형 UI 두 가지 패턴 표본. 운영 메타 그대로 (`flextudio-ai-studio/scenario_sample_tab/` 원본). v1 컨트랙트 검증보다는 **패턴 참조용**.
+
+| 파일 | 패턴 | 핵심 컨트롤 / 메타 |
+|---|---|---|
+| [tab/tab-control-cafe.json](tab/tab-control-cafe.json) | **Tab 컨트롤** — 탭마다 다른 Step 임베드 (HOME/COFFEE/DRINK/BOTTLE) | `Tab` 본체 + `Items[].LinkedStepId`, `Height: 100%` 패턴, 탭별 `Events.Click` |
+| [tab/radiobox-styletab-approval.json](tab/radiobox-styletab-approval.json) | **RadioBox + ControlStyle:"styleTab"** — 같은 리스트의 필터만 변경 (결재/신청 전환) | `RadioBox` 의 `ControlStyle:"styleTab"`, Click 이벤트로 필터 reload |
+
+---
+
+## tree/ — 트리 컨트롤 표본
+
+| 파일 | 패턴 | 핵심 컨트롤 / 메타 |
+|---|---|---|
+| [tree/tree-sample.json](tree/tree-sample.json) | **Tree 컨트롤** — flat array 계층 (NodeId/ParentId/Title) + 검색바 + 단일·다중 선택 | `Tree` + `CollectionMapper` + `UseExpandAll`/`UseSearchBar`/`UseParentAutoSelect`, DataSourceType 'API' |
+
+---
+
+## 공통 규칙 (모든 샘플)
+
+v1 컨트랙트 강제 항목 — 변환 스크립트가 자동 보정:
+
+- 시나리오 루트 const: `modules: {}`, `Collections: {}`, `htmlkey: "stephtml"`, `ScenarioTitle: ""`, `fConverterVersion: 1`, `FlexSQLService: {}`
+- Step 식별자: `^Step[1-9][0-9]*$`
+- Group/Control/BottomButton Id: `^f_[1-9][0-9]*$` — 시나리오 전체 유일
+- 모든 Control: `ControlDefaultName` + `ControlName2`(같은 값) + `Caption` + `isColumnCtrl: false`
+- Step Reachability: 각 Step 은 `StartSteps` 또는 다른 Step 의 `Next` 에서 정확히 1번
+- Dialog 컨트롤(InputDate / Combo / Search) 본체에는 `UseEvents`/`Events` 두지 않음 — 자식 Calendar / ComboList / List 안에만
+- Ckeys 사용 컨트롤은 상위 Group 어딘가에 `UseDataConnection: true` + `DataConnection`
+- ImageBox: `ViewGroup.{ImgPath, BucketUrl}` 비움 (운영 시 채워짐)
+
+## 프로토타이핑 정책
+
+13개 통과 샘플 모두 **프로토타이핑 모드** — `DataSources: {}`, 정적 라벨 (`LabelType:"labeltext"` + `labeltext`).
+
+운영 메타로 검증할 때는:
+- `PROTO_STRICT=0` — Ckeys / DataConnection / LabelCKey 허용
+- `IMAGE_PATH_STRICT=0` — ImageBox path 채워진 상태 허용
+- `SAMPLE_DATA_STRICT=0` — Service / Collection / API DataSource 허용
+
+## 잔여 검증 비통과 (3건)
+
+| 파일 | 잔여 에러 | 사유 |
+|---|---|---|
+| `complex/order-management.json` | `[schema]` 1건 — Step2.Contents[1] (Tab) | v1 외 컨트롤 + 깊은 중첩 oneOf 폭발 |
+| `enhanced/asset-management.json` | `[schema]` 2건 — BottomButton.Next | `MoveTo:"Next"` + `MoveStepOrder` 빈 배열 (then-require) |
+| `tile/second-hand-marketplace.json` | `[schema]` 39건 — 깊은 ImageBox/Group 중첩 | 운영 특수 패턴 (oneOf 폭발) |
+
+이 3건은 운영 특수 패턴 — 자동 변환으로 의미 손실 없이 해결 어려움. 패턴 참조용으로는 그대로 사용 가능.
+
+## 디자인 시스템과의 매핑
+
+[../schema/v1/design-system/](../schema/v1/design-system/) 의 컴포지션과 매칭:
+
+| 디자인 패턴 (assets.json) | 대응 examples |
+|---|---|
+| `composition.list.card-list` | minimal/basic-list-detail, basic/delivery-address-popup |
+| `composition.dialog.popup` / `dialog.slideup` | minimal/search-period-popup, enhanced/trade-statement-list |
+| `composition.fixed.search-bar` | minimal/fixedtop-floating-form, enhanced/work-report |
+| `composition.list.card-tile-grid` | tile/second-hand-marketplace |
+| `composition.group-nesting` (★ 4~7 레벨) | complex/* (특히 crm-main, field-work-register) |
+| `content-style.rectangle-shadow` | complex/crm-main (26회 사용 — 운영 1위 표본) |