Plan shell completion implementation

docs/roadmap/completion.md

@@ -0,0 +1,187 @@
+# Shell completion
+
+Status: initial scope and all four product decisions selected; implementation
+has not started. Provide canonical suggestions with alias-aware interpretation
+for Bash, Zsh, and Fish through explicitly installed completion support.
+
+## Purpose
+
+Provide useful shell completion for core-only applications and applications with
+optional integrations. Reuse installed command declarations and CommandKit's
+routing rules so consumers need little completion-specific wiring.
+
+Completion helps an operator construct an invocation. It does not execute the
+selected application command. Preserve application ownership of runtime behavior
+and upstream ownership of configuration and prompt semantics.
+
+## Current baseline
+
+Reviewed baseline: `2301872` (`Stop flag interpretation at unknown flags`).
+
+- Core captures declarations and builds a routing snapshot containing canonical
+  commands and separate application aliases.
+- [Neutral metadata](../../internal/commandmeta/metadata.go) describes command
+  names, descriptions, flags, boolean/value distinctions, repetition, required
+  flags, and operand cardinality. It has no completion choices or path hints.
+- The [Cobra adapter](../../internal/cobra/parse.go) constructs a backend tree
+  for parsing and help. CommandKit owns execution and presentation outside that
+  tree; enabling Cobra's default completion command alone is insufficient.
+- [Alias routing](../../route.go) resolves complete command paths and coordinates
+  canonical parsing with entered spellings. Completion must also handle partial
+  words and an empty current word.
+- Invocation reporting controls ordinary output and diagnostics. Shell completion
+  queries need machine-readable replies independent of flags in the unfinished
+  command line.
+- The core module uses Cobra v1.10.1 and pflag v1.0.9. Cobra supplies script
+  generators and completion callbacks for Bash, Zsh, Fish, and PowerShell.
+  See its [versioned completion documentation](https://github.com/spf13/cobra/blob/v1.10.1/site/content/completions/_index.md).
+
+[ADR 0013](../adr/0013-application-alias-routing.md) owns the separation between
+alias routes and canonical commands. [ADR 0014](../adr/0014-invocation-reporting.md)
+owns invocation reporting. This roadmap defines completion within those
+boundaries; it does not establish a replacement command model.
+
+## Target experience
+
+An operator generates and loads a shell integration script, then receives
+suggestions for installed commands, applicable canonical flags, and declared
+value choices or paths. The selected script-generation grammar is:
+
+```text
+app completion bash
+app completion zsh
+app completion fish
+```
+
+Consumers explicitly install a core completion declaration through the existing
+installation API. The completion namespace is reserved only when installed.
+Keep the machine query hidden from ordinary help, with collision validation for
+its selected path. Installation must not replace an application-owned command.
+
+Script generation writes to the caller-selected result stream. Shell setup
+instructions explain loading the script; automatic modification of shell startup
+files is outside the initial implementation.
+
+The initial MVP suggests canonical command names and flag spellings. Completed aliases
+already entered by the operator are interpreted to identify the canonical target.
+For example, with `jobs` routing to `workspace jobs`, completing after
+`app jobs ` can suggest the canonical children of `workspace jobs`.
+Completion should preserve the text the operator has already entered.
+
+Matching partial canonical names, resolving completed aliases, and interpreting
+an alias-only discovery prefix are distinct cases. Initially, an alias-only
+prefix with no canonical target offers no command continuations. For example,
+if `legacy inspect` is an alias but `legacy` has no canonical target,
+`app legacy <TAB>` offers no command continuations. After the complete alias is
+entered, completion uses its canonical target. Applicable flag suggestions can
+still follow the existing discovery context.
+
+Suggested continuations must form a valid next step when inserted into the
+entered route. Do not append canonical words that would create an invalid route.
+Alias discovery may be omitted from the initial MVP; this is a scope choice,
+not a permanent limitation of CommandKit. Suggesting alias names or alias-path
+continuations remains [potential future work](deferred.md#alias-completion-and-discovery).
+
+### Flag suggestions
+
+Initially suppress already supplied singleton flags from flag-name suggestions.
+Canonical and aliased occurrences count as the same flag. Keep repeatable flags
+available. Keep all four reporting flags (`--quiet`, `--verbose`, `--debug`, and
+`--progress`) available because later occurrences can intentionally change or
+reset their settings.
+
+Suggestion filtering leaves accepted syntax unchanged. Operators can still type
+singleton flags again under the existing repetition rules. If an operator has
+already entered a repeated flag, continue completing its value according to its
+hint even when its name would have been omitted from suggestions.
+
+## Selected initial scope
+
+Provide canonical command and flag suggestions, descriptions where supported by
+the selected shells, alias-aware interpretation, static value choices, and
+file/directory hints. Apply the same declaration facilities to application-owned
+commands and optional integrations.
+
+Support Bash, Zsh, and Fish using the existing backend generators, with validation
+in each shell. PowerShell is outside the initial supported shell set because
+there is no current consumer need; this does not preclude future support.
+
+Static suggestions should come from captured metadata. Completion should not
+invoke ordinary handlers, input/state factories, or acquisition callbacks to
+obtain it. Application startup and declaration-factory effects remain owned by
+the consumer, just as they do for help.
+
+Dynamic discovery of configured prompt names, remote resources, or other live
+values is a possible later extension. Deferring it avoids selecting provider
+lifetimes and latency behavior before a concrete consumer need; it is not a
+permanent prohibition on dynamic completion.
+
+## Ownership and implementation approach
+
+Core owns completion context, alias interpretation, and neutral suggestions.
+The internal backend adapter owns Cobra-specific types, directives, script
+emission, and protocol details. Prefer the existing backend facilities where
+compatible with CommandKit's grammar. Verify the adapter approach with a small
+end-to-end prototype before fixing private interfaces.
+
+A completion request identifies completed words and the current partial word,
+including an empty word after a space. Interpret only what is needed to locate
+suggestions. Ordinary required-value validation and input conversion must not
+reject a partially constructed invocation before completion can help fill it.
+Reuse token and flag interpretation helpers where practical without changing
+normal execution grammar or treating incomplete input as an executable command.
+
+Account for command-local flags, aliases, consumed values, `--`, attached values,
+boolean assignments, short clusters, repeatable flags, and operand positions.
+Keep provenance sufficient to return a replacement for the word being edited.
+Completion candidates are suggestions, not an additional input validator.
+
+When both an operand and a flag are valid, use the operand's hint for an
+empty current word after a space. Offer flag names when the operator starts
+the word with `-` in a context where flags are accepted.
+
+Value choices and path hints belong in CommandKit-owned public metadata. Carry
+them through declaration capture and neutral metadata to the adapter. Arbitrary
+converter functions cannot reliably reveal their accepted values. Adding a list
+of suggestions must not silently restrict the values a converter accepts.
+
+Provide declarative static choices with optional descriptions, file/directory
+hints, and an explicit way to request no value suggestions. Unannotated values
+default to no value suggestions; applicable commands and flags still complete.
+Filename completion requires a path hint. This keeps unrelated filenames out of
+identifier and numeric completions. The implementation plan specifies how hints
+fit into existing binding declarations.
+
+Initially use one hint strategy per value position: static choices, files,
+directories, or no value suggestions. Optional choice descriptions belong to the
+static-choice strategy. Combined choices and filesystem suggestions can be
+considered later if consumers need them; the initial API need not define their
+merging or deduplication behavior.
+
+Verify the same strategy works for separated and attached flag values, such as
+`app serve --config ./par<TAB>` and `app serve --config=./par<TAB>`. For the
+attached form, preserve `--config=` and complete its value correctly. Validate
+the resulting command line in each supported shell.
+
+Keep ordinary script generation under the existing reporting policy. A hidden
+shell query is a protocol exchange: flags in the command being completed are
+request data, so `--quiet` must not erase its reply and `--debug` must not append
+ordinary diagnostics to it. When an unrecognized or incomplete command line
+leaves no inferable completion context, return a valid empty reply that disables filename fallback. Reserve
+protocol errors for failures in the query itself. Specify their wire behavior
+and output ownership in the implementation plan. A completion request must not
+accidentally run the target command.
+Hidden protocol names are implementation details unless deliberately published.
+
+## Delivery plan
+
+The [implementation plan](implementation.md) owns the sprint sequence, API and
+protocol design, and validation steps. The target includes behavioral coverage
+and shell-level validation through the public consumer path in Bash, Zsh, and
+Fish.
+
+## Deferred scope
+
+Alias discovery remains a potential extension beyond the MVP. Dynamic discovery
+remains deferred until a concrete consumer need justifies its callback,
+cancellation, error-handling, and provider-lifetime design.

docs/roadmap/deferred.md

@@ -25,12 +25,28 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only
 for a concrete consumer need and a deliberate API/behavior decision under the
 relevant ADRs.
 
+### Alias completion and discovery
+
+The [shell-completion roadmap](completion.md) selects an initial MVP with
+canonical suggestions and alias-aware interpretation. Potential future work
+includes suggesting command and flag alias spellings and valid continuations of
+alias-only prefixes. For example, completion could suggest `inspect` after
+`app legacy ` when `legacy inspect` is an installed alias.
+
+Alias discovery may be omitted from the MVP. This deferral does not establish a
+permanent canonical-only completion contract or prohibit future alias discovery.
+A later design should determine how alias suggestions are presented alongside
+canonical suggestions while ensuring inserted continuations form valid next
+steps. No delivery date or final API is selected here.
+
 ## Other deferred proposals
 
 These capabilities remain outside the delivered scope and require a concrete
 operator or consumer need and an appropriate ownership/behavior decision:
 
-- JSON reports, shell completion, and output-file management or reloadable export.
+- JSON reports and output-file management or reloadable export.
+- Shell-completion extensions beyond the initial scope in the
+  [completion roadmap](completion.md), including alias discovery described above.
 - Configuration mutation, generic value assignment, and exhaustive field-origin
   inventories.
 - Credential diagnostics beyond PromptKit's native smoke checks and additional

docs/roadmap/remediation.md

@@ -5,7 +5,7 @@ Status: remediation complete; all 7 findings addressed.
 ## Review scope
 
 Reviewed the reporting implementation from `2a1096b` through `7c035cc` against
-the [feature roadmap](reporting.md), [implementation plan](implementation.md),
+the [feature roadmap](reporting.md), [implementation plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md),
 [ADR 0014](../adr/0014-invocation-reporting.md),
 [ADR 0005](../adr/0005-invocation-outcomes.md), and the
 [architecture policy](../policy/architecture.md).
@@ -214,7 +214,7 @@ that failed before writing and a rejected result write. The corresponding
 reporter and execution tests currently assert this generic text, so they preserve
 the gap rather than the selected distinction.
 
-[Stage 4](implementation.md#stage-4-implement-deferred-delivery-and-finalization)
+[Stage 4](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md#stage-4-implement-deferred-delivery-and-finalization)
 requires a useful core-owned explanation when presentation turns success into
 failure. The roadmap assigns handling of reporting failures to CommandKit and
 distinguishes healthy diagnostic destinations from failed result destinations.

docs/roadmap/reporting.md

@@ -13,7 +13,7 @@ below are also selected. Architectural preparation is complete:
 [ADR 0014](../adr/0014-invocation-reporting.md) is accepted, and the
 [architecture policy](../policy/architecture.md) is aligned. Implementation and
 final validation are complete; Stages 1–20 are complete. The [implementation
-plan](implementation.md) records the stage order and validation evidence.
+plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md) records the stage order and validation evidence.
 
 ## Purpose
 
@@ -872,7 +872,7 @@ and upstream-adapter protections without testing upstream domain correctness.
 GoDoc, CLI documentation, consumer guidance, internal documentation, and release
 notes describe the implemented boundary under their canonical ownership.
 
-The [implementation plan](implementation.md) defines the concrete migration
+The [implementation plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md) defines the concrete migration
 steps, focused validation, and completion criteria. This roadmap defines the
 target behavior and selected policy choices.
 
@@ -887,4 +887,4 @@ target behavior and selected policy choices.
 
 OD-1 through OD-4 and the consumer API signatures are selected. The target end
 state includes maintained, executable consumers using those APIs; the
-[implementation plan](implementation.md) owns their delivery sequence.
+[implementation plan](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/230187296fae5253cb1773f16c2f1d1a39499ed0/docs/roadmap/implementation.md) owns their delivery sequence.