Improve event-driven-claims-agent: cost routing, deterministic execution, doc

[wilmatos]

Summary

Enhance and harden the existing event-driven-claims-agent sample
(02-use-cases/02-workflow-automation-agents/event-driven-claims-agent/)
to make it production-realistic and publication-ready. All changes are
confined to this sample (plus sample-scoped entries in the root .gitignore).

Motivation

The current sample works but has rough edges for learners: a third LLM call in
the execution phase, secret handling that could be more secure, thin test
coverage, and documentation that had drifted from the code. This issue tracks a
focused pass to improve cost/latency, tighten security posture, expand tests,
and align docs with the implementation.

Proposed changes

• Agent architecture
  • Cost-based model routing — Haiku for the classification-only Validation
    Agent (Phase 2), Sonnet for reasoning (ADR-0013).
  • Deterministic Phase 3 execution — remove the third LLM call and invoke
    Gateway tools directly from structured output (ADR-0014).
  • Fire-and-forget trigger invocation and more resilient prompts.
  • Refactor: inline MCP client, extract a testable routing.py, remove
    legacy modules.
• Auth & config
  • Manage the Gateway OAuth secret via AgentCore Identity token vault instead
    of environment-variable injection (ADR-0010).
  • Sanitize agentcore/agentcore.json for publication — placeholders for
    account, region, and Cognito pool/client (no environment-specific values).
• Tests
  • Unit tests for routing, structured output, Lambda handlers, and the
    trigger; Cedar policy tests; authentication-path tests; E2E suite with
    evidence-based assertions.
• Docs
  • Refresh docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/deployment.md,
    and docs/tutorial.md; add ADRs 0011–0014 and fix a duplicate ADR number.
  • Regenerate the high-level architecture.png (with committed source and
    AgentCore icons).
  • Replace the 6 MB demo.mp4 with an inline demo.gif in the README.

Out of scope

• Other samples in the repository.
• Switching the Policy Engine out of its current enforcement configuration.

Verification

• Unit tests: python3 -m pytest tests/
• Lint: ./scripts/lint.sh
• End-to-end (deployed stack): python3 scripts/test_e2e.py --region <region>
• Auth paths: python3 scripts/test_auth.py --region <region>

Acceptance criteria

• Changes limited to the event-driven-claims-agent sample.
• No environment-specific values or secrets in tracked files.
• Unit tests and lint pass locally.
• Docs match the current code (commands, file names, resource names).
• README renders the demo GIF and the updated architecture diagram.