docs: split AGENTS.md into directory-scoped rule files

[mforce]

TL;DR

This PR moves rules that apply only to a few paths out of the root AGENTS.md and into scoped AGENTS.md files. The root drops from 80.4 KB to 26.9 KB (67%), and every session loads it. No rule text changes. A script checked that every non-blank line of the old root appears exactly once across the new files.

Closes #1034

Design

• The repo keeps one CLAUDE.md (root, @AGENTS.md).
• The root has a Scoped rule files index. It lists the paths that trigger each scoped file and tells every harness to read the linked file before editing those paths. Each harness loads a scoped file only when it needs it.
• A rule moves only when the index lists every path that can trigger it. Rules that apply across these trees stay in the root.

Paths	Scoped file	Rules
src/**, tests/**, tools/simulation/**, Dockerfile, deploy/**, .editorconfig, Directory.Build.props	src/AGENTS.md	the old Conventions section (application shape and the module ledger, data and tenancy, auth, boot guards, the backend operations rules) and the single serving instance (#271)
web/**	web/AGENTS.md	#662 badge case, #688 help prose follows labels, #662 selector call sites, #824 retiring style guards
src/Cluckwork.Infrastructure/Persistence/**, docs/schema/**, tools/schema-docs/**	src/Cluckwork.Infrastructure/Persistence/AGENTS.md	#407, #283, #417, #318, #505
.github/**, docs/releasing.md, deploy/**	.github/AGENTS.md	#782 docs-only gating, Action SHA pins, runs-on labels, the Releases and image publishing (#351) section including the canonical deploy-boundary paragraph

Stayed in the root on purpose: layout, build/test, secrets, host-agnostic, writing a guard, CI security gates, Git/PR, phase context, graphify, and a new Browser tests, screenshots and verification section (#277, UI screenshots, the verify skill). Also:

• CI: measure where Build and test's 10 minutes go, and what the backend suite covers #775: the CI matrix is triggered by adding a test project.
• Backend: measure test coverage, report before gating #776: coverage tooling lives in tools/coverage/.
• SPA UI verification track: Playwright E2E smoke + canary-under-load over the #243 sim fixture #277: E2E placement applies in web/ too.
• Three release bullets every PR author needs, now under Git / PR workflow.

How to review

1. 8d2916f6 is the move itself. Read only the root Scoped rule files section, the line-5 intro change and the scoped file headers. Everything else is moved text, with relative links re-prefixed for the new depth.
2. 2083d9ad repoints references to the new locations: decision-record Rule — pointers, the #releases-and-image-publishing-351 anchors in SECURITY.md and docs/releasing.md, and comments in workflows and CODEOWNERS.
3. f3c0014e drops the per-directory CLAUDE.md shims (owner: one CLAUDE.md).
4. 55bcbc73 applies the Codex Astra review: three rules return to the root, the index lists every trigger path, and chore(infra): do not partition AuditEvents by time — record why, and what to do instead #505 moves to Persistence.
5. 7a789c82 moves the backend rules to src/AGENTS.md (owner request). It repoints about 40 decision-record pointers, the CONTRIBUTING.md Version anchor, the Background worker has no single-runner guarantee — double-runs if scaled >1 instance #271 anchor (which was broken before this PR), five live comments in workflows, deploy/ and .specify, and RenameAccountDocsTests, which now reads src/AGENTS.md for the CLI: rename-account verb to change a farm code (replaces the raw-SQL runbook path) #732 link.
6. d247ea3f applies Astra round 2: routes Directory.Build.props and tools/simulation/**, adds a Farm configuration and identity become Owner-only, matching spec §5.1 #729 note to the web/** entry, returns Deploy: container/image hardening — non-root USER, pinned base digests, image vulnerability scan #267 to the root, fixes the chore(infra): do not partition AuditEvents by time — record why, and what to do instead #505 link and three stale references.

Verification (head d247ea3f, rebased on a71ec7af)

• Split check: every old line is present exactly once. The only expected differences are the intro, the table of contents and the dropped ### Migrations and schema heading, and the screenshot rule's anchor.
• Documentation tests: 20/20 passed.
• SchemaDocsTests and SolutionTestProjectSplitTests: 5/5 passed.
• changed-paths.test.mjs: 16/16 passed.
• git diff --check: clean.

This PR is not documentation-only under #782, because it adds .md files outside the root, so web and image run.

Not repointed: code comments in tests/ and src/ that cite "AGENTS.md" generically. The root index resolves them, and editing about 24 .cs files only to change a comment is noise.

[mforce]

Review round 1: Codex gpt-6-astra (high), local review over ebd4e3a6. Fixed in 55bcbc73.

#	Sev	Finding	Response
1	P2	#776 coverage is triggered under tools/coverage/, outside .github/.	Fixed: returned to the root.
2	P2	#775: adding a test project in tests/ never loads the matrix rule, and the guard goes green if someone edits its array without adding a CI leg.	Fixed: returned to the root.
3	P2	#417's "never hand-edit" covers docs/schema/**, outside Persistence.	Fixed: the index now routes docs/schema/** and tools/schema-docs/** to the Persistence file.
4	P2	#277 E2E placement also applies when someone adds browser tests in web/.	Fixed: returned to the root. tools/simulation/AGENTS.md became empty and was removed.
5	P3	The release boundary paragraph also governs docs/releasing.md and deploy docs.	Fixed: the index routes docs/releasing.md and deploy/** to .github/AGENTS.md.
6	P3	Prose still names the old location.	Fixed: the live amendment in docs/superpowers/specs/2026-07-25-dependabot-lockfix-design.md. Kept as history: docs/plans/** and the slice table in docs/designs/822-mui-revamp.md, which record what was done at the time.
7	P3	#505 is triggered by a migration.	Fixed: moved to Persistence and listed in the index.

I also took the reviewer's suggested index wording: each entry lists explicit trigger paths, and one read instruction applies to every harness. The reviewer could not refute rule preservation, link resolution, the guards or in-tree discovery.

Verification at 55bcbc73, rebased on a71ec7af: the split check is clean, and the documentation tests (20/20), SchemaDocsTests with SolutionTestProjectSplitTests (5/5) and changed-paths (16/16) all pass.

[mforce]

Rule-following probe at 7a789c82: 3 tasks × 2 cheap models.

Each run started in the PR worktree, so it loaded only this branch's root AGENTS.md. The prompts never mention AGENTS.md. Each run had to plan without editing and list every rule that applies, with the file it comes from.

Task	Model	Scoped files opened	Rules applied	Missed
Customer Notes field	claude-haiku-4-5	src/, Persistence/	Version, Idempotency-Key, validator, new migration, schema docs, UpdatedAtUtc, tenancy	the parallel-race test (it cited the Version rule but not the test it requires)
Customer Notes field	codex gpt-6-luna	src/, Persistence/	Version + race test, Idempotency-Key, validator, InitialCreate freeze, schema docs, tenancy, module ledger	—
Third-party Action in CI	haiku	.github/	SHA pin + # vX.Y.Z, ubuntu-26.04	—
Third-party Action in CI	luna	.github/	SHA pin + # vX.Y.Z, ubuntu-26.04	—
Help sentence + .chip CSS	haiku	web/	label per locale (#688), transform callers (#662), call-site count, badgeCase	—
Help sentence + .chip CSS	luna	web/	label per locale, transform callers, call-site count (found that .chip does not exist)	—

All 6 runs found the right scoped files through the root index alone. The only miss was a detail inside a rule the model had already opened, not a failure to find the rule. Raw runs and the runner are in /tmp/ruletest/ on the coordinator host.

[mforce]

Review round 2: Codex gpt-6-astra (high), local review over 7a789c82. Fixed in d247ea3f.

#	Sev	Finding	Response
1	P2	Directory.Build.props can break #985 (EnforceCodeStyleInBuild) and #264 (InvariantGlobalization) but is not routed.	Fixed: added to the src/AGENTS.md route.
2	P2	#729's exact-Admin Farm settings nav entry is implemented in web/src/routes/nav.tsx.	Fixed: the web/** entry now says role-gated navigation also needs src/AGENTS.md (#729).
3	P2	#370 "never disable a guard" applies to edits in tools/simulation/.	Fixed: tools/simulation/** is routed to src/AGENTS.md.
4	P2	#267's weekly, non-gating image scan can be broken from .github/workflows/.	Fixed: #267 returns to the root's CI security gates section, and its decision pointer is reverted to the root.
5	P3	The #505 decision link climbed one directory too far, a bug in my round-1 script.	Fixed: ../../../docs/decisions/505-….
6	P3	Stale live references.	Fixed: the docs/decisions/README.md residency sentence, verify-harness.sh (two comments), 776-backend-coverage.md:157, and the root phase-context link to the single-instance section.
—	P3 opt.	Move the Testcontainers bullet.	Declined: it is a useful run prerequisite in Build / test / run, and the reviewer rated it context cost only.

Verification at d247ea3f: every old line is present exactly once, and the only differences are the declared intro, TOC, heading and link changes. A script resolved every relative link in the five AGENTS.md files. The documentation tests (20/20) and changed-paths (16/16) pass, and bash -n verify-harness.sh is clean. The root is now 26.9 KB, down from 80.4 KB.

That makes two review rounds. Both found real routing defects and no product defects (this is a docs PR). Per the owner's loop rule, I am not triggering a third round. The owner decides whether to merge.