spr-ai-native 0.2.0 → 0.3.0

package/README.md

@@ -133,7 +133,7 @@ Cursor는 전역 규칙을 파일로 두지 않고 Settings > Rules > User Rules
 [사용자] D1=A, D2=B
    │
 [PM]     planner Phase 2 → engineer → qa ─┐
-         │                                 │ FAIL이면 engineer fix (최대 3회)
+         │                                 │ FAIL이면 engineer fix (기본 최대 3회)
          └── qa PASS ──────────────────────┘
          works/TECG-582/pm-report.md 작성 + 채팅 보고
    │
@@ -160,6 +160,27 @@ brief에 들어가지 않는 것: 구현 방법, 파일 목록, 작업 단위,
 
 채팅으로 정정하는 대신 **`pm-brief.md`를 직접 편집**하는 것을 권합니다. planner는 사용자가 확인한 그 파일을 그대로 읽습니다. `범위: 제외` 항목은 planner가 계획에 넣지 않고 `followups.md`로만 넘깁니다.
 
+### README는 두 역할이 나눠 씁니다
+
+`works/` 밖에서 에이전트가 손대는 파일은 `README.md` 하나뿐입니다.
+
+| 구간 | 작성자 | 내용 |
+|---|---|---|
+| 실행 방법 | engineer | 설치 / 실행 / 테스트 명령을 **실제로 실행해본 그대로**. 환경변수는 이름과 예시값만 |
+| 개요 · 범위 · 알려진 한계 | pm | `pm-brief.md`의 `범위: 제외`와 약점 표에서 사용자에게 영향이 가는 것만 |
+
+PM은 engineer가 쓴 실행 방법 섹션을 수정하지 않습니다. 실제로 실행해보고 쓴 쪽이 engineer이기 때문입니다.
+
+**사용자에게 보이는 변화가 있을 때만 갱신합니다.** 내부 리팩터링이나 테스트 추가만으로는 README를 건드리지 않으며, 기존 README에 사람이 써 둔 내용은 지우지 않고 해당 섹션만 갱신합니다.
+
+### 알려진 약점은 산출물에 남습니다
+
+완료 보고(`pm-report.md`)는 **판정과 함께 알려진 약점을 반드시 적습니다.** 판정이 `완료`여도 생략하지 않습니다.
+
+재료는 구현한 쪽에서 나옵니다. engineer는 회차 보고에 자기가 작성한 코드 중 **재현 조건을 적을 수 있는** 취약 지점을 남기고, QA는 미커버리지(N/A)를 남깁니다. PM은 이 둘과 `범위: 제외`·`followups.md`에서 파급이 큰 순으로 3개 내외를 추려 `지점 / 왜 위험한가 / 다음에 검증할 것`으로 정리합니다.
+
+**PM은 코드를 읽지 않으므로 이 표는 추측이 아니라 인용입니다.** 재현 조건을 못 적는 것은 약점이 아니라 추측이라고 보고 걸러냅니다. 통과 보고서만 남기면 다음 사람이 같은 지뢰를 다시 밟기 때문입니다.
+
 ### 세션이 끊겨도 이어집니다
 
 상태가 대화가 아니라 파일에 있으므로, 새 세션에서 `/pm <task_id>`만 다시 호출하면 재개 지점을 판단합니다.
@@ -169,6 +190,7 @@ brief에 들어가지 않는 것: 구현 방법, 파일 목록, 작업 단위,
 | 없음 | 착수 브리프 작성 |
 | `pm-brief.md` | planner Phase 1 |
 | `pm-brief.md` + `pending.md` | 결정 회신 대기 (회신과 함께 호출하면 Phase 2) |
+| `plan.md`가 있으면 (위 조건보다 우선) | engineer부터. planner를 다시 부르지 않습니다 |
 
 ### 산출물
 
@@ -181,7 +203,7 @@ works/<task_id>/
   engineer.md      engineer 회차별 구현 보고
   qa.md            qa       검증 결과
   followups.md     3개 역할 append
-  pm-report.md     pm       완료 보고 (판정: 완료 / 미완료(에스컬레이션))
+  pm-report.md     pm       완료 보고 (판정 · 알려진 약점)
 ```
 
 `.gitignore`는 건드리지 않으므로 `works/`를 커밋할지는 직접 결정하세요.
@@ -190,16 +212,26 @@ works/<task_id>/
 
 | 역할 | 코드 수정 | 산출물 | 비고 |
 |---|---|---|---|
-| pm | ✗ | pm-brief.md, pm-report.md | 메인 세션 역할 |
+| pm | ✗ | pm-brief.md, pm-report.md, README(개요·범위·한계) | 메인 세션 역할 |
 | planner | ✗ (`works/`만) | pending.md, plan.md, decisions.md, followups.md | |
-| engineer | ✓ | engineer.md (회차별 append) | git 커밋/푸시 금지 |
+| engineer | ✓ | engineer.md (회차별 append), README(실행 방법) | git 커밋/푸시 금지 |
 | qa | ✗ | qa.md, followups.md | Cursor에서는 `readonly: true`로 강제 |
 
 - **PM은 서브에이전트가 아니라 메인 세션의 역할**입니다. `/pm`으로 진입하면 그 세션이 PM이 되어 나머지 3개에게 위임합니다. 서브에이전트가 다시 서브에이전트를 호출하는 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다. 다만 도구 권한으로 PM의 코드 수정을 차단할 수 없어 프롬프트 규율에만 의존합니다 — 중첩 위임 의존성을 없애기 위한 트레이드오프입니다.
 - **task_id는 사용자에게 확인받습니다.** PM이 git 브랜치명에서 후보를 제안하지만 확정은 사용자가 합니다. 디렉터리명이 되므로 `/`나 공백이 들어가면 되묻습니다.
-- QA가 3회 fix 후에도 FAIL이면 임의로 통과시키지 않고, `pm-report.md`에 `판정: 미완료(에스컬레이션)`으로 기록한 뒤 사용자에게 넘깁니다.
+- QA가 재시도 상한을 소진하고도 FAIL이면 임의로 통과시키지 않고, `pm-report.md`에 `판정: 미완료(에스컬레이션)`으로 기록한 뒤 사용자에게 넘깁니다.
 
-### PM 없이 단계만 실행
+### 어느 진입점을 쓸까
+
+`/pm`은 게이트 2개와 서브에이전트 호출 4회 이상을 포함합니다. **모든 작업에 쓰라고 만든 것이 아닙니다.**
+
+| 작업 | 진입점 | 이유 |
+|---|---|---|
+| 스택·범위·설계에 갈림길이 있다 | `/pm` | 미결정 사항을 사용자 결정으로 확정하는 것이 이 워크플로우의 값어치입니다 |
+| 계획은 이미 섰고 구현만 남았다 | `/engineer` → `/qa` | brief·pending·plan을 만들 이유가 없습니다 |
+| 계획만 받아보고 싶다 | `/planner` | 구현은 나중에 판단합니다 |
+| 방금 고친 것만 검증하고 싶다 | `/qa` | |
+| 오타 수정, 한 줄 변경 | **아무것도 쓰지 않음** | 워크플로우 비용이 작업보다 큽니다 |
 
 ```
 /planner TECG-582 <작업 주제>
@@ -207,7 +239,20 @@ works/<task_id>/
 /qa TECG-582
 ```
 
-해당 서브에이전트만 호출하는 얇은 래퍼입니다. 브리프 게이트도, QA fix 루프도 없습니다 — QA가 FAIL이면 fix를 제안만 하고 재호출은 직접 하셔야 합니다.
+개별 커맨드는 해당 서브에이전트만 호출하는 얇은 래퍼입니다. 브리프 게이트도, QA fix 루프도 없습니다 — QA가 FAIL이면 fix를 제안만 하고 재호출은 직접 하셔야 합니다. 산출물 파일 규약은 `/pm`과 동일하므로, 개별 커맨드로 시작했다가 도중에 `/pm`으로 넘어가도 이어집니다.
+
+### 작업 예산으로 무게 조절
+
+프로젝트 지침 문서 **§5의 작업 예산** 표로 `/pm`의 왕복 횟수를 조절합니다. 기본값은 아래와 같고, 그대로 두면 지금까지의 동작과 같습니다.
+
+| 항목 | 기본값 | 조절했을 때 |
+|---|---|---|
+| QA fix 재시도 횟수 | 3 | 줄이면 실패가 빨리 사용자에게 올라옵니다. `0`은 fix 없이 첫 QA 결과로 종료 |
+| 계획 단계 | 분리 | `통합`은 planner 호출을 2회 → 1회로 줄입니다 |
+
+`계획 단계 = 통합`이면 planner가 `pending.md`와 **권장안을 채택했다고 가정한 `plan.md`** 를 한 번에 씁니다. 사용자가 `진행`으로 답하면 planner를 다시 부르지 않고 곧바로 engineer로 넘어갑니다.
+
+대신 사용자가 권장안을 뒤집으면 planner를 Phase 2로 다시 불러야 하므로 그만큼 계획 작성이 헛일이 됩니다. **권장안 채택률이 높은 작업에서만 이득**입니다. 그래서 기본값은 `분리`입니다.
 
 ## 모델 변경
 

package/package.json

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

package/preset/common/commands/engineer.md

@@ -13,7 +13,7 @@ argument-hint: <task_id> [fix]
 - `task_id` — 입력의 첫 토큰. **없으면 사용자에게 먼저 요청합니다.** 임의로 정하지 마세요.
 - 모드 판단:
   - **신규 구현** — `works/<task_id>/plan.md` 경로와 `decisions.md` 경로를 전달합니다. `plan.md`가 없으면 위임하지 말고 planner를 먼저 실행하라고 사용자에게 안내합니다.
-  - **QA Fix** — 입력에 `fix`가 있거나 `works/<task_id>/qa.md`가 FAIL/PARTIAL이면, `qa.md` 경로와 회차(`<N>/3`)를 전달합니다. 회차는 `engineer.md`의 기존 회차 섹션 수를 보고 계산합니다.
+  - **QA Fix** — 입력에 `fix`가 있거나 `works/<task_id>/qa.md`가 FAIL/PARTIAL이면, `qa.md` 경로와 회차(`<N>/<최대>`)를 전달합니다. 최대 횟수는 프로젝트 지침 §5 작업 예산의 **QA fix 재시도 횟수**(기본 3)입니다. 회차는 `engineer.md`의 기존 회차 섹션 수를 보고 계산합니다.
 - 다음 지시를 함께 전달합니다: 구현 보고를 `works/<task_id>/engineer.md`에 회차별 append, **git 커밋/푸시 금지**.
 
 ## 이후 처리

package/preset/common/commands/pm.md

@@ -19,6 +19,7 @@ argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
 5. **사용자 컨펌 없이 미결정 사항을 임의로 결정하지 않습니다.**
 6. **각 서브에이전트는 격리된 컨텍스트입니다.** 이 대화를 보지 못합니다. task_id, 파일 경로, 회차를 매 호출 프롬프트에 모두 포함하세요.
 7. **서브에이전트 응답을 위조하지 않습니다.** 보고받은 내용만 사용자에게 전달합니다. 실행되지 않은 검증을 통과로 적지 않습니다.
+8. **약점을 숨기지 않습니다.** 완료 보고에는 알려진 약점을 함께 적습니다. "문제 없음"은 검증하지 않았다는 뜻일 가능성이 높습니다.
 
 ## 위임 방법
 
@@ -34,13 +35,22 @@ argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
 - task_id는 디렉터리명이 됩니다. `/`, 공백, 그 외 경로에 쓸 수 없는 문자가 포함되면 그대로 쓰지 말고 사용자에게 되묻습니다.
 - **임의로 정하지 마세요.**
 
+### 작업 예산 확인
+
+`{{PROJECT_DOC}}` §5의 **작업 예산** 표를 읽어 이번 워크플로우의 동작을 결정합니다. 표가 없거나 값이 비어 있으면 **QA fix 재시도 3회 / 계획 단계 분리**로 간주합니다.
+
+읽은 값은 1단계 보고에 한 줄로 밝힙니다. 예: `작업 예산: fix 2회 / 계획 단계 통합`
+
 ## 작업 모드 판단
 
 `works/<task_id>/`의 파일 존재 여부로 재개 지점을 판단합니다. 대화 컨텍스트가 없어도 이 판단만으로 이어서 진행할 수 있어야 합니다.
 
+**위에서부터 먼저 맞는 행을 적용합니다.**
+
 | 상태 | 진행할 단계 |
 |---|---|
 | `pm-brief.md` 없음 | **1단계 (착수 브리프)** |
+| `plan.md` 있음 | **3단계 (Execution) 2번(engineer)부터.** planner를 다시 부르지 않습니다 |
 | `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` 검토 요청 후 중단 |
@@ -78,6 +88,7 @@ brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.
 - 목표: <한 줄>
 - 범위 제외: <항목 나열 — 없으면 "없음">
 - 확인 필요: <항목 나열 — 없으면 "없음">
+- 작업 예산: fix <N>회 / 계획 단계 <분리 또는 통합>
 
 이 브리프가 맞는지 확인해주세요. 수정할 부분은 파일을 직접 편집하셔도 됩니다.
 확인되면 "진행"으로 회신해주세요.
@@ -87,6 +98,10 @@ brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.
 
 ## 2단계: Discovery
 
+작업 예산의 **계획 단계** 값에 따라 planner 호출 방식이 달라집니다.
+
+### 계획 단계 = 분리 (기본)
+
 planner를 Phase 1로 호출합니다.
 
 ```
@@ -105,6 +120,29 @@ plan/decisions는 작성하지 마세요.
   - `works/<task_id>/pending.md` 경로
   - 회신 형식 안내: "`D1=A, D2=B` 형식으로 회신해주세요"
 
+### 계획 단계 = 통합
+
+planner를 한 번만 호출해 미결정 분석과 계획 수립을 함께 받습니다.
+
+```
+Phase 1+2 (통합).
+task_id: <task_id>
+착수 브리프: works/<task_id>/pm-brief.md
+
+미결정 사항을 분석해 works/<task_id>/pending.md를 작성하고,
+각 항목의 권장안을 채택했다고 가정해
+works/<task_id>/plan.md, decisions.md, followups.md까지 이어서 작성하세요.
+decisions.md에는 각 결정이 권장안이며 사용자 미확인임을 명시하세요.
+```
+
+- **미결정 항목이 0개**면 계획서가 이미 확정입니다. 사용자 확인 없이 3단계 **2번(engineer)** 부터 진행합니다.
+- 1개 이상이면 사용자에게 보고하고 **중단**합니다.
+  - 발견 항목 수 + 각 항목 한 줄 요약 (권장안 포함)
+  - "권장안을 전제로 `works/<task_id>/plan.md`까지 작성되어 있습니다."
+  - 회신 형식 안내: "권장안대로 진행하려면 `진행`, 바꿀 항목만 `D1=B` 형식으로 회신해주세요"
+- 사용자가 `진행`으로 회신하면 **planner를 다시 부르지 않고** 3단계 **2번(engineer)** 부터 진행합니다.
+- 사용자가 항목을 바꾸면 3단계 **1번(planner Phase 2)** 부터 진행합니다. 바뀐 항목뿐 아니라 **모든 결정의 최종값**을 전달하세요.
+
 ## 3단계: Execution
 
 1. planner를 Phase 2로 호출합니다.
@@ -129,7 +167,7 @@ plan/decisions는 작성하지 마세요.
    구현 보고는 works/<task_id>/engineer.md에 회차별 append로 남기세요.
    git 커밋/푸시는 금지입니다.
    ```
-3. **qa 호출 + Fix 루프 (engineer 최대 4회 = 초기 1회 + fix 3회)**
+3. **qa 호출 + Fix 루프.** 재시도 상한 `<F>`는 작업 예산의 **QA fix 재시도 횟수**입니다 (기본 3). engineer 호출은 최대 `1 + <F>`회입니다.
    - qa 호출:
      ```
      task_id: <task_id>
@@ -142,14 +180,15 @@ plan/decisions는 작성하지 마세요.
    - **FAIL / PARTIAL**이면 engineer 재호출:
      ```
      task_id: <task_id>
-     QA 실패. 회차: <N>/3
+     QA 실패. 회차: <N>/<F>
      QA 결과: works/<task_id>/qa.md
 
      이 문서의 "실패 원인"과 "Fix 가이드"를 참고해 수정하세요.
      Fix 결과는 works/<task_id>/engineer.md에 회차 섹션으로 append 하세요.
      ```
      수정 후 qa 재호출.
-   - **3회 fix 후에도 FAIL이면 루프를 중단하고 4단계로 갑니다.** 임의로 통과 처리하거나 4회차를 시도하지 마세요.
+   - **`<F>`회 fix 후에도 FAIL이면 루프를 중단하고 4단계로 갑니다.** 임의로 통과 처리하거나 상한을 넘겨 시도하지 마세요.
+   - `<F>`가 `0`이면 fix 없이 첫 QA 결과로 4단계로 갑니다.
 
 ## 4단계: 완료 보고 (`pm-report.md`)
 
@@ -180,14 +219,48 @@ plan/decisions는 작성하지 마세요.
 - 검증 명령: <목적별 PASS / FAIL / N/A>
 - 시나리오: <X> PASS / <Y> FAIL / <Z> N/A
 
+## 알려진 약점
+
+| 지점 | 왜 위험한가 | 다음에 검증·개선할 것 |
+|---|---|---|
+| <파일·모듈 경로> | <어떤 상황에서 어떻게 깨지는가> | <구체적인 검증 방법> |
+
 ## 다음 액션
 - 코드 리뷰 후 직접 커밋해주세요.
 - <미커버리지 항목이나 후속 조치가 있으면>
 ```
 
+### "알려진 약점" 작성 규칙
+
+**PM은 코드를 읽지 않습니다. 따라서 이 표는 추측이 아니라 인용이어야 합니다.** 아래 네 곳에서만 재료를 가져오고, 없는 것을 지어내지 마세요.
+
+| 재료 | 출처 |
+|---|---|
+| engineer가 보고한 알려진 약점 | `engineer.md` 최신 회차 |
+| QA로 넘긴 미확인 항목 | `engineer.md` |
+| 미커버리지(N/A) 시나리오 · N/A로 남은 검증 명령 | `qa.md` |
+| 이번 범위에서 제외한 것 | `pm-brief.md` "범위: 제외", `followups.md` |
+
+- 3개 내외로 추립니다. 전부 나열하지 말고 **파급이 큰 순서**로 고르세요.
+- "왜 위험한가"는 재현 조건이나 영향 범위로 씁니다. `followups.md`의 문장을 그대로 옮기지 말고 무엇이 위험한지로 바꿔 쓰세요.
+- **표가 비는 경우는 거의 없습니다.** 범위에서 제외한 것이 있으면 그것이 곧 한계입니다. 그래도 없다고 판단되면 "없음"으로 적고 그 근거를 한 줄 덧붙입니다.
+- 판정이 `완료`여도 이 표는 생략하지 않습니다.
+
+### README 정리
+
+`pm-report.md`를 쓴 뒤 `README.md` 상단을 정리합니다. **engineer가 작성한 실행 방법 섹션은 그대로 보존합니다.**
+
+- **무엇을 만들었는가** — 한 문단.
+- **범위: 포함 / 제외** — `pm-brief.md` 기준. 제외 항목은 이유를 한 줄씩 붙입니다.
+- **알려진 한계** — 위 약점 표에서 **사용자에게 영향이 가는 것만** 옮깁니다. 내부 구현 리스크는 `pm-report.md`에 두세요.
+
+- 기존 README에 사람이 써 둔 내용이 있으면 지우지 말고 위 항목만 추가·갱신합니다.
+- **구현하지 않은 것을 구현한 것처럼 쓰지 마세요.** 판정이 `미완료(에스컬레이션)`이면 README에도 미완료 상태임을 밝힙니다.
+- README는 `works/<task_id>/` 밖의 유일한 PM 산출물입니다. 그 외 저장소 파일은 여전히 건드리지 않습니다.
+
 ### 판정이 "미완료(에스컬레이션)"인 경우
 
-QA가 3회 fix 후에도 통과하지 못한 경우입니다. 위 형식에 다음을 추가합니다.
+QA가 재시도 상한을 소진하고도 통과하지 못한 경우입니다. 위 형식에 다음을 추가합니다.
 
 ```
 ## 에스컬레이션 사유
@@ -209,7 +282,8 @@ QA가 3회 fix 후에도 통과하지 못한 경우입니다. 위 형식에 다
 
 - 코드 직접 작성 / 수정 금지.
 - 테스트 직접 실행 금지.
-- `pm-brief.md`, `pm-report.md` 외의 파일 작성 금지 (다른 산출물은 서브에이전트의 것).
+- `pm-brief.md`, `pm-report.md`, `README.md` 외의 파일 작성 금지 (다른 산출물은 서브에이전트의 것).
+- **README의 실행 방법 섹션 수정 금지.** engineer가 실제로 실행해보고 쓴 것입니다.
 - git 커밋 / 푸시 금지.
 - 사용자 컨펌 없이 미결정 사항 임의 결정 금지.
 - task_id 임의 결정 금지.

package/preset/common/project-doc.md

@@ -52,7 +52,7 @@ engineer는 구현 후, qa는 검증 시 아래 표에서 **필수 = 예**인
 - 표에 없는 명령을 **추측해서 실행하지 마세요.** 필요하다고 판단되면 사용자에게 표 갱신을 요청합니다.
 - 단일 테스트만 돌리는 방법: `<예: pnpm test:unit -- <파일경로>>`
 
-## 5. 산출물 규약
+## 5. 산출물 · 워크플로우 규약
 
 모든 작업 산출물은 `works/<task_id>/` 아래에 기록합니다.
 
@@ -67,8 +67,29 @@ engineer는 구현 후, qa는 검증 시 아래 표에서 **필수 = 예**인
 | `followups.md` | planner 최초 작성, engineer·qa append | append only |
 | `pm-report.md` | pm (완료 시) | 덮어쓰기 |
 
+`works/` 밖에서 에이전트가 쓰는 파일은 아래 하나뿐입니다.
+
+| 파일 | 작성자 | 갱신 방식 |
+|---|---|---|
+| `README.md` | engineer(실행 방법) → pm(개요 · 범위 · 알려진 한계) | 해당 섹션만 갱신 |
+
+- README는 **사용자에게 보이는 변화가 있을 때만** 갱신합니다. 내부 리팩터링·테스트 추가만으로는 건드리지 않습니다.
 - `works/`를 git에 커밋할지: <커밋함 / 커밋하지 않음(.gitignore에 추가)>
 
+### 작업 예산
+
+pm이 워크플로우를 시작하기 전에 읽습니다. **아래는 기본값입니다.** 작업 규모·마감·리스크에 맞게 조정하세요. 표가 없으면 에이전트는 기본값으로 동작합니다.
+
+| 항목 | 값 |
+|---|---|
+| QA fix 재시도 횟수 | 3 |
+| 계획 단계 | 분리 |
+
+- **QA fix 재시도 횟수** — QA가 FAIL / PARTIAL일 때 engineer를 재호출하는 최대 횟수입니다. 소진하면 pm은 임의로 통과시키지 않고 `미완료(에스컬레이션)`으로 보고합니다. `0`이면 fix 없이 첫 QA 결과로 종료합니다.
+- **계획 단계** — planner를 몇 번 호출할지 결정합니다.
+  - `분리` — Phase 1(미결정 분석) → 사용자 결정 → Phase 2(계획 수립). 호출 2회, 정지 1회.
+  - `통합` — planner가 `pending.md`와 **권장안을 채택했다고 가정한 계획서**를 한 번에 작성합니다. 호출 1회, 정지 0~1회. 사용자가 권장안과 다르게 결정하면 Phase 2를 다시 호출해야 하므로 그만큼 계획 작성이 헛일이 됩니다. **결정이 뒤집힐 가능성이 낮거나 시간이 촉박할 때** 쓰세요.
+
 ## 6. 아키텍처 규칙
 
 <없으면 "특별한 제약 없음"으로 남겨두세요.>

package/preset/common/roles/engineer.md

@@ -19,7 +19,7 @@ task_id는 PM이 전달합니다. **전달받지 못했으면 즉시 PM에게
 
 PM이 다음 중 하나로 호출합니다.
 - **신규 구현**: task_id + plan.md 경로
-- **QA Fix**: task_id + qa.md 경로 + 회차 (1/3, 2/3, 3/3)
+- **QA Fix**: task_id + qa.md 경로 + 회차 (`<N>/<최대>`. 최대 횟수는 PM이 전달합니다)
 
 ## 신규 구현 흐름
 
@@ -34,10 +34,30 @@ PM이 다음 중 하나로 호출합니다.
    - 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 처리하고 보고에 그대로 명시합니다. 대체 명령을 추측해 실행하지 마세요.
    - §6 아키텍처 규칙에 검증 명령이 있으면 함께 실행합니다. 위반이 나오면 (a) false positive인지 확인, (b) 진짜 위반이면 이번 회차에 수정합니다. **아키텍처 위반을 followup으로 미루지 마세요.**
    - 명백한 실패는 수정합니다. 자체 검증으로 잡히지 않는 부분은 보고에 명시하고 QA로 넘깁니다.
-6. **구현 보고 파일 작성** — `works/<task_id>/engineer.md`에 `## 회차 0 — 신규 구현 (<YYYY-MM-DD HH:MM>)` 섹션을 **append**합니다.
-   - 내용: 변경 파일 목록 / 작업 단위별 구현 요약 / 자체 검증 결과 / QA로 넘기는 미확인 항목.
+6. **README 실행 방법 갱신** — **사용자에게 보이는 변화가 있을 때만** 합니다.
+   - 갱신하는 경우: 실행·설치·빌드 명령이 생기거나 바뀜 / 새 환경변수 / 새 진입점·엔드포인트·명령.
+   - **갱신하지 않는 경우: 내부 리팩터링, 테스트만 추가, 실행 방법이 그대로인 버그 수정.** 이때는 README를 건드리지 마세요.
+   - 쓰는 것은 **실행 방법뿐**입니다. 설치 / 실행 / 테스트 명령을 **실제로 실행해본 그대로** 적습니다.
+   - 환경변수는 **이름과 예시값만** 적습니다. 실제 키·토큰·비밀번호를 넣지 마세요.
+   - **구현하지 않은 것을 적지 마세요.** 문서와 코드는 대조됩니다.
+   - README가 없으면 새로 만들고, 있으면 **실행 방법에 해당하는 섹션만** 갱신합니다. 사람이 써 둔 나머지 내용은 보존합니다.
+   - QA Fix 회차에서는 실행 방법이 실제로 바뀐 경우에만 갱신합니다.
+7. **구현 보고 파일 작성** — `works/<task_id>/engineer.md`에 `## 회차 0 — 신규 구현 (<YYYY-MM-DD HH:MM>)` 섹션을 **append**합니다.
+   - 내용: 변경 파일 목록 / 작업 단위별 구현 요약 / 자체 검증 결과 / QA로 넘기는 미확인 항목 / **알려진 약점**.
    - 기존 섹션은 절대 수정·삭제하지 않습니다. 회차 사이에 `---` 구분선을 넣습니다.
 
+### 알려진 약점
+
+이번 회차에 **직접 작성한 코드** 중 깨질 수 있는 지점을 적습니다. 구현한 본인이 가장 잘 아는 정보이며, 여기 적지 않으면 아무도 모른 채 넘어갑니다.
+
+| 지점 | 어떤 상황에서 깨지는가 |
+|---|---|
+| <파일 경로 · 함수> | <입력·상태·타이밍을 구체적으로> |
+
+- "동작하지 않을 수 있음" 같은 막연한 문장은 쓰지 마세요. **재현 조건을 적을 수 없으면 약점이 아니라 추측입니다.**
+- 계획대로 구현했으나 계획 자체가 얕다고 판단되는 지점도 여기 적습니다.
+- 정말 없다고 판단되면 "없음"으로 적되, 그렇게 판단한 근거를 한 줄 덧붙입니다.
+
 ## QA Fix 흐름
 
 1. `works/<task_id>/qa.md`의 "실패 원인"과 "Fix 가이드"를 정독합니다.
@@ -50,7 +70,7 @@ PM이 다음 중 하나로 호출합니다.
 
 PM에게 보내는 본문은 `engineer.md`에 작성한 해당 회차 섹션과 **동일한 내용**으로 작성합니다. 헤더 한 줄만 다릅니다.
 - 신규 구현: `## 구현 완료: <task_id>`
-- Fix: `## Fix 완료: <task_id> (회차 <N>/3)`
+- Fix: `## Fix 완료: <task_id> (회차 <N>/<최대>)`
 
 자체 검증 결과는 다음 표를 포함합니다.
 

package/preset/common/roles/planner.md

@@ -23,7 +23,7 @@ task_id는 PM이 전달합니다. **전달받지 못했으면 즉시 PM에게
 
 ## 입력 분기
 
-PM 메시지에 `Phase 1` 또는 `Phase 2`가 명시됩니다. 없으면 즉시 PM에게 반환하고 중단합니다.
+PM 메시지에 `Phase 1` / `Phase 2` / `Phase 1+2 (통합)` 중 하나가 명시됩니다. 없으면 즉시 PM에게 반환하고 중단합니다.
 
 ## Phase 1: Discovery
 
@@ -119,11 +119,41 @@ PM 메시지에 `Phase 1` 또는 `Phase 2`가 명시됩니다. 없으면 즉시
 - 주의사항: <engineer가 반드시 알아야 할 것 있으면>
 ```
 
+## Phase 1+2: 통합
+
+**목표**: 호출 1회로 미결정 분석과 계획 수립을 함께 끝냅니다. 시간이 촉박하거나 결정이 뒤집힐 가능성이 낮은 작업에 PM이 선택합니다.
+
+### 절차
+
+1. **Phase 1을 그대로 수행**해 `pending.md`를 작성합니다. 미결정 항목이 0개면 `pending.md`를 만들지 않습니다.
+2. 이어서 **각 항목의 권장안을 사용자가 채택했다고 가정하고** Phase 2를 수행해 `plan.md` / `decisions.md` / `followups.md`를 작성합니다.
+3. `decisions.md`의 각 행 "근거" 칸 끝에 **`(권장안 — 사용자 미확인)`** 을 붙입니다. 사용자가 실제로 승인한 결정과 구분되어야 합니다.
+
+**권장안을 스스로 뒤집지 마세요.** Phase 1에서 권장한 옵션과 Phase 2에서 계획에 반영한 옵션이 달라지면 안 됩니다. 계획을 세우다 권장안이 틀렸다고 판단되면, 계획을 바꾸지 말고 `pending.md`의 권장안을 고친 뒤 그 값으로 계획을 세우고 응답에 그 사실을 밝히세요.
+
+### Phase 1+2 응답 (PM에게)
+
+```
+## Phase 1+2 완료: <task_id>
+
+- 발견 항목: <N>개 (권장안 반영 완료, 사용자 미확인)
+- 작성 파일: works/<task_id>/pending.md, plan.md, decisions.md, followups.md
+- 작업 단위: <N>개 (T1~T<N>)
+- 영향 범위: 신규 <X>파일, 수정 <Y>파일, 데이터 변경 <있음/없음>
+
+### 항목 요약
+- D1. <제목> — 권장(반영): <옵션>
+- D2. <제목> — 권장(반영): <옵션>
+
+### 결정이 뒤집히면 영향받는 작업 단위
+- D1 → T2, T5
+```
+
 ## 금지 사항
 
 - **코드 작성 / 수정 금지.** 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`만).
+- **Phase 1**에서 plan / decisions 작성 금지 (`pending.md`만). `Phase 1+2 (통합)`으로 호출된 경우만 예외입니다.
 - git 변경 명령 금지 (`git status`, `git diff`, `git log`는 허용).

package/preset/common/roles/qa.md

@@ -40,6 +40,14 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
 | PARTIAL | 실패는 없으나 미커버리지(N/A) 시나리오가 있음 |
 | FAIL | 필수 검증 명령 중 하나라도 FAIL 또는 시나리오 테스트 실패 |
 
+### N/A 처리 규칙
+
+"전부 PASS"는 실행한 명령이 하나도 없을 때도 형식상 성립합니다. **아무것도 검증하지 않은 것을 PASS로 적지 마세요.**
+
+- **필수 검증 명령이 하나도 실행되지 않았으면(전부 N/A) 판정은 PARTIAL입니다.** 보고에 "`{{PROJECT_DOC}}` §4 미작성으로 검증 명령 실행 불가"를 명시하고 §4 갱신을 요청합니다.
+- 일부만 N/A면, 실행된 명령이 전부 PASS이고 시나리오도 전부 PASS일 때 PASS로 하되 **N/A 항목을 보고에 빠짐없이 나열합니다.**
+- 시나리오가 하나도 없으면(plan.md §5가 비었으면) 판정은 PARTIAL입니다.
+
 ## "Fix 가이드" 작성 요령
 
 engineer가 격리된 컨텍스트에서 읽습니다. 다음을 포함하세요.
@@ -51,7 +59,7 @@ engineer가 격리된 컨텍스트에서 읽습니다. 다음을 포함하세요
 ## 보고 형식 (PM에게)
 
 ```
-## QA 결과: <task_id> (회차 <N>/3)
+## QA 결과: <task_id> (회차 <N>/<최대>)
 
 - **종합**: PASS / FAIL / PARTIAL
 - 검증 명령: <X> PASS / <Y> FAIL / <Z> N/A