diff --git a/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/CODE_REVIEW-cloud-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/CODE_REVIEW-cloud-G07.md new file mode 100644 index 00000000..acc2c125 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,151 @@ + + +# 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-06 +task=m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing, plan=1, 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_1.log` and `PLAN-local-G06.md` → `plan_local_G06_1.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve the first-line `milestone-task=cleanup-observation` metadata in `complete.log` and report it for runtime aggregation. 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 Define closed observation and timing semantics | [ ] | + +## Implementation Checklist + +- [ ] Define a closed, copy-safe single-request observation schema and explicit allowlists that exclude all raw or unbounded values. +- [ ] Measure request total, provider-active stage, Node tool, and cleanup durations/outcomes exactly once without counting tool time as stage pure time. +- [ ] Prove timing math, terminal races, observer panic/error isolation, and secret-sentinel sanitization with a deterministic service test. +- [ ] Run dependency, focused race, package, vet, and whitespace verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** Implementers must not modify/check this section. + +- [ ] Append verdict, routing signals, dimensions, and findings. +- [ ] Archive the active pair to routed suffix `1` logs and verify `.gitignore`. +- [ ] On PASS write `complete.log`, preserve/report Milestone metadata, move this directory, and keep the parent while siblings remain. +- [ ] On WARN/FAIL write only the official next loop state. + +## Deviations from Plan + +_Record deviations and rationale._ + +## Key Design Decisions + +_Record implemented decisions._ + +## Reviewer Checkpoints + +- Confirm observation values and allowlists are closed and omit every raw/request-derived value. +- Confirm stage pure time pauses across tools and request total includes cleanup/terminal resolution. +- Confirm one terminal winner emits exactly once under success/error/cancel races. +- Confirm observer error/panic cannot alter response, cancellation, cleanup, or process ownership. + +## Verification Results + +Paste actual stdout/stderr for every command; record replacements under deviations. + +### 1. Packet 05 dependency + +`test -f agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log' | wc -l)" -eq 1` + +```text +[fill] +``` + +### 2. Packet 12 dependency + +`test -f agent-task/m-iop-owned-single-request-agent-execution/12+05,08,11_internal_tool_loop/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/12+05,08,11_internal_tool_loop/complete.log' | wc -l)" -eq 1` + +```text +[fill] +``` + +### 3. Packet 13 dependency + +`test -f agent-task/m-iop-owned-single-request-agent-execution/13+12_workspace_cleanup/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/13+12_workspace_cleanup/complete.log' | wc -l)" -eq 1` + +```text +[fill] +``` + +### 4. Focused race test + +`go test -race ./apps/edge/internal/service -run 'TestSingleRequestObservation' -count=1` + +```text +[fill] +``` + +### 5. Package regression + +`go test ./apps/edge/internal/service -count=1` + +```text +[fill] +``` + +### 6. Vet + +`go vet ./apps/edge/internal/service` + +```text +[fill] +``` + +### 7. Whitespace + +`git diff --check` + +```text +[fill] +``` + +--- + +> **[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 | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/PLAN-local-G06.md b/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/PLAN-local-G06.md new file mode 100644 index 00000000..2f549a0c --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/PLAN-local-G06.md @@ -0,0 +1,137 @@ + + +# Closed Single-request Observation Timing Semantics + +## For the Implementing Agent + +Do not start until packets 05, 12, and 13 each have `complete.log`. Define and instrument only the service-owned closed observation and timing semantics, run every listed command, and fill `CODE_REVIEW-cloud-G07.md`. Review finalization remains outside this packet. + +## Background + +The completed ingress, internal-tool, and cleanup lifecycle needs a closed, copy-safe event model and deterministic timing ownership before production metrics/log adapters can consume it. This packet defines that service boundary and proves timing and terminal behavior without adding adapters or HTTP evidence. + +## Analysis + +### Files Read + +- `apps/edge/internal/service/service.go` +- `apps/edge/internal/openai/hot_path_observation.go` +- `packages/go/observability/observability.go` +- `agent-spec/runtime/edge-node-execution.md` + +### SDD Criteria + +- S07 requires raw-free request/stage/tool/cleanup/total timing and outcomes across success/error/cancel. +- Stage pure time excludes internal-tool execution, while total time includes cleanup and terminal resolution. +- Observation failure must never change lifecycle semantics. + +### Verification Context + +- Existing Hot Path observation provides the repository pattern for closed enums, allowlists, injected sinks, and failure isolation. +- Packets 12 and 13 supply the stable lifecycle seams consumed here. +- Deterministic service tests use an injected clock and observer; no external runner is required. + +### State and Concurrency Findings + +- The terminal winner owns exactly one terminal event and one request-total event. +- Provider-active timing pauses during `internal_tool` execution and resumes on continuation. +- Observer panic/error must be contained outside request state transitions. + +### Test Coverage Gaps + +- No closed single-request observation DTO, stage-pure accumulator, or lifecycle observer exists. +- No deterministic test covers success/error/cancel races, timing math, sanitization, or observer failure. + +### Symbol References + +- Add a distinct service-owned observer; do not merge it with route-01 `hotPathObserver`. +- Instrument packet 12's tool-loop seam and packet 13's cleanup/terminal lifecycle without changing their outcomes. +- No API, wire, config, metrics adapter, bootstrap, or Node log changes belong here. + +### Split Judgment + +- The closed schema and timing state form one service-local correctness unit with a deterministic race test. +- Edge/Node adapters consume this boundary in packet 15; HTTP/spec closure follows in packet 16. + +### Scope Rationale + +- Include closed DTO/enums, explicit allowlists/sanitization, injected clock/observer, timing accumulation, lifecycle hooks, and deterministic service tests. +- Exclude Prometheus/zap production adapters, bootstrap wiring, Node logs, HTTP correlation, spec updates, and external smoke. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; build closures are true; scores 1/2/1/1/1 = G06. +- Finalizer `finalize-task-policy.sh` in `pair` mode selected `local-fit`, lane `local`, filename `PLAN-local-G06.md`. +- Build signals: `large_indivisible_context=false`; positive risks `temporal_state`, `concurrent_consistency`, `variant_product` (3); no rework or evidence-integrity failure. +- Review closures are true; scores 1/2/1/2/1 = G07; official review filename `CODE_REVIEW-cloud-G07.md`. + +## Dependencies and Execution Order + +1. Require packets 05, 12, and 13 to complete. +2. Define the closed observation contract and injected clock/observer. +3. Instrument request, stage, tool, cleanup, terminal, and total seams, then prove the timing/race invariants. + +## Implementation Checklist + +- [ ] Define a closed, copy-safe single-request observation schema and explicit allowlists that exclude all raw or unbounded values. +- [ ] Measure request total, provider-active stage, Node tool, and cleanup durations/outcomes exactly once without counting tool time as stage pure time. +- [ ] Prove timing math, terminal races, observer panic/error isolation, and secret-sentinel sanitization with a deterministic service test. +- [ ] Run dependency, focused race, package, vet, and whitespace verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-1] Define closed observation and timing semantics + +**Problem** + +- `apps/edge/internal/service/service.go:28` has no observer or clock for the packet 03/12/13 lifecycle. +- `apps/edge/internal/openai/hot_path_observation.go:1` is route-01-specific and has different states and identities. + +**Solution** + +Add service-owned closed enums for event class (`request`, `stage`, `tool`, `cleanup`, `terminal`), stage (`plan`, `work`, `review`), operation, and outcome/error class. The DTO may include a bounded generated execution correlation id for later logs, but it contains only closed identities, durations/counts, and truncated booleans. It never contains request text, public model, provider id, Node/root/path, command/template/env, tool input/output, error string, header, credential, or raw terminal. + +Add an injectable clock and failure-isolated observer snapshot on `Service`. Accumulate provider-active stage intervals around `internal_tool`, record Node tool duration once, cleanup once, terminal once, and request total after acknowledgement/cancel resolution. Unknown enum/value normalizes to empty and is dropped. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/service/service.go` — configure and snapshot the observer and clock safely. +- [ ] `apps/edge/internal/service/single_request_observation.go` — add closed DTO/enums, allowlists, sanitizer, timer accumulation, and safe emit. +- [ ] `apps/edge/internal/service/single_request.go` — add request/stage/terminal/total timing hooks. +- [ ] `apps/edge/internal/service/single_request_tool_loop.go` — add tool pause/resume timing hooks. +- [ ] `apps/edge/internal/service/single_request_observation_test.go` — cover deterministic timing, success/error/cancel/race, schema/sentinel, and observer failure. + +**Test Strategy** + +- Use a manual clock and capturing/panicking observer. Assert exact event count/order and `stage_active + tool + cleanup <= total`, with tool duration excluded from stage active time. + +**Verification** + +- `go test -race ./apps/edge/internal/service -run 'TestSingleRequestObservation' -count=1` +- Expected: timing/event ownership is deterministic and observer failure never changes terminal behavior. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/service/service.go` | API-1 | +| `apps/edge/internal/service/single_request_observation.go` | API-1 | +| `apps/edge/internal/service/single_request.go` | API-1 | +| `apps/edge/internal/service/single_request_tool_loop.go` | API-1 | +| `apps/edge/internal/service/single_request_observation_test.go` | API-1 | +| `agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/CODE_REVIEW-cloud-G07.md` | API-1 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log' | wc -l)" -eq 1` +2. `test -f agent-task/m-iop-owned-single-request-agent-execution/12+05,08,11_internal_tool_loop/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/12+05,08,11_internal_tool_loop/complete.log' | wc -l)" -eq 1` +3. `test -f agent-task/m-iop-owned-single-request-agent-execution/13+12_workspace_cleanup/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/13+12_workspace_cleanup/complete.log' | wc -l)" -eq 1` +4. `go test -race ./apps/edge/internal/service -run 'TestSingleRequestObservation' -count=1` +5. `go test ./apps/edge/internal/service -count=1` +6. `go vet ./apps/edge/internal/service` +7. `git diff --check` + +Expected: all predecessors are uniquely complete; closed timing math, terminal ownership, sanitization, and observer failure isolation pass; the service package remains clean. Cached tests are not acceptable. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_workspace_observation/CODE_REVIEW-cloud-G08.md b/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/code_review_cloud_G08_0.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_workspace_observation/CODE_REVIEW-cloud-G08.md rename to agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/code_review_cloud_G08_0.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_workspace_observation/PLAN-cloud-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/plan_cloud_G07_0.log similarity index 100% rename from agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_workspace_observation/PLAN-cloud-G07.md rename to agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/plan_cloud_G07_0.log diff --git a/agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/CODE_REVIEW-cloud-G08.md b/agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/CODE_REVIEW-cloud-G08.md new file mode 100644 index 00000000..51a1a357 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/CODE_REVIEW-cloud-G08.md @@ -0,0 +1,135 @@ + + +# 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-06 +task=m-iop-owned-single-request-agent-execution/15+14_observation_adapters, 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-G08.md` → `code_review_cloud_G08_0.log` and `PLAN-cloud-G07.md` → `plan_cloud_G07_0.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve the first-line `milestone-task=cleanup-observation` metadata in `complete.log` and report it for runtime aggregation. 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-2 Emit bounded Edge metrics/logs and safe Node events | [ ] | + +## Implementation Checklist + +- [ ] Add failure-isolated bounded Prometheus/zap observers, wire them at Edge startup, and emit raw-free Node tool/cleanup logs. +- [ ] Prove collector cardinality, exact outcome counts, duplicate-terminal protection, exact log allowlists, secret-sentinel rejection, and observer panic/error isolation. +- [ ] Preserve packet 05 ingress ownership while exposing only the bounded test correlation needed by the later closure packet. +- [ ] Run dependency, focused race, package, vet, and whitespace verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** Implementers must not modify/check this section. + +- [ ] Append verdict, routing signals, dimensions, and findings. +- [ ] Archive the active pair to routed suffix `0` logs and verify `.gitignore`. +- [ ] On PASS write `complete.log`, preserve/report Milestone metadata, move this directory, and keep the parent while siblings remain. +- [ ] On WARN/FAIL write only the official next loop state. + +## Deviations from Plan + +_Record deviations and rationale._ + +## Key Design Decisions + +_Record implemented decisions._ + +## Reviewer Checkpoints + +- Confirm metric labels are closed/bounded and omit request/stage/tool ids and every raw value. +- Confirm Edge and Node log keys are exact allowlists with path/command/output/credential sentinels rejected. +- Confirm collectors register once and duplicate terminal attempts do not double-count. +- Confirm observer error/panic cannot alter response, cancellation, cleanup, or process ownership. + +## Verification Results + +Paste actual stdout/stderr for every command; record replacements under deviations. + +### 1. Packet 14 dependency + +`test -f agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log' | wc -l)" -eq 1` + +```text +[fill] +``` + +### 2. Focused race tests + +`go test -race ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/node/internal/workspace -run 'Test(SingleRequestMetrics|SingleRequestObservationWiring|WorkspaceObservation)' -count=1` + +```text +[fill] +``` + +### 3. Package regression + +`go test ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/edge/internal/openai ./apps/node/internal/workspace -count=1` + +```text +[fill] +``` + +### 4. Vet + +`go vet ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/edge/internal/openai ./apps/node/internal/workspace` + +```text +[fill] +``` + +### 5. Whitespace + +`git diff --check` + +```text +[fill] +``` + +--- + +> **[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 | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/PLAN-cloud-G07.md b/agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/PLAN-cloud-G07.md new file mode 100644 index 00000000..342bc332 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/PLAN-cloud-G07.md @@ -0,0 +1,144 @@ + + +# Bounded Edge and Node Observation Adapters + +## For the Implementing Agent + +Do not start until packet 14 has `complete.log`. Add only the bounded Edge metrics/zap adapter, bootstrap wiring, and raw-free Node workspace observer listed below, run every command, and fill `CODE_REVIEW-cloud-G08.md`. Do not change lifecycle outcomes or add HTTP/spec closure. + +## Background + +Packet 14 supplies the closed service observation contract and deterministic timing ownership. This packet projects that contract into bounded Edge metrics/logs and adds an equivalent raw-free Node workspace completion observer without exposing request-derived metric labels or runtime secrets. + +## Analysis + +### Files Read + +- `apps/edge/internal/bootstrap/runtime.go` +- `apps/edge/internal/openai/server.go` +- `apps/edge/internal/openai/hot_path_metrics.go` +- `packages/go/observability/observability.go` +- `agent-spec/runtime/edge-node-execution.md` + +### SDD Criteria + +- S07 requires linked raw-free lifecycle observation and cleanup-preservation evidence. +- D10 forbids internal reasoning/tool protocol and raw command/path/output/credential values from observation. +- Metric labels must remain closed and bounded; observer failure must not affect runtime outcomes. + +### Verification Context + +- Packet 14 provides the service event DTO and safe observer seam consumed here. +- Packet 05 owns the no-label ingress counter; this packet only exposes the bounded correlation accessor needed later. +- Deterministic tests use a Prometheus gatherer and captured zap cores; no external runner is required. + +### State and Concurrency Findings + +- Collectors must register once and duplicate terminal attempts must not double-count. +- Production observers are installed before request handling and their failures are swallowed. +- Node tool/cleanup events must emit at common completion seams with exact key allowlists. + +### Test Coverage Gaps + +- No single-request lifecycle collectors or production zap adapter exists. +- Node workspace results have duration fields but no raw-free local observation seam. + +### Symbol References + +- Consume packet 14's service-owned observer; do not merge it with route-01 Hot Path observation. +- Extend packet 05's `single_request_metrics.go` only for its existing ingress test accessor. +- Do not change API/wire/config schemas or coordinator semantics. + +### Split Judgment + +- Edge/Node adapters and their wiring form one cross-component bounded-observation result. +- HTTP ingress-to-total correlation and living-spec synchronization remain the closure-only packet 16. + +### Scope Rationale + +- Include service Prometheus/zap adapter, collector tests, Edge bootstrap wiring, bounded ingress accessor, Node tool/cleanup observer, and raw-free tests. +- Exclude service timing semantics, HTTP integration evidence, specs, dashboards/ledger, external smoke, and semantic outcome changes. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; build closures are true; scores 2/1/1/1/2 = G07. +- Finalizer `finalize-task-policy.sh` in `pair` mode selected `risk-boundary`, lane `cloud`, filename `PLAN-cloud-G07.md`. +- Build signals: `large_indivisible_context=false`; positive risks `temporal_state`, `concurrent_consistency`, `boundary_contract`, `variant_product` (4); no rework or evidence-integrity failure. +- Review closures are true; scores 2/1/1/2/2 = G08; official review filename `CODE_REVIEW-cloud-G08.md`. + +## Dependencies and Execution Order + +1. Require packet 14's closed observation/timing boundary. +2. Add bounded Edge collectors/log projection and wire them before request handling. +3. Add the Node completion observer, then prove cardinality, allowlist, and failure-isolation behavior. + +## Implementation Checklist + +- [ ] Add failure-isolated bounded Prometheus/zap observers, wire them at Edge startup, and emit raw-free Node tool/cleanup logs. +- [ ] Prove collector cardinality, exact outcome counts, duplicate-terminal protection, exact log allowlists, secret-sentinel rejection, and observer panic/error isolation. +- [ ] Preserve packet 05 ingress ownership while exposing only the bounded test correlation needed by the later closure packet. +- [ ] Run dependency, focused race, package, vet, and whitespace verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-2] Emit bounded Edge metrics/logs and safe Node events + +**Problem** + +- Packet 05's planned `single_request_metrics.go` contains only `iop_anthropic_single_request_ingress_total`. +- Node workspace runtime has no allowlisted outcome log projection. + +**Solution** + +Create service lifecycle Prometheus histograms/counters with closed labels and a zap observer with an exact key allowlist. Register once, normalize Edge id, and expose test-only gather helpers without request-derived labels. In Edge bootstrap, install this observer on the service before input servers are created. Extend packet 05's test metric helper only as needed to compare ingress and request-total deltas later. + +Add a workspace observer at the single `Runtime.Execute`/cleanup completion seams. Its exact zap fields are execution correlation, operation, closed outcome/error code, duration, truncation, process/artifact counts; never path/content/command/env/stdout/stderr. Observer failure is swallowed. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/service/single_request_metrics.go` — add bounded collectors and production zap/metric observer. +- [ ] `apps/edge/internal/service/single_request_metrics_test.go` — cover collector labels/cardinality, exact deltas, and duplicate-terminal protection. +- [ ] `apps/edge/internal/bootstrap/runtime.go` — install the production observer before request handling. +- [ ] `apps/edge/internal/bootstrap/single_request_observation_test.go` — assert wiring and failure isolation. +- [ ] `apps/edge/internal/openai/single_request_metrics.go` — preserve ingress ownership and expose bounded test correlation only. +- [ ] `apps/node/internal/workspace/observation.go` — add raw-free Node event projection and safe zap observer. +- [ ] `apps/node/internal/workspace/runtime.go` — emit one tool event at the common completion seam. +- [ ] `apps/node/internal/workspace/cleanup.go` — emit one cleanup event. +- [ ] `apps/node/internal/workspace/observation_test.go` — cover exact key allowlist, sentinel rejection, outcome count, and observer panic/error. + +**Test Strategy** + +- Gather metrics before and after deterministic flows and inspect captured zap cores. Assert no forbidden keys/values and no request id in metric labels. + +**Verification** + +- `go test -race ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/node/internal/workspace -run 'Test(SingleRequestMetrics|SingleRequestObservationWiring|WorkspaceObservation)' -count=1` +- Expected: bounded metrics/logs emit once and cannot influence runtime outcomes. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/service/single_request_metrics.go` | API-2 | +| `apps/edge/internal/service/single_request_metrics_test.go` | API-2 | +| `apps/edge/internal/bootstrap/runtime.go` | API-2 | +| `apps/edge/internal/bootstrap/single_request_observation_test.go` | API-2 | +| `apps/edge/internal/openai/single_request_metrics.go` | API-2 | +| `apps/node/internal/workspace/observation.go` | API-2 | +| `apps/node/internal/workspace/runtime.go` | API-2 | +| `apps/node/internal/workspace/cleanup.go` | API-2 | +| `apps/node/internal/workspace/observation_test.go` | API-2 | +| `agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/CODE_REVIEW-cloud-G08.md` | API-2 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log' | wc -l)" -eq 1` +2. `go test -race ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/node/internal/workspace -run 'Test(SingleRequestMetrics|SingleRequestObservationWiring|WorkspaceObservation)' -count=1` +3. `go test ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/edge/internal/openai ./apps/node/internal/workspace -count=1` +4. `go vet ./apps/edge/internal/service ./apps/edge/internal/bootstrap ./apps/edge/internal/openai ./apps/node/internal/workspace` +5. `git diff --check` + +Expected: packet 14 is uniquely complete; bounded collectors and raw-free Edge/Node logs emit once, observer failures are isolated, and affected packages remain clean. Cached tests are not acceptable. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.** diff --git a/agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/CODE_REVIEW-cloud-G03.md b/agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/CODE_REVIEW-cloud-G03.md new file mode 100644 index 00000000..077fe97a --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/CODE_REVIEW-cloud-G03.md @@ -0,0 +1,152 @@ + + +# 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-06 +task=m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence, 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-G03.md` → `code_review_cloud_G03_0.log` and `PLAN-local-G03.md` → `plan_local_G03_0.log`. +3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill. +4. If PASS, preserve the first-line `milestone-task=cleanup-observation` metadata in `complete.log` and report it for runtime aggregation. 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-3 Link ingress, lifecycle, and documented evidence | [ ] | + +## Implementation Checklist + +- [ ] Prove a real marked Anthropic POST links ingress, request-total, terminal, stage/tool/cleanup counts, and raw-free correlation without public tool protocol. +- [ ] Synchronize input/runtime specs with stage-pure, cardinality, privacy, and deterministic evidence semantics while explicitly deferring external Claude/Mac smoke. +- [ ] Keep production handler, lifecycle, metrics, and log schemas unchanged. +- [ ] Run dependency, HTTP, package, vet, documentation, and whitespace verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Review-Only Checklist + +> **[REVIEW AGENT ONLY]** Implementers must not modify/check this section. + +- [ ] Append verdict, routing signals, dimensions, and findings. +- [ ] Archive the active pair to routed suffix `0` logs and verify `.gitignore`. +- [ ] On PASS write `complete.log`, preserve/report Milestone metadata, move this directory, and keep the parent while siblings remain. +- [ ] On WARN/FAIL write only the official next loop state. + +## Deviations from Plan + +_Record deviations and rationale._ + +## Key Design Decisions + +_Record implemented decisions._ + +## Reviewer Checkpoints + +- Confirm one marked POST produces exactly one ingress, request-total, and terminal observation. +- Confirm expected stage/tool/cleanup deltas and safe generated correlation agree across captured evidence. +- Confirm public output and logs contain no private tool protocol or raw sentinels. +- Confirm specs describe only deterministic evidence and explicitly defer external Claude/Mac smoke. +- Confirm no production file changed in this closure packet. + +## Verification Results + +Paste actual stdout/stderr for every command; record replacements under deviations. + +### 1. Packet 14 dependency + +`test -f agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log' | wc -l)" -eq 1` + +```text +[fill] +``` + +### 2. Packet 15 dependency + +`test -f agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/complete.log' | wc -l)" -eq 1` + +```text +[fill] +``` + +### 3. HTTP evidence + +`go test ./apps/edge/internal/openai -run 'TestAnthropicSingleRequestObservation' -count=1` + +```text +[fill] +``` + +### 4. Package regression + +`go test ./apps/edge/internal/openai -count=1` + +```text +[fill] +``` + +### 5. Vet + +`go vet ./apps/edge/internal/openai` + +```text +[fill] +``` + +### 6. Spec search + +`rg --sort path -n 'stage.*pure|tool.*duration|cleanup|total|raw|cardinality|Claude.*defer' agent-spec/input/openai-compatible-surface.md agent-spec/runtime/edge-node-execution.md` + +```text +[fill] +``` + +### 7. Whitespace + +`git diff --check` + +```text +[fill] +``` + +--- + +> **[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 | diff --git a/agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/PLAN-local-G03.md b/agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/PLAN-local-G03.md new file mode 100644 index 00000000..2e08f5a6 --- /dev/null +++ b/agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/PLAN-local-G03.md @@ -0,0 +1,130 @@ + + +# Linked Single-request Observation Evidence + +## For the Implementing Agent + +Do not start until packets 14 and 15 each have `complete.log`. Add only the real-POST ingress/lifecycle correlation assertions and living-spec synchronization listed below, run every command, and fill `CODE_REVIEW-cloud-G03.md`. Do not alter production lifecycle or observation behavior. + +## Background + +Packets 14 and 15 provide deterministic timing ownership and bounded Edge/Node observers. S07 still needs one synthetic HTTP flow that links ingress, request-total, terminal, stage/tool/cleanup counts, and raw-free logs, plus current living-spec documentation that explicitly defers real Claude/Mac evidence. + +## Analysis + +### Files Read + +- `apps/edge/internal/openai/server.go` +- `agent-spec/input/openai-compatible-surface.md` +- `agent-spec/runtime/edge-node-execution.md` + +### SDD Criteria + +- S07 requires linked request/stage/tool/cleanup/total timing and outcome evidence across the single-request path. +- S12 owns later actual Claude/Mac evidence; this packet must claim deterministic synthetic evidence only. +- D10 requires internal tools and raw values to remain absent from outer output and observation. + +### Verification Context + +- Packet 12's real marked POST fixture already exercises multiple internal tools. +- Packets 14 and 15 provide lifecycle metric accessors and captured raw-free logs. +- A focused endpoint test and deterministic documentation search are sufficient; no external runner is required. + +### State and Concurrency Findings + +- One marked POST must produce ingress=1, request-total=1, terminal=1, and the expected closed stage/tool/cleanup deltas. +- Correlation may use only the bounded generated execution id in logs and never a request-derived metric label. +- Production behavior is frozen by the predecessor packets; this closure packet changes tests and specs only. + +### Test Coverage Gaps + +- No real-POST assertion currently links ingress to lifecycle metrics and safe logs. +- Living specs do not yet state stage-pure/cardinality/privacy semantics for this path. + +### Symbol References + +- Extend packet 12's `single_request_handler_test.go` fixture; do not change handler production code. +- Consume the bounded metric/log accessors from packet 15. +- Keep external Claude/Mac timing evidence explicitly deferred to `claude-smoke`. + +### Split Judgment + +- This is the allowed integration/closure-only child: one endpoint evidence result and its matching living-spec statements. +- It has no production write set and must remain downstream of both predecessor children. + +### Scope Rationale + +- Include real-POST lifecycle delta/log privacy assertions and the two living-spec updates. +- Exclude all production code, new metrics/log fields, dashboards/ledger, and external smoke. + +### Final Routing + +- `evaluation_mode=isolated-reassessment`; build closures are true; scores 1/0/0/1/1 = G03. +- Finalizer `finalize-task-policy.sh` in `pair` mode selected `local-fit`, lane `local`, filename `PLAN-local-G03.md`. +- Build signals: `large_indivisible_context=false`; no matched loop-risk signatures, rework, or evidence-integrity failure. +- Review closures are true; scores 1/0/0/1/1 = G03; official review filename `CODE_REVIEW-cloud-G03.md`. + +## Dependencies and Execution Order + +1. Require packet 14's timing semantics and packet 15's production adapters. +2. Extend the real marked POST fixture with closed metric deltas and safe-log correlation assertions. +3. Synchronize input/runtime living specs with only the proven deterministic behavior. + +## Implementation Checklist + +- [ ] Prove a real marked Anthropic POST links ingress, request-total, terminal, stage/tool/cleanup counts, and raw-free correlation without public tool protocol. +- [ ] Synchronize input/runtime specs with stage-pure, cardinality, privacy, and deterministic evidence semantics while explicitly deferring external Claude/Mac smoke. +- [ ] Keep production handler, lifecycle, metrics, and log schemas unchanged. +- [ ] Run dependency, HTTP, package, vet, documentation, and whitespace verification. +- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output. + +## Implementation Plan + +### [API-3] Link ingress, lifecycle, and documented evidence + +**Problem** + +- S07 evidence needs one linked synthetic flow and specs describing pure-time/cardinality/privacy semantics; current living specs have only generic/route-01 observation. + +**Solution** + +Extend packet 12's real-POST test to snapshot ingress and lifecycle metrics, run multiple stages/tools plus cleanup, and assert deltas: ingress=1, request-total=1, terminal=1, and the expected stage/tool/cleanup counts. Capture logs using the safe generated correlation id and verify forbidden sentinels are absent. Keep actual Claude/Mac timing evidence explicitly deferred to `claude-smoke`. + +**Modified Files and Checklist** + +- [ ] `apps/edge/internal/openai/single_request_handler_test.go` — add ingress/lifecycle delta and raw-free correlation integration assertions. +- [ ] `agent-spec/input/openai-compatible-surface.md` — document ingress/terminal correlation and privacy. +- [ ] `agent-spec/runtime/edge-node-execution.md` — document stage-pure/tool/cleanup/total timing, labels, Node logs, and external-smoke deferral. + +**Test Strategy** + +- Add or extend `TestAnthropicSingleRequestObservation` using the real marked POST fixture and deterministic internal tools. + +**Verification** + +- `go test ./apps/edge/internal/openai -run 'TestAnthropicSingleRequestObservation' -count=1` +- `rg --sort path -n 'stage.*pure|tool.*duration|cleanup|total|raw|cardinality|Claude.*defer' agent-spec/input/openai-compatible-surface.md agent-spec/runtime/edge-node-execution.md` +- Expected: one synthetic request links all closed timing/outcome evidence and docs do not claim external smoke. + +## Modified Files Summary + +| File | Item | +|------|------| +| `apps/edge/internal/openai/single_request_handler_test.go` | API-3 | +| `agent-spec/input/openai-compatible-surface.md` | API-3 | +| `agent-spec/runtime/edge-node-execution.md` | API-3 | +| `agent-task/m-iop-owned-single-request-agent-execution/16+14,15_observation_evidence/CODE_REVIEW-cloud-G03.md` | API-3 | + +## Final Verification + +1. `test -f agent-task/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/14+05,12,13_observation_timing/complete.log' | wc -l)" -eq 1` +2. `test -f agent-task/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/15+14_observation_adapters/complete.log' | wc -l)" -eq 1` +3. `go test ./apps/edge/internal/openai -run 'TestAnthropicSingleRequestObservation' -count=1` +4. `go test ./apps/edge/internal/openai -count=1` +5. `go vet ./apps/edge/internal/openai` +6. `rg --sort path -n 'stage.*pure|tool.*duration|cleanup|total|raw|cardinality|Claude.*defer' agent-spec/input/openai-compatible-surface.md agent-spec/runtime/edge-node-execution.md` +7. `git diff --check` + +Expected: packets 14 and 15 are uniquely complete; one synthetic request links bounded lifecycle evidence without raw values; the living specs defer external smoke; the affected package remains clean. Cached tests are not acceptable. + +**After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.**