commandkit/docs/roadmap/implementation.md

Implement PromptKit comparison and catalogs

Status: Stages 1–7 complete; remaining stages are planned.

Scope and authority

This plan implements the accepted PromptKit feature roadmap. That roadmap owns the target state and product choices; this document assigns work needed to reach it. Baseline: CommandKit commit 20e19b9. ConfigKit comparison is complete, ckprompt uses PromptKit v0.12.0, and PromptKit comparison and catalogs are not yet exposed.

Read development orientation and applicable policies, including agent discipline, architecture, testing, documentation ownership, OSS, and release policy. The accepted ADRs linked from the feature roadmap govern declaration capture, scope capabilities, and paired inputs.

CommandKit exposes capabilities owned by PromptKit and ConfigKit. It owns CLI access and presentation, not a replacement definition of comparison or catalog membership. Dependencies remain ckprompt to ckconfig and core. This sprint needs no core API, backend, general registry, or additional module.

The repository is an unreleased alpha with no downstream consumers. Give the prototype shape no compatibility preference: choose straightforward private helpers and refactor existing ones where useful. Preserve deliberately selected contracts, not incidental implementation details. No compatibility wrappers, migration period, or buildable intermediate commits are required. The final assembled end state must build and pass relevant validation.

Execute the stages

• Follow stages in order. Each stage is one bounded Luna assignment; inspect its linked owners and current code before editing.
• Scope changes to that stage and necessary integration repairs. Reuse existing paths rather than copying parser, comparison, or delivery infrastructure.
• Format changed Go files and add focused behavioral evidence as assigned. Validation instructions apply during implementation, not this planning pass. Use existing fast native fixtures; no model-provider access is needed.
• Add completion evidence under each completed stage: changes, checks actually run, results, and validation deferred until a later stage. Do not mark the adoption complete before its assembled behavior works.
• Commit completed nonempty units with plain English messages under the agent policy. Do not create empty commits, publish releases, or push changes.
• Existing tests asserting that PromptKit comparison is unavailable become obsolete intentionally. Replace them in their assigned stage; do not add temporary behavior to preserve that expectation.

Target	Primary stages
PromptKit v0.14.0 and real dependency metadata	1, 11, 12
Side diagnostics and native configuration comparison	2–4
Optional native catalog providers	5
Catalog YAML presentation and command invocation	6–8
Maintained consumer and canonical documentation	9–10
Notices, prepared notes, and complete validation	11–12

Stage 1: Adopt PromptKit and prepare module validation

Outcome: ckprompt selects PromptKit v0.14.0 using real upstream metadata, and the sprint has a usable local validation setup.

Steps

1. Upgrade integrations/ckprompt/go.mod from PromptKit v0.12.0 to v0.14.0, pinned by the feature roadmap to upstream commit 143c6e9b3a675872117b0471e2ff8bcb25055a54. Reconcile legitimate indirect requirements and real checksums using Go tooling against the released module.
2. Retain Go 1.26.0, ConfigKit v0.7.1, and existing independent CommandKit prerequisites: core v0.2.0 and ckconfig v0.1.0. Core's declared ReleaseKit v0.4.0 tool/launcher stays unchanged; integration graphs may select v0.4.1 through upstream dependencies.
3. Preserve an existing ignored go.work; ensure it includes core, ckconfig, and ckprompt. Commit neither workspace files nor sibling replacements.
4. Establish workspace-off checks using disposable copies of each integration's module file and accompanying sum file in a temporary directory (go.mod and go.sum, so -modfile finds the matching sums). Replace only unpublished CommandKit prerequisites: core for ckconfig, and core plus ckconfig for ckprompt. Resolve PromptKit and ConfigKit at real released versions. Keep disposable files outside the tracked distribution.
5. If tidying a disposable module file, transfer legitimate requirements and sums back without temporary replacements. Invent no sums for unpublished modules; workspace selection is not evidence of an independently declared graph.

Validation and handoff

Run the existing ckprompt suite against the upgrade before adding capabilities. List the isolated module graph to confirm PromptKit v0.14.0 and ConfigKit v0.7.1. Record baseline failures, and repair genuine upgrade regressions. The composed negative PromptKit diff test remains valid until Stage 3 enables the capability; its replacement belongs to Stage 9.

For isolated test/list checks after preparing the disposable files, use GOWORK=off GOTOOLCHAIN=local, -modfile=<disposable module file>, and -mod=readonly. This proves local-source compatibility, not future tag availability. The reviewed maintainer toolchain is Go 1.26.8; do not raise the consumer minimum to that patch version.

Completion evidence (2026-10-12)

• Updated ckprompt to PromptKit v0.14.0. go mod download -json confirmed the release tag resolves to the roadmap's pinned source commit 143c6e9b3a675872117b0471e2ff8bcb25055a54; Go tooling supplied the module checksums. Go 1.26.0, ConfigKit v0.7.1, and the existing CommandKit module requirements remain unchanged. No additional indirect requirements were needed, and the ignored workspace remains unchanged.
• Workspace-off go test ./... passed for both ckprompt and ckconfig with GOWORK=off GOTOOLCHAIN=local, -mod=readonly, temporary module/sum pairs, and local replacements only for unpublished CommandKit prerequisites.
• GOTOOLCHAIN=local go test ./... passed in integrations/ckprompt with the workspace. The isolated ckprompt graph selected PromptKit v0.14.0 and ConfigKit v0.7.1; the isolated ckconfig graph selected ConfigKit v0.7.1 and contained no PromptKit module. The existing composed negative diff test passed; there were no baseline failures.
• Full repository and final assembled-state validation remain assigned to Stage 12.

Stage 2: Make engine diagnostics reusable for paired acquisition

Outcome: private engine acquisition retains completed diagnostics and can identify comparison sides without duplicating native loading logic.

Starting points: loadPromptKitEngine and promptKitDiagnostics in integrations/ckprompt/adapters.go; acquisition and deferred-diagnostic tests in adapters_test.go.

Steps

1. Refactor the private helper to support ordinary and comparison-side diagnostic headings. Keep the existing ordinary scope heading; comparison headings identify scope promptkit and left/right. A private heading parameter/helper is sufficient; add no public diagnostic API.
2. Continue adapting configkit.LoadError sources and records while preserving supported error identity. Retain the nil-engine operational failure and ordinary configuration inspection facets.
3. After a successful engine load, obtain its captured configuration inspection and adapt its diagnostics before honoring cancellation observed after the load. The current helper returns too early and loses those diagnostics. Return collected diagnostics with the cancellation error, without starting a later side or delivering a report.
4. Retain deferred writers, severity conversion, and the metadata copies needed by those writers. Each side's native source IDs must remain associated with its own source legend.
5. Preserve ordinary public callbacks and successful reports. Reuse this helper in following stages; do not promise interruption inside synchronous inspection or transactional output.

Validation and handoff

Extend adapter tests with a loader that returns an engine with inspection warnings and cancels before returning. Observe cancellation identity and retained warnings. Check ordinary headings and deferred-writer error propagation. Create native diagnostic fixtures through public APIs; do not import upstream internals or assert exact cancellation polling counts.

Completion evidence (2026-10-12)

• Refactored the private engine loader to collect inspection diagnostics before checking cancellation observed after a successful load. Diagnostic headings retain the ordinary scope form and can identify a comparison side. ConfigKit load diagnostics and the original load error remain available.
• Added adapter coverage for post-load cancellation, ConfigKit load-error identity and diagnostics, ordinary and comparison-side headings, and deferred-writer error propagation. GOTOOLCHAIN=local go test ./... passed in integrations/ckprompt.
• PromptKit v0.14.0 provides no public warning callback in engine configuration, and its native configuration path emits no warnings. Therefore a successful engine with inspection warnings cannot be constructed through the public API; native warning retention across cancellation remains unexercised. The ordering change directly retains any diagnostics if a later PromptKit version supplies them. The selected integration evidence is otherwise complete.
• Full repository and final assembled-state validation remain assigned to Stage 12.

Stage 3: Add the bundled PromptKit configuration pair provider

Outcome: ConfigScope advertises Diff and supplies a native provider usable by ckconfig's existing paired-input command and report path.

Starting points: ConfigScope in ckprompt's adapters.go, and public ckconfig.Scope, ComparisonRequest, and the existing ConfigKit adapter.

Steps

1. Add ckconfig.Diff to the bundled operations and supply Compare with the existing request/state signature, returning commandkit.Acquired[[]configkit.Difference].
2. Use already prepared left/right selections and inputs. Load left then right with the same supplied S, obtain both ConfigurationInspection views through Stage 2's helper, and call native left.Diff(right).
3. Accumulate reached-side diagnostics in order. Keep left diagnostics if right acquisition fails and both sides' diagnostics if comparison fails. Add scope, side, or comparison context through supported error wrapping, preserving errors.Is/errors.As behavior.
4. Check cancellation at operation boundaries before reaching the next loader or comparison, retaining completed diagnostics. Equal selections do not skip reached loader calls; application caches determine whether engines are reused.
5. Keep ordinary Acquire and facets. Retain nil-loader construction errors even when operations are narrowed or cleared. Callers may still replace Compare or narrow capabilities before declaration capture.

Validation and handoff

Use two fast real engines with different captured configurations, comparing the adapter's native records with the upstream result. Cover equal selections reaching both calls, correct side inputs/shared state, left failure stopping right, right failure retaining left diagnostics, and cancellation retaining completed side diagnostics. Exercise reachable native failures without adding a public comparator injection hook solely for tests. Add no reconstructed configuration model or duplicate ckprompt comparison renderer.

Completion evidence (2026-10-12)

• ConfigScope now declares ckconfig.Diff and supplies a pair callback that loads left then right with each side's selection/input and the shared state, collects diagnostics in order, checks cancellation at operation boundaries, and returns PromptKit's native ConfigurationInspection.Diff records. Ordinary acquisition and the retained nil-loader issue remain available.
• Added fast native-engine adapter coverage for the PromptKit result, equal selections reaching both loader calls, side inputs/shared state, left failure stopping right, right ConfigKit load diagnostics and error identity, and cancellation stopping before right load. GOTOOLCHAIN=local go test -count=1 . passed in integrations/ckprompt.
• PromptKit v0.14.0 exposes no public way to add successful inspection warnings, and valid engine-derived inspection views do not expose a reachable native Diff failure. Therefore successful left-side warning retention on right failure, both-side warning retention on native failure, and a native Diff failure are not exercisable without adding a test-only injection path. The implementation accumulates reached diagnostics and preserves error causes; these limits remain recorded alongside Stage 2's warning-retention limitation.
• Installed-command verification and the composed consumer's obsolete negative comparison expectation remain for Stages 4 and 9 respectively.

Stage 4: Verify comparison through installed config commands

Outcome: the adapter works through public assembly, existing typed-input preparation, and existing YAML report delivery.

Starting points: ckprompt external composition tests and ckconfig comparison coverage. New integration behavior belongs in ckprompt; retain generic coverage with its current owner.

Steps

1. Install ckconfig.Command with a real ckprompt.ConfigScope and an app scope for default-scope evidence; invoke config diff --scope promptkit through a public commandkit.App.
2. Demonstrate left/right selection, omitted right inheritance, and a supplied empty override. Apply one original captured domain selector to both separately prepared inputs, finish both checks before shared state, and observe received loader values. Reuse generic ckconfig preparation tests for unrelated cases.
3. Decode the report using the existing additions/changes/deletions schema; demonstrate meaningful native changes and successful comparisons with differences. Bare diff still defaults to app, and comparison with scope all remains unsupported.
4. Check help/discovery reflects a narrowed operation set and that help, version, and scope discovery acquire no engines. Clearing Diff leaves other declared scope operations usable.
5. Verify diagnostics/error identity through an installed failure path. Reuse generic delivery-failure coverage unless the integration exposes a distinct gap; do not copy the comparator, parser matrix, or renderer test suite.

Validation and handoff

Run focused ckprompt comparison tests. The composed example's obsolete negative expectation is knowingly pending Stage 9; do not report the whole suite as passing while it remains. Keep assertions on semantic reports and supported outcomes, not exact diagnostic snapshots or private layout.

Completion evidence (2026-10-12)

• Added external-package integration coverage that installs ckconfig.Command with the real ckprompt.ConfigScope, an app scope, and a public commandkit.App. It compares two native PromptKit engines and decodes the existing additions/changes/deletions YAML report, including a meaningful change.
• Verified explicit left/right selection, omitted-right inheritance, and a supplied empty right override. The same captured campaign selector reaches separately prepared left/right inputs; both checks finish before shared state creation, and the provider receives those inputs and state.
• Confirmed bare diff uses the app scope, scope all is rejected before engine loading, installed ConfigKit failure preserves its LoadError identity and left-side diagnostic heading, and help/version/scope discovery do not load an engine. Narrowed discovery lists only enabled operations, and Show remains usable after Diff is cleared.
• GOTOOLCHAIN=local go test -count=1 . passed in integrations/ckprompt. The composed example's obsolete negative expectation remains assigned to Stage 9; no full-module pass is claimed here.

Stage 5: Add optional catalog providers to the public suite

Outcome: either catalog can be supplied independently, and FromEngine provides both using PromptKit's native APIs.

Starting points: Suite and FromEngine in integrations/ckprompt/adapters.go.

Steps

1. Add the accepted fields to Suite[I, S] exactly as selected:

   ListPrompts func(context.Context, ckconfig.Selection, I, S) (commandkit.Acquired[[]promptkit.PromptIdentity], error)
   ListProfiles func(context.Context, ckconfig.Selection, I, S) (commandkit.Acquired[[]string], error)
   

2. Update declaration comments for catalogs and named inspection. Document optional callbacks and retain existing input/state zero-value and check timing contracts. Add no catalog request wrapper.

3. Extend FromEngine to supply both callbacks alongside its named-inspection callbacks. Acquire only when reached, then call Engine.ListPrompts(ctx) or Engine.ListProfiles(ctx) through the public API.

4. Return native identities/order with acquisition diagnostics and supported error identity. Use Stage 2's ordinary-heading acquisition helper. Do not derive catalogs from YAML or perform named inspection/readiness loops.

5. Keep nil-loader issues attached even when callers clear all four operations. This stage changes providers; family assembly follows in Stage 7.

Validation and handoff

Use real engines and their public listing results as the native oracle. Cover selection/input/state forwarding, load diagnostics/errors, and cancellation. Retain named-inspection tests. Custom empty catalogs and presentation belong to Stage 8; do not retest PromptKit's complete membership semantics.

Completion evidence (2026-10-12)

• Added the selected optional ListPrompts and ListProfiles callbacks to ckprompt.Suite with the accepted signatures, and updated its declaration and FromEngine documentation to cover catalogs alongside named inspection.
• FromEngine now loads an engine only when a catalog callback is reached, delegates to PromptKit's native ListPrompts and ListProfiles, and returns the native ordered results with acquisition diagnostics.
• Adapter tests compare both results with the same engine's public native methods and cover context/selection/input/state forwarding, ConfigKit load diagnostic and error identity retention, cancellation after loading, and a nil-loader issue after all four callbacks are cleared. Existing named inspection coverage remains in place.
• GOTOOLCHAIN=local go test -count=1 . passed in integrations/ckprompt. Family assembly and catalog presentation remain assigned to Stages 7 and 8.

Stage 6: Implement the catalog YAML representation

Outcome: small private helpers encode the explicitly selected CLI schema.

Starting points: ckprompt's existing YAML/buffered report helpers in command.go.

Steps

1. Define a private prompt catalog entry with explicit yaml:"id" and yaml:"version" string fields, without omitempty, populated from native PromptIdentity values. Upstream struct serialization does not define the CLI schema.
2. Encode one bare entry sequence for prompts and a bare string sequence for profiles. Preserve provider order and exact strings, including duplicates, whitespace, and numeric-looking versions. Let the YAML encoder quote values.
3. Normalize both nil and allocated empty successful slices to an empty sequence rendered as [], not null. Named-inspection nil-pointer failure handling does not apply to successful catalog slices.
4. Prepare the full encoded bytes before output; Stage 7 reuses existing delivery. Add no public report type or generic resource serialization framework.

Validation and handoff

Review the mapping to the accepted schema. Add command-boundary schema evidence in Stage 8 once helpers are wired. Test decoded types, fields, sequence order, and empty inventories; incidental quoting style, private names, and indentation are not new contracts.

Completion evidence (2026-10-12)

• Added private YAML encoders that map native prompt identities to entries with explicit string id and version fields and encode profile IDs as a bare string sequence. Both return fully prepared bytes using the existing YAML encoder; nil and allocated empty catalogs normalize to empty sequences.
• Unit coverage decodes prompt entries and profile values to check field names, string types, order, duplicates, whitespace, and numeric-looking values. Nil and allocated empty inputs both encode as [].
• GOTOOLCHAIN=local go test -count=1 . passed in integrations/ckprompt. Command-boundary schema coverage remains assigned to Stage 8; command wiring and delivery remain assigned to Stage 7.

Stage 7: Assemble and execute independent catalog commands

Outcome: catalog commands and optional named-show commands share existing capture, input preparation, acquisition, and outcome mechanics.

Starting points: Command, newDefinitionCommand, prepareDefinitionInput, and runDefinitionInspection in ckprompt; writePromptReport and definitionFailure.

Steps

1. Return absence only when all four operation callbacks are nil. Retain attached construction errors before skipping absence. Valid absence claims no namespace; a nonempty family retains root-only installation/collision behavior.
2. Generate show only with supplied named-inspection operations and list only with supplied catalog operations. Generate list prompts and list profiles independently. Empty intermediate groups/help entries vanish.
3. Capture selector metadata and callback references when Command is called. Use CaptureFlags and original handles for ApplyTo, not a second parser, internal setters, or backend objects.
4. Catalogs accept presence-aware config/overlay selection and suite selectors, no operands, version selector, or scope selector. Default --format to yaml; accept only yaml here. Preserve named-show formats/defaults.
5. Check format before runtime acquisition. Reuse or straightforwardly generalize private input preparation: create one suite I, apply captured converted selectors once, then call CheckInput(selection, input).
6. After checks, when reached, initialize one suite S and invoke only the selected provider. Nil factories supply zero values including nil pointers. Do not repair caller aliases or allocate arbitrary pointer types; preserve core-owned parsed collection independence.
7. Retain diagnostics on provider, cancellation, encoding, and delivery errors; check cancellation at existing operation boundaries. Successful nil/empty catalogs use Stage 6's empty-sequence path.
8. Finish encoding before delivery; reuse writePromptReport for failures, short writes, and incomplete-report fields. Preserve usage/operational classifications and supported error identity. Caller effects remain theirs.

Validation and handoff

Compile and exercise custom prompts-only/profiles-only suites. Check a successful catalog, invalid format stopping before factories, and catalog-only help omitting show. Stage 8 completes evidence. No new core public API should be necessary.

Completion evidence (2026-10-12)

• Command now builds show and list independently, omits absent families, retains construction issues when all four callbacks are cleared, and captures the caller's selectors when the command is created. Catalog commands expose config, overlay, selectors, and YAML format without named-show arguments.
• Catalog invocation checks format before suite input preparation, applies captured selectors once, checks the prepared input, then creates one state and calls only the selected provider. It retains diagnostics through provider and cancellation failures, encodes before output, and reuses existing report delivery behavior.
• Added focused command coverage for prompts-only and profiles-only help, catalog-only omission of show, successful preparation and provider input, and invalid-format preflight before suite factories/providers.
• GOTOOLCHAIN=local go test -count=1 . passed in integrations/ckprompt. Complete lifecycle, YAML schema, cancellation, and delivery-failure coverage remains assigned to Stage 8.

Stage 8: Complete catalog invocation and presentation coverage

Outcome: observable catalog contracts have focused coverage without freezing private organization or repeating upstream suites.

Starting points: ckprompt command_test.go, external composition_test.go, and existing fake writers/public declaration helpers.

Steps

1. Cover independent callbacks, catalog-only/show-only/mixed trees, and valid absence. Extend installation coverage only for distinct new risks. Confirm nil-loader errors remain after all four callbacks are cleared.
2. Observe construction, installation, help, and version invoking no suite factories/providers. Help with supplied flags still performs normal conversion.
3. Cover one input/state per reached invocation, checks before state/provider, failed preflight/check preventing acquisition, nil-factory zero values, and original selector identity/presence. Include representative supplied empty/false/zero and repeatable values, plus a second run without leaked values. Assert received data and selected lifecycle events, not private storage.
4. Decode custom-provider reports: explicit prompt id/version strings, profile strings, no envelope, exact values/order, and nil/allocated-empty inventories. Include numeric-looking versions, YAML-sensitive identifiers, and deliberately unsorted entries to detect command-side reordering.
5. Check default/explicit YAML, unsupported format, and unwanted operands. Core parsing owns unknown version/scope flags; add no special rejection parser.
6. Cover provider errors with diagnostics, cancellation after a completed provider preventing delivery, writer errors, and short writes. Observe supported error identity, classification, diagnostics, and incomplete delivery fields. Reuse existing diagnostic-writer coverage.

Validation and handoff

Run focused catalog and existing named-show tests through assembled public commands. Native membership belongs to Stage 5. Add no provider network access, benchmark thresholds, concurrency guarantees, or general fixture framework.

Stage 9: Demonstrate capabilities in the composed consumer

Outcome: the maintained example exercises both features through bundled adapters, without duplicated application command infrastructure.

Starting points: integrations/ckprompt/examples/composed/main.go, tests, fixtures, and README.

Steps

1. Keep ConfigScope(loadPromptEngine) and FromEngine(loadPromptEngine); their new defaults provide comparison and catalogs. Do not reproduce commands.
2. Demonstrate PromptKit-scope diff using the existing before/after fixtures and campaign selection through the selection-aware application loader. Adjust a small fixture only if needed for meaningful native evidence.
3. Replace TestPromptKitScopeDoesNotSupportConfigurationDiff with a positive public invocation test decoding a meaningful YAML change. Retain app comparison and cache tests distinguishing selection and supplied campaign identity.
4. Add both catalog invocations with campaign/config selection and native identities. Check relevant entries without pinning the entire maintained upstream inventory. No requirement inspection or readiness loop is added.
5. Update the example README with copyable diff/catalog/named-show commands. Preserve session restore and scope-specific domain checks. Example cache choices are recommendations/evidence, not policy for consuming applications.

Validation and handoff

Run example tests and the complete ckprompt suite. Existing ordinary scope operations, named reports, app comparison, and the domain command must work with the upgraded dependency.

Stage 10: Reconcile canonical documentation and capability status

Outcome: current documentation describes delivered behavior and separates completed adoption from deferred requirement inspection.

Steps

1. Update ckprompt declarations/GoDoc and doc.go for providers, defaults, narrowing, and preparation. Exact public contracts belong there. Review the module/root READMEs for accurate orientation.
2. Update the CLI reference for both catalogs, selectors, YAML default/schema, empty inventories, and PromptKit diff availability through the existing comparison section. Keep named-show formats and comparison rules.
3. Update consumer guidance, internal overview, and development examples. Explain all four FromEngine callbacks and ConfigScope's Diff plus ordinary operations. Show narrowing before capture; link maintained examples for full code rather than adding another complete prose example.
4. Replace claims of absent PromptKit comparison/catalogs. Reconcile the completed configkit.md summary and deferred.md; keep a standard InspectRequirements command deferred without inventing syntax or adding it to validation/show.
5. Review architecture/ADRs for consistency; existing decisions authorize this work. Do not revise durable records merely to duplicate fields/report details. Report any actual authority conflict instead of strengthening policy silently.
6. Record the feature roadmap's delivered status, with final validation evidence in Stage 12. Preserve previous implementation history links; do not restart completed ConfigKit work.

Validation and handoff

Review diffs, links/fragments, examples, and stale statements; run documented Markdown whitespace checks. Describe native semantics as upstream-owned. Do not promise arbitrary catalog/provider data is safe for public disclosure.

Stage 11: Reconcile notices and prepared release notes

Outcome: distributed metadata/notices match actual graphs, and unpublished integration notes describe delivered capabilities.

Steps

1. Reconcile final ckprompt requirements/sums with Stage 1's isolated procedure. Review other manifests for accidental workspace-induced changes. No committed local replacements or invented prerequisite sums.
2. Update integrations/ckprompt/docs/oss/attribution.md to PromptKit v0.14.0 with the roadmap's pinned source. Review upstream grant, license, notices, and selected direct/transitive graph; change copied texts/entries where required.
3. Keep notice ownership module-local. Core notices describe its declared ReleaseKit v0.4.0 tool; integration selection of v0.4.1 does not alter that declaration. Preserve project grants and source-pinned links.
4. Confirm integrations/ckprompt/docs/releases/v0.1.0.md is still prepared and unpublished before editing. Describe PromptKit v0.14.0, native engine-scope diff, both catalogs, and optional selection. Remove its obsolete no-diff claim.
5. Follow independent versioning and the existing release procedure. Do not mirror upstream versions, manufacture tags, or publish. Published notes remain immutable: if release state changed, prepare the next appropriate unpublished note rather than rewriting a published one.

Validation and handoff

Check graph/notice consistency, pinned links, required texts, and module-local release/attribution URLs. Validate prose using existing procedures. No publication exercise or new release gate is needed for this adoption sprint.

Stage 12: Validate the complete end state and finish

Outcome: features work together, distribution boundaries remain intact, and completion evidence matches checks actually performed.

Steps

1. Format changed Go files. With the ignored workspace, run go test ./... in core, ckconfig, and ckprompt separately; root traversal misses nested modules. Include maintained consumer tests in their owning module suites.

2. Run core tests with GOWORK=off GOTOOLCHAIN=local and -mod=readonly. Run integration suites likewise with their disposable module/sum files and only the unpublished CommandKit replacements from Stage 1. Use go list -m all for each isolated selected graph and go list -deps -test ./... for imported dependencies, with the same environment/module-file flags as its test run.

3. Confirm ckprompt selects PromptKit v0.14.0 and ConfigKit v0.7.1; ckconfig selects ConfigKit without ckprompt/PromptKit. Core has no optional integration or owning-library dependency through production, tests, examples, or tools. Distinguish root and integration release-tool selections.

4. From the composed example directory exercise representative invocations:

   go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml
   go run . promptkit list prompts --campaign spring
   go run . promptkit list profiles --campaign spring --format yaml
   go run . promptkit show prompt briefing --campaign spring --format yaml
   go run . session restore session-42 --campaign spring
   

   Retain representative app diff and ordinary multi-scope inspection checks from that example. Inspect YAML semantically; external services are unnecessary.

5. Audit every roadmap target against code, tests, docs, and notices. Resolve implementation defects; report environmental limits honestly rather than declaring unrun checks successful. If required validation remains blocked, record it as pending rather than marking that check or the sprint complete.

6. Add final completion evidence here and in promptkit.md. Keep requirement inspection deferred. Review documentation links/whitespace and final status, then commit the completed nonempty unit.

Completion criteria

• Native captured PromptKit comparison uses ckconfig's existing paired preparation and YAML delivery path, preserving reached diagnostics and error identity.
• Independent catalogs preserve native identities, render the accepted YAML, and follow selected preparation, cancellation, diagnostic, and delivery behavior.
• Optional groups, absence, narrowing, and construction errors follow existing installation contracts; named-show behavior remains available.
• Relevant module suites, consumers, and isolated graph/import checks pass; any external validation limits are recorded as pending work.
• Metadata, notices, prepared notes, and canonical docs match implemented behavior. No workspace files, local replacements, unrelated changes, or publication form part of the sprint.

All product/API decisions needed for this plan are settled; no open questions remain.