spr-ai-native 0.2.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)로 개발할 때 쓰는 **개발 규칙 문서와 서브에이전트 프리셋**을 현재 프로젝트에 생성하는 CLI입니다.
 
-생성되는 것은 `pm` → `planner` → `engineer` → `qa` 4개 역할로 구성된 개발 워크플로우입니다. 프로젝트 스택에 종속되지 않는 범용 프리셋이며, 스택·검증 명령·금지 사항은 생성된 프로젝트 지침 문서에 직접 작성해 채웁니다.
+생성되는 것은 `pm` → `planner` → `engineer` → `qa` 4개 역할로 구성된 개발 워크플로우입니다. 프로젝트 스택에 종속되지 않는 범용 프리셋이며, 스택·검증 항목·금지 사항은 생성된 프로젝트 지침 문서에 채웁니다.
 
 ## 사용법
 
@@ -103,17 +103,25 @@ Cursor는 전역 규칙을 파일로 두지 않고 Settings > Rules > User Rules
 
 ## 생성 직후 해야 할 일
 
-프로젝트 지침 문서(`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/10-project.mdc`)의 `<...>` 플레이스홀더를 채우세요. 특히 **§4 검증 명령**은 `engineer`와 `qa`가 그대로 실행하는 계약입니다.
+프로젝트 지침 문서(`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/10-project.mdc`)의 `<...>` 플레이스홀더를 채우세요.
+
+**§4 검증 항목의 명령 칸은 비워둬도 됩니다.**
 
 ```markdown
-| 목적 | 명령 | 필수 |
+| 항목 | 실행 | 명령 |
 |---|---|---|
-| 린트 | `pnpm lint` | 예 |
-| 타입 체크 | `pnpm typecheck` | 예 |
-| 단위 테스트 | `pnpm test:unit` | 예 |
+| 린트 | 필수 | |
+| 타입 체크 | 필수 | |
+| 단위 테스트 | 필수 | |
+| 통합 테스트 | 선택 | |
+| 포맷 검사 | 안 함 | |
 ```
 
-비어 있는 행은 에이전트가 **N/A로 보고**하며, 대체 명령을 추측해 실행하지 않습니다. 검증이 조용히 생략되는 것보다 N/A로 드러나는 편이 안전하기 때문입니다.
+사람이 정하는 것은 **`실행`(필수 / 선택 / 안 함)** 뿐입니다. "이 프로젝트가 무엇을 검증해야 하는가"는 사람의 판단이고, "그 명령이 무엇인가"는 프로젝트 설정에 이미 적혀 있는 사실이기 때문입니다.
+
+명령 칸이 비어 있으면 `engineer`가 매니페스트·CI 설정·도구 설정에서 **근거를 찾아** 실행하고, 찾은 명령을 §4 표에 적어 넣습니다. 다음 회차부터는 다시 찾지 않습니다. `qa`는 표를 고치지 않고 찾은 명령을 `qa.md`에 기록만 합니다.
+
+**근거를 못 찾으면 실행하지 않고 N/A로 보고합니다.** "아마 이 명령일 것"은 발견이 아니라 추측이며, 검증이 조용히 생략되는 것보다 N/A로 드러나는 편이 안전하기 때문입니다. 감시(watch) 모드로 도는 명령과 코드를 자동 수정하는 옵션이 붙은 명령도 같은 이유로 실행하지 않습니다.
 
 ## 워크플로우
 
@@ -133,7 +141,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 +168,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 +198,7 @@ brief에 들어가지 않는 것: 구현 방법, 파일 목록, 작업 단위,
 | 없음 | 착수 브리프 작성 |
 | `pm-brief.md` | planner Phase 1 |
 | `pm-brief.md` + `pending.md` | 결정 회신 대기 (회신과 함께 호출하면 Phase 2) |
+| `plan.md`가 있으면 (위 조건보다 우선) | engineer부터. planner를 다시 부르지 않습니다 |
 
 ### 산출물
 
@@ -181,7 +211,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 +220,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 +247,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/bin/cli.js

@@ -111,7 +111,7 @@ function main(argv) {
 
   console.log('\n다음 단계');
   console.log(
-    `  1. 프로젝트 지침 문서의 플레이스홀더(<...>)를 채우세요. 특히 §4 검증 명령은 engineer/qa가 그대로 실행합니다.`
+    `  1. 프로젝트 지침 문서의 플레이스홀더(<...>)를 채우세요. §4 검증 항목의 명령 칸은 비워두면 에이전트가 찾아 채웁니다.`
   );
   for (const [i, note] of notes.entries()) console.log(`  ${i + 2}. ${note}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spr-ai-native",
-  "version": "0.2.0",
+  "version": "0.4.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

@@ -1,7 +1,8 @@
 <!--
   이 문서는 spr-ai-native가 생성한 템플릿입니다.
   각 섹션의 <> 플레이스홀더를 프로젝트 실제 값으로 채우세요.
-  §4 "검증 명령"은 engineer / qa 서브에이전트가 그대로 실행하는 계약입니다. 반드시 채우세요.
+  §4 "검증 항목"의 명령 칸은 비워둬도 됩니다. 에이전트가 프로젝트 설정에서 찾아 채웁니다.
+  다만 `실행`(필수 / 선택 / 안 함)은 사람이 정하세요. 이 프로젝트가 무엇을 검증해야 하는지의 계약입니다.
 -->
 
 # 프로젝트 개발 지침
@@ -34,25 +35,49 @@ tests/
   integration/
 ```
 
-## 4. 검증 명령
+## 4. 검증 항목
 
-engineer는 구현 후, qa는 검증 시 아래 표에서 **필수 = 예**인 명령을 모두 실행합니다.
+engineer는 구현 후, qa는 검증 시 아래 항목을 수행합니다. **명령 칸은 비워둬도 됩니다.** 비어 있으면 에이전트가 프로젝트 설정에서 실제 명령을 찾아 실행하고, 찾은 명령을 이 표에 적어 넣습니다.
 
-| 목적 | 명령 | 필수 |
+| 항목 | 실행 | 명령 |
 |---|---|---|
-| 린트 | `<예: pnpm lint>` | 예 |
-| 타입 체크 | `<예: pnpm typecheck>` | 예 |
-| 단위 테스트 | `<예: pnpm test:unit>` | 예 |
-| 통합 테스트 | `<예: pnpm test:integration>` | 아니오 |
-| 포맷 검사 | `<예: pnpm format:check>` | 아니오 |
-| 빌드 | `<예: pnpm build>` | 아니오 |
+| 린트 | 필수 | |
+| 타입 체크 | 필수 | |
+| 단위 테스트 | 필수 | |
+| 통합 테스트 | 선택 | |
+| 빌드 | 선택 | |
+| 포맷 검사 | 안 함 | |
+| 단일 테스트 실행 | — | |
 
-**규칙**
-- 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 처리하고, 보고서에 N/A로 명시합니다.
-- 표에 없는 명령을 **추측해서 실행하지 마세요.** 필요하다고 판단되면 사용자에게 표 갱신을 요청합니다.
-- 단일 테스트만 돌리는 방법: `<예: pnpm test:unit -- <파일경로>>`
+**`실행` 값**
 
-## 5. 산출물 규약
+| 값 | 의미 |
+|---|---|
+| `필수` | 실행하고, 실패하면 FAIL |
+| `선택` | 실행하되 실패는 보고만 (판정에 반영하지 않음) |
+| `안 함` | 실행하지 않음. 이 프로젝트에 해당 없음 |
+
+`단일 테스트 실행`은 판정 항목이 아니라 engineer가 반복 실행에 쓰는 명령입니다.
+
+### 명령을 찾는 방법
+
+명령 칸이 비어 있으면 아래 순서로 **근거를 찾아** 채웁니다.
+
+1. 패키지 매니페스트 · 태스크 러너에 정의된 스크립트
+2. CI 설정이 실행하는 명령
+3. 해당 도구의 설정 파일이 있으면, 그 도구의 표준 실행 방법
+
+**찾은 명령은 이 표에 적어 넣습니다.** 다음 회차부터는 다시 찾지 않습니다.
+
+### 찾을 때 지켜야 할 것
+
+- **근거가 없으면 실행하지 않습니다.** "아마 이 명령일 것"은 발견이 아니라 추측입니다. 근거를 못 찾으면 **N/A**로 보고하고 사용자에게 표 갱신을 요청하세요.
+- **끝나지 않는 명령(감시 모드)을 그대로 쓰지 마세요.** 1회 실행 옵션을 확인하고, 없으면 N/A로 보고합니다.
+- **코드를 자동 수정하는 옵션이 붙은 명령을 쓰지 마세요.** 검사만 하는 형태를 찾고, 없으면 N/A로 보고합니다. qa는 코드 수정이 금지되어 있습니다.
+- 외부 서비스 · 자격증명이 없어 실패한 경우는 FAIL이 아니라 **N/A(환경 미비)** 로 보고합니다.
+- 어디서 찾았는지(파일 · 위치)를 보고에 남깁니다.
+
+## 5. 산출물 · 워크플로우 규약
 
 모든 작업 산출물은 `works/<task_id>/` 아래에 기록합니다.
 
@@ -67,8 +92,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

@@ -9,7 +9,7 @@ description: planner가 작성한 계획에 따라 코드와 테스트를 구현
 
 ## 먼저 읽어야 할 것
 
-1. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, **§4 검증 명령**, §6 아키텍처 규칙, §7 금지 사항, §8 컨벤션.
+1. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, **§4 검증 항목**, §6 아키텍처 규칙, §7 금지 사항, §8 컨벤션.
 2. `works/<task_id>/plan.md` — 정독. §3 작업 단위와 §5 테스트 전략이 구현 계약입니다.
 3. `works/<task_id>/decisions.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이 전달합니다)
 
 ## 신규 구현 흐름
 
@@ -30,19 +30,41 @@ PM이 다음 중 하나로 호출합니다.
    - 스키마 변경이 필요하면 plan.md §4에 따라 마이그레이션을 작성합니다.
    - **테스트 코드 작성** — plan.md §5 테스트 전략의 시나리오를 실제 테스트 코드로 옮깁니다. 계획에 있는 시나리오를 빠뜨리지 마세요.
 4. 구현 중 발견한 추후 항목은 `works/<task_id>/followups.md`에 **append**합니다 (`발생 단계: engineering`). 기존 행은 보존하고 새 행만 추가합니다.
-5. **자체 검증** — `{{PROJECT_DOC}}` §4 검증 명령 표에서 **필수 = 예**인 명령을 모두 실행합니다.
-   - 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 처리하고 보고에 그대로 명시합니다. 대체 명령을 추측해 실행하지 마세요.
+5. **자체 검증** — `{{PROJECT_DOC}}` §4 검증 항목 표에서 `실행`이 **필수**인 항목을 모두 수행합니다. `선택`도 가능하면 수행하되 실패는 보고만 합니다.
+   - **명령 칸이 비어 있으면 §4 "명령을 찾는 방법"에 따라 프로젝트 설정에서 찾고, 찾은 명령을 §4 표에 적어 넣습니다.** 이 표 갱신은 계획 범위 외 변경이 아닙니다.
+   - **근거를 찾지 못하면 N/A로 보고합니다.** 대체 명령을 추측해 실행하지 마세요. 감시 모드로 도는 명령, 코드를 자동 수정하는 옵션이 붙은 명령도 쓰지 않고 N/A로 처리합니다.
+   - 외부 서비스·자격증명이 없어 실패한 항목은 FAIL이 아니라 **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 가이드"를 정독합니다.
 2. **실패한 시나리오만 타겟팅해 수정합니다. plan.md 범위 외 변경 금지.**
-3. 자체 검증 — 수정 범위에 해당하는 테스트 재실행 + `{{PROJECT_DOC}}` §4의 필수 명령. §6 아키텍처 검증 명령이 있으면 함께 실행하고 위반은 이번 회차에 해결합니다.
+3. 자체 검증 — 수정 범위에 해당하는 테스트 재실행 + `{{PROJECT_DOC}}` §4의 `필수` 항목. §6 아키텍처 검증 명령이 있으면 함께 실행하고 위반은 이번 회차에 해결합니다.
 4. `works/<task_id>/engineer.md`에 `## 회차 <N> — Fix (<YYYY-MM-DD HH:MM>)` 섹션을 **append**합니다. 기존 회차 섹션은 절대 수정·삭제하지 않습니다.
 5. PM에게 fix 완료 보고.
 
@@ -50,16 +72,16 @@ PM이 다음 중 하나로 호출합니다.
 
 PM에게 보내는 본문은 `engineer.md`에 작성한 해당 회차 섹션과 **동일한 내용**으로 작성합니다. 헤더 한 줄만 다릅니다.
 - 신규 구현: `## 구현 완료: <task_id>`
-- Fix: `## Fix 완료: <task_id> (회차 <N>/3)`
+- Fix: `## Fix 완료: <task_id> (회차 <N>/<최대>)`
 
 자체 검증 결과는 다음 표를 포함합니다.
 
 ```
-| 목적 | 명령 | 결과 |
-|---|---|---|
-| 린트 | <실행한 명령> | PASS / FAIL / N/A |
-| 타입 체크 | <실행한 명령> | PASS / FAIL / N/A |
-| 단위 테스트 | <실행한 명령> | PASS / FAIL / N/A |
+| 항목 | 실행한 명령 | 출처 | 결과 |
+|---|---|---|---|
+| 린트 | <명령> | <§4 기입 / 찾은 파일·위치> | PASS / FAIL / N/A |
+| 타입 체크 | <명령> | | PASS / FAIL / N/A |
+| 단위 테스트 | <명령> | | PASS / FAIL / N/A |
 ```
 
 ## 금지 사항

package/preset/common/roles/planner.md

@@ -12,7 +12,7 @@ description: 작업을 분석하고 구현 계획을 작성합니다. 코드는
 1. **`works/<task_id>/pm-brief.md`** — PM이 작성하고 사용자가 확인한 착수 브리프. **작업 정의의 유일한 근거**입니다. 목표 / 배경 / 범위(포함·제외) / 참고 자료 / 확인 필요 항목이 들어 있습니다.
    - **"범위: 제외" 항목을 계획에 넣지 마세요.** 의도적으로 이번 범위에서 빠진 것입니다. 필요하다고 판단되면 `followups.md`에만 기록합니다.
    - 이 파일이 없으면 즉시 PM에게 반환하고 중단합니다. 작업 정의를 추측하지 마세요.
-2. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, §4 검증 명령, §6 아키텍처 규칙, §7 금지 사항.
+2. `{{PROJECT_DOC}}` — §2 기술 스택, §3 디렉터리 구조, §4 검증 항목, §6 아키텍처 규칙, §7 금지 사항.
    - 이 문서가 없거나 플레이스홀더(`<...>`)만 남아 있으면, 계획서에 "프로젝트 지침 미작성"을 명시하고 확인 가능한 사실만으로 계획을 세웁니다. 스택을 추측하지 마세요.
 3. brief의 "참고 자료"에 적힌 문서들.
 
@@ -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
 
@@ -94,7 +94,7 @@ PM 메시지에 `Phase 1` 또는 `Phase 2`가 명시됩니다. 없으면 즉시
 - §2 영향 범위 — 신규 / 수정 파일 목록 (경로 단위).
 - §3 작업 단위 — `T1`~`Tn`. 각 항목에 **무엇을 / 어디에 / 완료 판정 기준**.
 - §4 데이터 · 마이그레이션 — 스키마 변경이 있으면. 없으면 "없음".
-- §5 테스트 전략 — 시나리오별로 **어느 파일에 어떤 테스트가 있어야 하는지** 매핑. `{{PROJECT_DOC}}` §4의 테스트 명령을 그대로 인용합니다.
+- §5 테스트 전략 — 시나리오별로 **어느 파일에 어떤 테스트가 있어야 하는지** 매핑. `{{PROJECT_DOC}}` §4에서 이 작업에 해당하는 검증 항목을 밝힙니다. 명령이 비어 있으면 항목 이름만 적고, 명령을 지어내지 마세요.
 - §6 비고 — 리스크, 롤백 방법, 범위 외 항목.
 
 ### `decisions.md` 권장 구조
@@ -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

@@ -9,7 +9,7 @@ description: engineer가 구현한 코드와 테스트를 실행해 검증합니
 
 ## 먼저 읽어야 할 것
 
-1. `{{PROJECT_DOC}}` — **§4 검증 명령**, §6 아키텍처 규칙.
+1. `{{PROJECT_DOC}}` — **§4 검증 항목**, §6 아키텍처 규칙.
 2. `works/<task_id>/plan.md` — §5 테스트 전략. 어느 시나리오가 어느 파일에 있어야 하는지의 기준입니다.
 3. `works/<task_id>/engineer.md` — 최신 회차 섹션. 변경 파일과 engineer가 QA로 넘긴 미확인 항목.
 
@@ -17,9 +17,12 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
 
 ## 검증 절차
 
-1. `{{PROJECT_DOC}}` §4 검증 명령 표의 명령을 실행합니다.
-   - **필수 = 예**인 명령은 전부 실행합니다. 선택 항목도 가능하면 실행합니다.
-   - 명령 칸이 비어 있거나 플레이스홀더 그대로인 행은 **N/A**로 기록합니다. **대체 명령을 추측해 실행하지 마세요.**
+1. `{{PROJECT_DOC}}` §4 검증 항목을 수행합니다.
+   - `실행`이 **필수**인 항목은 전부 수행합니다. **선택**도 가능하면 수행하되, 실패해도 판정에 반영하지 않고 보고만 합니다. **안 함**은 건너뜁니다.
+   - 명령 칸이 비어 있으면 §4 "명령을 찾는 방법"에 따라 찾아 실행하고, **어디서 찾았는지를 `qa.md`에 남깁니다.** engineer가 이미 채워 두었으면 그 명령을 그대로 씁니다.
+   - **근거를 못 찾으면 N/A로 기록합니다. 대체 명령을 추측해 실행하지 마세요.** 감시 모드로 도는 명령, 코드를 자동 수정하는 옵션이 붙은 명령도 실행하지 않고 N/A로 기록합니다.
+   - 외부 서비스·자격증명이 없어 실패한 항목은 FAIL이 아니라 **N/A(환경 미비)** 로 기록합니다.
+   - **§4 표를 직접 고치지 않습니다.** 비어 있던 항목은 `qa.md`에 찾은 명령을 적고 사용자에게 §4 기입을 요청합니다.
    - §6에 아키텍처 검증 명령이 있으면 실행하고, 결과를 PASS / FAIL / false-positive로 분류합니다.
 2. plan.md §5의 시나리오별로 다음을 확인합니다.
    - 대응 테스트가 **실제로 존재하는가** (Grep으로 파일·테스트명 확인)
@@ -27,7 +30,7 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
    - 대응 테스트가 없으면 **N/A(미커버리지)** 로 표시하고 followup에 기록합니다. 테스트가 없는 것을 PASS로 처리하지 마세요.
 3. `works/<task_id>/qa.md`를 작성합니다 (회차마다 덮어쓰기). 권장 구조:
    - 종합 판정 (PASS / FAIL / PARTIAL)
-   - 검증 명령 결과 표 (목적 / 실행한 명령 / 결과)
+   - 검증 항목 결과 표 (항목 / 실행한 명령 / 출처 / 결과)
    - 시나리오별 결과 표 (시나리오 / 대응 테스트 / 결과)
    - 실패가 있으면 **"실패 원인"** 과 **"Fix 가이드"** 섹션 추가. 없으면 생략합니다.
 4. 발견한 추후 개선 사항은 `works/<task_id>/followups.md`에 **append**합니다 (`발생 단계: qa`).
@@ -36,9 +39,19 @@ task_id와 회차는 PM이 전달합니다. **전달받지 못했으면 즉시 P
 
 | 판정 | 조건 |
 |---|---|
-| PASS | 필수 검증 명령 전부 PASS + 모든 시나리오에 대응 테스트 존재 및 PASS |
+| PASS | `필수` 항목 전부 PASS + 모든 시나리오에 대응 테스트 존재 및 PASS |
 | PARTIAL | 실패는 없으나 미커버리지(N/A) 시나리오가 있음 |
-| FAIL | 필수 검증 명령 중 하나라도 FAIL 또는 시나리오 테스트 실패 |
+| FAIL | `필수` 항목 중 하나라도 FAIL 또는 시나리오 테스트 실패 |
+
+`선택` 항목의 실패는 판정을 FAIL로 만들지 않습니다. 결과는 그대로 보고합니다.
+
+### N/A 처리 규칙
+
+"전부 PASS"는 실행한 명령이 하나도 없을 때도 형식상 성립합니다. **아무것도 검증하지 않은 것을 PASS로 적지 마세요.**
+
+- **`필수` 항목이 하나도 실행되지 않았으면(전부 N/A) 판정은 PARTIAL입니다.** 보고에 왜 실행하지 못했는지(근거 없음 / 도구 없음 / 환경 미비)를 항목별로 명시하고 `{{PROJECT_DOC}}` §4 갱신을 요청합니다.
+- 일부만 N/A면, 실행된 항목이 전부 PASS이고 시나리오도 전부 PASS일 때 PASS로 하되 **N/A 항목과 그 사유를 보고에 빠짐없이 나열합니다.**
+- 시나리오가 하나도 없으면(plan.md §5가 비었으면) 판정은 PARTIAL입니다.
 
 ## "Fix 가이드" 작성 요령
 
@@ -51,10 +64,10 @@ engineer가 격리된 컨텍스트에서 읽습니다. 다음을 포함하세요
 ## 보고 형식 (PM에게)
 
 ```
-## QA 결과: <task_id> (회차 <N>/3)
+## QA 결과: <task_id> (회차 <N>/<최대>)
 
 - **종합**: PASS / FAIL / PARTIAL
-- 검증 명령: <X> PASS / <Y> FAIL / <Z> N/A
+- 검증 항목: <X> PASS / <Y> FAIL / <Z> N/A
 - 시나리오: <X> PASS / <Y> FAIL / <Z> N/A(미커버리지)
 - 결과 문서: works/<task_id>/qa.md
 - 추가된 followup: F<N>, F<N+1> (있을 때만)

package/src/targets/cursor.js

@@ -38,7 +38,7 @@ export function apply({ writer, cwd, useGlobal }) {
   writer.write(
     join(cwd, '.cursor', 'rules', '10-project.mdc'),
     `${frontmatter([
-      ['description', quoted('프로젝트 개요 · 기술 스택 · 검증 명령 · 산출물 규약')],
+      ['description', quoted('프로젝트 개요 · 기술 스택 · 검증 항목 · 산출물 규약')],
       ['alwaysApply', 'true'],
     ])}\n${readPreset('project-doc.md').trim()}\n`
   );