<!-- task=m-iop-agent-cli-runtime/21+13,17,20_project_log_sink plan=1 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=1, 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_local_G08_0.log`
  - `agent-task/m-iop-agent-cli-runtime/21+13,17,20_project_log_sink/code_review_cloud_G08_0.log`
- Prior verdict: `FAIL`.
- Required findings:
  - `EmitWithLocators` was test-only; production `Emit` discarded exact manager locators and synthesized route/state identities.
  - `TestS12LoopParallelArchiveMatrix` used separate project/workspace stores and no archive failure hooks; the archive timeline remained the legacy projection.
  - append was not idempotent by durable event identity, so replay before or after archive could duplicate records and archive ordinals; raw `Detail` leaked into the persisted `RecordID`.
  - the standalone contract used `project-log-sink` instead of `project-logs` and omitted exact S12 test paths.
- Fresh reviewer verification passed formatting, focused/full tests, race, vet, and `git diff --check`, but those commands did not repair the production-path evidence gaps.
- Roadmap carryover remains `project-logs`; no completion may be reported until the 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_1.log` and `PLAN-cloud-G10.md` → `plan_cloud_G10_1.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] Resolve production `Sink.Emit` from exact durable task evidence, remove placeholder identity synthesis, and use bounded opaque record ids.
- [x] Partition task journals under one project/workspace, make append/archive replay idempotent across restart, and archive the full WORK_LOG projection.
- [x] Rebuild the named S12 matrix through production `Emit` and align both contracts with exact source, test, command, and `project-logs` evidence.
- [x] Run the focused, full, race, 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_1.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G10_1.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 stayed within the planned files and ran every verification command exactly as written.

## Key Design Decisions

- `StateStoreEvidenceResolver` binds production `Sink.Emit` to one exact manager state revision and `WorkRecord`; project-scoped events are the only events allowed to omit work evidence.
- Manager `EventID` values are required and projected as bounded SHA-256 record IDs. A persistent record-ID index retains the original sequence and canonical fingerprint after terminal prune, so identical replay converges while conflicting reuse fails closed.
- Work events are routed to deterministic work-unit journals below the project/workspace store. Each task owns independent sequences, archive roots, and archive ordinals, while project-only append/replay/archive operations remain available.
- Archive reconciliation reconstructs a missing JSONL artifact from the exact journal prefix and durable intent, then verifies the complete immutable artifact set before pruning. Timeline artifacts encode complete redacted `WorkLogEntry` JSONL.
- The S12 fixture uses one project/workspace, two task scopes, 11 explicit review-failure/follow-up pairs, production `Emit`, durable state/store reopen boundaries, all five archive failure phases, and post-archive replay.

## Reviewer Checkpoints

- `Sink.Emit` alone resolves exact durable state evidence; `EmitWithLocators` and every placeholder identity are absent.
- identical `EventID` replay converges before and after archive/restart; conflicting content fails closed and raw detail is absent from `RecordID`.
- same-project work units own independent journals and archive ordinals without blocking each other's dynamic frontier.
- archived timeline JSONL decodes as complete redacted WORK_LOG entries with exact loop, attempt, dispatch, role/result, and locator identity.
- the named S12 fixture executes 11 explicit retry/follow-up pairs, all five archive failure phases, restart, replay, and terminal-only cleanup under race.
- both contracts name `project-logs`, exact source/test paths, 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 ./apps/agent/internal/projectlog -run 'TestSink|TestTimeline|TestRecord'
```

Exit code: `0`

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

### REVIEW_API-2 Focused Verification

```bash
go test -count=1 ./apps/agent/internal/projectlog -run 'TestStoreReplay|TestStoreRejectsConflicting|TestStoreScopesParallel|TestArchive'
```

Exit code: `0`

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

### REVIEW_API-3 S12 Race Verification

```bash
go test -count=1 -race ./apps/agent/internal/projectlog -run TestS12LoopParallelArchiveMatrix
```

Exit code: `0`

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

### Final Verification

```bash
gofmt -w apps/agent/internal/projectlog/*.go
test -z "$(gofmt -d apps/agent/internal/projectlog/*.go)"
go test -count=1 ./apps/agent/internal/projectlog -run 'TestSink|TestTimeline|TestRecord|TestStoreReplay|TestStoreRejectsConflicting|TestStoreScopesParallel|TestS12LoopParallelArchiveMatrix'
go test -count=1 ./apps/agent/internal/projectlog
go test -count=1 -race ./apps/agent/internal/projectlog ./packages/go/agentstate
go vet ./apps/agent/internal/projectlog
rg --sort path -n 'implemented S12 source|\\| S12 \\|' agent-contract/inner/iop-agent-cli-runtime.md
git diff --check
```

`gofmt -w apps/agent/internal/projectlog/*.go`

Exit code: `0`

```text
```

`test -z "$(gofmt -d apps/agent/internal/projectlog/*.go)"`

Exit code: `0`

```text
```

`go test -count=1 ./apps/agent/internal/projectlog -run 'TestSink|TestTimeline|TestRecord|TestStoreReplay|TestStoreRejectsConflicting|TestStoreScopesParallel|TestS12LoopParallelArchiveMatrix'`

Exit code: `0`

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

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

Exit code: `0`

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

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

Exit code: `0`

```text
ok  	iop/apps/agent/internal/projectlog	7.552s
ok  	iop/packages/go/agentstate	1.113s
```

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

Exit code: `0`

```text
```

`rg --sort path -n 'implemented S12 source|\| S12 \|' agent-contract/inner/iop-agent-cli-runtime.md`

Exit code: `0`

```text
12:- implemented S12 source/tests: `apps/agent/internal/projectlog/sink.go`, `apps/agent/internal/projectlog/store.go`, `apps/agent/internal/projectlog/record.go`, `apps/agent/internal/projectlog/sink_test.go`, `apps/agent/internal/projectlog/store_test.go`, and `apps/agent/internal/projectlog/record_test.go`.
43:| S12 | Production `Sink.Emit` state-resolution tests plus `TestS12LoopParallelArchiveMatrix` in `apps/agent/internal/projectlog/sink_test.go`, `store_test.go`, and `record_test.go`; verification command: `go test -count=1 -race ./apps/agent/internal/projectlog ./packages/go/agentstate` | `project-logs` proves 11 explicit review-failure/follow-up pairs, independent same-project task completion, exact locator identity across state/store restarts, complete redacted WORK_LOG JSONL, durable event replay deduplication, and exactly-once task-scoped terminal archive reconciliation for every crash phase. |
```

`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 — `packages/go/agenttask/review.go:37`: the production manager emits `EventReviewResult` before the review result is committed at lines 73-127, while `apps/agent/internal/projectlog/sink.go:347` can project a verdict only from the durable `WorkRecord.Review`. The first review is therefore recorded without its verdict and later reviews can use stale evidence. `packages/go/agenttask/reconcile.go:422` also emits `EventDependencyReady` inside the pre-CAS mutation, so the resolver loads the prior work identity and the manager silently discards the resulting sink error at `packages/go/agenttask/manager.go:555`. The S12 fixture avoids both production orderings by calling `putS12Work` before each direct `Sink.Emit` at `apps/agent/internal/projectlog/store_test.go:1697`. Commit exact work evidence before emission (or introduce an equivalent durable outbox), surface sink failures, and add manager-to-sink tests that prove dependency, review, follow-up, and terminal WORK_LOG entries through the real event call sites.
  - Required — `apps/agent/internal/projectlog/store.go:1069`: replay fingerprinting clears only `Sequence`, so the timestamp assigned afresh by `packages/go/agenttask/manager.go:554` and the current global `StateRevision` resolved by `apps/agent/internal/projectlog/sink.go:57` make the same logical `event_id` conflict after time or unrelated state advances. The replay tests reuse an identical `ProjectLogRecord`/fixed event timestamp at `apps/agent/internal/projectlog/store_test.go:1458` and `apps/agent/internal/projectlog/store_test.go:1859`, so they do not prove the contract at `agent-contract/inner/agent-runtime.md:61-63`. Separate a stable manager-event fingerprint from volatile projection evidence, check it before re-resolving current state, retain it through prune/restart, and test same-ID replay after clock and unrelated manager-state revisions while still rejecting changed logical event content.
- Routing Signals:
  - `review_rework_count=2`
  - `evidence_integrity_failure=true`
- Next Step: Invoke the plan skill with these raw findings and materialize the freshly routed follow-up pair.
