base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Retire completed shared debug roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-08 15:11:40 +00:00
parent 56e3b013f9
commit 68288ed684
4 changed files with 4 additions and 542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/development.md
View File

@@ -73,7 +73,8 @@ Read all applicable rows for cross-cutting work. Go declarations and GoDoc own
current exported contracts; the CLI reference owns operator behavior. The
[maintainer release procedure](release.md) owns current release operations.
Completed roadmaps and implementation evidence remain available in Git history,
including [audit remediation and its declaration-path follow-up](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap),
including [shared debug binding and reporting-mode implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/56e3b013f9f83c9c9494f11602e802ce5ed8814e/docs/roadmap),
[audit remediation and its declaration-path follow-up](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/aac0e11ae67c78a35745ed9a25688aa51c15e793/docs/roadmap),
[shared reporting and PromptKit v0.20.0 implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/2f43f78f76439f5d11ef313cd379bec036543504/docs/roadmap),
[PromptKit v0.18.0 adoption and implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap),
[ConfigKit adoption, reporting, release-tooling, and remediation records](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap),

2
docs/roadmap/future.md
View File

@@ -8,6 +8,8 @@ No delivery dates are selected here.
Earlier completed roadmaps, implementation plans, and review findings have been retired.
This document preserves unfinished work and unselected ideas under the
[release policy](../policy/release.md#release-documentation-and-preparation).
The completed shared debug binding and reporting-mode implementation is recorded
in its [retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/56e3b013f9f83c9c9494f11602e802ce5ed8814e/docs/roadmap).
The completed [documentation refresh](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/5c960532552037d38119941389e558f78bf73aad/docs/roadmap/documentation-refresh.md) remains available in Git history.
The completed audits, consolidated remediation, implementation plan, and
declaration-path follow-up remain available in the

345
docs/roadmap/implementation.md
View File

@@ -1,345 +0,0 @@
# Shared debug binding implementation plan
Status: complete; Stages 1–7 implemented and verified.
Baseline: `6727d22ce6e1ac668b56a3e6d8fa5f7a06e54d88`.
Execution audience: Luna coding agent.
## Target and execution instructions
The [feature roadmap](shared-debug-binding.md) owns the accepted behavior,
intent, examples, and scope. OD-1 and OD-2 are resolved. The original
Audita request is motivation, not an additional
capture policy for CommandKit. This plan owns implementation order and checks.
Implement Stage 1 through Stage 7 in order as one end-to-end sprint after the
user approves implementation. Stages are work units, not approval checkpoints
or separate agent prompts. Continue through internal dependencies without
requesting permission after each stage. Intermediate stages need not compile
or leave a coherent repository. Record checks that depend on later stages as
pending, then resolve them before finishing; do not add temporary compatibility
code just to make an intermediate stage pass. Investigate and fix failures
within the selected scope. Surface a genuine contradiction rather than silently
changing the target.
Start with [development guidance](../development.md) and follow the
[agent](../policy/agents.md), [architecture](../policy/architecture.md),
[testing](../policy/testing.md), and [documentation](../policy/documentation.md)
policies. Use graph discovery for code as directed by AGENTS.md. Preserve
unrelated work and the ignored workspace files. Record actual completion and
verification here as work lands. Commit completed nonempty units with plain
English messages; dependent stages may share a commit. This sprint does not
publish releases, push refs, or implement Audita artifact capture.
## Implementation decisions
- Accept the existing `BoolFlag` form named `debug`, including ordinary captured
and renamed boolean bindings. Its private `boolean` property identifies the
constructor semantics; a matching name alone does not. Retain validity,
duplicate-name, short-spelling, and wiring checks. Other reserved reporting
bindings remain rejected. There is no new public constructor or subscription.
- Retain every consumer entry in `commandmeta.Command.Flags` at its original
index, including shared debug. Retain the core reporting declarations in
`CoreFlags`. Produce one effective flag list for backend registration,
token interpretation, and completion, combining only the selected debug
overlap. Never remove a consumer entry to deduplicate parser registration.
- Build that effective list through one small helper in
[internal/commandmeta](../../internal/commandmeta/metadata.go), used by the
backend and completion. Copy metadata rather than changing captured
declarations. Combine core debug usage with application usage, short spelling,
requiredness, and completion settings directly. Keep the core reporting
default false; preserve the application default in its original binding.
When the application default is true, label it separately in help and explain
that reporting still defaults to ordinary. Exact prose and helper names are
implementation details; no generic metadata-merging facility is selected.
- When a debug binding participates, honor its completion hint just as for an
ordinary application boolean, including no completion or an empty choice list.
With no application binding, keep core's existing boolean suggestions. Hints
never constrain parsing. A command-local short spelling belongs only to that
command; existing flag aliases retain their existing scope and collision rules.
- Feed the single parsed occurrence sequence to reporting reduction and its
indexed raw debug values to ordinary typed preparation. Defaults and
requiredness are application input rules, not reporter selection inputs.
- Define public `ReportingMode uint8` and the four selected constants with
ordinary as zero. Use that type for the existing reporter mode field, replacing
the private mode type/constants rather than adding a second mutable selection.
Keep the internal parser's neutral type and translate at `applySelection`.
`Invocation.ReportingMode()` reads reporter state under its existing mutex,
returns ordinary for a zero invocation, and remains readable after finalization.
No public type aliases an internal/backend type; no setter or second public
accessor is added. Keep the existing reporting callback reentrancy contract.
## Stage 1 — Expose the resolved reporting mode
**Complete.** The invocation exposes the existing reporter selection, including
zero and finalized values. Focused reporting and public accessor checks passed
with Go 1.27.0 and offline module resolution; concurrent reads also passed with
`-race -count=1`.
Primary files: [reporter.go](../../reporter.go),
[identity.go](../../identity.go), [execute.go](../../execute.go).
1. Define `ReportingModeOrdinary`, `ReportingModeQuiet`, `ReportingModeVerbose`,
and `ReportingModeDebug` on the public type. Replace the private mode
representation in reporter state, visibility switches, and selection mapping.
Keep ordinary as the zero value. Update tests referring to removed private
identifiers without changing their behavioral expectations.
2. Add `func (inv Invocation) ReportingMode() ReportingMode`. Handle a missing
reporter/state as ordinary; otherwise read the existing field under its
mutex. Finalization must preserve the mode while releasing its current writer
references. Each execution continues to create its own reporter.
3. Preserve execution order: reduce explicit occurrences and call
`applySelection` before typed input preparation and the handler. Do not
infer mode from bound values, output, format, or progress.
4. Document the method's zero value, stable handler/finalized selection, and
compatibility with concurrent reporting. It reads selection, not delivery
success; it adds no concurrent App dispatch or writer-lifetime guarantee.
5. Use `shared_debug_external_test.go` (package `commandkit_test`) as the public
behavior owner for this API and the shared-binding table in Stage 3. Add
checks for all four modes, a zero invocation, retained invocation after
return, and a subsequent execution with no flags.
Exercise concurrent mode reads alongside reporter operations using bounded
goroutines and explicit synchronization, not sleeps or concurrent dispatch.
Reuse an existing safe in-memory destination and existing visibility checks.
Complete when the accessor observes the existing selection without side effects,
and concurrent use and retained invocations preserve the selected result.
## Stage 2 — Recognize shared boolean bindings and compose metadata
**Complete.** Declaration validation accepts only boolean debug bindings and
retains other reservation and wiring checks. Effective metadata combines the
shared option without removing consumer entries. Focused validation and metadata
tests passed offline with Go 1.27.0; backend adoption follows in Stage 3.
Primary files: [command.go](../../command.go), [binding.go](../../binding.go),
[parser.go](../../parser.go), and
[neutral metadata](../../internal/commandmeta/metadata.go).
1. In declaration validation, allow the reporting reservation exception only
for a valid boolean binding named `debug`. The existing boolean property is
carried by `BoolFlag`, `CaptureFlags`, and `RenameFlag`; it is not set by
`ValueFlag` or `OccurrenceFlag`. Preserve all ordinary validation, including
missing setters, duplicate debug bindings, other reserved names, duplicate
shorts and reserved `-h`. Do not accept a custom converter because it returns
a Go bool.
2. Keep the bridge's consumer metadata and indexes intact. Add the effective
list helper described above: retain ordinary consumer flags, replace the
participating debug entry with the combined declaration, then append the
remaining core flags. Only the boolean debug overlap is combined. The helper
does not turn invalid duplicate application declarations into valid ones.
3. The combined declaration remains boolean with core's false reporting
default. Use application short spelling, requiredness, and completion hint;
combine usage text and label a differing application default. The original
consumer declaration keeps its own default for typed preparation. Backend
raw input remains empty on omission; metadata must not synthesize an explicit
occurrence or presence.
4. Adjust the reservation tests in [flag_aliases_test.go](../../flag_aliases_test.go)
to distinguish accepted `BoolFlag` from still-rejected string/custom-parser
declarations. Add focused checks for successful registration and duplicate
or invalid wiring rejection, retaining existing transactional registration
assertions. Test the effective metadata at its package boundary where that
gives distinct protection; do not snapshot private slice layouts wholesale.
Complete when declarations express the agreed exception and one effective debug
option can coexist with unchanged consumer indexing and application defaults.
Backend-dependent checks may remain pending until Stage 3.
## Stage 3 — Parse one debug option into both consumers
**Complete.** Backend registration and interpretation use effective flags while
consumer values retain their original indexes. Public mode/value cases, aliases,
invalid values, option-looking values and terminated operands pass, as do focused
backend parsing checks, offline with Go 1.27.0.
Primary files: [backend parse.go](../../internal/cobra/parse.go),
[backend flags.go](../../internal/cobra/flags.go),
[parser.go](../../parser.go), [binding.go](../../binding.go).
1. Use the effective list in `buildTree` registration and `Session.Parse` token
interpretation. Iterate it once when queuing entered spellings; do not queue
the same raw debug value twice. Retain existing pflag boolean no-value syntax,
raw-value collection, alias interpretation, and failure precedence.
2. Extract `FlagValues` and `FlagSpellings` by iterating the original consumer
`Flags`, looking up each effective backend flag by canonical name. This
delivers shared debug to its original index while core-only flags still
occupy no consumer index. Preserve the occurrence log's canonical names,
entered spellings, and order, including interleaving with other flags.
3. Keep `reduceReportingOccurrences` authoritative for visibility and invalid
reporting values. Use ordinary `BoolFlag.prepare` for the application value.
Do not add a setter path in the reporter, rescan argv, or reconstruct mode
from the final boolean. Reporting must still work on unbound commands,
root/group help, version, and discovery routes.
4. At the backend boundary, extend
[parse_test.go](../../internal/cobra/parse_test.go) and existing flag grammar
coverage only where needed to establish shared extraction, stable indexes
with ordinary flags before/after debug, and one occurrence stream through
aliases/short spellings. Do not duplicate the facade behavior table here.
5. At the public command boundary, extend `shared_debug_external_test.go` with
the roadmap's mode/value/presence table, observing both typed input and the
new accessor. Check invalid/empty boolean input prevents factories and handler
execution as appropriate under existing preparation timing. Keep tokens consumed as
another flag's value and operands following `--` out of reporting reduction.
Complete when debug feeds normal typed preparation and mode selection from one
parse, without changing unrelated input indexes, grammar, or failure handling.
## Stage 4 — Preserve composition, defaults, and alias behavior
**Complete.** Existing capture and rename machinery retains the boolean
identity and requiredness without production changes. Focused public tests
cover true defaults, explicit false, direct and captured requiredness, both
application methods, renaming in both directions, and an alias to the local
short spelling; capture and alias tests pass offline with Go 1.27.0.
Primary files: [flag_values.go](../../flag_values.go),
[binding.go](../../binding.go), [flag_aliases.go](../../flag_aliases.go).
1. Review the shared binding through `CaptureFlags`, `FlagValues.ApplyTo`, and
`ApplySuppliedTo`. Retain original binding identity, independently selectable
destinations, and existing conversion timing. Capture already preserves the
boolean property; avoid adding another store or observer if no change is needed.
2. Preserve `deferredRequired`: direct bindings enforce required input during
ordinary preparation, while captured bindings check requiredness when selected
for application, as they do today. An explicit false satisfies presence.
A true application default with `Set=false` must not satisfy requiredness or
turn on reporting. `ApplySuppliedTo` must keep its ordinary omission behavior.
3. Keep shared behavior determined by the current binding name and boolean
semantics. Renaming debug to an ordinary name yields an ordinary independent
boolean and stops observing core debug; renaming an ordinary boolean to debug
uses the same accepted attachment. Do not leave a sticky sharing marker.
4. Review canonical short spellings and alias compilation together. A local
debug short and aliases targeting its canonical debug input must feed the
same occurrence stream. Preserve existing collision errors, scope, and
registration rollback; do not add short spellings to unrelated commands.
5. Extend [flag_values_test.go](../../flag_values_test.go), existing rename and
alias tests for representative captured application, true default/explicit
false, requiredness, renamed-away behavior, and an alias targeting the local
short spelling. Use the public table from Stage 3 for visibility behavior
instead of repeating it in each composition test. Modify production code
here only where the selected behavior actually needs a change.
Complete when shared binding behaves like an ordinary reusable boolean across
capture, selection, application and rename, with visibility still independent.
## Stage 5 — Present one debug option in help and completion
**Complete.** Completion uses the same effective declarations as parsing and
help. Canonical and alias help and usage failures expose the combined option;
focused tests cover local shorts, requiredness, application defaults, choices,
file and directory hints, boolean validation, and idle application callbacks.
Primary files: [completion_flags.go](../../completion_flags.go),
[internal/cobra/parse.go](../../internal/cobra/parse.go),
[internal/commandmeta](../../internal/commandmeta/metadata.go).
1. Make `completionFlags` use the same effective declarations as the backend,
alongside the existing help flag. Eliminate the duplicate debug long option
without suppressing the application's local short spelling. Keep canonical
suggestion and existing alias interpretation policies; this is not alias
discovery work.
2. Ensure canonical command help, explicit help targets, alias help, and usage
failures show the combined debug option once. Core usage and application
usage must both be intelligible; a true application default is labeled as
application input, alongside the ordinary reporting default. Retain existing
required markers and help's exemption from required-input enforcement.
3. Preserve application completion hints, including choices, no completion, and
file/directory hints under ordinary handling. An arbitrary suggested value
remains subject to boolean parsing. Keep normal unbound core suggestions;
do not introduce a debug-specific completion rejection rule.
4. Use existing completion query tests and help tests to check one long debug
suggestion/row, the local short, a true default/required help case, explicit
boolean value completion, and one custom hint. Assert meaningful fragments
and counts for the effective option, not a complete help snapshot or exact
new explanatory wording. Queries and help must not call input factories,
setters, `CheckInput`, handlers, or providers. Retain help's existing conversion
of supplied input for syntax validation; completion continues to use metadata.
Complete when help and completion describe the same single parsed option and
clearly distinguish application defaults from reporting selection.
## Stage 6 — Document the implemented contracts
**Complete.** GoDoc, the CLI reference, consumer and internal guidance describe
the shared binding and reporting selection. The core v0.6.0 candidate note
records the feature and compatibility impact; no release has been published.
1. Update `BoolFlag`, `FlagMeta`, binding composition, and Invocation GoDoc with
the supported debug exception and mode API. Explain defaults, presence,
requiredness, short spellings, and retained mode without making all reporting
names bindable or treating mode as delivered-output evidence.
2. Update the [CLI reference](../cli.md#placement-and-aliases) where it describes
reserved names and command help. Keep API wiring in the
[consumer guide](../consumers/guide.md#invocation-reporting). Add a small
compiling example showing `BoolFlag` on `debug` and the mode query, using
`--debug --quiet` to explain why their results differ. Applications still own
artifact creation and other effects.
3. Add the feature and consumer impact to the next core minor candidate note,
`docs/releases/v0.6.0.md`, using the release and OSS policies for its title
and immutable licensing footer. Core v0.5.0 is published and must not be
rewritten. If version state has changed before implementation, select the
next unused minor through the release procedure; this is release bookkeeping,
not a new decision about this feature. No tag or publication is part of this
sprint. Integration dependencies and upstream versions need no upgrade here.
4. Update [internal guidance](../internal/overview.md) only where the effective
flag view and authoritative reporter mode change its explanation. Validate
changed links, fragments, Go snippets, and prose against the final code.
Do not introduce a new ADR for this addition.
Complete when GoDoc owns the precise API, operator guidance explains the flag,
and consumer guidance distinguishes input policy from reporting selection.
## Stage 7 — Verify the assembled sprint and record completion
**Complete.** The feature checklist has been reviewed against the implementation
and focused tests. Go 1.27.0 passed the independent core suite, the aligned
three-module workspace suite, and the concurrent mode-read test under the race
detector. The consumer snippet compiled, local documentation links and headings
were checked, and changed Go files were formatted. Optional interactive Zsh and
Fish checks remain deferred in future work. The v0.6.0 note is a candidate;
source completion does not publish a release. Completed planning records are
retired separately with this completed record retained in Git history.
1. Review every target/checklist item in the feature roadmap against the final
implementation and evidence. Ensure tests that formerly rejected all reserved
reporting bindings now allow only the selected boolean form. Review capture
and requiredness separately from the direct binding cases.
2. Run focused tests as the stages become testable, then the independent core
suite and the aligned three-module suite with Go 1.27.0 and cached dependencies:
```sh
GOWORK=off GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./...
GOTOOLCHAIN=local GOPROXY=off go test -mod=readonly ./... ./integrations/ckconfig/... ./integrations/ckprompt/...
```
Use the ignored workspace described in the developer guide. The aligned
integration run exercises this changed core; independent integrations still
select released core v0.5.0 and cannot establish that boundary by themselves.
Do not upgrade manifests or commit local replacements to run these checks.
3. Run the new focused concurrent mode-read check under `-race -count=1` when
supported; choose its actual test name after implementation. No full race
matrix, timing assertion, live provider, or Audita processing run is needed.
Record unavailable optional tooling accurately and continue with supported
verification; never describe an unavailable check as passed.
4. Run gofmt on changed Go files; inspect diffs and verify current Markdown links
and fragments, snippet compilation, and tracked/staged prose whitespace using
the developer guide. Use a temporary `GOCACHE` if the default is unwritable.
Reuse passed checks for unchanged content; repeat for actual changes or failures.
5. Record completed stages, actual checks, limitations, and residual release
preparation here. Mark the feature checklist complete only with its evidence.
Retire completed planning records through the normal documentation lifecycle,
preserving unfinished work in `future.md`, repairing links and retaining a
Git-history reference. Do not turn source completion into a publication claim.
6. Review and commit the remaining completed nonempty changes. Report the API
and behavior delivered, verification, any remaining work, commit identifiers,
and worktree state. Resolve supported failing checks within scope before
claiming completion; a broad passing suite does not replace missing behavior.
Complete when the agreed target is implemented, verified and documented as one
coherent source state, with no new consumer restrictions or application policies.
## Open Questions
None. The feature roadmap resolves the public behavior and settings policy;
this plan selects the internal approach and validation ownership. Private helper
names, exact help prose, and test organization are ordinary implementation
choices within these decisions, not additional product gates.

196
docs/roadmap/shared-debug-binding.md
View File

@@ -1,196 +0,0 @@
# Shared debug binding and reporting-mode access
Status: implemented and verified. OD-1 and OD-2 are resolved; no significant
open decisions remain. The
[implementation plan](implementation.md) owns the ordered stages and verification.
Baseline: `69257066e21c12ea3492237ebee072598adea60c`.
## Purpose and authority
Applications should be able to receive the boolean value of CommandKit's
`--debug` flag through normal typed input binding. Applications that need the
resolved reporting mode should also have a read-only invocation API.
The original Audita request motivated this work. Subsequent
discussion selected a broader distinction: application debug behavior and CLI
reporting visibility are separate choices. Audita's original requirement that
capture follow reporting mode is an application policy, not a CommandKit
requirement. This roadmap records the agreed direction from that discussion;
it does not treat every proposal in the original request as accepted.
The [architecture policy](../policy/architecture.md#ownership-boundaries) and
[ADR 0006](../adr/0006-invocation-reporting.md) already assign CLI mechanics to
core and domain behavior to applications. This work fits those boundaries and
does not require another ADR. Implemented behavior remains documented in
[Go declarations](../../command.go) and the [CLI reference](../cli.md#reporting)
until this work lands.
## Current baseline
| Area | Current implementation | Work needed |
| --- | --- | --- |
| Typed binding | `BoolFlag` in [binding.go](../../binding.go) converts supplied occurrences and applies the last boolean with `Supplied[bool]` presence. | Let a binding receive the existing core debug flag's input. |
| Registration | `FlagMeta` and `validateBindings` in [command.go](../../command.go) reserve every reporting name, including `debug`. | Recognize the selected shared-binding form without treating it as an independent competing flag. |
| Parser metadata | [commandmeta](../../internal/commandmeta/metadata.go) separates `CoreFlags` from consumer-indexed `Flags`; [parser.go](../../parser.go) supplies core flags to each command. | Preserve consumer binding identity and indexes while sharing one parser declaration. |
| Backend | [internal/cobra/parse.go](../../internal/cobra/parse.go) registers both lists, records occurrences, and extracts indexed values only for consumer flags. | Supply shared debug values and spellings to the participating binding without duplicate backend registration. |
| Reporting | `reduceReportingOccurrences` in [parser.go](../../parser.go) resolves the mutually exclusive mode from ordered occurrences. | Preserve that reduction independently of the bound debug boolean. |
| Invocation | [execute.go](../../execute.go) applies reporting selection before input preparation and execution. [reporter.go](../../reporter.go) stores the mode privately; [Invocation](../../identity.go) exposes no mode query. | Expose the already resolved selection through a CommandKit-owned public type. |
Simply permitting the name in registration is insufficient: the backend would
otherwise receive two declarations for `debug`. Existing occurrence capture is
the starting point; applications should not scan or reparse arguments.
## Targeted end state
### Bind the debug boolean independently
OD-1 is resolved: an application declares a normal `BoolFlag` with
`FlagMeta.Name` set to `debug`. CommandKit attaches that binding to the existing
core flag. The application uses the same `Flag[I]`, `Supplied[bool]`, command
binding list, and typed setter model as for other boolean flags. No dedicated
`DebugFlag` constructor is planned. Application metadata follows the accepted
OD-2 decision below.
Commands without such a binding retain the standard core flag and reporting
behavior.
This choice keeps the application API familiar and avoids another public
constructor. Core handles shared registration internally; an arbitrary
string-valued or custom-parser flag named `debug` is not equivalent to the
selected boolean binding merely because its name matches.
The shared binding receives `Supplied[bool]`: omission produces the application's
declared default with `Set=false`; an explicitly supplied false produces
`Value=false, Set=true`. Repeated debug occurrences follow ordinary boolean
binding semantics: every supplied value must be valid, and the last value wins.
Other reporting flags do not rewrite the bound debug value.
Shared bindings retain ordinary capture, identity, presence, and application
semantics through `CaptureFlags`, `FlagValues.ApplyTo`, and `ApplySuppliedTo`.
Renaming the boolean to an ordinary application name makes it independent of
core debug input while retaining its ordinary binding behavior.
The following examples appear after a complete command path. They show the
ordinary false-default binding and the existing mode-selection rules together:
| Arguments | Debug value | Supplied | Resolved reporting mode |
| --- | --- | --- | --- |
| None | false | false | Ordinary |
| `--debug` | true | true | Debug |
| `--debug --quiet` | true | true | Quiet |
| `--quiet --debug` | true | true | Debug |
| `--debug --verbose` | true | true | Verbose |
| `--debug --debug=false` | false | true | Ordinary |
| `--verbose --debug --debug=false` | false | true | Ordinary |
| `--debug --quiet=false` | true | true | Debug |
| `--debug --progress=false` | true | true | Debug |
Aliases use the same canonical debug input. Tokens consumed as other flag
values or appearing after `--` keep their existing meaning. Invalid reporting
booleans remain usage failures without handler execution. Existing placement,
help, and input-preparation timing continue to apply.
Application code can use the bound value for diagnostic artifacts even when
quiet mode suppresses ordinary CLI output. Core continues to own reporting
visibility; applications own capture, redaction, file lifecycle, and any other
domain effects. No capture policy is imposed on Audita or other applications.
### Honor application binding settings, help, and aliases
OD-2 is resolved: honor ordinary application binding settings while keeping
core reporting selection independent. Application defaults and requiredness
affect the receiving binding; they do not select a reporting mode. Core continues
to resolve reporting from explicit CLI occurrences under the existing rules.
For example, a non-required binding with a true default receives
`Value=true, Set=false` when debug is omitted, while reporting remains ordinary
in the absence of mode flags. An explicit `--debug=false` overrides that default.
With `--debug --quiet`, the binding receives true while reporting is quiet.
Requiredness follows ordinary presence semantics: if required, omission is a
usage failure, while an explicit false satisfies the presence requirement.
An application default does not count as explicit input.
Honor the application's short spelling through existing alias and collision
rules. Both that spelling and other registered aliases feed the same canonical
debug input and reporting occurrence sequence.
Show one debug option in command help, combining the core reporting explanation
with any application-specific usage text. Clearly label an application default
that differs from core behavior, so a true application default does not imply
that debug reporting is enabled by default. Show application requiredness using
the existing help conventions. Keep ordinary boolean binding completion behavior
and metadata handling; this feature adds no special rejection of completion
settings. Completion suggestions do not change the shared boolean grammar.
This choice keeps ordinary `BoolFlag` settings useful without adding restrictions
solely for shared registration. The distinction between application input and
reporting selection must be clear in help and consumer guidance. Implement this
small combination directly; a general metadata-merging framework is unnecessary.
### Query the resolved reporting mode
Add a CommandKit-owned `ReportingMode` type with ordinary, quiet, verbose, and
debug values, and one canonical accessor:
```go
func (inv Invocation) ReportingMode() ReportingMode
```
Use `ReportingModeOrdinary`, `ReportingModeQuiet`, `ReportingModeVerbose`, and
`ReportingModeDebug` as the planned constant names, with ordinary as zero.
The accessor reads the existing selection without output or mutation. The mode
is final when the handler receives the invocation and remains its selection
after execution finishes. A manually constructed zero-value invocation returns
ordinary. Reads are compatible with concurrent reporting on that invocation;
this does not add concurrent dispatch support or extend writer lifetimes.
An application deliberately following reporting visibility can use:
```go
captureArtifacts := inv.ReportingMode() == commandkit.ReportingModeDebug
```
This reports the selected mode, not whether output was delivered successfully.
Progress and report format remain separate selections. Keep the public type
independent of internal/backend types and avoid a second mutable copy of the
resolved mode. A second accessor on `Reporter` is unnecessary for this scope.
## Scope and documentation
This is core work. It does not require ConfigKit or PromptKit API additions or
adoption of Audita's artifact implementation. Binding other core flags, adding
mode setters, or creating a general flag-sharing framework is not part of this
sprint; that scope limit is not a permanent prohibition on later capabilities.
## Completion criteria
The table above supplies representative boundary expectations. The
[implementation plan](implementation.md) assigns test ownership and verification
under the [testing policy](../policy/testing.md).
- [x] A registered application command receives the shared debug boolean and
presence through normal typed input preparation, including when quiet or
verbose becomes the resolved reporting mode.
- [x] The public query returns the selected mode without changing visibility;
cover zero value, retained invocation, and fresh selection on subsequent runs.
- [x] Focused coverage establishes safe mode reads during existing concurrent
reporter use, without asserting concurrent dispatch support.
- [x] Exercise aliases, explicit false, repeated values, invalid booleans, and
option-looking operands/values where they establish the new binding boundary.
Preserve existing failure precedence and no-handler-on-parse-failure behavior.
- [x] A command with both shared debug and ordinary flags receives the correct
values; help and completion describe one effective debug option. Exercise
representative capture/application composition and any affected rename path.
- [x] Cover a true application default without debug reporting, explicit false
overriding that default, and ordinary requiredness/presence behavior. Help
combines core and application explanations and distinguishes the application
default; local short spellings use existing collision and alias rules.
- [x] The allowed boolean binding is accepted while unsupported/custom-parser
debug declarations and other reserved reporting declarations retain their
ordinary validation. Metadata handling adds no debug-specific restrictions
beyond the selected boolean binding contract.
- [x] GoDoc and consumer guidance distinguish boolean input from reporting
mode, and canonical docs describe the implemented registration exception.
Canonical binding and invocation GoDoc, the CLI reference, consumer guidance,
and the applicable core release note will describe the implemented exception
and mode query. The implementation plan records the completed work and verification.