Balance the AI-instruction filenames orient.py detects (don't single out one vendor) #49

New Issue

2026-06-22T14:24:02-04:00

claude commented

2026-06-22 14:24:02 -04:00

Problem

AGENTS.md forbids pinning a lesson to one LLM vendor and hardcoding one tool's config filename. The shipped orient.py (M23) detects AI-instruction files by hardcoding AGENTS.md AND CLAUDE.md (one vendor's name) with no GEMINI.md/.cursor/Copilot equivalents, under a comment claiming it's "tool- and language-agnostic on purpose." Its forge detection is balanced (.github/.gitea/.gitlab), but its AI-instruction detection is not.

Evidence

modules/23-working-with-existing-codebases/lab/orient.py (~lines 52-53): "AGENTS.md": …, "CLAUDE.md": …. (Weaker, largely defensible: M22 lab/suspicious-skill/SKILL.md is a real on-disk specimen filename; M27 llm_judge.py "OpenAI-style /chat/completions" is an env-var-driven wire-format label the README already flags "not branded.")

Why it matters

A detection script must name real filenames to function, but the asymmetry (only one vendor's AI file beyond AGENTS.md) cuts against the vendor-neutral promise in a shipped artifact.

Proposed change

In orient.py, ADD the sibling AI-instruction filenames to balance the set — e.g. GEMINI.md, .cursorrules/.cursor/rules, copilot-instructions — rather than removing CLAUDE.md (removing it would degrade a real scanner; CLAUDE.md is a common real file).
Optional/minor: gloss M22's SKILL.md as "this vendor's format; yours may differ (Module 21)."
M27 "OpenAI-style" is largely defensible; if touched, keep the README's existing "compatible but not branded" framing.

Acceptance criteria

orient.py detects a balanced set of AI-instruction filenames (not just AGENTS.md + one vendor).
CLAUDE.md detection is retained (the scanner still surfaces it).

Affected files

modules/23-working-with-existing-codebases/lab/orient.py (optional: modules/22-.../README.md)

References

Source finding F16 (realVotes 2/3 — one lens judged it adequately handled in-source; lower confidence). The fix here corrects the original finding's "detect only AGENTS.md" suggestion, which would have degraded the scanner.

Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.

## Problem AGENTS.md forbids pinning a lesson to one LLM vendor and hardcoding one tool's config filename. The shipped `orient.py` (M23) detects AI-instruction files by hardcoding `AGENTS.md` AND `CLAUDE.md` (one vendor's name) with no `GEMINI.md`/`.cursor`/Copilot equivalents, under a comment claiming it's "tool- and language-agnostic on purpose." Its forge detection is balanced (`.github`/`.gitea`/`.gitlab`), but its AI-instruction detection is not. ## Evidence `modules/23-working-with-existing-codebases/lab/orient.py` (~lines 52-53): `"AGENTS.md": …`, `"CLAUDE.md": …`. (Weaker, largely defensible: M22 `lab/suspicious-skill/SKILL.md` is a real on-disk specimen filename; M27 `llm_judge.py` "OpenAI-style /chat/completions" is an env-var-driven wire-format label the README already flags "not branded.") ## Why it matters A detection script must name real filenames to function, but the asymmetry (only one vendor's AI file beyond AGENTS.md) cuts against the vendor-neutral promise in a shipped artifact. ## Proposed change 1. In `orient.py`, ADD the sibling AI-instruction filenames to balance the set — e.g. `GEMINI.md`, `.cursorrules`/`.cursor/rules`, `copilot-instructions` — rather than removing `CLAUDE.md` (removing it would degrade a real scanner; CLAUDE.md is a common real file). 2. Optional/minor: gloss M22's `SKILL.md` as "this vendor's format; yours may differ (Module 21)." 3. M27 "OpenAI-style" is largely defensible; if touched, keep the README's existing "compatible but not branded" framing. ## Acceptance criteria - [ ] `orient.py` detects a balanced set of AI-instruction filenames (not just AGENTS.md + one vendor). - [ ] `CLAUDE.md` detection is retained (the scanner still surfaces it). ## Affected files - `modules/23-working-with-existing-codebases/lab/orient.py` (optional: `modules/22-.../README.md`) ## References Source finding F16 (realVotes 2/3 — one lens judged it adequately handled in-source; lower confidence). The fix here corrects the original finding's "detect only AGENTS.md" suggestion, which would have degraded the scanner. --- *Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.*