Restructure AGENTS.md to terse wayfinding, relocate release and macOS specs - #22
Merged
Merged
Conversation
AGENTS.md had grown into walls of actionable specification the house rules keep out of a wayfinding file. The codebase map collapses to one terse line per structural piece, each keeping its "one home" pointer and every file/symbol name a reader needs to navigate, and the H1 becomes a plain first line. Two spec blocks move to their own docs with one-line hooks: the make app / make dmg / signing / notarization / Release DMG / cask-bump mechanics to docs/releasing.md, and the macOS process, launchd, SMAppService, and BTM rebind reference to docs/macos-lifecycle.md. Every hard rule and engineering rule stays, tightened but never dropped, since those are the invariants the file exists to hold.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AGENTS.md had grown into walls of actionable specification, which the house rules keep out of a wayfinding file (that file holds invariants, one-line map entries, and keyword hooks; specification belongs in a feature doc). This restructures it and relocates the specs. Stacked on #21; review that first. Docs only, no code.
What changed
# devctlH1 becomes a plain first line, per the agent-loaded-file formatting rule.make app/make dmg/ signing / notarization /Release DMGworkflow / Homebrew cask bump mechanics move to a newdocs/releasing.md, with a one-line hook in AGENTS. AGENTS keeps the shortmake build/make test/ smoke-script pointers.docs/macos-lifecycle.md, with a one-line hook.What did not change
Every hard rule and every engineering rule stays. Those are the invariants the file exists to hold, so they were tightened in wording where the mechanism already lives in code comments, but none was dropped, weakened, or stripped of its rationale or version pin. The coverage rule keeps its exact measurement command, as the house rules require naming the command that prints the live figure.
Verification
Follow-up worth a backlog entry
The map names about fifty files and symbols and nothing checks they still exist, so a rename rots it silently. A small CI grep asserting each
Sources/...path and each backticked symbol in AGENTS.md resolves would make that fail loudly. Noting it here since the maintainer-local BACKLOG.md is not in a clone.