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.

WORKFLOWS.md、OBSERVABILITY.md、INTERACTIVE_AGENTS.mdから始め、次に列挙されているproducerとconsumerを調査します: agent/src/progress_writer.py、agent/src/workflow/runner.py、agent/src/hooks.py、cli/src/commands/watch.ts。カタログを定義する前に、現在のTaskEvents、milestone strings、watchまたはdispatcherの使用状況を整理します。レビュー済みの命名カタログ、安定したenvelope、productとtracingの境界、および移行計画が揃えば完了です。

索引モデルが issue の本文から書いたものです。