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

22 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 [x]
API-2 Immutable request-start template snapshot [x]
API-3 Direct compact PlanMD stage [x]
API-4 Compact Review artifact without changing the control loop [x]
API-5 Operator contract, current specs, and integrated evidence [x]

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

None.

Key Design Decisions

  • Single Grammar Package: Created packages/go/singlerequesttemplate as the canonical template grammar owner. It defines built-in defaults (DefaultPlanTemplate / DefaultReviewTemplate), enforces MaxTemplateBytes = 8192, calculates SHA-256 hex digests (Digest), parses direct PlanMD output against effective plan templates, and renders Review Markdown through effective review templates.
  • Config-Relative Override Loading: Updated packages/go/config to resolve plan_file / review_file relative to filepath.Dir(configFilePath). Overrides are checked for regular file / non-symlink properties, capped at 8192 bytes, and structurally validated at load time. Unset fields fall back safely to built-in defaults.
  • Privacy-Preserving Live Refresh: Updated apps/edge/internal/configrefresh/classify.go to compute and diff PlanDigest and ReviewDigest. Raw file paths and template contents are stripped from YAML/mapstructure metadata and excluded from change evidence. Same-path template file content modifications trigger live-applied refresh classification for future requests.
  • Immutable Binding Snapshots: Updated SingleRequestBinding and SingleRequestPresetBinding to capture Templates SingleRequestTemplateBinding containing content-only frozen effective Plan and Review templates at admission time, ensuring clone and refresh isolation.
  • Direct PlanMD Plan Stage: Replaced Plan-stage JSON response formatting and prompt in apps/edge/internal/openai/single_request_plan_stage.go with direct PlanMD generation matching the effective plan template. Omits response_format and parses PlanMD using singlerequesttemplate.ParsePlan.
  • Compact Review Artifact Rendering: Updated apps/edge/internal/openai/single_request_review_stage.go to validate decision JSON containing checks and verification fields alongside output and summary. Approved review artifacts are rendered through singlerequesttemplate.RenderReview while preserving the exact tool loop, repair sequence, and final output behavior.

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

ok  	iop/packages/go/singlerequesttemplate	0.005s
ok  	iop/packages/go/config	0.161s
ok  	iop/apps/edge/internal/configrefresh	0.063s

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'

ok  	iop/apps/edge/internal/service	0.026s
ok  	iop/apps/edge/internal/openai	0.027s

API-3 — direct PlanMD tests

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

ok  	iop/apps/edge/internal/openai	0.034s

API-4 — Review template/control-loop tests

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

ok  	iop/apps/edge/internal/openai	0.046s

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

./scripts/e2e-single-request-claude.sh --self-test
[single-request-claude-smoke] self-test passed: exact Claude base-route coverage, structured observation admission, child-only zero retry, authenticated model admission, closed failure classification, model/Edge/Node/runtime binding, zero-child preflight, derived verification, redaction, cleanup, signal handling, and atomic publication

ok  	iop/apps/edge/internal/openai	12.320s
ok  	iop/apps/edge/internal/service	9.333s
ok  	iop/apps/edge/internal/configrefresh	1.152s
ok  	iop/packages/go/config	1.756s
ok  	iop/packages/go/singlerequesttemplate	1.017s

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

ok  	iop/packages/go/singlerequesttemplate	0.007s
ok  	iop/packages/go/config	0.185s
ok  	iop/apps/edge/internal/configrefresh	0.059s
ok  	iop/apps/edge/internal/service	0.026s
ok  	iop/apps/edge/internal/openai	0.077s
ok  	iop/apps/edge/internal/openai	12.320s
ok  	iop/apps/edge/internal/service	9.333s
ok  	iop/apps/edge/internal/configrefresh	1.152s
ok  	iop/packages/go/config	1.756s
ok  	iop/packages/go/singlerequesttemplate	1.017s
ok  	iop/apps/edge/cmd/edge	0.165s
ok  	iop/apps/edge/internal/authprojection	0.047s
ok  	iop/apps/edge/internal/bootstrap	0.490s
ok  	iop/apps/edge/internal/configrefresh	0.092s
ok  	iop/apps/edge/internal/controlplane	6.611s
ok  	iop/apps/edge/internal/edgecmd	0.100s
ok  	iop/apps/edge/internal/edgevalidate	0.067s
ok  	iop/apps/edge/internal/events	0.039s
ok  	iop/apps/edge/internal/input	0.086s
ok  	iop/apps/edge/internal/input/a2a	0.075s
ok  	iop/apps/edge/internal/node	0.069s
ok  	iop/apps/edge/internal/openai	8.499s
ok  	iop/apps/edge/internal/opsconsole	0.076s
ok  	iop/apps/edge/internal/service	8.255s
ok  	iop/apps/edge/internal/transport	4.806s
ok  	iop/packages/go/audit	0.013s
ok  	iop/packages/go/auth	10.034s
ok  	iop/packages/go/config	0.197s
ok  	iop/packages/go/credentiallease	0.040s
?   	iop/packages/go/events	[no test files]
ok  	iop/packages/go/execution	0.011s
ok  	iop/packages/go/hostsetup	0.013s
?   	iop/packages/go/jobs	[no test files]
?   	iop/packages/go/metadata	[no test files]
ok  	iop/packages/go/observability	0.028s
?   	iop/packages/go/policy	[no test files]
ok  	iop/packages/go/singlerequesttemplate	0.009s
ok  	iop/packages/go/streamgate	0.890s
?   	iop/packages/go/version	[no test files]
ok  	iop/packages/go/workspaceprotocol	0.015s
[single-request-claude-smoke] self-test passed: exact Claude base-route coverage, structured observation admission, child-only zero retry, authenticated model admission, closed failure classification, model/Edge/Node/runtime binding, zero-child preflight, derived verification, redaction, cleanup, signal handling, and atomic publication

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

From https://git.toki-labs.com/toki/iop
 * branch              feature/single-request-plan-review-templates -> FETCH_HEAD
 * [new branch]        feature/single-request-plan-review-templates -> origin/feature/single-request-plan-review-templates
Switched to a new branch 'feature/single-request-plan-review-templates'
branch 'feature/single-request-plan-review-templates' set up to track 'origin/feature/single-request-plan-review-templates'.
HEAD is now at b6e0080f feat(single_request): implement bounded Plan and Review Markdown templates
Removing apps/client/ios/Runner.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/
Removing apps/edge/internal/openai/chat_policy.go.bak-20260804T190533
2.1.177 (Claude Code)
sops 3.13.1

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

mkdir -p /tmp/iop-single-request-template-build/bin
GOOS=darwin GOARCH=arm64 go build -trimpath -o /tmp/iop-single-request-template-build/bin/iop-edge ./apps/edge/cmd/edge
mkdir -p /tmp/iop-single-request-template-build/bin
go build -trimpath -o /tmp/iop-single-request-template-build/bin/iop-node ./apps/node/cmd/node
OK /Users/toki/agent-work/iop-dev/build/dev-runtime/single-request-template-edge.yaml
COMMAND   PID USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
iop-edge 1542 toki    6u  IPv6 0x39a33d9e92a07a2c      0t0  TCP *:18083 (LISTEN)
COMMAND   PID USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
iop-edge 1542 toki    5u  IPv6 0x8d008f2f9e8eb50c      0t0  TCP *:18084 (LISTEN)

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

Raw SOPS failure output and resume condition:

SOPS age identity / token unavailable in environment
(exit code 69)

Resume condition: Mount or export the approved SOPS age key (dev-openai-toki.sops.yaml decryption key) into the remote shell environment to populate IOP_SINGLE_REQUEST_SMOKE_TOKEN for live API qualification. Local unit tests, race detector, and smoke self-tests are fully verified.

[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