Configuration

Added in 0.3. The matching producer capability is configuration.

run.configuration records what ran, separately from how it went. It has two parts: a workflow, the shape of the work (pieces of agent work, the artifacts they pass, and the control policy that gates and repairs), and a setting for each piece (harness, model, reasoning effort, context policy and options). Its id is computed from both, so the same workflow with the same settings has the same id in every tool, and runs of one configuration can be counted together. The id covers the declared configuration only: an attempt may override its piece’s setting, so two runs with the same id can still differ in what individual attempts used.

"configuration": {
  "id": "cfg_ab15440a2d9c",
  "workflow": {
    "id": "implement_review", "version": 1, "title": "Implement, then review",
    "pieces": [
      { "id": "implement", "role": "implementer" },
      { "id": "review", "role": "reviewer" }
    ],
    "artifacts": [
      { "id": "issue", "kind": "issue" }, { "id": "repo", "kind": "repo" },
      { "id": "diff", "kind": "diff" }, { "id": "verdict", "kind": "verdict" }
    ],
    "edges": [
      ["issue", "implement"], ["repo", "implement"], ["implement", "diff"],
      ["diff", "review"], ["issue", "review"], ["review", "verdict"]
    ],
    "control": {
      "gates": ["review"],
      "repair": { "review": "implement" },
      "budget": 3,
      "rescue": { "kind": "configuration", "ref": "usual" }
    }
  },
  "settings": {
    "implement": { "harness": "claude-code", "model": { "raw": "claude-opus-5-5", "id": "claude-opus-5-5" }, "effort": "high", "context_policy": "fresh", "options": {} },
    "review": { "harness": "codex", "model": { "raw": "gpt-6-astra", "id": "gpt-6-astra" }, "effort": "xhigh", "context_policy": "fresh", "options": {} }
  },
  "source": "exploration"
}

The workflow above, drawn. The dashed arrow is the repair: when the review rejects, implement runs again, up to three rounds in all. What ran: a workflow and a setting per piece vertex.

string

cfg_ plus the first 12 hex digits of SHA-256 over the canonical JSON of {workflow, settings} (see Configuration id): keys sorted, no whitespace, workflow id, version, title and ext excluded. Same shape and settings, same id, everywhere (E190).

Workflow | WorkflowRef

Inline, or a catalog reference such as {“ref”: “plan_implement_review”, “version”: 1}.

map of Setting

Piece vertex id to setting. Every piece vertex has one (E191).

enum

Why this configuration ran. usual: the user’s usual workflow. alternative: an alternative loopmath offered. exploration: an exploration pick. user_edit: the user edited a suggestion. habit: a logged run, chosen by habit. designed: chosen by a planner such as loopmath plan.One of: usual, alternative, exploration, user_edit, habit, designed.

string

The recommendation id (rec_…) this choice came from.At most 200 characters.

Ext

Workflow

A workflow is a graph with two kinds of vertex. A piece is one unit of agent (or command) work; an artifact is what pieces consume and produce. Edges only join a piece and an artifact. A workflow shape: piece and artifact vertices, typed edges, and the control policy.

string

Catalog or user workflow id. Excluded from the configuration id hash.At most 200 characters.

integer

Excluded from the configuration id hash.

ShortText

Excluded from the configuration id hash.

Piece[]

required

WorkflowArtifact[]

array[]

Pairs [from, to]. Piece to artifact means produces; artifact to piece means consumes. Every edge joins a piece and an artifact and the graph is acyclic (E192); the repair loop lives in control.repair, not in an edge. Artifacts with no producer are inputs; with no consumer, outputs.

Control

Ext

An edge [piece, artifact] means the piece produces the artifact; [artifact, piece] means the piece consumes it. An artifact with no producer is an input, one with no consumer an output.
Piece and artifact ids share one namespace and MUST be unique in it, every edge MUST join a piece and an artifact that exist, and the edges MUST NOT form a cycle (E192). A repair loop is written in control.repair, never as an edge.
A nested workflow is checked the same way.

A workflow MAY be given by reference instead of inline. A reader resolves the reference through its catalog; a reader that cannot resolve it skips E190 and E191. A workflow by reference instead of inline.

string

required

A catalog or user workflow id, e.g. plan_implement_review.At most 200 characters.

integer

Ext

Pieces

A piece vertex: one unit of agent (or command) work in the workflow.

required

Vertex id, unique across the workflow’s pieces and artifacts.

string

What the piece does. loopmath writes planner, implementer, reviewer, tester, referee, worker; readers never rewrite roles.Recommended values (open set): planner, implementer, reviewer, tester, referee, worker, plan, implement, review, test, integrate, select, research, docs.At most 100 characters.

integer

Parallel copies of the piece (best of n). 1 when absent.

Workflow | WorkflowRef

A nested workflow. A piece may have a role, a nested workflow, both or neither.

Ext

role is an open string. loopmath writes planner, implementer, reviewer, tester, referee and worker. A reader MUST NOT rewrite a role into its own vocabulary; it compares roles as written.
width above 1 runs that many copies of the piece in parallel, as in best of n.
A piece may name a role, hold a nested workflow, do both, or do neither: the schema requires only id, and 0.3 allows all four. A piece that holds a nested workflow and has no role needs no setting (E191); every other top-level piece does.

Artifacts

An artifact vertex: what pieces consume and produce.

required

Vertex id, unique across the workflow’s pieces and artifacts.

string

What the artifact is.Recommended values (open set): issue, repo, plan, spec, diff, review, verdict, test_record, report, other.At most 100 characters.

Ext

Control

The control policy: gates, the repair map, the repair budget and the rescue.

string[]

Piece ids whose output is a verdict (E193: each names a piece).

map of string

Gate id to the piece that reruns when the gate rejects (E193: keys are gates, values are pieces).

integer

Rounds allowed, including the first. 1 means no repair; a missing or 0 budget reads as 1.

Rescue

Ext

Extension data. The key dev.loopmath.gate_rules (piece id to a gate rule other than the role’s default) is part of the configuration id.

budget counts rounds including the first. A budget of 1 means no repair, and a missing or 0 budget reads as 1.
Every control.gates entry MUST name a piece, every control.repair key MUST be a gate, and every control.repair value MUST be a piece (E193).
The extension key dev.loopmath.gate_rules maps a gate to a rule other than its role’s default. Because it changes what ran, it is part of the configuration id, the one ext key that is.

string

required

The fallback when the workflow ends without acceptance. configuration: redo with the configuration in ref (usually the user’s usual one). person: a person does it. none: no fallback.Recommended values (open set): configuration, person, none.At most 100 characters.

string

At most 200 characters.

number

Ext

Settings

settings maps each piece id to the setting it ran with. Every top-level piece of the workflow MUST have an object in settings under its id, except a piece that holds a nested workflow and has no role (E191). How one piece runs: harness, model, reasoning effort, context policy and harness options.

string

The harness that runs the piece. command marks a mechanical gate whose command is in options.command.Recommended values (open set): claude-code, codex, command.At most 100 characters.

ModelRef

string

Reasoning-effort label as configured (low, medium, high, xhigh, max, default); harness-specific values kept verbatim.At most 100 characters.

string

Open string; fresh when absent.Recommended values (open set): fresh, inherit, summary, default.At most 100 characters.

object

Harness options, e.g. {“command”: “pytest -q”} for a command gate.

Ext

A setting without context_policy reads as fresh.
harness: "command" marks a mechanical gate, such as a test run, whose command is in options.command.
An attempt carries its own setting only when it differs from the configuration’s setting for its piece. Such overrides are not part of the configuration id. node.vertex and attempt.vertex name the piece a node or attempt executes, and attempt.round the repair round, from 1.

Configuration id

configuration.id is cfg_ followed by the first 12 hexadecimal digits of the SHA-256 digest of the canonical JSON of {"workflow": W, "settings": S}. The canonical form keeps the declared workflow and baseline settings and drops labels, so renaming a workflow or giving it a new version does not change the id, and changing a model or a budget does. Per-attempt setting overrides are outside the id. A document whose id does not match its workflow and settings fails E190.

Resolve the workflow

If the workflow is a reference {ref, version} without pieces, replace it with the catalog workflow it names.

Canonicalize the workflow (W)

Keep exactly four keys, and drop the workflow’s id, version, title, ext and any other field:

pieces: each piece object as {id, width}, with width 1 when absent, plus role when present and workflow when present (a nested workflow is canonicalized the same way). Other piece fields are dropped. Sorted by id; [] when absent.
artifacts: each artifact object as {id}, plus kind when present. Sorted by id; [] when absent.
edges: the [from, to] pairs, sorted by the string forms of their two ends; [] when absent.
control: gates sorted, [] when absent; repair as given, {} when absent; budget as max(1, budget) when it is an integer and 1 otherwise, so a missing budget and a number with a fraction part such as 2.0 both read as 1; rescue reduced to its kind and ref, only when present; and gate_rules, the value of control.ext["dev.loopmath.gate_rules"], only when present and not empty. Other ext keys are dropped. An absent control reads as {"budget": 1, "gates": [], "repair": {}}.

Canonicalize the settings (S)

Map every key of settings, not only the piece ids, to {harness, model, effort, context_policy, options}: harness as given, else null; model is the modelRef’s id, else its raw, else a bare string as given, else null; effort is "default" when absent, context_policy "fresh" and options {}. The setting’s ext is dropped.

Serialize

Write {"workflow": W, "settings": S} as JSON with object keys sorted at every level, no whitespace (separators , and :), non-ASCII characters written as themselves, and encode it as UTF-8.

Hash

Take the SHA-256 digest of those bytes, in lowercase hexadecimal. The id is cfg_ plus its first 12 digits.

Worked example

A one-piece workflow, solo: one agent reads the issue and the repository and writes a diff.

{
  "workflow": {
    "id": "solo", "version": 1, "title": "One agent implements",
    "pieces": [{ "id": "implement", "role": "implementer", "width": 1 }],
    "artifacts": [{ "id": "issue", "kind": "issue" }, { "id": "repo", "kind": "repo" }, { "id": "diff", "kind": "diff" }],
    "edges": [["issue", "implement"], ["repo", "implement"], ["implement", "diff"]],
    "control": { "gates": [], "repair": {}, "budget": 1, "rescue": { "kind": "configuration", "ref": "usual" } }
  },
  "settings": {
    "implement": { "harness": "claude-code", "model": { "raw": "claude-opus-5-5", "id": "claude-opus-5-5" }, "effort": "high", "context_policy": "fresh", "options": {} }
  }
}

{"settings":{"implement":{"context_policy":"fresh","effort":"high","harness":"claude-code","model":"claude-opus-5-5","options":{}}},"workflow":{"artifacts":[{"id":"diff","kind":"diff"},{"id":"issue","kind":"issue"},{"id":"repo","kind":"repo"}],"control":{"budget":1,"gates":[],"repair":{},"rescue":{"kind":"configuration","ref":"usual"}},"edges":[["implement","diff"],["issue","implement"],["repo","implement"]],"pieces":[{"id":"implement","role":"implementer","width":1}]}}

cfg_261aaa36000b

Try it

Paste a configuration, or a whole OCP document, to compute its id. loopmath’s loopmath.ocp.canonical.config_id is the reference implementation, and loopmath ocp validate checks it as E190. Numbers are written as the reference implementation’s JSON encoder writes them, so 2.0 in options stays 2.0. The calculator above was tested against the reference implementation on randomly generated configurations and on every example document. A producer that computes ids in another language should check its output the same way, for example on the documents in examples/v0.3/, whose ids all verify.

Why it ran

source says why this configuration ran: the user’s usual workflow, an alternative a recommender offered, an exploration pick, a user_edit of a suggestion, habit for a logged run, or designed by a planner. rec names the recommendation the choice came from. Provenance says whether the run was logged or designed.

Rules

Rule	Checks
E190	`configuration.id` equals the canonical id of its workflow and settings.
E191	Every top-level piece has a setting, except one that holds a nested workflow and has no role.
E192	Unique vertex ids, edges that join an existing piece and artifact, no cycles; nested workflows too.
E193	Gates are pieces; the repair map runs from a gate to a piece.

Specification

The document

The observation

Conformance

Reference

Workflow

Pieces

Artifacts

Control

Settings

Configuration id

Worked example

Try it

Why it ran

Rules

​Workflow

​Pieces

​Artifacts

​Control

​Settings

​Configuration id

​Worked example

​Try it

​Why it ran

​Rules

Workflow

Pieces

Artifacts

Control

Settings

Configuration id

Worked example

Try it

Why it ran

Rules