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>
2026-09-11 19:47:12 +03:00 · 2026-08-11 23:22:38 -04:00
parent e856ddb52f
commit 4a780c4757
4 changed files with 347 additions and 0 deletions
@@ -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.
@@ -0,0 +1,128 @@
+# Agent Contract: <contract-title>
+
+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: <DRAFTED | ACTIVE | FULFILLED | VIOLATED | EXPIRED | TERMINATED>
+- Date: <YYYY-MM-DD>
+- Manifest version this contract is drawn from: <v1>
+- Renegotiation count (resets on each accepted revision): <0>
+
+## 1. Parties
+
+| Party | Side | Role in this contract | Contact / address |
+|---|---|---|---|
+| <Human name or team> | Acceptor and evaluator | <sponsor / reviewer / supervisor> | <email / channel / calendar> |
+| <agent-id> | Promiser | <role from manifest> | <endpoint / runtime / workspace> |
+| <agent-id> | Promiser | <role from manifest> | <endpoint / runtime / workspace> |
+
+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 |
+|---|---|---|---|---|---|---|---|---|
+| <promise-id> | <capability | intent | constraint | self-promise> | <agent-id> | <agent-id | human | all> | <what the promiser will do> | <observable condition(s) that must hold> | <eval | manual | monitor | audit> | <impact | standard | low> | <condition that ends the promise> |
+| <promise-id> | <...> | <...> | <...> | <...> | <...> | <...> | <...> | <...> |
+
+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 |
+|---|---|---|
+| <promise-id> | <1-6> | <e.g., "action guard rejects file writes outside src/"> |
+
+Degradation tier (named before any breach): <fail-closed | best-effort |
+safe default>, 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 |
+|---|---|---|---|---|
+| <promise-id> | <human | agent-id | guard> | <per-deliverable / daily / on-change / 1-in-10 random sample> | <method and tooling> | <review minutes or tokens per period> |
+
+- 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 <human supervisor or next acceptance authority>
+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 |
+|---|---|---|---|
+| <name> | <supervisor / owner> | <...> | <e.g., 1 business day> |
+
+## 5. Review cadence
+
+- Review frequency: <weekly / per-sprint / per-release>
+- 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: <YYYY-MM-DD>
+
+## 6. Signatures / consent
+
+| Party | Consent method | Signature / acceptance record | Date |
+|---|---|---|---|
+| <Human name or team> | <e.g., typed name in chat, approval comment on the contract> | <signature / link to approval> | <YYYY-MM-DD> |
+| <agent-id> | <logged acceptance handshake> | <ledger entry id of the accept> | <YYYY-MM-DD> |
+| <agent-id> | <logged acceptance handshake> | <ledger entry id of the accept> | <YYYY-MM-DD> |
+
+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: <what the human will supply, by what cadence> | <observable condition(s)> | <manual | monitor> | <impact | standard | low> | <condition that ends the commitment> |
+| Review agent output within <response SLA> | <e.g., every deliverable reviewed within 1 business day> | <manual> | <standard> | <...> |
+| Respond to escalations within <response SLA> | <e.g., ESCALATE-2 cases answered within 1 business day> | <manual> | <impact> | <...> |
+| Maintain consent: keep signatures and the manifest/contract version current | <...> | <monitor> | <low> | <...> |
+
+Human verification of agent promises: the human evaluates <promise ids from
+section 3> by <how — e.g., reading each deliverable, spot-checking citations>
+on the verification schedule in section 3, and records verdicts in the
+promise ledger.
@@ -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 = <agent-id> | 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             # <agent-id> | 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
@@ -0,0 +1,75 @@
+# Promise Review: <review title or period>
+
+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: <start date> to <end date>
+- Date of review: <YYYY-MM-DD>
+- Participants (who assessed): <names / agent ids>
+- Manifest version(s) under review: <v1, v2, ...>
+- 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 |
+|---|---|---|---|---|
+| <promise-id> | <agent-id> | <agent-id | human | all> | <body> | <version> |
+| <promise-id> | <agent-id> | <...> | <...> | <...> |
+
+## 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) |
+|---|---|---|---|---|---|
+| <promise-id> | <kept | breached | not yet due | withdrawn> | <human | agent-id | guard> | <date> | <the observation checked> | <entry id / artifact> |
+| <promise-id> | <...> | <...> | <...> | <...> | <...> |
+
+## 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 |
+|---|---|---|---|
+| <promise-id> | <specification | inter-agent conflict | verification> | <...> | <e.g., "rewrite the body", "renegotiate the acceptance handshake", "add a monitor"> |
+
+## 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) |
+|---|---|---|---|
+| <promise-id> | <change kind> | <new value> | <specification / inter-agent conflict / verification> |
+| <promise-id> | <...> | <...> | <...> |
+
+## 5. Action items
+
+| # | Action | Owner | Due | Verification of completion |
+|---|---|---|---|---|
+| 1 | <what will be done> | <human | agent-id> | <date> | <how completion will be checked> |
+| 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.