@angar2/taskery 0.1.0 → 0.1.2

package/template/.claude/skills/task-init/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: task-init
+description: task 시작 — 워크트리 분기 + 6 섹션 빈 골격 + 헤더 5컬럼 (status=draft) task.md 생성 (멀티세션 0.1.2+)
+---
+
+# /task-init
+
+## 개요
+
+새 task 시작 시 호출. **워크트리 분기 + task.md 빈 골격 작성**.
+
+멀티세션 0.1.2+ — 본 스킬은 *작업 격리 워크트리*를 dev에서 분기 (`~/.taskery/worktrees/<projectId>/TASK-NNN_<출처>_<슬러그>/`) + 빈 골격 `task.md`를 작성한다. Requirements / Scope / Dev Plan / Test Plan 본문은 다음 단계 `/task-plan`에서 채움.
+
+> **호출 위치**: 메인 워크트리(dev 체크아웃 상태)에서 호출. 다른 워크트리에서 호출 시 → 사용자 호출 + 중단.
+
+## 호출 시점
+
+- 새 task 시작 시 (사용자 발화: *"~~ 추가해줘"*, *"~~ 버그 고쳐"*, *"~~ 리팩터링"*).
+- 직전 대화로 작업 맥락 명확해진 직후.
+- 백로그 항목 진행 (사용자: *"BL-003 진행하자"*).
+- 로드맵 항목 진행 (사용자: *"로드맵 RM-002 시작"*).
+
+## 입력 처리
+
+인자 = (선택) 주제 / 유형 / 출처(BL-NNN, RM-NNN, DR) / 규모. 예: `/task-init 로그인 기능` / `/task-init BL-003` / 인자 없이 호출.
+
+두 분기:
+- **분기 1 (제안)**: 직전 맥락 명확 → 메인이 *"이렇게 task 만들까요?"* 제안 + 사용자 confirm.
+- **분기 2 (인터뷰)**: 직전 맥락 부족 → 한 번에 한 질문씩 인터뷰.
+
+**자동 추정 진행 X** — 사용자 confirm 또는 답 받기 전 워크트리 생성 / 파일 생성 금지.
+
+## 단계
+
+### Step 1 — 사전 검증 (멀티세션 안전망)
+
+`bin/lib.js` 유틸 활용 — 메인 워크트리 + dev 검증.
+
+1. **메인 워크트리 검출**:
+   ```sh
+   MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+   ```
+   - git ≥ 2.31 필요. 실패 시 *"git 버전 확인 — 2.31+ 필요"* 보고 + 중단.
+2. **현재 cwd가 메인 워크트리인지 확인**:
+   ```sh
+   CURRENT_WT=$(git rev-parse --show-toplevel)
+   [ "$CURRENT_WT" = "$MAIN_WT" ] || abort "메인 워크트리에서 호출해야 함 (현재: $CURRENT_WT)"
+   ```
+3. **dev 브랜치 존재 검증**:
+   ```sh
+   git -C "$MAIN_WT" rev-parse --verify dev || abort "dev 브랜치 부재. 사용자 결정 필요 (생성?)"
+   ```
+4. **메인 워크트리 = dev 검증**:
+   ```sh
+   CURRENT=$(git -C "$MAIN_WT" rev-parse --abbrev-ref HEAD)
+   [ "$CURRENT" = "dev" ] || abort "메인 워크트리가 dev 아님 (현재: $CURRENT). taskery 정책 위배"
+   ```
+5. **stale 의심 감지** (`npx @angar2/taskery status`로 위임 가능):
+   - 케이스 A (폴더 없는 워크트리): `git worktree prune` 제안 + 사용자 확인 후 실행
+   - 케이스 B (N일↑ 미커밋 브랜치): 알림만
+   - 케이스 C (워크트리 폴더 존재, N일↑ 비활성): 알림만
+   - 케이스 D (rebase 잔여 상태 — 워크트리에 `.git/rebase-apply` 또는 `.git/rebase-merge` 존재): 사용자 호출 + 선택 (continue / abort)
+   - N = `.taskery-manifest.json`의 `stale_days` (기본 30)
+
+위 검증 1개라도 실패 시 → 사용자 호출 + 중단.
+
+### Step 2 — active plan 버전 확인
+
+1. `$MAIN_WT/.project/AGENT-GUIDE.md` Read → *활성 plan 버전* 추출 (예: `v1.0`).
+2. AGENT-GUIDE.md 없거나 활성 버전 누락 시 → 사용자에게 *"활성 plan 버전이 없는데 `/plan-init` 먼저 실행할까요?"* 묻고 중단.
+3. `$MAIN_WT/.project/plans/<vX.X>/` 디렉토리 존재 확인. 없으면 동일하게 `/plan-init` 안내 + 중단.
+
+### Step 3 — 분기 판단 + 메타 수집
+
+직전 대화 정독:
+- 작업 주제 / 유형 / 출처 / 규모 추정 가능?
+  - **추정 가능** → 분기 1 (제안):
+    *"직전 맥락 보니 다음 task 만들까요? 주제: <X> / 유형: <Y> / 출처: <Z> / 규모: <W> / 플랜: <vX.X>. 어떠세요?"*
+    사용자 답 — *"OK"* / *"규모는 large야"* / *"유형은 bug야"* 등 부분 수정 받음.
+  - **추정 불가** → 분기 2 (인터뷰): 한 번에 한 질문씩.
+    - Q1: *"무슨 작업인가요? (한 줄로)"*
+    - Q2: *"유형? (feature / bug / improvement / refactor / docs / chore)"*
+    - Q3: *"출처? (백로그 BL-NNN / 로드맵 RM-NNN / 직접 요구사항 DR)"*
+    - Q4: *"규모? (micro / small / medium / large) — 잘 모르겠으면 추정 알려드림."*
+    - (필요 시) Q5: *"플랜 버전 `<vX.X>` 맞나요?"*
+
+수집 항목 (모두 확정되어야 진행):
+- 주제 (한국어 — kebab-slug 변환은 Step 4)
+- 유형: `feature` / `bug` / `improvement` / `refactor` / `docs` / `chore`
+- 출처: `BL-NNN` / `RM-NNN` / `DR`
+- 규모: `micro` / `small` / `medium` / `large`
+- 플랜 버전: 활성 버전 그대로 (Step 2에서 가져온 값)
+
+### Step 4 — TASK 번호 결정 + 결정적 슬러그 + SSoT 안전망
+
+#### 4.1 다음 TASK-NNN 계산
+
+`bin/lib.js` `getNextTaskNumber(MAIN_WT)` 호출. 내부 동작:
+```sh
+# 진행중 (SSoT) — TASK-* 패턴 작업 브랜치 전체. `--no-merged dev` 미사용:
+# 워크트리 분기 직후 브랜치는 dev와 동일 commit이라 `--no-merged dev`가 *완전 머지 상태*로
+# 처리 → 빈 결과 → getNextTaskNumber 충돌. 브랜치 존재 자체가 SSoT.
+A=$(git -C "$MAIN_WT" branch --list \
+    'feature/*_TASK-*' 'bug/*_TASK-*' 'improve/*_TASK-*' \
+    'refactor/*_TASK-*' 'docs/*_TASK-*' 'chore/*_TASK-*' \
+    | grep -oE 'TASK-[0-9]+')
+# dev 머지 히스토리
+B=$(git -C "$MAIN_WT" log dev --grep='TASK-[0-9]\+' --extended-regexp --oneline \
+    | grep -oE 'TASK-[0-9]+')
+# 합집합 최대 + 1
+MAX=$( (echo "$A"; echo "$B") | sort -uV | tail -1 | sed 's/TASK-//')
+NEXT=$((MAX + 1))
+```
+- 3자리 zero-padded (`001`, `015`, `120`).
+- 합집합 비어 있으면 `001`.
+
+#### 4.2 메타 가져오기 (BL/RM)
+
+- BL: `$MAIN_WT/.project/tasks/<활성버전>/BACKLOG.md` Read → `BL-NNN` 블록 파싱 → `{ status, type, title, slug, summary, target, taskNums }` (활성 버전은 `AGENT-GUIDE.md`에서 검출. `bin/lib.js`의 `parseBacklogItem(mainWtPath, blId)` 호출 권장). 개요 / 대상 영역 → task.md §1 Requirements 초안에 자동 복사 (얕은 분석이 task 문서 시작점)
+- RM: `$MAIN_WT/.project/plans/<활성버전>/ROADMAP.md` Read → `RM-NNN` grep → 항목 메타 파싱
+- DR: 사용자 발화에서 주제 그대로
+
+#### 4.2.5 이미 `[x]` BL 재진행 케이스
+
+`parseBacklogItem` 결과 `status === 'checked'`이고 `taskNums` 비어 있지 않을 때:
+- 사용자 호출 + 결정: *"BL-NNN은 ${taskNums}로 이미 처리된 적 있어. 새 task로 다시 진행할까?"*
+- 사용자 OK → 새 TASK-NNN 진행. §7.5 (BL 확인 마킹) 단계에서 `- TASK:` 줄에 콤마로 추가 (덮어쓰기 X)
+- 사용자 X → task-init 중단
+
+#### 4.3 결정적 슬러그 산출
+
+- BL/RM: BACKLOG/ROADMAP에 박힌 슬러그 그대로 사용 (`parseBacklogItem` 결과의 `slug` 필드). task-init이 별도 변환 X — 재현성 보장
+- DR: 사용자 작명 또는 메시지에서 자동 산출 후 confirm
+- 한국어 → 영어 kebab-case. 짧고 명확하게 (3 단어 이내 권장).
+- 같은 항목이면 같은 슬러그 → 같은 브랜치명 → git이 동시 분기 자동 거부 (race 차단 1층).
+
+#### 4.4 SSoT 안전망 (race 차단 2층)
+
+```sh
+git -C "$MAIN_WT" branch --no-merged dev --list \
+  'feature/*_TASK-*' 'bug/*_TASK-*' 'improve/*_TASK-*' \
+  'refactor/*_TASK-*' 'docs/*_TASK-*' 'chore/*_TASK-*' \
+  | grep -E "_${SRC}_"
+```
+- BL-NNN/RM-NNN이 *진행중*에 있으면 → 중단 + 사용자 알림 (*"BL-003은 이미 X 세션에서 진행 중"*).
+- DR은 본 안전망 검사 X (별도 ID 없음).
+
+### Step 5 — 파일 vs 폴더 결정 + 브랜치명 산출
+
+1. 파일 vs 폴더 분기 (기존 룰 유지):
+   - **파일 default**: 단일 `NNN_<slug>.md`.
+   - **폴더 승격 조건**: (a) 규모 `large`, 또는 (b) 사용자 명시 *"폴더로 만들어줘"*, 또는 (c) task에 *추가 자료* 다수 예상.
+   - **spec-diffs / screenshots / mockup은 vX.X 공통** — 단일/폴더 모두 `.project/tasks/<vX.X>/{spec-diffs,screenshots,mockup}/`에 위치. (TASK_DOC_RULE §1.5)
+2. 브랜치명 산출 (멀티세션 형식):
+   ```
+   {타입}/{개발자}_TASK-NNN_{출처}_{슬러그}
+   예: feature/claude_TASK-007_BL-003_login-feature
+       bug/angar2_TASK-012_DR_mobile-form-refresh
+   ```
+   - **타입**: feature → `feature`, bug → `bug`, improvement → `improve`, refactor → `refactor`, docs → `docs`, chore → `chore`
+   - **개발자**: 메인 세션 = `claude`, 사용자 세션 = `angar2` 등
+3. 사용자에게 브랜치명 + 파일/폴더 confirm.
+
+### Step 6 — 워크트리 생성
+
+```sh
+PROJECT_ID=$(jq -r '.projectId' "$MAIN_WT/.taskery-manifest.json")
+WORKTREES_ROOT="$HOME/.taskery/worktrees/$PROJECT_ID"
+WT_PATH="$WORKTREES_ROOT/TASK-${NNN}_${SRC}_${SLUG}"
+mkdir -p "$WORKTREES_ROOT"
+git -C "$MAIN_WT" worktree add "$WT_PATH" -b "$BRANCH" dev
+```
+
+- git이 동일 브랜치명 자동 거부 (race 차단 1층).
+- 동시 충돌 시 *"브랜치 이미 존재 — 다른 세션이 같은 항목 진행 중"* 보고 + 중단.
+
+### Step 7 — task 문서 위치 결정 + 빈 골격 작성
+
+`.gitignore` 케이스 분기 — task 문서를 *메인 워크트리에 직접 작성* vs *워크트리 안에 작성*:
+
+```sh
+git -C "$MAIN_WT" check-ignore -q "$MAIN_WT/.project/dummy"
+```
+
+| 결과 | 케이스 | 작성 위치 |
+|------|--------|----------|
+| exit 0 | **등록됨** (퍼블릭 리포 default) | **메인 워크트리** (`$MAIN_WT/.project/tasks/<vX.X>/`) — proper-lockfile로 안전 쓰기. 멀티세션 공유 단일 소스. dev untracked (git 자동 무시) |
+| exit 1 | **미등록** | **워크트리 안** (`$WT_PATH/.project/tasks/<vX.X>/`) — 워크트리 커밋 + 머지 시 dev에 반영 |
+
+빈 골격 형식 (TASK_DOC_RULE §1.3 참조):
+
+```markdown
+# TASK-<NNN> — <한국어 제목>
+
+| 생성일 | 플랜 | 유형 | 규모 | 상태 |
+|--------|------|------|------|------|
+| <YYYY-MM-DD> | <vX.X> | <유형> | <규모> | draft |
+
+## Requirements
+
+(사용자 요구 + 메인 증폭 — `/task-plan`에서 채움)
+
+## Scope
+
+(영향 범위 — `/task-plan`에서 채움)
+
+## Dev Plan
+
+(Phase 1, 2, ... — `/task-plan`에서 채움)
+
+## Test Plan
+
+(테스트 방법 + 검증 명령 — `/task-plan`에서 채움)
+
+## Result
+
+(진행 + 테스트 결과 — `/task-dev`, `/task-test`에서 채움)
+```
+
+- 6 섹션 placeholder는 *빈 헤딩 + 한 줄 안내*. 구체 내용 X.
+- 폴더 승격 시 `TASK-<NNN>_<slug>/task.md`로 동일 본문 작성.
+
+### Step 7.5 — BL 출처 BACKLOG.md 확인 마킹 (BL일 때만)
+
+§4 출처 결정에서 *BL*이 선택된 경우만 실행. RM/DR은 skip.
+
+`bin/lib.js`의 `markBacklogChecked(mainWtPath, blId, taskNum)` 호출.
+
+내부 흐름 (`withMetaLock` 안에서 원자성 보장):
+1. 첫 줄 패턴 `- [ ] **BL-NNN**` → `- [x] **BL-NNN**`로 4번째 글자(체크박스) 치환
+2. 같은 BL 블록 끝 (다음 `- ` 헤드 또는 파일 끝 직전, 빈 줄 건너뛴 위치) 에 `  - TASK: TASK-NNN` 한 줄 append
+3. 이미 `  - TASK:` 줄 있으면 → 콤마로 추가 (`TASK-007, TASK-012`. 덮어쓰기 X)
+
+`[x]` 의미: *"이 항목은 task로 옮겼다"*. **dev 머지 완료 의미 X**. 완료 추적은 `git log dev --grep 'BL-NNN'` + 브랜치명 + `npx @angar2/taskery status`.
+
+> §4.2.5 (이미 `[x]` BL 재진행 케이스)에서 사용자 OK 받은 경우만 본 단계 진입. 사용자 X로 중단된 경우 본 Step 7.5도 skip.
+
+### Step 8 — 결과 보고
+
+```
+✅ TASK-<NNN> 생성 완료
+- 워크트리: <WT_PATH>
+- 브랜치: <BRANCH>
+- task 문서: <TASK_DOC_PATH> (메인 워크트리 / 워크트리 안 — 위 케이스에 따라)
+- 헤더: <생성일> / <vX.X> / <유형> / <규모> / draft
+- BL 마킹: BL-<NNN> [x] (BL 출처 시. RM/DR이면 생략)
+- 다음: 워크트리 폴더에서 새 세션 열기 → /task-plan TASK-<NNN> 으로 기획 채우기
+```
+
+## 도구 가이드
+
+- **Bash**: 메인 워크트리 검출 / 사전 검증 / `git worktree add` / SSoT 조회 / TASK-NNN 계산
+- **Read**: `$MAIN_WT/.project/AGENT-GUIDE.md` / `$MAIN_WT/.project/tasks/<활성버전>/BACKLOG.md` / `$MAIN_WT/.project/plans/<활성버전>/ROADMAP.md`
+- **Write**: task.md 빈 골격 작성 (위치는 .gitignore 케이스에 따라)
+- **AskUserQuestion**: 분기 2 인터뷰 (한 번에 한 질문)
+
+## 주의사항
+
+- **워크트리 생성 + task 문서 작성만 담당** — 본문 채우기 금지. Requirements / Scope / Dev Plan / Test Plan 본문은 *반드시* `/task-plan`에서.
+- **단계 경계 — 허용/금지 명시 (stash FRICTION_LOG #11 반영)**:
+  - **허용 (화이트리스트)**: `$MAIN_WT/.project/plans/<활성버전>/ROADMAP.md` §4(다음 작업 영역) 확인 / SSoT 조회 / TASK-NNN 계산 / 빈 골격 Write
+  - **금지 (블랙리스트)**: ARCHITECTURE.md / API-SPEC.md / FEATURES.md 등 9 기획 문서 본문 Read / 도메인 코드 Read · Grep / 기존 task 본문 Read
+  - 본문 정보 수집은 *다음 단계 `/task-plan`*에서 수행.
+- **자동 추정 진행 X** — 직전 맥락 명확해도 *제안 + 사용자 OK* 거친 후 워크트리/파일 생성.
+- **상태는 `draft` 고정** — `/task-init` 끝의 상태는 `draft` 외 작성 금지.
+- **NNN 충돌 회피** — SSoT 조회로 진행중 + dev 머지 히스토리 합집합 확인.
+- **slug 한국어 잔존 X** — 영어 kebab-case로 변환.
+- **헤더 5컬럼 모두 채움** — *"미정"* placeholder 작성 금지.
+- **메인 워크트리 검출 실패 시 즉시 중단** — git 버전 / 정책 위배 / dev 부재 등 안전망. 묵묵히 진행 X.
+- **race 발생 시 사용자 호출** — `git worktree add` 실패(같은 브랜치명) → SSoT 재조회 + 사용자에게 *"X 세션이 같은 항목 진행 중"* 알림.
+
+## 상태 전이
+
+| 진입 시 | 종료 시 |
+|--------|--------|
+| (없음 — 신규 생성) | `draft` |
+
+## 멀티세션 정합
+
+- **다른 세션 진행중 태스크** = SSoT (git branch --no-merged) 단일 진실 소스
+- **워크트리 정리**: 본 스킬은 *생성*만. 제거는 `/task-close` 또는 `npx @angar2/taskery prune`
+- **머지 락**: 본 스킬은 머지 안 함 — 락 불필요
+- **충돌 자체 해결**: 본 스킬 영역 X — `/task-close`에서 처리

package/template/.claude/skills/{task-plan.md → task-plan/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-plan
 description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Plan 4 섹션 작성, draft → planned
 ---
 
@@ -10,6 +11,23 @@ description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Pl
 
 리뷰는 *대화로 OK* 자동 전이로 단순화 — 별도 리뷰 단계 없음.
 
+## 멀티세션 메타 위치 (0.1.2+)
+
+본 스킬은 워크트리에서 호출된다. 메타(`.project/`, `CLAUDE.md`) 접근 시 **메인 워크트리 절대 경로** 우선 — *task 문서 단일 진실 소스* 유지.
+
+```sh
+MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+```
+
+`.gitignore` 케이스 분기:
+
+| 케이스 | task 문서 위치 | 9 기획 문서 위치 | 동시 쓰기 |
+|--------|--------------|----------------|----------|
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<vX.X>/...` | `$MAIN_WT/.project/plans/<vX.X>/...` | `withMetaLock` (`bin/lib.js`) |
+| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안, 머지 시 dev 반영) | `$MAIN_WT/.project/plans/<vX.X>/...` (plan 문서는 여전히 단일 소스) | 단일 세션 가정 (워크트리 내부) |
+
+본문 모든 `.project/...` 경로는 *위 분기에 따라* 적용. spec-diff / mockup / screenshots는 task 문서와 같은 위치.
+
 ## 호출 시점
 
 - `/task-init`로 만든 빈 골격 task에 기획 채울 때.
@@ -119,33 +137,108 @@ description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Pl
 ### Phase 2 — ...
 ```
 
-### Step 5 — Test Plan (자유 형식 + 가이드라인)
+### Step 4.5 — HTML 목업 프로세스 (UX/UI 구현 task 한정 — stash FRICTION_LOG #14+19 반영)
 
-양식 강제 X. *작업에 맞게 자유롭게* 작성. 단 가이드라인 준수 (TASK_DOC_RULE §2.5):
+본 task가 UX/UI 구현 포함하면 *시각 영역 사전 정합* + *task-test 시 USER 검수 기준 확보*용 HTML 목업 생성.
 
-- **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
-- **명령/기대값 포함**: 무엇을 실행하고 무엇이 기대되는지 명확.
-- **메인 가정 X**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
+#### 1. UX/UI 구현 task 판단
+
+Step 2 Requirements 인터뷰 결과로 본 task가 *UX/UI 구현 (페이지/컴포넌트 신규 / 시각 변경 / 인터랙션 신규)* 포함 여부 판단.
+
+- UX/UI 포함 → 2~5 진행
+- 미포함 (백엔드 / CLI / 인프라 등) → 본 Step 패스, Step 5로 직진
+
+#### 2. 목업 confirm
+
+사용자에게 한 줄 질문:
+*"이 task UX/UI 구현 포함되어 있어. HTML 목업 만들까? 구현 정확도 + 사용자 사전 시각 확인 + task-test 검수 기준 확보 효과."*
+
+- 사용자 *"OK"* → 3 진행
+- 사용자 *"NO"* → 본 Step 패스 (목업 없이 진행)
+
+#### 3. 목업 생성 + 사용자 승인
+
+1. 메인이 HTML 목업 생성 — 정적 HTML/CSS (외부 라이브러리 X, 단일 파일 안 inline style + 필요 시 vanilla JS):
+   - 시각 영역 (레이아웃 / 색상 / 간격 / 타이포 / 호버 효과)
+   - 인터랙션 (가능한 범위 — 클릭 / 호버 시뮬)
+2. 사용자에게 *"브라우저로 `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html` 열어 확인 후 ✓/✗ 응답"*.
+3. 사용자 ✓ → 승인 완료, 4 진행. ✗ → 메인이 수정 후 재승인 요청.
+
+#### 4. 파일 위치 / 네이밍
+
+- 위치: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+  - 예: `001_login-form.md` → `001_login-form-mockup.html`
+- **task 1개 = 목업 1개**. multi-file 예외 영구 X. 복잡해도 한 파일 안 섹션 분리 (`<section id="popover">` `<section id="settings">` 등).
+
+#### 5. Test Plan 연결
+
+승인된 목업 = task-test의 *시각 영역 USER 검수 기준*. Step 5 Test Plan 작성 시 시각 시나리오에 `[USER]` 분류 + 목업 경로 참조 명시.
 
-자유 형식 예 (체크리스트 / 시나리오 / 명령 나열):
+---
+
+### Step 5 — Test Plan (실질 동작 시나리오 — stash FRICTION_LOG #14+19 / #25 반영)
+
+#### 본질
+
+Test Plan = *본 task에서 구현한 요구사항이 정상 동작하는지* 검증 시나리오. **유닛 테스트 X** (유닛 테스트는 task-dev Step 6.5에서 단일 시점 실행 — *코드 정상성* 영역, 본 Test Plan과 직교).
+
+검증 대상:
+- 기능 동작: 사용자 입력 → 기대 결과 / API 호출 → 응답 / 데이터 처리 → 상태 변화
+- UX/UI 동작: 클릭 → 결과 / 호버 → 상태 / 드래그 → 위치 변경
+- UX/UI 시각: 레이아웃 / 색상 / 간격 / 호버 효과 (목업 기준)
+- 백엔드 동작: 시스템 호출 → 외부 응답 / 사이드 이펙트 / 에러 처리
+
+#### 실질 테스트 방식 카탈로그
+
+각 시나리오마다 아래 방식 중 적합한 1개 이상 선택:
+
+| 방식 | 적용 영역 | 설명 |
+|------|----------|------|
+| 수동 검수 | UI / UX / 인터랙션 | 사용자가 실제 앱·환경에서 직접 조작·확인 |
+| 시나리오 스크립트 실행 | 백엔드 / 통합 흐름 | end-to-end script (bash / node 등) 일련의 명령 자동 실행 |
+| API/엔드포인트 호출 | 백엔드 / 외부 인터페이스 | 실제 호출 + 응답·상태 코드·결과 데이터 확인 |
+| 입출력 비교 | 함수 / 변환 / 처리 | 입력 → 출력 비교 (snapshot / golden file) |
+| 사이드 이펙트 확인 | DB / 파일 / 로그 | 시나리오 실행 후 상태 직접 조회 |
+| 회귀 시나리오 | 기존 기능 영향 | 직전 동작하던 시나리오 재실행 |
+| E2E 자동화 도구 | UI 자동화 (도구 있을 시) | Playwright / Cypress / XCTest UI Test 등 — 가능하면 자동화, 안 되면 수동 검수 |
+
+#### UX/UI 영역 분리 + 검증 방식 매트릭스 (UX/UI 구현 task 한정)
+
+| 영역 | 자동화 가능 시 | 자동화 불가 시 |
+|------|---------------|---------------|
+| 동작 (클릭/호버/드래그/입력 → 결과) | `[AUTO]` E2E 자동화 시나리오 스크립트 | `[USER]` 체크리스트 |
+| 시각 (레이아웃/색상/간격/호버 효과 강도) | (자동 비교 의미 없음 — 픽셀 단위 변화 + 주관 판단 영역) | `[USER]` 체크리스트 + 목업 기준 참조 |
+
+#### 시나리오 형식
 
 ```markdown
 ## Test Plan
 
-1. `npm run dev` → http://localhost:3000/<경로> 접속.
-2. <시나리오 1>:
-   - 기대: <응답/표시>
-3. <시나리오 2>:
-   - 기대: ...
-
-검증 명령:
-- `npm run lint` PASS
-- `npm run typecheck` PASS
-- `npm run build` PASS
-- `npm test <관련 파일>` PASS
+| # | 시나리오 | 분류 | 방식 | PASS 기준 |
+|---|---------|------|------|----------|
+| 1 | <한 줄 설명> | [AUTO] / [USER] | <카탈로그 방식> | <명확한 기대값> |
+| 2 | ... | ... | ... | ... |
+
+(UX/UI task — 목업 있으면) 시각 USER 시나리오 기준: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
 ```
 
-검증 명령은 프로젝트 루트 `CLAUDE.md`의 *검증 명령* 섹션을 참조해 그대로 인용.
+#### 시각 영역 fix 사이클 사전 예고 (stash FRICTION_LOG #14 반영)
+
+시각 영역 시나리오가 1개 이상 있으면 Test Plan 끝에 명시:
+
+> 시각 영역 항목 N개 — 한 사이클로 100% 일치 보장 X. fix 사이클 1~2회 예상. ✗ 발견 시 정상 (사용자 부정 반응 누적 방지 — 기대치 사전 정렬).
+
+#### 가이드라인 (TASK_DOC_RULE §2.5 정합)
+
+- **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
+- **명령/기대값 포함**: 무엇을 실행하고 무엇이 기대되는지 명확.
+- **메인 가정 X**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
+
+#### 검증/테스트 명령 참조
+
+`/task-test` 격리 세션은 프로젝트 루트 `CLAUDE.md`의 두 섹션을 자동 참조 — Test Plan에 재인용 불필요:
+- `## 검증 명령` (코드 상태 — 빌드/린트/타입체크)
+- `## 테스트 명령` (테스트 실행 — 단위/통합/E2E)
 
 ### Step 6 — spec-diff 처리 (Phase 0 변경 있을 시)
 
@@ -196,10 +289,14 @@ description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Pl
 
 - **본문 영역만 작성** — 헤더 5컬럼 중 *상태*만 갱신(`draft` → `planned`). 생성일/플랜/유형/규모는 `/task-init`에서 작성된 값 유지. 단 Step 4에서 *규모가 명백히 잘못 추정*된 게 드러나면 사용자 confirm 후 갱신 OK (예: medium 추정했는데 Phase 8개 나옴 → large 갱신 + 분리 검토).
 - **Phase 선제적 일괄 작성 금지** — small task에 medium 분량 Phase 작성하는 함정 회피. 명확한 것만 작성하고 진행 중 추가.
+- **Test Plan = 실질 동작 시나리오 (유닛 테스트 X)** — Test Plan은 *요구사항이 정상 동작하는지* 검증. 유닛 테스트는 task-dev Step 6.5에서 단일 시점 실행 (코드 정상성 영역, Test Plan과 직교).
 - **Test Plan 자기완결적** — 격리 세션이 *task.md만 보고* 수행 가능해야. 메인의 plan/dev 컨텍스트 *"위 Phase에서 만든 X"* 같은 표현 금지. 코드/동작/명령만 명시.
 - ***"잘 될 거야"* 가정 금지** — Test Plan에 메인 가정 작성 금지. 코드와 동작만 신뢰.
 - **합의 없이 status 전환 X** — 사용자 OK 받기 전 `planned` 작성 금지. 합의가 *대화로 OK = 자동 전이* 룰의 핵심.
 - **과규모(large) 시 분리 제안** — Phase 8개 초과 또는 성격 다른 기능 혼재 시 task 분리 권장. 사용자에게 *"A/B로 쪼갤까요?"* 제안.
+- **UX/UI task — 목업 프로세스 누락 X** — UX/UI 구현 task는 Step 4.5 목업 confirm 필수. 사용자 *NO* 응답이면 패스, *OK*면 생성 + 승인. 목업 누락 시 task-test 시각 USER 시나리오 기준 부재.
+- **디자인 산출 정독 의무 (stash FRICTION_LOG #14+19 / #12 일반화)** — task에 디자인 산출 (HTML 목업 / Figma / 디자인 파일) 있으면 메인이 *직접 Read* 후 Test Plan 작성. sub-agent 위임 금지 (요약만 받아 시각 정합 깨짐).
+- **모호 발화 confirm 룰 (stash FRICTION_LOG #21+22 반영)** — 사용자 발화가 복수 매칭 가능할 때 자율 추정 금지. 메인 *자체 안 1개* + *"X 의미 맞아?"* 한 줄 confirm. 옵션 4개 늘어놓기 금지.
 
 ## 상태 전이
 

package/template/.claude/skills/{task-test.md → task-test/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: task-test
 description: task 격리 세션 검증 — Task tool 격리 호출 + Test Plan 그대로 수행, developed → testing → tested
 ---
 
@@ -10,6 +11,23 @@ description: task 격리 세션 검증 — Task tool 격리 호출 + Test Plan
 
 **왜 격리?** 메인 세션은 plan/dev 컨텍스트가 누적되어 *"잘 됐을 거야"* confirmation bias 작동. 격리 세션이 *코드와 동작만 신뢰*해서 가정 없이 검증.
 
+## 멀티세션 메타 위치 (0.1.2+)
+
+본 스킬은 워크트리에서 호출된다. 격리 세션 prompt에 넘기는 task 문서 + 검증/테스트 명령 출처:
+
+```sh
+MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+```
+
+`.gitignore` 케이스 분기:
+
+| 케이스 | task 문서 위치 | 격리 세션 작업 디렉토리 |
+|--------|--------------|---------------------|
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<vX.X>/...` | `$WT_PATH` (워크트리 — 코드 변경 위치) |
+| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안) | `$WT_PATH` (워크트리) |
+
+격리 세션은 *워크트리 안*에서 검증/테스트 명령 실행 (`$MAIN_WT/CLAUDE.md`의 `## 검증 명령` / `## 테스트 명령` 단일 진실 소스).
+
 ## 호출 시점
 
 - `/task-dev` 끝나고 self-check PASS 받은 직후.
@@ -52,39 +70,50 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 파일 경로: <ABSOLUTE_PATH_TO_TASK_MD>
 
 이 파일을 직접 Read 해서 ## Test Plan 섹션 + ## Dev Plan의 Phase별 완료 기준을 정독하세요. 다른 문서 참조 X — task.md 하나만 봅니다.
+(단 task.md가 `mockup/<task-doc-name>-mockup.html` 참조하면 해당 목업 파일도 직접 Read — 시각 USER 시나리오의 *기준*으로 사용. 자동 비교 X.)
 
 ## 수행 룰
 
-1. ## Test Plan 시나리오를 *순서대로* 그대로 수행. 임의 추가 / 스킵 / 변형 금지.
-2. 각 시나리오마다 *실제 명령 실행* — 실행 없이 pass 처리 절대 금지.
-3. 검증 명령 (린트/타입/빌드/테스트) 모두 직접 실행.
-4. 코드와 동작만 신뢰. *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 일체 금지.
-5. UI/브라우저 시나리오는 가능한 범위에서 자동화 (Playwright 사용 가능). 자동화 불가능 시 UNCERTAIN으로 표기 + 사용자검수 필요 안내.
-6. 코드 파일 직접 수정 절대 금지. 임시 파일(테스트 스크립트 등) 생성 시 종료 후 삭제.
+1. **본질 — Test Plan 시나리오 기반 실질 동작 검증**. 본 task에서 구현한 *요구사항이 정상 동작하는지* 검증이 목적. 단위 테스트 수치(카운트 +N / 모든 PASS) 자체로 task PASS 단정 절대 X — Test Plan에 명시된 *각 시나리오*가 PASS인지가 본질.
+2. ## Test Plan 시나리오를 *순서대로* 그대로 수행. 임의 추가 / 스킵 / 변형 금지. 각 시나리오의 `[AUTO]` / `[USER]` 분류 (task-plan에서 정의됨) 그대로 따름.
+3. `[AUTO]` 시나리오 — *실제 명령 실행*. 실행 없이 pass 처리 절대 금지. 검증 도구 (단위/통합/E2E 테스트 / API 호출 / 스크립트 실행 등) 직접 수행 + 결과 로그 확보.
+4. `[USER]` 시나리오 — 자동 검증 불가 영역 (UI 인터랙션 / 시각 디자인 / 사용자 입력). UNCERTAIN으로 분류 + *사용자 직접 검수 항목*으로 리턴. 격리 세션에서 검증 시도 X.
+5. CLAUDE.md `## 검증 명령` (빌드/린트/타입체크) + `## 테스트 명령` (단위/통합/E2E 테스트) 둘 다 직접 실행 + 결과 리턴.
+6. **신규 테스트 식별자 등장 확인 (stash FRICTION_LOG #19 반영)** — 본 task에서 신규 테스트 추가되었으면, 단순 *카운트 +N / 모든 PASS* 자체로 PASS 단정 X. 신규 *테스트 식별자* (suite / class / function / describe 등) 가 테스트 runner 결과 로그에 *실제 등장*했는지 grep 직접 확인 (1 hit 이상). 등장 안 하면 *Suite 미실행* → FAIL.
+7. 코드와 동작만 신뢰. *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 일체 금지.
+8. 코드 파일 직접 수정 절대 금지. 임시 파일(테스트 스크립트 등) 생성 시 종료 후 삭제.
+9. **task.md 본문 메타 발언과 raw 결과 분리** — task.md (Requirements / Scope / Dev Plan / Test Plan 본문)의 *어떠한 메타 발언* (*"본 Test Plan은 Dev Plan과 의도적 mismatch"* / *"본 task는 FAIL이 정상"* / *"aborted 시뮬"* 등) 도 raw 시나리오 결과 판정을 *덮을 수 없다*. raw 결과 판정 = *실행 명령 exit code / 로그 출력 / 어서션 통과 여부*만. 본문 의도 해석 영역 외 — 결과 기반 판정만.
 
 ## 결과 형식 (이 포맷 그대로 리턴)
 
 ### 종합 판정
 - **PASS** / **FAIL** / **UNCERTAIN** 중 하나
+- UNCERTAIN = `[USER]` 시나리오 또는 자동 검증 불가 항목이 1개 이상 있으면. PASS 자동 전이 X — 사용자 직접 검수 필요.
 - 한 줄 요약
 
 ### 시나리오별 결과
-| # | 시나리오 | 실행 명령/방식 | 결과 | 근거 |
-|---|---------|------------|------|------|
-| 1 | <Test Plan 시나리오 1 그대로> | <실행한 명령> | ✅/❌/❓ | <로그 인용 / 응답 / 출력> |
-| 2 | ... | ... | ... | ... |
+| # | 시나리오 | 분류 | 실행 명령/방식 | 결과 | 근거 |
+|---|---------|------|------------|------|------|
+| 1 | <Test Plan 시나리오 1 그대로> | [AUTO] / [USER] | <실행한 명령 또는 "USER 검수 필요"> | ✅/❌/❓ | <로그 인용 / 응답 / 출력 또는 목업 경로> |
+| 2 | ... | ... | ... | ... | ... |
 
-### 검증 명령 결과
+### 검증 명령 결과 (`## 검증 명령` — 코드 상태)
 - 린트: <PASS/FAIL + exit code + 메시지>
 - 타입체크: <...>
 - 빌드: <...>
+
+### 테스트 명령 결과 (`## 테스트 명령` — 테스트 실행)
 - 단위 테스트: <PASS 케이스 수 / FAIL 케이스 수>
+- 통합 테스트: <...>
+- E2E 테스트: <...>
+- 신규 식별자 등장 확인: <suite/class/function 명 + grep 결과 hit 수>
 
 ### 실패 / 불확정 상세 (해당 시)
 - <어느 시나리오 / 무엇이 깨졌는지 / 어느 로그가 그 증거인지>
 
-### 사용자검수 필요 항목 (해당 시)
-- <자동화 불가능한 시나리오 — 스크린샷 경로 또는 수동 검수 가이드>
+### USER 검수 필요 항목 (UNCERTAIN — 해당 시)
+- <시나리오 N: 검수 항목 한 줄>
+- <목업 파일 경로 — 있을 시 시각 영역 기준으로 참조>
 
 ## 종료 조건
 
@@ -149,13 +178,26 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 ```
 3. 사용자 *"고쳐"* → 헤더 status `testing` → `developing` Edit + `/task-dev` 안내. 사용자 *"OK 마무리"* → status `testing` → `tested` Edit (단 Result 섹션에 *"알려진 결함 있음"* 명시) + `/task-close` 안내.
 
-#### UNCERTAIN 분기
+#### UNCERTAIN 분기 (USER 검수 흐름)
+
+격리 세션이 `[USER]` 시나리오 또는 자동화 불가능한 시나리오(UI 인터랙션 / 시각 디자인 / 사용자 입력 등) 발견 시. **자동 PASS 전이 X — 사용자 직접 검수 PASS 받은 후에만 `tested` 전이**.
 
-격리 세션이 자동화 불가능한 시나리오(예: 모바일 사파리 / 외부 결제 / 시각 디자인) 발견 시:
+1. 메인이 사용자에게 *체크리스트 형식*으로 항목 보고 (stash FRICTION_LOG #14+19 반영):
+
+```
+USER 검수 — N 항목 (목업 기준: <mockup path — 있을 시>)
+
+[ ] <시나리오 1>
+[ ] <시나리오 2 (목업 §X 참조)>
+...
+
+각 항목 ✓/✗ 응답
+```
 
-1. 사용자검수 필요 항목 사용자에게 표시 + 스크린샷 경로 (있으면).
-2. 사용자에게 *"이 부분 직접 검수 부탁. 결과 어땠어?"* 묻기.
-3. 사용자 *"PASS"* → PASS 분기로. 사용자 *"FAIL"* → FAIL 분기로.
+2. **시각 영역 fix 사이클 사전 예고** — 시각 영역 항목 있으면 *"시각 영역은 한 사이클로 100% 일치 보장 X. fix 사이클 1~2회 예상. ✗ 발견 시 정상."* 안내. 사용자 기대치 사전 정렬, 부정 반응 누적 방지.
+3. 사용자 응답 받음:
+   - 모두 ✓ → PASS 분기로 (`tested` 전이).
+   - ✗ 1개 이상 → FAIL 분기로 (`developing` 회귀 + ✗ 항목별 fix).
 
 ### Step 6 — 결과 보고 (위 분기별 메시지)
 

package/template/.project/FRICTION_LOG.md

@@ -1,23 +1,16 @@
 # FRICTION_LOG
 
-> 짜증 / 한계 / 짚이는 부분 누적.
-> 메인이 사용자 발화에서 *"이거 짜증나"* 감지하거나 사용자 명시 요청 시 한 줄씩 추가.
-> `/refine` 스킬이 정독 + 반복 패턴 감지 + bottoms-up 보강 제안.
+> 사용자가 작업 흐름 중 겪은 불편 / 한계 / 짚이는 부분의 누적.
+> `/log-friction` 스킬이 사용자 합의 후 한 행씩 추가한다.
 
 **사용 규칙**:
-- 한 행에 한 짜증
+- 한 행에 한 불편
 - 손수 편집 X — 메인이 대화로 적음
-- *"이거 짜증나, 적어줘"* 발화 또는 메인 자체 감지 시 추가
+- 사용자 명시 호출 / 사용자 불만 발화 캐치 / task-close 직후 마찰 신호 자체 감지 시 추가
 
 ---
 
-## 짜증 누적
+## 불편 누적
 
-| 날짜 | 짜증 | 맥락 (어느 task / 스킬 / 카테고리) |
+| 날짜 | 불편 | 맥락 (어느 task / 스킬 / 카테고리) |
 |------|------|-----------------------------------|
-
----
-
-## /refine 회고 메타 행
-
-(매 `/refine` 호출 결과를 메타 행으로 추가 — 다음 회고가 *이전 결과 참조*용)