[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort) — the three lint pcapkit, and no pcapkit/ file changed; the two new files are isort -l100 and mypy clean, and actionlint/shellcheck report nothing new

• make test passes, and a test case covers the change — ran the affected test files, not the whole suite

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Description of your pull request and other information

Change. Option (1) from #1674. The new util/vendor_code_changed.py (stdlib only) compares each file verify-changed-files lists with HEAD. It compares ASTs, with every bare string statement dropped; comments never reach the AST. A file counts as code if it is new, deleted, non-Python, outside pcapkit/const/, has a changed mode, does not parse, or is identical to HEAD. cron-vendor.yml bumps, commits and pushes as before only when some file is code. Otherwise it commits "Updated vendor documentation without a version bump" and pushes, without running bump_version.py. If the classifier step itself fails (continue-on-error), the bump stands.

Measured. On b5–b12's real diffs, b6, b7, b9, b10, b11 and b12 come out comment-only. b5 (_missing_) and b8 (pjj_player_disc → newmood_player) come out as code.

What the push triggers. Create Release still runs when Vendor Update completes, as it already does after a crawl that changes nothing. version_check reads an unchanged __version__, so its evidence says the version is already published. That skips the gate and every publisher (test_the_gate_skips_when_everything_is_already_published, test_release_gates.py:2051). Unit Tests runs on the pushed commit, and its completion starts Vendor Update again.

No loop. That second crawl should find nothing. If it finds more comment changes, they are held, not committed: the step reads github.event.workflow_run.head_commit (in the payload schema, octokit/webhooks workflow-run.schema.json; Unit Tests run 38458870161's head_commit holds the bot's email and the full message). So one documentation commit never follows another. Bumps still need code changes, as today.

Tests. tests/project/test_vendor_comment_only_no_bump_1674.py has 23 tests: the script on fixtures, a step-by-step walk of the job, and the commit step run in a scratch repo. All pass here (pytest: 23 passed, 30 subtests). On origin/main they all fail (unittest: FAILED (failures=41)). Each of 12 mutations to the workflow or the script makes at least one test fail. The related release-gate, verdict, isort, bump-version and doc-claim tests pass.

#1677. Its only cron-vendor.yml hunk applies cleanly on top of this change (patch --dry-run).

Closes #1674

[JarryShaw]

Verdict: GOOD TO GO at 618217788. A Sonnet cross-review checked the Opus worker's change. I re-ran the new test with test_release_gates.py: 143 passed.

What it does.

• Classify. A new stdlib script, util/vendor_code_changed.py, compares each changed file with HEAD by AST, with docstrings dropped; comments never reach the AST. New, deleted, non-Python or unparsable files, and anything outside pcapkit/const/, count as code.
• Commit comment-only changes without a bump. cron-vendor.yml then commits a comment-only regeneration as "Updated vendor documentation without a version bump". If the classifier fails, the old bump path runs.
• Prevent a loop. A run started by the bot's own documentation commit holds the changes instead of committing again.
• Nothing gets released. Create Release's version_check finds the version already published, so a documentation commit releases nothing.

Measured on history. b6, b7 and b9-b12 classify as comment-only; b4, b5 and b8 as code. The reviewer replayed each bump and tried 13 mutations of its own, every one of them caught.

Unverified until a live run: that workflow_run.head_commit carries the bot's commit, which the hold depends on. It matches the webhook schema and run 38458870161. Even if it is empty, a second crawl finds nothing.

This merges cleanly with #1677.