Docs(refactor[agents]): Route instead of restate

why: AGENTS.md is read on every task, so a policy that matters to one
class of change costs context on all the others. Splitting how we work
from how we write lets each be loaded when it applies, and keeps both
discoverable to humans rather than only to agents.

what:
- Replace the AGENTS.md body with a router: the project map, universal
  change discipline, then one pointer per class of change
- Add .github/WRITING.md for prose policy, folding in docs/AGENTS.md's
  voice guidance and the prose-policy parts of the old AGENTS.md
- Add .github/CONTRIBUTING.md for workflow policy, folding in the
  workflow parts of the old AGENTS.md plus Logging Standards (kept out
  of src/libvcs/ so it cannot leak into the built wheel)
- Turn docs/project/contributing.md and docs/project/code-style.md
  into pointer pages to the canonical .github/ files; code-style.md
  keeps its one executing doctest, since testpaths includes docs/ but
  not .github/
- Delete docs/AGENTS.md and docs/CLAUDE.md, absorbed into WRITING.md
- Rewrite README.md to the new prose policy; fix the stale version
  pin example (>=0.37,<0.38 -> >=0.45,<0.46); preserve every link and
  every heading anchor

Author: tony

.github/CONTRIBUTING.md

@@ -0,0 +1,262 @@
+# Contributing
+
+Thanks for looking. libvcs accepts contributions through
+[GitHub](https://github.com/vcs-python/libvcs). libvcs is pre-1.0: bug
+reports with a reproduction, and reports of where the API or the
+documentation misled you, are the most useful contributions right now.
+
+How this project writes prose — README, `CHANGES`, commit messages,
+docstrings, and source comments — is set out separately in
+[WRITING.md](WRITING.md). Read that before changing any of it. The
+constraints every change is held to, and the map of what is where, are in
+[AGENTS.md](../AGENTS.md).
+
+## Getting set up
+
+Development requires [uv](https://github.com/astral-sh/uv).
+
+```console
+$ git clone https://github.com/vcs-python/libvcs.git
+```
+
+```console
+$ cd libvcs
+```
+
+```console
+$ uv sync --all-extras --dev
+```
+
+## The gates
+
+[ruff](https://ruff.rs) formats and lints in a single tool. The full rule
+set is declared in `pyproject.toml` under `[tool.ruff]`.
+
+Format:
+
+```console
+$ uv run ruff format .
+```
+
+Lint:
+
+```console
+$ uv run ruff check . --fix --show-fixes
+```
+
+[mypy](http://mypy-lang.org/) runs in strict mode (`[tool.mypy] strict =
+true`):
+
+```console
+$ uv run mypy .
+```
+
+Test:
+
+```console
+$ uv run pytest
+```
+
+Documentation is a gate, not a courtesy. Examples in docstrings,
+documentation pages under `docs/`, and `README.md` are executed by
+`pytest`; the doctest flags live in `pyproject.toml`, so there is no
+separate doctest step and a green `pytest` is the proof. Which blocks
+qualify, and the one mistake that silently removes a test, are in
+[WRITING.md](WRITING.md#documented-examples-that-run).
+
+Before claiming a test or a gate works, show it failing. A gate that has
+never been red is an assumption.
+
+### Imports
+
+- `from __future__ import annotations` at the top of every file.
+- Standard-library modules use namespace imports: `import pathlib`, not
+  `from pathlib import Path`. Third-party packages may use
+  `from X import Y`.
+- Typing: `import typing as t`, then access via namespace —
+  `t.NamedTuple`, `t.Any`.
+
+### Logging
+
+These rules guide future logging changes; existing code may not yet
+conform.
+
+**Setup.** Use `logging.getLogger(__name__)` in every module. Add a
+`NullHandler` in library `__init__.py` files. Never configure handlers,
+levels, or formatters in library code — that is the application's job.
+
+**Structured context via `extra`.** Pass structured data on every log call
+where useful for filtering, searching, or test assertions. Core keys are
+stable, scalar, and safe at any log level: `vcs_cmd` (`str`, the VCS command
+line), `vcs_type` (`str`, git/svn/hg), `vcs_url` (`str`), `vcs_exit_code`
+(`int`), `vcs_repo_path` (`str`). Heavy keys — `vcs_stdout`, `vcs_stderr`
+(`list[str]`) — are DEBUG-only; truncate or cap them (`stdout[:100]`).
+Names are `snake_case` with a `vcs_` prefix. Treat established keys as
+compatibility-sensitive — downstream users may build dashboards and alerts
+on them.
+
+**Lazy formatting.** `logger.debug("msg %s", val)`, not f-strings: the
+interpolation is skipped entirely when the level is filtered, and a
+log-aggregator's message-template grouping treats `"Running %s"` as one
+signature instead of one per f-string value. Guard an expensive `val` with
+`if logger.isEnabledFor(logging.DEBUG)`.
+
+**`stacklevel` for wrappers.** Increment it for each wrapper layer so
+`%(filename)s:%(lineno)d` and OTel `code.filepath` point to the real
+caller. Verify whenever call depth changes.
+
+**`LoggerAdapter` for persistent context.** For objects with stable
+identity (Repository, Remote, Sync), use `LoggerAdapter` instead of
+repeating the same `extra` on every call.
+
+**Log levels.** `DEBUG` for internal mechanics and VCS I/O; `INFO` for
+repository lifecycle and user-visible operations; `WARNING` for recoverable
+issues, deprecations, and user-actionable config; `ERROR` for failures that
+stop an operation. Config-discovery noise is `DEBUG`; only a surprising or
+user-actionable config issue escalates to `WARNING`.
+
+**Message style.** Lowercase, past tense for events — `"repository
+cloned"`, `"vcs command failed"` — no trailing punctuation. Keep the
+message short; put details in `extra`.
+
+**Exception logging.** Use `logger.exception()` only inside an `except`
+block when not re-raising. Use `logger.error(..., exc_info=True)` for a
+traceback outside an `except` block. Avoid `logger.exception()` followed by
+`raise` — it duplicates the traceback.
+
+**Testing logs.** Assert on `caplog.records` attributes, not string
+matching on `caplog.text`: scope capture with
+`caplog.at_level(logging.DEBUG, logger="libvcs.cmd")`, filter records by
+attribute rather than position, and assert on schema
+(`record.vcs_exit_code == 0`, not `"exit code 0" in caplog.text`).
+`caplog.record_tuples` cannot access extra fields.
+
+**Avoid:** f-strings or `.format()` in log calls; unguarded logging in hot
+loops; catch-log-reraise without adding context; `print()` for
+diagnostics; logging secret env var values; non-scalar objects in `extra`;
+custom `extra` fields referenced in a format string without a safe default
+(a missing key raises `KeyError`).
+
+## Tests
+
+The suite spawns real `git`, `hg`, and `svn` processes. A test that needs a
+VCS binary is skipped automatically when that binary is not on `PATH` — you
+do not need all three installed to contribute.
+
+**Write tests as standalone functions** (`test_*`), not classes. Avoid
+`class TestFoo:` groupings; use descriptive function names and file
+organization instead. This applies to pytest tests, not doctests.
+
+**Parameterized tests** use `typing.NamedTuple` for the fixture shape:
+
+```python
+class RepoFixture(t.NamedTuple):
+    test_id: str  # For test naming
+    repo_args: dict[str, t.Any]
+    expected_result: str
+
+
+@pytest.mark.parametrize(
+    list(RepoFixture._fields),
+    REPO_FIXTURES,
+    ids=[test.test_id for test in REPO_FIXTURES],
+)
+def test_sync(...): ...
+```
+
+**Fixtures.** `src/libvcs/pytest_plugin.py` (registered as a `pytest11`
+entry point) provides:
+
+- `create_git_remote_repo`, `create_hg_remote_repo`, `create_svn_remote_repo`
+  — build a temporary remote repository, each gated on its VCS binary being
+  installed.
+- `git_repo`, `hg_repo`, `svn_repo` — a ready-to-use sync instance checked
+  out from a session-cached remote; every consumer gets an isolated copy, so
+  a test may mutate it freely, including under parallel runs.
+- `set_home`, `vcs_gitconfig`, `vcs_hgconfig`, `git_commit_envvars` —
+  environment fixtures that isolate `$HOME` and VCS configuration from the
+  host running the tests.
+
+The full reference, including the doctest-only helpers each fixture backs,
+is at
+[the pytest plugin API page](https://libvcs.git-pull.com/api/pytest-plugin/).
+
+**Running in parallel.** On a multi-core machine, [pytest-xdist](https://pytest-xdist.readthedocs.io/)
+spreads the real-subprocess tests across workers:
+
+```console
+$ just test-parallel
+```
+
+This runs `uv run py.test -n auto`, where `auto` sizes the worker pool to
+the machine's cores. Parallelism is opt-in — `just test` and `uv run pytest`
+stay serial by default.
+
+**Order independence.** Tests must pass regardless of the order they run
+in. Keep fixtures self-contained and reset any global state in teardown.
+Check locally with a shuffled run:
+
+```console
+$ uv run --with pytest-randomly py.test -p randomly
+```
+
+**Debugging.** When stuck in a debugging loop: pause and name the loop out
+loud, strip the reproduction down to its minimum, and write down what you
+tried before changing approach. Guessing repeatedly at the same fix wastes
+more time than the pause does.
+
+## Documentation
+
+```console
+$ just build-docs
+```
+
+runs Sphinx and fails the build on a broken cross-reference — the doctests
+do not catch that, so build the docs before committing a page that adds or
+moves a `{ref}`, `{doc}`, or other role target.
+
+```console
+$ just start-docs
+```
+
+starts [sphinx-autobuild](https://github.com/executablebooks/sphinx-autobuild)
+at <http://localhost:8068>, rebuilding on file changes.
+
+## Releasing
+
+Never create tags. Never push tags. The owner handles tagging and tag
+pushes, because a tag triggers the publish workflow. See
+[Release commits](WRITING.md#release-commits).
+
+libvcs is pre-1.0: a minor version bump (0.39 to 0.40) may contain breaking
+changes; a patch bump (0.39.0 to 0.39.1) is reserved for bug fixes and
+documentation. The version is set in `src/libvcs/__about__.py` and
+`pyproject.toml`. The maintainer's full release checklist is published at
+[Releasing](https://libvcs.git-pull.com/project/releasing/).
+
+## Pull requests
+
+One subject per pull request. Unrelated cleanup found along the way belongs
+in its own commit, and usually in its own pull request.
+
+Discuss a substantial change via an issue before making it.
+
+Commit format is in [WRITING.md](WRITING.md#commits).
+
+## Decorum
+
+- Participants will be tolerant of opposing views.
+- Participants must ensure that their language and actions are free of
+  personal attacks and disparaging personal remarks.
+- When interpreting the words and actions of others, participants should
+  always assume good intentions.
+- Behaviour which can be reasonably considered harassment will not be
+  tolerated.
+
+Based on [Ruby's Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/).
+
+## Security
+
+Please do not open a public issue for a vulnerability. Report it privately
+through the repository's
+[security advisories](https://github.com/vcs-python/libvcs/security).