feat(fleet): shrink always-loaded AGENTS.md and generate the skill index from frontmatter - #1341
Open
sbracewell64 wants to merge 2 commits into
Open
feat(fleet): shrink always-loaded AGENTS.md and generate the skill index from frontmatter#1341sbracewell64 wants to merge 2 commits into
sbracewell64 wants to merge 2 commits into
Conversation
Author
|
Conflict-free at 2039ca5; fork-side CI 9/9 green (mirror: sbracewell64#18, identical SHA); upstream workflow runs awaiting approval. |
…c ownership
Lane B of the documentation single-source-of-truth commission: reduce the
always-loaded contract to what only it can own, and convert the review's
ownership table from prose into a mechanically enforced artifact.
B1/B4 - AGENTS.md section 2 becomes a pointer plus safety lines.
The 9,407-byte fenced home tree restated docs/configuration.md, which already
declares itself the layout owner and explicitly pushes exact child fields to
each producing script's header. Every artifact the tree named was verified to
have such an owner before removal. What survives is what has no other owner:
the wake-event-not-truth rule, the never-touch watcher/auto-arm/sub-supervisor
classes, the check.sh execution-trust boundary, the scout report's survival of
teardown, and the corrected secondmates.md wording (created lazily by
fm-home-seed.sh, so absence means no secondmate is registered).
B2 - section 13 becomes a generated trigger index.
bin/fm-skill-index.sh renders the roster from each skill's own frontmatter,
selecting on user-invocable:false. It stays silent on harnesses that already
inject skill descriptions (claude, grok - both verified) and emits everywhere
else, including unknown harnesses: suppression requires positive evidence,
because a wrongly suppressed index silently removes every load trigger. A new
agent-only skill is now registered once, in its own frontmatter.
B3 - documentation-audiences.json gains injection and responsibility per
surface, and fm-doc-audience-check.sh requires both. The one-sentence limit on
responsibility is the enforcement: a surface needing two sentences owns too
much. The always-loaded set is now a queryable list rather than a claim.
Measured byte deltas (always-loaded plane):
AGENTS.md 55,237 -> 45,071 (-10,166)
section 2 10,777 -> 2,758 (-8,019; plan target -6,907)
section 13 2,913 -> 605 (-2,308; plan target -2,927)
Generated index costs 5,329 bytes only on non-injecting harnesses, so the
net is -10,166 on claude/grok and -4,837 elsewhere.
documentation-audiences.json grows 8,344 -> 17,081, never injected.
Certification: session-start smoke read under both a claude and an opencode
primary confirms no operator action lost its instruction; new
tests/fm-skill-index.test.sh (6 cases) covers suppression, emission, roster
derivation, folded-description rendering, and digest composition;
tests/fm-documentation-audiences.test.sh gains 2 cases for the required
fields; fm-lint.sh and fm-doc-audience-check.sh green.
…ames skill triggers
sbracewell64
force-pushed
the
fm/doc-truth-fleet-lane
branch
from
July 31, 2026 02:46
2039ca5 to
81fb495
Compare
Owner
|
Automated reminder: thanks for the PR! This branch currently has a merge conflict with the base branch. When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again. Noted for firstmate#1341 at |
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
2 participants
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.
Intent
Execute Lane B of the captain-authorized documentation single-source-of-truth commission (2026-07-30) for the firstmate fleet repo. Lane B is defined by section 11 of data/doc-truth-review/report.md, a prior read-only scout review; this branch implements its B1, B4, B2, and B3 rows.
GOAL: shrink firstmate's always-loaded AGENTS.md contract to only what it alone can own, and convert the review's documentation-ownership table from prose into a mechanically enforced artifact.
B1+B4 - AGENTS.md section 2 was 10,777 bytes, of which a 9,407-byte fenced directory tree restated docs/configuration.md. docs/configuration.md already declares itself the single owner of the operational-home layout and explicitly delegates exact child fields to each producing script's header. Before deleting anything I verified every artifact the tree named has such an owner; several (check-trust, pr-poll-retirement, turnend-claude-blocks, the grok/kimi turn-end tokens, pr-check-quarantine) are documented ONLY in bin/ scripts and not in docs/, which is exactly what the owner's declared boundary prescribes, so their removal from AGENTS.md is correct rather than a loss. What deliberately survives is every fact with no other owner anywhere in the repo: the status-line-is-a-wake-event rule, the never-touch rule for watcher/Claude-auto-arm/sub-supervisor state under state/ (I grepped the whole repo and this instruction exists nowhere else), the check.sh execution-trust boundary, the scout report surviving teardown, and B4's corrected secondmates.md wording (created lazily by fm-home-seed.sh, so absence means no secondmate is registered rather than a lost registry). The plan targeted -6,907 bytes; the measured result is -8,019 because collapsing the tree to five safety bullets beat the estimate. The report's own section 15.2 marks its after-column byte figures as engineering targets, not measurements, so beating one is expected.
B2 - AGENTS.md section 13 was a hand-maintained 2,913-byte roster of 13 agent-only skill triggers, duplicating each skill's own frontmatter description, which some harnesses inject into the session prompt unprompted. New bin/fm-skill-index.sh renders that roster from frontmatter, selecting on the existing user-invocable:false marker (verified to match the old roster exactly, 13 for 13). It is composed into the session-start digest by bin/fm-session-start.sh.
DELIBERATE DEPARTURE FROM THE REPORT, made on safety grounds and worth not flagging as a mistake: the report's section 7.3 table lists codex and kimi as 'likely' injecting skill descriptions, but its own section 15.2 admits those cells are unverified. I suppress the generated index ONLY where injection is positively verified - claude (proved by direct observation) and grok (harness-adapters records 'firstmate skills are discovered' plus a verified end-to-end invocation) - and emit it for every other harness including unknown. The asymmetry is intentional: a redundant index only costs bytes, whereas a wrongly suppressed one silently removes every agent-only skill's load trigger. The script header documents this and requires positive evidence before adding a harness to the suppression list.
Section 13 kept three sentences rather than collapsing to the report's suggested single sentence, so it fell 619 bytes short of the -2,927 target: the ownership pointer to fm-skill-index.sh and the register-once rule are contract facts a future maintainer needs, not roster. Net across AGENTS.md is -10,166 bytes, 332 better than the combined plan target.
Also honestly measured and contrary to the report's estimate: the report predicted the generated index would be byte-neutral on non-injecting harnesses. It actually costs 5,329 bytes there because frontmatter descriptions are richer than the old abridged roster. Net is therefore -10,166 on claude/grok and -4,837 elsewhere - still a reduction everywhere, but not the wash predicted. This is stated plainly rather than rounded away.
B3 - docs/documentation-audiences.json gains an injection field (always/lazy/generated/referenced/never) and a one-sentence responsibility for each of its 57 surfaces, and bin/fm-doc-audience-check.sh now REQUIRES both, refusing rather than defaulting a missing field. The one-sentence limit on responsibility is enforced by regex and is the point of the mechanism, per the commission: a surface that needs two sentences owns too much and should be split. This makes the always-loaded set a queryable list rather than a claim, and a test asserts it stays bounded to AGENTS.md plus its CLAUDE.md symlink.
CROSS-REFERENCES updated for the one-owner rule: firstmate-coding-guidelines and fmx-respond skills pointed at 'section 13' as the place to register a trigger; README.md said triggers are named in AGENTS.md; docs/scripts.md gains a row for the new script. All corrected in the same change.
CERTIFICATION already run locally: the plan requires a session-start smoke read for B1 proving no operator action lost its instruction - done under both a claude and an opencode primary, walking each instruction the removed tree carried. New tests/fm-skill-index.test.sh (6 cases) covers suppression, emission including unknown harnesses, roster derivation independently from frontmatter, folded multi-line description rendering, and digest composition. tests/fm-documentation-audiences.test.sh gains 2 cases for the required fields. bin/fm-lint.sh and bin/fm-doc-audience-check.sh are green.
KNOWN PRE-EXISTING FAILURE, not introduced here: tests/fm-session-start.test.sh has one failing case ('MISSING diagnostic did not appear at all'). I stashed this branch's changes and re-ran it on the base commit f0d7cbe, where it fails identically - it is environment-dependent tool detection, unrelated to this change.
CONSTRAINTS: this is firstmate's own shared tracked material, so repo style rules apply - one sentence per line in tracked Markdown, plain dash never em dash, no agent co-author on commits, bin/*.sh shellcheck-clean via bin/fm-lint.sh, tests colocated in tests/ as .test.sh extending existing runners, and tests must exercise behavior through executable interfaces rather than asserting implementation-source bytes.
What Changed
docs/configuration.mdis collapsed to five safety bullets (keeping only facts with no other owner, e.g. the status-line wake rule, the never-touchstate/rule, and thecheck.shtrust boundary), and section 13's hand-maintained 2,913-byte roster of agent-only skill triggers is reduced to a three-sentence ownership pointer.bin/fm-skill-index.shrenders the agent-only skill roster from each skill's frontmatter (verified 13-for-13 against the old roster) and is composed into the session-start digest bybin/fm-session-start.sh; the generated index is suppressed only on harnesses positively verified to inject skill descriptions (claude, grok) and emitted everywhere else, including unknown harnesses.docs/documentation-audiences.jsongains requiredinjectionand one-sentenceresponsibilityfields for all 57 surfaces, enforced bybin/fm-doc-audience-check.sh(refuses rather than defaults a missing field), with a test asserting the always-loaded set stays bounded to AGENTS.md plus its CLAUDE.md symlink; stale "section 13" cross-references in the firstmate-coding-guidelines and fmx-respond skills, README.md, anddocs/scripts.mdare updated, and new tests cover the skill index (6 cases) and the required audience fields.Risk Assessment
✅ Low: A well-bounded documentation-consolidation and tooling change whose key claims I independently verified: the generated skill index matches the removed 13-entry roster exactly, suppression is limited to the two positively verified injecting harnesses per the stated intent, the stricter inventory check passes green on the updated 57-surface inventory, removed AGENTS.md facts have confirmed owners elsewhere, and new behavior-level tests cover the suppression/emission matrix and required-field enforcement.
Testing
Ran the two new/extended test suites (12/12 cases green), then manually verified every intent claim end-to-end: skill-index emission/suppression per harness including the positive-evidence rule for unknown harnesses, real session-start digest composition under opencode vs claude primaries, doc-audience-check refusing missing injection and two-sentence responsibility fields while green on the real 57-surface inventory, exact 13-for-13 roster parity with the old hand-maintained section 13, byte deltas matching the claimed -10,166 net and -8,019 section 2, survival of all five no-other-owner facts, and corrected cross-references; the single fm-session-start.test.sh failure was reproduced identically at the base commit, confirming it pre-exists this change. No visual evidence applies - this is a CLI/docs repo and the transcripts captured are the end-user surface.
Evidence: Skill index emission/suppression transcript (opencode, claude, grok, unknown harness)
Evidence: Doc-audience-check: green run plus refusals for missing injection and two-sentence responsibility
$ bin/fm-doc-audience-check.sh fm-doc-audience-check: ok surfaces=57 local_links=162 exit 0 (green) $ bin/fm-doc-audience-check.sh --inventory <copy with one surface's injection field removed> fm-doc-audience-check: .agents/skills/afk/SKILL.md: unsupported injection None exit 1 $ bin/fm-doc-audience-check.sh --inventory <copy with a two-sentence responsibility> fm-doc-audience-check: .agents/skills/ahoy/SKILL.md: responsibility must be exactly one sentence - split the document instead of widening the field exit 1Evidence: Real session-start digest: AGENT-ONLY SKILLS section present under opencode primary, absent under claude
Evidence: Always-loaded set queried from inventory (exactly AGENTS.md + CLAUDE.md)
injection=always surfaces: ['AGENTS.md', 'CLAUDE.md']Evidence: Byte measurements vs base and 13-for-13 roster parity
AGENTS.md byte measurements (base f0d7cbe vs target e5e4161): whole file: 55237 -> 45071 (delta -10166; intent claims -10,166) section 2 (layout tree removed): 10777 -> 2758 (delta -8019; intent claims -8,019 for B1+B4) section 13 (roster replaced by generated index): 2913 -> 605 (delta -2308) Roster parity: old hand-maintained section 13 names vs generated index names: IDENTICAL - 13 skills in both (13-for-13)Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
.agents/skills/fmx-respond/SKILL.md:193- The updated cross-reference says "AGENTS.md §14 declares the load trigger for X-mode-linked milestone or terminal wakes", but §14 only explicitly declares the mention/error check-wake load and the terminal-outcome load; the milestone-wake trigger now lives solely in fmx-respond's own frontmatter description (surfaced via harness injection or fm-skill-index.sh). No trigger is functionally lost, but the sentence slightly overstates what §14 declares.bin/fm-session-start.sh:347- fm-session-start.sh invokes fm-skill-index.sh with stderr discarded and treats empty output as "suppress". If the index ever renders empty on a non-injecting harness due to a runtime failure (e.g. awk error), the digest silently omits every agent-only skill trigger - the exact silent-suppression failure the script's own header identifies as the dangerous direction. A diagnostic line distinguishing "suppressed by design" from "rendered empty despite agent-only skills existing" would make that failure visible; the independent roster test does mitigate this in CI.tests/fm-session-start.test.sh- tests/fm-session-start.test.sh has one failing case ('MISSING diagnostic did not appear at all') that is confirmed pre-existing: the identical test file extracted from base commit f0d7cbe fails the same way in this environment, matching the author's stated known failure. Because the runner halts at the first failure, the later cases in that file were not exercised on either commit; the change's own digest-composition behavior is instead covered by tests/fm-skill-index.test.sh case 6 and a manual end-to-end run, both green.bash tests/fm-skill-index.test.sh- all 6 cases pass (suppression, emission incl. unknown harness, roster derivation, frontmatter folding, --force, digest composition)bash tests/fm-documentation-audiences.test.sh- all 6 cases pass, including the 2 new required-field cases and the bounded always-loaded-set assertionManual:bin/fm-skill-index.sh --harness {opencode,claude,grok,some-future-harness}- emitted for opencode and unknown harness, silent (exit 0) for claude and grokManual:bin/fm-doc-audience-check.shgreen on real inventory (57 surfaces); refuses a copy with one surface's injection field removed and a copy with a two-sentence responsibilityManual end-to-end:bin/fm-session-start.shunder a fake-ps opencode primary renders the AGENT-ONLY SKILLS digest section; under CLAUDECODE=1 the index is absentManual: queried docs/documentation-audiences.json for injection=always - exactly AGENTS.md and CLAUDE.mdManual: diffed old hand-maintained AGENTS.md section 13 roster names against generated index names - identical, 13 for 13Manual: byte measurements vs base f0d7cbe - AGENTS.md 55,237 -> 45,071 (-10,166, matching claim), section 2 10,777 -> 2,758 (-8,019, matching claim), section 13 2,913 -> 605Manual: grepped new AGENTS.md for the five claimed surviving no-other-owner facts (status-line wake event, never-touch state/ internals, check.sh trust boundary, scout report survives teardown, lazy secondmates.md) - all present; no stale 'section 13' cross-references remain in skills or READMEbash tests/fm-session-start.test.shon both target and base-commit copies - identical single pre-existing failure ('MISSING diagnostic'), confirming it is not introduced by this change✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.