Code review

Review is garden’s most differentiated surface, and where GitHub habits will mislead you. Four differences matter.

1. Comments are drafts until you submit

garden review comment writes a draft only you can see:

garden review comment 42 --file src/api.go --line 88 -b "This needs a bound."
garden review status 42      # your pending drafts
garden review submit 42 --approve

So you can work through a whole diff and publish once, with a verdict.

2. Comments anchor to a commit, not a diff position

Each comment records the commit whose file and line it references, and the viewer renders it on whichever side of the diff matches.

The payoff: comments survive rebases and new revisions. When an author amends and pushes, your threads stay attached to the code they were about. Don’t re-post because the diff changed.

Anchors are ranged — path:line[:col][-line[:col]]:

# The whole function, not one marker line
garden review comment 42 --file api/foo.go --line 42 --end-line 48 -b "..."

3. Unresolved threads block the merge

Open threads gate the merge queue alongside owner approval and green CI. There is no “merge and follow up”.

Resolution rides the latest published item in a thread, so a reply carries it without restating the point:

garden review 42 --threads     # each thread gets a c:1a2b3c4d handle
garden review comment 42 --reply-to c:1a2b3c4d --resolve -b "Fixed in rev 2."

4. Each PR in a stack has its own threads

Comments don’t propagate between a parent and child PR. A stack of five commits is five independent reviews.

Reading a PR

garden review 42                    # annotated diff, threads inline
garden review 42 --threads          # thread-centric view
garden review 42 --unresolved       # only what still blocks
garden review 42 --range 1:2        # what changed between revisions
garden review 42 --json             # structured bundle

Incremental re-review

Mark files reviewed up to the current revision; on re-review only later changes show for those files:

garden review mark-reviewed 42 src/api.go src/db.go
garden review mark-reviewed 42 --unmark src/api.go

Whole reviews in one document

When an agent produces a full review, garden review apply is the right path — one YAML document with the verdict, comments, replies, resolutions, and reviewed marks, applied atomically:

verdict: comment
comments:
  - at: "api/foo.go:42-48"
    body: "This allocates on every request."
  - reply_to: c:1a2b3c4d
    resolve: true
    body: "Good catch — fixed."
reviewed: ["*"]

garden review apply 42 -f review.yaml
garden review apply 42 -f review.yaml --draft    # stage without publishing

Full schema: review apply, or garden docs review.

Responding on your own PR

garden review 42 --threads
# fix the code
garden commit --amend
garden push
garden review comment 42 --reply-to c:1a2b3c4d --resolve -b "Fixed in rev 2."

After a new revision, threads anchored to earlier revisions drop out of the default view. The header says how many and prints the command to bring them back — usually garden review 42 --range 1:2 --threads.

Confirm the PR is mergeable with garden pr view 42.

CI failures arrive here too

A failing check posts an inline thread on the failing line, authored by ci-bot. It reopens when a test re-fails and resolves when it passes — even if a human resolved it in between — and counts toward the merge gate like any other thread. See Continuous integration.