# Shared debug binding and reporting-mode access

Status: agreed capability direction; not implemented. Public binding details
remain open below. 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 [Audita request](audita-feature-request.md) 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. Metadata rules remain open in OD-2.
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 ordinary shared binding receives `Supplied[bool]`: omission produces
`Value=false, 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.

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.

### 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.

## 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
   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,
   metadata bridging, and backend value extraction together. Register one
   effective debug flag, retain canonical occurrence order and supplied
   spellings, and deliver its values through normal input preparation. Keep
   reporting reduction based on the same parsed occurrences, including for
   commands that have no application debug binding. Reuse current mechanisms;
   a general observer registry, alternate parser, or subscription lifecycle is
   not needed for this feature.
3. **Preserve binding composition.** Review `CaptureFlags`, `FlagValues.ApplyTo`,
   and `ApplySuppliedTo` in [flag_values.go](../../flag_values.go). A shared
   binding should participate through the existing identity and presence
   machinery. Review `RenameFlag` if a special binding marker is introduced:
   renaming to an ordinary application name must not accidentally keep reading
   core debug input. Avoid adding separate storage or application callbacks just
   to carry this boolean.
4. **Expose the mode query.** Reuse reporter state and its synchronization as
   appropriate; document the zero-value, invocation lifetime, and concurrent-read
   behavior. Do not expose backend objects or add public mutation APIs.
5. **Update canonical documentation when implemented.** Update binding and
   invocation GoDoc, the reserved-name wording in `FlagMeta`, and the
   [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
   addition in the applicable release note. Retire this roadmap through the
   normal documentation lifecycle when complete.

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.

## Validation and completion checklist

Follow the [testing policy](../policy/testing.md): test the public behavior and
reuse existing parser and reporting coverage rather than duplicate it wholesale.
The table above supplies representative boundary expectations, not a request
for separate copies of the same cases at every layer.

- [ ] 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.
- [ ] The public query returns the selected mode without changing visibility;
  cover zero value, retained invocation, and fresh selection on subsequent runs.
- [ ] Focused coverage establishes safe mode reads during existing concurrent
  reporter use, without asserting concurrent dispatch support.
- [ ] 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.
- [ ] 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.
- [ ] 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
  register and execute. No live providers or Audita processing tests are needed.
- [ ] GoDoc and consumer guidance distinguish boolean input from reporting
  mode, and canonical docs describe the implemented registration exception.

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.