chore: consolidate agent instructions into .claude/CLAUDE.md

[sbryngelson]

Summary

Consolidates the repository's agent instruction files into a single source of truth at .claude/CLAUDE.md, and makes that same file load in Codex via an AGENTS.md symlink.

• CLAUDE.md (root, 147 lines) and .claude/rules/common-pitfalls.md (173 lines) are removed.
• .claude/CLAUDE.md (15 lines) replaces both.
• AGENTS.md is a symlink to .claude/CLAUDE.md (mode 120000), so Codex picks up the same rules with no per-user configuration.

Net: +16 / -320.

Why the symlink rather than a config file

Codex does not read a repository-level .codex/config.toml. This was measured rather than assumed, in a scratch repo:

setup	rules loaded?
repo .codex/config.toml with project_doc_fallback_filenames = [".claude/CLAUDE.md"]	no
same key passed as -c project_doc_fallback_filenames=[...]	yes
bogus key in repo .codex/config.toml + --strict-config	no error raised, so the file is never parsed
root AGENTS.md symlinked to .claude/CLAUDE.md, no config at all	yes

The fallback-filename mechanism itself works and accepts a path with a directory component; the repo-level config file is simply not a location Codex reads. The symlink needs no configuration from any contributor.

Claude Code loads .claude/CLAUDE.md directly (it is a first-class instruction-file location) and does not read AGENTS.md, so there is no double-loading.

Dangling references, fixed here

Two places pointed at the removed files. Both failed silently rather than erroring, so neither would have shown up in CI:

1. .github/workflows/claude-code-review.yml ran cat CLAUDE.md and cited the "Code Review Priorities" section of the old root file. Both reads are guarded with 2>/dev/null || true, so the review step would have proceeded with empty review standards. It now reads .claude/CLAUDE.md; the priority list is already inlined in the workflow, so the citation was dropped rather than repointed.
2. toolchain/mfc/lint_source.py named .claude/rules/common-pitfalls.md in a lint error message and in the check's docstring. The docstring already carries the full CCE explanation, so both now cite the sbryngelson/compiler-bugs reproducer only.

The workflow's .claude/rules/*.md reads are left in place. That directory no longer exists, but all three call sites are already guarded no-ops and will pick up rule files again if any are added.

Verified: the workflow YAML parses, and check_device_routine_element_args runs against the tree and reports 0 findings, unchanged.

Where the pitfalls content went

.claude/rules/common-pitfalls.md documented traps whose failure modes are silent, so it is relocated rather than dropped. Each block went to the page that owns its subject instead of to a new page:

content	destination
grid extents, ghost cells, buff_size, eqn_idx	contributing.md, "Array Bounds and Indexing"
derived-type broadcast, patch_ib, checker placement, analytic ICs, case-opt rebuild	contributing.md, new "Parameter Plumbing"
GPU_LOOP serialization, ftn-7066, CCE element-by-reference, m_thermochem traps, USING_AMD guards	gpuParallelization.md, new "Silent-Failure Traps"
--only semantics, define_case_d reachability, --no-build, stale binaries, worktree hook, /tmp	testing.md, new "Selection and Execution Pitfalls"

Material already covered in those pages was dropped rather than duplicated: Riemann j/j+1 indexing, the add-a-parameter procedure and its still-manual list, and the AMD case-optimization bound pattern in the GPU_ROUTINE helper section.

One inconsistency surfaced and is fixed: testing.md described --only as matching traces that "contain a certain feature," but the filter matches whole trace elements and ANDs labels, which is why --only bubbles silently matches nothing.

All three destination pages are already in the DOCS list that lint_docs.py scans, so the added file-path references are now checked. check_docs, check_cite_keys, and check_param_refs all report 0 errors against the tree.

Note on tooling

The commit was made with assistance from Claude Code. The consolidation decision, the contents of .claude/CLAUDE.md, and the removal of the previous instruction files are the author's; the Codex behaviour above was verified experimentally before the approach was chosen.

[github-actions]

Claude Code Review

Head SHA: 1e643af

Files changed:

• 6
• .claude/CLAUDE.md
• .claude/rules/common-pitfalls.md
• .github/workflows/claude-code-review.yml
• AGENTS.md
• CLAUDE.md
• toolchain/mfc/lint_source.py

Findings:

• .claude/rules/common-pitfalls.md is deleted outright (173 lines removed) with no content migrated anywhere else in this diff. That file catalogued the project's hard-won, silent-failure GPU/compiler traps (the CCE OpenACC element-by-reference bug, the USING_AMD fypp guards, thermochem device-routine call-site rules, parameter broadcast/emitter gotchas, test-filter footguns). toolchain/mfc/lint_source.py's check_device_routine_element_args docstring and its emitted error message are edited in this same diff to drop the pointer to that file (one reference removed outright, the other repointed only to the external sbryngelson/compiler-bugs repo), confirming the file's removal is intentional rather than incidental — but none of its other cataloged pitfalls (parameters, tests, remaining GPU rules) are preserved anywhere, so that institutional knowledge is lost for future contributors and reviewers relying on it.
• The root CLAUDE.md (147 lines) is deleted and replaced by a much smaller .claude/CLAUDE.md (15 lines) that drops the "Critical Rules" section (GPU-macro-only directive, precision-only-via-wp/stp, abort-only-via-s_mpi_abort/@:PROHIBIT, no goto/COMMON/global save, @:ALLOCATE/@:DEALLOCATE pairing) and the "Code Review Priorities" list entirely, with no equivalent content added to the new file. .github/workflows/claude-code-review.yml is edited in the same diff to stop citing "CLAUDE.md 'Code Review Priorities'" (since that section no longer exists anywhere), but the enforceable engineering guardrails themselves are not carried over into the new, much shorter file.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Consolidates AI/agent instruction sources by replacing the root CLAUDE.md and .claude/rules/common-pitfalls.md with a single .claude/CLAUDE.md, and wires tooling/docs to reference the new locations.

Changes:

• Remove legacy instruction files and add .claude/CLAUDE.md as the new instruction source.
• Update workflow/tooling references to avoid dangling reads and stale citations.
• Relocate “silent failure / pitfalls” guidance into existing docs pages, and clarify --only semantics in testing docs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
toolchain/mfc/lint_source.py	Updates references in docstring and lint error message away from removed pitfalls doc.
docs/documentation/testing.md	Clarifies --only semantics and adds a “Selection and Execution Pitfalls” section.
docs/documentation/gpuParallelization.md	Adds “Silent-Failure Traps” section documenting measured GPU/compiler pitfalls.
docs/documentation/contributing.md	Adds indexing/parameter “pitfalls” content formerly in the removed common pitfalls doc.
CLAUDE.md	Removes the legacy root instruction file.
AGENTS.md	Adds Codex-discoverable entry intended to point to .claude/CLAUDE.md.
.github/workflows/claude-code-review.yml	Updates workflow to read .claude/CLAUDE.md and removes outdated citation reference.
.claude/rules/common-pitfalls.md	Removes the legacy common pitfalls doc (content moved into docs).
.claude/CLAUDE.md	Adds the consolidated instruction file.

Suppressed comments (1)

AGENTS.md:1

• If the intent is for AGENTS.md to be a symlink (as described in the PR), it’s worth confirming the PR actually records it as a symlink in git (mode 120000) rather than a regular text file containing a path. If it lands as a plain file, Codex may not follow it as intended; if symlinks are not reliably supported in some contributor environments, a fallback (e.g., duplicating the small file content) may be more robust.

* New branches cannot be made on MFlowCode/MFC, they are made on forks

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.26%. Comparing base (e7139bc) to head (9dabc27).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1855   +/-   ##
=======================================
  Coverage   61.26%   61.26%           
=======================================
  Files          84       84           
  Lines       22330    22330           
  Branches     3265     3265           
=======================================
  Hits        13680    13680           
  Misses       6207     6207           
  Partials     2443     2443           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.