[FEATURE] Add "Avoid Symlinks" to AI-Friendly Repo Recommendations

[jwm4]

Proposal: Add "Avoid Symlinks" Check and Remove Symlink Recommendations

Description

Add a new assessor that flags symbolic links to mutable source files within repositories intended for AI coding agents. Additionally, update existing AgentReady guidance and internals that currently recommend or use symlinks.

The Problem

Current-generation AI agents frequently fail to distinguish between a file and a symlink. This leads to several failure modes that can cause data loss or incorrect file states:

1. Destructive Overwrites: Agents may write through a symlink without recognizing it, replacing the contents of the underlying target file. This is especially dangerous for configuration files like .env that may symlink to external secret stores.
2. Read/Write Asymmetry: Agents can often write to a file via a symlink (as the OS resolves the path), but then fail to read it back (because the agent's file-indexing tool sees the path as a link and skips it). This causes the agent to think the file is empty or missing and overwrite it.
3. Security Bypass: Symlinks can be used to bypass agent permission controls. CVE-2026-25724 demonstrated that Claude Code's deny rules could be circumvented via symlinks because access control evaluated literal paths rather than resolved canonical paths.
4. Platform Incompatibility: On Windows with Git's default core.symlinks=false, symlinks become plain-text stub files containing paths. Agents parse these stubs as literal content, causing YAML/config parsing failures.

Supporting Evidence

• Cursor IDE: Reports of read/write asymmetry through symlinks causing file overwrites. The agent can write through symlinks but fails to read back, leading to repeated overwrites.
  • Source: Cursor Forum: "Cursor doesn't follow symlinks"
• OpenAI Codex: A verified bug where apply_patch followed a .env symlink to an external secret store and overwrote the target file's contents (~10 environment variables lost).
  • Source: GitHub Issue: openai/codex#10037
• Claude Code: CVE-2026-25724 — symlink bypass of deny rules in settings.json, allowing read access to explicitly restricted files. Fixed in v2.1.7.
  • Source: GitHub Advisory: GHSA-4q92-rfm6-2cqx, NVD: CVE-2026-25724
• GitHub Copilot CLI: On Windows, Git symlinks materialized as text stubs caused 18 agent files to fail with YAML frontmatter errors across 546 symlinks in a single repo.
  • Source: GitHub Issue: github/copilot-cli#2286

Scope

This issue covers three changes:

1. New symlink_usage assessor

• Rule: Flag symlinks to mutable source files within the repository.
• Exception: Symlinks for static/read-only dependencies are acceptable only if those paths are excluded from AI indexing (e.g., via .gitignore, .cursorignore).
• Alternative guidance: Use a flat directory structure, explicit copy scripts (e.g., a pre-commit hook), or tool-specific reference mechanisms (e.g., @ references in CLAUDE.md).
• Tier: TBD — likely Tier 2 or Tier 3 given the direct impact on agent reliability.

2. Update CLAUDEmdAssessor to stop recommending symlinks

The current CLAUDEmdAssessor (assessors/documentation.py) recommends CLAUDE.md as a symlink to AGENTS.md and gives it a full score. This should be changed to:

• Prefer @ references or direct files over symlinks
• Continue to accept symlinks (don't penalize existing repos that use them) but stop recommending them in remediation guidance
• Update remediation text to remove "Option 2: symlink CLAUDE.md to AGENTS.md"

3. Replace AgentReady's internal use of symlinks

AgentReady creates *-latest symlinks for reports (cli/main.py, cli/harbor.py). These should be replaced with an alternative mechanism (e.g., direct copies, or a latest text file containing the path).

[jwm4]

Updated the issue body based on analysis of the existing codebase and verification of all cited sources:

Key changes:

• Toned down editorialized language (removed "sabotaging") and linked to primary sources (CVE, GitHub advisories) instead of secondary posts
• Expanded scope to three concrete work items: new assessor, CLAUDEmdAssessor update, and internal symlink replacement
• Clarified that existing symlinks in assessed repos should still be accepted (not penalized retroactively) — the change is to stop recommending them
• Noted that the @ reference mechanism already supported by CLAUDEmdAssessor is the preferred alternative

All four cited sources were verified:

• ✅ Cursor forum thread (real, describes read/write asymmetry bug)
• ✅ OpenAI Codex #10037 (real, closed as completed, .env symlink data loss)
• ✅ CVE-2026-25724 (real, published in NVD, fixed in Claude Code v2.1.7)
• ✅ Copilot CLI #2286 (real, Windows symlink-to-text-stub issue)

This comment was posted by Claude Code under the supervision of Bill Murdock.