# v0.5.0 Observability Plan

## Goal
Turn `v0.4.0`'s unattended dogfood milestone into an operator-trust milestone.

`v0.4.0` proved Tutti can execute an end-to-end SDLC loop without intervention.
`v0.5.0` should make those runs inspectable, explainable, and debuggable while
shipping the first usable local web dashboard for operator workflows.

## Why this release
- `tt runs` and the SDLC ledger already provide a run-history baseline.
- `status` / `watch` now classify agent health states consistently.
- `observe.dashboard` / `observe.port` are parsed today but not acted on.
- The remaining product gap is not "more autonomy"; it is operator visibility
  into what happened, where a run failed, and what to do next.

## Release thesis
Ship the minimum viable observability layer and first local web dashboard that
let an operator answer:
1. What is running right now?
2. What happened in the last run?
3. Where did it fail?
4. Was the failure caused by routing, runtime, policy, tooling, or provider state?
5. What exact step or agent should I inspect or retry?

## In scope

### 1. Run timeline and stage history
- Persist step-level start, finish, duration, and outcome data for workflow runs.
- Distinguish planned, running, succeeded, failed, skipped, and resumed stages.
- Surface the data in CLI output first; keep the storage model API-ready.

### 2. Failure attribution
- Add a stable failure taxonomy for operator-facing summaries.
- Attribute failures to categories such as `routing`, `runtime`, `tool`,
  `policy`, `provider`, `config`, and `unknown`.
- Include a short failure message plus the nearest actionable hint.

### 3. Queryable run and event history
- Extend local run history beyond coarse ledger rows so operators can inspect a
  single run without reading log files manually.
- Expose the history through machine-readable CLI output and local API surfaces.

### 4. Local web dashboard
- Convert `observe.dashboard`, `observe.port`, and related state into an actual
  local web dashboard instead of parsed-but-unused config.
- Ship a minimal browser-based operator view backed by first-class run,
  failure, and agent state.
- Keep this local-first and intentionally narrow rather than drifting into a
  hosted control plane.

### 5. Operator workflow polish
- Make it obvious from `tt status`, `tt watch`, `tt runs`, and `tt verify --last`
  how to jump from a failing run to the responsible agent, logs, or retry path.

## Explicit non-goals
- Multi-user identity, API keys, or RBAC.
- Hosted control-plane deployment.
- Full provider failover orchestration.
- Billing, forecasting, or commercial analytics.
- A polished hosted dashboard product beyond what is needed to validate the
  operator workflow locally.

## Release deliverables
1. Step-level run timeline persisted in local state.
2. Stable failure attribution model used by run summaries.
3. `tt runs` expansion for inspecting one run in detail.
4. Local API read endpoints for run/event inspection.
5. Minimal local web dashboard wired to real data.
6. Docs for the operator debugging loop.

## CLI and API targets

### CLI
- `tt runs` should support detailed inspection of a single run.
- `tt status` / `tt watch` should show current stage plus last failure cause.
- `tt verify --last` should include failure attribution when present.

### API
- Read-only endpoints or equivalent surfaces for runs, stages, and latest
  failure state.
- Event payloads should be idempotent, stable, and safe to consume from a local
  dashboard.

### Dashboard
- A browser-based local operator view should render current agent state, active
  runs, recent failures, and run timelines from first-class data.
- The first version can be read-mostly, but it should be usable enough to
  replace ad hoc log-hunting for the common debugging loop.

## Acceptance criteria
- An operator can identify the failing workflow step and agent for the latest
  run without opening raw transcript logs.
- An operator can distinguish between provider, policy, tool, and config
  failures from structured output alone.
- A local UI or API consumer can render a run timeline using first-class data
  instead of regexing terminal output.
- A local browser dashboard can show the current state of agents and recent
  runs without requiring transcript inspection.
- Existing unattended workflows remain backward-compatible.

## Release risks
- Scope creep into full control-plane work.
- Overfitting the failure taxonomy to current runtimes.
- Building a dashboard before the event/run model is stable.

## Release sequence
1. Persist the missing timeline and attribution data.
2. Surface it in CLI and JSON output.
3. Expose read endpoints for local consumers.
4. Add the first local web dashboard.
5. Document the failure-debugging loop.
