2.5 KiB
2.5 KiB
pipeline observability
Status: direction — as of 2026-07-16 Connects to: pipeline-stages, self-improvement-loops, never-ask-twice, overview
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's raw input), and a human-facing summary. This is the feed the loops in self-improvement-loops 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