# Integration dependency alignment

Status: proposed release-preparation roadmap. This pass adds documentation only;
dependency changes and publication remain future work.

## Purpose and authority

Align the independently released integrations with the core APIs their current
source already uses. Publish compatible module versions in dependency order so
each integration builds and validates against its declared, downloaded
dependencies with workspace discovery off.

The [release procedure](../release.md) owns publication commands and release
order. The [release policy](../policy/release.md),
[agent policy](../policy/agents.md), [testing policy](../policy/testing.md),
[documentation policy](../policy/documentation.md), and
[OSS policy](../policy/oss.md) govern the work. This roadmap selects the target
and release-preparation scope; it does not change those policies.

## Baseline and investigation evidence

Reviewed baseline: `289a171e97699ad9aa57ee2cc40bdad1c0b680a9`.

- Both integration module declarations require core v0.2.0. The
  [ckprompt declaration](../../integrations/ckprompt/go.mod) also requires
  ckconfig v0.1.0; the [ckconfig declaration](../../integrations/ckconfig/go.mod)
  has no dependency on ckprompt.
- Current integration source uses newer core APIs including `CompletionHint`,
  `Explanation`, and `Reporter`. Both independent Go 1.26.8 suites fail to
  compile with `GOWORK=off` and their existing read-only module graphs.
- Updating core alone is insufficient for ckprompt: published ckconfig v0.1.0
  still uses removed core APIs, including `Invocation.Streams`,
  `Outcome.Diagnostics`, and `SeverityError`, plus the old `Failure(error)`
  call shape.
- The authoritative `origin` tag listing contains core v0.1.0 and v0.2.0, and
  the two integration v0.1.0 tags. The proposed next versions below were unused
  at review. Remote `main` was `230187296fae5253cb1773f16c2f1d1a39499ed0`;
  the reviewed local changes still need normal publication to the authoritative
  branch as part of candidate preparation.
- A checked-in [core v0.3.0 draft](../releases/v0.3.0.md) already describes the
  reporting and alias migration. It is an unpublished draft, not proof that
  the module version can be downloaded.

The investigation used disposable alternate module files, Go 1.26.8,
`GOWORK=off`, and read-only offline tests. Only temporary dependency selections
changed; the real module declarations, sums, and source remained unchanged.

| Current source under test | Temporary dependency selection | Result |
| --- | --- | --- |
| ckconfig | Current core source | Module suite and maintained example passed. |
| ckprompt | Current core source, published ckconfig v0.1.0 | Compilation failed in the old ckconfig implementation. |
| ckprompt | Current core and current ckconfig source | Module suite and maintained example passed. |

The successful cases retained ConfigKit v0.8.0 and PromptKit v0.16.0. These
results isolate the CommandKit dependency alignment needed here; they do not
prove that future published versions or their downloaded sums already exist.

## Targeted end state

### Compatible independently released modules

Use the following proposed next versions, subject to the existing fresh-version
publication guards:

| Module | Next release | Required CommandKit dependencies | Full tag |
| --- | --- | --- | --- |
| Core | v0.3.0 | None | `v0.3.0` |
| ckconfig | v0.2.0 | Core v0.3.0 | `integrations/ckconfig/v0.2.0` |
| ckprompt | v0.2.0 | Core v0.3.0 and ckconfig v0.2.0 | `integrations/ckprompt/v0.2.0` |

Minor integration releases fit the existing pre-1.0 compatibility policy: the
reporting migration changes consumer-facing behavior and adopts a core version
with incompatible API changes. Migration notes explain the impact on provider
results, invocation reporting, and consuming applications.

The three modules retain independent versions and source tags. Their candidates
may identify successive commits: core publication need not wait for integration
metadata that depends on that newly published core. Each selected module's
final release suite runs against its actual declared dependencies.

### Retained architecture and scope

Keep the current library APIs and integration adapters, Go 1.26.0 consumer
minimum, Go 1.26.8 maintainer toolchain, and root-selected ReleaseKit v0.9.0.
The successful diagnostic suites indicate dependency selection is sufficient;
this work selects no API rollback or compatibility shim for old reporting APIs.

Retain ConfigKit v0.8.0, PromptKit v0.16.0, and other dependency selections
unless ordinary tidy changes the resolved graph as a consequence of the
CommandKit updates. Inspect and explain the resulting graph rather than
bundling unrelated upgrades. In particular, transitive tools with different
module paths may coexist; attribution must reflect the actual selection.

Preserve the existing launchers, three release profiles, generic validators,
credential handling, and separate source-publication and hosted-delivery
outcomes. Development workspaces remain useful and ignored. Diagnostic local
replacements and the earlier temporary Go shim remain development evidence;
release validation uses normal downloaded dependencies without that redirection.

## Work needed

### Prepare and release core

Review the v0.3.0 draft against changes since the published v0.2.0 tag, including
completion, invocation reporting, aliases, and release-tool maintenance. Bring
its summary, migration guidance, and immutable source/licensing links into line
with the final candidate and current release procedure. Keep published notes
and tags unchanged.

Prepare and commit the intended core candidate on `main`, then use the existing
source-publication workflow to publish v0.3.0. Preserve the procedure's required
candidate-commit publication before tag publication. The root suite covers the
root module; the still-pending integration alignment is separate work.

### Align and release ckconfig

After core v0.3.0 is published, update ckconfig's core requirement to that version
and prepare dependencies with workspace discovery off. Tidy its module metadata
and retain authentic sums from actual downloads. No future checksum or local
replacement substitutes for the published dependency.

Prepare `integrations/ckconfig/docs/releases/v0.2.0.md`, documenting the new core
requirement and reporting/completion behavior relevant to consumers. Update
affected current guidance and module-local attribution from the actual resolved
graph, including immutable notice links. Validate and publish the selected
ckconfig candidate through the ordinary module release workflow.

### Align and release ckprompt

After ckconfig v0.2.0 is published, update ckprompt's direct requirements to core
v0.3.0 and ckconfig v0.2.0 together. Prepare downloaded dependencies and tidy
with workspace discovery off. Retain real sums and inspect indirect changes.

Prepare `integrations/ckprompt/docs/releases/v0.2.0.md`, covering the compatible
dependency set and consumer migration. Align current guidance and module-local
attribution with that selection. Validate and publish its candidate through the
ordinary module release workflow.

### Record the aligned result

Record the selected versions, candidate revisions, validation outcomes, and
source-publication outcomes separately for all three modules. Update current
dependency-readiness statements that still describe this mismatch as unresolved;
preserve historical baseline failures in completed review and implementation
records. Link future implementation tracking here without restarting the
completed ReleaseKit adoption or remediation work.

## Validation and completion boundaries

Use the selected module's ordinary deterministic offline suite with
`GOWORK=off` and read-only metadata after dependency preparation. Its maintained
consumer compiles and runs with that suite. ReleaseKit's publication command
owns the final candidate suite and selected file checks; validation-only checks
remain optional diagnostics. Reuse successful evidence for unchanged candidates
instead of adding a required check-then-publish repetition.

Retrieving a newly published dependency is preparation for the next module's
release. It does not turn proxy availability or consumer installation into a
completion gate for the preceding source release. Continue to resolve failed
or ambiguous publication using the existing policy and upstream recovery flow.
Hosted Gitea delivery keeps its separate outcome; this roadmap adds no CI
polling, live provider calls, or additional publication gate.

Alignment is complete when the matched source versions are published, each
integration declares the compatible versions with authentic downloaded sums,
each final selected-module suite passes without workspace or replacement
redirection, and its current documentation and attribution agree with that
graph. Temporary local-source success alone does not establish that end state.