[shiplog/plan] PR envelope: add Reviews index line for signed reviews

[devallibus]

Context

shiplog cross-model review sign-offs currently live only in PR issue-comments. That is the right place for the signed artifact — it matches the GitHub-API constraint documented in skills/shiplog/references/closure-and-review.md:206 — but it means the review state of a PR is invisible unless a consumer explicitly pulls the comments endpoint. Issue #140 fixes the hunt command to do exactly that, and once it lands the primary bug is gone.

This issue covers the secondary, belt-and-suspenders fix: make review state visible from the PR envelope itself. A single compact "Reviews" index line in the PR body — updated when a signed review is posted — gives every consumer (humans skimming, other tools, terse AI summaries) a cheap, reliable way to see "yes, this PR already has a signed Opus review" without having to know to pull the comments slice. It also protects against future hunt-like tools regressing the same bug in a new entry point.

The cost is a small, well-bounded edit contract: the reviewer appends one line to the PR body when they post their signed review, with an Updated-by: signature per the existing envelope edit rules (skills/shiplog/references/artifact-envelopes.md).

Design Summary

• Add a canonical "Reviews" index section to the PR envelope template
• Populate it as a side-effect of posting a signed review comment; the signed comment remains the authoritative artifact
• Keep the index minimal: date, reviewer signature, disposition, link to the comment
• Treat the index as derived state; the comment is still the source of truth in case of divergence

Approach

Update the PR body template in skills/shiplog/references/phase-templates.md (and any related templates the pr-workflow reference documents) to include a "Reviews" section immediately under the shiplog envelope and above the substantive PR body. The default section shows a placeholder ("No signed reviews yet.") at PR creation.

Update skills/shiplog/references/closure-and-review.md §4 so that the review-posting step requires the reviewer to edit the PR body and append a one-line entry under "Reviews" whenever a signed review comment is posted. The edit is an Updated-by: envelope edit with edit_kind: amendment.

Define one standard entry format, for example:

- 2026-04-18 — Reviewed-by: claude/opus-4.7 (claude-code) — Disposition: approve — https://github.com/<repo>/pull/<N>#issuecomment-<id>

Document that the index is derived; the signed comment stays authoritative if they ever diverge.

Alternatives Considered

• Rely only on the hunt fix from [shiplog/plan] Hunt command misses comment-based signed reviews #140: rejected. It closes the immediate bug but leaves every other entry point (future commands, ad-hoc reviews, humans skimming) one query mistake away from the same miss.
• Pin a comment instead of editing the body: rejected. GitHub pinned comments are per-user UI state and cannot be relied on for machine retrieval.
• Require a GitHub label per review state: rejected. Labels compress all review nuance into one slot and cannot record reviewer identity or multiple reviews; the index line can.

Tasks

• T1: Define the Reviews index format [tier-1]

  • What: Specify the canonical Reviews section structure (header, placeholder, one-line entry format, ordering) as an addendum in skills/shiplog/references/phase-templates.md.
  • Files: skills/shiplog/references/phase-templates.md (modify)
  • Allowed to change: The PR body template blocks and their surrounding commentary.
  • Must not change: The shiplog envelope schema in artifact-envelopes.md.
  • Forbidden judgment calls: Do not introduce new provenance roles or compete with Reviewed-by: — this is an index, not a re-signing surface.
  • Verification: Read the updated template and confirm a fresh PR body rendered from it contains the Reviews section with the placeholder line.

• T2: Wire the index into the review-posting workflow [tier-2]

  • What: Update the review protocol so posting a signed review comment is paired with appending one entry to the Reviews section of the PR body, under an Updated-by: amendment.
  • Files: skills/shiplog/references/closure-and-review.md (modify); linked references from skills/shiplog/references/pr-workflow.md if they document the review-posting flow
  • Allowed to change: The ordered review-posting steps and any checklists downstream consumers use.
  • Must not change: The cross-model independent-review gate or the signed-comment being authoritative.
  • Forbidden judgment calls: Do not let the index replace or substitute the signed comment if they diverge; the comment wins.
  • Verification: Walk through the updated workflow on a hypothetical PR and confirm the reviewer ends with both a signed comment and a matching Reviews line.

• T3: Document the derived-state rule [tier-1]

  • What: Add an explicit note in both the template and the protocol that the Reviews index is derived from signed comments; the comment is authoritative on divergence.
  • Files: skills/shiplog/references/phase-templates.md (modify); skills/shiplog/references/closure-and-review.md (modify)
  • Allowed to change: The derived-state callout only.
  • Must not change: The rest of the review protocol or envelope definition.
  • Forbidden judgment calls: Do not invent a reconciliation procedure; "comment wins on conflict" is the rule.
  • Verification: Both files contain a short "derived state" note with a pointer to the signed comment as source of truth.

Provenance

Authored-by: claude/opus-4.7 (claude-code)

[devallibus]

Related: #140 (primary fix for hunt query), #142 (envelope marker). This issue is explicitly belt-and-suspenders for #140.

[devallibus]

Referenced from #143 (simplification meta-plan): benefits from L2 if tag/label/kind vocabularies collapse to a single source of truth.

[devallibus]

[shiplog/amendment] Referenced by simplification meta-plan

Parent: #143. Workstream D (#146) T5 (pr.md co-location) pulls in the Reviews index format from this issue if it lands first; otherwise T5 uses the current PR body shape and a follow-up wires the index in.

Authored-by: claude/opus-4.7 (claude-code)