docs: add AI_POLICY.md with full AI-assisted contribution policy

AI_POLICY.md

@@ -0,0 +1,312 @@
+# AI-Assisted Contribution Policy for xarray-spatial
+
+## Summary
+
+xarray-spatial is currently moving toward its first major release after a period of stalled development. At this stage of the project, we want to increase development velocity, improve bug-finding, and reduce review bottlenecks by making responsible AI-assisted review part of our normal contribution workflow.
+
+Our policy is that contributors are expected to use the project’s approved AI-assisted review workflow before submitting pull requests, unless they explicitly explain why they did not.
+
+However, AI tools are not authors, maintainers, reviewers, or accountable contributors. Every contribution must be linked to a human who understands the change, accepts responsibility for it, and can maintain it after merge.
+
+We do not want pull requests, commits, issues, or comments that advertise a particular AI or LLM service. Contributions should not be attributed to “Claude,” “ChatGPT,” “Copilot,” or any other tool. The human contributor is the author.
+
+## Core principle
+
+AI may help find bugs, review code, suggest tests, improve documentation, or identify edge cases.
+
+But the human contributor is always responsible for the contribution.
+
+A pull request should never ask maintainers to review something that the contributor does not understand. The contributor must be able to explain the change, defend the design, respond to review comments, and maintain the code later.
+
+## Project assumption
+
+For the current phase of xarray-spatial, we assume that pull requests have gone through AI-assisted self-review using the project’s command-suite prompts.
+
+This means that, by default, maintainers may ask:
+
+> “Has this PR gone through the xarray-spatial AI review workflow?”
+
+rather than:
+
+> “Did you use AI to create this?”
+
+The important question is not whether AI touched the work. The important question is whether the contributor used the project’s review workflow responsibly and remained accountable for the result.
+
+## Policy
+
+Contributors may use any tools they want while developing their changes, but pull requests to xarray-spatial should use the project’s approved AI-assisted review workflow before being submitted for maintainer review.
+
+This workflow must be based on the prompts and commands maintained by the xarray-spatial project. The purpose is to make AI review consistent, project-specific, and focused on the kinds of failures we care about before the first major release.
+
+Contributors must personally review all code, tests, documentation, comments, generated suggestions, and issue text before submitting them. Submitting raw or lightly reviewed AI output is not acceptable.
+
+The contributor is always the author and is fully accountable for the contribution.
+
+## No AI authorship or service advertising
+
+Do not attribute commits, pull requests, issues, documentation, or review comments to an AI service.
+
+Avoid language such as:
+
+```text
+Generated by ChatGPT
+Written by Claude
+Committed by Copilot
+Authored by an AI agent
+```
+
+Do not add AI tools as commit authors, co-authors, maintainers, reviewers, or credited contributors.
+
+Acceptable wording focuses on the project workflow, not the vendor or model:
+
+```text
+AI review: completed using the xarray-spatial command-suite workflow.
+```
+
+or:
+
+```text
+AI review: not completed; see explanation below.
+```
+
+The human contributor’s name, account, and judgment must remain attached to the work.
+
+## Pull request expectations
+
+Every non-trivial pull request should include an AI review statement.
+
+Suggested PR template section:
+
+```markdown
+## AI-assisted review
+
+- [ ] I ran the xarray-spatial AI-assisted review workflow for this PR.
+- [ ] I reviewed the AI output myself and made my own judgment about what to accept.
+- [ ] I understand this change and can maintain it.
+- [ ] This PR does not attribute authorship to an AI tool or service.
+
+If AI-assisted review was not used, explain why:
+
+> 
+```
+
+For pull requests that did use the workflow, contributors should summarize what the review found:
+
+```markdown
+## AI-assisted review notes
+
+The xarray-spatial review workflow was run against this change.
+
+Issues found:
+- Added a regression test for malformed spatial metadata.
+- Reworked error handling around empty geometry collections.
+- Confirmed no change to public API behavior.
+
+Open concerns:
+- Performance impact on large tiled datasets may need follow-up benchmarking.
+```
+
+For pull requests that did not use the workflow:
+
+```markdown
+## AI-assisted review notes
+
+The xarray-spatial review workflow was not used.
+
+Reason:
+- This change only fixes a typo in documentation.
+```
+
+or:
+
+```markdown
+Reason:
+- The workflow could not run locally because of an environment issue.
+- I manually reviewed the change and would appreciate maintainer guidance.
+```
+
+## What counts as the xarray-spatial AI workflow?
+
+The approved workflow is the set of prompts, scripts, commands, or review instructions maintained in the xarray-spatial repository.
+
+The workflow may include checks for:
+
+- likely bugs
+- missing tests
+- incorrect edge-case handling
+- unclear error messages
+- API compatibility issues
+- documentation gaps
+- unsafe assumptions
+- spatial indexing or geometry edge cases
+- release-blocking regressions
+- maintainability risks
+
+The goal is not to produce more code. The goal is to find problems earlier.
+
+Contributors should prefer project-provided prompts over generic “review this code” prompts. Generic AI review often misses project-specific context and may produce noisy or misleading suggestions.
+
+## Human review is still required
+
+AI-assisted review does not replace maintainer review.
+
+AI-assisted review also does not replace the contributor’s own judgment.
+
+Before asking maintainers to review a pull request, contributors should be confident that:
+
+- they understand the change;
+- the change is appropriately scoped;
+- tests have been added or updated where needed;
+- the AI review output has been read critically;
+- irrelevant AI suggestions have been ignored;
+- accepted AI suggestions have been checked for correctness;
+- the PR is worth the maintainer time required to review it.
+
+Passing maintainer comments into an AI tool and reposting the result without understanding it is not acceptable.
+
+## Non-extractive contribution standard
+
+Maintainer attention is scarce. xarray-spatial currently needs speed, but not at the cost of flooding the project with low-quality changes.
+
+A good contribution should be worth more to the project than the time required to review it.
+
+AI-assisted workflows are encouraged because they can help contributors reduce the cost of review before maintainers get involved. They should make contributions less extractive, not more extractive.
+
+Examples of helpful AI-assisted use:
+
+- finding missing tests before opening the PR;
+- identifying edge cases in spatial data handling;
+- checking whether error paths are covered;
+- improving documentation clarity after the contributor writes the first draft;
+- producing a list of review risks for the contributor to evaluate;
+- comparing implementation behavior against expected release goals.
+
+Examples of unhelpful or extractive use:
+
+- submitting AI-written code the contributor does not understand;
+- opening a large PR with no explanation of design tradeoffs;
+- accepting AI-suggested refactors unrelated to the issue;
+- posting AI-generated maintainer replies without human judgment;
+- using AI to argue with reviewers;
+- replacing a focused bug fix with broad, speculative rewrites.
+
+## Agents and automated comments
+
+Automated agents must not take action in xarray-spatial project spaces without human approval.
+
+This includes agents that:
+
+- open issues;
+- open pull requests;
+- push commits;
+- publish review comments;
+- respond to maintainers;
+- apply labels;
+- close or reopen issues;
+- make release-related changes.
+
+Opt-in tools that keep a human in the loop are allowed. For example, a contributor may run a local AI review command, read the result, decide what matters, make changes manually, and summarize the result in the PR.
+
+Automated review comments posted directly by a bot or AI service are not allowed unless the maintainers have explicitly approved that integration for the project.
+
+## Contributions covered by this policy
+
+This policy applies to:
+
+- code pull requests;
+- tests;
+- documentation;
+- examples;
+- RFCs and design proposals;
+- issue reports;
+- security reports;
+- pull request reviews;
+- maintainer-facing comments;
+- release notes;
+- project governance text.
+
+## Handling missing AI review
+
+Because xarray-spatial is intentionally using AI-assisted review to accelerate development, maintainers may flag pull requests that do not include an AI review statement.
+
+Suggested maintainer response:
+
+```text
+This PR does not include the expected xarray-spatial AI-assisted review statement.
+
+For this phase of the project, we ask contributors to run the project’s AI-assisted review workflow before requesting maintainer review, unless there is a clear reason not to.
+
+Please update the PR with either:
+
+1. a short summary of the AI-assisted review results, or
+2. an explanation of why the workflow was not used.
+
+The contributor remains the author of the change and is responsible for understanding and maintaining it.
+```
+
+Possible labels:
+
+```text
+needs-ai-review
+needs-human-explanation
+extractive
+needs-smaller-scope
+```
+
+The `needs-ai-review` label does not mean the contribution is bad. It means the PR has not yet followed the project’s expected pre-review workflow.
+
+## Handling misuse
+
+Maintainers may ask for changes, close a pull request, or lock a discussion if a contribution appears to misuse AI tools in a way that shifts excessive work onto maintainers.
+
+Examples include:
+
+- the contributor cannot explain the change;
+- the PR appears to be raw AI output;
+- the PR contains hallucinated APIs, files, tests, or behavior;
+- the contribution advertises or attributes authorship to an AI service;
+- the contributor repeatedly reposts AI-generated responses without understanding them;
+- the PR ignores the project’s required review workflow without explanation;
+- the change is much larger or more speculative than the issue requires.
+
+Suggested maintainer response:
+
+```text
+This contribution does not currently meet the xarray-spatial policy for responsible AI-assisted contributions.
+
+We encourage use of the project’s AI-assisted review workflow, but the human contributor must remain accountable for the change and must be able to explain and maintain it.
+
+Please revise this PR by:
+
+- reducing its scope,
+- explaining the motivation and implementation,
+- running the xarray-spatial AI-assisted review workflow,
+- summarizing the issues found,
+- and confirming that you personally reviewed the result.
+
+Until then, this PR is not ready for maintainer review.
+```
+
+## Copyright and licensing
+
+Contributors are responsible for ensuring that they have the right to contribute all code, documentation, tests, and other materials under the xarray-spatial project license.
+
+Using an AI tool does not remove copyright or licensing obligations.
+
+Contributors must not use AI tools to reproduce copyrighted code, documentation, tests, or examples from incompatible sources. If a reviewer has concerns about the origin of a contribution, they may ask the contributor to explain how the work was produced.
+
+Contributions that violate copyright, licensing, or attribution requirements may be removed.
+
+## Maintainer discretion
+
+This policy is intended to support xarray-spatial’s current development phase: moving faster toward a first major release while keeping responsibility human and review costs sustainable.
+
+Maintainers may waive the AI-assisted review expectation for trivial changes, emergency fixes, mechanical updates, or cases where the workflow is not applicable.
+
+Maintainers may also require AI-assisted review before considering a complex change.
+
+The goal is not bureaucracy. The goal is to make better contributions reach review faster.
+
+## Credits
+
+This policy is adapted from the GDAL AI/LLM tool policy, with substantial changes for xarray-spatial’s current project needs and its preference for proactive, project-specific AI-assisted review rather than AI-use disclosure as an exception.

CONTRIBUTING.md

@@ -45,6 +45,8 @@ In order to avoid duplication of effort, it's always a good idea to comment on a
 
 ### AI-Assisted Contribution and Review
 
+See [AI_POLICY.md](AI_POLICY.md) for the full AI-assisted contribution policy. The summary below covers the essentials.
+
 xarray-spatial welcomes responsible AI-assisted development and review when it helps contributors move faster, improve quality, and reduce maintainer burden. The project has limited dedicated development capacity, so contributors are encouraged to use AI tools for testing, debugging, feature work, documentation, deployment, and release preparation.
 
 Attribution and responsibility belong to human contributors. Do not add AI tools, coding agents, or AI companies as commit authors, co-authors, reviewers, or attribution lines in commits, pull requests, changelogs, or release notes.