@decencia/ch-cli 1.8.2 → 1.11.0

package/skill/2t-decencia-channel-spec-v2/SKILL.md

@@ -2,15 +2,16 @@
 name: 2t-decencia-channel-spec-v2
 description: |
   [2t][v2] 소통채널 기능명세(=Story) 작성/수정 표준.
-  Epic-Story-Task 구조에서 UI/Logic/DB/Task 필드 각각의 작성 패턴, JSON 템플릿, 입자 기준을 다룬다.
+  Epic-Story 구조에서 UI/Logic/DB 필드 각각의 작성 패턴, JSON 템플릿을 다룬다.
+  Story는 Task로 쪼개지 않는다 — 규모는 spec 단위 Story Point(`points`)로 매긴다.
   Spec ID는 JIRA 스타일 사용자 지정(`LOGIN-001`) 또는 자동 생성 선택 가능 — §1.5.
   작업 일지(workStatus)는 라이프사이클이 달라 [[2t-decencia-channel-work-status-v2]]로 분리.
   Use when:
   (1) spec(=Story)을 작성·수정할 때,
   (2) UI 메타데이터·비즈니스 로직·DB 참조를 함께 다룰 때,
-  (3) Task를 JIRA 스타일(points·assignee·description·completedAt)로 잘게 쪼갤 때,
+  (3) Story 규모를 Story Point(`--points`)로 매길 때,
   (4) 신규 spec ID를 `LOGIN-001` 같은 JIRA 스타일로 부여하고 싶을 때 (`ch specs create --id`).
-version: 1.8.2
+version: 1.11.0
 ---
 
 <!-- ch-version-gate -->
@@ -28,7 +29,7 @@ ch check
 구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
 
 
-# 기능명세 — Story / Epic / Task 작성 표준
+# 기능명세 — Epic / Story 작성 표준
 
 CLI 명령은 [[2t-decencia-channel-cli-v2]], DB 테이블 작성은 [[2t-decencia-channel-db-schema-v2]] 참조.
 
@@ -41,14 +42,16 @@ CLI 명령은 [[2t-decencia-channel-cli-v2]], DB 테이블 작성은 [[2t-decenc
 | **Spec ID** | `spec.id` (string) | 식별자. **JIRA 스타일 사용자 지정 가능** (예: `LOGIN-001`). §1.5 |
 | **Epic** | `spec.epic` (string) | 분류 라벨. 같은 에픽 spec끼리 자동 그룹핑 |
 | **Story** | spec 자체 (1 spec = 1 story) | 명세 1건. CLI 명칭은 `specs` 그대로 |
-| **Task** | `spec.tasks[]` | Story 완료를 위한 체크리스트 (points/assignee/description/completedAt) |
+| **Story Point** | `spec.points` (number) | Story 규모 점수. Story를 Task로 쪼개지 않고 spec 단위로 매긴다. §3 |
 | **UI**   | `spec.ui` (object) | Figma·route·file·access·interactionMap |
-| **Logic** | `spec.logic` (object) | dataFlow·stateTransitions·businessRules |
+| **Logic** | `spec.logic` (object) | dataFlowScenarios·stateTransitions·businessRules |
 | **DB**   | `spec.dbTableRefs` (string[]) | db-tables 컬렉션의 테이블 ID 배열. 양방향 동기화 |
 
 `spec.workStatus`(작업 일지)는 개발 진행 중에 누적되는 별개 라이프사이클 — [[2t-decencia-channel-work-status-v2]] 참조.
 
-**완료 조건**: 별도 acceptanceCriteria 없음. **연관 SQA 통과 = 완료**.
+**Story는 Task로 쪼개지 않는다.** 규모는 spec 단위 Story Point(`points`)로 매긴다(§3). 진행률(%) 개념은 없다 — 완료 여부는 `spec.status`로 표현한다.
+
+**완료 조건**: 별도 acceptanceCriteria 없음. **연관 SQA 통과 = 완료**. (`tasks`는 deprecated — 하위호환용으로만 남는다.)
 
 ---
 
@@ -56,12 +59,12 @@ CLI 명령은 [[2t-decencia-channel-cli-v2]], DB 테이블 작성은 [[2t-decenc
 
 ```bash
 ch specs get <specId> --json > /tmp/spec.json     # 1) 현재 상태 백업
-# 편집 (tasks/ui/logic JSON 통째 교체 위험)
-ch specs update <specId> --tasks /tmp/tasks.json --no-version
-ch specs get <specId> --json | jq '.tasks'        # 3) 검증
+# 편집 (ui/logic JSON 통째 교체 위험)
+ch specs update <specId> --logic /tmp/logic.json --no-version
+ch specs get <specId> --json | jq '.logic'        # 3) 검증
 ```
 
-`--tasks` / `--ui` / `--logic` / `--work-status`는 **각 필드 자체를 통째로 교체**. 일부만 바꾸려면 반드시 전체 가져와서 편집 후 전송.
+`--ui` / `--logic` / `--work-status`는 **각 필드 자체를 통째로 교체**. 일부만 바꾸려면 반드시 전체 가져와서 편집 후 전송. (`--points`는 스칼라라 통째 교체 위험 없음 — 그 값만 바뀐다.)
 
 ---
 
@@ -71,11 +74,11 @@ ch specs get <specId> --json | jq '.tasks'        # 3) 검증
 |---|---|
 | `content` | 개요 1~3줄 + 권한 요약. 짧게 유지 |
 | `ui.*` | 화면 메타 (figma/route/file/access) + 인터랙션 맵 |
-| `logic.dataFlow` | 데이터 READ/WRITE 흐름 |
-| `logic.stateTransitions` | 상태 머신 |
+| `logic.dataFlowScenarios` | 시나리오별 데이터 흐름. 시나리오 → 순서 있는 단계 → 단계별 테이블 참조(refs) |
+| `logic.stateTransitions` | 화면 상태 전이 (저장되는 엔티티 상태는 db-table.stateMachines) |
 | `logic.businessRules` | 도메인 규칙 |
 | `dbTableRefs[]` | 참조 테이블 ID (스키마 본문은 db-tables 문서에) |
-| `tasks[]` | 작업 단위 체크리스트 |
+| `points` | Story 규모 점수 (Story Point). Story 단위로 매긴다 (§3) |
 
 ---
 
@@ -159,73 +162,40 @@ ch db-tables list --json
 
 ---
 
-## 3. Task — JIRA 스타일 체크리스트
+## 3. Story Point — spec 단위 규모
 
-### 3-1. tasks.json 구조
+Story(=spec)를 Task로 쪼개지 않는다. Story 하나의 규모를 **Story Point 한 값**으로 매긴다. Sprint 용량 산정은 Σ spec.points로 한다([[2t-decencia-channel-sprint-builder-v2]]).
 
-```json
-[
-  {
-    "id": "",
-    "title": "로그인 폼 UI 구현",
-    "done": false,
-    "assignee": "박준하",
-    "points": 5,
-    "description": "## 세부\n- React Hook Form + Yup\n- error UI 별도 컴포넌트\n- 참고: [Figma](https://...)"
-  },
-  {
-    "id": "",
-    "title": "Firebase Auth 연결",
-    "done": false,
-    "points": 3,
-    "description": "- signInWithEmailAndPassword 사용\n- 5회 실패 시 잠금 로직은 별도 spec"
-  },
-  {
-    "id": "a1b2c3d4",
-    "title": "유효성 검증",
-    "done": true,
-    "points": 1,
-    "completedAt": "2026-05-29T08:00:00.000Z"
-  }
-]
-```
+### 3-1. 부여 방법
 
-서버가 자동 처리:
-- `id` 비어있으면 UUID 부여
-- `done: true && completedAt 없음` → 현재 ISO 부여
-- `done: false` → completedAt 제거
-- 전체 progress(%) 자동 재계산 (`Math.round(doneCount / total * 100)`)
-
-### 3-2. 입자 기준
+```bash
+ch specs create --name "로그인 화면" --device web --domain user --type 인증 --points 5
+ch specs update <specId> --points 8 --no-version
+```
 
-| 너무 크다 | 적정 | 너무 작다 |
-|---|---|---|
-| "로그인 기능 구현" (points 13+) | "로그인 폼 UI 구현" (3~5p) | "input 태그 추가" (0p) |
+- `--points <n>` — 0 이상의 숫자. 보통 피보나치(1/2/3/5/8/13)를 쓴다.
+- 진행률(%)·완료율은 없다. 완료 여부는 `spec.status`로 표현한다.
 
-- **1 Task = 반나절~2일 작업**. points 1~8 (피보나치).
-- 13 이상이면 쪼개라.
-- 1 이하면 description bullet으로 합쳐라.
+### 3-2. points 부여 가이드 (피보나치)
 
-### 3-3. points 부여 가이드 (피보나치)
+Story 하나를 끝내는 데 드는 규모를 매긴다.
 
-| points | 의미 | 예 |
+| points | 의미 | 예 (Story 1건) |
 |---|---|---|
-| 1 | 거의 자명. 30분~2시간 | 단순 텍스트 변경, 색상 토큰 적용 |
-| 2 | 1일 이내. 구현 + 단순 검증 | 기존 폼에 필드 추가 |
-| 3 | 1~2일. 신규 컴포넌트/엔드포인트 | 로그인 폼 UI 구현 |
-| 5 | 2~3일. 통합 작업 (API + UI + state) | Firebase Auth 통합 |
-| 8 | 1주~. 큰 모듈, 모르는 영역 포함 | 결제 모듈 통합 |
-| 13 | 너무 큼 — **쪼개라** | — |
+| 1 | 거의 자명. 반나절 이내 | 단순 텍스트/색상 변경 화면 |
+| 2 | 1일 이내 | 기존 화면에 필드 1개 추가 |
+| 3 | 1~2일. 신규 화면/엔드포인트 1개 | 로그인 화면 |
+| 5 | 2~3일. UI + API + 상태 통합 | 회원가입 플로우 |
+| 8 | 1주~. 큰 모듈, 모르는 영역 포함 | 결제 연동 화면 |
+| 13 | 너무 큼 — **Story를 쪼개라** (spec 분리) | — |
 
-### 3-4. description 작성 권장
+### 3-3. 너무 크면 Story를 나눈다
 
-- 마크다운 사용 가능 (목록·표·코드블록·링크)
-- 들어가야 할 것: 구체 산출물, 의존성, 참고 자료(Figma/문서 링크), 엣지케이스
-- 들어가지 말 것: 작업 일지(→ [[work-status-v2]] 참조), 완료 보고(→ done + completedAt)
+13 이상이면 한 Sprint에 못 끝낸다. Task로 쪼개는 게 아니라 **spec 자체를 여러 Story로 나눈다**(§9).
 
-### 3-5. assignee 표기
+### 3-4. tasks 필드는 deprecated
 
-자유 문자열. 한글 이름 또는 GitHub 핸들. 팀 컨벤션 통일 권장.
+과거의 `spec.tasks[]`(체크리스트)는 deprecated다. 신규 spec에는 쓰지 않는다. `--tasks`는 하위호환으로 계속 통과되지만 사용 시 경고가 뜬다. 기존 spec의 tasks는 그대로 두거나, 규모가 필요하면 `--points`로 대체한다.
 
 ---
 
@@ -283,54 +253,159 @@ ch db-tables list --json
 
 ```json
 {
-  "dataFlow": "...",
+  "dataFlowScenarios": [],
   "stateTransitions": "...",
   "businessRules": "..."
 }
 ```
 
-세 필드 모두 마크다운. 필요한 것만 채워도 됨.
+`dataFlowScenarios`는 배열(아래 §5-2). `stateTransitions`·`businessRules`는 마크다운 문자열. 필요한 것만 채운다.
 
-### 5-2. dataFlow — READ/WRITE 매핑 표
+### 5-2. dataFlowScenarios — 시나리오 → 순서 있는 단계 → 참조
 
-이 spec이 다루는 데이터의 출처/목적지를 명시.
+데이터 흐름을 **시나리오 단위**로 적는다. 한 시나리오는 하나의 동작 경로다(예: "로그인 성공", "비밀번호 5회 실패로 잠금").
 
-```markdown
-| 데이터 | 소스/대상 | 방향 | 조건/비고 |
-|---|---|---|---|
-| 이메일·비밀번호 | 사용자 입력 | IN | 클라이언트 검증 |
-| Firebase Auth credential | Firebase | WRITE | signInWithEmailAndPassword |
-| ID Token | Firebase | READ | 쿠키에 httpOnly 저장 |
-| users/{uid} 문서 | Firestore | READ | 최초 로그인 시 lastLoginAt 갱신 |
-| users/{uid}.lastLoginAt | Firestore | WRITE | serverTimestamp() |
+시나리오는 두 방식 중 **하나**로 쓴다. 흐름이 선형이면 **순서 있는 단계(steps)**로 적는다. 분기(성공/실패, 조건 갈림)가 있으면 **분기 그래프(nodes/edges)**로 적는다(§5-2-1). 각 단계·노드는 그 지점이 건드리는 테이블·컬럼을 `refs`로 가리킨다. steps와 nodes가 **둘 다 비면 무효**다.
+
+아래는 선형(steps) 예시다.
+
+```json
+{
+  "dataFlowScenarios": [
+    {
+      "name": "로그인 성공",
+      "description": "회원이 이메일과 비밀번호로 로그인에 성공하면 인증 토큰을 발급하고 마지막 로그인 시각을 갱신한다.",
+      "steps": [
+        {
+          "description": "클라이언트가 입력한 이메일과 비밀번호를 인증 서버로 전송한다."
+        },
+        {
+          "description": "인증 서버가 자격 증명을 확인하고 ID 토큰을 발급해 httpOnly 쿠키에 저장한다.",
+          "refs": [
+            { "tableId": "tbl_sessions", "direction": "WRITE", "note": "세션 레코드 생성" }
+          ]
+        },
+        {
+          "description": "인증에 성공하면 사용자 문서의 마지막 로그인 시각을 현재 시각으로 갱신한다.",
+          "refs": [
+            { "tableId": "tbl_users", "field": "lastLoginAt", "direction": "WRITE", "note": "로그인 성공 시 갱신" }
+          ]
+        }
+      ]
+    }
+  ]
+}
 ```
 
+#### 구조
+
+| 필드 | 타입 | 의미 |
+|---|---|---|
+| `dataFlowScenarios[]` | 배열 | 시나리오 목록 |
+| `…[].name` | 문자열(필수) | 시나리오 이름. 동작 경로를 짧게 가리킨다. 예: `로그인 성공` |
+| `…[].description` | 문자열(선택) | 시나리오 전체를 요약한 완결 문장 1~2개 |
+| `…[].steps[]` | 배열(선택) | **순서 있는** 단계(선형 흐름). 배열 순서 = 실행 순서. nodes를 쓰면 생략 |
+| `…steps[].description` | 문자열(필수) | 그 단계에서 일어나는 일을 적은 완결 문장 |
+| `…steps[].refs[]` | 배열(선택) | 이 단계가 읽거나 쓰는 테이블·컬럼 참조(§6-2-1) |
+| `…[].nodes[]` | 배열(선택) | 분기 그래프의 노드(§5-2-1). steps를 쓰면 생략 |
+| `…[].edges[]` | 배열(선택) | 분기 그래프의 간선(§5-2-1) |
+
+> steps와 nodes는 **둘 중 하나**만 채운다. 둘 다 비면 무효다.
+
+#### 작성 원칙 — 완결 문장으로
+
+- `description`은 **6하원칙(누가·언제·어디서·무엇을·어떻게·왜)을 담은 완결 문장**으로 쓴다. 필드명이나 단어만 나열하지 않는다.
+- 단, "누가", "어디에" 같은 **소제목·라벨은 달지 않는다**. 6하원칙은 문장 안에 자연스럽게 녹인다.
+- ❌ 나쁜 예 (단어 나열): `이메일/비밀번호 → Firebase Auth → ID Token, users.lastLoginAt WRITE`
+- ❌ 나쁜 예 (소제목): `누가: 회원 / 무엇을: 로그인 / 어디에: users 테이블`
+- ⭕ 좋은 예 (완결 문장): `회원이 이메일과 비밀번호로 로그인하면, 인증 서버가 자격 증명을 확인한 뒤 마지막 로그인 시각을 갱신한다.`
+- 한 단계 = 흐름의 한 매듭. 너무 잘게 쪼개지 말고, 데이터가 한 번 이동·변형하는 단위로 묶는다.
+- 외부 API 호출도 한 단계로 적는다(예: "결제 서버에 승인을 요청한다"). 그 단계가 우리 테이블을 건드리면 `refs`로 표시한다.
+- 🔒 컬럼은 **이름으로만** 가리킨다 — `type`/`nullable` 등 정의는 적지 않는다(§6-2 SSOT 규칙). 기계 추적 가능한 참조는 `refs`로 구조화한다(§6-2-1).
+
+### 5-2-1. 분기 그래프 (nodes/edges) — 분기가 있을 때
+
+흐름이 조건에 따라 갈리면(성공/실패, 재고 있음/품절 등) steps 대신 **노드(nodes)와 간선(edges)**으로 한 시나리오 안에 분기 흐름을 한 장에 그린다.
+
+- **node** = 흐름의 한 지점. `kind`로 종류를 나눈다: `step`(기본, 처리 단계)·`decision`(마름모, 조건 갈림)·`terminal`(종료 지점).
+- **edge** = 노드 사이의 이동. `label`에 분기 조건을 적는다(예: `재고 있음`, `결제 실패`).
+- decision 노드에서 edge 여러 개가 갈라져 나가고, 각 edge의 `label`이 그 갈림의 조건이다. terminal 노드에서 끝난다.
+- 각 노드도 steps처럼 `refs`로 그 지점이 R/W하는 테이블·컬럼을 가리킨다(§6-2-1).
+
+```json
+{
+  "dataFlowScenarios": [
+    {
+      "name": "주문 결제 처리",
+      "description": "재고를 확인한 뒤 결제를 승인하거나 품절로 중단한다.",
+      "nodes": [
+        { "id": "n1", "kind": "step", "description": "주문 상태와 재고를 확인한다.",
+          "refs": [{ "tableId": "tbl_orders", "field": "status", "direction": "READ" }] },
+        { "id": "d1", "kind": "decision", "description": "재고가 있는가?" },
+        { "id": "n2", "kind": "step", "description": "결제를 승인하고 주문을 결제완료로 바꾼다.",
+          "refs": [{ "tableId": "tbl_orders", "field": "status", "direction": "WRITE", "toState": "paid" }] },
+        { "id": "t_ok", "kind": "terminal", "description": "결제 완료" },
+        { "id": "t_no", "kind": "terminal", "description": "품절 안내 후 종료" }
+      ],
+      "edges": [
+        { "from": "n1", "to": "d1" },
+        { "from": "d1", "to": "n2", "label": "재고 있음" },
+        { "from": "d1", "to": "t_no", "label": "품절" },
+        { "from": "n2", "to": "t_ok" }
+      ]
+    }
+  ]
+}
+```
+
+필드:
+
+| 필드 | 필수 | 의미 |
+|---|---|---|
+| `nodes[].id` | 필수 | 노드 식별자. 한 시나리오 안에서 유일 |
+| `nodes[].kind` | 선택 | `step`(기본)·`decision`·`terminal` |
+| `nodes[].description` | 필수 | 그 지점에서 일어나는 일(완결 문장) |
+| `nodes[].refs[]` | 선택 | 그 지점이 R/W하는 테이블·컬럼(§6-2-1) |
+| `edges[].from`/`to` | 필수 | 잇는 두 노드의 `id`. 같은 시나리오 nodes에 실재해야 함 |
+| `edges[].label` | 선택 | 분기 조건. decision에서 갈리는 edge에 붙인다 |
+
 규칙:
-- READ: 화면/기능이 읽는 데이터
-- WRITE: 기능 결과로 쓰이는 데이터
-- 조건/비고: 필터·정렬·트랜잭션 여부·인덱스 활용 등
-- 외부 API 호출도 동일 형식 (소스/대상 = "Firebase Auth", "Toss Payments API" 등)
-- 🔒 컬럼은 **이름으로만** 적는다 — `type`/`nullable` 등 정의는 붙이지 않는다(§6-2 SSOT 규칙). 기계 추적이 필요하면 서술형 대신/병행해 `logic.dataFlowRefs` 구조적 참조 사용(§6-2-1).
+- **선형이면 steps, 분기가 있으면 nodes/edges. 둘 중 하나로 작성한다**(둘 다 비면 무효).
+- decision 노드에서 나가는 edge마다 `label`로 조건을 밝힌다.
+- 상태 컬럼을 WRITE하는 node ref는 `toState`로 목표 상태를 명시한다(§6-2-1).
+
+### 5-3. stateTransitions — 화면 상태 전이 표
+
+`logic.stateTransitions`는 **UI/화면의 휘발성 상태 전이 전용**이다. 화면이 떠 있는 동안만 존재하고 새로고침하면 사라지는 상태만 적는다. 예: `idle → loading → error → success`, 모달 열림/닫힘, 폼 단계.
+
+**엔티티의 생애주기는 여기 적지 않는다.** DB에 저장되는 상태(주문 `pending→paid→delivered`, 배포 `대기→진행→완료`, 계정 `active→locked` 등)는 `db-table.stateMachines`가 SSOT다 — [[2t-decencia-channel-db-schema-v2]] §5-4. spec은 그 상태를 *이용하는* 흐름만 `dataFlowScenarios`·`businessRules`로 이름 참조한다.
+
+두 개념은 이렇게 갈린다:
+
+| 구분 | 어디에 | 무엇 |
+|---|---|---|
+| **화면 전이** (휘발성) | `spec.logic.stateTransitions` (여기, prose 표) | idle/loading/error, 모달 열림/닫힘, 폼 단계 |
+| **엔티티 상태** (저장됨) | `db-tables.stateMachines` (구조화, SSOT) | 주문 status, 배포 phase, 계정 상태 |
 
-### 5-3. stateTransitions — 상태 머신 표
+엔티티 상태를 건드리는 흐름은 `dataFlowScenarios`의 ref로 잇는다 — 상태 컬럼을 WRITE하는 ref에 `toState`를 붙인다(§6-2-1). 같은 엔티티 전이를 stateTransitions 표에도 적으면 **중복·불일치**다. 저장되는 상태는 db-tables에만.
 
-상태가 있는 기능(주문/배포/인증 등)은 머신 다이어그램 대신 표로.
+화면 상태는 머신 다이어그램 대신 표로:
 
 ```markdown
 | 현재 상태 | 이벤트 | 다음 상태 | 사이드이펙트 |
 |---|---|---|---|
 | idle | submit | loading | spinner 표시 |
 | loading | success | authenticated | 토큰 저장 + /dashboard 이동 |
-| loading | error | error | 에러 메시지 + lockCount++ |
+| loading | error | error | 에러 메시지 표시 |
 | error | retry | loading | spinner |
 | authenticated | logout | idle | 토큰 제거 |
-| error | (lockCount >= 5) | locked | 1시간 잠금 타이머 |
 ```
 
 규칙:
 - 컬럼: 현재 / 이벤트 / 다음 / 사이드이펙트 (이펙트 컬럼은 옵션)
 - 가드 조건은 이벤트 컬럼에 `(조건)` 또는 별도 컬럼
 - 진입 시점 = idle (또는 init)을 명시
+- 저장되는 엔티티 상태(주문/계정/배포 등)는 여기 말고 `db-table.stateMachines`에
 
 ### 5-4. businessRules — 도메인 규칙 목록
 
@@ -348,7 +423,7 @@ ch db-tables list --json
 - 1 규칙 = 1 불릿
 - 임계값·기간·조건을 구체 수치로
 - 큰 규칙은 별도 spec 분리 가능
-- 🔒 enum/상태값의 **허용값 집합 정의는 적지 않는다**(db-tables가 SSOT) — 그 값을 *이용한 규칙*만 적는다(§6-2). 규칙이 거는 테이블·필드는 `logic.businessRuleRefs`로 구조화(§6-2-1).
+- 🔒 enum/상태값의 **허용값 집합 정의는 적지 않는다**(db-tables가 SSOT) — 그 값을 *이용한 규칙*만 적는다(§6-2). 규칙이 어떤 테이블·컬럼을 검사·갱신하는지는 그 규칙이 작동하는 시나리오의 단계 `refs`로 가리킨다(§5-2, §6-2-1). businessRules에는 별도 구조적 참조 필드를 두지 않는다.
 
 ---
 
@@ -364,7 +439,7 @@ ch db-tables list --json
 
 | 위치 | 내용 |
 |---|---|
-| **spec** | "이 화면/기능이 어느 테이블의 어떤 컬럼을 R/W하는가" — `logic.dataFlow` 표에 **이름으로 참조만** |
+| **spec** | "이 화면/기능이 어느 테이블의 어떤 컬럼을 R/W하는가" — `logic.dataFlowScenarios`의 단계 `refs`로 **이름으로 참조만** |
 | **db-tables** | 컬럼 정의, 인덱스, 보안 규칙, 역할 매트릭스 (스키마의 SSOT) |
 
 spec.dbTableRefs는 **포인터만**. 스키마 본문은 [[2t-decencia-channel-db-schema-v2]] 참조.
@@ -376,28 +451,36 @@ spec.dbTableRefs는 **포인터만**. 스키마 본문은 [[2t-decencia-channel-
 - enum/상태값의 **정의**(허용값 집합)는 db-tables. businessRules는 그 값을 이용한 **규칙**만 적는다. (예: ❌ "status는 draft|published|archived" / ⭕ "published 상태에서만 외부 노출")
 - 같은 정보를 db-tables와 spec 양쪽에 쓰면 스키마 변경 시 반드시 어긋난다. 의심되면 정의는 지우고 `dbTableRefs` 링크로 대체.
 
-### 6-2-1. 필드 단위 구조적 참조 (`logic.dataFlowRefs` / `logic.businessRuleRefs`)
+### 6-2-1. 구조적 참조 (`steps[].refs[]` · `nodes[].refs[]`)
 
-이름 참조를 **기계가 추적 가능하게** 구조화한 필드. `logic` 안에 둔다.
+각 단계·노드가 읽거나 쓰는 테이블·컬럼을 **기계가 추적 가능하게** 가리키는 참조다. 시나리오의 `steps[]`(선형) 또는 `nodes[]`(분기 그래프) 안에 둔다(§5-2, §5-2-1).
 
 ```json
 {
-  "dataFlow": "...(서술형 마크다운, 선택)...",
-  "dataFlowRefs": [
-    { "tableId": "tbl_users", "field": "lastLoginAt", "direction": "WRITE", "note": "로그인 성공 시 갱신" },
-    { "tableId": "tbl_sessions", "direction": "READ" }
-  ],
-  "businessRules": "...(서술형, 선택)...",
-  "businessRuleRefs": [
-    { "tableId": "tbl_users", "field": "lockedUntil" }
+  "dataFlowScenarios": [
+    {
+      "name": "로그인 성공",
+      "steps": [
+        {
+          "description": "인증에 성공하면 마지막 로그인 시각을 갱신한다.",
+          "refs": [
+            { "tableId": "tbl_users", "field": "lastLoginAt", "direction": "WRITE", "note": "로그인 성공 시 갱신" },
+            { "tableId": "tbl_sessions", "direction": "READ" }
+          ]
+        }
+      ]
+    }
   ]
 }
 ```
 
-- `tableId` **필수** — db-tables의 실제 id. `field` 선택(컬럼명). `direction` `READ|WRITE|READWRITE`(dataFlow용). `note` 선택.
+- `tableId` **필수** — db-tables의 실제 id. `field` 선택(컬럼명). `direction` 선택(`READ|WRITE|READWRITE`). `note` 선택.
+- **상태 전이 링크 (`toState`)** — `field`가 그 테이블 db-table의 `stateMachines[].columnRef`와 같으면, 그 ref는 그 엔티티의 **상태머신 접근**이다. WRITE면 `toState`로 목표 상태를 밝힌다. `toState` 값은 그 머신 `states[].value` 중 하나여야 한다. 예: `{ "tableId": "tbl_orders", "field": "status", "direction": "WRITE", "toState": "paid" }`
+- 상태 **정의**(허용 상태·전이)는 db-tables.stateMachines가 SSOT다. ref는 tableId+field+toState **링크만** 저장한다 — 상태 목록을 spec에 베끼지 않는다. `ch specs get`이 그 머신 요약을 읽기 시점에 인라인해 준다([[2t-decencia-channel-db-schema-v2]] §5-4).
 - 서버가 **실존 검증**: 없는 tableId → 400, 컬럼 정의가 있는 테이블에 없는 field → 400(끊긴 참조 차단).
 - CLI는 `--logic logic.json`으로 통째 전달(별도 플래그 없음). 웹은 spec 상세의 DB 섹션에서 칩+피커로 편집.
 - **여전히 정의는 금지** — refs는 가리키기만 한다. type/nullable/enum 허용값 등은 db-tables.
+- 레거시 spec의 `dataFlowRefs`/`businessRuleRefs`(logic 최상위 배열)는 하위호환으로 읽히지만, 신규·수정 시에는 해당 컬럼을 건드리는 **단계·노드의 refs**로 옮긴다.
 
 ### 6-3. 신규 spec에서 신규 테이블이 필요한 경우 순서
 
@@ -436,22 +519,22 @@ spec 작성 시점이 아니라 **개발 진행 중에 누적**되는 일지(`sp
 ### 8-A. 화면 명세 (가장 흔함)
 
 - `ui` 모든 필드 채움 (figmaNodeId/route/file/access/interactionMap)
-- `logic.dataFlow` 필수
-- `tasks[]` 5~10개 (UI/로직/테스트 분리)
+- `logic.dataFlowScenarios` 필수 (화면이 다루는 주요 동작 경로별 시나리오)
+- `points` 화면 하나의 규모 (보통 3~8)
 - `dbTableRefs` 화면이 R/W하는 테이블 전부
 
 ### 8-B. 기능 명세 (Cron · 배치 · 외부 연동)
 
 - `ui` 통째 생략
-- `logic.dataFlow` + `logic.businessRules` 필수
-- `logic.stateTransitions` 작업 상태 머신
-- `tasks[]` 트리거·처리·에러처리·로깅
+- `logic.dataFlowScenarios` + `logic.businessRules` 필수
+- `logic.stateTransitions` 작업 진행 상태 전이 (저장되는 엔티티 상태는 db-table.stateMachines)
+- `points` 트리거·처리·에러처리를 포함한 규모
 
 ### 8-C. 공통 명세 (인증 · 알림 · 업로드)
 
 - `ui` 생략 (모듈이라 화면 없음)
 - `logic.businessRules` 중심 (정책·제약)
-- `tasks[]` 인터페이스 구현·통합 테스트
+- `points` 인터페이스 구현·통합까지 포함한 규모
 - 다른 spec이 이걸 import한다는 점을 `note`에 명시
 
 ---
@@ -462,9 +545,8 @@ spec 작성 시점이 아니라 **개발 진행 중에 누적**되는 일지(`sp
 
 | 지표 | 한계 | 조치 |
 |---|---|---|
-| `tasks` 개수 | 12+ | spec 분리 검토 |
-| Task points 합 | 30+ | sprint 1회로 못 끝남 → 분리 |
-| `logic.dataFlow` 표 행 수 | 15+ | 화면/기능이 다중일 가능성 → 분리 |
+| `points` (Story Point) | 13+ | sprint 1회로 못 끝남 → spec 분리 |
+| `logic.dataFlowScenarios` 시나리오 수 | 6+ | 화면/기능이 다중일 가능성 → 분리 |
 | `ui.interactionMap` 줄 수 | 80+ | 화면이 너무 큼 → 분리 |
 | 같은 spec에 화면 2개 이상 | 항상 분리 | 1 화면 = 1 spec |
 
@@ -472,11 +554,13 @@ spec 작성 시점이 아니라 **개발 진행 중에 누적**되는 일지(`sp
 
 ## 10. 흔한 함정
 
-- `--tasks/--ui/--logic` JSON 통째 교체 → 일부 수정도 **반드시 get 후 편집**.
+- `--ui/--logic` JSON 통째 교체 → 일부 수정도 **반드시 get 후 편집**. (`--points`는 스칼라라 안전.)
 - `dbTableRefs`를 손으로 JSON에 넣어도 서버가 무시 (CLI `--db-tables` 또는 웹 picker만 사용).
-- 항구적 작업 정의는 `tasks[].description`. 시간축 진행 메모는 workStatus(별도 스킬).
-- estimate(시간)는 사용하지 않음. points만 사용.
+- **Story를 Task로 쪼개려 하지 말 것.** 규모는 spec 단위 `--points`로 매기고, 너무 크면 spec 자체를 나눈다(§9).
+- 시간축 진행 메모는 workStatus(별도 스킬)에 적는다.
+- `tasks`는 deprecated. `--tasks`는 하위호환으로만 통과된다(사용 시 경고).
 - **스키마 정의를 logic에 베껴 넣기** — 컬럼 type/nullable/index/보안규칙/enum 허용값은 db-tables에만. spec은 이름 참조 + `dbTableRefs` 링크만(§6-2).
+- **dataFlow를 단어 나열로 적기** — 시나리오의 단계 `description`은 화살표·필드명 나열이 아니라 완결 문장으로(§5-2). "누가/어디에" 소제목도 달지 않는다.
 
 ---
 
@@ -487,10 +571,10 @@ spec 작성 시점이 아니라 **개발 진행 중에 누적**되는 일지(`sp
 1. `ch specs meta --json` → 스키마 옵션 확인
 2. 화면이 사용하는 테이블 정리 → 없으면 `ch db-tables create` 먼저
 3. **Spec ID 결정** (§1.5) — JIRA 스타일(`EPIC-NNN`) 사용 시 다음 번호 결정. 자동 ID로 가도 됨
-4. `tasks.json` 작성 (5~10개, points 부여)
+4. `points`(Story Point) 산정 — Story 하나의 규모 (§3, 보통 3~8)
 5. `ui.json` 작성 (figmaNodeId/route/file/access/interactionMap)
-6. `logic.json` 작성 (dataFlow 필수, 나머지 해당 시)
-7. `ch specs create [--id LOGIN-001] --name ... --epic ... --tasks ... --ui ... --logic ... --db-tables tbl_a,tbl_b`
+6. `logic.json` 작성 (dataFlowScenarios 필수 — 시나리오→단계→refs, 나머지 해당 시)
+7. `ch specs create [--id LOGIN-001] --name ... --epic ... --points 5 --ui ... --logic ... --db-tables tbl_a,tbl_b`
 8. `ch specs get <id> --json`으로 결과 검증
 9. SQA 항목은 [[2t-decencia-channel-sqa-v2]]에 따라 별도 등록
 10. 개발 착수 후의 진행 일지는 [[2t-decencia-channel-work-status-v2]]에서 관리

package/skill/2t-decencia-channel-sprint-builder-v2/SKILL.md

@@ -2,12 +2,12 @@
 name: 2t-decencia-channel-sprint-builder-v2
 description: |
   [2t][v2] 소통채널 Sprint 구성 가이드.
-  spec의 epic·tasks·points를 활용한 스프린트 산정과 자동 배치 원칙.
+  spec의 epic·points(Story Point)를 활용한 스프린트 산정과 자동 배치 원칙.
   Use when:
   (1) sprint를 구성할 때,
-  (2) Story Point 합산 기반 sprint 용량 산정이 필요할 때,
+  (2) Σ spec.points 기반 sprint 용량 산정이 필요할 때,
   (3) Epic·도메인·의존성을 함께 고려해 spec을 sprint에 배분할 때.
-version: 1.8.2
+version: 1.11.0
 ---
 
 <!-- ch-version-gate -->
@@ -30,7 +30,7 @@ ch check
 ## 0. Read-before-Write
 
 ```bash
-ch specs list --json > /tmp/specs.json    # 모든 spec과 tasks/points 확보
+ch specs list --json > /tmp/specs.json    # 모든 spec과 points 확보
 ch sprints list --json > /tmp/sprints.json
 # 분석 후
 ch sprints create --name "Sprint 1" --start 2026-06-01 --end 2026-06-14 --specs <id1>,<id2>
@@ -39,8 +39,8 @@ ch sprints create --name "Sprint 1" --start 2026-06-01 --end 2026-06-14 --specs
 ## 1. 산정 절차
 
 1. 모든 spec을 `ch specs list --json`로 수집.
-2. 각 spec의 `epic`, `tasks[].points` 추출.
-3. spec 단위 totalPoints = Σ tasks.points (points 없는 task는 1로 가정 또는 skip — 정책 결정).
+2. 각 spec의 `epic`, `points`(Story Point) 추출.
+3. Sprint 용량 = **Σ spec.points**. spec 하나가 규모 단위이며 별도 하위 합산은 없다. `points` 미지정 spec은 산정 전에 [[2t-decencia-channel-spec-v2]] §3으로 부여한다(미지정은 0이 아니라 누락으로 본다).
 4. Sprint 용량(예: 30 SP / 2주) 설정 후, 다음 순서로 채우기:
    - **의존성** (PRD/spec.dbTableRefs 분석): DB 테이블 신규 생성 spec → 그걸 참조하는 spec 순.
    - **Epic 단위 묶음**: 같은 Epic은 한 sprint에 몰아주는 게 컨텍스트 비용 ↓.
@@ -72,6 +72,7 @@ Sprint 1 (06-01 ~ 06-14, 용량 30 SP)
 
 ## 4. 흔한 함정
 
-- points 없는 task가 많으면 산정 부정확 → spec 작성 시 모든 task에 points 부여 권장(0/1/2/3/5/8).
-- Sprint에 spec 추가 후 spec 내 tasks를 늘리면 sprint SP 합이 변동 — sprint 재산정 필요.
+- `points` 미지정 spec이 많으면 산정 부정확 → spec마다 `--points` 부여(피보나치 1/2/3/5/8/13).
+- Sprint에 담은 spec의 `points`를 바꾸면 sprint SP 합이 변동 — sprint 재산정 필요.
+- Story를 Task로 쪼개 합산하지 않는다 — 규모는 spec 단위 `points` 하나다([[2t-decencia-channel-spec-v2]] §3).
 - Sprint와 spec.workStatus는 별개. Sprint 진행 상황은 sprint 자체 status로, spec별 메모는 workStatus로.

package/skill/2t-decencia-channel-sprint-runner/SKILL.md

@@ -2,7 +2,7 @@
 name: 2t-decencia-channel-sprint-runner
 description: 특정 Sprint를 끝까지 실행(run)하는 오케스트레이터 스킬. Sprint의 spec을 시드로 이슈 목록을 분해·발행(github-issue)하고, GitHub milestone에 묶인 이슈를 상태별로 분류해 issue-coder(병렬)·pr-merger(직렬)로 전진시킨 뒤, 사람확인이 필요한 곳에서 멈춘다. 사람이 확인·체크 후 재호출하면 멱등하게 이어간다(반복 루프). "스프린트 돌려줘"·"sprint N 실행"·"이 스프린트 개발 진행해줘" 류 요청 시.
 allowed-tools: Skill Agent Read Bash(ch:*) Bash(gh:*) Bash(git:*)
-version: 1.8.2
+version: 1.11.0
 ---
 
 <!-- ch-version-gate -->