promise-theory git:20261102.514d06bA

Immutable. This exact content never changes and is served at /api/v1/blob/3b7f73770f20b7ce.

---
name: promise-theory
description: >-
  Teach promise vocabulary, fundamentals, and coordination diagnosis for promise-based
  systems. Do not use this skill for Semantic Spacetime models or SST CLI tooling; use
  `semantic-spacetime` for those model and tool workflows.
license: MIT
---

# Promise Theory

Promise theory (Mark Burgess; formalized with Jan Bergstra) is a method of
analysis for systems of autonomous agents — humans, LLM agents, APIs, and
deterministic automation. It supplies the vocabulary for designing and
diagnosing delegation: promises, acceptances, assessments, breaches, and
renegotiation. This skill is a thin router; load the dense material only when
a row in [Load By Need](#load-by-need) matches your task.

## Cross-agent design handoff

Use [multi-agent-coordination](../multi-agent-coordination/SKILL.md) for topology,
work ownership, communication contracts and collective recovery. Use this skill
for the promise/acceptance/assessment model within that design. An accepted offer
or peer approval cannot expand an execution grant; verify rights at the runtime
boundary through harness-engineering and governance through ai-governance.

When a worker has local facts and an approver has broad intent, assemble both
before assessment. Record which claim is being assessed and what evidence the
assessor can see. Repeated acceptance without relevant evidence is not calibrated
trust. If either decision context or authority is missing, hold that decision and
route it to its owner while authorized unaffected work continues.

## Core model
A promise is an autonomous declaration of intended, but as yet unverified,
behaviour from a promiser to a promisee (body: label Λ, type τ, constraint χ).
Agents are autonomous: no agent can promise another's behaviour. Coordination
emerges from voluntary cooperation — an offer plus an acceptance (a
counter-promise) — never from imposed obligation. Obligations are derived,
non-autonomous impositions (imposition + penalty). Agents keep promises via an
evaluation loop: observe → assess → act, converging on the promised state. The
Downstream Principle: the most downstream party in a promise chain carries the greatest causal responsibility for the outcome.

## When to use

Load this skill when any of these triggers matches:

- **Modeling delegation between humans and agents** — decide who may promise what to whom, and who accepts, in a human + AI workforce.
- **Designing capability manifests or agent contracts** — declare capabilities and intent with acceptance criteria, verification, and withdrawal semantics.
- **Diagnosing coordination failures** — explain unkept promises, refused acceptances, or missing assessments in multi-agent work.
- **Calibrating trust and verification** — decide how much to verify an agent, at what rate, and at what cost.
- **Designing self-healing or convergent infrastructure** — evaluation loops that observe, assess, and act toward a desired state.
- **Converting obligation-based designs to promise-based ones** — replace push commands and mandates with voluntary offers and acceptance.

## When not to use

- **When enforceable centralized control is guaranteed** — if you can command and verify compliance directly, promise theory's machinery is overhead, not insight.
- **For simple single-agent prompting** — one model and one prompt, with no delegation graph to model, needs no promise vocabulary.
- **For imperative push-based orchestration scripts that need no consent modeling** — a cron job or CI pipeline that runs without acceptance semantics is not a promise system.
- **For legal contracts** — promise theory is not contract law; it models voluntary intent and assessment, not enforceable legal instruments. Draft real contracts with legal counsel.
- **When the user needs a specific tool manual** — route to the tool's own skill (for example, [cli-builder](../cli-builder/SKILL.md) for CLI conventions) instead of framing the tool with promise theory.

## Load By Need

| Need | Load |
|------|------|
| Re-derive a definition or the formal model (promise, imposition, obligation, bindings, trust, Downstream Principle) | [references/foundations.md](references/foundations.md) |
| Learn from CFEngine, IaC, or distributed-systems practice before designing convergent infrastructure | [references/applications-infrastructure.md](references/applications-infrastructure.md) |
| Design coordination between specific humans and agents (manifests, acceptance handshakes, oversight, authority) | [references/agent-coordination.md](references/agent-coordination.md) |
| Apply a named pattern — promise manifest, acceptance handshake, agent contract, evaluation loop, breach→renegotiation, redundancy, trust calibration | [references/patterns.md](references/patterns.md) |
| Decide how much to verify an agent, set a starting trust level, or wire assessment into evals and observability | [references/trust-and-verification.md](references/trust-and-verification.md) |
| Diagnose a coordination failure, run the breach taxonomy, or check the theory's limitations | [references/diagnosis-and-debugging.md](references/diagnosis-and-debugging.md) |
| Hit an unfamiliar term while applying this skill | [references/glossary.md](references/glossary.md) |

## Quick Start

Run these commands from the skill directory (`promise-theory/`); `python3 scripts/promise-contract.py --help` lists every command and flag.

1. **Draft a promise manifest.** Copy `templates/promise-manifest.yaml.tmpl` to a working file (for example `promise-manifest.yaml`) and fill the placeholders: agent ids and roles, at least one promise per agent (body, type, target), and at least one `expectations` entry whose `about` references a declared promise id.
2. **Lint it.** Run `python3 scripts/promise-contract.py lint promise-manifest.yaml`. Exit 0 with full expectation coverage means the manifest is valid; exit 1 names the violations to fix (coverage gaps, dangling acceptances, invalid enums) or reports a malformed file as a parse error — never a traceback. Re-run after each fix until clean.
3. **Add `--json` for machine-readable output.** Run `python3 scripts/promise-contract.py lint promise-manifest.yaml --json` to get a single JSON object on stdout (`valid`, `errors`, `warnings`, `coverage`, `bindings`) and nothing else.
4. **Add `--dry-run` to confirm no writes.** Run `python3 scripts/promise-contract.py lint promise-manifest.yaml --dry-run` to repeat the same check; lint is read-only, so nothing is written or modified.

## Available Scripts

This skill bundles one script; there are no others to discover. Both commands are read-only (`--dry-run` is accepted everywhere as a no-op guard).

| Script | Purpose | Invocation |
|---|---|---|
| `scripts/promise-contract.py` | Validates and renders promise-theory manifest contracts (restricted-YAML or JSON). `lint` checks a promise manifest against the promise-manifest v1 schema (exit 0 = valid with full expectation coverage; exit 1 = named lint errors or coverage gaps; exit 2 = usage/IO errors) and `render` prints a promise-graph summary of agents, promises, bindings, and uncovered expectations. Run `lint` after drafting or every edit of a manifest until it exits clean, and `render` when you need a human- or machine-readable view of the coordination model you just built. | `python3 scripts/promise-contract.py lint promise-manifest.yaml` |

Append `--json` for machine-readable output (a single JSON object on stdout); `render --json` gives the same treatment to the graph summary.

## Related Skills

| Skill | Route when... |
|-------|---------------|
| [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) | You need the assessment layer: evals, guardrails, and observability that verify promises are kept (also routed from `references/trust-and-verification.md`) |
| [agent-council](../agent-council/SKILL.md) | You need multi-agent debate as structured promise exchange and convergence (also routed from `references/agent-coordination.md`) |
| [multi-agent-coordination](../multi-agent-coordination/SKILL.md) | You need to design a workflow as a chain of promises (also routed from `references/patterns.md`) |
| [artifact-pyramids](../artifact-pyramids/SKILL.md) | You need to structure promise-keeping evidence as summaries → analysis → evidence dossiers (also routed from `references/trust-and-verification.md`) |
| [agent-skills](../agent-skills/SKILL.md) | You are authoring or editing an Agent Skills-format skill — the format this skill follows |
| [cli-builder](../cli-builder/SKILL.md) | You are building or refactoring the bundled CLI — `scripts/promise-contract.py` follows cli-builder conventions (non-interactive, `--json`, `--dry-run`) |

## Gotchas

1. **Provenance honesty.** The direct "promise theory + AI agents" literature is thin and recent (Burgess, "Cooperation in Human and Machine Agents," arXiv:2604.10505, 2026). In the references, claims not verified against a primary source carry `[UNVERIFIED]`, and the promise-theory → LLM-agent synthesis is labeled `EXTRAPOLATION`. Preserve those markers; they are what keep this skill honest.
2. **The theory is "semi-formal."** The authors themselves use that term: there is a notation, definitions, lemmas, and rules, but no complete axiomatisation or model theory. The famous ≤50% (impositions) vs ≤100% (promises) claim is an informal heuristic, not a derived result. Use the formalism as a reasoning aid, not a proof system.
3. **Autonomy is a modeling postulate, not an ideology.** It does not claim decentralization is morally right or always better; it is chosen because it forces complete documentation of intended behaviour and exposes failure modes.
4. **Promise-keeping must be stored as data.** CFEngine's documented gap: it reported whether a promise was kept right now, but promise-keeping was never stored as data, so the evaluation loop was incomplete. In a hybrid workforce, record assessments as versioned data (a promise ledger) or trust cannot accumulate.
5. **Verification loads are an attention/energy budget.** The rate at which you check (kinetic mistrust) is spent attention; Burgess & Dunbar model it as a bounded budget. Budget verification cost explicitly and start unknown agents at 50-50 rather than assuming trust or distrust.

## Prerequisites

- Python 3 with standard library only; `promise-contract.py` requires no third-party packages.
- A manifest to lint or render: copy `templates/promise-manifest.yaml.tmpl` and fill the placeholders (see Quick Start) before running either command.

## Limitations

- The CLI validates declaration structure, enum values, expectation coverage, and dangling acceptances — it cannot judge whether the promised behaviour is sensible, achievable, or actually kept; assessments live in your promise ledger, not in this tool.
- Promise theory is not contract law: nothing the script validates creates an enforceable legal instrument (see When not to use).
- Lint is a static check at a point in time; it does not observe agents or verify runtime promise-keeping.

## Exit Conditions

Stop when the delegation is modeled as a promise set, acceptances and assessments are recorded (or their absence explicitly deferred), and every breach has a renegotiation or escalation path. When diagnosing, stop after three non-converging passes and report the evidence instead of re-litigating the same promises.