The deadlock
scripts/ci/vendored-patch-audit.sh cannot be satisfied by a Dependabot PR that carries a major version bump. Two rules combine:
1. The exemption is non-major only.
if [ "$PR_ACTOR" = "dependabot[bot]" ] && \
[ -n "$DEPENDABOT_UPDATE_TYPE" ] && \
[ "$DEPENDABOT_UPDATE_TYPE" != "version-update:semver-major" ]; then
echo "✅ vendored-patch-audit: exempt — Dependabot $DEPENDABOT_UPDATE_TYPE bump (#2975)"
2. The audit doc must be in the PR's own diff.
CHANGED_FILES=$(git diff --name-only "$BASE_REF"...HEAD)
AUDIT_DOC=$(grep -E '^docs/dependency-audits/[0-9]{4}-[0-9]{2}-[0-9]{2}-.+\.md$' <<< "$CHANGED_FILES" || true)Dependabot does not write audit docs and never will. So a semver-major Dependabot PR fails the gate at open, cannot fix itself, and cannot be fixed by a separate documentation PR either. It parks until a human notices and does something manual.
Both rules are individually right. The exemption should not cover majors, and an audit doc that is not in the diff is not an audit of that diff. The gap is that nothing tells anyone what to do about the combination.
How it showed up
#3686, #3683 and #3681 bump @microsoft/agent-governance-sdk from 4.0.0 to 5.0.0 in the three CLI packages. All three had been red on Dependency Audit Trail since 2026-08-11 with no indication that the failure was structural rather than a problem with the change. I worked around it in #3721 by cherry-picking the three commits onto one branch and adding the audit doc alongside them, which is not something the next person will necessarily think to do.
Options
A. Let the doc arrive on a later commit to the same branch. Smallest change, and no code change at all: a maintainer pushes the audit doc onto the Dependabot branch and the gate passes on re-run. The cost is that pushing to a Dependabot branch takes it out of Dependabot's management, so it stops rebasing and stops superseding itself.
B. Have the gate emit the doc skeleton it wants. On failure, write a docs/dependency-audits/<date>-<slug>.md stub to the job summary, pre-filled with the package names and versions parsed from the lockfile diff and the three required headings. Turns a dead end into a copy-paste. Does not change what the gate accepts.
C. Accept an audit doc referenced by path from the PR body. Lets one doc cover a set of related bumps without consolidating branches. More surface to get wrong, and weakens the "audits the diff" property, so probably not worth it.
D. Have Dependabot's own config open majors as drafts with a checklist. Does not fix the gate, but stops a structurally-blocked PR from sitting in the ready queue looking like a normal red build.
B is the smallest change that helps every future case, and it composes with A.
Related
The deadlock
scripts/ci/vendored-patch-audit.shcannot be satisfied by a Dependabot PR that carries a major version bump. Two rules combine:1. The exemption is non-major only.
2. The audit doc must be in the PR's own diff.
Dependabot does not write audit docs and never will. So a semver-major Dependabot PR fails the gate at open, cannot fix itself, and cannot be fixed by a separate documentation PR either. It parks until a human notices and does something manual.
Both rules are individually right. The exemption should not cover majors, and an audit doc that is not in the diff is not an audit of that diff. The gap is that nothing tells anyone what to do about the combination.
How it showed up
#3686, #3683 and #3681 bump
@microsoft/agent-governance-sdkfrom4.0.0to5.0.0in the three CLI packages. All three had been red onDependency Audit Trailsince 2026-08-11 with no indication that the failure was structural rather than a problem with the change. I worked around it in #3721 by cherry-picking the three commits onto one branch and adding the audit doc alongside them, which is not something the next person will necessarily think to do.Options
A. Let the doc arrive on a later commit to the same branch. Smallest change, and no code change at all: a maintainer pushes the audit doc onto the Dependabot branch and the gate passes on re-run. The cost is that pushing to a Dependabot branch takes it out of Dependabot's management, so it stops rebasing and stops superseding itself.
B. Have the gate emit the doc skeleton it wants. On failure, write a
docs/dependency-audits/<date>-<slug>.mdstub to the job summary, pre-filled with the package names and versions parsed from the lockfile diff and the three required headings. Turns a dead end into a copy-paste. Does not change what the gate accepts.C. Accept an audit doc referenced by path from the PR body. Lets one doc cover a set of related bumps without consolidating branches. More surface to get wrong, and weakens the "audits the diff" property, so probably not worth it.
D. Have Dependabot's own config open majors as drafts with a checklist. Does not fix the gate, but stops a structurally-blocked PR from sitting in the ready queue looking like a normal red build.
B is the smallest change that helps every future case, and it composes with A.
Related