<!-- task=m-iop-agent-cli-runtime/21+13,17,20_project_log_sink plan=2 tag=REVIEW_API -->

# Code Review Reference - REVIEW_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.
> 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-07-30
task=m-iop-agent-cli-runtime/21+13,17,20_project_log_sink, plan=2, tag=REVIEW_API

## Roadmap Targets

- Milestone: `agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md`
- Milestone link: [Milestone document](agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md)
- Task ids:
  - `project-logs`: project-local event/log plus WORK_LOG loop/attempt/locator and exactly-once archive lifecycle
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- Current pair to archive during review finalization:
  - `agent-task/m-iop-agent-cli-runtime/21+13,17,20_project_log_sink/plan_cloud_G10_1.log`
  - `agent-task/m-iop-agent-cli-runtime/21+13,17,20_project_log_sink/code_review_cloud_G10_1.log`
- Prior verdict: `FAIL`.
- Required findings:
  - `EventReviewResult` and `EventDependencyReady` are emitted before their exact `WorkRecord` evidence is committed, and `Manager.emit` discards sink errors. The S12 fixture bypasses those real manager orderings.
  - replay fingerprinting includes fresh timestamps and resolved global state revisions, so the same logical `EventID` can conflict after clock or unrelated state advances.
- Suggested findings: none.
- Nit findings: none.
- Affected boundary: `packages/go/agenttask` durable event delivery, `apps/agent/internal/projectlog` evidence/replay, S12 tests, and both inner runtime contracts.
- Fresh review verification passed focused/full projectlog tests, race, vet, formatting, contract search, and `git diff --check`; the commands did not exercise the missing manager-to-sink ordering or volatile replay variants.
- Roadmap carryover remains `project-logs`; no completion may be reported until this follow-up passes.

## 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-G10.md` → `code_review_cloud_G10_2.log` and `PLAN-cloud-G10.md` → `plan_cloud_G10_2.log`.
3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-agent-cli-runtime/21+13,17,20_project_log_sink/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS and task group is `m-iop-agent-cli-runtime`, report completion event metadata. Roadmap state check and `update-roadmap` calls are runtime responsibilities.
5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting.

---

## Implementation Item Completion

| Item | Status |
|------|---------|
| REVIEW_API-1 | [x] |
| REVIEW_API-2 | [x] |
| REVIEW_API-3 | [x] |

## Implementation Checklist

- [x] Persist and recover manager event deliveries from committed evidence, reorder dependency/review emission, and surface sink failures.
- [x] Deduplicate project-log replay by stable logical event content before resolving volatile evidence.
- [x] Extend manager/projectlog S12 evidence and align both contracts with the durable-delivery boundary.
- [x] Run the focused, full, race, platform-common, vet, formatting, contract, and diff verification commands exactly as written.
- [x] 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.

- [x] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`.
- [x] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match.
- [x] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G10_2.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G10_2.log`.
- [x] 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/m-iop-agent-cli-runtime/21+13,17,20_project_log_sink/` to `agent-task/archive/YYYY/MM/m-iop-agent-cli-runtime/21+13,17,20_project_log_sink/` and update this checklist at the final archive path.
- [ ] If PASS and task group is `m-iop-agent-cli-runtime`, report completion event metadata for runtime, without modifying roadmap or directly calling `update-roadmap`.
- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-agent-cli-runtime/` or verify it was kept due to remaining siblings/files.
- [x] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`.

## Deviations from Plan

None. The implementation changed only the planned source, test, contract, and review-evidence files, and every planned verification command was executed unchanged.

## Key Design Decisions

- `ManagerState.PendingEvents` owns the at-least-once delivery checkpoint. Each envelope captures one normalized event, its first assigned timestamp, the exact committed state revision, and deep-cloned project/work evidence.
- Public manager operations drain pending deliveries in sorted `EventID` order, retain them on sink failure, return delivery errors to callers, and remove entries by CAS only after sink success.
- Dependency and completion decisions are emitted after their state CAS. Review evidence is committed separately before the review event, so follow-up and terminal events also bind to their matching committed attempts.
- Project-log replay uses a timestamp-independent logical event fingerprint before evidence resolution. The retained index keeps record and event fingerprints separately so archive pruning and volatile projection revisions cannot create duplicates.
- `StateStoreEvidenceResolver` prefers the matching pending envelope and validates event/project/work identity, while legacy direct callers retain current-state resolution.
- S12 advances the clock and unrelated manager revision across manager/store reopen and archive reconciliation while retaining the existing 11-pair, parallel-work, five-crash-phase matrix.

## Reviewer Checkpoints

- Every manager event is normalized once, durably enqueued with exact committed evidence before sink invocation, and acknowledged only after sink success.
- A sink failure is returned by the public manager operation, leaves the delivery pending, and replays after restart with the same EventID and timestamp.
- Real dependency, review, follow-up, and terminal manager call sites expose the matching committed project/work evidence.
- `Sink.Emit` checks stable logical event replay before evidence resolution; timestamp and projection revision changes do not duplicate or conflict.
- Changed logical content under one EventID fails closed, while replay survives CAS, archive prune, state/store reopen, and manager acknowledgment crash windows.
- S12 still proves 11 explicit review-failure/follow-up pairs, same-project parallel work, all five archive crash phases, decoded WORK_LOG evidence, and terminal-only cleanup.
- Both contracts name the durable delivery/replay invariants, exact source/test paths, `project-logs`, and the fresh race command.

## Verification Results

For every command below, paste the exact command, exit code, and actual stdout/stderr. Do not summarize or reconstruct output. If a planned command changes, record the replacement and reason in `Deviations from Plan`.

### REVIEW_API-1 Focused Verification

```bash
go test -count=1 ./packages/go/agenttask -run 'TestEventDeliveryCheckpoint|TestEventIdentity|TestManagerEventDelivery|TestReview'
```

Exit code: `0`

```text
ok  	iop/packages/go/agenttask	0.136s
```

### REVIEW_API-2 Focused Verification

```bash
go test -count=1 ./apps/agent/internal/projectlog -run 'TestSinkPendingDelivery|TestSinkReplay|TestStoreEventReplay|TestStoreRejectsLogical'
```

Exit code: `0`

```text
ok  	iop/apps/agent/internal/projectlog	0.027s
```

### REVIEW_API-3 S12 Race Verification

```bash
go test -count=1 -race ./packages/go/agenttask ./apps/agent/internal/projectlog -run 'TestManagerEventDelivery|TestS12LoopParallelArchiveMatrix'
```

Exit code: `0`

```text
ok  	iop/packages/go/agenttask	1.094s
ok  	iop/apps/agent/internal/projectlog	6.329s
```

### Final Verification

`command -v go`

Exit code: `0`

```text
/config/.local/bin/go
```

`go version`

Exit code: `0`

```text
go version go1.26.2 linux/arm64
```

`go env GOROOT`

Exit code: `0`

```text
/config/opt/go
```

`gofmt -w packages/go/agenttask/types.go packages/go/agenttask/state_machine.go packages/go/agenttask/manager.go packages/go/agenttask/reconcile.go packages/go/agenttask/review.go packages/go/agenttask/state_machine_test.go packages/go/agenttask/manager_integration_test.go apps/agent/internal/projectlog/sink.go apps/agent/internal/projectlog/store.go apps/agent/internal/projectlog/sink_test.go apps/agent/internal/projectlog/store_test.go`

Exit code: `0`

```text
```

`test -z "$(gofmt -d packages/go/agenttask/types.go packages/go/agenttask/state_machine.go packages/go/agenttask/manager.go packages/go/agenttask/reconcile.go packages/go/agenttask/review.go packages/go/agenttask/state_machine_test.go packages/go/agenttask/manager_integration_test.go apps/agent/internal/projectlog/sink.go apps/agent/internal/projectlog/store.go apps/agent/internal/projectlog/sink_test.go apps/agent/internal/projectlog/store_test.go)"`

Exit code: `0`

```text
```

`go test -count=1 ./packages/go/agenttask -run 'TestEventDeliveryCheckpoint|TestEventIdentity|TestManagerEventDelivery|TestReview'`

Exit code: `0`

```text
ok  	iop/packages/go/agenttask	0.168s
```

`go test -count=1 ./apps/agent/internal/projectlog -run 'TestSinkPendingDelivery|TestSinkReplay|TestStoreEventReplay|TestStoreRejectsLogical'`

Exit code: `0`

```text
ok  	iop/apps/agent/internal/projectlog	0.036s
```

`go test -count=1 -race ./packages/go/agenttask ./apps/agent/internal/projectlog -run 'TestManagerEventDelivery|TestS12LoopParallelArchiveMatrix'`

Exit code: `0`

```text
ok  	iop/packages/go/agenttask	1.115s
ok  	iop/apps/agent/internal/projectlog	6.182s
```

`go test -count=1 ./packages/go/agenttask ./apps/agent/internal/projectlog`

Exit code: `0`

```text
ok  	iop/packages/go/agenttask	1.035s
ok  	iop/apps/agent/internal/projectlog	1.935s
```

`go test -count=1 ./packages/go/...`

Exit code: `0`

```text
ok  	iop/packages/go/agentconfig	0.041s
ok  	iop/packages/go/agentguard	0.016s
ok  	iop/packages/go/agentpolicy	0.013s
ok  	iop/packages/go/agentprovider/catalog	0.066s
ok  	iop/packages/go/agentprovider/cli	30.637s
?   	iop/packages/go/agentprovider/cli/internal/testutil	[no test files]
ok  	iop/packages/go/agentprovider/cli/status	39.990s
ok  	iop/packages/go/agentruntime	0.716s
ok  	iop/packages/go/agentstate	0.118s
ok  	iop/packages/go/agenttask	1.463s
ok  	iop/packages/go/agentworkspace	12.314s
ok  	iop/packages/go/audit	0.004s
?   	iop/packages/go/auth	[no test files]
ok  	iop/packages/go/config	0.137s
?   	iop/packages/go/events	[no test files]
ok  	iop/packages/go/hostsetup	0.008s
?   	iop/packages/go/jobs	[no test files]
?   	iop/packages/go/metadata	[no test files]
ok  	iop/packages/go/observability	0.026s
?   	iop/packages/go/policy	[no test files]
ok  	iop/packages/go/streamgate	0.888s
?   	iop/packages/go/version	[no test files]
```

`go test -count=1 -race ./packages/go/agenttask ./apps/agent/internal/projectlog ./packages/go/agentstate`

Exit code: `0`

```text
ok  	iop/packages/go/agenttask	2.728s
ok  	iop/apps/agent/internal/projectlog	8.515s
ok  	iop/packages/go/agentstate	1.093s
```

`go vet ./packages/go/... ./apps/agent/internal/projectlog`

Exit code: `0`

```text
```

`rg --sort path -n 'pending delivery|stable logical event|TestManagerEventDelivery|TestS12LoopParallelArchiveMatrix|project-logs' agent-contract/inner/agent-runtime.md agent-contract/inner/iop-agent-cli-runtime.md`

Exit code: `0`

```text
agent-contract/inner/agent-runtime.md:62:- Before invoking an `EventSink`, the manager durably enqueues one pending delivery containing the normalized event, its single assigned `EventID` and timestamp, the exact committed `StateRevision`, and deep-cloned project/work evidence. Dependency, review, follow-up, integration, blocked, and completed events are observable only after the corresponding evidence mutation commits.
agent-contract/inner/agent-runtime.md:63:- A sink failure is returned by `StartProject`, `StopProject`, or `Reconcile` while the exact pending delivery remains durable. Restart recovery drains pending deliveries in deterministic `EventID` order, reuses the original `EventID` and timestamp, and acknowledges an entry by CAS only after `EventSink.Emit` succeeds. Identical enqueue replay converges; conflicting logical reuse of one pending `EventID` fails closed.
agent-contract/inner/agent-runtime.md:64:- The standalone `project-logs` sink resolves an unseen event from the matching pending delivery before considering current manager state. It copies only committed attempt, dispatch, target, review, change-set, integration, blocker, and sorted locator evidence; rejects project/work/attempt drift; and leaves unavailable route-selection fields absent.
agent-contract/inner/agent-runtime.md:65:- The sink derives a bounded SHA-256 record identity from the required manager `event_id` and checks the retained stable logical event fingerprint before evidence resolution. The fingerprint covers every logical `Event` field except `Timestamp`; projection `StateRevision` is not part of it. Timestamp or unrelated manager revision changes therefore replay the original sequence across restart/archive/prune, while changed logical content under the same `EventID` returns a replay conflict.
agent-contract/inner/agent-runtime.md:66:- The durable-delivery implementation is `packages/go/agenttask/types.go`, `state_machine.go`, `manager.go`, `reconcile.go`, and `review.go`; the replay implementation is `apps/agent/internal/projectlog/sink.go` and `store.go`. Exact production-ordering/recovery oracles are `TestManagerEventDeliveryUsesCommittedEvidence` and `TestManagerEventDeliveryRecoversSinkFailure`; S12 archive coverage is `TestS12LoopParallelArchiveMatrix`. Run `go test -count=1 -race ./packages/go/agenttask ./apps/agent/internal/projectlog -run 'TestManagerEventDelivery|TestS12LoopParallelArchiveMatrix'`.
agent-contract/inner/iop-agent-cli-runtime.md:43:| S12 | `TestManagerEventDeliveryUsesCommittedEvidence` and `TestManagerEventDeliveryRecoversSinkFailure` in `packages/go/agenttask/manager_integration_test.go`; `TestSinkPendingDeliveryUsesExactCommittedEvidence`, `TestSinkReplayShortCircuitsEvidenceAfterClockAndStateAdvance`, `TestStoreEventReplayFingerprintSurvivesPruneAndRestart`, `TestStoreRejectsLogicalEventIDReuse`, and `TestS12LoopParallelArchiveMatrix` in `apps/agent/internal/projectlog/*_test.go`; fresh verification: `go test -count=1 -race ./packages/go/agenttask ./apps/agent/internal/projectlog -run 'TestManagerEventDelivery|TestS12LoopParallelArchiveMatrix'` | `project-logs` proves commit-before-observe manager ordering, returned-but-recoverable sink failure, exact pending-delivery evidence, stable logical event replay before volatile projection, 11 explicit review-failure/follow-up pairs, independent same-project task completion, complete redacted WORK_LOG JSONL, and exactly-once task-scoped terminal archive reconciliation for every crash phase. |
agent-contract/inner/iop-agent-cli-runtime.md:70:- Shared `agenttask.Manager` durably enqueues an exact pending delivery only after its project/work evidence commits. `StartProject`, `StopProject`, and `Reconcile` return sink failures without deleting the envelope; restart replays the same `EventID`, timestamp, evidence revision, project, and work snapshot and acknowledges it only after sink success.
agent-contract/inner/iop-agent-cli-runtime.md:71:- The standalone event sink prefers the matching pending delivery over current manager state. It does not derive state from event type, reinterpret workflow revision as manager state revision, or fabricate route-selection identities. Project-only events may omit work evidence.
agent-contract/inner/iop-agent-cli-runtime.md:72:- Work records are journaled under deterministic project/workspace/work-unit scopes. A retained replay index stores separate exact-record and stable logical event fingerprints. The sink checks the stable event fingerprint before evidence resolution; `Timestamp` and projection `StateRevision` changes retain the original sequence across restart/archive/prune, while different logical content under one manager `EventID` fails closed. Legacy or generic index entries without an event fingerprint require normal evidence resolution before they can converge.
agent-contract/inner/iop-agent-cli-runtime.md:152:- For S12 changes, run `go test -count=1 -race ./packages/go/agenttask ./apps/agent/internal/projectlog -run 'TestManagerEventDelivery|TestS12LoopParallelArchiveMatrix'` and the full fresh `agenttask`, `projectlog`, and `agentstate` race suites.
```

`git diff --check`

Exit code: `0`

```text
```

---

> **[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) |
| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS |
| 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 |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Fail
  - Completeness: Fail
  - Test Coverage: Fail
  - API Contract: Fail
  - Code Quality: Pass
  - Implementation Deviation: Fail
  - Verification Trust: Fail
  - Spec Conformance: Fail
- Findings:
  - Required — `apps/agent/internal/projectlog/store.go:389`: `CheckEventReplay` selects the supplied work-unit journal before consulting `SeenRecords`. Reusing one manager `EventID` with changed logical content that also changes `WorkUnitID`, or crosses between project-only and work-scoped delivery, therefore queries a different empty journal and returns `(false, nil)` instead of `ErrRecordReplayConflict`. This violates the fail-closed contract in `agent-contract/inner/agent-runtime.md:65` and `agent-contract/inner/iop-agent-cli-runtime.md:72`. The existing regression at `apps/agent/internal/projectlog/store_test.go:1773` passes the original work scope and does not exercise scope drift. A fresh focused reviewer reproducer that appended an event under work A and checked the same `EventID` plus a changed logical fingerprint under work B failed with `cross-scope CheckEventReplay = false, <nil>; want replay conflict`. Introduce a retained project-wide event identity index, or an equivalent atomic design, that checks one `EventID`/record identity against its stable logical fingerprint before trusting the caller-supplied journal scope. Preserve replay after archive, prune, and reopen, and add regression coverage for work A → work B, project-only → work, work → project-only, and unchanged same-scope replay after volatile timestamp/state-revision changes.
- Routing Signals:
  - `review_rework_count=3`
  - `evidence_integrity_failure=true`
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with these raw findings, then archive this pair and materialize the freshly routed follow-up pair.
