Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0056: Adopt a canonical-only compatibility boundary

Status: accepted | Date: 2026-07-25

Tags: cli, editing, schema, migration

References: ADR-0037, ADR-0030, ADR-0034, RFC-0002, RFC-0006, RFC-0002:C-COMPATIBILITY-BOUNDARY, RFC-0002:C-CRUD-VERBS, RFC-0006:C-LOOP-STATE-STORAGE, ADR-0047

Context

ADR-0037 established canonical path-oriented edit while retaining shorthand verbs during migration. ADR-0030 selected strict full-input path parsing while retaining aliases and wire-layout prefixes. ADR-0034 selected canonical TOML with a migration boundary, and ADR-0047 removed journal from the editable Work Item surface while allowing historical rendering. These transitional policies now duplicate command documentation, expand agent choice, preserve silent input tolerance, and require broad compatibility tests. The governing constraints are the canonical resource contract in RFC-0002:C-CRUD-VERBS, the explicit schema-3 boundary and safety diagnostics in RFC-0002:C-COMPATIBILITY-BOUNDARY, the loop-state model in RFC-0006:C-LOOP-STATE-STORAGE, and preservation of conforming governance history.

Decision

We will adopt one canonical-only compatibility boundary in the breaking release because:

  1. One migration event lets automation move directly to the retained interface instead of crossing several temporary states.
  2. CLI help, describe metadata, skills, guides, and tests can describe one mutation grammar and one repository baseline.
  3. Compatibility code can be removed rather than carried through another deprecation cycle.

This decision supplies the rationale for RFC-0002:C-COMPATIBILITY-BOUNDARY; that RFC clause owns the exact accepted syntax, schema baseline, migration eligibility, and diagnostics. We preserve the canonical edit direction from ADR-0037, strict full-input parsing from ADR-0030, canonical TOML from ADR-0034, and the loop-centric Work Item boundary from ADR-0047. We end only their transitional compatibility policies: sibling mutation-verb sugar, path aliases and wire-layout prefixes, pre-baseline migration branches, and legacy inline-journal rendering.

Consequences

Positive

  • CLI help, describe metadata, skills, guides, and tests converge on one mutation grammar.
  • Repository loading and migration have one documented support baseline.
  • Compatibility normalization and silent-tolerance branches leave the runtime instead of remaining permanent maintenance obligations.

Negative

  • Existing scripts using aliases, sibling mutation verbs, or resource-specific shortcuts require coordinated updates. The breaking-release notes provide command translations.
  • Repositories below the RFC-defined schema baseline require an earlier compatible govctl version before upgrading. The unsupported-schema diagnostic identifies that prerequisite.
  • Legacy inline Work Item journal data is not retained by the new binary. Users must export any history they need with a compatible earlier version before crossing the boundary.

Neutral

  • Canonical edit semantics, strict path parsing, TOML storage, loop-centric execution state, released changelog content, and conforming historical artifacts remain in force.
  • The RFC, rather than this ADR, defines the exact external contract and schema version.

Alternatives Considered

Keep all existing compatibility surfaces indefinitely (rejected)

  • Pros: Avoids breaking existing scripts and old repositories
  • Cons: Preserves duplicated CLI and storage paths without an end state
  • Rejected because: Indefinite compatibility conflicts with the goal of a small canonical interface and keeps migration complexity in every future release

Remove compatibility surfaces gradually across several releases (rejected)

  • Pros: Spreads user migration work over time
  • Cons: Extends the period where every authoring surface must explain two grammars and multiple storage generations
  • Rejected because: A coordinated breaking release gives users one explicit migration event and lets implementation, documentation, and tests converge atomically

Adopt one canonical-only boundary in the breaking release (accepted)

  • Pros: Leaves one mutation grammar and one supported repository baseline, Allows help, describe metadata, skills, docs, and tests to teach the same interface
  • Cons: Requires users to update scripts and migrate older repositories before upgrading