feat(ci): maint-48 monthly docs-drift audit - #2367
Conversation
…actionable issue) Doc-rot is the 2026-06 audit's most pervasive defect class. maint-48 seeds one deduped, scoped "[Docs Drift Audit]" issue per month (1st, 07:00 UTC) listing the canonical docs to diff against the tree; the lane fleet picks it up and opens fix PRs. Mirrors maint-66's monthly-audit-issue pattern. Routes the LLM diffing through the cost-managed lanes (Sonnet-pinned) rather than an inline Claude Action, which post-2026-06-15 bills against the metered Agent-SDK credit. Registered in EXPECTED_NAMES + both inventory docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
GitHub Actions
Inactive
Workflow source neededPR #2367 needs either a linked GitHub issue or one valid non-issue Workflow Source before PR metadata automation can manage it safely. Please do one of:
Once a valid source is present, this warning will not be reposted. |
Automated Status SummaryHead SHA: 72b73d0
Coverage Overview
Coverage Trend
Top Coverage Hotspots (lowest coverage)
Low Coverage Files (<50.0%)
Updated automatically; will refresh on subsequent CI/Docker completions. Keepalive checklistScopeNo scope information available Tasks
Acceptance criteria
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 065de8819a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| persist-credentials: false | ||
|
|
||
| - name: Create the docs-drift audit issue (deduped) | ||
| if: ${{ inputs.create_issue != false }} |
There was a problem hiding this comment.
On the monthly schedule trigger there is no inputs.create_issue value; GitHub Actions loose equality treats the missing/empty value the same as false, so this condition is false and the only issue-creation step is skipped. The scheduled audit will therefore only write the summary and never seed the monthly docs-drift issue unless it is run manually with the default input.
Useful? React with 👍 / 👎.
| fi | ||
| gh issue create --repo "$REPO" --title "$title" \ | ||
| --body-file .github/docs-drift-audit-template.md \ | ||
| --label "documentation,maintenance" |
There was a problem hiding this comment.
For manual runs that do create the issue, these labels leave it outside the inspected agent entry points: agents-auto-pilot.yml only starts on the agents:auto-pilot label, while agents-71-codex-belt-dispatcher.yml selects issues with agent:<key>,status:ready. With only documentation,maintenance, the promised lane-fleet pickup never happens and the audit issue sits for humans to route manually.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a new maintenance entry point to keep documentation aligned with the repo by seeding a recurring “docs drift” audit issue, and updates the workflow inventories/tests so the new workflow is tracked consistently.
Changes:
- Introduces
maint-48-docs-drift-audit.yml, a monthly (and manually-dispatchable) workflow that creates a single deduped[Docs Drift Audit]issue using a body template. - Adds
.github/docs-drift-audit-template.mdto standardize the audit issue checklist and scope. - Registers the new workflow in inventory docs and the workflow name mapping test.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
tests/workflows/test_workflow_naming.py |
Adds maint-48-docs-drift-audit.yml to EXPECTED_NAMES so naming/inventory tests stay green. |
docs/ci/WORKFLOWS.md |
Documents the new maintenance workflow in the inventory list. |
docs/ci/WORKFLOW_SYSTEM.md |
Adds Maint 48 to the “Maintenance & repo health” reference table with trigger + purpose. |
.github/workflows/maint-48-docs-drift-audit.yml |
New monthly issue-seeder workflow with dedupe logic and scoped permissions. |
.github/docs-drift-audit-template.md |
New issue body template defining scope, verification steps, and completion criteria. |
What
Adds
maint-48-docs-drift-audit.yml— a monthly workflow that seeds one deduped, scoped[Docs Drift Audit]issue for the lane fleet to diff the canonical docs against the current tree and open fix PRs. Body template in.github/docs-drift-audit-template.md.Why
Doc-rot was the audit's most pervasive defect class (most of §1/§4 findings were stale docs).
maint-66's monthly audit only carries a static "update docs" checklist; nothing systematically detects drift. This closes that gap on a monthly cadence.Design choice (issue-seeder vs inline Claude Action)
The audit sketched "a monthly claude-code-action that diffs docs and opens a fix PR." I implemented the same outcome via the system's issue→agent mechanism (mirrors
maint-66) rather than a dedicated inline Claude Action, because:To diff inline instead, swap the issue-create step for a
claude-code-actionrun — easy follow-up.Validation
EXPECTED_NAMES+ both inventory docs;tests/workflows/green (24 passed).persist-credentials: false, scopedissues: write.[Docs Drift Audit]issue at a time.🤖 Generated with Claude Code
Note
Low Risk
Scheduled issue-seeder with read-only checkout and narrow
issues: write; no changes to auth, Gate, or agent execution paths beyond a new maintenance entry point.Overview
Adds a monthly maintenance workflow (
maint-48-docs-drift-audit.yml) that runs on the 1st at 07:00 UTC (and viaworkflow_dispatch) to create at most one open[Docs Drift Audit]issue per month, using a new checklist body template (.github/docs-drift-audit-template.md) so lane agents diff canonical docs against the repo and open small fix PRs—instead of relying only onmaint-66’s static “update docs” checklist.The workflow dedupes on open issues with that title prefix, uses scoped
issues: write+persist-credentials: false, and documents the choice to route LLM work through the existing issue→agent path rather than an inline Claude Action.Inventory alignment:
docs/ci/WORKFLOWS.md,docs/ci/WORKFLOW_SYSTEM.md, andtests/workflows/test_workflow_naming.py(EXPECTED_NAMES) register Maint 48 Docs Drift Audit so workflow inventory tests stay green.Reviewed by Cursor Bugbot for commit 065de88. Bugbot is set up for automated code reviews on this repo. Configure here.