@decencia/ch-cli 1.31.0 → 1.31.2

package/agent/2t-decencia-channel-issue-coder.md

@@ -3,7 +3,7 @@ name: 2t-decencia-channel-issue-coder
 description: GitHub issue 1개를 입력으로 받아 끝까지 처리하는 코딩 에이전트. 이슈 읽기 → 소통채널 spec/SQA 확인 → git worktree+브랜치에서 구현 → 자체 소프트리뷰 루프 → unittest + SQA → PR 생성 → 소통채널 workStatus·이슈 기록. 다수 병렬 실행 전제, PR까지만(머지·base 브랜치 직접 push·이슈 close는 사람).
 tools: Read, Write, Edit, Grep, Glob, Bash, Agent
 model: opus
-version: 1.31.0
+version: 1.31.2
 ---
 
 ## 역할

package/agent/2t-decencia-channel-pr-merger.md

@@ -3,7 +3,7 @@ name: 2t-decencia-channel-pr-merger
 description: issue-coder가 낸 PR을 기본 완전 자율로 base 브랜치(기본 브랜치 또는 sprint 통합 브랜치)에 머지하는 에이전트. 핵심 역량은 다수 병렬 worktree가 만든 충돌을 작업 의도 기반(semantic)으로 해결하는 것. CI green+충돌없음이면 바로 squash 머지, 충돌이면 의도대로 해결 후 테스트로 검증하여 머지. 재SQA·전면 재리뷰는 하지 않음. 다수 PR은 직렬 머지.
 tools: Read, Write, Edit, Grep, Glob, Bash
 model: opus
-version: 1.31.0
+version: 1.31.2
 ---
 
 ## 역할

package/agent/2t-decencia-channel-terraformer.md

@@ -3,7 +3,7 @@ name: 2t-decencia-channel-terraformer
 description: 소통채널을 쓰지 않던 기존 코드베이스를 역분석하여 소통채널 프로젝트로 편입(terraforming)하는 자율 에이전트. 코드가 single source of truth — 코드를 읽어 DB 스키마 → 기능명세(spec) → PRD를 bottom-up으로 역생성한다(SQA 제외). 대량 분석은 서브에이전트 병렬, 코드로 못 메우는 의도는 [추정]으로 채우고 "사람확인 질문 리스트"를 산출물로 남긴다. PR/머지·이슈 발행은 하지 않음.
 tools: Read, Write, Edit, Grep, Glob, Bash, Agent
 model: opus
-version: 1.31.0
+version: 1.31.2
 ---
 
 ## 역할

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decencia/ch-cli",
-  "version": "1.31.0",
+  "version": "1.31.2",
   "description": "Decencia Communication Channel CLI",
   "main": "dist/index.js",
   "bin": {

package/skill/2t-decencia-channel-change-manager/SKILL.md

@@ -2,7 +2,7 @@
 name: 2t-decencia-channel-change-manager
 description: 기존 소통채널 프로젝트의 기능 추가/수정을 사용자와 대화로 명확화 → 전파 스킬로 연관 PRD/spec/DB/SQA 일괄 갱신 → 변경으로 생긴 새 할일을 GitHub 이슈로 발행하는 오케스트레이터 스킬. (1)대화로 변경 내용 확정 → (2)[게이트] 영향 범위 확인 후 전파 적용 → (3)[게이트] 할일 목록 확인 후 이슈 발행. "이 기능 바꿀래"·"기획 수정"·"이거 추가해줘(기존 프로젝트)" 류 요청 시.
 allowed-tools: Bash(ch:*) Bash(git:*) Bash(gh:*) Read Write
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

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

@@ -10,7 +10,7 @@ description: |
   (3) 명세·DB·SQA가 서로 어긋나 있는 의심이 들 때 (정합성 점검),
   (4) PRD 갱신 후 하위 spec/db/SQA로 변경분을 흘려보내야 할 때,
   (5) Sprint 진행 중 도메인 규칙·스키마가 흔들렸을 때 연쇄 갱신이 필요할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

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

@@ -10,7 +10,7 @@ description: |
   (4) ch screens 명령(list/get/create/update/delete/migrate)으로 화면을 다루거나 레거시 프로젝트를 화면 모드로 이관할 때,
   (5) spec의 화면 연결을 CLI로 걸거나 풀 때 (`ch specs screen-refs`),
   (6) Spec ID를 JIRA 스타일(`LOGIN-001`)로 직접 지정할 때 (`ch specs create --id`).
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -56,8 +56,7 @@ ch specs create --id AUTH-001 \
   --points 5 \
   --story "회원은 이메일과 비밀번호로 로그인해서, 재인증 없이 자신의 프로젝트에 바로 접근하고 싶다." \
   --preconditions ./preconditions.md \
-  --logic ./logic.json \
-  --db-tables tbl_users,tbl_sessions
+  --logic ./logic.json
 
 # 수정: 지정한 플래그만 PATCH. --no-version 시 버전 기록 생략.
 ch specs update <specId> --story "..." --no-version
@@ -69,7 +68,8 @@ ch specs update <specId> --points 8 --no-version
 - `--preconditions <텍스트|파일경로>` — 사전 조건 마크다운.
 - `--domain`은 쉼표로 **복수** 지정 (`--domain 회원,관리자`).
 - `--type`(기능유형)·`--content`는 스토리 명세 모드에서 쓰지 않는다 (레거시 전용).
-- `--ui`는 화면 연결이 필요할 때 `{"screenRefs":[...]}`만 싣는다 (생성 시에만 — §1 화면 연결).
+- `--ui`는 생성 시 보통 생략한다 — 화면설계서는 spec보다 나중(작성 순서 ④)이라, 화면을 만든 뒤 `ch specs screen-refs`로 연결한다(§1 화면 연결).
+- `--db-tables`·흐름 `refs`도 생성 시 생략한다 — DB 스키마는 ③정책정의서 뒤라, 테이블을 만든 뒤 `ch specs update --db-tables`·`--logic`(refs 보강)으로 연결한다([[2t-decencia-channel-spec-v2]] §10-3).
 
 **레거시 모드** (`storySpecsEnabled` 미설정·false — 기존 프로젝트):
 

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

@@ -8,7 +8,7 @@ description: |
   (2) DB 테이블 단위로 컬럼·인덱스·보안규칙을 등록·수정할 때,
   (3) 새 테이블을 추가하면서 전체 인벤토리도 함께 업데이트할 때,
   (4) spec.dbTableRefs와 양방향 동기화가 필요한 작업 시.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -26,7 +26,9 @@ ch check
 구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
 
 
-# DB 스키마 — 전체 스펙 + per-table 분담
+# DB 스키마
+
+> **작성 순서상 ③정책정의서 뒤 · ④화면설계서 앞이다** — 정책(만료·상태·타임아웃)이 스키마를 결정하므로 정책 확정 후에 설계하고, 화면설계서가 `테이블.컬럼`을 참조하므로 그 앞이어야 한다. 테이블을 만들면 spec을 되짚어 `ch specs update --db-tables`·흐름 refs를 보강한다([[2t-decencia-channel-spec-v2]] §10-3). — 전체 스펙 + per-table 분담
 
 소통채널은 두 개의 리소스를 함께 운영한다.
 

package/skill/2t-decencia-channel-github-issue/SKILL.md

@@ -2,7 +2,7 @@
 name: 2t-decencia-channel-github-issue
 description: gh CLI로 현재 repo에 GitHub 이슈를 작성한다. 이슈 1개=유형 1개(feat/fix/bug), 표준 본문 양식(작업내용·관련 명세 백링크·완료조건)으로 발행. "이슈 만들어줘"/"깃헙 이슈로 등록해줘" 요청 시, 또는 소통채널 기획·명세 작업 후 처리할 일들을 GitHub 이슈로 옮길 때 사용. 멱등성/중복방지·확인단계는 다루지 않음(요청대로 바로 생성).
 allowed-tools: Bash(gh:*) Bash(git:*) Read Write
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

package/skill/2t-decencia-channel-orchestrator/SKILL.md

@@ -2,7 +2,7 @@
 name: 2t-decencia-channel-orchestrator
 description: 소통채널 작업의 단일 진입점(디스패처). 사용자 요청을 듣고 7종(bootstrap·terraformer·change-manager·github-issue·issue-coder·pr-merger·sprint-runner) 중 적절한 곳으로 라우팅하고, 필요하면 여러 단계를 순차 오케스트레이션한다. 대화형 스킬은 메인 세션에서 Skill로, 자율 에이전트는 Agent로 위임. "소통채널 작업 해줘"·"이거 어떻게 처리하지?"처럼 무엇부터 할지 모를 때, 또는 신규기획/코드편입/기획변경/이슈/구현/머지/스프린트실행 어디로든 시작할 때.
 allowed-tools: Skill Agent Read Bash(ch:*) Bash(gh:*) Bash(git:*)
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

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

@@ -8,7 +8,7 @@ description: |
   (1) 정책정의서를 새로 쓰거나 수정할 때,
   (2) 유저플로우·기능명세를 검토하다 "이건 정해진 게 없다"는 질문이 나왔을 때,
   (3) 알림 발송 매트릭스·크레딧 지급 기준·타임아웃 처리 같은 횡단 정책을 정리할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -29,6 +29,7 @@ ch check
 # 정책정의서 — 작성 표준
 
 정책정의서는 **여러 Story·영역에 걸치는 프로젝트 정책**을 판정 가능한 문장으로 기록하는 문서다. 웹 "정책정의서" 탭에 올린다.
+**작성 순서상 ③이다** — ①기능명세·②유저플로우에서 질문을 수확해 쓰고, ④화면설계서·⑤검증기준서가 뒤따른다.
 
 ## 0. 경계 — 어디에 적나
 

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

@@ -7,7 +7,7 @@ description: |
   (1) PRD를 작성하거나 갱신할 때,
   (2) PRD 구성에서 Epic/스토리 구조를 후속 spec 작성에 매핑할 때,
   (3) Read-before-Write 규칙으로 PRD content를 안전하게 수정해야 할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

package/skill/2t-decencia-channel-project-bootstrap/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: 2t-decencia-channel-project-bootstrap
-description: 신규 기획을 사용자와 대화하며 step-by-step으로 소통채널 프로젝트로 만드는 오케스트레이터 스킬. (1)대화로 PRD 완성 → (2)기능명세(spec) 내용 확정 → (3)DB 스키마 → (4)spec 업로드 → (5)화면 구성·연결 → (6)SQA 시트. 각 단계 사용자 승인 게이트, 작성 디테일은 기존 2t-decencia-channel-*-v2 스킬을 적극 재사용. "새 기획 만들어줘"·"프로젝트 처음부터 세팅" 류 요청 시.
+description: 신규 기획을 사용자와 대화하며 step-by-step으로 소통채널 프로젝트로 만드는 오케스트레이터 스킬. (1)대화로 PRD 완성 → (2)기능명세(spec) 내용 확정 → (3)spec 업로드 → (4)유저플로우 → (5)정책정의서 → (6)DB 스키마·spec 연결 → (7)화면설계서(화면 생성·연결) → (8)검증기준서(SQA). 각 단계 사용자 승인 게이트, 작성 디테일은 기존 2t-decencia-channel-*-v2 스킬을 적극 재사용. "새 기획 만들어줘"·"프로젝트 처음부터 세팅" 류 요청 시.
 allowed-tools: Bash(ch:*) Bash(git:*) Read Write
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -27,8 +27,10 @@ ch check
 
 ## 핵심 원칙
 - **각 단계마다 사용자 승인 게이트.** "괜찮다"는 확인 없이는 절대 다음 단계로 넘어가지 않는다. 수정 요청이면 그 단계를 반복.
-- **화면은 기능에서 파생된다. 기능명세가 먼저, 화면 구성이 뒤다.** 기능을 알아야 화면을 짤 수 있다.
-- 작성 디테일은 호출: PRD→`2t-decencia-channel-prd-v2`, 기능명세→`2t-decencia-channel-spec-v2`, 화면→`2t-decencia-channel-cli-v2` §3(screens 명령), DB→`2t-decencia-channel-db-schema-v2`, SQA→`2t-decencia-channel-sqa-v2`, 업로드→`2t-decencia-channel-cli-v2`.
+- **기획 문서 작성 순서는 고정이다: ①기능명세 → ②유저플로우 → ③정책정의서 → ④화면설계서 → ⑤검증기준서.** 기능적 기획(①~③)을 다 끝낸 뒤 개발적 형상(DB·화면)으로 들어간다.
+- **DB 스키마는 ③과 ④ 사이에 끼어든다** — 정책(만료·상태·타임아웃)이 스키마를 결정하므로 정책 뒤가 맞고, "테이블.컬럼"을 참조하는 첫 문서가 화면설계서라 그 앞이어야 한다.
+- **화면·DB 모두 "비워뒀다 나중에 연결"이다** — spec보다 화면을 먼저 만들지 않고(§7에서 연결), 테이블도 먼저 만들지 않는다(§6에서 연결·refs 보강).
+- 작성 디테일은 호출: PRD→`2t-decencia-channel-prd-v2`, 기능명세→`2t-decencia-channel-spec-v2`, 유저플로우→`2t-decencia-channel-userflow-v2`, 정책→`2t-decencia-channel-policy-v2`, 화면→`2t-decencia-channel-screen-v2`(+`cli-v2` §3 screens 명령), DB→`2t-decencia-channel-db-schema-v2`, SQA→`2t-decencia-channel-sqa-v2`, 업로드→`2t-decencia-channel-cli-v2`.
 
 ## Use when
 - "새 기획 만들어줘", "프로젝트 처음부터 세팅해줘", 아이디어/요구사항을 소통채널 프로젝트로 구조화하고 싶을 때.
@@ -36,12 +38,17 @@ ch check
 ## 전체 흐름
 
 ```
-(1) PRD → (2) 기능명세 내용 확정 → (3) DB 스키마 → (4) spec 업로드 → (5) 화면 구성·연결 → (6) SQA
+(1) PRD → (2) 기능명세 내용 확정 → (3) spec 업로드(연결 없이)
+        → (4) 유저플로우 → (5) 정책정의서
+        → (6) DB 스키마 + spec 연결(dbTableRefs·흐름 refs 보강)
+        → (7) 화면설계서(화면 생성·연결) → (8) 검증기준서(SQA)
 ```
 
-**spec 업로드는 DB 스키마 뒤, 화면 구성 앞이다.**
-- 테이블 연결(`dbTableRefs`)은 spec 생성 때 함께 싣는다. 그래서 DB가 먼저다.
-- 화면 연결(`screenRefs`)은 화면을 만든 뒤 §5에서 `ch specs screen-refs`로 건다. 생성 때 실을 필요가 없다.
+(2)~(8)이 기획 문서 작성 순서 ①기능명세→②유저플로우→③정책정의서→④화면설계서→⑤검증기준서에 대응하고, DB 스키마(6)는 ③과 ④ 사이에 끼어든다.
+
+- spec은 **테이블·화면 연결 없이** 먼저 올린다. 로직 플로우도 이 시점엔 `refs` 없이 완결 문장으로만 쓴다(서버가 refs의 tableId를 실존 검증하므로).
+- 테이블 연결(`dbTableRefs`)과 흐름 `refs`는 §6에서 `ch specs update`로 보강한다.
+- 화면 연결(`screenRefs`)은 화면을 만든 뒤 §7에서 `ch specs screen-refs`로 건다.
 
 ---
 
@@ -56,7 +63,7 @@ ch check
 - **신규 프로젝트는 서버가 `screensEnabled: true` + `storySpecsEnabled: true`로 만든다.** 화면 정보의 SSOT는 screens 리소스다. **신규 프로젝트 spec에는 `ui.route`를 쓰지 않는다.**
 - `storySpecsEnabled=true`면 spec은 **스토리 명세 구조**다(스토리문장·사전 조건·로직 플로우·비즈니스 규칙 — [[2t-decencia-channel-spec-v2]] §1). 기존 프로젝트(플래그 없음)는 종전 ui/logic 구조 그대로다.
 - 기존 프로젝트를 이어 쓰면 `ch projects info --json`으로 `screensEnabled`를 본다. **키가 아예 없거나 false면 레거시다.** (레거시 프로젝트 응답에는 이 키가 없다. 없음 = false로 읽는다.)
-- **레거시는 route 방식을 그대로 유지한다.** §5(화면 구성)를 건너뛰고 spec의 `ui.route`를 계속 쓴다.
+- **레거시는 route 방식을 그대로 유지한다.** §7(화면설계서)을 건너뛰고 spec의 `ui.route`를 계속 쓴다.
 
 ### 0-2. 레거시를 화면 모드로 옮길 때만
 - `ch screens migrate --dry-run`으로 계획을 보고 → 사용자 확인 → `ch screens migrate`.
@@ -77,23 +84,15 @@ ch check
 - Epic은 도메인 단위 코드로 (AUTH/PROD/ORDER/POINT/ADMIN/SYS … — [[2t-decencia-channel-spec-v2]] §3). PRD 기능 요구사항의 카테고리와 같은 코드다.
 - spec 본문은 스토리 명세 구조로 짠다: 스토리문장(As a/I want/So that 줄글) · 사전 조건 · 로직 플로우 · 비즈니스 규칙.
   - interactionMap·primaryActions·keyInformation·stateTransitions는 쓰지 않는다 — 스토리 명세에 없다.
-  - 화면 연결(`screenRefs`)은 지금은 비워둔다. 화면이 아직 없다 — §5에서 연결한다.
+  - 화면 연결(`screenRefs`)은 지금은 비워둔다. 화면이 아직 없다 — §7에서 연결한다.
   - 레거시 프로젝트(§0-1)는 예외다. 종전 ui/logic 구조([[2t-decencia-channel-spec-v2]] §L)로 쓴다.
-- 이 단계의 산출물은 **기능 목록 + spec 본문 초안**이다. 항목: 이름 · Spec ID(EPIC-NNN) · epic · points · 스토리문장 · 필요 테이블 후보.
-- ⚠️ **서버 업로드는 여기서 하지 않는다.** 테이블을 먼저 만들고 §4에서 `dbTableRefs`와 함께 생성한다.
+- 이 단계의 산출물은 **기능 목록 + spec 본문 초안**이다. 항목: 이름 · Spec ID(EPIC-NNN) · epic · points · 스토리문장 · 필요 테이블 후보(§6에서 사용).
 - → **[게이트] 사용자 확인.** OK면 3단계.
 
-## 3. DB 스키마
-*(기능명세 승인 후에만)*
-- `2t-decencia-channel-db-schema-v2`로 db-schema(ERD/정책) + db-tables(컬럼·인덱스·보안규칙) 작성.
-- `spec.dbTableRefs` ↔ `dbTable.relatedSpecIds` 양방향.
-- **spec 업로드보다 앞선다.** spec 생성 시 `--db-tables`에 실제 tableId가 필요하기 때문이다([[2t-decencia-channel-spec-v2]] §10-3 — 테이블 먼저, spec 연결은 그 다음).
-- → **[게이트] 사용자 확인.** OK면 4단계.
-
-## 4. spec 업로드
-*(테이블이 다 만들어진 뒤)*
+## 3. spec 업로드
+*(기능명세 승인 후)*
 
-이제 spec을 서버에 만든다. 테이블 연결을 생성에 함께 싣는다. 화면 연결은 §5에서 건다.
+spec을 서버에 만든다. **테이블·화면 연결은 싣지 않는다** — DB는 §6, 화면은 §7에서 연결한다.
 
 ```bash
 ch specs create --id PROJ-001 --name "프로젝트 목록" \
@@ -101,18 +100,41 @@ ch specs create --id PROJ-001 --name "프로젝트 목록" \
   --epic PROJ --points 5 \
   --story "관리자는 진행 중인 프로젝트를 한눈에 보고, 원하는 프로젝트로 바로 들어가고 싶다." \
   --preconditions ./preconditions.md \
-  --logic logic.json --db-tables tbl_projects,tbl_members
+  --logic logic.json
 ```
 
 ⚠️ `--device`·`--domain`은 **필수 플래그**다. 값은 `ch specs meta --json`이 준 스키마 안에서 고른다. `--domain`은 쉼표로 복수 지정 가능하다.
 
 - `logic.json`은 로직 플로우 시나리오(실패·차단 분기 포함) + businessRules — [[2t-decencia-channel-spec-v2]] §7·§8.
-- `--ui`는 생성 시점에 넣지 않는다. 화면이 아직 없다 — 연결은 §5에서 `ch specs screen-refs`로 건다.
+- ⚠️ **이 시점엔 흐름 `refs`를 넣지 않는다** — 테이블이 아직 없고, 서버가 refs의 tableId를 실존 검증해 400이 난다. 완결 문장으로만 쓰고 §6에서 refs를 보강한다.
+- `--ui`도 넣지 않는다. 화면이 아직 없다 — 연결은 §7에서 `ch specs screen-refs`로 건다.
 - 레거시 프로젝트(§0-1)는 종전 플래그(`--type`·`--content`·`--ui ui.json`)를 그대로 쓴다 — [[2t-decencia-channel-cli-v2]] §1.
+- → **[게이트] 사용자 확인.** OK면 4단계.
+
+## 4. 유저플로우
+*(spec 업로드 후)*
+- [[2t-decencia-channel-userflow-v2]]대로 **분기 있는 여정만** 골라 Mermaid로 그린다 (프로젝트당 3~7장, 해피패스 중앙 일직선).
+- 대상은 PRD·Epic-Story 목록에서 뽑는다: 돈이 흐르는 경로·최빈 경로·역방향·역할별 여정 우선.
+- `ch userflows create --name "<여정>" --file ./flow.mmd`로 업로드. 웹 "유저플로우" 탭에서 확인.
 - → **[게이트] 사용자 확인.** OK면 5단계.
 
-## 5. 화면 구성·연결
-*(spec 업로드 후에만. 레거시 프로젝트는 건너뛴다 — §0-1)*
+## 5. 정책정의서
+*(유저플로우 후)*
+- [[2t-decencia-channel-policy-v2]]의 3단계: **수확**(유저플로우·로직 플로우의 분기에서 "정해진 게 없는" 질문 발굴) → **확정**(질문마다 선택지 2~4개를 사용자에게 제시해 결정받기 — 임의 결정 금지) → **명문화**(판정 가능한 문장).
+- `ch policies create --id POL-001 --name "<정책명>" --category <영역> --file ./policy.md --related-specs <ids>`로 업로드.
+- → **[게이트] 사용자 확인.** OK면 6단계.
+
+## 6. DB 스키마 — 작성 + spec 연결·refs 보강
+*(정책정의서 후에만 — 정책(만료·상태·타임아웃)이 스키마를 결정하므로 이 순서다)*
+
+- `2t-decencia-channel-db-schema-v2`로 db-schema(ERD/정책) + db-tables(컬럼·인덱스·보안규칙·stateMachines) 작성. §2의 "필요 테이블 후보"와 §5의 정책(수치·상태)이 입력이다.
+- 테이블이 생겼으니 **spec을 되짚어 연결·보강**한다 (spec마다):
+  1. `ch specs update <specId> --db-tables tbl_a,tbl_b` — `dbTableRefs` 연결 (서버가 `dbTable.relatedSpecIds`와 양방향 동기화)
+  2. 로직 플로우 `refs` 보강 — `ch specs get <id> --json`으로 logic을 받아 각 단계·노드에 `refs`(tableId·field·direction·toState)를 채우고 `ch specs update <id> --logic <파일>`로 통째 교체 (Read-before-Write — [[2t-decencia-channel-spec-v2]] §10-2)
+- → **[게이트] 사용자 확인.** OK면 7단계.
+
+## 7. 화면설계서 — 화면 생성·연결
+*(DB 스키마 후에만. 레거시 프로젝트는 건너뛴다 — §0-1)*
 
 기능들을 **화면에 배치**한다. 화면은 사용자가 실제로 마주하는 단위다.
 화면마다 적을 내용(필수 기재항목 6종·디스크립션 작성규칙·예외상태 4종)은 [[2t-decencia-channel-screen-v2]]를 따른다.
@@ -158,7 +180,7 @@ ch specs screen-refs PROJ-002 --screens SCR-PROJECTS,SCR-PROJECT-DETAIL   # 화
 
 6. 검증: `ch specs get PROJ-001 --json`의 `ui.screenRefs`와 `ch screens get SCR-PROJECTS --json`의 `relatedSpecIds`가 **양쪽 다** 채워졌는지 본다.
 
-7. → **[게이트] 사용자 확인.** OK면 6단계.
+7. → **[게이트] 사용자 확인.** OK면 8단계.
 
 ### 🚫 1 spec = 1 화면으로 뽑지 마라
 그러면 화면이 route의 복사본이 된다. 화면 모델을 만든 이유가 사라진다.
@@ -192,9 +214,9 @@ ch specs screen-refs PROJ-002 --screens SCR-PROJECTS,SCR-PROJECT-DETAIL   # 화
 ### 화면의 단위는 사용자가 이동하는 URL이다
 탭·모달·바텀시트는 별도 화면이 아니다. 그 화면의 `states`·`entryPoints`로 적는다.
 
-## 6. SQA 시트
-*(화면 연결 후에만)*
-- `2t-decencia-channel-sqa-v2`로 SQA 작성: **A축**(명세별 기능 TC — 영역별 번들에서 도출) + **B축**(비기능 표준 40).
+## 8. 검증기준서 (SQA)
+*(화면 연결 후에만 — 작성 순서 마지막)*
+- `2t-decencia-channel-sqa-v2`로 작성: **A축**(명세별 기능 TC — Story당 4겹: 해피패스/경계·예외/권한/상태반영) + **B축**(비기능 표준 40) + **시나리오**(§4.6 — ⑤단계에서 유저플로우 기반 5~10개, Sprint 완료조건으로 할당).
 
 ### 디자인 핸드오프로 이어가기 (안내만)
 화면이 다 짜였으면 **디자인 핸드오프**로 넘어갈 수 있다. 디자이너가 웹 화면 탭 **[통합 핸드오프 zip 받기]** 또는 `ch handoff export --dir <폴더>`로 화면 기획 묶음을 받아 Claude Design에 넣는다. 절차는 `docs/design-handoff-sop.md`. 읽기전용 export라 이 스킬이 대신 실행하지 않는다 — 화면이 막 만들어진 이 지점에서 **사용자에게 안내만** 한다. (명령 상세는 [[2t-decencia-channel-cli-v2]] handoff 명령.)

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

@@ -9,7 +9,7 @@ description: |
   (1) 화면(screens) 문서를 작성·수정할 때,
   (2) 화면의 표시 데이터·액션·입력 검증·예외상태를 기재할 때,
   (3) 웹 "화면" 탭의 IA 트리·화면 상세에 올릴 내용을 쓸 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -33,6 +33,8 @@ ch check
 
 역할 분담: 흐름(시나리오)은 spec([[2t-decencia-channel-spec-v2]] §7), 여정 갈림길은 유저플로우([[2t-decencia-channel-userflow-v2]]), 횡단 정책은 정책정의서([[2t-decencia-channel-policy-v2]]). 화면설계서는 **그 화면 안에서 보이는 것·눌리는 것**만 적는다.
 
+> **작성 순서상 ④다** — ①기능명세 → ②유저플로우 → ③정책정의서 → DB 스키마가 끝난 뒤에 화면을 만든다. **spec보다 화면을 먼저 만들지 않는다.** 화면을 만들면서 `ch specs screen-refs <specId> --screens <ids>`로 기존 spec들과 연결하고, 그다음 ⑤검증기준서로 넘어간다. (영역별 표시 데이터의 `테이블.컬럼` 참조는 DB 스키마가 앞서 있어야 쓸 수 있다.)
+
 ## 1. 필수 기재항목
 
 | 항목 | 내용 |

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

@@ -12,7 +12,7 @@ description: |
   (3) 스토리문장·사전 조건·로직 플로우·비즈니스 규칙을 작성할 때,
   (4) Story 규모를 Story Point(`--points`)로 매길 때,
   (5) 신규 spec ID를 `AUTH-001` 같은 JIRA 스타일로 부여할 때 (`ch specs create --id`).
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -34,6 +34,9 @@ ch check
 
 CLI 명령은 [[2t-decencia-channel-cli-v2]], DB 테이블 작성은 [[2t-decencia-channel-db-schema-v2]] 참조.
 
+> **기획 문서 작성 순서**: ①기능명세(이 문서) → ②유저플로우 → ③정책정의서 → (DB 스키마) → ④화면설계서 → ⑤검증기준서.
+> **화면도 테이블도 먼저 만들지 않는다** — spec 작성 시점에 둘 다 없는 게 정상이다. DB는 ③ 뒤에 만들어 `--db-tables`·흐름 refs를 보강하고(§10), 화면은 ④에서 만들어 `ch specs screen-refs`로 연결한다(§9).
+
 ---
 
 ## 0. 두 가지 모드
@@ -195,7 +198,10 @@ Story가 무엇인지 **As a / I want / So that** 형식의 줄글로 적는다.
 
 ## 7. 로직 플로우 (dataFlowScenarios)
 
-동작 경로를 **시나리오 단위**로 적는다. 정상·예외를 따로 나누지 않는다 — **실패·차단·이탈 경로는 흐름 안의 분기로 포함**한다(분기가 있으면 nodes/edges, 경로가 아예 다른 여정이면 별도 시나리오).
+동작 경로를 **시나리오 단위**로 적는다. 정상·예외를 따로 나누지 않는다 — **실패·차단·이탈 경로는 흐름 안의 분기로 포함**한다(분기는 nodes/edges — §7-2).
+
+- **별도 시나리오는 진입점이 다를 때만** 판다 — 다른 트리거·다른 액터·다른 시작 상태일 때. **같은 진입에서 조건으로 갈라지는 것(실패·차단·타임아웃·품절)은 전부 그 시나리오의 분기다.**
+- 권장: **spec당 시나리오 1~3개.** 4개 이상이면 먼저 분기로 합칠 수 있는지 본다.
 
 시나리오는 두 방식 중 하나로 쓴다. 선형이면 **순서 있는 단계(steps)**, 분기가 있으면 **분기 그래프(nodes/edges)**(§7-2). 각 단계·노드는 건드리는 테이블·컬럼을 `refs`로 가리킨다. steps와 nodes가 둘 다 비면 무효다.
 
@@ -224,20 +230,13 @@ Story가 무엇인지 **As a / I want / So that** 형식의 줄글로 적는다.
           ]
         }
       ]
-    },
-    {
-      "name": "비밀번호 5회 실패로 잠금",
-      "description": "비밀번호를 5회 연속 틀리면 계정을 1시간 잠그고 로그인 시도를 차단한다.",
-      "steps": [
-        { "description": "5회째 실패를 감지하면 계정 문서에 잠금 해제 시각을 기록한다.",
-          "refs": [ { "tableId": "tbl_users", "field": "lockedUntil", "direction": "WRITE" } ] },
-        { "description": "잠금 중 로그인 시도에는 남은 잠금 시간을 안내하고 인증을 수행하지 않는다." }
-      ]
     }
   ]
 }
 ```
 
+> 로그인 실패·잠금 경로를 별도 시나리오로 파지 않는다 — 같은 진입이므로 **분기**다. 분기가 있는 순간 이 시나리오는 §7-2의 그래프로 옮긴다(아래 예시가 바로 그것).
+
 구조:
 
 | 필드 | 타입 | 의미 |
@@ -256,33 +255,43 @@ Story가 무엇인지 **As a / I want / So that** 형식의 줄글로 적는다.
 - ⭕ `회원이 이메일과 비밀번호로 로그인하면, 인증 서버가 자격 증명을 확인한 뒤 마지막 로그인 시각을 갱신한다.`
 - 한 단계 = 데이터가 한 번 이동·변형하는 매듭(외부 API 호출도 한 단계). 너무 잘게 쪼개지 않는다.
 - 🔒 컬럼은 **이름으로만** 가리킨다. type/nullable 등 정의는 적지 않는다 (§10-1 SSOT 규칙).
+- **spec 작성 시점(DB 스키마 전)에는 `refs`를 넣지 않는다** — 서버가 tableId를 실존 검증해 400이 난다. 완결 문장으로만 쓰고, DB 스키마 단계에서 refs를 보강한다(§10-3).
 
 ### 7-2. 분기 그래프 (nodes/edges)
 
 흐름이 조건에 따라 갈리면 steps 대신 노드·간선으로 그린다. 성공·실패가 한 그래프에서 갈리면 시나리오 하나로 묶는다.
 
-- **node**: `id`(시나리오 안 유일, 필수) · `kind`(`step` 기본 · `decision` 조건 갈림 · `terminal` 종료) · `description`(완결 문장, 필수) · `refs[]`(선택, §10-2)
+- **node**: `id`(시나리오 안 유일, 필수 — `n1·d1·t1` 순번이면 충분하다) · `kind`(`step` 기본 · `decision` 조건 갈림 · `terminal` 종료) · `description`(완결 문장, 필수) · `refs[]`(선택, §10-2)
 - **edge**: `from`/`to`(노드 id, 필수) · `label`(분기 조건 — decision에서 갈라지는 edge마다 붙인다)
 - 선형이면 steps, 분기면 nodes/edges — 둘 중 하나로만(둘 다 비면 무효). 상태 컬럼을 WRITE하는 ref는 `toState`로 목표 상태를 명시한다(§10-2).
 
+예시 — §7-1의 로그인을 분기까지 담아 **시나리오 하나**로 그린 것이다(성공·재입력·잠금을 시나리오 셋으로 나누지 않는다):
+
 ```json
 {
   "dataFlowScenarios": [
     {
-      "name": "주문 결제 처리",
+      "name": "로그인",
       "nodes": [
-        { "id": "n1", "kind": "step", "description": "주문 상태와 재고를 확인한다." },
-        { "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": "품절 안내 후 종료" }
+        { "id": "n1", "kind": "step", "description": "회원이 입력한 이메일과 비밀번호를 인증 서버로 보낸다." },
+        { "id": "d1", "kind": "decision", "description": "자격 증명이 유효한가?" },
+        { "id": "n2", "kind": "step", "description": "ID 토큰을 발급하고 마지막 로그인 시각을 갱신한다.",
+          "refs": [{ "tableId": "tbl_users", "field": "lastLoginAt", "direction": "WRITE" }] },
+        { "id": "t1", "kind": "terminal", "description": "로그인 완료 — 대시보드 진입" },
+        { "id": "d2", "kind": "decision", "description": "연속 실패가 5회째인가?" },
+        { "id": "n3", "kind": "step", "description": "계정을 1시간 잠그고 잠금 해제 시각을 기록한다.",
+          "refs": [{ "tableId": "tbl_users", "field": "lockedUntil", "direction": "WRITE" }] },
+        { "id": "t2", "kind": "terminal", "description": "잠금 안내 후 종료" },
+        { "id": "t3", "kind": "terminal", "description": "오류 표시 후 재입력 대기" }
       ],
       "edges": [
         { "from": "n1", "to": "d1" },
-        { "from": "d1", "to": "n2", "label": "재고 있음" },
-        { "from": "d1", "to": "t_no", "label": "품절" },
-        { "from": "n2", "to": "t_ok" }
+        { "from": "d1", "to": "n2", "label": "유효" },
+        { "from": "n2", "to": "t1" },
+        { "from": "d1", "to": "d2", "label": "무효" },
+        { "from": "d2", "to": "n3", "label": "5회째" },
+        { "from": "n3", "to": "t2" },
+        { "from": "d2", "to": "t3", "label": "5회 미만" }
       ]
     }
   ]
@@ -320,8 +329,8 @@ Story가 무엇인지 **As a / I want / So that** 형식의 줄글로 적는다.
 화면 정의의 SSOT는 **screens 리소스**다 (route·목적·권한·figmaNodeId·file·상태). spec은 `screenRefs`로 링크만 건다.
 
 - **화면과 spec은 N:1이다.** 한 화면에 여러 spec이 붙는 것이 정상이다. spec 수만큼 화면을 만들지 마라.
-- 붙일 화면이 없으면 `ch screens create`로 **먼저 화면을 만들고** 그 ID를 넣는다.
-- 화면이 없는 기능(Cron·배치·외부 연동)은 화면 연결을 비워둔다.
+- **spec 작성 시점에는 화면 연결을 비워둔다.** 화면설계서는 작성 순서상 ④ — 기능명세·유저플로우·정책정의서 뒤에 만든다([[2t-decencia-channel-screen-v2]]). 화면이 생기면 `ch specs screen-refs`로 연결한다.
+- 화면이 없는 기능(Cron·배치·외부 연동)은 그 뒤에도 화면 연결을 비워둔다.
 
 **`screenRefs`는 서버 관리 필드다.** 규칙 두 개:
 
@@ -334,7 +343,7 @@ Story가 무엇인지 **As a / I want / So that** 형식의 줄글로 적는다.
 
 ### 10-1. 흐름과 SSOT 규칙
 
-테이블 먼저 만들고(`ch db-tables create`) spec에서 `--db-tables tbl_a,tbl_b`로 연결한다. 서버가 `spec.dbTableRefs` ↔ `table.relatedSpecIds`를 양방향 동기화한다.
+**DB 스키마는 작성 순서상 ③정책정의서 뒤·④화면설계서 앞이다** — 정책이 스키마를 결정하기 때문이다. spec 생성 시점에는 `dbTableRefs`를 비워두고, DB 단계에서 테이블을 만든 뒤(`ch db-tables create`) `ch specs update --db-tables tbl_a,tbl_b`로 연결한다. 서버가 `spec.dbTableRefs` ↔ `table.relatedSpecIds`를 양방향 동기화한다.
 
 - **spec** = 이 Story가 어느 테이블·컬럼을 R/W하는가 — 흐름의 `refs`로 **이름 참조만**
 - **db-tables** = 컬럼 정의·인덱스·보안 규칙·상태머신 (스키마의 SSOT — [[2t-decencia-channel-db-schema-v2]])
@@ -348,13 +357,16 @@ Story가 무엇인지 **As a / I want / So that** 형식의 줄글로 적는다.
 - **`toState`** — `field`가 그 테이블 `stateMachines[].columnRef`와 같으면 상태머신 접근이다. WRITE면 목표 상태를 `toState`로 밝힌다(값은 그 머신 `states[].value` 중 하나).
 - 레거시 `dataFlowRefs`/`businessRuleRefs`(logic 최상위)는 하위호환으로 읽히지만, 신규·수정 시에는 단계·노드의 refs로 옮긴다.
 
-### 10-3. 신규 테이블이 필요한 경우 순서
+### 10-3. DB 단계에서의 연결·refs 보강 절차
+
+DB 스키마 단계(③ 뒤)에서 spec마다 되짚어 보강한다:
 
 ```bash
-ch db-tables create --name users --columns ./cols.json ...   # 1) 테이블 먼저 → {"id":"tbl_xyz"}
-ch specs create --name "로그인" ... --db-tables tbl_xyz      # 2) spec 생성 시 연결
-# 추가 연결: ch specs get <id> --json 으로 현재 목록을 받아 합쳐 통째로 보낸다
-ch specs update <specId> --db-tables tbl_xyz,tbl_new --no-version
+ch db-tables create --name users --columns ./cols.json ...     # 1) 테이블 생성 → {"id":"tbl_xyz"}
+ch specs update <specId> --db-tables tbl_xyz,tbl_abc           # 2) dbTableRefs 연결 (통째 교체)
+ch specs get <specId> --json > spec.json                       # 3) 흐름 refs 보강 — Read-before-Write
+#    logic의 각 단계·노드에 refs(tableId·field·direction·toState) 채워 넣기
+ch specs update <specId> --logic ./logic-with-refs.json --no-version
 ```
 
 ---
@@ -407,10 +419,9 @@ ch specs get <specId> --json | jq '.logic'        # 3) 검증
 4. **Epic 코드 결정**(§3) → **Spec ID 결정**(§4, `EPIC-NNN`)
 5. `points` 산정 (§11, 보통 3~8)
 6. 스토리문장(§5)·사전 조건(§6) 작성
-7. `logic.json` 작성 — 로직 플로우 시나리오(실패·차단 분기 포함, §7), businessRules(§8)
-8. 필요한 테이블 확인 → 없으면 `ch db-tables create` 먼저 (§10)
-9. 붙을 화면 확인 — `ch screens list --json`. 없으면 `ch screens create` 먼저 (§9)
-10. 생성:
+7. `logic.json` 작성 — 로직 플로우 시나리오(실패·차단 분기 포함, §7), businessRules(§8). **refs는 넣지 않는다**(테이블이 아직 없다 — §10-3에서 보강)
+8. **DB·화면 연결은 여기서 하지 않는다** — DB 스키마 단계(③ 뒤)에서 `--db-tables`·refs 보강(§10-3), 화면설계서 단계(④)에서 `ch specs screen-refs` 연결(§9)
+9. 생성:
 
 ```bash
 ch specs create --id AUTH-001 --name "로그인" \
@@ -418,14 +429,12 @@ ch specs create --id AUTH-001 --name "로그인" \
   --epic AUTH --points 5 \
   --story "회원은 이메일과 비밀번호로 로그인해서, 재인증 없이 자신의 프로젝트에 바로 접근하고 싶다." \
   --preconditions ./preconditions.md \
-  --logic ./logic.json \
-  --db-tables tbl_users,tbl_sessions \
-  --ui ./ui.json          # {"screenRefs":["SCR-LOGIN"]} — 생성 때만
+  --logic ./logic.json
 ```
 
-11. `ch specs get <id> --json`으로 결과 검증
-12. SQA 항목은 [[2t-decencia-channel-sqa-v2]]에 따라 별도 등록
-13. 개발 착수 후 진행 일지는 [[2t-decencia-channel-work-status-v2]]
+10. `ch specs get <id> --json`으로 결과 검증
+11. 이후 문서는 작성 순서대로: 유저플로우(②) → 정책정의서(③) → DB 스키마(이때 dbTableRefs·refs 보강) → 화면설계서(④, 이때 화면 연결) → 검증기준서(⑤, [[2t-decencia-channel-sqa-v2]])
+12. 개발 착수 후 진행 일지는 [[2t-decencia-channel-work-status-v2]]
 
 ---
 

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

@@ -7,7 +7,7 @@ description: |
   (1) sprint를 구성할 때,
   (2) Σ spec.points 기반 sprint 용량 산정이 필요할 때,
   (3) Epic·도메인·의존성을 함께 고려해 spec을 sprint에 배분할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

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.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->

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

@@ -12,7 +12,7 @@ description: |
   (4) 보안/성능/접근성/호환성 비기능 TC를 시트에 채워야 할 때,
   (5) 명세 영역별 완성형 TC 번들(퍼블리싱/프론트/백엔드 디센시아 운영 관점 포함)을 가져다 쓸 때,
   (6) Sprint 종료 전 spec별 TC 통과·시나리오 통과 여부를 점검할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -32,6 +32,8 @@ ch check
 
 # SQA(검증기준서) — TC 검증 + 시나리오 검증
 
+**작성 순서상 ⑤(마지막)다** — ①기능명세·②유저플로우·③정책정의서·DB 스키마·④화면설계서가 갖춰진 뒤에 TC(spec에서)·시나리오(유저플로우에서)를 도출한다.
+
 ## 0. Read-before-Write
 
 시트 항목(item) 단위 CRUD는 이제 CLI로 모두 지원된다(§3.5). 항상 `ch sqa get <sheetId> --json`으로 현재 항목 목록·id를 먼저 받고 수정한다. 항목 수정/삭제/순서변경은 `id`를 키로 지정하므로 최신 id 확보가 선행되어야 한다.

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

@@ -8,7 +8,7 @@ description: |
   (1) 유저플로우(사용자 여정 분기도)를 새로 그리거나 수정할 때,
   (2) PRD·Epic-Story 목록에서 플로우로 그릴 대상을 고를 때,
   (3) 웹 "유저플로우" 탭에 올릴 Mermaid 코드를 작성할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->
@@ -30,6 +30,7 @@ ch check
 
 유저플로우는 **분기가 있는 사용자 여정**을 Mermaid로 그린 문서다. 웹 "유저플로우" 탭에 올린다.
 역할 분담: PRD는 무엇을(기능), spec은 어떻게(흐름 상세 — [[2t-decencia-channel-spec-v2]] §7), 유저플로우는 **여정의 갈림길**을 보여준다.
+**작성 순서상 ②다** — ①기능명세 다음에 그리고, ③정책정의서·④화면설계서·⑤검증기준서가 뒤따른다.
 
 ## 0. 원칙
 

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

@@ -8,7 +8,7 @@ description: |
   (2) "작업 현황 적어줘", "workStatus 갱신해줘" 요청 시,
   (3) Sprint 종료 회고나 인수인계용으로 spec별 진행 상태를 정리할 때,
   (4) `ch specs update --work-status` 또는 웹 "작업 현황" 탭에서 갱신할 때.
-version: 1.31.0
+version: 1.31.2
 ---
 
 <!-- ch-version-gate -->