diff --git a/docs/development.md b/docs/development.md index 5410a73..e594415 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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), diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 5c13f5e..548a604 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 0517036..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/shared-debug-binding.md b/docs/roadmap/shared-debug-binding.md deleted file mode 100644 index 928cac3..0000000 --- a/docs/roadmap/shared-debug-binding.md +++ /dev/null @@ -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.