lee-spec-kit 0.6.42 → 0.7.0

package/README.en.md

@@ -107,7 +107,7 @@ You can paste the following as an agent session-start instruction.
 Start procedure:
 1) Run npx lee-spec-kit detect --json
 2) If isLeeSpecKitProject === true, run npx lee-spec-kit context --json-compact (use --json only when full detail is needed)
-3) If actionOptions exist, show approvalPrompt and finalPrompt exactly as provided, then wait for user approval (<LABEL> or <LABEL> OK)
+3) If approvalRequest.required=true, show approvalRequest.userFacingLines exactly as provided, then wait for user approval (<LABEL> or <LABEL> OK)
 4) Do not execute before approval; execute requiresUserCheck=true actions only after approval
 5) If isLeeSpecKitProject === false, skip lee-spec-kit-specific flow and continue with normal workflow
 ```
@@ -280,30 +280,26 @@ Use advanced selectors (`--component`, `--all`, `--done`) only when you need mul
 - A one-time execution token issued by the CLI when you approve a label via `--approve`.
 - `--ticket` is required for `--execute` only when the selected action has `requiresUserCheck=true`.
 - It is short-lived (5 minutes by default) and cannot be reused after one execution.
+- When you `--execute` a handoff-only command (`pre_pr_review_run`, `code_review_run`), the result is `approved_handoff_prepared` with `nextMainState` instead of the normal `approved_executed`.
 
-`context --json-compact` is the default recommended format, providing a reduced and deduplicated decision state.  
+`context --json-compact` is the default recommended format, providing a minimal hot-path contract for agents.  
 Use `context --json` only when full-detail debugging fields are required.
 
 **Core fields (recommended for normal agent flows)**
 
 - `status` / `reasonCode`: current state and reason code
-- `actions[]`: atomic action list
-  - `type: "command"`: `scope` (project|docs), `cwd`, `cmd`, `category`, `operationType`, `requiresUserCheck`
-  - `type: "instruction"`: `message`, `category`, `operationType`, `requiresUserCheck`
-- `actionOptions[]`: `label` (`A`, `B`, `C`...) + target `action` + user-facing `summary` / `detail` / `approvalPrompt`
-- `approvalRequest`: ready-to-use approval/execute guidance (`labels`, `approveCommand`, `executeCommand`, `options[]`)
+- `actionOptions[]`: `label` (`A`, `B`, `C`...) + the minimal execution contract (`detail`, `actionType`, `category`, `operationType`, `requiresUserCheck`, plus command/instruction payload)
+- `approvalRequest`: approval state and user-facing prompt lines (`required`, `userFacingLines`, `finalPrompt`)
 - `requiredDocs`: built-in docs to read before the current action (`id`, `command`)
-- `checkPolicy`: approval validation policy (`token`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion`, ...)
-- `agentOrchestration`: main-agent (conversation/approval) + sub-agent (execution) contract. The current SSOT is `subAgentHandoff` plus `matchedFeature.currentSubstate*`; `delegateCommandExecution`, `longRunningCategories`, and `currentActionShouldDelegate` are compatibility fields.
+- `checkPolicy`: minimal approval state (`token`, `validLabels`, `checkRequiredLabels`, `checkRequiredCategories`, `approvalRequired`, `contextVersion`)
+- `agentOrchestration`: compact keeps only `subAgentHandoff`. Delegation SSOT is `matchedFeature.currentSubstate*` + `subAgentHandoff`.
 - `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`: current step-internal execution state for owner/phase-aware orchestration
+- `actions[]`: the raw atomic action list remains available in detailed `context --json`.
 
 **Advanced/reference fields (automation edge cases or debugging)**
 
-- `selectionFallback`: fallback used when branch auto-detection does not match (`none` | `open_features` | `all_features` | `done_features`)
-- `primaryActionLabel` / `primaryActionType` / `primaryActionCategory` / `primaryActionOperationType`: summary metadata for the first atomic action
-- `workflowPolicy`: current completion policy (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
-- `taskCommitGatePolicy`: task commit gate policy (`off` | `warn` | `strict`)
-- `prePrReviewPolicy`: pre-PR review policy (`enabled`, `skills`, `fallback`)
+- `selectionFallback`: fallback used when branch auto-detection does not match (`none` | `open_features` | `all_features` | `done_features`) and only appears in compact for non-hot-path selection states
+- `primaryActionLabel` / `workflowPolicy` / `taskCommitGatePolicy` / `prePrReviewPolicy`: detailed debugging/policy fields available from `context --json`
 
 Error payloads (`status: "error"`) include `reasonCode` and labeled `suggestions` (`A/B/C`) (e.g. `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`).
 
@@ -402,12 +398,15 @@ Auto gate mode rules:
 - `--request` requires auto mode.
   - Exception: if `workflow.auto.defaultPreset` is configured, `--request` alone enables auto mode.
 - `--resume <run-id>` cannot be combined with `<feature-name>`, `--component`, `--all`, `--done`, `--auto-*`, or `--request`. (It uses settings from the stored checkpoint.)
-- Auto-run stops as `gate_reached` when a target category appears, then prints that step's approval text (`approvalRequest.userFacingLines`).
+- Auto-run stops as `gate_reached` when a target category appears, then prints `autoRun.gate.userFacingLines`. (This is copied from that step's `approvalRequest.userFacingLines`.)
+- In `context --json` / `--json-compact`, `autoRun.available` means "auto-run can execute right now". If config allows auto-run but the current step is instruction-only, you get `autoRun.available=false`, `autoRun.policyEligible=true`, `autoRun.executableNow=false`, and `autoRun.manualBoundary`.
 - If the current action set is instruction-only (no executable command), auto-run may stop with `AUTO_MANUAL_REQUIRED`. This is an automation boundary, not a CLI crash.
 - If progress stalls (same context/action repeating), it stops with `AUTO_NO_PROGRESS`.
-- In JSON mode, inspect `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.executions`, and `autoRun.resume`.
+- In JSON mode, inspect `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.manual`, and `autoRun.resume`.
+  - Detailed `flow --json` keeps the full `autoRun.executions` array.
+  - Compact `flow --json-compact` keeps only `autoRun.executionCount` and `autoRun.lastExecution`.
 - Inspect JSON `agentOrchestration` and `matchedFeature.currentSubstate*` for main/sub-agent responsibilities and pause/report boundaries.
-  - Prefer `matchedFeature.currentSubstateOwner` plus `subAgentHandoff` as the delegation signal when present. `longRunningCategories` and `currentActionShouldDelegate` remain legacy compatibility metadata for older non-substate paths.
+  - Prefer `matchedFeature.currentSubstateOwner` plus `subAgentHandoff` as the delegation signal when present. Compact keeps only `subAgentHandoff`; use detailed `--json` / `flow --json` when you need extra orchestration metadata.
 - With `--start-auto`, JSON also includes `autoRun.run` (`runId`, `status`, `resumeCommand`).
 
 Agent resume rules (recommended):
@@ -438,7 +437,7 @@ npx lee-spec-kit github pr F001 --create --merge --confirm OK --labels enhanceme
 Key points:
 - Issue/PR helpers validate required body sections and related docs paths.
 - `--json` output includes both `body` (inline markdown) and `bodyFile` (file path).
-- Labels are validated (at least one required).
+- If `--labels` is omitted, the default label is `enhancement`. When you pass `--labels` explicitly, it must not be empty.
 - `--create`/`--merge` are remote operations and require `--confirm OK`.
 - PR helper can sync `tasks.md` PR URL/PR Status automatically (`--no-sync-tasks` to skip).
 - PR artifact sections are controlled by `--screenshots (auto|on|off)` and `--mermaid (auto|on|off)`.
@@ -590,16 +589,11 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 - the `[CHECK required]` tag in text output
 - `actionOptions[].requiresUserCheck` in `context --json-compact` (`actions[].requiresUserCheck` in `--json`)
 - `checkPolicy.token` (`context --json-compact`/`--json`): approval token format (`<LABEL>`)
-- `checkPolicy.acceptedTokens`: accepted reply templates (e.g. `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
-- `checkPolicy.tokenPattern`: input validation regex for approval replies
 - `checkPolicy.validLabels`: currently selectable labels (`A`, `B`, `C`...)
-- `checkPolicy.activeCategories`: categories currently present in actions (from `actionOptions[].category`)
-- `checkPolicy.knownCategories`: full category list recognized by the CLI
-- `checkPolicy.uncategorizedLabels`: labels with missing category (should normally be empty)
-- `checkPolicy.categoryPolicyGuidance`: guidance for matching categories in `approval.mode="category"`
-- `checkPolicy.requireExplanationBeforeApproval`: require label-by-label explanation before asking approval
-- `checkPolicy.requiredExplanationFields`: fields to use for explanation (e.g. `actionOptions[].detail`)
+- `checkPolicy.checkRequiredLabels` / `checkPolicy.checkRequiredCategories`: labels/categories that currently require approval
+- `checkPolicy.approvalRequired`: whether the current state is approval-blocked
 - `checkPolicy.contextVersion`: snapshot hash for stale-context validation
+- `checkPolicy.acceptedTokens`, `tokenPattern`, `activeCategories`, `knownCategories`, `uncategorizedLabels`, `categoryPolicyGuidance`, `requireExplanationBeforeApproval`, and `requiredExplanationFields` remain available in detailed `context --json`.
 - `actionOptions`: maps `label` (`A`, `B`, `C`...) to each atomic `action`
 - `workflowPolicy`: current completion policy (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
 - `taskCommitGatePolicy`: task commit gate policy (`off` | `warn` | `strict`)
@@ -711,7 +705,7 @@ Pre-PR execution gate risks and mitigations:
 }
 ```
 
-> Discover category values from `context --json`/`--json-compact` using `checkPolicy.activeCategories` (current), `checkPolicy.knownCategories` (full), and `actionOptions[].category` (per-label).
+> Discover category values from detailed `context --json` using `checkPolicy.activeCategories` / `checkPolicy.knownCategories`, or from `actionOptions[].category`. Compact keeps only the hot-path contract.
 
 ### pr (PR artifacts policy)
 

package/README.md

@@ -122,7 +122,7 @@ npx lee-spec-kit detect --json
 작업 시작 절차:
 1) npx lee-spec-kit detect --json
 2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json-compact 실행 (필요 시 --json으로 상세 조회)
-3) actionOptions가 있으면 approvalPrompt와 finalPrompt를 그대로 사용자에게 제시하고 승인(<LABEL> 또는 <LABEL> OK) 대기
+3) approvalRequest.required=true 이면 approvalRequest.userFacingLines를 그대로 사용자에게 제시하고 승인(<LABEL> 또는 <LABEL> OK) 대기
 4) 승인 전에는 실행하지 말고, requiresUserCheck=true 액션은 승인 후에만 실행
 5) isLeeSpecKitProject === false 이면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행
 ```
@@ -299,30 +299,26 @@ npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-
 - `--approve`로 라벨을 승인할 때 CLI가 발급하는 1회용 실행 토큰입니다.
 - 선택한 액션이 `requiresUserCheck=true`인 경우에만 `--execute`에서 `--ticket`이 필요합니다.
 - 발급 후 짧은 시간(기본 5분)만 유효하며, 한 번 사용하면 재사용할 수 없습니다.
+- handoff-only command(`pre_pr_review_run`, `code_review_run`)를 `--execute`하면 일반 실행 완료(`approved_executed`) 대신 `approved_handoff_prepared`와 `nextMainState`가 반환됩니다.
 
-기본 권장 포맷은 `context --json-compact`이며, 같은 판단 정보를 중복 없이 축약해 전달합니다.  
+기본 권장 포맷은 `context --json-compact`이며, 에이전트 hot path에 필요한 상태만 최소 계약으로 전달합니다.  
 `context --json`은 디버깅/세부 필드 확인이 필요할 때만 사용하세요.
 
 **핵심 필드 (실사용 권장)**
 
 - `status`/`reasonCode`: 현재 상태와 이유 코드
-- `actions[]`: 원자 액션 목록
-  - `type: "command"`: `scope`(project|docs), `cwd`, `cmd`, `category`, `operationType`, `requiresUserCheck`
-  - `type: "instruction"`: `message`, `category`, `operationType`, `requiresUserCheck`
-- `actionOptions[]`: `label`(`A`, `B`, `C`...) + 실행 대상 `action` + 사용자 안내용 `summary`/`detail`/`approvalPrompt`
-- `approvalRequest`: 승인 요청/실행에 바로 사용하는 안내 데이터 (`labels`, `approveCommand`, `executeCommand`, `options[]`)
+- `actionOptions[]`: `label`(`A`, `B`, `C`...) + 최소 실행 계약 (`detail`, `actionType`, `category`, `operationType`, `requiresUserCheck`, 그리고 command/instruction payload)
+- `approvalRequest`: 승인 대기 여부와 사용자 표시 문구 (`required`, `userFacingLines`, `finalPrompt`)
 - `requiredDocs`: 현재 액션 전에 읽어야 할 CLI 내장 문서 목록 (`id`, `command`)
-- `checkPolicy`: 승인 검증 정책 (`token`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion` 등)
-- `agentOrchestration`: 메인(대화/승인) + 서브(명령 실행) 역할 분리 계약. 현재 SSOT는 `subAgentHandoff`와 `matchedFeature.currentSubstate*`이며, `delegateCommandExecution`/`longRunningCategories`/`currentActionShouldDelegate`는 compatibility field입니다.
+- `checkPolicy`: 최소 승인 상태 (`token`, `validLabels`, `checkRequiredLabels`, `checkRequiredCategories`, `approvalRequired`, `contextVersion`)
+- `agentOrchestration`: compact에서는 `subAgentHandoff`만 유지합니다. 위임 SSOT는 `matchedFeature.currentSubstate*` + `subAgentHandoff`입니다.
 - `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`: step 내부 실행 상태와 owner/phase 기반 오케스트레이션 판단용 필드
+- `actions[]`: 원자 액션 원본 목록은 상세 `context --json`에서 확인합니다.
 
 **고급/참고 필드 (자동화 고급 시나리오 또는 디버깅용)**
 
-- `selectionFallback`: 자동 감지 실패 시 사용된 폴백 (`none` | `open_features` | `all_features` | `done_features`)
-- `primaryActionLabel`/`primaryActionType`/`primaryActionCategory`/`primaryActionOperationType`: 첫 번째 원자 액션 요약 메타데이터
-- `workflowPolicy`: 현재 완료 조건 정책 (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
-- `taskCommitGatePolicy`: 태스크 커밋 게이트 정책 (`off` | `warn` | `strict`)
-- `prePrReviewPolicy`: pre-PR 리뷰 정책 (`enabled`, `skills`, `fallback`)
+- `selectionFallback`: 자동 감지 실패 시 사용된 폴백 (`none` | `open_features` | `all_features` | `done_features`) - compact에서는 비-hot-path 상태에서만 노출될 수 있음
+- `primaryActionLabel`/`workflowPolicy`/`taskCommitGatePolicy`/`prePrReviewPolicy`: 상세 `context --json`에서 확인하는 디버깅/정책 필드
 
 오류 응답(`status: "error"`)에는 `reasonCode`와 `suggestions`(라벨형 다음 동작: `A/B/C`)가 포함됩니다. (예: `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`)
 
@@ -421,12 +417,15 @@ npx lee-spec-kit flow --strict
 - `--request`는 auto 모드와 함께 사용해야 합니다.
   - 예외적으로 `workflow.auto.defaultPreset`이 설정되어 있으면 `--request`만으로도 auto 모드가 활성화됩니다.
 - `--resume <run-id>`는 `<feature-name>`, `--component`, `--all`, `--done`, `--auto-*`, `--request`와 함께 사용할 수 없습니다. (체크포인트에 저장된 설정을 사용)
-- 자동 진행은 지정한 category가 등장하면 `gate_reached`로 멈추고, 해당 단계의 승인 문구(`approvalRequest.userFacingLines`)를 그대로 출력합니다.
+- 자동 진행은 지정한 category가 등장하면 `gate_reached`로 멈추고, `autoRun.gate.userFacingLines`를 그대로 출력합니다. (이 값은 해당 단계의 `approvalRequest.userFacingLines`를 flow 결과에 복사한 것입니다.)
+- `context --json` / `--json-compact`의 `autoRun.available`는 "지금 바로 실행 가능한 auto-run"만 의미합니다. 설정상 auto-run 대상이어도 현재 단계가 instruction-only이면 `autoRun.available=false`, `autoRun.policyEligible=true`, `autoRun.executableNow=false`, `autoRun.manualBoundary`로 표시됩니다.
 - 현재 액션이 instruction-only라 command 자동 실행이 불가능하면 `AUTO_MANUAL_REQUIRED`로 멈출 수 있습니다. (CLI 오류가 아니라 자동화 경계 도달 상태)
 - 진행 정체(동일 context/action 반복)가 감지되면 `AUTO_NO_PROGRESS`로 중단됩니다.
-- JSON 모드에서는 `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.executions`, `autoRun.resume`로 상세 상태를 확인할 수 있습니다.
+- JSON 모드에서는 `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.manual`, `autoRun.resume`를 확인하세요.
+  - 상세 `flow --json`은 `autoRun.executions` 배열을 유지합니다.
+  - 압축 `flow --json-compact`는 `autoRun.executionCount`, `autoRun.lastExecution`만 유지합니다.
 - JSON `agentOrchestration`과 `matchedFeature.currentSubstate*`로 메인/서브 에이전트 역할 및 중단/보고 조건을 확인할 수 있습니다.
-  - 위임 판단은 `matchedFeature.currentSubstateOwner`와 `subAgentHandoff`를 우선 사용하세요. `longRunningCategories`와 `currentActionShouldDelegate`는 substate가 없는 레거시 경로용 compatibility 메타데이터입니다.
+  - 위임 판단은 `matchedFeature.currentSubstateOwner`와 `subAgentHandoff`를 우선 사용하세요. compact는 `subAgentHandoff`만 유지하고, 상세 `--json`/`flow --json`이 추가 오케스트레이션 메타데이터를 제공합니다.
 - `--start-auto`를 사용하면 JSON `autoRun.run`에 `runId`, `status`, `resumeCommand`가 포함됩니다.
 
 에이전트 재개 규칙(권장):
@@ -457,7 +456,7 @@ npx lee-spec-kit github pr F001 --create --merge --confirm OK --labels enhanceme
 핵심 동작:
 - Issue/PR helper는 필수 섹션과 관련 문서 경로를 검증합니다.
 - `--json` 출력에는 `body`(본문 문자열)와 `bodyFile`(파일 경로)가 함께 제공됩니다.
-- 라벨은 최소 1개 이상 필수입니다.
+- `--labels`를 생략하면 기본값 `enhancement`를 사용합니다. 값을 직접 줄 때는 비어 있으면 안 됩니다.
 - `--create`/`--merge`는 원격 작업이므로 `--confirm OK`가 필요합니다.
 - PR helper는 기본적으로 `tasks.md`의 `PR`/`PR Status`를 동기화합니다. (`--no-sync-tasks`로 비활성화)
 - PR helper의 아티팩트 섹션은 `--screenshots (auto|on|off)`, `--mermaid (auto|on|off)`로 제어할 수 있습니다.
@@ -642,16 +641,11 @@ npx lee-spec-kit update --force
 - 텍스트 출력의 `[확인 필요]` 표시
 - `context --json-compact`의 `actionOptions[].requiresUserCheck` (`--json`에서는 `actions[].requiresUserCheck`)
 - `checkPolicy.token` (`context --json-compact`/`--json`): 승인 토큰 형식 (`<LABEL>`)
-- `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
-- `checkPolicy.tokenPattern`: 승인 응답 검증용 정규식
 - `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
-- `checkPolicy.activeCategories`: 현재 액션에 실제 등장한 category 목록 (`actionOptions[].category` 기준)
-- `checkPolicy.knownCategories`: CLI가 인식하는 전체 category 목록
-- `checkPolicy.uncategorizedLabels`: category가 비어 있는 라벨 목록 (정상이라면 빈 배열)
-- `checkPolicy.categoryPolicyGuidance`: `approval.mode="category"` 사용 시 category 매칭 기준 안내
-- `checkPolicy.requireExplanationBeforeApproval`: 승인 요청 전에 라벨별 설명을 포함해야 함
-- `checkPolicy.requiredExplanationFields`: 라벨 설명에 사용할 필드 목록 (예: `actionOptions[].detail`)
+- `checkPolicy.checkRequiredLabels` / `checkPolicy.checkRequiredCategories`: 현재 승인 필수 라벨/카테고리
+- `checkPolicy.approvalRequired`: 현재 승인 대기 여부
 - `checkPolicy.contextVersion`: stale context 검증용 스냅샷 해시
+- `checkPolicy.acceptedTokens`, `tokenPattern`, `activeCategories`, `knownCategories`, `uncategorizedLabels`, `categoryPolicyGuidance`, `requireExplanationBeforeApproval`, `requiredExplanationFields`는 상세 `context --json`에서 확인합니다.
 
 > 실제 명령 실행을 강제/차단하는 기능은 아닙니다. (에이전트가 참고하도록 신호를 제공)
 > 기존 설정에 `approval`이 없으면 `builtin`으로 동작합니다. (마이그레이션 불필요)
@@ -760,7 +754,7 @@ Pre-PR 실행 게이트 리스크와 완화:
 }
 ```
 
-> 사용 가능한 `category` 값은 `context --json`/`--json-compact`의 `checkPolicy.activeCategories`(현재), `checkPolicy.knownCategories`(전체), `actionOptions[].category`(라벨별)에서 확인하세요.
+> 사용 가능한 `category` 값은 `context --json`의 `checkPolicy.activeCategories`/`checkPolicy.knownCategories`, 또는 `actionOptions[].category`에서 확인하세요. compact는 hot path 최소 계약만 유지합니다.
 
 ### pr (PR 결과물 정책)