# Tutti v0.2 Leverage Checklist

Goal: make Tutti fully operable by an autonomous external orchestrator (for example, OpenClaw/Wren) without fragile wrappers.

Status (as of 2026-03-14):
- ✅ Item 1 complete
- ✅ Item 2 complete
- ✅ Item 3 complete
- ✅ Item 4 complete
- ✅ Item 5 complete
- ✅ Item 6 complete
- ✅ Item 7 complete
- ✅ Item 8 complete

## Release Gates

- ✅ Beta gate: items 1–4 complete
- ✅ Prod gate: items 1–6 complete
- ✅ Autonomous-at-scale gate: items 1–8 complete

## Tracking Issues (GitHub)

- 1) Native OpenClaw Runtime Adapter: [#2](https://github.com/nutthouse/tutti/issues/2)
- 2) Deterministic Send-Complete Semantics: [#3](https://github.com/nutthouse/tutti/issues/3)
- 3) Full Local Control API: [#4](https://github.com/nutthouse/tutti/issues/4)
- 4) Event Stream (Push): [#5](https://github.com/nutthouse/tutti/issues/5)
- 5) Policy Enforcement Parity Across Runtimes: [#6](https://github.com/nutthouse/tutti/issues/6)
- 6) Reliability Layer (Failover + Retry): [#7](https://github.com/nutthouse/tutti/issues/7)
- 7) Cost/Budget Guardrails: [#8](https://github.com/nutthouse/tutti/issues/8)
- 8) Install/Validation Path for Operators: [#9](https://github.com/nutthouse/tutti/issues/9)

## 1) Native OpenClaw Runtime Adapter

Goal: `tt up` can launch/manage OpenClaw sessions like other runtimes.

Done when:
- `runtime = "openclaw"` works in `tutti.toml`
- `tt up/down/status/send` supports OpenClaw voices
- Session IDs + metadata persist in `.tutti/state/*`
- No wrapper script required for core lifecycle

Issue-sized tasks:
- Add `OpenClawAdapter` to runtime registry with availability check, spawn command, status/auth detection.
- Extend state schema to include OpenClaw-specific session metadata.
- Add adapter-focused unit tests for status/auth heuristics and spawn command construction.
- Add integration smoke for `tt up/down/send` against a mocked OpenClaw CLI.

## 2) Full Local Control API (Beyond Health)

Goal: machine-safe local API for orchestration.

Done when `/v1/*` includes:
- `/status`, `/voices`, `/workflows`, `/runs`, `/logs`, `/handoffs`
- Action endpoints for `up/down/send/run/verify/review/land`
- Consistent JSON envelope: `ok/action/error/data`
- Idempotency key support for mutating actions

Issue-sized tasks:
- Define shared API envelope type and error taxonomy.
- Add read endpoints for status/workflow/runs/logs/handoffs.
- Add action endpoints with idempotency-key persistence under `.tutti/state/api-idempotency.json`.
- Add contract tests for envelope shape and idempotent replays.

## 3) Event Stream (Push)

Goal: orchestration without polling loops.

Done when:
- SSE or WebSocket endpoint emits:
  - `agent.started/stopped/idle/working/auth_failed`
  - `workflow.started/completed/failed`
  - `handoff.generated/applied`
- Each event has `workspace`, `agent`, `timestamp`, `correlation_id`

Issue-sized tasks:
- Introduce event bus module and persisted event log (`.tutti/state/events.jsonl`).
- Emit events from lifecycle/workflow/handoff execution points.
- Add `/v1/events` SSE endpoint with cursor support.
- Add tests for event schema and ordering guarantees.

## 4) Deterministic Send-Complete Semantics

Goal: reliable chaining after `tt send --wait`.

Done when:
- Runtime adapters expose explicit completion signals.
- Timeout/error reasons are structured (`idle_timeout`, `auth_failed`, etc.).
- Heuristic-only detection remains fallback, not primary.

Issue-sized tasks:
- Add adapter capability trait for completion signals.
- Return structured wait outcome payload from `tt send`.
- Keep current pane-delta/idle heuristic as fallback path with explicit reason.
- Add adapter-by-adapter tests for completion and failure reasons.

## 5) Policy Enforcement Parity Across Runtimes

Goal: same safety guarantees for Claude/Codex/Aider/OpenClaw.

Done when:
- Constrained allowlist is enforceable (not prompt-only) for all runtimes.
- Policy decision logs persist per command/action.
- `tt permissions check` mirrors runtime behavior.

Issue-sized tasks:
- Define runtime-agnostic policy decision engine.
- Add per-runtime launch/run wrappers that call the same policy engine.
- Persist policy decisions in `.tutti/state/policy-decisions.jsonl`.
- Add parity tests comparing `tt permissions check` and actual command outcomes.

## 6) Reliability Layer (Failover + Retry)

Goal: unattended operation survives provider issues.

Done when:
- Per-profile retry/backoff policy.
- Automatic profile rotation on auth/rate-limit/provider outage.
- Resumable workflow execution with checkpoint state.

Issue-sized tasks:
- Add retry policy config + executor integration.
- Add profile-rotation strategy module and decision reasons.
- Add workflow checkpointing (`.tutti/state/workflow-checkpoints/<run>.json`).
- Add resume command (`tt run --resume <run-id>`) and tests.

## 7) Cost/Budget Guardrails

Goal: prevent runaway usage autonomously.

Done when:
- Per-agent + per-workspace budget caps.
- Pre-exec budget checks with hard-stop options.
- Alert events before/at threshold breaches.

Issue-sized tasks:
- Add budget config model and defaults.
- Add preflight budget checks for `up/send/run/verify`.
- Emit budget threshold events and persist them.
- Add strict-mode behavior for budget hard stops.

## 8) Install/Validation Path for Operators

Goal: one command proves stack operability.

Done when:
- `tt doctor --strict` validates binaries, permissions, runtime auth, scheduler readiness.
- Each failed check includes explicit fix guidance.
- CI smoke profile exists for headless verification.

Issue-sized tasks:
- Add strict mode to doctor with non-zero on warnings.
- Expand checks for scheduler/event/API readiness and runtime auth state.
- Standardize fix guidance strings for each check.
- Add CI smoke job that runs strict doctor + minimal workflow.

## Suggested Execution Order

1. 1 + 4 together (runtime integration + deterministic send completion)
2. 2 + 3 together (control API + event stream)
3. 5 + 6 (safety parity + resilience)
4. 7 + 8 (budget guardrails + operator hardening)
