Record checklist for preparing the initial feature roadmap

docs/roadmap/initial-plan.md

@@ -0,0 +1,200 @@
+# Preparing the initial CommandKit feature roadmap
+
+Status: agreed drafting process; checklist work pending.
+
+Date: 2026-10-07.
+
+## Purpose and use
+
+Use this checklist to prepare `docs/roadmap/initial.md`, which will describe the
+targeted end state of CommandKit's initial implementation: its packages, features,
+integration contracts, and ownership boundaries. After reviewing that roadmap,
+use it to prepare a separate, ordered implementation plan for a Luna agent.
+
+Work through the sections below in order. Check an item when its result is
+recorded in the draft or its supporting planning notes. Record unresolved choices
+with a recommendation, alternatives, and the decision needed. Revisit earlier
+sections when later evidence affects their conclusions.
+
+The [architecture policy](../policy/architecture.md) and accepted ADRs control
+architectural choices. This document owns the preparation process; `initial.md`
+will own the initial feature targets. Exact implemented contracts will belong in
+Go declarations, GoDoc, and the CLI reference under the
+[documentation policy](../policy/documentation.md).
+
+## 1. Establish authoritative requirements
+
+- [ ] Review all nine accepted ADRs and the architecture policy.
+- [ ] Build a requirements checklist linking each requirement to its authority.
+- [ ] Review the four numbered roadmaps as evidence and design proposals:
+  [CLI plan](01-cli-plan.md), [dispatcher](02-dispatch.md),
+  [backend](03-backend.md), and [facade](04-facade.md).
+- [ ] Identify conflicts with accepted decisions and carry the controlling choice
+  into the new roadmap.
+- [ ] Distinguish accepted requirements, remaining design choices, and proposed
+  delivery scope. Approval of this drafting process leaves those design choices
+  to be resolved during roadmap preparation.
+
+Use these ADR owners for traceability:
+
+| Topic | Authority |
+| --- | --- |
+| Dispatch, registration, typed inputs, and consumer boundaries | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) |
+| Initial backend and invocation state | [ADR 0002](../adr/0002-cobra-backend.md) |
+| Public facade and internal adapter | [ADR 0003](../adr/0003-public-facade.md) |
+| Standard operations and capability-based availability | [ADR 0004](../adr/0004-standard-inspection-surface.md) |
+| Outcomes, streams, and diagnostic delivery | [ADR 0005](../adr/0005-invocation-outcomes.md) |
+| Grammar and vocabulary guidance | [ADR 0006](../adr/0006-command-grammar.md) |
+| Native YAML and combined display | [ADR 0007](../adr/0007-native-yaml-reports.md) |
+| Semantic comparison and sensitivity gaps | [ADR 0008](../adr/0008-semantic-configuration-diff.md) |
+| Scopes, supported operations, and selection defaults | [ADR 0009](../adr/0009-configuration-scopes.md) |
+
+Confirm these known differences from older planning material:
+
+- Singleton flags use the last occurrence; repeatable flags accumulate in order.
+- Configuration operations, including validation, default to `app`.
+- Straightforward implementation may live in the root package.
+- Providers can expose subsets of inspection capabilities.
+- Loading all selected views before output is specifically a `config show`
+  requirement; other operations define their own output timing.
+
+**Result:** a traceable requirements checklist and a reconciliation of older
+planning assumptions.
+
+## 2. Select a concrete package layout
+
+Evaluate this starting recommendation:
+
+| Package | Target responsibilities |
+| --- | --- |
+| Root `commandkit` | Public API; instance registry; command groups; typed bindings and presence; invocation coordination; outcomes; standard handlers; scope metadata; ConfigKit/PromptKit integration contracts; report composition. Straightforward unexported implementation can live here. |
+| `internal/cobra` | Translate backend-neutral declarations into Cobra/pflag machinery; implement parsing and help mechanics; maintain independent invocation state; translate backend-owned failures. |
+
+- [ ] Define each package's purpose, owned features, inputs, outputs, dependencies,
+  and extension points.
+- [ ] Describe the boundary between the root and adapter, including how declarations
+  and callbacks cross it while retaining supported value and error semantics.
+- [ ] Keep Cobra/pflag types and operations confined to the internal adapter and
+  retain root-owned public named types.
+- [ ] Evaluate whether comparison or inspection code warrants another cohesive
+  internal package, using concrete implementation and integration needs.
+- [ ] Settle package placement during roadmap preparation so the later plan gives
+  Luna a defined target layout.
+- [ ] Keep package structure proportionate to the actual responsibilities under
+  the architecture and agent policies.
+
+**Result:** a target package inventory and dependency/ownership map.
+
+## 3. Define the initial feature inventory
+
+Organize the inventory around these feature groups:
+
+| Group | Features to evaluate |
+| --- | --- |
+| Command infrastructure | Construction, registration, groups, ownership checks, typed inputs, presence, repetition, operands, help, and invocation. |
+| Identity and outcomes | Application/component version reporting, classifications, supported error identity, streams, and delivery failures. |
+| Configuration inspection | Scopes, validation, native display, combined display, sources, explanation, and semantic comparison. |
+| PromptKit inspection | Configuration scope, prompt/profile catalogs, and definition inspection. |
+| Consumer integration | Lazy acquisition, selector applicability, upstream public types, and application-owned callbacks. |
+
+- [ ] Assign stable feature identifiers for later implementation-plan traceability.
+- [ ] For each feature, specify its observable result, package owner, provider
+  requirements, dependencies, and completion evidence.
+- [ ] Describe CommandKit behavior and provider result contracts separately from
+  recommended consumer practices.
+- [ ] Build an upstream capability matrix from current supported ConfigKit and
+  PromptKit public APIs, recording the inspected revisions or versions.
+- [ ] Identify which capabilities are available now and which need upstream work.
+- [ ] For each missing capability, recommend including the upstream work or
+  explicitly deferring that feature, with the reason and affected targets.
+- [ ] Settle initial delivery scope before preparing the ordered implementation
+  plan. Missing capabilities leave independently supported operations available.
+
+**Result:** feature specifications and an explicit initial delivery scope with its
+upstream dependencies and deferrals.
+
+## 4. Evaluate existing code for reuse
+
+Begin with these review candidates:
+
+- [Notarius configuration commands](../../../notarius/internal/cli/configkit_commands.go):
+  native effective configuration and explanation integration.
+- [Scriptorium inspection commands](../../../scriptorium/internal/adapter/cli/inspect.go):
+  PromptKit inspection acquisition and report preparation.
+
+Expand to other consumers where their implementations provide useful evidence.
+Use the repository's code-discovery workflow when locating and tracing code.
+
+- [ ] Identify reusable logic and the behavior it supplies.
+- [ ] Separate it from application-specific acquisition, schemas, domain resolution,
+  parsers, names, statuses, and formats.
+- [ ] Evaluate the candidate against the accepted CommandKit contracts and the
+  selected feature target.
+- [ ] For each proposed port, record the source revision, relevant symbols/files,
+  adaptation work, and dependencies.
+- [ ] Verify applicable licensing and attribution treatment under the
+  [OSS policy](../policy/oss.md) before copying material.
+- [ ] Identify reusable examples or fixtures that demonstrate meaningful behavior.
+- [ ] Use representative simple and complex consumer examples to evaluate whether
+  the proposed API removes repeated infrastructure and remains practical to wire.
+
+Sibling checkout links are review references. CommandKit implementation and
+consumer examples use supported published APIs and module dependencies.
+
+**Result:** a reuse assessment and representative integration examples, with
+provenance and adaptation requirements for proposed ports.
+
+## 5. Resolve implementation choices explicitly
+
+- [ ] Recommend construction, registration, command-group, and typed-binding API
+  shapes, including presence-aware inputs.
+- [ ] Select narrow provider representations against concrete integration needs,
+  reusing upstream public types where useful.
+- [ ] Define acquisition lifetime and any justified dependency coordination or
+  result reuse, with callback ownership clear.
+- [ ] Specify configuration and context selectors and their applicability.
+- [ ] Define diagnostic presentation responsibility and delivery-failure handling.
+- [ ] Select report formats, framing, and schemas for the included operations.
+- [ ] Define comparison selection inputs for included diff capabilities.
+- [ ] Select the module baseline and supported dependency versions using the
+  applicable policies and current dependency requirements.
+- [ ] For viable alternatives, record a recommendation and a short analysis of
+  each alternative.
+- [ ] Resolve choices that would otherwise require Luna to invent public behavior
+  or package boundaries while following the implementation plan.
+
+API shapes in planning remain design targets until implemented. Go declarations
+and GoDoc will own the exact exported contracts. Significant changes to accepted
+architecture follow the ADR process in the documentation policy.
+
+**Result:** a coherent design with remaining decisions explicitly tracked and
+resolved to the depth needed by the later implementation plan.
+
+## 6. Define completion and prepare the handoff
+
+- [ ] Define observable completion criteria for each included feature.
+- [ ] Cover supported commands, capability discovery, native YAML preservation,
+  outcomes, backend isolation, and representative public API usage.
+- [ ] Identify proportionate evidence under the [testing policy](../policy/testing.md),
+  prioritizing real adapter behavior and the supported public consumer boundary.
+- [ ] Identify documentation and attribution deliverables as their corresponding
+  implementation lands.
+- [ ] Review the complete draft against its requirements checklist and package map.
+- [ ] Make upstream work, deferrals, and unresolved decisions visible in the draft.
+- [ ] Review the targeted end state before translating it into implementation tasks.
+- [ ] Prepare the subsequent staged plan with ordered tasks, prerequisites, precise
+  deliverables, and completion checks mapped to the roadmap's feature identifiers.
+
+**Result:** a reviewed feature roadmap that can be translated into a strictly
+ordered implementation plan suitable for Luna.
+
+## Recommended outline for `initial.md`
+
+1. Authority and initial scope.
+2. Target package layout and dependencies.
+3. Public API and integration model.
+4. Feature specifications by package.
+5. Ownership boundaries.
+6. Upstream dependencies and reuse candidates.
+7. Explicit deferrals.
+8. Completion criteria.