Review Work

---
name: "review-work"
description: "Report-only critique before Builder verification. Records a critique slice through the public workflow interface without claiming Flow completion."
---

# Review Work

## Role

This is a Builder step skill.

Review Work is the report-only critique step. It asks whether the changed work
should change before verification: correctness risks, maintainability, security,
dependencies, architecture, standards, and applicable policy.

It does not prove accepted behavior and it does not fix source files.

## Binding

| Context | Binding | Flow expectation |
| --- | --- | --- |
| Active Builder run | `builder.build` at `verify` | `clean-critique`. Review Work owns the critique claim, not verification completion. |
| Active existing-change run | `builder.review-existing` or `builder.deliver-existing` at `verify` | `clean-critique`, for a change that existed before the run. Cite `<slug>--existing-change.md` instead of the execution report. |
| Standalone invocation | No Flow binding | No workflow mutation. |

For an active run, inspect the binding before work:

The steering hook injects the run state at session start and re-injects it whenever it changes; if a steering state block appears anywhere in your context and you have not recorded evidence or a critique since it appeared, it is current. Run `flow-agents workflow status --session-dir <session-dir> --json` only after such a write or when no steering state block appears in your context at all; the write itself refuses an unbound, stale, or wrong-step binding either way.

Run this skill only when the reported run is `builder.build`,
`builder.review-existing`, or `builder.deliver-existing` at `verify`.
If there is no matching active run, operate standalone. Do not publish a gate
expectation from this skill.

## Model Routing

Resolve `delegate-implementation` from `.datum/config.json` and follow
`context/contracts/execution-contract.md`. The Goodhart guard applies: review
must never resolve below the reasoning tier of the checked work. Record any
fallback or escalation in the critique artifact.

## Inputs

- Changed-file scope from the session, plan, or `RepositoryAdapter`.
- Acceptance criteria and implementation intent.
- Repository standards and relevant decisions.
- Available `CheckProvider` evidence and policy constraints.

## Review Work

1. Establish the changed-file scope. If it cannot be established, record the
   scope review as `NOT_VERIFIED`.
2. Select review lanes from the changed scope and risk, not from a fixed list
   run unconditionally:
   - `tool-code-reviewer` for code quality, correctness, architecture, and standards.
   - `tool-security-reviewer` for authentication, authorization, secrets,
     untrusted input, data handling, network boundaries, infrastructure, and
     security-policy changes.
   - `tool-dependencies-updater` for dependency-manifest, lockfile, or dependency-tooling changes.
   - A configured domain or policy reviewer when the repository requires one.

   When review fans out to delegated reviewer lanes, declare the fan-out in the
   session's wave manifest (`waves.json`, schema
   `schemas/workflow-waves.schema.json`, step `review`) with one
   `expected_workers` entry per reviewer lane before dispatch. Reconcile against
   that manifest at collection — "N of M reported" — instead of collecting from
   memory: every declared reviewer lands exactly one terminal status record;
   record a reviewer that never reports as `not_reported` in the manifest —
   never silently absorb it — and carry that lane into the critique as
   `not_verified` with the missing report named. A missing reviewer is never a
   clean lane.
3. Use repository-provided scanners and checks when applicable. Do not install
   a scanner, silently substitute a different one, or mark an unavailable
   required lane clean; record the lane as `NOT_VERIFIED` with the missing
   capability and consequence.
4. Keep findings actionable: severity, affected scope, evidence, and the
   required route back. Do not install scanners or change code to obtain a
   cleaner result.
5. Reviewing a fix round, establish its scope against the head the superseded
   critique targeted — read `<session-dir>/trust.bundle`, match the critique by
   `metadata.critique_record_id`, and take
   `metadata.review_target.workspace_snapshot.head_sha`, a real commit — before
   reading the change, and check the scope against what each finding's remedy
   requires.
   A round whose remedy was behavioral but which landed only test or doc changes
   is green by construction — the assertions moved, not the behavior — and the
   round's own passing suite cannot see it. Missing remedy scope is a finding
   that routes back with the absent change named, not an observation in passing.
   A round that legitimately lands only tests or docs (a coverage gap, a
   documentation defect) is in scope by that same test — say which finding it
   answers rather than treating the file mix itself as the verdict.
6. Produce the critique artifact. Open blocking findings route to implementation;
   unavailable required review remains `NOT_VERIFIED`.

## Output

For a matching active run, record the review through the public interface:

```bash
flow-agents workflow critique --session-dir <session-dir> \
  --verdict <pass|fail|not_verified> \
  --summary "Review scope, findings, and unresolved gaps are recorded." \
  --artifact-ref ".kontourai/flow-agents/<slug>/<slug>--deliver.md" \
  --artifact-ref "<reviewed-changed-file>" \
  --lane-json '{"id":"code-review","status":"pass","summary":"Code quality, correctness, architecture, and standards were reviewed.","evidence_refs":[{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--deliver.md","summary":"Reviewed delivery artifact and changed-scope context."}]}'
```

The delegated reviewer must invoke this operation under its own runtime actor
identity. The public operation requires an active implementation assignment but
rejects the assigned implementation actor as the reviewer; do not proxy the
review through the implementation actor or supply a caller-selected reviewer
label. The critique is stored as the review slice in `trust.bundle`: reviewer
identity, covered scope, lane verdicts, severity-tagged findings, evidence, and
unresolved `NOT_VERIFIED` gaps. A clean critique satisfies the declared
`clean-critique` expectation, but it is not test evidence, does not satisfy
`tests-evidence`, and does not independently advance a Flow run.

Runtime actor separation is a coordination guarantee, not cryptographic
attestation. When repository policy requires an externally attested reviewer
credential and the runtime cannot provide one, record reviewer identity as
`NOT_VERIFIED`; do not describe the review as independently authenticated.

Every critique needs at least one substantive `--lane-json`. A passing critique
also needs existing local `--artifact-ref` values for the execution report and
reviewed changed files. The public writer captures the owned execution report
as immutable historical `review_context` automatically. It separately anchors
the execution controls, complete plan, accepted criterion identity, and live
plan/scope claims. Source and control references remain `review_subject`;
legacy untyped references keep their strict subject semantics.

Optional later observations belong under one final `## Verification Evidence`
appendix in the execution report. That informational appendix can grow without
another review of unchanged implementation. It cannot redefine scope, DoD, or
criteria, contain new control headings, or duplicate the appendix marker.
Markers inside fenced examples are ordinary content. Ambiguous reports retain
strict subject hashing. The writer owns capture; no manual freeze or extra
artifact operation is required.

Git repositories still bind review to exact `HEAD`, tracked diff, and untracked
file bytes. Non-Git reviews need explicit implementation subjects. Changes to
source, execution controls, plan, criteria, scope claims, or captured historical
context invalidate the review. A report-only verification appendix does not.

For standalone use, return the same report to the caller without creating a
workflow record.