Visual Aids

With HTML artifact mode on, /flow-next:make-pr also emits a PR render lens at .flow/artifacts/<spec-id>/pr.html — a self-contained HTML page built for one job: getting a human reviewer through the diff fast, with the spec’s acceptance criteria in hand.

It is a read-only review instrument: masthead + dials, a sticky review-progress bar, the 90-second read, a churn map grouped by review intent (canonical vs generated-mirror vs mechanical), the R-ID → evidence table, a where-to-look checklist, and a risk register.

A PR render lens masthead: dark instrument panel with diff stats, file count, R-ID coverage, tasks done and a human-review-lines dial, a sticky review-coverage progress bar, and a serif 90-second-read paragraph with a load-bearing-claims callout. — The PR lens for the PR that shipped it — diff dials including the human-review-lines estimate (added lines minus generated and mechanical churn), the sticky review-progress bar, and the 90-second read. Click to zoom.

Diff-derived, never commit messages

The lens is built from the flowctl spec export-cognitive-aid payload plus the real diff — commit subjects and bodies are not lens input. What a reviewer reads reflects what actually changed, not what the commits claim changed.

The churn map of a PR render lens: collapsible groups ordered by review intent — disclosure reference, canonical skill integrations, flowctl and regression tests, a generated Codex mirror group, docs, scripts and mechanical version surfaces — each with colored plus-minus stats, file counts and proportional churn bars. — The churn map groups the diff by review intent: canonical changes to actually review, generated mirrors to verify-not-line-review (gray bars), docs, and mechanical lockstep. Click to zoom.

R-ID verification — warn, never block

Before publishing, the lens is verified against the spec’s R-ID export. Mismatches — claimed evidence outside the diff range, uncovered R-IDs, evidence touching no diff files — render as visibly flagged rows (red R-ID cell, mismatch chip, reason). A mismatch never blocks PR creation and is never silently dropped: the discrepancy is the finding.

The bottom of the R-ID evidence table with two red-flagged external rows whose evidence lives in another repository, followed by the where-to-look review checklist with three checked cards struck through in green and the sticky progress bar reading three of nine checked. — Flagged rows in action — two R-IDs whose evidence lives in a separate repo render with red flags and a one-line reason — above the where-to-look checklist, whose checkmarks persist locally and feed the sticky progress bar. Click to zoom.

How it ships with the PR

Narrow commit. When the artifact is tracked, it lands in exactly one pathspec-confined commit (chore(flow): pr artifact <spec-id>, the artifact file only — never git add -A) before the PR body captures the head SHA, so the body’s SHA-pinned blob link resolves once the branch pushes. Gitignored artifacts get local-open guidance instead — never a blob link that 404s.
The GitHub limitation. GitHub renders committed HTML as raw source, so the body link carries the note: open locally in a browser (open .flow/artifacts/<spec-id>/pr.html).
--dry-run writes nothing. No artifact, no commit, no body line.
Failure is non-fatal. Artifact generation or staging failure degrades to no-body-line plus one stderr note; the PR is still created.

Why there is no annotate loop

The spec lens opens a Lavish annotation session when available; the PR lens never does — interactive and autonomous alike. A PR artifact derives from an immutable diff, and GitHub already owns review conversation — duplicating that surface would create a sync problem. PR feedback belongs in review threads, where /flow-next:resolve-pr picks it up.

Autonomous discipline

Pilot, Land, and Ralph generate artifacts at the same touchpoints but never open a Lavish session and never poll — a loop never blocks on a human. Ralph’s PR_URL= stdout contract is untouched: all artifact messaging routes to stderr. See the safety model.