AGENTS.md/CLAUDE.md describe qa.sh checks that don't exist; duplicated guideline files risk drift

[dceoy]

Problem

AGENTS.md (and its byte-identical copy CLAUDE.md) describes the QA script as: "The script checks core action metadata and README examples, including the composite action declaration, opencode github run, and documented usage" (AGENTS.md:15). qa.sh does none of that — and never has.

What .agents/skills/local-qa/scripts/qa.sh actually does:

• prettier --write './**/*.md' — rewrites markdown files
• yamllint on tracked *.yml
• shellcheck on tracked shell scripts
• zizmor --fix=safe .github/workflows — modifies workflow files
• actionlint on workflows, checkov on the repo
• validate-opencode.sh — agent frontmatter and /review-pr reference validation

Nothing greps action.yml for the composite declaration, checks README examples, or verifies documented usage.

Evidence

• AGENTS.md:15 vs. .agents/skills/local-qa/scripts/qa.sh (all six commands).
• The description doesn't match even the initial version of the script: git show 7c1bb99:.agents/skills/local-qa/scripts/qa.sh.
• diff AGENTS.md CLAUDE.md → identical files; both must be edited in lockstep by hand.
• The guide also omits that "validation" mutates the working tree (prettier --write, zizmor --fix=safe), which surprises contributors running it before staging.

Impact

This file is consumed by contributors and by the bundled code-reviewer agent, whose whole job is checking "AGENTS.md compliance" (.opencode/agents/code-reviewer.md:3). Inaccurate guidance yields wrong review findings and misleads contributors about what is actually tested. The manual AGENTS.md/CLAUDE.md duplication will drift the first time only one copy is edited.

Suggested fix

1. Rewrite the "Build, Test, and Development Commands" paragraph to describe what qa.sh actually runs (markdown formatting, YAML/shell/workflow linting, checkov, and validate-opencode.sh), noting that it modifies files.
2. Replace CLAUDE.md with a symlink to AGENTS.md — the repo already tracks a symlink (.claude/skills → ../.agents/skills) — or reduce it to a one-line pointer.

Validation

Re-read the new text against qa.sh command-by-command; confirm git ls-files -s CLAUDE.md shows the symlink (mode 120000) and that Claude Code still loads the project instructions.