The OpenAPI document describes a pull's review states and attaching a look #5402

The OpenAPI document now describes GET and POST …/pulls/{number}/review-states and POST …/pulls/{number}/looks. bun test test/openapi passes (46 tests) and bun x tsc --noEmit is clean. I did not run the rest of the suite.

• Rows: the three rows sit in ROUTES in src/contract/openapi.ts, right after the …/merge row. Their summaries, bodies and refusals come from the handlers in src/http/api.ts.

- GET review-states: needs no token. - POST review-states: rw scope, answers 201. Body is state, body and comments. Refusals are invalid_state, invalid_comments, self_review, bad_anchor and too_many_lines, all 422. - POST looks: rw scope, answers 201 with {id, width, says, by, commit, url}. Body is width, says and image. Refusals are too_large (413), not_open and no_app (409), and bad_image, bad_note and bad_width (422).

• Coverage test: the three lines are out of NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
• New test: test/openapi-oa-pull-review.test.ts reads the rows from the served document and fails without them. It checks each method, the request bodies, the 201 responses and a refusal code for each POST.
• Left out: the 403 and 404 answers that requireScope and loadPull give. The existing rows leave those out too.
• Other entries: the coverage test says 26 NOT_YET_DESCRIBED entries could now be removed. They are not part of this issue, so I left them.

To try it, run curl $URL/api/v1/openapi.json and look for the review-states and looks paths.

Closes #5382

The OpenAPI document now describes GET and POST …/pulls/{number}/review-states and POST …/pulls/{number}/looks. bun test test/openapi passes (46 tests) and bun x tsc --noEmit is clean. I did not run the rest of the suite.

• Rows: the three rows sit in ROUTES in src/contract/openapi.ts, right after the …/merge row. Their summaries, bodies and refusals come from the handlers in src/http/api.ts.

- GET review-states: needs no token. - POST review-states: rw scope, answers 201. Body is state, body and comments. Refusals are invalid_state, invalid_comments, self_review, bad_anchor and too_many_lines, all 422. - POST looks: rw scope, answers 201 with {id, width, says, by, commit, url}. Body is width, says and image. Refusals are too_large (413), not_open and no_app (409), and bad_image, bad_note and bad_width (422).

• Coverage test: the three lines are out of NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
• New test: test/openapi-oa-pull-review.test.ts reads the rows from the served document and fails without them. It checks each method, the request bodies, the 201 responses and a refusal code for each POST.
• Left out: the 403 and 404 answers that requireScope and loadPull give. The existing rows leave those out too.
• Other entries: the coverage test says 26 NOT_YET_DESCRIBED entries could now be removed. They are not part of this issue, so I left them.

To try it, run curl $URL/api/v1/openapi.json and look for the review-states and looks paths.

The full gate on land was red; the pull is open again. Red tests:

• the gate audit before any shard > a new file is in the gate with no list naming it, and explicit files are not audited
• the gate audit before any shard > a new file is in the gate with no list naming it, and explicit files are not audited [77.71ms] [shard 103]

Red on top of #5456, #5514, #5515, #5516, #5518, which landed first from the same merge-queue candidate: red on its own on that base, or only together with them. Bring this pull up to date with the base and push.

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

The OpenAPI document now describes a pull's review states and attaching a look, and this pull is merged up to date with main.

• Merge: main moved each OpenAPI row into its own file under src/contract/openapi/routes/. I took main's layout and re-added my three rows there: GET and POST …/pulls/{number}/review-states, and POST …/pulls/{number}/looks. I regenerated routes/index.ts.
• Coverage list: the three matching NOT_YET_DESCRIBED entries are gone from test/openapi-coverage.test.ts. The row-reading test test/openapi-oa-pull-review.test.ts is unchanged.
• Tests: the type check is clean, and test/openapi* passes (270 tests) and test/shards.test.ts passes (69). I did not run the full gate. The gate-audit failure from the last land did not reproduce on the merged base. I changed nothing for it, so a repeat there would be a base-state flake, not this pull.
• Not done: I left juniper's two follow-ups for separate pulls. One is documenting the 403/404 answers from requireScope and loadPull, across the existing rows too. The other is removing the 15 NOT_YET_DESCRIBED entries the coverage test now says can go.

Taken over by nobody; stopped @scout.

Handed to a person by the crew: this pull is approved, but 2 runs to bring it up to date with main ended without a push, so no more start here. Conflicting files: src/contract/openapi/routes/index.ts. Merge main into it, or say what to try and assign it back to the crew. (The forge posts this under your name; you did not write it.)

The OpenAPI document now describes GET and POST …/pulls/{number}/review-states and POST …/pulls/{number}/looks. This push brings the branch up to date with main. bun test test/openapi passes (334 tests) and bun x tsc --noEmit is clean. I did not run the rest of the suite.

• Merge: the only conflict was src/contract/openapi/routes/index.ts. Main now keeps one route file per path, and both sides had added export lines in the same spot. I kept both and regenerated the index with bun scripts/openapi-routes.ts. The routes-index freshness test failed until I did.
• Routes: getApiV1ReposOwnerNamePullsNumberReviewStates.ts, postApiV1ReposOwnerNamePullsNumberReviewStates.ts and postApiV1ReposOwnerNamePullsNumberLooks.ts are the three route files.

- GET review-states: needs no token. - POST review-states: rw scope, answers 201. - POST looks: rw scope, answers 201.

• Tests: test/openapi-oa-pull-review.test.ts reads the rows from the served document and fails without them. The three entries are out of NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
• Left out: the 403 and 404 answers that requireScope and loadPull give. The existing rows leave those out too.
• Other NOT_YET_DESCRIBED entries: the coverage test says 44 entries could now be removed. They are not part of this issue, so I left them.

To try it, run curl $URL/api/v1/openapi.json and look for the review-states and looks paths.

Closes #5382