This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

OpenSpec

1 - Specifications

1.1 - Review delivery

1.1.1 - review-delivery Specification

Make validated pull-request review delivery reliable and concise while preserving exact-candidate and mutation consistency checks.

The CLI SHALL offer a single review-address operation using a published validation receipt, a thread ID, and a reasoned reply file. It SHALL derive current expectations, post at most one reply per durable reply receipt, and resolve only the verified resulting thread. A retry SHALL resume an existing valid reply receipt rather than posting another reply.

  • WHEN the published validated head and unresolved thread match the supplied candidate receipt
  • THEN the operation posts the reasoned reply, verifies it, resolves the unchanged thread, and returns the resulting inventory
  • WHEN the published head differs or the target thread changes during processing
  • THEN the operation refuses mutation or stops further mutation with diagnostic state

The CLI SHALL preserve the original unexpired reply receipt when a transient provider read or advancing review epoch prevents observing a coherent inventory before any resolution mutation. It SHALL retain single-use consumption on attempted mutations, semantic mismatches, and expiry, without extending authority.

  • WHEN read-only inventory collection observes an advancing GitHub epoch before resolution
  • THEN the operation reports that resolution was not attempted and leaves the original unexpired receipt available for a guarded retry
  • WHEN a resolution mutation was attempted but its result cannot be verified
  • THEN the receipt remains consumed and the tool requires fresh inspection

Review inspection SHALL include every returned thread and comment while fetching the first comment page with the thread page. It SHALL fetch additional comment pages when necessary and retain request, byte, and node limits, identity checks, and duplicate detection.

  • WHEN every returned thread has one page of comments
  • THEN inspection obtains their comments without one separate details request per thread
  • WHEN a thread has more comments than its embedded page
  • THEN inspection follows its cursor and returns all comments or refuses incomplete state