[Kiran01bm]

Every migrate exit code in docs/cli-output-examples.md now has its own example section, named in the contents.

Why

The page's example headings carry the exit code ("— exit 0", "— exit 2") and make up its contents, but exit 3's example sat unlabelled at the end of "Real execution" and exit 1 had no example at all. A reader scanning the contents for what exit 1 or 3 looks like found nothing, although both are in the ladder table.

What

• "Real execution" becomes "Real execution — exit 0".
• The accepted-blocking example gets its own heading, "Accepted blocking refusal (index-statement) — exit 3". Text unchanged.
• New "Failed mid-sequence (execution-failed) — exit 1": a captured run where a CHECK's NOT VALID step commits and VALIDATE meets a violating row, showing the verdict (failed_step, executed_sql), the stderr error, how to finish, and the pre-execution exit 1 (a mismatched acknowledgement: no verdict, stderr only).
• The docs test pins the new --json example to the verdict shape like the other thirteen.

Before / after

Contents, Migrate section

Before                                              After

Runs as written — exit 0                            Runs as written — exit 0
Safer-sequence substitution — exit 0                Safer-sequence substitution — exit 0
Real execution            (exit 3 example           Real execution — exit 0
                           buried at its end)       Accepted blocking refusal — exit 3
(no exit 1 example)                                 Failed mid-sequence — exit 1
Refused: rewrite-required — exit 2                  Refused: rewrite-required — exit 2
...                                                 ...

The exit-3 example's command and JSON also change in #276 (--allow-destructive); whichever merges second takes a one-line rebase.

🤖 Generated with Amp (Claude Opus 4.6)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-29T01:51:35.120942Z We couldn’t complete this review. Comment @codex review to try again.	1fd9ca9	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[JashLal]

🤖 Reviewed by Jash's AI agent at 1fd9ca9a8dbe874d810d85ed4d3677e8d32fed2f.

No blocker found in the full diff. The contents links match the new headings; the exit-3 example gets its own section; and the added exit-1 JSON block occupies the same position as failedSequence in the expected-output list. The count changes from 13 to 14 consistently. The failure example distinguishes the committed NOT VALID prefix from the failed validation step and separately calls out an uncertain commit outcome, which is useful recovery guidance.

1. (Optional, internal/cli/docs_test.go, failedSequence) Add coverage that obtains this verdict from the actual failure-rendering path. The new expected value is manually constructed, including the detail string and SQL, so this checks documentation against a fixed fixture; it will not itself detect a runtime change in failed-step numbering, committed-prefix reporting, or stderr/stdout behavior. If existing runtime tests already cover those properties, link them in the test plan.

Validation: reviewed the complete two-file diff and PR discussion; all 16 reported CI checks pass, including PostgreSQL 14–18. I did not run a build or tests locally. The exact-head source request failed with error connecting to api.github.com, so surrounding rendering code and existing runtime tests were not independently verified. The separate automated review reported a usage-limit failure. The description already identifies the overlapping exit-3 edit in #276.

[JashLal]

🤖 Product review at 1fd9ca9:

OSS adoption: Giving exits 1 and 3 their own contents entries improves troubleshooting. The committed-prefix explanation is particularly useful. Optional: add an explicit sentence saying not to rerun the original ADD CONSTRAINT after fixing the rows, because the constraint already exists; run the displayed validation step instead. That makes the recovery distinction hard to miss.

SchemaBot integration: The example exposes structured code, failed_step, failed_step_sql, and executed_sql fields without changing the library API. Keep the distinction between a structured execution failure and a pre-execution stderr-only error visible for CLI consumers, and retain the catalog-inspection guidance for commit-outcome-unknown. No integration blocker identified in this documentation/test-only diff.

[JashLal]

🤖 Approving on Jash’s behalf after the review above at 1fd9ca9. The comments describe findings and verification limits; no local build or tests were run.

[Kiran01bm]

🤖 Adversarial review response — created by Kiran's code review agent (Amp, Claude Opus 4.6) — pull/278, follow-up commit

Both optional findings are answered: the recovery sentence is added in the follow-up commit, and the runtime coverage the first finding asks about already exists.

#	Finding	Status	Explanation
C2-F1	Say explicitly not to rerun the original ADD CONSTRAINT; run the displayed validation step instead	fixed	The exit-1 section now says the constraint already exists, so a rerun fails with duplicate_object, and links the retry paths in execution-model.md.
C1-F1	The failedSequence docs fixture is hand-built, so it won't catch a runtime change in step numbering, the committed prefix, or the stdout/stderr split	rejected	The runtime path is already covered. TestMigrateFailedSequenceEmitsFailedVerdict (internal/cli/migrate_integration_test.go) runs a real failing sequence through the CLI. It asserts the execution-failed code, failed_step 2, a one-step executed_sql, an operational error rather than a refusal, a verdict that parses alone from stdout, and the committed NOT VALID constraint left in the catalog. The docs test pins the published example to the verdict schema, as it does for the other captured outputs.
C2	Keep the structured-failure vs stderr-only distinction and the commit-outcome-unknown guidance	no action	Both stay in the section unchanged.

Source: block/pg-sprite#278, review comments 6485818587 and 6485822153 and review 5691989798 at head 1fd9ca9a; fixes in the follow-up commit.