Plan integration dependency alignment

docs/roadmap/integration-dependency-alignment.md

@@ -0,0 +1,168 @@
+# 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.