docs: cut AGENTS.md fixed context cost by routing prose to its owners - #1
Open
jdille wants to merge 5 commits into
Open
docs: cut AGENTS.md fixed context cost by routing prose to its owners#1jdille wants to merge 5 commits into
jdille wants to merge 5 commits into
Conversation
AGENTS.md was 66,883 bytes and is loaded in full by every session of every fleet member before any work starts. This applies the one-owner rule from firstmate-coding-guidelines to the prose that restated contracts already owned elsewhere, so each fact is stated once, in its owner, and pointed to from here. Section 2: replace the 75-line exhaustive layout tree with the records firstmate reads or writes by name, plus a categorical pointer for the rest. docs/configuration.md already declares itself the single owner of the home layout and says the exhaustive state tree should not be duplicated into it; the config/ and machinery entries are owned by that file and by the script headers that write each record. Section 3: drop the seven-stage digest enumeration. bin/fm-session-start.sh's header owns the ordering and stage contents in more detail, and AGENTS.md already named it the single owner. Kept the run-once, read-once, lock-refusal, consent, ABSENT, and unconfirmed-network-check rules that docs/configuration.md says AGENTS.md must retain. Section 4: drop the provider-relation, quota-granularity, and authentication detail owned in full by quota-array-dispatch. Kept the intake boundary, every-candidate accounting, malformed-config refusal, and the strongest-reasoning and tie rules that skill says AGENTS.md owns. Section 7: point at bin/fm-crew-state.sh for the run-step-to-state mapping, bin/fm-check-register.sh for the custom-check file requirements it enforces, and bin/fm-promote.sh for the promoted-worker instructions its header already carries verbatim. Consolidated the secondmate idle contract into section 6. Section 8: point at docs/watcher-continuity.md for the acknowledgement episode contract. The every-turn drain, wake-handling, and away-mode rules stay inline because they must be actionable with no other file loaded. Result: 66,883 -> 51,842 bytes, a 22.5 percent cut. Unchanged, verified byte-identical: section 1's five hard rules, section 7's delivery-path and merge-authority block, section 9's escalation translation table, all of section 13's skill triggers, section 8's away-mode stub, wake-kind list, and stuck-worker trigger, sections 10 through 12, section 14, and the captain-instruction precedence rule.
…-requirement rule
…heritance ownership in owners
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.
Cuts
AGENTS.mdfrom 66,883 to 52,099 bytes (22.1 percent), 568 to 494 lines, without weakening any safety boundary.Every firstmate session loads
AGENTS.mdin full before doing any work, so this is fixed context cost paid by every session of every fleet member. A new session was already starting at 45 percent context.Method
The one-owner rule from
.agents/skills/firstmate-coding-guidelines/SKILL.md: state a contract once, in its owner, and point at it from here. Every cut names the authoritative owner the reader is now sent to.docs/configuration.mdalready declares itself single owner of the home layout and states the exhaustive state tree should not be duplicated into it; per-record detail lives in the script headers that write each recordbin/fm-session-start.shheader, already named single owner two lines above the enumeration, documents nine stages in more detailquota-array-dispatch, which states in its own text that it is the single owner and that section 4 keeps only the intake boundary, load trigger, malformed-config refusal, every-candidate accounting, and strongest-reasoning and tie rulesbin/fm-crew-state.sh,bin/fm-check-register.sh(which enforces and fails closed on those rules),bin/fm-promote.sh(whose header carries the sequence verbatim)docs/watcher-continuity.mddocs/configuration.mdline 24 explicitly specifies which factsAGENTS.mdmust retain for session start; that statement guided what stayed rather than personal judgment.Deliberately not cut
Section 8 was flagged as a worst offender but is left nearly intact: most of it is the drain-and-handle contract that must be actionable mid-session with no other file loaded, since the emitted supervision block only arrives at session start. Section 7's intake and merge-authority block is untouched because
docs/architecture.mdline 184 explicitly assigns that contract toAGENTS.md. A smaller honest cut beats an aggressive one that loses a boundary.Unchanged, verified byte-identical
Section 1's five hard rules, section 5, section 7's delivery-path and merge-authority block (never-merge-red, the yolo boundary, ask-user authority), section 9's escalation translation table, all of section 13's skill triggers, section 8's away-mode stub, wake-kind list, and stuck-worker trigger, sections 10 through 12, section 14, and the captain-instruction precedence rule.
Three skills show fewer total mentions (
fmx-respond,process-event-sources,secondmate-provisioning). Every lost mention was traced: each was a descriptive reference inside the deleted layout tree, never a load trigger. Section numbering is unchanged, so the cross-references that name sections by number stay valid.Review fixes included
Three defects the pipeline review caught, all fixed in this branch:
4e8bbb3- the compressed state-machinery rule became a blanket prohibition that contradictedfmx-respond's requiredrm -f state/x-inbox/<request_id>.json, which would have caused a duplicate public reply on the next poll. Narrowed to permit owner-directed deletes, and both documented safe-to-delete affordances restored.bbad45f- prose compression had dropped the word "prefer" from the validate-phase rule, silently converting a preference into a directive. Restored.ec3a347- a pointer named the wrong owner:axi status --helpdocuments only--runand-h, whileaxi sync --helpis what ownsrecover_custody,--recover, and--keep-local. Redirected.Verification
bin/fm-doc-audience-check.shpasses (68 surfaces, 253 local links)tests/fm-session-start.test.shpasses in full, including itsAGENTS.mdinstruction-refresh and baseline-hash casesAGENTS.mdprose content; baselines are computed at runtimeStatus
Parked deliberately. This targets
jdille/firstmatemain and is not intended for merge.