ci-doctorr 0.1.0__tar.gz

ci_doctorr-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,10 @@
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
+
+- **MCP tool** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.
+- **Shell** (always works): `codegraph explore "<symbol names or question>"` prints the same output.
+
+If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
+<!-- CODEGRAPH_END -->

ci_doctorr-0.1.0/.claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__codegraph__*"
+    ]
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "codegraph prompt-hook"
+          }
+        ]
+      }
+    ]
+  }
+}

ci_doctorr-0.1.0/.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

ci_doctorr-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: release
+
+# On every push to master: analyze conventional commits, bump the version + tag,
+# generate a GitHub Release from the commits, attach the Docker image as a gzipped
+# tar, and publish to PyPI. If no releasable commit (feat/fix/BREAKING) is found, it no-ops.
+on:
+  push:
+    branches: [master]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: write   # push the version-bump commit + tag, create/upload the Release
+  id-token: write   # PyPI Trusted Publishing (OIDC) — no stored token needed
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # full history so commit analysis works
+
+      # Bump version (pyproject), update CHANGELOG.md, commit, tag vX.Y.Z, push,
+      # create the GitHub Release from the commits, and build the sdist+wheel into dist/.
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build Docker image and save as gzipped tar
+        if: ${{ steps.release.outputs.released == 'true' }}
+        run: |
+          IMAGE="ci-doctor:${{ steps.release.outputs.version }}"
+          docker build -t "$IMAGE" .
+          docker save "$IMAGE" | gzip -9 > "ci-doctor-${{ steps.release.outputs.version }}-image.tar.gz"
+
+      - name: Attach Docker image to the release
+        if: ${{ steps.release.outputs.released == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "${{ steps.release.outputs.tag }}" "ci-doctor-${{ steps.release.outputs.version }}-image.tar.gz" --clobber
+
+      # Trusted Publishing: authenticates via OIDC (id-token: write above). No token/secret.
+      # Requires a matching publisher on PyPI (repo fennet82/ci-doctor, workflow release.yml).
+      - name: Publish distributions to PyPI
+        if: ${{ steps.release.outputs.released == 'true' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Upload the built distributions to the GitHub Release
+        if: ${{ steps.release.outputs.released == 'true' }}
+        uses: python-semantic-release/publish-action@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.release.outputs.tag }}

ci_doctorr-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+# ci-doctor's own artifacts
+report.md
+report.json
+# local Claude Code settings / temp
+.claude/settings.local.json
+.claude/*.tmp*

ci_doctorr-0.1.0/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": [
+        "serve",
+        "--mcp"
+      ]
+    }
+  }
+}

ci_doctorr-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-07-24)
+
+### Documentation
+
+- Astro documentation site + GitHub Actions example
+  ([`522cf47`](https://github.com/fennet82/ci-doctor/commit/522cf476ca450fd37bcfd06344518f642eeaaae5))
+
+- docs/site: static Astro site (overview, requirements, configuration, usage, CI/CD examples) with a
+  shared layout, light/dark styles, and Shiki-highlighted snippets. Builds to dist/ (npm run build);
+  node_modules/dist gitignored. - examples/github-actions.example.yml: workflow_run-triggered
+  analyzer job - README: link to the docs site
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+
+- Refresh README (accurate test count, example endpoint); bump Astro to 7
+  ([`03aeabf`](https://github.com/fennet82/ci-doctor/commit/03aeabf4f6fc9a8babd1c09b386b1d506bec9a6a))
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+
+### Features
+
+- Automated release pipeline and publishable package
+  ([`8339e19`](https://github.com/fennet82/ci-doctor/commit/8339e199cb5f90b3812d0888ef6db039653586a4))
+
+Push to master -> python-semantic-release bumps the version from conventional commits, tags,
+  generates the GitHub Release, builds the sdist/wheel; the workflow then attaches the Docker image
+  (gzipped tar) to the release and publishes to PyPI via Trusted Publishing (OIDC, no token).
+
+Distribution renamed to `ci-doctorr` (the `ci-doctor` name was taken on PyPI); the import package
+  `ci_doctor` and the CLI command `ci-doctor` are unchanged.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

ci_doctorr-0.1.0/Dockerfile

@@ -0,0 +1,10 @@
+# Self-contained image. Built where there is internet; needs none at runtime
+# (ci-doctor only ever talks to your configured GitLab and LLM endpoints).
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY . /app
+RUN pip install --no-cache-dir .
+
+# No network at job runtime, no telemetry, no update checks.
+ENTRYPOINT ["ci-doctor"]

ci_doctorr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elad Cohen
+
+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.

ci_doctorr-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: ci-doctorr
+Version: 0.1.0
+Summary: Postmortem CI failure analyzer: deterministic phase attribution plus one LLM explanation. Read-only, air-gap friendly.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: openai>=2.48.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-gitlab>=8.4.0
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: litellm>=1.40; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == 'litellm'

ci_doctorr-0.1.0/README.md

@@ -0,0 +1,221 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/site/public/ci-doctor-logo-dark.svg">
+    <img src="docs/site/public/ci-doctor-logo.png" alt="ci-doctor" width="540">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Root-cause analysis for CI/CD.</strong><br>
+  A postmortem step that runs when a pipeline fails, works out <em>where</em> and <em>why</em> it broke,
+  and emits a structured report — without ever touching your code.
+</p>
+
+<p align="center">
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white">
+  <img alt="Providers: GitLab | GitHub" src="https://img.shields.io/badge/providers-GitLab%20%7C%20GitHub-fc6d26">
+  <img alt="Read-only, always exit 0" src="https://img.shields.io/badge/read--only-always%20exit%200-2dd4bf">
+  <img alt="LLM: bring your own (optional)" src="https://img.shields.io/badge/LLM-bring%20your%20own%20·%20optional-1f6feb">
+</p>
+
+---
+
+When a pipeline fails, the logs are long and loud. An LLM handed the whole trace will
+confidently blame the runner or a missing cache — because that text is alarming — even
+when the real failure was an `exit code 1` three sections down. ci-doctor fixes that with
+one rule:
+
+> **Deterministic code decides *where* the job failed. The LLM only explains *why*.**
+
+Phase attribution is a pure function of job metadata and log structure, computed **before**
+any model is called. A loud, non-fatal `WARNING:` can never outrank the actual failure. If
+the classifier is wrong, that's a bug with a failing test — not a prompt to tune.
+
+## Features
+
+- **Deterministic phase attribution** — a pure, fully-tested classifier decides where a job
+  broke (`provision` · `prepare` · `fetch` · `script` · `post`) from metadata and log
+  structure. Non-fatal `WARNING:` lines can never be blamed.
+- **Read-only and safe** — never edits code, commits, or opens MRs, and **always exits 0**,
+  so it can't change your pipeline's status or hide the real failure.
+- **Useful with no LLM** — ships a deterministic report out of the box: phase, reason,
+  terminal command, evidence excerpt, and templated remediation.
+- **Bring-your-own model** — optional LLM step via `openai` (any OpenAI-compatible endpoint),
+  `litellm`, `anthropic`, or the local `claude` CLI, selected by config.
+- **GitLab & GitHub** — one provider-neutral core; the GitHub adapter was added with *zero*
+  changes to core.
+- **Air-gap friendly** — no telemetry, no update checks, no runtime downloads; ship as a
+  self-contained Docker image or an offline wheel bundle.
+- **Secret redaction** — scrubs secrets from the prompt *and* the report (round-trip tested).
+- **Structured output** — a rich terminal report, `report.md` + `report.json` artifacts (with
+  a self-contained `handoff_prompt` you can paste into a coding agent), and one idempotent
+  MR/PR note.
+
+## How it works
+
+```
+acquire → segment → attribute → denoise → extract → budget → (LLM) → render / deliver
+          └── deterministic: decides WHERE it failed ──┘        └── explains WHY ──┘
+```
+
+1. **Acquire** the failed jobs and their logs (a missing log is valid data — the
+   "never got a runner" case).
+2. **Segment** the trace into sections (GitLab `section_*` markers / GitHub `##[group]`).
+3. **Attribute** the failure to a phase — the pure classifier, first-match-wins precedence
+   ladder with a `WARNING:`-is-never-fatal rule.
+4. **Denoise / extract / budget** the blamed section into a small, high-signal evidence slice
+   (ANSI/CR/dedup denoising, anchored windows, token budgeting — every truncation is visible).
+5. **LLM (optional)** explains the cause *within* the already-decided phase, returning a
+   validated JSON report. Disabled or unreachable → deterministic report instead.
+6. **Render / deliver** to the terminal, `report.md`/`report.json`, and an idempotent MR/PR note.
+
+## Install
+
+> On PyPI the distribution is **`ci-doctorr`** (the `ci-doctor` name was taken); the import package is `ci_doctor` and the command stays `ci-doctor`.
+
+```sh
+git clone https://github.com/fennet82/ci-doctor
+cd ci-doctor
+uv sync                       # or: pip install .
+
+# optional LLM backends:
+uv sync --extra anthropic     # or: pip install '.[anthropic]'  /  '.[litellm]'  /  '.[all]'
+```
+
+Or build the self-contained image:
+
+```sh
+docker build -t ci-doctor .
+```
+
+## Quickstart
+
+```sh
+# Replay a captured log offline — no network, no LLM:
+uv run ci-doctor analyze --from-file failing-job.log
+
+# Against a live pipeline (reads $CI_PIPELINE_ID etc. inside CI):
+uv run ci-doctor analyze "$CI_PIPELINE_ID"
+```
+
+```
+ci-doctor analyze [RUN_ID] [OPTIONS]
+
+  --from-file PATH   Replay a raw job log offline (no network, no LLM).
+  --job-id TEXT      Analyze a single job id.
+  --config PATH      Path to .ci-doctor.yml.
+  --no-color         Disable coloured output (also honours NO_COLOR).
+  -v, --verbose      Enable debug logging.
+  --version          Show version and exit.
+```
+
+## Configuration
+
+Layered and pydantic-validated — `defaults.yml` < repo `.ci-doctor.yml` < `CI_DOCTOR_*` env
+< CLI flags. Unknown keys are an error. Minimal config:
+
+```yaml
+provider: gitlab
+
+gitlab:
+  base_url: https://gitlab.com        # default; override for self-hosted
+  token_env: CI_DOCTOR_GITLAB_TOKEN   # or gitlab.token_file for a secret mount
+
+llm:
+  enabled: true                       # false => deterministic-only report
+  backend: openai                     # openai | litellm | anthropic | claude_code
+  model: qwen2.5-coder:32b
+  api_base: http://openai-compatible-endpoint.internal:8000/v1
+```
+
+Nested env vars use `__`: `CI_DOCTOR_LLM__MODEL=…`. See the full reference in
+[docs/site](docs/site) or [docs/PLAN.md §9](docs/PLAN.md).
+
+### LLM backends
+
+| `llm.backend` | Calls | Needs |
+|---|---|---|
+| `openai` *(default)* | any OpenAI-compatible endpoint (Ollama, vLLM, llama.cpp, gateway) | `model` + `api_base` — base install |
+| `litellm` | any [litellm](https://docs.litellm.ai/) provider | `model`; `pip install '.[litellm]'` |
+| `anthropic` | Claude via the official SDK (defaults to `claude-opus-4-8`) | API key / `ant` profile; `'.[anthropic]'` |
+| `claude_code` | the local `claude` CLI, headless | `claude` on PATH |
+
+The LLM step is optional throughout — when it's disabled, unconfigured, or unreachable,
+ci-doctor emits the deterministic report instead of failing.
+
+## Use it in CI
+
+**GitLab** (`.gitlab-ci.yml`) — runs only on failure, always exits 0:
+
+```yaml
+ci-doctor:
+  stage: .post
+  image: registry.internal.example.com/ci-doctor:latest
+  rules:
+    - when: on_failure
+  allow_failure: true
+  variables:
+    CI_DOCTOR_GITLAB_TOKEN: "$CI_DOCTOR_TOKEN"
+  script:
+    - ci-doctor analyze "$CI_PIPELINE_ID"
+  artifacts:
+    when: always
+    paths: [report.md, report.json]
+```
+
+**GitHub Actions** — triggered on a failed workflow run. Full examples in
+[`examples/`](examples/).
+
+## Air-gapped / offline
+
+ci-doctor makes no network calls except to the GitLab/GitHub and LLM endpoints you
+configure. Build once where there is internet, then ship inside — a Docker image, or an
+offline wheel bundle (`pip install --no-index --find-links ./wheels ci-doctorr`). See
+[docs/OFFLINE.md](docs/OFFLINE.md).
+
+## Documentation
+
+A full documentation site (overview, requirements, configuration, usage, CI/CD examples)
+lives in [`docs/site/`](docs/site) — built with Astro:
+
+```sh
+cd docs/site && npm install && npm run dev    # or: npm run build -> dist/
+```
+
+The original design spec is [docs/PLAN.md](docs/PLAN.md).
+
+## Development
+
+```sh
+uv sync
+uv run pytest        # 88 tests, no network, no LLM
+```
+
+```
+ci_doctor/
+  cli.py            typer entrypoint (always exits 0)
+  config/           pydantic schema + defaults.yml + layered loader
+  core/             provider-neutral: models, ports, attribution (pure), denoise,
+                    extract, budget, redact, analyze
+  llm/              Report schema, prompt templates, backends (openai/litellm/anthropic/claude_code)
+  render/           terminal (rich), markdown, json
+  providers/
+    gitlab/         python-gitlab adapter + segmenter + reasons
+    github/         GitHub Actions adapter + segmenter + reasons
+tests/              fixtures + golden-file attribution suite
+docs/site/          Astro documentation site
+examples/           .gitlab-ci.yml + GitHub Actions snippets
+Dockerfile
+```
+
+### Design guardrails
+
+- The LLM never selects the failure phase — that lives in `core/attribution.py`.
+- `core/` depends on no provider or vendor SDK — `grep -riE 'gitlab|github|openai' ci_doctor/core/`
+  is clean. Adding the GitHub adapter required no core changes.
+- `attribution.py` is a pure function — no I/O, network, or clock.
+- Always exits 0 · never emits unredacted log content · every truncation is visible.
+
+## License
+
+[MIT](LICENSE) © Elad Cohen

ci_doctorr-0.1.0/ci_doctor/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ci-doctorr")  # PyPI distribution name (import pkg stays ci_doctor)
+except PackageNotFoundError:  # not installed (e.g. running from a raw checkout)
+    __version__ = "0.0.0"

ci_doctorr-0.1.0/ci_doctor/cli.py

@@ -0,0 +1,211 @@
+"""ci-doctor CLI (typer).
+
+`analyze <pipeline_id>` against live GitLab, or `--from-file` to replay a raw log
+offline. Both run the same pipeline: segment -> classify -> evidence -> report ->
+render/deliver.
+
+Guardrail #3: the analyzer must never change a pipeline's outcome, so `main()`
+catches everything and always exits 0.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import typer
+
+from ci_doctor import __version__
+from ci_doctor.config.loader import load_config
+from ci_doctor.core.models import FailureReason, Job, Run
+
+app = typer.Typer(add_completion=False, help="Explain why a CI pipeline failed (read-only postmortem).")
+
+log = logging.getLogger("ci_doctor.cli")
+
+
+def _configure_logging(verbose: bool) -> None:
+    """`--verbose` (or CI_DOCTOR_LOG_LEVEL=DEBUG) turns on debug logs across ci_doctor.*."""
+    level_name = os.environ.get("CI_DOCTOR_LOG_LEVEL", "").upper()
+    level = logging.DEBUG if verbose else getattr(logging, level_name, logging.INFO)
+    logging.getLogger("ci_doctor").setLevel(level)
+    if verbose:
+        log.debug("verbose logging enabled")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    """Explain why a CI pipeline failed (read-only postmortem)."""
+
+
+@app.command()
+def analyze(
+    run_id: str = typer.Argument(None, help="Pipeline/run id. Omit when using --from-file."),
+    from_file: Path = typer.Option(
+        None, "--from-file", help="Replay a raw job log offline (no network, no LLM)."
+    ),
+    job_id: str = typer.Option(None, "--job-id", help="Analyze a single job id."),
+    config_path: Path = typer.Option(None, "--config", help="Path to .ci-doctor.yml."),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable coloured terminal output."),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable debug logging."),
+) -> None:
+    _configure_logging(verbose)
+    cfg = load_config(repo_config=config_path)
+    log.debug("provider=%s from_file=%s run_id=%s job_id=%s", cfg.provider, from_file, run_id, job_id)
+
+    run = provider = None
+    if from_file is not None:
+        results = [_process(job, cfg) for job in _run_from_file(from_file).jobs]
+    elif run_id is not None:
+        run, provider, results = _analyze_live(run_id, cfg, job_id)
+    else:
+        typer.echo("nothing to do: pass a pipeline id, or --from-file to replay a log.", err=True)
+        return
+
+    _deliver(results, cfg, no_color=no_color)
+    _maybe_post_mr(provider, run, results, cfg)
+
+
+def _make_provider(cfg):
+    # Import adapters lazily so `core` and the offline path never pull a provider in.
+    if cfg.provider == "gitlab":
+        from ci_doctor.providers.gitlab.provider import GitLabProvider
+
+        return GitLabProvider(cfg)
+    if cfg.provider == "github":
+        from ci_doctor.providers.github.provider import GitHubProvider
+
+        return GitHubProvider(cfg)
+    raise ValueError(f"unsupported provider: {cfg.provider}")
+
+
+def _make_segmenter(cfg):
+    if cfg.provider == "github":
+        from ci_doctor.providers.github.segmenter import GitHubSegmenter
+
+        return GitHubSegmenter()
+    from ci_doctor.providers.gitlab.segmenter import GitLabSegmenter
+
+    return GitLabSegmenter()
+
+
+def _analyze_live(run_id: str, cfg, job_id: str | None):
+    from ci_doctor.core.select import select_failed_jobs
+
+    provider = _make_provider(cfg)
+    run = provider.fetch_run(run_id)
+    jobs = select_failed_jobs(run.jobs, cfg.analysis.include_allowed_failures)
+    if job_id is not None:
+        jobs = [j for j in jobs if j.id == job_id]
+    log.debug("run %s: %d jobs, %d failed and selected", run_id, len(run.jobs), len(jobs))
+
+    selected = jobs[: cfg.analysis.max_jobs_analyzed]
+    log.info("analyzing %d failed job(s) from run %s", len(selected), run_id)
+    results = []
+    for job in selected:
+        job.log = provider.fetch_job_log(job)
+        results.append(_process(job, cfg))
+    return run, provider, results
+
+
+def _run_from_file(path: Path) -> Run:
+    """Load a raw job log into the domain model for offline replay."""
+    log = path.read_text()
+    job = Job(id="local", name=path.stem, status="failed",
+              failure_reason=FailureReason.UNKNOWN, log=log)
+    return Run(id="local", jobs=[job])
+
+
+def _process(job: Job, cfg):
+    """Segment + classify + assemble evidence + produce the report for one job.
+
+    Deterministic when the LLM is disabled/unconfigured; one LLM call otherwise.
+    GitLab log format is assumed (the only provider today); a provider-driven
+    segmenter arrives with M6.
+    """
+    from ci_doctor.core.analyze import build_bundle
+    from ci_doctor.core.attribution import attribute
+    from ci_doctor.core.phases import assign_phases
+    from ci_doctor.llm.report import produce_report
+
+    job.sections = _make_segmenter(cfg).segment(job.log or "")
+    log.debug("job %s: %d top-level sections", job.name, len(job.sections))
+    assign_phases(job.sections, cfg.phases)
+    attr = attribute(job, job.sections)
+    log.debug("job %s: attribution phase=%s reason=%s rule=%s confidence=%s",
+              job.name, attr.phase, attr.reason, attr.rule_id, attr.confidence)
+    bundle = build_bundle(job, attr, job.sections, cfg)
+    report = produce_report(job, attr, bundle, cfg)
+    log.debug("job %s: report category=%s confidence=%s infra=%s",
+              job.name, report.category, report.confidence, report.is_infra_not_code)
+    return job, attr, report
+
+
+def _deliver(results, cfg, *, no_color: bool) -> None:
+    import json
+    import os
+
+    from ci_doctor.render.markdown import MarkdownRenderer
+    from ci_doctor.render.terminal import render_terminal
+
+    if not results:
+        typer.echo("no failed jobs to analyze.")
+        return
+
+    reports = [report for *_, report in results]
+    if cfg.output.terminal:
+        wrap = os.environ.get("GITLAB_CI") == "true"  # collapsible only inside GitLab CI
+        for report in reports:
+            render_terminal(report, no_color=no_color, wrap_section=wrap)
+
+    md = "\n\n---\n\n".join(MarkdownRenderer().render(r) for r in reports)
+    Path(cfg.output.markdown_path).write_text(md)
+    Path(cfg.output.json_path).write_text(json.dumps([r.model_dump(mode="json") for r in reports], indent=2))
+    typer.echo(f"wrote {cfg.output.markdown_path} and {cfg.output.json_path}", err=True)
+
+
+def _maybe_post_mr(provider, run, results, cfg) -> None:
+    if not cfg.output.mr_note or provider is None or run is None or run.mr is None:
+        return
+    reports = [report for *_, report in results]
+    if not any(r.confidence in ("medium", "high") for r in reports):  # user's gate
+        typer.echo("MR note skipped: confidence below medium.", err=True)
+        return
+
+    from ci_doctor.render.markdown import MarkdownRenderer
+
+    body = "\n\n---\n\n".join(MarkdownRenderer().render(r) for r in reports)
+    marker = f"<!-- ci-doctor:pipeline:{run.id} -->"
+    try:
+        provider.post_note(run.mr, body, marker)
+        typer.echo("posted/updated MR note.", err=True)
+    except Exception as exc:  # noqa: BLE001 - delivery must never break the run
+        typer.echo(f"MR note failed (ignored): {exc}", err=True)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="ci-doctor [%(levelname)s] %(message)s")
+    try:
+        app()
+    except SystemExit:
+        # typer/click signal both normal and usage exits via SystemExit; force 0.
+        raise SystemExit(0)
+    except BaseException as exc:  # noqa: BLE001 - analyzer must never alter pipeline outcome
+        print(f"ci-doctor: internal error, exiting 0 to preserve pipeline status: {exc}", file=sys.stderr)
+        raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    main()