Clarify debug defaults and operator data handling
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user