<!-- task=m-iop-owned-single-request-agent-execution/20+19_review_repair plan=2 tag=API milestone-task=review-stage -->

# Review and bounded repair stage

## For the Implementing Agent

Filling the implementation-owned sections of `CODE_REVIEW-cloud-G07.md` is the mandatory last implementation step. Run every verification command, paste actual output, keep both active files in place, and report ready for review; only the official code-review skill may append a verdict, archive files, write `complete.log`, or classify the next state. If blocked, record the exact blocker, attempted commands/output, and resume condition only in the review evidence fields; do not ask the user, call a user-input tool, create a control-plane stop file, or change the owner or scope.

## Background

The artifact, Plan, and Work packets establish service-owned lifecycle and private provider/tool primitives without installing a production executor. This child implements the Gemini Review stage itself: strict pass, direct inspection, bounded repair/re-review, durable REVIEW evidence, and reviewer-approved output. Composite construction and production installation remain in dependent children.

## Archive Evidence Snapshot

- Original parent plan: `agent-task/m-iop-owned-single-request-agent-execution/20+19_review_repair/plan_cloud_G09_1.log`.
- Original parent review stub: `agent-task/m-iop-owned-single-request-agent-execution/20+19_review_repair/code_review_cloud_G09_1.log`.
- Earlier self-review snapshots remain `plan_cloud_G09_0.log` and `code_review_cloud_G09_0.log`; neither archived pair contains implementation evidence or an official verdict.
- The parent was split once into Review/repair, composite executor, and production activation children without changing its implementation or verification scope.

## Analysis

### Files Read

- The original parent PLAN/CODE_REVIEW pair and its recorded source, test, contract, and SDD findings.
- No source, test, archived log body, or verification output was reread for this refinement.

### SDD Criteria

- This child contributes `review-stage`.
- S10 requires Gemini high-reasoning Review, strict pass, permitted reviewer inspection, one IOP-owned repair call at a time, legal saved-stage restoration, re-review after repair, REVIEW persistence, and only then finalization.
- The lifecycle permits `reviewing -> internal_tool|repairing|finalizing` and `repairing -> internal_tool|finalizing`; it does not permit `repairing -> reviewing`.

### Verification Context

- Deterministic provider and workspace-tool fixtures prove the Review stage without remote credentials or an external runner.
- Actual Claude/Mac full-cycle qualification remains the separate S12 `claude-smoke` task.

### Test Coverage Gaps

- No provider runner currently proves direct reviewer inspection or repair/re-review semantics.
- No test proves that re-review dispatch occurs while controller state remains `repairing`, or that reviewer-approved output is returned only after durable REVIEW evidence.

### Symbol References

- `isValidTransition` in `apps/edge/internal/service/single_request.go` remains the lifecycle oracle and is not modified.
- The predecessor's provider-stage codec, controller artifact API, and request-safe continuation bridge are reused.

### Split Judgment

- This child owns the cohesive Review/inspection/repair state machine in one production file and its deterministic tests.
- `21+20_single_request_executor` consumes its approved output contract to compose Plan, Work, and Review.
- `22+21_executor_activation` installs the proven composite and synchronizes current documentation.
- The children created in this refinement are not recursively split.

### Scope Rationale

Include only Review prompt/result decoding, direct inspection, repair/re-review, durable REVIEW write, finalization ordering, bounded correlation, and their tests. Exclude composite construction, production installation, public schema changes, generic error/cancel quality work, and external qualification.

### Final Routing

- `evaluation_mode=isolated-reassessment`; all build/review closures are true; no capability gap.
- Build scores `1/2/1/1/2` => G07, base `local-fit`; loop risks `temporal_state`, `concurrent_consistency`, `boundary_contract`, `structured_interpretation` (4) select `risk-boundary`, `worker/cloud/G07`, `PLAN-cloud-G07.md`.
- Review scores `1/2/1/1/2` => G07, `official-review`, `review/cloud/G07`, `CODE_REVIEW-cloud-G07.md`.
- `large_indivisible_context=false`; `review_rework_count=0`; `evidence_integrity_failure=false`; finalizer `finalize-task-policy.sh`, mode `pair`.

## Dependencies and Execution Order

1. Before implementation or review, run the exact dependency command in Final Verification. It must print exactly one task-19 completion path from active or archive storage and exit zero.
2. Read only that resolved `complete.log`, then consume the completed Work result and continuation bridge contracts without reopening predecessor ownership.
3. Prove strict pass, direct inspection, and repair/re-review before reporting this child ready for review.

## Implementation Checklist

- [ ] Implement Gemini high-reasoning Review with strict pass, direct non-mutating inspection, REVIEW persistence before finalization, and fail-closed bounded results.
- [ ] Implement one-tool-at-a-time repair with `repairing -> internal_tool(saved repairing) -> repairing`, re-review dispatch while state remains repairing, and no invalid `repairing -> reviewing` transition.
- [ ] Add pass, inspection, repair, correlation, limits, cancellation, failure, artifact-ordering, and waiter-cleanup fixtures under `-race`.
- [ ] Run dependency, focused race, service compatibility, OpenAI vet/regression, deterministic state search, unchanged-transition, and diff checks.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] Implement strict Review, inspection, and persisted pass evidence

**Problem**

Work returns only a private completion candidate and verification evidence. Returning it directly would skip independent Review, while reviewer inspection must use the existing saved-stage tool path rather than a caller continuation.

**Solution**

Add `single_request_review_stage.go`. Read PLAN, accept bounded Work evidence, submit `reviewing`, and dispatch a fixed Gemini high request. Decode only strict pass, one admitted non-mutating inspection call, or one admitted repair call. Inspection records `reviewing -> internal_tool(saved reviewing) -> reviewing`; pass writes `SingleRequestArtifactReview` before `finalizing` and returns only approved output.

**Modified Files and Checklist**

- [ ] Add prompt, high-option dispatch, closed result decoding, inspection loop, write-before-finalize ordering, and bounded DTOs in `apps/edge/internal/openai/single_request_review_stage.go`.
- [ ] Add pass, direct inspection, exact request body, malformed/mixed/multiple/provider error, artifact failure, bounds, and cancellation tests in `apps/edge/internal/openai/single_request_review_stage_test.go`.

**Test Strategy**

Use deterministic provider/tool fakes and a recording controller. Assert the saved-stage inspection sequence, high reasoning on every Review request, durable REVIEW before finalizing, exact correlation, and no private candidate/error leakage.

**Verification**

Run the focused ReviewStage race test in Final Verification.

### [API-2] Drive bounded repair and re-review without a false state edge

**Problem**

The service restores `repairing` after every repair tool result and rejects `repairing -> reviewing`. Re-review must therefore dispatch while lifecycle state remains `repairing`.

**Solution**

On a mutating defect call, submit `repairing`, execute one admitted tool through `internal_tool` with saved `repairing`, restore `repairing`, append a bounded sanitized exchange, and redispatch Gemini Review without changing state to `reviewing`. Only a later strict pass may persist REVIEW and submit `finalizing`.

**Modified Files and Checklist**

- [ ] Add repair/re-review behavior to `apps/edge/internal/openai/single_request_review_stage.go` using the predecessor bridge and controller API.
- [ ] Add pass-after-repair, repeated bounded tool, correlation, failure, stale/duplicate result, cancellation, and waiter-cleanup fixtures in `apps/edge/internal/openai/single_request_review_stage_test.go`.
- [ ] Assert re-review dispatch occurs while recorded lifecycle state is `repairing` and no code or test attempts `repairing -> reviewing`.

**Test Strategy**

Record states separately from provider dispatches and prove finalization occurs only after strict pass plus durable REVIEW.

**Verification**

Run focused Review race tests and the deterministic state-order search; keep the canonical service transition file unchanged.

## Modified Files Summary

| File | Items |
|------|-------|
| `apps/edge/internal/openai/single_request_review_stage.go` | API-1, API-2 |
| `apps/edge/internal/openai/single_request_review_stage_test.go` | API-1, API-2 |
| `agent-task/m-iop-owned-single-request-agent-execution/20+19_review_repair/CODE_REVIEW-cloud-G07.md` | API-1, API-2 |

## Final Verification

Fresh output is required; Go tests use `-count=1` and cached output is not acceptable.

1. `bash -c 'set -euo pipefail; shopt -s nullglob; candidates=(agent-task/m-iop-owned-single-request-agent-execution/19_*/complete.log agent-task/m-iop-owned-single-request-agent-execution/19+*/complete.log agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/19_*/complete.log agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/19+*/complete.log); printf "%s\n" "${candidates[@]}"; ((${#candidates[@]} == 1))'` — prints exactly one predecessor completion path and exits zero.
2. `go test -race ./apps/edge/internal/openai -run 'TestSingleRequestReviewStage' -count=1` — pass, direct inspection, repair/re-review, correlation, cancellation, and failure fixtures pass without races.
3. `go test ./apps/edge/internal/service -run 'TestSingleRequest(InternalToolLoop|Cleanup|EnvelopeOrdering)' -count=1` — unchanged coordinator state and cleanup invariants pass freshly.
4. `go vet ./apps/edge/internal/openai && go test ./apps/edge/internal/openai -count=1` — the changed package vets cleanly and its regressions pass.
5. `rg --sort path -n 'reasoning_effort|SingleRequestArtifactReview|finalizing|repairing|reviewing' apps/edge/internal/openai/single_request_review_stage.go apps/edge/internal/openai/single_request_review_stage_test.go` — high Review, legal repair, durable REVIEW, and finalization ordering are explicit; no `repairing -> reviewing` behavior is introduced.
6. `test ! -e apps/edge/internal/openai/single_request_executor.go && bash -c 'set -euo pipefail; if rg --sort path -n "NewSingleRequestExecutor|SetSingleRequestExecutor" apps/edge/internal/input/manager.go; then exit 1; else test $? -eq 1; fi'` — exits zero with no output only when composite construction and production installation remain deferred.
7. `git diff --exit-code HEAD -- apps/edge/internal/service/single_request.go` — the canonical service transition table remains unchanged.
8. `git diff --check` — no whitespace errors.

Actual provider/Claude full-cycle evidence remains owned by S12 `claude-smoke`.

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
