RFC: Typed task event catalog with dot-notation names

## Primary area

Cross-cutting / multiple

## Related issue or feature request

- [WORKFLOWS.md](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/design/WORKFLOWS.md) — step milestones (`step::start`)
- [OBSERVABILITY.md](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/design/OBSERVABILITY.md) — TaskEvents audit trail
- [INTERACTIVE_AGENTS.md](https://github.com/aws-samples/sample-autonomous-cloud-coding-agents/blob/main/docs/design/INTERACTIVE_AGENTS.md) — event model

## Summary

TaskEvents today mix typed lifecycle events (`task_created`, `session_started`, `pr_created`) with free-form `agent_milestone` strings (`step:implement:start`, `clone_complete`). This RFC proposes a **canonical event catalog** with lowercase dot-notation names (e.g. `step.started`, `agent.tool.completed`), a stable JSON envelope for event-specific fields, and a documented boundary between **product-facing events** (durable, user-visible) and **tracing logs** (developer diagnostics).

## Use case and motivation

Operators debugging long-running tasks need to filter, aggregate, and export events without parsing ad hoc milestone strings. CLI `bgagent watch`, notification dispatchers, and future eval pipelines all consume TaskEvents; inconsistent naming makes cross-run queries fragile.

## Proposal

### Event naming

Adopt lowercase dot notation. Initial catalog (illustrative): `task.created`, `task.completed`, `step.started`, `step.completed`, `step.failed`, `agent.tool.started`, `agent.tool.completed`, `session.started`.

### Migration

- **Phase 1:** Document catalog; dual-emit legacy `event_type` + new `event` field for one release.
- **Phase 2:** Update `watch.ts`, fan-out dispatchers, and docs to prefer dot notation.
- **Phase 3:** Deprecate free-form milestone strings for step boundaries.

### Tracing boundary

Document in OBSERVABILITY.md: CloudWatch/OTEL traces are for developers; TaskEvents are the operator audit trail.

## Out of scope

- Replacing X-Ray / OTEL span names
- Changing DDB table keys or TTL
- Breaking CLI output in a single release without deprecation period

## Potential challenges

- Tool-level events may increase DDB write rate; may need sampling or opt-in `--trace` mode.
- `watch.ts` and Slack templates need a mapping layer during migration.

## Dependencies and integrations

- `agent/src/progress_writer.py`, `agent/src/workflow/runner.py`, `agent/src/hooks.py`
- `cli/src/commands/watch.ts`, `cdk/src/handlers/`
- Optional: JSON Schema in `contracts/task-events/`

---

**Note:** Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

Empieza por WORKFLOWS.md, OBSERVABILITY.md e INTERACTIVE_AGENTS.md; después inspecciona los productores y consumidores indicados: agent/src/progress_writer.py, agent/src/workflow/runner.py, agent/src/hooks.py y cli/src/commands/watch.ts. Mapea el uso actual de TaskEvents, las milestone strings y watch o dispatcher antes de definir el catálogo. Se considera terminado cuando haya un catálogo de nombres revisado, un envelope estable, un límite entre producto y tracing y un plan de migración.

Escrito por el modelo de indexación a partir del texto del issue.