Skip to content

Artifact contracts

A task class says what kind of work this is. Its artifact contract says what the run must produce, how that is checked, and what happens when a check fails. The contract is a sibling file referenced by the task class, so verification policy can change without touching routing.

flowchart LR
    TC["task_class.yaml<br/>artifact_contract_ref"] --> AC["artifact_contract.yaml"]
    AC --> V1["success_verifiers[0]"]
    V1 -- pass --> V2["success_verifiers[1]"]
    V2 -- pass --> OK["artifact accepted"]
    V1 -- fail --> FP["failure_policy"]
    V2 -- fail --> FP
    FP --> RC["request_changes"]
    FP --> ES["escalate"]
    FP --> RB["rollback"]

Required fields

Field Required Meaning
task_class yes Must match the task class name
expected_artifact yes patch · prose · plan · image · data · composite
failure_policy yes request_changes · escalate · rollback

expected_artifact

Value The run produces
patch A git diff or PR-shaped change
prose Markdown or documentation
plan A structured plan document
image A generated image
data A structured data file
composite More than one of the above

A verifier may check more than the declared kind, but the kind tells the executor and the publisher what "the artifact" means.

Verification

success_verifiers:
  - verifiers/typecheck.py
  - verifiers/test.py
  - verifiers/metamorphic.py
  • Entries are ordered and evaluated in sequence.
  • First failure short-circuits — later verifiers do not run.
  • Every named verifier must exist in the verifier contract registry.
  • All of them must pass for the artifact to be accepted.

A verifier that cannot produce a discriminating signal reports vacuous. Verify records that as unmeasured, never as a pass. This is deliberate: "the check did not run" and "the check passed" must not collapse into the same verdict.

Failure policy

Policy On failure
request_changes Send findings back to the implementer for bounded revise rounds
escalate Open an inbox item for a human
rollback Invoke rollback_policy immediately

request_changes is the common choice for code. The workflow's retries edges decide how many rounds are spent before an escalates_to edge fires.

Rollback

failure_policy: request_changes
rollback_policy: >
  git checkout HEAD -- <changed-files>
  if reviewer rejects after 3 iterations.

rollback_policy is free text that documents the procedure, and must name a workflow node of type rollback or a named rollback script when it is actually invoked. The workflow's rollback_strategy names the rollback node.

Output declaration

Optional fields that make a run's outputs discoverable:

Field Default Meaning
outputs [] Declared run outputs. Each entry is a path string or {path, mime, description, required}. Paths may use ${MINI_ORK_RUN_DIR}
source_artifact — Run-dir-relative primary artifact handed to publishing or review
artifact_path_template .mini-ork/artifacts/{run_id}/{task_class} Where the artifact is expected; supports {run_id}, {task_class}, {timestamp}
max_size_bytes 0 Size ceiling; 0 = no limit
retention_days 30 Artifact retention; 0 = forever
description — Human-readable summary
tags [] Free-form labels

outputs is checked by mini-ork validate and mini-ork garden, and published by the executor. That makes a missing output a static finding rather than a surprise at delivery time.

Example

The shipped code-fix contract:

task_class: code_fix
expected_artifact: patch

success_verifiers:
  - verifiers/typecheck.py
  - verifiers/test.py
  - verifiers/metamorphic.py

failure_policy: request_changes

rollback_policy: >
  git checkout HEAD -- <changed-files>
  if reviewer rejects after 3 iterations.

Read it as a claim: a code-fix run is accepted only if typing passes, the test suite passes, and the metamorphic layer either holds or reports vacuous — the first two are what a PROVEN verdict actually rests on.

Contract versus workflow

The contract governs acceptance. The workflow governs execution — which nodes run, in what order, on which lane. A gate in workflow.yaml and a verifier in artifact_contract.yaml are different mechanisms even when they test similar things; the contract's verifiers are the acceptance list.