One sentence
foreman-plane is a governance plane that runs outside the agent harness. DeepSeek Harness, Claude Code, Codex and any CLI agent are interchangeable execution bodies. What the plane owns is the part a session cannot own: dispatch, dependency gating, objective acceptance and an append-only ledger.
A promise the agent forgot is not a promise. The verdict is derived from files on disk, so it outlives the session that produced it.
┌──────────────────┐ ┌──────────────────────┐
│ execution bodies │ │ foreman-plane │
│ Claude Code │ ─────▶ │ dispatch │
│ Codex │ │ dependency gates │
│ DeepSeek Harness │ ◀───── │ objective acceptance │
│ any CLI agent │ │ append-only ledger │
└──────────────────┘ └──────────────────────┘
MCP / stdio — JSON-RPC 2.0, one JSON object per line
- Cross session — the ledger outlives every conversation.
- Cross instance — several agents share one task graph.
- Cross day — a task dispatched today can be resumed tomorrow by any body.
- Zero intrusion — the plane is a plain process, no agent framework has to be patched.
Zero third-party dependencies. Python ≥ 3.10, standard library only.
Why foreman-plane?
| Capability | What it changes |
|---|---|
| Two-level dependency gate | A card with [depends_on] cannot start until every upstream is terminal, passed and accepted. [needs_api] is the soft level: a missing artefact is reported, the task still runs. |
| Objective acceptance | Pass and fail are computed from the artefact — min_bytes, sha256, contains, exit_code. A task that promises a report but writes no file fails. |
| No ghost dispatch | A card stopped by the gate writes a blocked event and no dispatch event, so the ledger can never show a task that never ran. |
| Append-only ledger | One JSON line per decision. History is never rewritten or deleted, and it can be queried, diffed and audited by something that is not an LLM. |
| Pluggable execution bodies | The plane picks no model and does not care which command runs a card. Swap the command, keep the governance. |
| Unparsed dependencies are fatal | A dependency marker that cannot be parsed refuses the dispatch. It is never silently dropped. |
What it feels like
You:
Finish these reports first, then let the downstream job merge them.foreman-plane: Three cards. The downstream one carries
[depends_on], so it cannot even start while the upstream files are missing. When everything is done the artefacts get checked again, a missing field meansfail, and the ledger records which file fell short.
Install
pip install foreman-plane
Or run it straight from a checkout:
cd foreman-plane
export PYTHONPATH="$PWD/src"
export FOREMAN_HOME="$PWD/.foreman"
Wire it into DSH
foreman-plane ships an MCP server, so no plugin code is needed. Point the profile patch at the stdio server and DSH talks to the plane directly:
# ~/.dsh/profiles/headless/cordis.patch.yml
mcp:
servers:
- name: foreman
command: python3
args:
- -m
- foreman.mcp_server
env:
FOREMAN_HOME: /var/lib/foreman
Wire it into Claude Code, Codex or any MCP client
{
"mcpServers": {
"foreman": {
"command": "python3",
"args": ["-m", "foreman.mcp_server"],
"env": { "FOREMAN_HOME": "/var/lib/foreman" }
}
}
}
The task card
A task card is plain text. Four markers may appear anywhere in it:
| Marker | Meaning |
|---|---|
[id] |
task id, shaped like T-YYYYMMDD-NN |
[depends_on] |
hard dependency: the upstream must be terminal, passed and accepted |
[needs_api] |
soft dependency: the artefact only has to exist, not be finished |
[acceptance] |
acceptance artefact plus optional objective criteria |
[id] T-20261109-20
[depends_on] T-20261109-01
[needs_api] T-20261109-01#/var/lib/foreman/api/order_book.json
[acceptance] reports/order_book_20261109.md::min_bytes=200::contains=Conclusion
Read order_book.json, produce the report and add a Conclusion section.
The half-width bracketed form above is the canonical one. The full-width
variants such as 【id】 and the colon forms such as id: are still accepted,
as are full-width spaces and colons. What never happens is a silent drop —
a dependency marker that cannot be parsed refuses the dispatch with
dependency_unparsed.
What the plane guarantees
How one card runs
task card
│
├─ parse ──▶ contract: id / hard dependencies / soft dependencies / acceptance criteria
│
├─ gate ───▶ every hard dependency terminal, passed and accepted?
│ ├─ no ──▶ blocked: one ledger line, nothing runs, no dispatch event
│ └─ yes
│ ▼
├─ run ────▶ call the execution body: Claude Code / Codex / DSH / any command
│
├─ accept ─▶ check the artefact: min_bytes / sha256 / contains / exit_code
│
└─ ledger ─▶ append one JSON line: dispatch / running / done / blocked / …
Hard gate — a task never runs too early
A card with [depends_on] is released only when every upstream task is
terminal, verdict=pass and artefact acceptance passed. Otherwise the plane
writes a blocked event and stops. There is no dispatch event for a task
that did not run, so the ledger cannot show a ghost dispatch.
[depends_on] T-20261109-01 → upstream done, verdict=pass → released
→ upstream still running → blocked(dependency_pending)
→ upstream unknown → blocked(dependency_unknown)
→ upstream verdict=fail → blocked(dependency_failed)
→ unparsable dependency marker → blocked(dependency_unparsed)
Soft gate — a task may start without a missing artefact
[needs_api] marks artefacts that must be ready but do not have to be
finished. A missing artefact is reported as needs_api_pending and the task
still runs.
Objective acceptance — the artefact decides, not the model
[acceptance] reports/report.md::min_bytes=200::sha256=<hex>::contains=Conclusion
Supported criteria: min_bytes, sha256, contains, exit_code. All
criteria are ANDed, relative paths resolve against the working directory, and
an unknown criterion fails closed.
Append-only audit trail
Every decision is one JSON line in ${FOREMAN_HOME}/ledger.jsonl:
{"ts":"2026-11-09T09:41:02.113456+00:00","event":"dispatch","task_id":"T-20261109-20","actor":"foreman","depends_on":["T-20261109-01"],"needs_api":[],"acceptance":"reports/report.md::min_bytes=200","needs_api_pending":false,"detail":{}}
Event types: dispatch, running, blocked, done, cancelled, replan.
History is never rewritten or deleted.
MCP tools
| Tool | Purpose |
|---|---|
foreman_dispatch |
dispatch a task card: parse, gate, run, accept |
foreman_status |
ledger status of one task or of everything |
foreman_cancel |
cancel a task; unknown ids are rejected |
CLI
foreman dispatch --file TASK.md [--agent NAME] [--workdir DIR] [--force] [--json]
foreman status [--task-id ID] [--json]
foreman ledger list | show | ready | blocked | cancel | replan
foreman verify --acceptance "<acceptance string>"
foreman mcp
foreman config
Exit codes: 0 success, 2 blocked by the gate, 3 artefact acceptance failed,
1 anything else.
Configuration
| Variable | Meaning |
|---|---|
FOREMAN_HOME |
plane home: ledger, run logs, agents.json |
FOREMAN_TIMEOUT |
execution timeout in seconds, default 900 |
FOREMAN_AGENT |
default execution body, default generic |
FOREMAN_ACTOR |
actor recorded in the ledger, default foreman |
FOREMAN_HOME resolves as the environment variable, then $HOME/.foreman,
then <cwd>/.foreman. The plane still works when HOME is not set.
Execution bodies live in ${FOREMAN_HOME}/agents.json, one command per name:
{"agents": {"mybot": {"command": "mybot run --prompt {task}"}}}
Development
PYTHONPATH=src python3 -m unittest discover -s tests -v
The specification lives in docs/SPEC.md, the wire contract in
docs/PROTOCOL.md.
License
MIT — see LICENSE.
Metadata
Release files for foreman-plane 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 |
|---|---|---|---|---|
| foreman_plane-0.1.1.tar.gz | 60.7 kB | Without provenance | Details for foreman_plane-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| foreman_plane-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for foreman_plane-0.1.1-py3-none-any.whl |
Total release size: 89.2 kB
Release files / foreman_plane-0.1.1.tar.gz
| Download URL | foreman_plane-0.1.1.tar.gz |
|---|---|
| Size | 60.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9840e8af7dd15c83a2532504270372171e305af1779db3a9de197873cd90a725
|
|
BLAKE2b-256 checksum How to use checksums |
ae11491ab90dc66b7374a4a99419888477edb33fe2b7621fb80c17279ffe85a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.12
|
Release files / foreman_plane-0.1.1-py3-none-any.whl
| Download URL | foreman_plane-0.1.1-py3-none-any.whl |
|---|---|
| Size | 28.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57c3b51aabe5fd548d4d1e95d9bb589982ac43db946d5e1655a35c6f1fb7c86e
|
|
BLAKE2b-256 checksum How to use checksums |
69187cb0625ba5933c1ca434cf5c64a7635905ef72effbb5303a103cdfc7e260
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.12
|
Security for foreman-plane 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.