docs: record the spec as the source of truth, add a PR template

[nielspardon]

Two gaps in the contributor docs.

Nothing stated that this repository implements the Substrait specification rather than defining it, or how to proceed when the spec is ambiguous. CONTRIBUTING.md now leads with that and gives an escalation order: the sibling language bindings under Active Libraries are the closest comparison for modeling questions, since they solve the same problem at the same layer; the engines under Powered by Substrait are the better reference for runtime semantics; and a clarification issue upstream comes only when neither shows a consensus. AGENTS.md carries the agent-specific half, because filling a spec gap with something plausible and then describing it as spec-defined is a failure mode worth naming outright.

There was also no PR template, even though the title and body are linted together and the body becomes the squash-merge commit body. That makes the description changelog input rather than a review scratchpad, so the template is a commit-body skeleton with its guidance in HTML comments rather than the usual checklist — boilerplate left behind would otherwise be published verbatim in the release notes.

The template's BREAKING CHANGE placeholder is indented deliberately. The conventional-commits parser anchors its note pattern at line start and has no notion of HTML comments, so a line-start placeholder in an un-edited template parses as a real note and publishes with a trailing -->. Indented it is inert until the author un-indents it.

That same behavior is why the footer has to come last: the parser ends a note only at another footer keyword or an issue reference, so a rationale paragraph or tool-attribution line after it is absorbed into the note. .releaserc.mjs already strips trailing git trailers for this reason, but it cannot match arbitrary prose, so ordering is the remaining defense.

Finally, this drops the gh CLI instruction from AGENTS.md: it describes the agent's environment rather than anything about this repository.

🤖 Generated with AI

[alexandrefimov]

Useful change, and the CONTRIBUTING sections read well. One thing in the template is worth fixing before it ships, noted inline.

Checked the TOC anchors against the new headings -- those all resolve.

Minor: the AGENTS.md rewrite drops For GitHub work (issues, PRs), use the gh CLI. from the intro. Unrelated to the spec-source-of-truth point, so it looks accidental rather than intended.

[alexandrefimov]

This block re-creates the trap it warns about, with --> standing in for the git trailer.

The placeholder sits inside the HTML comment and the instruction is to un-indent it. If someone does that but leaves the enclosing <!-- / --> -- easy to miss, since the whole block is invisible in GitHub's preview -- the squash-merge body ends up as:

BREAKING CHANGE: <what breaks, and what consumers should do instead>
-->

GitHub copies the PR description into the squash commit verbatim, comment markers included, and the parser ends the note only at another note keyword or a reference -- exactly as the text above this line says. So --> gets absorbed into the note and published in the release notes.

stripTrailers in .releaserc.mjs won't catch it either: it pops only blank lines and lines matching TRAILER_KEYS, so it breaks on the first --> and leaves it in place.

Either fix works:

• Move the breaking-change block outside the comment, so there is no --> left to trail the footer.
• Add a trailing --> to what stripTrailers strips -- the same belt-and-braces rationale as the git trailers it already handles.