Add three patterns from graduated agent shapes

[chris-colinsky]

Summary

First of five docs-polish items. Graduates three substantive entries from docs/agent/non-obvious-shapes.md into full pattern docs under docs/patterns/, each following the existing pattern doc structure (Problem → Approach → Snippet → When this is right → When it isn't → Cross-references):

• state-migration-on-resume: schema_version conventions, the Callable[[Any], Any] migrate signature, the JSON-backed checkpointer requirement, chained migrations, and the fail-loud CheckpointStateMigrationMissing failure mode.
• caller-supplied-trace-identifiers: invoke(metadata=...) and set_invocation_metadata propagation through OTel attributes and Langfuse trace.metadata, with the boundary validation rules (reserved-key namespaces, OTel-compatible scalar types).
• observer-state-reconciliation: per-invocation dict keyed on (namespace, branch_name, attempt_index, fan_out_index) for custom observers that need to thread state between paired events; uses a NamedTuple for the timing record so the shape is self-documenting.

Three graduated entries removed from non-obvious-shapes.md (the patterns catalog handles discoverability). Bundled AGENTS.md and the programmatic patterns API (openarmature.patterns) regenerated; catalog grows from 4 to 7 entries.

Notable while writing: the original with_state_migration recipe in non-obvious-shapes had the wrong migrate callable signature (claimed three-arg; actual is single-arg Callable[[Any], Any]). Pattern A ships the corrected shape plus the serialization=\"json\" checkpointer requirement that makes the migration path actually work.

Test plan

• uv run pytest -q (1080 pass, no regressions)
• uv run pyright src tests clean
• AGENTS.md drift test passes
• tests/unit/test_patterns_api.py bumped to expect the 7-entry sorted list
• Local mkdocs serve and confirm the three new patterns render correctly under the Patterns nav

Out of scope

• Items 2-5 of the docs-polish sweep (vLLM production notes, deep docs sweep, README pointer-block thinning, version on homepage). Separate PRs.
• Lifting "subgraphs > conditional-edge spaghetti": closer to a Concepts decision than a Pattern; stayed as a non-obvious shape.

[Copilot]

Pull request overview

Graduates three “non-obvious shapes” into first-class Pattern docs (and wires them into the docs site and the programmatic openarmature.patterns catalog), while removing the graduated entries from docs/agent/non-obvious-shapes.md.

Changes:

• Add three new pattern docs (state migration on resume, caller-supplied trace identifiers, observer started→completed reconciliation) under docs/patterns/ and mirrored into src/openarmature/_patterns/.
• Update the docs navigation, patterns index, and generated AGENTS.md to include the new patterns and remove the graduated “non-obvious shapes” entries.
• Update the patterns API unit test to expect the expanded 7-pattern list.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/unit/test_patterns_api.py	Updates expected openarmature.patterns.list() slugs to include the three new patterns.
src/openarmature/AGENTS.md	Regenerates bundled docs to include the three new patterns and removes the graduated sections.
src/openarmature/_patterns/state-migration-on-resume.md	Adds packaged pattern markdown for programmatic access via openarmature.patterns.get().
src/openarmature/_patterns/caller-supplied-trace-identifiers.md	Adds packaged pattern markdown for programmatic access via openarmature.patterns.get().
src/openarmature/_patterns/observer-state-reconciliation.md	Adds packaged pattern markdown for programmatic access via openarmature.patterns.get().
mkdocs.yml	Adds the three new patterns to the MkDocs nav.
docs/patterns/state-migration-on-resume.md	Adds new site pattern doc for checkpoint state migration.
docs/patterns/caller-supplied-trace-identifiers.md	Adds new site pattern doc for invocation metadata propagation.
docs/patterns/observer-state-reconciliation.md	Adds new site pattern doc for observer started→completed reconciliation.
docs/patterns/index.md	Adds the three new patterns to the patterns catalog index page.
docs/agent/non-obvious-shapes.md	Removes the three entries that were graduated into full pattern docs.
CHANGELOG.md	Notes the addition of three pattern docs and the patterns API growth from 4→7.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.