Repository navigation
Description
Documentation cleanup owed after the #834 CI path-trigger epic. Each item is independent; one PR can carry them all.
1. Retire the old workflow names from AGENTS.md
The epic collapsed the per-concern workflows into per-domain ones. AGENTS.md still names the retired files and jobs throughout (conventions.yml, python-test.yml, ts-test.yml, rust-test.yml, the "seven non-internals-checks Conventions lanes", docs.yml). Replace with the surviving set: dirsql-python-ci.yml, dirsql-typescript-ci.yml, dirsql-rust-ci.yml, plugin-dirsql-embedding-ci.yml, internals-checks-ci.yml, internals-distcheck-ci.yml, docs-ci.yml, docs-release.yml, release-ci.yml, changelog-check.yml, putitoutthere-config-check.yml, release.yml.
Also affects agents/reference/testing-conventions-ci.md and agents/reference/testing-gates.md, which describe the gates as living inside conventions.yml.
2. Rewrite the stale Mergify section
AGENTS.md's "PR Monitoring" section is written around anchor conditions — "success_conditions therefore names one anchor per unconditionally-triggered workflow (Conventions, Release Precheck, Release Config Check, Changelog Check)", "renaming a caller job id … requires the matching .mergify.yml edit in the same PR", "never anchor a path-filtered workflow", and the diagnostic guidance for "an unmet anchor".
#881 deleted every anchor. .mergify.yml on main is now:
success_conditions:
- "#check-failure = 0"All of that guidance is now wrong, including the failure modes it teaches contributors to look for. Rewrite against the current file.
3. Document the zero-check-merge policy
The corollary of #881 that nothing currently states: a PR that triggers zero checks is vacuously green and will merge. This is deliberate — it is the accepted cost of removing the anchors, whose coupling to trigger filters deadlocked the gate in #832 — but it is load-bearing and undocumented. Write it down explicitly, along with the consequence that a path-filtered workflow still in flight does not hold the gate.
The one class where this is a genuine gap rather than an accepted cost is CI-config-only PRs; that is tracked separately in #862 and should be cross-referenced here rather than re-argued.
4. Amend the #834 rules text for READMEs
The maintainer decision recorded during the stack's final review: package README edits keep requiring a changelog fragment. The gate behavior is correct as written (_is_exempt in internals/checks/src/checks/changelog_gate/decide.py treats READMEs as code) and needs no code change — only the rules text does. Amend #834's wording to:
READMEs → release-ci + changelog-check
READMEs ship in all three published artifacts (PyPI long-description, npm tarball, crate), which is why release-ci.yml deliberately does not exclude them while it does exclude fragment dirs.
5. Fix #885, and the MIGRATIONS.md asymmetry it sits next to
#885 ("Docs site publishes a permanently stale Migrations page") names the publisher as docs-deploy.yml. That file does not exist — the publisher is docs-release.yml. Correct the issue, then note the related asymmetry while fixing it:
| Workflow | Event | MIGRATIONS.md in paths:? |
|---|---|---|
docs-ci.yml |
pull_request |
no |
docs-release.yml |
push to main |
yes |
So a MIGRATIONS.md edit shows zero checks on its PR and then runs the publisher on main — the exact pre-#882 shape that docs-ci.yml was created to close, surviving for one file. #885's chosen fix (delete docs/migrations.md, drop MIGRATIONS.md from the publisher's paths) resolves the asymmetry by removing the trigger rather than adding it, which is the right direction given the file is frozen. Worth stating explicitly in that issue so the two entries are not re-added independently later.
Separately: docs-ci.yml has no self-path (.github/workflows/docs-ci.yml is absent from its own paths:), which #862's spec row 16 would flag.
Activity
thekevinbot commentedon Aug 20, 2026
Still owed, and its scope moved under it again: items 2 and 3 were written against anchor-less Mergify, but #950 has since removed Mergify entirely and restored pr-monitor as the gate (plus #954 dropped CODEOWNERS, #955 added gate concurrency). The rewrite should target the pr-monitor world, not
.mergify.yml. Items 1 and 4 unchanged. Note AGENTS.md currently has ~13 staleMergify/conventions.ymlreferences.thekevinbot commentedon Aug 20, 2026
Item 1 misses one file:
agents/reference/e2e-attestation.md:6also places the gate inside the retired workflow — "The freshness check runs inside the reusable workflow (conventions.yml, thepython-sdk/typescript-sdke2e-verifygate)".So the item-1 file set is AGENTS.md plus all three of
agents/reference/{testing-conventions-ci,testing-gates,e2e-attestation}.md.Generated by Claude Code