Skip to content

LGC-2026-06-17T045443

LGC-2026-06-17T045443: Guard AGENTS.md versions + add semantic drift-audit workflow (#8891)
@malmstein malmstein tagged this 16 Jun 20:42 
Task/Issue URL:
https://app.asana.com/1/137249556945/project/1214901934989258/task/1214933126123976

### Description
Builds on the merged AI config check (#8762) to cover the half a
deterministic gate can't: keeping the AI docs honest about facts and
behaviour.

- **AGENTS.md version guard** — extends `AiConfigChecker` with an
AGENTS.md-scoped, fence-aware check that flags any tool name followed by
a semver. AGENTS.md intentionally states no hardcoded versions (they
live in the build files and are pointed to); this keeps that invariant
from eroding. Scoped to AGENTS.md only — the rule files legitimately
carry example versions (e.g. `dependency-updates.mdc`'s library table).
+4 tests.
- **Semantic drift-audit workflow** — a `gh-aw` workflow
(`drift-audit.md`) that catches *semantic* drift: when a rule's
described behaviour no longer matches the code it documents (e.g. a
refactored Wide Events flow). Area-mapped (rule doc → code paths),
surveys recent develop activity, opens a draft PR with the fix. Never
merges.

Division of labour: `aiConfigCheck` (from #8762) is the synchronous
structural gate; this adds the version guard to it and a periodic agent
for the semantic drift a gate can't see.

Supersedes #8809 and #8811 (their standalone Python checker is replaced
by the in-`AiConfigChecker` guard, and `path-exists` is redundant with
#8762's dangling-reference check).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

### Steps to test this PR
- [x] `./gradlew :buildSrc:test --tests
"com.duckduckgo.gradle.AiConfigCheckerTest"` passes
- [x] `./gradlew aiConfigCheck` → `AI config check passed: 0
violations.`
- [x] Add `Kotlin 1.9.24` to AGENTS.md, run `./gradlew aiConfigCheck` →
fails reporting the restated version

### UI changes
| Before  | After |
| ------ | ----- |
| No UI changes | No UI changes |

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> New scheduled agent workflow uses secrets (ANTHROPIC_API_KEY,
GT_DAXMOBILE) and can open draft PRs to develop; AiConfigChecker change
is narrow and well-tested.
> 
> **Overview**
> Extends **`aiConfigCheck`** with a new **`checkVolatileFacts`** step
on **`AGENTS.md` only**: fence-aware detection of known tool names
followed by semver strings, so shared agent docs don’t restate
Gradle/Kotlin/etc. versions that belong in build files.
**`.cursor/rules`** example versions stay allowed; four unit tests cover
pass, fail, rule-file exemption, and fenced blocks.
> 
> Adds a **gh-aw “AI-docs Semantic Drift Audit”** workflow
(`drift-audit.md` plus compiled **`drift-audit.lock.yml`**): runs on a
**every-three-days** schedule (and manual dispatch), uses Claude with
read-only GitHub MCP to compare recent **`develop`** merges against rule
docs via an area map, and may open **at most one draft PR** (docs only,
**`[Drift Audit]`** label) when described behaviour no longer matches
code. **`actionlint.yaml`** ignores shellcheck noise on generated
**`*.lock.yml`** files.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
aa29788ba4a66c62667504e4422b017873832b51. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Assets 2
Loading