v1.5.0

[mattyhansen]

This pull request prepares the v1.5.0 release with PHP client runtime features, typed response helpers, streaming improvements, and GOAT Flow documentation and agent-workflow scaffolding. It is not documentation-only; the runtime changes are part of the release scope.

Key changes include:

PHP Client Runtime Features

• Added OpenTelemetry tracing middleware that emits client spans and injects W3C trace-context headers when explicitly configured.
• Added typed stream callback handlers, including a printing reference handler and cancellation support through typed on* hooks.
• Added typed citation and guardrail assessment DTO accessors while preserving the existing raw array fields for backward compatibility.
• Added structured-output hydration, additional stop reasons, richer AgentInput media helpers, and specialized AgentErrorException subclasses.

Tests, Fixtures, and Release Notes

• Expanded unit coverage and fixtures for citations, guardrails, streaming helpers, exceptions, media inputs, and tracing middleware.
• Updated README and CHANGELOG entries for the v1.5.0 release features.

GOAT Flow and Agent Workflow Materials

• Added and updated GOAT Flow architecture, code map, learning-loop buckets, scratch/log/task anchors, and skill-reference playbooks.
• Mirrored agent skill documentation for the .agents and .claude runtimes, including goat-critique reference extraction for rubrics and sub-agent directives.
• Added local agent hook/config templates and repository housekeeping for the agent workflow.

Summary by CodeRabbit

• New Features

  • New multi-skill “goat-*” workflows (critique, review, debug, plan, qa, security), richer multi‑modal inputs (images/videos/documents/cache points), enhanced tracing/observability, sanitized stream summaries, response-observer hooks, and finer error/stop classifications.

• Documentation

  • Published Wire Contract v1, comprehensive skill/reference guides, patterns, architecture, examples, and a Python gateway reference.

• Tests

  • Expanded fixtures and suites covering tracing, streams, citations, guardrails, media inputs, exception mapping, and contract compatibility.

• Chores

  • Added safety hooks, formatting/guard scripts, dependency/install utilities, release tooling, and repo housekeeping.