docs: track and shorten the agent guidance

[sindredg]

AGENTS.md was gitignored, so no rule in it reached a fresh clone. An agent working here read the code and inferred the conventions instead, which is how the file drifted two renames behind without anyone noticing.

The claim the rest of the file rested on

It stated that main is protected, and that tests and ruff are required checks binding administrators too. Checked:

sky main -> protected: False
required_status_checks: {'enforcement_level': 'off', 'contexts': [], 'checks': []}

Neither holds. The history shows what that permits: 7683fdc Delete .github directory and 864a812 Rename project and simplify README content both went straight to main with no pull request. The first removed CI along with the workflows, and 26 tests asserted on missing files for ten days before anything ran them again.

The file now states the real position and cites that commit. Turning on branch protection with CI required is the change that makes the original sentence true, and it is a repository setting, not something a commit can do.

Removed, as describing a project that no longer exists

Removed	Why
Azure hard rules: ARM_SUBSCRIPTION_ID, AcrPush, norwayeast, bootstrap identity split	The Azure estate was deleted
Terraform conventions section	terraform/ no longer exists
Layout tree	Named styles.css which is gone, missed galaxy.py, and said test_places "arrives with PR #7"
"There is no Dockerfile and no compose file yet"	Both exist
docs/decisions/ references	Directory was deleted
WSL environment traps, ports, .superpowers/ sweeping	Machine specific, belongs in the local notes that stay ignored
CONTEXT.md section	Told agents to read it every session while it stayed ignored and absent on a fresh clone

Kept, as judgment that cannot be checked

The agent authority boundary, "tests assert properties, not copies", the stacked pull request lesson from #18 and #19, and the writing rules. The examples in the properties section were re-drawn from live code, since the originals cited Terraform that is gone.

Two rules became tests

A rule in prose is skimmed. A rule in a test fails the build.

• test_the_shared_agent_guidance_is_tracked fails if AGENTS.md is ignored or missing
• test_no_em_dashes_in_tracked_markdown enforces the style rule that was previously prose

test_the_agent_notes_stay_ignored became test_the_local_agent_notes_stay_ignored, still covering CLAUDE.md, CONTEXT.md and docs/superpowers/.

Attribution and conventional commit prefixes were considered for tests and left as prose. Both need context pytest does not have: actions/checkout is shallow by default so git log sees one commit, and a pull request title is not visible from inside the suite. Those belong in a CI step if they are worth enforcing.

Cost

140 lines against roughly 300, so some genuine nuance went. The attribution reasoning and the merge ordering economics are shorter than they were.

Verified

Every assertion in test_repository_contract.py was evaluated directly: all 12 pass. compileall clean, no line over 88 characters so ruff format has nothing to reflow, and git check-ignore confirms AGENTS.md is now trackable. CI on this pull request runs the full suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---

Generated by Claude Code