lee-spec-kit 0.9.4 → 0.9.6

package/package.json

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

package/templates/en/common/README.md

@@ -120,7 +120,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 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`, and `--completion-strategy`.
+`--reviews`, `--max-review-rounds`, and `--completion-strategy`.
 
 - 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).
@@ -142,6 +142,7 @@ Non-interactive setup exposes the same choices through `--task-agent`,
   - `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.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`
@@ -197,6 +198,7 @@ Non-interactive setup exposes the same choices through `--task-agent`,
       }
     },
     "agentReview": {
+      "maxRounds": 1,
       "plan": {
         "enabled": true,
         "evidenceMode": "path_required",
@@ -240,7 +242,7 @@ Non-interactive setup exposes the same choices through `--task-agent`,
 }
 ```
 
-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. 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 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.
 
 ```json
 {

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

@@ -53,12 +53,13 @@ This document defines workflow policy, not a custom runtime loop.
 - lee-spec-kit owns docs structure, workflow stages, and validators.
 - Codex owns the execution loop, tool usage, and hook lifecycle.
 - Modify implementation code only when `implementationAllowed === true`. Normal task work uses `stage === "implementation"`; review fixes use `task_review_fix` or `feature_review_fix`, and verification fixes use `feature_remediation`.
-- When `nextAction.category` is `plan_review` with `executor: subagent`, delegate a fresh read-only review of `spec.md` and `plan.md` for the returned `specHash` and `planHash`. The main agent records Plan Review evidence, decision, reviewer metadata, and both hashes. Any later spec/plan content change invalidates that review.
+- When `nextAction.category` is `plan_review` with `executor: subagent`, delegate a fresh read-only review of `spec.md` and `plan.md` for the returned `specHash` and `planHash`. The main agent records the returned `reviewRound`, Plan Review evidence, decision, reviewer metadata, and both hashes. Any later spec/plan content change invalidates that review.
 - When `nextAction.category` is `task_execute` with `executor: subagent`, mark that one task active, then delegate its implementation and task-scoped checks to a fresh subagent in the returned `workingDirectory` with the returned model, reasoning effort, unavailability policy, and exact `workerContract`. No named execution skill is required.
 - The implementation worker executes directly, follows the approved Verification Contract, and does not add unplanned durable tests. It must not run `workflow-stage` or spawn another subagent. It may edit project code and run scoped checks, but it must not edit lee-spec-kit docs, change task state, commit, request approvals, or perform remote/destructive actions. The main agent inspects the result and owns docs synchronization, task transitions, commits, and workflow continuation; official hooks block commits while `task_execute` remains active.
-- When `nextAction.category` is `task_review` with `executor: subagent`, delegate a fresh read-only review for the returned task ID and SHA/tree range.
-- When `nextAction.category` is `pre_pr_review` with `executor: subagent`, run a fresh read-only Feature review using the returned model, reasoning effort, and SHA/tree range. Do not select or require a named review skill.
+- 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.
 - 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,7 +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 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.
+- 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 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

@@ -31,8 +31,10 @@ When `workflow-stage --json` returns `nextAction.executor: subagent`, delegate t
 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. Confirm `Pre-PR Reviewed Head` and `Pre-PR Reviewed Tree` match the `targetSha` and `targetTree` returned by `workflow-stage`.
-12. Ensure the final decision is `approve` before moving to PR creation.
+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.
 
 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

@@ -23,7 +23,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
-  - move `[REVIEW]` to `[DONE]` only after the task reviewer approves the current SHA/tree
+  - 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`
   - 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/plan.md

@@ -18,6 +18,8 @@
   - Example: `docs/features/F001-foo/decisions.md` or another existing review artifact under the docs root
 - **Plan Review Decision**: -
   - Format: `decision: approve|changes_requested|blocked ...`
+- **Plan Review Round**: -
+  - Positive integer returned by `workflow-stage --json`; the first review is `1`
 - **Plan Reviewed Spec Hash**: -
   - Exact `specHash` returned by `workflow-stage --json`
 - **Plan Reviewed Plan Hash**: -

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

@@ -7,10 +7,11 @@
 - **Task communication / confirmation**:
   - `[TODO] → [DOING]`: share the task title first, then update the task state in `tasks.md`
   - `[DOING] → [REVIEW]/[DONE]`: share the result and verification first, then update `Acceptance` and `Checklist` in the same edit
-  - `[REVIEW] → [DONE]`: record the fresh task review evidence, decision, reviewed head, and reviewed tree before completion
+  - `[REVIEW] → [DONE]`: record the returned review round, fresh task review evidence, decision, reviewed head, and reviewed tree before completion
   - 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`.
 - **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.
@@ -41,6 +42,8 @@
 - **Pre-PR Decision**: -
   - Format: `decision: approve|changes_requested|blocked ...` (or `결정: ...`)
   - PR creation requires final decision `approve`
+- **Pre-PR Review Round**: -
+  - Positive integer returned by `workflow-stage --json`; the first review is `1`
 - **Pre-PR Reviewed Head**: -
   - Project code commit SHA reviewed by the Feature reviewer
 - **Pre-PR Reviewed Tree**: -
@@ -66,6 +69,7 @@
     - [ ] (subtask)
   - Review Evidence: -
   - Review Decision: -
+  - Review Round: -
   - Reviewed Head: -
   - Reviewed Tree: -
 ```

package/templates/ko/common/README.md

@@ -119,7 +119,7 @@ npx lee-spec-kit docs get agents --json
 `lee-spec-kit init`을 실행하면 문서 루트(기본: `docs/`)에 `.lee-spec-kit.json`이 생성됩니다.
 대화형 init에서는 권장 설정을 그대로 쓰거나 Task 구현 위임, Plan/Task/Feature 검수,
 Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에서는 `--task-agent`,
-`--reviews`, `--completion-strategy`로 같은 값을 지정합니다.
+`--reviews`, `--max-review-rounds`, `--completion-strategy`로 같은 값을 지정합니다.
 
 - `lee-spec-kit feature`, `config`, `update`, `detect`, workflow validator에서 문서 위치/프로젝트 타입/언어를 해석하는 용도로 사용됩니다.
 - `docsRepo`, `pushDocs`, `docsRemote`는 CLI 관리 **Docs Push 정책**을 위한 메타데이터입니다. (자동 push는 하지 않습니다)
@@ -141,6 +141,7 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
   - `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.agentReview.plan` / `workflow.agentReview.task` / `workflow.agentReview.feature` (object): Plan/태스크/Feature 독립 리뷰 설정
   - `enabled`: 해당 리뷰 게이트 활성화 여부. 새 프로젝트는 Plan과 Feature `true`, task `false`
   - `evidenceMode`: `path_required | any`
@@ -196,6 +197,7 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
       }
     },
     "agentReview": {
+      "maxRounds": 1,
       "plan": {
         "enabled": true,
         "evidenceMode": "path_required",
@@ -239,7 +241,7 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
 }
 ```
 
-새 프로젝트와 업데이트된 프로젝트는 기본적으로 태스크 구현을 위임하고 Plan 검수를 활성화합니다. 직접 구현하거나 Plan 검수를 끄려면 각각 `workflow.agentExecution.task.enabled` 또는 `workflow.agentReview.plan.enabled`를 `false`로 설정하세요. 새 local 프로젝트는 `local-ff`와 Feature agent review를 사용합니다. 태스크마다 리뷰하려면 `workflow.agentReview.task.enabled`를 `true`로 켜세요. base branch에 하나의 commit만 남기려면 `local-squash`를 선택하세요. 이때 task checkpoint 증거를 위해 원본 Feature tip을 내부 `refs/lee-spec-kit/integrations/*` ref로 보존합니다. 기존 local 프로젝트에 명시적 `completionStrategy`가 없으면 `update`가 `none`을 넣어 업그레이드 도중 현재 브랜치를 갑자기 병합하지 않습니다. 준비가 끝난 뒤 `local-ff` 또는 `local-squash`로 명시적으로 전환하세요.
+새 프로젝트와 업데이트된 프로젝트는 기본적으로 태스크 구현을 위임하고 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`로 명시적으로 전환하세요.
 
 ```json
 {

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

@@ -53,12 +53,13 @@
 - lee-spec-kit은 문서 구조, workflow 단계, validator를 담당합니다.
 - Codex는 실행 루프, 도구 사용, hook lifecycle을 담당합니다.
 - `implementationAllowed === true`일 때만 구현 코드를 수정합니다. 일반 태스크 구현은 `stage === "implementation"`에서, 리뷰 수정은 `task_review_fix` 또는 `feature_review_fix`에서, 검증 수정은 `feature_remediation`에서만 수행합니다.
-- `nextAction.category`가 `plan_review`이고 `executor`가 `subagent`이면 반환된 `specHash`와 `planHash`를 대상으로 fresh 읽기 전용 서브에이전트가 `spec.md`와 `plan.md`를 검수합니다. 메인 에이전트가 Plan 검수 evidence, decision, reviewer metadata와 두 hash를 기록하며 이후 spec/plan 내용 변경은 기존 검수를 무효화합니다.
+- `nextAction.category`가 `plan_review`이고 `executor`가 `subagent`이면 반환된 `specHash`와 `planHash`를 대상으로 fresh 읽기 전용 서브에이전트가 `spec.md`와 `plan.md`를 검수합니다. 메인 에이전트가 반환된 `reviewRound`, Plan 검수 evidence, decision, reviewer metadata와 두 hash를 기록하며 이후 spec/plan 내용 변경은 기존 검수를 무효화합니다.
 - `nextAction.category`가 `task_execute`이고 `executor`가 `subagent`이면 해당 태스크 하나를 활성화한 뒤, 반환된 `workingDirectory`에서 fresh 서브에이전트에게 반환된 모델·추론도·unavailability 정책과 정확한 `workerContract`로 구현과 태스크 범위 검증을 위임합니다. 특정 이름의 실행 스킬은 요구하지 않습니다.
 - 구현 worker는 승인된 Verification Contract를 따르고 계획되지 않은 영구 테스트를 추가하지 않으며 직접 실행합니다. `workflow-stage`를 호출하거나 다른 서브에이전트를 생성하지 않습니다. 프로젝트 코드 수정과 범위 내 검사는 수행할 수 있지만 lee-spec-kit 문서 수정, 태스크 상태 변경, 커밋, 승인 요청, 원격/파괴적 작업은 하지 않습니다. 메인 에이전트가 결과를 확인하고 문서 동기화, 태스크 전환, 커밋, 후속 workflow를 소유하며, 공식 hook은 `task_execute`가 활성화된 동안 커밋을 차단합니다.
-- `nextAction.category`가 `task_review`이고 `executor`가 `subagent`이면 반환된 task ID와 SHA/tree 범위를 fresh context의 읽기 전용 서브에이전트가 리뷰합니다.
-- `nextAction.category`가 `pre_pr_review`이고 `executor`가 `subagent`이면 반환된 모델·추론도·SHA/tree 범위로 fresh context의 읽기 전용 Feature 리뷰를 실행합니다. 리뷰 스킬 이름을 선택하거나 요구하지 않습니다.
+- `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` 결정은 자동 완료하지 않습니다.
 - 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,7 +24,8 @@
   - `tasks.md`는 실제 실행 순서를 정의합니다
   - `issue.md`, `pr.md`는 GitHub 단계에 들어가면 stage gate의 일부로 사용합니다
 - `tasks.md`가 있다고 바로 구현하지 않습니다. 구현은 `workflow-stage --json`가 허용할 때만 시작합니다.
-- Plan 검수가 활성화되어 있으면 `plan.md`를 Review로 바꾸고 반환된 fresh 읽기 전용 `plan_review`를 위임한 뒤 evidence, decision, reviewer metadata, `specHash`, `planHash`를 기록합니다. 현재 hash에 대한 approve 검수만 Plan 승인으로 이어질 수 있습니다. reviewer는 문서를 수정하지 않고 NONE/UPDATE/ADD 결정, 요구사항 커버리지, 독립적인 Oracle, 안정적인 관찰 경계, 현실적인 실패/롤백, 제외 범위, focused/full 검증 범위를 점검합니다.
+- 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`는 자동 완료하지 않습니다.
 - 범위나 동작이 바뀌면 같은 턴 안에서 활성 feature 문서를 같이 업데이트합니다.
 - 사용자 승인은 문서화된 review checkpoint와 원격/파괴적 작업 전에만 요청합니다.
 - docs 경로 검사가 중요하면 `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다.

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

@@ -31,8 +31,10 @@ Pre-PR 리뷰에서 서브에이전트가 항상 수행하는 최소 기준입
 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 전 리뷰 Head`와 `PR 전 리뷰 Tree`가 `workflow-stage`의 `targetSha`와 `targetTree`와 일치하는지 확인합니다.
-12. PR 생성 단계로 이동하기 전 최종 Decision이 `approve`인지 확인합니다.
+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`인지 확인합니다.
 
 리뷰 산출물에는 실제 사용한 `executor`, `model`, `reasoningEffort`, 검토한 commit/diff 범위, target SHA/tree, finding과 최종 decision을 기록합니다. 리뷰 서브에이전트는 코드를 수정하지 않으며, finding 반영과 문서 갱신은 메인 에이전트가 담당합니다.
 

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

@@ -23,7 +23,8 @@
 - `tasks.md`를 현실과 맞게 유지합니다:
   - 실제 완료/검증 없이 `[DONE]`로 바꾸지 않습니다
   - `workflow.agentReview.task.enabled=true`이면 구현/검증 완료 후 `[DONE]` 대신 `[REVIEW]`로 바꾸고 checkpoint commit을 만든 뒤 독립 리뷰를 진행합니다
-  - task review가 현재 SHA/tree를 `approve`한 뒤에만 `[REVIEW]`를 `[DONE]`으로 바꿉니다
+  - 반환된 `reviewRound`를 기록하고, task review가 현재 SHA/tree를 `approve`한 뒤에만 `[REVIEW]`를 `[DONE]`으로 바꿉니다
+  - `workflow.agentReview.maxRounds`는 최초 task 리뷰가 아니라 지적 자동 반영 횟수입니다. 한도 뒤 남은 `changes_requested` finding은 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 task를 DONE으로 전환합니다. `blocked`는 자동 완료하지 않습니다
   - 태스크를 닫을 때는 같은 수정에서 `Acceptance`와 `Checklist`도 함께 갱신합니다
   - 완료된 태스크에 후속 작업이 생기면 히스토리를 고치지 말고 새 태스크를 추가합니다
 - 새 태스크를 추가해야 한다면 `tasks.md`에 구체적인 제목, `Acceptance`, `Checklist`, 그리고 `NON-PRD` 또는 기존 `PRD-*` 태그가 있는 완전한 태스크 블록을 추가하세요.

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

@@ -18,6 +18,8 @@
   - 예: `docs/features/F001-foo/decisions.md` 또는 docs 루트 아래의 실제 리뷰 산출물
 - **Plan 검수 Decision**: -
   - 형식: `결정: approve|changes_requested|blocked ...` 또는 `decision: ...`
+- **Plan 검수 Round**: -
+  - `workflow-stage --json`이 반환한 양의 정수이며 첫 리뷰는 `1`
 - **Plan 검수 Spec Hash**: -
   - `workflow-stage --json`이 반환한 정확한 `specHash`
 - **Plan 검수 Plan Hash**: -

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

@@ -7,10 +7,11 @@
 - **태스크 공유 / 확인**:
   - `[TODO] → [DOING]`: 시작 전 태스크 제목을 공유하고 `tasks.md`에서 상태를 함께 갱신합니다
   - `[DOING] → [REVIEW]/[DONE]`: 완료 전 결과/검증을 공유하고 같은 수정에서 `Acceptance`와 `Checklist`를 함께 갱신합니다
-  - `[REVIEW] → [DONE]`: 완료 전에 fresh 태스크 리뷰 Evidence, Decision, Reviewed Head, Reviewed Tree를 기록합니다
+  - `[REVIEW] → [DONE]`: 완료 전에 반환된 리뷰 Round와 fresh 태스크 리뷰 Evidence, Decision, Reviewed Head, Reviewed Tree를 기록합니다
   - 태스크 상태 변경 전에 승인이 필요한 경우는 문서화된 review checkpoint 또는 원격/파괴적 작업 직전뿐입니다.
   - 워크플로우가 요구하지 않는 standalone `OK` 승인 단계는 만들지 않습니다.
   - 해당 태스크의 `Checklist`에 unchecked 항목이 남아 있으면 `[DONE]`으로 전환하지 않습니다.
+  - `workflow.agentReview.maxRounds`는 최초 리뷰가 아니라 리뷰 지적 자동 반영 횟수입니다. 그 횟수를 다 쓰면 남은 `changes_requested` finding을 잔여 위험으로 보존하고 사용자 승인 없이 리뷰 게이트를 자동 완료합니다. `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`와 태스크 태그를 함께 맞추세요.
@@ -41,6 +42,8 @@
 - **PR 전 리뷰 Decision**: -
   - 형식: `결정: approve|changes_requested|blocked ...` (또는 `decision: ...`)
   - PR 생성 전 최종 통과 기준은 `approve`
+- **PR 전 리뷰 Round**: -
+  - `workflow-stage --json`이 반환한 양의 정수이며 첫 리뷰는 `1`
 - **PR 전 리뷰 Head**: -
   - Feature 리뷰가 확인한 project code commit SHA
 - **PR 전 리뷰 Tree**: -
@@ -66,6 +69,7 @@
     - [ ] (서브 태스크)
   - Review Evidence: -
   - Review Decision: -
+  - Review Round: -
   - Reviewed Head: -
   - Reviewed Tree: -
 ```