lee-spec-kit 0.6.43 → 0.7.0

package/package.json

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

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

@@ -36,13 +36,13 @@ Prohibited:
 - 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).
-- 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 approval-waiting state, prefer `approvalRequest.userFacingLines` from `context --json-compact`. If full `--json` is used, fall back to `actionOptions[*].approvalPrompt` plus `approvalRequest.finalPrompt`. Do not add your own rewritten label summary before or between those lines.
+- Prefer `matchedFeature.currentSubstateOwner` plus `agentOrchestration.subAgentHandoff` as the delegation SSOT.
 - 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 approval is still pending after answering an unrelated question, answer first, then re-open approval with the exact CLI-provided approval lines (`approvalRequest.userFacingLines`, or `actionOptions[*].approvalPrompt` + `approvalRequest.finalPrompt` in full `--json`).
 - 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.
+- If `matchedFeature.currentSubstateOwner="subagent"` and `agentOrchestration.subAgentHandoff.required=true` with `mode="command"`, delegation is mandatory: call `spawn_agent` first. Do not execute that 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"`.
 - Prefer `agentOrchestration.subAgentHandoff` as the handoff SSOT. Pass only its minimal fields (`featureRef`, `category`, `cwd`, `cmd`) to the sub-agent.
 - For delegated runs, execute one-time verification from `subAgentHandoff.verify` (`pwd`, `git rev-parse --show-toplevel`) and cache by `verify.cacheKey`. If mismatched, stop and report; collect detailed logs only on mismatch.

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

@@ -28,19 +28,22 @@ Execute exactly one option from `👉 Next Options (Atomic)` as printed by the C
 - 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.
+- Prefer `matchedFeature.currentSubstateOwner` plus `agentOrchestration.subAgentHandoff` as the delegation SSOT.
+- When `matchedFeature.currentSubstateOwner="subagent"` and `agentOrchestration.subAgentHandoff.required=true` with `mode="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`).
+- If an action option exposes `handoffOnly=true` and `advancesWorkflow=false`, do not treat `--execute` success as workflow progress. Finish the delegated work and update the required evidence/state before running `context` again.
 - Run `subAgentHandoff.verify.commands` only once per session using `verify.cacheKey` (`pwd`, `git rev-parse --show-toplevel`). Stop/report on mismatch, and gather detailed logs only when mismatch happens.
 - 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). Before fallback execution, report a one-line fallback reason to the user.
-- If `context --json-compact` exposes `autoRun.available=true`, you may use `autoRun.command` to continue automatically until approval-required categories are reached.
+- Use `autoRun.command` only when `context --json-compact` exposes `autoRun.available=true`.
+- If `autoRun.policyEligible=true` but `autoRun.executableNow=false`, handle `autoRun.manualBoundary` first instead of starting an auto loop.
 - For long-running auto execution, start with `flow <feature> --auto-... --start-auto --json-compact` and prefer `autoRun.run.resumeCommand` (`flow --resume <RUN_ID>`) after interruption/compression (`--json` only when full-detail debugging fields are required).
 - 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 `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.
+- If `flow/context --execute --json` returns `approved_handoff_prepared`, stop re-approving the same label. Complete the delegated work first, then refresh context.
 
 ### Step 3: Update tasks.md (only what you did)
 

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

@@ -4,6 +4,8 @@
 
 - **Status**: -
   - Values: Draft | Ready
+- **Title**: {feature-name}
+- **Labels**: enhancement
 - **Base**: main
 - **Created**: {YYYY-MM-DD}
 

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

@@ -25,14 +25,17 @@
 - **PR Status**: -
   - Values: Review | Approved
 - **Pre-PR Review**: -
-  - Values: Pending | Done
-  - Mark `Done` after pre-PR review is completed
+  - Values: Pending | Running | Done
+  - Mark `Running` when the pre-PR review handoff starts, then `Done` after the review is recorded
 - **Pre-PR Evidence**: -
   - Example: `docs/features/F001-foo/decisions.md` (must exist)
 - **Pre-PR Decision**: -
   - Format: `decision: approve|changes_requested|blocked ...` (or `결정: ...`)
   - PR creation requires final decision `approve`
   - Follow `agents/skills/create-pr.md` (`Pre-PR Baseline Checklist`) as the default baseline
+- **PR Review**: -
+  - Values: Pending | Running | Done
+  - Mark `Running` when PR review handoff starts; use `Done` only if your team explicitly tracks review completion here
 - **PR Review Evidence**: -
   - Example: `summary: ...` (or `요약: ...`), or `docs/features/F001-foo/decisions.md` with `PR Review Log`
 - **PR Review Decision**: -

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

@@ -36,13 +36,13 @@
 - 기준 데이터는 최신 `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[*].approvalPrompt`를 원문 그대로 보여주고, 마지막에는 `approvalRequest.finalPrompt`를 원문 그대로 붙입니다. 가능하면 `approvalRequest.userFacingLines`를 우선 사용합니다. 이 사이에 에이전트가 임의로 다시 쓴 라벨 요약을 끼워 넣지 않습니다.
-- 위임 판단 SSOT는 `matchedFeature.currentSubstateOwner`와 `agentOrchestration.subAgentHandoff`를 우선 사용하세요. `currentActionShouldDelegate`는 구형 소비자를 위한 compatibility mirror입니다.
+- 승인 대기 상태에서는 `context --json-compact`의 `approvalRequest.userFacingLines`를 우선 그대로 보여주세요. 전체 `--json`을 쓸 때만 `actionOptions[*].approvalPrompt`와 `approvalRequest.finalPrompt` 조합으로 폴백합니다. 이 사이에 에이전트가 임의로 다시 쓴 라벨 요약을 끼워 넣지 않습니다.
+- 위임 판단 SSOT는 `matchedFeature.currentSubstateOwner`와 `agentOrchestration.subAgentHandoff`를 우선 사용하세요.
 - 비승인 상태의 진행 보고/분석/일반 답변에서는 라벨 블록이나 `approvalRequest.finalPrompt`를 덧붙이지 않습니다. 현재 옵션을 사용자가 직접 물었을 때만 예외입니다.
-- 관련 없는 질문에 먼저 답한 뒤에도 승인이 여전히 필요하면, 답변 후 `actionOptions[*].approvalPrompt`와 `approvalRequest.finalPrompt`를 함께 다시 제시합니다.
+- 관련 없는 질문에 먼저 답한 뒤에도 승인이 여전히 필요하면, 답변 후 CLI가 준 승인 문구(`approvalRequest.userFacingLines`, 또는 전체 `--json`의 `actionOptions[*].approvalPrompt` + `approvalRequest.finalPrompt`)를 다시 제시합니다.
 - 사용자 입력에 유효 라벨이 없으면 실행하지 말고 라벨 선택을 다시 요청합니다.
 - 승인된 command 옵션 실행은 `flow --approve <LABEL> --execute` 1회 호출을 기본으로 하며, `context --approve`와 `context --execute --ticket`를 턴/세션 사이로 분리하지 않습니다.
-- `agentOrchestration.currentActionShouldDelegate=true`이고 선택한 옵션이 `actionType="command"`면 위임이 필수입니다. 먼저 `spawn_agent`를 호출하고, 해당 명령을 메인 에이전트에서 직접 실행하지 않습니다.
+- `matchedFeature.currentSubstateOwner="subagent"`이고 `agentOrchestration.subAgentHandoff.required=true`이며 `mode="command"`면 위임이 필수입니다. 먼저 `spawn_agent`를 호출하고, 해당 명령을 메인 에이전트에서 직접 실행하지 않습니다.
 - `autoRun.available`만으로 auto 루프 위임을 결정하지 않습니다. `agentOrchestration.subAgentHandoff.required=true`이고 `agentOrchestration.subAgentHandoff.mode="auto_run"`일 때만 auto 루프를 서브 에이전트에 위임합니다.
 - 위임 시에는 `agentOrchestration.subAgentHandoff`를 handoff SSOT로 사용하고, 최소 필드(`featureRef`, `category`, `cwd`, `cmd`)만 전달합니다.
 - 위임 실행 전 `subAgentHandoff.verify`의 검증 명령(`pwd`, `git rev-parse --show-toplevel`)을 세션당 1회만 실행하고(`verify.cacheKey` 기준), 불일치 시 즉시 중단/보고합니다. 상세 로그 수집은 불일치 시에만 수행합니다.

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

@@ -28,19 +28,22 @@ CLI가 가리키는 **Active Task** 또는 **`👉 Next Options (Atomic)`의 단
 - 메인 에이전트는 승인 경계, 상태 전이, 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`를 호출하고, 해당 명령을 메인 에이전트에서 직접 실행하지 않습니다.
+- 위임 판단은 `matchedFeature.currentSubstateOwner`와 `agentOrchestration.subAgentHandoff`를 SSOT로 우선 사용하세요.
+- `matchedFeature.currentSubstateOwner="subagent"`이고 `agentOrchestration.subAgentHandoff.required=true`이며 `mode="command"`면 위임이 필수입니다. 먼저 `spawn_agent`를 호출하고, 해당 명령을 메인 에이전트에서 직접 실행하지 않습니다.
 - `autoRun.available`만으로 auto 루프 위임을 결정하지 않습니다. `agentOrchestration.subAgentHandoff.required=true`이고 `agentOrchestration.subAgentHandoff.mode="auto_run"`일 때만 auto 루프를 서브 에이전트에 위임합니다.
 - `agentOrchestration.subAgentHandoff`를 최소 handoff 계약(`featureRef`, `category`, `cwd`, `cmd`)으로 사용합니다.
+- action option에 `handoffOnly=true`와 `advancesWorkflow=false`가 있으면 `--execute` 성공을 workflow 전진으로 간주하지 않습니다. delegated work와 필요한 evidence/state 갱신을 끝낸 뒤에 다시 `context`를 실행합니다.
 - `subAgentHandoff.verify.commands`(`pwd`, `git rev-parse --show-toplevel`)은 `verify.cacheKey` 기준 세션당 1회만 실행합니다. 불일치 시 즉시 중단/보고하고, 상세 로그는 불일치 시에만 수집합니다.
 - 메인 에이전트 fallback은 서브 에이전트 실행이 불가능한 경우(예: 도구 미지원, spawn 실패, 명령 실행 전 서브 에이전트 실패)에만 허용합니다. fallback 실행 전에는 사유를 사용자에게 한 줄로 먼저 알립니다.
-- `context --json-compact`에 `autoRun.available=true`가 있으면 `autoRun.command`를 사용해 승인 필요 카테고리 전까지 자동 진행할 수 있습니다.
+- `context --json-compact`에서 `autoRun.available=true`일 때만 `autoRun.command`를 사용해 자동 루프를 시작합니다.
+- `autoRun.policyEligible=true`이지만 `autoRun.executableNow=false`이면 auto 루프를 시작하지 말고 `autoRun.manualBoundary`를 먼저 처리합니다.
 - 장시간 자동 실행이 필요하면 `flow <feature> --auto-... --start-auto --json-compact`으로 run id를 생성하고, 중단/압축 후에는 `autoRun.run.resumeCommand`(`flow --resume <RUN_ID>`)를 우선 사용해 재개합니다. (상세 디버깅 필드가 필요할 때만 `--json`)
 - 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)"** 을 따릅니다. 라벨 문구는 승인 대기 상태에서만 보여주고, CLI가 준 승인 문구를 임의로 바꾸지 않습니다.
 - 승인된 command 옵션 실행은 `npx lee-spec-kit flow <slug|F001|F001-slug> --approve <LABEL> --execute`를 기본으로 사용하고, `context --approve`와 `context --execute --ticket` 분리 실행은 지양합니다.
+- `flow/context --execute --json` 결과가 `approved_handoff_prepared`이면 같은 라벨을 다시 승인 루프로 열지 말고, 먼저 delegated work를 완료한 뒤 context를 새로 확인합니다.
 
 ### 3단계: 기록 및 반복 (Record & Loop)
 

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

@@ -4,6 +4,8 @@
 
 - **상태**: -
   - 값: Draft | Ready
+- **제목**: {기능명}
+- **라벨**: enhancement
 - **Base**: main
 - **작성일**: {YYYY-MM-DD}
 

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

@@ -25,14 +25,17 @@
 - **PR 상태**: -
   - 값: Review | Approved
 - **PR 전 리뷰**: -
-  - 값: Pending | Done
-  - 사전 코드리뷰 완료 후 `Done`으로 변경
+  - 값: Pending | Running | Done
+  - pre-PR 리뷰 handoff를 시작하면 `Running`, 리뷰 결과 기록까지 끝나면 `Done`으로 변경
 - **PR 전 리뷰 Evidence**: -
   - 예: `docs/features/F001-foo/decisions.md` (실제 존재 경로)
 - **PR 전 리뷰 Decision**: -
   - 형식: `결정: approve|changes_requested|blocked ...` (또는 `decision: ...`)
   - PR 생성 전 최종 통과 기준은 `approve`
   - 기본 베이스라인으로 `agents/skills/create-pr.md`(`Pre-PR 기본 체크리스트`) 기준을 따르세요
+- **PR 리뷰**: -
+  - 값: Pending | Running | Done
+  - PR 리뷰 handoff를 시작하면 `Running`, 팀에서 별도 완료 상태를 추적할 때만 `Done`으로 변경
 - **PR 리뷰 Evidence**: -
   - 예: `요약: ...`(또는 `summary: ...`), 또는 `PR Review Log`가 있는 `docs/features/F001-foo/decisions.md`
 - **PR 리뷰 Decision**: -