docs: stale-PR re-eval, experimental-export, and background-coder review guidance (#288)

* docs: add stale-PR re-eval, experimental-export, and consumer-lens guidance

Adopting a months-old PR (#243) surfaced three gaps in the AICA review/authoring
guides:

- no discipline for re-evaluating a stale or pre-merge PR (retire temporary
  uv.sources pins once upstream lands; re-check drift vs current main)
- the experimental-vs-top-level export convention was undocumented, so the
  code_mode exemplar steered new-capability authors toward top-level exports
- the review checklist named "dogfooding need" but no reference consumer or the
  cache/cost/reliability lens a long-running background coder cares about

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: key export-stability rule on shipped-in-release, not on a symbol list

Only CodeMode has shipped in a published release (v0.3.0 exports just CodeMode);
FileSystem, ManagedPrompt, and Shell are top-level on main but pre-release. The
earlier wording labeled all four "already-released", which is inaccurate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: drop the reference-consumer lens bullet

Keep the two clearest gaps (stale-PR re-eval, experimental-vs-released exports);
drop the consumer-lens addition, which named pydanty (a separate repo) in the
harness review checklist and was the most likely to read as out-of-place.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: David SF <david.sanchez@pydantic.dev>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -44,7 +44,9 @@ Before implementing or reviewing a capability change:
    signatures when needed. Do not assume a contributor's local checkout layout.
 5. Use `pydantic_ai_harness.code_mode` as the exemplar for capability shape,
    docs, tests, and public exports until another capability becomes a better
-   example.
+   example. `code_mode` is a released top-level capability; new capabilities
+   start under `pydantic_ai_harness.experimental` (see
+   `agent_docs/capability-authoring.md`, "Experimental Vs Released Exports").
 
 ## Capabilities API reference
 

agent_docs/capability-authoring.md

@@ -31,6 +31,22 @@ Each capability package should normally have:
 The root `pydantic_ai_harness/__init__.py` should re-export stable public
 capabilities. Keep implementation helpers private unless users need them.
 
+### Experimental Vs Released Exports
+
+New capabilities land under `pydantic_ai_harness/experimental/`. Each
+experimental package calls `warn_experimental('<name>')` in its `__init__.py` so
+importing it emits `HarnessExperimentalWarning`. Anything under `experimental`
+may change or be removed in any release, without a deprecation period.
+
+Promote a capability to a top-level package and a top-level re-export in
+`pydantic_ai_harness/__init__.py` only when its API is stable.
+
+Top-level exports in `pydantic_ai_harness/__init__.py` are the intended public
+surface. Once an export has shipped in a published release it is a
+backward-compatibility commitment: do not move, rename, or break it. (`CodeMode`
+is a shipped, released example.) Do not relocate an already-top-level capability
+into `experimental`.
+
 ## API Design
 
 - Prefer a small dataclass capability with typed fields.

agent_docs/review-checklist.md

@@ -20,6 +20,21 @@ Use this before opening a PR or reviewing a capability change.
 - Capability ordering is justified when present.
 - Dependency changes were made through `uv` and have a clear reason.
 
+## Stale Or Pre-Merge PRs
+
+Run these checks when adopting, rebasing, or re-reviewing a PR that was opened
+well before now, or that was built against unreleased Pydantic AI changes.
+
+- Temporary `[tool.uv.sources]` pins to a branch or git ref are removed once the
+  upstream change they waited on has landed in a released `pydantic-ai-slim`.
+- Each upstream Pydantic AI PR or branch the change rode on has merged. Link the
+  upstream PR and its merge state.
+- The touched surface has not drifted: re-check the capability, hook, and toolset
+  signatures it depends on against current main, not against the state at fork
+  time.
+- Behavior the PR worked around because a primitive was missing is reconsidered
+  if that primitive now exists in core.
+
 ## Tests
 
 - Tests cover the public `Agent(..., capabilities=[...])` path where possible.