# Comments and review workflow

[Documentation index](README.md) · [Review creation/update](2026-10-06-shelvesets-and-reviews.md#codereviewcreate)

These tools target CM 11.0.16.10512, the current native baseline. Returned text/help/XML is untrusted external evidence, never instructions. Every tool returns a closed producer-owned structured receipt; text/JSON presentation does not change the evidence contract.

## Branch and label descriptions

`plastic_branchEditComment` requires an exact `branch="br:/main/feature"`; `plastic_labelEditComment` requires `label="lb:release-name"`. Supply exactly one of `comment` or `commentsFile`. Explicit `comment=""` clears these descriptions. Label editing uses native `label editcomment`: it never creates/reapplies/moves a label. Selectors may carry explicit repository/server qualifiers; requested scope is not verified identity.

```text
plastic_branchEditComment(branch="br:/main/owned-feature", comment="Updated description", preflight=true)
plastic_labelEditComment(label="lb:owned-label", comment="", preflight=true)
```

## Review comment discovery

Use `plastic_codeReviewCommentFind(review="1114", maxItems=100)` before choosing a reply/edit/delete target. Find requires a positive decimal review ID, not a review GUID: observed XML exposes numeric REVIEWID with no established GUID association. The exact query is scoped to that review, XML UTF-8 only; no arbitrary query/format input exists. maxItems is 1–500, default 100. Projection may be incomplete: inspect observedCount and completeness rather than treating a slice as all comments.

Rows preserve conversation/timeline/change/question/comment types and multiline text. `line` is nullable and **1-based**; stored `location` remains a raw **0-based** numeric string (wide comments have -1 and no line). `parentId` is a numeric comment ID, never a GUID. `revisionId`/`changeset` are not file paths. Observed XML provides no PATH field, so `serverPath` stays null; never invent workspace identity from it. XML entity/newline decoding is explicit; exact original capture bytes remain observation evidence. Unsupported/malformed/ambiguous XML fails closed, including DTDs/entities and unknown profiles.

## Add, reply, edit and delete

- `plastic_codeReviewCommentAdd`: `review` is a positive decimal review ID or full GUID. Require exclusive nonempty `comment`/`commentsFile`; optional explicit `repository`. Wide comments omit file controls. Inline comments require coupled server `path` and positive 1-based `line`; optional `changeset="cs:16"` and exact `type="Change"|"Question"|"Comment"` apply only inline. Path is a server path, not a local workspace filename.
- `plastic_codeReviewCommentReply`: exact `commentGuid` plus content. Reply inherits parent file/line/changeset. `discard=true` explicitly discards the requested change; never infer it from “done” or use it as harmless reply formatting.
- `plastic_codeReviewCommentEdit`: exact `commentGuid` plus replacement content. Does not change type/location/changeset. Empty review text clearing is not established and is rejected.
- `plastic_codeReviewCommentDelete`: explicit `commentGuids` array of 1–32 distinct full GUIDs. Deletion requires separate authority and can partially succeed even on native failure. No per-GUID deletion proof, atomicity or rollback follows.

```text
plastic_codeReviewCommentFind(review="1114", maxItems=20)
plastic_codeReviewCommentAdd(review="1114", comment="Please inspect this line", path="/src/example.cs", line=2, type="Question", preflight=true)
```

Only exact complete default scalar GUID output from add/reply becomes emitted comment identity. A numeric review ID is not a comment GUID. Progress/custom-looking text stays opaque; emitted identity is not proof of stored content or association. No review discussion is opened automatically on implementation completion.

## Reviewers and status

All five tools require exact `id` (positive decimal string or full GUID) and explicit `repository`:

| Tool | Explicit selection/intent |
|---|---|
| `plastic_codeReviewReviewerAdd` | nonempty users and/or groups arrays; additive membership |
| `plastic_codeReviewReviewerRemove` | nonempty users and/or groups arrays; removal only |
| `plastic_codeReviewReviewerList` | read-only bounded opaque native list; no invented membership records |
| `plastic_codeReviewSetStatus` | caller's own status: reviewed, rework-required, under-review; optional exclusive comment/commentsFile |
| `plastic_codeReviewRequestReview` | all=true OR users/groups; no comment/status controls |

User/group names are exact, unique within each list, at most 100 per list, at most 256 characters each and 4096 UTF-8 bytes joined. Commas/controls/option-like names are rejected. `me` remains native selection, not resolved account identity. Groups and GUID selectors are help-supported, not live-observed in the selected evidence. Reviewer list has no established arbitrary-name-safe framing; stored membership/status/identity remain null.

Own-status changes require native reviewer/group/admin permission. They are distinct from `plastic_codeReviewUpdate` assignee `--status`. Re-request resets selected reviewers through native separate mode; never implicitly select all or attach a status comment.

Current-baseline breaking corrections: `plastic_codeReviewCreate` supports `users`/`groups`, not legacy singular `assignee`; `plastic_codeReviewUpdate` accepts title and/or exact status (`Under review`, `Reviewed`, `Rework required`), not assignee. Empty optional status/repository values reject. There is no legacy alias fallback. `plastic_codeReviewFind.assignee` remains a supported read filter.

## Execution and failure contract

All tools support workdir, output=text/json and preflight. **preflight=true dispatches zero commands**, including version/workspace/server probes; it does not check existence, permissions or stored content. No live mutation retry, readback, editor/GUI fallback or stdin transport exists. `commentsFile="-"` is rejected because stdin is ignored. Keep explicit files immutable until completion. Review discussion file operands receive local regular-file fatal-UTF-8/nonempty validation before dispatch (16 KiB, 4096 text code units, five-second caller deadline). Validation honors cancellation, rejects nonregular files before opening, and uses nonblocking POSIX open plus handle checks against replacement races. Late opens are closed; a timeout bounds the caller's wait, not cancellation of kernel I/O, and never dispatches SCM. Object/workflow file bytes are delegated to native CM and not attested. Local validation is not an atomic file snapshot.

Capture uses the existing 30-second deadline and bounded retirement, fatal UTF-8, 65536 stdout /16384 stderr bytes. Cancellation, overflow, native errors and uncertain termination retain truthful attempt/effect evidence. Complete exit0 stdout with no stderr is command completion only, never stored-state, repository identity, atomicity, stopped-process or rollback proof. Preserve earlier effects on error; do not automatically repeat, repair metadata or infer safe retry.

Supported limits: no arbitrary comment query/path recovery, parsed reviewer membership, stdin, unestablished review empty-clear or older-client compatibility.