47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
# pipeline observability
|
|
|
|
_Status: direction — as of 2026-07-16_
|
|
_Connects to: [pipeline-stages](pipeline-stages.md), [self-improvement-loops](self-improvement-loops.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
|
|
|
|
## Purpose
|
|
|
|
Defines what a pipeline run writes down — its exhaust — where it goes, and how long it
|
|
lives. The self-improvement loops and the never-ask-twice promotion mechanism are only as
|
|
good as this exhaust; it was implicit in the original design and is made explicit here.
|
|
Load this before designing any run report, audit input, or blocked-stage log.
|
|
|
|
## Design
|
|
|
|
- **Every run emits exhaust**: stages executed, actor per stage, gate outcomes (red/green,
|
|
iterations consumed), blocked-stage reports (the questions the pipeline could not
|
|
auto-resolve — [never-ask-twice](never-ask-twice.md)'s raw input), and a human-facing
|
|
summary. This is the feed the loops in
|
|
[self-improvement-loops](self-improvement-loops.md) consume.
|
|
- **Every exhaust artifact has a predefined lifespan** (composes with os-doc-hygiene):
|
|
run-scoped scratch dies with the worktree; run reports persist on the ticket; anything
|
|
durable gets *promoted* to its proper home (ADR, vault note, issue comment) rather than
|
|
accumulating as clutter. No unbounded log directories.
|
|
- **Copy → tag → audit pattern** (deterministic where possible, per the three-actor test):
|
|
the write side is a hook (code actor), the review side is the periodic audit (agent
|
|
actor). Reference case — ADRs: the ADR-writing skill becomes a named agent whose hook
|
|
copies every new ADR into the vault at write time; the ADR audit then reads only *virgin*
|
|
(untagged) vault copies, keeps the durable ones, revises for clarity where needed, and
|
|
tags them audited — the next round checks only new virgin ADRs. The same pattern
|
|
generalizes to other streams (blocked-stage reports, run reports): mechanical capture at
|
|
write time, audit consumes the untagged backlog, tagging marks progress.
|
|
|
|
## Open questions
|
|
|
|
- Run-report format and home: an issue comment on the ticket (durable, in-tracker, visible
|
|
at merge review) vs. a file artifact — leaning issue comment.
|
|
- Lifespan policy per artifact class (scratch / run report / blocked-stage report) and how
|
|
os-doc-hygiene enforces it.
|
|
- Which exhaust stream gets the copy-tag-audit hook first (ADRs are the obvious pilot).
|
|
|
|
## Sources
|
|
|
|
- 2026-07-16 design session — user-identified gap ("I assumed this mechanism was baked into
|
|
the concept") + the ADR copy-tag-audit proposal
|
|
- os-doc-hygiene plugin (lifespan enforcement)
|
|
- ADR-0037
|