Foreman

Status: open/draft

Summary

A distributed work runner: a single self-contained Rust binary that schedules, claims, and executes registered processes against work orders.
Runs on a laptop. No cluster, no database, no broker — coordination is git refs, run records are local append-only journals. Distribution is several user machines over one shared ref authority, never a hosted control plane.
Domain-blind by build constraint. It knows work scheduling and nothing else; SDLC is one adapted instance bound in through the ports, and a second instance must be conceivable at all times.
Named seams are ports with swappable implementations: coordination, run records, work-order source, runner context, agent driver.
Ships its own CLI and a read-only status API from v0; sdlc engine is a convenience over it, not its only door.

The name follows the manufacturing vocabulary the architecture already adopted — work orders routed through registered processes — where the foreman is the role that takes an order and assigns it to a station. The crate is packages/rust/foreman.

What it is

Foreman is the loop that D-VSLI names:

work order → schedule (frontier + filters) → claim (lease) → run (registered process)
          → record (execution substrate) → verdict (terminal write to corpus)

It reads work orders through the work-order source port, asks PR-DZTZ-graph-scheduler for the frontier in-process, applies a policy filter chain, claims by compare-and-swap on a git ref, and activates the process the work order’s kind: routes to. Execution has virtual-actor semantics: the lease ref is the actor identity, dispatch is activation, TTL and steal-on-expired are supervision, and all actor state rehydrates from the substrate.

Its first implementation is salvage, not greenfield — a working supervisor loop, worker and handler registry, session lifecycle and agent delegation already exist in apps/ontological-legacy/src-tauri/src/engine/ and are lifted out of that host app onto the coordination port.

Rust is not incidental. P-0012-rust-core-adapters-as-needed puts semantics once at the centre, and the layers that wrap that centre stay Rust as they narrow: scheduling core → work runner → the SDLC engine over it. Other languages enter at the edges as adapters, built when a consumer exists.

Boundary

Inside this product:

The scheduler: frontier plus the policy filter chain, with explain() over the same verdicts.
The execution plane: claims, leases, fencing, heartbeats, supervision.
The process registry and its tagged step variants — built-in, shell command, child process over the step protocol, agent step; WASM later.
Long-lived system actors: dispatcher, reconciler, corpus-writer, PR shepherd, trigger service.
Run records as append-only journals, and the read-only status API over frontier, leases, runs, triggers and the registry.
The step protocol — stdio JSON-RPC, one contract for engine↔runner, runner↔step, and runner↔agent-driver.

Outside it:

Any SDLC concept. No task, no corpus schema, no readiness contract, no lifecycle vocabulary. Those live in the SDLC engine that wraps this one.
Authoring. PR-FLWL-flowline writes workflows; foreman runs them.
The corpus. Markdown on disk is never a port, and foreman never becomes a system of record.
The agent itself. Claude Code is one implementation behind the agent-driver port.
A control plane. An always-on host is one more peer, never a requirement.

Drivers

Driver	Kind	What it wants
DR-G846-orchestrator-parallel-dispatch	use-case	The next N parallel-safe work orders under per-category in-flight caps — a dispatch decision, not a frontier
DR-QKVQ-goal-directed-frontier	use-case	Dispatch concentrated toward one milestone, and what blocks it
DR-0001	pain-point	The lifecycle is human-driven at every junction
DR-0005	use-case	Keep the project moving hands-off

Both graph-scheduler drivers currently sit on PR-DZTZ-graph-scheduler, which explicitly disclaims execution and caps — they describe a dispatcher and belong here. Re-scope them when this product moves off draft.

← Back to Products