[shiplog/plan] Operationalize provenance preflight before PR review

[devallibus]

Context

During review of PR #130, the reviewer began substantive diff review before checking whether the newest signed author-side artifact was from the same model/version. The current review protocol already says to inspect signed provenance first, skip same-model PRs, and only proceed with an explicit user-confirmed self-review as a non-gate-satisfying audit artifact.

That means the immediate failure was operator error, not missing policy. But it also exposed a product gap: the policy lives in closure-and-review.md, while common entry points such as direct "review PR #N" requests and lightweight review flows do not force a provenance preflight before substantive review begins. Issue #132 addresses the hunt recommendation side of this problem; this issue covers the remaining execution-path gap.

Design Summary

• Treat provenance and reviewability resolution as a mandatory preflight before any substantive PR review work
• Keep the existing cross-model gate and self-review audit rules; this issue is about operationalizing them, not changing the policy
• Make the preflight visible in the review workflow so agents do not have to remember a buried paragraph in a long reference file
• Ensure the fallback for same-model or unknown-reviewability cases leads directly to the correct next action: stop, ask for confirmation for audit-only self-review, or emit a review contract

Approach

Add an explicit review-entry section to the shiplog review workflow that runs before diff inspection. That section should require the reviewer to resolve reviewability from signed artifacts, classify the PR as cross-model / same-model / unknown, and branch immediately:

1. cross-model: proceed to substantive review
2. same-model: stop and ask whether to record an audit-only self-review
3. unknown: stop and clarify provenance or generate a review contract

This should be documented in the main review protocol and any review-facing command or template that currently jumps straight from "user asked for review" to "inspect the diff."

Alternatives Considered

• Leave the policy as-is and rely on reviewer discipline: rejected because the existing wording was already correct, yet a same-model substantive review still happened.
• Fold everything into hunt only: rejected because direct review requests can bypass hunt, so fixing recommendation logic alone does not close the execution gap.
• Ban audit-only self-review entirely: rejected because the current protocol intentionally allows it as a visible non-gate-satisfying artifact when explicitly confirmed.

Tasks

• T1: Add a mandatory review-entry preflight to the protocol [tier-2]

  • What: Update the review guidance so the first step of any PR review flow is to resolve signed provenance and reviewability before reading the diff in detail.
  • Files: skills/shiplog/references/closure-and-review.md (modify)
  • Allowed to change: Review target selection and review execution ordering
  • Must not change: The core independent-review gate or the meaning of self-review
  • Forbidden judgment calls: Do not weaken same-model restrictions or allow inference from unsigned artifacts
  • Verification: Read the updated section and confirm the preflight happens before substantive review steps
  • Return artifact: Diff plus the final preflight checklist text
  • Decision budget: narrow
  • Accept when: A reviewer following the doc top-to-bottom cannot reach substantive review without first classifying cross-model / same-model / unknown

• T2: Wire the preflight into review-facing entry points [tier-2]

  • What: Audit the repo's review-related docs and command surfaces, then add or reference the same mandatory preflight so lightweight review requests do not bypass it.
  • Files: review-facing command/docs entry points in this repo
  • Allowed to change: Review instructions, command wording, templates, or checklists
  • Must not change: Non-review workflows except where they invoke review
  • Stop and ask if: The cleanest fix requires introducing a new dedicated review command or larger command reorganization
  • Verification: Manual read-through of each touched entry point
  • Return artifact: Diff summary naming each entry point updated
  • Decision budget: narrow
  • Accept when: The common ways to ask shiplog for a review all force or clearly front-load the provenance preflight

• T3: Define the blocked-path outputs for same-model and unknown cases [tier-1]

  • What: Specify the exact reviewer behavior after preflight for blocked cases, including the wording and required artifacts for audit-only self-review, provenance clarification, and review-contract handoff.
  • Files: skills/shiplog/references/closure-and-review.md (modify), any linked review workflow references needed for consistency
  • Decision budget: full
  • Accept when: The docs give a deterministic next step for same-model and unknown cases without leaving the reviewer in an ambiguous half-reviewed state
  • Why tier-1: This requires deciding how strict and centralized the blocked-path UX should be across shiplog

Open Questions

• Should shiplog add a dedicated review command or short review skill whose entire first phase is provenance preflight, instead of relying on a long shared reference doc?
• Should a same-model audit-only self-review be prohibited from including substantive findings unless the user explicitly requests the audit artifact?
• Should blocked review attempts be captured as a signed timeline artifact on the PR, or only surfaced to the user unless they choose audit-only self-review?

Related

• Issue [shiplog/plan] Add PR-body review snapshot for hunt and review triage #132 covers the hunt recommendation gap for reviewability-aware triage

---

Authored-by: openai/gpt-5.4 (codex, effort: high)
Captain's log entry created by shiplog