spr-ai-native 0.3.0 → 0.5.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) 모드로 도는 명령과 코드를 자동 수정하는 옵션이 붙은 명령도 같은 이유로 실행하지 않습니다.
 
 ## 워크플로우
 
@@ -219,7 +227,7 @@ works/<task_id>/
 
 - **PM은 서브에이전트가 아니라 메인 세션의 역할**입니다. `/pm`으로 진입하면 그 세션이 PM이 되어 나머지 3개에게 위임합니다. 서브에이전트가 다시 서브에이전트를 호출하는 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다. 다만 도구 권한으로 PM의 코드 수정을 차단할 수 없어 프롬프트 규율에만 의존합니다 — 중첩 위임 의존성을 없애기 위한 트레이드오프입니다.
 - **task_id는 사용자에게 확인받습니다.** PM이 git 브랜치명에서 후보를 제안하지만 확정은 사용자가 합니다. 디렉터리명이 되므로 `/`나 공백이 들어가면 되묻습니다.
-- QA가 재시도 상한을 소진하고도 FAIL이면 임의로 통과시키지 않고, `pm-report.md`에 `판정: 미완료(에스컬레이션)`으로 기록한 뒤 사용자에게 넘깁니다.
+- **engineer fix 재호출은 최대 3회**입니다 (engineer 호출 최대 4회, qa 호출 최대 4회). 3회 fix 후에도 FAIL이면 임의로 통과시키지 않고, `pm-report.md`에 `판정: 미완료(에스컬레이션)`으로 기록한 뒤 사용자에게 넘깁니다. fix 루프 없이 검증만 받고 싶으면 `/engineer` → `/qa`를 쓰세요.
 
 ### 어느 진입점을 쓸까
 
@@ -241,19 +249,6 @@ works/<task_id>/
 
 개별 커맨드는 해당 서브에이전트만 호출하는 얇은 래퍼입니다. 브리프 게이트도, 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.3.0",
+  "version": "0.5.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>/<최대>`)를 전달합니다. 최대 횟수는 프로젝트 지침 §5 작업 예산의 **QA fix 재시도 횟수**(기본 3)입니다. 회차는 `engineer.md`의 기존 회차 섹션 수를 보고 계산합니다.
+  - **QA Fix** — 입력에 `fix`가 있거나 `works/<task_id>/qa.md`가 FAIL/PARTIAL이면, `qa.md` 경로와 회차(`<N>/3`)를 전달합니다. 회차는 `engineer.md`의 기존 회차 섹션 수를 보고 계산합니다.
 - 다음 지시를 함께 전달합니다: 구현 보고를 `works/<task_id>/engineer.md`에 회차별 append, **git 커밋/푸시 금지**.
 
 ## 이후 처리

package/preset/common/commands/pm.md

@@ -35,12 +35,6 @@ argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
 - task_id는 디렉터리명이 됩니다. `/`, 공백, 그 외 경로에 쓸 수 없는 문자가 포함되면 그대로 쓰지 말고 사용자에게 되묻습니다.
 - **임의로 정하지 마세요.**
 
-### 작업 예산 확인
-
-`{{PROJECT_DOC}}` §5의 **작업 예산** 표를 읽어 이번 워크플로우의 동작을 결정합니다. 표가 없거나 값이 비어 있으면 **QA fix 재시도 3회 / 계획 단계 분리**로 간주합니다.
-
-읽은 값은 1단계 보고에 한 줄로 밝힙니다. 예: `작업 예산: fix 2회 / 계획 단계 통합`
-
 ## 작업 모드 판단
 
 `works/<task_id>/`의 파일 존재 여부로 재개 지점을 판단합니다. 대화 컨텍스트가 없어도 이 판단만으로 이어서 진행할 수 있어야 합니다.
@@ -88,7 +82,6 @@ brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.
 - 목표: <한 줄>
 - 범위 제외: <항목 나열 — 없으면 "없음">
 - 확인 필요: <항목 나열 — 없으면 "없음">
-- 작업 예산: fix <N>회 / 계획 단계 <분리 또는 통합>
 
 이 브리프가 맞는지 확인해주세요. 수정할 부분은 파일을 직접 편집하셔도 됩니다.
 확인되면 "진행"으로 회신해주세요.
@@ -98,10 +91,6 @@ brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.
 
 ## 2단계: Discovery
 
-작업 예산의 **계획 단계** 값에 따라 planner 호출 방식이 달라집니다.
-
-### 계획 단계 = 분리 (기본)
-
 planner를 Phase 1로 호출합니다.
 
 ```
@@ -120,29 +109,6 @@ 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로 호출합니다.
@@ -167,7 +133,7 @@ decisions.md에는 각 결정이 권장안이며 사용자 미확인임을 명
    구현 보고는 works/<task_id>/engineer.md에 회차별 append로 남기세요.
    git 커밋/푸시는 금지입니다.
    ```
-3. **qa 호출 + Fix 루프.** 재시도 상한 `<F>`는 작업 예산의 **QA fix 재시도 횟수**입니다 (기본 3). engineer 호출은 최대 `1 + <F>`회입니다.
+3. **qa 호출 + Fix 루프.** engineer fix 재호출은 **최대 3회**입니다. 따라서 engineer 호출은 최대 4회(신규 구현 1 + fix 3), qa 호출도 최대 4회(초회 1 + fix 후 재검증 3)입니다.
    - qa 호출:
      ```
      task_id: <task_id>
@@ -180,15 +146,14 @@ decisions.md에는 각 결정이 권장안이며 사용자 미확인임을 명
    - **FAIL / PARTIAL**이면 engineer 재호출:
      ```
      task_id: <task_id>
-     QA 실패. 회차: <N>/<F>
+     QA 실패. 회차: <N>/3
      QA 결과: works/<task_id>/qa.md
 
      이 문서의 "실패 원인"과 "Fix 가이드"를 참고해 수정하세요.
      Fix 결과는 works/<task_id>/engineer.md에 회차 섹션으로 append 하세요.
      ```
      수정 후 qa 재호출.
-   - **`<F>`회 fix 후에도 FAIL이면 루프를 중단하고 4단계로 갑니다.** 임의로 통과 처리하거나 상한을 넘겨 시도하지 마세요.
-   - `<F>`가 `0`이면 fix 없이 첫 QA 결과로 4단계로 갑니다.
+   - **3회 fix 후에도 FAIL이면 루프를 중단하고 4단계로 갑니다.** 임의로 통과 처리하거나 상한을 넘겨 시도하지 마세요.
 
 ## 4단계: 완료 보고 (`pm-report.md`)
 

package/preset/common/project-doc.md

@@ -1,7 +1,8 @@
 <!--
   이 문서는 spr-ai-native가 생성한 템플릿입니다.
   각 섹션의 <> 플레이스홀더를 프로젝트 실제 값으로 채우세요.
-  §4 "검증 명령"은 engineer / qa 서브에이전트가 그대로 실행하는 계약입니다. 반드시 채우세요.
+  §4 "검증 항목"의 명령 칸은 비워둬도 됩니다. 에이전트가 프로젝트 설정에서 찾아 채웁니다.
+  다만 `실행`(필수 / 선택 / 안 함)은 사람이 정하세요. 이 프로젝트가 무엇을 검증해야 하는지의 계약입니다.
 -->
 
 # 프로젝트 개발 지침
@@ -34,23 +35,47 @@ 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 -- <파일경로>>`
+| 린트 | 필수 | |
+| 타입 체크 | 필수 | |
+| 단위 테스트 | 필수 | |
+| 통합 테스트 | 선택 | |
+| 빌드 | 선택 | |
+| 포맷 검사 | 안 함 | |
+| 단일 테스트 실행 | — | |
+
+**`실행` 값**
+
+| 값 | 의미 |
+|---|---|
+| `필수` | 실행하고, 실패하면 FAIL |
+| `선택` | 실행하되 실패는 보고만 (판정에 반영하지 않음) |
+| `안 함` | 실행하지 않음. 이 프로젝트에 해당 없음 |
+
+`단일 테스트 실행`은 판정 항목이 아니라 engineer가 반복 실행에 쓰는 명령입니다.
+
+### 명령을 찾는 방법
+
+명령 칸이 비어 있으면 아래 순서로 **근거를 찾아** 채웁니다.
+
+1. 패키지 매니페스트 · 태스크 러너에 정의된 스크립트
+2. CI 설정이 실행하는 명령
+3. 해당 도구의 설정 파일이 있으면, 그 도구의 표준 실행 방법
+
+**찾은 명령은 이 표에 적어 넣습니다.** 다음 회차부터는 다시 찾지 않습니다.
+
+### 찾을 때 지켜야 할 것
+
+- **근거가 없으면 실행하지 않습니다.** "아마 이 명령일 것"은 발견이 아니라 추측입니다. 근거를 못 찾으면 **N/A**로 보고하고 사용자에게 표 갱신을 요청하세요.
+- **끝나지 않는 명령(감시 모드)을 그대로 쓰지 마세요.** 1회 실행 옵션을 확인하고, 없으면 N/A로 보고합니다.
+- **코드를 자동 수정하는 옵션이 붙은 명령을 쓰지 마세요.** 검사만 하는 형태를 찾고, 없으면 N/A로 보고합니다. qa는 코드 수정이 금지되어 있습니다.
+- 외부 서비스 · 자격증명이 없어 실패한 경우는 FAIL이 아니라 **N/A(환경 미비)** 로 보고합니다.
+- 어디서 찾았는지(파일 · 위치)를 보고에 남깁니다.
 
 ## 5. 산출물 · 워크플로우 규약
 
@@ -76,20 +101,6 @@ engineer는 구현 후, qa는 검증 시 아래 표에서 **필수 = 예**인
 - 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` — 결정 배경 컨텍스트.
 
@@ -30,8 +30,10 @@ 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. **README 실행 방법 갱신** — **사용자에게 보이는 변화가 있을 때만** 합니다.
@@ -62,7 +64,7 @@ PM이 다음 중 하나로 호출합니다.
 
 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 완료 보고.
 
@@ -75,11 +77,11 @@ PM에게 보내는 본문은 `engineer.md`에 작성한 해당 회차 섹션과
 자체 검증 결과는 다음 표를 포함합니다.
 
 ```
-| 목적 | 명령 | 결과 |
-|---|---|---|
-| 린트 | <실행한 명령> | 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` / `Phase 1+2 (통합)` 중 하나가 명시됩니다. 없으면 즉시 PM에게 반환하고 중단합니다.
+PM 메시지에 `Phase 1` / `Phase 2` 중 하나가 명시됩니다. 없으면 즉시 PM에게 반환하고 중단합니다.
 
 ## Phase 1: Discovery
 
@@ -94,7 +94,7 @@ PM 메시지에 `Phase 1` / `Phase 2` / `Phase 1+2 (통합)` 중 하나가 명
 - §2 영향 범위 — 신규 / 수정 파일 목록 (경로 단위).
 - §3 작업 단위 — `T1`~`Tn`. 각 항목에 **무엇을 / 어디에 / 완료 판정 기준**.
 - §4 데이터 · 마이그레이션 — 스키마 변경이 있으면. 없으면 "없음".
-- §5 테스트 전략 — 시나리오별로 **어느 파일에 어떤 테스트가 있어야 하는지** 매핑. `{{PROJECT_DOC}}` §4의 테스트 명령을 그대로 인용합니다.
+- §5 테스트 전략 — 시나리오별로 **어느 파일에 어떤 테스트가 있어야 하는지** 매핑. `{{PROJECT_DOC}}` §4에서 이 작업에 해당하는 검증 항목을 밝힙니다. 명령이 비어 있으면 항목 이름만 적고, 명령을 지어내지 마세요.
 - §6 비고 — 리스크, 롤백 방법, 범위 외 항목.
 
 ### `decisions.md` 권장 구조
@@ -119,41 +119,11 @@ PM 메시지에 `Phase 1` / `Phase 2` / `Phase 1+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+2 (통합)`으로 호출된 경우만 예외입니다.
+- **Phase 1**에서 plan / decisions 작성 금지 (`pending.md`만).
 - 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,16 +39,18 @@ 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 미작성으로 검증 명령 실행 불가"를 명시하고 §4 갱신을 요청합니다.
-- 일부만 N/A면, 실행된 명령이 전부 PASS이고 시나리오도 전부 PASS일 때 PASS로 하되 **N/A 항목을 보고에 빠짐없이 나열합니다.**
+- **`필수` 항목이 하나도 실행되지 않았으면(전부 N/A) 판정은 PARTIAL입니다.** 보고에 왜 실행하지 못했는지(근거 없음 / 도구 없음 / 환경 미비)를 항목별로 명시하고 `{{PROJECT_DOC}}` §4 갱신을 요청합니다.
+- 일부만 N/A면, 실행된 항목이 전부 PASS이고 시나리오도 전부 PASS일 때 PASS로 하되 **N/A 항목과 그 사유를 보고에 빠짐없이 나열합니다.**
 - 시나리오가 하나도 없으면(plan.md §5가 비었으면) 판정은 PARTIAL입니다.
 
 ## "Fix 가이드" 작성 요령
@@ -59,10 +64,10 @@ engineer가 격리된 컨텍스트에서 읽습니다. 다음을 포함하세요
 ## 보고 형식 (PM에게)
 
 ```
-## QA 결과: <task_id> (회차 <N>/<최대>)
+## 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`
   );