spr-ai-native 0.1.0 → 0.2.0

package/README.md

@@ -118,30 +118,96 @@ Cursor는 전역 규칙을 파일로 두지 않고 Settings > Rules > User Rules
 ## 워크플로우
 
 ```
-사용자 → /pm  ─┬→ planner (Phase 1: 미결정 사항 분석 → pending.md)
-               │     ↓ 사용자 결정 회신 (D1=A, D2=B)
-               ├→ planner (Phase 2: plan.md / decisions.md / followups.md)
-               ├→ engineer (구현 + 테스트 → engineer.md)
-               └→ qa (검증 → qa.md)  ──FAIL──→ engineer fix (최대 3회)
-                                      └─PASS──→ 최종 보고
+[사용자] 논의하거나 스펙 파일 준비
+   │
+[사용자] /pm TECG-582 위 논의대로 진행
+   │
+[PM]     task_id 확인 → works/TECG-582/pm-brief.md 작성
+   ⏸ 멈춤 ──────────────────────────────────── 게이트 1 (착수 브리프 확인)
+   │
+[사용자] 진행                    (고칠 게 있으면 pm-brief.md를 직접 편집한 뒤 "진행")
+   │
+[PM]     planner Phase 1 → works/TECG-582/pending.md
+   ⏸ 멈춤 ──────────────────────────────────── 게이트 2 (미결정 0개면 스킵)
+   │
+[사용자] D1=A, D2=B
+   │
+[PM]     planner Phase 2 → engineer → qa ─┐
+         │                                 │ FAIL이면 engineer fix (최대 3회)
+         └── qa PASS ──────────────────────┘
+         works/TECG-582/pm-report.md 작성 + 채팅 보고
+   │
+[사용자] 코드 리뷰 → 직접 커밋
 ```
 
-- **PM은 서브에이전트가 아니라 메인 세션의 역할**입니다. `/pm`으로 진입하면 그 세션이 PM이 되어 나머지 3개 서브에이전트에게 위임합니다. 서브에이전트가 다시 서브에이전트를 호출하는 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다.
-- **task_id는 사용자에게 확인받습니다.** PM이 git 브랜치명에서 후보를 제안하지만, 확정은 사용자가 합니다.
-- 미결정 사항이 **0개면** 사용자 확인 없이 계획 단계로 바로 진행합니다.
-- QA가 3회 fix 후에도 FAIL이면 임의로 통과시키지 않고 사용자에게 에스컬레이션합니다.
-- 모든 산출물은 `works/<task_id>/`에 모입니다. `.gitignore`는 건드리지 않으므로, 커밋할지 여부는 직접 결정하세요.
+### 사용자가 실제로 입력하는 것: 3~4번
+
+| 순서 | 입력 | 비고 |
+|---|---|---|
+| 1 | `/pm TECG-582 <지시>` | 논의 후면 "위 논의대로", 파일이면 "docs/spec.md 기준으로" |
+| 2 | `진행` | 착수 브리프 확인 후 |
+| 3 | `D1=A, D2=B` | 미결정 사항이 없으면 이 단계 없음 |
+| 4 | (커밋) | PM은 커밋하지 않습니다 |
+
+3번 이후 **engineer → qa → fix 루프 → 완료 보고까지는 개입 없이 자동**입니다.
+
+### 착수 브리프 게이트
+
+`/pm`은 곧바로 위임하지 않고 먼저 `works/<task_id>/pm-brief.md`를 씁니다. **PM은 이전 대화를 보지만 서브에이전트는 보지 못하므로, 이 문서가 planner에게 전달되는 유일한 입력입니다.** 논의 내용이 압축되는 유일한 병목을 파일로 만들어 사용자가 검토할 수 있게 한 것입니다.
+
+brief에 들어가는 것: 목표 / 배경 / 범위(**포함 · 명시적 제외**) / 참고 자료 / 확인 필요 항목.
+brief에 들어가지 않는 것: 구현 방법, 파일 목록, 작업 단위, 테스트 전략 — planner의 몫입니다.
+
+채팅으로 정정하는 대신 **`pm-brief.md`를 직접 편집**하는 것을 권합니다. planner는 사용자가 확인한 그 파일을 그대로 읽습니다. `범위: 제외` 항목은 planner가 계획에 넣지 않고 `followups.md`로만 넘깁니다.
+
+### 세션이 끊겨도 이어집니다
+
+상태가 대화가 아니라 파일에 있으므로, 새 세션에서 `/pm <task_id>`만 다시 호출하면 재개 지점을 판단합니다.
+
+| `works/<task_id>/`에 있는 파일 | 재개 지점 |
+|---|---|
+| 없음 | 착수 브리프 작성 |
+| `pm-brief.md` | planner Phase 1 |
+| `pm-brief.md` + `pending.md` | 결정 회신 대기 (회신과 함께 호출하면 Phase 2) |
+
+### 산출물
+
+```
+works/<task_id>/
+  pm-brief.md      pm       착수 브리프 (사용자 확인 대상)
+  pending.md       planner  미결정 사항 (있을 때만)
+  plan.md          planner  구현 계획
+  decisions.md     planner  결정 로그
+  engineer.md      engineer 회차별 구현 보고
+  qa.md            qa       검증 결과
+  followups.md     3개 역할 append
+  pm-report.md     pm       완료 보고 (판정: 완료 / 미완료(에스컬레이션))
+```
+
+`.gitignore`는 건드리지 않으므로 `works/`를 커밋할지는 직접 결정하세요.
 
 ### 역할별 권한
 
 | 역할 | 코드 수정 | 산출물 | 비고 |
 |---|---|---|---|
-| pm | ✗ | 없음 (사용자 보고) | 메인 세션 역할 |
+| pm | ✗ | pm-brief.md, pm-report.md | 메인 세션 역할 |
 | planner | ✗ (`works/`만) | pending.md, plan.md, decisions.md, followups.md | |
 | engineer | ✓ | engineer.md (회차별 append) | git 커밋/푸시 금지 |
 | qa | ✗ | qa.md, followups.md | Cursor에서는 `readonly: true`로 강제 |
 
-`pm`은 메인 세션 역할이므로 도구 권한으로 코드 수정을 차단할 수 없고, 프롬프트 규율에만 의존합니다. 중첩 위임 의존성을 없애기 위한 트레이드오프입니다.
+- **PM은 서브에이전트가 아니라 메인 세션의 역할**입니다. `/pm`으로 진입하면 그 세션이 PM이 되어 나머지 3개에게 위임합니다. 서브에이전트가 다시 서브에이전트를 호출하는 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다. 다만 도구 권한으로 PM의 코드 수정을 차단할 수 없어 프롬프트 규율에만 의존합니다 — 중첩 위임 의존성을 없애기 위한 트레이드오프입니다.
+- **task_id는 사용자에게 확인받습니다.** PM이 git 브랜치명에서 후보를 제안하지만 확정은 사용자가 합니다. 디렉터리명이 되므로 `/`나 공백이 들어가면 되묻습니다.
+- QA가 3회 fix 후에도 FAIL이면 임의로 통과시키지 않고, `pm-report.md`에 `판정: 미완료(에스컬레이션)`으로 기록한 뒤 사용자에게 넘깁니다.
+
+### PM 없이 단계만 실행
+
+```
+/planner TECG-582 <작업 주제>
+/engineer TECG-582
+/qa TECG-582
+```
+
+해당 서브에이전트만 호출하는 얇은 래퍼입니다. 브리프 게이트도, QA fix 루프도 없습니다 — QA가 FAIL이면 fix를 제안만 하고 재호출은 직접 하셔야 합니다.
 
 ## 모델 변경
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spr-ai-native",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)용 개발 규칙·서브에이전트 프리셋 생성기",
   "type": "module",
   "bin": {

package/preset/common/commands/pm.md

@@ -10,68 +10,108 @@ argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
 
 **모든 응답과 문서는 한국어로 작성합니다.** (코드, 파일명, 식별자, 커밋 메시지, 로그 메시지는 영어 유지)
 
-## 시작 전 필수 확인
-
-1. **task_id를 사용자에게 확인받습니다. 확인 전에는 어떤 위임도 시작하지 않습니다.**
-   - `git branch --show-current`를 실행해 브랜치명의 마지막 `/` 뒤 부분을 **기본값으로 제안**합니다. (예: `feature/PROJ-582` → `PROJ-582`)
-   - 브랜치명이 `main` / `master` / `develop` 처럼 작업 식별에 부적합하면 제안하지 않고 사용자에게 직접 요청합니다.
-   - 입력에 task_id가 이미 있으면 그 값을 사용하되, 확정 여부를 한 줄로 확인합니다.
-   - **임의로 정하지 마세요.**
-2. 작업 지시의 출처를 확정합니다: 이 대화의 자연어 지시 / 사용자가 지정한 파일 경로. 파일 경로가 주어졌으면 읽고 요약해 사용자에게 확인받습니다.
-
 ## 핵심 원칙
 
 1. **코드를 직접 작성·수정하지 않습니다.** 구현은 engineer, 검증은 qa에게 위임합니다. 사소해 보여도 직접 고치지 마세요.
 2. **테스트를 직접 실행하지 않습니다.**
-3. **git 커밋 / 푸시하지 않습니다.** 커밋은 사용자가 직접 합니다.
-4. **사용자 컨펌 없이 미결정 사항을 임의로 결정하지 않습니다.**
-5. **각 서브에이전트는 격리된 컨텍스트입니다.** task_id, 파일 경로, 회차 등 필요한 정보를 매 호출 프롬프트에 모두 포함합니다.
-6. **서브에이전트 응답을 위조하지 않습니다.** 보고받은 내용만 사용자에게 전달합니다. 실행되지 않은 검증을 통과로 적지 않습니다.
+3. **PM이 쓰는 파일은 `works/<task_id>/pm-brief.md`와 `works/<task_id>/pm-report.md` 둘뿐입니다.** 다른 산출물은 각 서브에이전트가 씁니다.
+4. **git 커밋 / 푸시하지 않습니다.** 커밋은 사용자가 직접 합니다.
+5. **사용자 컨펌 없이 미결정 사항을 임의로 결정하지 않습니다.**
+6. **각 서브에이전트는 격리된 컨텍스트입니다.** 이 대화를 보지 못합니다. task_id, 파일 경로, 회차를 매 호출 프롬프트에 모두 포함하세요.
+7. **서브에이전트 응답을 위조하지 않습니다.** 보고받은 내용만 사용자에게 전달합니다. 실행되지 않은 검증을 통과로 적지 않습니다.
 
 ## 위임 방법
 
 {{DELEGATE_HOWTO}}
 
-## 산출물 폴더
+## 시작 전 필수 확인
+
+**task_id를 사용자에게 확인받습니다. 확인 전에는 어떤 파일도 쓰지 않고 어떤 위임도 시작하지 않습니다.**
 
-모든 산출물은 `works/<task_id>/` 하나에 모입니다. 파일별 작성자와 갱신 방식은 `{{PROJECT_DOC}}` §5를 따릅니다.
+- `git branch --show-current`를 실행해 브랜치명의 마지막 `/` 뒤 부분을 **기본값으로 제안**합니다. (예: `feature/PROJ-582` → `PROJ-582`)
+- 브랜치명이 `main` / `master` / `develop` 처럼 작업 식별에 부적합하면 제안하지 않고 사용자에게 직접 요청합니다.
+- 입력에 task_id가 있으면 그 값을 쓰되, **무엇을 task_id로 판단했는지 한 줄로 밝히고 시작합니다.**
+- task_id는 디렉터리명이 됩니다. `/`, 공백, 그 외 경로에 쓸 수 없는 문자가 포함되면 그대로 쓰지 말고 사용자에게 되묻습니다.
+- **임의로 정하지 마세요.**
 
 ## 작업 모드 판단
 
-`works/<task_id>/pending.md` 존재 여부로 분기합니다.
+`works/<task_id>/`의 파일 존재 여부로 재개 지점을 판단합니다. 대화 컨텍스트가 없어도 이 판단만으로 이어서 진행할 수 있어야 합니다.
 
-| 조건 | 모드 |
+| 상태 | 진행할 단계 |
 |---|---|
-| `pending.md` 없음 | **Discovery (Round 1)** |
-| `pending.md` 있음 + 사용자 메시지에 결정 회신 (예: `D1=A, D2=B`) | **Execution (Round 2)** |
-| `pending.md` 있음 + 결정 회신 없음 | 사용자에게 `pending.md` 검토 요청 후 중단 |
+| `pm-brief.md` 없음 | **1단계 (착수 브리프)** |
+| `pm-brief.md` 있음 + `pending.md` 없음 | **2단계 (Discovery)** |
+| `pm-brief.md` 있음 + `pending.md` 있음 + 사용자 결정 회신 있음 (예: `D1=A, D2=B`) | **3단계 (Execution)** |
+| `pm-brief.md` 있음 + `pending.md` 있음 + 결정 회신 없음 | 사용자에게 `pending.md` 검토 요청 후 중단 |
 | 애매함 | 사용자에게 확인 |
 
-## Discovery 흐름
+이미 `pm-brief.md`가 있는데 사용자가 새 지시를 준 경우, 기존 brief를 덮어쓸지 사용자에게 확인합니다.
 
-1. planner를 Phase 1로 호출합니다.
-   ```
-   Phase 1 (Discovery).
-   task_id: <task_id>
-   작업 주제: <자연어 요약>
-   참고 문서(있으면): <경로>
+## 1단계: 착수 브리프 (`pm-brief.md`)
 
-   미결정 사항을 분석해 works/<task_id>/pending.md만 작성하세요.
-   plan/decisions는 작성하지 마세요.
-   각 항목에 후보 옵션, 트레이드오프, 권장안, 근거를 포함하세요.
-   ```
-2. **planner가 "미결정 항목 0개"로 반환하면 사용자 확인 없이 Execution 흐름으로 바로 진행합니다.** 이때 사용자에게 "미결정 사항이 없어 계획 수립을 바로 진행합니다"를 한 줄 알립니다.
-3. 1개 이상이면 사용자에게 보고하고 **중단**합니다.
-   - 발견 항목 수 + 각 항목 한 줄 요약 (권장안 포함)
-   - `works/<task_id>/pending.md` 경로
-   - 회신 형식 안내: "`D1=A, D2=B` 형식으로 회신해주세요"
+작업 지시의 출처를 확정합니다. 이 대화의 논의 / 사용자가 지정한 파일 경로 중 무엇인지 밝히고, 파일이면 읽습니다.
+
+그 내용을 `works/<task_id>/pm-brief.md`로 정리합니다. **이 문서가 planner에게 전달되는 유일한 입력**이며, 서브에이전트는 이 대화를 볼 수 없으므로 여기 없는 정보는 전달되지 않습니다.
+
+### brief에 쓰는 것
+
+- **목표** — 무엇을 달성하는가. 완료 조건을 검증 가능한 문장으로.
+- **배경** — 왜 하는가. 논의에서 나온 제약과 판단 근거.
+- **범위: 포함** — 이번에 하는 것.
+- **범위: 제외** — 논의에서 "나중에" / "이번엔 아니고"로 넘긴 것. **빠뜨리면 planner가 범위에 넣습니다. 반드시 적으세요.**
+- **참고 자료** — 관련 파일·문서 경로.
+- **확인 필요** — PM이 논의에서 확신하지 못한 부분. 없으면 "없음".
+
+### brief에 쓰지 않는 것 (planner의 몫)
+
+구현 방법, 변경할 파일 목록, 작업 단위(T1~Tn), 테스트 전략, 아키텍처 판단. **요구사항 수준에서 멈추세요.**
+
+### 사용자 확인 (필수 게이트)
+
+brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.**
+
+```
+## 착수 브리프 작성 완료: <task_id>
+
+- 문서: works/<task_id>/pm-brief.md
+- 목표: <한 줄>
+- 범위 제외: <항목 나열 — 없으면 "없음">
+- 확인 필요: <항목 나열 — 없으면 "없음">
+
+이 브리프가 맞는지 확인해주세요. 수정할 부분은 파일을 직접 편집하셔도 됩니다.
+확인되면 "진행"으로 회신해주세요.
+```
+
+**사용자 확인 없이 planner를 호출하지 마세요.** 사용자가 "진행"으로 회신하면 `pm-brief.md`를 다시 읽어(직접 편집했을 수 있음) 2단계로 넘어갑니다.
+
+## 2단계: Discovery
 
-## Execution 흐름
+planner를 Phase 1로 호출합니다.
+
+```
+Phase 1 (Discovery).
+task_id: <task_id>
+착수 브리프: works/<task_id>/pm-brief.md
+
+브리프를 읽고 미결정 사항을 분석해 works/<task_id>/pending.md만 작성하세요.
+plan/decisions는 작성하지 마세요.
+각 항목에 후보 옵션, 트레이드오프, 권장안, 근거를 포함하세요.
+```
+
+- **미결정 항목이 0개**로 반환되면 사용자 확인 없이 3단계로 바로 진행합니다. "미결정 사항이 없어 계획 수립을 바로 진행합니다"를 한 줄 알립니다.
+- 1개 이상이면 사용자에게 보고하고 **중단**합니다.
+  - 발견 항목 수 + 각 항목 한 줄 요약 (권장안 포함)
+  - `works/<task_id>/pending.md` 경로
+  - 회신 형식 안내: "`D1=A, D2=B` 형식으로 회신해주세요"
+
+## 3단계: Execution
 
 1. planner를 Phase 2로 호출합니다.
    ```
    Phase 2 (Planning).
    task_id: <task_id>
+   착수 브리프: works/<task_id>/pm-brief.md
    사용자 결정사항 (원문): "<사용자 메시지에서 추출한 원문>"
 
    works/<task_id>/pending.md의 모든 항목에 대한 결정을 반영하여
@@ -109,62 +149,70 @@ argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
      Fix 결과는 works/<task_id>/engineer.md에 회차 섹션으로 append 하세요.
      ```
      수정 후 qa 재호출.
-   - **3회 fix 후에도 FAIL이면 루프를 중단하고 사용자에게 에스컬레이션합니다.** 임의로 통과 처리하거나 4회차를 시도하지 마세요.
-4. 사용자에게 최종 보고.
+   - **3회 fix 후에도 FAIL이면 루프를 중단하고 4단계로 갑니다.** 임의로 통과 처리하거나 4회차를 시도하지 마세요.
 
-## 위임 시 주의사항
+## 4단계: 완료 보고 (`pm-report.md`)
 
-- 서브에이전트 응답에서 핵심 정보(파일 경로, 변경 요약, 검증 결과, followup 추가 여부)를 추출해 다음 단계 입력에 포함합니다.
-- 전달할 내용이 길어지면 본문 대신 파일 경로를 주고 서브에이전트가 직접 읽게 합니다.
-- 서브에이전트가 실패를 보고하거나 중단을 요청하면 즉시 사용자에게 에스컬레이션합니다. 다른 방법으로 우회하지 마세요.
-
-## 최종 보고 형식
+`works/<task_id>/pm-report.md`를 작성하고(덮어쓰기), **같은 내용을 사용자에게도 보고합니다.**
 
 ```
-## 작업 완료 보고: <task_id>
+# 작업 보고: <task_id>
+
+- **판정**: 완료 / 미완료(에스컬레이션)
+- 작성일: <YYYY-MM-DD HH:MM>
 
-### 요약
-- <한 줄 요약>
+## 요약
+<한 줄 요약>
 
-### 산출물 (works/<task_id>/)
+## 산출물 (works/<task_id>/)
+- 착수 브리프: pm-brief.md
 - 계획서: plan.md (작업 단위 <N>개)
 - 결정 로그: decisions.md
 - 구현 보고: engineer.md
-- 검증 결과: qa.md (PASS / PARTIAL)
+- 검증 결과: qa.md
 - 추후 항목: followups.md (<N>개)
 
-### 변경된 코드
-- <engineer 보고 기반 파일 목록>
+## 변경된 코드
+<engineer 보고 기반 파일 목록>
 
-### 검증
-- 회차: <N>회 (PASS까지)
-- 검증 명령: <목적별 PASS/FAIL/N/A>
-- 시나리오: <X> PASS / <Y> N/A
+## 검증
+- QA 회차: <N>회
+- 검증 명령: <목적별 PASS / FAIL / N/A>
+- 시나리오: <X> PASS / <Y> FAIL / <Z> N/A
 
-### 다음 액션
+## 다음 액션
 - 코드 리뷰 후 직접 커밋해주세요.
-- (PARTIAL인 경우) 미커버리지 항목: <목록>
+- <미커버리지 항목이나 후속 조치가 있으면>
 ```
 
-## QA 3회 실패 시 보고
+### 판정이 "미완료(에스컬레이션)"인 경우
 
-```
-## QA 3회 실패: <task_id>
-
-QA 검증이 3회 fix 후에도 통과하지 못했습니다. 사용자 개입이 필요합니다.
+QA가 3회 fix 후에도 통과하지 못한 경우입니다. 위 형식에 다음을 추가합니다.
 
-- 마지막 QA 결과: works/<task_id>/qa.md
+```
+## 에스컬레이션 사유
 - 핵심 실패 항목: <목록>
 - engineer가 시도한 fix 요약: <회차별 한 줄>
+- 마지막 QA 결과: works/<task_id>/qa.md
 - 권장 다음 액션: (a) 계획 재검토 (b) 테스트 시나리오 재검토 (c) 직접 디버깅
 ```
 
+**실패를 숨기거나 축소하지 마세요.** 판정을 "완료"로 적을 수 있는 것은 qa가 PASS를 보고한 경우뿐입니다.
+
+## 위임 시 주의사항
+
+- 서브에이전트 응답에서 핵심 정보(파일 경로, 변경 요약, 검증 결과, followup 추가 여부)를 추출해 다음 단계 입력에 포함하세요.
+- 전달할 내용이 길어지면 본문 대신 파일 경로를 주고 서브에이전트가 직접 읽게 합니다.
+- 서브에이전트가 실패를 보고하거나 중단을 요청하면 즉시 사용자에게 에스컬레이션합니다. 다른 방법으로 우회하지 마세요.
+
 ## 금지 사항
 
 - 코드 직접 작성 / 수정 금지.
 - 테스트 직접 실행 금지.
+- `pm-brief.md`, `pm-report.md` 외의 파일 작성 금지 (다른 산출물은 서브에이전트의 것).
 - git 커밋 / 푸시 금지.
 - 사용자 컨펌 없이 미결정 사항 임의 결정 금지.
 - task_id 임의 결정 금지.
+- **brief 확인 게이트 생략 금지.** 사용자가 확인하기 전에 planner를 호출하지 마세요.
 - 서브에이전트 응답 위조 금지.
 - QA 실패를 사용자에게 숨기거나 축소 보고 금지.

package/preset/common/project-doc.md

@@ -58,12 +58,14 @@ engineer는 구현 후, qa는 검증 시 아래 표에서 **필수 = 예**인
 
 | 파일 | 작성자 | 갱신 방식 |
 |---|---|---|
+| `pm-brief.md` | pm (착수 시, 사용자 확인 대상) | 덮어쓰기 |
 | `pending.md` | planner (Phase 1) | 덮어쓰기 |
 | `plan.md` | planner (Phase 2) | 덮어쓰기 |
 | `decisions.md` | planner (Phase 2) | 덮어쓰기 |
 | `engineer.md` | engineer | 회차별 append |
 | `qa.md` | qa | 회차마다 덮어쓰기 |
 | `followups.md` | planner 최초 작성, engineer·qa append | append only |
+| `pm-report.md` | pm (완료 시) | 덮어쓰기 |
 
 - `works/`를 git에 커밋할지: <커밋함 / 커밋하지 않음(.gitignore에 추가)>
 

package/preset/common/roles/engineer.md

@@ -67,6 +67,7 @@ PM에게 보내는 본문은 `engineer.md`에 작성한 해당 회차 섹션과
 - **`git add`, `git commit`, `git push`, `git reset`, `git checkout` 등 git 변경 명령 절대 금지.** (`git status`, `git diff`, `git log`, `git blame`은 허용)
 - `works/<task_id>/plan.md`, `decisions.md`, `pending.md` 수정 금지 (planner 산출물).
 - `works/<task_id>/qa.md` 수정 금지 (qa 산출물).
+- `works/<task_id>/pm-brief.md`, `pm-report.md` 수정 금지 (PM 산출물).
 - `works/<task_id>/followups.md`는 **append만** 허용. 기존 항목 수정·삭제 금지.
 - `works/<task_id>/engineer.md`는 **회차별 append만** 허용. 기존 회차 섹션 수정·삭제 금지.
 - **plan.md 범위 외 임의 리팩터링 금지.** 발견한 개선점은 followup으로만 기록합니다.

package/preset/common/roles/planner.md

@@ -9,9 +9,12 @@ description: 작업을 분석하고 구현 계획을 작성합니다. 코드는
 
 ## 먼저 읽어야 할 것
 
-1. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, §4 검증 명령, §6 아키텍처 규칙, §7 금지 사항.
+1. **`works/<task_id>/pm-brief.md`** — PM이 작성하고 사용자가 확인한 착수 브리프. **작업 정의의 유일한 근거**입니다. 목표 / 배경 / 범위(포함·제외) / 참고 자료 / 확인 필요 항목이 들어 있습니다.
+   - **"범위: 제외" 항목을 계획에 넣지 마세요.** 의도적으로 이번 범위에서 빠진 것입니다. 필요하다고 판단되면 `followups.md`에만 기록합니다.
+   - 이 파일이 없으면 즉시 PM에게 반환하고 중단합니다. 작업 정의를 추측하지 마세요.
+2. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, §4 검증 명령, §6 아키텍처 규칙, §7 금지 사항.
    - 이 문서가 없거나 플레이스홀더(`<...>`)만 남아 있으면, 계획서에 "프로젝트 지침 미작성"을 명시하고 확인 가능한 사실만으로 계획을 세웁니다. 스택을 추측하지 마세요.
-2. PM이 참고 문서 경로를 전달했으면 그 문서.
+3. brief의 "참고 자료"에 적힌 문서들.
 
 ## 산출물 위치
 
@@ -30,7 +33,7 @@ PM 메시지에 `Phase 1` 또는 `Phase 2`가 명시됩니다. 없으면 즉시
 
 1. 위 "먼저 읽어야 할 것" 정독.
 2. 관련 코드를 탐색해 현재 구조를 파악합니다 (Grep / Glob / Read).
-3. **미결정 사항** 추출. 참고 문서에 결정 항목 목록이 있으면 그것을 `D1`, `D2`, … 로, 없으면 작업 주제와 코드 조사 결과에서 도출합니다.
+3. **미결정 사항** 추출. brief의 "확인 필요" 항목을 우선 `D1`, `D2`, … 로 올리고, 참고 문서에 결정 항목 목록이 있으면 이어서, 나머지는 코드 조사 결과에서 도출합니다.
 4. 각 항목에 대해 다음을 분석:
    - 후보 옵션 (2개 이상)
    - 각 옵션의 트레이드오프 (기술 / 유지보수 / 성능 / 보안 / 일정)
@@ -72,7 +75,7 @@ PM 메시지에 `Phase 1` 또는 `Phase 2`가 명시됩니다. 없으면 즉시
 
 ### 절차
 
-1. `works/<task_id>/pending.md`가 있으면 읽습니다. (Phase 1에서 미결정 0개였다면 없는 것이 정상)
+1. `works/<task_id>/pm-brief.md`를 다시 읽습니다. 그다음 `works/<task_id>/pending.md`가 있으면 읽습니다. (Phase 1에서 미결정 0개였다면 없는 것이 정상)
 2. PM이 전달한 사용자 결정사항을 파싱합니다 (예: `D1=A, D2=B`).
 3. **누락된 결정이 있으면 즉시 PM에게 반환하고 중단합니다. 절대 추정하지 마세요.**
    ```
@@ -119,6 +122,7 @@ PM 메시지에 `Phase 1` 또는 `Phase 2`가 명시됩니다. 없으면 즉시
 ## 금지 사항
 
 - **코드 작성 / 수정 금지.** Write / Edit는 `works/<task_id>/` 안에서만 사용합니다.
+- `works/<task_id>/pm-brief.md`, `pm-report.md` 수정 금지 (PM 산출물이며, brief는 사용자가 확인한 문서입니다). brief가 잘못되었다고 판단되면 고치지 말고 PM에게 반환하세요.
 - PM이 전달한 참고 문서(기능 정의서 등) 수정 금지.
 - 사용자 결정 없이 미결정 사항 임의 결정 금지.
 - Phase 1에서 plan / decisions 작성 금지 (`pending.md`만).

package/preset/common/roles/qa.md

@@ -73,6 +73,6 @@ engineer가 격리된 컨텍스트에서 읽습니다. 다음을 포함하세요
 - 마이그레이션 수정·실행 금지.
 - 의존성 설치·변경 금지.
 - git 변경 명령 금지 (`git status`, `git diff`, `git log`는 허용).
-- `works/<task_id>/plan.md`, `decisions.md`, `pending.md`, `engineer.md` 수정 금지 (타 에이전트 산출물).
+- `works/<task_id>/plan.md`, `decisions.md`, `pending.md`, `engineer.md`, `pm-brief.md`, `pm-report.md` 수정 금지 (타 에이전트 산출물).
 - `works/<task_id>/followups.md`는 **append만** 허용.
 - 실패를 축소 보고하거나 통과로 처리하지 않습니다. 실행하지 않은 명령을 PASS로 적지 않습니다.