docs: make AGENTS.md the shared agent canon and slim CLAUDE.md to an import

[zelentsov-dev]

Intent

CLAUDE.md was a 212-line copy of AGENTS.md that differed only in the tool name (6 lines), so every rule change had to land twice. AGENTS.md becomes the single canon for Codex and Claude Code; CLAUDE.md imports it (@AGENTS.md) and keeps only Claude Code specifics.

Changes

• AGENTS.md: tool-neutral intro; the doc-comment rule is marked as this repository's exception to the owner's global comment default (every public method keeps a doc comment).
• CLAUDE.md: @AGENTS.md + three Claude notes — swift build / swift test (pure SwiftPM server, exception to the XcodeBuildMCP rule), the settings ask list prompts the owner for the main production-effect ASC families but is not exhaustive, companies.json and Keys/*.p8 are local secrets.

Risk and authority

• Change class: docs-only
• Deployment authority: no-deploy (target develop; releases stay with the owner)

Evidence

• Source: diff reviewed; no code, Package.swift or workflow changes.
• CI: runs on the PR (docs-only change).

Not checked

• Fresh-session loading of @AGENTS.md in a Claude Code session in this repo.

[zelentsov-dev]

Protocol: DX-REVIEW/1
Message: FINAL_RECEIPT
Round: 3
Repository: zelentsov-dev/asc-mcp
PR: 30
Base-SHA: 5e04643ab99e89be5908bf3879b270408c6992c0
Head-SHA: 9ee25eb4512dfd48cb817c9f1cc212e5cd1232b4
Previous-Reviewed-Head: e607b506105dc99cc23e08442b6b7318493b0c77
Delta: e607b506105dc99cc23e08442b6b7318493b0c77..9ee25eb4512dfd48cb817c9f1cc212e5cd1232b4
Change-Class: base-merge-only
Deployment-Authority: no-deploy

## Intent and user effect
Round-3 exact-delta re-review of 9ee25eb, a merge of develop 5e04643 (carrying #31, the Apple spec 4.5 re-baseline) into the approved round-2 head e607b50, with replay of PR30-F001 and PR30-F002 and a re-check of the six round-2 ask entries. The merge adds only develop's own content, the PR's own diff is byte-identical to round 2, and the three required checks are green on the exact head. One new non-blocking P3 on the PR description (PR30-F003).

## Scope and exclusions
- Delta e607b50..9ee25eb: one merge commit, first parent e607b506 (approved round-2 head), second parent 5e04643a (develop tip, the current PR base); merge-base(e607b50, 5e04643) = fcfa12f, the round-2 base; PR head = origin/docs/agents-canon = 9ee25eb, PR base = origin/develop = 5e04643
- The round delta equals develop's own delta byte for byte: git diff e607b50 9ee25eb = git diff fcfa12f 5e04643 (51 modified files, none added, deleted or renamed, neither AGENTS.md nor CLAUDE.md; patch-id 9eb42574 on both)
- Whole-PR coherence at the head: AGENTS.md path references resolve and its 502-tool count matches the CI contract report; #31 renamed and added no tools, so CLAUDE.md:8-13 still describes the ask list correctly
- Out-of-repo evidence replayed read-only: permissions in ~/.claude, ~/.claude-icloud and ~/.claude-wheele settings.json (only the six matching key names were printed); ~/.claude/skills/swift-build-discipline/SKILL.md and its icloud, wheele and ~/.agents copies; Dev essentials in ~/dev/work/CLAUDE.md and ~/dev/personal/CLAUDE.md
- Excluded: The #31 content (manifest re-baseline, plan_types fix, tests, docs): reviewed under #31, whose FINAL_RECEIPT (issue comment 5811389573, approved head 44ec237) records the merge 5e04643; not re-reviewed here beyond CI on the merged tree
- Excluded: Local build and test (read-only brief)

## Preserved contracts and invariants
- Every rule of the base CLAUDE.md stays reachable through @AGENTS.md: VERIFIED, AGENTS.md blob 51fdef71 and CLAUDE.md blob 6bbd60ef are the round-2 blobs
- No secret value in docs: VERIFIED, the PR's diff is byte-identical to round 2
- Releases stay owner-only: VERIFIED, the delta changes no workflow; publish-release runs only on refs/tags/v* (.github/workflows/ci.yml:318-321)

## Risk focus
1. The merge must add nothing beyond develop's content: VERIFIED by full tree identity, byte-identical diffs and an empty remerge-diff
2. The required checks must be green on the exact head with the #31 manifest: VERIFIED, run 35980774431
3. The six round-2 ask entries must still exist in all three profiles: VERIFIED, 6 of 6 in each
4. The PR record must match the reviewed text: the PR description still carries the pre-round-2 ask-list claim (PR30-F003, P3, non-blocking)

## Evidence ledger
| Layer | Status | Evidence |
|---|---|---|
| source | VERIFIED | Parents of 9ee25eb: e607b50 and 5e04643. Tree dc90ad49 equals develop's tree with only AGENTS.md and CLAUDE.md taken from e607b50 (466 entries, 0 mismatches). git diff 5e04643 9ee25eb is byte-identical to git diff fcfa12f e607b50 (13,710 bytes, 2 files, +18/-214, patch-id --stable 8b5ff94b46ca on both; the blobs match, so this is byte identity, not only patch-id equality). Tool names are unchanged by #31 (the ToolDefinitions and manifest tool-name sets match at fcfa12f and 9ee25eb). All six round-2 entries are exact permissions.ask entries in the three profiles (three separate files, 131 entries each, ask arrays and whole permissions objects identical). Against the 502 public tool names, each of the 65 asc-mcp and 65 release entries matches at least one tool, and all 46 write tools I classed under the 12 families named in CLAUDE.md:9-12 are gated. SKILL.md changed after round 2 but still carries the scoped rule and exception 2; both Dev essentials blocks are identical Post-merge read-back by the TeamLead: merge commit 13abadd66ead01a4b41abeb82e2b3bd4b99259b4 on develop at 2026-09-24T13:57:29Z, parents = base 5e04643a + approved head 9ee25eb4, git diff approved-head..merge is empty (tree identical to the approved head); merged with a merge commit per the repo convention. PR30-F003 closed before the merge: the PR description now says the ask list covers the main production-effect families and is not exhaustive (head unchanged). |
| local | NOT CHECKED | No local build or test (read-only brief). Local git only: git show --remerge-diff 9ee25eb prints 0 bytes (git 2.54.0) |
| CI | VERIFIED | Run 35980774431 (pull_request, head_sha 9ee25eb; checkout of refs/pull/30/merge b1f5af0, whose tree dc90ad49 is the head tree): Promotion Lineage success; Tests success, 1,868 tests in 138 suites; Release & Apple Contract success, Operation contract 4.5 with 502 public tools, 0 unclassified, 0 structural errors, 0 implementation drift and 0 warnings, plus a clean coverage diff for spec 4.5 (973 paths, 1,270 operations); Mint MCP Smoke & Publish Release skipped (ci.yml:320, tag-only). The develop ruleset requires exactly these three checks with the strict up-to-date policy; mergeable_state clean; no review threads. Develop push run 35979983983 on 5e04643: success |
| device | N/A | Docs-only PR diff |
| staging | N/A | No staging for this repo |
| provider | N/A | Docs-only PR diff; the CI contract step read the live Apple spec 4.5 |
| production | N/A | No production effect; merge target is develop and publish-release runs only on v* tags |

## Topology checks
- Stacked: no
- Retarget: no
- Merge-Commit: yes
- Tree-Identity: VERIFIED. Tree dc90ad49 = develop 5e04643 with AGENTS.md (51fdef71) and CLAUDE.md (6bbd60ef) from e607b50, 466 entries, 0 mismatches. git diff 5e04643 9ee25eb is byte-identical to the round-2 PR diff git diff fcfa12f e607b50 (patch-id 8b5ff94b46ca). git diff e607b50 9ee25eb is byte-identical to develop's delta git diff fcfa12f 5e04643 (patch-id 9eb42574)
- Remerge-Diff: VERIFIED. git show --remerge-diff 9ee25eb prints nothing; develop's delta touches neither AGENTS.md nor CLAUDE.md, so the merge had nothing to resolve

## Findings
### PR30-F001
- Severity: P3
- Confidence: 0.9
- Blocking: no
- State: CLOSED
- Location: CLAUDE.md:8-13 (head 9ee25eb, blob unchanged since e607b50); permissions.ask in ~/.claude, ~/.claude-icloud and ~/.claude-wheele settings.json
- Impact: In round 1 the note implied that the ask list gated every production-effect ASC tool, while live-store toggles resolved on allow mcp__asc-mcp__* with no prompt. Since e607b50 the note states the general rule (every write against a real company is live and owner-only unless provably reversible) and calls the ask list not exhaustive, and the three toggles are ask-gated. The base merge changes neither.
- Original-Counterexample: Original: mcp__asc-mcp__ppo_update_experiment state START resolved on allow mcp__asc-mcp__* with no prompt. Replay on 9ee25eb: CLAUDE.md is byte-identical to round 2; mcp__asc-mcp__{ppo_update_experiment,custom_pages_update,accessibility_update} and the three mcp__asc-mcp-release__ twins are exact permissions.ask entries in all three profiles. Rules are evaluated deny, then ask, then allow, and no mode auto-approves a tool matched by an explicit ask rule, bypassPermissions included (code.claude.com/docs/en/permissions and /docs/en/permission-modes, 'Actions no mode auto-approves'), so the call prompts. The toggles are still exposed only on these tools (ProductPageOptimizationWorker+ToolDefinitions.swift:70-73,92; CustomProductPagesWorker+ToolDefinitions.swift:59; AccessibilityWorker+ToolDefinitions.swift:58), and #31 renamed and added no tools. The counterexample does not reproduce.
- Required-Correction: Done in e607b50 (CLAUDE.md:8-13) and in the owner settings; unchanged by the merge.
- Follow-Up: None for this finding. Residual by design (unchanged): other live writes, such as promotional text through apps_update_metadata, stay unprompted and rely on the note's general rule.
### PR30-F002
- Severity: P3
- Confidence: 0.9
- Blocking: no
- State: CLOSED
- Location: CLAUDE.md:5-7 (head 9ee25eb); /Users/zelentsovalexey/.claude/skills/swift-build-discipline/SKILL.md:3,11-13,17,32-36 (lines shifted since round 2)
- Impact: In round 1 the skill that Dev essentials cites for details forbade swift build in every repository, while the repo note prescribed it. The skill scopes the XcodeBuildMCP-only rule to app targets and iOS packages and documents exception 2 for pure SwiftPM CLI and server packages, and the note names both sources.
- Original-Counterexample: Original: SKILL.md:9-11,15,22-27 forbade swift build in every repository while CLAUDE.md:5 prescribed it. Replay: SKILL.md was edited after round 2 (a 'Last verified' line at :9; sha256 now f793a7d7, mtime 2026-09-24 12:35), but :11-13 still limit the XcodeBuildMCP-only rule to Apple-platform app targets and iOS SPM packages, :17 limits the NEVER swift build rule to 'those targets', and :32-36 keep exception 2 for pure SwiftPM CLI and server packages 'e.g. asc-mcp'. The icloud, wheele and ~/.agents copies have the same content; the Dev essentials lines ~/dev/work/CLAUDE.md:93 and ~/dev/personal/CLAUDE.md:25 carry the same exception, and the two blocks are identical. CLAUDE.md:5-7 is byte-identical to round 2. The counterexample does not reproduce.
- Required-Correction: Done outside the repo (SKILL.md) and in e607b50 (CLAUDE.md:5-7); unchanged by the merge.
- Follow-Up: None for this finding. The round-2 SKILL.md line citations are superseded by :11-13, :17 and :32-36.
### PR30-F003
- Severity: P3
- Confidence: 0.95
- Blocking: no
- State: CLOSED
- Location: GitHub PR #30 description, '## Changes', CLAUDE.md bullet (PR metadata, not a repository file)
- Impact: The PR description still summarizes the CLAUDE.md note as 'production-effect ASC tools are on the settings ask list', the claim that PR30-F001 corrected in the file: CLAUDE.md:8-13 says every write against a real company is live and owner-only unless provably reversible, and that the ask list covers the main families but is not exhaustive (promotional text through apps_update_metadata is not gated). A reader of the PR record gets the pre-fix guarantee. Impact is low: the repository text is correct, and develop merge commits carry only the PR title (repository setting merge_commit_message PR_TITLE, as in the develop merges of #21, #23, #25, #27 and #31), so the description does not enter git history.
- Original-Counterexample: PR #30 description read through GitHub MCP at head 9ee25eb: 'CLAUDE.md: @AGENTS.md + three Claude notes ... production-effect ASC tools are on the settings ask list ...'. CLAUDE.md:9-12 at 9ee25eb: 'The ask list of the Claude Code settings prompts the owner for the main production families (...), but it is not exhaustive.'
- Required-Correction: Edit the CLAUDE.md bullet of the PR description to match CLAUDE.md:8-13: writes against a real company are live and owner-only unless provably reversible; the ask list prompts for the main production families and is not exhaustive. A description edit does not change the head, so this approval stands.
- Follow-Up: Closed by the TeamLead before the merge: PR description edited, head unchanged.

## Verdict
- Patch: APPROVE
- Merge: READY
- Merge-Actor: TEAMLEAD
- Release-Deploy: NOT_ASSESSED
- Production-Authority: OWNER_ONLY
- Approved-Head: 9ee25eb4512dfd48cb817c9f1cc212e5cd1232b4
- CI: Exact-head run 35980774431 (9ee25eb): Promotion Lineage success, Tests success (1,868 tests in 138 suites), Release & Apple Contract success (Operation contract 4.5: 502 public tools, 0 unclassified, 0 structural errors, 0 implementation drift, 0 warnings), Mint MCP Smoke & Publish Release skipped (tag-only). These are exactly the develop ruleset's required checks under the strict up-to-date policy; mergeable_state clean, no review threads. A merge-commit or squash merge lands exactly the CI-tested tree dc90ad49 on develop while develop stays at 5e04643. Any new head, including another develop merge, invalidates this approval.
- Remaining-Not-Checked: Fresh Claude Code and Codex sessions loading the canon; worktree sessions under .claude/worktrees; local swift build/test; the #31 content beyond CI (reviewed in #31); the edited PR description for PR30-F003

## Not checked and residual risk
- Not checked: Fresh Claude Code session in the repo reading the canon (/memory listing AGENTS.md through the import)
- Not checked: Codex session reading AGENTS.md
- Not checked: Worktree sessions under .claude/worktrees: the main-checkout CLAUDE.md import is external (unchanged from round 1)
- Not checked: Local swift build/test (read-only brief; CI built and tested the exact tree)
- Not checked: The #31 content beyond CI (reviewed and receipted in #31)
- Not checked: The 502-name tool list used for the family check is SUPPLIED (the TeamLead's #31 head build dump, tree identical to develop); every name was found in the head Sources, but no local tools/list was run
- Residual risk: The settings are live files outside git: the six ask entries existed at review time; re-check them at the FINAL_RECEIPT (the owner's notes record a TUI rewrite race)
- Residual risk: Other live-store writes outside the ask list (for example promotional text through apps_update_metadata) stay unprompted by design and rely on the note's general rule
- Residual risk: PR30-F003: the PR description overstates the ask list until it is edited
- Residual risk: If develop moves before the merge, the strict up-to-date policy forces a branch update, which is a new head and needs a re-review
- Residual risk: Outside this PR (unchanged): the repo-root companies.json is protected only by the note and .gitignore