Symlink CLAUDE.md to AGENTS.md

[urda]

Summary

• Add CLAUDE.md -> AGENTS.md as a symlink so Claude Code picks up the same repository guidelines already documented for agents.
• Avoids maintaining two copies of build/test/coding-style guidance that would drift out of sync.
• Fix hanging *** spotted in AGENTS.md.

Test plan

• Update local repo to commit in PR to "create" symlink.
  • Tested OK.
• Start a claude session.
  • Tested OK.
• Invoke /context and confirm we see CLAUDE.md in context.
  • Tested OK - CLAUDE.md: 2.4k tokens.

[clawsweeper]

Codex review: needs changes before merge. Reviewed August 9, 2026, 7:12 PM ET / 23:12 UTC.

ClawSweeper review

What this changes

This PR adds CLAUDE.md as a symlink to the shared AGENTS.md guidance and removes a stray trailing marker from that guidance.

Merge readiness

⚠️ Needs maintainer review before merge - 2 items remain

Keep open: the symlink’s Claude Code behavior is demonstrated, but the new root instruction entry point is not covered by the CI path gate that protects contributor contracts.

Priority: P3
Reviewed head: c075e190265756d761e5af815cf6d5025bbf0ab8

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The intended Claude behavior has direct proof, but a small CI-classification defect must be corrected before merge.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): The PR body supplies a screenshot of a live Claude /context result showing CLAUDE.md loaded after the symlink change.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): The PR body supplies a screenshot of a live Claude /context result showing CLAUDE.md loaded after the symlink change.
Evidence reviewed	4 items	New instruction entry point: The PR adds CLAUDE.md as a symlink to AGENTS.md, making it a second root-level contributor-guidance path. Current CI classification: The current path gate treats only AGENTS.md and docs/configuration.md as contracts; a CLAUDE.md-only change falls through the generic Markdown skip branch. Missing regression cases: The existing classifier matrix covers AGENTS.md modification and both rename directions, but contains no equivalent CLAUDE.md cases.
Findings	1 actionable finding	[P2] Classify CLAUDE.md as a contributor contract
Security	None	None.

How this fits together

Root guidance files tell coding assistants how to work in CodexBar. The CI path gate classifies changed files to decide whether macOS Swift tests must run before the workflow continues.

flowchart LR
A[Changed pull-request paths] --> B[CI path gate]
B --> C{Contributor contract?}
C -->|AGENTS.md| D[Require macOS Swift tests]
C -->|CLAUDE.md today| E[Skip as Markdown]
D --> F[macOS test shards]
E --> G[Portable checks only]

Loading

Before merge

• Classify CLAUDE.md as a contributor contract (P2) - CLAUDE.md becomes a second root instruction entry point, but the path gate only recognizes AGENTS.md and docs/configuration.md. A future CLAUDE.md-only modification or rename therefore falls through *.md and skips macOS tests. Add the alias to the classifier and mirror the existing modification and rename cases in the gate matrix.
• Resolve merge risk (P1) - Merging leaves future CLAUDE.md-only modifications or renames classified as ordinary Markdown, allowing a contributor-contract change to skip the macOS Swift test gate.

Findings

• [P2] Classify CLAUDE.md as a contributor contract — CLAUDE.md:1

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Path-gate coverage	3 AGENTS.md cases, 0 CLAUDE.md cases	The new alias has no modify or rename coverage despite becoming a root contributor-contract entry point.

Merge-risk options

Maintainer options:

1. Cover the CLAUDE.md alias in the path gate (recommended)
   Classify CLAUDE.md as a contributor contract and add matching modification and rename assertions before merging.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Add CLAUDE.md to the contributor-contract classifier and extend the path-gate matrix for modification plus both rename directions; keep the existing AGENTS.md behavior unchanged.

Technical review

Best possible solution:

Treat both root guidance aliases as contributor contracts in the path gate and cover modify plus both rename directions in its regression matrix.

Do we have a high-confidence way to reproduce the issue?

Yes—source inspection gives a high-confidence path: a CLAUDE.md-only modification or rename reaches the generic Markdown branch and skips the macOS-test requirement.

Is this the best way to solve the issue?

No—the symlink is the maintainable shared-guidance mechanism, but it should ship with matching CI classification and regression coverage for the new alias.

Full review comments:

• [P2] Classify CLAUDE.md as a contributor contract — CLAUDE.md:1
  CLAUDE.md becomes a second root instruction entry point, but the path gate only recognizes AGENTS.md and docs/configuration.md. A future CLAUDE.md-only modification or rename therefore falls through *.md and skips macOS tests. Add the alias to the classifier and mirror the existing modification and rename cases in the gate matrix.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a0d77c37f9cc.

Labels

Label justifications:

• P3: This is a narrow documentation and CI-gating repair with no demonstrated runtime user impact.
• merge-risk: 🚨 automation: The new root guidance path can bypass the workflow's macOS-test selection until the classifier is updated.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): The PR body supplies a screenshot of a live Claude /context result showing CLAUDE.md loaded after the symlink change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body supplies a screenshot of a live Claude /context result showing CLAUDE.md loaded after the symlink change.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body supplies a screenshot of a live Claude /context result showing CLAUDE.md loaded after the symlink change.

Evidence

Acceptance criteria:

• [P1] bash Scripts/test_ci_path_gate.sh.
• [P1] make check.

What I checked:

• New instruction entry point: The PR adds CLAUDE.md as a symlink to AGENTS.md, making it a second root-level contributor-guidance path. (CLAUDE.md:1, c075e1902657)
• Current CI classification: The current path gate treats only AGENTS.md and docs/configuration.md as contracts; a CLAUDE.md-only change falls through the generic Markdown skip branch. (Scripts/ci_macos_test_gate.sh:44, 0e46d1940c35)
• Missing regression cases: The existing classifier matrix covers AGENTS.md modification and both rename directions, but contains no equivalent CLAUDE.md cases. (Scripts/test_ci_path_gate.sh:57, a0d77c37f9cc)
• Real behavior proof: The PR body reports a live Claude /context check showing CLAUDE.md in context, with a screenshot attached; the reported CI checks are also green. (CLAUDE.md:1, c075e1902657)

Likely related people:

• Peter Steinberger: Blame attributes the current contributor-contract classifier to this release commit, which also establishes the test-gating behavior affected by the omission. (role: recent CI-path-gate author; confidence: high; commits: 0e46d1940c35; files: Scripts/ci_macos_test_gate.sh, Scripts/test_ci_path_gate.sh)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add CLAUDE.md to the CI path classifier and its modification/rename matrix.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (21 earlier review cycles; latest 8 shown)

• reviewed 2026-08-08T11:53:08.646Z sha ed3e340 :: needs maintainer review before merge. :: none
• reviewed 2026-08-08T13:46:47.131Z sha ed3e340 :: needs changes before merge. :: [P1] Preserve the newer Claude status-line policy on rebase
• reviewed 2026-08-08T16:55:48.898Z sha ed3e340 :: needs changes before merge. :: [P1] Rebase without dropping the status-line policy
• reviewed 2026-08-08T17:39:33.171Z sha 37a3bd3 :: needs maintainer review before merge. :: none
• reviewed 2026-08-08T23:41:34.062Z sha 37a3bd3 :: needs changes before merge. :: [P2] Classify CLAUDE.md as a contributor contract
• reviewed 2026-08-09T04:54:52.120Z sha 37a3bd3 :: needs changes before merge. :: [P2] Classify CLAUDE.md as a contributor contract
• reviewed 2026-08-09T07:15:45.082Z sha 37a3bd3 :: needs changes before merge. :: [P2] Classify CLAUDE.md as a contributor contract
• reviewed 2026-08-09T22:09:08.263Z sha c075e19 :: needs changes before merge. :: [P2] Classify CLAUDE.md as a contributor contract

[urda]

Note for reviewers: the failing build-linux-cli (linux-arm64) check here is a
pre-existing flake, not this diff. This PR changes two text files, and neither is
compiled, linted, or tested.

Evidence that it is environmental:

• linux-x64 passed in the same run, on the same commit.
• linux-arm64 passed on the base commit 15a855a21.
• Failing job: https://github.com/steipete/CodexBar/actions/runs/30885238832/job/91914882363

Root cause and fix: #2644. CLICardsClaudeSwapTests writes a shell script and
executes it immediately, which races with concurrent Process.run() forks under
swift test --parallel and fails with ETXTBSY. Reproduced on Linux arm64 at
112 failures in 600 attempts, and 0 in 600 with the fix.

I cannot rerun the job, since that needs admin rights on this repository. Once
#2644 merges I will rebase this branch onto main so the checks rerun clean.

[urda]

I think a rebase after #2644 lands will result in less flakes.

[urda]

Rebased post #2644 merge.

[urda]

@steipete easy PR win here for ya.