From 209f674ec9cf698a517d73cf1394110a99026093 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 19 Jul 2026 19:56:37 +0900 Subject: [PATCH] sync: from iop v1.1.169 --- agent-ops/.version | 2 +- agent-ops/skills/common/code-review/SKILL.md | 297 ++++-------------- .../common/code-review/agents/openai.yaml | 2 +- .../common/finalize-task-routing/SKILL.md | 180 +++++++++++ .../finalize-task-routing/agents/openai.yaml | 4 + .../scripts/finalize-task-route.sh | 58 ++++ agent-ops/skills/common/plan/SKILL.md | 256 ++++----------- .../skills/common/plan/agents/openai.yaml | 2 +- .../plan/templates/review-stub-template.md | 106 +++++++ agent-ops/skills/common/router.md | 7 + 10 files changed, 487 insertions(+), 427 deletions(-) create mode 100644 agent-ops/skills/common/finalize-task-routing/SKILL.md create mode 100644 agent-ops/skills/common/finalize-task-routing/agents/openai.yaml create mode 100755 agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh create mode 100644 agent-ops/skills/common/plan/templates/review-stub-template.md diff --git a/agent-ops/.version b/agent-ops/.version index 64440a3..3e8f33b 100644 --- a/agent-ops/.version +++ b/agent-ops/.version @@ -1 +1 @@ -1.1.168 +1.1.169 diff --git a/agent-ops/skills/common/code-review/SKILL.md b/agent-ops/skills/common/code-review/SKILL.md index e0f3178..49b4e43 100644 --- a/agent-ops/skills/common/code-review/SKILL.md +++ b/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, 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. +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 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 @@ -10,9 +10,9 @@ description: Use for active task review requests such as 리뷰 진행해, 리 Review the implementation phase of the plan-code-review loop: ```text -plan skill -> implementation -> code-review skill - ^ | - +----- issues found: new routed plan/review files +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`. @@ -20,21 +20,21 @@ Implementation may stop early by filling the active review stub's `사용자 리 ## 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-`, 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. 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, write a normal WARN/FAIL follow-up plan instead. +- 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-`, 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, if details are uncertain, 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. +- 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. Write a narrower follow-up plan or report the non-roadmap blocker as verification evidence that remains unresolved. +- 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 write a normal WARN/FAIL follow-up plan when implementation can continue, or report the blocker without asking the user. +- 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 @@ -68,6 +68,7 @@ Filename rules: - 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: @@ -87,16 +88,13 @@ Milestone task group contract: - 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-` 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. -Review routing rules: +Follow-up routing boundary: -- Prefer `local` whenever the scope is bounded and verifiable; high local usage is fine. Do not choose `cloud` just to balance lane usage. -- `local` is for bounded, explicit, locally verifiable review: required behavior is explicit in the plan or existing pattern; relevant context fits in edited files plus nearby types/helpers, direct call sites, and existing or planned targeted tests/fixtures; correctness can be checked by code inspection plus type/build/unit tests or deterministic commands; no open-ended product/design judgment, live external provider/runtime semantics, broad cross-domain context, or evidence-trust diagnosis is decisive. -- `cloud` is required when any local condition is false, including when correctness depends on behavior promised outside the bounded context, wider context, or evidence-trust diagnosis. Repeated Required issues are evidence only when they show a local condition is false. -- `local-G01` through `local-G10` and `cloud-G01` through `cloud-G10` are valid. Lane is capability fit; grade is complexity within the chosen lane. Do not raise `local-GNN` to compensate for missing judgment, missing context, weak verification, or a previous loop failure. +- 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. -- `cloud-G07` or higher is mandatory only when terminal-agent or external interactive behavior is central and cannot be made deterministic for local review, or when the review requires more source/test/diff/log context than local can hold without omitting material evidence: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, terminal benchmark-style tasks, real bin/smoke/integration failures after unit tests passed, TUI/PTY/browser/screen repaint/cursor stream behavior, rerun-mismatched verification trust failures, or very large cross-module/cross-domain changes that cannot be safely split for review. -- On WARN/FAIL follow-up with 5+ `Required` findings, reassess lane/grade and default to `cloud-G07` or higher unless all findings are one narrow mechanical fix pattern; if keeping `local`, record why local conditions still hold. -- Previous loop lane does not matter. Recompute lane from the current review or follow-up scope using these rules. Directory states: @@ -104,11 +102,13 @@ Directory states: |-------|---------| | `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` | Ready for code-review skill | +| `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`) | Task terminated mid-loop or abandoned | +| 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. @@ -128,14 +128,21 @@ Classify the combined set of active `CODE_REVIEW-*-G??.md` and `USER_REVIEW.md` | Result | Action | |--------|--------| -| Exactly one active path and it is `CODE_REVIEW-*-G??.md` | Review that task; exactly one `PLAN-*-G??.md` is expected beside it. | +| 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 | Stop and report that no active review exists. | +| 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: @@ -200,16 +207,34 @@ Verdict consistency: - 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 - Archive Active Files +## Step 5 - Prepare Next State And Archive Active Files -Archive is mandatory for `PASS`, `WARN`, and `FAIL`. Before the archive order, 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`. +Do not archive WARN/FAIL files until the next-state content is fully prepared in memory. -Archive order is fixed: +- `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. -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`. +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. -After archiving, neither active `.md` file remains unless Step 6 writes a follow-up plan/review or `USER_REVIEW.md`. +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_`, 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 @@ -226,202 +251,14 @@ 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`, apply the user-review gate before writing follow-up files. +For `WARN` or `FAIL`, materialize the next state prepared in Step 5 immediately after archive: -If the user-review gate triggers: +- 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. -- Write `agent-task/{task_name}/USER_REVIEW.md` from `agent-ops/skills/common/code-review/templates/user-review-template.md`. -- Fill every placeholder. Use only `milestone-lock` 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 linked Milestone 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-`, 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_`. -- If the selected task group is `m-`, write the follow-up plan/review under the same `m-` task group. -- Base the follow-up scope directly on the archived review findings. Keep it narrow and actionable. -- Choose lane/grade again from the current follow-up scope using Review routing rules. Ignore the prior lane and do not increment GNN solely because the previous loop failed. -- If the finding is only missing or untrusted verification evidence that an appropriate follow-up lane can produce by rerunning commands or collecting artifacts, do not write `USER_REVIEW.md` solely for that reason. Write a follow-up plan that reruns the exact commands in an appropriate lane and records actual stdout/stderr. -- If follow-up verification involves mobile/UI hangs, timeouts, or no progress for 2 minutes, stop blind retries; require focused rerun output plus screenshot/window/UI-tree evidence path, or the exact reason capture is impossible. -- Write an `Archive Evidence Snapshot` section in every WARN/FAIL follow-up plan. Copy enough prior-loop evidence from the archived plan/review logs for the next implementer to act without rereading archive by default: current archived plan/review log paths, verdict, Required/Suggested/Nit summary, affected files, verification evidence, and any roadmap carryover. If exact prior context is still required, cite the specific archive file paths allowed to read; do not instruct the implementer to search `agent-task/archive/**` broadly. -- Copy the follow-up plan's `Archive Evidence Snapshot` section exactly into the follow-up review stub. -- If the archived plan or review had `Agent UI Completion` and the follow-up still works toward the same agent-ui status update, include an updated `Agent UI Completion` section in the follow-up plan and review stub. If the follow-up intentionally no longer claims agent-ui status completion, omit the section and explain why in the follow-up plan `범위 결정 근거`. -- Before choosing the follow-up route, apply this gate: - - Keep the follow-up on `local` when all local allowlist conditions are true for the current fix; otherwise use `cloud`. - - If the follow-up work is terminal-agent work that cannot be reduced to deterministic commands and evidence, use `cloud-G07` or higher. - - If unit tests passed but a real bin/smoke/integration command failed and local follow-up cannot isolate the failure with deterministic evidence, use `cloud-G07` or higher. - - If the task depends on interactive TUI/PTY/browser/external CLI behavior, screen repaint/cursor stream parsing, or live command-palette state that cannot be captured deterministically, use `cloud-G07` or higher. - - If the follow-up requires more source/test/diff/log context than local can hold without dropping material evidence, or the failure spans broad cross-module/cross-domain context that cannot be safely split, use `cloud-G07` or higher. - - If verification evidence is missing, reconstructed, stale, untrusted, or mismatched on rerun, use a local follow-up only when exact commands and actual stdout/stderr capture are enough; use `cloud-G07` or higher when evidence trust recovery needs stronger diagnosis. -- `FAIL`: one plan item per Required issue. -- `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 forbid direct user prompts and 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. -- If the archived plan had `Roadmap Targets` and the follow-up still works toward the same Milestone Task completion, copy that section into the follow-up plan and review stub. If the follow-up intentionally no longer claims roadmap Task completion, omit the section and explain why in the follow-up plan `범위 결정 근거`. - -Routed review stub template (fill `{…}` placeholders; everything else is fixed and must not be changed by the implementing agent): - -```markdown - - -# Code Review Reference - {TAG} - -> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** -> 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 selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service setup, generic scope conflicts, loop exhaustion, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves. -> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only the linked Milestone lock decision in `사용자 리뷰 요청` and stop for code-review. -> 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. - -## 개요 - -date={YYYY-MM-DD} -task={task_name}, plan={N}, tag={TAG} - -{copy the follow-up plan's Roadmap Targets section exactly if present; omit this block if the follow-up plan has no Roadmap Targets} -{copy the follow-up plan's Archive Evidence Snapshot section exactly if present; omit this block if the follow-up plan has no Archive Evidence Snapshot} - -## 이 파일을 읽는 리뷰 에이전트에게 - -> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. - -각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. -리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. - -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이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다. -4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. -5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. - ---- - -## 구현 항목별 완료 여부 - -| 항목 | 완료 여부 | -|------|---------| -| [{TAG}-1] {item description} | [ ] | -| [{TAG}-2] {item description} | [ ] | - -## 구현 체크리스트 - -{copy the follow-up plan's 구현 체크리스트 items exactly, preserving order and checkbox text} - -## Agent UI Completion - -> Include this section only when the follow-up plan has `Agent UI Completion`; otherwise omit it entirely. -> **[IMPLEMENTING AGENT]** Fill actual code evidence and implementation verification output for the listed docs. -> **[REVIEW AGENT ONLY]** On PASS, update only the listed agent-ui docs to `구현됨`, add the listed code evidence, run `validate-agent-ui`, and copy this section into `complete.log`. - -- Mode: review-pass-status-update -- Agent UI docs: - - `agent-ui/definition/views//index.md` -- Actual code evidence: - - [ ] ``: -- Implementation verification evidence: - - [ ] ``: -- Status updates requested on PASS: - - [ ] `agent-ui/definition/views//index.md`: `계획` -> `구현됨` -- Review finalization: - - [ ] Review agent updated the listed agent-ui docs and code evidence. - - [ ] Review agent ran `validate-agent-ui scope=` after the status/evidence update. - -## 코드리뷰 전용 체크리스트 - -> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. -> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. - -- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. -- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. -- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. -- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. -- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. -- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. -- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. -- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. -- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. -- [ ] 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`를 남기지 않는다. -- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. - -## 계획 대비 변경 사항 - -_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ - -## 주요 설계 결정 - -_구현 에이전트가 주요 설계 결정 사항을 기록한다._ - -## 사용자 리뷰 요청 - -_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._ - -- 상태: 없음 -- 사유 유형: 없음 -- 연결 대상: 없음 -- 결정 필요: 없음 -- 차단 근거: 없음 -- 실행한 검증/명령: 없음 -- 자동 후속 불가 이유: 없음 -- 재개 조건: 없음 - -## 리뷰어를 위한 체크포인트 - -{pre-filled from plan — one bullet per review focus area} - -## 검증 결과 - -_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ - -필수 규칙: -- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. -- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. -- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. -- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. -- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다. - -### {TAG}-1 중간 검증 -``` -$ {verification command from plan} -(output) -``` - -### 최종 검증 -``` -$ {final verification command from plan} -(output) -``` - ---- - -> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** -> If anything is blank, go back and fill it in before saving this file. -> Leave review-agent-only sections unchanged. -``` - -Sections and their ownership: - -| 섹션 | 소유자 | 설명 | -|------|--------|------| -| 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하거나 실행하지 않음 | -| Roadmap Targets | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 수정하지 않음; PASS 시 code-review가 `complete.log`의 `Roadmap Completion`으로 복사 | -| Archive Evidence Snapshot | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트의 기본 이전 루프 컨텍스트; 추가 확인이 필요할 때 여기에 명시된 archive 파일만 좁게 읽음 | -| Agent UI Completion | Mixed | Present only for agent-ui code work that should become `구현됨` on code-review PASS; implementing agent fills actual evidence, review agent applies the status/evidence update and copies the section into `complete.log` | -| 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 | -| 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 | -| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section | -| 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 | -| 사용자 리뷰 요청 | 구현 에이전트가 채움 | 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채움; 구현 중 직접 질문은 금지; 환경/secret/서비스/검증 공백/일반 범위 조정은 사용자 리뷰 요청으로 쓰지 않음 | -| 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 | -| 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움; 명령 변경은 `계획 대비 변경 사항`에 기록 | -| 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 | +If the task group is `m-` 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 @@ -436,12 +273,12 @@ After Step 6: - `WARN` and `FAIL` do not update the roadmap Milestone; the follow-up plan remains under the same `m-` 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}/code_review_{review_lane}_GNN_N.log`, where `{final_task_name}` is the archived task path, including `{task_group}/` for split work. +- 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}/code_review_{review_lane}_GNN_N.log`. +- 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, follow-up plan/review write, or `USER_REVIEW.md` write first. +- 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`. @@ -470,8 +307,8 @@ Report Required/Suggested counts, archive names, the final task archive path for ## Final Checklist -- `code_review_{review_lane}_GNN_N.log` exists with verdict appended. -- `plan_{build_lane}_GNN_M.log` exists. +- `{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. @@ -481,8 +318,8 @@ Report Required/Suggested counts, archive names, the final task archive path for - 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: 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 follow-up: new active plan and 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. +- 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. diff --git a/agent-ops/skills/common/code-review/agents/openai.yaml b/agent-ops/skills/common/code-review/agents/openai.yaml index 0ef4d88..1ebc3a3 100644 --- a/agent-ops/skills/common/code-review/agents/openai.yaml +++ b/agent-ops/skills/common/code-review/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Code Review" short_description: "Review and route task loops" - default_prompt: "Use $code-review to review or resolve the active repository task, archive active files, and create complete.log, follow-up plan/review files, or USER_REVIEW.md." + default_prompt: "Use $code-review to review or resolve the active task, archive it, and on WARN/FAIL invoke $plan so $finalize-task-routing creates the next routed pair." diff --git a/agent-ops/skills/common/finalize-task-routing/SKILL.md b/agent-ops/skills/common/finalize-task-routing/SKILL.md new file mode 100644 index 0000000..b89b362 --- /dev/null +++ b/agent-ops/skills/common/finalize-task-routing/SKILL.md @@ -0,0 +1,180 @@ +--- +name: finalize-task-routing +description: PLAN/CODE_REVIEW 작성 직전 현재 작업 증거만으로 cloud/local lane과 G01-G10 등급을 독립 평가하고 canonical 파일명을 확정한다. 최초 plan, review 실패 후 follow-up plan, 라우팅 재평가, lane/G 판단, routed filename 결정에 사용한다. +--- + +# Finalize Task Routing + +## 목적 + +계획 분석이 끝난 뒤 구현과 리뷰 target의 lane과 G 등급을 처음부터 평가하고 canonical 파일명을 반환한다. +이 스킬은 라우팅 판단의 단일 원본이며 plan/review 내용을 작성하거나 task 파일을 직접 생성하지 않는다. + +## 언제 호출할지 + +- `plan`이 최초 PLAN/CODE_REVIEW pair를 쓰기 직전 +- `code-review`의 WARN/FAIL 후 `plan`이 follow-up PLAN/CODE_REVIEW pair를 다시 쓰기 직전 +- 기존 lane/G 판정이 검증 실패, 증거 충돌, 범위 변화, 소유권 변화로 무효화된 뒤 재평가할 때 +- 사용자가 현재 작업의 cloud/local, G 등급, canonical task 파일명만 요청할 때 + +## 입력 + +- `targets`: `build`, `review`, 또는 둘 다. `plan`은 항상 둘 다 전달한다 (필수) +- `evaluation_mode`: 이전 라우팅이 없는 최초 평가는 `first-pass`, 무효화된 기존 라우팅이 있는 평가는 `isolated-reassessment` (필수) +- `task_snapshot`: 사용자 요구, 현재 scope, 수정/영향 경로, 불변조건, 상태 전이, 검증 계획과 실제 증거 (필수) +- `context_snapshot`: 함께 유지해야 하는 source/test/diff/log/contract 범위와 분할 가능성 (필수) +- `ownership_snapshot`: 공유 상태, 병행 작업, sibling task, 외부 책임 경계 (필수) +- `decision_snapshot`: 미해결 의미 판단, 사용자 권한이 필요한 결정, 외부 환경 의존성 (필수) +- `invalidation_evidence`: 검증 실패, 실제 로그, review finding, 변경된 범위 등 현재 판정을 바꾸는 원시 증거 (선택) + +이전 `lane`, `grade`, 점수, 라우팅 사유, routed filename은 입력에서 제외한다. +이전 PLAN/CODE_REVIEW 문서의 코드 경로, 실제 로그, finding은 원본에서 재확인한 뒤 원시 증거로만 사용할 수 있다. + +## 먼저 확인할 것 + +- [ ] `agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh`가 실행 가능한가 +- [ ] 호출자가 plan 분석, scope, split, 검증 계획을 모두 확정했는가 +- [ ] `targets`마다 필요한 구현 또는 리뷰 작업이 구분되어 있는가 +- [ ] 이전 lane/G와 그 평가 문구가 입력에서 격리되었는가 +- [ ] `isolated-reassessment`이면 이전 평가를 보지 않은 새 평가 context/sub-invocation에 중립 snapshot만 전달했는가 +- [ ] 주장이나 요약이 아니라 현재 파일, diff, 명령 출력, 확정된 제약을 우선 증거로 사용했는가 + +## 실행 절차 + +1. **평가 상태 초기화** + - 호출할 때마다 각 target을 `unrouted`로 시작한다. + - `isolated-reassessment`는 이전 평가가 없는 새 context/sub-invocation에서 실행하고, 현재 원시 증거로 재구성한 중립 snapshot만 노출한다. + - 호출자가 격리 실행을 제공할 수 없으면 독립 재평가를 완료했다고 주장하지 말고 `status: blocked`, `blocked_reason: isolated-routing-unavailable`을 반환한다. + - 이전 lane/G를 승계하거나 하한으로 사용하지 않는다. + - 실패 횟수, Required 개수, 이전 G 등급만으로 cloud 또는 상위 G를 선택하지 않는다. + - 실패는 자동 승격 조건이 아니라 현재 증거에 추가되는 판정 무효화 사건으로만 취급한다. + - 새 결과가 확정되기 전에는 이전 평가와 비교하지 않는다. 필요하면 호출자가 routed 출력 이후에만 감사용 delta를 기록한다. + +2. **폐쇄성 평가** + - 각 target을 bounded local execution으로 완료·판정할 수 있는지를 기준으로 아래 값을 `true`, `false`, `unknown` 중 하나로 독립 판정하고 근거를 한 줄로 기록한다. + - `scope_closed`: 정확성 조건과 영향 경로가 확정된 범위 안에서 설명되는가 + - `context_closed`: 중요한 증거를 생략하지 않고 필요한 컨텍스트를 함께 다룰 수 있는가 + - `verification_closed`: 결정적인 명령과 관찰로 성공 여부를 증명할 수 있는가 + - `evidence_trusted`: 검증이 의도한 실제 경로를 실행하며 출력이 재현 가능하고 현재 상태와 일치하는가 + - `ownership_closed`: 공유 상태, 병행 작업, 외부 소유권이 판단을 모호하게 만들지 않는가 + - `decision_closed`: 사용자 권한이나 미해결 외부 의미 결정 없이 작업을 완료할 수 있는가 + - 동시성, dirty worktree, 외부 명령, 많은 finding은 그 자체로 lane을 결정하지 않는다. 위 폐쇄성에 미치는 영향만 평가한다. + +3. **판정 가능성 확인** + - 하나라도 `unknown`이면 `status: needs_evidence`와 필요한 증거를 반환한다. lane, grade, filename은 반환하지 않는다. + - 하나 이상의 값이 `false`이고 cloud의 더 넓은 컨텍스트나 진단도 그 폐쇄 실패를 해소할 수 없으면 `status: blocked`, 폐쇄 실패별 `blocked_reason`, 해제 조건을 반환한다. 사용자 권한, secret, 접근 권한, 제품 결정은 대표적인 예일 뿐이며 이에 한정하지 않는다. + - 호출자는 `needs_evidence`를 cloud로 해석하지 말고 증거를 보강한 뒤 이 스킬을 처음부터 다시 실행한다. + +4. **Lane 결정** + - 모든 폐쇄성이 `true`인 target만 `local`로 정한다. + - `unknown`이 없고 하나 이상의 폐쇄성이 `false`이며 cloud의 더 넓은 컨텍스트나 진단이 그 실패를 실제로 해소할 수 있을 때 `cloud`로 정한다. + - `false`를 cloud가 해소할 수 있는지 근거를 기록한다. 해소 가능성을 설명할 수 없으면 추측으로 cloud를 선택하지 않고 Step 3의 `blocked`를 반환한다. + - 실패 후에도 현재 폐쇄성이 모두 `true`이면 다시 `local`을 선택할 수 있다. + - lane은 capability fit이며 작업량이나 모델 사용량 균형을 위한 값이 아니다. + +5. **G 등급 재산정** + - lane을 정한 뒤에만 각 target을 아래 다섯 차원에서 `0`, `1`, `2`로 처음부터 채점한다. + - `scope_coupling`: `0` 단일 국소 변경 / `1` 여러 연결 지점 / `2` 다중 모듈·계약 + - `state_concurrency`: `0` 무상태 / `1` 상태 전이 / `2` 공유 상태·순서·동시성 + - `blast_irreversibility`: `0` 내부 가역 / `1` 다중 호출자·설정·지속 상태 / `2` 외부 계약·권한·비가역 영향 + - `evidence_diagnosis`: `0` 직접 증거 / `1` 복수 증거 조합 / `2` 충돌·불신 증거 진단 + - `verification_complexity`: `0` 단일 결정 명령 / `1` 복수 단계·통합 검증 / `2` 외부·상호작용·장시간 검증 + - grade는 `max(1, 다섯 점수의 합)`이며 유효 범위는 `G01`부터 `G10`이다. + - 이전 grade, 실패 횟수, lane 변경은 점수에 더하지 않는다. + +6. **파일명 확정** + - 각 target에 대해 다음 명령을 실행하고 stdout의 grade와 filename을 그대로 사용한다. + + ```bash + agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh \ + \ + \ + + ``` + + - 모델이 점수 합산, zero-padding, prefix 조합을 직접 계산하지 않는다. + - 두 target은 같은 lane/G를 복사하지 말고 각자의 실행 범위로 독립 평가한다. + - 모든 요청 target이 `routed`일 때만 filename을 반환한다. + - 결과 확정 뒤 scope, 검증, 증거, 소유권, 결정 조건이 달라지면 결과를 무효화하고 Step 1부터 다시 실행한다. + +## 실행 결과 검증 + +- [ ] 모든 요청 target에 여섯 폐쇄성 값과 현재 증거 근거가 있는가 +- [ ] 재평가가 `isolated-reassessment`로 실행되었고 새 결과 전까지 이전 평가가 노출·비교되지 않았는가 +- [ ] `unknown` 또는 `blocked` 상태에서 lane/G/filename을 만들지 않았는가 +- [ ] 이전 lane/G, 실패 횟수, finding 개수를 승계하거나 자동 승격 근거로 사용하지 않았는가 +- [ ] lane을 먼저 정하고 G 등급을 별도 차원 점수로 산정했는가 +- [ ] 각 target에 formatter script를 실행했고 grade와 filename을 stdout 그대로 사용했는가 +- [ ] build/review filename이 target별 formatter 결과와 정확히 일치하는가 +- 검증 실패 시: 결과를 `unrouted`로 폐기하고 누락된 현재 증거부터 보강한 뒤 전체 평가를 다시 수행한다. + +## 출력 형식 + +```yaml +status: routed | needs_evidence | blocked +evaluation_mode: first-pass | isolated-reassessment +targets: + build: + closures: + scope_closed: true + context_closed: true + verification_closed: true + evidence_trusted: true + ownership_closed: true + decision_closed: true + closure_basis: + scope_closed: "" + context_closed: "" + verification_closed: "" + evidence_trusted: "" + ownership_closed: "" + decision_closed: "" + lane: local + grade_scores: + scope_coupling: 1 + state_concurrency: 1 + blast_irreversibility: 1 + evidence_diagnosis: 0 + verification_complexity: 1 + grade: G04 + filename: PLAN-local-G04.md + review: + closures: + scope_closed: true + context_closed: false + verification_closed: true + evidence_trusted: false + ownership_closed: true + decision_closed: true + closure_basis: + scope_closed: "" + context_closed: "" + verification_closed: "" + evidence_trusted: "" + ownership_closed: "" + decision_closed: "" + lane: cloud + grade_scores: + scope_coupling: 1 + state_concurrency: 1 + blast_irreversibility: 1 + evidence_diagnosis: 2 + verification_complexity: 1 + grade: G06 + filename: CODE_REVIEW-cloud-G06.md +missing_evidence: [] +blocked_reason: null +``` + +`needs_evidence` 또는 `blocked`에서는 해당 target의 `lane`, `grade_scores`, `grade`, `filename`을 `null`로 둔다. + +## 금지 사항 + +- 이전 lane/G를 기본값, 최소값, 비교 기준으로 사용하지 않는다. +- 기존 평가가 있는 재평가를 같은 평가 context에서 수행하지 않는다. +- local 실패를 이유로 cloud로 자동 승격하지 않는다. +- 높은 local G로 cloud에 필요한 컨텍스트나 판단을 보상하지 않는다. +- 파일 수, 동시성, dirty 상태, Required 개수 같은 단일 휴리스틱으로 lane을 정하지 않는다. +- grade나 filename을 formatter script 출력과 다르게 수작업으로 만들지 않는다. +- `needs_evidence`를 `cloud`로 치환하거나 미완성 상태에서 routed filename을 만들지 않는다. +- PLAN, CODE_REVIEW, archive, complete.log 파일을 직접 생성·수정·이동하지 않는다. diff --git a/agent-ops/skills/common/finalize-task-routing/agents/openai.yaml b/agent-ops/skills/common/finalize-task-routing/agents/openai.yaml new file mode 100644 index 0000000..06679a1 --- /dev/null +++ b/agent-ops/skills/common/finalize-task-routing/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Finalize Task Routing" + short_description: "Finalize task lane, grade, and filenames" + default_prompt: "Use $finalize-task-routing after task analysis to independently determine build/review lanes, grades, and canonical filenames." diff --git a/agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh b/agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh new file mode 100755 index 0000000..9729f06 --- /dev/null +++ b/agent-ops/skills/common/finalize-task-routing/scripts/finalize-task-route.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + printf '%s\n' \ + 'usage: finalize-task-route.sh ' >&2 + exit 2 +} + +if [[ $# -ne 7 ]]; then + usage +fi + +target=$1 +lane=$2 +shift 2 +scores=("$@") + +case "$target" in + build) + prefix=PLAN + ;; + review) + prefix=CODE_REVIEW + ;; + *) + usage + ;; +esac + +case "$lane" in + local|cloud) + ;; + *) + usage + ;; +esac + +sum=0 +for score in "${scores[@]}"; do + case "$score" in + 0|1|2) + sum=$((sum + score)) + ;; + *) + usage + ;; + esac +done + +if [[ $sum -lt 1 ]]; then + sum=1 +fi + +printf 'target=%s\n' "$target" +printf 'lane=%s\n' "$lane" +printf 'grade=G%02d\n' "$sum" +printf 'filename=%s-%s-G%02d.md\n' "$prefix" "$lane" "$sum" diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index b23e25c..00f66ce 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/agent-ops/skills/common/plan/SKILL.md @@ -1,6 +1,6 @@ --- name: plan -description: Analyze the current repository and write a detailed PLAN-{build_lane}-GNN.md for implementation work. Also writes the CODE_REVIEW-{review_lane}-GNN.md stub that the implementing agent will fill in after coding. Use for any feature, refactor, bug fix, or follow-up fix that should enter the plan-code-review loop. Milestone-linked work uses a reserved m-prefixed task group so runtime can route PASS completion events to update-roadmap. A separate implementing agent, or the same agent in an implementation pass, reads the plan file and does the coding. +description: Analyze the current repository and write a detailed PLAN-{build_lane}-GNN.md plus CODE_REVIEW-{review_lane}-GNN.md stub for implementation work. Use for every feature, refactor, bug fix, and code-review WARN/FAIL follow-up that enters the plan-code-review loop. Every initial or follow-up pair must run finalize-task-routing after analysis and before routed filenames are chosen. Milestone-linked work uses a reserved m-prefixed task group so runtime can route PASS completion events to update-roadmap. --- # Plan @@ -10,9 +10,9 @@ description: Analyze the current repository and write a detailed PLAN-{build_lan Create the planning artifacts for the implementation loop: ```text -plan skill -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub +plan skill -> analysis -> finalize-task-routing -> PLAN-{build_lane}-GNN.md + CODE_REVIEW-{review_lane}-GNN.md stub 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 +code-review skill -> verdict + archive, complete.log and task-directory archive move, USER_REVIEW.md, or mandatory plan-skill follow-up runtime -> for m-prefixed PASS completion events, state check and optional update-roadmap call ``` @@ -24,6 +24,12 @@ The plan file and review stub must be self-sufficient for implementation agents 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. +Invocation modes: + +- `write` is the default for initial plans and explicit replans. After routing, this skill archives any prior active pair and writes the new pair. +- `prepare-follow-up` is used only when code-review has appended WARN/FAIL but has not archived the active pair. This skill completes analysis, final routing, and exact PLAN/review-stub rendering in memory without mutating repository files. It returns `prepared_plan`, `prepared_review`, their routed basenames, the current pair's predicted archive names/numbers, and the post-archive log counts used by the new pair. +- Both modes execute the same mandatory Step 3. `prepare-follow-up` is not a route-only shortcut. + 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`. @@ -40,6 +46,7 @@ Filename rules: - Review stub: `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`; the runtime maps lane+grade to current models externally. +- Lane, grade, and both canonical basenames come only from `agent-ops/skills/common/finalize-task-routing/SKILL.md`. Role boundary rules: @@ -93,18 +100,15 @@ Task directory naming rules: - Example: split independent docs/UI plus an integration under one task group as `01_core`, `02+01_db`, `03+02_api`, `04_docs`, `05_ui`, `06+05_integration`; `01_core`, `04_docs`, and `05_ui` can start together, and `06+05_integration` waits only for `05_ui`. - Preserve task group and subtask directory names verbatim; do not normalize, reinterpret, or choose execution order by agent judgment. -Routing rules: +Final routing boundary: -- Prefer `local` whenever the scope is bounded and verifiable; high local usage is fine. Do not choose `cloud` just to balance lane usage. -- `local` is for bounded, explicit, locally verifiable work: required behavior is explicit in task evidence, contracts, or existing pattern; relevant context fits in edited files plus nearby types/helpers, direct call sites, and existing or planned targeted tests/fixtures; correctness can be checked by code inspection plus type/build/unit tests or deterministic commands; no open-ended product/design judgment, live external provider/runtime semantics, or broad cross-domain context is decisive. -- Use `cloud` when any local condition is false, including when a plausible but wrong implementation could pass local checks while breaking behavior promised outside the bounded context. -- `local-G01` through `local-G10` and `cloud-G01` through `cloud-G10` are valid. Lane is capability fit; grade is complexity within the chosen lane. Do not raise `local-GNN` to compensate for missing judgment, missing context, weak verification, or a previous loop failure. -- Use `cloud-G07` or higher only when terminal-agent or external interactive behavior is central and cannot be made deterministic for local handling, or when the task requires more source/test/diff/log context than local can hold without omitting material evidence: shell/CLI workflow implementation, bin script orchestration, process control, stdout/stderr parsing, exit-status contracts, long-running command diagnosis, terminal benchmark-style tasks, TUI/PTY/browser/screen repaint/cursor stream behavior, real bin/smoke/integration failures after unit tests passed, or very large cross-module/cross-domain changes that cannot be safely split. -- For follow-ups from a review with 5+ `Required` findings, reassess lane/grade and default to `cloud-G07` or higher unless all findings are one narrow mechanical fix pattern; if keeping `local`, record why local conditions still hold. -- Previous loop lane does not matter. Recompute lane from the current plan or follow-up scope using these rules. -- Treat non-behavioral review artifact drift as reviewer-repairable unless it prevents judging implementation correctness, tests, or contracts. -- Treat obvious non-behavioral source nits as reviewer-repairable too: typos, stale comments, docs, or formatting only, with no behavior/test/API contract change. -- Raise `GNN` with scope, ambiguity, missing tests, irreversible behavior, and blast radius after lane selection; keep grade model-independent. +- Do not estimate, inherit, or write lane/G while analyzing. Keep the task `unrouted` until all plan scope, split, verification, evidence, ownership, and decision facts are complete. +- Execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` for both `build` and `review` after analysis. Its routed outputs are the only source for active PLAN/CODE_REVIEW filenames. +- Apply this boundary to first-pass plans, review WARN/FAIL follow-ups, USER_REVIEW replans, and each split subtask independently. +- A previous loop's lane, grade, score, rationale, and filename are quarantined. Prior code paths, actual command output, and review findings may be carried only as revalidated raw evidence. +- `needs_evidence` requires evidence collection and a fresh full routing run. `blocked` stops plan-file creation. Neither state may produce active routed filenames. +- If plan facts change after routing, invalidate both target results and run final routing again before writing files. +- Treat non-behavioral review artifact drift and obvious non-behavioral source nits as current-scope evidence; they do not bypass final routing. Directory states: @@ -113,11 +117,12 @@ 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 claims a selected Milestone lock decision blocker; ready for code-review to validate and create `USER_REVIEW.md` only if justified | -| `PLAN-*-G??.md` + filled `CODE_REVIEW-*-G??.md` | Ready for code-review skill | +| `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 is pending. Continue only when code-review invokes `prepare-follow-up`; `write` mode must not overwrite this state. | | `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`) | Task terminated mid-loop or abandoned | +| Only `*.log` files (no `complete.log`) | Inspect the newest review log. A verdict with no required next state is post-archive finalization pending; otherwise the task is terminated mid-loop or abandoned. | ## Step 1 - Determine Task @@ -145,6 +150,8 @@ If no active plan exists but one or more `USER_REVIEW.md` files exist, report th 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 a later explicit command selects either user-review resolution or the active plan/review path. +If the selected review already has an appended verdict, accept it only in `prepare-follow-up` mode invoked by code-review. In every other mode, leave the pair unchanged and report that code-review finalization must resume. + 로드맵 확인: - `agent-roadmap/current.md`는 브랜치별 로컬 포인터다. 있으면 구현 계획 파일을 만들기 전에 읽고, 사용자 요청, 브랜치, 변경 경로를 기준으로 관련 Phase와 Milestone을 선택한다. @@ -194,33 +201,38 @@ Complete all items below before creating active plan/review files. Work through - [ ] **Verify verification commands** — confirm that the final verification commands actually run in this repository layout. - [ ] **Stabilize fragile verification** — for search or generated-output checks, choose deterministic commands up front, such as `rg --sort path`, and decide whether cached test output is acceptable or `-count=1` is required. -## Step 3 - Determine GXX Grade +## Step 3 - Finalize Task Routing -GXX is an output of analysis, not an input. Determine lane and grade only after Step 2 is fully complete. +This step is mandatory and must be the last semantic decision before routed filenames are fixed. Complete Step 2 and prepare the full plan structure in memory before starting it. -- [ ] **Assess change scope** — count affected files, interface impact, call-site count, and the amount of source/test/review context that must stay loaded together. -- [ ] **Check risk factors** — mark any that apply: behavior promised outside edited files, persisted-state rule, permission boundary, shared-state risk, irreversible behavior. -- [ ] **Evaluate test confidence** — judge whether existing tests sufficiently verify the changed behavior. -- [ ] **Decide lane** — apply `Routing rules` as a gate. Use `local` only when all local allowlist conditions are true; otherwise use `cloud`. Ignore previous loop lane. -- [ ] **Decide GNN** — assign grade within the selected lane as scope, ambiguity, irreversibility, and blast radius increase. Grade is complexity-based, not model-name-based; both `local-G10` and `cloud-G01` are valid when lane evidence supports them. Do not increment GNN solely because a previous loop failed. +- [ ] **Build neutral input** — prepare current scope, affected paths, invariants, context size, split result, verification plan, actual evidence, ownership, unresolved decisions, and failure evidence for `build` and `review`. Exclude every previous lane, grade, routing score, rationale, filename, and archive basename that exposes them. +- [ ] **Select evaluation mode** — use `first-pass` only when no prior routing exists. Review follow-ups, invalidated routes, and USER_REVIEW replans use `isolated-reassessment` and must pass the neutral input to a fresh evaluation context/sub-invocation that has not seen the previous assessment. +- [ ] **Run the routing skill** — read and fully execute `agent-ops/skills/common/finalize-task-routing/SKILL.md` with both targets in the selected mode. Do not reproduce or replace its decision logic inside this skill. If isolated evaluation is unavailable, treat the routing result as `blocked`; do not silently evaluate in the current anchored context. +- [ ] **Resolve non-final states** — for `needs_evidence`, collect the named evidence and rerun from `unrouted`; for `blocked`, stop without mutating task files and report the exact release condition. In `prepare-follow-up`, leave the verdict-appended active pair in place so code-review recovery can resume without losing the loop state. +- [ ] **Accept only routed output** — require independent `build` and `review` closure records, lane, grade scores, GNN, and canonical filename. +- [ ] **Freeze the result** — use those exact basenames in Steps 4-6. If any routing input changes before the files are written, discard both outputs and repeat this step from the beginning. ## Step 4 - Archive Existing Active Files -Before writing new active files for the chosen active task directory: +In `write` mode, complete this step before writing new active files. In `prepare-follow-up` mode, calculate the same counts and archive names but do not modify any repository file; code-review owns the later archive. -- Ensure `.gitignore` has the Agent-Ops managed gitignore block before renaming any active file to `*.log` or creating local `agent-roadmap/current.md`. 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`. -- 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 linked Milestone decision is resolved for replanning, rename `USER_REVIEW.md` to `user_review_U.log`. +- Validate that the task directory contains at most one active `PLAN-(local|cloud)-G(0[1-9]|10).md`, at most one active `CODE_REVIEW-(local|cloud)-G(0[1-9]|10).md`, and at most one `USER_REVIEW.md`. Reject ambiguous or malformed active names. +- In `write` mode, ensure `.gitignore` has the Agent-Ops managed gitignore block before renaming any active file to `*.log` or creating local `agent-roadmap/current.md`. 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`. In `prepare-follow-up` mode, only inspect the block and return `gitignore_repair_needed: true|false`; code-review performs any repair after preparation. +- Count existing `plan_*.log` as `current_plan_archive_number`. If an active plan exists, parse `current_build_lane` and `current_build_grade` from that active filename and set `current_plan_archive_name=plan_{current_build_lane}_{current_build_grade}_{current_plan_archive_number}.log`. Require that destination not to exist. In `write` mode rename that exact active file to the calculated name; in `prepare-follow-up` only return the name and number. Never use the newly routed build lane/grade to archive the old active plan. +- Count existing `code_review_*.log` as `current_review_archive_number`. If an active review exists, parse `current_review_lane` and `current_review_grade` from that active filename and set `current_review_archive_name=code_review_{current_review_lane}_{current_review_grade}_{current_review_archive_number}.log`. Require that destination not to exist. In `write` mode rename that exact active file to the calculated name; in `prepare-follow-up` only return the name and number. Never use the newly routed review lane/grade to archive the old active review. +- Count existing `user_review_*.log` as `current_user_review_archive_number`. If `USER_REVIEW.md` exists and the linked Milestone decision is resolved for replanning, set `current_user_review_archive_name=user_review_{current_user_review_archive_number}.log`; require that destination not to exist and rename it only in `write` mode. +- Compute `post_archive_plan_log_count`, `post_archive_review_log_count`, and `post_archive_user_review_log_count` from the filesystem after actual archive in `write` mode, or from the predicted addition of each current active file in `prepare-follow-up` mode. -The new plan number is the count of `plan_*.log` after archiving. +Set `plan_number=post_archive_plan_log_count`. The new pair's future archive suffixes are `plan_log_number=post_archive_plan_log_count` and `review_log_number=post_archive_review_log_count`. These are intentionally different concepts from `current_plan_archive_number` and `current_review_archive_number`. ## Step 5 - Write Plan File +Render the complete plan in memory first. In `write` mode, write it to the routed plan basename. In `prepare-follow-up` mode, return the exact rendered body as `prepared_plan` and do not write it. + Header line must be exactly: ```markdown - + ``` Required sections: @@ -258,7 +270,7 @@ Required sections: - Status updates on PASS: - `agent-ui/definition/views//index.md`: `계획` -> `구현됨` ``` -- `분석 결과`: 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: +- `분석 결과`: record the findings from Step 2 and the final routed output from 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 agent-test rule/profile files only when they were actually present and read. - `SDD 기준`: for `SDD: 필요` Milestones, list the SDD path, status, targeted Acceptance Scenario ids, their Milestone Task ids, and the Evidence Map rows that drive the plan. State explicitly how those rows shaped the implementation checklist and final verification. If the selected Milestone has `SDD: 불필요`, state the recorded reason. If the work is not Milestone-linked, state "not applicable". - `테스트 환경 규칙`: state the chosen `test_env`, whether `agent-test//rules.md` was present/read/missing/intentionally unused, every matched profile path read when any, the concrete rules/commands applied, any structural blank/skeleton or missing rules, any `<확인 필요>` values, and any fallback verification source. If any required verification leaves the current checkout, include a `테스트 환경 프리플라이트` record with runner, repo root/workdir, branch/HEAD/dirty state, source sync status, binary/artifact paths, required command help/version output, config path, runtime identity such as Edge id, ports/process state, external hosts, OS/arch assumptions, and the exact setup/sync/rebuild step or blocker derived from mismatches. If agent-test is absent or unusable, explicitly say no agent-test rule was applied, what fallback is used, and whether test-rule maintenance is actually needed or not needed for this task. @@ -266,7 +278,7 @@ Required sections: - `심볼 참조`: list renamed/removed symbols and every call site found, or state "none" if no symbols were changed. - `분할 판단`: state that the split decision policy was evaluated before choosing plan files. For a single plan, explain why each relevant split gate does not apply and why single-plan coordination is safer than splitting. For multi-plan output, list the shared task group plus each sibling subtask directory and dependency relationship. For dependent subtask plans, include each predecessor index and whether it is satisfied by an active or archived `complete.log`, missing, or ambiguous. - `범위 결정 근거`: state which files or areas were explicitly excluded from this change and why. This is the boundary justification — the implementing agent must not silently expand scope beyond what is recorded here. - - `빌드 등급`: state the decided lane and GNN grade with a one-line rationale. + - `최종 라우팅`: record the `evaluation_mode` plus `build` and `review` closure results, grade scores, lane, GNN, and canonical filename returned by `finalize-task-routing`. Do not include or compare a previous loop's lane/G. - `구현 체크리스트`: a top-level checklist the implementing agent must follow while coding. Include one item per implementation/verification unit; if the roadmap feature Task has `검증:`, keep that verification in the same checklist item instead of making a separate completion-criteria item. Include one item for whole-plan intermediate/final verification only when it is not already covered by the feature items, and make the final item exactly: `- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.` Copy this checklist into the review stub's `구현 체크리스트` section with the same item text and order. - One item per change: `### [TAG-1] Title`, `TAG-2`, etc. - `수정 파일 요약`: table mapping files to item ids. @@ -319,165 +331,17 @@ 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. +Read `agent-ops/skills/common/plan/templates/review-stub-template.md` in full only after Step 3 returns `status: routed`. +Replace every occurrence of each token below: -```markdown - +- Scalar tokens: `{date}`, `{task_group}`, `{task_name}`, `{plan_number}`, `{TAG}`, `{build_lane}`, `{build_grade}`, `{review_lane}`, `{review_grade}`, `{plan_log_number}`, `{review_log_number}`. +- Plan-copy tokens: `{roadmap_targets_or_omit}`, `{archive_evidence_snapshot_or_omit}`, `{agent_ui_completion_or_omit}`, `{implementation_checklist}`, `{review_checkpoints}`. +- Generated row/section tokens: `{implementation_completion_rows}` contains one row for every plan item, and `{verification_result_sections}` contains the fixed verification instructions plus every intermediate/final command from the plan. +- `{implementation_user_review_request_section}` is replaced by the full contents of `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`; do not prepend another `사용자 리뷰 요청` heading. -# Code Review Reference - {TAG} - -> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** -> 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 selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves. -> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review. -> 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. - -## 개요 - -date={YYYY-MM-DD} -task={task_name}, plan={N}, tag={TAG} - -{copy the plan's Roadmap Targets section exactly if present; omit this block if the plan has no Roadmap Targets} -{copy the plan's Archive Evidence Snapshot section exactly if present; omit this block if the plan has no Archive Evidence Snapshot} - -## 이 파일을 읽는 리뷰 에이전트에게 - -> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. - -각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. -리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. - -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이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다. -4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. -5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. - ---- - -## 구현 항목별 완료 여부 - -| 항목 | 완료 여부 | -|------|---------| -| [{TAG}-1] {item description} | [ ] | -| [{TAG}-2] {item description} | [ ] | - -## 구현 체크리스트 - -{copy the plan's 구현 체크리스트 items exactly, preserving order and checkbox text} - -## Agent UI Completion - -> Include this section only when the plan has `Agent UI Completion`; otherwise omit it entirely. -> **[IMPLEMENTING AGENT]** Fill actual code evidence and implementation verification output for the listed docs. -> **[REVIEW AGENT ONLY]** On PASS, update only the listed agent-ui docs to `구현됨`, add the listed code evidence, run `validate-agent-ui`, and copy this section into `complete.log`. - -- Mode: review-pass-status-update -- Agent UI docs: - - `agent-ui/definition/views//index.md` -- Actual code evidence: - - [ ] ``: -- Implementation verification evidence: - - [ ] ``: -- Status updates requested on PASS: - - [ ] `agent-ui/definition/views//index.md`: `계획` -> `구현됨` -- Review finalization: - - [ ] Review agent updated the listed agent-ui docs and code evidence. - - [ ] Review agent ran `validate-agent-ui scope=` after the status/evidence update. - -## 코드리뷰 전용 체크리스트 - -> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. -> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. - -- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. -- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. -- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다. -- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다. -- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. -- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. -- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. -- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. -- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. -- [ ] 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`를 남기지 않는다. -- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. - -## 계획 대비 변경 사항 - -_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ - -## 주요 설계 결정 - -_구현 에이전트가 주요 설계 결정 사항을 기록한다._ - -## 사용자 리뷰 요청 - -_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._ - -- 상태: 없음 -- 사유 유형: 없음 -- 연결 대상: 없음 -- 결정 필요: 없음 -- 차단 근거: 없음 -- 실행한 검증/명령: 없음 -- 자동 후속 불가 이유: 없음 -- 재개 조건: 없음 - -## 리뷰어를 위한 체크포인트 - -{pre-filled from plan — one bullet per review focus area} - -## 검증 결과 - -_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ - -필수 규칙: -- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. -- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. -- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. -- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. -- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다. - -### {TAG}-1 중간 검증 -``` -$ {verification command from plan} -(output) -``` - -### 최종 검증 -``` -$ {final verification command from plan} -(output) -``` - ---- - -> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** -> If anything is blank, go back and fill it in before saving this file. -> Leave review-agent-only sections unchanged. -``` - -Sections and their ownership: - -| Section | Owner | Note | -|---------|-------|------| -| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | -| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS | -| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | -| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies `구현됨` status/evidence update on PASS and copies the section into `complete.log` | -| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | -| 구현 체크리스트 (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 a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation; do not ask the user directly during implementation; environment/secret/service blockers, generic scope changes, and evidence gaps are not user-review requests | -| 리뷰어를 위한 체크포인트 | 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 | +Use the routed build/review grades independently. Remove optional plan-copy content by replacing its token with an empty string, not by leaving template instructions. +In `write` mode, write the rendered stub to the routed review basename. In `prepare-follow-up` mode, return it as `prepared_review` without writing. +Do not write or return a prepared pair when either routing target is not `routed`. After rendering, scan for the exact template-token inventory above and reject the output if any known token remains; do not reject unrelated braces in copied commands or code. ## Naming @@ -490,14 +354,15 @@ Sections and their ownership: ## Final Checklist -- `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` both exist under the active task directory `agent-task/{task_name}/`. -- `.gitignore` has the Agent-Ops managed gitignore block that unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`, so active files and archived `*.log` task artifacts are trackable even when the project ignores `*.log`. +- In `write` mode, the routed `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` both exist under `agent-task/{task_name}/`. In `prepare-follow-up` mode, neither routed file was written; both exact bodies and basenames were returned while the verdict-appended current pair remained active. +- In `write` mode, `.gitignore` has the Agent-Ops managed block that unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores local `agent-roadmap/current.md`. In `prepare-follow-up` mode, the block was only inspected and any needed repair was returned as `gitignore_repair_needed`. - Single-plan work stores active files directly under `agent-task/{task_group}/`. - Split work, if any, uses one shared `agent-task/{task_group}/` parent and one subtask directory per plan/review pair with names like `01_core`, `02+01_edge_integration`, `03+01_node_integration`; dependency details live in the subtask directory name as `NN+PP[,QQ...]_subtask_name`. - Milestone-linked work uses `agent-task/m-/` as the task group; non-roadmap task groups do not start with `m-`. -- Both first lines match ``. -- 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 resolved linked Milestone decision was recorded in the new plan. +- Both first lines match ``. +- The review stub was rendered from `agent-ops/skills/common/plan/templates/review-stub-template.md` after routing and has no unresolved known template token. +- In `write` mode, previous active files, if any, were archived with lane/grade parsed from their own basenames and the correct current archive suffixes. In `prepare-follow-up` mode, those archive names were only predicted. +- In `write` mode when resuming from `USER_REVIEW.md`, it was archived to the calculated `current_user_review_archive_name` and the resolved linked Milestone decision was recorded in the new plan. - `Roadmap Targets` exists only when PASS should check explicit Milestone Task ids, the task group is `m-` for the listed Milestone path, and every listed Task id exists in the selected active Milestone. - If `Roadmap Targets` exists in the plan, the review stub contains the identical section. If it does not exist in the plan, the review stub omits it too. - If `Agent UI Completion` exists in the plan, the review stub contains the matching section with implementation-owned evidence fields. If it does not exist in the plan, the review stub omits it too. @@ -507,7 +372,10 @@ Sections and their ownership: - Dependent split plans record predecessor completion using active sibling `complete.log` or matching archived `complete.log`; ambiguous archive matches are not guessed. - 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. +- `finalize-task-routing` ran after all analysis for both `build` and `review` in the required evaluation mode; its output status is `routed`, and the active filenames plus `분석 결과 > 최종 라우팅` exactly match its two results. +- Review WARN/FAIL follow-ups entered through this plan skill and did not inherit or compare the archived lane/G. - The plan's implementer instructions and review stub both forbid direct user prompts during implementation and 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. +- In `prepare-follow-up`, no repository file was mutated and the returned prepared basenames/bodies, `plan_number`, current archive names/numbers, post-archive log counts, and `gitignore_repair_needed` are complete; in `write`, prior active state was archived with its own parsed route and both new active files were written. diff --git a/agent-ops/skills/common/plan/agents/openai.yaml b/agent-ops/skills/common/plan/agents/openai.yaml index 45057de..763c4dd 100644 --- a/agent-ops/skills/common/plan/agents/openai.yaml +++ b/agent-ops/skills/common/plan/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Plan" short_description: "Write implementation plans" - default_prompt: "Use $plan to create grouped PLAN/CODE_REVIEW task files for this repository change." + default_prompt: "Use $plan to analyze this repository change, run $finalize-task-routing as the final decision, and create the routed PLAN/CODE_REVIEW pair." diff --git a/agent-ops/skills/common/plan/templates/review-stub-template.md b/agent-ops/skills/common/plan/templates/review-stub-template.md new file mode 100644 index 0000000..3bc6103 --- /dev/null +++ b/agent-ops/skills/common/plan/templates/review-stub-template.md @@ -0,0 +1,106 @@ + + +# Code Review Reference - {TAG} + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> 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 selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves. +> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review. +> 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. + +## 개요 + +date={date} +task={task_name}, plan={plan_number}, tag={TAG} + +{roadmap_targets_or_omit} +{archive_evidence_snapshot_or_omit} + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-{review_lane}-{review_grade}.md` → `code_review_{review_lane}_{review_grade}_{review_log_number}.log`, `PLAN-{build_lane}-{build_grade}.md` → `plan_{build_lane}_{build_grade}_{plan_log_number}.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 plan skill을 실행해 fresh routing된 다음 active pair를 만들거나 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다. +4. PASS이고 task group이 `m-`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +{implementation_completion_rows} + +## 구현 체크리스트 + +{implementation_checklist} + +{agent_ui_completion_or_omit} + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_{review_grade}_{review_log_number}.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_{build_grade}_{plan_log_number}.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 plan skill을 실행하고 `finalize-task-routing`의 fresh 결과와 일치하는 다음 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`를 남기지 않는다. +- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +{implementation_user_review_request_section} + +## 리뷰어를 위한 체크포인트 + +{review_checkpoints} + +## 검증 결과 + +{verification_result_sections} + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. + +## 섹션 소유권 + +| Section | Owner | Note | +|---------|-------|------| +| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) | +| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS | +| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required | +| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies `구현됨` status/evidence update on PASS and copies the section into `complete.log` | +| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only | +| 구현 체크리스트 (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 a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation; do not ask the user directly during implementation; environment/secret/service blockers, generic scope changes, and evidence gaps are not user-review requests | +| 리뷰어를 위한 체크포인트 | 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 | diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index 454e152..86f7e7a 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -37,8 +37,15 @@ | roadmap dependency 확인, locks.yaml 판별, 외부 의존 잠금 확인, unlock-ready 판별, 잠금 해제 조건 충족 여부 확인, roadmap-dependency-checker.sh | `agent-ops/skills/common/check-roadmap-dependency/SKILL.md` | | 지금 작업이 뭐지?, 현재 작업 분석, 어디까지 했지?, 로드맵상 현 위치, 현재 마일스톤 위치, current 기준 breadcrumb | `agent-ops/skills/common/analyze-roadmap-position/SKILL.md` | | 계획 세워줘, 계획 작성해, 계획 만들어줘, 구현 계획, PLAN.md, plan, plan 작성해, plan 만들어줘 | `agent-ops/skills/common/plan/SKILL.md` | +| 최종 라우팅, task routing, cloud/local 재평가, lane/G 판단, G 등급 재평가, routed filename 결정 | `agent-ops/skills/common/finalize-task-routing/SKILL.md` | | 코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프 | `agent-ops/skills/common/code-review/SKILL.md` | | 커밋해줘, 푸시해줘, commit, push, 반영해줘 | `agent-ops/skills/common/commit-push/SKILL.md` | | agent-ops 싱크해, agent-ops 동기화해, agentic-framework에 올려줘, agent-ops를 [프로젝트]로 싱크해 | `agent-ops/skills/common/sync-push/SKILL.md` | | agent-ops pull해, agent-ops 가져와, agentic-framework에서 가져와, agent-ops 내려받아 | `agent-ops/skills/common/sync-pull/SKILL.md` | | 도메인 업데이트, domain rule 갱신, 도메인 검토, domain 스캔 | `agent-ops/skills/common/update-domain-rule/SKILL.md` | + +라우팅 우선순위: + +- PLAN/CODE_REVIEW 작성 또는 재작성이 요청 범위에 포함되면 `plan`을 선택한다. `plan`이 최종 단계에서 `finalize-task-routing`을 필수 호출한다. +- lane/G/canonical filename 판단만 요청되고 plan 문서 작성은 요청되지 않았을 때만 `finalize-task-routing`을 직접 선택한다. +- 코드 리뷰 요청은 `code-review`를 선택한다. WARN/FAIL follow-up은 `code-review -> plan -> finalize-task-routing` 순서를 유지한다.