Schemas¶

mini-ork validates three files before a run starts: the task class, the workflow and the artifact contract. A recipe is a directory containing one of each. The schemas themselves live in schemas/ in the repository and are JSON Schema (draft 2020-12).

Two commands use them:

mini-ork validate        # static checks over the project's recipes
mini-ork recipe-eval     # author-time lint of one recipe definition

A malformed recipe is rejected at load time, not halfway through a run.

This page covers the file schemas

The SQLite state schema — task_runs, epics, execution_traces and the rest — is documented separately in docs/SCHEMA.md.

The three recipe files¶

flowchart LR
    TC[task_class.yaml] -->|default_workflow| WF[workflow.yaml]
    TC -->|artifact_contract_ref| AC[artifact_contract.yaml]
    WF -->|nodes, edges, gates| R[run]
    AC -->|verifiers, failure policy| R

File	Schema	Answers
`task_class.yaml`	`task_class.schema.json`	When does this recipe apply, and how risky is it?
`workflow.yaml`	`workflow.schema.json`	Which agents run, in what order, with which gates?
`artifact_contract.yaml`	`artifact_contract.schema.json`	What must come out, and what happens when it fails?

task_class.schema.json¶

Describes a category of work. The classifier scores a kickoff against every task class and picks the best match.

Required fields¶

Field	Type	Meaning
`name`	string, `^[a-z][a-z0-9_-]*$`	Canonical identifier, unique across the registry
`description`	string, ≥ 10 chars	What belongs in this class
`default_workflow`	string	Workflow used when no override is given
`risk_class`	`low` \| `medium` \| `high` \| `critical`	Promotion and review policy

Optional fields¶

Field	Type	Default	Meaning
`task_class`	string	—	Alias kept by recipe-local files; must equal `name`
`version`	string	—	Recipe version, e.g. `0.1.0`
`artifact_contract_ref`	string	`""`	Contract governing outputs
`matches`	object	—	Routing matchers: `keywords`, `regex`, `path_globs`
`default_gates`	array	`[]`	Gates applied to every run of this class
`max_parallel_runs`	integer	`0`	Concurrency cap; `0` = unlimited
`budget_cap_usd`	number	`0`	Per-run ceiling; `0` = inherit global
`tags`	array	`[]`	Free-form labels
`heterogeneity`	object	—	Advisory lane-diversity declarations

matches is evaluated in order — keywords, then regex, then path globs — and the first match wins. regex uses POSIX ERE against the task title and description concatenation.

Risk classes¶

Risk	What it unlocks
`low`	Auto-promotion is acceptable
`medium`	Shadow and benchmark before promotion
`high`	Human gate required
`critical`	Dual human approval plus an immutable safety check

Minimal valid example¶

name: code_fix
description: "Single-patch code change: bug fix, small feature, refactor of a single function"
artifact_contract_ref: artifact_contract.yaml
default_workflow: workflow.yaml
matches:
  keywords: [fix, bug, patch, update, refactor]
  path_globs: ["**/*"]
  regex: []
default_gates: [scope_gate, budget_gate, deployment_gate]
risk_class: medium

workflow.schema.json¶

Defines a named DAG of agent nodes. The graph must be acyclic; bounded recursion is declared explicitly under recursion.

Required top-level fields¶

Field	Type	Meaning
`version`	string	Sequential or semantic version
`task_class`	string	Must match a task class `name`
`nodes`	array, ≥ 1	Agent invocations
`edges`	array	Directed edges between nodes

Optional top-level fields¶

Field	Type	Meaning
`rollback_strategy`	string	Node name invoked when a hard-fail gate fires
`description`	string	Human-readable summary
`dispatch_mode`	`serial` \| `parallel` \| `partitioned` \| `speculative`	Default for nodes that omit it
`max_self_correction_iterations`	integer	Bounded repair rounds
`recursion`	object	`max_iterations`, `convergence_check`, per-iteration and total budget caps, `divergence_kill`
`source_artifact`	string \| null	Final artifact used by publishing or review
`human_decision_artifact`	string \| null	Records a human approval boundary
`selected_option_artifact`	string \| null	Records the option chosen after a decision gate
`tags`	array	Free-form labels

Node fields¶

A node requires name, type and dispatch_mode.

Field	Type	Meaning
`name`	string	Unique within the workflow
`type`	enum	`planner`, `researcher`, `transform`, `implementer`, `reviewer`, `verifier`, `eval`, `reflector`, `publisher`, `rollback`
`model_lane`	string	Lane hint, default `sonnet`; role names resolve through `agents.yaml`
`dispatch_mode`	enum	`serial`, `parallel`, `partitioned`, `speculative`
`gates`	array	Gate IDs that must pass before the node is done
`prompt_ref`	string \| null	Prompt template path or key
`verifier_ref`	string \| null	Recipe-relative verifier script
`timeout_minutes`	integer	Hard timeout; `0` = inherit
`max_cost_usd`	number	Per-invocation ceiling; `0` = none
`retries`	integer, 0–5	Retry count before escalation
`partition_key`	string	Input key used to shard work
`requires_capabilities`	string \| array	Provider capabilities the node needs
`tools`	array \| object	Harness tools, optionally split into `native` and `mcp`
`mcp_servers`	array	MCP servers the node may reach
`skills`	array	Skills the node may load
`agent_doc`	string	Instruction document injected into dispatch
`env`	object	Variables declared by the recipe, `${NAME}` resolved at the node boundary
`transform`	string	Deterministic transform identifier (transform nodes)
`strict_handshake`	boolean	Disable artifact-based completion; the self-report is the deliverable
`inputs` / `outputs`	object / array	Typed artifact ports
`retry`	object	Infrastructure retry policy: `max_attempts`, `initial_interval`, `backoff_factor`, `max_interval`, `jitter`

A node's tool grants are the union of tools and mcp_servers; nothing else is visible to it. The shipped recipes follow a structural invariant: no single node holds repo-write, untrusted-content ingress and an outbound channel at once.

Edge types¶

`edge_type`	Meaning
`depends_on`	Ordering only
`supplies_context_to`	Artifact handoff
`verifies`	Verifier applies to the producer
`blocks`	Producer must finish before consumer starts
`retries`	Bounded revise loop; the only edge type that consumes `condition`
`escalates_to`	Operator escalation path
`human_decision_gate`	Stops for human input
`verifies_user_choice`	Checks the selected option

Edges may also declare from_output / to_input for explicit artifact handoffs, and recursive: true for control edges excluded from readiness ordering.

A condition may be a legacy string (preserved but inert) or a JSON-schema predicate:

- from: reviewer
  to: implementer
  edge_type: retries
  condition:
    pointer: /verdict
    match: { const: revise }

Minimal valid example¶

version: "0.1.0"
task_class: code_fix
description: "Single-patch fix with typecheck, test and review"

nodes:
  - name: planner
    type: planner
    model_lane: planner
    prompt_ref: prompts/planner.md
    dispatch_mode: serial

  - name: implementer
    type: implementer
    model_lane: worker
    prompt_ref: prompts/implementer.md
    dispatch_mode: serial
    gates: [scope_gate, budget_gate]

  - name: test
    type: verifier
    verifier_ref: verifiers/test.py
    dispatch_mode: serial

edges:
  - { from: planner, to: implementer, edge_type: supplies_context_to }
  - { from: implementer, to: test, edge_type: verifies }

artifact_contract.schema.json¶

Declares what a task class must produce and how failure is handled. One contract per task class, referenced by artifact_contract_ref.

Required fields¶

Field	Type	Meaning
`task_class`	string	Must match the task class `name`
`expected_artifact`	`patch` \| `prose` \| `plan` \| `image` \| `data` \| `composite`	Primary output kind
`failure_policy`	`request_changes` \| `escalate` \| `rollback`	What happens when a verifier fails

Optional fields¶

Field	Type	Default	Meaning
`success_verifiers`	array	`[]`	Ordered verifier names; first failure short-circuits
`rollback_policy`	string	`""`	Procedure run when policy is `rollback`
`artifact_path_template`	string	`.mini-ork/artifacts/{run_id}/{task_class}`	Where verifiers look
`max_size_bytes`	integer	`0`	Size ceiling; `0` = none
`retention_days`	integer	`30`	Retention before purge; `0` = forever
`source_artifact`	string \| null	—	Primary artifact handed to publishing
`outputs`	array	`[]`	Bare paths or `{path, mime, description, required}`
`description`	string	—	Human-readable summary
`tags`	array	`[]`	Free-form labels

success_verifiers entries reference verifier scripts or registered verifiers. A verifier that cannot produce a trustworthy signal reports vacuous, which the run records as unmeasured — never as a pass.

Minimal valid example¶

task_class: code_fix
expected_artifact: patch
success_verifiers:
  - verifiers/typecheck.py
  - verifiers/test.py
failure_policy: request_changes

Certificate schema (`mini-ork.certificate/v1`)¶

mini-ork certify writes a certificate JSON alongside its summary. Every key is required and load-bearing; the schema id is the literal string mini-ork.certificate/v1.

Key	Contents
`schema`	`mini-ork.certificate/v1`
`id`	Certificate UUID
`issued_at`	UTC timestamp
`verdict`	`PROVEN`, `REFUTED` or `UNVERIFIED`
`reason`	One-line explanation of the verdict
`repo`	`path`, `remote`, `base`, `head`
`change`	`sha256` of the patch, plus the list of files it touches
`claim`	`sha256` of the issue text and the first 200 characters
`method`	`oracle`, `mr_n`, `proven_bar`, `model`, `image`, optional `context_files`
`evidence`	`probe` result, `mr_pass_rate`, per-invariant records
`cost`	`usd` and `llm_calls`
`duration_s`	Wall-clock seconds
`digest`	SHA-256 over the canonical JSON of every other key

The digest is computed with sorted keys and compact separators, so it can be re-derived byte-for-byte elsewhere. Any added or removed key changes the digest — that is deliberate.

{
  "schema": "mini-ork.certificate/v1",
  "verdict": "PROVEN",
  "reason": "the fix holds across 100% of 4 perturbed inputs",
  "change": { "sha256": "506d…", "files": ["stats.py"] },
  "method": { "oracle": "metamorphic", "mr_n": 4, "proven_bar": 0.667 },
  "digest": "…"
}

The certificate is the durable, auditable record: the probe, the invariants, hashes of both the change and the claim, and the digest. It is what CI gates on and what a reviewer reads instead of trusting the run's prose.

Other schemas in the repository¶

Schema	Used for
`environment.schema.json`	Environment and node profile definitions
`verifier_contract.schema.json`	Verifier registration and capability contract
`verifier_card.schema.json`	Per-verifier metadata
`agent_version.schema.json`	Versioned agent configuration
`ask.schema.json`	Operator questions and answers
`spec-card.schema.json`, `spec-index.schema.json`	Spec-driven delivery artifacts
`metrics_sdd.schema.json`	Spec-driven development metrics

Schemas¶

The three recipe files¶

task_class.schema.json¶

Required fields¶

Optional fields¶

Risk classes¶

Minimal valid example¶

workflow.schema.json¶

Required top-level fields¶

Optional top-level fields¶

Node fields¶

Edge types¶

Minimal valid example¶

artifact_contract.schema.json¶

Required fields¶

Optional fields¶

Minimal valid example¶

Certificate schema (mini-ork.certificate/v1)¶

Other schemas in the repository¶

Related¶

Certificate schema (`mini-ork.certificate/v1`)¶