diff --git a/docs/roadmap/shared-debug-binding.md b/docs/roadmap/shared-debug-binding.md index 7222a66..2e3eec8 100644 --- a/docs/roadmap/shared-debug-binding.md +++ b/docs/roadmap/shared-debug-binding.md @@ -1,7 +1,8 @@ # Shared debug binding and reporting-mode access -Status: agreed capability direction; not implemented. Public binding details -remain open below. Baseline: `69257066e21c12ea3492237ebee072598adea60c`. +Status: agreed scope and public behavior; not implemented. OD-1 and OD-2 are +resolved; no significant open decisions remain. +Baseline: `69257066e21c12ea3492237ebee072598adea60c`. ## Purpose and authority @@ -46,7 +47,8 @@ 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. Metadata rules remain open in OD-2. +`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. @@ -55,8 +57,8 @@ 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 ordinary shared binding receives `Supplied[bool]`: omission produces -`Value=false, Set=false`; an explicitly supplied false produces +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. @@ -86,6 +88,38 @@ 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 @@ -116,9 +150,10 @@ resolved mode. A second accessor on `Reporter` is unnecessary for this scope. ## Implementation work -1. **Implement ordinary binding attachment and settle metadata.** Use the - selected `BoolFlag` form and resolve OD-2 before making the registration - exception. Document how its application metadata is handled. Preserve ordinary +1. **Implement ordinary binding attachment and metadata handling.** Use the + selected `BoolFlag` form and the accepted application metadata rules above. + Preserve application defaults, presence, requiredness, and short spellings; + combine help without changing core reporting selection. Preserve ordinary validation for unrelated names and bindings; do not broadly disable reserved name or collision checks. 2. **Connect shared parsing to typed input.** Update declaration validation, @@ -144,7 +179,7 @@ resolved mode. A second accessor on `Reporter` is unnecessary for this scope. [CLI reference](../cli.md#placement-and-aliases). Add a short example to the [consumer guide](../consumers/guide.md#invocation-reporting) contrasting a bound debug boolean with an explicit mode query. Explain application effects - in application help using the metadata choice from OD-2. Record the core API + in application help using the accepted metadata rules. Record the core API addition in the applicable release note. Retire this roadmap through the normal documentation lifecycle when complete. @@ -173,8 +208,13 @@ for separate copies of the same cases at every layer. - [ ] 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. -- [ ] Test only the metadata/collision decisions actually selected below; - replace obsolete blanket rejection assertions for the allowed binding form. +- [ ] 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. +- [ ] Replace obsolete blanket rejection assertions for the allowed binding + form. Preserve ordinary metadata handling without new debug-specific + restrictions beyond the selected boolean binding contract. - [ ] Run focused binding/parser/reporter tests, then the core suite and aligned integration suites using the [developer guide](../development.md). The shared parser change justifies checking that standard integration commands still @@ -184,37 +224,3 @@ for separate copies of the same cases at every layer. For this documentation pass, review baseline accuracy, scope, links, and whitespace only. Implementation and the unchecked items above remain future work. - -## Open Decisions - -### OD-2: Which application metadata can accompany a shared flag? - -**Recommendation:** retain the core boolean grammar and false default. Allow -command-local usage text to explain additional application effects alongside -core reporting help, and allow a local short spelling through existing alias -and collision rules. Keep one displayed option. Continue using core boolean -completion. Under the ordinary `BoolFlag` approach, report conflicting default, -requiredness, or completion overrides as declaration errors rather than silently -ignoring them. These are proposed rules for the shared attachment only, not -accepted new restrictions on ordinary application flags. - -This preserves consistent debug input across applications and avoids help that -claims a default or requirement different from the shared flag. Its tradeoff is -that a normal-looking declaration would accept fewer metadata choices. - -**Viable alternative:** let application defaults and requiredness affect only -the receiving binding, using ordinary binding semantics, while core reporting -continues to follow explicit occurrences. That gives applications more familiar -flexibility: for example, an application default of true could enable its own -diagnostics without selecting debug reporting. However, omission would no longer -necessarily mean a false bound value, and help would need to distinguish an -application default from the core reporting default. If selected, revise the -omission contract above and explain this distinction explicitly; do not silently -allow local metadata to change core reporting selection. - -**Simpler help alternative:** retain core flag help unchanged and put application -effects in the command description, with short spellings supplied through the -existing `FlagAliasFor` mechanism. This avoids help merging, at the cost of less -convenient flag-local documentation. With ordinary `BoolFlag` registration, -this alternative would also need to explain how supplied usage text and short -spellings are handled. There is no need for a general metadata-merging framework.