bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(drift-check): forbid per-tool subdirectory AGENTS.md duplicates

Browse Source 
Extends scripts/check-agent-docs-drift.sh to catch a second class of
agent-doc drift: per-tool subdirectory duplicates introduced by an
earlier 'centralize AI agent documentation references' refactor.

The refactor (visible in learning_ai_clock origin/main, commit c73fda7)
created .claude/AGENTS.md, .cline/AGENTS.md, .cursor/AGENTS.md as 1-line
redirect pointers, plus .devin/AGENTS.md (218 lines) and .devin/CONTEXT.md
(206 lines) with full duplicate documentation. All five duplicate the
canonical repo-root AGENTS.md.

The drift check now exits 1 if any of those five paths exist in any
repo listed in repos.txt. Also renumber comment markers (was 1..5,
now 1..6) and update the header comment.

Verified: bash scripts/check-agent-docs-drift.sh exits 0 with
'17 repos in sync' across the ecosystem.
This commit is contained in:
saravanakumardb1 2026-05-23 13:07:26 -07:00
parent 191b81756d
commit 88b57478aa
1 changed files with 31 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
scripts/check-agent-docs-drift.sh
View File

@ -11,11 +11,17 @@
# What is checked per repo: # What is checked per repo:
# 1. Legacy files MUST NOT exist (they used to duplicate AGENTS.md): # 1. Legacy files MUST NOT exist (they used to duplicate AGENTS.md):
# .cursorrules, .windsurfrules, .clinerules, CLAUDE.md # .cursorrules, .windsurfrules, .clinerules, CLAUDE.md
# 2. AGENTS.md MUST contain the canonical-behavior-pointer marker. # 2. Per-tool subdirectory AGENTS.md duplicates MUST NOT exist (an earlier
# 3. .github/copilot-instructions.md MUST contain the AUTO-GENERATED marker # "centralize agent docs" refactor introduced redirect pointers in
# .claude/, .cline/, .cursor/, .devin/ that duplicate the canonical
# repo-root AGENTS.md). Listed files:
# .claude/AGENTS.md, .cline/AGENTS.md, .cursor/AGENTS.md,
# .devin/AGENTS.md, .devin/CONTEXT.md
# 3. AGENTS.md MUST contain the canonical-behavior-pointer marker.
# 4. .github/copilot-instructions.md MUST contain the AUTO-GENERATED marker
# AND a reference to the canonical guidelines file. # AND a reference to the canonical guidelines file.
# 4. .aider.conf.yml MUST exist and reference AGENTS.md. # 5. .aider.conf.yml MUST exist and reference AGENTS.md.
# 5. .editorconfig MUST exist with the canonical first line "root = true". # 6. .editorconfig MUST exist with the canonical first line "root = true".
# #
# Repair: bash scripts/update-agent-docs.sh # Repair: bash scripts/update-agent-docs.sh
@ -33,6 +39,15 @@ if [[ ! -f "$REPOS_TXT" ]]; then
fi fi
LEGACY_FILES=(.cursorrules .windsurfrules .clinerules CLAUDE.md) LEGACY_FILES=(.cursorrules .windsurfrules .clinerules CLAUDE.md)
# Per-tool subdirectory duplicates (introduced by an earlier "centralize
# agent docs" refactor and superseded by single-source-of-truth).
LEGACY_SUBDIR_FILES=(
.claude/AGENTS.md
.cline/AGENTS.md
.cursor/AGENTS.md
.devin/AGENTS.md
.devin/CONTEXT.md
)
AGENTS_POINTER_MARKER="<!-- BEGIN: canonical-behavior-pointer (auto-managed) -->" AGENTS_POINTER_MARKER="<!-- BEGIN: canonical-behavior-pointer (auto-managed) -->"
COPILOT_GENERATED_MARKER="<!-- AUTO-GENERATED by learning_ai_common_plat/scripts/update-agent-docs.sh -->" COPILOT_GENERATED_MARKER="<!-- AUTO-GENERATED by learning_ai_common_plat/scripts/update-agent-docs.sh -->"
COPILOT_CANONICAL_REF="agent-behavior-guidelines.md" COPILOT_CANONICAL_REF="agent-behavior-guidelines.md"
@ -62,19 +77,26 @@ for repo in "${REPOS[@]}"; do
issues=() issues=()
# 1 — Legacy files must be gone. # 1 — Legacy root files must be gone.
for f in "${LEGACY_FILES[@]}"; do for f in "${LEGACY_FILES[@]}"; do
if [[ -e "${repo_dir}/${f}" ]]; then if [[ -e "${repo_dir}/${f}" ]]; then
issues+=("legacy file still present: $f") issues+=("legacy file still present: $f")
fi fi
done done
# 2 — AGENTS.md must have the canonical pointer block. # 2 — Legacy per-tool subdirectory duplicates must be gone.
for f in "${LEGACY_SUBDIR_FILES[@]}"; do
if [[ -e "${repo_dir}/${f}" ]]; then
issues+=("legacy per-tool duplicate still present: $f")
fi
done
# 3 — AGENTS.md must have the canonical pointer block.
if ! grep -qF "$AGENTS_POINTER_MARKER" "${repo_dir}/AGENTS.md"; then if ! grep -qF "$AGENTS_POINTER_MARKER" "${repo_dir}/AGENTS.md"; then
issues+=("AGENTS.md missing canonical-behavior-pointer block") issues+=("AGENTS.md missing canonical-behavior-pointer block")
fi fi
# 3 — Copilot file: must exist, must be AUTO-GENERATED, must reference canonical. # 4 — Copilot file: must exist, must be AUTO-GENERATED, must reference canonical.
copilot="${repo_dir}/.github/copilot-instructions.md" copilot="${repo_dir}/.github/copilot-instructions.md"
if [[ ! -f "$copilot" ]]; then if [[ ! -f "$copilot" ]]; then
issues+=(".github/copilot-instructions.md missing") issues+=(".github/copilot-instructions.md missing")
@ -87,7 +109,7 @@ for repo in "${REPOS[@]}"; do
fi fi
fi fi
# 4 — Aider config: must exist and reference AGENTS.md. # 5 — Aider config: must exist and reference AGENTS.md.
aider="${repo_dir}/.aider.conf.yml" aider="${repo_dir}/.aider.conf.yml"
if [[ ! -f "$aider" ]]; then if [[ ! -f "$aider" ]]; then
issues+=(".aider.conf.yml missing") issues+=(".aider.conf.yml missing")
@ -95,7 +117,7 @@ for repo in "${REPOS[@]}"; do
issues+=(".aider.conf.yml does not reference AGENTS.md") issues+=(".aider.conf.yml does not reference AGENTS.md")
fi fi
# 5 — Editorconfig: must exist with canonical first line. # 6 — Editorconfig: must exist with canonical first line.
editorconfig="${repo_dir}/.editorconfig" editorconfig="${repo_dir}/.editorconfig"
if [[ ! -f "$editorconfig" ]]; then if [[ ! -f "$editorconfig" ]]; then
issues+=(".editorconfig missing") issues+=(".editorconfig missing")