sync: to agentic-framework v1.1.56

agent-ops/.version

@@ -1 +1 @@
-1.1.55
+1.1.56

agent-ops/rules/common/rules-roadmap.md

@@ -85,7 +85,7 @@
 - 런타임은 PASS 완료 이벤트의 task group에서 `m-<milestone-slug>`를 판별하고, 상태 체크 후 `update-roadmap` 흐름으로 Milestone 업데이트를 호출한다.
 - 런타임 완료 이벤트가 최종 archive 경로만 갖고 있으면 `agent-task/archive/YYYY/MM/m-<milestone-slug>/...`를 `agent-task/m-<milestone-slug>/...` 형태의 `origin-task`로 정규화해 전달한다.
 - 런타임 호출에서 매칭되는 활성 Milestone이 없거나 둘 이상이면 추정하지 말고 수동 target 선택이 필요하다고 보고한다.
-- `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않고 같은 `m-<milestone-slug>` task group에서 follow-up plan/review를 이어간다.
+- `WARN` 또는 `FAIL`은 Milestone 완료 업데이트를 하지 않는다. 일반적으로 같은 `m-<milestone-slug>` task group에서 follow-up plan/review를 이어가지만, code-review의 user-review gate가 트리거되면 `USER_REVIEW.md`를 남기고 사용자 판단을 기다린다.
 - `[스케치]` Milestone은 Milestone 기반 `agent-task` 생성 대상이 아니다. 런타임이나 plan 스킬은 이를 구현 작업으로 라우팅하지 않고 `[계획]` 승격 필요를 보고한다.
 
 ## 완료 리뷰

agent-ops/skills/common/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, or 리뷰 루프. Review the active PLAN/CODE_REVIEW pair, append PASS/WARN/FAIL, archive both active files, and create the required next state: PASS writes complete.log, moves the task to archive, and reports m-prefixed completion metadata for runtime; WARN/FAIL immediately writes follow-up PLAN/CODE_REVIEW files. Never stop after verdict append.
+description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, or 리뷰 루프. Review the active PLAN/CODE_REVIEW pair, append PASS/WARN/FAIL, archive both active files, and create the required next state: PASS writes complete.log and moves the task to archive; WARN/FAIL writes follow-up PLAN/CODE_REVIEW files unless the user-review gate requires USER_REVIEW.md. Never stop after verdict append without writing the required next-state artifact.
 ---
 
 # Code Review
@@ -19,10 +19,21 @@ plan skill -> implementation -> code-review skill
 
 - Trigger: Korean or English active-task review requests, including `리뷰 진행해` and `리뷰해줘`, must use this skill when an active `CODE_REVIEW-*-G??.md` exists under `agent-task/*/` or `agent-task/*/*/`, excluding `agent-task/archive/**`.
 - Finalize every selected active review: append one verdict, archive the active review and plan files, then create exactly one next state before reporting.
-- Next state: `PASS` writes `complete.log` and moves the task under `agent-task/archive/YYYY/MM/`; if the task group is `m-<milestone-slug>`, report completion metadata for the runtime event; `WARN` or `FAIL` writes the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`.
+- Next state: `PASS` writes `complete.log` and moves the task under `agent-task/archive/YYYY/MM/`; if the task group is `m-<milestone-slug>`, report completion metadata for the runtime event. `WARN` or `FAIL` normally writes the next active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md`; if the user-review gate triggers, write `USER_REVIEW.md` instead.
-- Do not ask for confirmation before WARN/FAIL follow-up files. If details are uncertain, write the smallest concrete follow-up plan with file references and verification commands.
+- Do not ask for confirmation before WARN/FAIL follow-up files unless the user-review gate triggers. If details are uncertain but the gate does not trigger, write the smallest concrete follow-up plan with file references and verification commands.
 - Recovery: if a prior turn appended a verdict without archive or next-state files, resume at Step 5 and finish finalization first.
 
+## User Review Gate
+
+`USER_REVIEW.md` is a loop stop state for cases where automatic follow-up is likely to waste cycles or needs a human decision.
+
+- Compute `review-number` as `count(agent-task/{task_name}/code_review_*.log) + 1` before archiving the active review.
+- If `review-number >= 5` and the verdict is `WARN` or `FAIL`, stop the automatic loop and write `USER_REVIEW.md`.
+- If `review-number == 1`, the verdict is `FAIL`, and the blocking issue is a test environment problem rather than a repo-fixable implementation issue, stop the automatic loop and write `USER_REVIEW.md`.
+- Treat a first-review failure as a test environment problem only with evidence: missing SDK/tool/runtime, unavailable external service, absent secret/credential, unsupported OS/device/interactive environment, or another prerequisite outside the repository. Record the exact command and stdout/stderr. Before claiming a tool is missing, require `command -v <tool>` or the project-equivalent check.
+- Do not classify repo-owned setup bugs as environment problems. If a manifest, bootstrap script, test fixture, or documented project entrypoint should provide the dependency, write a normal follow-up plan instead.
+- `USER_REVIEW.md` is created from `agent-ops/skills/common/code-review/templates/user-review-template.md`, filled with the archived loop history, current archived plan/review paths, verdict, loop count, blocking evidence, and user decision options.
+
 ## Workflow Contract
 
 Active work must live under an active task directory using routed filenames. This is the state protocol shared with the plan skill.
@@ -76,6 +87,7 @@ Directory states:
 | `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub or placeholders | Implementation is pending/incomplete; review should fail completeness if invoked |
 | `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill |
 | `complete.log` + `*.log` files | Task complete (PASS), before final task-directory archive move |
+| `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan |
 | `agent-task/archive/YYYY/MM/{task_name}/complete.log` + `*.log` files | Archived completed task path (PASS); not active |
 | Only `*.log` files (no `complete.log`) | Task terminated mid-loop or abandoned |
 
@@ -88,12 +100,19 @@ Find active review files with both globs, excluding `agent-task/archive/**`:
 - `agent-task/*/CODE_REVIEW-*-G??.md`
 - `agent-task/*/*/CODE_REVIEW-*-G??.md`
 
+Also note active user-review stops, excluding `agent-task/archive/**`:
+
+- `agent-task/*/USER_REVIEW.md`
+- `agent-task/*/*/USER_REVIEW.md`
+
 | Result | Action |
 |--------|--------|
 | Exactly one | Review that task; exactly one `PLAN-*-G??.md` is expected beside it |
-| None | Nothing to review; stop and report |
+| None | If one or more `USER_REVIEW.md` files exist, report that user decision is required and list the paths. Otherwise stop and report that no active review exists. |
 | Multiple | If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active review file, review that directory. Otherwise list paths and ask which task to review; do not choose by agent judgment. |
 
+If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, report an inconsistent loop state instead of overwriting either state.
+
 ## Step 2 - Load Context
 
 Count `agent-task/{task_name}/code_review_*.log` in the selected active task directory:
@@ -125,7 +144,7 @@ Required fields:
 - `종합 판정`: exactly `PASS`, `WARN`, or `FAIL`.
 - `차원별 평가`: Pass/Warn/Fail for correctness, completeness, test coverage, API contract, code quality, plan deviation, verification trust.
 - `발견된 문제`: `없음`, or bullets using `Required`, `Suggested`, or `Nit` with `file:line` and a concrete fix.
-- `다음 단계`: keep only the matching PASS/WARN/FAIL line.
+- `다음 단계`: keep only the matching PASS, WARN/FAIL follow-up, or USER_REVIEW line.
 
 Do not check archive/next-state items in `코드리뷰 전용 체크리스트` during Step 4. Complete the applicable dedicated checklist items in the archived `code_review_*.log` during Step 7, after archive, next-state writes, and PASS task-directory moves are done.
 
@@ -134,8 +153,8 @@ Severity semantics:
 | Verdict | Meaning | Follow-up plan |
 |---------|---------|----------------|
 | `PASS` | No Required/Suggested issues. Nit-only findings may still PASS. | No |
-| `WARN` | One or more Suggested issues, zero Required. | Yes |
+| `WARN` | One or more Suggested issues, zero Required. | Yes, unless the user-review gate triggers |
-| `FAIL` | One or more Required issues. | Yes |
+| `FAIL` | One or more Required issues. | Yes, unless the user-review gate triggers |
 
 Issue severity:
 
@@ -156,7 +175,7 @@ Archive is mandatory for `PASS`, `WARN`, and `FAIL`. Archive order is fixed:
 1. Count existing `code_review_*.log` as `N`; rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_N.log`.
 2. Count existing `plan_*.log` as `M`; rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_M.log`.
 
-After archiving, neither active `.md` file remains unless Step 6 writes a follow-up.
+After archiving, neither active `.md` file remains unless Step 6 writes a follow-up plan/review or `USER_REVIEW.md`.
 
 ## Step 6 - Post-Review Actions
 
@@ -170,7 +189,18 @@ Complete log template:
 - Use `없음` for empty `잔여 Nit` or `후속 작업`.
 - A PASS `complete.log` must not contain unresolved Required or Suggested issues. Nit-only leftovers may be recorded under `잔여 Nit`.
 
-For `WARN` or `FAIL`, write new routed plan/review files using the plan skill format:
+For `WARN` or `FAIL`, apply the user-review gate before writing follow-up files.
+
+If the user-review gate triggers:
+
+- Write `agent-task/{task_name}/USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`.
+- Fill every placeholder. Use `loop-limit` or `environment-blocked` as the reason type.
+- Include all available archived loop history in chronological order, the current archived plan/review log paths, the final verdict, review number, issue summary, blocking evidence, and the exact user decision needed.
+- Do not write a new active `PLAN-{build_lane}-GNN.md` or `CODE_REVIEW-{review_lane}-GNN.md`.
+- Do not write `complete.log`.
+- If the task group is `m-<milestone-slug>`, report that the milestone task is blocked on user review; do not emit PASS completion metadata and do not call `update-roadmap`.
+
+If the user-review gate does not trigger, write new routed plan/review files using the plan skill format:
 
 - New plan number is the count of `plan_*.log` after archive.
 - Header tag is `REVIEW_<PARENT_TAG>`.
@@ -216,7 +246,7 @@ task={task_name}, plan={N}, tag={TAG}
 
 1. 판정을 append한다.
 2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다.
-3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 다음 active plan/review 파일을 즉시 작성한다.
+3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
 4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
 5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
 
@@ -246,7 +276,8 @@ task={task_name}, plan={N}, tag={TAG}
 - [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
 - [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
 - [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
-- [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
+- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
+- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
 
 ## 계획 대비 변경 사항
 
@@ -311,14 +342,15 @@ After Step 6:
 - If verdict is `PASS` and `{task_group}` matches `m-<milestone-slug>`, do not resolve the roadmap target and do not call `update-roadmap`. Report completion event metadata after the task archive move: `origin-task=agent-task/{task_name}` from the original active task path, `task-group={task_group}`, `milestone-slug=<milestone-slug>`, final archive path, `complete.log` path, and archived plan/review log paths.
 - The runtime consumes that completion event, checks current state, resolves `agent-ops/roadmap/phase/*/milestones/<milestone-slug>.md`, and calls `update-roadmap` if needed.
 - `WARN` and `FAIL` do not update the roadmap Milestone; the follow-up plan remains under the same `m-<milestone-slug>` task group when the original task was Milestone-linked.
+- `USER_REVIEW` does not update the roadmap Milestone and does not produce PASS completion metadata. Keep the active task directory in place with `USER_REVIEW.md` and archived plan/review logs until the user decides how to resume, replan, defer, or abandon the task.
 - For `PASS`, open the moved `agent-task/archive/YYYY/MM/{final_task_name}/code_review_{review_lane}_GNN_N.log`, where `{final_task_name}` is the archived task path, including `{task_group}/` for split work.
 - For `WARN` or `FAIL`, open `agent-task/{task_name}/code_review_{review_lane}_GNN_N.log`.
 - Check every applicable item in `코드리뷰 전용 체크리스트`; leave mutually exclusive verdict items unchecked.
-- If any applicable item cannot be checked, finish the missing archive, `complete.log`, task-directory move, or follow-up plan/review write first.
+- If any applicable item cannot be checked, finish the missing archive, `complete.log`, task-directory move, follow-up plan/review write, or `USER_REVIEW.md` write first.
 - Do not recreate an active review file just to update this checklist; update the archived `code_review_*.log`.
-- Only report after the archived review log has the verdict, applicable checked review-only checklist, required next-state files, for `PASS` the final task archive move, and for `m-*` PASS tasks the completion event metadata.
+- Only report after the archived review log has the verdict, applicable checked review-only checklist, required next-state files, for `PASS` the final task archive move, for `m-*` PASS tasks the completion event metadata, and for `USER_REVIEW` the filled `USER_REVIEW.md`.
 
-Report Required/Suggested counts, archive names, the final task archive path for `PASS` or new plan path for `WARN`/`FAIL`, and any `m-*` runtime completion event metadata.
+Report Required/Suggested counts, archive names, the final task archive path for `PASS`, the new plan path for normal `WARN`/`FAIL`, the `USER_REVIEW.md` path for user review stops, and any `m-*` runtime completion event metadata.
 
 ## Review Dimensions
 
@@ -349,5 +381,6 @@ Report Required/Suggested counts, archive names, the final task archive path for
 - PASS: `complete.log` written from `agent-ops/skills/common/code-review/templates/complete-log-template.md`, then task directory moved under `agent-task/archive/YYYY/MM/` with task-group path preserved for split work.
 - PASS milestone task group: `m-<milestone-slug>` completion event metadata was reported for runtime; roadmap was not modified by code-review.
 - PASS split: empty active parent `agent-task/{task_group}/` removed after the subtask move; non-empty parent left in place.
-- WARN/FAIL: new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` created with matching headers and matching `구현 체크리스트`; no `complete.log`.
+- WARN/FAIL without user-review gate: new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` created with matching headers and matching `구현 체크리스트`; no `complete.log`.
+- USER_REVIEW: `USER_REVIEW.md` exists from template, no active `PLAN-*.md` or `CODE_REVIEW-*.md` remains, and no `complete.log` was written.
 - The applicable review-agent-only finalization checklist was completed before reporting.

agent-ops/skills/common/code-review/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Code Review"
-  short_description: "Review and continue task loops"
+  short_description: "Review and route task loops"
-  default_prompt: "Use $code-review to review the active repository task, archive active files, and create complete.log or follow-up plan/review files."
+  default_prompt: "Use $code-review to review the active repository task, archive active files, and create complete.log, follow-up plan/review files, or USER_REVIEW.md."

agent-ops/skills/common/code-review/templates/user-review-template.md

@@ -0,0 +1,47 @@
+# User Review Required - {task_name}
+
+## 요청 일시
+
+{YYYY-MM-DD or ISO-8601}
+
+## 상태
+
+USER_REVIEW
+
+## 사유
+
+- 유형: {loop-limit or environment-blocked}
+- 현재 리뷰 회차: {review-number}
+- 최종 판정: {WARN or FAIL}
+- 요약: {why automatic follow-up stopped}
+
+## 루프 이력
+
+| Plan | Review | Verdict | 메모 |
+|------|--------|---------|------|
+| `{plan-log-0}` | `{code-review-log-0}` | {PASS/WARN/FAIL/unknown} | {main issue or blocking reason} |
+| `{current-archived-plan-log}` | `{current-archived-review-log}` | {WARN/FAIL} | {main issue or blocking reason} |
+
+## 차단 근거
+
+- 문제: {review finding summary}
+- 현재 archive plan: `{current-archived-plan-log}`
+- 현재 archive review: `{current-archived-review-log}`
+- 검증 명령: `{command or 없음}`
+- 실제 출력: {stdout/stderr excerpt or saved output path}
+- 환경 판단 근거: {why this is outside repo-fixable scope, or 없음}
+
+## 사용자 결정 필요
+
+- [ ] 자동 follow-up plan/review를 계속 진행한다.
+- [ ] 계획을 재작성한다.
+- [ ] 테스트 환경, secret, 외부 서비스, SDK, 장비 조건을 준비한 뒤 재시도한다.
+- [ ] 작업 범위를 줄이거나 보류/폐기한다.
+
+## 재개 조건
+
+- {what must be true before the next plan/review loop should start}
+
+## 다음 실행 힌트
+
+- {suggested command, task path, or user decision needed to resume}

agent-ops/skills/common/plan/SKILL.md

@@ -12,10 +12,12 @@ Create the planning artifacts for the implementation loop:
 ```text
 plan skill -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub
 implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md
-code-review skill -> verdict + archive, complete.log, and PASS task-directory archive move or new follow-up plan/review files
+code-review skill -> verdict + archive, complete.log, and PASS task-directory archive move, new follow-up plan/review files, or USER_REVIEW.md
 runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call
 ```
 
+`code-review` may stop the automatic loop with `USER_REVIEW.md` when repeated non-PASS reviews or first-review test environment blockers require a user decision. Plan creation after `USER_REVIEW.md` requires an explicit user decision.
+
 ## Workflow Contract
 
 This skill intentionally uses routed active files under an active task directory as the state protocol. Do not change this directory or filename contract unless the paired code-review skill is updated together.
@@ -99,6 +101,7 @@ Directory states:
 | `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub | Implementation is pending/in progress |
 | `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill |
 | `complete.log` + `*.log` files | Task complete (PASS), before final task-directory archive move |
+| `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan |
 | `agent-task/archive/YYYY/MM/{task_name}/complete.log` + `*.log` files | Archived completed task path (PASS); not active |
 | Only `*.log` files (no `complete.log`) | Task terminated mid-loop or abandoned |
 
@@ -111,6 +114,11 @@ Otherwise, find active plan files with both globs, excluding `agent-task/archive
 - `agent-task/*/PLAN-*-G??.md`
 - `agent-task/*/*/PLAN-*-G??.md`
 
+Also note active user-review stops, excluding `agent-task/archive/**`:
+
+- `agent-task/*/USER_REVIEW.md`
+- `agent-task/*/*/USER_REVIEW.md`
+
 | Result | Action |
 |--------|--------|
 | Exactly one | Continue that task |
@@ -119,6 +127,10 @@ Otherwise, find active plan files with both globs, excluding `agent-task/archive
 
 The routed plan file is the loop entry point. A missing active plan normally means only that no plan has been started for a new task; do not create task files for casual analysis, status, or review requests unless the user explicitly asks for a plan.
 
+If no active plan exists but one or more `USER_REVIEW.md` files exist, report that user decision is required and list the paths unless the user explicitly asked to resume one of them. If a selected active task directory contains `USER_REVIEW.md`, read it before planning. Do not write a new follow-up plan unless the user explicitly decides to continue, replan, retry after preparing the environment, or change the task scope. When planning resumes from `USER_REVIEW.md`, archive it to `user_review_N.log` in the same task directory before writing the new active plan/review pair, and record the user decision in the new plan `배경` or `분석 결과`.
+
+If a selected task directory contains both `USER_REVIEW.md` and active `PLAN-*-G??.md` or `CODE_REVIEW-*-G??.md`, report an inconsistent loop state and do not overwrite either state until the user decides whether to resume from user review or continue the active plan/review.
+
 로드맵 확인:
 
 - `agent-ops/roadmap/current.md`가 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다.
@@ -176,6 +188,7 @@ Before writing new active files for the chosen active task directory:
 
 - Count existing `agent-task/{task_name}/plan_*.log`; call it `N`. If `PLAN-*-G??.md` exists in that same directory, rename `PLAN-{build_lane}-GNN.md` to `plan_{build_lane}_GNN_N.log`.
 - Count existing `agent-task/{task_name}/code_review_*.log`; call it `M`. If `CODE_REVIEW-*-G??.md` exists in that same directory, rename `CODE_REVIEW-{review_lane}-GNN.md` to `code_review_{review_lane}_GNN_M.log`.
+- Count existing `agent-task/{task_name}/user_review_*.log`; call it `U`. If `USER_REVIEW.md` exists in that same directory and the user explicitly decided to resume planning, rename `USER_REVIEW.md` to `user_review_U.log`.
 
 The new plan number is the count of `plan_*.log` after archiving.
 
@@ -277,7 +290,7 @@ task={task_name}, plan={N}, tag={TAG}
 
 1. 판정을 append한다.
 2. `CODE_REVIEW-{review_lane}-GNN.md` → `code_review_{review_lane}_GNN_N.log`, `PLAN-{build_lane}-GNN.md` → `plan_{build_lane}_GNN_M.log`로 아카이브한다.
-3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 다음 active plan/review 파일을 즉시 작성한다.
+3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
 4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
 5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
 
@@ -307,7 +320,8 @@ task={task_name}, plan={N}, tag={TAG}
 - [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
 - [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
 - [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
-- [ ] WARN/FAIL이면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
+- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
+- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
 
 ## 계획 대비 변경 사항
 
@@ -379,6 +393,7 @@ Sections and their ownership:
 - Milestone-linked work uses `agent-task/m-<milestone-slug>/` as the task group; non-roadmap task groups do not start with `m-`.
 - Both first lines match `<!-- task={task_name} plan={N} tag={TAG} -->`.
 - Previous active files, if any, were archived with correct numeric suffixes.
+- If resuming from `USER_REVIEW.md`, it was archived to `user_review_N.log` and the user decision was recorded in the new plan.
 - Every plan item has problem, solution, checklist, test decision, and intermediate verification.
 - The plan and review stub have matching `구현 체크리스트` item text/order, and the final checkbox is the mandatory `CODE_REVIEW-*-G??.md` completion item.
 - The review stub has a clearly marked `코드리뷰 전용 체크리스트` owned only by the review agent.