Repository navigation
Doc staleness via git history (context.drift) - #11
Merged
Merged
Conversation
A context doc is drifting when it hasn't been committed for 90+ days and 25+ later commits edited the files it names or added/removed files in the directories it describes (manifests, lockfiles and docs excluded). Local git log only; n/a outside git, in shallow clones and for docs without code references. Symlinked docs are judged by their target and docs with uncommitted edits are skipped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Conflicts: src/checks/index.ts (docHistoryCheck registered alongside agentToolingChecks and runChecks), README.md (check table keeps every item and adds the 'not drifting' Context item; both the --run and doc-drift paragraphs kept; roadmap ticks doc staleness) and CHANGELOG.md (context.drift added to the single [Unreleased] Added list). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Roadmap item: Doc staleness via git history (a doc untouched while the code it references churned).
What
New check
context.drift(context category, weight 1) insrc/checks/doc-history.ts. It complementscontext.fresh: that check catches references to paths that are gone, while this one catches docs describing code that changed underneath them.git logonly, no network. For each context doc (root and nestedAGENTS.md/CLAUDE.md, Cursor rules, Copilot instructions), the check takes:context.freshdoes. Manifests, lockfiles, changelogs and other docs are excluded, because they change for unrelated reasons.<doc commit>..HEAD -- <refs>(--no-merges, capped at 5000 commits) and counts commits that:src/don't make an architecture section stale; new or deleted modules do.CLAUDE.md -> AGENTS.md, common in pydantic-ai) are judged by their target, because a symlink's own commit never changes.fetch-depth: 0) and for docs that reference no code. CI checkouts default to depth 1, so CI scores don't move unless you fetch full history.Example finding (excalidraw):
Tests
test/doc-history.test.ts(6 tests). It builds synthetic repos with backdatedGIT_COMMITTER_DATEcommits and covers:CLAUDE.mdis reported once, under its targetgit clone --depth 1 file://…) and for prose-only docsnpm run check && npm run buildpass (89 tests). Self-score is still 100/100.Scores (before → after)
On the 14-repo comparison set, only vitest moved: context 87 → 88, overall 91 → 91. Its docs were recently edited, so it gains a passing check. Repos without context docs are unchanged.
Extra full-history clones (
--filter=blob:none, read-only):Cost: pydantic-ai (6k files, 5.6k commits, 39 docs) adds ~290 ms; vitest ~50 ms.
Decision for the owner
The 90-day / 25-commit thresholds (exported as
MIN_AGE_DAYS/MIN_COMMITS) were tuned so that none of the actively maintained docs above trip them. Excalidraw's CLAUDE.md is the only hit. Tighter thresholds would catch more, at the risk of nagging healthy repos.🤖 Generated with Claude Code