lee-spec-kit 0.6.36 → 0.6.38

package/package.json

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

package/templates/en/common/README.md

@@ -38,6 +38,35 @@ npx lee-spec-kit context --json-compact
 
 ---
 
+## SSOT Relationship (PRD / Ideas / Features)
+
+To avoid ambiguity, treat the following as the single source of truth (SSOT).
+
+- **PRD (`docs/prd/`)**: requirements SSOT
+  - Assign stable IDs per requirement: `PRD-FR-001`, `PRD-US-002`, `PRD-NFR-003`
+  - Keep IDs stable (prefer marking as Deprecated over deleting; do not renumber).
+- **Ideas (`docs/ideas/`)**: pre-Feature SSOT (hypotheses/experiments/candidates)
+  - Put `PRD Refs:` at the top (example: `PRD-FR-001, PRD-US-002`).
+  - Once promoted, the SSOT moves to `docs/features/` and the idea should be archived.
+- **Features (`docs/features/`)**: implementation scope/progress SSOT
+  - `spec.md`: scope + `PRD Refs` (the PRD IDs this feature covers)
+  - `tasks.md`: map each task line to PRD IDs via bracket tags like `[PRD-FR-001]`, or tag non-PRD tasks as `[NON-PRD]`
+  - `decisions.md`: record changes/trade-offs/requirement changes (why it changed) with evidence links
+
+## Change Protocol (When Requirements/Scope Change Mid-Work)
+
+When requirements/scope change, the “what to update” must be explicit in docs. Minimum checklist:
+
+1. **PRD changes** (add/change/deprecate requirements):
+   - `docs/prd/*.md`: add/update/deprecate the affected IDs
+2. **If still in Idea stage**:
+   - `docs/ideas/*.md`: update `PRD Refs` and in/out scope
+3. **If already a Feature**:
+   - `docs/features/.../spec.md`: update `PRD Refs` + reflect scope change summary
+   - `docs/features/.../tasks.md`: add tasks for the change + tag each task as `[PRD-...]` or `[NON-PRD]`
+   - `docs/features/.../plan.md`: update if architecture/testing strategy changed
+   - `docs/features/.../decisions.md`: record why/what changed + evidence (commit/PR/test)
+
 ## CLI Config (`.lee-spec-kit.json`)
 
 When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs root (default: `docs/`).

package/templates/en/common/agents/agents.md

@@ -32,13 +32,14 @@ Prohibited:
 
 ## 🧾 Label Response Contract (SSOT)
 
-- End **every user-facing reply** with current status + available labels.
+- Treat approval-waiting as a separate state. Approval-waiting means `context --json-compact` (or `context --json`) exposes executable `actionOptions[]` and you are explicitly waiting for user approval.
 - Use the latest `npx lee-spec-kit context --json-compact` as the default source (fallback: `context --json` or `flow --json` when full detail is required; prefer `flow --json-compact` for default flow output).
 - When using auto results from `flow --json-compact` (or `flow --json`), treat `autoRun.resume.flowCommand` as SSOT for resume (including after context compression/reset).
 - Treat `AUTO_MANUAL_REQUIRED` as an automation boundary, not an immediate failure. Re-check `context --json-compact`, then decide stop/report by `approvalRequest.required` (`context --json` only for full-detail debugging fields).
-- Use `actionOptions[].detail` or command `cmd` **verbatim**. Do not paraphrase.
-- Even when the user asks something else, append the same label block at the end if executable labels exist.
-- If no executable labels exist, print `Available labels: none` and guide re-check with `npx lee-spec-kit context`.
+- In approval-waiting state, show `actionOptions[*].approvalPrompt` lines exactly as provided and end with `approvalRequest.finalPrompt` exactly as provided. Prefer `approvalRequest.userFacingLines` when available. Do not add your own rewritten label summary before or between those lines.
+- Prefer `matchedFeature.currentSubstateOwner` plus `agentOrchestration.subAgentHandoff` as the delegation SSOT. Treat `currentActionShouldDelegate` as a compatibility mirror for older consumers.
+- In non-approval state, do not append labels or `approvalRequest.finalPrompt` unless the user explicitly asked for current options.
+- If approval is still pending after answering an unrelated question, answer first, then re-open approval with both the matching `actionOptions[*].approvalPrompt` lines and `approvalRequest.finalPrompt`.
 - If user input does not contain a valid label, do not execute; request label selection again.
 - For approved command options, prefer one-shot `flow --approve <LABEL> --execute`; do not split `context --approve` and `context --execute --ticket` across turns/sessions.
 - If `agentOrchestration.currentActionShouldDelegate=true` and the selected option is `actionType="command"`, delegation is mandatory: call `spawn_agent` first. Do not execute that command directly from the main agent.
@@ -48,15 +49,7 @@ Prohibited:
 - Main-agent fallback is allowed only when sub-agent execution is unavailable (for example: tool not available, spawn failed, or sub-agent failed before command execution).
 - When fallback is used, report a one-line fallback reason to the user before running the command in the main agent.
 
-Output format:
-
-```text
-Current status: <reasonCode or brief state>
-Available labels:
-A: <detail>
-B: <detail>
-Reply format: "<LABEL>" or "<LABEL> OK"
-```
+Approval-waiting output must reuse the exact CLI-provided prompt lines. Do not invent a custom wrapper such as `Current status:` / `Available labels:` if the CLI did not provide those lines.
 
 ---
 

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

@@ -21,11 +21,11 @@ Always run this checklist in Pre-PR review. Treat it as the minimum baseline, th
 1. Review alignment with `spec.md` / `plan.md` / `tasks.md` and confirm implementation still matches the original goal.
 2. Inspect regression, exception handling, critical/security risks, side effects, user flow impact, and release readiness.
 3. Check maintainability: split oversized functions/files when needed, reuse/integrate existing code where appropriate, and remove obsolete code.
-4. Run related test/verification commands (or explicitly record why they were not run).
-5. Run the review agent first and generate `review-trace.json` with non-empty `commandsExecuted`, then run `npx lee-spec-kit pre-pr-review <feature-ref> --evidence review-trace.json`.
-6. `Pre-PR Evidence` should point to a real existing path. (default: `workflow.prePrReview.evidenceMode=path_required`)
-7. With `workflow.prePrReview.enforceExecutionEvidence=true` (default), `commandsExecuted` is required and cannot be empty.
-8. In `decisions.md`, include a `Pre-PR Review Log` section with non-placeholder `Summary` and `Decision` entries.
+4. Judge whether the implementation actually fits the feature intent and scope documented in `spec.md` / `plan.md` / `tasks.md`.
+5. When `workflow.prePrReview.evidenceMode=path_required` (default), run the review agent first, generate `review-trace.json`, then run `npx lee-spec-kit pre-pr-review <feature-ref> --evidence review-trace.json`. In `evidenceMode=any`, direct record mode without `--evidence` is also allowed unless execution evidence is explicitly enforced.
+6. `Pre-PR Evidence` should follow the configured evidence policy. In `path_required`, it must point to a real existing path.
+7. Record `Summary`, `Feature Intent Summary`, `Implementation Fit`, `Missing Cases`, `Spec Alignment Checked`, `Finding Count`, `Blocking Findings`, `Findings`, and `Residual Risks` with non-placeholder content.
+8. Use `commandsExecuted` only for optional audit/targeted verification that you actually chose to run during review.
 9. In code-review stage, keep `PR Review Evidence/Decision` aligned with `decisions.md` by adding a `PR Review Log` section with `Summary` and `Decision`.
 10. `Pre-PR Decision` must use `decision: approve|changes_requested|blocked ...` (or `결정: ...`).
 11. Ensure the final decision is `approve` before moving to PR creation.

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

@@ -24,7 +24,11 @@ Execute exactly one option from `👉 Next Options (Atomic)` as printed by the C
 - Treat `approvalRequest.required` from `context --json-compact` as SSOT for approval waiting (`--json` only when full-detail debugging fields are required).
   - `false`: continue without label approval.
   - `true`: wait for label-token approval (`A`, `A OK`) before execution.
-- Default execution model is **main-agent orchestration + selective sub-agent execution**. Keep short steps (spec/plan/tasks approvals, issue/PR metadata sync) in the main agent, and delegate long-running loops (`task_execute`, `code_review`, `review_fix_commit`, `pre_pr_review`, auto-run) to a sub-agent.
+- Default execution model is **main-agent orchestration + sub-agent-first execution for sub-agent-owned run states**. Use `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase` from `context --json-compact` as the execution-state SSOT when present.
+- Main agent owns approval boundaries, state transitions, record/commit steps, and remote operations. Sub-agent execution is the default for command substates owned by `subagent` (for example `task_run`, `pre_pr_review_run`, `code_review_run`, and auto-run handoff commands).
+- `pre_pr_review` is split into `pre_pr_review_run` (sub-agent review execution) and `pre_pr_review_record` (main-agent recording of evidence/results).
+- PR review follows the same pattern: `code_review_run` is the sub-agent review/fix execution state, and the merge/push/final decision stays in the main-agent finalize state.
+- Prefer `matchedFeature.currentSubstateOwner` plus `agentOrchestration.subAgentHandoff` as the delegation SSOT. `currentActionShouldDelegate` remains a compatibility mirror.
 - When `agentOrchestration.currentActionShouldDelegate=true` and the selected option is `actionType="command"`, delegation is mandatory: call `spawn_agent` first and do not execute the command directly from the main agent.
 - Do not delegate auto loops from `autoRun.available` alone. Delegate auto loops only when `agentOrchestration.subAgentHandoff.required=true` and `agentOrchestration.subAgentHandoff.mode="auto_run"`.
 - Use `agentOrchestration.subAgentHandoff` as the minimal handoff contract (`featureRef`, `category`, `cwd`, `cmd`).
@@ -35,7 +39,7 @@ Execute exactly one option from `👉 Next Options (Atomic)` as printed by the C
 - If auto execution stops, treat `autoRun.resume` from `flow --json-compact` (or `flow --json`) as SSOT. After interruption/compression, resume with `autoRun.resume.flowCommand`; if needed, check current state first with `autoRun.resume.contextCommand`.
 - Treat `AUTO_MANUAL_REQUIRED` as an automation boundary (instruction-only segment), not an immediate crash. Re-check `context --json-compact` and report whether `approvalRequest.required` is now true.
 - If the CLI prints commands, copy/paste them. (In standalone setups commands may include `git -C ...` and scopes like `project`/`docs`.)
-- Follow user-facing response format (including the final status/label block in every reply) from `agents.md` **"Label Response Contract (SSOT)"**.
+- Follow `agents.md` **"Label Response Contract (SSOT)"**. Show label prompts only in approval-waiting state, and reuse the exact CLI-provided approval lines instead of paraphrasing them.
 - For approved command options, default to `npx lee-spec-kit flow <slug|F001|F001-slug> --approve <LABEL> --execute` and avoid split `context --approve` / `context --execute --ticket` runs across turns.
 
 ### Step 3: Update tasks.md (only what you did)

package/templates/en/common/features/README.md

@@ -60,6 +60,28 @@ npx lee-spec-kit status --write
 
 ---
 
+## PRD Requirement Traceability (Recommended)
+
+- Assign stable requirement IDs in PRD docs (`docs/prd/*.md`) like `PRD-FR-001`.
+- Link each task line in `tasks.md` with a tag like `[PRD-FR-001]`. For non-PRD tasks, use `[NON-PRD]`.
+- Coverage report: `npx lee-spec-kit requirements` (alias: `npx lee-spec-kit prd`)
+
+---
+
+## Change Protocol (When Requirements/Scope Change Mid-Feature)
+
+When things change mid-work, it must be explicit what was updated.
+
+- Record changes as **new tasks** (do not edit `[DONE]` tasks; create a new task instead).
+- Every change task must be tagged as `[PRD-...]` or `[NON-PRD]`. (Recommended: also add `[CHANGE]`.)
+- If the change impacts PRD/spec/plan, update these too:
+  - `docs/prd/*.md` (add/update/deprecate requirement IDs)
+  - `spec.md` (`PRD Refs`, scope/AC)
+  - `plan.md` (architecture/testing strategy)
+  - `decisions.md` (why it changed + evidence)
+
+---
+
 ## Status Glossary
 
 | Scope | Field | Values |

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

@@ -55,3 +55,5 @@
 ## Related Documents
 
 - PRD: `../../prd/`
+- PRD Refs: - (e.g. `PRD-FR-001`, `PRD-US-002`)
+  - When requirements/scope change, update PRD docs + this field + `tasks.md` task tags together.

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

@@ -7,6 +7,7 @@
   - `[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)
+- **PRD mapping (recommended)**: add a PRD requirement ID tag like `[PRD-FR-001]` to each task line, or tag non-PRD tasks as `[NON-PRD]`.
 
 ---
 
@@ -45,7 +46,7 @@
 > Copy and use the format below.
 
 ```markdown
-- [TODO][P1] T-F{number}-01 {Task Title}
+- [TODO][P1][PRD-FR-001] T-F{number}-01 {Task Title}
   - Date: YYYY-MM-DD
   - Acceptance:
     - (verification condition)
@@ -53,6 +54,19 @@
     - [ ] (subtask)
 ```
 
+(Recommended) Requirement/scope change task:
+
+Record mid-work changes as **new tasks**, and explicitly list which docs need updating via `Impact Docs`.
+
+```markdown
+- [TODO][P1][PRD-FR-001][CHANGE] T-F{number}-02 {Task Title} (requirement/scope change)
+  - Impact Docs:
+    - docs/prd/... (when requirements change)
+    - spec.md (PRD Refs/AC/scope)
+    - plan.md (architecture/testing strategy)
+    - decisions.md (why it changed + evidence)
+```
+
 ---
 
 ## Completion Criteria

package/templates/en/common/ideas/README.md

@@ -14,17 +14,28 @@ Core rule: once an idea becomes a Feature, the SSOT moves to `docs/features/`.
 - Put at least these at the top:
   - Goal / context
   - Rough scope (what’s in/out)
+  - PRD Refs (recommended): `PRD-FR-001, PRD-US-002` (use `NON-PRD` when not tied to PRD)
   - Target component (optional): `api` / `app` / `worker` / `all`
+  - Status (recommended): `Active | Converted | Dropped`
 
 ---
 
 ## Promotion / Cleanup (Idea → Feature)
 
 1. Create a Feature folder with `npx lee-spec-kit feature <name>`
-2. Add the idea doc path to the new Feature’s `spec.md` or `tasks.md`
-   - Example: `docs/ideas/login-rate-limit.md`
+2. In the new Feature, record all of the following:
+   - Idea doc path in `spec.md` or `tasks.md` (example: `docs/ideas/login-rate-limit.md`)
+   - `PRD Refs` in `spec.md` (example: `PRD-FR-001, PRD-US-002`)
+   - PRD mapping tags in `tasks.md` task lines like `[PRD-FR-001]` (use `[NON-PRD]` for non-PRD tasks)
 3. Remove the idea from the active list (choose one):
    - **Recommended**: move to `docs/ideas/archive/` and add `Status: Converted`, `Feature: F00X-...` on top
    - Or: delete it (only if you don’t need history)
 
 > Tip: archiving is usually better than deleting for traceability (“why this feature exists”).
+
+---
+
+## Change Protocol (When Ideas Change Mid-Work)
+
+- If PRD requirements change: update the idea’s `PRD Refs` first, and update PRD docs (`docs/prd/*.md`) when needed (add/update IDs).
+- If the idea is already promoted: update the Feature SSOT instead (`spec.md`/`tasks.md`/`plan.md`/`decisions.md`), not the idea.

package/templates/en/common/prd/README.md

@@ -13,6 +13,34 @@ This folder contains product requirements documents.
 2. Write main features and user stories
 3. Include technical architecture overview
 
+## Requirement ID Conventions (Recommended)
+
+To let the CLI report “which PRD items are implemented”, assign **stable IDs** to PRD requirements.
+
+- Format: `PRD-FR-001`, `PRD-US-002`, `PRD-NFR-003`
+- The ID only needs to appear on the same line (heading/bullet).
+- Reference it from a Feature `tasks.md` task line as a **bracket tag** like `[PRD-FR-001]`.
+- For non-PRD tasks, tag them as `[NON-PRD]`.
+
+Example:
+
+```md
+- PRD-FR-001: Login rate limit
+### PRD-US-002: Admin can view metrics
+```
+
+## Change Rules (Add/Change/Deprecate Requirements)
+
+When requirements change, it must be obvious what needs updating.
+
+- **Stable IDs**:
+  - Do not renumber or reuse IDs.
+  - Prefer marking a requirement as `Deprecated` (with reason / replacement IDs) over deleting it.
+  - If requirements split/merge, keep the original ID and add new IDs, then document the relationship in PRD.
+- **Cascade updates (required)**:
+  - If the PRD change affects an in-flight Feature, update the Feature SSOT too: `spec.md` (`PRD Refs`), `tasks.md` (task tags), and `plan.md`/`decisions.md` when applicable.
+  - If no Feature exists yet, keep an Idea doc (`docs/ideas/*.md`) with `PRD Refs` so it remains traceable before promotion.
+
 ## Example Files
 
 - `{project-name}-prd.md` - Main PRD document

package/templates/ko/common/README.md

@@ -38,6 +38,35 @@ npx lee-spec-kit context --json-compact
 
 ---
 
+## SSOT 관계 (PRD / Ideas / Features)
+
+문서 간 관계가 모호해지지 않도록, 아래를 “SSOT(단일 기준)”로 사용합니다.
+
+- **PRD (`docs/prd/`)**: 요구사항 SSOT
+  - 요구사항마다 ID를 부여합니다: `PRD-FR-001`, `PRD-US-002`, `PRD-NFR-003`
+  - ID는 안정적으로 유지합니다. (삭제 대신 `Deprecated` 표기 권장, 재번호 부여 금지)
+- **Ideas (`docs/ideas/`)**: Feature 전 단계 SSOT (가설/실험/후보)
+  - Idea 문서 상단에 `PRD Refs:`를 기록합니다. (예: `PRD-FR-001, PRD-US-002`)
+  - Feature로 승격되면 SSOT는 `docs/features/`로 이동하고, Idea는 archive로 정리합니다.
+- **Features (`docs/features/`)**: 구현 범위/진행 SSOT
+  - `spec.md`: 범위 정의 + `PRD Refs`(기능이 커버하는 PRD ID 목록)
+  - `tasks.md`: 태스크 단위로 PRD ID를 태그(`[PRD-FR-001]`)로 매핑하거나, PRD 무관 태스크는 `[NON-PRD]`로 표시
+  - `decisions.md`: 변경/트레이드오프/요구사항 변경(왜 바뀌었는지) 기록 + Evidence 링크
+
+## 변경 프로토콜 (중간에 요구사항/기능이 추가·변경될 때)
+
+요구사항/범위가 변하면, “무엇을 고쳐야 하는지”가 문서로 남아야 합니다. 최소 아래를 지킵니다.
+
+1. **PRD 변경** (요구사항 추가/수정/폐기):
+   - `docs/prd/*.md`: 해당 ID 추가/수정/Deprecated 표기
+2. **Idea 단계라면**:
+   - `docs/ideas/*.md`: `PRD Refs` 및 범위(포함/제외) 갱신
+3. **Feature 단계라면**:
+   - `docs/features/.../spec.md`: `PRD Refs` 갱신 + 스코프 변경 요약 반영
+   - `docs/features/.../tasks.md`: 변경을 반영하는 새 태스크 추가 + 각 태스크에 `[PRD-...]` 또는 `[NON-PRD]` 태그 부여
+   - `docs/features/.../plan.md`: 아키텍처/테스트 전략이 바뀌면 함께 갱신
+   - `docs/features/.../decisions.md`: 변경 사유/결정/영향 범위 + Evidence(커밋/PR/테스트) 기록
+
 ## CLI 설정 파일 (`.lee-spec-kit.json`)
 
 `lee-spec-kit init`을 실행하면 문서 루트(기본: `docs/`)에 `.lee-spec-kit.json`이 생성됩니다.

package/templates/ko/common/agents/agents.md

@@ -32,13 +32,14 @@
 
 ## 🧾 라벨 응답 계약 (SSOT)
 
-- 사용자에게 보내는 **모든 응답의 마지막**에 현재 상태 + 선택 가능한 라벨을 표시합니다.
+- 승인 대기 상태를 별도 상태로 취급합니다. 승인 대기란 `context --json-compact`(또는 `context --json`)에 실행 가능한 `actionOptions[]`가 있고, 현재 사용자의 승인을 기다리는 경우를 의미합니다.
 - 기준 데이터는 최신 `npx lee-spec-kit context --json-compact`를 기본으로 사용하고, 상세 필드가 필요할 때만 `context --json` 또는 `flow --json`을 사용합니다. (`flow`는 기본적으로 `--json-compact` 우선)
 - `flow --json-compact`(또는 `flow --json`)의 auto 결과를 사용할 때는 `autoRun.resume.flowCommand`를 재개 SSOT로 사용합니다. (컨텍스트 압축/리셋 후 동일 규칙 적용)
 - `AUTO_MANUAL_REQUIRED`는 자동화 경계 상태이며 실패 단정 신호가 아닙니다. `context --json-compact` 재확인 후 `approvalRequest.required` 기준으로 멈춤/보고를 판단합니다. (상세 디버깅 필드가 필요할 때만 `context --json`)
-- 라벨 설명은 `actionOptions[].detail` 또는 command `cmd`를 **원문 그대로** 사용합니다. (요약/의역 금지)
-- 사용자가 다른 질문을 하더라도, 실행 가능한 라벨이 있으면 응답 마지막에 동일 블록을 다시 표시합니다.
-- 실행 가능한 라벨이 없으면 `선택 가능: 없음` + `npx lee-spec-kit context` 재확인을 안내합니다.
+- 승인 대기 상태에서는 `actionOptions[*].approvalPrompt`를 원문 그대로 보여주고, 마지막에는 `approvalRequest.finalPrompt`를 원문 그대로 붙입니다. 가능하면 `approvalRequest.userFacingLines`를 우선 사용합니다. 이 사이에 에이전트가 임의로 다시 쓴 라벨 요약을 끼워 넣지 않습니다.
+- 위임 판단 SSOT는 `matchedFeature.currentSubstateOwner`와 `agentOrchestration.subAgentHandoff`를 우선 사용하세요. `currentActionShouldDelegate`는 구형 소비자를 위한 compatibility mirror입니다.
+- 비승인 상태의 진행 보고/분석/일반 답변에서는 라벨 블록이나 `approvalRequest.finalPrompt`를 덧붙이지 않습니다. 현재 옵션을 사용자가 직접 물었을 때만 예외입니다.
+- 관련 없는 질문에 먼저 답한 뒤에도 승인이 여전히 필요하면, 답변 후 `actionOptions[*].approvalPrompt`와 `approvalRequest.finalPrompt`를 함께 다시 제시합니다.
 - 사용자 입력에 유효 라벨이 없으면 실행하지 말고 라벨 선택을 다시 요청합니다.
 - 승인된 command 옵션 실행은 `flow --approve <LABEL> --execute` 1회 호출을 기본으로 하며, `context --approve`와 `context --execute --ticket`를 턴/세션 사이로 분리하지 않습니다.
 - `agentOrchestration.currentActionShouldDelegate=true`이고 선택한 옵션이 `actionType="command"`면 위임이 필수입니다. 먼저 `spawn_agent`를 호출하고, 해당 명령을 메인 에이전트에서 직접 실행하지 않습니다.
@@ -48,15 +49,7 @@
 - 메인 에이전트 fallback은 서브 에이전트 실행이 불가능한 경우(예: 도구 미지원, spawn 실패, 명령 실행 전 서브 에이전트 실패)에만 허용합니다.
 - fallback을 사용할 때는 메인 실행 전에 fallback 사유를 사용자에게 한 줄로 먼저 알립니다.
 
-출력 형식:
-
-```text
-현재 상태: <reasonCode 또는 상태 요약>
-선택 가능:
-A: <detail>
-B: <detail>
-응답 형식: "<LABEL>" 또는 "<LABEL> OK"
-```
+승인 대기 상태 출력은 CLI가 제공한 승인 문구를 그대로 재사용해야 합니다. CLI가 주지 않은 `현재 상태:` / `선택 가능:` 같은 래퍼 문구를 에이전트가 임의로 만들어 붙이지 마세요.
 
 ---
 

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

@@ -21,11 +21,11 @@ Pre-PR 리뷰에서 항상 수행하는 최소 기준입니다. 가능한 경우
 1. `spec.md` / `plan.md` / `tasks.md` 기준으로 변경 범위 정합성을 확인하고, 구현이 원래 목적에 맞는지 점검합니다.
 2. 회귀/예외 처리, 크리티컬·보안 리스크, 사이드 이펙트, 사용자 흐름 영향, 배포 준비도를 점검합니다.
 3. 유지보수성을 점검합니다: 큰 함수/파일은 필요 시 분리하고, 기존 코드 재사용·통합 가능성을 확인하며, 불필요해진 코드를 정리합니다.
-4. 관련 테스트/검증 명령을 실행합니다. 실행하지 못했다면 사유를 명시합니다.
-5. 리뷰 에이전트를 먼저 실행해 비어있지 않은 `commandsExecuted`를 포함한 `review-trace.json`을 만든 뒤 `npx lee-spec-kit pre-pr-review <feature-ref> --evidence review-trace.json`을 실행합니다.
-6. `PR 전 리뷰 Evidence`는 실제 존재하는 문서 경로를 사용합니다. (`workflow.prePrReview.evidenceMode=path_required` 기본)
-7. `workflow.prePrReview.enforceExecutionEvidence=true`(기본)일 때 `commandsExecuted`는 필수이며 비어있을 수 없습니다.
-8. `decisions.md`에 `Pre-PR Review Log`(또는 `PR 전 리뷰 로그`) 섹션을 두고 `Summary`/`Decision`을 placeholder 없이 기록합니다.
+4. 현재 구현이 `spec.md` / `plan.md` / `tasks.md`에 기록된 feature 의도와 범위에 실제로 맞는지 평가합니다.
+5. `workflow.prePrReview.evidenceMode=path_required`(기본)일 때는 리뷰 에이전트를 먼저 실행해 `review-trace.json`을 만든 뒤 `npx lee-spec-kit pre-pr-review <feature-ref> --evidence review-trace.json`을 실행합니다. `evidenceMode=any`에서는 실행 증거 강제가 없는 한 `--evidence` 없이 직접 기록하는 경로도 허용됩니다.
+6. `PR 전 리뷰 Evidence`는 설정된 evidence 정책을 따라야 합니다. `path_required`일 때는 실제 존재하는 문서 경로를 사용합니다.
+7. `Summary`, `Feature Intent Summary`, `Implementation Fit`, `Missing Cases`, `Spec Alignment Checked`, `Finding Count`, `Blocking Findings`, `Findings`, `Residual Risks`를 placeholder 없이 기록합니다.
+8. 리뷰 중에 audit/타깃 검증 명령을 실제로 실행했다면 그때만 `commandsExecuted`에 기록합니다.
 9. 코드리뷰 단계에서도 `PR 리뷰 Evidence/Decision`과 `decisions.md`를 동기화하고 `PR Review Log`(또는 `PR 리뷰 로그`)의 `Summary`/`Decision`을 기록합니다.
 10. `PR 전 리뷰 Decision`은 `결정: approve|changes_requested|blocked ...` (또는 `decision: ...`) 형식을 사용합니다.
 11. PR 생성 단계로 이동하기 전 최종 Decision이 `approve`인지 확인합니다.

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

@@ -24,7 +24,11 @@ CLI가 가리키는 **Active Task** 또는 **`👉 Next Options (Atomic)`의 단
 - **[DOING] 상태인 태스크가 있다면**: 해당 태스크를 최우선으로 완료하세요.
 - 태스크 상태 전환 규칙은 `tasks.md`의 **"태스크 규칙"** 섹션을 SSOT로 따릅니다.
 - 승인 대기 여부는 `context --json-compact`의 `approvalRequest.required`를 SSOT로 따릅니다. (`--json`은 상세 디버깅이 필요할 때만 사용) `false`면 라벨 승인 없이 진행하고, `true`면 라벨 규칙(`A`, `A OK`)으로 승인 후 진행합니다.
-- 기본 실행 모델은 **메인 에이전트 오케스트레이션 + 선택적 서브 에이전트 실행**입니다. 짧은 단계(spec/plan/tasks 승인, 이슈/PR 메타 동기화 등)는 메인 에이전트가 직접 처리하고, 장시간 루프(`task_execute`, `code_review`, `review_fix_commit`, `pre_pr_review`, auto-run)는 서브 에이전트에 위임합니다.
+- 기본 실행 모델은 **메인 에이전트 오케스트레이션 + 서브에이전트 소유 run 상태의 우선 위임 실행**입니다. `context --json-compact`에 `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`가 있으면 그것을 실행 상태 SSOT로 사용합니다.
+- 메인 에이전트는 승인 경계, 상태 전이, record/commit 단계, 원격 작업을 담당합니다. `subagent` 소유 command substate(예: `task_run`, `pre_pr_review_run`, `code_review_run`, auto-run handoff command)는 서브 에이전트 실행이 기본입니다.
+- `pre_pr_review`는 `pre_pr_review_run`(서브 에이전트 리뷰 실행)과 `pre_pr_review_record`(메인 에이전트의 결과 기록)로 분리됩니다.
+- PR 리뷰도 같은 패턴입니다. `code_review_run`은 서브 에이전트 리뷰/수정 실행 상태이고, push/merge/최종 결정은 메인 에이전트 finalize 상태에 남깁니다.
+- 위임 판단은 `matchedFeature.currentSubstateOwner`와 `agentOrchestration.subAgentHandoff`를 SSOT로 우선 사용하세요. `currentActionShouldDelegate`는 compatibility mirror로 남아 있습니다.
 - `agentOrchestration.currentActionShouldDelegate=true`이고 선택한 옵션이 `actionType="command"`면 위임이 필수입니다. 먼저 `spawn_agent`를 호출하고, 해당 명령을 메인 에이전트에서 직접 실행하지 않습니다.
 - `autoRun.available`만으로 auto 루프 위임을 결정하지 않습니다. `agentOrchestration.subAgentHandoff.required=true`이고 `agentOrchestration.subAgentHandoff.mode="auto_run"`일 때만 auto 루프를 서브 에이전트에 위임합니다.
 - `agentOrchestration.subAgentHandoff`를 최소 handoff 계약(`featureRef`, `category`, `cwd`, `cmd`)으로 사용합니다.
@@ -35,7 +39,7 @@ CLI가 가리키는 **Active Task** 또는 **`👉 Next Options (Atomic)`의 단
 - auto 실행이 중단되면 `flow --json-compact`(또는 `flow --json`)의 `autoRun.resume`를 SSOT로 따릅니다. 컨텍스트 압축/리셋 후에는 `autoRun.resume.flowCommand`로 재개하고, 필요 시 `autoRun.resume.contextCommand`로 상태를 먼저 확인합니다.
 - `AUTO_MANUAL_REQUIRED`는 실패가 아니라 자동화 경계(현재 instruction-only 구간)입니다. 즉시 오류로 단정하지 말고 현재 `context --json-compact`를 다시 확인한 뒤 승인 필요 여부(`approvalRequest.required`)를 보고합니다.
 - CLI가 명령어를 출력하면 **그대로 복사해 실행**합니다. (standalone 환경에서도 레포 경로가 포함될 수 있습니다)
-- 사용자 응답 포맷(매 응답 말미의 상태/라벨 표시 포함)은 `agents.md`의 **"라벨 응답 계약 (SSOT)"** 을 따릅니다.
+- 사용자 응답 포맷은 `agents.md`의 **"라벨 응답 계약 (SSOT)"** 을 따릅니다. 라벨 문구는 승인 대기 상태에서만 보여주고, CLI가 준 승인 문구를 임의로 바꾸지 않습니다.
 - 승인된 command 옵션 실행은 `npx lee-spec-kit flow <slug|F001|F001-slug> --approve <LABEL> --execute`를 기본으로 사용하고, `context --approve`와 `context --execute --ticket` 분리 실행은 지양합니다.
 
 ### 3단계: 기록 및 반복 (Record & Loop)

package/templates/ko/common/features/README.md

@@ -60,6 +60,28 @@ npx lee-spec-kit status --write
 
 ---
 
+## PRD 요구사항 추적 (권장)
+
+- PRD 문서(`docs/prd/*.md`)에 `PRD-FR-001` 같은 요구사항 ID를 부여하세요.
+- `tasks.md`의 각 태스크 라인에 `[PRD-FR-001]` 태그로 연결하세요. PRD와 무관한 태스크는 `[NON-PRD]`를 사용하세요.
+- 커버리지 리포트: `npx lee-spec-kit requirements` (alias: `npx lee-spec-kit prd`)
+
+---
+
+## 변경 프로토콜 (기능 진행 중 요구사항/범위 변경)
+
+중간 변경이 생기면, “어디를 고쳤는지”와 “무엇을 업데이트했는지”가 문서로 남아야 합니다.
+
+- 변경은 **새 태스크로 추가**합니다. (`[DONE]` 태스크를 고치지 말고 새 태스크를 만드세요)
+- 변경 태스크에는 `[PRD-...]` 또는 `[NON-PRD]` 태그를 반드시 붙입니다. (권장: `[CHANGE]` 태그 추가)
+- 변경이 PRD/스펙/설계에 영향을 주면 아래도 함께 갱신합니다:
+  - `docs/prd/*.md` (요구사항 ID 추가/수정/Deprecated)
+  - `spec.md` (`PRD Refs`, 스코프/AC)
+  - `plan.md` (아키텍처/테스트 전략)
+  - `decisions.md` (왜 바뀌었는지 + Evidence)
+
+---
+
 ## 상태 용어 정리
 
 | 구분 | 필드 | 값 |

package/templates/ko/common/features/feature-base/spec.md

@@ -55,3 +55,5 @@
 ## 관련 문서
 
 - PRD: `../../prd/`
+- PRD Refs: - (예: `PRD-FR-001`, `PRD-US-002`)
+  - 요구사항/스코프 변경 시 PRD 문서 + 이 필드 + `tasks.md` 태스크 태그를 함께 갱신하세요.

package/templates/ko/common/features/feature-base/tasks.md

@@ -7,6 +7,7 @@
   - `[TODO] → [DOING]`: 시작 전 태스크 제목 공유 + 사용자 승인(OK)
   - `[DOING] → [DONE]`: 완료 전 결과/검증 공유 + 사용자 승인(OK)
 - **우선순위**: P0(긴급) > P1(높음) > P2(보통) > P3(낮음)
+- **PRD 매핑(권장)**: 각 태스크 라인에 `[PRD-FR-001]` 같은 PRD 요구사항 ID 태그를 추가하거나, PRD와 무관한 태스크는 `[NON-PRD]`로 표시하세요.
 
 ---
 
@@ -45,7 +46,7 @@
 > 아래 포맷을 복사해 사용하세요.
 
 ```markdown
-- [TODO][P1] T-F{번호}-01 {태스크 제목}
+- [TODO][P1][PRD-FR-001] T-F{번호}-01 {태스크 제목}
   - Date: YYYY-MM-DD
   - Acceptance:
     - (검증 조건)
@@ -53,6 +54,19 @@
     - [ ] (서브 태스크)
 ```
 
+(권장) 요구사항/범위 변경 태스크:
+
+중간 변경은 **새 태스크로 추가**하고, 어떤 문서를 함께 업데이트해야 하는지 `Impact Docs`로 명시합니다.
+
+```markdown
+- [TODO][P1][PRD-FR-001][CHANGE] T-F{번호}-02 {태스크 제목} (요구사항/범위 변경)
+  - Impact Docs:
+    - docs/prd/... (요구사항 변경이 있으면)
+    - spec.md (PRD Refs/AC/스코프)
+    - plan.md (아키텍처/테스트 전략)
+    - decisions.md (변경 사유 + Evidence)
+```
+
 ---
 
 ## 완료 조건

package/templates/ko/common/ideas/README.md

@@ -14,17 +14,30 @@ Feature로 발전하기 전의 아이디어 / To-do / 실험 기록을 모아두
 - 상단에 최소한 아래 메타 정보를 둡니다:
   - 목적/배경
   - 대략 범위(뭘 할지/안 할지)
+  - PRD Refs(권장): `PRD-FR-001, PRD-US-002` (PRD와 무관하면 `NON-PRD` 명시)
   - 대상 컴포넌트(필요 시): `api` / `app` / `worker` / `all`
+  - 상태(권장): `Active | Converted | Dropped`
 
 ---
 
 ## 승격/정리 규칙 (Idea → Feature)
 
 1. `npx lee-spec-kit feature <name>`로 Feature 폴더 생성
-2. 새 Feature의 `spec.md` 또는 `tasks.md`에 아이디어 문서 경로를 남깁니다
-   - 예: `docs/ideas/login-rate-limit.md`
+2. 새 Feature에 아래를 모두 남깁니다
+   - `spec.md` 또는 `tasks.md`에 아이디어 문서 경로 (예: `docs/ideas/login-rate-limit.md`)
+   - `spec.md`의 `PRD Refs`(예: `PRD-FR-001, PRD-US-002`)
+   - `tasks.md` 태스크 라인에 `[PRD-FR-001]` 같은 PRD ID 태그 (PRD와 무관한 태스크는 `[NON-PRD]`)
 3. 아이디어 문서는 **목록에서 제거**합니다 (둘 중 하나 선택):
    - **권장**: `docs/ideas/archive/`로 이동 후 상단에 `Status: Converted`, `Feature: F00X-...` 기록
    - 또는: 완전히 삭제 (히스토리가 필요 없을 때만)
 
 > 💡 완전 삭제 대신 archive를 권장합니다: “왜 이 Feature가 생겼는지” 추적에 도움이 됩니다.
+
+---
+
+## 변경 프로토콜 (Idea 단계에서 내용이 바뀔 때)
+
+Idea 단계에서도 변경은 “어디를 고쳤는지”가 남아야 합니다.
+
+- PRD 요구사항이 추가/변경되면: Idea 문서의 `PRD Refs`를 먼저 갱신하고, 필요하면 PRD 문서(`docs/prd/*.md`)에도 ID를 추가/수정합니다.
+- 아이디어가 Feature로 승격된 뒤에 변경이 생기면: Idea가 아니라 Feature(`spec.md`/`tasks.md`/`plan.md`/`decisions.md`)를 SSOT로 갱신합니다.

package/templates/ko/common/prd/README.md

@@ -13,6 +13,34 @@
 2. 주요 기능과 사용자 스토리를 작성하세요
 3. 기술 아키텍처 개요를 포함하세요
 
+## 요구사항 ID 규칙 (권장)
+
+PRD의 “어느 요구사항이 구현됐는지”를 CLI가 집계할 수 있도록, 요구사항에 **안정적인 ID**를 부여하세요.
+
+- 형식: `PRD-FR-001`, `PRD-US-002`, `PRD-NFR-003`
+- 같은 줄(헤더/불릿) 안에 ID만 포함되어 있으면 됩니다.
+- Feature의 `tasks.md` 태스크 라인에 `[PRD-FR-001]`처럼 **대괄호 태그**로 참조하세요.
+- PRD와 무관한 태스크는 `[NON-PRD]` 태그로 표시하세요.
+
+예시:
+
+```md
+- PRD-FR-001: 로그인 rate limit
+### PRD-US-002: 관리자는 지표를 볼 수 있다
+```
+
+## 변경 규칙 (요구사항 추가/변경/폐기)
+
+요구사항이 바뀌면 “어디를 고쳐야 하는지”가 명확해야 합니다.
+
+- **ID 안정성**:
+  - ID는 재번호 부여/재사용하지 않습니다.
+  - 요구사항이 폐기되면 삭제 대신 `Deprecated` 표기 + 이유/대체 ID를 기록합니다.
+  - 요구사항이 분리/병합되면, 기존 ID는 유지하고 새 ID를 추가한 뒤 관계를 PRD에 명시합니다.
+- **연쇄 업데이트(필수)**:
+  - PRD 변경이 이미 진행 중인 Feature에 영향을 주면, 해당 Feature의 `spec.md`(`PRD Refs`), `tasks.md`(태스크 태그), 필요 시 `plan.md`와 `decisions.md`까지 함께 갱신합니다.
+  - 아직 Feature가 없다면, `docs/ideas/*.md`에 `PRD Refs`를 남겨 “승격 전 상태”에서도 추적 가능하게 유지합니다.
+
 ## 예시 파일
 
 - `{project-name}-prd.md` - 메인 PRD 문서