From 065de8819a698114562e47f4489780d02b25da8e Mon Sep 17 00:00:00 2001 From: Tim Stranske Date: Sat, 13 Jun 2026 23:37:13 -0500 Subject: [PATCH] feat(ci): add maint-48 monthly docs-drift audit (seeds a scoped lane-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) --- .github/docs-drift-audit-template.md | 31 ++++++++ .../workflows/maint-48-docs-drift-audit.yml | 70 +++++++++++++++++++ docs/ci/WORKFLOWS.md | 1 + docs/ci/WORKFLOW_SYSTEM.md | 4 ++ tests/workflows/test_workflow_naming.py | 1 + 5 files changed, 107 insertions(+) create mode 100644 .github/docs-drift-audit-template.md create mode 100644 .github/workflows/maint-48-docs-drift-audit.yml diff --git a/.github/docs-drift-audit-template.md b/.github/docs-drift-audit-template.md new file mode 100644 index 000000000..aac6b28c1 --- /dev/null +++ b/.github/docs-drift-audit-template.md @@ -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 ``" 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._ diff --git a/.github/workflows/maint-48-docs-drift-audit.yml b/.github/workflows/maint-48-docs-drift-audit.yml new file mode 100644 index 000000000..c8f6cd45b --- /dev/null +++ b/.github/workflows/maint-48-docs-drift-audit.yml @@ -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" + 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" diff --git a/docs/ci/WORKFLOWS.md b/docs/ci/WORKFLOWS.md index 9e2312fb3..3ee434082 100644 --- a/docs/ci/WORKFLOWS.md +++ b/docs/ci/WORKFLOWS.md @@ -123,6 +123,7 @@ The gate uses the shared `.github/scripts/detect-changes.js` helper to decide wh * [`maint-62-integration-consumer.yml`](../../.github/workflows/maint-62-integration-consumer.yml) runs daily at 05:05 UTC, on release publication, or by manual dispatch to execute the integration-repo scenarios via the reusable Python CI template and keep the integration failure issue updated. * [`maint-65-sync-label-docs.yml`](../../.github/workflows/maint-65-sync-label-docs.yml) synchronizes `docs/LABELS.md` to consumer repositories weekly (Sundays 00:00 UTC) or via manual dispatch. * [`maint-66-monthly-audit.yml`](../../.github/workflows/maint-66-monthly-audit.yml) performs comprehensive monthly workflow health audits, collecting statistics and creating actionable tracking issues. +* [`maint-48-docs-drift-audit.yml`](../../.github/workflows/maint-48-docs-drift-audit.yml) seeds a monthly scoped docs-drift audit issue (deduped) for the lane fleet to diff the canonical docs against reality and open fix PRs. * [`maint-60-release.yml`](../../.github/workflows/maint-60-release.yml) creates GitHub releases automatically when version tags (`v*`) are pushed. ## Agents Control Plane diff --git a/docs/ci/WORKFLOW_SYSTEM.md b/docs/ci/WORKFLOW_SYSTEM.md index 0f2397f11..650e7d1c5 100644 --- a/docs/ci/WORKFLOW_SYSTEM.md +++ b/docs/ci/WORKFLOW_SYSTEM.md @@ -563,6 +563,10 @@ Keep this table handy when you are triaging automation: it confirms which workfl at 06:00 UTC), collecting run statistics, identifying high-failure workflows, listing never-run workflows, and creating/updating a tracking issue with an actionable checklist. +- **Maint 48 Docs Drift Audit** – `.github/workflows/maint-48-docs-drift-audit.yml` + seeds one scoped docs-drift audit issue per month (1st at 07:00 UTC, deduped) + so the lane fleet diffs the canonical docs against the current tree and opens + fix PRs. Doc-rot is the audit's most pervasive defect class. - **Maint 45 Cosmetic Repair** – `.github/workflows/maint-45-cosmetic-repair.yml` is a manual workflow. It runs pytest and the guardrail fixers, then opens a labelled PR if changes are needed. diff --git a/tests/workflows/test_workflow_naming.py b/tests/workflows/test_workflow_naming.py index 96b70dceb..ef3b42a72 100644 --- a/tests/workflows/test_workflow_naming.py +++ b/tests/workflows/test_workflow_naming.py @@ -239,6 +239,7 @@ def test_workflow_display_names_are_unique(): "maint-45-cosmetic-repair.yml": "Maint 45 Cosmetic Repair", "maint-46-post-ci.yml": "Maint 46 Post CI", "maint-47-disable-legacy-workflows.yml": "Maint 47 Disable Legacy Workflows", + "maint-48-docs-drift-audit.yml": "Maint 48 Docs Drift Audit", "maint-50-tool-version-check.yml": "Maint 50 Tool Version Check", "maint-51-dependency-refresh.yml": "Maint 51 Dependency Refresh", "maint-sync-action-versions.yml": "Maint Sync Action Versions",