# Delivery Review Outcome Comment

Use this shared comment contract after the delivery specialist review gate has
enough information to decide whether delivery can merge, must stop, or can
continue with an accepted residual risk. The owning `deliver-*` workflow posts
the comment; `code-review-specialists` stays read-only.

## Ownership

- `deliver-github-pr` posts the outcome on the PR before `close-github-pr`.
- `deliver-gitlab-mr` posts the outcome on the MR before `close-gitlab-mr`.
- `deliver-tracking-issue` records the PR/MR outcome comment URL in issue-hosted
  session or validation evidence instead of duplicating the full report.
- `code-review-specialists` supplies review evidence only. It must not post or
  update live PR/MR comments.

## Timing

- Post one final outcome comment after review and repair pass, before final
  merge/close.
- If review blocks delivery, post a blocked outcome comment before stopping when
  provider auth and permissions allow it.
- Do not post every intermediate specialist finding or repair iteration unless
  the user explicitly asks for verbose audit comments.
- If comment posting fails, stop before merge and report the provider command,
  exit status, and retry action. A delivery that requires this contract is not
  complete without the outcome comment.

## Provider Commands

GitHub:

```bash
gh pr comment <pr> --body-file <comment.md>
```

GitLab:

```bash
glab mr note create <iid> < <comment.md>
```

Use provider repository flags such as `--repo` / `-R` when local remotes are
ambiguous. Prefer creating an append-only outcome comment; edit or replace an
existing comment only when the workflow has explicitly identified the previous
`agent-kit:delivery-review-outcome:v1` comment from the same delivery attempt.

## Required Comment Shape

```markdown
<!-- agent-kit:delivery-review-outcome:v1 -->
## Delivery Review Outcome

- Reviewable: PR #123
- Decision: proceed-to-merge | blocked | proceed-with-accepted-residual
- Lenses: testing, maintainability, api-contract
- Validation: scripts/check.sh --all pass
- Provider checks: required checks pass

| Item | Disposition | Reason | Evidence |
| --- | --- | --- | --- |
| Missing edge-case test | fixed-now | Required for behavior coverage. | commit + validation |
| Minor wording note | no-action | N/A | reviewed docs diff |
| Cleanup opportunity | follow-up-linked | Outside this delivery scope. | issue URL |
```

Required fields:

- Marker: `<!-- agent-kit:delivery-review-outcome:v1 -->`
- Reviewable identifier: PR number/URL or MR IID/URL.
- Decision: `proceed-to-merge`, `blocked`, or
  `proceed-with-accepted-residual`.
- Lenses used, including forced minimum lenses.
- Validation and provider check or pipeline status.
- Findings table. Use a single `none` row when there were no findings or
  residual risks to report.

## Dispositions

Use these dispositions for every meaningful review item:

- `fixed-now`: repaired in the delivery branch before merge.
- `accepted-residual`: real risk accepted for this delivery.
- `follow-up-linked`: actionable work moved outside this delivery with a linked
  issue or durable follow-up.
- `deferred-task`: issue-backed work left in an explicit deferred task row.
- `no-action`: reviewed observation with no required change or follow-up.
- `blocked`: cannot continue until a user, project, provider, or policy action
  occurs.

Reason rules:

- `fixed-now`: reason optional; evidence and validation are required.
- `no-action`: reason optional for trivial observations; use `N/A` when omitted.
- `accepted-residual`: reason required.
- `follow-up-linked`: reason and follow-up link required.
- `deferred-task`: reason and deferred task row/evidence required.
- `blocked`: reason and exact unblock action required.

Keep the comment compact. Link to detailed specialist reports, validation logs,
issue evidence, or follow-up records instead of pasting long raw review output.
