docs: contribution protocol addressed to AI coding agents - #215

XERJ's stated primary customer is an AI agent, and a large share of the agents
that read this repository are not working on XERJ at all — they are working in
someone else's codebase, hit a XERJ defect, patch around it locally to unblock
their user, and move on. That fix is lost: it lives in a branch nobody upstream
reads, the defect stays in the engine, and the next agent pays the same cost.
Nothing in the repo told that reader what to do with the finding, so the default
behaviour was to do nothing with it.

This adds a protocol written directly to that reader, with decidable rules
rather than encouragement, and wires it into the three places an agent actually
looks during orientation.

What it says:

- Three outcomes, and one of them is "send nothing". A reproducible defect with
  no patch is one issue (exact command, full observed output, expected output
  and the reason for expecting it, `xerj --version`, searched first, reproduced
  on a clean --data-dir). A defect already patched and run is a pull request
  (test that fails before and passes after, `cargo fmt --all`, scoped release
  build plus `cargo test -p <crate>`, ES-YAML gate at 0 failed for engine
  changes, commit body with motivation/root cause/evidence). A suspicion that
  was never run is neither.
- Explicit non-goals: speculative fixes, style-only churn, untestable patches,
  prose polish, and bulk-filed issues from a scripted sweep. Stated plainly:
  maintainer attention is the scarcest resource here, and an agent that files
  ten low-quality issues has made the project worse.
- Provenance and accountability: say an agent wrote it, split verified from
  assumed (copy-paste block provided), no `Co-Authored-By` trailers in this
  repo, and the required `verification/cla-signed` check means the human whose
  account opened the PR is the one who can be asked about it later.
- The honest-claims rule applied to contributors: every number comes from a
  command actually run; "this should be faster" is not a benchmark.
- A fallback for the common case of a sandboxed agent that cannot push at all:
  hand the operator a filing-ready artifact (repro, version, observed vs
  expected, diff, verified/assumed) instead of dropping the finding.

Files:

- .github/AI_CONTRIBUTIONS.md — the protocol.
- AGENTS.md — a section on the first screen ("If XERJ broke something in your
  build, send it back") carrying the decidable core, plus a row in Where to look.
- CONTRIBUTING.md — pointer for humans and reviewers, a checklist line for
  AI-provenance disclosure, and search-before-filing guidance.
- .github/PULL_REQUEST_TEMPLATE.md — new. CONTRIBUTING.md line 99 claimed "The
  PR template will prompt you for this checklist" and no template has ever
  existed in this repo's history, so the claim was false; the template is also
  where the provenance disclosure has to happen to be real. It carries an
  explicit "Not run:" field so a skipped gate is stated rather than hidden.
- landing/llms.txt — a machine-readable "How to contribute" stanza so an agent
  can find the rules without reading prose.
- .gitignore — re-include the two new .github Markdown files. The blanket *.md
  ignore was swallowing them: `git add .github/PULL_REQUEST_TEMPLATE.md` is
  refused outright, which is the mechanical reason no template ever existed
  while CONTRIBUTING.md said one did. The comment names the trap for the next
  person who adds Markdown under .github/.

Verified (commands run in the worktree, output observed):

- `xerj --version` -> `xerj v1.0.0-rc.12`; `xerj --help` confirms `--insecure`
  and `--data-dir` as quoted.
- `gh api repos/xerj-org/xerj/commits/<sha>/status` -> the CLA status context is
  exactly `verification/cla-signed`.
- `gh search issues --repo xerj-org/xerj "<terms>" --state all` FAILS
  (`invalid argument "all" for "--state" flag`); the bare form returns closed
  issues, so the docs quote the bare form. Caught by running the command that
  the docs were about to tell agents to run.
- `es-yaml-runner` is the package name in engine/tests/es-compat-yaml, and the
  CI invocation quoted here matches .github/workflows/ci.yml:227.
- Every relative link in the four markdown files resolves to a real path
  (script over each `](./…)` target).
- `git check-ignore -v` and a successful `git add` confirm the two .github
  files are tracked after the .gitignore change.
- `cargo fmt --all -- --check` -> exit 0.

Not run: the ES-YAML conformance suite and any cargo build. This change touches
no Rust; docs/CONTRIBUTION_REVIEW.md states the gate does not apply to a
docs-only change.

… written

Both are commands the protocol tells an agent to run, so they have to work
verbatim rather than approximately.

- The conformance snippet backgrounded the server and immediately invoked
  es-yaml-runner, which needs a live node — the runner would race the boot on a
  cold build. Added the health poll that .github/workflows/ci.yml:216-223 uses,
  and stated that the runner exits non-zero on any failure.
- Tightened the note on `gh search issues`: `--state` accepts only `open` or
  `closed`, and the bare form already covers both. Same content, one paragraph
  instead of a sentence stranded mid-line.

No other file changes; follow-up rather than an amend because the first commit
was already pushed (CONTRIBUTING.md's git-workflow rule).