Skip to content

docs: add contract.yaml cheatsheet reference and monitor-alert-escalate pattern (#29, #30) #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Skull-boy merged 1 commit into from
Sep 2, 2026
Merged

docs: add contract.yaml cheatsheet reference and monitor-alert-escalate pattern (#29, #30) #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions docs/contract-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# 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:`<br>&nbsp;&nbsp;`name: issue-triage`<br>&nbsp;&nbsp;`purpose: Triages new bug reports`<br>&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`mode: request-response`<br>&nbsp;&nbsp;`initiation: human-only`<br>&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`- name: webhook_payload`<br>&nbsp;&nbsp;&nbsp;&nbsp;`type: payload`<br>&nbsp;&nbsp;&nbsp;&nbsp;`required: true` | Specifying internal execution variables rather than true external inputs. |
| `outputs` | **Yes** | Results, structured artifacts, or return objects generated by the system. | `outputs:`<br>&nbsp;&nbsp;`- name: triage_summary`<br>&nbsp;&nbsp;&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`- resource: github_issues`<br>&nbsp;&nbsp;&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`- type: comment`<br>&nbsp;&nbsp;&nbsp;&nbsp;`resource: github_issues`<br>&nbsp;&nbsp;&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`strategy: retry`<br>&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`mode: idempotent`<br>&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`- name: GitHub API`<br>&nbsp;&nbsp;&nbsp;&nbsp;`type: api`<br>&nbsp;&nbsp;&nbsp;&nbsp;`required: true` | Listing internal module imports rather than external operational dependencies. |
| `state` | **Yes** | Persistence tier, storage mechanism, and scope across executions. | `state:`<br>&nbsp;&nbsp;`persistence: ephemeral`<br>&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`level: basic`<br>&nbsp;&nbsp;`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:`<br>&nbsp;&nbsp;`level: low` | Marking an agent taking financial or destructive actions as `low` risk. |
| `security` | Optional | Sandboxing, transport encryption, and authentication constraints. | `security:`<br>&nbsp;&nbsp;`auth_required: true`<br>&nbsp;&nbsp;`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:

```yaml
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
```
92 changes: 92 additions & 0 deletions patterns/monitor-alert-escalate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Pattern: Monitor → Alert → Escalate

**Status:** Proposed / Active
**Category:** Operational / Observability / Safety pattern

---

## Intent

The **Monitor → Alert → Escalate** pattern governs ongoing, non-single-shot workflows and agents that continuously watch external or internal state sources over time, filter routine background activity, alert when defined operational thresholds or anomalies are crossed, and escalate to human decision-makers only when severity or confidence warrants intervention.

---

## When to Use It

- **Continuous tracking:** You are watching a high-volume continuous stream, polling an API, checking uptime, tracking metrics, or monitoring external data (e.g. competitor updates, cloud spend, error rates).
- **Tiered severity handling:** Routine events or minor variations require automated self-healing, caching, or silent logging, whereas medium anomalies require team alerts and critical failures require active human escalation.
- **Asymmetric human attention:** Humans cannot review every single event in real time, but must be in the loop for high-impact or ambiguous edge cases.
- **Cost / Token budget management:** Continually summarizing or filtering signals at low cost, reserving expensive actions or alerts for verified incidents.

---

## When NOT to Use It

- **Single-shot reactive tasks:** If a workflow executes once in response to an explicit user webhook or pull request to perform a direct verification, use [`detect-judge-approve-act`](./detect-judge-approve-act.md) instead.
- **Purely passive cron pipelines:** If a scheduled task just performs an ETL batch transform with deterministic outputs and no stateful thresholding or alerting logic.
- **Fully autonomous destructive loops:** If an agent is expected to execute critical irreversible external modifications without human escalation gates.

---

## Structure

```
Continuous Watch
│
▼
┌─────────────┐
│ MONITOR │ ◀─── (Poll / Webhook / Stream)
└──────┬──────┘
│
Threshold / Anomaly?
┌────────┴────────┐
│ │
[No / Below] [Yes / Match]
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ Log/Cache │ │ ALERT │
│ (Silent) │ └─────┬─────┘
└───────────┘ │
Severity Level?
┌──────┴──────┐
│ │
[Medium/Info] [Critical]
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ Broadcast │ │ ESCALATE │
│ (Channel) │ │ (Human- │
└───────────┘ │ in-Loop) │
└───────────┘
```

The pattern is structured across three core stages:

1. **Monitor (Ingest & Filter)** — Ingests updates from the target stream or schedule. Evaluates raw data against baseline conditions, ignoring noise and recording telemetry state silently.
2. **Alert (Format & Notify)** — When an event breaches operational thresholds or matches pattern heuristics, the agent generates structured alerts (e.g. posting digests to a dedicated notification channel, tagging teams, or updating dashboards).
3. **Escalate (Human-in-the-Loop Intervene)** — When severity surpasses automated response boundaries, ambiguity is detected, or irreversible actions are required, the agent triggers an escalation gate, waiting for human confirmation or handing over full incident control.

---

## Contract Requirements

When declaring a `contract.yaml` implementing the Monitor → Alert → Escalate pattern, the following fields are critical:

- `lifecycle.mode`: Typically `scheduled` or `persistent`, reflecting ongoing execution rather than one-off `request-response`.
- `lifecycle.idle_behavior`: Bounded description of polling intervals or background standby logic.
- `permissions`: Granular read scopes for monitored streams and bounded write scopes for alert channels (e.g., `slack:chat:write`, `github:issues:write`).
- `approval_points`: Explicit escalation triggers (actions requiring human intervention before proceeding).
- `side_effects`: Clearly partitioned between low-severity notification emits and high-severity escalation actions.
- `state`: Explicit state persistence configuration (e.g. tracking last-seen timestamp, event hashes, or baseline watermarks).
- `observability`: Set to `audit` or `verbose` to capture telemetry and threshold breach history.

---

## Known Implementations

| Framework | Implementation | Contract |
|---|---|---|
| n8n | [`competitor-feature-parity-watcher`](../implementations/n8n/competitor-feature-parity-watcher) | [contract.yaml](../implementations/n8n/competitor-feature-parity-watcher/contract.yaml) |

*(Additional implementations across LangGraph and custom daemon agents can be proposed through the RFC process.)*
Loading