docs: restructure contribution guidelines around authorship vs composition

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,17 +5,18 @@
 
 ## Summary
 
-[Describe what this PR changes and why, in your own words.]
+[Open with at least one sentence you wrote yourself: why does this change exist, and why is it worth a reviewer's attention? No agent may write this sentence for you. Machine-composed detail may follow, labeled with the tool that produced it.]
 
 ## For reviewers
 
 [What would you most value a second look at? What are you already confident in? For a refactor, say whether behavior is meant to be unchanged.]
 
 ## Author attestation
 
-- [ ] I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.
+- [ ] I am a human. I have reviewed and understood every change, and can explain why each is correct.
+- [ ] The opening of this description is my own. Any machine-composed text below it is labeled with the tool that produced it and whether I have read it — and where I endorsed it, I trimmed it to what a reviewer needs.
 
-AI coding assistance is welcome, but a human must be the author and is responsible for the contents of the PR. The description and any review responses must be in your own words. Please read [AI-assisted contributions](https://zarr.readthedocs.io/en/stable/contributing/#ai-assisted-contributions) before opening.
+AI coding assistance is welcome, and so is machine-composed text where it is labeled. But a human must be the author, in the sense of being answerable for every part of this pull request, and review responses must be in your own words. An agent preparing this pull request must leave these boxes for its operator to check. Please read the [contribution guidelines](https://zarr.readthedocs.io/en/stable/contributing/#contribution-guidelines) before opening.
 
 ## TODO
 

.gitignore

@@ -41,6 +41,9 @@ htmlcov/
 .cache
 coverage.xml
 *,cover
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
 
 # Translations
 *.mo
@@ -94,3 +97,38 @@ zarr.egg-info/
 
 # zarr-metadata package lockfile (a library, not an app)
 packages/zarr-metadata/uv.lock
+
+# ─── Agentic coding: local/personal state (provider-agnostic) ───
+# Commit shared instruction files (AGENTS.md, CLAUDE.md, .cursor/rules/) intentionally;
+# ignore only per-user/local state, session data, and caches below.
+
+# Local overrides & personal instruction variants
+CLAUDE.local.md
+AGENTS.local.md
+AGENTS.override.md
+*.local.md
+
+# Agent tool state directories
+.claude/
+.windsurf/
+.aider*
+.continue/
+.codeium/
+
+# Agent session transcripts, logs, scratch
+.agent/
+.agent-workspace/
+.agent-scratch/
+agent-logs/
+*.session.json
+*.transcript.*
+
+# MCP configs (frequently contain tokens/credentials)
+.mcp.local.json
+*.mcp.local.json
+
+# Agent caches / embeddings / vector stores
+.agent-cache/
+.context-cache/
+.embeddings/
+.vectorstore/

AGENTS.md

@@ -0,0 +1,88 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+`docs/contributing.md` is authoritative for contribution policy; read its **Contribution guidelines** section and follow it. The rules below restate the parts that bind you directly.
+
+- **Do not attest on your operator's behalf.** The pull request template asks the author to confirm they are a human who has reviewed and understood every change. Leave those boxes unchecked, and tell your operator they must check them.
+- **Do not open pull requests or issues unattended.** Do so only when your operator asks you to, on changes they have reviewed.
+- **Label text you composed**, and say whether a human read it first. Prefix it with one of:
+  - `:robot: _AI-generated text below, from <tool name>. I have read and endorse it._ :robot:` — only when your operator actually read it, edited it, and said to post it as-is.
+  - `:robot: _AI-generated text below, from <tool name>. Not yet reviewed by a human._ :robot:` — in every other case, including when you are posting on your operator's behalf without them having read the text.
+
+  Do not speak as your operator.
+- **Write less.** A human reads everything you post here. Say what changed and why it is correct; cut restatement of the diff, hedging, and summary of your own process. If your operator has to trim it before posting, you wrote too much.
+- **Do not write review responses.** When a reviewer asks a question, your operator answers it, in their own words.
+- **A pull request opens with a sentence your operator wrote.** Do not write it, and do not draft one for them to paste — the point is that they thought about the change, and a sentence you supplied proves nothing. Leave a placeholder saying so. You may draft the detail that follows, labeled.
+- **Attribute your commits** with an `Assisted-by: <harness>:<model>` trailer. Never add yourself as a commit author or `Co-authored-by:` — agents assist, humans author.
+
+Keep diffs small and reviewable.
+
+## Project overview
+
+`zarr-python` (PyPI package `zarr`) implements chunked, compressed, N-dimensional arrays for Python. This is the 3.x line, which reads and writes both Zarr format v2 and v3 data. Requires Python >= 3.12. The public API is re-exported from `src/zarr/__init__.py` (`Array`, `Group`, `create_array`, `open`, etc.).
+## Related projects
+
+`zarr-python` depends on the contents of the Zarr [v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html) and Zarr [v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html) storage specifications. We are committed to compliance with the specs, and also consistency with other Zarr implementations, namely:
+-  [TensorStore](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html) (C++ / Python)
+- [Zarrs](https://github.com/zarrs/zarrs) (Rust)
+- [Zarrita](https://github.com/manzt/zarrita.js/) (Javascript)
+## Environment and common commands
+
+Development uses **hatch** (with `uv` as the installer) for managed environments, and `uv` directly for ad-hoc commands. The canonical test environments are named `test.py3.{12,13,14}-{minimal,optional}`; `optional` pulls in remote stores (fsspec, obstore, s3fs), the CLI, and universal-pathlib.
+
+```bash
+# Run the full test suite in a managed env (benchmarks excluded by default)
+hatch env run --env test.py3.12-optional run
+
+# Run with coverage (XML report); coverage must reach 100% for CI to pass
+hatch env run --env test.py3.12-optional run-coverage
+
+# Ad-hoc test runs with uv (faster iteration than spinning up a hatch env).
+# Prefer uv run pytest for narrow runs; reach for hatch envs for full/coverage runs.
+uv run pytest tests/test_array.py                 # one test file
+uv run pytest tests/test_array.py::test_name      # one test function
+uv run pytest tests/test_array.py -k "expr"       # tests matching a -k expression
+uv run pytest "tests/test_array.py::test_name[param-id]"  # one parametrized case
+uv run pytest tests/test_array.py -x --lf         # stop on first failure, rerun last-failed
+
+# Run tests in parallel across CPUs with pytest-xdist (-n). Big speedup for the
+# full suite; for a handful of tests the worker startup cost usually isn't worth it.
+uv run pytest -n auto tests/                       # auto = one worker per core
+uv run pytest -n 4 tests/test_codecs/             # fixed worker count
+
+# Type-check (strict mypy over src + tests) — this is what CI's Lint job runs
+uv run --frozen mypy
+
+# Hypothesis property tests (slow; opt in)
+hatch env run --env test.py3.12-optional run-hypothesis
+
+# Docs: live-reloading server / strict build
+hatch --env docs run serve
+hatch --env docs run check
+```
+
+Note: `pytest` `testpaths` include `src`, `tests`, and `docs/user-guide`, and `--doctest-modules` is on — docstrings in `src/` are executed as tests, and the user-guide markdown is doctested. `xfail_strict = true` and `filterwarnings = ["error", ...]` mean an unexpected pass or an unfiltered warning fails the suite.
+
+## Linting and pre-commit
+
+The project uses [`prek`](https://github.com/j178/prek) (a drop-in pre-commit runner) against `.pre-commit-config.yaml`. Ruff (lint + format, line length 100) and `mypy` run here, plus codespell, numpydoc validation, towncrier-check, and zizmor.
+
+```bash
+prek run --all-files          # all hooks
+prek run --last-commit        # only files changed in the last commit
+```
+
+Two local rules worth knowing because they will reject otherwise-valid code:
+- **No `.lstrip("...")` / `.rstrip("...")` with multi-char string args** (`ban-lstrip-rstrip`) — these are character-set operations and almost always a bug where `removeprefix`/`removesuffix` was intended.
+- **numpydoc validation** is enforced on docstrings (Parameters/Returns sections must match signatures).
+
+## Changelog (required for most PRs)
+
+Every user-facing change needs a news fragment in `changes/` named `{issue-or-pr-number}.{type}.md`, where type is one of `feature`, `bugfix`, `doc`, `removal`, `misc`. Generated into `docs/release-notes.md` by towncrier at release time. `towncrier create` scaffolds one. The `towncrier-check` pre-commit hook will flag PRs missing a fragment.
+
+## Conventions
+
+- **Public API surface:** anything added to `__all__` in `__init__.py` / `api/synchronous.py` is public and must have a numpydoc docstring and an entry under `docs/api/*.md`. New user-facing behavior also belongs in `docs/user-guide/`.
+- **Experimental features** go under `src/zarr/experimental/`, are documented in `docs/user-guide/experimental.md`, and carry no stability guarantees (may be removed in any release). The team aims to promote or remove them within ~6 months.
+- **Versioning is EffVer, not SemVer** — breaking changes are possible in minor (and rarely patch) releases, judged by upgrade effort. Prefer backwards-compatible changes and deprecation warnings over hard breaks.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

changes/4041.doc.md

@@ -0,0 +1 @@
+Add guidance for agents to AGENTS.md and CLAUDE.md and gitignore agent state.

changes/4140.doc.md

@@ -0,0 +1 @@
+Restructure the contribution guidelines around the distinction between authorship (who is accountable for a contribution, which a tool can never be) and composition (who wrote the text, which a tool may do if it is labeled). Machine-composed text is now explicitly permitted in pull request descriptions where it is labeled with the tool that produced it and with whether a human has read it, provided the description opens with a sentence the author wrote themselves. Endorsing such text means having trimmed it, not merely read it. Review responses must still be in the author's own words. Commits may carry an `Assisted-by:` trailer, but a tool is never an author. The separate "AI-assisted contributions" section is removed, as its rules now follow from the general guidelines, which apply equally to contributors, core developers, and agents; `AGENTS.md` restates the agent-facing rules and defers to the contributing guide.