Clarify debug defaults and operator data handling

This commit is contained in:
2026-11-19 18:38:43 +00:00
parent a299869fcc
commit d11d379bd4

View File

@@ -97,9 +97,9 @@ Two application needs already identified for deliberate treatment are:
replaces its presentation with one compact application report rendered natively
for humans and machines. Exact fields/versioning remain with U9; reports must
describe the actual publication and domain outcome.
- Item 5 uses native `--debug` for diagnostic verbosity and for capture when a
debug directory is supplied through CLI or configuration. Capture selection
remains independent of the final reporting mode.
- Item 5 uses native `--debug` for diagnostic verbosity and for capture when an
effective debug directory is available, including an application default.
Capture selection remains independent of the final reporting mode.
### Intended Sequencing
@@ -645,24 +645,30 @@ retains the bookkeeping boundary; U9 still owns concrete durable record choices.
**Discussion / decision:** Controls, native capture hooks, lifecycle, failure
policy, and optional diagnostics agreed. Use `--debug` for native verbosity and
conditional durable capture. The summary/trace distinction, concrete capture
inventory, and bundle organization remain under discussion. Implementation is
pending.
conditional durable capture. The default-directory policy is reopened; removing
the existing default is not an agreed requirement. Operator-owned data handling
and recording each fact once are agreed. The summary/trace distinction, concrete
capture inventory, and bundle organization remain under discussion.
Implementation is pending.
### Shared Debug Control With Conditional Capture
Attach a native application boolean binding to CommandKit's shared `--debug`
option on the pipeline run command. Capture is enabled when that boolean is true
and a debug directory is defined by `--debug-dir PATH` or `debug.directory` in
application configuration. The CLI directory overrides the configured directory.
A directory alone does not enable capture. Do not add a separate
and an effective debug directory is available. `--debug-dir PATH` overrides
`debug.directory` in application configuration, which may have an application
default. A directory alone does not enable capture. Do not add a separate
`--capture-debug` flag.
Make the configured directory optional, removing the implicit
`./notarius-debug` default. With no supplied destination, `--debug` supplies
native diagnostics without creating files. Preserve normal CLI/configuration
path resolution; detailed empty-value handling can be settled with the
configuration migration.
**Default-directory discussion:** The earlier removal of the implicit
`./notarius-debug` default was an inference, not a user-selected requirement;
withdraw it. A default destination is compatible with the design. With a default,
`--debug` ordinarily enables both verbosity and capture without an explicit path.
The existing destination is relative to the selected main configuration file;
explicit CLI paths are relative to the invocation directory. Decide the default
and whether there is a useful explicit way to select no capture destination
before finalizing absent/empty-value behavior. Do not assume omission of a CLI or
configuration key means there is no effective destination.
Determine capture from the application boolean and destination, not from
`Invocation.ReportingMode()`. A later quiet or verbose selection can change
@@ -671,11 +677,14 @@ native boolean binding semantics and disables capture.
| Invocation flags | Reporting selection | Capture |
| --- | --- | --- |
| `--debug`, no CLI/configured directory | Debug | None. |
| `--debug`, with CLI/configured directory | Debug | Enabled. |
| `--debug --quiet`, no CLI/configured directory | Quiet | None. |
| `--debug --quiet`, with CLI/configured directory | Quiet | Enabled. |
| `--quiet --debug`, with CLI/configured directory | Debug | Enabled. |
| `--debug`, no effective directory | Debug | None. |
| `--debug`, effective directory from CLI/configuration/default | Debug | Enabled. |
| `--debug --quiet`, no effective directory | Quiet | None. |
| `--debug --quiet`, effective directory from CLI/configuration/default | Quiet | Enabled. |
| `--quiet --debug`, effective directory from CLI/configuration/default | Debug | Enabled. |
The no-effective-directory rows apply only if the final directory policy allows
that state; with a default, omission alone does not select it.
**Upstream ordering clarification:** CommandKit uses the last enabled reporting
mode. Thus `--debug --quiet` suppresses command output while retaining capture;
@@ -746,15 +755,26 @@ capture finalization succeed. If finalization fails after publication, identify
the published output and available debug location in the native failure
explanation; preserve the successful publication as a fact.
### Disclosure And Retention
### Debug Data And Operator Responsibility
Retain the separate debug root, restrictive debug permissions, and explicit
operator retention policy. Captured content may include source material, rendered
requests, generated output, and correction history. Credential redaction does not
make that material safe to share. Do not record credential values, authorization
headers, or environment dumps. Use upstream safe inspection where available and
deliberate content selection elsewhere. No summary or directory label should
imply that arbitrary diagnostic content is non-sensitive.
Debug artifacts are expected to contain internal application data, including
source material, rendered requests, model output, and correction history where
useful for diagnosis. If the application data is sensitive, the debug artifacts
are sensitive in the same way. Operators secure them through the ordinary means
used for application inputs and outputs, such as filesystem permissions. Do not
require a special debug-only security or retention model, or use sensitivity
concerns to limit useful diagnostic content.
Do not directly print or serialize values explicitly marked as secrets by
ConfigKit, such as resolved API keys. Use native secret-aware configuration
inspection and preserve upstream credential omissions. This boundary does not
authorize scanning or rewriting LLM output, prompts, source content, or arbitrary
strings for suspected sensitive values. Do not carry forward heuristic content
scrubbing or generic secret-detection machinery as a migration requirement.
Separate debug/output/cache lifecycles and no automatic debug deletion remain
application organization choices. Choose capture contents for diagnostic value,
size, and duplication, rather than promising a shareable or sanitized bundle.
### Native Optional Diagnostics
@@ -777,10 +797,14 @@ status zero alone does not establish that a check passed.
### Open Discussion: Summary And Trace
**Agreed principle:** Record each fact once and reference it where needed. Use
shared application outcome facts and native execution evidence rather than
parallel summary/trace accounting or repeated snapshots.
The current `summary/` and `trace/` layout is not selected as the new design.
Discuss what diagnostic questions the bundle should answer, which application
records and native evidence it needs, and how to avoid duplicate snapshots or
execution accounting. Keep these choices open:
Discuss what diagnostic questions the bundle should answer and which application
records and native evidence it needs. Summary/trace are not separate security
classes. Keep these choices open:
- Whether a separate summary is useful, and whether it is a compact index/final
outcome rather than another copy of execution records.
@@ -812,6 +836,9 @@ The current [debug lifecycle](../internal/state.md#debug-bundles) and
and which migration examples, documentation, and ADRs need coordinated updates?
- What release-documentation guidance will show operators and subprocess callers
how to migrate their workflows and integrations to the new conventions?
- Reconcile older debug-sensitivity language, special-handling requirements, and
heuristic redaction behavior/tests with item 5's clarified boundary. Do not
reintroduce them as implicit requirements while migrating documentation or code.
After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing,
removals, and acceptance criteria, including its treatment of existing inspection