<!-- task=m-iop-hot-path-one-shot-execution/10+07,09_light_flow plan=0 tag=API milestone-task=light-flow -->

# Light Plan, Local Work, Review, and Repair Flow

## For the Implementing Agent

Start only after predecessors 07 and 09 complete. Implement, run all verification, and fill `CODE_REVIEW-cloud-G10.md` with actual notes/output. Keep active files for official review. If blocked, record exact evidence and resume condition only; do not ask the user, create control state, classify, archive, or write `complete.log`.

## Background

With identity, structural selection, and artifact mapping available, `light` can be implemented as one selector/planner stage, local worker, and one fixed cloud review stage. Stage inputs and route bindings must remain immutable, visible output must continue, and review resolution must rely on model/tool flow rather than Edge reading or parsing `review.md`.

## Dependencies and Execution Order

- `07+02,04,06_route_selector_direct` and `09+06,08_artifact_pair` must produce `complete.log`; their own predecessors are transitively satisfied.

## Analysis

### Files Read

- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md`
- `apps/edge/internal/openai/chat_handler.go`
- `apps/edge/internal/openai/anthropic_handler.go`
- `apps/edge/internal/openai/dispatch_context.go`
- `apps/edge/internal/openai/anthropic_surface_test.go`
- `apps/edge/internal/openai/stream_gate_ingress_test.go`
- `agent-spec/runtime/stream-evidence-gate.md`
- `agent-contract/inner/edge-node-runtime-wire.md`

### SDD Criteria

Approved/unlocked SDD; task/scenario/Evidence row S08. Evidence must prove immutable stage inputs, pair-success transition, local work/tool loops, completion terminal transition, review write then same-stage review resolution, pass and defect repair, no Edge file read/text verdict, and no second review loop.

### Verification Context

No handoff. Deterministic fake services and normalized event fixtures can drive all stages; no real agent/workspace/provider is needed for S08. Fresh and race tests required. Endpoint multi-stage codec polish remains Epic 3, but internal transition evidence must use current Stream Evidence Gate terminal semantics. Confidence: medium-high due to state/product complexity.

### Test Coverage Gaps

Current stream tests cover one provider stage and recovery, not ordered model-stage transitions or prompt isolation. Add a scripted stage service and state-machine tests for Chat/Messages pass/repair and failures.

### Symbol References

No rename/removal. Extend the `hot_path_dispatch.go` hook from child 07; add new stage/input builders rather than duplicate endpoint handlers.

### Split Judgment

This unchanged pair depends exactly on 07/09. `local` and `review` remain one packet because the committed local terminal correlation is the transaction boundary for reviewer input and a complete S08 cannot independently PASS either half. Cleanup remains pair 11 because the flow can reach `cleanup_pending` without claiming final success.

### Scope Rationale

Exclude second review loops, heavy mode, Edge filesystem reads, review text parsing, hidden provider calls after disconnect, final cleanup/TTL, cross-stage public id/usage remapping, and external agent smoke.

### Final Routing

`evaluation_mode=first-pass`; `finalizer=finalize-task-policy.sh` pair. Build closures true, scores `(2,2,2,2,2)` => G10 grade-boundary cloud; `large_indivisible_context=false`, risks `temporal_state,concurrent_consistency,boundary_contract,structured_interpretation,variant_product` (5), rework 0, evidence-integrity false, no gap; `PLAN-cloud-G10.md`. Review scores `(2,2,2,2,2)` => official cloud G10, `CODE_REVIEW-cloud-G10.md`, Codex `gpt-5.6-sol` xhigh.

## Implementation Checklist

- [ ] Transition exact Plan/Review pair success into an immutable local stage with visible content/tool loops and terminal correlation.
- [ ] Run one fixed cloud review stage through write, read-resolution, pass or defect repair, then stop at cleanup_pending without Edge file reads or a second review.
- [ ] Run scripted flow, isolation, common race, vet, and diff verification exactly as written.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] Run the isolated local worker stage

#### Problem

Current dispatch contexts represent one request/provider (`dispatch_context.go` and handler flows), while SDD lines 67-71 require pair success to switch to a pinned local route and prompt without copying workspace file contents.

#### Solution

Build local input only from immutable user task, committed selector correlation, and issued plan/review paths. Resolve the pinned canonical local reference via the child-04 route authorization, revalidate current credential revision, release content/reasoning/general tools, resume tool frontiers on the same stage, and treat Stream Evidence Gate completion as transition evidence to one reviewer.

```go
// Before: artifact success only proves local eligibility.

// After
localInput := buildLocalStageInput(req.ImmutableTask, req.ArtifactPaths, req.SelectorCommit)
terminal := runPinnedStage(req.Stage(localRole), localInput)
req.CommitLocalCandidate(terminal.Correlation)
```

#### Modified Files and Checklist

- [ ] `apps/edge/internal/openai/hot_path_stage_input.go` — isolated selector/local/review input builders.
- [ ] `apps/edge/internal/openai/hot_path_light.go` — local state transitions and pinned-stage dispatch.
- [ ] `apps/edge/internal/openai/hot_path_dispatch.go` — invoke light after exact pair success.
- [ ] `apps/edge/internal/openai/hot_path_light_test.go` — scripted local content/tool/completion and input isolation.

#### Test Strategy

Write `TestHotPathLightLocalTransition` and `TestHotPathStageInputIsolation`. Assert both pair results required, immutable task and two paths present, file contents/credentials/internal prompts absent, wrong route revision fails, tool loop resumes same stage, and one completion candidate starts one review.

#### Verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(LightLocal|StageInput)'
```

Expect PASS.

### [API-2] Run one review write/resolution and optional repair

#### Problem

No current state keeps review write, read-resolution, and repair on one cloud route/model. The Edge must not read the file or parse review prose, and repair must not trigger a second review (`SDD.md:71-73,134-143`).

#### Solution

Pin a single review stage binding and explicit subphase. Emit canonical review write, validate its mapped result, and resume the same stage with a canonical read operation. Decide only from normalized structure: a completion terminal with no repair tool frontier is pass and goes to `cleanup_pending`; ordinary repair/verification tool calls keep the same review stage active until its later completion, which then goes to `cleanup_pending`. Do not add or parse a verdict marker, review prose, hidden control text, or a second review. Reject attempts to re-enter selector/local.

```go
// Before: no review state.

// After
review_active -> review_write_wait -> review_resolution_active
review_resolution_active -> agent_tool_wait | cleanup_pending
```

#### Modified Files and Checklist

- [ ] `apps/edge/internal/openai/hot_path_review.go` — pinned review subphases, write/read mapping, pass/repair transition.
- [ ] `apps/edge/internal/openai/hot_path_review_test.go` — pass/defect/repair/no-second-review tables for both endpoints.

#### Test Strategy

Write `TestHotPathReviewPass` and `TestHotPathReviewDefectRepair`. Use only provider events and tool results, never fixture file reads. Assert review route identity remains fixed, review write success precedes resolution, a completion-without-repair is pass, ordinary repair tools are visible and remain in the same stage, prose verdict words have no effect, and cleanup pending is reached exactly once.

#### Verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Review|Light)'
```

Expect PASS.

## Modified Files Summary

| File | Items |
|------|-------|
| `apps/edge/internal/openai/hot_path_stage_input.go` | API-1 |
| `apps/edge/internal/openai/hot_path_light.go` | API-1 |
| `apps/edge/internal/openai/hot_path_dispatch.go` | API-1 |
| `apps/edge/internal/openai/hot_path_light_test.go` | API-1 |
| `apps/edge/internal/openai/hot_path_review.go` | API-2 |
| `apps/edge/internal/openai/hot_path_review_test.go` | API-2 |
| `agent-task/m-iop-hot-path-one-shot-execution/10+07,09_light_flow/CODE_REVIEW-cloud-G10.md` | API-1, API-2 |

## Final Verification

```bash
test -f agent-task/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/complete.log
test -f agent-task/m-iop-hot-path-one-shot-execution/09+06,08_artifact_pair/complete.log
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Light|Review|StageInput)'
go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service
go vet ./apps/edge/internal/openai
git diff --check
```

Expected: all exit 0; pass and defect repair each reach cleanup pending once; stage inputs remain isolated; no test permits Edge file reads or a second review. Cache is not acceptable. After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
