docs: clarify document ownership and what durable prose leaves out - #162
Merged
Conversation
Reference inventories shortcuts, so a surface's keyboard behavior reads as though it belongs there. It does not, and the context popup's arrow keys were written up in both documents before the split was settled.
The commit rule binds every contributor. The verification step repeats it for an agent, which writes with a whole session in context, and extends it to comments and pull request text.
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.
Summary
Two guidance gaps that #161 walked into, both fixed where the guidance is read rather than where the symptom appeared.
docs/README.mdnow states the distinction it already implied: Reference lists what exists, Specification states how it behaves, and keyboard behavior is Specification's even though Reference inventories the shortcuts.CONTRIBUTING.mdbans verification evidence, commands run, and per-file summaries from commit bodies, but not the account of how the work unfolded, which is what fix: reach and operate the editor context popup by keyboard #161's documentation commits carried: references to sibling commits and to what an earlier attempt got wrong. The new rule names that, ties it to the squash merge that discards the sequence, and goes after the cause — a commit that exists only because documentation was held back until its code landed will produce such a body, so the documentation should land with the change it describes.AGENTS.mdgains the matching checkpoint under verification, since an agent writes with a whole session in context and the same habit reaches code comments and pull request text. It draws the line at recoverability: rationale a reader cannot reconstruct from the diff stays, the account of how it was reached goes.Related Issue
Not applicable. Small, self-contained correction, per
CONTRIBUTING.md. Refs #161, which is where both gaps surfaced.Verification
pnpm exec oxfmt --check AGENTS.md CONTRIBUTING.md docs/README.mdpasses, and the pre-commit hook ran the same check on each commit. Documentation-only with no executable configuration touched, so no application suite, per the documentation-only rule inCONTRIBUTING.mdandAGENTS.md.Nothing here is mechanically enforced, and that is deliberate: no linter separates a comment that explains a workaround from one that narrates the afternoon, and a gate that cannot make that call would either pass everything or block correct prose.
Notes
Pull Requestssection gets no duplicate rule. TheAGENTS.mdline already covers pull request text, and a second enumeration invites matching the list rather than the principle, which is how the original rule was obeyed to the letter and missed anyway.docs/README.mdare unchanged. Removing "shortcuts" from Reference's description would be wrong, since Reference does inventory them; the ambiguity is about behavior versus inventory, which is where the sentence was added.