lee-spec-kit 0.4.12 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "Project documentation structure generator for AI-assisted development",
   "type": "module",
   "bin": {

package/templates/en/common/agents/pr-template.md

@@ -25,6 +25,11 @@ For file links within the repo in PR body, **always use current branch name**:
 > ⚠️ `main` branch links will return 404 until merged!
 > Always use the **current feature branch name** (e.g., `feat/5-feature-name`).
 
+### Labels (Required)
+
+- PRs must have **at least 1 label**. (cannot be empty)
+- If you're unsure which label to use, confirm with the user before creating the PR.
+
 ---
 
 ## PR Body Template
@@ -59,6 +64,7 @@ For file links within the repo in PR body, **always use current branch name**:
 
 ## Screenshots (Frontend / UI changes)
 
+<!-- If there are no UI changes, or if screenshot upload is disabled (e.g. `.lee-spec-kit.json` has `pr.screenshots.upload: false`), remove this section. -->
 > If you follow the Release assets upload flow in `skills/create-pr.md`, you can include images in the PR body without committing files to your branch.
 
 {Screenshot markdown (e.g. ![](URL))}
@@ -66,9 +72,18 @@ For file links within the repo in PR body, **always use current branch name**:
 ## Architecture Diagram (Backend / core structure changes)
 
 ```mermaid
-flowchart LR
-  A[Client] --> B[API]
-  B --> C[DB]
+sequenceDiagram
+  %% Guidelines:
+  %% - Express the key "request → processing → storage/response" flow in time order
+  %% - Keep participants ≤ 6
+  %% - Keep messages ≤ 12; summarize/split if needed
+  participant Client as Client
+  participant API as API
+  participant DB as DB
+  Client->>API: Request
+  API->>DB: Query/Command
+  DB-->>API: Result
+  API-->>Client: Response
 ```
 
 ## Related Documents
@@ -107,6 +122,9 @@ gh pr create \
 
 After all reviews are resolved:
 
+> ⚠️ Merging (`git merge`/`gh pr merge`) and creating merge commits are considered **remote git operations**.
+> Before running these commands, share the changes with the user and proceed only after the user replies with exactly `OK`.
+
 ```bash
 # Update main before merge
 git checkout main

package/templates/en/common/agents/skills/create-feature.md

@@ -37,22 +37,8 @@ After completing the action, go back to Step 1 and run `context` again.
 2. **Do not skip**: Do not fake issue numbers/statuses to advance steps.
 3. **No self-judgment**: If unsure, run `context` again.
 
----
-
-## Reference: the 10-step workflow (reference only)
-
-> ⚠️ Do NOT execute these from memory. Always follow the CLI.
-
-1. Feature folder created
-2. Write `spec.md`
-3. Get `spec.md` approved
-4. Create GitHub Issue and record `#`
-5. Create feature branch
-6. Write `plan.md`
-7. Get `plan.md` approved
-8. Write/execute `tasks.md`
-9. Pre-commit verification
-10. Commit docs
+> Note: the workflow steps may change over time. Do not memorize step numbers.
+> Treat `context` output as the SSOT.
 
 ---
 

package/templates/en/common/agents/skills/create-pr.md

@@ -23,16 +23,18 @@ Guide for creating Pull Requests.
 | -------- | ---------------------------------- |
 | Title    | `feat(#{issue-number}): {feature} ({short description})` |
 | Body     | Overview, Changes, Tests, Docs     |
-| Labels   | Appropriate labels                 |
+| Labels   | **At least 1 required** (cannot be empty) |
 | Assignee | `@me` (default)                    |
 
+> ⚠️ Labels cannot be empty. If you’re unsure which label to use, ask/confirm with the user before creating the PR.
+
 ### 2. Test Verification
 
 > 🚨 **PR cannot be created if tests fail**
 
 1. Run relevant test commands (e.g., `npm test`, `pnpm test`); if no tests exist, request them from the user
 2. Check results (PASS/FAIL)
-3. In the PR body "Tests" section, add **only the tests you actually ran** as checklist items and ensure they are **all checked ([x])** (do not include unexecuted tests)
+3. In the PR body "Tests" section, follow `pr-template.md` rules as-is. (add/check only what you actually ran)
 4. If you didn’t run any tests, request/confirm with the user before creating the PR
 
 ### 3. Prepare Screenshots / Diagrams (Include in PR Body)
@@ -44,9 +46,20 @@ Include the artifacts in the PR body.
 
 #### UI changes (Frontend PR)
 
+- Default is `pr.screenshots.upload: false`. If you need upload/URL inclusion, enable it in `.lee-spec-kit.json`.
+- If `.lee-spec-kit.json` has `pr.screenshots.upload: false`, **do not upload/include URLs**, and **do not include a "Screenshots" section** in the PR body.
 - Use `agent-browser` to generate screenshots.
 - Save files under a local temp folder (`/tmp/lee-spec-kit/pr-assets/`).
 - Upload them as Release assets, then put the image URLs into the "Screenshots" section of the PR body.
+- Before uploading, **open the image file** and verify, then ask the user to validate before PR creation:
+  - It is not a login/permission/error/blank page
+  - The PR-relevant change is actually visible
+  - No sensitive info is exposed (prod tokens/PII/internal URLs)
+
+> If the page requires auth, request one of the following from the user before taking screenshots:
+> - A preview URL that is accessible **without login** (dev-only bypass is OK)
+> - A **test account** (no real accounts / no production tokens) + login instructions
+> - A reproducible route with seeded/dummy data
 
 ```bash
 # (one-time) install agent-browser
@@ -67,12 +80,18 @@ agent-browser open "$PREVIEW_URL"
 agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
 agent-browser close
 
+# (required) open and validate the screenshot (re-capture if login/error/blank)
+ls -lh /tmp/lee-spec-kit/pr-assets/ui-1.png
+# macOS: open /tmp/lee-spec-kit/pr-assets/ui-1.png
+# Linux: xdg-open /tmp/lee-spec-kit/pr-assets/ui-1.png
+
 # (recommended) stop the dev server you started for screenshots
 kill \"$DEV_PID\" >/dev/null 2>&1 || true
 ```
 
 ```bash
 # Upload to Release assets and generate the URL to paste into the PR body
+# - If `.lee-spec-kit.json` has `pr.screenshots.upload: false`, skip this section.
 REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
 SAFE_BRANCH=$(git branch --show-current | tr '/' '-')
 TAG="pr-assets/${SAFE_BRANCH}"
@@ -87,7 +106,7 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 
 #### Logic/structure changes (Backend PR)
 
-- Write a Mermaid diagram (flowchart/sequence/etc.) in the PR body (see the "Architecture Diagram" section in `pr-template.md`).
+- Write a Mermaid **`sequenceDiagram`** in the PR body (follow the "Architecture Diagram" rules in `pr-template.md` as-is).
 
 ### 4. Request User Approval
 
@@ -97,7 +116,7 @@ Before creating PR, share the following **in a code block** and wait for **expli
 
 - Title
 - Full body (`pr-template.md` format)
-- Labels
+- Labels (at least 1; cannot be empty)
 
 ### 5. Create PR
 
@@ -105,6 +124,7 @@ Before creating PR, share the following **in a code block** and wait for **expli
 gh pr create \
   --title "feat(#{issue-number}): {feature} ({short description})" \
   --body-file /tmp/pr-body.md \
+  --label "{label1,label2}" \
   --assignee @me \
   --base main
 ```

package/templates/en/common/agents/skills/execute-task.md

@@ -20,7 +20,7 @@ npx lee-spec-kit context
 Execute the `👉 Next Action` exactly as printed by the CLI.
 
 - If the CLI points to an active task, focus on that task only.
-- If there is no active task, **share the task title and get user approval (OK)**, then switch the next `[TODO]` task to `[DOING]` and start.
+- Treat the task state/approval rules in `tasks.md` **"Task Rules"** as SSOT (e.g. when OK is required for `[TODO]→[DOING]`, `[DOING]→[DONE]`).
 - If the CLI prints commands, copy/paste them. (In standalone setups commands may include `git -C ...` and scopes like `project`/`docs`.)
 
 ### Step 3: Update tasks.md (only what you did)
@@ -33,8 +33,10 @@ Keep `tasks.md` aligned with reality.
 ### Step 3.25: Commit per task (important)
 
 - Complete **only one task at a time** (do not batch-finish multiple tasks in one commit).
-- After marking a task `[DONE]` (and updating any checklist items), create commits (code commit + docs commit) so each task has its own history.
-- Once all tasks are `[DONE]`, share the "Completion Criteria" checklist with the user and get approval (OK), then check it (especially the **User approval (OK) received** item).
+- After you share the outcome/verification and get approval (OK), mark the task `[DONE]` (and update any checklist items), then create commits (code commit + docs commit) so each task has its own history.
+- If `context` shows `[CHECK required]`, for commits/push/merge, **share the commit message + included files and wait for explicit OK** before running the commands.
+- Once all tasks are `[DONE]`, share the "Completion Criteria" checklist with the user and get **final approval (OK)**, then check it (especially the **Final user approval (OK) received** item).
+  - Note: `Doc Status (Review→Approved)` is **progress approval (OK)**, while the completion checklist approval is **final approval (OK)**.
 
 ### Step 3.5: Record decisions (strongly recommended, effectively required)
 

package/templates/en/fullstack/README.md

@@ -31,6 +31,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 - `docsRepo` ("embedded" | "standalone"): How docs are managed
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
+- `approval` (object, optional): Override `[CHECK required]` / `requiresUserCheck` policy in `context` output (approval token: `OK`)
 
 ### Examples
 
@@ -40,7 +41,8 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "projectType": "fullstack",
   "lang": "en",
   "createdAt": "{{date}}",
-  "docsRepo": "embedded"
+  "docsRepo": "embedded",
+  "approval": { "mode": "builtin" }
 }
 ```
 
@@ -52,6 +54,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "createdAt": "{{date}}",
   "docsRepo": "standalone",
   "pushDocs": true,
-  "docsRemote": "git@github.com:org/{{projectName}}-docs.git"
+  "docsRemote": "git@github.com:org/{{projectName}}-docs.git",
+  "approval": { "mode": "builtin" }
 }
 ```

package/templates/en/fullstack/agents/agents.md

@@ -8,6 +8,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 
 > ⚠️ **The following actions require explicit user approval (OK) before proceeding.**
 > **If approval is not given, stop immediately and request confirmation.**
+> ✅ “OK” means the user replies with exactly `OK`.
 
 | Action                | When to Confirm          | What to Share             |
 | --------------------- | ------------------------ | ------------------------- |
@@ -17,7 +18,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 | Issue Creation        | Before `gh issue create` | Title, body, labels       |
 | PR Creation           | Before `gh pr create`    | Title, body, labels       |
 | Assignee Change       | When assigning others    | Target username           |
-| Remote Git Operations | Before `push`, `merge`   | Branch, changes           |
+| Remote Git Operations | Before `push`, `merge` (including merge commits) | Branch, changes           |
 
 ### Approval Process
 

package/templates/en/fullstack/features/feature-base/plan.md

@@ -9,7 +9,7 @@
 - **Feature ID**: F{number}
 - **Target Repo**: {{projectName}}-{be|fe}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/fullstack/features/feature-base/spec.md

@@ -11,7 +11,7 @@
 - **Target Repo**: {{projectName}}-{be|fe}
 - **Issue Number**: #{issue-number}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/fullstack/features/feature-base/tasks.md

@@ -3,12 +3,16 @@
 ## Task Rules
 
 - **Status**: `[TODO]` → `[DOING]` → `[DONE]`
+- **Approvals**:
+  - `[TODO] → [DOING]`: share task title first + user approval (OK)
+  - `[DOING] → [DONE]`: share result/verification first + user approval (OK)
 - **Priority**: P0(urgent) > P1(high) > P2(medium) > P3(low)
 
 ---
 
 ## GitHub Issue
 
+- **Doc Status**: Review | Approved
 - **Repo**: {{projectName}}-{be|fe}
 - **Issue**: #{issue-number}
 - **Branch**: `feat/{issue-number}-{feature-name}`
@@ -23,11 +27,16 @@
 
 ### Phase 1: {Phase Name}
 
+> Add tasks below. **At least 1 task is required.**
+> Copy and use the format below.
+
+```markdown
 - [TODO][P1] T-F{number}-01 {Task Title}
   - Acceptance:
     - (verification condition)
   - Checklist:
     - [ ] (subtask)
+```
 
 ---
 
@@ -37,7 +46,7 @@
 
 - [ ] All tasks are `[DONE]`, and each task's `Acceptance` is verified and `Checklist` is checked
 - [ ] Tests executed and passing (record command/result below)
-- [ ] User approval (OK) received
+- [ ] Final user approval (OK) received (review the outcome)
 
 ### Test Run Log
 

package/templates/en/single/README.md

@@ -30,6 +30,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 - `docsRepo` ("embedded" | "standalone"): How docs are managed
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
+- `approval` (object, optional): Override `[CHECK required]` / `requiresUserCheck` policy in `context` output (approval token: `OK`)
 
 ### Examples
 
@@ -39,7 +40,8 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "projectType": "single",
   "lang": "en",
   "createdAt": "{{date}}",
-  "docsRepo": "embedded"
+  "docsRepo": "embedded",
+  "approval": { "mode": "builtin" }
 }
 ```
 
@@ -51,6 +53,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "createdAt": "{{date}}",
   "docsRepo": "standalone",
   "pushDocs": true,
-  "docsRemote": "git@github.com:org/{{projectName}}-docs.git"
+  "docsRemote": "git@github.com:org/{{projectName}}-docs.git",
+  "approval": { "mode": "builtin" }
 }
 ```

package/templates/en/single/agents/agents.md

@@ -8,6 +8,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 
 > ⚠️ **The following actions require explicit user approval (OK) before proceeding.**
 > **If approval is not given, stop immediately and request confirmation.**
+> ✅ “OK” means the user replies with exactly `OK`.
 
 | Action                | When to Confirm          | What to Share             |
 | --------------------- | ------------------------ | ------------------------- |
@@ -17,7 +18,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 | Issue Creation        | Before `gh issue create` | Title, body, labels       |
 | PR Creation           | Before `gh pr create`    | Title, body, labels       |
 | Assignee Change       | When assigning others    | Target username           |
-| Remote Git Operations | Before `push`, `merge`   | Branch, changes           |
+| Remote Git Operations | Before `push`, `merge` (including merge commits) | Branch, changes           |
 
 ### Approval Process
 

package/templates/en/single/features/feature-base/plan.md

@@ -9,7 +9,7 @@
 - **Feature ID**: F{number}
 - **Target Repo**: {{projectName}}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/single/features/feature-base/spec.md

@@ -11,7 +11,7 @@
 - **Target Repo**: {{projectName}}
 - **Issue Number**: #{issue-number}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/single/features/feature-base/tasks.md

@@ -3,12 +3,16 @@
 ## Task Rules
 
 - **Status**: `[TODO]` → `[DOING]` → `[DONE]`
+- **Approvals**:
+  - `[TODO] → [DOING]`: share task title first + user approval (OK)
+  - `[DOING] → [DONE]`: share result/verification first + user approval (OK)
 - **Priority**: P0(urgent) > P1(high) > P2(medium) > P3(low)
 
 ---
 
 ## GitHub Issue
 
+- **Doc Status**: Review | Approved
 - **Repo**: {{projectName}}
 - **Issue**: #{issue-number}
 - **Branch**: `feat/{issue-number}-{feature-name}`
@@ -23,11 +27,16 @@
 
 ### Phase 1: {Phase Name}
 
+> Add tasks below. **At least 1 task is required.**
+> Copy and use the format below.
+
+```markdown
 - [TODO][P1] T-F{number}-01 {Task Title}
   - Acceptance:
     - (verification condition)
   - Checklist:
     - [ ] (subtask)
+```
 
 ---
 
@@ -37,7 +46,7 @@
 
 - [ ] All tasks are `[DONE]`, and each task's `Acceptance` is verified and `Checklist` is checked
 - [ ] Tests executed and passing (record command/result below)
-- [ ] User approval (OK) received
+- [ ] Final user approval (OK) received (review the outcome)
 
 ### Test Run Log
 

package/templates/ko/common/agents/pr-template.md

@@ -25,6 +25,11 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 > ⚠️ `main` 브랜치 링크는 머지 전까지 404가 발생합니다!
 > 반드시 **현재 피처 브랜치명** (예: `feat/5-feature-name`)을 사용하세요.
 
+### 라벨 (필수)
+
+- PR에는 **최소 1개 라벨이 반드시 필요**합니다. (비워둘 수 없음)
+- 어떤 라벨을 써야 할지 확신이 없으면 PR 생성 전에 사용자에게 확인하세요.
+
 ## PR 본문 템플릿
 
 ```markdown
@@ -57,6 +62,7 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 
 ## 스크린샷 (프론트엔드 / UI 변경 시)
 
+<!-- UI 변경이 아니거나, 스크린샷을 업로드하지 않았다면(예: `.lee-spec-kit.json`의 `pr.screenshots.upload: false`) 이 섹션은 제거하세요. -->
 > `skills/create-pr.md`의 Release assets 업로드 절차를 사용하면 브랜치에 파일을 커밋하지 않고도 이미지를 본문에 포함할 수 있습니다.
 
 {스크린샷 마크다운 (예: ![](URL))}
@@ -64,9 +70,18 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 ## 아키텍처 다이어그램 (백엔드 / 핵심 구조 변경 시)
 
 ```mermaid
-flowchart LR
-  A[Client] --> B[API]
-  B --> C[DB]
+sequenceDiagram
+  %% 가이드:
+  %% - 핵심 "요청→처리→저장/응답" 흐름을 시간 순서로 표현
+  %% - 참여자(participant)는 6개 이내 권장
+  %% - 메시지는 12개 이내 권장 (너무 길면 핵심만 남기고 요약/분리)
+  participant Client as Client
+  participant API as API
+  participant DB as DB
+  Client->>API: Request
+  API->>DB: Query/Command
+  DB-->>API: Result
+  API-->>Client: Response
 ```
 
 ## 관련 문서
@@ -105,6 +120,9 @@ gh pr create \
 
 모든 리뷰 해결 시:
 
+> ⚠️ 머지(`git merge`/`gh pr merge`) 및 머지 커밋 생성은 **Git 원격 작업**에 해당합니다.
+> 실행 전 변경 사항을 사용자에게 공유하고, 사용자가 **정확히 `OK`**라고 답한 뒤에만 진행하세요.
+
 ```bash
 # 머지 전 main 최신화
 git checkout main

package/templates/ko/common/agents/skills/create-feature.md

@@ -38,22 +38,8 @@ CLI가 출력하는 **`👉 Next Action` 메시지를 읽고, 그 지시만 정
 2. **건너뛰지 않기**: "이슈 생성" 단계를 귀찮아서 생략하거나 가짜 번호를 넣지 마세요.
 3. **스스로 판단 금지**: "이 정도면 됐겠지?"라고 생각하지 말고 CLI에게 물어보세요.
 
----
-
-## 참조: CLI가 안내하는 10단계 (참조용)
-
-> ⚠️ 이 단계를 외워서 실행하지 마세요. **참조용**일 뿐입니다. 항상 CLI를 믿으세요.
-
-1. **Feature 폴더 생성**: `npx lee-spec-kit feature ...`
-2. **spec.md 작성**: 기능 정의 (Status: Draft)
-3. **spec.md 승인**: 사용자 검토 및 승인 (Status: Approved)
-4. **GitHub Issue 생성**: 이슈 번호 발급
-5. **브랜치 생성**: `git checkout -b feat/...`
-6. **plan.md 작성**: 구현 계획 (Status: Draft)
-7. **plan.md 승인**: 사용자 검토 및 승인 (Status: Approved)
-8. **tasks.md 작성/실행**: 태스크 분해 및 진행
-9. **문서 커밋 전 확인**: 최종 점검
-10. **문서 커밋**: Docs Sync
+> 참고: 워크플로우 단계는 변경될 수 있으므로, “단계 번호”를 외우지 마세요.
+> **항상 `context` 출력만**을 SSOT로 따르세요.
 
 ---
 

package/templates/ko/common/agents/skills/create-pr.md

@@ -23,16 +23,18 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 | ------ | ---------------------------------- |
 | 제목   | `feat(#{이슈번호}): {기능명} ({짧은 설명})` |
 | 본문   | 개요, 변경 사항, 테스트, 관련 문서 |
-| 라벨   | 적절한 라벨 지정                   |
+| 라벨   | **최소 1개 필수** (비워둘 수 없음) |
 | 담당자 | `@me` (기본값)                     |
 
+> ⚠️ 라벨을 비워둘 수 없습니다. 적절한 라벨이 없거나 확신이 없다면, PR 생성 전에 사용자에게 라벨을 요청/확인하세요.
+
 ### 2. 테스트 검증
 
 > 🚨 **테스트 미통과 시 PR 생성 불가**
 
 1. 작업과 관련된 테스트 명령어 실행 (예: `npm test`, `pnpm test`), 테스트가 없는 경우 사용자에게 요청
 2. 결과 확인 (PASS/FAIL)
-3. PR 본문 "테스트" 섹션에 **실행한 테스트만** 체크리스트로 추가하고, **모두 체크([x])** 합니다. (미실행 항목은 작성하지 않기)
+3. PR 본문 "테스트" 섹션은 `pr-template.md`의 규칙을 그대로 따릅니다. (실행한 테스트만 추가/체크)
 4. 테스트를 실행하지 않았다면, PR 생성 전에 사용자에게 요청/확인합니다.
 
 ### 3. 스크린샷/다이어그램 작성 (PR 본문에 포함)
@@ -44,9 +46,20 @@ PR 본문에 결과물을 포함합니다.
 
 #### UI 변경 (프론트엔드 PR)
 
+- 기본값은 `pr.screenshots.upload: false`입니다. 업로드/URL 포함이 필요하다면 `.lee-spec-kit.json`에서 `true`로 켜세요.
+- `.lee-spec-kit.json`에서 `pr.screenshots.upload: false`라면 **업로드/URL 포함을 하지 않으며**, PR 본문에서도 **"스크린샷" 섹션을 만들지 않습니다.**
 - `agent-browser`로 스크린샷을 생성합니다.
 - 스크린샷 파일은 로컬 임시 폴더(`/tmp/lee-spec-kit/pr-assets/`)에 저장합니다.
 - 릴리스 자산(Release assets)으로 업로드한 뒤, 생성된 이미지 URL을 PR 본문 "스크린샷" 섹션에 넣습니다.
+- 스크린샷을 업로드하기 전에 **이미지 파일을 직접 열어** 다음을 확인하고, PR 생성 전 사용자에게도 검증받습니다.
+  - 로그인 화면/권한 오류/에러 화면/빈 화면이 아닌지
+  - 이번 PR의 변경 사항이 실제로 보이는지
+  - 민감 정보(실서비스 토큰/개인정보/내부 URL)가 노출되지 않았는지
+
+> 로그인/권한이 필요한 화면이라면, 스크린샷을 찍기 전에 사용자에게 아래 중 하나를 요청하세요.
+> - 개발 서버에서 **로그인 없이** 접근 가능한 미리보기 URL 제공 (dev-only bypass 포함)
+> - **테스트 계정** 제공(실계정/실서비스 토큰 금지) + 로그인 절차 안내
+> - 시드 데이터/더미 데이터로 재현 가능한 경로 제공
 
 ```bash
 # (최초 1회) agent-browser 설치
@@ -67,12 +80,18 @@ agent-browser open "$PREVIEW_URL"
 agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
 agent-browser close
 
+# (필수) 스크린샷 파일을 열어 검증 (로그인/에러/빈 화면이면 재촬영)
+ls -lh /tmp/lee-spec-kit/pr-assets/ui-1.png
+# macOS: open /tmp/lee-spec-kit/pr-assets/ui-1.png
+# Linux: xdg-open /tmp/lee-spec-kit/pr-assets/ui-1.png
+
 # (권장) 스크린샷을 위해 띄운 개발 서버는 작업이 끝나면 종료합니다.
 kill \"$DEV_PID\" >/dev/null 2>&1 || true
 ```
 
 ```bash
 # 스크린샷을 Release assets로 업로드하고, PR 본문에 넣을 URL 만들기
+# - `.lee-spec-kit.json`에서 `pr.screenshots.upload: false`라면 이 단계는 생략합니다.
 REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
 SAFE_BRANCH=$(git branch --show-current | tr '/' '-')
 TAG="pr-assets/${SAFE_BRANCH}"
@@ -87,7 +106,7 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 
 #### 로직/구조 변경 (백엔드 PR)
 
-- PR 본문에 Mermaid 다이어그램(예: flowchart/sequence)을 작성합니다. (`pr-template.md`의 "아키텍처 다이어그램" 섹션 참고)
+- PR 본문에 Mermaid **`sequenceDiagram`**을 작성합니다. (`pr-template.md`의 "아키텍처 다이어그램" 섹션 규칙을 그대로 따르세요)
 
 ### 4. 사용자 확인 요청
 
@@ -97,7 +116,7 @@ PR 생성 전 다음 내용을 **코드블록으로** 사용자에게 공유하
 
 - 제목
 - 본문 전체 (`pr-template.md` 형식)
-- 라벨
+- 라벨(최소 1개, 비워둘 수 없음)
 
 ### 5. PR 생성
 
@@ -105,6 +124,7 @@ PR 생성 전 다음 내용을 **코드블록으로** 사용자에게 공유하
 gh pr create \
   --title "feat(#{이슈번호}): {기능명} ({짧은 설명})" \
   --body-file /tmp/pr-body.md \
+  --label "{라벨1,라벨2}" \
   --assignee @me \
   --base main
 ```

package/templates/ko/common/agents/skills/execute-task.md

@@ -9,7 +9,7 @@
 
 모든 태스크가 완료될 때까지(`[DONE]`) 다음 과정을 **계속 반복**하세요.
 
-### 1단계: 할 일 확인 (Check)
+### 1단계: 할 일 확인
 
 작업을 시작하거나 하나를 마칠 때마다 **반드시** 아래 명령어를 실행합니다.
 
@@ -22,8 +22,7 @@ npx lee-spec-kit context
 CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 
 - **[DOING] 상태인 태스크가 있다면**: 해당 태스크를 최우선으로 완료하세요.
-- **[DOING]이 없다면**: CLI가 추천하는 다음 태스크(`[TODO]`)를 시작하기 전에, **태스크 제목을 공유하고 사용자 승인(OK)을 받은 뒤** `[DOING]`으로 변경하세요.
-- **완료 조건(Acceptance)을 검증**하고, 테스트를 통과해야만 완료(`[DONE]`) 처리합니다.
+- 태스크 상태 전환/승인 규칙은 `tasks.md`의 **"태스크 규칙"** 섹션을 SSOT로 따릅니다. (예: `[TODO]→[DOING]`, `[DOING]→[DONE]` 시점의 OK)
 - CLI가 명령어를 출력하면 **그대로 복사해 실행**합니다. (standalone 환경에서도 레포 경로가 포함될 수 있습니다)
 
 ### 3단계: 기록 및 반복 (Record & Loop)
@@ -46,10 +45,12 @@ CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 
 #### 3-2) 태스크/체크리스트 업데이트 + 커밋
 
-1. 작업이 끝나면 해당 태스크의 상태를 `[DONE]`으로 변경하고, `Acceptance/Checklist` 항목을 `[x]`로 체크합니다.
+1. 작업이 끝나면 결과/검증을 사용자에게 공유해 승인(OK)을 받은 뒤, 해당 태스크의 상태를 `[DONE]`으로 변경하고 `Acceptance/Checklist` 항목을 `[x]`로 체크합니다.
 2. **한 번에 하나의 태스크만** `[DONE]` 처리합니다. (태스크 2개 이상을 한 번에 완료/커밋으로 묶지 않기)
 3. 커밋을 생성합니다 (코드 커밋 + 문서 커밋). 태스크 단위로 커밋이 남아야 합니다.
-4. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유하고 승인(OK)을 받은 뒤 체크합니다. (특히 **사용자 승인(OK) 완료** 항목)
+   - `context`에 `[확인 필요]`가 보이면, **커밋/푸시 같은 원격 작업은 사용자에게 커밋 메시지/포함 파일을 공유하고 OK를 받은 뒤** 실행합니다.
+4. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유하고 **최종 승인(OK)** 을 받은 뒤 체크합니다. (특히 **최종 사용자 승인(OK) 완료** 항목)
+   - 참고: `문서 상태(Review→Approved)`는 **진행 승인(OK)** 이고, 완료 조건의 승인은 **최종 승인(OK)** 입니다.
 5. **즉시 1단계로 돌아가** 다음 할 일을 CLI에게 물어봅니다.
 
 ---
@@ -66,14 +67,7 @@ CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 
 > ⚠️ 직접 판단하지 말고 CLI가 시키는 대로 하세요.
 
-1. **[TODO] → [DOING]**: 작업 시작 시 표시
-2. **[DOING] → [DONE]**: 테스트 통과 및 사용자 승인 후 표시
-
-```markdown
-- [DONE] T-01: 로그인 UI (완료됨)
-- [DOING] T-02: API 연동 (현재 작업 중)
-- [TODO] T-03: 에러 처리 (대기 중)
-```
+태스크 상태 전환/승인 규칙은 `tasks.md`의 **"태스크 규칙"** 섹션을 따르세요.
 
 ## 비상시 대처 (Emergency)
 

package/templates/ko/fullstack/README.md

@@ -31,6 +31,7 @@
 - `docsRepo` ("embedded" | "standalone"): Docs 관리 방식
 - `pushDocs` (boolean, optional): `docsRepo: "standalone"`일 때만 생성 (원격 push 여부)
 - `docsRemote` (string, optional): `pushDocs: true`일 때만 생성 (원격 레포 URL)
+- `approval` (object, optional): `context` 출력의 `[확인 필요]` / `requiresUserCheck` 정책 오버라이드 (승인 토큰: `OK`)
 
 ### 예시
 
@@ -40,7 +41,8 @@
   "projectType": "fullstack",
   "lang": "ko",
   "createdAt": "{{date}}",
-  "docsRepo": "embedded"
+  "docsRepo": "embedded",
+  "approval": { "mode": "builtin" }
 }
 ```
 
@@ -52,6 +54,7 @@
   "createdAt": "{{date}}",
   "docsRepo": "standalone",
   "pushDocs": true,
-  "docsRemote": "git@github.com:org/{{projectName}}-docs.git"
+  "docsRemote": "git@github.com:org/{{projectName}}-docs.git",
+  "approval": { "mode": "builtin" }
 }
 ```