stratum

# Stratum

[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

**State machine dispatch server for AI agent workflows.**

*Your agent proposes the step. Stratum decides whether it actually finished.*

Stratum gives AI coding agents (Claude Code, Codex, etc.) a formal execution model. Instead of improvising a plan and retrying blindly, the agent writes a typed spec, the server tracks state, enforces postconditions, and returns structured failure context on retry. Every step produces an auditable trace record.

**Where it sits.** Stratum is the execution kernel, one layer below the thing most people run day to day. [Compose](https://github.com/smartmemory/compose) drives the product lifecycle (design, blueprint, plan, review gates) and calls Stratum to execute each step. Reach for Stratum directly when you want the state machine and the postconditions without a lifecycle on top of them.

The founding intent behind this machinery is recorded in [docs/VISION.md](docs/VISION.md): a spec language that keeps LLMs on rails invisibly, so the same conversation yields stronger results than freeform execution.

One shipped component:

- **`ts/`** — the TypeScript engine (`@smartmemory/stratum`): IR validation (`version: 1` specs), flow execution with ensure postconditions, MCP server for Claude Code, `query`/`gate`/`guard` CLI, background flows and background agent runs. Published to npm as `@smartmemory/stratum` (bins: `stratum`, `stratum-mcp`) and listed in the MCP registry as `ai.smartmemory/stratum-mcp`.

> **Engine status (2026-07-18, STRAT-PY-RETIRE):** the TS engine is the ONLY engine.
> The Python library (`stratum-py`) and Python MCP server (`stratum-mcp`) are retired.
> Their source is archived on the [`python-legacy`](../../tree/python-legacy) branch, and PyPI packages are
> frozen at their final releases. The engine executes **`version: 1`** specs exclusively.
> Legacy v0.x specs are rejected by `validate` and classified (report-only) by
> `stratum migrate --check`. The authoritative v1 shape is the Zod IR schema in
> [`ts/src/ir/`](ts/src/ir/) plus `stratum validate` output.

**Governed workflows as auditable flows — on any agent, not just one vendor.** Unlike a single-vendor in-context orchestrator, Stratum runs as an MCP server and a library under Claude Code, Codex, or any MCP host; enforces typed contracts and `ensure` postconditions on every flow execution; stops at real human gates; dispatches Claude *and* Codex agents in one flow (so an independent reviewer can be a different model from the implementer); and persists flow state across sessions. Where you want raw in-context fan-out, reach for an in-host workflow runtime; where you want the run governed, portable, and auditable, that's a Stratum workflow.

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [YAML Spec Reference](#yaml-spec-reference)
- [MCP Tools API](#mcp-tools-api)
- [Step Types](#step-types)
- [Ensures (Postconditions)](#ensures-postconditions)
- [Contracts and Output Validation](#contracts-and-output-validation)
- [Gates (Human-in-the-Loop)](#gates-human-in-the-loop)
- [Flow Composition](#flow-composition)
- [Routing](#routing)
- [Iterations](#iterations)
- [Checkpoints](#checkpoints)
- [Recovery and Retry Logic](#recovery-and-retry-logic)
- [Workflows](#workflows)
- [Task Compiler](#task-compiler)
- [Skills](#skills)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Python Library (Track 1)](#python-library-track-1)
- [Examples](#examples)
- [Development](#development)
- [License](#license)

---

## Installation

Install from npm (Node >= 22):

```bash
npm install -g @smartmemory/stratum    # provides `stratum` (CLI) and `stratum-mcp` (MCP server)
```

Or run from a checkout for development:

```bash
git clone https://github.com/smartmemory/stratum
cd stratum/ts && npm install    # or pnpm install
```

Requires node >= 22 (erasable-syntax type stripping; node >= 24 needs no flags — the CLI
bootstrap gates `--experimental-transform-types` automatically).

### MCP Server (for Claude Code)

Register the server in your project's `.mcp.json`. From the npm package:

```json
{
  "mcpServers": {
    "stratum": {
      "command": "npx",
      "args": ["-y", "-p", "@smartmemory/stratum", "stratum-mcp"]
    }
  }
}
```

From a checkout:

```json
{
  "mcpServers": {
    "stratum": {
      "command": "node",
      "args": ["/absolute/path/to/stratum/ts/src/mcp/bin.mjs"]
    }
  }
}
```

Restart Claude Code to activate. Optionally append the [Stratum execution model block](#claudemd-block) to your `CLAUDE.md`.

### CLI

```bash
stratum help                    # validate | migrate | query | gate | guard | watch  (npm install)
node ts/src/cli/bin.mjs help    # same, from a checkout
```

From a checkout, a thin wrapper script (e.g. `~/bin/stratum-ts`) pointing at `ts/src/cli/bin.mjs` avoids a PATH collision with the installed `stratum` bin.

---

## Quick Start

When Claude Code has Stratum installed, it uses it automatically for non-trivial tasks:

1. Claude writes a `.stratum.yaml` spec internally (never shown to you)
2. Calls `stratum_plan` to validate the spec and get the first step
3. Executes each step using its own tools (reading files, writing code, running tests)
4. Calls `stratum_step_done` after each step -- the server checks postconditions
5. If a postcondition fails, Claude gets back the specific violation and retries
6. Calls `stratum_audit` at the end for a full execution trace

You see plain English narration throughout. The spec, state management, and postcondition enforcement happen behind the scenes.

---

## Core Concepts

### Specification vs Flow

A **specification** is the authored, version-controlled `.stratum.yaml` document. It declares contracts and one or more flows. The `flows.entry` field selects the flow that starts a run.

A **flow** is an executable directed acyclic graph of steps. Running the entry flow creates a persisted run with a `runId`. The v0.x top-level `workflow:` registration block and `stratum_list_workflows` were retired with the Python server.

### Flows

A flow declares typed `input` fields, a typed `output`, optional limits, and `steps`. References and `after` lists form data and ordering edges. Gate routing and `on_fail` add explicit routing edges.

### Steps

A step has an `id`, optional `after` dependencies, an optional `when` condition, and exactly one construct: `do`, `set`, `gate`, `fanout`, or `run`.

### Tasks

A `do` step is an agent-dispatched task. The task text is declared inline, and `${...}` references inject flow input or prior step output values. The v0.x `functions:` registry and `function:` steps have no place in a v1 document.

### Contracts

Contracts define named output shapes. A `do` or `set` step declares its output contract with `out`. A flow declares both the step-output reference that supplies its result and the contract used to validate that result.

### Ensures

Ensures are structured postconditions on `do`, `set`, and fanout stage results. V1 supports expression, file existence, file content, and judged predicates.

### Retries

A `do` or `fanout` step can set the positive integer `attempts` limit. The default is two attempts. Contract failures, ensure failures, task failures, and exhausted iterations use the same failure path. A deterministic `set` failure terminates the flow without retrying.

### Gates

Gate steps pause execution for an external `approve`, `revise`, or `kill` decision. Approve and kill routes may name a later step or use `null`. A revise route may name a strict ancestor and requires a flow-level `max_rounds` limit.

---

## YAML Spec Reference

The Zod IR schema in [`ts/src/ir/`](ts/src/ir/) and the errors produced by `stratum validate` are authoritative. The root is strict and has exactly three fields: `version`, `contracts`, and `flows`. Unknown fields are rejected.

### Minimal Example

```yaml
version: 1
contracts:
  SentimentResult:
    label: string
    confidence: number
flows:
  entry: classify
  classify:
    input:
      text: string
    output:
      from: "${classify_text.output}"
      contract: SentimentResult
    steps:
      - id: classify_text
        do: "Classify the sentiment of ${input.text}"
        agent: claude
        out: SentimentResult
        ensure:
          - expr: "result.label != ''"
          - expr: "result.confidence > 0.7"
        attempts: 2
```

### Full Example with a Gate

```yaml
version: 1
contracts:
  WorkOutput:
    result: string
    quality_score: number
flows:
  entry: reviewed_work
  reviewed_work:
    input:
      text: string
    output:
      from: "${work.output}"
      contract: WorkOutput
    max_rounds: 3
    steps:
      - id: work
        do: "Produce the deliverable requested in ${input.text}"
        agent: codex
        out: WorkOutput
        ensure:
          - expr: "result.quality_score >= 0.8"
        attempts: 3
      - id: review
        after: [work]
        gate:
          on_approve: null
          on_revise: work
          on_kill: null
          max_rounds: 2
```

### Full Field Reference

#### `version` (required)

The only accepted value is the number `1`. Quoted strings such as `"1"` and all v0.x values are rejected.

#### `contracts` (required)

Each contract maps field names to type strings. Objects are strict at runtime, so undeclared output fields are rejected.

| Type form | Meaning |
|---|---|
| `string`, `integer`, `number`, `boolean` | Scalar value |
| `object`, `array` | Untyped JSON object or array |
| `string[]`, `Result[]` | Typed array |
| `draft|final` | String enum |
| `(draft|final)[]` | Array of string enum values |
| `Result` | Another named contract |
| `string?`, `Result[]?` | Optional field |

Named contract references use an initial capital letter. Recursive contract references and unknown contract names are rejected.

#### `flows` (req