beta-roadmap.md

Alpha-to-beta roadmap

Hecate keeps shipping v0.1.0-alpha.N releases while beta work lands incrementally. Beta is not the next release by default; it is the quality gate after core runtime contracts, view-by-view UX polish, and cleanup/refactoring are complete.

master stays the protected integration and release branch. Beta-scope work happens on feature branches forked from current master, lands through PRs, and is released in alpha tags only after it merges.

Core Runtime First

Area	Beta bar
Error contracts	Hecate-native errors across gateway, model chat, Hecate Chat, External Agent, Tasks, approvals, storage, retention, and provider readiness return stable type values, correct HTTP statuses, trace IDs when available, friendly operator messages, and raw details.
Provider/model readiness	Provider readiness is the canonical setup contract: credential state, discovery state, discovered model count, selected-model validity, route blocking reason, tool capability, pricebook status, last probe/result, and repair action.
Routing explainability	Route reports persist and expose selected route, skipped candidates, skip reasons, failover path, cache path, budget/policy decision, pricebook source, provider latency/error state, and final error.
Task runtime hardening	Queue, lease, running, awaiting approval, approved/rejected, cancelled, failed, completed, retry, resume, stale worker recovery, and shutdown behavior are audited and tested.
Storage and retention	Memory/SQLite parity is verified for providers, chats, tasks, approvals, grants, model capabilities, retention pruning, startup reconcile, and schema migration safety.
OpenTelemetry	Route choice/skip, provider failure, cache hit/miss, task lifecycle, approval lifecycle, chat segment lifecycle, external adapter behavior, retention, rate limits, and readiness probes emit useful spans, metrics, or logs.
Endpoint stability	Hecate-native endpoints stay under /hecate/v1/*; provider-compatible endpoints stay under /v1/*; tests and docs checks prevent old /admin/* and accidental Hecate-native /v1/* routes from returning.

UX By View

View	Beta bar
Chats	Hecate Chat, External Agent, and direct model chat have clear segment boundaries, queued prompts, busy state, task/trace/run links, approvals, markdown/code rendering, run activity grouping, changed-files review, model/tool capability state, stale-model repair, and refresh/resume accuracy.
Providers	Provider setup is self-explanatory: readiness cards, discovered/running/installed states, credential repair, duplicate endpoint handling, route blocking reasons, model discovery failures, local provider discovery, and optimistic edits/deletes where safe.
Tasks	Task Detail is the canonical deep-debug view: clear run timeline, grouped advanced activity, approval cards, stdout/stderr/artifacts, retry/resume/cancel explanations, patch review, and chat-origin links.
Observability	The UI answers "what happened?" without JSON archaeology: request ledger, route report, trace viewer, skipped providers, policy/budget denial, cost calculation, cache path, provider failure, and final outcome.
Settings	Settings stays focused on pricebook, retention, model capability overrides/probes, External Agent readiness/grants, and OTel/export knobs when needed.
Costs	Costs clearly separates enforced gateway cost from adapter-reported usage. External Agent usage remains labelled as reported by adapter and not enforced by Hecate.
Desktop app	Before beta, decide whether unsigned desktop bundles are acceptable. If not, complete signing/notarization or clearly keep desktop labelled alpha while the rest of Hecate enters beta.

Cleanup And Refactoring

• Shared transcript/activity primitives: model chat, Hecate Chat, External Agent chat, and Task Detail converge on one shared transcript/activity component family.
• Canonical readiness model: one provider/model readiness type feeds API, UI, docs, tests, and trace/telemetry labels.
• Task/chat boundaries: Tasks remain canonical for full run history and patch review; Hecate Chat projections stay accurate and linked. One chat can have many historical segments but only one active task-backed loop.
• Docs structure: user docs, runtime/API docs, RFCs, and docs-ai guidance describe the same product and same caveats.
• Remove stale legacy: old endpoint names, old /gateway language, one-binary claims, stale screenshots, obsolete scripts, dead fixtures, and duplicate UI rendering paths are removed.
• Release automation: alpha releases stay boring: docs drift checks, screenshots, links, Docker/native/binary parity, Tauri version stamp, release-doc refresh, and recovery instructions.

Branching And Release Workflow

• Create a feature branch from current master for every beta-scope slice, for example feature/provider-readiness-contracts or refactor/shared-transcript-activity.
• Rebase feature branches onto origin/master before opening or updating PRs.
• Merge only reviewed PRs into master; do not implement beta features directly on master.
• Use direct master commits only for release mechanics or urgent tiny corrections that are explicitly requested, such as version stamps, release-reference docs, or failed-release recovery.
• Cut alpha releases from master after completed PR slices merge and just verify passes.
• Do not create a long-lived beta branch unless beta stabilization later needs a freeze window. Until then, master remains the alpha release train and integration branch.
• The first beta tag should be v0.1.0-beta.1 after the beta gate passes.

Beta Gate

Hecate can move from alpha releases to a beta tag only when all of these are true:

• Runtime errors are stable and friendly across the main surfaces.
• Provider/model readiness can explain and repair common setup failures.
• Routing decisions are inspectable in traces/UI.
• Hecate Chat supports mixed direct/model and tools-on task-backed segments reliably.
• External Agent sessions have approvals, readiness, diagnostics, guardrails, diff inspect/revert, and trusted-subprocess warnings.
• Task runtime lifecycle is tested for approval, cancel, retry/resume, stale worker recovery, and shutdown.
• Memory/SQLite persistence and retention boundaries are tested and documented.
• OTel covers the important runtime decisions.
• UI polish passes are complete for Chats, Providers, Tasks, Observability, and Settings.
• README, known limitations, runtime API docs, release docs, screenshots, and docs-ai guidance all describe the same product.
• Latest alpha release passes just verify, release workflow, links workflow, and desktop release matrix.

Test Plan

Layer	Coverage
Go unit/API tests	Error contracts, provider readiness, route reports, task lifecycle, storage parity, retention, model capabilities, approvals, endpoint namespace checks.
Go e2e tests	Docker startup, OTLP smoke, ACP smoke, approval persistence/reconcile, provider readiness scenarios, task retry/resume/cancel, release-critical startup paths.
UI unit tests	Shared transcript components, friendly errors, readiness cards, chat segment state, queued prompts, approvals, task links, provider repair states.
Playwright e2e	First-run provider onboarding, stale selected model repair, Hecate Chat tools on/off/on, task approval in Chats, refresh during running/awaiting approval, External Agent approval + diff inspect/revert, provider readiness repair, trace/task links.
Release checks	just verify, links, screenshots, Docker image pull/run, release asset presence, Tauri matrix, README release links.

Assumptions

• Alpha releases continue normally while this work is in progress.
• Beta is a quality gate, not a marketing rename for the next release.
• No feature work lands directly on master; work is done in feature branches and merged through PRs.
• No compatibility shims are required for alpha-only endpoint/API changes unless explicitly decided later.
• Hecate remains local-first and single-operator shaped for beta; multi-node and hosted deployments stay out of scope.
• External Agent CLIs remain trusted subprocesses for beta; Hecate supervises and warns, but does not sandbox their internals.