pipelinemd 0.1.0__tar.gz

pipelinemd-0.1.0/.dockerignore

@@ -0,0 +1,12 @@
+# The image build reads pyproject.toml, README.md, LICENSE and src/ and nothing
+# else. Allow-listing them keeps the context small, keeps job traces in the
+# corpus out of it, and means a stray local file can never end up in an image.
+*
+!pyproject.toml
+!README.md
+!LICENSE
+!src/
+
+# Even inside src/, never ship interpreter or tool droppings.
+**/__pycache__
+**/*.py[cod]

pipelinemd-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local scratch - never commit real job traces, they can carry secrets
+*.local.log
+scratch/

pipelinemd-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to pipelinemd are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+How a section becomes a release is in [docs/releasing.md](docs/releasing.md).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-06
+
+The first release.
+
+### Added
+
+- `pipelinemd diagnose` takes a GitLab job or pipeline URL, or `--project`
+  with `--pipeline`/`--job`, and with no target at all diagnoses the pipeline
+  it is running in. On a pipeline it picks the failed job, names the rest, and
+  `--all-jobs` diagnoses every one. Credentials come from `--token`,
+  `$PIPELINEMD_TOKEN`, `$GITLAB_TOKEN`, `$GITLAB_PRIVATE_TOKEN` or
+  `$CI_JOB_TOKEN`.
+- `pipelinemd distill` distils a saved trace, or one on stdin, fully offline.
+- A deterministic distiller: replays ANSI escapes and `\r`/`\b` overwrites,
+  parses GitLab sections, strips runner timestamps, scores every line against
+  failure signals and dampeners, and spends a fixed line budget on the windows
+  that explain the outcome, always keeping the runner's verdict at the tail.
+- Redaction of credential-shaped text (GitLab, GitHub, AWS and Slack tokens,
+  JWTs, URL credentials, `Authorization:` headers, secret flags and
+  assignments, PEM private keys) before evidence reaches the prompt, the
+  terminal or the JSON output.
+- A catalog of 59 known CI failure signatures, each with an explanation and
+  fixes, browsable with `pipelinemd rules` and `pipelinemd explain`.
+- Every report is placed in one of seven v1 failure classes (`yaml`,
+  `ci_vars`, `image_pull`, `cache_artifact`, `test`, `runner`, `flaky`) with a
+  fix type. Flaky comes from GitLab's retry history: another attempt of the
+  same job passing on the same commit.
+- An optional Claude diagnosis (the `[llm]` extra, `ANTHROPIC_API_KEY`) that
+  reads only the distilled evidence and must cite evidence lines; a diagnosis
+  citing nothing real is rejected, and invented line numbers are shown beside
+  one that cites a mix. A failed call is never fatal.
+- An analysis-level confidence capped at its weakest signal, with a **needs
+  human review** flag at low, and an estimated cost from the API's own token
+  counts, totalled across a run with `--all-jobs`.
+- Terminal, Markdown and JSON output. JSON is versioned by `schema_version`.
+- A labelled corpus of 62 failure traces across the v1 taxonomy, and
+  `pipelinemd eval` (`make eval`, `make gate`) scoring rule@1, class accuracy,
+  evidence hit rate and exit-code accuracy, with thresholds that fail CI on a
+  regression.
+- A Docker image, `ghcr.io/rbalukja15/pipelinemd`, for amd64 and arm64, so a
+  GitLab CI job can diagnose a failed pipeline without a pip install, and a
+  release workflow that publishes it and the PyPI package as one version.
+
+[Unreleased]: https://github.com/rbalukja15/pipelinemd/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rbalukja15/pipelinemd/releases/tag/v0.1.0

pipelinemd-0.1.0/Dockerfile

@@ -0,0 +1,68 @@
+# The pipelinemd image: the CLI with the Claude diagnosis layer, ready to name
+# in a CI job's `image:` so a failed pipeline is diagnosed without a pip install
+# - which is exactly when PyPI being slow or unreachable would hurt most.
+#
+# Two stages. The builder turns the source tree into wheels for pipelinemd and
+# its [llm] dependencies; the runtime stage installs from those wheels alone,
+# so the published image carries no build backend, no source tree and no pip
+# cache.
+
+ARG PYTHON_VERSION=3.12
+
+FROM python:${PYTHON_VERSION}-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /src
+
+# Only what the build backend reads. Copying the whole context would make every
+# edit to a test or a doc invalidate this layer.
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN pip wheel --wheel-dir /wheels ".[llm]"
+
+
+FROM python:${PYTHON_VERSION}-slim
+
+# Set from the release tag by the release workflow and from __version__ by
+# `make image`; a bare `docker build` says "dev".
+ARG VERSION=dev
+
+LABEL org.opencontainers.image.title="pipelinemd" \
+      org.opencontainers.image.description="GitLab CI/CD failure doctor - diagnoses failed pipelines and suggests fixes." \
+      org.opencontainers.image.source="https://github.com/rbalukja15/pipelinemd" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.version="${VERSION}"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+# The wheels are bind-mounted rather than copied, so they never become a layer
+# of their own. --no-index keeps pip off the network entirely: what gets
+# installed is exactly what the builder resolved.
+RUN --mount=type=bind,from=builder,source=/wheels,target=/wheels \
+    pip install --no-index --find-links /wheels --root-user-action=ignore "pipelinemd[llm]"
+
+# A fixed numeric uid, not just a name: Kubernetes runners with runAsNonRoot
+# can only verify a number. GitLab's Docker executor makes the build directory
+# writable for whichever user the image declares.
+RUN useradd --create-home --uid 10001 --user-group pipelinemd
+USER 10001:10001
+WORKDIR /home/pipelinemd
+
+# GitLab runs job scripts through a shell, so a job using this image overrides
+# the entrypoint with `entrypoint: [""]`; the slim base keeps /bin/sh for that.
+# Everywhere else the image is the CLI itself: `docker run <image> distill -`.
+ENTRYPOINT ["pipelinemd"]
+CMD ["--help"]
+
+# `docker stop` (and compose and Kubernetes) send the image's stop signal.
+# Python running as PID 1 ignores SIGTERM but turns SIGINT into
+# KeyboardInterrupt, which the CLI already answers with "interrupted" and exit
+# 130 - so a stop takes a fraction of a second instead of waiting 10 s for
+# SIGKILL.
+STOPSIGNAL SIGINT

pipelinemd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rbalukja15
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pipelinemd-0.1.0/Makefile

@@ -0,0 +1,130 @@
+# Developer entry points. Everything here runs offline.
+#
+# Tools are invoked through the interpreter rather than by bare name: a
+# standalone `pytest` or `mypy` on PATH may belong to a different environment
+# than the one pipelinemd is installed into, and then the suite fails to import
+# the package it is meant to be testing. CI calls these same targets, so that
+# fix applies there too and the two cannot drift.
+PYTHON ?= python3
+PYTEST_ARGS ?=
+
+# The regression floor for `make gate`. rule@1 is 55/55 today, so 0.92 is 51/55
+# - the gate trips on the fifth regression. That headroom exists for one
+# reason: the corpus is meant to grow with observed traces, which will be
+# harder than the authored ones, and a gate that goes red the moment someone
+# commits a real failing log discourages the contribution this project most
+# needs. Single-case regressions stay visible either way, since `make eval`
+# names every miss.
+#
+# Adding hard traces will eventually push the rate under this floor, and the
+# right response is to lower it in a commit that says why. That is the point:
+# it makes the number move in review rather than silently.
+MIN_RULE_ACCURACY ?= 0.92
+
+# The class floor. Class is the input to the fix type, and yaml_patch is what
+# #24's MR generator acts on, so a regression here is the one with the sharpest
+# downside - it should fail a build, not just move a printed number. Class is
+# 51/62 today; 0.78 is 49/62, so the gate trips on the third regression. Same
+# rule as above: lowering it in a commit that says why is the intended response
+# to adding hard traces, not a failure.
+MIN_CLASS_ACCURACY ?= 0.78
+
+# Known gaps are excluded from every rate, so a rule that starts firing on one
+# moves no number. Zero tolerance here: the catalog growing a confident wrong
+# answer where it used to stay silent is a regression worth failing over.
+MAX_GAP_FALSE_POSITIVES ?= 0
+
+# The image `make image` builds and `make image-smoke` runs. PACKAGE_VERSION
+# is read from the same line hatch stamps the wheel with, so the smoke test
+# checks the image reports the version the package claims. Not plain VERSION:
+# that name is common enough in a CI environment to be picked up by accident.
+IMAGE ?= pipelinemd:dev
+PACKAGE_VERSION ?= $(shell sed -n 's/^__version__ = "\(.*\)"$$/\1/p' src/pipelinemd/__init__.py)
+SMOKE_TRACE ?= corpus/traces/runner-oom-killed.log
+
+.PHONY: help install lint format typecheck test eval gate check dist image image-smoke \
+	release-notes clean
+
+help:
+	@echo "install        editable install with dev extras"
+	@echo "lint           ruff check + ruff format --check"
+	@echo "format         ruff format (rewrites files)"
+	@echo "typecheck      mypy --strict"
+	@echo "test           pytest"
+	@echo "eval           score the deterministic pipeline against corpus/"
+	@echo "gate           eval, failing below rule@1 $(MIN_RULE_ACCURACY) or class $(MIN_CLASS_ACCURACY)"
+	@echo "check          lint + typecheck + test + gate, CI's test job"
+	@echo "dist           sdist + wheel into dist/, then twine check (needs build, twine)"
+	@echo "image          build the Docker image as $(IMAGE) (needs docker)"
+	@echo "image-smoke    run $(IMAGE) the ways CI and GitLab will (needs docker)"
+	@echo "release-notes  check \$$TAG against the version and changelog, print its notes"
+
+install:
+	$(PYTHON) -m pip install -e ".[dev]"
+
+lint:
+	$(PYTHON) -m ruff check src tests scripts
+	$(PYTHON) -m ruff format --check src tests scripts
+
+format:
+	$(PYTHON) -m ruff format src tests scripts
+
+typecheck:
+	$(PYTHON) -m mypy
+
+test:
+	$(PYTHON) -m pytest $(PYTEST_ARGS)
+
+eval:
+	$(PYTHON) -m pipelinemd eval
+
+gate:
+	$(PYTHON) -m pipelinemd eval \
+		--min-rule-accuracy $(MIN_RULE_ACCURACY) \
+		--min-class-accuracy $(MIN_CLASS_ACCURACY) \
+		--max-gap-false-positives $(MAX_GAP_FALSE_POSITIVES)
+
+check: lint typecheck test gate
+
+# --strict turns twine's warnings into failures: PyPI will not let a version be
+# uploaded twice, so a broken long description is cheaper to catch here.
+dist:
+	rm -rf dist
+	$(PYTHON) -m build
+	$(PYTHON) -m twine check --strict dist/*
+
+# Not part of `check`: that has to run anywhere Python does, and these need a
+# Docker daemon. CI runs them in a job of their own. buildx with --load works
+# with both the default builder and a docker-container one, and leaves the
+# result where `docker run` can find it.
+image:
+	docker buildx build --load --build-arg VERSION=$(PACKAGE_VERSION) -t $(IMAGE) .
+
+# Each line is a promise the README makes about the image. The output is
+# captured before it is searched, so a container that fails after printing
+# the right text still fails the target.
+image-smoke:
+	@echo "--version reports $(PACKAGE_VERSION)"
+	@out=$$(docker run --rm $(IMAGE) --version) && echo "$$out" && \
+		test "$$out" = "pipelinemd $(PACKAGE_VERSION)"
+	@echo "the default command runs"
+	docker run --rm $(IMAGE) > /dev/null
+	@echo "distill - reads a trace on stdin, offline, and finds its rule and evidence"
+	@out=$$(docker run --rm -i --network none $(IMAGE) distill --color never - < $(SMOKE_TRACE)) && \
+		echo "$$out" | grep -F "runner.oom-killed" && echo "$$out" | grep -E "^Evidence +[0-9]+ of"
+	@echo "the [llm] extra is installed"
+	docker run --rm --entrypoint python $(IMAGE) -c "import anthropic; print(anthropic.__version__)"
+	@echo "it does not run as root"
+	@uid=$$(docker run --rm --entrypoint id $(IMAGE) -u) && echo "uid $$uid" && test "$$uid" != 0
+	@echo "a shell script runs with the entrypoint cleared, as GitLab runs one"
+	docker run --rm --entrypoint "" $(IMAGE) sh -c 'pipelinemd --version'
+
+# The tag comes from the environment, never the command line, and is only ever
+# expanded by the shell inside quotes: a tag name is text someone else chose,
+# and make would paste it into the recipe unquoted.
+release-notes:
+	@$(PYTHON) scripts/release_notes.py "$$TAG"
+
+clean:
+	rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov dist build
+	find . -name __pycache__ -type d -prune -exec rm -rf {} +

pipelinemd-0.1.0/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.5
+Name: pipelinemd
+Version: 0.1.0
+Summary: GitLab CI/CD failure doctor - diagnoses failed pipelines and suggests fixes.
+Project-URL: Homepage, https://github.com/rbalukja15/pipelinemd
+Project-URL: Source, https://github.com/rbalukja15/pipelinemd
+Project-URL: Issues, https://github.com/rbalukja15/pipelinemd/issues
+Author: rbalukja15
+License: MIT License
+        
+        Copyright (c) 2026 rbalukja15
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cd,ci,claude,diagnostics,gitlab,logs,pipeline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# pipelinemd
+
+[![CI](https://github.com/rbalukja15/pipelinemd/actions/workflows/ci.yml/badge.svg)](https://github.com/rbalukja15/pipelinemd/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/rbalukja15/pipelinemd/blob/main/LICENSE)
+
+**GitLab CI/CD failure doctor** — takes a failed pipeline, works out what
+actually broke, and tells you how to fix it.
+
+A failed job's log is a terminal recording, not a report. It can run to tens of
+thousands of lines, most of them progress bars that rewrote themselves five
+hundred times, and the one line that matters is somewhere in the middle.
+pipelinemd does two things about that:
+
+1. **A deterministic distiller** replays the trace the way a terminal would,
+   strips the noise, scores every line for failure-likeness, and keeps only the
+   regions that explain the outcome — then matches them against a catalog of
+   **59 known CI failure signatures**, each with a real fix.
+   Every report is placed in one of seven **v1 failure classes** — `yaml`,
+   `ci_vars`, `image_pull`, `cache_artifact`, `test`, `runner`, `flaky` — with
+   the kind of fix it wants. Flaky comes from GitLab's retry history, not from
+   a guess: if another attempt of the same job passed on the same commit, it
+   says so.
+2. **An optional Claude diagnosis** reads only that distilled evidence and
+   names the root cause, separating the actual fault from its fallout — and
+   must cite the evidence lines it relied on. A diagnosis that cites nothing
+   real is rejected rather than reported.
+
+Every report says how far to trust it and what it cost. The **confidence** is
+never more than the weakest signal behind it; at low, the report says **needs
+human review** and why. The **cost** is $0 for rules alone, and an estimate
+from the API's own token counts when Claude was asked.
+
+The first half needs no API key, no model, and **no third-party packages at
+all**. The second is the upgrade.
+
+```
+$ pipelinemd diagnose https://gitlab.com/acme/web/-/jobs/98765
+
+pipelinemd  build (test) #98765
+  acme/web · ref main · exit code 1 · 47s
+  ERROR: Job failed: exit code 1
+  test → code_patch  ·  high  ·  from npm.lockfile-out-of-sync
+  confidence high
+  est. cost $0.0519 · claude-opus-5 · 5,210 in / 1,034 out tokens
+
+Diagnosis   high confidence · dependency
+
+  npm ci refused to install because package-lock.json no longer matches package.json.
+
+  Line 41203 shows npm rejecting the install outright rather than resolving it.
+  The lockfile still pins react@17 while package.json now asks for ^18 (line
+  41211), which is the change that broke the pair.
+
+Suggested fixes
+  1. Regenerate the lockfile and commit it
+
+       npm install
+       git add package-lock.json && git commit -m 'Regenerate lockfile'
+
+Rule matches
+  ● npm.lockfile-out-of-sync  package-lock.json is out of sync with package.json  L41203
+
+Evidence   9 of 41,284 lines · 100.0% reduced
+```
+
+---
+
+## Install
+
+```bash
+pip install pipelinemd              # core: distiller + rules, zero dependencies
+pip install 'pipelinemd[llm]'       # adds the Claude diagnosis layer
+```
+
+Requires Python 3.11+.
+
+Or skip Python altogether. The image has the `[llm]` extra installed, runs as
+an unprivileged user, and is built for amd64 and arm64:
+
+```bash
+docker run --rm ghcr.io/rbalukja15/pipelinemd:0.1 --version
+docker run --rm -i ghcr.io/rbalukja15/pipelinemd:0.1 distill - < build.log
+```
+
+The image runs as uid 10001, so to save a report redirect stdout rather than
+passing `-o` into a mounted directory, which that user may not be allowed to
+write to:
+
+```bash
+docker run --rm -i ghcr.io/rbalukja15/pipelinemd:0.1 distill - < build.log > report.txt
+```
+
+On rootful Linux Docker, `--user "$(id -u):$(id -g)"` also lets `-o` write into
+a mount; rootless Docker and Podman map that uid elsewhere, so redirect there.
+
+Tags follow the package: `0.1.0` exactly, `0.1` for the latest patch release,
+and `latest`. The image and the PyPI package are published by one workflow
+from one tag, so a version means the same thing in both
+([docs/releasing.md](https://github.com/rbalukja15/pipelinemd/blob/main/docs/releasing.md)).
+
+## Use
+
+### Diagnose a failed job or pipeline
+
+```bash
+pipelinemd diagnose https://gitlab.com/acme/web/-/jobs/98765
+pipelinemd diagnose https://gitlab.com/acme/web/-/pipelines/12345   # picks the failed job
+pipelinemd diagnose --project acme/web --pipeline 12345
+```
+
+Give it a pipeline and it finds the failed jobs for you; with more than one it
+diagnoses the first and names the rest (`--all-jobs` does them all).
+
+Credentials come from `--token`, `$PIPELINEMD_TOKEN`, `$GITLAB_TOKEN`,
+`$GITLAB_PRIVATE_TOKEN` or `$CI_JOB_TOKEN` — in that order, with the right
+header for each. Public projects need no token at all.
+
+### Distil a log you already have — fully offline
+
+```bash
+pipelinemd distill build.log
+kubectl logs job/ci-run | pipelinemd distill -
+```
+
+No network, no model, no key. Useful on its own for shrinking a log before
+pasting it anywhere.
+
+### Score it against the corpus
+
+```bash
+make eval
+```
+
+Runs the distiller and rule engine over 62 labelled traces in [`corpus/`](https://github.com/rbalukja15/pipelinemd/blob/main/corpus/README.md)
+and reports rule@1, evidence hit rate and exit-code accuracy per failure class.
+Offline and deterministic. Results and their caveats: [docs/evaluation.md](https://github.com/rbalukja15/pipelinemd/blob/main/docs/evaluation.md).
+
+`make gate` is the same run with CI's thresholds, and runs on every push — a
+catalog regression fails the build rather than being noticed later.
+
+### Browse the rule catalog
+
+```bash
+pipelinemd rules                        # all 59, grouped by category
+pipelinemd rules --category dependency
+pipelinemd rules --search docker
+pipelinemd explain npm.eresolve         # one rule in full, patterns included
+```
+
+### Inside GitLab CI
+
+Run with no target at all and it diagnoses the pipeline it is running in:
+
+```yaml
+diagnose:
+  stage: .post
+  image:
+    name: ghcr.io/rbalukja15/pipelinemd:0.1
+    entrypoint: [""]
+  when: on_failure
+  script:
+    - pipelinemd diagnose --format markdown -o diagnosis.md
+  artifacts:
+    when: always
+    paths: [diagnosis.md]
+```
+
+Nothing is installed when the job runs, so a failure is diagnosed even while
+PyPI is slow or unreachable. The `entrypoint: [""]` matters: the image's
+entrypoint is the CLI, and GitLab needs a shell to run `script:`.
+
+`CI_JOB_TOKEN` and `CI_PIPELINE_ID` are picked up automatically. Set
+`ANTHROPIC_API_KEY` as a masked CI variable to enable the diagnosis layer.
+
+Any image with Python 3.11+ works too, at the cost of an install on every
+failure:
+
+```yaml
+diagnose:
+  stage: .post
+  image: python:3.12-slim
+  when: on_failure
+  script:
+    - pip install 'pipelinemd[llm]'
+    - pipelinemd diagnose --format markdown -o diagnosis.md
+  artifacts:
+    when: always
+    paths: [diagnosis.md]
+```
+
+A ready-made job is in [`examples/gitlab-ci-diagnose.yml`](https://github.com/rbalukja15/pipelinemd/blob/main/examples/gitlab-ci-diagnose.yml).
+
+## Output formats
+
+| `--format` | For |
+| --- | --- |
+| `terminal` (default) | Reading it yourself. Colour honours `NO_COLOR` and non-TTY output. |
+| `markdown` | Pasting into a merge request or issue. Collapsible evidence. |
+| `json` | Other tooling. Versioned via `schema_version`. One job is one report object; several (`--all-jobs`) are `{"reports": [...], "cost": {...}}`, with the run's total cost beside them. |
+
+## How the distiller works
+
+Each stage is pure, independently testable, and does one thing:
+
+| Stage | What it removes or adds |
+| --- | --- |
+| **ANSI** | Colour codes, cursor moves, erase sequences, OSC hyperlinks. |
+| **Overwrites** | Replays `\r` and `\b` positionally — a progress bar that rewrote one line 500 times collapses to its final frame. |
+| **Sections** | Parses `section_start`/`section_end` markers into structured spans with durations, and attributes every line to the section it ran in. |
+| **Timestamps** | Strips the runner's optional per-line RFC3339 prefix. |
+| **Redaction** | Masks credential-shaped substrings *before* anything leaves the process. |
+| **Scoring** | Weights every line against 27 failure signals and 5 dampeners, so `0 failed, 12 passed` does not outrank the real fault. |
+| **Windowing** | Grows context around strong signals, merges overlapping windows, spends a fixed line budget on the best, and always keeps the tail — the runner writes its verdict there. |
+| **Collapsing** | Folds runs of near-identical lines into one entry with a repeat count. |
+
+Same trace in, same evidence out — which is what makes it cheap to cache and
+safe to assert on in tests.
+
+## Redaction
+
+pipelinemd can send evidence to an LLM, and you will paste its output into
+merge requests. GitLab masks *known* CI variables; anything a build tool prints
+itself does not get that protection. So before evidence reaches the prompt, the
+terminal, or the JSON output, these shapes are masked:
+
+GitLab tokens (`glpat-`, `glrt-`, …) · GitHub tokens · AWS access key ids ·
+Slack tokens · JWTs · credentials embedded in URLs · `Authorization:` headers ·
+`--password`/`--token` style flags · `KEY=value` where the key names a secret ·
+PEM private key blocks.
+
+Values that only look secret-shaped (`SECRET=false`, `***`) are left alone.
+This reduces exposure; it is not a guarantee — treat traces from untrusted
+pipelines accordingly.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | A report was produced. |
+| `2` | Usage error — bad URL, missing argument, unknown rule. |
+| `3` | GitLab error — unreachable, unauthorised, not found. |
+| `4` | Nothing to diagnose — the pipeline has no failed jobs. |
+
+A failed Claude call is **not** fatal: pipelinemd warns on stderr and reports
+the deterministic findings anyway.
+
+For how the pieces fit together, see [docs/architecture.md](https://github.com/rbalukja15/pipelinemd/blob/main/docs/architecture.md);
+for how a version reaches PyPI and the image, [docs/releasing.md](https://github.com/rbalukja15/pipelinemd/blob/main/docs/releasing.md).
+
+## Design notes
+
+- **The core has no dependencies.** Not "few" — none. It installs into any
+  runner image without dragging a tree behind it, which matters for a tool
+  whose whole job is to run in someone else's broken build.
+- **Rules first, model second.** Every rule fires without a network call. The
+  model is asked to do only what rules cannot: decide which of several signals
+  is the cause and which is the consequence.
+- **The model never sees a raw trace.** It sees distilled, redacted evidence
+  plus what the rules already concluded — which keeps requests small and cheap,
+  and keeps the model's effort on the judgement call.
+- **A diagnosis must point at something.** Every diagnosis cites line numbers,
+  and every cited number is resolved against the excerpt the model was shown.
+  Cite nothing real and the diagnosis is rejected; cite a mix and the invented
+  numbers are printed alongside it. Confident prose is easy; a claim you can
+  check is the product.
+- **Confidence is earned, not asserted.** An analysis is only as confident as
+  its weakest part — the rule, the model's own rating — and loses a level for
+  each sign of trouble. It stays high/medium/low: a decimal would claim a
+  calibration nothing here has, and `make eval` reports how often each level
+  is right instead.
+- **The distiller is pure.** No clock, no network, no randomness.
+
+## Contributing a rule
+
+Rules live in `src/pipelinemd/rules/catalog.py`. A good one is narrow: anchor
+`patterns` to text the tool actually prints, write `explanation` as *why this
+happens*, and make each entry of `fixes` something someone can do. Add a
+fixture under `tests/fixtures/traces/` and assert the rule fires on it.
+
+Then give it a v1 class in `RULE_CLASS` in `src/pipelinemd/taxonomy.py` — the
+suite fails until you do. Choose from what the failure *is*, and only use
+`flaky` if it is transient whatever the environment; anything that is merely
+often transient is flaky only when retry history says so.
+
+## License
+
+MIT — see [LICENSE](https://github.com/rbalukja15/pipelinemd/blob/main/LICENSE).