lee-spec-kit 0.5.0 → 0.5.2

package/README.en.md

@@ -150,6 +150,7 @@ npx lee-spec-kit feature payment --id F123 --desc "Improve payment flow"
 | `--id <id>`         | Feature ID (`F001` format)                  | auto-generate |
 | `-d, --desc <desc>` | Default purpose/description text for `spec.md` | empty string |
 | `--non-interactive` | Fail immediately instead of prompting for user input | `false` |
+| `--json`            | JSON output (`featureId`, `featurePath`, `component`) | `false` |
 
 ### Context (agent guide)
 
@@ -202,9 +203,12 @@ npx lee-spec-kit context F001 --approve A --execute --execute-strict
 `--json` output includes:
 
 - `reasonCode`: status reason code (`SINGLE_MATCHED`, `MULTIPLE_ACTIVE_FEATURES`, etc.)
-- `actionOptions`: maps labels to atomic actions
+- `operationType`: action nature (`local` | `remote` | `manual`)
+- `actionOptions`: maps labels to atomic actions plus `summary`/`approvalPrompt` for user-facing label explanation
+- `primaryActionLabel` / `primaryActionType` / `primaryActionCategory` / `primaryActionOperationType`: metadata for the first atomic action
+- `selectionFallback`: fallback used when branch auto-detection does not match (`none` | `open_features` | `all_features` | `done_features`)
 - `workflowPolicy`: current completion policy (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
-- `checkPolicy`: approval validation policy (`token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion`, ...)
+- `checkPolicy`: approval validation policy (`hint`, `policyOnly`, `token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `requireExplanationBeforeApproval`, `requiredExplanationFields`, `contextVersion`, ...)
 
 Error payloads (`status: "error"`) include `reasonCode` and labeled `suggestions` (`A/B/C`) (e.g. `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`).
 
@@ -249,6 +253,28 @@ npx lee-spec-kit flow --json
 | `--execute-strict`| With `--execute`, fail if approved option is instruction-only |
 | `--strict`        | Also run `status --strict` and `doctor --strict` |
 
+### GitHub helpers
+
+```bash
+# Generate issue body from selected feature
+npx lee-spec-kit github issue F001
+
+# Generate + create issue
+npx lee-spec-kit github issue F001 --create --labels enhancement,frontend
+
+# Generate PR body
+npx lee-spec-kit github pr F001
+
+# Generate + create PR + sync tasks.md metadata + merge with retry
+npx lee-spec-kit github pr F001 --create --merge --labels enhancement,frontend
+```
+
+Key points:
+- Issue/PR helpers validate required body sections and related docs paths.
+- Labels are validated (at least one required).
+- PR helper can sync `tasks.md` PR URL/PR Status automatically (`--no-sync-tasks` to skip).
+- Merge includes retry and automatic head-branch refresh (fetch/rebase/force-push) on out-of-date failures.
+
 ### Status
 
 ```bash
@@ -286,8 +312,16 @@ npx lee-spec-kit doctor --strict
 npx lee-spec-kit doctor --json
 npx lee-spec-kit doctor --fix
 npx lee-spec-kit doctor --fix --dry-run
+npx lee-spec-kit doctor --decisions-placeholders off
+npx lee-spec-kit doctor --decisions-placeholders info
+npx lee-spec-kit doctor --decisions-placeholders warn
 ```
 
+- `--decisions-placeholders <mode>`:
+  - `off`: ignore `decisions.md` placeholders
+  - `info` (default): include as informational findings (non-blocking)
+  - `warn`: treat as warnings
+
 ### Update templates
 
 By default, `update` runs only when the `docs/` working tree is clean; in that case it overwrites changed files without prompting.  
@@ -314,7 +348,7 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
   "lang": "en",
   "createdAt": "YYYY-MM-DD",
   "docsRepo": "embedded",
-  "workflow": { "mode": "github" },
+  "workflow": { "mode": "github", "codeDirtyScope": "auto" },
   "pr": { "screenshots": { "upload": false } },
   "approval": { "mode": "builtin" }
 }
@@ -331,7 +365,7 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 | `pushDocs`    | (standalone only) whether to manage/push docs repo as a separate git repo |
 | `docsRemote`  | (standalone + pushDocs) docs repo remote URL |
 | `projectRoot` | (standalone only) project repo path (single: string, multi: `{ [component]: path }`) |
-| `workflow`    | (optional) workflow completion policy (`github`/`local`) |
+| `workflow`    | (optional) workflow completion policy (`github`/`local`, `codeDirtyScope`) |
 | `pr`          | (optional) PR artifacts policy (e.g. screenshot upload) |
 | `approval`    | (optional) Override CHECK-required policy in `context` output (for automation/semi-auto) |
 
@@ -348,6 +382,8 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 - `checkPolicy.acceptedTokens`: accepted reply templates (e.g. `["<LABEL>", "<LABEL> OK"]`)
 - `checkPolicy.tokenPattern`: input validation regex for approval replies
 - `checkPolicy.validLabels`: currently selectable labels (`A`, `B`, `C`...)
+- `checkPolicy.requireExplanationBeforeApproval`: require label-by-label explanation before asking approval
+- `checkPolicy.requiredExplanationFields`: fields to use for explanation (e.g. `actionOptions[].summary`)
 - `checkPolicy.contextVersion`: snapshot hash for stale-context validation
 - `actionOptions`: maps `label` (`A`, `B`, `C`...) to each atomic `action`
 - `workflowPolicy`: current completion policy (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
@@ -361,12 +397,18 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 - `workflow.mode: "github"` (default): issue/branch/PR/review are required in workflow completion
 - `workflow.mode: "local"`: local-first workflow; issue/branch/PR/review are not required
   - Feature templates generated in local mode minimize Issue/PR-focused sections by default.
+- `workflow.codeDirtyScope`:
+  - `repo`: evaluate uncommitted code changes across the whole project repo
+  - `component`: evaluate only paths mapped to the current feature component (recommended for multi)
+  - `auto`: `single => repo`, `multi => component`
+  - `workflow.componentPaths` (optional): explicit per-component paths for component-scoped checks (e.g. `"web": ["apps/web", "packages/web-ui"]`)
+  - backward compatibility: if omitted, runtime defaults to `repo`
 
 Example:
 
 ```json
 {
-  "workflow": { "mode": "local" }
+  "workflow": { "mode": "local", "codeDirtyScope": "auto" }
 }
 ```
 

package/README.md

@@ -166,6 +166,7 @@ npx lee-spec-kit feature payment --id F123 --desc "결제 플로우 개선"
 | `--id <id>`         | Feature ID (`F001` 형식)                     | 자동 생성   |
 | `-d, --desc <desc>` | `spec.md`의 목적(설명) 기본 문구             | 빈 문자열   |
 | `--non-interactive` | 사용자 입력이 필요하면 프롬프트 대신 즉시 실패 | `false`     |
+| `--json`            | JSON 출력 (`featureId`, `featurePath`, `component`) | `false` |
 
 ### Context 확인 (AI 에이전트 가이드)
 
@@ -221,12 +222,15 @@ npx lee-spec-kit context F001 --approve A --execute --execute-strict
 - `reasonCode`: 상태 이유 코드 (`SINGLE_MATCHED`, `MULTIPLE_ACTIVE_FEATURES` 등)
 - `type: "command"`: `scope`(project|docs), `cwd`, `cmd` 제공 (복사하여 붙여넣기 가능한 형태로 `cd ... && git ...` 형태로 출력)
 - `type: "instruction"`: 사람이 수행해야 하는 안내 메시지
-- `actionOptions`: `label`(`A`, `B`, `C`...)과 해당 `action` 매핑
+- `operationType`: 액션 성격 (`local` | `remote` | `manual`)
+- `actionOptions`: `label`(`A`, `B`, `C`...)과 해당 `action` 매핑 + `summary`/`approvalPrompt`(라벨 설명 템플릿)
+- `primaryActionLabel`/`primaryActionType`/`primaryActionCategory`/`primaryActionOperationType`: 첫 번째 원자 액션의 요약 메타데이터
+- `selectionFallback`: 자동 감지 실패 시 사용된 폴백 (`none` | `open_features` | `all_features` | `done_features`)
 - `category`: 액션 분류 (자동화/반자동용 `approval.mode: "category"`에서 사용)
 - `requiresUserCheck`: 사용자 확인 필요 여부 (에이전트는 **사용자 응답을 `<라벨>` 또는 `<라벨> OK` 형식(예: `A`, `A OK`)으로 제한**하는 것을 권장 / 설정의 `approval`로 오버라이드 가능)
 - `workflowPolicy`: 현재 완료 조건 정책 (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
 
-또한 `checkPolicy`가 포함되어, 에이전트가 사용자 확인 정책을 적용할 때 참고할 수 있습니다. (`docPath`, `hint`, `token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion`, `config`)
+또한 `checkPolicy`가 포함되어, 에이전트가 사용자 확인 정책을 적용할 때 참고할 수 있습니다. (`docPath`, `hint`, `policyOnly`, `token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `requireExplanationBeforeApproval`, `requiredExplanationFields`, `contextVersion`, `config`)
 
 오류 응답(`status: "error"`)에는 `reasonCode`와 `suggestions`(라벨형 다음 동작: `A/B/C`)가 포함됩니다. (예: `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`)
 
@@ -271,6 +275,28 @@ npx lee-spec-kit flow --json
 | `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
 | `--strict`         | `status --strict`, `doctor --strict`까지 함께 검사 |
 
+### GitHub helper
+
+```bash
+# 선택된 Feature 기준 Issue 본문 생성
+npx lee-spec-kit github issue F001
+
+# Issue 본문 생성 + 실제 Issue 생성
+npx lee-spec-kit github issue F001 --create --labels enhancement,frontend
+
+# PR 본문 생성
+npx lee-spec-kit github pr F001
+
+# PR 본문 생성 + PR 생성 + tasks.md 메타데이터 동기화 + merge 재시도
+npx lee-spec-kit github pr F001 --create --merge --labels enhancement,frontend
+```
+
+핵심 동작:
+- Issue/PR helper는 필수 섹션과 관련 문서 경로를 검증합니다.
+- 라벨은 최소 1개 이상 필수입니다.
+- PR helper는 기본적으로 `tasks.md`의 `PR`/`PR Status`를 동기화합니다. (`--no-sync-tasks`로 비활성화)
+- merge 시 head 브랜치가 뒤쳐진 경우 fetch/rebase/force-push 후 재시도합니다.
+
 ### 상태 확인
 
 ```bash
@@ -327,8 +353,18 @@ npx lee-spec-kit doctor --fix
 
 # 수정 예정 항목만 미리 확인 (파일 미변경)
 npx lee-spec-kit doctor --fix --dry-run
+
+# decisions.md 플레이스홀더 진단 레벨 조정
+npx lee-spec-kit doctor --decisions-placeholders off
+npx lee-spec-kit doctor --decisions-placeholders info
+npx lee-spec-kit doctor --decisions-placeholders warn
 ```
 
+- `--decisions-placeholders <mode>`
+  - `off`: `decisions.md` 플레이스홀더를 진단에서 제외
+  - `info` (기본): 정보 레벨로만 보고 (strict 실패 대상 아님)
+  - `warn`: 경고로 보고
+
 ### 템플릿 업데이트
 
 기본 동작은 `docs/` 작업트리에 변경사항이 없을 때만 업데이트를 진행하며, 이 경우 변경된 파일은 확인 없이 덮어씁니다.  
@@ -364,7 +400,7 @@ npx lee-spec-kit update --force
   "lang": "ko",
   "createdAt": "YYYY-MM-DD",
   "docsRepo": "embedded",
-  "workflow": { "mode": "github" },
+  "workflow": { "mode": "github", "codeDirtyScope": "auto" },
   "pr": { "screenshots": { "upload": false } },
   "approval": { "mode": "builtin" }
 }
@@ -381,7 +417,7 @@ npx lee-spec-kit update --force
 | `pushDocs`    | (standalone만) docs 레포를 별도 Git으로 관리/푸시할지 여부 |
 | `docsRemote`  | (standalone+pushDocs) docs 레포 remote URL |
 | `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 (single: string, multi: `{ [component]: path }`) |
-| `workflow`    | (선택) 워크플로우 요구사항 정책 (`github`/`local`) |
+| `workflow`    | (선택) 워크플로우 요구사항 정책 (`github`/`local`, `codeDirtyScope`) |
 | `pr`          | (선택) PR 결과물 정책 (예: 스크린샷 업로드 여부) |
 | `approval`    | (선택) `context` 출력의 `[확인 필요]`/`requiresUserCheck` 정책 오버라이드 (자동화/반자동용) |
 
@@ -400,6 +436,8 @@ npx lee-spec-kit update --force
 - `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK"]`)
 - `checkPolicy.tokenPattern`: 승인 응답 검증용 정규식
 - `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
+- `checkPolicy.requireExplanationBeforeApproval`: 승인 요청 전에 라벨별 설명을 포함해야 함
+- `checkPolicy.requiredExplanationFields`: 라벨 설명에 사용할 필드 목록 (예: `actionOptions[].summary`)
 - `checkPolicy.contextVersion`: stale context 검증용 스냅샷 해시
 
 > 실제 명령 실행을 강제/차단하는 기능은 아닙니다. (에이전트가 참고하도록 신호를 제공)
@@ -411,12 +449,18 @@ npx lee-spec-kit update --force
 - `workflow.mode: "github"` (기본): Issue/브랜치/PR/리뷰 단계를 포함한 전체 워크플로우를 완료 조건으로 사용
 - `workflow.mode: "local"`: 로컬 중심 워크플로우로 동작하며 Issue/브랜치/PR/리뷰 단계를 필수로 요구하지 않음
   - local 모드로 생성한 Feature 템플릿은 기본적으로 Issue/PR 중심 섹션을 축소합니다.
+- `workflow.codeDirtyScope`:
+  - `repo`: 프로젝트 레포 전체 변경으로 코드 미커밋 여부를 판정
+  - `component`: 현재 Feature 컴포넌트 경로 변경만 판정 (multi 권장)
+  - `auto`: `single => repo`, `multi => component`
+  - `workflow.componentPaths`(선택): component 판정 경로를 컴포넌트별로 명시 (예: `"web": ["apps/web", "packages/web-ui"]`)
+  - 하위 호환: 값이 없으면 기존 동작인 `repo`로 처리
 
 예시:
 
 ```json
 {
-  "workflow": { "mode": "local" }
+  "workflow": { "mode": "local", "codeDirtyScope": "auto" }
 }
 ```