feat(ci): maint-48 monthly docs-drift audit #2367
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| ## Summary | ||
| Monthly docs-drift audit. Doc-rot is this system's most pervasive defect class (the 2026-06 audit found stale counts/claims across the canonical docs). Diff the canonical docs below against the **current tree** and open focused fix PR(s) for any claim that no longer matches reality. | ||
|
|
||
| ## Scope — canonical docs to verify (this round) | ||
| For each, check that every concrete claim (file paths, counts, workflow names, command names, described behavior) matches the current repo: | ||
| - [ ] `README.md` — pipeline overview, consumer list, entry points | ||
| - [ ] `docs/ci/WORKFLOWS.md` + `docs/ci/WORKFLOW_SYSTEM.md` — workflow inventory (names, triggers, counts) | ||
| - [ ] `docs/STRUCTURE.md` — directory/file counts and key-directory prose | ||
| - [ ] `docs/INTEGRATION_GUIDE.md` — inputs/secrets/versioning claims vs the reusables | ||
| - [ ] `docs/keepalive/GoalsAndPlumbing.md` + `docs/keepalive/Agents.md` — labels, guardrails, agent routing | ||
| - [ ] `docs/AGENTS_POLICY.md` + `docs/LABELS.md` — protected-workflow list + canonical label inventory | ||
|
|
||
| ## How to verify (no hand-waving) | ||
| - Cross-check each claim against the actual file/command/workflow it describes; cite the source `path:line` in the fix PR. | ||
| - Where a doc-validation test exists it must stay green: `pytest tests/workflows/ -q` (e.g. `test_workflow_naming.py::test_inventory_docs_list_all_workflows` enforces that the inventory docs list every workflow). | ||
|
|
||
| ## Tasks | ||
| - [ ] For each drifted claim found, open a focused fix PR correcting the doc to match reality (link the source `path:line`). | ||
| - [ ] Keep PRs small and per-doc where practical; don't rewrite docs wholesale. | ||
| - [ ] If a doc is already accurate, tick its box with a one-line "verified vs `<evidence>`" note. | ||
|
|
||
| ## Non-Goals | ||
| - No scaffolding, no TODO-only edits, no net-new docs. | ||
| - Don't restructure/rewrite prose that is accurate — fix only drifted claims. | ||
| - Not a consumer-template sync (that's `maint-68`); fix the source docs here. | ||
|
|
||
| ## Done | ||
| All scope boxes ticked (verified or fixed); `tests/workflows/` green; doc claims match the tree. | ||
|
|
||
| --- | ||
| _Seeded monthly by `maint-48-docs-drift-audit.yml`. Dedup: one open `[Docs Drift Audit]` issue at a time._ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| name: Maint 48 Docs Drift Audit | ||
|
|
||
| # Monthly docs-drift audit. Doc-rot is this system's most pervasive defect class (the 2026-06 | ||
| # audit found stale counts/claims across the canonical docs). This seeds one scoped, | ||
| # agent-actionable issue per month so the lane fleet diffs the canonical docs against the | ||
| # current tree and opens fix PRs. | ||
| # | ||
| # Design note: the LLM diffing is done by whichever lane/keepalive agent picks the issue up | ||
| # (cost-managed via the configured models, Sonnet-pinned) rather than a dedicated inline Claude | ||
| # Action — which post-2026-06-15 bills against the metered Agent-SDK credit. Same outcome as the | ||
| # audit's "monthly docs-drift agent", routed through the system's own issue->agent mechanism | ||
| # (mirrors maint-66's monthly-audit-issue pattern). To diff inline instead, swap the create step | ||
| # for a claude-code-action run. | ||
|
|
||
| on: | ||
| schedule: | ||
| - cron: '0 7 1 * *' # 1st of each month, 07:00 UTC (after maint-66 monthly audit at 06:00) | ||
| workflow_dispatch: | ||
| inputs: | ||
| create_issue: | ||
| description: 'Create the docs-drift audit issue' | ||
| type: boolean | ||
| default: true | ||
|
|
||
| permissions: | ||
| contents: read | ||
| issues: write | ||
|
|
||
| concurrency: | ||
| group: ${{ github.workflow }}-${{ github.ref }} | ||
| cancel-in-progress: true | ||
|
|
||
| jobs: | ||
| seed-audit: | ||
| name: Seed monthly docs-drift audit issue | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v6 | ||
| with: | ||
| persist-credentials: false | ||
|
|
||
| - name: Create the docs-drift audit issue (deduped) | ||
| if: ${{ inputs.create_issue != false }} | ||
| env: | ||
| GH_TOKEN: ${{ github.token }} | ||
| REPO: ${{ github.repository }} | ||
| run: | | ||
| set -euo pipefail | ||
| title="[Docs Drift Audit] $(date +%B' '%Y)" | ||
| # Dedup: one open audit at a time (skip if last month's isn't done yet). | ||
| existing=$(gh issue list --repo "$REPO" --state open \ | ||
| --search '"[Docs Drift Audit]" in:title' --json number --jq '.[0].number // empty') | ||
| if [ -n "$existing" ]; then | ||
| echo "Open docs-drift audit issue already exists: #$existing — skipping." | ||
| exit 0 | ||
| 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: Useful? React with 👍 / 👎. |
||
| echo "Created docs-drift audit issue: $title" | ||
|
|
||
| - name: Summary | ||
| if: always() | ||
| run: | | ||
| { | ||
| echo "## Maint 48 Docs Drift Audit" | ||
| echo "Seeds one scoped \`[Docs Drift Audit]\` issue per month (deduped) for the lane fleet" | ||
| echo "to diff the canonical docs against reality and open fix PRs." | ||
| } >> "$GITHUB_STEP_SUMMARY" | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the monthly
scheduletrigger there is noinputs.create_issuevalue; GitHub Actions loose equality treats the missing/empty value the same asfalse, 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 👍 / 👎.