@angar2/taskery 0.2.1 → 0.3.1

package/template/shared/skills/task-plan/SKILL.md

@@ -21,10 +21,10 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 `.gitignore` 케이스 분기:
 
-| 케이스 | task 문서 위치 | 9 기획 문서 위치 | 동시 쓰기 |
+| 케이스 | task 문서 위치 | 제품 관통 문서 위치 | 동시 쓰기 |
 |--------|--------------|----------------|----------|
-| 등록 (퍼블릭 리포 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 문서는 여전히 단일 소스) | 단일 세션 가정 (워크트리 내부) |
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<NNN_slug>/...` | `$MAIN_WT/.project/<doc>.md` (루트 평평) | `withMetaLock` (`bin/lib.js`) |
+| 미등록 | `$WT_PATH/.project/tasks/<NNN_slug>/...` (워크트리 안, 머지 시 dev 반영) | `$MAIN_WT/.project/<doc>.md` (제품 문서는 여전히 단일 소스) | 단일 세션 가정 (워크트리 내부) |
 
 본문 모든 `.project/...` 경로는 *위 분기에 따라* 적용. spec-diff / mockup / screenshots는 task 문서와 같은 위치.
 
@@ -32,14 +32,15 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 - `/task-init`로 만든 빈 골격 task에 기획 채울 때.
 - 기존 task 기획 다시 짜고 싶을 때 (단 status=`draft`만. `planned` 이상이면 *직접 Edit*하거나 `/task-init` 새로 만들 것 권장).
+- **Test Plan 보수 재진입** (status=`testing`만): `/task-test`가 *시험문제 결함(UNCERTAIN 검증 불가)*으로 반려한 직후 — Test Plan 시나리오를 [실행 명령 + 구체적 기대값]으로 다시 작성하러 온 경우. **Test Plan 섹션만** 보수하고 Requirements / Scope / Dev Plan / 코드는 보존한다 (아래 Step 1 가드 예외 참조).
 
 ## 입력 처리
 
 인자 = (선택) `TASK-NNN` 또는 자동 선택.
 
 분기:
-- **인자 명시**: `.project/tasks/<vX.X>/<NNN>_*.md` 또는 `TASK-<NNN>_*/task.md` 찾아서 진행.
-- **인자 없음**: 활성 plan 버전의 `.project/tasks/<vX.X>/` 안 *상태=draft인 가장 최근 task* 자동 선택 + confirm.
+- **인자 명시**: `.project/tasks/<NNN_slug>/<NNN>_*.md` 또는 `TASK-<NNN>_*/task.md` 찾아서 진행.
+- **인자 없음**: 활성 plan의 `.project/tasks/<NNN_slug>/` 안 *상태=draft인 가장 최근 task* 자동 선택 + confirm.
 
 ## 단계
 
@@ -48,8 +49,11 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 1. `.project/AGENT-GUIDE.md` Read → 활성 plan 버전 확인.
 2. task 파일 Read:
    - 인자 있음 → 해당 파일.
-   - 인자 없음 → `ls .project/tasks/<vX.X>/` 결과 중 status=draft인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"draft 상태 task가 없네요. `/task-init` 먼저 호출하세요."* + 종료.
-3. 상태 = `draft` 검증. 다른 상태면 종료 + 안내.
+   - 인자 없음 → `ls .project/tasks/<NNN_slug>/` 결과 중 status=draft인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"draft 상태 task가 없네요. `/task-init` 먼저 호출하세요."* + 종료.
+3. 상태 검증 — 두 진입만 허용, 그 외 종료 + 안내:
+   - **`draft`** → 일반 기획 (Step 2~ 전체 진행).
+   - **`testing` + Test Plan 보수 모드** → `/task-test`가 *시험문제 결함*으로 반려해 되돌아온 경우에 한해 허용. 이때는 **Test Plan 섹션만 보수**(Requirements / Scope / Dev Plan 보존), Step 2~4는 건너뛰고 Step 5(Test Plan)만 수행, status는 `testing` 그대로 둔다(전이 X — 보수 후 `/task-test` 재실행).
+   - **그 외(`planned` / `developing` / `developed` / `tested` / `closed`)** → 종료 + 안내. (특히 `tested` / `closed`는 보수 모드로도 진입 거부 — 우회 방지.)
 
 ### Step 2 — Requirements 인터뷰 + 증폭
 
@@ -112,8 +116,9 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
    - **어떻게**: 구현 방법 1~3줄
    - **완료 기준**: 끝났다고 판단할 기준 (예: *"API endpoint 200 반환"*)
    - **진행**: `[ ]`
-4. **Phase 0 (선택) — plan 문서 변경 검토**:
-   - 본 task가 `.project/plans/<vX.X>/` 9 기획 문서 중 어느 것을 *수정/추가/삭제*해야 하는지 검토.
+4. **Phase 0 (선택) — 제품 관통 문서 변경 검토**:
+   - 본 task가 `.project/` 루트 제품 관통 문서(FEATURES / UX-UI / DATA-MODEL / API-SPEC / SERVICE-POLICY / TECH-STACK / ARCHITECTURE) 중 어느 것을 *수정/추가/삭제*해야 하는지 검토.
+   - **DATA-MODEL / API-SPEC 상세는 여기가 채우는 주체** — plan-init은 의도/빈 헤더까지만 두고 미뤘다. 본 task가 스키마·엔드포인트를 *구현 동반*으로 확정해 본문을 채운다(선기획 금지의 귀결).
    - 변경 있음 → Phase 0에 명시 + `spec-diffs/<NNN>_<slug>_spec-diff.md` 파일 생성 (Step 6).
    - 변경 없음 → Phase 0 생략.
 5. **Phase 점진 작성 OK** — 처음부터 모든 Phase 일괄 작성 금지. 지금 명확한 Phase만 작성하고 진행 중 추가 가능.
@@ -121,8 +126,8 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 ```markdown
 ## Dev Plan
 
-### Phase 0 — plans/<vX.X>/ 기획 문서 변경 (선택)
-- 변경 문서: <FEATURES.md / API-SPEC.md / ...>
+### Phase 0 — 제품 관통 문서(.project/ 루트) 변경 (선택)
+- 변경 문서: <FEATURES.md / API-SPEC.md / DATA-MODEL.md / ...>
 - 변경 내용: <요약>
 - spec-diff: `spec-diffs/<NNN>_<slug>_spec-diff.md`
 - 진행: [ ]
@@ -139,7 +144,7 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 ### Step 4.5 — HTML 목업 프로세스 (UX/UI 구현 task 한정 — stash FRICTION_LOG #14+19 반영)
 
-본 task가 UX/UI 구현 포함하면 *시각 영역 사전 정합* + *task-test 시 USER 검수 기준 확보*용 HTML 목업 생성.
+본 task가 UX/UI 구현 포함하면 *시각 영역 사전 정합* + *task-test 시각 자동 대조 정답지 확보*용 HTML 목업 생성.
 
 #### 1. UX/UI 구현 task 판단
 
@@ -167,18 +172,21 @@ Step 2 Requirements 인터뷰 결과로 본 task가 *UX/UI 구현 (페이지/컴
 1. 메인이 HTML 목업 생성 — 정적 HTML/CSS (외부 라이브러리 X, 단일 파일 안 inline style + 필요 시 vanilla JS):
    - 시각 영역 (레이아웃 / 색상 / 간격 / 타이포 / 호버 효과)
    - 인터랙션 (가능한 범위 — 클릭 / 호버 시뮬)
-2. 사용자에게 *"브라우저로 `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html` 열어 확인 후 ✓/✗ 응답"*.
+2. 사용자에게 *"브라우저로 `.project/tasks/<NNN_slug>/mockup/<task-doc-name>-mockup.html` 열어 확인 후 ✓/✗ 응답"*.
 3. 사용자 ✓ → 승인 완료, 4 진행. ✗ → 메인이 수정 후 재승인 요청.
 
 #### 4. 파일 위치 / 네이밍
 
-- 위치: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+- 위치: `.project/tasks/<NNN_slug>/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]` 분류 + 목업 경로 참조 명시.
+승인된 목업 = task-test의 **시각 *자동 대조* 정답지** (+ 미세 취향은 사용자 최종 사인). 사용자가 맘에 들 때까지 승인 안 하므로 목업 = 이미 사용자가 검증한 정답지 — task-test 격리 세션이 *실제 화면 캡처 → 이 목업과 자동 대조*해 객관적 깨짐을 잡는다. Step 5 Test Plan 작성 시:
+- **시각 *객관* 영역(레이아웃/요소 유무/색/배치) → `[AUTO]`** (캡처-목업 대조) + 목업 경로 참조 명시.
+- **시각 *미세 취향*(2px·색조·느낌) → `[USER]`** (사용자 최종 사인, 증거 캡처).
+(이전의 "승인 목업 = USER 검수 기준 / 시각=전부 [USER]"는 폐기 — 사용자에게 흠 사냥을 떠넘기던 원인.)
 
 ---
 
@@ -194,38 +202,65 @@ Test Plan = *본 task에서 구현한 요구사항이 정상 동작하는지*
 - UX/UI 시각: 레이아웃 / 색상 / 간격 / 호버 효과 (목업 기준)
 - 백엔드 동작: 시스템 호출 → 외부 응답 / 사이드 이펙트 / 에러 처리
 
+#### 방식 선택 규칙 (요구사항 성격 → 필수 방식, 재량 0)
+
+방식을 *느낌으로* 고르지 말 것. 각 요구사항을 아래 표에 *기계적으로* 대조해 필수 방식을 정한다. 여러 행에 걸리면 *다 붙인다*:
+
+| 요구사항이 이런 거면 | 필수 테스트 방식 |
+|---|---|
+| 화면을 새로 그리거나 바꾼다 | 시각 (캡처-목업 대조) |
+| 클릭·입력 등 상호작용 | UI 동작 (E2E 또는 사람) |
+| 엔드포인트 추가·변경 | API 호출 |
+| 데이터 쓰기·변경·삭제 | 데이터 상태 조회 (사이드 이펙트) |
+| 순수 계산·변환 | 입출력 비교 |
+| 기존 동작 영역 건드림 | 회귀 |
+
+이렇게 고른 방식을 아래 카탈로그의 *구체적 방식*으로 옮긴다. (이 규칙은 뒤의 "요구사항 ↔ 시나리오 커버리지 점검"의 *입력* — 매핑이 방식을 정하고, 커버리지 점검이 빠진 요구사항을 잡는다. 중복 아니라 보강 관계.)
+
 #### 실질 테스트 방식 카탈로그
 
-각 시나리오마다 아래 방식 중 적합한 1개 이상 선택:
+각 시나리오마다 위 규칙으로 고른 방식을 아래에서 구체화. **각 방식은 *비교할 정답지*가 다르다 — 정답지 없는 검사는 무의미**:
 
-| 방식 | 적용 영역 | 설명 |
-|------|----------|------|
-| 수동 검수 | UI / UX / 인터랙션 | 사용자가 실제 앱·환경에서 직접 조작·확인 |
-| 시나리오 스크립트 실행 | 백엔드 / 통합 흐름 | end-to-end script (bash / node 등) 일련의 명령 자동 실행 |
-| API/엔드포인트 호출 | 백엔드 / 외부 인터페이스 | 실제 호출 + 응답·상태 코드·결과 데이터 확인 |
-| 입출력 비교 | 함수 / 변환 / 처리 | 입력 → 출력 비교 (snapshot / golden file) |
-| 사이드 이펙트 확인 | DB / 파일 / 로그 | 시나리오 실행 후 상태 직접 조회 |
-| 회귀 시나리오 | 기존 기능 영향 | 직전 동작하던 시나리오 재실행 |
-| E2E 자동화 도구 | UI 자동화 (도구 있을 시) | Playwright / Cypress / XCTest UI Test 등 — 가능하면 자동화, 안 되면 수동 검수 |
+| 방식 | 적용 영역 | 정답지 (무엇과 비교) | 누가 검사 | 설명 |
+|------|----------|------|------|------|
+| 수동 검수 | UI 미세 / UX 느낌 | 주관(목업·사용감) | 사람 (증거 첨부) | 정답지가 주관인 것만 — 객관 깨짐은 아래 시각 자동으로 |
+| 시나리오 스크립트 실행 | 백엔드 / 통합 흐름 | 구체적 출력·종료코드 | test 자동 | end-to-end script (bash / node 등) 일련의 명령 자동 실행 |
+| API/엔드포인트 호출 | 백엔드 / 외부 인터페이스 | 상태코드 + 응답 필드값 | test 자동 | 실제 호출 + 응답·상태 코드·결과 데이터 확인 |
+| 입출력 비교 | 함수 / 변환 / 처리 | 구체적 기대 출력 | test 자동 | 입력 → 출력 비교 (snapshot / golden file) |
+| 사이드 이펙트 확인 | DB / 파일 / 로그 | 조회 결과(행/파일/카운트) | test 자동 | 시나리오 실행 후 상태 직접 조회 |
+| 시각 (캡처-목업 대조) | UI 레이아웃/색/배치 | 승인된 목업 | test 자동 (+ 미세는 사람) | 실제 화면 캡처 → 목업과 대조, 어긋남 목록 |
+| 회귀 시나리오 | 기존 기능 영향 | 이전과 동일 결과 | test 자동 | 직전 동작하던 시나리오 재실행 |
+| E2E 자동화 도구 | UI 동작 자동화 (도구 있을 시) | 액션 후 관측 변화 | 도구면 test, 아니면 사람 | Playwright / Cypress / XCTest UI Test 등 — 가능하면 자동화, 안 되면 수동 검수 |
 
 #### UX/UI 영역 분리 + 검증 방식 매트릭스 (UX/UI 구현 task 한정)
 
-| 영역 | 자동화 가능 시 | 자동화 불가 시 |
-|------|---------------|---------------|
-| 동작 (클릭/호버/드래그/입력 → 결과) | `[AUTO]` E2E 자동화 시나리오 스크립트 | `[USER]` 체크리스트 |
-| 시각 (레이아웃/색상/간격/호버 효과 강도) | (자동 비교 의미 없음 — 픽셀 단위 변화 + 주관 판단 영역) | `[USER]` 체크리스트 + 목업 기준 참조 |
+| 영역 | 분류 | 기준 |
+|------|------|------|
+| 동작 (클릭/호버/드래그/입력 → 결과) | 도구 있으면 `[AUTO]` E2E, 없으면 `[USER]` 체크리스트 | 액션 후 관측되는 변화 |
+| 시각 *객관* (레이아웃/요소 유무/색/배치 깨짐) | `[AUTO]` 캡처-목업 대조 | 승인된 목업 (격리 세션이 화면 캡처 → 대조 → 어긋남 목록) |
+| 시각 *미세 취향* (2px·색조·호버 강도·느낌) | `[USER]` 체크리스트 + 목업 참조 | 사용자 최종 사인 (증거 캡처 첨부) |
+
+#### 시나리오 형식 — [명령/입력] + [구체적 기대값] 한 쌍 강제
+
+**모든 `[AUTO]` 시나리오 = [실제 실행할 명령/입력] + [실제로 나올 구체적·관측 가능한 값] 한 쌍.** 이게 task-test 격리 세션이 "문 앞 검사"에서 자격을 확인하는 형태다 — 안 갖추면 검사가 시작되지 않고 *시험문제 결함*으로 반려된다(빈 권고 아님).
 
-#### 시나리오 형식
+- **소원 금지** — "정상 동작 / 잘 됨 / 확인한다 / 문제 없음"은 PASS 기준이 아니다. 눈에 보이는 결과(출력값 / 상태코드 / 어서션 / 조회 행수 / 화면 상태)여야 한다.
+- **장면 쪼개기** — "로그인 되나 봐" 한 덩어리 금지. *진짜 떨어질 장면 여러 개*로 분해.
+- **잣대** — "이게 고장나면 *어떻게 걸리나*"를 못 적는 장면 = 테스트 아님 → 버린다.
+
+예 (로그인 5회 실패 시 15분 잠금):
+- ❌ `5번 실패하면 잠긴다 | 잠금이 정상 동작함`
+- ✅ `틀린 비번 5회 POST → 6번째 응답코드 == 423 + body에 retry_after. 4번째는 401(미잠금).`
 
 ```markdown
 ## Test Plan
 
-| # | 시나리오 | 분류 | 방식 | PASS 기준 |
+| # | 시나리오 | 분류 | 방식 | PASS 기준 (구체적 기대값) |
 |---|---------|------|------|----------|
-| 1 | <한 줄 설명> | [AUTO] / [USER] | <카탈로그 방식> | <명확한 기대값> |
+| 1 | <쪼갠 장면 한 줄: 무엇을 실행> | [AUTO] / [USER] | <카탈로그 방식> | <관측 가능한 구체값 — 출력/상태코드/조회결과/화면상태> |
 | 2 | ... | ... | ... | ... |
 
-(UX/UI task — 목업 있으면) 시각 USER 시나리오 기준: `.project/tasks/<vX.X>/mockup/<task-doc-name>-mockup.html`
+(UX/UI task — 목업 있으면) 시각 시나리오 정답지: `.project/tasks/<NNN_slug>/mockup/<task-doc-name>-mockup.html`
 ```
 
 #### 시각 영역 fix 사이클 사전 예고 (stash FRICTION_LOG #14 반영)
@@ -239,7 +274,7 @@ Test Plan = *본 task에서 구현한 요구사항이 정상 동작하는지*
 - **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
 - **명령/기대값 포함**: 무엇을 실행하고 무엇이 기대되는지 명확.
 - **메인 가정 X**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
-- **grep/Read-only 존재 확인 시나리오 = 보조용** (stash FRICTION_LOG 2026-06-01 반영) — 구현 코드의 존재 여부를 grep/Read로 재확인하는 시나리오는 *동어반복*. PASS 카운트에서 제외하거나 실동작 시나리오의 *보조*로만 사용. 단독 검증 가치 X.
+- **grep/Read-only 존재 확인 시나리오 = 보조용, PASS 대체 영구 금지** (stash FRICTION_LOG 2026-06-01 반영) — 구현 코드의 존재 여부를 grep/Read로 재확인하는 시나리오는 *동어반복*. PASS 카운트에서 제외, 실동작 시나리오의 *보조*로만 사용. 단독 검증 가치 X — grep으로 실동작 검증을 *대체*할 수 없다(task-test 룰 10과 동일 강도).
 - **요구사항당 end-to-end 1개 이상 강제** — Requirements 각 항목이 *사용자 관점에서 실제 작동하는지* 검증하는 end-to-end 실동작 시나리오 최소 1개 보장. 산출물 실행 → 결과 확인 형태.
 - **무거운 검증 회피 영구 금지** — 부담(빌드 수 분+ / 외부 의존 / 환경 설정) 이유로 실동작 시나리오를 grep 동어반복으로 대체 X. 최소 1회는 실제 산출물로 확인. 부담은 *fix 사이클 1~2회 예상* 같은 사전 예고로 처리 (생략 사유 X).
 
@@ -263,21 +298,33 @@ Test Plan 작성 완료 후 *반드시* 점검 단계 수행. *"누적/리셋
 | <Req 3 한 줄> | #5 |
 ```
 
+#### 실행 경로 확인 — "이 프로젝트에서 이 방식을 실제로 어떻게 돌리나" (필수)
+
+방식을 골랐어도, **격리 세션이 *이 프로젝트의* DB/API/E2E에 실제로 어떻게 접근하는지 모르면 그 시나리오는 실행 불가능한 허울뿐인 명세다.** 스택마다 다르다(NestJS+TypeORM이면 그 DataSource/repository, 다른 프로젝트는 또 다름). 그래서 *모르면 묻고, 알면 재사용*:
+
+1. 필요 방식마다 `$MAIN_WT/.project/TEST-GUIDE.md`를 Read → **이 프로젝트에 실행 경로가 적혀 있나** 확인.
+2. **있으면** → 그 경로를 시나리오의 *방식* 칸에 반영(재사용). 앱은 기존 실행 명령으로 띄움.
+3. **없으면** → *멈추고 사용자에게 요구*: 예) *"이 요구사항은 DB 검증이 필요한데 이 프로젝트에 실행 경로가 없다. 어떻게 검증할지 알려주거나 도구를 깔아줘."* → 사용자가 경로를 주거나 결정.
+4. **확인받은 즉시 `TEST-GUIDE.md`에 기록** → 다음 task/세션부터 안 묻고 재사용. (재사용 = 기억이 아니라 *파일* — 세션/컴팩트로 사라지지 않게.)
+
+> TEST-GUIDE는 init이 빈 골격으로 깔아둔다(`.project/TEST-GUIDE.md`). 방식별 섹션(데이터 검증 / API 호출 / UI·E2E / 시각 실행 / 기타)에 *이 프로젝트의 실제 실행 방법*을 채운다.
+
 #### 검증/테스트 명령 참조
 
-`/task-test` 격리 세션은 프로젝트 루트 `CLAUDE.md`의 두 섹션을 자동 참조 — Test Plan에 재인용 불필요:
+`/task-test` 격리 세션은 프로젝트 루트 `CLAUDE.md`의 두 섹션 + `TEST-GUIDE.md`를 자동 참조 — Test Plan에 재인용 불필요:
 - `## 검증 명령` (코드 상태 — 빌드/린트/타입체크)
 - `## 테스트 명령` (테스트 실행 — 단위/통합/E2E)
+- `.project/TEST-GUIDE.md` (각 방식의 *이 프로젝트 실제 실행 방법*)
 
 ### Step 6 — spec-diff 처리 (Phase 0 변경 있을 시)
 
-1. `.project/tasks/<vX.X>/spec-diffs/` 디렉토리 존재 확인 (없으면 `mkdir -p`).
+1. `.project/tasks/<NNN_slug>/spec-diffs/` 디렉토리 존재 확인 (없으면 `mkdir -p`).
 2. `spec-diffs/<NNN>_<slug>_spec-diff.md` Write — 형식:
 
 ```markdown
 # Spec Diff — TASK-<NNN> <제목>
 
-## <plans/<vX.X>/<문서명>.md> [NEW|MOD|DEL]
+## <.project/<문서명>.md> [NEW|MOD|DEL]
 
 +++
 + <추가/변경 내용>
@@ -308,7 +355,7 @@ Test Plan 작성 완료 후 *반드시* 점검 단계 수행. *"누적/리셋
 
 ## 도구 가이드
 
-- **Read**: task 파일 / 활성 plan 9 기획 문서 / 관련 코드 정독
+- **Read**: task 파일 / `.project/` 루트 제품 관통 문서 / 관련 코드 정독
 - **Grep / Glob**: Scope 코드 서치 (관련 함수/파일 탐색)
 - **Edit**: task 파일 4 섹션 채우기 + status 전환
 - **Write**: spec-diff 파일 (Phase 0 변경 시)
@@ -332,5 +379,7 @@ Test Plan 작성 완료 후 *반드시* 점검 단계 수행. *"누적/리셋
 | 진입 시 | 종료 시 |
 |--------|--------|
 | `draft` | `planned` |
+| `testing` (Test Plan 보수 모드) | `testing` (유지 — Test Plan만 보수 후 `/task-test` 재실행) |
 
 (예외 — 합의 못 함: status 그대로 `draft` 유지. 다음 호출 시 다시 시도.)
+(Test Plan 보수 모드: `/task-test`가 *시험문제 결함*으로 반려한 경우만 — Step 1 가드 참조. Requirements/Scope/Dev Plan/코드 보존, status 전이 X.)

package/template/shared/skills/task-test/SKILL.md

@@ -23,11 +23,13 @@ MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 
 | 케이스 | task 문서 위치 | 격리 세션 작업 디렉토리 |
 |--------|--------------|---------------------|
-| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<vX.X>/...` | `$WT_PATH` (워크트리 — 코드 변경 위치) |
-| 미등록 | `$WT_PATH/.project/tasks/<vX.X>/...` (워크트리 안) | `$WT_PATH` (워크트리) |
+| 등록 (퍼블릭 리포 default) | `$MAIN_WT/.project/tasks/<NNN_slug>/...` | `$WT_PATH` (워크트리 — 코드 변경 위치) |
+| 미등록 | `$WT_PATH/.project/tasks/<NNN_slug>/...` (워크트리 안) | `$WT_PATH` (워크트리) |
 
 격리 세션은 *워크트리 안*에서 검증/테스트 명령 실행 (`$MAIN_WT/CLAUDE.md`의 `## 검증 명령` / `## 테스트 명령` 단일 진실 소스).
 
+**검증 방법 출처 = `$MAIN_WT/.project/TEST-GUIDE.md`** — 각 테스트 방식(데이터 조회 / API 호출 / E2E / 시각 실행)을 *이 프로젝트에서 실제로 어떻게 돌리나*가 적힌 단일 소스. 격리 세션 prompt에 task 문서 경로와 *동일 방식*으로 이 절대 경로를 넘긴다 (메모리 아닌 파일 — 세션/컴팩트 무관 재사용).
+
 ## 호출 시점
 
 - `/task-dev` 끝나고 self-check PASS 받은 직후.
@@ -67,29 +69,39 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 
 ## 대상 task
 
-파일 경로: <ABSOLUTE_PATH_TO_TASK_MD>
+task 파일 경로: <ABSOLUTE_PATH_TO_TASK_MD>
+검증 방법 문서: <ABSOLUTE_PATH_TO_TEST_GUIDE_MD>
 
-이 파일을 직접 Read 해서 ## Test Plan 섹션 + ## Dev Plan의 Phase별 완료 기준을 정독하세요. 다른 문서 참조 X — task.md 하나만 봅니다.
-(단 task.md가 `mockup/<task-doc-name>-mockup.html` 참조하면 해당 목업 파일도 직접 Read — 시각 USER 시나리오의 *기준*으로 사용. 자동 비교 X.)
+task 파일을 직접 Read 해서 ## Test Plan 섹션 + ## Dev Plan의 Phase별 완료 기준을 정독하세요. 그리고 *검증 방법 문서(TEST-GUIDE.md)* 도 직접 Read — 각 테스트 방식을 *이 프로젝트에서 실제로 어떻게 실행하나*(DB 조회 경로 / API 호출법 / E2E 셋업 등)의 단일 소스입니다. 이 둘 + 목업 외 다른 문서 참조 X.
+(단 task.md가 `mockup/<task-doc-name>-mockup.html` 참조하면 해당 목업 파일도 직접 Read — *승인된 목업 = 시각 시나리오의 정답지*입니다. 시각 시나리오 = 실제 화면 캡처 → 이 목업과 자동 대조.)
 
 ## 수행 룰
 
 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.
+4. `[USER]` 시나리오 — *정답지가 주관*인 영역만 (시각 미세 취향 / 색조·여백 2px 수준 / UX 사용감·매끄러움). UNCERTAIN(사람 검수)으로 분류 + *사용자 직접 검수 항목*으로 리턴 (단 증거=캡처 첨부). **시각 *객관* 영역(레이아웃 깨짐 / 요소 빠짐 / 빈 화면 / 색 완전히 틀림 / 배치 딴판)은 `[USER]`가 아니라 `[AUTO]`** — 실제 화면 캡처 → 승인 목업과 직접 대조해 격리 세션이 판정. (시각이라고 무조건 사람에게 넘기지 말 것 — 객관 깨짐은 네가 잡는다.)
 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 / 로그 출력 / 어서션 통과 여부*만. 본문 의도 해석 영역 외 — 결과 기반 판정만.
 10. **grep/Read-only 존재 확인 시나리오 = 보조 검증** (stash FRICTION_LOG 2026-06-01 반영) — 시나리오가 *코드/파일에 X가 존재하나*를 grep / Read로 재확인하는 형태(동어반복)면 *보조 검증*으로 분류. 종합 판정의 PASS 카운트에서 제외하고, 같은 영역의 *실동작 시나리오*가 PASS인 경우에만 보조 자료로 첨부. 단독 PASS 가치 X. 실동작 시나리오 없이 grep-only 시나리오만으로 종합 PASS 단정 영구 금지 — 그 경우 *실동작 시나리오 부재*로 UNCERTAIN/FAIL 판정 + 메인 보고.
+11. **문 앞 검사 — 실행 전 시험문제 자격 확인 (먼저)**. 시나리오를 돌리기 *전에*, 각 `[AUTO]` 시나리오가 **[실행할 명령/입력] + [구체적 기대값(관측 가능한 결과 — 출력값 / 상태코드 / 어서션 / 조회 결과 / 화면 상태)]** 한 쌍을 갖췄는지 확인. *"정상 동작" / "잘 됨" / "확인한다"* 같은 *소원*은 기대값이 아님. 자격 미달 `[AUTO]` 시나리오가 있으면 → **그 시나리오는 검사하지 말고 "시험문제 결함(검증 불가)"으로 분류** + 무엇이 빠졌는지 지목 (아래 룰 13). 자격 미달을 PASS로 반올림 영구 금지.
+12. **증거 일치 시만 PASS**. 자격을 갖춘 `[AUTO]` 시나리오는 *실제로 실행*하여 — *관측한 결과가 기대값과 일치할 때만* PASS. 코드 정독 "그럴듯함" / 추정 / "될 듯"으로 PASS 영구 금지. 증거(명령 출력 · 응답 로그 · 캡처 · 조회 결과)를 결과 표 근거 칸에 첨부.
+13. **UNCERTAIN 두 종류 — 섞지 말 것**.
+    - **UNCERTAIN(사람 검수)** — 정답지가 *주관*인 영역(룰 4: 시각 미세 취향 / UX 느낌). 정상. 사용자 직접 검수 항목으로 리턴 (증거 캡처 첨부).
+    - **UNCERTAIN(검증 불가)** — `[AUTO]`로 분류됐는데 *대조할 기대값을 구성하지 못한* 경우 = **시험문제 결함**. PASS로 반올림 금지, 사람 검수로도 넘기지 말 것(주관 아님). **근거 의무**: *무엇을 시도했고 왜 기대값을 구성할 수 없는지* 반드시 기록. (이건 네가 쉴 자리가 아니라 task-plan으로 되돌아가 Test Plan을 보수해야 하는 신호 — 도망쳐도 이득 없음.)
+14. **시각 `[AUTO]` 시나리오 = 캡처-목업 대조**. 앱을 띄워 실제 화면을 캡처 → 승인된 목업(정답지)과 대조. 어긋나면 → *구체적 어긋남 목록*(예: "헤더 색 틀림 / 카드가 가로 아닌 세로로 쌓임 / 저장 버튼 없음")을 뽑아 **FAIL**로 보고. 합격선 = *픽셀 일치가 아니라* "사람이 보면 '이거네' 할 정도로 본질적으로 같다" (객관적 깨짐만 잡고 미세 취향은 룰 4로). 증거 = 스크린샷 + 어긋남 목록.
 
 ## 결과 형식 (이 포맷 그대로 리턴)
 
 ### 종합 판정
 - **PASS** / **FAIL** / **UNCERTAIN** 중 하나
-- UNCERTAIN = `[USER]` 시나리오 또는 자동 검증 불가 항목이 1개 이상 있으면. PASS 자동 전이 X — 사용자 직접 검수 필요.
+- **UNCERTAIN** = 아래 둘 중 하나라도 1개 이상이면. *두 경우 모두 PASS 자동 전이 X* (공통). 그 다음 종류에 따라 라우팅이 갈림:
+  - **UNCERTAIN(사람 검수)** — 정답지가 주관인 `[USER]` 항목. → 사용자 직접 검수.
+  - **UNCERTAIN(검증 불가)** — `[AUTO]`인데 기대값 구성 불가 = 시험문제 결함. → task-plan으로 Test Plan 보수 (사람 검수 아님). 어느 시나리오가 왜 검증 불가인지 명시.
+- 종합이 UNCERTAIN일 때 *두 종류 중 무엇인지* 반드시 표기 (둘 다면 둘 다).
 - 한 줄 요약
 
 ### 시나리오별 결과
@@ -112,19 +124,25 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 ### 실패 / 불확정 상세 (해당 시)
 - <어느 시나리오 / 무엇이 깨졌는지 / 어느 로그가 그 증거인지>
 
-### USER 검수 필요 항목 (UNCERTAIN — 해당 시)
-- <시나리오 N: 검수 항목 한 줄>
+### USER 검수 필요 항목 (UNCERTAIN 사람 검수 — 해당 시)
+- <시나리오 N: 검수 항목 한 줄 (주관 정답지 — 시각 미세 / UX 느낌)>
 - <목업 파일 경로 — 있을 시 시각 영역 기준으로 참조>
 
+### 시험문제 결함 (UNCERTAIN 검증 불가 — 해당 시)
+- <시나리오 N: 무엇이 [AUTO]인데 기대값을 못 만들었나 + 무엇을 시도했나 + 왜 불가한가>
+  → task-plan으로 Test Plan 보수 필요 (이 시나리오를 [실행 명령 + 구체적 기대값]으로 다시 작성).
+
 ## 종료 조건
 
 위 형식 그대로 리턴 후 종료. 코드 수정 시도 금지 — 결과 리턴만.
 ```
 
 **구현 디테일**:
-- `<ABSOLUTE_PATH_TO_TASK_MD>` 자리에 `.project/tasks/<vX.X>/<NNN>_<slug>.md` (또는 폴더 승격 시 `<...>/task.md`)의 절대 경로 삽입.
+- `<ABSOLUTE_PATH_TO_TASK_MD>` 자리에 `.project/tasks/<NNN_slug>/<NNN>_<slug>.md` (또는 폴더 승격 시 `<...>/task.md`)의 절대 경로 삽입.
+- `<ABSOLUTE_PATH_TO_TEST_GUIDE_MD>` 자리에 `$MAIN_WT/.project/TEST-GUIDE.md`의 절대 경로 삽입 (위 "멀티세션 메타 위치"의 `MAIN_WT` 사용 — 워크트리에서 호출돼도 메인 워크트리의 단일 소스를 읽도록).
 - Task tool의 `subagent_type`: `general-purpose` (도구 풀 다 필요).
 - Task tool의 `description`: `Isolated test for TASK-<NNN>`.
+- **코덱스 spawn (플랫폼 패리티)**: 코덱스에선 `.codex/agents/task-tester.toml`의 `task-tester` 서브에이전트로 spawn하되, *위 펜스 전체를 task prompt로 그대로 전달*한다 — 펜스가 양 플랫폼 공통 단일 룰 소스다(클로드 = `general-purpose` + 펜스 / 코덱스 = `task-tester` + 펜스, 동일 효과). `task-tester`의 `developer_instructions`는 같은 룰의 코덱스 기준선 미러 — 본 펜스의 수행 룰을 바꾸면 그 `developer_instructions`도 함께 갱신한다.
 
 ### Step 4 — 결과 리턴 + Result 섹션 기록
 
@@ -178,10 +196,26 @@ Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 +
 2. "OK 마무리" — 실패 알면서 /task-close 진행 (위험: 알려진 결함 채로 closed)
 ```
 3. 사용자 *"고쳐"* → 헤더 status `testing` → `developing` Edit + `/task-dev` 안내. 사용자 *"OK 마무리"* → status `testing` → `tested` Edit (단 Result 섹션에 *"알려진 결함 있음"* 명시) + `/task-close` 안내.
+4. **시각 어긋남 FAIL의 경우** — 격리 세션이 준 *어긋남 목록*을 그대로 보고에 실어, 사용자 *"고쳐"* 시 `/task-dev`가 그 목록을 **한 번에 배치로** 수정하도록 안내(흠을 사용자가 직접 찾지 않음 — test가 찾아줌). **재검사 라운드 상한 = 3회** (기본값, 프로젝트별 조정 가능): dev↔test를 3회 돌고도 어긋남이 남으면 멈추고 *현 상태 + 남은 어긋남*을 사용자에게 보고해 판단을 받는다. (전이는 매 라운드 사용자 *"고쳐"* 발화로 진행 — 무인 자동 루프 아님.)
+
+#### UNCERTAIN(검증 불가) 분기 — 시험문제 결함 → Test Plan 보수
+
+격리 세션이 `[AUTO]` 시나리오인데 *대조할 기대값을 구성하지 못함*(시험문제 결함)을 보고한 경우. 코드 결함이 아니라 *시험문제* 결함이므로 `/task-dev`(코드 수정)가 아니라 `/task-plan`(Test Plan 보수)으로 간다.
+
+1. status는 `testing` 그대로 유지 (코드는 멀쩡 — 되돌리지 않음).
+2. 사용자에게 보고:
+```
+⚠️ TASK-<NNN> 격리 검증 — 시험문제 결함 (검증 불가)
+- 결함 시나리오: <목록 + 무엇을 시도했고 왜 기대값 구성 불가인지>
+- 코드 결함 아님 — 구현은 보존됨.
 
-#### UNCERTAIN 분기 (USER 검수 흐름)
+→ /task-plan 으로 Test Plan만 보수 (이 시나리오를 [실행 명령 + 구체적 기대값]으로 다시 작성) → 보수 후 /task-test 재실행
+```
+3. `/task-plan`은 *Test Plan 섹션만* 보수 (Requirements / Scope / Dev Plan / 코드 보존). 보수 후 `/task-test` 재실행 (코드 미변경이므로 `/task-dev` 재실행 없음). status는 `testing` 유지.
 
-격리 세션이 `[USER]` 시나리오 또는 자동화 불가능한 시나리오(UI 인터랙션 / 시각 디자인 / 사용자 입력 등) 발견 시. **자동 PASS 전이 X — 사용자 직접 검수 PASS 받은 후에만 `tested` 전이**.
+#### UNCERTAIN(사람 검수) 분기 (USER 검수 흐름)
+
+격리 세션이 `[USER]` 시나리오(정답지가 *주관*인 영역 — 시각 미세 취향 / UX 느낌) 발견 시. **자동 PASS 전이 X — 사용자 직접 검수 PASS 받은 후에만 `tested` 전이**. (시각 *객관* 깨짐은 여기 아니라 FAIL — 격리 세션이 캡처-목업 대조로 이미 잡음.)
 
 > **검수 서버 먼저 기동** (`## 검수 실행 명령` 선언 + 시각/UI 검수 항목 포함 시): 체크리스트를 제시하기 *전에* 서버를 백그라운드 기동(포트 = 기준 포트 + TASK번호)하고 접속 URL을 함께 제공한다 — 사용자가 실제 화면을 보며 ✓/✗ 검수하도록. 격리 세션이 기능상 이미 띄웠으면 재사용. 사용자 *"안 띄워도 돼"* 시 생략. 상세: GIT_RULE "멀티세션 검수 환경".
 
@@ -227,7 +261,7 @@ USER 검수 — N 항목 (목업 기준: <mockup path — 있을 시>)
 - **자기완결성 검증 먼저** — Step 1에서 Test Plan이 *"위에서 만든 X"* 같은 메인 컨텍스트 의존 표현 있으면 격리 세션이 헤맴. 보강 후 재시도.
 - **PASS 자체 판정 X** — 메인이 *"잘 됐을 듯"* 판정하지 X. 격리 세션 결과만 신뢰.
 - **임시 파일 정리** — 격리 세션이 만든 Playwright 스크립트 / 임시 데이터 종료 시 삭제. 코드베이스 오염 X.
-- **사용자검수 시나리오는 자동화 못 잡음** — UI 미세 조정 / 시각 디자인 / 외부 결제 등은 UNCERTAIN으로 가야 정상. PASS 강제 X.
+- **사용자검수 시나리오는 자동화 못 잡음** — UI 미세 취향 / UX 느낌 / 외부 결제 등 *정답지가 주관*인 것만 UNCERTAIN(사람 검수)으로 가야 정상. PASS 강제 X. **단 시각 *객관* 깨짐(요소 빠짐 / 빈 화면 / 배치 딴판 / 색 완전히 틀림)은 사람 검수가 아니라 격리 세션이 캡처-목업 대조로 직접 잡아 FAIL** — 사용자에게 흠 사냥을 떠넘기지 않는다.
 - **FAIL → developing 자동 되돌림 X** — 사용자 *"고쳐"* 답 받기 전 status 갱신 금지. *대화로 OK = 자동 전이* 룰의 핵심.
 - **테스트 후 plumbing fix 발견 시** — 격리 PASS 후에도 plumbing(빌드 산출물 정리, 설정 수정 등) fix 필요할 수 있음. 분기:
   - 검증 명령 *동작 자체에 영향 X* (예: 산출물 위치 정리, 주석 수정) → 메인 자체 재검증 OK (lint/typecheck/build/test 재실행)
@@ -235,9 +269,13 @@ USER 검수 — N 항목 (목업 기준: <mockup path — 있을 시>)
 
 ## 상태 전이
 
-| 진입 시 | 종료 시 |
-|--------|--------|
-| `developed` | `tested` (PASS) |
-| `developed` | `developing` (FAIL + 사용자 *"고쳐"*) |
-| `developed` | `tested` (FAIL + 사용자 *"OK 마무리"* — 알려진 결함 명시) |
-| `testing` (이어가기) | 동일 분기 |
+| 진입 시 | 종료 시 | 트리거 |
+|--------|--------|--------|
+| `developed` | `tested` | PASS |
+| `developed` | `developing` | FAIL (코드 결함) + 사용자 *"고쳐"* |
+| `developed` | `tested` | FAIL + 사용자 *"OK 마무리"* (알려진 결함 명시) |
+| `developed` / `testing` | `testing` (유지) | UNCERTAIN(사람 검수) — 사용자 직접 검수 대기 |
+| `developed` / `testing` | `testing` (유지) | UNCERTAIN(검증 불가, 시험문제 결함) → `/task-plan`으로 Test Plan 보수 → `/task-test` 재실행 (코드·status 보존) |
+| `testing` (이어가기) | 동일 분기 | — |
+
+> **세 갈래 요약**: PASS → `tested` / 코드 결함 → `developing`(사용자 *"고쳐"*) / 시험문제 결함 → Test Plan 보수(`task-plan`, 코드·status 보존) → 재검사. UNCERTAIN(사람 검수)은 검수 ✓ 받으면 `tested`, ✗면 `developing`.