markov-ci
Markov-governed, self-healing CI/CD — governance for agentic pipelines.
markov-ci models an agentic CI/CD pipeline as an absorbing Markov chain — a small
state space, measured transition probabilities, and three designed terminal outcomes —
instead of a deterministic DAG governed by brittle if/else retry rules. From that
model it forecasts what your agents will cost, governs them with hard limits at
runtime, and learns from its own telemetry.
Status: pre-alpha. Private during initial development; intended for open-source release under Apache-2.0. The CLI, config, and telemetry contracts are specified and documented; implementation lands per the WBS.
The problem
CI/CD stopped being deterministic, for two reasons:
- Ephemeral infrastructure — distributed suites, cloud runners, spot interruptions: identical commits now flake.
- AI agents in the loop — agents triage, patch, and refactor inside pipelines, with probabilistic behavior (fix ~75% / loop ~15% / regress ~10% is typical).
Governed by rigid rules, probabilistic agents give you one of two disasters: guardrails so strict the agent never helps, or runaway retries that burn tokens, hang PRs, and silently weaken your tests. And nobody can answer "should the agent get 2 retries or 10?" with a number.
What it does
| Capability | You get | |
|---|---|---|
| 📊 | Forecast | Expected agent attempts, token spend, and outcome probabilities per failure category — before you enable anything. N = (I−Q)⁻¹ · B = N·R · t = N·1 · C = N·c |
| 🛡️ | Govern | Budget, attempt-cap, and confidence gates; enforced write allowlists; test-weakening hard-stopped; patches isolated to ai-fix/* branches; humans always merge |
| 🔁 | Learn | One versioned JSONL event per state hop; the transition matrix recomputes from your own telemetry, per failure category and per agent harness |
Why it cannot run away: attempt caps remove loop-back edges at assembly time, so every chain markov-ci can execute is absorbing by construction. Termination is a theorem, not a timeout — even under adversarial probabilities.
Quick start
The commands below are the v0.1.0 contract. Docs-are-tests: CI runs them verbatim (see
docs/quick-start.md, executed bytests/unit/docs/test_docs_are_tests.py).
git clone https://github.com/deghosal-2026/markov-ci && cd markov-ci
pip install -e ".[dev]"
markov-ci analyze # zero-config: prints the worked example
markov-ci analyze --category unit_assertion # per-attempt decay + expected cost
markov-ci run examples/01-lint-error/config.yaml \
--junit examples/01-lint-error/report.xml \
--repo examples/01-lint-error/repo --seed 42
No API keys, no network — the default agent is a seeded, offline simulator. See the quick start for the full five-minute path.
How it works
A pipeline becomes a chain of decision states with three absorbing outcomes:
s0 verify ─▶ s1 triage ─▶ s2 agent ─▶ s3 sandbox ─▶ s4 regression ─▶ a1 ready-for-review
▲ │ ▲
└──── loop ────┘ escalate ─▶ a2 · budget ─▶ a3
(attempt index in the state: s2#1, s3#2, …)
Per-attempt decay is modeled by step-augmented states (s2#1, s2#2, …), which
keeps the chain genuinely Markov so the closed-form math stays exact. The engine
evaluates gates strictly in order — budget → attempt cap → confidence — and every
hop emits a versioned telemetry event. Read
the math, derived or the
architecture.
Documentation
Everything below also builds as a site — run mkdocs serve.
Start here
- Overview — what & why — the concept in depth
- Quick start — first forecast in five minutes
- Architecture — modules and data flow
Guides
- Tutorials: 01 — lint fix · 02 — decay → escalate · 03 — infra timeout · 04 — runner pools · 05 — GitHub Actions · 06 — adversarial runaway · 07 — cheating agent
- Examples: 01 lint error · 02 assertion decay · 03 infra timeout · 04 runner pools · 05 GitHub Actions (live) · 06 adversarial runaway · 07 cheating agent
- How-to: GitHub Actions · GitLab & Jenkins · run the examples in Docker · use a local LLM
Reference & explanations
How this project is specified
- PRD · spec contracts · ADRs · WBS & issues
Project files
Roadmap
| Release | Theme | Highlights |
|---|---|---|
| v0.1.0 | Absorption | Math core · policy engine · triage · simulated agent · guardrails · runtime · telemetry · CLI · offline proof-suite demos 01–03, 06–07 |
| v0.2.0 | Capacity & reach | GitHub Action · queueing (Erlang-C + DES) · simulate · recompute · harness adapters (Claude Code, OpenCode, Aider) |
| v0.3.0 | Live operations | MCP governance server · currency cost model · drift alerts · community harness templates |
Full ticket-level breakdown: docs/WBS.md.
What it is not
Not an agent harness (it governs harnesses) · not auto-merge (a1 is always a human
decision) · not a CI replacement (it plugs into GitHub Actions / GitLab / Jenkins) ·
not a dashboard (CLI + JSON events) · no telemetry leaves your machine.
Contributing
Contributions are welcome once the repository goes public. Start with CONTRIBUTING.md and the ADRs — every design decision and its rationale is recorded there.
License
Metadata
Release files for markov-ci 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| markov_ci-0.1.0.tar.gz | 159.5 kB | Without provenance | Details for markov_ci-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| markov_ci-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for markov_ci-0.1.0-py3-none-any.whl |
Total release size: 221.1 kB
Release files / markov_ci-0.1.0.tar.gz
| Download URL | markov_ci-0.1.0.tar.gz |
|---|---|
| Size | 159.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1ff542c35909a12da52546fadd12ffc89149e691e75c293a9f27c6879b245a24
|
|
BLAKE2b-256 checksum How to use checksums |
24771f26b1786a6d491a09c31234f36621e6bf7104e245a7fd7a033006c441b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / markov_ci-0.1.0-py3-none-any.whl
| Download URL | markov_ci-0.1.0-py3-none-any.whl |
|---|---|
| Size | 61.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6aa353c9af865385de45123b4286b418bc7ae22974ceddc9bb78c10fb5aaedf8
|
|
BLAKE2b-256 checksum How to use checksums |
d6ca24e4e983913f0f177bf10ea13f3a1a8b28806b183aaa3f57f72289bc2c5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for markov-ci 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.