contract-reference.md

Contract Field Reference & Cheatsheet

This cheatsheet provides a fast, one-page reference for writing a valid contract.yaml (v1.1) for workflows and agent systems without needing to read the entire normative specification.

---

📋 Field Reference Table

Field	Required?	What it means	Minimal example	Common mistake
version / contract_version	Yes	Schema version discriminator targeting the specification version (use "1.1").	version: "1.1"	Omitting quotes when specifying numeric strings or using unsupported version numbers.
system	Yes (or legacy agent/workflow)	Core identity block containing name, version, and natural language purpose.	system:   name: issue-triage   purpose: Triages new bug reports   version: "1.0.0"	Leaving name empty or omitting required identity metadata.
lifecycle	Yes	Execution model, invocation trigger, resumability behavior, and idle activity limits.	lifecycle:   mode: request-response   initiation: human-only   resumability: stateless	Omitting idle_behavior when mode: persistent is specified.
inputs	Yes	Data artifacts and event streams entering the system, along with source requirements.	inputs:   - name: webhook_payload     type: payload     required: true	Specifying internal execution variables rather than true external inputs.
outputs	Yes	Results, structured artifacts, or return objects generated by the system.	outputs:   - name: triage_summary     type: document	Documenting side effects (e.g. comments posted) as outputs instead of distinct data payloads.
permissions	Yes	Granular external resource scopes and action permissions required to run.	permissions:   - resource: github_issues     actions: [read, write]	Using wildcard permissions (e.g. github:* or admin:full), which fail schema validation and linter checks.
side_effects	Yes	External, observable actions performed in the real world (comments, DB writes, messages).	side_effects:   - type: comment     resource: github_issues     description: Posts triage label	Omitting side effects that alter third-party systems or failing to flag irreversible: true when appropriate.
approval_points / approvals	Yes	Explicit checkpoints where human sign-off is required before continuing execution.	approval_points: []	Leaving this field out entirely instead of declaring [] when no human approval is required.
recovery / recovery_strategy	Yes	Error handling and recovery behavior on dependency failure (retry, stop, rollback, human_escalation, fallback).	recovery:   strategy: retry   details: Retries on 5xx up to 3 times	Specifying unstructured strategies not matching standard recovery semantics.
replay / replay_semantics	Yes	Idempotency and replay safety when triggered repeatedly with identical inputs (idempotent, non_idempotent, conditional, prohibited).	replay:   mode: idempotent   details: Upserts by record ID	Claiming idempotency when repeated runs produce duplicate side effects (e.g. multiple comments).
dependencies	Yes	External APIs, services, databases, or runtime libraries required to execute.	dependencies:   - name: GitHub API     type: api     required: true	Listing internal module imports rather than external operational dependencies.
state	Yes	Persistence tier, storage mechanism, and scope across executions.	state:   persistence: ephemeral   storage: memory	Claiming none when vectors, tokens, or cache records persist between triggers.
observability	Yes	Telemetry, logging level (none, basic, audit, verbose), and notification sinks.	observability:   level: basic   sinks: [github_issue]	Emitting sensitive credential data or logs into insecure public sinks.
risk	Optional	Risk assessment tier (low, medium, high, critical) and hazard categories.	risk:   level: low	Marking an agent taking financial or destructive actions as low risk.
security	Optional	Sandboxing, transport encryption, and authentication constraints.	security:   auth_required: true   sandbox_required: true	Assuming unauthenticated trigger endpoints are safe.

---

⚡ Minimal Valid contract.yaml

Below is a complete, minimal, and fully schema-compliant contract.yaml (v1.1) that you can copy, paste, and adapt for any new workflow:

version: "1.1"
contract_version: "1.1"

system:
  name: my-minimal-agent
  purpose: Example minimal agent workflow description
  version: "1.0.0"

lifecycle:
  mode: request-response     # request-response | persistent | scheduled
  initiation: human-only     # human-only | schedule | self | agent
  resumability: stateless   # stateless | context-snapshot | replay-from-log

inputs:
  - name: input_data
    type: document
    required: true

outputs:
  - name: output_data
    type: document

permissions:
  - resource: service_api
    actions: [read]

side_effects: []            # List side effects or [] if read-only

approval_points: []         # List human gates or [] if fully automated

recovery:
  strategy: stop            # stop | retry | rollback | human_escalation | fallback
  details: Fails execution and logs error if API is unreachable

replay:
  mode: idempotent          # idempotent | non_idempotent | conditional | prohibited
  details: Pure read-only operation; safe to repeat anytime

dependencies:
  - name: Service API
    type: api
    required: true

state:
  persistence: none         # none | session | persistent | ephemeral
  storage: none

observability:
  level: basic              # none | basic | audit | verbose
  sinks: [stdout]

risk:
  level: low                # low | medium | high | critical