Skip to content

Restructure AGENTS.md to terse wayfinding, relocate release and macOS specs - #22

Merged
quantizor merged 1 commit into
fix/process-safety-teardownfrom
docs/agents-restructure
Aug 9, 2026
Merged

Restructure AGENTS.md to terse wayfinding, relocate release and macOS specs#22
quantizor merged 1 commit into
fix/process-safety-teardownfrom
docs/agents-restructure

Conversation

@quantizor

Copy link
Copy Markdown
Owner

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

  • The codebase map collapses from six wall-of-text bullets to one terse line per structural piece, each keeping its "one home" pointer (prepareSpawn is the trust gate, liveDescendants is the descendant-union home, displayPort is the shown-port home, and so on) and every file and symbol name a reader needs to navigate. The # devctl H1 becomes a plain first line, per the agent-loaded-file formatting rule.
  • The make app / make dmg / signing / notarization / Release DMG workflow / Homebrew cask bump mechanics move to a new docs/releasing.md, with a one-line hook in AGENTS. AGENTS keeps the short make build / make test / smoke-script pointers.
  • The macOS "Stack notes" (swift-subprocess sessions, launchd PATH/ThrottleInterval/ExitTimeOut, SMAppService status traps, the BTM ad-hoc CDHash rebind saga, the DMG/Applications shared-bundle-id rules) move verbatim to a new 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

  • AGENTS.md dropped from roughly 29.5 KB to 19 KB, almost all of it the two relocated sections and the map compression.
  • Every file and symbol named in the rewritten map was grepped and resolves; the relocated macOS notes preserve every specific (BackgroundItems-v16.btm, the sfltool no-sudo note, the xpcproxy invalidation, diagnose-by-UUID). No em-dashes; no H1, bold, tables, or horizontal rules in AGENTS.md.

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.

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.
Copilot AI lite review requested due to automatic review settings August 9, 2026 20:13

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@quantizor
quantizor merged commit cd3fa5b into main Aug 9, 2026
2 checks passed
@quantizor
quantizor deleted the docs/agents-restructure branch August 9, 2026 20:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants