| name | logging-patterns |
| description | Use for changes under cli/src/infra/logging/, task result recording, status rows, progress lines, detail ordering, or final summaries. Not for generic error policy or task scheduling without output changes.
|
Logging Patterns
Ownership
- Startup initializes one shared
Logger; task code uses ctx.log.
engine::execute() records task results. Tasks do not call
record_task() directly.- Records are keyed by
TaskId::record_key(), never display name.
ExecutionSummary controls success and later phases. Logger counters are
presentation only.
Output contract
- Visible task rows stay in natural completion order.
- Non-verbose mode shows reportable outcomes; verbose mode also shows current
and not-applicable tasks plus elapsed time.
- A task reason stays on its status row after
·. Indented lines are actions
or planned actions and must not restate the row.
- Normalize detail through
compact_detail_line; sort only consecutive action
runs inside one task.
- Resource descriptions read
subject -> value; symlinks are target -> source.
- Final summaries count tasks, not detail lines or parsed display text.
- Progress uses
Running · {done}/{total} done · {active} and the denominator
matches visible summary accounting.
- Transient status lines are always cleared and never replace durable logging.
Message intent
| Intent | Use |
|---|
trace | plumbing that never reaches the console |
debug | diagnostic item detail |
info | concise action detail |
warn / error | visible problems |
dry_run | planned mutation |
always | output that must be visible |
startup | the single dim run-context header |
Do not hardcode indentation, duplicate task recording, rephrase a task reason as
detail, or build task-local buffering.
When summary semantics change, test statuses, visibility, details, progress
denominator, totals, and both verbose modes. Wrapper style belongs in
shell-patterns.
