[Roadmap] Conversational deterministic workflows and portable goal loops

## Overview

CAO workflows should let a user describe deterministic work to one agent, have
that agent produce and validate a saved workflow, approve the resolved plan,
run it, and reuse it whenever needed.

The user should not need to choose YAML versus Python or know whether a provider
implements `/goal`, `/loop`, or another native command. CAO should resolve and
freeze those decisions before execution.

## Problem

The execution substrate largely exists: CAO supports saved Python and YAML
artifacts, validation, typed inputs, durable run identifiers, status, results,
cancellation, and resume.

The pieces do not yet form one consistent product experience:

- conversational authoring is taught by a skill rather than exposed as a
complete cross-provider flow;
- Python resume re-executes completed `run_step` calls instead of replaying
their journaled results;
- provider-native goal and loop commands can be sent as prompt text but are not
capability-tested, normalized, or resolved by CAO;
- failure evidence and Python outputs are not yet complete enough to guarantee
efficient repair by a later agent; and
- YAML remains the more reliable recovery path even though Python is the
stronger format for agent-authored control flow.

## Product Principles

- A workflow provides deterministic control through a reviewed and frozen
artifact. Provider output may remain nondeterministic.
- "On demand" and "recurring" are invocation choices, not different workflow
types.
- Python is the primary format generated by authoring agents.
- Existing sequential YAML workflows remain supported, but new YAML loop,
branch, and parallel features are not part of this roadmap.
- Resume re-drives a frozen run after a transient failure.
- Repair changes the artifact and starts a new run.
- Agents own diagnosis and repair; CAO owns durable evidence and execution.
- Provider, model, native command or fallback, limits, completion checks, and
failure policy must be resolved and frozen before approval.
- Retry and resume must never silently re-resolve provider capabilities.

## User Stories

- As a user, I want to describe a multi-step process to one agent so that I do
not need to learn workflow syntax.
- As a user, I want to rerun the saved workflow whenever needed, regardless of
whether it is invoked manually, by schedule, or by an event.
- As a user, I want CAO to select a tested provider-native goal or loop command
when available and generate a bounded Python fallback otherwise.
- As a user, I want a failed workflow to retain enough evidence for any capable
agent to resume it or repair the artifact.
- As an operator, I want resume to skip completed Python work so that recovery
does not duplicate cost or side effects.

## Target Experience

```text
describe intent
-> agent authors a Python workflow
-> CAO resolves provider and native capabilities
-> validate the resolved artifact
-> explain steps, limits, and known limitations
-> user approves
-> run and observe
-> resume a transient failure, or repair and start a new run
-> retain the artifact for later invocation
```

## Roadmap

### Milestone 0: Replay-safe Python resume

- [ ] Connect completed script calls to the journal replay lookup.
- [ ] Return journaled results for matching completed calls without launching a
new terminal.
- [ ] Fail loudly when a stable step identifier has a different call
fingerprint on replay.
- [ ] Cover sequential and looped Python resume end to end.
- [ ] Verify recovery does not duplicate completed side effects.
- [ ] Correct documentation that currently overstates Python replay behavior.

### Milestone 1: Portable provider-native goal loops

- [ ] Define an explicit `goal_loop` intent with goal, completion condition,
provider policy, and hard budget.
- [ ] Define a tested provider capability contract covering supported versions,
command rendering, status, completion, cancellation, output extraction,
background work, and known limitations.
- [ ] Inventory Kiro CLI, Claude Code, Codex, and other target providers.
- [ ] Prove at least one native adapter through CAO's real terminal transport.
- [ ] Generate a bounded Python fallback for a provider without native support.
- [ ] Show and freeze provider, model, command or fallback, limits, completion
checks, retry policy, and resolution rationale before approval.
- [ ] Disable automatic retry by default for opaque native loops.
- [ ] Return a consistent outer status and termination summary from native and
Python strategies.

### Milestone 2: First-class conversational authoring

- [ ] Define one cross-provider authoring contract for creating and changing
workflows.
- [ ] Add the minimum definition operations needed for an agent to create,
validate, inspect, and replace workflows consistently.
- [ ] Default to Python without asking the user to select an artifact format.
- [ ] Present the resolved execution plan and request approval before running.
- [ ] Observe the durable result and classify failures as resume or repair.
- [ ] Validate the experience with a staged product-build workflow.
- [ ] Validate the experience with the existing PR review workflow.
- [ ] Validate the experience with the existing PR health and scoring workflow.

### Milestone 3: Durable diagnostics and Python parity

- [ ] Retain enough provider, model, profile, input, prompt or fingerprint,
terminal, error, output, and frozen-source information for a later agent
to diagnose a failed run.
- [ ] Make Python structured outputs durable and consistently retrievable.
- [ ] Retain Python run-level output beyond the live blocking response.
- [ ] Define the parity gate that must pass before YAML retirement is
reconsidered.

## Acceptance Criteria

- A user can explicitly ask one agent to build a workflow without selecting
YAML, Python, or provider-specific commands.
- The agent produces a validated Python artifact and presents the resolved plan
before execution.
- Completed Python calls are replayed rather than executed again during resume.
- One `goal_loop` intent executes through a tested provider-native adapter.
- The same intent executes through a bounded Python fallback on a provider
without native support.
- Unsupported provider versions fail before execution instead of attempting an
unverified slash command.
- Provider selection and capability resolution remain unchanged across retry
and resume.
- A new agent can inspect a failed run and determine whether to resume it or
repair the artifact without access to the original conversation.
- Existing sequential YAML workflows remain functional.

## Validation Signals

- Time and manual intervention from request to validated artifact.
- Time from failed run to successful resume or repaired run.
- Duplicate work or side effects after recovery.
- Native capability detection accuracy by provider and version.
- Native versus Python fallback completion and cancellation rates.
- User overrides of provider selection before approval.
- Completion rate, wall-clock time, and cost within declared budgets.

## Deferred / Non-Goals

- Simulated workflow dry run.
- Autonomous workflow repair or self-modifying execution.
- First-class repair, promotion, rollback, or revision management.
- A workflow revision database.
- A general YAML loop, branch, or parallel engine.
- A general CAO-owned convergence engine.
- A visual workflow editor.
- Removal of existing YAML support before Python reaches recovery and output
parity.

## Open Questions

- Which provider and version combinations expose `/goal`, `/loop`, or
equivalent native behavior?
- Should `goal_loop` support `prefer_native`, `require_native`, and
`require_python` strategies?
- Which completion gates belong in the first portable intent?
- Can each native adapter accept CAO's budget, or only an outer wall-clock
ceiling?
- How should capability probes be cached and invalidated after provider
upgrades?
- Which definition operations must be first-class MCP tools rather than
filesystem and CLI actions performed by the authoring agent?

## Related Work

- #49: Ralph Loop
- #312: deterministic workflows
- #420: Python workflow authoring
- #504: workflow journal and playback
- #505: workflow run discoverability
- #506: bounded convergence loops