lee-spec-kit 0.9.6 → 0.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {

package/templates/en/common/README.md

@@ -121,6 +121,8 @@ Interactive init lets you keep the recommended defaults or customize task
 implementation delegation, Plan/Task/Feature reviews, and Local integration.
 Non-interactive setup exposes the same choices through `--task-agent`,
 `--reviews`, `--max-review-rounds`, and `--completion-strategy`.
+Existing projects can change the same settings with `lee-spec-kit config
+--interactive` or the corresponding non-interactive flags.
 
 - Used by `lee-spec-kit feature`, `config`, `update`, `detect`, and workflow validators to resolve docs location / project type / language.
 - `docsRepo`, `pushDocs`, `docsRemote` are metadata for the CLI-managed **Docs Push policy** (the CLI does not auto-push).
@@ -135,14 +137,15 @@ Non-interactive setup exposes the same choices through `--task-agent`,
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
 - `workflow.agentExecution.task` (object): task implementation delegation settings
-  - `enabled`: delegates each `task_execute` action to a subagent; new and updated projects default to `true`
+  - `enabled`: delegates each `task_execute` action to a subagent; new projects default to `true`, while projects created before this setting existed keep it disabled until explicitly enabled
   - `type`: currently only `"subagent"` is supported
   - `model`: `"inherit"` or a model name supported by the runtime
   - `reasoningEffort`: `low | medium | high | xhigh | max | ultra`
   - `onUnavailable`: `inherit | error` when the requested model is unavailable
   - `workflow-stage` returns a stable task ID, working/docs directories, and a machine-readable `workerContract`. The worker executes directly without rerunning `workflow-stage` or delegating again.
   - The implementation subagent can edit project code and run task-scoped checks. The main agent retains docs, task state, commits, approvals, and remote actions; official hooks reject commits while `task_execute` is active.
-- `workflow.agentReview.maxRounds` (positive integer): maximum automatic finding-remediation passes shared by Plan/task/Feature reviews before remaining `changes_requested` findings are preserved as residual risks and the review gate auto-completes; the initial review is not counted and the default is `1`
+- `workflow.agentAutomationConfigured` (boolean): records that `init` or `config` explicitly selected the agent automation policy, preventing legacy-default repair from overriding that choice
+- `workflow.agentReview.maxRounds` (positive integer): maximum number of fresh reviews shared by Plan/task/Feature gates. Findings from the final allowed `changes_requested` review are applied once, then remaining findings and the resulting target change are preserved as residual risks and the gate auto-completes without another review. The default is `1`, which means there is no round 2
 - `workflow.agentReview.plan` / `workflow.agentReview.task` / `workflow.agentReview.feature` (object): Plan/task/Feature independent review settings
   - `enabled`: enables that review gate; new projects default Plan and Feature to `true`, and task to `false`
   - `evidenceMode`: `path_required | any`
@@ -183,6 +186,7 @@ Non-interactive setup exposes the same choices through `--task-agent`,
   "docsRepo": "embedded",
   "workflow": {
     "mode": "local",
+    "agentAutomationConfigured": true,
     "baseBranch": "main",
     "completionStrategy": "local-ff",
     "deleteFeatureBranchAfterMerge": true,
@@ -237,12 +241,16 @@ Non-interactive setup exposes the same choices through `--task-agent`,
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
+    "requireCheckCategories": [
+      "spec_approve",
+      "implementation_approve",
+      "local_merge"
+    ]
   }
 }
 ```
 
-New and updated projects delegate task implementation and enable Plan review by default; set `workflow.agentExecution.task.enabled` or `workflow.agentReview.plan.enabled` to `false` to opt out. New local projects use `local-ff` with Feature agent review enabled. Set `workflow.agentReview.task.enabled` to `true` when every task also needs independent review. Finding remediation defaults to `1`: findings from the first review are applied once and reviewed again. If the next review still returns `changes_requested`, those findings remain as residual risks and the review gate completes automatically without user approval. `blocked` never auto-completes. Choose `local-squash` to create one base-branch commit while preserving the source Feature tip under an internal `refs/lee-spec-kit/integrations/*` ref for task-checkpoint evidence. During `update`, an existing local project with no explicit `completionStrategy` receives `none` so an upgrade does not unexpectedly merge its current branch. Set it to `local-ff` or `local-squash` deliberately when ready.
+New projects delegate task implementation and enable Plan review by default. Existing projects that predate those settings keep task delegation and Plan/Task review disabled, so updating does not silently change the execution policy. An older project whose generated defaults were already backfilled by v0.9.4-v0.9.6 is also restored to the safe disabled state when its creation date and untouched generated settings identify that case; customized agent settings are preserved. Use `lee-spec-kit config --interactive`, or `config --task-agent on|off --reviews plan,task,feature|none --max-review-rounds N`, to opt in or change it. New local projects use `local-ff` with Feature agent review enabled. Legacy Feature review behavior is preserved from the former Pre-PR setting and workflow mode. The fresh-review limit defaults to `1`: findings from round 1 are applied once, then remaining findings and the resulting target change are preserved as residual risks and the review gate completes automatically without round 2 or user approval. `blocked` never auto-completes. Choose `local-squash` to create one base-branch commit while preserving the source Feature tip under an internal `refs/lee-spec-kit/integrations/*` ref for task-checkpoint evidence. During `update`, an existing local project with no explicit `completionStrategy` receives `none` so an upgrade does not unexpectedly merge its current branch. Set it to `local-ff` or `local-squash` deliberately when ready.
 
 ```json
 {
@@ -256,7 +264,11 @@ New and updated projects delegate task implementation and enable Plan review by
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
+    "requireCheckCategories": [
+      "spec_approve",
+      "implementation_approve",
+      "local_merge"
+    ]
   }
 }
 ```

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

@@ -59,7 +59,10 @@ This document defines workflow policy, not a custom runtime loop.
 - When `nextAction.category` is `task_review` with `executor: subagent`, delegate a fresh read-only review for the returned task ID and SHA/tree range, then record the returned `reviewRound`.
 - When `nextAction.category` is `pre_pr_review` with `executor: subagent`, run a fresh read-only Feature review using the returned model, reasoning effort, `reviewRound`, and SHA/tree range. Do not select or require a named review skill.
 - Review subagents return findings without modifying code. The main agent remediates findings and records reviewer metadata, reviewed scope, evidence, decision, and exact hash/SHA/tree target metadata.
-- `workflow.agentReview.maxRounds` counts automatic finding-remediation passes, not the initial review. After those passes are exhausted, preserve the latest `changes_requested` findings as residual risks and automatically complete the Plan/task/Feature review gate without asking for a user review-approval token. A `blocked` decision never auto-completes.
+- After delegating to a subagent, wait until it returns a terminal outcome: completed, explicit failure, cancellation, or an approval/user-input request that requires action.
+- While the subagent remains running, use repeated bounded waits, preferably longer waits. A bounded wait that returns no update, a lack of status messages, or a lack of file changes means only that the subagent is still pending; none is evidence of failure or stalled work. Read-only review subagents are expected not to modify files.
+- Do not interrupt, replace, or abandon a running subagent solely because it has been quiet or has not changed files. Stop it only after an explicit user request, a terminal failure/cancellation, or an unrecoverable runtime status.
+- `workflow.agentReview.maxRounds` is the maximum number of fresh reviews for each Plan/task/Feature gate. A `changes_requested` decision on the final allowed review is remediated once, but the changed target is not reviewed again; preserve remaining findings and the post-review target change as residual risks and automatically complete the gate without asking for a user review-approval token. For example, `maxRounds=1` means review round 1, remediate once, then continue with no round 2. A `blocked` decision never auto-completes.
 - Treat spec/plan/tasks approval, issue creation, and branch creation as hard gates before implementation.
 - In standalone mode, do not hand-write `git worktree add`; run the exact `nextAction.command` from `workflow-stage` so the managed workspace path, stale directory cleanup, and `.env`/`.env.*` copy step stay consistent.
 - In local mode, do not stop after implementation approval. Follow the exact `local verify`, `local merge`, and `local cleanup` commands returned by `workflow-stage` until verified integration and cleanup produce `done`. A `feature_remediation` stage explicitly permits fixes in the Feature worktree.

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

@@ -24,8 +24,8 @@ This guide defines how to start or continue a feature in the Codex-native lee-sp
   - `tasks.md` drives execution order
   - `issue.md` / `pr.md` are part of the stage gate once the feature reaches GitHub workflow stages
 - Do not begin implementation just because `tasks.md` exists. Implementation starts only when `workflow-stage --json` allows it.
-- When Plan review is enabled, move `plan.md` to Review, delegate the returned fresh read-only `plan_review`, and record its `reviewRound`, evidence, decision, reviewer metadata, `specHash`, and `planHash`. Only an approved review of the current hashes can reach Plan approval. The reviewer challenges NONE/UPDATE/ADD decisions, requirement coverage, independent oracles, stable observation boundaries, realistic failure/rollback cases, exclusions, and focused/full verification scope without editing docs.
-- `workflow.agentReview.maxRounds` counts Plan finding-remediation passes, not the initial review. After the limit, preserve remaining `changes_requested` findings as residual risks, promote the Plan automatically, and do not request a user review-approval token. Never auto-complete `blocked`.
+- When Plan review is enabled, move `plan.md` to Review, delegate the returned fresh read-only `plan_review`, and record its `reviewRound`, evidence, decision, reviewer metadata, `specHash`, and `planHash`. An approved review must match the current hashes; exhausted `changes_requested` follows the automatic residual-risk path below. The reviewer challenges NONE/UPDATE/ADD decisions, requirement coverage, independent oracles, stable observation boundaries, realistic failure/rollback cases, exclusions, and focused/full verification scope without editing docs.
+- `workflow.agentReview.maxRounds` is the maximum number of fresh Plan reviews. On `changes_requested` at the final allowed round, apply the findings once, preserve remaining findings and the resulting hash changes as residual risks, promote the Plan automatically, and do not request another review or a user review-approval token. With `maxRounds=1`, there is no round 2. Never auto-complete `blocked`.
 - When scope or behavior changes, update the active feature docs in the same turn before continuing.
 - Ask for approval at documented review checkpoints and before remote or destructive actions.
 - Use `npx lee-spec-kit commit-audit --json` before `git commit` when docs-path validation matters.

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

@@ -33,8 +33,8 @@ When `workflow-stage --json` returns `nextAction.executor: subagent`, delegate t
 10. `Pre-PR Decision` must use `decision: approve|changes_requested|blocked ...` (or `결정: ...`).
 11. Record `Pre-PR Review Round` from the returned `reviewRound`.
 12. Confirm `Pre-PR Reviewed Head` and `Pre-PR Reviewed Tree` match the `targetSha` and `targetTree` returned by `workflow-stage`.
-13. `workflow.agentReview.maxRounds` counts Feature finding-remediation passes, not the initial review. After the limit, preserve remaining `changes_requested` findings as residual risks and auto-complete the Feature review gate without a user review-approval token. Never auto-complete `blocked`.
-14. Ensure the final decision is `approve` before moving to PR creation.
+13. `workflow.agentReview.maxRounds` is the maximum number of fresh Feature reviews. On `changes_requested` at the final allowed round, apply the findings once, preserve remaining findings and the resulting target change as residual risks, and auto-complete the Feature review gate without another review or a user review-approval token. With `maxRounds=1`, there is no round 2. Never auto-complete `blocked`.
+14. Move to PR creation after an `approve` decision or after the exhausted `changes_requested` path above auto-completes the gate.
 
 The review artifact must record the actual `executor`, `model`, `reasoningEffort`, reviewed commit/diff scope, target SHA/tree, findings, and final decision. The review subagent must not modify code; the main agent owns finding remediation and documentation updates.
 

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

@@ -15,6 +15,8 @@ Use the active feature folder as the execution SSOT.
 - Work one task at a time. Do not batch-complete multiple tasks in one pass.
 - When `nextAction.executor === "subagent"`, delegate that task's implementation and task-scoped verification to a fresh subagent in `nextAction.workingDirectory` using the returned `model`, `reasoningEffort`, `onUnavailable`, and exact `workerContract`. If a requested model is unavailable, `inherit` means retry with the current model inherited and `error` means stop and report the failure.
 - The implementation worker executes the assigned task directly. It must not run `workflow-stage`, delegate again, edit lee-spec-kit docs, change task state, commit, request approval, or perform remote/destructive actions. It may edit project code and run task-scoped checks only.
+- After delegation, the main agent waits for the worker's terminal outcome. While it remains running, use repeated bounded waits, preferably longer waits; a wait with no update, no status message, or no file change is not evidence of failure or stalled work.
+- Do not interrupt, replace, or abandon the running worker solely because it has been quiet or has not changed files. Stop only after an explicit user request, a terminal failure/cancellation, or an unrecoverable runtime status.
 - The implementation worker follows the approved `plan.md` Verification Contract: `NONE` adds no durable test, `UPDATE` minimally changes the owning existing test, and `ADD` adds only contract-linked tests. If the approved decision is insufficient, report the gap to the main agent instead of expanding test scope.
 - Legacy task lines without an explicit ID receive a stable synthetic `taskId` from `workflow-stage`; use that returned ID without rewriting the legacy task solely to add an ID.
 
@@ -23,8 +25,8 @@ Use the active feature folder as the execution SSOT.
 - Keep `tasks.md` aligned with reality:
   - do not mark `[DONE]` without real completion and verification
   - when `workflow.agentReview.task.enabled=true`, move completed implementation to `[REVIEW]` instead of `[DONE]`, create the checkpoint commit, and run the independent review
-  - record the returned `reviewRound`, and move `[REVIEW]` to `[DONE]` only after the task reviewer approves the current SHA/tree
-  - `workflow.agentReview.maxRounds` counts task finding-remediation passes, not the initial review; after the limit, preserve remaining `changes_requested` findings as residual risks, mark the task DONE, and continue without a user review-approval token; never auto-complete `blocked`
+  - record the returned `reviewRound`, and move `[REVIEW]` to `[DONE]` after the task reviewer approves the current SHA/tree or the exhausted `changes_requested` path below auto-completes the gate
+  - `workflow.agentReview.maxRounds` is the maximum number of fresh task reviews; on `changes_requested` at the final allowed round, apply the findings once, preserve remaining findings and the resulting target change as residual risks, mark the task DONE, and continue without another review or a user review-approval token; with `maxRounds=1`, there is no round 2; never auto-complete `blocked`
   - update `Acceptance` and `Checklist` in the same edit when closing a task
   - if a completed task needs follow-up, add a new task instead of rewriting history
 - If you need to add a new task, append a complete task block in `tasks.md` with a concrete title, `Acceptance`, `Checklist`, and `NON-PRD` or existing `PRD-*` tag.

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

@@ -11,7 +11,7 @@
   - Ask for approval before changing task state only when the task crosses a documented review checkpoint or before remote/destructive actions.
   - Do not invent a standalone `OK` approval step when the workflow does not require one.
   - Do not mark `[DONE]` while any item in that task's `Checklist` remains unchecked.
-  - `workflow.agentReview.maxRounds` counts automatic finding-remediation passes, not the initial review. After those passes are exhausted, preserve remaining `changes_requested` findings as residual risks and auto-complete the review gate without user approval. Never auto-complete `blocked`.
+  - `workflow.agentReview.maxRounds` is the maximum number of fresh reviews. On `changes_requested` at the final allowed round, apply the findings once, preserve remaining findings and the resulting target change as residual risks, and auto-complete the review gate without another review or user approval. With `maxRounds=1`, there is no round 2. Never auto-complete `blocked`.
 - **PRD mapping (recommended)**: add an existing PRD requirement ID tag like `[PRD-FR-001]` or `[PRD-SCOPE-V1-DESKTOP-EDITOR]` to each task line, or tag non-PRD tasks as `[NON-PRD]`.
   - Do not invent PRD IDs in `tasks.md`. Only reference IDs that already exist in `docs/prd` or the upstream requirements doc.
   - If this is a legacy feature without PRD IDs yet, backfill IDs in the source requirements doc first, then align `spec.md` `PRD Refs` and task tags together.

package/templates/ko/common/README.md

@@ -120,6 +120,8 @@ npx lee-spec-kit docs get agents --json
 대화형 init에서는 권장 설정을 그대로 쓰거나 Task 구현 위임, Plan/Task/Feature 검수,
 Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에서는 `--task-agent`,
 `--reviews`, `--max-review-rounds`, `--completion-strategy`로 같은 값을 지정합니다.
+기존 프로젝트도 `lee-spec-kit config --interactive` 또는 같은 config 플래그로
+이 설정을 변경할 수 있습니다.
 
 - `lee-spec-kit feature`, `config`, `update`, `detect`, workflow validator에서 문서 위치/프로젝트 타입/언어를 해석하는 용도로 사용됩니다.
 - `docsRepo`, `pushDocs`, `docsRemote`는 CLI 관리 **Docs Push 정책**을 위한 메타데이터입니다. (자동 push는 하지 않습니다)
@@ -134,14 +136,15 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
 - `pushDocs` (boolean, optional): `docsRepo: "standalone"`일 때만 생성 (원격 push 여부)
 - `docsRemote` (string, optional): `pushDocs: true`일 때만 생성 (원격 레포 URL)
 - `workflow.agentExecution.task` (object): 태스크 구현 위임 설정
-  - `enabled`: 각 `task_execute`를 서브에이전트에게 위임할지 여부. 새 프로젝트와 업데이트된 프로젝트의 기본값은 `true`
+  - `enabled`: 각 `task_execute`를 서브에이전트에게 위임할지 여부. 새 프로젝트의 기본값은 `true`이며, 이 설정이 생기기 전 프로젝트는 명시적으로 켜기 전까지 꺼진 상태를 유지
   - `type`: 현재 `"subagent"`만 지원
   - `model`: `"inherit"` 또는 런타임이 지원하는 모델명
   - `reasoningEffort`: `low | medium | high | xhigh | max | ultra`
   - `onUnavailable`: 지정 모델을 사용할 수 없을 때 `inherit | error`
   - `workflow-stage`는 안정적인 태스크 ID, 작업/docs 경로, machine-readable `workerContract`를 반환합니다. worker는 `workflow-stage` 재호출이나 재위임 없이 직접 실행합니다.
   - 구현 서브에이전트는 프로젝트 코드와 태스크 범위 검사를 담당하고, 메인 에이전트는 문서, 태스크 상태, 커밋, 승인, 원격 작업을 유지합니다. 공식 hook은 `task_execute` 중 커밋을 거부합니다.
-- `workflow.agentReview.maxRounds` (양의 정수): Plan/태스크/Feature 리뷰에 공통 적용되는 리뷰 지적 자동 반영 최대 횟수. 한도 뒤 남은 `changes_requested` finding은 잔여 위험으로 보존하고 리뷰 게이트를 자동 완료합니다. 최초 리뷰는 세지 않으며 기본값은 `1`
+- `workflow.agentAutomationConfigured` (boolean): `init` 또는 `config`에서 에이전트 자동화 정책을 명시적으로 선택했음을 기록해, 구버전 기본값 복구가 해당 선택을 덮어쓰지 않게 함
+- `workflow.agentReview.maxRounds` (양의 정수): Plan/태스크/Feature 게이트에 공통 적용되는 fresh 리뷰 최대 실행 횟수. 마지막 허용 `changes_requested` 리뷰의 지적은 한 번 반영하고, 남은 finding과 그 결과의 target 변경을 잔여 위험으로 보존한 뒤 추가 리뷰 없이 게이트를 자동 완료합니다. 기본값은 `1`이며 Round 2는 실행하지 않습니다
 - `workflow.agentReview.plan` / `workflow.agentReview.task` / `workflow.agentReview.feature` (object): Plan/태스크/Feature 독립 리뷰 설정
   - `enabled`: 해당 리뷰 게이트 활성화 여부. 새 프로젝트는 Plan과 Feature `true`, task `false`
   - `evidenceMode`: `path_required | any`
@@ -182,6 +185,7 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
   "docsRepo": "embedded",
   "workflow": {
     "mode": "local",
+    "agentAutomationConfigured": true,
     "baseBranch": "main",
     "completionStrategy": "local-ff",
     "deleteFeatureBranchAfterMerge": true,
@@ -236,12 +240,16 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
+    "requireCheckCategories": [
+      "spec_approve",
+      "implementation_approve",
+      "local_merge"
+    ]
   }
 }
 ```
 
-새 프로젝트와 업데이트된 프로젝트는 기본적으로 태스크 구현을 위임하고 Plan 검수를 활성화합니다. 직접 구현하거나 Plan 검수를 끄려면 각각 `workflow.agentExecution.task.enabled` 또는 `workflow.agentReview.plan.enabled`를 `false`로 설정하세요. 새 local 프로젝트는 `local-ff`와 Feature agent review를 사용합니다. 태스크마다 리뷰하려면 `workflow.agentReview.task.enabled`를 `true`로 켜세요. 리뷰 지적 자동 반영 기본값은 `1`입니다. 즉 첫 리뷰 지적은 한 번 반영하고 다시 리뷰합니다. 다음 리뷰도 `changes_requested`이면 finding을 잔여 위험으로 보존하고 사용자 승인 없이 리뷰 게이트를 자동 완료합니다. `blocked`는 자동 완료하지 않습니다. base branch에 하나의 commit만 남기려면 `local-squash`를 선택하세요. 이때 task checkpoint 증거를 위해 원본 Feature tip을 내부 `refs/lee-spec-kit/integrations/*` ref로 보존합니다. 기존 local 프로젝트에 명시적 `completionStrategy`가 없으면 `update`가 `none`을 넣어 업그레이드 도중 현재 브랜치를 갑자기 병합하지 않습니다. 준비가 끝난 뒤 `local-ff` 또는 `local-squash`로 명시적으로 전환하세요.
+새 프로젝트는 기본적으로 태스크 구현을 위임하고 Plan 검수를 활성화합니다. 해당 설정이 생기기 전의 기존 프로젝트는 Task 위임과 Plan/Task 검수를 꺼진 상태로 유지하므로, 업데이트만으로 실행 정책이 바뀌지 않습니다. v0.9.4-v0.9.6 업데이트가 생성 기본값을 이미 기록한 기존 프로젝트도 생성일과 수정되지 않은 기본 설정 형태로 식별되면 안전한 비활성 상태로 복구하며, 커스텀 에이전트 설정은 보존합니다. `lee-spec-kit config --interactive` 또는 `config --task-agent on|off --reviews plan,task,feature|none --max-review-rounds N`으로 명시적으로 켜거나 변경할 수 있습니다. 새 local 프로젝트는 `local-ff`와 Feature agent review를 사용합니다. 기존 Feature 리뷰 동작은 이전 Pre-PR 설정과 workflow mode의 의미를 보존합니다. fresh 리뷰 최대 실행 횟수의 기본값은 `1`입니다. 즉 Round 1의 지적을 한 번 반영한 뒤 다시 리뷰하지 않고, 남은 finding과 변경된 target을 잔여 위험으로 보존해 사용자 승인 없이 리뷰 게이트를 자동 완료합니다. `blocked`는 자동 완료하지 않습니다. base branch에 하나의 commit만 남기려면 `local-squash`를 선택하세요. 이때 task checkpoint 증거를 위해 원본 Feature tip을 내부 `refs/lee-spec-kit/integrations/*` ref로 보존합니다. 기존 local 프로젝트에 명시적 `completionStrategy`가 없으면 `update`가 `none`을 넣어 업그레이드 도중 현재 브랜치를 갑자기 병합하지 않습니다. 준비가 끝난 뒤 `local-ff` 또는 `local-squash`로 명시적으로 전환하세요.
 
 ```json
 {
@@ -255,7 +263,11 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
+    "requireCheckCategories": [
+      "spec_approve",
+      "implementation_approve",
+      "local_merge"
+    ]
   }
 }
 ```

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

@@ -59,7 +59,10 @@
 - `nextAction.category`가 `task_review`이고 `executor`가 `subagent`이면 반환된 task ID와 SHA/tree 범위를 fresh context의 읽기 전용 서브에이전트가 리뷰하고 반환된 `reviewRound`를 기록합니다.
 - `nextAction.category`가 `pre_pr_review`이고 `executor`가 `subagent`이면 반환된 모델·추론도·`reviewRound`·SHA/tree 범위로 fresh context의 읽기 전용 Feature 리뷰를 실행합니다. 리뷰 스킬 이름을 선택하거나 요구하지 않습니다.
 - 리뷰 서브에이전트는 finding만 반환하고 코드를 수정하지 않습니다. 메인 에이전트가 finding을 반영하고 reviewer metadata, reviewed scope, evidence, decision, 정확한 hash/SHA/tree target metadata를 기록합니다.
-- `workflow.agentReview.maxRounds`는 최초 리뷰 횟수가 아니라 리뷰 지적 자동 반영 횟수입니다. 그 횟수를 모두 사용하면 최신 `changes_requested` finding을 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 Plan/task/Feature 리뷰 게이트를 자동 완료합니다. `blocked` 결정은 자동 완료하지 않습니다.
+- 서브에이전트에게 위임한 뒤에는 완료, 명시적 실패, 취소, 또는 조치가 필요한 승인·사용자 입력 요청 중 하나의 종결 상태를 반환할 때까지 기다립니다.
+- 서브에이전트가 실행 중이면 가급적 긴 bounded wait를 반복합니다. 한 번의 대기가 새 소식 없이 끝난 것, 상태 메시지가 없는 것, 파일 변경이 없는 것은 아직 실행 중이라는 뜻일 뿐 실패나 정체의 증거가 아닙니다. 읽기 전용 리뷰 서브에이전트는 파일을 변경하지 않는 것이 정상입니다.
+- 조용하거나 파일을 변경하지 않았다는 이유만으로 실행 중인 서브에이전트를 중단·교체·포기하지 않습니다. 사용자의 명시적 중단 요청, 종결 실패·취소, 또는 복구 불가능한 런타임 상태가 있을 때만 중단합니다.
+- `workflow.agentReview.maxRounds`는 Plan/task/Feature 게이트별 fresh 리뷰의 최대 실행 횟수입니다. 마지막 허용 리뷰가 `changes_requested`이면 지적을 한 번 반영하지만 변경된 target을 다시 리뷰하지 않으며, 남은 finding과 리뷰 이후 target 변경을 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 게이트를 자동 완료합니다. 예를 들어 `maxRounds=1`이면 Round 1 리뷰와 지적 반영 후 Round 2 없이 계속합니다. `blocked` 결정은 자동 완료하지 않습니다.
 - spec / plan / tasks 승인, issue 생성, branch 생성은 구현 전 하드 게이트로 취급합니다.
 - standalone 모드에서는 `git worktree add`를 직접 만들지 말고 `workflow-stage`의 정확한 `nextAction.command`를 실행해 managed workspace 경로, stale 디렉터리 정리, `.env`/`.env.*` 복사 단계가 일관되게 유지되도록 합니다.
 - local 모드에서는 구현 승인 직후 종료하지 않습니다. `workflow-stage`가 반환하는 정확한 `local verify`, `local merge`, `local cleanup` 명령을 따라 검증·통합·정리가 확인되어 `done`이 될 때까지 진행합니다. `feature_remediation` 단계에서는 Feature worktree 수정이 명시적으로 허용됩니다.

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

@@ -24,8 +24,8 @@
   - `tasks.md`는 실제 실행 순서를 정의합니다
   - `issue.md`, `pr.md`는 GitHub 단계에 들어가면 stage gate의 일부로 사용합니다
 - `tasks.md`가 있다고 바로 구현하지 않습니다. 구현은 `workflow-stage --json`가 허용할 때만 시작합니다.
-- Plan 검수가 활성화되어 있으면 `plan.md`를 Review로 바꾸고 반환된 fresh 읽기 전용 `plan_review`를 위임한 뒤 `reviewRound`, evidence, decision, reviewer metadata, `specHash`, `planHash`를 기록합니다. 현재 hash에 대한 approve 검수만 Plan 승인으로 이어질 수 있습니다. reviewer는 문서를 수정하지 않고 NONE/UPDATE/ADD 결정, 요구사항 커버리지, 독립적인 Oracle, 안정적인 관찰 경계, 현실적인 실패/롤백, 제외 범위, focused/full 검증 범위를 점검합니다.
-- `workflow.agentReview.maxRounds`는 최초 Plan 리뷰가 아니라 지적 자동 반영 횟수입니다. 한도 뒤 남은 `changes_requested` finding은 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 Plan을 자동 승격합니다. `blocked`는 자동 완료하지 않습니다.
+- Plan 검수가 활성화되어 있으면 `plan.md`를 Review로 바꾸고 반환된 fresh 읽기 전용 `plan_review`를 위임한 뒤 `reviewRound`, evidence, decision, reviewer metadata, `specHash`, `planHash`를 기록합니다. approve 검수는 현재 hash와 일치해야 하며, 한도를 소진한 `changes_requested`는 아래의 잔여 위험 자동 완료 경로를 따릅니다. reviewer는 문서를 수정하지 않고 NONE/UPDATE/ADD 결정, 요구사항 커버리지, 독립적인 Oracle, 안정적인 관찰 경계, 현실적인 실패/롤백, 제외 범위, focused/full 검증 범위를 점검합니다.
+- `workflow.agentReview.maxRounds`는 fresh Plan 리뷰의 최대 실행 횟수입니다. 마지막 허용 Round가 `changes_requested`이면 지적을 한 번 반영하고 남은 finding과 그 결과의 hash 변경을 잔여 위험으로 보존한 뒤, 추가 리뷰나 사용자 리뷰 승인 토큰 없이 Plan을 자동 승격합니다. `maxRounds=1`이면 Round 2는 없습니다. `blocked`는 자동 완료하지 않습니다.
 - 범위나 동작이 바뀌면 같은 턴 안에서 활성 feature 문서를 같이 업데이트합니다.
 - 사용자 승인은 문서화된 review checkpoint와 원격/파괴적 작업 전에만 요청합니다.
 - docs 경로 검사가 중요하면 `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다.

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

@@ -33,8 +33,8 @@ Pre-PR 리뷰에서 서브에이전트가 항상 수행하는 최소 기준입
 10. `PR 전 리뷰 Decision`은 `결정: approve|changes_requested|blocked ...` (또는 `decision: ...`) 형식을 사용합니다.
 11. 반환된 `reviewRound`를 `PR 전 리뷰 Round`에 기록합니다.
 12. `PR 전 리뷰 Head`와 `PR 전 리뷰 Tree`가 `workflow-stage`의 `targetSha`와 `targetTree`와 일치하는지 확인합니다.
-13. `workflow.agentReview.maxRounds`는 최초 Feature 리뷰가 아니라 지적 자동 반영 횟수입니다. 한도 뒤 남은 `changes_requested` finding은 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 Feature 리뷰 게이트를 자동 완료합니다. `blocked`는 자동 완료하지 않습니다.
-14. PR 생성 단계로 이동하기 전 최종 Decision이 `approve`인지 확인합니다.
+13. `workflow.agentReview.maxRounds`는 fresh Feature 리뷰의 최대 실행 횟수입니다. 마지막 허용 Round가 `changes_requested`이면 지적을 한 번 반영하고 남은 finding과 그 결과의 target 변경을 잔여 위험으로 보존한 뒤, 추가 리뷰나 사용자 리뷰 승인 토큰 없이 Feature 리뷰 게이트를 자동 완료합니다. `maxRounds=1`이면 Round 2는 없습니다. `blocked`는 자동 완료하지 않습니다.
+14. 최종 Decision이 `approve`이거나 위의 한도 소진 `changes_requested` 경로가 게이트를 자동 완료한 뒤 PR 생성 단계로 이동합니다.
 
 리뷰 산출물에는 실제 사용한 `executor`, `model`, `reasoningEffort`, 검토한 commit/diff 범위, target SHA/tree, finding과 최종 decision을 기록합니다. 리뷰 서브에이전트는 코드를 수정하지 않으며, finding 반영과 문서 갱신은 메인 에이전트가 담당합니다.
 

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

@@ -15,6 +15,8 @@
 - 한 번에 하나의 태스크만 진행합니다.
 - `nextAction.executor === "subagent"`이면 반환된 `workingDirectory`에서 해당 태스크의 구현과 태스크 범위 검증을 fresh 서브에이전트에게 반환된 `model`, `reasoningEffort`, `onUnavailable` 설정과 정확한 `workerContract`로 위임합니다. 지정 모델을 사용할 수 없을 때 `inherit`은 현재 모델을 상속해 다시 위임하고, `error`는 중단 후 실패를 보고한다는 뜻입니다.
 - 구현 worker는 할당된 태스크를 직접 실행합니다. `workflow-stage` 재호출, 재위임, lee-spec-kit 문서 수정, 태스크 상태 변경, 커밋, 승인 요청, 원격/파괴적 작업은 하지 않습니다. 프로젝트 코드 수정과 태스크 범위 검사만 수행합니다.
+- 위임한 뒤 메인 에이전트는 worker의 종결 상태를 기다립니다. worker가 실행 중이면 가급적 긴 bounded wait를 반복하며, 한 번의 대기가 새 소식 없이 끝난 것, 상태 메시지가 없는 것, 파일 변경이 없는 것은 실패나 정체의 증거가 아닙니다.
+- 조용하거나 파일을 변경하지 않았다는 이유만으로 실행 중인 worker를 중단·교체·포기하지 않습니다. 사용자의 명시적 중단 요청, 종결 실패·취소, 또는 복구 불가능한 런타임 상태가 있을 때만 중단합니다.
 - 구현 worker는 승인된 `plan.md` Verification Contract를 따릅니다. `NONE`이면 영구 테스트를 추가하지 않고, `UPDATE`이면 계약을 소유한 기존 테스트만 최소 수정하며, `ADD`이면 계약에 연결된 테스트만 추가합니다. 승인된 결정이 충분하지 않다면 테스트 범위를 임의로 넓히지 말고 메인 에이전트에 보고합니다.
 - 명시적 ID가 없는 레거시 태스크는 `workflow-stage`가 안정적인 synthetic `taskId`를 반환합니다. ID 추가만을 위해 레거시 태스크 문서를 다시 쓰지 말고 반환된 ID를 사용합니다.
 
@@ -23,8 +25,8 @@
 - `tasks.md`를 현실과 맞게 유지합니다:
   - 실제 완료/검증 없이 `[DONE]`로 바꾸지 않습니다
   - `workflow.agentReview.task.enabled=true`이면 구현/검증 완료 후 `[DONE]` 대신 `[REVIEW]`로 바꾸고 checkpoint commit을 만든 뒤 독립 리뷰를 진행합니다
-  - 반환된 `reviewRound`를 기록하고, task review가 현재 SHA/tree를 `approve`한 뒤에만 `[REVIEW]`를 `[DONE]`으로 바꿉니다
-  - `workflow.agentReview.maxRounds`는 최초 task 리뷰가 아니라 지적 자동 반영 횟수입니다. 한도 뒤 남은 `changes_requested` finding은 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 task를 DONE으로 전환합니다. `blocked`는 자동 완료하지 않습니다
+  - 반환된 `reviewRound`를 기록하고, task review가 현재 SHA/tree를 `approve`하거나 아래의 한도 소진 `changes_requested` 경로가 자동 완료된 뒤 `[REVIEW]`를 `[DONE]`으로 바꿉니다
+  - `workflow.agentReview.maxRounds`는 fresh task 리뷰의 최대 실행 횟수입니다. 마지막 허용 Round가 `changes_requested`이면 지적을 한 번 반영하고 남은 finding과 그 결과의 target 변경을 잔여 위험으로 보존한 뒤, 추가 리뷰나 사용자 리뷰 승인 토큰 없이 task를 DONE으로 전환합니다. `maxRounds=1`이면 Round 2는 없습니다. `blocked`는 자동 완료하지 않습니다
   - 태스크를 닫을 때는 같은 수정에서 `Acceptance`와 `Checklist`도 함께 갱신합니다
   - 완료된 태스크에 후속 작업이 생기면 히스토리를 고치지 말고 새 태스크를 추가합니다
 - 새 태스크를 추가해야 한다면 `tasks.md`에 구체적인 제목, `Acceptance`, `Checklist`, 그리고 `NON-PRD` 또는 기존 `PRD-*` 태그가 있는 완전한 태스크 블록을 추가하세요.

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

@@ -11,7 +11,7 @@
   - 태스크 상태 변경 전에 승인이 필요한 경우는 문서화된 review checkpoint 또는 원격/파괴적 작업 직전뿐입니다.
   - 워크플로우가 요구하지 않는 standalone `OK` 승인 단계는 만들지 않습니다.
   - 해당 태스크의 `Checklist`에 unchecked 항목이 남아 있으면 `[DONE]`으로 전환하지 않습니다.
-  - `workflow.agentReview.maxRounds`는 최초 리뷰가 아니라 리뷰 지적 자동 반영 횟수입니다. 그 횟수를 다 쓰면 남은 `changes_requested` finding을 잔여 위험으로 보존하고 사용자 승인 없이 리뷰 게이트를 자동 완료합니다. `blocked`는 자동 완료하지 않습니다.
+  - `workflow.agentReview.maxRounds`는 fresh 리뷰의 최대 실행 횟수입니다. 마지막 허용 Round가 `changes_requested`이면 지적을 한 번 반영하고 남은 finding과 그 결과의 target 변경을 잔여 위험으로 보존한 뒤, 추가 리뷰나 사용자 승인 없이 리뷰 게이트를 자동 완료합니다. `maxRounds=1`이면 Round 2는 없습니다. `blocked`는 자동 완료하지 않습니다.
 - **PRD 매핑(권장)**: 각 태스크 라인에 `[PRD-FR-001]` 또는 `[PRD-SCOPE-V1-DESKTOP-EDITOR]` 같은 기존 PRD 요구사항 ID 태그를 추가하거나, PRD와 무관한 태스크는 `[NON-PRD]`로 표시하세요.
   - 단, `tasks.md`에서 PRD ID를 임의로 만들지 마세요. `docs/prd` 또는 상위 요구사항 문서에 먼저 정의된 ID만 참조해야 합니다.
   - 레거시 문서에 아직 PRD ID가 없다면, 먼저 원문 요구사항 문서에 ID를 backfill한 뒤 `spec.md`의 `PRD Refs`와 태스크 태그를 함께 맞추세요.