docs: add provisional root CLAUDE.md - #144
Conversation
@AGENTS.md import + a Claude Code delta section, per the documented pattern for repos that already have an AGENTS.md (code.claude.com/docs/en/memory). Records as a maintainer-only HTML comment (stripped from context) the one open question this design has not fully closed: whether managed Code Review's CLAUDE.md consumption expands @import the same way normal session loading does. Documentation gives no carve-out for CLAUDE.md the way it explicitly does for REVIEW.md, which is evidence but not an explicit statement or empirical confirmation - untestable on a Max-plan subscription (Code Review is Team/Enterprise-only). Kept provisional with a stated re-verification trigger. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V1x1KNkkjSe2CjbuTb4Gis
|
Claude finished @kyle-sexton's task in 0s —— View job I'll analyze this and get back to you. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3a8e49cd09
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
## Summary - Adds a root-only `AGENTS.md` (P2·3 step 4) — the repo-owned agent-orientation file the standards-sync design calls for. - Deliberately thin: cites `README.md` for repository shape, ownership boundaries, and validation commands rather than restating them (this repo's own cite-don't-duplicate discipline), and adds only what's genuinely agent-specific and not described elsewhere — the dogfooding expectation, the fresh-authoring-never-ported rule for review criteria, the `.claude/` staging hazard, and PR mechanics. - States the root-only placement rationale: Codex concatenates every `AGENTS.md` it finds rather than nearest-wins-overriding, so a nested copy would compound instructions instead of scoping them. ## Test plan - [x] `lefthook` pre-commit (typos, gitleaks, editorconfig, markdownlint) — passed locally. - [ ] CI green (markdown lint, lychee, review bot). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> (cherry picked from commit 1962226)
REVIEW.md does not exist in this commit tree yet (it is being authored separately in #143), so the markdown link to it was dead and failing the offline lychee link-check gate. Drop the link syntax but keep the CLAUDE.md/REVIEW.md split rationale as plain prose; re-link once REVIEW.md lands.
|
Claude finished @kyle-sexton's task in 2m 56s —— View job PR Review
What this PR actually changes vs.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 579dc926c2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The root-only rationale pointed maintainers wanting subtree-local instructions at a nested CLAUDE.md or .claude/rules/ overlay, but Codex reads neither for this purpose - its documented mechanism is nested AGENTS.md/AGENTS.override.md, concatenated root-down with files closer to the working directory read later in the combined prompt (and therefore able to supersede broader guidance), with AGENTS.override.md available to replace rather than append. Point at the mechanism Codex actually honors, and correct the "concatenates rather than override" framing - concatenation is how the override happens, not an alternative to it. Fixes the chatgpt-codex-connector P2 finding "Use Codex-readable files for scoped guidance" (developers.openai.com/codex/agent-configuration/agents-md). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 36s —— View job PR Review
What changed in the latest commit (
|
| Finding | Round | Status |
|---|---|---|
P1 — broken REVIEW.md link |
Round 1 | Fixed in 579dc92 (dropped link syntax, kept prose) |
P2 — AGENTS.md absent |
Round 1 | Non-issue — AGENTS.md was in main before this PR was authored |
| P2 — subtree advice points at non-Codex files | Round 2 | Fixed in ef43b4f |
All Codex findings are addressed. Nothing left to block here.
Summary
Clean, well-scoped PR. The ef43b4f fix is the exact right correction for the legitimate Codex P2 finding — the advice now points maintainers at AGENTS.md / AGENTS.override.md rather than files Codex won't read. CLAUDE.md is well-formed. Ready to merge.
…ep note Append the review note for the gh-free gate revision: what changed in the selector (fallback label, ci-workflows#141/#144), how each of the six contracts registered at 90f1c54 compares to its newest previously approved SHA, and the updated rollout counts (ten approved selector revisions, seven owner-scoped). Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
## What Declare `visibility: "public"` in `.github/runner-policy.json` (selfHostedCi false, exception inventory emptied) and remove the `select-runner` job from all seven workflows: every lane now runs on GitHub-hosted `ubuntu-24.04`, with each reviewed reusable receiving its `runner` input explicitly. Net −181 lines. ## Why The repository is public (confirmed intentional), and the runner-policy engine fails closed on the visibility mismatch — currently red on main's own CI and on #189. For public repositories the engine forbids local-runner selector routing outright (`public-self-hosted-routing`), so the reconciliation is the full hosted conversion, not a one-line declaration. Hosted minutes are free for public repositories, and this removes the standards CI load from the self-hosted fleet entirely. Reusable pins move to `90f1c54` where a reviewed contract exists at that revision; `standards-sync` stays at its newest registered contract (`ec91c34`). This supersedes the selector-pin portion of #189. ## Verification `node components/runner-policy/runner-policy.mjs --root . --repository-visibility public` passes; 224/224 runner-policy component tests pass; actionlint clean on all seven workflows; lefthook gauntlet green. ## Related No linked issue. #189 (superseded selector pins), #195 (policy exception-category removal this builds on), melodic-software/ci-workflows#141/#144 (the 90f1c54 revision). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YZxBP1B8Hf7ZRaqDrP6ma9 Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
1 participant
Summary
CLAUDE.md(P2·3 step 5) as@AGENTS.md+ a small Claude Code delta section — the exact patterncode.claude.com/docs/en/memorydocuments for a repo that already has anAGENTS.md.code.claude.com/docs/en/memorydescribes@importexpansion as unconditional ("Imported files are expanded and loaded into context at launch") with no Code-Review carve-out, whilecode.claude.com/docs/en/code-reviewexplicitly calls out onlyREVIEW.mdas not expanding@import("pasted verbatim... referenced files are not read into the prompt"). The asymmetry is documentation-level evidence thatCLAUDE.md's@AGENTS.mdimport is expanded for Code Review too — but it's not an explicit statement to that effect, and Code Review is Team/Enterprise-only so it's untestable on this org's Max-plan subscription.CLAUDE.mdvsREVIEW.mdrole boundary (general project context / nit-level vs. review-only / highest-priority, per the same docs) so review rules don't drift into this file out of habit.Test plan
lefthookpre-commit (typos, gitleaks, editorconfig, markdownlint) — passed locally.🤖 Generated with Claude Code