lee-spec-kit 0.9.7 → 0.9.8

package/package.json

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

package/templates/en/common/README.md

@@ -145,7 +145,7 @@ Existing projects can change the same settings with `lee-spec-kit config
   - `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.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 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.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`
@@ -250,7 +250,7 @@ Existing projects can change the same settings with `lee-spec-kit config
 }
 ```
 
-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. 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
 {

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

@@ -62,7 +62,7 @@ This document defines workflow policy, not a custom runtime loop.
 - 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` 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.
+- `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

@@ -25,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

@@ -144,7 +144,7 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
   - `workflow-stage`는 안정적인 태스크 ID, 작업/docs 경로, machine-readable `workerContract`를 반환합니다. worker는 `workflow-stage` 재호출이나 재위임 없이 직접 실행합니다.
   - 구현 서브에이전트는 프로젝트 코드와 태스크 범위 검사를 담당하고, 메인 에이전트는 문서, 태스크 상태, 커밋, 승인, 원격 작업을 유지합니다. 공식 hook은 `task_execute` 중 커밋을 거부합니다.
 - `workflow.agentAutomationConfigured` (boolean): `init` 또는 `config`에서 에이전트 자동화 정책을 명시적으로 선택했음을 기록해, 구버전 기본값 복구가 해당 선택을 덮어쓰지 않게 함
-- `workflow.agentReview.maxRounds` (양의 정수): Plan/태스크/Feature 리뷰에 공통 적용되는 리뷰 지적 자동 반영 최대 횟수. 한도 뒤 남은 `changes_requested` finding은 잔여 위험으로 보존하고 리뷰 게이트를 자동 완료합니다. 최초 리뷰는 세지 않으며 기본값은 `1`
+- `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`
@@ -249,7 +249,7 @@ Local 통합 방식을 직접 선택할 수 있습니다. 비대화형 실행에
 }
 ```
 
-새 프로젝트는 기본적으로 태스크 구현을 위임하고 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의 의미를 보존합니다. 리뷰 지적 자동 반영 기본값은 `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
 {

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

@@ -62,7 +62,7 @@
 - 서브에이전트에게 위임한 뒤에는 완료, 명시적 실패, 취소, 또는 조치가 필요한 승인·사용자 입력 요청 중 하나의 종결 상태를 반환할 때까지 기다립니다.
 - 서브에이전트가 실행 중이면 가급적 긴 bounded wait를 반복합니다. 한 번의 대기가 새 소식 없이 끝난 것, 상태 메시지가 없는 것, 파일 변경이 없는 것은 아직 실행 중이라는 뜻일 뿐 실패나 정체의 증거가 아닙니다. 읽기 전용 리뷰 서브에이전트는 파일을 변경하지 않는 것이 정상입니다.
 - 조용하거나 파일을 변경하지 않았다는 이유만으로 실행 중인 서브에이전트를 중단·교체·포기하지 않습니다. 사용자의 명시적 중단 요청, 종결 실패·취소, 또는 복구 불가능한 런타임 상태가 있을 때만 중단합니다.
-- `workflow.agentReview.maxRounds`는 최초 리뷰 횟수가 아니라 리뷰 지적 자동 반영 횟수입니다. 그 횟수를 모두 사용하면 최신 `changes_requested` finding을 잔여 위험으로 보존하고 사용자 리뷰 승인 토큰 없이 Plan/task/Feature 리뷰 게이트를 자동 완료합니다. `blocked` 결정은 자동 완료하지 않습니다.
+- `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

@@ -25,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`와 태스크 태그를 함께 맞추세요.