sonamu 0.8.13 → 0.8.14

package/src/skills/sonamu/cdd.md

@@ -22,7 +22,10 @@ This project follows Contract-Driven Development (CDD). All development work mus
 ## Project Structure
 
 ```text
-packages/api/contract/
+contract/
+|- schemas/
+|  |- default-contract.schema.json  # contract schema definition
+|  \- default-spec.schema.json       # spec schema definition
 |- main.contract.json          # project root contract
 |- {domain}/
 |  |- main.contract.json       # domain representative contract
@@ -36,7 +39,7 @@ packages/api/contract/
 Example:
 
 ```text
-packages/api/contract/
+contract/
 |- main.contract.json
 |- auth/
 |  |- main.contract.json
@@ -58,22 +61,59 @@ packages/api/contract/
 
 ## Document Model
 
+### Schema (`.schema.json`)
+
+Contract/Spec 문서의 포맷을 정의하는 파일. `contract/schemas/` 디렉터리에 위치한다.
+
+```json
+{
+  "id": "default-spec",
+  "type": "spec",
+  "fields": [
+    {
+      "name": "modules",
+      "type": "Record<string, string>",
+      "renderer": "label-grid",
+      "required": true,
+      "description": "구현에 사용되는 모듈 정의"
+    }
+  ]
+}
+```
+
+| Field | Description |
+|---|---|
+| `id` | 스키마 식별자 (Contract/Spec의 `schema` 필드에서 참조) |
+| `type` | `contract` \| `spec` |
+| `fields` | 문서에 포함될 커스텀 필드 목록 |
+| `fields[].name` | 필드명 |
+| `fields[].type` | `string`, `string[]`, `Record<string, string>`, `Record<string, object>` |
+| `fields[].renderer` | 렌더링 컴포넌트 (생략 시 디폴트 사용) |
+| `fields[].required` | 필수 여부 |
+| `fields[].description` | `cdd advance` Layer 2 검증 기준으로 사용됨 |
+
 ### Contract (`.contract.json`)
 
 A business-logic document that non-developers can read. AI must treat this file as **read-only**. If an update is needed, AI should only propose the change to the user.
 
 ```json
 {
+  "schema": "default-contract",
   "lastModified": "YYYY-MM-DD",
-  "content": ["## Overview", "", "Markdown lines as string array", ...]
+  "features": {
+    "login": "이메일/비밀번호 로그인 및 세션 발급"
+  },
+  "overview": [...],
+  "domainGlossary": [...],
+  "userRoles": [...],
+  "businessRules": [...],
+  "edgeCases": [...]
 }
 ```
 
-`content` is a `string[]` where each element is one line of Markdown.
+필수 필드: `schema`, `lastModified`, `features`. 나머지 필드는 적용된 schema의 `fields`에 따라 결정된다.
 
-`content` fixed sections:
-
-`Overview -> Domain Glossary -> Features/Capabilities -> User Roles/Actors -> Business Rules/Constraints -> Edge Cases`
+`features` 맵의 각 키는 Spec 파일명(feature key)과 1:1 매칭된다.
 
 ### Spec (`.spec.json`)
 
@@ -81,19 +121,33 @@ A feature-level technical document derived from Contract. Each file represents e
 
 ```json
 {
-  "schemaVersion": 1,
+  "schema": "default-spec",
+  "schemaVersion": 2,
   "summary": "Login processing and session issuance",
   "description": [
     "Validates user credentials and issues JWT-based sessions.",
     "Includes password retry limit and account lockout policy."
   ],
   "acceptanceCriteria": [
-    "Valid email/password login returns a JWT token",
-    "5 wrong password attempts locks account for 30 minutes",
-    "Expired session request returns 401 response"
+    {
+      "id": "ac-login-1",
+      "condition": "유효한 이메일/비밀번호 로그인 시 세션이 생성된다",
+      "testRef": {
+        "target": "packages/api/src/application/auth/login.test.ts",
+        "pattern": "ac-login-1"
+      }
+    },
+    {
+      "id": "ac-login-2",
+      "condition": "잘못된 비밀번호 입력 시 인증 실패 응답이 반환된다",
+      "testRef": {
+        "target": "",
+        "pattern": ""
+      }
+    }
   ],
   "lastModified": "YYYY-MM-DD",
-  "status": "draft | in-progress | done",
+  "status": "draft | specifying | implementing | validating | done",
   "sources": ["packages/api/src/application/auth/login.ts", "packages/api/src/application/auth/login.test.ts"],
   "contracts": ["./main.contract.json"],
   "dependsOnSpecs": ["./session.spec.json"],
@@ -122,12 +176,13 @@ A feature-level technical document derived from Contract. Each file represents e
 
 | Field | Type | Required | Description |
 |---|---|---|---|
+| `schema` | `string` | Y | 적용된 schema id |
 | `schemaVersion` | `number` | Y | Schema version |
 | `summary` | `string` | Y | One-line feature summary |
 | `description` | `string[]` | Y | Detailed feature description |
-| `acceptanceCriteria` | `string[]` | Y | Completion criteria (verifiable conditions) |
+| `acceptanceCriteria` | `object[]` | Y | Completion criteria. 각 항목은 `id`, `condition`, `testRef` 포함 |
 | `lastModified` | `string` | Y | Last modified date (YYYY-MM-DD) |
-| `status` | `string` | Y | `"draft"` / `"in-progress"` / `"done"` |
+| `status` | `string` | Y | `"draft"` / `"specifying"` / `"implementing"` / `"validating"` / `"done"` |
 | `sources` | `string[]` | Y | Implementation/test files (relative to project root) |
 | `contracts` | `string[]` | Y | Referenced Contract files (relative to Spec file) |
 | `dependsOnSpecs` | `string[]` | N | Dependent Spec files (relative to Spec file) |
@@ -136,9 +191,24 @@ A feature-level technical document derived from Contract. Each file represents e
 | `dataFlow` | `string[]` | Y | Inter-module data flow |
 | `errorHandling` | `Record<string, string>` | Y | Error handling (key: error name, value: trigger condition) |
 | `constraints` | `string[]` | Y | Technical constraints |
+| `guards` | `string[]` | N | Access control guards (e.g. `["admin"]`, `["admin", "sot"]`) |
+| `testCases` | `string[]` | N | Key test scenarios derived from errorHandling/acceptanceCriteria (used as fixture/test design hints) |
+| `fixtureStrategy` | `string` | N | Notes on fixture generation order or dependencies (e.g. "User → Department → Lab 순으로 생성") |
 
 **Empty section notation**: `string[]` -> `[]`, `Record<string, string>` -> `{}`
 
+### 엔티티 레벨 권장 추가 항목 (constraints에 명시)
+
+다음 항목들은 Entity 설계에 영향을 주므로 `constraints` 또는 별도 필드에 명시해 두면 Entity 설계 시 혼선을 방지할 수 있다.
+
+| 항목 | 예시 |
+|---|---|
+| PK 타입 전략 | `"User.id는 string (better-auth). 나머지는 number auto-increment"` |
+| i18n 대상 여부 | `"name 필드는 ko/en 다국어 지원 (naite 패턴 사용)"` |
+| 파일 업로드 여부 | `"thumbnail: SonamuFile (eager upload)"` |
+| ManyToMany FK 타입 일치 | `"user__roles: user_id(string FK), role_id(number FK) 혼합"` |
+| Read-only 엔티티 | `"Log 엔티티는 insert only. save/del 불필요"` |
+
 **Spec is higher authority than code.** Code must always follow the confirmed Spec. If Spec and code conflict, code is wrong.
 
 ### Contract-Spec linking
@@ -155,23 +225,44 @@ Contract is not extended as a structural source of feature keys. **Spec referenc
 
 | Value | Meaning | Transition condition |
 |---|---|---|
-| `draft` | Spec is being written, not confirmed yet | Initial state |
-| `in-progress` | Spec confirmed, implementation in progress | After all Spec sections are confirmed |
-| `done` | Implementation complete, consistency validation passed, all `acceptanceCriteria` met | After code passes consistency check against Spec |
+| `draft` | Spec 초안 작성 중, 미확정 | 초기 상태 |
+| `specifying` | 명세 세분화 중 | contracts 유효 참조, required 필드 충족, summary/description/AC 비어있지 않음 |
+| `implementing` | Spec 확정, 구현 진행 중 | 명세 전체 확정 후 |
+| `validating` | 구현 완료, AC 매칭 검증 중 | sources 파일 존재, AC testRef 지정 및 존재 |
+| `done` | 전체 AC 만족, 일관성 검증 통과 | testRef.pattern 매칭, 빌드/테스트 통과 |
 
-**Regression**: When `sources`, `contracts`, `dependsOnSpecs`, or `acceptanceCriteria` change on a `done` Spec, `status` reverts to `in-progress`.
+**Regression**: When `sources`, `contracts`, `dependsOnSpecs`, or `acceptanceCriteria` change on a `done` Spec, `status` reverts to `implementing`.
 
 ### `acceptanceCriteria` field
 
-Conditions that must be met for this Spec's implementation to be considered "done". AI uses these as a checklist during consistency validation.
+Conditions that must be met for this Spec's implementation to be considered "done". Each item is an object:
+
+```json
+{
+  "id": "ac-login-1",
+  "condition": "유효한 이메일/비밀번호 로그인 시 세션이 생성된다",
+  "testRef": {
+    "target": "packages/api/src/application/auth/login.test.ts",
+    "pattern": "ac-login-1"
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `id` | AC 식별자. `ac-{feature}-{n}` 형식 |
+| `condition` | 검증 가능한 구체적 조건 |
+| `testRef.target` | AC를 검증하는 테스트 파일 경로 |
+| `testRef.pattern` | 테스트 파일 내 항목 식별 패턴 (`pnpm cdd test <target> -p <pattern>`) |
 
 **Authoring rules**:
-- Each item must be a verifiable, specific condition. Vague expressions like "should work well" are not allowed.
+- `condition`은 검증 가능한 구체적 조건이어야 한다. 모호한 표현 불가.
 - Include conditions derived from Contract's business rules and Edge Cases.
 - Conditions derived from `constraints` and `errorHandling` may also be included.
-- Recommended format: "When X, then Y" (input-result).
+- Recommended format: "조건 X이면 Y이다" (input-result).
+- `testRef`는 `implementing` 단계에서 비워두고, `validating` 단계에서 채운다.
 
-**Validation usage**: When transitioning `status` to `"done"`, AI verifies all items are satisfied in code. If any item is unmet, `"done"` transition is blocked.
+**Validation usage**: `cdd advance <spec>` 실행 시 Layer 1/Layer 2 검증에 사용된다. `testRef.pattern` 매칭은 `validating → done` 전이 시 확인된다.
 
 ### Spec detail level
 
@@ -193,8 +284,8 @@ Whenever any Spec field changes, update `lastModified` to today's date.
 Spec files do not store history internally. Git handles it.
 
 ```bash
-git log -- packages/api/contract/auth/login.spec.json
-git log --follow -- packages/api/contract/auth/login.spec.json  # track renames
+git log -- contract/auth/login.spec.json
+git log --follow -- contract/auth/login.spec.json  # track renames
 ```
 
 ---
@@ -222,7 +313,7 @@ Contract review -> Spec authoring/fix -> Code implementation -> Test authoring/e
 - Fill all structured fields (`modules`, `interfaces`, `dataFlow`, `errorHandling`, `constraints`).
 - Define `acceptanceCriteria` with verifiable completion conditions.
 - Add planned implementation file paths to `sources`.
-- **All fields must be confirmed in this step.** After confirmation, set `status` to `"in-progress"` and continue.
+- **All fields must be confirmed in this step.** After confirmation, set `status` to `"implementing"` and continue.
 
 **Step 3: Code implementation**
 - Implement exactly following the confirmed module structure and interfaces defined in Spec.
@@ -263,7 +354,7 @@ Impact analysis -> Contract/Spec review -> Spec update/fix -> Code update -> Tes
 - If Spec update is required, update and confirm Spec first.
 - If files are added/removed, update `sources`.
 - Update `acceptanceCriteria` if completion conditions have changed.
-- Set `status` to `"in-progress"`.
+- Set `status` to `"implementing"`.
 - **Continue only after Spec is confirmed.**
 
 **Step 4: Code update**
@@ -300,7 +391,7 @@ Bug analysis -> Related Spec/Contract review -> Spec update/fix (if needed) -> C
 - If the bug is a missing technical case in Spec `errorHandling` or `constraints`, update those fields first.
 - If the bug is a missing business case in Contract `Edge Cases`, propose Contract update to user. After Contract update, update Spec.
 - Add missing conditions to `acceptanceCriteria` if applicable.
-- Set `status` to `"in-progress"`.
+- Set `status` to `"implementing"`.
 - **Continue only after Spec is confirmed.**
 
 **Step 4: Code fix**
@@ -317,6 +408,33 @@ Bug analysis -> Related Spec/Contract review -> Spec update/fix (if needed) -> C
 - **If mismatch exists, fix code.**
 - After all validations pass, set `status` to `"done"` and update `lastModified` to today.
 
+### 4. Spec-Code Audit (정합성 감사)
+
+구현이 어느 정도 진행된 시점에서 전체 Spec과 코드의 정합성을 일괄 점검하는 패턴. 특히 여러 세션에 걸쳐 개발이 진행된 경우, 또는 구현 완료 후 리뷰 전에 실행한다.
+
+```text
+전체 Spec 스캔 -> 누락/불일치 목록 작성 -> 우선순위 정렬 -> 순차 수정
+```
+
+**Step 1: 전체 Spec 스캔**
+- `pnpm cdd spec list --status implementing` 또는 `pnpm cdd tree`로 전체 Spec 현황 파악
+- 각 Spec의 `acceptanceCriteria`와 `interfaces`를 기준으로 코드 구현 여부 확인
+- 누락된 API, 잘못된 guard, 미구현 에러 처리 등을 목록으로 정리
+
+**Step 2: 감사 결과 파일로 기록**
+- `contract/spec-vs-code-audit.md` 또는 `.claude/skills/project/spec-audit.md`에 기록
+- 형식: `[domain/feature] 항목 — 상태 (구현됨 / 누락 / 불일치)`
+- 이 파일을 새 세션에서 컨텍스트 복원용으로 활용 가능
+
+**Step 3: 우선순위 기반 수정**
+- 가장 쉽고 확실한 것부터 순서 번호를 붙여 처리
+- 각 항목 완료 시 감사 파일에 완료 표시
+
+**활용 시점**:
+- 긴 세션 종료 후 새 세션 시작 시 — 현황 파악 비용 최소화
+- Claude Desktop에서 전체 Spec 스캔 → Claude Code에서 불일치 수정하는 분업 패턴에서 유용
+- 도메인 단위 구현 완료 후 PR 전 최종 점검
+
 ---
 
 ## Contract/Spec Authoring Guide
@@ -338,7 +456,7 @@ Bug analysis -> Related Spec/Contract review -> Spec update/fix (if needed) -> C
 - In `interfaces`, include only function/API names and short descriptions (no signatures or implementation logic).
 - `dataFlow` and `constraints` use `string[]` format.
 - `errorHandling` uses `Record<string, string>` format (key: error name, value: trigger condition).
-- `acceptanceCriteria` must contain verifiable, specific conditions.
+- `acceptanceCriteria` is an `object[]`. Each item must have `id`, `condition`, `testRef`. `condition` must be a verifiable, specific condition.
 - `sources` must list all related implementation and test files.
 - `contracts` must list relative paths to base Contract files.
 - Empty sections: `[]` for `string[]` fields, `{}` for `Record<string, string>` fields.
@@ -354,6 +472,7 @@ The `cdd` CLI tool automates CDD workflow tasks. Run via `pnpm cdd <command>`.
 | Command | Description |
 |---|---|
 | `cdd init [dir]` | Initialize a CDD project (creates `contract/`, `main.contract.json`, `cdd.md`) |
+| `cdd advance <spec> [--commit]` | Gate 검증 + delegate (Layer 1/2). `--commit`: Layer 2 통과 선언 후 즉시 상태 전이 |
 | `cdd tree` | Display Contract/Spec tree grouped by domain with status colors |
 | `cdd status` | Show project dashboard (Contract/Spec counts, status breakdown) |
 | `cdd status <file>` | Spec/Contract status with relationship info (contracts, deps, dependents) |
@@ -361,6 +480,7 @@ The `cdd` CLI tool automates CDD workflow tasks. Run via `pnpm cdd <command>`.
 | `cdd impact <file>` | Analyze source file change impact (direct Specs, chain Contracts, indirect Specs) |
 | `cdd check` | Verify Code-Spec-Contract consistency + `acceptanceCriteria` fulfillment |
 | `cdd spec create <n>` | Create a Spec template. Requires `--domain <n>` or `--contract <path>` |
+| `cdd contract create [name]` | Contract 템플릿 생성. `name` 미지정 시 `main` |
 | `cdd spec set-status <spec> <status>` | Change Spec status |
 | `cdd spec list` | List Specs. Filters: `--status`, `--domain`, `--contract` |
 | `cdd spec get <spec>` | Show full Spec or a specific field (`--field`) |

package/src/skills/sonamu/cone.md

@@ -199,6 +199,22 @@ pnpm sonamu stub entity Post --no-cones
 }
 ```
 
+### better-auth 엔티티 PK (Account / Session / Verification)
+
+better-auth가 관리하는 엔티티의 id는 `crypto.randomUUID()`로 생성되는 UUID다.
+`fixtureStrategy: "sequence"`를 사용하면 fixture sync 시 `MAX(id::bigint)` 오류가 발생하므로 반드시 `fixtureGenerator: "faker.string.uuid()"`를 사용한다.
+
+```json
+{
+  "name": "id",
+  "type": "string",
+  "cone": {
+    "note": "better-auth가 crypto.randomUUID()로 생성하는 UUID 형식의 식별자",
+    "fixtureGenerator": "faker.string.uuid()"
+  }
+}
+```
+
 ### enum 필드
 
 ```json

package/src/skills/sonamu/entity-relations.md

@@ -636,7 +636,7 @@ async save(spa: QuestionCollectionSaveParams[]): Promise<number[]> {
 
   const categoryIdsList: (number[] | undefined)[] = [];
   spa.forEach((sp) => {
-    const { category_ids, ...collectionData } = sp as any;
+    const { category_ids, ...collectionData } = sp as QuestionCollectionSaveParams;
     categoryIdsList.push(category_ids);
     wdb.ubRegister("question_collections", collectionData);
   });

package/src/skills/sonamu/fixture-cli.md

@@ -49,6 +49,10 @@ production/development master (실제 DB)
 
 faker 기반으로 새로운 테스트 데이터를 생성합니다.
 
+**CRITICAL: `--use-llm` 옵션은 실제 프로젝트에서 항상 사용해야 한다.** `--use-llm` 없이 생성하면 cone.note 기반 도메인 맥락이 반영되지 않아 faker 기본값만 사용되므로, 의미 없는 데이터가 생성될 수 있다. LLM이 `requirements.md`, `business-logic.md`를 참조해 맥락에 맞는 데이터를 생성하려면 이 옵션이 필수이다.
+
+**CRITICAL: fixture gen을 실행하기 전에 `cone.note`가 주요 prop에 존재하는지 확인한다.** cone.note가 없으면 LLM이 맥락을 파악할 수 없어 의미 있는 데이터 생성이 불가능하다. cone.note가 부족하면 `pnpm sonamu cone generate --use-llm`으로 cone을 재생성한다.
+
 #### 기본 사용법
 
 ```bash

package/src/skills/sonamu/frontend.md

@@ -490,6 +490,71 @@ export function UserIdAsyncSelect<T extends UserSubsetKey>({
 - `value`: 현재 선택된 값 (PK 타입에 따라 number 또는 string)
 - `onValueChange`: 값 변경 핸들러
 
+### Cascade Dropdown 패턴 (계층 선택)
+
+부서 → 과소 → 연구실처럼 상위 선택에 따라 하위 목록이 변해야 하는 경우, `baseListParams`를 동적으로 전달하면 된다.
+
+**핵심 동작**: `baseListParams` prop이 변경되면 `IdAsyncSelect` 내부 React Query가 새 파라미터로 자동 재조회한다. (v0.2.5+에서 수정된 버그 - 이전 버전은 초기값만 사용하고 변경을 반영하지 않았음)
+
+```tsx
+// 예시: 부서 → 과소 → 연구실 3단계 cascade
+function UserForm() {
+  const { form, register, setForm } = useTypeForm(UserSaveParams, {
+    dept_id: null,
+    division_id: null,
+    lab_id: null,
+  });
+
+  return (
+    <form>
+      {/* 1단계: 부서 선택 (전체 목록 → preload 또는 기본 IdAsyncSelect) */}
+      <DepartmentIdAsyncSelect
+        subset="A"
+        {...register("dept_id")}
+        onValueChange={(v) => {
+          // 부서 변경 시 하위 값 초기화
+          setForm((prev) => ({ ...prev, dept_id: v ?? null, division_id: null, lab_id: null }));
+        }}
+      />
+
+      {/* 2단계: 과소 선택 (선택된 부서의 과소만 조회) */}
+      <DivisionIdAsyncSelect
+        subset="A"
+        baseListParams={form.dept_id ? { department_id: form.dept_id } : undefined}
+        disabled={!form.dept_id}
+        {...register("division_id")}
+        onValueChange={(v) => {
+          // 과소 변경 시 연구실 초기화
+          setForm((prev) => ({ ...prev, division_id: v ?? null, lab_id: null }));
+        }}
+      />
+
+      {/* 3단계: 연구실 선택 (선택된 과소의 연구실만 조회) */}
+      <LabIdAsyncSelect
+        subset="A"
+        baseListParams={form.division_id ? { division_id: form.division_id } : undefined}
+        disabled={!form.division_id}
+        {...register("lab_id")}
+      />
+    </form>
+  );
+}
+```
+
+**주의사항**:
+- 상위가 변경될 때 하위 값을 명시적으로 `null`로 초기화해야 한다. IdAsyncSelect는 자동으로 초기화하지 않는다.
+- `disabled` prop으로 상위가 선택되지 않은 경우 하위를 비활성화하는 것이 UX에 좋다.
+- `baseListParams`가 `undefined`이면 IdAsyncSelect는 enabled=false 상태로 조회하지 않는다.
+
+**Spec에 명시할 항목** (cascade가 있는 경우 spec.json의 acceptanceCriteria에 추가 권장):
+```json
+"acceptanceCriteria": [
+  "부서 선택 시 해당 부서의 과소만 드롭다운으로 조회된다",
+  "과소 선택 시 해당 과소의 연구실만 드롭다운으로 조회된다",
+  "부서 변경 시 하위 과소/연구실 선택이 초기화된다"
+]
+```
+
 ### IMPORTANT: String Primary Key Support
 
 대부분 Entity는 Number PK (`IdAsyncSelect<number>`)이지만, better-auth 관련 Entity는 String PK를 사용합니다.

package/src/skills/sonamu/migration.md

@@ -33,6 +33,8 @@ pnpm sonamu migrate run         # 실제 DB에 적용
 
 **예외:** PK 타입 변경 등 Sonamu가 자동 처리할 수 없는 특수 케이스만 raw SQL 허용 (아래 "PK 타입 변경" 섹션 참조)
 
+**CRITICAL: Cross-table 연쇄 변경은 단일 파일로 처리한다.** FK drop → 타입 변경 → FK restore처럼 여러 테이블에 걸친 연쇄 변경은 반드시 하나의 migration 파일 안에서 순서대로 실행해야 한다. 파일을 나누면 중간 상태에서 constraint 위반이 발생한다. (상세: 아래 "PK 타입 변경" 섹션 참조)
+
 ## 기본 구조
 
 ```typescript
@@ -176,7 +178,7 @@ grep -r "with.*User" --include="*.entity.json"
 
 ### 흔한 실수
 
-1. **여러 migration으로 분리**: Migration 1에서 PK 변경, Migration 2에서 FK 변경 시도 → FK constraint 위반
+1. **여러 migration으로 분리**: FK drop, 타입 변경, FK restore를 별도 파일로 나누면 첫 번째 파일 apply 직후 constraint 위반. 관련 변경은 항상 단일 파일로 통합할 것.
 
 2. **constraint 제거 없이 타입 변경**: `cannot alter type of a column used by a foreign key` 에러 발생
 

package/src/skills/sonamu/model.md

@@ -684,3 +684,31 @@ if (params.search === "id") {
 - [ ] dry-run으로 변경 내용 검증
 - [ ] pnpm typecheck로 타입 오류 확인
 - [ ] pnpm test로 동작 검증
+- [ ] `any` 타입 사용 여부 (사용 금지)
+
+### any 타입 금지
+
+`any` 타입은 TypeScript의 타입 안전성을 무력화하므로 **절대 사용하지 않는다.**
+
+**BAD: any 사용**
+```typescript
+const { category_ids, ...data } = sp as any;
+function process(input: any) { ... }
+```
+
+**GOOD: 정확한 타입 또는 unknown 사용**
+```typescript
+// 정확한 타입으로 구조 분해
+const { category_ids, ...data } = sp as QuestionCollectionSaveParams;
+
+// 타입을 알 수 없을 때는 unknown (any 대신)
+function process(input: unknown) {
+  if (typeof input === "string") { ... }
+}
+```
+
+**규칙:**
+- `any`는 사용 금지
+- 타입을 모를 때는 `unknown` 사용 후 타입 가드로 좁힌다
+- 구조 분해 시 타입 단언이 필요하면 정확한 타입명을 명시한다 (`as ConcreteType`)
+- `eslint-disable @typescript-eslint/no-explicit-any` 같은 억제 주석도 사용 금지

package/src/skills/sonamu/workflow.md

@@ -243,15 +243,22 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
     - cone.note가 비어있는 prop이 있으면 사용자에게 보고하고 `pnpm sonamu cone generate --use-llm`으로 cone을 재생성할지 확인
     - cone.note가 있어야 LLM이 맥락에 맞는 fixture 데이터를 생성할 수 있다
 44. 생성할 데이터의 최소 row 수 확인 (최소 10 ~ 최대 100)
-45. 승인하면 테스트에서 batch로 나눈 대로 fixture 생성 (LLM 사용 필수)
-46. 실제 DB에 생성되었는지 사용자에게 확인 요청
-47. **`pnpm sonamu test`로 전체 테스트 재실행**
-48. `pnpm dump`으로 DB 덤프 파일 생성
+45. **better-auth 엔티티 먼저 생성** (의존성 순서 필수):
+    - User → Account → Session 순으로 생성
+    - `pnpm sonamu fixture gen --include User,Account,Session --count 10 --use-llm`
+    - **CRITICAL**: User.id string PK를 위한 `users_id_seq`가 생성되어 있어야 함 (PHASE 0 Step 18-19에서 설정)
+    - 상세 내용은 `auth-migration.md` "Better-auth 엔티티 Fixture 생성" 섹션 참조
+46. 승인하면 테스트에서 batch로 나눈 대로 fixture 생성 (LLM 사용 필수)
+    - `--use-llm` 옵션은 반드시 사용 (cone.note 기반 도메인 맥락 반영 필수)
+47. 실제 DB에 생성되었는지 사용자에게 확인 요청
+48. **`pnpm sonamu test`로 전체 테스트 재실행**
+49. `pnpm dump`으로 DB 덤프 파일 생성
 
 **완료 기준:**
 
 - [ ] cone.note 존재 여부 체크 완료
-- [ ] fixture 데이터 생성 완료 (사용자 승인 시)
+- [ ] better-auth 엔티티 (User, Account, Session) fixture 먼저 생성 완료
+- [ ] fixture 데이터 생성 완료 (사용자 승인 시, `--use-llm` 사용)
 - [ ] DB에 데이터 존재 확인
 - [ ] 전체 테스트 통과
 - [ ] `pnpm dump` 실행 완료

package/src/stream/sse.ts

@@ -29,9 +29,11 @@ class SSEConnectionImpl<T extends z.ZodObject> implements SSEConnection<T> {
     private readonly socket: FastifyRequest["socket"],
     private readonly reply: FastifyReply,
   ) {
-    this.socket.on("close", () => {
+    const markClosed = () => {
       this._closed = true;
-    });
+    };
+    this.socket.on("close", markClosed);
+    this.socket.on("error", markClosed);
   }
 
   publish<K extends keyof z.infer<T>>(event: K, data: z.infer<T>[K]): void {

package/src/template/__tests__/generated.template.search-text.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "vitest";
+import { Sonamu } from "../../api";
+import { EntityManager } from "../../entity/entity-manager";
+import { Template__generated } from "../implementations/generated.template";
+import { Template__init_types } from "../implementations/init_types.template";
+import { propToZodType, propToZodTypeDef } from "../zod-converter";
+
+const TEST_API_ROOT = "/Users/Nebuleto/Workspace/sonamu/modules/sonamu";
+
+Sonamu.apiRootPath = TEST_API_ROOT;
+
+let entitySeq = 0;
+
+async function registerEntity() {
+  entitySeq += 1;
+
+  const entity = {
+    id: `GeneratedTemplateSearchText${entitySeq}`,
+    title: `GeneratedTemplateSearchText${entitySeq}`,
+    table: `generated_template_search_text_${entitySeq}`,
+    props: [
+      { name: "id", type: "integer" as const },
+      { name: "title", type: "string" as const },
+      {
+        name: "slug",
+        type: "string" as const,
+        generated: {
+          type: "STORED" as const,
+          expression: "title",
+        },
+      },
+      {
+        name: "search_text",
+        type: "searchText" as const,
+        sourceColumns: [{ name: "title", caseInsensitive: true }],
+      },
+    ],
+    indexes: [],
+    subsets: {
+      A: ["id", "title", "slug", "search_text"],
+    },
+    enums: {},
+  };
+
+  await EntityManager.register(entity, {
+    deferSearchTextJsonSourceValidation: true,
+  });
+
+  return EntityManager.get(entity.id);
+}
+
+describe("Template__generated searchText", () => {
+  test("searchText를 문자열 스키마로 변환해야 한다", async () => {
+    const prop = {
+      name: "search_text",
+      type: "searchText" as const,
+      sourceColumns: [{ name: "title", caseInsensitive: true }],
+    };
+
+    const schema = await propToZodType(prop);
+
+    expect(propToZodTypeDef(prop, [])).toBe("search_text: z.string(),");
+    expect(schema.safeParse("fuzzy query").success).toBe(true);
+    expect(schema.safeParse(123).success).toBe(false);
+  });
+
+  test("searchText를 __generated__ 메타데이터에 포함하면서 기존 generated 키를 유지해야 한다", async () => {
+    const entity = await registerEntity();
+    const template = new Template__generated();
+
+    const source = template.getBaseSchemaSourceCode(entity).lines.join("\n");
+
+    expect(source).toContain("search_text: z.string(),");
+    expect(source).toContain('readonly __generated__: readonly ["slug", "search_text"],');
+    expect(source).toContain('readonly __hasDefault__: readonly ["id"],');
+  });
+
+  test("SaveParams write schema에서 generated/searchText 컬럼을 제외해야 한다", async () => {
+    const entity = await registerEntity();
+    const template = new Template__init_types();
+    template.getTargetAndPath = () => ({ target: "", path: "" });
+
+    const { body } = template.render({ entityId: entity.id });
+
+    expect(body).toContain(
+      `export const ${entity.id}SaveParams = ${entity.id}BaseSchema.omit({ slug: true, search_text: true }).partial({ id: true });`,
+    );
+  });
+});

package/src/template/generated.template.test-d.ts

@@ -0,0 +1,46 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { z } from "zod";
+import type { InsertData } from "../database/puri.types";
+
+type GeneratedTemplateRow = {
+  id: number;
+  title: string;
+  code: string;
+  slug: string;
+  search_text: string;
+  __hasDefault__: readonly ["id"];
+  __generated__: readonly ["slug", "search_text"];
+};
+
+describe("generated template __generated__ metadata", () => {
+  it("searchText와 기존 generated 컬럼을 write payload에서 제외해야 한다", () => {
+    type Result = InsertData<GeneratedTemplateRow>;
+
+    expectTypeOf<Result>().toEqualTypeOf<{
+      id?: number;
+      title: string;
+      code: string;
+    }>();
+  });
+
+  it("SaveParams와 동등한 write schema 추론도 generated/searchText 컬럼을 제외해야 한다", () => {
+    const GeneratedTemplateSaveParams = z
+      .object({
+        id: z.number(),
+        title: z.string(),
+        code: z.string(),
+        slug: z.string(),
+        search_text: z.string(),
+      })
+      .omit({ slug: true, search_text: true })
+      .partial({ id: true });
+
+    type Result = z.infer<typeof GeneratedTemplateSaveParams>;
+
+    expectTypeOf<Result>().toEqualTypeOf<{
+      id?: number;
+      title: string;
+      code: string;
+    }>();
+  });
+});