Skip to main content

foreman-plane

The task governance plane that runs outside your agent harness

PyPI version downloads Protocol Python License

English · 简体中文

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 talk to foreman-plane over MCP/stdio

┌──────────────────┐        ┌──────────────────────┐
│ 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 means fail, 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

How one task card runs through the plane

  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)

Source distribution for foreman-plane 0.1.1
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)

Table of built distributions (wheels) for foreman-plane 0.1.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page