Remove the shape a review reply keeps failing in

[ptr727]

Implements the decision recorded on #580, which closed with the reply-and-resolve helper carried forward as its own TODO.md cluster and the dependency it waited on already met.

Why a helper rather than a firmer rule

A reply-and-resolve run by hand keeps failing the same way: a GitHub node id typed into a mutation. Three instances are on record. The third happened while preparing this cluster, when gh-write-guard refused a resolveReviewThread mutation carrying an id hand-typed out of the previous query's output, roughly an hour after the same session quoted that exact rule in a pull request body.

The rule is stated in GOVERNANCE.md and again in the host-level guidance, and the agents that broke it had read both. That says the shape of the operation fails rather than the reader's knowledge of the rule, so this changes the shape.

What reply does

python3 scripts/pr_review.py reply <N> --repo <owner>/<name> \
  --match "<words from the finding>" --body "<answer>" --resolve

It queries the thread id itself and passes it straight to the mutation. There is deliberately no argument an id fits in, and a case asserts the id each mutation carries is the one that run just read.

• Selects on the finding's own words, not a line number. A fix push moves the line, which is how three replies once posted against nothing while the resolves still succeeded, closing the threads carrying no answer. Matching is case-insensitive, since the text is quoted back out of a digest by a reader.
• Every failure stops rather than falls back, because each alternative closes a finding while leaving it unanswered. No match exits 60 and prints the open threads, since a no-match and an already-answered thread read identically from here. More than one match exits 61 and prints both candidates rather than taking the first. A reply whose response carries no url, or whose body came back empty, exits 62 without resolving. A resolve that does not confirm exits 63, with the reply already posted.
• --resolve is opt-in, since a decline is resolved only once its evidence is in the thread.
• A target under another owner exits 64 before anything is read.

The trade this makes, stated rather than glossed

The script carried test_no_mutation_reaches_this_script, locking it read-only so that mutations stayed visible to the gh-write-guard PreToolUse hook. This reverses that, so the test is narrowed rather than deleted: every other state-changing call is still banned tree-wide and the mutation-document count is pinned at exactly two, so a third arriving is a write nobody reviewed as one.

The hook genuinely cannot see a write this script performs, since it sees python3 pr_review.py reply and no gh write. That is a real loss of a second pair of eyes. It is taken because what the hook guards against there is a fabricated id, and this removes that at the source instead of catching it afterwards.

The guard's other rule is re-implemented rather than assumed. in_scope refuses a target under an owner other than this checkout's, and it takes no GH_WRITE_GUARD_ALLOW escape: a grant this process can be handed is one the caller sets on the command that runs it, and a grant the caller writes for itself is not a grant. The cross-owner case goes through the runbook's explicit gh path, where the hook reads the maintainer's grant from the session instead. It is honest in the docs that this stops a mistake rather than a determined caller.

Corrections carried in this change

• The cluster's cost line was wrong. .github/copilot-instructions.md is carried at intent fidelity per spec/files.json, so the runbook edit is not hub-only. A sixth Detail under the Fleet Sweeps re-vendor entry records it, noting a repo still on the old copy is not broken, since the mutations that copy documents still work.
• OPERATIONS.md scoped the gh pr edit breakage to --base, narrower than this repo's own runbook, which states the same failure against --title/--body. The failure is in the mutation the command builds rather than the field asked for. Widened, with the runbook cross-referenced. Not exercised live here, since gh pr edit is a write.
• TODO.md carried a clause naming "The Prose Gate Scope Floor", a cluster that shipped and was deleted; the phrase appeared nowhere else in the tree.

GOVERNANCE.md is deliberately untouched. It owns the review contract and routes mechanics to .github/copilot-instructions.md, so naming the helper there would add a verbatim re-vendor for nothing.

Verification

Run from this checkout on the branch head:

• python3 scripts/test_pr_review.py — 103 tests, OK. The suite gains cases for selection without an id, cursor-followed pagination, ambiguity and no-match refusal, reply confirmation before resolve, owner scope, and argument validation.
• python3 scripts/test_prose_lint.py (190), python3 scripts/test_repo_gate.py (23), python3 spec/audit.py --selftest, python3 spec/validate.py, python3 scripts/repo_gate.py — all pass.
• python3 scripts/prose_lint.py . --check charset --check dupword --check spelling and --diff origin/develop --summary — both clean.
• markdownlint and editorconfig-checker over the tree — clean.
• python3 scripts/pr_review.py status 588 --repo ptr727/ProjectTemplate — a live read confirming the transport refactor, which routes gql through a shared gh_graphql that also checks the errors key rather than reading the null it leaves.

Not verified live: every success path of reply posts a public comment, so it has not been run against a real pull request. The logic is covered by mocked cases only, and the two refusal paths that make no network call were exercised directly. This pull request's own review round is the natural first live exercise.

Closes the TODO.md cluster "The Reply-and-Resolve Helper", deleted here per the file's own rule 9.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a hub-hosted reply helper to scripts/pr_review.py so review-thread replies and optional resolves can be performed without ever hand-typing a GitHub node id, and updates docs/tests accordingly.

Changes:

• Implement pr_review.py reply with thread selection by finding text (and optional --path) plus explicit refusal modes (no match / ambiguous / not confirmed / out of scope).
• Refactor GraphQL transport into gh_graphql() with explicit errors handling and safe variable passing (-f for strings).
• Update documentation/runbooks and tests; remove the now-landed TODO cluster entry.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
TODO.md	Removes the completed “Reply-and-Resolve Helper” cluster and cleans up a stale clause.
scripts/pr_review.py	Adds the reply subcommand, owner-scope guard, thread pagination/matching, and shared gh_graphql() transport.
scripts/test_pr_review.py	Adds coverage for selection/matching, pagination, refusal codes, confirmation-before-resolve, and scope enforcement.
scripts/README.md	Documents the new reply command and updates the script’s write-surface contract description.
OPERATIONS.md	Broadens the gh pr edit limitation documentation and points to the runbook section.
.github/copilot-instructions.md	Adds the recommended “use the hub’s helper” path before the hand-run mutation workflow.