@angar2/taskery 0.6.1 → 0.8.0

package/template/.claude/skills/run-team/SKILL.md

@@ -24,7 +24,7 @@ description: agent teams로 다건 태스크를 독립 워크트리에서 자동
 | 통신 | 결과만 리더에 반환 | 팀원↔리더 자동 통지 + 팀원끼리 직접 통신 (리더가 다 봄) |
 | 스킬 호출 | 제한적 | 프로젝트 `.claude/skills/` 그대로 로드 → taskery 5스킬 직접 호출 |
 
-팀원은 각자 새 세션으로 시작하며 프로젝트 `CLAUDE.md`를 자동 로드하므로 taskery 룰을 그대로 따른다.
+팀원은 각자 새 세션으로 시작하며 진입 문서(`CLAUDE.md` → `@AGENTS.md`)를 자동 로드하므로 taskery 룰을 그대로 따른다.
 
 ## 호출 시점
 
@@ -62,7 +62,7 @@ description: agent teams로 다건 태스크를 독립 워크트리에서 자동
   MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
   ```
 - 대상이 명시 작업 목록이면 그 발화를 그대로.
-- 활성 plan은 `$MAIN_WT/.project/AGENT-GUIDE.md`에서 검출.
+- 활성 plan은 `status` 도구(또는 `npx @angar2/taskery status`)로 검출.
 
 ### Step 2 — 태스크 묶기 판단
 
@@ -112,8 +112,8 @@ description: agent teams로 다건 태스크를 독립 워크트리에서 자동
 
 ## 도구 가이드
 
-- **Bash**: 메인 워크트리 검출 / 활성화 가드 확인 / BACKLOG·AGENT-GUIDE 정독용 경로 산출
-- **Read**: `$MAIN_WT/.project/tasks/<활성 plan>/BACKLOG.md` / `$MAIN_WT/.project/AGENT-GUIDE.md`
+- **Bash**: 메인 워크트리 검출 / 활성화 가드 확인 / `status`로 활성 plan 검출 / BACKLOG 정독용 경로 산출
+- **Read**: `$MAIN_WT/.project/tasks/<활성 plan>/BACKLOG.md` / `$MAIN_WT/.project/rules/TASKERY_RULE.md`
 - **agent teams (자연어)**: 팀원 생성 + 태스크별 지시 + 모니터링. (전용 슬래시 명령은 없음 — 리더가 자연어로 팀을 가동)
 - **AskUserQuestion**: 태스크 묶음 / 팀원 수 / 중단점 모드 확인
 

package/template/.codex/agents/task-tester.toml

@@ -1,7 +1,7 @@
 # taskery 격리 검증 서브에이전트 — /task-test가 spawn하는 독립 tester
 #
 # 클로드의 "Task tool 격리 세션"에 대응하는 코덱스 서브에이전트 정의.
-# 메인 세션의 plan/dev 컨텍스트(확증편향) 없이 task.md + TEST-GUIDE.md를 보고 독립 검증한다.
+# 메인 세션의 plan/dev 컨텍스트(확증편향) 없이 task.md + TEST_RULE.local.md를 보고 독립 검증한다.
 #
 # ⚠ 미러 — 아래 developer_instructions는 `.agents/skills/task-test/SKILL.md`의 격리 펜스(수행 룰)와
 #   *같은 효과*를 내야 한다. /task-test는 그 펜스 전체를 spawn prompt(task)로 전달하므로 펜스가 단일 룰
@@ -10,26 +10,32 @@
 #
 # ⚠ model 명시 필수 — 생략하면 자식 모델 resolve가 service tier validation에서 실패한다.
 #   환경의 사용 가능 모델에 맞게 조정한다(기본 gpt-5.5).
+#
+# ⚠ sandbox_mode = workspace-write — 음성 대조(펜스 룰 19: 구현 일시 되돌림 → FAIL 확인 → 즉시 원복)가
+#   쓰기를 요구해 read-only에서 workspace-write로 전환. 코드 수정 금지 원칙(룰 8)은 유지되며 룰 19가
+#   유일 예외(원복 의무 + 메인 측 전후 스냅샷 대조가 안전망).
 
 name = "task-tester"
-description = "격리 검증 에이전트. 메인의 확증편향 없이 task.md + TEST-GUIDE를 보고 Test Plan을 증거 기반으로 독립 수행한다. /task-test가 spawn한다."
+description = "격리 검증 에이전트. 메인의 확증편향 없이 task.md + TEST_RULE.local.md를 보고 Test Plan을 증거 기반으로 독립 수행한다. /task-test가 spawn한다."
 model = "gpt-5.5"
-sandbox_mode = "read-only"
+sandbox_mode = "workspace-write"
 developer_instructions = """
 너는 격리된 tester다. 메인 세션의 가정(plan/dev 컨텍스트, "잘 될 거야")을 일체 신뢰하지 말고, 넘겨받은 검사 지시(spawn prompt)와 문서만 보고 자기완결적으로 검증하라.
 
 검사 룰의 단일 소스 = spawn 시 넘겨받은 검사 지시(prompt)다. 그것을 그대로 따르며, 아래는 그 핵심을 코덱스에서 동일하게 보장하는 기준선이다(넘겨받은 지시와 충돌 시 넘겨받은 지시 우선):
 
-- 넘겨받은 task.md와 TEST-GUIDE.md를 직접 읽는다(task.md가 목업을 참조하면 목업도). "task.md 하나만"이 아니다 — TEST-GUIDE는 각 검증 방식을 *이 프로젝트에서 실제로 어떻게 실행하나*(DB 조회 경로 / API 호출법 / E2E 셋업 / 시각 실행)의 단일 소스다.
+- 넘겨받은 task.md와 TEST_RULE.local.md를 직접 읽는다(task.md가 목업을 참조하면 목업도, 시험지 원본 경로가 주어졌으면 그것도). "task.md 하나만"이 아니다 — TEST_RULE.local.md는 각 검증 방식을 *이 프로젝트에서 실제로 어떻게 실행하나*(DB 조회 경로 / API 호출법 / E2E 셋업 / 시각 실행)의 단일 소스다.
 - task.md의 ## Test Plan 시나리오를 순서대로 그대로 수행한다(임의 추가/스킵/변형 금지).
-- 문 앞 검사(먼저) — 각 [AUTO] 시나리오가 [실행 명령/입력 + 구체적·관측 가능한 기대값(출력값/상태코드/어서션/조회 결과/화면 상태)] 한 쌍을 갖췄는지 확인한다. "정상 동작/잘 됨/확인한다" 같은 소원은 기대값이 아니다. 미달인 [AUTO]는 검사하지 말고 "시험문제 결함(검증 불가)"으로 분류 + 무엇이 빠졌는지 지목한다(PASS 반올림 금지).
+- 문 앞 검사(먼저) — 각 [AUTO] 시나리오가 [실행 명령/입력 + 구체적·관측 가능한 기대값(출력값/상태코드/어서션/조회 결과/화면 상태)] 한 쌍을 갖췄는지 확인한다. "정상 동작/잘 됨/확인한다" 같은 소원은 기대값이 아니다. UX/UI task의 [AUTO] 기대값은 출처 표기("(출처: 목업 §N / Req N)")도 자격 요건 — 무표기·"(출처 없음 — 사용자 확인 필요)" 잔존은 자격 미달. 미달인 [AUTO]는 검사하지 말고 "시험문제 결함(검증 불가)"으로 분류 + 무엇이 빠졌는지 지목한다(PASS 반올림 금지).
+- 시험지 오염 대조(시험지 원본 경로가 주어졌을 때, 먼저) — 원본을 Read해 task.md ## Test Plan과 칸 단위 대조. 무플래그 차이 = 무조건 오염 즉시 반려. 플래그 칸은 종류별 검증 — 【A수정】은 방식 칸만 허용(원안 문자열이 원본과 일치해야 하며 시나리오·PASS 기준의 A수정 = 오염), 【사용자결정】·【보수】는 허용 경로(원안 표기 일치만 확인). 방식 교체를 빙자해 기대값·시나리오 의미가 함께 바뀌었으면 오염. 오염 = UNCERTAIN(검증 불가) + "시험지 오염" 라벨로 리턴(어느 칸이 어떻게 다른지 명시).
+- 음성 대조(핵심 시나리오 최소 1개 — 코드 수정 금지의 유일 예외) — 구현 코드를 일시 되돌린 상태에서 그 시나리오가 실제로 FAIL함을 확인한 후 즉시 원복하고 통과 근거에 포함한다(git 명령 금지, 종료 시 되돌림 흔적 0 의무 — 원복 후 스스로 diff 확인). 되돌리기가 위험한 영역이면 생략 + 사유 기록.
 - 증거 일치 시만 PASS — 자격 갖춘 [AUTO]는 실제로 실행해 *관측 결과가 기대값과 일치할 때만* PASS. 코드 정독 "그럴듯함"·추정으로 PASS 금지. 증거(명령 출력/응답 로그/캡처/조회 결과)를 첨부한다.
-- [AUTO]/[USER] 분류 — [USER]는 정답지가 *주관*인 것만(시각 미세 취향 / 색조·2px / UX 느낌) → UNCERTAIN(사람 검수) + 증거 캡처로 리턴. 시각 *객관* 깨짐(요소 빠짐/빈 화면/배치 딴판/색 완전히 틀림)은 [USER]가 아니라 [AUTO] — 실제 화면 캡처 → 승인 목업과 대조해 네가 직접 판정한다(어긋나면 *구체적 어긋남 목록* + FAIL). 시각이라고 무조건 사람에게 넘기지 마라. 단 시각 객관의 [AUTO] 승격은 TEST-GUIDE의 *시각 실행* 절에 캡처 실행 경로가 있을 때 한정이다 — 경로가 없어 task.md가 [USER]로 분류했으면 그 분류를 존중한다.
+- [AUTO]/[USER] 분류 — [USER]는 정답지가 *주관*인 것만(시각 미세 취향 / 색조·2px / UX 느낌) → UNCERTAIN(사람 검수) + 증거 캡처로 리턴. 시각 *객관* 깨짐(요소 빠짐/빈 화면/배치 딴판/색 완전히 틀림)은 [USER]가 아니라 [AUTO] — 실제 화면 캡처 → 승인 목업과 대조해 네가 직접 판정한다(어긋나면 *구체적 어긋남 목록* + FAIL). 시각이라고 무조건 사람에게 넘기지 마라. 단 시각 객관의 [AUTO] 승격은 TEST_RULE.local.md의 *시각 실행* 절에 캡처 실행 경로가 있을 때 한정이다 — 경로가 없어 task.md가 [USER]로 분류했으면 그 분류를 존중한다.
 - UNCERTAIN 세 종류 — (사람 검수)=정답지가 주관인 영역 / (검증 불가)=[AUTO]인데 대조할 기대값을 구성 못 함=시험문제 결함 / (실행 보류)=화면·입력 점유 제약으로 실행하지 않음=환경 제약(사용자 승인 또는 격리 실행 경로 필요. 무엇을 왜 실행하지 않았는지 기록해 리턴). 검증 불가는 PASS로 반올림하거나 사람 검수로 떠넘기지 말고, *무엇을 시도했고 왜 기대값을 구성할 수 없는지* 근거를 반드시 기록한다(task-plan으로 Test Plan을 보수해야 하는 신호).
 - 신규 테스트 추가 시 카운트 +N / 모든 PASS만으로 단정 X — 신규 *테스트 식별자*(suite/class/function 등)가 runner 로그에 실제 등장했는지 grep으로 확인한다(1 hit 이상, 없으면 Suite 미실행 → FAIL). grep/Read 존재 확인은 보조용 — 실동작 PASS를 대체할 수 없다.
 - 픽스처 현실성 — 픽스처·시드가 실제 산출물과 형식·정밀도가 같은지 의심하고, 의심되면 실제 코드(writer·생성기)로 재생성해 재실행한 결과로 판정한다. 재생성 경로가 없어 대조를 구성할 수 없으면 시험문제 결함(검증 불가)으로 분류한다.
 - 어서션 정면성 — 기대값이 요구사항을 정면으로 겨누는지 확인한다("벗어날 수 없다"면 실제로 벗어나 볼 것. 버튼 disabled 확인은 우회 지표다). 우회 지표로 검사하는 [AUTO] 시나리오는 시험문제 결함으로 분류하고 무엇이 정면 관측인지 지목한다.
-- 화면·입력 점유 금지 — 실제 앱을 띄워 UI를 자동 조작하는 스위트는 사용자의 화면·입력을 점유한다. TEST-GUIDE의 *테스트 실행 환경* 절에 격리 실행 경로(창 숨김·헤드리스 / 컨테이너 / VM / CI)가 있으면 그 경로로 실행하고, 없으면 비점유 부분만 실행하거나 실행 보류(사용자 승인 필요)로 표시해 리턴한다. 헤드리스 모드가 있으면 항상 그쪽을 쓴다.
-- 코드와 동작만 신뢰한다. 코드 파일 수정 금지. 임시 파일(테스트 스크립트 등)은 종료 후 삭제한다.
+- 화면·입력 점유 금지 — 실제 앱을 띄워 UI를 자동 조작하는 스위트는 사용자의 화면·입력을 점유한다. TEST_RULE.local.md의 *테스트 실행 환경* 절에 격리 실행 경로(창 숨김·헤드리스 / 컨테이너 / VM / CI)가 있으면 그 경로로 실행하고, 없으면 비점유 부분만 실행하거나 실행 보류(사용자 승인 필요)로 표시해 리턴한다. 헤드리스 모드가 있으면 항상 그쪽을 쓴다.
+- 코드와 동작만 신뢰한다. 코드 파일 수정 금지(유일 예외 = 위 음성 대조의 일시 되돌림 — 즉시 원복). 임시 파일(테스트 스크립트 등)은 종료 후 삭제한다.
 - 검증을 마치면 넘겨받은 검사 지시의 결과 형식(종합 판정 PASS/FAIL/UNCERTAIN / 시나리오별 결과 / 검증·테스트 명령 결과 / UNCERTAIN 3종 / 시험문제 결함 / 실행 보류)을 그대로 리턴한다.
 """

package/template/.codex/agents/test-plan-author.toml

@@ -0,0 +1,34 @@
+# taskery 출제 분리 서브에이전트 — /task-plan Step 5-B가 spawn하는 독립 Test Plan 출제자(B)
+#
+# 클로드의 "서브에이전트 격리 호출"에 대응하는 코덱스 서브에이전트 정의.
+# 구현자(A=메인)가 출제를 겸하면 같은 오독이 문제지와 답안지에 함께 들어가므로,
+# B는 Requirements 합의문 + 승인 목업 + TEST_RULE.local.md만 보고 출제한다 (Dev Plan·코드 접근 없음).
+#
+# ⚠ 미러 — 아래 developer_instructions는 `.agents/skills/task-plan/SKILL.md` Step 5-B의 B prompt 펜스와
+#   *같은 효과*를 내야 한다. /task-plan은 그 펜스 전체를 spawn prompt(task)로 전달하므로 펜스가 단일 룰
+#   소스이며, 이 지침은 코덱스에서 동일 효과를 보장하는 기준선이다. 펜스의 룰이 바뀌면 이 지침도 함께 갱신한다.
+#   (클로드 = 서브에이전트 격리 호출 + 펜스 / 코덱스 = 본 에이전트 + 펜스 — 양쪽 동일 효과)
+#
+# ⚠ model 명시 필수 — 생략하면 자식 모델 resolve가 service tier validation에서 실패한다.
+#   환경의 사용 가능 모델에 맞게 조정한다(기본 gpt-5.5).
+
+name = "test-plan-author"
+description = "출제 분리 에이전트(B). Requirements 합의문 + 승인 목업 + TEST_RULE.local.md만 보고 Test Plan을 출제한다 — 구현 계획·코드 접근 없음. /task-plan Step 5-B가 spawn한다."
+model = "gpt-5.5"
+sandbox_mode = "read-only"
+developer_instructions = """
+너는 격리된 Test Plan 출제자(B)다. 구현 계획·코드에 대한 어떤 가정도 없이, spawn prompt에 명시된 자료만 보고 검증 시나리오를 출제하라.
+
+출제 룰의 단일 소스 = spawn 시 넘겨받은 출제 지시(prompt)다. 그것을 그대로 따르며, 아래는 그 핵심을 코덱스에서 동일하게 보장하는 기준선이다(넘겨받은 지시와 충돌 시 넘겨받은 지시 우선):
+
+- 입력은 prompt에 인라인된 Requirements 합의문 + (있을 때만) 승인 목업 경로 + 검증 규칙(TEST_RULE.local.md) 경로뿐이다. task 문서·코드·기타 문서를 열지 않는다. Requirements에 적힌 것만 검증 대상 — 적히지 않은 요구를 추정해 시나리오를 만들지 않는다.
+- 검증 규칙 파일이 주어졌으면 반드시 Read — ① 방식별 실행 경로 ② 테스트 실행 환경(점유 스위트 격리 경로·사용자 결정 기록) ③ 범위·방식 정책.
+- 시나리오 형식 = [실제 실행할 명령/입력] + [구체적·관측 가능한 기대값] 한 쌍 강제. "정상 동작/잘 됨" 같은 소원 금지. 장면 쪼개기 — 진짜 떨어질 장면 여러 개로 분해.
+- 방식 선택은 기계적으로 — 화면 신규·변경=시각(캡처-목업 대조) / 상호작용=UI 동작 / 엔드포인트=API 호출 / 데이터 변경=사이드 이펙트 조회 / 순수 계산=입출력 비교 / 기존 영역=회귀. 여러 개 걸리면 다 붙인다.
+- 방식 칸은 검증 규칙의 "방식별 실행 경로" 절에 등재된 경로로 채운다. 등재 경로가 없으면 그 칸에 "등재 경로 없음 — 메인 확인 필요"라고 적는다(실행 경로를 지어내지 않는다).
+- 어서션 정면성 — 기대값이 요구사항 자체를 관측해야 한다. "벗어날 수 없다"면 실제로 벗어나 보는 것이 정면, disabled 확인 같은 우회 지표는 PASS 기준이 될 수 없다.
+- 기대값 출처 표기 — UX/UI 요구의 모든 [AUTO] PASS 기준 끝에 출처를 단다: "(출처: 목업 §N / Req N)". 달 수 없으면 "(출처 없음 — 사용자 확인 필요)"로 표기한다(추정 은폐 금지).
+- 화면·입력 점유 스위트는 검증 규칙 "테스트 실행 환경" 절의 현재 기록 기준으로 분류한다 — 격리 경로 선언 있음=[AUTO] / "없음 — 매번 승인" 기록 또는 무기록=시나리오에 "사용자 승인 후 실행" 표기(사용자 질문은 메인 몫).
+- grep/Read-only 존재 확인 시나리오는 보조용 — 단독 PASS 가치 없음. Requirements 각 항목당 end-to-end 실동작 시나리오 최소 1개.
+- 출력은 넘겨받은 출제 지시의 출력 형식 그대로 — ## Test Plan 표(시나리오/분류/방식/PASS 기준) + Requirements ↔ Test Plan 매트릭스. 코드·문서 수정 금지 — 출제만 하고 리턴한다.
+"""

package/template/.project/rules/CHANGELOG_RULE.md

@@ -2,7 +2,7 @@
 
 > 본 파일은 taskery 시스템 권장 프로젝트별 CHANGELOG 정책이다.
 > 우선순위: **이 파일** (`.project/rules/CHANGELOG_RULE.md`) → 메인 판단.
-> 프로젝트별 변형이 필요하면 `.project/rules/CHANGELOG_RULE.local.md` 생성 (npx update 미터치).
+> 프로젝트별 변형이 필요하면 `.project/rules/CHANGELOG_RULE.local.md` 생성 (npx update 미터치, 구속력은 코어와 동등 — `TASKERY_RULE` §7).
 
 ---
 
@@ -16,27 +16,30 @@
 
 ## 2. 항목 형식
 
-각 task close 시 새 항목 1개 추가:
+**작성 주체 = close CLI 자동.** 각 task close 시 `npx @angar2/taskery close`가 새 항목 1개를 직접 append한다 (헤더=task 문서 H1 제목 / 날짜 / 타입=헤더 유형 / 변경 요약=Dev Plan Phase 명 목록):
 
 ```markdown
-## [TASK-NNN] <한 줄 요약>
+## [TASK-NNN] <제목 — task 문서 H1>
 
 - **날짜**: YYYY-MM-DD
 - **타입**: feature / bug / improvement / refactor / docs / chore
-- **변경 요약**: <2-3 줄>
-- **영향 파일**: <주요 파일 경로 리스트>
-- **사유**: <변경 이유 한 줄>
+- **변경 요약**:
+  - Phase 1 — <Phase 명>
+  - Phase 2 — <Phase 명>
 ```
 
-### 필수 필드
+### 필수 필드 (CLI 자동 작성분)
 
-1. 헤더 `## [TASK-NNN] <한 줄 요약>` (한 줄)
+1. 헤더 `## [TASK-NNN] <제목>` (한 줄)
 2. **날짜** (`YYYY-MM-DD`)
-3. **타입** (커밋 태그와 동일 — `feat` / `fix` / `improve` / `refactor` / `docs` / `chore`)
-4. **변경 요약** (2-3 줄)
+3. **타입** (task 헤더 유형 — `feature` / `bug` / `improvement` / `refactor` / `docs` / `chore`)
+4. **변경 요약** (Phase 명 목록 — Phase 부재 시 제목 1줄)
 
-### 선택 필드
+### 보강 (선택 — 세션·사용자 자유 편집)
 
+CLI 자동 작성분이 기본이고, 세션·사용자가 항목을 자유롭게 보강할 수 있다 (closed 잠금은 task 문서만 — changelog는 잠금 밖):
+
+- 변경 요약 문장 보강
 - 영향 파일 (참고용)
 - 사유 (참고용)
 - 관련 PR / 이슈 링크 (있을 시)
@@ -53,23 +56,24 @@
 
 ## 4. task-close 흐름과의 정합
 
-`/task-close` Step 4-4 (CHANGELOG 커밋) 단계에서 본 RULE 참조:
+**close CLI가 append한다 — 세션 수기 작성 불요, 보강만.**
 
-1. 본 RULE 정독
-2. 신규 항목 형식대로 작성
-3. *최신 위치 (맨 위)* 에 삽입
-4. 커밋 — 메시지 형식: `docs: [TASK-NNN] CHANGELOG 업데이트`
+1. `npx @angar2/taskery close`(또는 `task_close` 도구)가 §2 형식으로 항목을 자동 append — 파일 없으면 생성(§1 두 형식 중 단일 `CHANGELOG.md` 실재 시 그쪽, 아니면 이번 달 `<YYYY-MM>.md`), 최신 위치(맨 위) 삽입, `[TASK-NNN]` 중복 가드(재호출 시 skip)
+2. 세션은 필요 시 append된 항목을 보강(§2 보강)
+3. 커밋: 미등록 케이스는 close의 문서 커밋이 자동 수거 / 등록 케이스는 `.project/`가 git 밖이라 커밋 불요
 
 ---
 
 ## 5. 예시
 
 ```markdown
-## [TASK-042] 사용자 인증 OAuth 2.0 지원 추가
+## [TASK-042] 사용자 인증 OAuth 2.0 지원
 
 - **날짜**: 2026-06-15
 - **타입**: feature
-- **변경 요약**: Google / GitHub OAuth provider 추가. 기존 이메일·비밀번호 흐름 유지.
+- **변경 요약**:
+  - Phase 1 — OAuth provider 연동 (Google / GitHub)
+  - Phase 2 — 인증 라우트 배선
 - **영향 파일**: `src/auth/oauth.ts`, `src/routes/auth.ts`, `migrations/0042_oauth.sql`
 - **사유**: 외부 서비스 연동 요구 누적 — 인증 흐름 다변화
 
@@ -77,11 +81,12 @@
 
 - **날짜**: 2026-06-12
 - **타입**: bug
-- **변경 요약**: 이메일 형식 검증 누락으로 빈 입력 통과되던 버그 fix.
-- **영향 파일**: `src/components/LoginForm.tsx`
-- **사유**: TASK-038 신고 — 빈 이메일로 로그인 시도 시 서버 오류
+- **변경 요약**:
+  - Phase 1 — 이메일 형식 검증 보강
 ```
 
+(TASK-042 = CLI 자동 작성분에 영향 파일·사유를 보강한 예 / TASK-041 = CLI 자동 작성분 그대로.)
+
 ---
 
 ## 6. 수정 이력
@@ -89,3 +94,4 @@
 | 날짜 | 변경 사항 |
 |------|----------|
 | 2026-05-30 | 신규 작성 — 위치 / 형식 / 필수 필드 / task-close 정합 (stash FRICTION_LOG #8+9 반영) |
+| 2026-08-09 | 작성 주체를 close CLI 자동으로 개정 — §2 항목 형식(변경 요약=Phase 명 목록)·필수/보강 재편, §4 흐름 개정(수기 작성 불요·보강만·중복 가드). recordion FRICTION 2026-08-09(문서 갱신 세션 준수 의존) 반영 |

package/template/.project/rules/GIT_RULE.md

@@ -2,7 +2,7 @@
 
 > 이 파일은 taskery 시스템 권장 프로젝트별 git 정책이다.
 > 우선순위: **이 파일** (`.project/rules/GIT_RULE.md`) → 글로벌 (`~/.claude/rules/GIT_RULE.md`) → 메인 판단.
-> 프로젝트별 변형이 필요하면 `.project/rules/GIT_RULE.local.md` 생성 (npx update 미터치).
+> 프로젝트별 변형이 필요하면 `.project/rules/GIT_RULE.local.md` 생성 (npx update 미터치, 구속력은 코어와 동등 — `TASKERY_RULE` §7).
 
 ---
 
@@ -124,6 +124,7 @@ feat: [TASK-001] Phase 1 - 사용자 인증 로직 구현
 - **Dev Plan에 없는 빌드 산출물**(`*.pbxproj` / `package-lock.json` 등 잠금파일 계열) **→ 마지막 Phase 커밋에 자동 편입** + `(빌드 산출물 자동 편입)` 표기. 산출물은 소스에 딸려 바뀌는 파생물이라 Phase 소속을 물을 대상이 아니다.
 - **Dev Plan에 없는 일반 파일 → 자동 편입 없이 중단(blocked)** — 계획에 없던 작업일 수 있어 사람 판단으로 남긴다.
 - **중간 커밋의 독립 빌드 가능성은 보장 대상이 아니다** — 다중 Phase 편입 시 어느 배치로도 중간 커밋 빌드는 성립하지 않을 수 있다(최종 트리 정상이면 충분). 이를 이유로 매핑을 수동 재배치하지 않는다.
+- **`- 파일:` 다중 파일 표기 규격** — 권장 = `- 파일:` 다음 줄부터 들여쓴 목록(`  - <경로>`), 허용 = 쉼표·가운뎃점(`·`) 구분 한 줄. `(신규)`류 꼬리 괄호 주석은 파서가 제거한다. **규격 밖 표기는 파서가 못 읽어 `blocked:'mapping'`으로 멈춘다.**
 
 ### 태스크 문서 커밋 메시지
 
@@ -233,7 +234,7 @@ docs: [TASK-{NNN}] CHANGELOG 업데이트
 
 ### 메인 워크트리 절대 경로 검출
 
-워크트리 안에서 메인 워크트리 메타(`.project/`, `CLAUDE.md`)에 접근할 때 사용:
+워크트리 안에서 메인 워크트리 메타(`.project/`, `AGENTS.md`)에 접근할 때 사용:
 
 ```sh
 MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
@@ -262,12 +263,12 @@ git -C "$MAIN_WT" branch --list \
 
 여러 세션이 병렬로 검수용 dev 서버·터널을 띄울 때 포트·프로세스가 충돌하지 않도록 task별로 자원을 독립 소유한다. CLI·라이브러리 등 검수 서버가 없는 프로젝트는 무관.
 
-- **포트 격리 (결정적)**: 메인 세션(부모 브랜치) = 기준 포트, task 워크트리 = 기준 포트 + TASK번호. 기준 포트는 프로젝트가 `CLAUDE.md`(코덱스는 `AGENTS.md`) `## 검수 실행 명령`에 선언한다 (멀티 프로젝트 동시 운영 시 프로젝트마다 다른 기준 포트). TASK번호는 1부터라 offset 0(기준 포트)이 메인 몫으로 항상 비어 충돌하지 않는다.
+- **포트 격리 (결정적)**: 메인 세션(부모 브랜치) = 기준 포트, task 워크트리 = 기준 포트 + TASK번호. 기준 포트는 프로젝트가 `AGENTS.md` `## 검수 실행 명령`에 선언한다 (멀티 프로젝트 동시 운영 시 프로젝트마다 다른 기준 포트). TASK번호는 1부터라 offset 0(기준 포트)이 메인 몫으로 항상 비어 충돌하지 않는다.
 - **터널 (필수 아님)**: 모바일 검수 등 필요한 task만, 자기 포트를 가리키는 별도 프로세스로 판다 → task별 독립 URL.
 - **자기 것만 정리**: `/task-close` 시 본 task가 띄운 서버·터널(자기 포트 것)만 종료한다. **`pkill -f` 같은 광역 종료 금지** — 다른 세션의 서버까지 죽이는 원인.
 - **검수 기동 (자동)**: 사용자가 결과를 *눈으로 검수*하는 시점에 위 포트로 서버를 백그라운드 기동하고 접속 URL을 보고한다 (사용자가 매번 실행을 지시하지 않게). 정확한 발동 지점은 각 스킬 참조 — `/task-dev`는 세션이 거기서 끝날 때(Step 9), `/task-test`는 UNCERTAIN 검수 직전(Step 5)·PASS 후 종료 시(Step 7). FAIL→수정 흐름에서는 기동하지 않는다. 단계가 *기능상* 서버를 요구하면(E2E 등) 검수 시점과 무관하게 띄운다.
 - **중복 기동 방지**: 새로 띄우기 전에 해당 포트·프로세스가 이미 살아 있는지 확인한다. `Port … is in use` 류 경고는 *이미 떠 있다*는 신호이므로 무시하고 재기동하지 않는다. 종료 시에는 부모 프로세스만이 아니라 자식 프로세스(브라우저·렌더러 창 등)까지 확인해 정리한다.
-- **화면·입력 점유 회피**: 실제 앱을 띄워 UI를 자동 조작하는 테스트 스위트는 사용자의 화면·마우스·키보드를 점유해 작업을 중단시킨다. 자동 게이트·격리 세션은 `.project/TEST-GUIDE.md` *테스트 실행 환경* 절에 선언된 격리 실행 경로(창 숨김·헤드리스 / 컨테이너 / VM / CI)로만 자동 실행하고, 선언이 없으면 비점유 부분만 실행하거나 사용자 승인을 받는다.
+- **화면·입력 점유 회피**: 실제 앱을 띄워 UI를 자동 조작하는 테스트 스위트는 사용자의 화면·마우스·키보드를 점유해 작업을 중단시킨다. 자동 게이트·격리 세션은 `.project/rules/TEST_RULE.local.md` *테스트 실행 환경* 절에 선언된 격리 실행 경로(창 숨김·헤드리스 / 컨테이너 / VM / CI)로만 자동 실행하고, 선언이 없으면 비점유 부분만 실행하거나 사용자 승인을 받는다.
 - **효과 (정직)**: 포트 충돌은 결정적으로 제거된다. 다른 세션의 종료·턴 경계 프로세스 소실은 위 규율·백그라운드 실행으로 완화되나 문서 규율이라 강제는 아니다(best-effort).
 
 ---
@@ -320,3 +321,5 @@ git -C "$MAIN_WT" branch --list \
 | 2026-06-25 | §멀티세션 워크트리 정책에 "멀티세션 검수 환경" 추가 — task별 dev 서버 포트 격리(메인=기준 포트, task=기준+TASK번호) + 터널 독립 + close 시 자기 것만 종료(광역 종료 금지) + 사용자 검수 시점 서버 자동 기동(task-test UNCERTAIN/PASS·task-dev 종료, FAIL 제외). FRICTION 검토 F7 반영 |
 | 2026-08-08 | 출처 표기 개편 — `RM-NNN`(로드맵 항목 채번, 미구현) → `ST-N`(ROADMAP Stage 번호 그대로, 채번 불요·동일 출처 중복 게이트 미적용). 구형 RM-NNN은 호환 수용만. + §커밋 순서에 "Phase↔파일 매핑 규칙" 신설 — 다중 Phase 파일=이른 Phase 편입+표기 / 빌드 산출물=마지막 Phase 자동 편입 / 일반 미매핑만 blocked / 중간 커밋 독립 빌드 비보장 명문화. stash·recordion FRICTION_LOG 반영 |
 | 2026-08-08 | §멀티세션 검수 환경에 "중복 기동 방지"·"화면·입력 점유 회피" 2항 추가 — 검수 앱 중복 기동(부모만 종료해 창 잔존) 및 UI 자동조작 스위트의 화면·입력 강탈 마찰 반영. stash·recordion FRICTION_LOG |
+| 2026-08-08 | 0.7.0 문서 체계 재편 정합 — 진입 문서 단일화(`AGENTS.md` 본문 + `CLAUDE.md`는 임포트 한 줄)에 따라 검증 명령 참조 경로 변경, 폐지된 `TEST-GUIDE.md` 참조를 `TEST_RULE.local.md`로 교체. 머리말에 `.local.md` 구속력 안내 추가(코어와 동등 — `TASKERY_RULE` §7) |
+| 2026-08-09 | §Phase↔파일 매핑 규칙에 `- 파일:` 다중 파일 표기 규격 추가 — 권장=들여쓴 목록 / 허용=쉼표·가운뎃점 한 줄 / 꼬리 괄호 주석 파서 제거 / 규격 밖=blocked 명문화. recordion FRICTION 2026-08-09(TASK-010 — 가운뎃점 표기가 줄 전체 경로 하나로 파싱) 반영 |

package/template/.project/rules/MOCKUP_RULE.md

@@ -2,7 +2,7 @@
 
 > 본 파일은 taskery 시스템 권장 UX/UI 구현 task의 HTML 목업 정책이다.
 > 우선순위: **이 파일** (`.project/rules/MOCKUP_RULE.md`) → 메인 판단.
-> 프로젝트별 변형이 필요하면 `.project/rules/MOCKUP_RULE.local.md` 생성 (npx update 미터치).
+> 프로젝트별 변형이 필요하면 `.project/rules/MOCKUP_RULE.local.md` 생성 (npx update 미터치, 구속력은 코어와 동등 — `TASKERY_RULE` §7).
 
 ---
 

package/template/.project/rules/TASKERY_RULE.md

@@ -0,0 +1,237 @@
+# TASKERY_RULE — taskery 사용 설명서
+
+> 본 문서는 taskery의 **전체 사용법 단일 소스**다. 세션은 본 문서를 필독한 후 작업한다.
+> 본 문서는 taskery 패키지가 관리한다 — `npx @angar2/taskery update`로 갱신되므로 직접 수정하지 않는다.
+> 리포 특성 커스텀은 `TASKERY_RULE.local.md`(본 문서 짝)로 한다.
+> **경계**: 본 문서는 *전체 그림과 체계*까지만 담는다. 각 단계의 상세 수행 절차는 해당 스킬(`SKILL.md`)이, git 정책 상세는 `GIT_RULE`이, task 문서 양식은 `TASK_DOC_RULE`이 담당한다 — 여기에 상세 절차를 옮겨 적지 않는다.
+
+---
+
+## 1. taskery란
+
+taskery는 **task 단위 라이프사이클 관리 시스템**이다. 하나의 작업을 task로 세우고, 그 task의 문서·상태·git 브랜치·검증을 정해진 순서로 진행시킨다. 각 단계는 **스킬**(에이전트가 호출하는 절차서)이 주도하고, 결정적인 부분(채번·상태 전이·분기·커밋 준비)은 **CLI/도구**가 코드로 수행한다.
+
+목적은 두 가지다. 하나는 작업 이력이 문서와 git 양쪽에 일관된 형태로 남게 하는 것, 다른 하나는 여러 세션이 같은 리포에서 동시에 일해도 서로를 망가뜨리지 않게 하는 것이다.
+
+---
+
+## 2. task 라이프사이클
+
+### 7상태
+
+```
+draft → planned → developing → developed → testing → tested → closed
+```
+
+| 상태 | 의미 |
+|------|------|
+| `draft` | task 문서 골격만 생성된 상태 |
+| `planned` | 요구사항·범위·구현 계획·검증 계획 확정 |
+| `developing` | 구현 진행 중 |
+| `developed` | 구현 완료 + 자체 점검(린트·타입·빌드) 통과 |
+| `testing` | 격리 검증 진행 중 |
+| `tested` | 격리 검증 통과 |
+| `closed` | git 마무리 완료 |
+
+상태 전이는 **코드가 유효성을 검증**한다(`set_status` 도구 / `npx @angar2/taskery set-status`). 문서를 직접 편집해 상태를 바꾸지 않는다. 유효 전이표와 FAIL·UNCERTAIN 분기의 상세는 `TASK_DOC_RULE` §1.2에 있다.
+
+### 어느 상황에 어느 스킬을 호출하나
+
+| 상황 | 스킬 |
+|------|------|
+| 새 작업을 시작한다 | `/task-init` |
+| 무엇을 어떻게 만들지 정한다 | `/task-plan` |
+| 구현한다 | `/task-dev` |
+| 검증한다 | `/task-test` |
+| 마무리하고 부모 브랜치에 합친다 | `/task-close` |
+| 프로젝트를 처음 세운다 | `/project-init` (1회성) |
+| 기능 그룹을 새로 연다 | `/plan-init` |
+| 나중에 할 일을 적어 둔다 | `/add-backlog` |
+| 작업 중 겪은 불편을 남긴다 | `/log-friction` |
+
+**사용자가 명시한 범위만 수행한다.** 예를 들어 `/task-dev`까지 지시받았으면 `developed`에서 정지하고 보고한다. 다음 단계로 스스로 진입하지 않는다.
+
+---
+
+## 3. plan · task · 백로그의 관계
+
+- **plan** = 기능 그룹 단위. `.project/plans/<NNN_slug>/`에 `PLAN.md`(인덱스)와 `ROADMAP.md`(Stage 계획)를 둔다.
+- **task** = 실제 작업 단위. `.project/tasks/<NNN_slug>/`에 task 문서가 쌓인다.
+- **백로그** = 아직 task로 옮기지 않은 후보. `.project/tasks/<NNN_slug>/BACKLOG.md`에 `BL-NNN`으로 누적한다.
+
+**활성 plan**은 `.taskery-manifest.json`의 `activePlan` 필드가 단일 진실이다. 문서에 활성 plan을 자기선언하는 줄을 만들지 않는다. 확인은 `status` 도구, 전환은 `npx @angar2/taskery plan-switch <NNN_slug>`로 한다.
+
+**백로그 체크박스의 의미**:
+- `[ ]` = 미확인(task로 옮기지 않은 메모) / `[x]` = task로 옮김.
+- `[x]`는 *task로 옮겼다*는 메모일 뿐 완료·머지 여부와 무관하다. **`[x]` 항목이 실제로 끝났는지 굳이 확인하려 들지 않는다.**
+- 완료 여부를 반드시 알아야 하면 순서를 지킨다. ① `taskery status` 진행중 목록에 있으면 아직 진행 중이므로 `git log`가 비는 것이 정상이다(재조회하지 않는다). ② 목록에 없으면 `git log --all --grep 'BL-NNN'`으로 확인한다.
+
+백로그 조작은 **손편집하지 않는다** — `backlog_add` / `backlog_get` / `backlog_mark` 도구가 채번·서식·직렬화를 보장한다. 파일 위치는 등록/미등록과 무관하게 항상 메인 워크트리다.
+
+`.project/BACKLOG.md`(글로벌)는 *다음 기능 그룹* 후보 카탈로그로 성격이 다르며 `/plan-init` 영역이다.
+
+---
+
+## 4. 스킬
+
+| 스킬 | 레벨 | 하는 일 |
+|------|------|--------|
+| `/project-init` | project | `AGENTS.md` 리포 값 기입 + `.project/` 진입·제품 관통 문서 + 리포 로컬 룰 초안 생성 (1회성) |
+| `/plan-init` | plan | plan 폴더·PLAN·ROADMAP 생성 + FEATURES/UX-UI에 의도 추가 |
+| `/task-init` | task | 채번 + 워크트리·브랜치 분기 + task 문서 골격 (→ `draft`) |
+| `/task-plan` | task | Requirements / Scope / Dev Plan / Test Plan 작성 (→ `planned`). 해석 여지 태스크는 Test Plan을 격리 서브에이전트 B가 출제(출제 분리 — 구현자 겸 출제의 오독 동조 차단, 원문 origin 보존) |
+| `/task-dev` | task | Phase 순서 구현 + 자체 점검 (→ `developed`) |
+| `/task-test` | task | 서브에이전트 격리 검증 (→ `tested`). 출제 분리 태스크는 origin 대조로 시험지 오염 검사(무플래그 수정 즉시 반려) + 핵심 시나리오 음성 대조 |
+| `/task-close` | task | 문서 게이트(PLAN·수정이력 grep) + 커밋 + CHANGELOG 자동 append + 부모 브랜치 병합 (→ `closed`) |
+| `/add-backlog` | meta | 백로그 항목 1건 추가 (얕은 분석 + 채번) |
+| `/log-friction` | meta | 작업 흐름의 불편을 `FRICTION_LOG.md`에 한 행 기록 |
+| `/run-team` | meta · **Claude 전용** | 다건 task를 팀원 세션에 분배해 병렬 처리 |
+
+각 스킬의 수행 절차는 해당 `SKILL.md`에 있다. **스킬은 반드시 정식 호출한다** — 본문을 기억으로 대체해 진행하지 않는다(컨텍스트가 압축된 상태에서도 동일).
+
+`/run-team`은 기본 흐름이 아니다. *"백로그 한 번에 진행해"* 류의 트리거 발화가 있을 때만 발동하며, 실험 기능이라 `~/.claude/settings.json`의 `env`에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"` 설정이 선행돼야 한다. Codex에는 해당 기능이 없어 미지원이다.
+
+---
+
+## 5. 멀티세션 (워크트리)
+
+여러 메인 세션이 같은 프로젝트에서 독립 task를 병렬 진행할 수 있다. 작업 폴더는 git worktree로 격리하고, 부모 브랜치 병합은 락으로 직렬화한다.
+
+- **메인 워크트리 = 부모 브랜치 고정.** 메인 워크트리는 `/task-init` 시점에 체크아웃돼 있던 브랜치를 유지한다. taskery는 특정 이름을 고정하지 않고 *그때 서 있는 브랜치*를 부모로 삼는다.
+- **진행 중 task가 있는 동안 메인 워크트리의 HEAD를 옮기는 어떤 작업도 금지**한다(`checkout` / `switch` / `reset` / `rebase` 등). close가 부모로 되병합해야 하므로 부모에 서 있어야 한다.
+- ***"잠깐만 메인에서"* / *"테스트 한 번만 메인에서"* 류의 예외 발화도 거부**한다. 별도 워크트리에서 처리한다. 이런 발화는 규칙 충돌 신호이므로 정지 후 확인한다.
+- **세션 시작 시 자가 진단**: `git rev-parse --show-toplevel` 결과를 `~/.taskery/worktrees/` 경로와 비교해 지금이 메인 워크트리인지 task 워크트리인지 판정한다. task 워크트리면 그 task 맥락으로, 메인이면 새 task 또는 진행중 목록 흐름으로 진입한다.
+- **워크트리에서 메인 메타에 접근**할 때는 메인 워크트리 절대 경로를 쓴다:
+  ```sh
+  MAIN_WT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+  ```
+- **수동 git 작업은 정합성을 보장하지 않는다.** taskery 스킬과 `npx @angar2/taskery <서브커맨드>`로만 운영한다.
+- 보조 명령: `status`(진행중 task·워크트리·부모 머지 상태) / `prune`(오래된 워크트리 대화형 정리).
+
+git 정책의 상세(브랜치 명명·커밋 형식·병합 방식·금지 명령)는 `GIT_RULE`에 있다. 요건은 git 2.31 이상이다.
+
+---
+
+## 6. 문서 체계 지도
+
+| 구분 | 위치 | 성격 |
+|------|------|------|
+| 진입 문서 | `AGENTS.md` (+ `CLAUDE.md`는 이를 임포트) | 에이전트 최상위 지침 + 이 리포의 메타·명령 값 |
+| 코어 룰 | `.project/rules/` | taskery가 제공하며 모든 리포에 동일 |
+| 리포 로컬 룰 | `.project/rules/*.local.md` | 이 리포 고유 규칙 (§7) |
+| 제품 관통 문서 | `.project/` 루트 | SERVICE-POLICY / TECH-STACK / ARCHITECTURE / DATA-MODEL / API-SPEC / FEATURES / UX-UI |
+| plan 문서 | `.project/plans/<NNN_slug>/` | PLAN · ROADMAP |
+| task 문서 | `.project/tasks/<NNN_slug>/` | task 본문 · spec-diffs · screenshots · mockup |
+| 기계 상태 | `.taskery-manifest.json` | 활성 plan · projectId · 설치 자산 해시 — **손편집 금지** |
+
+**코어 룰 5종**:
+
+| 룰 | 관할 |
+|----|------|
+| `TASKERY_RULE` | taskery 사용법 전체 (본 문서) |
+| `TASK_DOC_RULE` | task 문서 양식 — 헤더 6컬럼 / 6섹션 / 7상태 |
+| `GIT_RULE` | git 정책 — 브랜치 · 커밋 · 병합 · 금지 명령 |
+| `CHANGELOG_RULE` | CHANGELOG 위치 · 형식 · 필수 필드 |
+| `MOCKUP_RULE` | UX/UI task의 HTML 목업 위치 · 형식 · 네이밍 |
+
+**Hook 안전망 2종** — 정상적으로 지키면 한 번도 작동하지 않는다.
+
+| Hook | 차단 대상 |
+|------|----------|
+| `git-guard.sh` | 보호 브랜치 직접 커밋 / `--force` / `--no-verify` / `branch -D` / `reset --hard` / `clean -fd` |
+| `closed-immutable.sh` | `closed` 상태 task 문서의 재수정 (spec-diffs · screenshots · mockup은 자유) |
+
+---
+
+## 7. `.local.md` 커스텀 체계
+
+코어 룰은 **항상 준수가 기본값**이다. 이 리포만의 규칙이 필요하면 해당 코어 문서의 짝을 만든다 — 파일명은 `<코어문서명>.local.md`이며 같은 `.project/rules/`에 둔다. 예: `GIT_RULE.local.md` · `TASK_DOC_RULE.local.md`.
+
+**구속력**:
+
+> 로컬 룰의 조항은 코어와 **동등한 구속력**을 가진다. 겹치는 조항은 로컬이 최우선이고, **겹치지 않는 로컬 조항도 그대로 준수한다.**
+
+**로컬이 뒤집을 수 없는 안전선** (아래는 로컬에 무엇을 적든 무효다):
+- 멀티세션 불변식 — 메인 워크트리 부모 브랜치 고정, task는 워크트리에서.
+- git 되병합·워크트리 정리는 `/task-close`만 수행.
+- destructive git 명령은 사용자 승인 필수.
+- 상태 전이 유효성 검증(코드 게이트).
+
+**갱신 안전 보장**: `*.local.md`는 taskery 패키지가 배포하는 자산이 아니므로 `npx @angar2/taskery update`가 **영구히 건드리지 않는다.** 반대로 코어 룰은 update가 갱신하므로 코어 파일을 직접 고치지 않는다 — 고쳐야 할 내용은 로컬 짝으로 옮긴다.
+
+---
+
+## 8. TEST_RULE.local.md · DEV_RULE.local.md — 모든 리포 필수
+
+이 둘은 코어 짝이 없는 **로컬 전용 문서**다. 프로젝트마다 검증·구현 방식이 근본적으로 달라 공통으로 배포할 내용이 없기 때문이다. 그러나 **모든 리포에 반드시 존재해야 한다** — 없으면 세션이 그 리포의 방식을 모른 채 일반론으로 진행하게 된다. `/project-init`이 초안을 만들고, 이후 작업 중 확인된 사항을 누적한다.
+
+**`TEST_RULE.local.md` 구성**:
+
+| 섹션 | 내용 |
+|------|------|
+| 방식별 실행 경로 | 데이터 조회 / API 호출 / UI·E2E / 시각 실행 — 각 방식을 *이 프로젝트에서 실제로 돌리는 명령·경로·셋업* |
+| 테스트 실행 환경 | 화면·입력을 점유하는 스위트의 **격리 실행 경로**(창 숨김·헤드리스 플래그 / 컨테이너·가상 디스플레이 / VM / CI 러너). 결정 자체도 기록 대상이다 — 격리 경로를 두지 않기로 했다면 *"없음 — 매번 승인(사용자 결정 YYYY-MM-DD)"*로 적어 미결정 상태와 구분한다 |
+| 범위·방식 정책 | 무엇을 얼마나 검증하나 — 수정 루프에서의 실행 범위, 테스트 신설 상한 등 |
+
+**"방식별 실행 경로"는 그대로 실행 가능한 형태로 적는다.** 추상적 설명이 아니라 명령과 경로다. 모르면 비워 두지 말고 사용자에게 확인한 즉시 기록한다 — 재사용의 근거는 기억이 아니라 파일이어야 세션이 바뀌어도 남는다.
+
+**"테스트 실행 환경"이 비어 있으면 점유 스위트를 자동 실행하지 않는다.** 사용자의 화면·마우스·키보드를 뺏어 작업을 중단시키기 때문이다. 비점유 부분만 한정 실행하거나, 실행 보류로 표시해 사용자 승인을 받는다.
+
+**`DEV_RULE.local.md` 구성**: 이 프로젝트 고유의 구현 정책과 테스트 실행 정책(빌드 선행 여부, 커밋 단위 관행, 금지 패턴 등).
+
+---
+
+## 9. 규칙을 새로 만드는 절차
+
+**트리거 2종**:
+1. 사용자가 직접 언급하거나 불편을 표현한 경우.
+2. 세션이 작업 중 문제를 인지한 경우(같은 실수 반복, 방식이 프로젝트와 맞지 않음 등).
+
+**판단** — 둘 중 어느 쪽인지 먼저 가른다.
+
+| 성격 | 처리 |
+|------|------|
+| **taskery 자체의 결함** — 모든 리포에서 똑같이 발생할 문제 | `/log-friction`으로 기록한다. 예: 스킬 지시가 서로 모순됨, CLI 반환값이 문서와 다름 |
+| **이 리포의 특성** — 이 프로젝트에서만 해당하는 방식·관행 | 해당 문서의 `.local.md` 감이다. 예: 이 프로젝트는 테스트 전에 빌드가 필요함, 이 리포는 특정 브랜치 명명을 씀 |
+
+**질문 후 생성** — 리포 특성으로 판단했으면 **반드시 사용자에게 묻는다**: *"이걸 이 리포 규칙(`<문서>.local.md`)으로 등록할까?"* 승인받은 후에만 파일을 만들거나 조항을 추가한다. 문안은 사용자와 확정한 내용으로 적는다. 양쪽에 모두 해당하면 둘 다 제안한다.
+
+새 로컬 문서의 파일명은 §7의 규칙을 따른다 — 코어 짝이 있으면 `<코어문서명>.local.md`, 없으면 `TEST_RULE` · `DEV_RULE`처럼 관할이 드러나는 이름에 `.local.md`를 붙인다.
+
+---
+
+## 10. 폴더 구조
+
+```
+.project/
+├─ rules/                    코어 룰 5종 + 이 리포의 *.local.md
+├─ *.md (루트)               제품 관통 문서 (SERVICE-POLICY / TECH-STACK / ARCHITECTURE /
+│                            DATA-MODEL / API-SPEC / FEATURES / UX-UI)
+├─ PROJECT.md                프로젝트 개요 + 초기 빌드 로드맵
+├─ GLOSSARY.md               도메인 용어집 (영문/한글 표기 단일 진실)
+├─ LINKED-REPOS.md           연결 리포 목록
+├─ BACKLOG.md                다음 기능 그룹 후보 카탈로그
+├─ FRICTION_LOG.md           불편 기록 (첫 기록 시 생성)
+├─ plans/<NNN_slug>/         PLAN.md · ROADMAP.md
+├─ tasks/<NNN_slug>/         task 문서 · spec-diffs/ · screenshots/ · mockup/
+├─ flows/                    도메인 흐름
+├─ shared/                   멀티리포 메시지
+├─ changelog/                월별 변경 이력
+└─ .env                      연결 리포 경로 (gitignore)
+```
+
+---
+
+## 11. 동기화 · 불편 기록 · 멀티리포
+
+**동기화 (사용자 의무)** — taskery는 문서 간 자동 빌드를 하지 않는다.
+- `.project/` 루트 제품 관통 문서를 변경하면 → 관련 task의 `spec-diffs/`를 갱신한다.
+- 진입 문서의 검증·테스트 명령을 변경하면 → 모든 스킬과 hook이 그대로 따르므로 별도 동기화가 불필요하다.
+- 룰 문서를 변경하면 → 다음 스킬 호출부터 반영된다.
+
+**불편 기록** — `.project/FRICTION_LOG.md`에 한 행씩 누적한다. 파일이 없으면 `/log-friction`이 첫 기록 때 생성한다. 발동 계기는 사용자 명시 호출 / 불만 발화 감지 / `/task-close` 직후 마찰 신호 자체 감지다.
+
+**멀티리포 통신** (해당 시)
+- 송신: `.project/shared/sent/<파일명>.md` 작성 → 수신 리포에서 `received/`로 복사 후 정독.
+- 처리 완료분은 각각 `completed/`로 이동한다.
+- 연결 리포 경로는 `.project/.env`, 리포 목록은 `.project/LINKED-REPOS.md`에 둔다.

package/template/.project/rules/TASK_DOC_RULE.md

@@ -2,6 +2,7 @@
 
 > taskery 태스크 문서(`task.md` 또는 `NNN_kebab-slug.md`) 작성 규칙.
 > **이 양식 그대로 채워. 섹션 추가/삭제 금지. 변형은 hook으로 차단되지 않으나 메인이 일관성 위해 강제 준수.**
+> 프로젝트별 변형이 필요하면 `.project/rules/TASK_DOC_RULE.local.md` 생성 (npx update 미터치, 구속력은 코어와 동등 — `TASKERY_RULE` §7).
 
 ---
 
@@ -102,6 +103,7 @@ draft → planned → developing → developed → testing → tested → closed
 | spec-diffs (변경된 제품 문서(루트) 추적) | `.project/tasks/<NNN_slug>/spec-diffs/<NNN>_<slug>_spec-diff.md` (**`<NNN_slug>` 공통** — 단일/폴더 모두) | `/task-plan` Step 6 (Phase 0 변경 시) |
 | screenshots (UI 작업 자료) | `.project/tasks/<NNN_slug>/screenshots/<NNN>_*.png` (**`<NNN_slug>` 공통**) | `/task-test` 격리 세션 또는 메인 |
 | mockup (UX/UI HTML 목업) | `.project/tasks/<NNN_slug>/mockup/<task-doc-name>-mockup.html` (**`<NNN_slug>` 공통** — 단일/폴더 모두) | `/task-plan` Step 4.5 (UX/UI task 한정) — 단일 진실 소스 `MOCKUP_RULE.md` |
+| test-plan-origin (출제 분리 B 원문) | `.project/tasks/<NNN_slug>/<NNN>_<slug>_test-plan-origin.md` (**`<NNN_slug>` 공통** — 단일/폴더 모두) | `/task-plan` Step 5-B (분리 적용 task 한정) — B 산출 그대로 보존, `/task-test` 오염 대조의 기준 사본 |
 | 폴더 승격 task의 추가 자료 (서브 문서 등) | `TASK-<NNN>_<slug>/` 안 자유 | 메인 / `/task-dev` |
 
 **원칙**:
@@ -110,7 +112,7 @@ draft → planned → developing → developed → testing → tested → closed
 - **spec-diff = per-task 기록** — 그 task가 어느 *제품 문서(`.project/` 루트)*를 NEW/MOD/DEL 했는지의 task 산출물. 제품 문서의 *정식 변경 이력은 git*이 단일 진실이며, 별도 전역 변경 인덱스는 두지 않는다.
 - 폴더 승격은 *task의 추가 자료*용 (서브 문서 / 디자인 자료 등) — *spec-diffs / screenshots / mockup 위치 X*.
 
-**closed-immutable hook 보호 범위** — task.md 본 파일만 (단일 파일 또는 폴더 승격 task.md). spec-diffs / screenshots / mockup / 폴더 승격 추가 자료는 *역사적 자료*로 자유 수정.
+**closed-immutable hook 보호 범위** — task.md 본 파일만 (단일 파일 또는 폴더 승격 task.md). spec-diffs / screenshots / mockup / 폴더 승격 추가 자료는 *역사적 자료*로 자유 수정. **단 test-plan-origin은 hook 보호 밖이어도 규약상 불변** — 오염 대조의 기준 사본이므로 어떤 주체도 수정하지 않는다.
 
 ---
 
@@ -216,9 +218,17 @@ draft → planned → developing → developed → testing → tested → closed
 | 시각 *객관* (레이아웃 / 요소 유무 / 색 / 배치 깨짐) | `[AUTO]` 캡처-목업 대조 | 승인 목업 (`mockup/<task-doc-name>-mockup.html`) — 화면 캡처 → 대조 → 어긋남 목록 |
 | 시각 *미세 취향* (2px / 색조 / 호버 강도 / 느낌) | `[USER]` 체크리스트 + 목업 참조 | 사용자 최종 사인 (증거 캡처) |
 
+**기대값 출처 표기** (UX/UI task 한정) — 모든 `[AUTO]` PASS 기준 끝에 출처를 단다: `(출처: 목업 §N / Req N)`. 출처를 못 다는 기대값은 `(출처 없음 — 사용자 확인 필요)`로 표기해 합의 때 사용자 확인 항목으로 분리한다. task-test 문 앞 검사의 자격 요건이다.
+
+**출제 분리 계약** (해석 여지 태스크 — task-plan Step 2.5 / 5-B):
+- 출제 주체 = 격리 서브에이전트 **B** (입력 = Requirements 합의문 + 승인 목업 + `TEST_RULE.local.md`만 — B 기동 시점에 Dev Plan 부재). B 원문은 `<NNN>_<slug>_test-plan-origin.md`로 그대로 보존한다 (§1.5).
+- **A(메인)의 수정권 = 방식 칸만**, 그것도 `TEST_RULE.local.md` 등재 경로로 교체할 때만. **시나리오 칸·PASS 기준 칸 불가침.**
+- **플래그 문법** — origin과 달라지는 모든 칸에 필수: `【<A수정|사용자결정|보수> · 원안: "<원문>"(· 근거: TEST_RULE.local.md §<절> — A수정만)】`. 정당 경로 3종 = A수정(방식 교체) / 사용자결정(Step 7 합의 변경) / 보수(Test Plan 보수 모드). **무플래그 차이 = task-test가 시험지 오염으로 즉시 반려.**
+- task-test는 origin 대조(룰 18)로 오염을 검사하고, 오염 판정 시 메인이 origin 기준으로 복원한다.
+
 **시각 영역 fix 사이클 사전 예고** — 시각 시나리오 있으면 Test Plan 끝에 *"시각 영역 항목 N개 — fix 사이클 1~2회 예상"* 명시 (사용자 기대치 사전 정렬).
 
-**검증 / 테스트 명령 참조** — `CLAUDE.md`의 `## 검증 명령` (코드 상태: 빌드 / 린트 / 타입체크) + `## 테스트 명령` (테스트 실행: 단위 / 통합 / E2E) 두 섹션을 격리 세션이 자동 참조. Test Plan 본문에 재인용 불필요.
+**검증 / 테스트 명령 참조** — `AGENTS.md`의 `## 검증 명령` (코드 상태: 빌드 / 린트 / 타입체크) + `## 테스트 명령` (테스트 실행: 단위 / 통합 / E2E) 두 섹션을 격리 세션이 자동 참조. Test Plan 본문에 재인용 불필요.
 
 **가이드라인**:
 - **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고도* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
@@ -387,7 +397,7 @@ Test Plan 작성 완료 후 *반드시* 점검. *"누적/리셋 안 함"* 같은
 | 5 | 한국어 ↔ 영어 전환 | [USER] | 수동 검수 | 메시지 언어 따라 변경 |
 ```
 
-> 검증 명령 / 테스트 명령은 `CLAUDE.md` 두 섹션을 격리 세션이 자동 참조 — Test Plan 본문 재인용 X.
+> 검증 명령 / 테스트 명령은 `AGENTS.md` 두 섹션을 격리 세션이 자동 참조 — Test Plan 본문 재인용 X.
 
 ### 4.6 Result
 
@@ -655,3 +665,4 @@ Test Plan 작성 완료 후 *반드시* 점검. *"누적/리셋 안 함"* 같은
 | 2026-05-30 | stash FRICTION_LOG 기반 정합 — §1.5 mockup 행 추가 (vX.X 공통, 단일 진실 소스 MOCKUP_RULE) + §2.5 Test Plan 본질 재정의 (실질 동작 시나리오 + `[AUTO]` / `[USER]` 분류 강제 + 카탈로그 7방식 + UX/UI 영역 분리 매트릭스 + 시각 fix 사이클 사전 예고 + 검증 / 테스트 명령 두 섹션 참조) + §4.5 / §5 완성 예시 3개 Test Plan 형식 갱신 (분류 표 + PASS 기준 명시. 기존 번호 매김 시나리오 + 검증 명령 나열은 옛 형식). (stash FRICTION_LOG #14+19 / #25 정합) |
 | 2026-06-02 | 0.1.3 F5 정합 — §2.5 가이드라인 안티패턴 3종 추가 (grep/Read-only 보조용 / 요구사항당 end-to-end 1개 이상 / 무거운 검증 회피 금지) + 요구사항 ↔ 시나리오 커버리지 점검 단계 신설 (stash FRICTION_LOG 2026-06-01 Test Plan 동어반복 + 누락 마찰 반영) |
 | 2026-06-27 | PLAYBOOK §13 정합 — plan = 기능 그룹. 헤더 *플랜* 컬럼 = `NNN_slug` 폴더명(예: 001_mvp). §1.5 경로 `tasks/<NNN_slug>/`, *`<NNN_slug>` 공통*으로 통일. spec-diff 정의 = *변경된 제품 문서(루트) 추적*(per-task 기록, 정식 변경 이력은 git 단일 진실) |
+| 2026-08-09 | 출제 분리 정합 — §1.5 test-plan-origin 행 추가(B 원문 보존, 규약상 불변) + §2.5 기대값 출처 표기·출제 분리 계약 명문(방식 칸 불가침 / 플래그 문법 【A수정|사용자결정|보수 · 원안】 / 무플래그 차이=오염 반려). recordion FRICTION 2026-08-09 반영 |