toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-task/single_request_plan_review_templates/CODE_REVIEW-cloud-G07.md
toki 8a8ea29abd docs(agent-task): 템플릿 작업 계획을 작성한다 
단일 요청 Plan과 Review 템플릿 변경을 구현·검증할 때 설정, 요청 스냅샷, 런타임 산출물의 경계를 한 작업 단위로 유지하기 위해 계획과 리뷰 기준을 고정한다.
2026-08-09 08:22:47 +09:00

16 KiB
Raw Blame History

Code Review Reference - API

[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 Implementation Checklist; the final checklist item is mandatory before saving. Fill implementation-owned sections, then stop with active files in place and report ready for review. Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt. If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields. Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state. Finalization (Code Review Result, log rename, complete.log, archive moves, Review-Only Checklist) is review-agent-only, even after compaction/resume. Follow the ownership table at the bottom of this file for which sections you own.

Overview

date=2026-08-09 task=single_request_plan_review_templates, plan=0, tag=API

For the Review Agent

[REVIEW AGENT ONLY] The finalization steps below are review-agent only. Implementing agents must not execute this section.

Compare implementation of each item against source files and verify that output in Verification Results matches code. Review completion means the following steps are finished:

  1. Append verdict and review_rework_count / evidence_integrity_failure routing signals.
  2. Archive CODE_REVIEW-cloud-G07.md → code_review_cloud_G07_0.log and PLAN-local-G07.md → plan_local_G07_0.log.
  3. If PASS, write complete.log and move active task directory to agent-task/archive/YYYY/MM/single_request_plan_review_templates/. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
  4. If PASS and task group is m-<milestone-slug>, preserve the first-line milestone-task metadata in complete.log and report it for the runtime aggregation event. Roadmap state evaluation belongs to sync-milestone-workstate.
  5. Check applicable Review-Only Checklist items at the final .log location before reporting.

Implementation Item Completion

Item Status
API-1 Bounded template contract and config loading [ ]
API-2 Immutable request-start template snapshot [ ]
API-3 Direct compact PlanMD stage [ ]
API-4 Compact Review artifact without changing the control loop [ ]
API-5 Operator contract, current specs, and integrated evidence [ ]

Implementation Checklist

  • [API-1] Add the bounded built-in Plan/Review template grammar, strict config-relative override loading, redacted live-refresh classification, and boundary tests.
  • [API-2] Freeze effective template content into immutable SingleRequestBinding admissions and verify clone/refresh isolation.
  • [API-3] Replace plan-stage JSON response formatting with direct compact PlanMD generation and structural validation.
  • [API-4] Render approved review artifacts through the compact Review template while preserving review/repair/final-output behavior.
  • [API-5] Update the operator example and current contracts/specs, then run fresh local and remote dev verification.
  • Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

Review-Only Checklist

[REVIEW AGENT ONLY] This checklist is used only by the review agent. Implementing agents must not modify or check this section.

  • Append one verdict of PASS, WARN, or FAIL and verified review_rework_count, evidence_integrity_failure to Code Review Result.
  • Verify that verdict, Dimension Assessment, and Required/Suggested/Nit classifications match.
  • Archive active CODE_REVIEW-*-G??.md to code_review_cloud_G07_0.log.
  • Archive active PLAN-*-G??.md to plan_local_G07_0.log.
  • Verify that the Agent-Ops managed block in .gitignore unignores agent-task/**/*.md and agent-task/**/*.log and ignores agent-roadmap/current.md.
  • If PASS, write complete.log based on agent-ops/skills/common/code-review/templates/complete-log-template.md and leave no active .md files.
  • If PASS, move active task directory agent-task/single_request_plan_review_templates/ to agent-task/archive/YYYY/MM/single_request_plan_review_templates/ and update this checklist at the final archive path.
  • If PASS and task group is m-<milestone-slug>, preserve and report milestone-task metadata for runtime aggregation, without modifying roadmap or directly calling update-roadmap.
  • If PASS for split work, remove empty active parent agent-task/single_request_plan_review_templates/ or verify it was kept due to remaining siblings/files.
  • If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write complete.log.

Deviations from Plan

Record any deviations from the plan and the rationale here.

Key Design Decisions

Record key design decisions here.

Reviewer Checkpoints

  • Confirm the shared grammar has exactly the approved placeholders/headings, independent built-in fallback, 8192-byte cap, config-relative regular-file loading, and fail-closed invalid override behavior.
  • Confirm refresh detects same-path content changes as live-applied for new requests while evidence/provider/caller surfaces expose neither file paths nor template bodies.
  • Confirm every admitted binding freezes content and clone/workspace revalidation cannot observe source mutation.
  • Confirm Plan provider requests no longer set JSON response format and malformed/non-compact Markdown never reaches internal artifacts.
  • Confirm Review inspection/repair/tool-budget sequencing and caller final output remain unchanged while only approved internal Review artifacts use the selected template.
  • Confirm current contracts/specs match code and local plus remote evidence is fresh; treat a reproducible SOPS age-identity failure as external verification evidence, not as permission to substitute a provider credential.

Verification Results

Paste actual stdout/stderr for every command. Do not summarize or reconstruct output. If output is too long, save it outside the repository and record the exact path and producing command.

API-1 — template/config/refresh tests

go test -count=1 ./packages/go/singlerequesttemplate ./packages/go/config ./apps/edge/internal/configrefresh

Actual output pending implementation.

API-2 — binding and preset snapshot tests

go test -count=1 ./apps/edge/internal/service -run 'TestSingleRequestBinding'
go test -count=1 ./apps/edge/internal/openai -run 'TestSingleRequestPresetBinding'

Actual output pending implementation.

API-3 — direct PlanMD tests

go test -count=1 ./apps/edge/internal/openai -run 'TestSingleRequestPlanStage'

Actual output pending implementation.

API-4 — Review template/control-loop tests

go test -count=1 ./apps/edge/internal/openai -run 'TestSingleRequestReviewStage'

Actual output pending implementation.

API-5 — smoke self-test and race tests

make test-single-request-claude-smoke-self-test
go test -race -count=1 ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/edge/internal/configrefresh ./packages/go/config ./packages/go/singlerequesttemplate

Actual output pending implementation.

Final — formatting and complete local suite

test -z "$(gofmt -l packages/go/singlerequesttemplate/template.go packages/go/singlerequesttemplate/template_test.go packages/go/config/execution_preset_types.go packages/go/config/load.go packages/go/config/model_execution_preset_config_test.go apps/edge/internal/configrefresh/classify.go apps/edge/internal/configrefresh/execution_preset_classify_test.go apps/edge/internal/service/single_request_types.go apps/edge/internal/service/single_request_types_test.go apps/edge/internal/openai/single_request_preset_binding.go apps/edge/internal/openai/single_request_preset_binding_test.go apps/edge/internal/openai/single_request_plan_stage.go apps/edge/internal/openai/single_request_plan_stage_test.go apps/edge/internal/openai/single_request_review_stage.go apps/edge/internal/openai/single_request_review_stage_test.go)"
go test -count=1 ./packages/go/singlerequesttemplate ./packages/go/config ./apps/edge/internal/configrefresh
go test -count=1 ./apps/edge/internal/service -run 'TestSingleRequestBinding'
go test -count=1 ./apps/edge/internal/openai -run 'TestSingleRequest(PlanStage|ReviewStage|PresetBinding)'
go test -race -count=1 ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/edge/internal/configrefresh ./packages/go/config ./packages/go/singlerequesttemplate
go test -count=1 ./apps/edge/... ./packages/go/...
make test-single-request-claude-smoke-self-test

Actual output pending implementation.

Final — pushed feature identity and remote runner sync

test "$(git branch --show-current)" = "feature/single-request-plan-review-templates"
test -z "$(git status --porcelain)"
git push origin HEAD:feature/single-request-plan-review-templates
expected_commit="$(git rev-parse HEAD)"
test "$(git ls-remote origin refs/heads/feature/single-request-plan-review-templates | cut -f1)" = "$expected_commit"
ssh -o BatchMode=yes toki@toki-labs.com bash -s -- "$expected_commit" <<'REMOTE'
set -eu
repo=/Users/toki/agent-work/iop-dev
cd "$repo"
git fetch origin feature/single-request-plan-review-templates
git switch --force-create feature/single-request-plan-review-templates origin/feature/single-request-plan-review-templates
git reset --hard origin/feature/single-request-plan-review-templates
git clean -fd
test "$(git rev-parse HEAD)" = "$1"
test -z "$(git status --porcelain)"
test "$(/opt/homebrew/bin/go env GOOS)-$(/opt/homebrew/bin/go env GOARCH)" = "darwin-arm64"
/opt/homebrew/bin/claude --version
/opt/homebrew/bin/sops --version
test -f /Users/toki/.config/iop/secrets/dev-openai-toki.sops.yaml
test -f build/dev-runtime/node-codex.yaml
test -f /Users/toki/agent-work/iop-s12-validation-20260808/source/build/s12/runtime/edge.yaml
REMOTE

Actual output pending implementation.

Final — remote dev rebuild/restart

ssh -o BatchMode=yes toki@toki-labs.com bash -s <<'REMOTE'
set -eu
repo=/Users/toki/agent-work/iop-dev
cd "$repo"
rm -rf /tmp/iop-single-request-template-build
PATH=/opt/homebrew/bin:$PATH make build-edge build-node BUILD_DIR=/tmp/iop-single-request-template-build EDGE_TARGET=darwin-arm64
cp /Users/toki/agent-work/iop-s12-validation-20260808/source/build/s12/runtime/edge.yaml build/dev-runtime/single-request-template-edge.yaml
/tmp/iop-single-request-template-build/bin/iop-edge config check --config "$repo/build/dev-runtime/single-request-template-edge.yaml"
for port in 18083 18084 19093 19101; do
  /usr/sbin/lsof -nP -iTCP:"$port" -sTCP:LISTEN || true
done
edge_pid="$(/usr/sbin/lsof -tiTCP:18083 -sTCP:LISTEN 2>/dev/null || true)"
if test -n "$edge_pid"; then
  edge_cmd="$(ps -p "$edge_pid" -o command=)"
  case "$edge_cmd" in
    *iop-s12-validation-20260808*edge*) kill "$edge_pid"; wait "$edge_pid" 2>/dev/null || true ;;
    *build/dev-runtime/bin/edge*) kill "$edge_pid"; wait "$edge_pid" 2>/dev/null || true ;;
    *) printf 'unexpected 18083 owner: %s\n' "$edge_cmd" >&2; exit 1 ;;
  esac
fi
node_pid="$(pgrep -f 'iop-s12-validation-20260808/.*/iop-node.*--config /Users/toki/agent-work/iop-dev/build/dev-runtime/node-codex.yaml serve' || true)"
if test -n "$node_pid"; then kill "$node_pid"; wait "$node_pid" 2>/dev/null || true; fi
install -m 0755 /tmp/iop-single-request-template-build/bin/iop-edge build/dev-runtime/bin/edge.next
install -m 0755 /tmp/iop-single-request-template-build/bin/iop-node build/dev-runtime/bin/iop-node.next
mv build/dev-runtime/bin/edge.next build/dev-runtime/bin/edge
mv build/dev-runtime/bin/iop-node.next build/dev-runtime/bin/iop-node
nohup build/dev-runtime/bin/edge --config "$repo/build/dev-runtime/single-request-template-edge.yaml" serve >build/dev-runtime/logs/edge.template.stdout.log 2>build/dev-runtime/logs/edge.template.stderr.log &
echo $! >build/dev-runtime/edge.pid
nohup build/dev-runtime/bin/iop-node --config "$repo/build/dev-runtime/node-codex.yaml" serve >build/dev-runtime/logs/node-template.stdout.log 2>build/dev-runtime/logs/node-template.stderr.log &
echo $! >build/dev-runtime/node-codex.pid
sleep 2
kill -0 "$(cat build/dev-runtime/edge.pid)"
kill -0 "$(cat build/dev-runtime/node-codex.pid)"
/usr/sbin/lsof -nP -iTCP:18083 -sTCP:LISTEN
REMOTE

Actual output pending implementation.

Final — one deployed Claude single-request cycle

After the approved SOPS age identity/loader populates IOP_SINGLE_REQUEST_SMOKE_TOKEN and the closed runtime-evidence file in the same remote shell, run:

cd /Users/toki/agent-work/iop-dev
test -n "${IOP_SINGLE_REQUEST_SMOKE_TOKEN:-}"
test -f /tmp/iop-single-request-template-runtime.json
rm -rf /tmp/iop-single-request-template-workspace
mkdir -m 700 /tmp/iop-single-request-template-workspace
rm -f /tmp/iop-single-request-template-smoke.json
PATH=/opt/homebrew/bin:$PATH make test-single-request-claude-smoke-preflight test-single-request-claude-smoke test-single-request-claude-smoke-validate \
  IOP_SINGLE_REQUEST_SMOKE_CLAUDE_BIN=/opt/homebrew/bin/claude \
  IOP_SINGLE_REQUEST_SMOKE_RUNTIME_EVIDENCE=/tmp/iop-single-request-template-runtime.json \
  IOP_SINGLE_REQUEST_SMOKE_BASE_URL=http://127.0.0.1:18083 \
  IOP_SINGLE_REQUEST_SMOKE_MODEL=iop-single-request-light \
  IOP_SINGLE_REQUEST_SMOKE_EDGE_BIN=/Users/toki/agent-work/iop-dev/build/dev-runtime/bin/edge \
  IOP_SINGLE_REQUEST_SMOKE_NODE_BIN=/Users/toki/agent-work/iop-dev/build/dev-runtime/bin/iop-node \
  IOP_SINGLE_REQUEST_SMOKE_EDGE_CONFIG=/Users/toki/agent-work/iop-dev/build/dev-runtime/single-request-template-edge.yaml \
  IOP_SINGLE_REQUEST_SMOKE_OBSERVATION_FILE=/Users/toki/agent-work/iop-s12-validation-20260808/source/build/s12/runtime/edge.log \
  IOP_SINGLE_REQUEST_SMOKE_METRICS_URL=http://127.0.0.1:19101/metrics \
  IOP_SINGLE_REQUEST_SMOKE_WORKSPACE=/tmp/iop-single-request-template-workspace \
  IOP_SINGLE_REQUEST_SMOKE_OUTPUT=/tmp/iop-single-request-template-smoke.json \
  IOP_SINGLE_REQUEST_SMOKE_SECRET_ENV=IOP_SINGLE_REQUEST_SMOKE_TOKEN

If the age identity remains unavailable, paste the raw SOPS failure and exact resume condition here; do not substitute a provider credential or reuse runtime evidence.

Actual output pending implementation.

[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section? If anything is blank, go back and fill it in before saving this file. Leave review-agent-only sections unchanged.

Section Ownership

Section Owner Note
Header comment, Overview, Review Agent Instructions Fixed at stub creation Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only)
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
Implementation Item Completion (item names) Fixed at stub creation Implementing agent checks [ ] → [x] only
Implementation Checklist (item text/order) Fixed at stub creation from plan Implementing agent checks [ ] → [x] only
Review-Only Checklist Review agent only Implementing agent must not modify or check this section
Deviations from Plan, Key Design Decisions Implementing agent Replace placeholder text with actual content
Reviewer Checkpoints Fixed at stub creation Pre-filled from plan
Verification Results (section headings + commands) Fixed at stub creation Implementing agent fills in command output only; command changes require a Deviations from Plan entry
Code Review Result Review agent appends Not included in stub