# KBX v36 Migration Guide

## 1. Screen Recipe `testProfile` 추가

`contracts/screens/kbx.screen-recipes.json`의 모든 T01~T09 Recipe는 다음을 가져야 한다.

```ts
interface KbxScreenRecipeTestProfile {
  requiredScenarioKinds: ('e2e'|'integration'|'contract')[]
  requiredTags: string[]
  requiredEvidence: string[]
  requiredChecks: string[]
}
```

Custom Recipe를 별도로 관리하는 소비자는 동일한 검증 정보를 추가해야 한다.

## 2. 새 Verification Manifest

생성 산출물이 하나 추가된다.

```text
generated/screen-recipe-verification-manifest.json
```

직접 수정하지 않는다.

```bash
node scripts/generate-screen-recipe-contracts.mjs
```

또는 `node scripts/validate-kbx.mjs`를 실행한다.

## 3. Scaffolder 생성 파일 추가

`kbx:new-screen`은 기존 Definition/Page/Route/README 외에:

```text
*.test-plan.ts
```

를 생성한다.

이 파일에는 Recipe의 Canonical Scenario, Required Check, Required Evidence가 들어간다. 삭제하지 말고 실제 Screen-specific Vitest/Playwright로 확장한다.

기존 보안 요구는 그대로다.

```text
master
transaction
fast-entry
```

은 계속 명시적인 `--write-permission`이 필요하다.

## 4. Home Attention API

신규 권장 API:

```ts
buildKbxHomeAttentionQueue(...)
```

반환:

```ts
{
  items,
  totalCount,
  overflowCount,
  sourceCounts,
}
```

기존:

```ts
buildKbxHomeAttention(...)
```

은 호환을 위해 유지되며 `items`만 반환한다.

`KbxHomeAttentionItem`에는 `occurredAt`이 필수다. 직접 Item을 생성하는 외부 코드가 있다면 발생 시각을 넣어야 한다.

## 5. Home 정렬 변경

업무 Priority 자체는 변경하지 않는다.

```text
미저장
→ 실패/부분완료
→ 중요 알림
→ 진행 작업
→ 일반 알림
```

동일 Priority에서는 v36부터 `occurredAt DESC`로 정렬한다.

## 6. Release Governance

Screen Recipe의 `testProfile`과 `canonicalScenarioIds` 변경이 Release Impact에 기록된다. `requiredPolicies`, `recoveryPolicies`, `securityPolicies`, `defaultCommands`, `scaffoldSurfaces` 변경은 구조적 영향으로 취급한다.

## 7. DB / API Migration

v36 자체는 PostgreSQL schema나 backend API route 변경을 요구하지 않는다. Frontend Screen Recipe/Test/Home Navigation 계약의 강화다.

## Foundation v50 — Template retryability

Templates that bind a known permanent `KbxProblem` should now pass `errorRetryable=false` rather than render a meaningless retry action. Existing callers remain backward compatible because the default is `true`.

`WMS-WORK-001` specifically treats `WMS_WORK_QUERY_NOT_CONNECTED` as non-retryable. When the real production endpoint is connected, classify transient network/service failures separately and set retryability according to the returned Problem contract.
