reflect_review

Category: reflection
Access: read
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Paginated, filterable candidate list for human review. Call it to triage a run's candidates before deciding and applying.

Arguments

Required: run_id.

Optional: candidate_type_filter, decision_filter, limit, offset.

run_id: parent run id.
candidate_type_filter: optional category narrowing (e.g. 'stale_overdue_tasks'). Note: Narrows to one of the six audit categories.
decision_filter: empty | pending | accept | reject | defer. Note: Empty, pending, accept, reject, or defer; anything else is an error.
limit: max rows (clamped to 1000). Note: Defaults 100, clamped 1 to 1000.
offset: pagination cursor. Note: Pagination cursor; negative behaves as 0.

Result

Object with candidates array (candidate_id, run_id, type, suggested_action, target_kind, target_ref, evidence, confidence, decision fields, timestamps, already_applied), total, limit, offset, and the two filters.

Boundaries

Foreign runs read as the empty shape. Candidates additionally filter by evidence project, so pre-gate runs with cross-project candidates stay contained; scoped callers get the visible total.

Lifecycle / side effects

Pure read over persisted candidates with parsed evidence and an already_applied flag derived from apply snapshots.

Errors

Unknown decision_filter fails as unknown_decision_filter. Missing run_id rejected by validation. Backend failures return normal invalid_argument payloads.

Example

{
  "run_id": "<uuid>"
}

Result shape:

{
  "candidates": [
    {
      "already_applied": false,
      "candidate_id": "<uuid>",
      "candidate_type": "stale_overdue_tasks"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 1
}