Repository navigation
ci(pr-hygiene): require a Reader: list on take-away diffs - #16115
Conversation
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- .github/workflows/code-review.yml:534 -- False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Detector hardcodes today's seam names with no drift pin; a rename in src/ silently de-fangs the gate it was built for. WatchThe shapes match literal strings ( Suggestions
[DESIGN-REVIEWED] 0e05270 Description read[DESCRIPTION-READ] 49cb6a396dd0df13b975165006d4df575cc7442a8c761ad4daf66fdbe4627aec That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the author's "4 flagged in the last 150 main commits" false-positive run — it is the one claim this gate's blast radius rests on and CI never re-measures it. What this change shipsInventory (8 items) — 8 justifiedIntent: stop a PR that takes something away from merging without naming the readers it breaks — an ADDITION (new CI gate), with provenance in two linked regressions (#13273 reverted by #16072; #12798 fixed by #16016/#16033).
Checked for a second spelling: [FIRST-PRINCIPLES-REVIEWED] 0e05270 Description read[DESCRIPTION-READ] 2dc70f6a3ae9b07f947932b9bc84f3f34388778fc2e667aba15d7cac9530f954 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsThe take-away gate's detector both misses a real take-away (a FINDING — .github/workflows/code-review.yml:534 — FINDING — .github/scripts/take_away_check.py:65 — [OPUS-REVIEWED] 0e05270 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
85f7cdf to
7600103
Compare
7600103 to
54e3f65
Compare
54e3f65 to
1af9485
Compare
A diff that hides, deletes, tightens or migrates something must list every reader of it under ## Backwards compatibility. #13273 and #12798 both passed CI and broke readers nobody listed. Adds .github/scripts/take_away_check.py (presence/format only), the template format, a convention doc and one AGENTS.md route.
1af9485 to
0e05270
Compare
|
|
|
|
|
|
Problem / Motivation
Goal: A PR that hides, deletes, tightens or migrates something must list every reader of that thing on main, so a reader on another entry point is not broken unnoticed.
Two take-away PRs passed CI and broke readers their authors never listed:
<config_dir>/appsfrom cron children. Every app cron that imports its ownapps/<app>/srcbroke (reverted by revert: #13273 apps-tree mask breaks every app script cron #16072; re-expose follow-up fix(cron): re-expose an app's code directories read-only inside the apps-tree mask #16061). Its body said "Compatible: ... No documented, reachable capability is removed" -- it checked the docs, not the code readers.config.agentsrows after checking only the Crew page. Chat resume, subagent continue/spawn and the prompt builder still read those rows (fixed by fix(chat): resume a chat whose synced crewmate the prune removed #16016 + fix(crew): keep every record that picked a pruned crewmate executable #16033).Why it matters
Both breaks reached main and hit every user of the affected entry point (all app script crons; resumed chats and subagent runs of a pruned crewmate). The template's
## Backwards compatibilitysection let an author answer from the Goal; nothing asked for the code readers.Not a goal
design-review.yml); a separate item parses the sameReader:format there.## Backwards compatibilitya required section for every PR.What changed (motivation → approach → change)
Readers were missed because nothing asked for them → make the author list them in a fixed, parseable line, and fail PR Hygiene when the diff has a take-away shape but the body lists none.
.github/PULL_REQUEST_TEMPLATE.md:## Backwards compatibilitynow asks, for a take-away diff, for one line per reader:Reader: <path>:<symbol> -- <entry: chat|cron|subagent|app|crew page|release> -- <why it still works | test name>, found by grepping origin/main across every entry point; otherwise exactly oneRemoves nothing: <why>line..github/scripts/take_away_check.py(new): reads the merge-base diff andPR_BODY(env, data only). Four shapes, each visible on one diff line, in product code (src/) only: a*_migration.pyfile with a changed code line (a comment-only edit is not), a newextra_hidden_dirs=argument (an exact pass-throughextra_hidden_dirs=extra_hidden_dirsis not), aconfig.agentsrowdel/.pop, a removed module-level publicdef(column 0, not re-added in the same file; a def moved to another module counts, its old import path breaks). Test files are skipped; a re-wrapped call is not a new hit. Removed config keys and stricter validators are left out: a line diff cannot tell a removed field from docstring prose or a parameter, so those shapes hard-failed unrelated edits. The doc says the rule still applies to them. On a hit, at least one well-formedReader:line must sit in## Backwards compatibility(outside comments and fences);Removes nothing:does not satisfy a hit; malformed lines are named..github/workflows/code-review.yml, PR Hygiene: a merge-base step (copied from the sibling jobs) and "Require a reader list on take-away diffs", after the Pattern harvest step. The body reaches the script only via env. Like the template-sections step above it, the new step skipsdependabot[bot], which writes its own body.docs/system-specs/common/take-away-changes.md(new): the rule, what CI checks, fix(cron): mask the apps tree from every cron child that runs model-supplied code #13273 and feat(members): prune sync-generated crewmates once at startup #12798 as worked examples with the reader lines they should have carried. Indexed indocs/system-specs/common/README.md.AGENTS.md: one routing row to that doc.Hit rate on the last 150 main commits: 4 flagged (the #13273 revert, a removed public
search_skills, twocrewmate_prune_migration.pyfollow-ups) -- each does take something away.Backwards compatibility
Removes nothing: adds a template paragraph, a new PR Hygiene step and a script; no existing step, key or function changes. The new step fails only PRs whose diff has a take-away shape and lists no
Reader:line (this PR's own diff has none -- verified by running the script on it).Tests
test/test_take_away_check.py(new):test/fixtures/take_away/). Both are flagged; both existing bodies FAIL (fix(cron): mask the apps tree from every cron child that runs model-supplied code #13273's has the section but noReader:line); adding one reader line makes fix(cron): mask the apps tree from every cron child that runs model-supplied code #13273 pass.src/, comment-only migration edit, re-wrapped call, exact pass-through mask, private/indented/re-signatured def, pure addition) are not; a same-named test helper does not hide a removed API.Removes nothing:on a hit, all six entries, bullets, malformed lines named, lines in comments/fences/other sections ignored, CRLF.::error::annotation; a body with shell/Python payloads is data, not code (the child runs intmp_path).PR_BODYin env (never inrun:), after the merge-base step; the template carries the exact line formats.Locally:
test_take_away_check.py,test_pr_hygiene_guidance.py,test_prepare_pr_body_register.py,test_fix_loop_discipline.py-- 95 passed. flake8 and isort clean on the new files.Manual verification
Ran the script on the full #13273 and #12798 diffs with their real bodies (both exit 1) and on this PR's own diff (exit 0).
Related Issues
Follows the #13273 / #12798 regressions (fixes #16072, #16016, #16033).
Checklist