fork-landing: shrink always-loaded AGENTS.md and generate the skill index from frontmatter (upstream #1341) - #29
Closed
sbracewell64 wants to merge 3 commits into
Closed
Conversation
…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
The consolidated doc-ownership check requires an injection and responsibility on every inventoried surface. Five surfaces added on the fork trunk after this branch was cut carried only an audience, so the check failed once the two were combined even though each side passed alone. Classify them by their audience's established value: the two agent-only reference skills lazy, the operator example, operator guide, and maintainer verification record referenced.
Owner
Author
|
Closing. This was opened as a fork-landing branch cut from fork The required Superseded pending a captain ruling. The shared contribution branch and its open upstream PR were never modified. |
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
1 participant
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.
Fork-landing branch for the contribution currently open upstream as kunchenguid#1341.
This branch is a separate branch cut from fork
main, carrying only that contribution's own changes. The shared branchfm/doc-truth-fleet-laneis not touched and remains at81fb495, so upstream kunchenguid#1341 is unaffected.Screening
The merge result is larger by +15 / -8. That is the reconciliation, itemised below, not unexplained drift.
Conflict reconciliation
The contribution shrinks always-loaded
AGENTS.mdtwo ways, and trunk had since added content to both places.The layout tree. The contribution replaces the inline directory tree with a short list of state facts that must survive with no other document loaded, delegating the rest to
docs/configuration.md. Every trunk entry the tree carried was confirmed present indocs/configuration.mdbefore the tree was dropped:config/models.json, the admission-control policy, the startup memory budget, the cmux socket password, the wedge alarm, Herdr presentation spaces, pending replies, and public follow-up. Nothing was lost.The skill roster. The contribution replaces the hand-maintained roster with
bin/fm-skill-index.sh, which renders triggers from each skill's own frontmatter. Verified empirically rather than assumed: the generator emits all 15 agent-only skills, including the two trunk added after this branch was cut (model-onboardingandfleet-admission). The generator is silent underclaudeby design, because that harness already injects skill descriptions;--forceand--list-agent-onlyconfirm the content.One genuine integration defect, fixed here
bin/fm-doc-audience-check.shpasses on trunk alone and passed on the contribution alone, but failed once combined: the contribution tightens the check to requireinjectionandresponsibilityon every inventoried surface, and five surfaces added on trunk after this branch was cut carried onlyaudience.Fixed in its own commit by classifying each of the five by its audience's established value —
lazyfor the two agent-only reference skills,referencedfor the operator example, the operator guide, and the maintainer verification record. This is the +15 / -8 above.Verification
bin/fm-doc-audience-check.shclean:ok surfaces=64 local_links=181.tests/fm-skill-index.test.sh: 6 cases, 0 failures.bin/fm-lint.shclean (ShellCheck 0.11.0).