toki/nexo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexo/agent-ops/skills/common/code-review/SKILL.md

37 KiB
Raw Blame History

name description
code-review 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 must invoke the plan skill, which reruns finalize-task-routing before writing the next pair, unless the user-review gate requires USER_REVIEW.md.

Code Review

Purpose

Review the implementation phase of the plan-code-review loop:

plan skill -> finalize-task-routing -> implementation -> code-review skill
     ^                                                     |
     +----- WARN/FAIL: invoke plan skill with raw findings -+

Implementation may stop early by filling the active review stub's 사용자 리뷰 요청 section from agent-ops/skills/common/_templates/implementation-user-review-request-section.md. This is the only implementation-time decision-stop path, and it is valid only for a selected Milestone 구현 잠금 > 결정 필요 item. Implementation must not ask the user directly, present choices in chat, or call a user-input tool such as request_user_input. 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, prepare the required next state, archive the active review and plan files, then materialize exactly one next state; for USER_REVIEW.md completion, update the stop state, write complete.log, and archive the task.
  • 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 invokes agent-ops/skills/common/plan/SKILL.md, which must run finalize-task-routing before writing the next active pair; 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. The user-review gate triggers only when the request is tied to a concrete selected Milestone 구현 잠금 > 결정 필요 item. If it is vague, unsupported, repo-fixable, about external environment/secret/service setup, a generic scope conflict, loop exhaustion, or only missing evidence that a follow-up agent can produce by rerunning commands or collecting artifacts, invoke the plan skill for a normal WARN/FAIL follow-up instead.
  • Do not replace USER_REVIEW.md with an inline user question. When the user-review gate triggers, write the file-based stop state and report its path.
  • Do not ask for confirmation before WARN/FAIL follow-up files. If the user-review gate triggers, write USER_REVIEW.md; otherwise invoke the plan skill with the current raw findings and let it write the smallest concrete follow-up after fresh routing.
  • Recovery: if a prior turn appended a verdict without archive or next-state files, do not append another verdict; resume Step 5 preparation/archive from that verdict. If exactly one member of the pair was archived after both archive destinations had been preflighted, verify the archived member and remaining source/destination, finish that archive, then use the post-archive recovery below. If both logs exist with a verdict but the required next state is absent, reconstruct it from those exact logs: PASS resumes complete.log; WARN/FAIL reruns the plan skill in write mode with raw archived findings and isolated-reassessment; a valid user-review gate rerenders USER_REVIEW.md. If a prior turn resolved USER_REVIEW.md without complete.log, resume at the matching finalization step.

User Review Gate

USER_REVIEW.md is a loop stop state only for selected Milestone lock decisions. Default to a normal WARN/FAIL follow-up; the gate requires positive evidence that the blocker is already represented, or must be represented, as a Milestone 구현 잠금 > 결정 필요 item.

  • Compute review-number as count(agent-task/{task_name}/code_review_*.log) + 1 before archiving the active review.
  • Repeated WARN/FAIL, loop exhaustion, missing verification evidence, and test environment blockers do not trigger USER_REVIEW.md by themselves. Invoke the plan skill for a narrower follow-up or report the non-roadmap blocker as verification evidence that remains unresolved.
  • If the active review file has a filled 사용자 리뷰 요청 with 상태 other than 없음, validate that 사유 유형 is milestone-lock, that 연결 대상 points to the selected Milestone, and that the requested decision matches a Milestone 구현 잠금 > 결정 필요 item.
  • If the filled request is about external environment/secret/service setup, unsupported device, generic scope conflict, agent execution limits, missing handoff evidence, incomplete verification records, or anything not tied to the Milestone lock, do not write USER_REVIEW.md; archive the review and invoke the plan skill for a normal WARN/FAIL follow-up when implementation can continue, or report the blocker without asking the user.
  • 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, connection target, and the exact Milestone decision item.

User Review Resolution

When an active USER_REVIEW.md exists and the linked Milestone decision closes the task as complete/PASS, finalization is still owned by this skill.

  • Read USER_REVIEW.md, archived plan_*.log, and archived code_review_*.log in that task directory.
  • Verify the linked decision and any follow-up evidence are sufficient to close the task. If a new implementation plan is needed instead, do not close; route back to the plan skill, which archives USER_REVIEW.md to user_review_N.log before writing a new plan.
  • Update USER_REVIEW.md in place to show a resolved state, final verdict, loop history, fulfilled decision items, and the evidence that closed the stop state.
  • Write complete.log from agent-ops/skills/common/code-review/templates/complete-log-template.md before moving or archiving the task directory. Include both the original archived review verdict and the user-review resolution line in 루프 이력.
  • Then apply the same task-directory archive move and m-<milestone-slug> PASS completion metadata rules as a normal PASS.
  • Do not leave an active task directory that contains USER_REVIEW.md and *.log files but no complete.log after the linked Milestone decision resolves the task as complete/PASS.

Workflow Contract

Active work must live under an active task directory using routed filenames. This is the state protocol shared with the plan skill.

Task path terms:

  • {task_group} is the top-level work category under agent-task/. Normal task groups use a short snake_case name such as refactoring.
  • Milestone-linked work uses the reserved task group form m-<milestone-slug>, where <milestone-slug> is the active Milestone filename without .md.
  • {subtask_dir} is used only for split work and follows the indexed directory naming contract, such as 01_core or 02+01_db.
  • {subtask_name} is the short snake_case name after the index or dependency prefix inside {subtask_dir}.
  • {task_name} in headers and templates means the active task path relative to agent-task/: either {task_group} for a single-plan task or {task_group}/{subtask_dir} for a split subtask.
  • A single-plan task stores active files directly under agent-task/{task_group}/.
  • Split work stores active files under agent-task/{task_group}/{subtask_dir}/; the parent agent-task/{task_group}/ is only the grouping folder and must not contain active plan/review files.

Filename rules:

  • Plan file: PLAN-{build_lane}-GNN.md
  • Review file: CODE_REVIEW-{review_lane}-GNN.md
  • {lane} is only local or cloud; never put model names in filenames.
  • GNN is a two-digit capability grade from G01 to G10; runtime maps lane+grade to current models externally.
  • This skill reads the active routed names but does not choose follow-up lane/G. Follow-up basenames come only from plan executing finalize-task-routing.

Multi-plan runtime contract:

  • Multi-plan work is represented as multiple subtask directories under one shared {task_group}. Each subtask directory owns exactly one normal active plan file and one normal active review file.
  • Multi-plan subtask directory names encode runtime scheduling metadata:
    • NN_{subtask_name} has no runtime dependencies.
    • NN+PP[,QQ...]_{subtask_name} depends on the listed earlier task indices.
  • Subtask directory names are the runtime dependency source of truth. Preserve them verbatim; do not normalize, reinterpret, infer extra dependencies from numeric order, or choose execution order by agent judgment.
  • If the user/runtime names a task group, task path, or subtask directory that identifies exactly one active review file, review that directory even when other active review files exist.

Milestone task group contract:

  • agent-task/m-<milestone-slug>/ is reserved for Milestone-linked work created by the plan skill.
  • Do not treat normal task groups that do not start with m- as runtime milestone completion targets.
  • For a selected task path, parse only the first path segment as {task_group}. If it matches ^m-[a-z0-9][a-z0-9-]*$, strip m- to get <milestone-slug>.
  • Do not modify agent-roadmap/** for milestone routing during code-review finalization. Read only the Milestone path from Roadmap Targets and its SDD path when needed to verify SDD Evidence Map.
  • Do not call update-roadmap from this skill. The runtime consumes the PASS completion event, checks current state, resolves the active Milestone, and calls update-roadmap if needed.
  • For m-<milestone-slug> PASS tasks, report the original active task path, final archive path, complete log path, task group, and milestone slug so the runtime has deterministic event inputs.

Follow-up routing boundary:

  • This skill records current source, actual verification output, and findings, but it must not estimate or recommend the next lane/G.
  • On WARN/FAIL, invoke the plan skill in prepare-follow-up mode with the selected task path and raw current evidence before archiving the current pair.
  • Do not pass the archived lane, grade, routing score, rationale, or filename as plan-routing input. Archive paths remain evidence pointers, and actual logs/findings remain raw evidence.
  • The plan skill must complete its full analysis and mandatory finalize-task-routing step before it writes the next pair. Code-review must not create a routed follow-up pair directly.
  • Repair non-behavioral review artifact drift during review instead of failing solely for it when implementation correctness, tests, and contracts remain judgeable.

Directory states:

State Meaning
PLAN-*-G??.md + unfilled CODE_REVIEW-*-G??.md stub/placeholders Implementation is not judgeable; review should fail completeness if invoked
PLAN-*-G??.md + CODE_REVIEW-*-G??.md with filled 사용자 리뷰 요청 Implementation claims a selected Milestone lock decision blocker; review validates the request and writes USER_REVIEW.md only if justified
PLAN-*-G??.md + filled CODE_REVIEW-*-G??.md without verdict Ready for code-review skill
PLAN-*-G??.md + CODE_REVIEW-*-G??.md with appended verdict Review finalization pending; do not append another verdict, resume Step 5 preparation/archive
Exactly one active pair member + its newly archived counterpart Partial archive after a preflighted finalization; verify both identities, finish the remaining archive, then resume post-archive recovery
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; linked Milestone lock decision must be resolved before creating another plan
agent-task/archive/YYYY/MM/{task_name}/complete.log + *.log files Archived completed task path (PASS or user-review-resolved PASS); not active
Only *.log files (no complete.log) If the newest review log has a verdict and its required next state is absent, post-archive finalization is pending; otherwise the task is terminated mid-loop or abandoned

The implementing agent never archives or deletes active files; archiving is this skill's responsibility.

Step 1 - Find Active Task

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

Classify the combined set of active CODE_REVIEW-*-G??.md and USER_REVIEW.md paths. Apply the first matching row:

Result Action
Exactly one active path and it is CODE_REVIEW-*-G??.md Review that task; exactly one PLAN-*-G??.md is normally expected beside it. If the review already has a verdict and its exact plan counterpart was just archived, use partial-archive recovery instead of reporting a missing plan.
Exactly one active path and it is USER_REVIEW.md, with a linked Milestone completion/resolution decision Perform User Review Resolution for that task.
One or more active paths and every active path is USER_REVIEW.md, with no completion/resolution decision Report that the linked Milestone decision is required and list the paths.
No active paths Apply the finalization-recovery scan below; stop only when it finds no recoverable task.
Multiple active paths If the user/runtime named a task group, task path, or subtask directory that identifies exactly one active path, use that directory. Otherwise list paths and stop with an ambiguity report; do not choose by agent judgment and do not create a user-review request for routing ambiguity.

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.

Finalization-recovery scan, excluding agent-task/archive/**:

  • Candidate A has exactly one active plan, no active review/USER_REVIEW/complete.log, and a newest review log whose verdict belongs to that plan's current loop.
  • Candidate B has no active plan/review/USER_REVIEW/complete.log, and its newest plan/review logs form one loop whose review verdict requires a missing next state.
  • Accept only candidates whose exact source/archive identities and verdict can be proven from headers, log suffixes, and review contents. Do not treat a generic log-only abandoned directory as recoverable.
  • If the user/runtime names one candidate task path, resume it. Otherwise resume only when exactly one candidate exists; list multiple candidates as ambiguity. Use the Core Loop Rules recovery path and never append a second verdict.

Step 2 - Load Context

Count agent-task/{task_name}/code_review_*.log in the selected active task directory:

  • 0: first review. Read the active review file, active plan file, every planned source file, related tests, and files importing/imported by changed files up to 2 levels deep.
  • >=1: follow-up review. Start with git diff, git diff --cached, and git log --oneline -5, then expand to related callers, implementers, tests, and any planned files missing from the diff.

The diff is the starting point, not the boundary. Follow behavior and API connections far enough to judge correctness.

If the active plan or review file contains Agent UI Completion, also read agent-ops/rules/common/rules-agent-ui.md and the listed active agent-ui documents. Do not read agent-ui/definition/archive/** or agent-ui/archive/user-review/** unless the review explicitly cites those archive paths.

Step 3 - Pre-Review Checklist

Before writing the verdict:

  • Compare actual source files against every planned checklist item.
  • Compare the plan 구현 체크리스트 and review stub 구현 체크리스트; repair non-behavioral drift when implementation remains judgeable.
  • When the active artifacts have Roadmap Targets, check whether the referenced Milestone has SDD: 필요. When it does, read only that Milestone and its SDD, compare implementation evidence against the SDD Acceptance Scenarios/Evidence Map for the targeted task ids, and fail completeness or verification trust when evidence is insufficient. Do not require a separate SDD target section.
  • Directly repair obvious non-behavioral source nits when safe: typos, stale comments, docs, or formatting only, with no behavior/test/API contract change.
  • 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; repair clear artifact drift when evidence supports completion.
  • If the active plan or review file contains Agent UI Completion, verify the implementation-owned fields are filled before PASS: listed agent-ui docs exist, actual code evidence paths exist, requested status updates are explicit, and implementation verification evidence is present. Missing or untrusted evidence is a completeness or verification-trust issue.
  • Treat review artifact gaps as failures only when they prevent judging implementation correctness, tests, contracts, or verification trust.
  • Read the 사용자 리뷰 요청 section. If 상태 is not 없음, validate the exact decision needed, 연결 대상, blocker evidence, command output or not-run reason, why automatic follow-up cannot resolve it, and resume condition before deciding whether the user-review gate triggers. Reject the request unless it is tied to a selected Milestone 구현 잠금 > 결정 필요 item.
  • 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.
  • For follow-up reviews, compare diff against the plan and scan for unplanned changes, debug prints, dead code, TODOs, formatting-only noise, and unrelated edits.

Step 4 - Append Verdict

Append 코드리뷰 결과 to the active CODE_REVIEW-*-G??.md.

Before appending PASS, if all other PASS conditions are met and the active review file contains Agent UI Completion, perform the review-pass status update first: update the listed agent-ui docs to 구현됨, add actual code evidence, run validate-agent-ui, and mark the section's review-agent-owned finalization items. If this update or validation fails, do not append PASS; classify the failure as WARN or FAIL and write the normal follow-up.

Required fields:

  • 종합 판정: exactly PASS, WARN, or FAIL.
  • 차원별 평가: Pass/Warn/Fail for correctness, completeness, test coverage, API contract, code quality, implementation deviation, verification trust. If SDD Evidence Map applies through Roadmap Targets, also include spec conformance.
  • 발견된 문제: 없음, or bullets using Required, Suggested, or Nit with file:line and a concrete fix.
  • 다음 단계: 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.

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, unless the user-review gate triggers
FAIL One or more Required issues. Yes, unless the user-review gate triggers

Issue severity:

  • Required: correctness, API contract, missing required test, missing integrated verification, plan-completeness issue, or review artifact gaps that prevent judging implementation quality.
  • Suggested: useful improvement that should enter the loop but does not block correctness.
  • Nit: tiny cleanup; directly repair obvious non-behavioral cases when safe, otherwise record without forcing WARN.

Verdict consistency:

  • PASS requires all dimensions to be Pass and no Required/Suggested issues. Nit-only findings may still PASS only when every dimension remains Pass.
  • Any Fail dimension or any Required issue forces FAIL.
  • Any Warn dimension or any Suggested issue forces WARN, unless the only findings are explicitly Nit and every dimension remains Pass.

Step 5 - Prepare Next State And Archive Active Files

Do not archive WARN/FAIL files until the next-state content is fully prepared in memory.

  • PASS: no routed follow-up preparation is required.
  • WARN/FAIL: apply the user-review gate before any rename.
    • If the gate triggers, render the complete USER_REVIEW.md body from agent-ops/skills/common/code-review/templates/user-review-template.md in memory.
    • Otherwise build the follow-up handoff described below and fully execute agent-ops/skills/common/plan/SKILL.md in prepare-follow-up mode.

Before preparing a follow-up, count the existing logs and parse each current active basename. Set current_review_archive_number=count(code_review_*.log) and current_plan_archive_number=count(plan_*.log). Derive current_review_archive_name and current_plan_archive_name from the current active files' own lane/grade plus those numbers. These names describe the pair being closed, not the next route.

The follow-up handoff contains the selected {task_name}, current verdict, Required/Suggested/Nit findings, affected files, actual verification output, current ownership/dependency facts, roadmap carryover, REVIEW_<PARENT_TAG>, and those predicted current-pair archive names. Keep current active paths only as evidence pointers. Do not add the prior lane, grade, routing score, rationale, or a preferred next route to the neutral routing snapshot, and require plan to omit route-bearing basenames from the isolated routing input. The plan may use current archive names only after routing to render Archive Evidence Snapshot.

  • prepare-follow-up must return status: routed, the exact routed basenames, prepared_plan, prepared_review, plan_number, current_plan_archive_name, current_plan_archive_number, current_review_archive_name, current_review_archive_number, plan_log_number, review_log_number, and gitignore_repair_needed. It must have executed finalize-task-routing in isolated-reassessment mode.
  • Verify that the returned current archive names/numbers equal the values derived before preparation, and that plan_log_number / review_log_number are the post-archive counts embedded in the new review stub for its future archive.
  • If preparation returns needs_evidence, continue evidence collection and rerun it before archiving.
  • If preparation returns blocked, leave the verdict-appended active PLAN/CODE_REVIEW pair in place, do not check archive/next-state items, and report a resumable finalization blocker. A later code-review invocation resumes this step without appending another verdict.

After the required next state is prepared, archive is mandatory for PASS, WARN, and FAIL. Ensure .gitignore has the Agent-Ops managed gitignore block for task artifacts before writing *.log outputs. Prefer source agent-ops/bin/ai-ignore.sh && agent_ops_ensure_gitignore_task_artifact_block .gitignore; if the helper is unavailable, add or update a block containing !agent-task/, !agent-task/**/, !agent-task/**/*.md, !agent-task/**/*.log, and agent-roadmap/current.md. Apply the repair here when prepare-follow-up returned gitignore_repair_needed: true.

Preflight both archive operations before either rename:

  1. Recount existing code_review_*.log as current_review_archive_number. Parse the active review's lane/grade from its own basename and derive current_review_archive_name=code_review_{current_review_lane}_{current_review_grade}_{current_review_archive_number}.log.
  2. Recount existing plan_*.log as current_plan_archive_number. Parse the active plan's lane/grade from its own basename and derive current_plan_archive_name=plan_{current_build_lane}_{current_build_grade}_{current_plan_archive_number}.log.
  3. Require both destinations not to exist. When the active stub contains concrete expected archive names, require them to match the derived names; legacy generic placeholders do not override the derived values.
  4. For WARN/FAIL, require exact matches with both prepared current archive names/numbers. If any check fails, do not rename either file.

After both operations pass preflight, rename the active review and then the active plan to those exact names. If either current archive count or derived name changed after preparation, discard the prepared pair and rerun plan prepare-follow-up before renaming. After archiving, verify that the actual plan/review log counts equal the prepared plan_log_number and review_log_number; neither active .md file remains until Step 6 materializes the prepared next state.

Step 6 - Post-Review Actions

For PASS, write agent-task/{task_name}/complete.log before reporting. If a USER_REVIEW.md stop is resolved as complete/PASS, write the same complete.log before archiving that task.

Complete log template:

  • Template path: agent-ops/skills/common/code-review/templates/complete-log-template.md
  • Copy the template's section order and fill every placeholder from the archived plan/review logs and final verdict.
  • Do not leave placeholders in complete.log.
  • If the task did not close through USER_REVIEW.md, remove the optional user-review row from the 루프 이력 table.
  • If the archived plan or review log contains Roadmap Targets, copy it into complete.log as Roadmap Completion. Include the Milestone path, completed Task ids, archived plan/review log paths, and verification evidence. If there is no Roadmap Targets section, remove the optional Roadmap Completion template section entirely and do not invent roadmap targets.
  • If the archived review log contains Agent UI Completion, copy the completed evidence into complete.log. If there is no Agent UI Completion section, remove the optional complete-log section entirely.
  • 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, materialize the next state prepared in Step 5 immediately after archive:

  • If the user-review gate triggered, write the prepared body to agent-task/{task_name}/USER_REVIEW.md. It must use only milestone-lock, contain every archived loop entry plus the exact linked decision, and contain no placeholder. Do not write active PLAN/CODE_REVIEW files or complete.log.
  • Otherwise write prepared_plan and prepared_review byte-for-byte to their routed basenames. Do not rerun, adjust, compare, or upgrade their lane/G after archive.
  • Verify the written follow-up pair contains the predicted archived plan/review paths in identical Archive Evidence Snapshot sections and contains no unresolved token from the review-stub template inventory. Unrelated braces in commands or code are allowed.
  • A prior local failure never changes the prepared pair into an automatic cloud upgrade.

If the task group is m-<milestone-slug> and the user-review gate triggered, report that the milestone task is blocked on user review; do not emit PASS completion metadata and do not call update-roadmap.

Step 7 - Complete Review-Only Checklist, Move PASS Task, And Report

After Step 6:

  • If verdict is PASS, determine archive month from the current completion date as YYYY/MM, create the needed archive parent directories, then move the selected active task directory agent-task/{task_name}/ to agent-task/archive/YYYY/MM/{task_name}/. For split work, the selected active task directory is the subtask directory, and the archive must preserve the task group path, e.g. agent-task/refactoring/01_core/ moves to agent-task/archive/YYYY/MM/refactoring/01_core/.
  • Do not overwrite an existing archive directory. If agent-task/archive/YYYY/MM/{task_name}/ already exists, append the next numeric suffix to the final path segment: single-plan agent-task/archive/YYYY/MM/{task_group}_1/, split-plan agent-task/archive/YYYY/MM/{task_group}/{subtask_dir}_1/, and so on.
  • After moving a split subtask, remove the active parent agent-task/{task_group}/ only if it is empty. If sibling subtask directories or other files remain, leave the parent task group in place.
  • 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, archived plan/review log paths, and roadmap-completion=<Task ids from complete.log or none>.
  • The runtime consumes that completion event, checks current state, and calls update-roadmap if needed. update-roadmap only checks Milestone Task ids when complete.log contains Roadmap Completion; if the section is absent, roadmap Task completion is a no-op even for m-* task groups.
  • If verdict is PASS and the archived review log contains Agent UI Completion, ensure the listed agent-ui status/evidence update and validate-agent-ui check are complete before writing or finalizing complete.log. Do not defer this to runtime or Milestone completion.
  • 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 linked Milestone lock decision is resolved.
  • If USER_REVIEW.md is later resolved as complete/PASS by linked Milestone decision and evidence, write complete.log, move the task directory to archive, and report m-* PASS completion metadata just like a normal PASS.
  • For PASS, open the moved agent-task/archive/YYYY/MM/{final_task_name}/{current_review_archive_name}, where {final_task_name} is the archived task path, including {task_group}/ for split work.
  • For user-review-resolved PASS, confirm the moved archive contains the resolved USER_REVIEW.md, complete.log, and the existing archived plan_*.log / code_review_*.log; do not recreate an active review file only to add a new checklist item.
  • For WARN or FAIL, open agent-task/{task_name}/{current_review_archive_name}.
  • Run git check-ignore -q -- on the generated task artifacts (plan_*.log, code_review_*.log, user_review_*.log when present, complete.log when present, and active follow-up .md files). If any are ignored, apply the Agent-Ops managed gitignore block and re-check before reporting.
  • 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, mandatory plan-skill follow-up, 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 or user-review-resolved PASS the final task archive move, for m-* PASS tasks the completion event metadata, and for unresolved USER_REVIEW the filled USER_REVIEW.md.

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

Dimension Check
Correctness Logic, edge cases, concurrency, errors
Completeness Planned implementation/verification items are done; review artifact drift is repaired when judgeable
Test coverage Required tests present and meaningful
API contract Call sites, compatibility, docs
Code quality No debug prints, dead code, leftover TODOs
Plan deviation Deviations justified, no unrelated risk
Verification trust Reported output matches actual code

Quality Rules

  • Lead with findings; use specific file:line.
  • Provide a concrete fix for every Required issue.
  • Name exact stale symbols or missing tests.
  • Do not write vague praise or style opinions without a rule.
  • Every dimension gets Pass/Warn/Fail.
  • For follow-up plans about verification trust, specify deterministic commands, for example rg --sort path, and forbid repo-local tool artifacts.

Final Checklist

  • {current_review_archive_name} exists with the verdict appended and was derived from the archived active review's own route.
  • {current_plan_archive_name} exists and was derived from the archived active plan's own route.
  • .gitignore unignores agent-task/**/*.md and agent-task/**/*.log and ignores local agent-roadmap/current.md; generated task artifacts are not ignored by git check-ignore.
  • No active .md files remain after PASS or user-review-resolved PASS.
  • PASS or user-review-resolved 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 with Roadmap Targets: complete.log contains Roadmap Completion with Milestone path, Task ids, archived plan/review evidence, and verification evidence.
  • PASS without Roadmap Targets: complete.log omits Roadmap Completion and reported metadata says roadmap-completion=none.
  • PASS with Agent UI Completion: listed agent-ui docs were updated to 구현됨 with code evidence, validate-agent-ui passed, and complete.log contains Agent UI Completion.
  • PASS without Agent UI Completion: complete.log omits Agent UI Completion.
  • 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: the plan skill was invoked for the exact task path, completed finalize-task-routing, and created new active PLAN-{build_lane}-GNN.md and CODE_REVIEW-{review_lane}-GNN.md files matching the fresh routed output; no complete.log.
  • WARN/FAIL follow-up: the plan input omitted prior lane/G assessment, and the new active plan/review stub contain identical Archive Evidence Snapshot sections with prior archived plan/review log paths, verdict, issue summary, affected files, verification evidence, and specific archive paths allowed for narrow reread when needed.
  • Follow-up review stubs include the 사용자 리뷰 요청 section from agent-ops/skills/common/_templates/implementation-user-review-request-section.md and forbid direct user prompts during implementation.
  • 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 linked Milestone 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.