docs: correct eight drift findings in the always-loaded contract and its docs - #2520
Open
IanQiu979 wants to merge 8 commits into
Open
docs: correct eight drift findings in the always-loaded contract and its docs#2520IanQiu979 wants to merge 8 commits into
IanQiu979 wants to merge 8 commits into
Conversation
The repo carried three mutually exclusive claims about test evidence: .no-mistakes.yaml said it is committed alongside the change, while CONTRIBUTING.md and docs/configuration.md both said it is kept outside the repo. store_in_repo was flipped to true in kunchenguid#2355 and none of the prose followed. Verified against the installed pipeline and this repo's own remote: store_in_repo writes artifacts into the working tree under .no-mistakes/evidence/<branch>/, which stays gitignored here, and the push step publishes them as commits on the orphan no-mistakes/evidence branch that PR bodies link into by commit sha. Nothing under .no-mistakes/ is ever committed to a code branch, so CI's tracked-path invariant keeps passing. All three statements now say that. Fixes drift-firstmate-a1 D3.
crew_dispatch_validate enforces a per-rule `select` field and the rule renderer prints it, but the section that declares itself the schema's single owner never mentioned it, so nobody hand-editing config/crew-dispatch.json could learn it exists. Documented to match bin/fm-bootstrap.sh: optional per-rule string, `quota-balanced` the only accepted value and already the implicit default for every profile array, no selector on the top-level default, and the two exact CREW_DISPATCH refusals for an empty or unknown value. Verified live by running bootstrap against the example config and against both malformed variants. Fixes drift-firstmate-a1 D4.
Five operator-facing variables were surfaced in script help or another doc but absent from the environment-variable reference, so a captain hitting a truncated startup digest or bearings view had no single place to find the knob. Adds FM_SESSION_START_TIMEOUT, FM_BEARINGS_LANDED, FM_BEARINGS_LANDED_PER_HOME, FM_BEARINGS_PR_LIMIT, and FM_LINT_JOBS with the defaults read from their producing scripts. Fixes drift-firstmate-a1 D9.
bin/fm-classify-lib.sh consumes a `note:` line and the wake drain's UNREAD STATUS section is its only guaranteed presentation, but no brief scaffold ever told a worker the verb exists. All three status protocols enumerated the same six states, so a worker with a substantive answer used `working:` instead, which the classifier absorbs as routine progress - exactly the burial AGENTS.md says that surface prevents. Adds the verb to the ship, scout, and secondmate-charter protocols, with a regression test asserting all three teach it. Fixes drift-firstmate-a1 D6.
Section 2 names docs/configuration.md the single owner of the home layout, and that page explicitly declines to keep one exhaustive state tree. AGENTS.md nonetheless carried a per-file map detailed enough to read as an inventory while omitting durable records such as state/terminal-outcomes/ and the Pi extension-loaded markers, so an agent could treat an unlisted entry as foreign or safe to remove - including markers supervision-health classification depends on. Says plainly that the map is an excerpt, keeps the owner pointer, and adds the safety consequence, without dropping anything it documents. Fixes drift-firstmate-a1 D7.
docs/scripts.md is the only index of bin/ and README.md links it as the toolbelt reference, but 33 shipped scripts had no row - including the process-event runner, the startup-memory accountant, fm-lint.sh, and the entire remote-secondmate transport family, several of which other pages already name as authoritative owners. Adds a row for each, purpose clauses taken from the scripts' own headers, and a regression test asserting coverage in both directions: an unlisted script and a row naming a file that no longer ships both fail. fm-doc-audience-check.sh validates prose inventory rather than bin/ coverage, so nothing caught this before. Fixes drift-firstmate-a1 D8.
The skill's window list was a schema revision behind live quota-axi output. Verified against a real --json snapshot at schemaVersion 3: unresolvedWindowIds and relationshipStatus are both present and unnamed. relationshipStatus matters most, because it corroborates exactly the provider relation the skill spends a section telling the agent to establish by hand. Also records that window ids are vendor-shaped rather than shared - the same snapshot reports five_hour, seven_day, and model:fable for claude against weekly for codex - so no reader assumes one vocabulary. The installed build is quota-axi 0.1.17, below firstmate's 0.1.25 floor, so a supported build may name further fields; these are additive facts observed live, and the skill's existing schema-variance handling still covers the rest. Fixes drift-firstmate-a1 D10.
…error AGENTS.md instructs firstmate to run fm-check-register.sh as the last step before the watcher may execute a custom check, but probing it for syntax parsed --help as the task id and reported "custom check is unavailable" - which reads as custom checks being disabled in the home rather than as a usage mistake. Adds --help/-h printing the header, expands that header to state what registration binds and when to repeat it, and rejects any leading-dash argument as misuse (exit 2). A genuinely absent check still reports the same capability error on exit 1, which the new test pins so the dash guard cannot swallow it. Fixes drift-firstmate-a1 C1.
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.
Eight documentation-drift findings, each verified by running the thing rather than reading about it. No behaviour changes except two
--helpoutputs.Findings fixed
crew-dispatchselectfield — validated, tested and rendered in code, absent fromdocs/configuration.md, which declares itself the schema's single owner.note:status verb — implemented, tested, and asserted byAGENTS.md, but no worker was ever told it exists. The brief scaffold's status list is now explicitly non-exhaustive and points at$FM_ROOT/bin/fm-classify-lib.shas the verb-set owner. The pointer is absolutized because crewmates read that brief from a project worktree, where a repo-relative path does not resolve.docs/scripts.md— omitted 33 of the 139 shippedbin/scripts; now covers the whole surface with a guard against regression.quota-array-dispatch— its window-id list was onequota-axischema revision behind. Corrected against live--jsonoutput atschemaVersion: 3.fm-check-register.sh --help— reported a capability error instead of usage.Not included, deliberately
Three further findings are captain-held decisions rather than corrections, because each changes a guarantee rather than fixing a typo — most notably that the secondmate liveness sweep iterates
state/*.metaand never readsdata/secondmates.md, soAGENTS.md's promise to account for every registered secondmate is not met when a registered home has no runtime record.Verification
Full pipeline: review, tests, documentation and lint gates all passed. Five test suites green, doc-audience check clean, coverage check clean.
🤖 Generated with Claude Code
https://claude.ai/code/session_017r6efPA7m2JkEUs7i9VAkf