update agent-ops skills and templates

agent-ops/.version

@@ -1 +1 @@
-1.1.78
+1.1.79

agent-ops/skills/common/_templates/implementation-user-review-request-section.md

@@ -0,0 +1,10 @@
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 재개 조건: 없음

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, USER_REVIEW.md resolution, 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; user review resolution that closes the task writes complete.log before archive. Never stop after verdict append or user-review closure without writing the required next-state artifact.
+description: Use for active task review requests such as 리뷰 진행해, 리뷰해줘, 코드 리뷰해줘, code review, CODE_REVIEW.md, USER_REVIEW.md resolution, implementation-time 사용자 리뷰 요청, 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; user review resolution that closes the task writes complete.log before archive. Never stop after verdict append or user-review closure without writing the required next-state artifact.
 ---
 
 # Code Review
@@ -15,11 +15,14 @@ plan skill -> implementation -> code-review skill
      +----- issues found: new routed plan/review files
 ```
 
+Implementation may stop early by filling the active review stub's `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`. Code-review validates that request and, when justified, writes `USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`.
+
 ## Core Loop Rules
 
 - Trigger: Korean or English active-task review requests, including `리뷰 진행해` and `리뷰해줘`, must use this skill when an active `CODE_REVIEW-*-G??.md` or `USER_REVIEW.md` exists under `agent-task/*/` or `agent-task/*/*/`, excluding `agent-task/archive/**`.
 - Finalize every selected active state: for `CODE_REVIEW-*-G??.md`, append one verdict, archive the active review and plan files, then create exactly one next state; for `USER_REVIEW.md` completion, update the stop state, write `complete.log`, and archive the task. Do not report before finalization is complete.
 - 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. A completed `USER_REVIEW.md` uses the same terminal `complete.log` and archive path as `PASS`.
+- A filled implementation-owned `사용자 리뷰 요청` is a review input, not a next state by itself. If it is a genuine user-only decision, external environment prerequisite, or scope conflict, the user-review gate triggers and this skill writes `USER_REVIEW.md`; if it is vague, unsupported, or repo-fixable, write a normal WARN/FAIL follow-up plan instead.
 - 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, or resolved `USER_REVIEW.md` without `complete.log`, resume at the matching finalization step and finish the missing artifacts first.
 
@@ -30,7 +33,9 @@ plan skill -> implementation -> code-review skill
 - 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`.
+- If the active review file has a filled `사용자 리뷰 요청` with `상태` other than `없음`, and the blocker is a user-only decision, external environment prerequisite, or scope conflict that the repository cannot safely resolve by code changes alone, 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.
+- Treat an implementation-owned `사용자 리뷰 요청` as valid only with specific decision questions, evidence, attempted commands/output or a reason commands could not run, and clear resume conditions. Vague uncertainty, repo-owned setup bugs, and ordinary incomplete implementation become normal WARN/FAIL follow-up plans instead.
 - 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.
 
@@ -96,6 +101,7 @@ Directory states:
 | State | Meaning |
 |-------|---------|
 | `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub or placeholders | Implementation is pending/incomplete; review should fail completeness if invoked |
+| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation is blocked on user input; review validates the request and writes `USER_REVIEW.md` if justified |
 | `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill |
 | `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move |
 | `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan |
@@ -146,6 +152,7 @@ Before writing the verdict:
 - If a checklist item contains integrated verification for a feature, treat that feature item as incomplete until both implementation evidence and the matching verification output are present. Do not accept a separate unchecked completion-criteria item as a substitute.
 - Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item.
 - Treat blank placeholder sections, missing actual implementation notes, missing checklist completion, or missing actual stdout/stderr in the active review file as a completeness or verification-trust failure.
+- Read the `사용자 리뷰 요청` section. If `상태` is not `없음`, validate the exact decision needed, blocker evidence, command output or not-run reason, and resume condition before deciding whether the user-review gate triggers.
 - Grep renamed/removed symbols for stale references.
 - Confirm every required test exists, name matches, and assertions are meaningful.
 - Cross-check claimed verification output in the active review file against actual code and project commands.
@@ -211,7 +218,7 @@ 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.
+- Fill every placeholder. Use `loop-limit`, `environment-blocked`, or `implementation-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`.
@@ -234,6 +241,8 @@ If the user-review gate does not trigger, write new routed plan/review files usi
 - `WARN`: one grouped plan item for Suggested issues, plus related Nit issues if useful.
 - Each plan item needs problem, solution with before/after when non-trivial, checklist, test decision, intermediate verification.
 - The follow-up plan and review stub must contain matching `구현 체크리스트` item text/order, including the final mandatory `CODE_REVIEW-*-G??.md` completion item.
+- The follow-up plan's implementer instructions and review stub must include the implementation-time `사용자 리뷰 요청` stop path so the next implementer can act without reading the plan skill.
+- Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the follow-up review stub's `사용자 리뷰 요청` section.
 
 Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent):
 
@@ -246,6 +255,7 @@ Routed review stub template (fill `{…}` placeholders; everything else is fixed
 > The task is NOT complete until every implementation-owned section below is filled in.
 > Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
 > Fill implementation-owned sections, then stop with active files in place and report ready for review.
+> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
 > Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
 > Follow the ownership table at the bottom of this file for which sections you own.
 
@@ -305,6 +315,17 @@ _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께
 
 _구현 에이전트가 주요 설계 결정 사항을 기록한다._
 
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 재개 조건: 없음
+
 ## 리뷰어를 위한 체크포인트
 
 {pre-filled from plan — one bullet per review focus area}
@@ -317,6 +338,7 @@ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후
 - 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
 - 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
 - `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
+- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
 
 ### {TAG}-1 중간 검증
 ```
@@ -346,6 +368,7 @@ Sections and their ownership:
 | 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 |
 | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
 | 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 |
+| 사용자 리뷰 요청 | 구현 에이전트가 채움 | 진행에 사용자 입력이 필요하지 않으면 `상태: 없음` 유지; 필요하면 결정 항목, 근거, 명령 출력, 재개 조건을 기록 |
 | 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 |
 | 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움; 명령 변경은 `계획 대비 변경 사항`에 기록 |
 | 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 |
@@ -402,6 +425,8 @@ Report Required/Suggested counts, archive names, the final task archive path for
 - 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 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`.
+- Follow-up review stubs include the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`.
 - USER_REVIEW: `USER_REVIEW.md` exists from template, no active `PLAN-*.md` or `CODE_REVIEW-*.md` remains, and no `complete.log` was written.
+- Implementation-requested USER_REVIEW: archived review log preserves the filled `사용자 리뷰 요청` evidence and the generated `USER_REVIEW.md` records the exact user decision needed.
 - USER_REVIEW resolved as PASS: archived task contains both resolved `USER_REVIEW.md` and `complete.log`.
 - The applicable review-agent-only finalization checklist was completed before reporting.

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

@@ -10,7 +10,7 @@ USER_REVIEW
 
 ## 사유
 
-- 유형: {loop-limit or environment-blocked}
+- 유형: {loop-limit, environment-blocked, or implementation-blocked}
 - 현재 리뷰 회차: {review-number}
 - 최종 판정: {WARN or FAIL}
 - 요약: {why automatic follow-up stopped}
@@ -29,7 +29,7 @@ USER_REVIEW
 - 현재 archive review: `{current-archived-review-log}`
 - 검증 명령: `{command or 없음}`
 - 실제 출력: {stdout/stderr excerpt or saved output path}
-- 환경 판단 근거: {why this is outside repo-fixable scope, or 없음}
+- 차단 판단 근거: {why this needs user decision or is outside repo-fixable scope, or 없음}
 
 ## 사용자 결정 필요
 

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

@@ -11,13 +11,15 @@ 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
+implementation -> code changes + filled CODE_REVIEW-{review_lane}-GNN.md, or blocked-state user-review request recorded in the review stub
 code-review skill -> verdict + archive, complete.log, and PASS/user-review-resolved 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. If the user decision closes the task as complete/PASS, code-review resolves `USER_REVIEW.md`, writes `complete.log`, and archives the task instead of creating a new plan.
 
+The plan file and review stub must be self-sufficient for implementation agents that do not read this skill. If implementation discovers a user-only decision, external environment prerequisite, or scope conflict that blocks safe progress, the implementing agent records a `사용자 리뷰 요청` in the active `CODE_REVIEW-*-G??.md`, leaves active files in place, and reports ready for review. The code-review skill validates that request and writes `USER_REVIEW.md` when the stop is justified. Use `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` as the shared section template.
+
 ## 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.
@@ -42,6 +44,7 @@ Filename rules:
 Role boundary rules:
 
 - Implementing agents fill implementation-owned `CODE_REVIEW-*-G??.md` sections, keep active files in place, and report ready for review.
+- If implementation cannot continue without user input, implementing agents fill the review stub's `사용자 리뷰 요청` section with the exact decision needed, evidence, commands/output, and resume condition, then stop with active files in place.
 - Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, review-only checklist) is code-review-skill only.
 
 Split decision policy:
@@ -99,6 +102,7 @@ Directory states:
 |-------|---------|
 | `PLAN-*-G??.md` only | Invalid; plan skill always writes both active files |
 | `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` stub | Implementation is pending/in progress |
+| `PLAN-*-G??.md` + `CODE_REVIEW-*-G??.md` with filled `사용자 리뷰 요청` | Implementation is blocked on user input; ready for code-review to validate and create `USER_REVIEW.md` if justified |
 | `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill |
 | `complete.log` + `*.log` files | Task complete (PASS or user-review-resolved PASS), before final task-directory archive move |
 | `USER_REVIEW.md` + `*.log` files | Automatic loop stopped; user decision is required before creating another plan |
@@ -206,8 +210,9 @@ Header line must be exactly:
 Required sections:
 
 - Title.
-- `이 파일을 읽는 구현 에이전트에게`: warn that filling implementation-owned `CODE_REVIEW-*-G??.md` sections is mandatory. Tell the implementer to run verification, fill actual notes/output, keep active files in place, and report ready for review; finalization is code-review-skill only.
+- `이 파일을 읽는 구현 에이전트에게`: warn that filling implementation-owned `CODE_REVIEW-*-G??.md` sections is mandatory. Tell the implementer to run verification, fill actual notes/output, keep active files in place, and report ready for review; finalization is code-review-skill only. Also state that if implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, the implementer must fill the review stub's `사용자 리뷰 요청` section with exact evidence and stop for code-review; the implementer does not create `USER_REVIEW.md`, archive logs, or write `complete.log`.
 - `배경`: 2-4 sentences explaining why the work is needed.
+- `사용자 리뷰 요청 흐름`: state that implementation-time blockers are recorded in the active review stub's `사용자 리뷰 요청` section, copied from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; code-review owns validation and the actual `USER_REVIEW.md` file write.
 - `분석 결과`: record the findings from Step 2 and Step 3. This section is the written output of the analysis — not a summary, but the actual findings that justify the plan's scope and decisions. Must include all of the following subsections:
   - `읽은 파일`: list every source and test file read during analysis, with path.
   - `테스트 커버리지 공백`: list each behavior change and whether existing tests cover it; explicitly note gaps.
@@ -266,6 +271,7 @@ Verification fidelity rules:
 ## Step 6 - Write Review Stub
 
 Use the template below exactly. Fill `{…}` placeholders from the plan; everything else is fixed and must not be changed by the implementing agent.
+Copy `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` into the review stub's `사용자 리뷰 요청` section.
 
 ```markdown
 <!-- task={task_name} plan={N} tag={TAG} -->
@@ -276,6 +282,7 @@ Use the template below exactly. Fill `{…}` placeholders from the plan; everyth
 > The task is NOT complete until every implementation-owned section below is filled in.
 > Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
 > Fill implementation-owned sections, then stop with active files in place and report ready for review.
+> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
 > Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
 > Follow the ownership table at the bottom of this file for which sections you own.
 
@@ -335,6 +342,17 @@ _구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께
 
 _구현 에이전트가 주요 설계 결정 사항을 기록한다._
 
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 재개 조건: 없음
+
 ## 리뷰어를 위한 체크포인트
 
 {pre-filled from plan — one bullet per review focus area}
@@ -347,6 +365,7 @@ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후
 - 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
 - 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
 - `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
+- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
 
 ### {TAG}-1 중간 검증
 ```
@@ -376,6 +395,7 @@ Sections and their ownership:
 | 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only; final checkbox is mandatory before saving |
 | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
 | 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
+| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required to proceed; when filled, include exact decision, evidence, commands/output, and resume condition |
 | 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
 | 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry |
 | 코드리뷰 결과 | Review agent appends | Not included in stub |
@@ -400,5 +420,7 @@ Sections and their ownership:
 - 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 plan's implementer instructions and review stub both explain the implementation-time `사용자 리뷰 요청` stop path.
+- The review stub includes the `사용자 리뷰 요청` section from `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`.
 - The review stub has a clearly marked `코드리뷰 전용 체크리스트` owned only by the review agent.
 - Routed review file completion table lists every plan item.