markov-ci
Markov-planned, guardrailed 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. The chain is
the planning model (it forecasts cost and attempts and sizes the caps); at runtime a
bounded governor admits, checks and stops the repair loop — it does not sample the
chain. From the model markov-ci forecasts what your agents will cost, governs
them with hard limits at runtime, and learns from its own telemetry (ADR-0014).
Status: pre-1.0.
v0.1.1("Trust") is the current release — the security and correctness fixes from the v0.1.1 review. Upgrade fromv0.1.0: that release ran the harness prompt through a shell (a remote-code-execution path);v0.1.1makes harness invocation argv-only (ADR-0016). See the CHANGELOG and SECURITY.md. The public API is not yet stable.
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 a commonly cited ballpark, not a markov-ci measurement).
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 — after the cap Q is
nilpotent, so absorption is a property of the model. The runtime stops via its
attempt counter plus per-call timeouts (a hung child is killed on timeout), so a run is
bounded even under adversarial probabilities.
⚠️ Security notice (v0.1.1). For
pull_requestevents from untrusted authors (forks), enable container isolation (container: python:3.12-slim, or the--container-imageflag) so PR code cannot reach host credentials; it is the recommended default for fork PRs. Without it, do not setadapter: harnesson untrusted forks — useadapter: simulated. See SECURITY.md and ADR-0013.
Quick start
The commands below are the v0.1.1 contract. Docs-are-tests: CI runs them verbatim (see
docs/quick-start.md, executed bytests/unit/docs/test_docs_are_tests.py). Installv0.1.1or later —v0.1.0carries the harness shell-injection advisory (ADR-0016, GHSA-5jj3-gcw8-pm5g).
pip install -U "markov-ci>=0.1.1" # PyPI; 3.11–3.13
# until 0.1.1 is on PyPI, install the release tag:
# pip install "markov-ci @ git+https://github.com/deghosal-2026/markov-ci@v0.1.1"
markov-ci analyze # zero-config: prints the worked example
markov-ci analyze --category unit_assertion # per-attempt decay + expected cost
# the offline demos live in the repo:
git clone https://github.com/deghosal-2026/markov-ci && cd markov-ci
markov-ci run examples/01-lint-error/config.yaml \
--junit examples/01-lint-error/report.xml \
--repo examples/01-lint-error/repo --seed 42
markov-ci is published on PyPI as markov-ci
(Trusted Publishing, PEP 740 build provenance). 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 worktree validation ─▶ 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 | Shipped: math core · policy engine · triage · simulated, harness and local-LLM agents · guardrails · runtime · telemetry + recompute · queueing (Erlang-C + DES) · CLI (validate/analyze/run/simulate/queue/recompute) · composite GitHub Action · offline demos 01–07 |
| v0.1.1 | Trust | Shipped (PyPI): argv-only harness (ADR-0016) · diff-derived guardrails · worktree validation + opt-in container isolation · hard budgets (remaining-timeout → a3) · patch delivery (--output-patch, --publish) · model/runtime honesty (analyze from s1) · hardened test suite · field-test evidence |
| v0.2.0 | Capacity & reach | Live harness verification (Claude Code / OpenCode / Aider) · MCP tool surface · drift/windowing |
| v0.3.0 | Live operations | MCP governance server · currency cost model · drift alerts · community harness templates |
Full ticket-level breakdown: v0.1.1 WBS · v0.1.0 WBS.
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.1
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.1.tar.gz | 219.9 kB | Without provenance | Details for markov_ci-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| markov_ci-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for markov_ci-0.1.1-py3-none-any.whl |
Total release size: 296.6 kB
Release files / markov_ci-0.1.1.tar.gz
| Download URL | markov_ci-0.1.1.tar.gz |
|---|---|
| Size | 219.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14f7051192ab3ad08ed51b45a435c4f8bc4b1091ff7ed544660d6f8e2f00c53d
|
|
BLAKE2b-256 checksum How to use checksums |
b443d1f2bce5c7855e69228d4f365f75dc734954d60e673a1f3918e298193713
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.5
|
Release files / markov_ci-0.1.1-py3-none-any.whl
| Download URL | markov_ci-0.1.1-py3-none-any.whl |
|---|---|
| Size | 76.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b82a8707a35095e03a3f7b8ea889b3626308c1e27480bbd0270cd526422c486f
|
|
BLAKE2b-256 checksum How to use checksums |
88e3d36c2b6f18083fe51e0be3ec7c8e5d40c07311a0587923526c4c7da2dd2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.5
|
Security for markov-ci 0.1.1
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.