Skip to content

GA blocker: remove all deprecated commands, compatibility code, and legacy documentation #83

Description

@pacphi

Goal

Before the 4.0 GA release, remove every deprecated command, compatibility alias, legacy function, and superseded implementation approach. Each supported capability must have one stable, documented forward path; no deprecated runtime surface may ship in GA.

GA policy

  • ak run is the sole stable execution surface. It is host-neutral and is the only path for explicit OpenCode execution.
  • AQE remains provider-axis only. OpenCode is never an AQE provider, primary host, or vendor-diversity fact.
  • A deprecated alias, wrapper, compatibility export, persisted compatibility shape, or legacy approach must be either migrated to a stable replacement or removed. Keeping it because it is convenient is out of scope for GA.

Required inventory and disposition

  • Produce a complete, reviewed inventory of active deprecated commands, aliases, compatibility exports, legacy functions, persisted legacy fields, generated templates, tests, and user documentation. Classify each as migrate, remove, or deliberately retained historical record.
  • Remove ak dual and all supporting dispatch, command, adapter, temporary-config, escalation-wrapper, test, and documentation paths after required behavior is migrated into ak run or explicitly retired.
  • Remove ak provider and ak x provider aliases after their stable ak host equivalents and migration coverage are complete.
  • Migrate every retained public behavior to one stable command/surface before deletion. This includes templates, route overrides, concurrency, timeouts, JSON output, escalation semantics, and error contracts; do not silently drop behavior.
  • Replace providers.dualRouting and any other persisted compatibility name with a GA-appropriate canonical envelope. Provide deterministic one-way migration that preserves user routes, models, escalation intent, and provenance.
  • Remove dead compatibility projections, helper functions, source modules, package dependencies, configuration writers, and test fixtures after consumers migrate.
  • Remove all active user-facing documentation, CLI help, generated guidance-template, and example references to deprecated commands or legacy approaches. Historical ADR/archive material may retain context only when clearly marked historical and excluded from active guidance.
  • Update upgrading/release guidance with one concise GA migration path, then remove it from ordinary operational documentation.

Verification and acceptance criteria

  • A clean GA install exposes only stable commands and no deprecation warnings. Removed commands fail as unknown commands.
  • Repository-wide checks verify no active source imports, dispatches, or executes a removed compatibility path.
  • A documentation/help guard fails if active user documentation, generated guidance, or CLI help reintroduces a removed command or legacy approach.
  • Migrated configuration preserves user-pinned routes, models, escalation intent, and provenance without duplicating old and new state.
  • ak run owns the migrated execution behavior and retains OpenCode safety boundaries.
  • pnpm run check passes, including migration, negative-command, and documentation-guard coverage.
  • GA release notes document the breaking changes and stable replacements.

Dependencies

This is a pre-GA milestone task. It follows the OpenCode routability work in #76. The cleanup must preserve the established safety boundary: OpenCode is opt-in and supervised through ak run, while AQE remains provider-only.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions