# 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