Stratum

State machine dispatch server for AI agent workflows.

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.

The founding intent behind this machinery is recorded in 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. Runs from this checkout; not published to a registry.

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 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/ 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
• Quick Start
• Core Concepts
• YAML Spec Reference
• MCP Tools API
• Step Types
• Ensures (Postconditions)
• Contracts and Output Validation
• Gates (Human-in-the-Loop)
• Flow Composition
• Routing
• Iterations
• Checkpoints
• Recovery and Retry Logic
• Workflows
• Task Compiler
• Skills
• CLI Reference
• Configuration
• Python Library (Track 1)
• Examples
• Development
• License

Installation

The engine runs directly from a checkout — there is nothing to install from a registry.

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 MCP bin in your project's .mcp.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 to your CLAUDE.md.

CLI

node ts/src/cli/bin.mjs help    # validate | migrate | query | gate | guard | watch

A thin wrapper script (e.g. ~/bin/stratum-ts) pointing at ts/src/cli/bin.mjs is convenient; the bare name stratum is not used to avoid PATH collisions.

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/ 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

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

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.

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

flows (required)

flows.entry must name a flow in the same mapping. Every flow has these fields:

The output.from value must be one full reference to a step output with a known contract. A fanout output is an array, so a flow output must select an item such as ${fan.output[0]}.

Steps

Step IDs start with a lowercase letter and may contain lowercase letters, digits, underscores, and hyphens. IDs are unique within a flow. Every step accepts id, optional after, and optional when, then exactly one construct with only the fields listed below.

agent is either claude or codex. attempts is a positive integer. An iterate object requires positive integer max and string expression until.

The nested gate object requires nullable on_approve, on_revise, and on_kill fields. It may also set a positive integer max_rounds.

The nested fanout object requires over, one or more steps, positive integer concurrency, isolation of worktree or none, require of all, any, or a positive integer, and merge: sequential. Optional fields are pre_merge and dispatch, whose value is engine or consumer. Each fanout stage requires do and may use agent, out, ensure, attempts, and when.

References

V1 uses ${...} references in task templates, subflow inputs, fanout sources, and flow outputs.

A full-value reference preserves its JSON type in with and fanout.over. A reference embedded in other text is interpolated into a string. Step-output references create data dependencies. Use after for ordering dependencies that are not implied by references.

Expressions in ensure, when, set, and iterate.until use the v1 expression bindings instead of ${...} interpolation. input is the flow input. In an ensure, result is the output under test. In when and set, result is a mapping of completed step IDs to outputs. Fanout stage expressions also receive item and prev.

Migrating v0.x Specs

stratum migrate --check <old.yaml> is a report-only classifier. It does not emit translated YAML.

Some legacy constructs have no v1 equivalent. These include verified or applied-gate judge predicates, judge budgets, score and accumulator fields, cross-item decompose dependencies, branch or manual parallel merge modes, certificate and timeout fields, nested pipeline regions, pipeline exit_when, gate policies, gate timeouts, and the top-level workflow block. Flatten or re-author supported regions. Unsupported regions must be redesigned before they can run on v1.

MCP Tools API

All tools are exposed via the MCP protocol. Claude Code calls them as tool invocations.

stratum_validate

Validate a .stratum.yaml spec without creating a flow.

Inputs: spec (str, inline YAML) Returns: {valid: bool, errors: list}

stratum_plan

Validate a spec, create execution state, and return the first step to execute.

Inputs:

• spec (str) -- inline YAML
• flow (str) -- flow name
• inputs (dict) -- flow-level inputs

Returns: Step dispatch object with status: "execute_step" or status: "await_gate", including:

• flow_id -- unique identifier for this execution
• step_id, step_number, total_steps
• function, intent, inputs (resolved)
• output_contract, output_fields, ensure
• retries_remaining
• agent, step_mode

stratum_step_done

Report a completed step result. The server validates the result against output schemas and ensure expressions.

Inputs:

• flow_id (str)
• step_id (str)
• result (dict) -- step output matching the output contract

Returns one of:

• Next step to execute (status: "execute_step")
• Ensure failure with retry info (status: "ensure_failed", violations, retries_remaining)
• Schema validation failure (status: "schema_failed", violations)
• Flow completion (status: "complete", output, trace, total_duration_ms)
• Retries exhausted (status: "error", error_type: "retries_exhausted")
• Routed to recovery step (routed_from, violations)

stratum_audit

Return the full execution trace for a flow.

Inputs: flow_id (str)

Returns:

• flow_id, flow_name, status (complete, in_progress, killed)
• steps_completed, total_steps
• trace -- array of step records (step_id, function_name, attempts, duration_ms, type, round)
• round, rounds -- round history for gate revise cycles
• iterations, archived_iterations -- iteration history
• child_audits -- audit snapshots from sub-flow executions
• total_duration_ms

stratum_gate_resolve

Resolve a gate step with a human/agent/system decision.

Inputs:

• flow_id (str)
• step_id (str) -- must be the current gate step
• outcome (str) -- "approve", "revise", or "kill"
• rationale (str) -- human-readable reason
• resolved_by (str) -- "human", "agent", or "system"

Returns: Next step, flow completion, or flow termination.

stratum_commit

Save a named checkpoint of the current flow state.

Inputs: flow_id (str), label (str)

stratum_revert

Roll back flow state to a previously committed checkpoint.

Inputs: flow_id (str), label (str)

stratum_compile_speckit

Compile a spec-kit tasks directory into a .stratum.yaml flow.

Inputs: tasks_dir (str), flow_name (str, default "tasks")

Returns: {status, yaml, flow_name, steps} on success.

stratum_resume

Rehydrate a persisted flow into this server process (live-process reparenting) so a fresh session can continue a run it did not start.

stratum_flow_run_bg / stratum_flow_poll / stratum_flow_bg_poll / stratum_flow_cancel_bg

Detached background flow execution: start a flow under a background driver, poll its progress, cancel it. Survives the launching session.

stratum_agent_run / stratum_agent_poll / stratum_cancel_agent_run

Dispatch an agent (Claude, Codex, opencode) as part of a flow step, synchronously or in the background; poll and cancel background runs. cancel is a documented no-op for synchronous runs.

The authoritative tool surface is ts/src/mcp/server.ts. Python-era tools that were retired rather than ported (parallel lifecycle, iterations, timers/skip, list_workflows, draft_pipeline, judge/distill/goal surfaces) live on python-legacy; see the Phase 2/3 usage audit in docs/plans/2026-07-11-strat-py-retire-progress.md for per-tool dispositions.

STRAT-GUARD — guarded transitions outside a flow

stratum_judge/stratum_gate_resolve enforce guarantees only inside a flow. STRAT-GUARD exposes the same independent-verification engine (run_judge) as a standalone, resource-agnostic, tamper-evident state machine for clients that manage a resource lifecycle outside a stratum flow (e.g. compose's feature tracker). A client registers a transition graph with per-edge evidence predicates; stratum then permits a transition only if the edge is legal and its predicates verify against trusted, server-read evidence (not caller-staged claims). Every attempt — applied or refused — is appended to a hash-chained ledger. See docs/features/STRAT-GUARD/.

stratum_guard_register

Register a guarded resource. The (graph, edge_predicates, terminal, stakes) policy is checksummed and immutable — re-registering an identical policy is a no-op; a different policy is rejected (use stratum_guard_migrate).

Inputs: resource_id (str, client-namespaced e.g. "compose:FEAT-1"), graph (dict[from -> list[to]]), edge_predicates (dict["from->to" -> list of {id,type,statement}]), initial (str), terminal (list[str]), stakes (dict["from->to" -> "cheap"|"default"|"paranoid"]), workspace_root (abs dir, for file/git/command evidence).

Predicate type: "deterministic" → server-side trusted evidence (server_file_exists/git_commit_exists/command_exit_zero/verdict_receipt_clean); "verified"/"judged" → LLM-tier, routed through run_judge. A paranoid edge must declare ≥1 trusted predicate.

Returns: {guard_id, checksum, status}.

stratum_guard_transition

Attempt from_state -> to_state. Trusted predicates are verified server-side; any LLM-tier predicates go through the judge at the edge's stakes. Optimistic concurrency: evaluation runs outside a per-resource lock, the commit re-validates state under it.

Inputs: resource_id, from_state, to_state, artifacts (dict[str,str]), modified_files (list[str]), idempotency_key (str|None), resolved_by (str).

Returns: {status: applied|refused|replayed, verdict: JudgeResult-dict, ledger_ref, current_state}. ledger_ref is the receipt token presented to verdict_receipt_clean.

stratum_guard_override

The single sanctioned bypass of predicate verification. Requires an out-of-band override_token (server env STRATUM_GUARD_OVERRIDE_TOKEN, not agent-mintable), a human resolver, and a rationale. Moves a legal edge without verifying predicates and records a deviation ledger entry. Replaces a force flag.

Inputs: resource_id, from_state, to_state, override_token, rationale, resolved_by ("human").

stratum_guard_migrate

Evolve a registered policy. Token-gated, bumps graph_version, writes a graph_version ledger entry, and never silently relaxes an in-flight resource's policy. The current state must remain a node in the new graph.

Inputs: resource_id, new_graph, new_edge_predicates, override_token, rationale, new_terminal, new_stakes.

stratum_guard_history

Return a resource's current state and its append-only, hash-chained transition/deviation ledger (the tamper-evident audit trail).

Inputs: resource_id. Returns: {resource_id, current_state, graph_version, ledger: [...]}.

Step Types

V1 has five mutually exclusive step constructs. This example includes all five:

version: 1
contracts:
  Analysis:
    summary: string
    score: number
  ItemResult:
    value: string
  Final:
    message: string
flows:
  entry: main
  main:
    input:
      topic: string
      items: string[]
    output:
      from: "${finish.output}"
      contract: Final
    steps:
      - id: analyze
        do: "Analyze ${input.topic}"
        agent: claude
        out: Analysis
      - id: normalize
        after: [analyze]
        set:
          summary: "result.analyze.summary"
          score: "result.analyze.score"
        out: Analysis
        ensure:
          - expr: "result.score >= 0"
      - id: review
        after: [normalize]
        gate:
          on_approve: null
          on_revise: null
          on_kill: null
      - id: inspect
        after: [review]
        fanout:
          over: "${input.items}"
          concurrency: 2
          isolation: none
          require: all
          merge: sequential
          steps:
            - do: "Inspect ${item}"
              agent: codex
              out: ItemResult
      - id: child
        after: [inspect]
        run: summarize
        with:
          topic: "${input.topic}"
      - id: finish
        after: [child]
        do: "Finalize ${child.output.message}"
        out: Final
  summarize:
    input:
      topic: string
    output:
      from: "${write_summary.output}"
      contract: Final
    steps:
      - id: write_summary
        do: "Summarize ${input.topic}"
        out: Final

do Tasks

do contains the task text sent to an agent. agent defaults to claude. out names the result contract. A task may also declare ensure, attempts, iterate, budget, and on_fail.

set Steps

set evaluates each field expression without dispatching an agent. The resulting object is validated against the required out contract, then checked against any ensures. Set steps are deterministic and are not retried.

gate Steps

gate pauses the run until an external decision arrives. Its three route fields are required, although any of them may be null. Gate steps cannot carry task, retry, budget, or ensure fields.

fanout Steps

fanout.over must be one full reference that resolves to an array. Each item moves through the declared stages. ${item} is the source item and ${prev} is the previous stage output. The final stage needs out when later steps or the flow output reference the fanout result.

isolation: worktree gives each item a Git worktree. merge only accepts sequential. require decides how many item successes are needed before merge. dispatch defaults to engine. Consumer-dispatched worktree fanout has extra validation rules, including a required unconditional successor gate.

run Steps

run names another flow in the same spec. with is required and its keys must exactly match the callee input keys. A run step's output contract is inherited from the callee. Non-entry flows cannot contain run or fanout, and recursive calls are rejected.

Mode Exclusion

Every step must have exactly one of do, set, gate, fanout, or run. Fields from one construct cannot be mixed into another.

Ensures (Postconditions)

An ensure array contains strict predicate objects. Predicates run in order, and the first failure stops evaluation.

Judged stakes are cheap, default, or paranoid. A judged predicate fails closed if no judge runner is configured. File predicates require a workspace root and are jailed to that root.

Expression Syntax

The v1 evaluator is a restricted expression language, not Python. It accepts JSON literals, member access, non-negative literal array indexes, function calls, parentheses, unary ! and -, arithmetic, comparisons, in, &&, and ||.

In an ensure, result is the step output and input is the flow input. Fanout stage ensures also receive item and prev.

Built-in Functions

Safety

• Only result, input, item, and prev can be bound.
• __proto__, constructor, and prototype member access is blocked.
• Parsing, nesting, regular expression size, and regular expression input are bounded.
• File helpers cannot escape the configured workspace root.

Failure Behavior

An ensure failure records a structured failure reason. A do task is dispatched again while its attempts budget remains. Identical output evidence stops retries early because the same deterministic predicate cannot change its verdict.

Contracts and Output Validation

Contracts in the Spec

Contracts use the field-to-type string language in the YAML reference. Task output is validated against out before ensures run. Flow output is validated again against output.contract when the referenced producer completes.

out is required on set. A do step may omit out only when no later reference or flow output needs a contract for that result.

Output Schema (Per-Step JSON Schema)

V1 does not accept per-step output_schema or output_contract. Move supported fields into a named contract and reference it with out. The v1 contract language supports the types listed above, but it is not arbitrary JSON Schema.

Gates (Human-in-the-Loop)

Gates are approval checkpoints that pause flow execution until resolved externally.

Defining a Gate

Declare the gate directly on a step, as shown in the full gate example. There is no gate function declaration in v1.

Gate Constraints

• on_approve, on_revise, and on_kill are all required and nullable.
• Named approve and kill targets must preserve an acyclic routing graph.
• A usable revise target must be a strict ancestor of the gate.
• Any non-null revise target requires flow-level max_rounds.
• Gate-level max_rounds may impose a tighter positive limit on that gate.
• A gate step accepts only common fields and the nested gate object.

Resolution

Gates are resolved through stratum_gate_resolve with runId, stepId, decision, and the observation-time gateToken. The token fences stale decisions. The CLI uses approve, revise, and reject, where reject maps to the engine's kill decision.

• approve routes to on_approve, or completes the gate when the route is null.
• revise resets the affected descendant region and routes to on_revise while round limits remain.
• kill routes to on_kill, or terminates the run when the route is null.

Gate policies, policy fallbacks, and gate timeouts were not ported to v1. Resolve every waiting gate explicitly.

Rounds

Each successful revise increments the flow round counter and the gate's local revision counter. The flow and optional gate limits are enforced before another revision begins.

Flow Composition

Steps with run invoke a subflow defined in the same spec. The parent step completes only after the child flow produces and validates its output.

version: 1
contracts:
  TestResult:
    all_passed: boolean
  DeployResult:
    status: string
flows:
  entry: deploy
  integration_tests:
    input:
      project: string
    output:
      from: "${run_tests.output}"
      contract: TestResult
    steps:
      - id: run_tests
        do: "Run integration tests for ${input.project}"
        out: TestResult
        ensure:
          - expr: "result.all_passed == true"
  deploy:
    input:
      project: string
    output:
      from: "${release.output}"
      contract: DeployResult
    steps:
      - id: test
        run: integration_tests
        with:
          project: "${input.project}"
      - id: release
        after: [test]
        do: "Deploy after test result ${test.output.all_passed}"
        out: DeployResult

• with values may contain nested literals and ${...} references.
• with keys must exactly match the callee input fields.
• The run step inherits the callee output contract.
• A run step may set budget and on_fail.
• Recursive calls are rejected.
• Non-entry flows cannot contain another run or a fanout.

Routing

on_fail Recovery Routing

on_fail activates a named recovery step after a task, fanout, or subflow exhausts its failure path. The target must be later in the validated DAG.

version: 1
contracts:
  TaskResult:
    ok: boolean
    details: string
flows:
  entry: build
  build:
    input:
      spec: string
    output:
      from: "${publish.output}"
      contract: TaskResult
    steps:
      - id: generate
        do: "Generate code for ${input.spec}"
        out: TaskResult
        attempts: 2
        on_fail: recover
      - id: verify
        after: [generate]
        when: "result.generate.ok == true"
        do: "Verify the generated code"
        out: TaskResult
      - id: recover
        do: "Repair generation failure"
        out: TaskResult
      - id: publish
        after: [verify, recover]
        do: "Publish the final result"
        out: TaskResult

Route-only recovery steps are skipped when their source succeeds. Downstream steps may depend on both the normal and recovery branches because skipped dependencies satisfy ordering edges.

Success Routing

V1 has no next field. Success follows the DAG formed by after and step-output references. Gates provide explicit approve and kill routes. Backward success jumps are not supported.

Conditional Skip

when is a positive v1 expression. The step runs only when the expression evaluates to true. Any other result skips the step. To migrate skip_if, invert the condition. A skipped step has no output, so later data references to it cannot resolve.

Iterations

iterate repeats a do task until its predicate holds or its positive max is reached.

version: 1
contracts:
  Draft:
    text: string
    quality: number
flows:
  entry: refine
  refine:
    input:
      brief: string
    output:
      from: "${improve.output}"
      contract: Draft
    steps:
      - id: improve
        do: "Improve the draft for ${input.brief}"
        out: Draft
        iterate:
          max: 5
          until: "result.quality >= 0.95"

The engine evaluates until after contracts and ensures pass. A false result records the attempt and redispatches the task. Repeated identical output stops early. Max exhaustion enters the normal failure path, including on_fail routing.

Removed Iteration Fields

V0.x score_expr, accumulate, and accumulate_key have no v1 equivalent. V1 also has no separate iteration lifecycle tools. Iteration is part of normal task dispatch and result reporting.

Checkpoints

Checkpoints are runtime operations, not YAML constructs. stratum_commit accepts flow_id and a non-empty label. stratum_revert accepts the same fields and re-advances the restored run.

{"flow_id": "<run-id>", "label": "after_analysis"}

A checkpoint captures run status, output, failure, spent budget, rounds, step state, audit events, cancellation state, and parallel state. It does not snapshot the spec, input, workspace files, run identity, or the checkpoint list itself. Commit and revert are state-only operations. The caller owns file-level rollback.

Checkpoints are stored with the persisted run and survive server restarts. Reusing a label replaces its snapshot while keeping the label's original insertion position.

Recovery and Retry Logic

Retry Budget

do tasks and fanout steps use attempts, with a default of two. A fanout stage can override the enclosing fanout attempt limit. set is deterministic and does not retry. run does not accept an attempts field.

Retry Flow

1. The executor reports a task result with the current dispatch token.
2. The engine validates the result against out.
3. The engine evaluates ensures in declaration order.
4. The engine evaluates iterate.until when iteration is configured.
5. A failure redispatches the task while attempts remain and evidence changed.
6. Exhaustion activates on_fail when configured, otherwise it fails the flow.

Persistence

Flow state is persisted to ~/.stratum/ts/flows/{runId}.json after state mutations. Runs survive MCP server restarts.

Server Restart Recovery

The engine loads a missing run from disk, revalidates its persisted spec, and resumes from persisted DAG state. Dispatch and gate tokens prevent stale work from mutating a newer issuance.

Workflows

V1 has no top-level workflow declaration and no discovery registry. Name the file for people, and select the executable entry flow with flows.entry. The former code-review workflow becomes a normal v1 specification:

version: 1
contracts:
  ReviewResult:
    summary: string
flows:
  entry: code_review
  code_review:
    input:
      files: string[]
      depth: string?
    output:
      from: "${review.output}"
      contract: ReviewResult
    steps:
      - id: review
        do: "Review ${input.files} for security, logic, and performance"
        out: ReviewResult

V1 input contracts support optional fields, but not default values. The caller supplies defaults before planning a run.

Task Compiler

The task compiler converts spec-kit task files (tasks/*.md) into .stratum.yaml flows.

Task File Format

# Task: [P] Implement authentication

Add JWT-based authentication to the API.

## Acceptance Criteria

- [ ] file src/auth/middleware.ts exists
- [ ] file src/auth/middleware.ts contains "verifyToken"
- [ ] tests pass
- [ ] no lint errors
- [ ] Error messages are user-friendly

Compilation Rules

• [P] in the title marks the task as parallelizable
• file X exists compiles to file_exists("X")
• file X contains Y compiles to file_contains("X", "Y")
• tests pass compiles to result.tests_pass == True
• no lint errors compiles to result.lint_clean == True
• Freeform criteria are incorporated into the step's intent

Dependency Graph

• Sequential tasks depend on the prior task
• Parallel tasks ([P]) share the same predecessor with no edges between them
• After a parallel group, the next sequential task depends on all tasks in the group

Usage

Via MCP tool: stratum_compile_speckit(tasks_dir, flow_name).

Skills

The eleven /stratum-* skills shipped and were installed by the python stratum-mcp install command, which is retired — their sources are archived on python-legacy (stratum-mcp/src/stratum_mcp/skills/). Skills already installed under ~/.claude/skills/ keep working (they drive the same stratum_plan / stratum_step_done / stratum_audit tools the TS server exposes). There is no TS installer yet.

CLI Reference

Two bins, both run with node from the checkout:

node ts/src/mcp/bin.mjs            # Start stdio MCP server (for Claude Code)

node ts/src/cli/bin.mjs <command>  # aka `stratum` via a wrapper script:
stratum validate <file>            # Validate a .stratum.yaml spec (version: 1)
stratum migrate --check <file>     # Report-only classification of a legacy v0.x spec
stratum query flows                # List all persisted flows (JSON)
stratum query flow <id>            # Full state for a single flow (JSON)
stratum query gates                # List all pending gate steps (JSON)
stratum gate approve <flow_id> <step_id> [--note "reason"]
stratum gate reject  <flow_id> <step_id> [--note "reason"]
stratum gate revise  <flow_id> <step_id> [--note "reason"]
stratum guard <action>             # Guard ledger operations (see STRAT-GUARD)
stratum watch <flow_id>            # Follow a flow's progress
stratum help                       # Show usage

Configuration

Flow State Storage

Persisted flows are stored in ~/.stratum/flows/{flow_id}.json. This directory is created automatically.

Hooks

The python installer's session hooks (~/.stratum/hooks/) are retired with it; sources are archived on python-legacy. Any hooks still registered in .claude/settings.json from an old install are inert once removed from there.

MCP Registration

The MCP server is registered in the project's .mcp.json:

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

CLAUDE.md Block

The execution model block appended to CLAUDE.md instructs the agent to use Stratum for non-trivial tasks:

## Stratum Execution Model

For non-trivial tasks, use Stratum internally:
1. Write a .stratum.yaml spec -- never show it to the user
2. Call stratum_plan to validate and get the first step
3. Narrate progress in plain English as you execute each step
4. Call stratum_step_done after each step -- the server checks your work
5. If a step fails postconditions, fix it silently and retry
6. Call stratum_audit at the end and include the trace in the commit

Python Library (Track 1)

RETIRED.

The stratum-py decorator library (@infer, @contract, @compute, @flow, @refine, parallel, debate, await_human, budgets, OTLP export) was retired with the python engine on 2026-07-18 (STRAT-PY-RETIRE). Its final source is archived on the python-legacy branch (src/stratum/), and its last PyPI release stays installable for existing users but receives no further updates.

Examples

Working examples in examples/:

The python decorator examples (01_sentiment.py … 06_hitl.py) retired with stratum-py; see python-legacy.

Development

git clone https://github.com/smartmemory/stratum
cd stratum/ts
npm install                      # or pnpm install
./node_modules/.bin/vitest run   # full engine suite

Never run two full vitest passes concurrently — the suites share on-disk state roots.

Test Counts

The TS engine has 640+ vitest tests across the IR, engine, MCP surface, guard, parallel, and migrate suites, including cross-engine goldens that pin byte compatibility with python-era ledgers and specs. Compose's suite (4,600+ tests, including the ts-cutover-* goldens that drive this engine's real binaries end-to-end) is the downstream integration harness.

CI/CD

PyPI publishing is retired with the python packages. There is no npm publish pipeline yet — consumers run the engine from a checkout (see Installation).

License

Apache 2.0