From 4a780c47572872c21f3b96279eb51a0dcda5ce67 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:22:38 -0400 Subject: [PATCH] feat(skill): promise-theory templates + human README Add the three fillable templates (promise manifest YAML, agent contract, promise review) and the human-facing README with the five required sections. The manifest template is a lint-clean, fully covered example of the pinned v1 schema with per-field comments; all intra-template id references (accepts, expectations.about) resolve cross-agent. The contract template carries the seven mandated sections with schema-aligned severity and type vocabulary; the review template carries the five retrospective sections with the three diagnosis categories. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- promise-theory/README.md | 44 ++++++ .../templates/agent-contract.md.tmpl | 128 ++++++++++++++++++ .../templates/promise-manifest.yaml.tmpl | 100 ++++++++++++++ .../templates/promise-review.md.tmpl | 75 ++++++++++ 4 files changed, 347 insertions(+) create mode 100644 promise-theory/README.md create mode 100644 promise-theory/templates/agent-contract.md.tmpl create mode 100644 promise-theory/templates/promise-manifest.yaml.tmpl create mode 100644 promise-theory/templates/promise-review.md.tmpl diff --git a/promise-theory/README.md b/promise-theory/README.md new file mode 100644 index 0000000..d1e07b8 --- /dev/null +++ b/promise-theory/README.md @@ -0,0 +1,44 @@ +# Promise Theory + +Coordinate hybrid human + AI agent workforces with promises, acceptances, and assessments — the promise-theory method of Mark Burgess and Jan Bergstra, made practical for agents. + +## Why Install This Skill + +Multi-agent systems fail in predictable ways: agents over-promise, refuse what was sent to them, drift from their instructions, and afterward nobody can say who promised what, who accepted, and whether it was kept. This skill gives your agent a vocabulary and a working method for that problem: model delegation as voluntary promises plus acceptance, then verify and renegotiate on a schedule instead of guessing. + +After installing, your agent can draft a promise manifest for a team of agents and humans, turn it into a signed agent contract with acceptance criteria, verification, and escalation rules, and run retrospectives that turn breaches into renegotiated promise sets rather than blame. The skill is grounded in promise theory's academic foundations and its proven use in infrastructure (CFEngine, Kubernetes-style convergence) and applies both to today's hybrid human + agent teams. + +## What You Get + +| Contents | Provides | +|---|---| +| `SKILL.md` | When to use promise theory, when not to, and what to load for the task at hand | +| `references/` | Seven load-on-demand references: foundations, infrastructure applications, agent coordination, coordination patterns, trust and verification, diagnosis and debugging, glossary | +| `templates/` | Fillable `promise-manifest.yaml.tmpl`, `agent-contract.md.tmpl`, and `promise-review.md.tmpl` | +| `scripts/promise-contract.py` | Stdlib-only CLI that lints promise manifests and renders the promise graph | +| `evals/` | Output-quality evals for the skill | +| `tests/` | Trigger probes and unit tests | +| `LICENSE` | MIT license | + +## Quick Start + +Copy `templates/promise-manifest.yaml.tmpl` to a working file, fill in your agents, promises, and expectations (every field has a comment), then lint it: + +``` +python3 scripts/promise-contract.py lint promise-manifest.yaml +``` + +Exit 0 means the manifest is valid and every expectation maps to a promise. Then fill `agent-contract.md.tmpl` from the manifest for the humans and agents involved, and run `promise-review.md.tmpl` retrospectives on a cadence. + +## Triggers + +- Modeling delegation between humans and AI agents +- Designing capability manifests or agent contracts +- Diagnosing coordination failures: unkept promises, refused acceptances, missing assessments +- Calibrating how much to verify an agent, at what rate, and at what cost +- Designing self-healing or convergent systems +- Converting obligation-based designs to promise-based ones + +## Requirements + +Python 3.10+ for the bundled `promise-contract.py` (standard library only, no dependencies). Everything else is plain Markdown and YAML. diff --git a/promise-theory/templates/agent-contract.md.tmpl b/promise-theory/templates/agent-contract.md.tmpl new file mode 100644 index 0000000..34ef5f2 --- /dev/null +++ b/promise-theory/templates/agent-contract.md.tmpl @@ -0,0 +1,128 @@ +# Agent Contract: + +A promise has no binding force on its own; a contract is a promise *plus* a +mechanism that makes deviation costly or impossible (M12, "From Promises to +Contracts," 2026). Promise theory supplies the acceptance half; this contract +supplies the enforcement half. Fill it from a signed-off +[promise manifest](promise-manifest.yaml.tmpl): promise ids, types, bodies, +verifiers, severities, and withdrawals below must match the manifest so the +two artifacts stay in sync. Severity and verifier use the manifest schema +enums; every promise maps to a manifest `type`. + +- Contract version: <0.1.0> +- Status: +- Date: +- Manifest version this contract is drawn from: +- Renegotiation count (resets on each accepted revision): <0> + +## 1. Parties + +| Party | Side | Role in this contract | Contact / address | +|---|---|---|---| +| | Acceptor and evaluator | | | +| | Promiser | | | +| | Promiser | | | + +Every party keeps its autonomy: each promise below is made voluntarily and +can be withdrawn under the stated conditions. Nothing in this contract is a +legal instrument. + +## 2. Promise set + +For each promise in scope, record: id (from the manifest), type (manifest +enum), promiser, target, body, acceptance criteria (the observable conditions +that define "kept"), verifier (manifest enum), severity (manifest enum), and +withdrawal (the condition that ends the promise). + +| Promise id | Type (manifest) | Promiser | Target | Body | Acceptance criteria | Verifier | Severity | Withdrawal | +|---|---|---|---|---|---|---|---|---| +| | | | | | | | | | +| | <...> | <...> | <...> | <...> | <...> | <...> | <...> | <...> | + +For every consequential promise, name the enforcement rung applied (M12 +ladder from promise to contract): 1 soft prompt, 2 self-check/reflection, +3 output validation/constrained decoding, 4 external action guards, +5 capability restriction/sandboxing ("won't" becomes "can't"), 6 formal +methods/typed effects. Enforcement lives outside the model. + +| Promise id | Enforcement rung (1-6) | Notes | +|---|---|---| +| | <1-6> | | + +Degradation tier (named before any breach): , with the decision rule (fail open when liveness matters; +fail closed when safety matters). + +## 3. Verification schedule + +Who verifies which promise, how often, at what cost. Verification is a +budget (kinetic mistrust), not a free good — budget it explicitly. + +| Promise id | Verifier | Frequency / trigger | Method (eval, manual, monitor, audit) | Verification budget | +|---|---|---|---|---| +| | | | | | + +- Starting trust level for each new promiser: <50-50, or a stated prior with + reasoning> +- Promise ledger: every assessment is appended to the ledger (who assessed, + when, against what observation, verdict), stored as versioned data so + trust can accumulate. + +## 4. Breach handling + +Breach is an information event, not a moral one. On a detected breach: + +1. Record it in the promise ledger (evidence, verdict). +2. Classify the cause: specification / inter-agent conflict / verification. +3. Renegotiate first: revise the promise set (body, acceptance criteria, + verifier, severity, withdrawal), add verification, or change the provider. +4. Adjust the trust estimate and the verification rate. +5. Apply redundancy if the promise is load-bearing. + +Escalate only when renegotiation fails to converge. Named escalation trigger: +**ESCALATE-2** — escalate to +after two full renegotiation cycles (one cycle = one breach -> one contract +revision -> one verification window) without convergence. Escalation owner: + +| Escalation owner | Role | Contact / channel | Response SLA | +|---|---|---|---| +| | | <...> | | + +## 5. Review cadence + +- Review frequency: +- What is reviewed: the promise set, recent assessments, verification budget + spent, refusal and breach rates, and the trust estimates. +- Review output: a revised contract version and/or a + [promise review](promise-review.md.tmpl) for the period. +- Next review date: + +## 6. Signatures / consent + +| Party | Consent method | Signature / acceptance record | Date | +|---|---|---|---| +| | | | | +| | | | | +| | | | | + +Consent is two-sided and withdrawable: any party may withdraw a promise +under the conditions in section 2; the contract is then renegotiated, not +abandoned. + +## 7. Accountability — human commitments + +The human side of this contract makes its own promises. These are recorded +in the manifest as `expectations` entries with `from: human` and assessed on +the same review cadence as agent promises. + +| Human promise | Acceptance criteria | Verifier | Severity | Withdrawal | +|---|---|---|---|---| +| Provide direction: | | | | | +| Review agent output within | | | | <...> | +| Respond to escalations within | | | | <...> | +| Maintain consent: keep signatures and the manifest/contract version current | <...> | | | <...> | + +Human verification of agent promises: the human evaluates by +on the verification schedule in section 3, and records verdicts in the +promise ledger. diff --git a/promise-theory/templates/promise-manifest.yaml.tmpl b/promise-theory/templates/promise-manifest.yaml.tmpl new file mode 100644 index 0000000..5871918 --- /dev/null +++ b/promise-theory/templates/promise-manifest.yaml.tmpl @@ -0,0 +1,100 @@ +# promise-manifest v1 +# +# Capability and intent declaration for a set of autonomous agents. A manifest +# publishes what each agent can and will do, what it accepts from other agents, +# and what the team expects of those promises. It is the first artifact of the +# promise lifecycle: declare -> accept -> verify -> review (see the agent +# contract and promise review templates in this directory). +# +# FILLING GUIDE +# ------------- +# Replace the example ids, roles, bodies, and lists below with your own values, +# keeping the structure. Then lint the filled file with: +# +# python3 scripts/promise-contract.py lint promise-manifest.yaml +# +# The linter enforces the rules below (exit 0 = valid with full coverage; +# exit 1 = violations to fix, each named on its own line): +# +# * agent ids are unique; promise ids are unique across the WHOLE manifest +# * "human" and "all" are reserved tokens and cannot be agent ids +# * `accepts` may only list promise ids declared by a DIFFERENT agent +# (cross-agent bindings). Human acceptance is modeled via an +# `expectations` entry with `from: human`, never via `accepts`. +# * `expectations.about` must reference an existing promise id (coverage) +# * `expectations.from` is "human" or a declared agent id +# * enums: type = capability | intent | constraint | self-promise +# target = | human | all +# verifier = eval | manual | monitor | audit +# severity = impact | standard | low +# * `expires` is an ISO-8601 duration (PT15M, P30D) or a date/datetime +# (YYYY-MM-DD or RFC 3339) +# * when `type: self-promise`, target MUST equal the promising agent's own id +# +# The example values below form a valid, fully covered manifest: every +# `accepts` reference points at a promise declared by another agent, and every +# `expectations.about` points at a promise declared in this file. + +agents: + # --- Agent 1: literature summarizer -------------------------------------- + - id: research-agent # required; unique across the manifest + role: literature summarizer # required; free text + accepts: [research-direction] # optional; promise ids declared by OTHER agents + promises: # required; at least one per agent + - id: lit-review # required; unique across the whole manifest + type: capability # capability | intent | constraint | self-promise + target: human # | human | all + body: Survey and summarize literature on promise theory. + constraint: limit 20 sources # optional; non-empty when present + withdraw: when coordinator withdraws direction # optional; non-empty when present + expires: P30D # optional; duration or date/datetime + - id: evidence-tables + type: capability + target: human + body: Produce evidence tables with citations for each summary. + - id: no-fabrication + type: constraint # example of a negative capability + target: human + body: Never fabricate citations; mark unverifiable sources as unverified. + + # --- Agent 2: reviewer (accepts the summarizer's lit-review promise) ------ + - id: reviewer # unique; do not reuse another agent's id + role: fact-checker + accepts: [lit-review] + promises: + - id: fact-check + type: capability + target: research-agent # directed at another agent in the manifest + body: Verify claims against cited sources and report discrepancies. + withdraw: when the claim is outside my declared domain + + # --- Agent 3: coordinator agent (an autonomous agent, not the human) ------ + - id: coordinator + role: workflow coordinator + accepts: [evidence-tables, fact-check] + promises: + - id: research-direction + type: intent + target: research-agent + body: Provide research direction and review summaries by the agreed cadence. + - id: self-quality + type: self-promise + target: coordinator # REQUIRED: must equal this agent's own id + body: Run a self-check pass over my own output before publishing. + +expectations: # required; at least one entry + - id: exp-lit-review # required; unique + from: human # "human" or a declared agent id + about: lit-review # REQUIRED: reference an existing promise id + verifier: manual # eval | manual | monitor | audit + severity: impact # impact | standard | low + - id: exp-fact-check + from: research-agent # agents can hold expectations too + about: fact-check + verifier: eval + severity: standard + - id: exp-research-direction + from: human + about: research-direction + verifier: monitor + severity: impact diff --git a/promise-theory/templates/promise-review.md.tmpl b/promise-theory/templates/promise-review.md.tmpl new file mode 100644 index 0000000..217907d --- /dev/null +++ b/promise-theory/templates/promise-review.md.tmpl @@ -0,0 +1,75 @@ +# Promise Review: + +A retrospective is renegotiation of the team's promise set, not blame. This +template records what was promised, what was kept and breached (with +evidence), the root cause of each breach in promise-theory diagnosis +categories, the renegotiated promise set, and the resulting action items. +Promise ids below must match the promise manifest and agent contract under +review so all artifacts stay cross-referenced. + +- Review period: to +- Date of review: +- Participants (who assessed): +- Manifest version(s) under review: +- Contract version(s) under review: <0.1.0, ...> + +## 1. Promise list under review + +Every promise in scope, drawn from the manifest(s) in force during the +period. + +| Promise id | Promiser | Target | Body (from manifest) | Manifest version | +|---|---|---|---|---| +| | | | | | +| | | <...> | <...> | <...> | + +## 2. Outcomes — kept and breached, with evidence + +For every promise: verdict (kept / breached / not yet due / withdrawn), who +assessed, when, and against what observation. Cite the promise-ledger +entries, traces, eval results, or human review records that support the +verdict. + +| Promise id | Verdict | Assessed by | When | Against what observation | Evidence (ledger / trace / eval / review) | +|---|---|---|---|---|---| +| | | | | | | +| | <...> | <...> | <...> | <...> | <...> | + +## 3. Root-cause analysis — diagnosis categories + +For each breached promise, assign exactly one of the three diagnosis +categories (the multi-agent failure taxonomy mapped to promise vocabulary): + +- **specification** — broken promise body: the promise was unclear, wrong, + or unverifiable as written +- **inter-agent conflict** — failed acceptance or incompatible co-languages + between agents +- **verification** — missing or inadequate assessment: the breach was not + detected, or was detected too late + +| Breached promise id | Diagnosis category | Evidence for the diagnosis | What the category implies for the fix | +|---|---|---|---| +| | | <...> | | + +## 4. Renegotiated promise set + +The output of this review is a revised promise set: amended bodies, +acceptance criteria, verifiers, severities, and withdrawals; promises added +or retired; and any trust-estimate or verification-rate adjustments. Each +change links to the section 3 diagnosis that motivated it. Version the +revised set. + +| Promise id | Change (body / acceptance criteria / verifier / severity / withdrawal / added / retired) | New value | Reason (linked diagnosis) | +|---|---|---|---| +| | | | | +| | <...> | <...> | <...> | + +## 5. Action items + +| # | Action | Owner | Due | Verification of completion | +|---|---|---|---|---| +| 1 | | | | | +| 2 | <...> | <...> | <...> | <...> | + +When an action changes a promise or contract, fold it into the next manifest +and contract revision so the artifacts do not drift apart.