commandkit/docs/roadmap/implementation.md

# Implement PromptKit comparison and catalogs

Status: Stages 1–12 complete.

## Scope and authority

This plan implements the accepted [PromptKit feature roadmap](promptkit.md).
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](../development.md) and applicable policies,
including [agent discipline](../policy/agents.md),
[architecture](../policy/architecture.md), [testing](../policy/testing.md),
[documentation ownership](../policy/documentation.md), [OSS](../policy/oss.md),
and [release policy](../policy/release.md). 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:

   ```go
   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.

**Completion evidence (2026-10-12)**

- Expanded assembled-command coverage for independent prompts/profiles, mixed
  show/list trees, catalog-only help, existing show-only and valid-absence
  behavior, and nil-loader errors after all four callbacks are cleared.
- Verified construction, installation, help, and version do not invoke suite
  factories or providers. Help with a supplied selector still converts it.
  Invocation tests observe one input and state after checks, usage rejection
  before acquisition, nil-factory zero values, original selector capture,
  supplied empty/false/zero/repeated values, and fresh values on a second run.
- Decoded command output to verify prompt `id`/`version` string fields, profile
  string sequences, no envelope, exact values and order, default and explicit
  YAML, and `[]` for nil and allocated-empty inventories. Extra operands and
  unavailable version/scope flags fail as usage without reaching providers.
- Covered provider error identity and diagnostics, cancellation after provider
  completion preventing output, report writer errors, and short writes with
  incomplete-report state and retained diagnostics.
- Focused assembled catalog/named-show tests and the complete ckprompt package
  suite passed with `GOTOOLCHAIN=local go test -count=1`.

## 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.

**Completion evidence (2026-10-12)**

- Replaced the obsolete negative PromptKit diff test with a public composed-app
  invocation that compares the before/after fixtures using the spring selector
  and decodes the native change under the spring profile. Updated the after
  fixture's spring model to make that comparison meaningful. The application
  diff test still checks the changed default and now also checks the model value
  under an explicit spring override.
- Added composed public invocations for both catalogs with config and campaign
  selection. Tests decode the YAML and find the configured `briefing` version
  and selected `autumn` profile without pinning PromptKit's full catalog.
- Updated the example README with copyable PromptKit diff/catalog commands and
  described how the selection-aware loader and sample cache behave. Existing
  ordinary scope operations, named reports, app comparison/cache behavior, and
  session command coverage remain in place.
- `GOTOOLCHAIN=local go test -count=1 .` passed in the composed example, and
  `GOTOOLCHAIN=local go test -count=1 ./...` passed in `integrations/ckprompt`.

## 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](../cli.md) 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](../consumers/guide.md),
   [internal overview](../internal/overview.md), 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.

**Completion evidence (2026-10-12)**

- Updated ckprompt GoDoc for native configuration comparison, all four optional
  callbacks, callback narrowing, selector/input preparation, nil-factory zero
  values, and catalog YAML defaults. Root and module READMEs now describe the
  shipped integration.
- Updated the CLI reference for PromptKit `config diff` and independent prompt
  and profile catalogs, including selectors, YAML schema/default, empty results,
  and the owning-library boundary for comparison and catalog membership. It
  leaves catalog data disclosure with the application/provider.
- Updated consumer guidance with a narrowing-before-capture example, the
  internal package overview, and development commands. The PromptKit roadmap now
  records delivered behavior; the ConfigKit roadmap summary reflects the later
  PromptKit adoption; and `deferred.md` retains only requirement inspection as a
  PromptKit capability deferred from this feature.
- Reviewed the architecture policy and ADRs 0004 and 0008–0012. They remain
  consistent with the delivered ownership and invocation model; no decision
  record changes were needed. Historical baseline and ConfigKit completion
  records remain clearly scoped to their original work.
- Markdown whitespace checks passed. A local-link and fragment check passed for
  all ten changed Markdown files. Composed example behavior was exercised and
  passed with Stage 9's example and complete ckprompt suite checks.

## 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.

**Completion evidence (2026-10-12)**

- The workspace graph selected PromptKit v0.14.0, ConfigKit v0.7.1,
  ReleaseKit v0.4.1, and `golang.org/x/tools` v0.49.0. PromptKit's Go module
  origin confirms tag v0.14.0 resolves to the roadmap-pinned commit
  `143c6e9b3a675872117b0471e2ff8bcb25055a54`. The graph's Go tools module
  origin confirms v0.49.0 resolves to `18332fec72972efbb8ab9881984fec2d8cfc2b58`.
- Updated ckprompt attribution to the selected PromptKit release and source.
  Inspected its released module's grant and LGPL license text; its copyright and
  grant are unchanged, and it contains no separate NOTICE file. Reconciled the
  stale Go tools attribution and included its applicable PATENTS notice. The
  core ReleaseKit v0.4.0 declaration and notices remain unchanged; ckprompt's
  graph selects v0.4.1. No module manifests or sums changed during workspace use.
- Updated the prepared ckprompt v0.1.0 note for native PromptKit comparison,
  prompt/profile catalogs, named inspection, and callback narrowing, removing
  the obsolete claim that PromptKit scopes lack comparison. The user confirmed
  both ckprompt and ckconfig v0.1.0 tags are unpublished, so the prepared note
  was eligible for revision. No release was published and no tag was changed.
- `GOTOOLCHAIN=local go list -m all` reported the graph above. `go mod download
  -json` confirmed both pinned origins. Local Markdown link targets in the two
  changed files exist, and `git diff --check -- '*.md' COPYRIGHT` passed.
- Stage 12's isolated graph audit found that the distributed ckprompt graph
  selects `golang.org/x/tools` v0.6.0 through `golang.org/x/text` v0.14.0;
  v0.49.0 was only selected in the broader workspace graph. The attribution
  now follows the isolated graph and its v0.6.0 source.
- Complete repository, consumer, and isolated graph/import validation is
  recorded in Stage 12 below.

## 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:

   ```sh
   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.

**Completion evidence (2026-10-12)**

- `GOTOOLCHAIN=local go test ./...` passed for core, ckconfig, and ckprompt with
  the local workspace. The root module includes its core example, backend, and
  release-tool packages; each integration suite includes its maintained
  consumer example.
- Workspace-off results for core and ckconfig used `GOWORK=off
  GOTOOLCHAIN=local` and `-mod=readonly`; isolated module and package/import
  enumeration also passed. The original ckprompt result did not establish
  compatibility with its committed manifest: review finding
  [R-5](remediation.md#r-5-validate-the-committed-ckprompt-manifest-without-an-extra-test-only-yaml-api)
  found a test-only YAML v3 import requiring additional manifest tidying.
- After the R-5 import repair, fresh copied ckprompt manifests passed
  `go test -count=1 ./...`, `go list -m all`, and `go list -deps -test ./...`
  with `GOWORK=off GOTOOLCHAIN=local` and `-mod=readonly` on Go 1.26.8. These
  copies added only temporary replacements for unpublished core/ckconfig
  prerequisites, were not tidied, and retained their exact manifest/sum bytes
  throughout validation. Distributed metadata needed no changes. The results
  prove compatibility with local prerequisite sources, not future tag
  availability.
- The isolated ckprompt graph selects PromptKit v0.14.0 and ConfigKit v0.7.1;
  ckconfig selects ConfigKit v0.7.1 without ckprompt or PromptKit. Core imports
  neither optional integration nor ConfigKit/PromptKit through production,
  tests, examples, or tools. Core declares ReleaseKit v0.4.0, while both
  integration graphs select v0.4.1. The isolated ckprompt graph selects
  `golang.org/x/tools` v0.6.0 through `golang.org/x/text` v0.14.0; its notice
  now follows that graph rather than the broader workspace selection.
- All seven composed example commands passed: PromptKit comparison, app
  comparison, prompt and profile catalogs, named prompt inspection, session
  restore, and ordinary multi-scope validation. The YAML output showed the
  fixture's native PromptKit additions/change/deletion, exact catalog values,
  and named prompt fields; the session command returned its synthetic session.
  No external service was used.
- Audited the completed target against implementation, focused tests, canonical
  docs, examples, and module-local notices. Requirement inspection remains
  deferred. The Stage 2 limitation remains recorded: PromptKit v0.14.0 exposes
  no public path to produce successful engine inspection warnings, so native
  warning retention could not be exercised.
- `git diff --check -- '*.md' COPYRIGHT` and the local Markdown link check for
  changed documentation passed. No workspace files, replacements, or module
  graph artifacts are tracked; no release was published or tagged.