From 236d678a9d7eb415e1df031826af97d19827462a Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 22:56:28 -0400 Subject: [PATCH 1/9] =?UTF-8?q?feat(skill):=20promise-theory=20scaffold=20?= =?UTF-8?q?=E2=80=94=20SKILL.md=20router=20+=20MIT=20LICENSE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the promise-theory skill's thin router (SKILL.md) and LICENSE per architecture §4.1: frontmatter (name, trigger-oriented description with a negative boundary, license MIT), a 8-line core-model summary with all six mandated elements, all six use triggers, all five anti-triggers, a Load-By-Need routing table covering the seven planned references, a Quick Start (draft from template, lint with scripts/promise-contract.py), cross-references to the six sibling skills, and all five gotchas. Grounded in the mission research reports; sibling links resolve; references/*.md links land with later reference features. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- promise-theory/LICENSE | 21 ++++++++++ promise-theory/SKILL.md | 93 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 promise-theory/LICENSE create mode 100644 promise-theory/SKILL.md diff --git a/promise-theory/LICENSE b/promise-theory/LICENSE new file mode 100644 index 0000000..a527323 --- /dev/null +++ b/promise-theory/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Groktopus + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/promise-theory/SKILL.md b/promise-theory/SKILL.md new file mode 100644 index 0000000..d0a505f --- /dev/null +++ b/promise-theory/SKILL.md @@ -0,0 +1,93 @@ +--- +name: promise-theory +description: >- + Design and diagnose coordination in hybrid human + AI agent workforces using + promise theory (Burgess/Bergstra): model agents as autonomous, coordination + as voluntary offers plus acceptance, and trust as calibrated assessment. Use + for delegation modeling, capability manifests and agent contracts, + coordination-failure diagnosis, trust/verification calibration, convergent + self-healing systems, and converting obligation-based designs to + promise-based. Do not use for enforceable centralized control, legal contract + drafting (promise theory is not contract law), simple single-agent prompting, + imperative push-based orchestration, or tool manuals — route those to the + tool's own skill. +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. + +## 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 + +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), and re-running after each fix converges to clean. + +## 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`) | +| [workflow-architect](../bundles/workflow-architect/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. + +## 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. From d01d7a1578e0eadc98a1654dc78cd89f3a3fb2f4 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:06:23 -0400 Subject: [PATCH 2/9] feat(skill): promise-theory references foundations + applications-infrastructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds references/foundations.md (academic core with Burgess/Bergstra citations: promise definition and notation S ─b→ R, proposals, scope, impositions, obligation-as-derived, polarity/bindings, assessment/belief/ evidence, trust as discounting, exact/empty promises, deception, matrices/ graphs, valence/bundles, roles, discovery, Downstream Principle, evaluation loops, history, adjacent frameworks, critiques; honest formal-status section) and references/applications-infrastructure.md (CFEngine case study incl. the promise-keeping-was-never-stored-as-data lesson, IaC comparison table, distributed-systems connection, adoption history, LLM-reasoning-layer argument). Both files < 60k chars with provenance markers per architecture §4.2. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- .../references/applications-infrastructure.md | 564 ++++++++++++++ promise-theory/references/foundations.md | 704 ++++++++++++++++++ 2 files changed, 1268 insertions(+) create mode 100644 promise-theory/references/applications-infrastructure.md create mode 100644 promise-theory/references/foundations.md diff --git a/promise-theory/references/applications-infrastructure.md b/promise-theory/references/applications-infrastructure.md new file mode 100644 index 0000000..9c8b610 --- /dev/null +++ b/promise-theory/references/applications-infrastructure.md @@ -0,0 +1,564 @@ +# Applications in Infrastructure & Code — CFEngine, IaC, and Distributed Systems + +**Load this file when you need the empirical record:** what promise theory did +(or failed to do) in real infrastructure — the CFEngine reference +implementation, the IaC generation's borrowing of its vocabulary, the +distributed-systems patterns that look promise-shaped, the adoption history, +and the 2026 argument that LLMs finally supply the reasoning layer the theory +always assumed. This is the practical companion to +[foundations.md](foundations.md), which carries the definitions and citations +for every concept used here; for the application of these lessons to hybrid +human + AI workforces see [agent-coordination.md](agent-coordination.md) and +[patterns.md](patterns.md). + +**Provenance.** This file follows the skill's provenance policy: `[UNVERIFIED]` +marks claims that rest on vendor-sourced or secondary accounts, and +`EXTRAPOLATION` marks interpretations that go beyond the cited sources (the +LLM-reasoning-layer synthesis in particular). Case-study figures from CFEngine +and LinkedIn are first-party/vendor materials; they are consistent with the +public record but are flagged where they cannot be independently corroborated. + +--- + +## 1. CFEngine — the reference implementation + +### 1.1 From physics to configuration (1993–2008) + +CFEngine ("Configuration Engine") began in 1993 as Burgess's personal tool for +managing Unix workstations at the University of Oslo. Two ideas shaped the +later theory: + +- **Convergent operators (1995–2003).** Change operations with the character + of mathematical fixed points: rather than describing steps ("run this + script"), CFEngine describes the final state and the agent derives the + steps; running it repeatedly from any initial state converges to a + predictable result. Key papers: "Cfengine: a site configuration engine" + (*USENIX Computing Systems* 8(3), 1995) and "On the theory of system + administration" (*Science of Computer Programming* 49, 2003). +- **Computer Immunology (1998).** The LISA 98 paper "Computer Immunology" was + a manifesto for self-healing systems — agents in each node continuously try + to keep their promises and correct deviations — which Wikipedia credits as + predating IBM's Autonomic Computing manifesto (2001). + +By the mid-2000s Burgess concluded that CFEngine 2 was reaching its limits and +spent roughly five years (2004–2008) formulating promise theory specifically +"to help me to rework CFEngine." CFEngine 3 was introduced in 2008 (CFEngine +AS founded June 2008; CFEngine 3 released 2009), rebuilt *around* promise +theory. + +### 1.2 CFEngine 3: everything is a promise + +CFEngine 3's documentation is explicit: "One concept in CFEngine should stand +out from the rest as being the most important: promises. Everything else is +just an abstraction that allows us to declare promises and model the various +actors in the system" (CFEngine 3.12 docs, "Promises"). The concrete +mechanisms: + +1. **Promise types, promisers, promisees, classes.** Promise types define the + subject — `files`, `packages`, `processes`, `services`, `commands`, + `methods`, `storage`, `databases`, `reports`, `access`, `classes`, `vars`, + `defaults`, `roles`, `meta`. Different CFEngine components keep different + promise types: `cf-serverd` cannot keep `packages` promises; `cf-agent` + cannot keep `access` promises. The *promiser* is the object that "promises + that a certain fact will be true" (a file promises permission `0755` and + owner `root`); the optional *promisee* records who the promise is made to; + *classes* control the conditions under which a promise is valid (OS type, + day of week, user-defined contexts). +2. **Bundles and bodies.** Promises are grouped into *bundles* (logical groups + such as "webserver" or "filesystem"); reusable attribute groups are + *bodies*. This maps directly to promise theory's "aspects and bundles" + (Burgess, "Promise You A Rose Garden," 2007). +3. **Normal ordering and fixed-point convergence.** CFEngine maintains a + default order of promise types "based on a simple logic of what needs to + come first, e.g. it makes no sense to create something and then delete it, + but it could make sense to delete and then create (an equilibrium)." Within + a bundle, promise types execute in round-robin "normal ordering," iterating + up to three times "converging towards a final state." Explicit ordering is + available via `depends_on` and class-based conditioning. This is the + operational embodiment of fixed-point convergence. +4. **Promise locking.** When a promise is validated (kept or repaired), it is + locked for a default interval (`ifelapsed`, 1 minute by default), keyed on + a hash of promiser + attributes + context. Locks control frequency and + prevent thrashing. +5. **Idempotence and statistical compliance.** "Promises are idempotent: + repetition confirms but they don't add up cumulatively" (Rose Garden + essay). A system never guarantees to be exactly in the ideal state; it + approaches the fixed point by best effort, at a rate determined by the + ratio of environmental change frequency to CFEngine execution frequency + (Wikipedia; "On the theory of system administration," 2003). +6. **The autonomous agent pull model.** The default architecture: a policy + server publishes policy (the "masterfiles"), and each host's `cf-agent` + *pulls* the policy it has agreed to apply over an authenticated channel + (`cf-serverd` access promises), then evaluates it locally. There is no + central scheduler issuing commands. "All decision-making and information is + made by each CFEngine agent autonomously... there is no strong coupling + through the network" (Burgess, InfoQ interview, 2014). The pull model is + simultaneously a *security* principle: agents dial out, firewalls stay + closed inbound, and an external actor cannot reach in to push commands — + "autonomy is deafness to exploitation" (Burgess, 2022). +7. **The agent loop: observe, reason, commit.** Each agent observes its local + environment (its promises define what it watches), reasons about which + promises are unkept, and repairs only those. + +In Burgess's own account (InfoQ, 2014), the theory shows up in CFEngine 3 in +three places: the language ("Absolutely everything that you express is a +promise, or part of a promise... Each promise is continuously measured — is it +kept or not kept?"); the decentralization of decision-making (routing-protocol- +like autonomy, "no strong coupling through the network"); and conflict and +knowledge tracking (two promises of the same type with different constraints +are broken promises — contradictions detectable by counting promises across the +graph). + +### 1.3 Scale: the LinkedIn case study + +The public LinkedIn case study (CFEngine AS, Nov 2014 — vendor first-party +material) reports: automation of **40,000+ servers by a six-person operations +team**; 5–10 production changes per day; new machines provisioned "in 15 +minutes or less"; user account management across "thousands of machines in +minutes"; phased rollouts using CFEngine *range classes* (assign a change to +0% of machines, expand to 10%, monitor, expand to 100%); and root access +granted broadly to engineers because CFEngine "will immediately restore the +system to its desired system state using its policy engine." The Wikipedia +summary adds: "The largest reported datacenter under management of CFEngine is +above a million servers, while sites as large as 40,000 machines are publicly +reported (LinkedIn)." The million-server figure is a repeated marketing claim +without a public citation — treat as `[UNVERIFIED]`. + +### 1.4 The documented gap: promise-keeping was never stored as data + +The CFEngine experience is the strongest evidence both for and against the +theory's practical power — and its failure mode is the single most important +lesson for this skill: + +- **Scope-bounded observation.** "A cf-agent observes what its promises + describe. Write a promise about `/etc/ssh/sshd_config` and the agent watches + that file. Write nothing about the security group in front of the host and + the agent holds no opinion" (Webframp, "The Promise None of Them Kept," + 2026). This is a *feature* of the theory (locality of knowledge) and a + *failure mode* in practice (silent drift outside the declared surface). +- **No retained history.** "It can tell you whether the promise is kept right + now. Ask what the config looked like last Tuesday... and there is no + queryable answer, because **promise-keeping was never stored as data**" + (Webframp, 2026). CFEngine's verdict is a snapshot, not a record. + +The consequence is exactly what the theory itself says trust requires but never +delivered: without a retained, versioned, queryable record of assessments you +cannot do trend analysis, rollback planning, breach→renegotiation, or trust +accumulation. **The evaluation loop was incomplete** — observe → assess → act +existed, but the *assessment* was not persisted as data, so the loop could not +learn across time. Any promise-theoretic system built today — including +AI-agent coordination — must store assessments as versioned data (a promise +ledger). This is the gap the skill's "evaluation loop" pattern and the +`promise-review` template close (see [patterns.md](patterns.md) and +[trust-and-verification.md](trust-and-verification.md)). + +--- + +## 2. The IaC landscape — vocabulary without the mechanism + +Burgess has said he is "surprised and a little humbled by how much of promise +theory has been taken on board by the industry" (InfoQ, 2014). The industry, +however, took the *words* (declarative, convergence, idempotency, desired +state) and mostly not the *mechanics* (autonomous agents, local reasoning, +voluntary acceptance, observation by the acting agent). + +### 2.1 The three-property test + +The following analysis uses a three-property test derived from promise theory's +axioms, following Webframp's 2026 framework (itself an interpretation of the +theory — `EXTRAPOLATION` in the sense that the axioms are the authors', the +operational test is the essayist's): + +1. **Observation** — does the agent perceive its environment itself, or diff + against a snapshot? +2. **Local reasoning** — does the agent decide, or merely execute precomputed + instructions? +3. **Voluntary commitment** — is the behaviour a promise about the agent's own + state, or an imposition on a remote party? + +### 2.2 Comparison table + +| System | Control model | Desired-state mechanism | Continuous convergence? | Agent on target? | Verdict | +|---|---|---|---|---|---| +| **CFEngine 3+** | Pull; agent autonomy | Promise language; fixed-point convergence | Yes (scheduled loop, ~5-min default) | Yes (`cf-agent`) | Reference implementation: observe, reason, commit | +| **Puppet** | Pull; master + agent | Declarative resource DSL; convergence per run | Yes on schedule | Yes | Partial: pull agent + desired state, but reasoning centralized in the master; catalog = obligations imposed | +| **Chef** | Pull; server + client | Recipes/attributes; "convergent" resources | Yes on schedule (~30 min) | Yes (`chef-client`) | Partial: local convergence, but "observation scoped to the declaration" | +| **Ansible** | Push; control node via SSH | Playbooks; module-level idempotency | No between runs; no resume after mid-run failure | No (agentless by default) | Imposition model; `ansible-pull` is the honest exception | +| **Terraform** | CLI plan/apply | HCL declarations; plan = diff vs last-known state file | No (inert between applies; `refresh` opt-in) | No | Fails all three properties: a batch script with a diffing preamble | +| **Nix / NixOS** | Apply-time build (pull from store) | Pure functional derivation; reproducibility | No repair loop (rebuild/switch is atomic) | No | Different axis: functional purity, not convergence; no observing agent | +| **Kubernetes** | Controller reconciliation (control plane + kubelet) | Declarative spec vs status; controllers drive actual → desired | Yes (continuous, level-triggered) | Yes (`kubelet` per node) | Closest mass-adopted cousin: the loop without the theory | +| **OPA / Kyverno** | Decision service / admission webhook | Rego/Kyverno rules; allow/deny/violation | No (evaluated per request) | No | Obligation-based gates → best fit as the *assessment* layer of promises | +| **Rudder** | CFEngine agent + UI | CFEngine promises + compliance reporting | Yes | Yes | Direct descendant: promise theory + continuous compliance | + +### 2.3 Verdicts in detail + +- **Terraform fails the three-axiom test.** Its state file "records + Terraform's own last write, the one piece of evidence an agent assessing its + own promise-keeping cannot use" (Webframp). It executes; it does not decide — + the reasoning was precomputed by the human who wrote the HCL. And it + "imposes changes on remote resources through API calls. The resources + promise nothing back, and Terraform promises nothing about ongoing + maintenance." Drift is only detected when a human runs `plan`; the + "terraform apply every 5 minutes" pattern is a manual reconstruction of the + loop the theory makes automatic. +- **Ansible is push/imposition.** "A control node connects to targets via SSH + and pushes tasks. It runs what it was told" (Webframp). In Burgess's terms + that is an *imposition model*: targets are obliged by the controller's + assumption of compliance. **`ansible-pull` is the honest exception** — it + "run[s] from cron on the target... gets a local agent that clones a playbook + repository, evaluates conditions locally, and converges on a schedule with no + controller involved. That is the promise-theoretic mode, shipped in the box, + and almost nobody deploys it" (Webframp). +- **Chef/Puppet are partial.** Both deploy pull agents that converge toward a + declared state, which is genuinely promise-like — but the reasoning is + centralized (the master builds the catalog; the server computes the + recipes), so the agent observes facts without deciding policy, and the + resources are obligations the master imposes via catalog rather than + promises the node accepted. +- **Nix is a different axis.** NixOS is "declarative" in a functional- + programming sense, not a convergence sense: the whole OS "is built by the Nix + package manager from a description in a purely functional build language... + building a new configuration cannot overwrite previous configurations" + (nixos.org, "How Nix Works"). Properties are reproducibility, atomic + upgrades, and rollback — there is **no continuous repair loop and no + observing agent**; convergence is replaced by determinism. Burgess has + publicly dismissed the immutability framing ("This nonsense about + immutability is a complete red herring, in my view," InfoQ 2014), while + conceding disposable-computing redundancy is the correct scaling strategy. +- **OPA/Kyverno are obligation gates.** The Open Policy Agent "provides a + high-level declarative language that lets you specify policy as code and + simple APIs to offload policy decision-making from your software" (OPA docs). + A Rego policy answers a query about input ("allow", "violation", "deny") and + the caller enforces the verdict. In promise-theoretic terms these are + **impositions evaluated at the gate**, not promises kept by agents: the + requestor does not promise to behave; it is (or is not) admitted. There is a + nuance: OPA is *consultative* — the caller promises to ask, the enforcement + point promises to check — but in practice the pattern is obligation layered + on the admission path. **The constructive reading: an operator building a + promise-theoretic system uses OPA/Kyverno as the *assessment* layer of + promises** — "I will not expose telnet" can be verified by evaluating Rego + against live config — which is exactly the assessment-layer role this skill + routes to [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) + (also routed from [trust-and-verification.md](trust-and-verification.md)). + +### 2.4 Honest exceptions and the residual need for declarations + +Imposition is legitimate where an agent cannot be installed (network switches, +locked-down appliances) — "imposition is the only available mode" (Webframp). +Declared intent still matters in three cases: *provisioning* (you cannot +observe what does not exist), *compliance baselines* ("all S3 buckets must +have encryption enabled" is intent, not observation), and *rollback targets*. +The lesson is scope, not abolition: keep declarations where intent is real, +and shrink the surface of state you pretend to manage by declaration. + +--- + +## 3. Distributed systems — promise-shaped ideas at scale + +Burgess has argued that the networking world "has pretty much always been +designed in a promise-compatible way" (InfoQ, 2014). A map of where +promise-theoretic ideas already appear: + +### 3.1 BGP peering and DNS + +- **BGP peering** is the canonical example of voluntary cooperation at scale: + providers exchange *mutual promises to transport packets*, and the value is + in the promise itself — "a matter of being seen to be connected to the right + people" (Rose Garden essay, citing Norton's peering work). Routing protocols + are decentralized, self-healing, convergent systems. +- **DNS** is the essay's worked example: name servers promise answers; + resolvers promise to accept requests, forward them, and *use* replies; + masters promise zone data to slaves, who promise to use it. Every promise is + a potential failure mode and a place to plan redundancy. + +### 3.2 Gossip / epidemic protocols + +Gossip protocols were introduced by **Demers et al., "Epidemic algorithms for +replicated database maintenance," PODC 1987**: each node periodically exchanges +state with a randomly chosen peer (anti-entropy and rumor mongering), so +information spreads epidemically with no central coordinator. This is +coordination *by voluntary peer exchange* — structurally the same +"bottom-up, many-to-many, no central controller" stance as promise theory, +though gossip propagates state, not intentions. The relationship: gossip gives +you *eventual consistency of information*; promises give you *stated +intentions that agents assess*. A promise-theoretic distributed system would +use gossip- or DNS-like discovery as the substrate for communicating promises +and local assessment for keeping them. + +### 3.3 Consensus vs promise-based coordination + +Strongly consistent consensus — Lamport's Paxos (1989/1998); Ongaro & +Ousterhout's Raft (USENIX ATC 2014) — is the opposite end of the spectrum: a +quorum agrees on a total order of operations. Promise-based coordination makes +no such guarantee; correctness is a property of the promise graph +(contradiction-freedom) rather than of a single ordered log. These are +complementary: Raft/etcd gives the few things that must be exactly agreed (who +is leader, what is the config version); promises give the many things that only +need approximate consistency (host configuration, drift repair). Kubernetes' +design is exactly this split — etcd (Raft) for the API store, per-resource +controllers for continuous reconciliation. + +### 3.4 Service discovery + +Burgess's DNS analysis generalizes: a discovery service is a set of agents +promising answers about where things are, and consumers promise to *use* those +answers. Modern equivalents (CoreDNS, Consul, etcd-based discovery, mDNS) +implement promise-shaped contracts: the registry promises freshness, the client +promises to re-resolve, and health checks are assessments of the "service is +running" promise. + +### 3.5 MAPE-K and autonomic computing + +IBM's Autonomic Computing initiative (2001; canonical statement **Kephart & +Chess, "The Vision of Autonomic Computing," *IEEE Computer* 36(1):41–50, +2003**) defined the MAPE-K control loop — Monitor, Analyze, Plan, Execute, +shared Knowledge — and the self-* properties. The connection to promise theory +is direct: Burgess's "Computer Immunology" (1998) predates the initiative, and +the bridge paper is **Burgess & Couch, "Autonomic Computing Approximated by +Fixed-Point Promises," MACE 2006**: MAPE-K loops are implementations of +promise-keeping, with convergence semantics giving stability guarantees. The +difference is again the unit of interaction: MAPE-K's manager commands +effectors; promise theory's agents promise. + +### 3.6 Cisco ACI / OpFlex — the one major vendor build + +Cisco ACI (2012–2014) is the only major vendor product built *explicitly* on +promise theory: "APIC policy use an object-oriented approach based on promise +theory. Promise theory is based on declarative, scalable control of intelligent +objects, in comparison to legacy imperative models" (Cisco Community, "Cisco +ACI Architecture – Simplified"). The southbound protocol **OpFlex** was +designed to "exhibit the same promise theory information model as ACI" +(Network World, 2014), and the promise-theoretic analysis of SDN is in +**Borrill, Burgess, Craw & Dvorkin, "A Promise Theory Perspective on Data +Networks," arXiv:1405.2627 (2014)**. In ACI, the endpoint group (EPG) and +contracts are the promise objects rendered by intelligent fabric devices rather +than dumb flow tables. (The ACI/OpFlex promise-theory basis is vendor + trade- +press attested; treat detail beyond the arXiv paper and Cisco's own +documentation as secondary `[UNVERIFIED]`.) OpFlex did not win the SDN +southbound debate — OpenFlow/OVSDB and vendor models did. + +### 3.7 Intent-based networking + +Cisco's IBN: "The goal is for the network to continuously monitor and adjust +network performance to help assure desired business outcomes" (cisco.com). The +closed loop has three blocks — **Translation** (intent → policy), +**Activation** (policy installation), **Assurance** (analytics/ML verifying +the intent is achieved). IBN is promise-shaped at the level of *intent and +assurance*; its mechanism, however, is controller-led policy push (obligation), +not autonomous device promises. + +### 3.8 Kubernetes — "the loop without the theory" + +Kubernetes is the most important real-world instance of promise-shaped control, +and its own documentation reads like a promise-theory summary: + +> "Kubernetes is not a mere orchestration system. In fact, it eliminates the +> need for orchestration... Kubernetes comprises a set of independent, +> composable control processes that continuously drive the current state +> towards the provided desired state. It shouldn't matter how you get from A to +> C. Centralized control is also not required." (kubernetes.io/docs/concepts/ +> overview) + +Mechanics: users declare desired state in API objects (`spec`); controllers +watch `spec` vs `status`, level-triggered, and take idempotent actions; +`kubelet` on each node is the local agent that keeps node-level promises +(containers running, health probes). Self-healing — "restarts containers that +fail, replaces containers, kills containers that don't respond to health +checks" — is the fixed-point loop. The divergences from the theory are equally +instructive: the API server + etcd is a *central source of truth* +(consensus-backed), and scheduling is *imposition* (a Pod does not promise to +run; the scheduler decides and the kubelet obeys). Kubernetes is thus "the +loop without the theory": it delivers observe–compare–repair at industrial +scale while keeping a centralized control spine. A fair claim is that +Kubernetes made the promise-theoretic control loop the default mental model of +infrastructure for a generation — while dropping the theory's stronger claims +about autonomy, locality, and voluntary acceptance. + +--- + +## 4. Adoption history — why it never dominated + +### 4.1 Timeline (abridged) + +| Year | Event | +|---|---| +| 1993 | CFEngine 1 ships (Burgess, Oslo) | +| 1998 | "Computer Immunology" (LISA 98): self-healing manifesto; CFEngine 2 | +| 2001 | IBM launches Autonomic Computing initiative (Kephart & Chess, 2003) | +| 2004 | Promise theory first proposed by Burgess (policy-based management context) | +| 2005 | DSOM 2005 paper introduces the name "Promise Theory"; informal best-paper recognition | +| 2005–2006 | Bergstra collaboration begins; impositions concept | +| 2007 | "Promise You A Rose Garden" essay | +| 2008–2009 | CFEngine 3 rebuilt on promise theory; CFEngine AS founded | +| 2012 | Cisco begins using promise theory in SDN/ACI initiatives | +| 2013–2014 | Tech media wave (Network World, NoJitter, Linux Journal); LinkedIn case study; first book edition | +| 2015 | *In Search of Certainty* and *Thinking in Promises* (O'Reilly) | +| 2016 | Chef Habitat unveiled; Wired profiles it with Burgess; Tim O'Reilly's *WTF* discusses promise theory | +| 2017 | CFEngine company renamed Northern.tech | +| 2019 | *Promise Theory: Principles and Applications*, 2nd ed. | +| 2023 | ~2,700 companies reported using CFEngine (Enlyft — vendor-ecosystem metric, `[UNVERIFIED]`) | +| 2025 | Ecma publishes NLIP, a natural-language agent-communication standard | +| 2026 | CFEngine 3.28.0 released (July 2026); Webframp's "The Promise None of Them Kept" | + +### 4.2 The two industry moments + +**Cisco ACI (2012–2014)** was the explicit, high-profile industrial adoption +(§3.6); it generated the famous tech-press moment but OpFlex lost the SDN +southbound race. **Chef Habitat (2016)** — "the automation travels with the +application"; supervisors as autonomous cells — was framed by Burgess in Wired +as an application of promise theory ("humans and autonomous agents work +together... You share your intentions with Habitat, and its autonomous agents +work to realize them"). It never achieved mainstream adoption, and Chef itself +was later acquired. + +### 4.3 Why academic traction outpaced industry dominance + +1. **The theory is analytic, not prescriptive.** "Promise theory is not a + technology or design methodology. It doesn't advocate any position or + design principle, except as a method of analysis" (Wikipedia). Enterprises + buy solutions, not analysis frameworks. +2. **Self-referential literature.** Most peer-reviewed output is + Burgess–Bergstra co-authored; Wikipedia flags the article's reliance on + sources "too closely associated with the subject." Independent validation + is thin (see [foundations.md](foundations.md) §6). +3. **The DSL and the cultural misfit.** CFEngine's promise language and the + "academization" agenda alienated practitioners, while Puppet/Chef/Ansible + courted developers with Ruby/Python/YAML and GitHub-style workflows. +4. **Timing and the container wave.** The 2010s moved from config management + to immutable images, containers, and orchestrators — a world Burgess has + criticized ("immutability... a complete red herring... I call that politics, + not science," InfoQ 2014). Disposable computing took the "numbers game" + redundancy he had predicted, but via images rather than promises. +5. **The market.** RedMonk's 2015 analysis documented Ansible's explosive + growth and minimal CFEngine community activity; Enlyft's 2023 data showed + CFEngine at 0.04% of IT management software market share. +6. **The company.** CFEngine AS → Northern.tech pivoted toward device lifecycle + management and compliance-heavy regulated industries — a defensible niche, + not the mainstream. + +### 4.4 Lessons for applying it now + +1. **Use it as a vocabulary and audit discipline, not a runtime.** The durable + asset is the questions: *Who is the agent? What does it observe, and can it + observe that directly? What may it promise, and about whom? Where does an + imposition happen, and did anything on the receiving end agree to accept + it?* (Webframp's formulation.) +2. **Design for the loop plus memory.** CFEngine proved the loop but could not + answer "what did last Tuesday look like?" Retained, versioned, queryable + observation records are the missing third leg; any modern promise-theoretic + system should store assessments as data (§1.4). +3. **Watch the imposition-to-promise ratio.** Push tools work, but they give + you neither autonomy nor convergence nor verification; when you cannot + install an agent, say so explicitly rather than pretending. +4. **Adopt the fixed-point discipline regardless of tool.** Desired state + + continuous reconciliation + idempotency is the one promise-theory idea that + demonstrably won (Kubernetes). It is safe to bet on. +5. **Expect the "hardwired centralization" reflex.** Burgess: "centralised + control is always the first idea people come back to when they need to + manage something. It's like it's hardwired into our culture" (InfoQ, 2014). + +--- + +## 5. The LLM-reasoning-layer argument + +### 5.1 The missing piece was never the agent + +CFEngine built the *agent* side of the theory completely: a real +promise-keeping engine with observation, local reasoning, voluntary pull, and +fixed-point convergence. What it never built — and what the IaC generation that +followed did not build either — was the *reasoning layer*: an actor that can +look at a live system, interpret what it sees, decide what matters, and commit +to a repair, at a semantic altitude above declarative diffs. Configuration +agents are bounded by their declarations; a promise about +`/etc/ssh/sshd_config` is watched, and everything else is ignored (§1.4). +That scope-boundedness is exactly what makes the evaluation loop incomplete. + +### 5.2 What LLMs supply — and what must still be built + +`EXTRAPOLATION` — this synthesis goes beyond the cited sources. Burgess's own +2026 work ("Cooperation in Human and Machine Agents," arXiv:2604.10505) +reframes promise theory for human–machine cooperation, and Webframp's 2026 +essay ("The Promise None of Them Kept") makes the direct claim: **large +language models supply the reasoning layer promise theory always assumed** — +an agent that can observe a live system, reason about what it sees (the +three-property test's "reason" step), and commit to action in natural language, +without a prewritten DSL describing every promise in advance. + +Three properties make LLMs a qualitatively different substrate than CFEngine +or Terraform: + +1. **Semantic observation.** An LLM can interpret unstructured observations + (logs, tickets, conversations, status pages) and map them to promises, + where a config agent can only see its declared surface. +2. **Local reasoning about intent.** An LLM can compare what a promise says + against what actually happened and *explain* the gap — turning the + assessment step (α, β, ε in [foundations.md](foundations.md)) from a + boolean verdict into a negotiable finding. +3. **Natural-language commitment.** LLMs make promises (capability + declarations, contracts, acceptance criteria) in the same language humans + use, closing the semantic gap that sank KQML/FIPA-ACL and The Coordinator + (agents no longer need a shared ontology — the model translates between + local ontologies, as Ecma's NLIP, standardized December 2025, begins to + formalize). + +The 2026 essay's title — "The Promise None of Them Kept" — cuts both ways: the +IaC generation *claimed* the promise lineage without the mechanism ("Chef +called its resources 'convergent.' Puppet called its catalogs 'desired state.' +Terraform called its plans 'declarative.' Ansible called its playbooks +'idempotent.' None of those four kept the promise. Burgess's own tool did, and +ran into a different limit" — the un-stored assessment history). LLMs may +finally supply the reasoning layer — but they inherit the same two failure +modes unless the loop is completed: **promise-keeping must be stored as data**, +and **assessments need provenance** (who assessed, when, against what +observation). + +### 5.3 Why this matters for a hybrid workforce + +`EXTRAPOLATION` — the application to human + AI coordination is the core thesis +of this skill and is developed in +[agent-coordination.md](agent-coordination.md). The infrastructure record +justifies the transfer: the theory's vocabulary (autonomous agents, promises, +impositions, assessment, the Downstream Principle) was forged in systems where +nobody could command anyone; a workforce containing humans (unformalizable), +LLMs (probabilistic), and machines (deterministic) has exactly that property. +The CFEngine lesson — *the loop is only as good as its stored assessments* — +and the Kubernetes lesson — *the loop is mass-adoptable when the reasoning is +centralized* — define the design space: run the loop, store the assessments, +and let each party promise only what it can observe. + +--- + +## 6. Sources (works cited above) + +**Primary (Burgess/Bergstra):** Burgess, "Cfengine: a site configuration +engine," *USENIX Computing Systems* 8(3), 1995; Burgess, "On the theory of +system administration," *Science of Computer Programming* 49, 2003; Burgess, +"Computer Immunology," LISA 98; Burgess, "Promise You A Rose Garden" (2007); +Burgess, DSOM 2005 (LNCS 3775, pp. 97–108); Bergstra & Burgess, *Promise +Theory: Principles and Applications* 2nd ed., χtAxis, 2019; Burgess, *In +Search of Certainty* (O'Reilly, 2015); Burgess, *Thinking in Promises* +(O'Reilly, 2015); Borrill, Burgess, Craw & Dvorkin, "A Promise Theory +Perspective on Data Networks," arXiv:1405.2627 (2014); Burgess & Couch, +"Autonomic Computing Approximated by Fixed-Point Promises," MACE 2006; +Burgess, "Cooperation in Human and Machine Agents," arXiv:2604.10505 (2026). + +**CFEngine and case materials:** CFEngine 3.12 documentation ("Promises", +"Normal Ordering"); CFEngine documentation (LTS), "What is CFEngine and why?"; +LinkedIn Infrastructure and Operations Automation at WebScale (CFEngine AS +case study, Nov 2014); Wikipedia: "CFEngine", "Promise theory" (index only). + +**Industry and IaC:** InfoQ interview with Burgess (2014); Network World, +"Promise Theory" (2014); Cisco Community, "Cisco ACI Architecture – Simplified" +(2014); Cisco, "Intent-Based Networking" (2024); Kubernetes documentation +("Overview"); nixos.org, "How Nix Works"; Open Policy Agent documentation; +Webframp, "The Promise None of Them Kept" (2026); RedMonk (2015); Enlyft +(2023); Wired, "The Quest to Make Code Work Like Biology Just Took A Big Step" +(2016); O'Reilly, *WTF* (2017). + +**Distributed systems and precedents:** Demers et al., "Epidemic algorithms +for replicated database maintenance," PODC 1987; Lamport, Paxos (1989/1998); +Ongaro & Ousterhout, Raft (USENIX ATC 2014); Kephart & Chess, "The Vision of +Autonomic Computing," *IEEE Computer* 36(1), 2003; Ecma TC56, NLIP (2025). +Full bibliographic details are in the mission research report +(applications-infrastructure.md); the repository standard is to cite the named +work inline, as above. diff --git a/promise-theory/references/foundations.md b/promise-theory/references/foundations.md new file mode 100644 index 0000000..7149c4f --- /dev/null +++ b/promise-theory/references/foundations.md @@ -0,0 +1,704 @@ +# Foundations — The Academic Core of Promise Theory + +**Load this file when you need the definitions, the formal model, the history, +or an honest assessment of the theory's status.** This is the academic anchor +of the skill: the practical mappings in +[applications-infrastructure.md](applications-infrastructure.md) (CFEngine, +IaC, distributed systems) and +[agent-coordination.md](agent-coordination.md) (hybrid human + AI workforces) +are built on the vocabulary defined here. For one-line definitions see +[glossary.md](glossary.md); for applying the model to infrastructure practice +see [applications-infrastructure.md](applications-infrastructure.md). + +**Provenance.** Every definition below is cited to a primary source: the +Burgess/Bergstra books and papers, the CFEngine documentation, and Burgess's +later arXiv work. Two markers are used consistently across every reference in +this skill: + +- `[UNVERIFIED]` — a claim that could not be verified against a primary source + (vendor-sourced figures, facts attested only in secondary accounts). +- `EXTRAPOLATION` — an interpretation that goes beyond the cited sources. The + promise-theory → AI-agent synthesis is the main such zone and is labeled + explicitly. + +The theory is "semi-formal" — its own authors' term — and Section 4 states +precisely what is defined, what is proven, and what is only informally claimed. + +--- + +## 1. The theory in one paragraph + +Promise theory is a method of analysis for systems of interacting components +developed by the British physicist-turned-computer-scientist Mark Burgess +(creator of CFEngine, formerly professor at Oslo University College / Oslo +Metropolitan University) and, from roughly 2007, jointly with the Dutch +computer scientist Jan A. Bergstra (emeritus professor, University of +Amsterdam). It models every actor — human, machine, process, or organisation — +as an *autonomous agent* that can only make promises about its own behaviour, +and treats coordination as emerging from *voluntary cooperation* (an offer plus +an acceptance) rather than from obligations, commands, or centralised control. +The founding claim is that obligation — the assumption that one agent can +command another and be obeyed — is the wrong primitive for reasoning about +distributed systems: in Burgess's phrase, obligation-based accounts of remote +policy "amounted to wishful thinking" (Burgess, "Promise You A Rose Garden," +2007, markburgess.org/rosegarden.pdf). The canonical statement of the theory is +Bergstra & Burgess, *Promise Theory: Principles and Applications* (2nd ed., +χtAxis Press, 2019), which describes itself as a "semi-formal language for +modelling intent and its outcome." + +## 2. Origin and history + +### 2.1 From CFEngine to a theory (1993–2005) + +Promise theory grew out of practical failure. CFEngine ("Configuration +Engine") began in 1993 as Burgess's personal tool for managing Unix +workstations at the University of Oslo (Burgess, "Cfengine: a site +configuration engine," *USENIX Computing Systems* 8(3):309–337, 1995). Its +core design idea was *convergence*: rather than executing imperative scripts +once, agents repeatedly enforce a desired state (a mathematical fixed point), +repairing drift on every pass. Burgess developed the theory of this approach in +"On the theory of system administration" (*Science of Computer Programming* +49(1–3):1–46, 2003) and framed configuration management through an "immunity +model" in "Configurable immunity for evolving human-computer systems" +(*Science of Computer Programming* 51(3):197–213, 2004). + +The direct precursor of promise theory is Burgess's observation, which he +dates to around 2002 (per his Semantic Spacetime project page: "puzzles that +have bugged me since I started thinking about promises around 2002"), that +obligation- and command-based models of distributed policy were wrong for +autonomous, physically independent machines: an operator cannot *cause* a +remote host to comply; it can only create conditions under which the host's own +agents choose to comply. The popular essay "Promise You A Rose Garden" (2007) +called existing obligation-based theories "wishful thinking." This is the +theory's origin story — Burgess's own account, repeated in the FAQ and in the +2025 twentieth-anniversary retrospective. + +### 2.2 DSOM 2005 — the founding paper + +The first formal academic statement is: + +> **M. Burgess, "An Approach to Understanding Policy Based on Autonomy and +> Voluntary Cooperation."** In: Schönwälder, J., Serrat, J. (eds), *Ambient +> Networks*, DSOM 2005, LNCS 3775, pp. 97–108, Springer, 2005. +> DOI 10.1007/11568285_9. Copyright © 2005 IFIP. + +The paper proposes "a theory of atomic policy units called 'promises'" and +argues that "a global authority is not required to build conventional +management abstractions, but work is needed to bind peers into a traditional +authoritative structure." Many citations render the year as 2004 because the +paper was written in 2004; DBLP and Springer record the proceedings year as +2005. Burgess's own 2025 retrospective states that promise theory "was first +presented to an academic audience at the DSOM" workshop. + +### 2.3 The Bergstra collaboration and mathematisation (2007–2014) + +Bergstra — best known for process algebra (ACP, with J. W. Klop) and program +algebra — collaborated with Burgess from around 2007 and deepened the formal +apparatus: + +- **Bergstra, Bethke & Burgess, "A process algebra based framework for promise + theory," arXiv:0707.0744 (2007)** — promises as process-algebra terms, + cooperation as synchronisation, conflict resolution handled algebraically, + with a transportation-planning example. +- **Bergstra & Burgess, "A static theory of promises," arXiv:0810.3294 + (submitted 2008; revised through v5, January 2014)** — the canonical + reference for the promise-vs-obligation distinction: "We compare promises to + the more established notion of obligations and find promises to be both + simpler and more effective at reducing uncertainty in behavioural outcomes." +- **Bergstra & Burgess, "Local and Global Trust Based on the Concept of + Promises," arXiv:0912.4637 (2009)** — local trust as the expectation that a + promise will be kept; global trust as a weighted eigenvector-centrality + ("voting") function over the promise graph. +- **Bergstra & Burgess, "Promises, Impositions, and other Directionals," + arXiv:1401.3381 (2014)** — refines the taxonomy of promise-like constructs + and their directionality. + +### 2.4 The books + +- **Bergstra & Burgess, *Promise Theory: Principles and Applications*, χtAxis + Press, 1st ed. February 2014 (ISBN 9781495437779); 2nd ed. 2019 (ISBN + 9781696578554).** The formal reference text; all numbered Definitions (Defs + 1–23) cited below are from the 2nd edition. Free PDF at markburgess.org. +- **Mark Burgess, *In Search of Certainty: Ruling the Machines That Rule the + World*, 2nd ed. O'Reilly, April 2015 (ISBN 9781491923337; first edition + self-published 2012 — first-edition date not independently confirmed + `[UNVERIFIED]`).** A broad science-of-infrastructure book in which promise + theory is the "semantic measuring stick." +- **Mark Burgess, *Thinking in Promises: Designing Systems for Cooperation*, + O'Reilly, June 2015 (ISBN 9781491917879).** The popular, non-technical + introduction — the best starting point for a newcomer. + +### 2.5 Recent and ongoing work (2024–2026) + +- **Burgess & Dunbar, "Causal evidence for social group sizes from Wikipedia + editing data," *Royal Society Open Science* 11:240514 (2024), DOI + 10.1098/rsos.240514** — the most prominent peer-reviewed empirical + application; derives a scaling law from a "promise theory model of bipartite + trust." +- **Burgess, "Cooperation in Human and Machine Agents: Promise Theory + Considerations," arXiv:2604.10505 (2026)** — directly relevant to hybrid + human–AI coordination: "Promise Theory represents the fundamentals of + signalling, comprehension, trust, risk, and feedback between agents, and + offers some lessons about success and failure." +- **Burgess, "Quantitative Promise Theory: Intentionality and Inference in + Autonomous Agents," arXiv:2606.08552 (2026)** — incorporates Bayesian + probability, information-theoretic optimisation, and Active Inference into + promise semantics. +- **Burgess, "Legal Responsibilities Using Autonomous Agents For Artificial + Intelligence," arXiv:2608.08022 (2026)** — applies the Downstream Principle + to assign legal responsibility in AI-agent incidents. + +--- + +## 3. The core model — definitions with citations + +### 3.1 Agents and autonomy + +The active entities in promise theory are *agents*: persons, animals, plants, +machines, or any other entity that exhibits behaviour whose observation leads +to the perception of behaviour and intentions in others. *Autonomy* is the a +priori assumption that agents cannot be coerced into making promises and that +"no agent may make promises on behalf of another" (Bergstra & Burgess, +*Promise Theory* 2nd ed., ch. 1). Each agent lives in its own private world +with incomplete information. + +The five tenets of promise theory (book §1.3): + +1. Agents are autonomous; they can only make promises about their own + behaviour; no other agent can impose a promise upon them. +2. Making a promise involves passing information to an observer, but not + necessarily an explicit linguistic message. +3. Assessment of whether a promise is kept may be made independently by any + agent in its scope. +4. Interpretation of a promise's intent may be made independently by any agent + in its scope. +5. The internal workings of agents are unknown; knowledge of them is assessed + from the promises they make and keep, and the agent boundary may be drawn + arbitrarily. + +The autonomy assumption is explicitly **not** an ideological commitment to +decentralisation (the book warns against this misreading); it is a modelling +postulate chosen because it forces complete documentation of intended behaviour +and exposes failure modes. The promise-theory notion of autonomy is +causal/physical (agents are causally independent), not moral. + +### 3.2 The promise (Def 1) and its notation + +**Def 1 (Promise or µ-promise).** "A promise is an autonomous declaration of +intended, but as yet unverified, behaviour from one agent (the promiser) to +one or more others (called promisees). Each promise contains a body b that +explains what is being promised." + +Notation (book eq. 3.1): + +``` + b +As ──→ Ar (promise from As to Ar with body b) +``` + +The shorthand `S ─b→ R` says the same thing: agent S promises to agent R a +body of behaviour b. The promise is "unverified" because one does not promise a +state of affairs already known; the promisee has yet to verify the outcome. A +promise may refer to past or future events. + +The **body b** of a promise contains: + +- a **name or label** Λ(b) uniquely identifying the promise; +- a **type** τ(b) describing the nature of the promise; +- an explicit **constraint** χ(b) on the affected state of the agent. + +The body is often written as a pair b ~ (τ(b), χ(b)). Negation: for each body +b there is a body ¬b with ¬¬b = b, τ(¬b) = τ(b), and ¬χ(b) = χ(¬b) — negation +applies to the constraint, not the type. The full description of a promise is +the tuple def(π) = ⟨A, b, A′, σ⟩ (promiser, body, promisee, scope). + +### 3.3 Promise proposals (Def 2) + +**Def 2 (Promise proposals).** "The statement of a promise that is posited for +consideration by one or more parties, prior to keeping or discarding the +promise." A proposal is a complete description of a possible promise that is +not yet intended — the book analogises to treaty negotiation and un-signed +contracts. Burgess's *In Search of Certainty* summary: "A promise proposal is +not yet promised — like a testament/will that hasn't yet been signed." In a +hybrid workforce, a *draft* capability manifest or a contract template before +acceptance is a promise proposal (`EXTRAPOLATION`: the mapping of proposals to +agent-workforce artifacts is this skill's synthesis, not a claim in the cited +sources; developed in [agent-coordination.md](agent-coordination.md)). + +### 3.4 Scope and knowledge (Defs 3–4) + +**Def 3.** The description of a promise π is denoted def(π); def(def(π)) = +def(π) (idempotent). Knowledge of a promise may itself be the content of a +promise ("I promise that X told me about her promise…"). + +**Def 4 (Scope).** "We denote the scope of a promise by a set of agents σ, +with whom information def(π) is shared." Only agents in scope can form +expectations. A promise directed to "any agent" is written to A?; to all +agents, to ∗. Scope is why a promise is not a global broadcast: expectations +are local — an agent cannot form an expectation about a promise it has never +learned of. + +### 3.5 Promisees, acceptors, consent, and ± polarity + +The promisee (recipient) is not passive. Because agents are autonomous, a +promise "to give" only has effect if the promisee makes a complementary +promise "to accept." The book introduces **signed (polarised) promises**: + +``` + +b +A1 ──→ A2 ("I will give b") + −b +A1 ──→ A2 ("I will accept b") +``` + +Pairs of back-to-back promises of opposite polarity form a **binding** (a +handshake). This is the formal content of "voluntary cooperation": cooperation +requires both *offer* and *acceptance*, and *consent* is modelled as the +promisee's own counter-promise. The book notes the analogy between ± promise +polarity and positive/negative electric charge. **Lemma 1** establishes the +inequivalence of "promise to accept" and "imposition to give": accepting is +not the same as being obliged to offer. (In human contexts empathy can blur +this — the book's "I promise to receive you at my wedding" example — but in +formal terms the distinction is preserved.) + +### 3.6 Impositions (Def 5) + +**Def 5 (Imposition).** "A message intended to induce voluntary cooperation in +another agent" — an attempt to implant an intention in an external agent, +*without* a prior promise to accept. Degrees include hints, suggestions, +requests, requirements, specifications, commands, and demands. + +Impositions are not promises (they cannot be kept by the one who makes them) +and are not obligations (no penalty semantics). An imposition only "works" +inside an existing network of promises that makes the target disposed to +accept. In notation, an imposition from A1 to A2 with body b is drawn with a +distinctive arrow (the book suggests "imagine a fist"). Every push-based +orchestration command — an Ansible task over SSH, a `kubectl` scale that the +scheduler enforces — is, in this vocabulary, an imposition (see +[applications-infrastructure.md](applications-infrastructure.md)). + +### 3.7 Obligation — a derived, non-autonomous construct + +*Obligation* (book §1.4, §3.7): "An imposition that implies a cost or penalty +for non-compliance." Obligations are imposed from outside and hence violate +(or at best suspend) autonomy: "Autonomous agents are, by definition, never +obliged to do anything they have not decided for themselves. To accept an +obligation, an autonomous agent must sacrifice some of its autonomy." + +The theory's central polemical move: in philosophy and law a promise is +usually taken to generate an obligation; promise theory rejects this and treats +promise and obligation as *independent* concepts (Bergstra & Burgess, "A +static theory of promises," arXiv:0810.3294). Obligations can be *modelled* in +promise theory only as derived structures: an agent voluntarily promising to +accept another's directives — the basis of *authority* (Burgess, "Authority +(I): A Promise Theoretic Formalization," SSRN 3855352, 2021). This is also the +theory's account of why command-and-control is not contradicted by autonomy: +"Since a promise can always be withdrawn, there is no contradiction between +voluntary cooperation and command and control" (Wikipedia, citing the static +theory). So the derived chain is: **obligation = imposition + penalty**, kept +alive only by a standing voluntary promise to accept. + +### 3.8 Self-promises + +An agent may promise to itself — the book's µ-promise of the first kind is +precisely S → R with S = R for self-promises. Self-promises are the formal +representation of *goals, policies and desired states* that an agent undertakes +to maintain (e.g., CFEngine's desired configuration state). Because promiser +and promisee coincide, assessment and verification are internal but still +deferred ("unverified" until assessed). The modern capability-manifest pattern +for AI agents — an agent's self-commitment to its own operating rules — is a +self-promise (`EXTRAPOLATION`: the mapping to AI capability manifests is this +skill's synthesis; developed in [agent-coordination.md](agent-coordination.md)). + +### 3.9 Bindings, promise chains, and valence + +*Acceptance* is a counter-promise (the −b promise of §3.5). A *binding* is a +pair of promises of opposite polarity that mutually connect two agents +("back-to-back"). Bindings are the primitive of all cooperative structure: "A +promise binding defines a voluntary constraint on agents. The perceived +strength of that binding is an individual value judgement made by each +individual agent" (book, ch. 3). The concept of *valence* (Def 15) measures +how many bindings an agent can sustain — an analogy drawn from the +valency/oxidation-number concept in chemistry; an agent that promises more than +its valence allows is *overcommitting*. + +A *promise chain* is a sequence of promises linking an upstream source to a +downstream recipient through intermediaries (each link typically itself a +binding). Chains are the unit of analysis for service delivery, supply chains, +and workflows; conditional promises allow redundant/alternative paths. The +book (fig. 13.14) illustrates a "+s1 → +s2 → +s3" chain with ownership resting +at the most downstream interior agent. + +### 3.10 Trust as discounting + +Trust in promise theory is defined relative to promises: + +- *Local trust* (Bergstra & Burgess, "Local and Global Trust Based on the + Concept of Promises," arXiv:0912.4637, 2009): "An agent is trustworthy if it + is expected that it will keep a promise." Reputation is the propagation of + such expectations from agent to agent. The 2009 paper argues trust is + fundamentally *heuristic* — promise-based information is insufficient for + rational judgement — and defines *global/community trust* as a weighted + eigenvector-centrality (self-consistent voting) function on the promise + graph. +- *Trust discounting* (book §3.12.5): a promise to keep a promise is believed + less than a direct promise. If β(π(b)) is belief in direct promise π, then + belief in π(n)(b) (an n-fold promise about a promise) satisfies + β(π(n)(b)) = δ(n)β(π(b)), with discounting factor δ ≤ 1. + +The FAQ adds: "Trust is a human judgement, informed by experience of +reliability, and how well agents keep their promises… Trustworthiness is an +assessment. It can also be promised about oneself or another agent." The book +also distinguishes this from the different technical meaning of "trust" in +computer security. + +### 3.11 Assessment α, belief β, and evidence ε + +**Def 21 (Assessment).** "A 'decision' by a single agent O about whether a +promise π has been kept or not," written αO(π); more fully +αA(π; t_i, t_f; I) — assessment by agent A of promise π over the time interval +[t_i, t_f] on the basis of a set of impressions I (measured data, hearsay, +etc.). The assessment function is itself a promise (to supply a +determination), so assessment is not a new kind of object in the theory. + +**Def 22 (Belief).** β(π, t_i, t_f, I): a *prior* (Bayesian-flavoured) +assessment of the likelihood that π will be kept within the stated interval. + +**Def 23 (Evidence).** ε(π, t_i, t_f, E): a *posterior* (frequentist / +evidential) assessment that π was kept, based on partial evidence E. + +**Lemma 5 (Assessments are relativistic non-invariants):** assessments result +from contextual observation and are in general non-repeatable and +agent-specific; observations at different places/times have the status of +random variables. Outcomes are either T(X) (true), F(X) (false), or +indeterminate. This is why the theory insists every assessment record must +carry *who assessed, when, and against what observation* — an assessment +without provenance is an opinion, not evidence (see +[applications-infrastructure.md](applications-infrastructure.md) and +[trust-and-verification.md](trust-and-verification.md)). + +### 3.12 Promise matrices and adjacency graphs + +**Def 6 (Promise matrix).** For a collection of n agents {A_i}, the promise +matrix π_ij collects all promises between A_i and A_j with agent labels +implicit; the union/sum over all pairs denotes the complete set of promises. + +**Def 7 (Promise adjacency matrix).** Π_ij = 1 iff A_i promises anything to +A_j (b_ij ≠ ∅), else 0. The matrix admits a rank decomposition +Π_ij = Σ_r Π_ij^(r) into matrices of promises of rank r. + +Promise graphs are directed graphs whose edges are promises; since each edge +requires a counter-promise to be *effective*, "a link requires the mutual +consent of two autonomous agents," making promise graphs more primitive than +ordinary graph adjacency — and the foundation for Burgess's notion of *semantic +spacetime* (Burgess, "Spacetimes with Semantics (I)," arXiv:1411.5563, 2014). +Graph-inspection is where broken promises show up: two promises of the same +type with different constraints are a contradiction (Burgess, "Promise You A +Rose Garden," 2007). + +### 3.13 Exact, inexact, and empty promises + +- **Exact vs inexact (Def 8):** a promise is *exact* if its constraint χ(b) + leaves no residual degrees of freedom, otherwise *inexact* (e.g., "q = 5" + exact vs "1 < q < 5" inexact; a 100 Ω ±5% resistor is an inexact promise). +- **Empty/superfluous promise (Def 9):** a promise whose body contains no type + or constraint ("I promise something or other"); it is trivially kept. + Promises about inevitable outcomes are superfluous. + +The empty promise is the formal limit of vacuous agreements — a contract whose +acceptance criteria are unstated satisfies nothing. This is why the skill's +manifest schema makes empty promises structurally impossible to declare +meaningfully (see [glossary.md](glossary.md) and `SKILL.md`'s Quick Start). + +### 3.14 Deception + +**Def 10 (Deception).** "A deception consists of two intentions: a documented +intention (i.e. a promise) and a non-documented intention, which are +incompatible." A lie is a promise made about something the agent knows it +cannot accomplish or does not intend to keep. Only the lying agent can +generally detect its own lie. The "I promise X if I can" dodge is an evasion +equivalent to an empty promise. Relatedly, *promise drift* (FAQ): intentions +drift as promises are forgotten, changed, or deprecated; if some agents change +while others do not, reliance fails. + +### 3.15 Bundles, valence, and roles + +**Bundles (Defs 12–14):** *promise bundles* aggregate promises between sets of +agents S, R ⊆ A (homogeneous and parameterised variants) — the origin of +CFEngine's bundle mechanism. **Valence (Defs 15–17):** the number of distinct +bindings an agent can sustain, with *net valence* of a graph and *utilization* +defined from the ± counts — the graph-theoretic quantity controlling saturation +and overcommitment. **Roles (Defs 18–20):** equivalence classes of agents — +roles *by association* (promisers making the same promise), *by appointment* +(promisees receiving the same promise), and *by cooperation* (coordinated +roles) — turning a promise graph into a compact organisational description. +Roles-by-association is exactly what a "role" in a multi-agent team manifests: +agents that promise the same capability. + +### 3.16 Discovery + +In a world of autonomous agents with no global registry, agents must find one +another. The book describes *discovery* as "a kind of Monte Carlo search": +agents become aware of one another's promises by random-walk encounters and +then bind to one another; communication is the act of binding to discovered +agents. The book also distinguishes *dispatch* (point-to-point delivery) from +*distribution/flooding* (broadcast to superagent binding sites) as +dissemination strategies. Modern service discovery (DNS, Consul, CoreDNS) is +the industrial form of this (see [applications-infrastructure.md](applications-infrastructure.md)). + +### 3.17 The Downstream Principle + +**Downstream principle** (book §13.6.3): in a chain of promises, dependencies +are *upstream* and benefactors are *downstream*; "the assurance of the final +promise outcome follows a 'downstream principal' [sic] that the most downstream +agent has both access and opportunity to correct or absorb faults, and hence +the greatest causal responsibility for an assessment of a promise not being +kept." The principle is explicitly a pragmatic observation about cause and +effect, "not a moral assessment," and it inverts conventional +hierarchy/Root-Cause-Analysis assumptions: influence propagates bidirectionally +through bindings while the final user retains ultimate causal responsibility +for securing the outcome. This principle is the load-bearing idea in Burgess's +2026 AI-legal-responsibility paper (arXiv:2608.08022) and in the skill's +"redundancy and downstream responsibility" pattern. + +### 3.18 Evaluation and convergence loops + +Keeping a promise is a process of *convergence*: agents continuously assess +(α, β, ε) and re-enforce promises, repairing drift toward the promised fixed +point. The book's conceptual graph is "Autonomy → Promise → Cooperation → +Assessment → …" — a feedback loop (fig. 1.2). Burgess's *In Search of Certainty* +summaries add that convergence goes beyond idempotence: a promise is kept when +the system ends in the correct state (a mathematical fixed point), and +"detailed balance" of opposing promises is how semantics are stabilised on top +of flawed dynamics. The 2019 "Locality, Statefulness, and Causality" paper +(arXiv:1909.09357) argues that feedback loops and recursion, which appear +acausal to external observers, make statefulness/statelessness an artifact of +observational scale. The practical expression of the loop — observe → assess → +act — is the mechanism behind CFEngine and Kubernetes (see +[applications-infrastructure.md](applications-infrastructure.md)). + +--- + +## 4. Formal status — what is actually defined, proven, and claimed + +The authors themselves describe the framework as a **semi-formal language** +(Bergstra & Burgess, *Promise Theory* 2nd ed., preface). Concretely: + +**What exists:** a defined notation; numbered Definitions (1–23 in chs. 3 and +5, more later); Rules (e.g., Rule 1 "Separate events have separate types"; +Rule 2 "Idempotence of promises"); Lemmas (Lemma 1: inequivalence of − promise +and + imposition; Lemma 5: assessments are non-invariants); Examples; and a +small algebra (idempotence, negation involution, def-idempotence, ± polarity, +δ-discounting). + +**What does not exist:** there is **no complete axiomatisation** — no closed +set of axioms with rules of inference, no sound-and-complete equational theory +(the "algebra" is a list of properties, not a calculus with meta-theorems) — +and **no model-theoretic semantics** in the mainstream sense (no truth +conditions over structures, no completeness results). The process-algebra +paper (arXiv:0707.0744, 2007) is the closest thing to a mainstream-formal +statement and it is short (9 pp.) and example-driven. There is also no +standalone publication titled "promise algebra"; the algebra lives inside the +book and its process-algebra companion. + +**What is rigorously proven:** essentially nothing beyond the algebraic +identities above, which follow directly from the definitions. The strongest +empirical validation is the 2024 Burgess–Dunbar *Royal Society Open Science* +paper, but its "proof" is a statistical fit to a scaling law, not a derivation +from axioms. + +**What is informally claimed:** that promises "reduce uncertainty" better than +obligations; that promise theory subsumes game theory and information theory +("games can always be expressed in promise language, but not vice versa"; "an +information model can always be represented as promises, but not vice versa" — +FAQ; arXiv:2004.12661); that any system of interacting components can be +analysed this way (universality). Most importantly for honesty: + +> **The ≤50% vs ≤100% claim is an informal heuristic.** The FAQ states that +> "the chance of an imposition being honoured within its expected time is at +> best 50/50, but that may increase up to 100% for promises." As stated it has +> **no derivation** and is **not a proven result**; it is an unfalsifiable-in- +> this-form heuristic about the relative reliability of voluntary promises over +> imposed commands. Use it as a mnemonic for why promises beat impositions, not +> as a quantitative law. + +Treat the formalism as a **reasoning aid, not a proof system**: it gives you a +vocabulary and a consistency check (contradiction detection on promise graphs), +not soundness guarantees. This is the honest boundary of the theory — and it is +a deliberate design choice to remain a *language* rather than a model of +everything with a canonical semantics. + +--- + +## 5. Adjacent frameworks — comparison with citations + +### 5.1 Social commitments in multi-agent systems (the closest relative) + +- **M. P. Singh, "An ontology for commitments in multiagent systems," + *Artificial Intelligence and Law* 7:97–113, 1999** — commitments as social, + directed, normative relations with operations (create, discharge, cancel, + delegate, assign, violate). +- **P. Yolum & M. P. Singh, "Commitment Machines," ATAL 2001 / *Intelligent + Agents VIII*, LNCS 2333, pp. 235–247, 2002** — protocols as commitment + machines compiled to finite-state machines with proven soundness/completeness. + +**Comparison.** Both traditions treat coordination as emerging from directed, +publicly observable social relations rather than from individual mental states. +Differences: (i) the MAS tradition keeps *obligations and violations* as +first-class (a violated commitment triggers normative consequences), while +promise theory removes penalty semantics; (ii) the MAS tradition has rigorous +temporal-logic semantics and verification (model checking of commitment +protocols), which promise theory largely lacks; (iii) promise theory adds the +physical/autonomy grounding (agents are causally independent, promises are +always revocable); (iv) promise theory's *assessment* is intentionally +relativistic (each agent judges), whereas commitment logic is objective and +global. The literatures barely cite each other — cross-citation is almost nil +(report interpretation). *Relationship in one line:* a commitment "to which +one is committed" is a special case of a promise (book §3.12.1). + +### 5.2 Deontic logic + +- **G. H. von Wright, "Deontic logic," *Mind* 60(237):1–15, 1951**; standard + deontic logic (O/P/F) and its paradoxes; dyadic / contrary-to-duty logic + (**Prakken & Sergot, 1997**). + +Promise theory is deliberately **antagonistic** to deontic logic. The DSOM 2005 +paper cites Chellas's *Modal Logic* and Prakken & Sergot — Burgess knew the +literature. The critique is pragmatic: obligation logic assumes an external +norm that an autonomous agent will follow, which in distributed systems is +precisely what cannot be assumed; obligations "amount to wishful thinking." +Promise theory therefore replaces the normative primitive (obligation) with a +descriptive one (declaration of intent) and derives obligation-like behaviour +as voluntary acceptance. **Consequence:** promise theory deliberately forgoes +the expressiveness of normative reasoning — permissions, prohibitions, +contrary-to-duty obligations — which matters when modelling *regulation* rather +than *coordination*. For compliance-driven AI governance, you may need both +(see also the OPA/Kyverno discussion in +[applications-infrastructure.md](applications-infrastructure.md)). + +### 5.3 Design by Contract + +- **B. Meyer, "Applying 'Design by Contract'," *IEEE Computer* 25(10):40–51, + 1992** — preconditions, postconditions, and invariants attached to software + modules, checked at runtime. + +**Comparison.** The structural parallel is strong: a service's promises are its +postconditions/invariants; a use-promise is the caller's precondition; +assessment is runtime assertion checking; convergence to fixed points is +invariant maintenance. The philosophical upgrade: DbC obligations are +enforced by the compiler/runtime (the system is not autonomous), while promise +theory insists both sides are autonomous and must *choose* to participate — +the *client* also promises to use the service correctly, making DbC a special, +one-sided case of a symmetric promise contract (report interpretation; +grounded in book §3.12.1 and the FAQ's "invariants" language). For an agent +workforce: DbC is the right tool *inside* a single program or agent; +promise theory is the right tool *between* agents (human or machine) that +cannot assume obedience. + +### 5.4 Control theory + +- **M. Burgess, "A control theory perspective on configuration management and + Cfengine," *ACM SIGBED Review* 3(2):12–16, 2006**; **Burgess & Couch, + "Autonomic Computing Approximated by Fixed-Point Promises," MACE 2006, + pp. 197–222**; the canonical autonomic-computing statement is **Kephart & + Chess, "The Vision of Autonomic Computing," *IEEE Computer* 36(1):41–50, + 2003** (MAPE loop). + +**Comparison.** Burgess explicitly connects CFEngine/promise theory to feedback +control: convergence to fixed points is tracking a reference signal; assessment +is error measurement; promises are reference/constraint signals. Promise theory +adds *semantic* (not just dynamic) stability — meaning and intent on top of +performance — and its control-theoretic reading is the most scientifically +conventional justification for its convergence claims. The skill's "evaluation +loop" pattern (observe → assess → act) is a MAPE loop in promise vocabulary. + +### 5.5 (Brief) Policy-based management, game/information theory, sociology of trust + +- **Policy-based management** is the theory's immediate intellectual context: + Sloman & Moffett's policy hierarchies (1993), Lupu & Sloman's role-based + frameworks (1996/1997), and Ponder (Damianou et al., 2000) modelled policy as + obligations and authorisations imposed from above. The DSOM 2005 paper argues + this fails for autonomous networks and proposes promises as "atomic policy + units." +- **Game theory:** the "Voluntary Economic Cooperation in Policy Based + Management" paper (2004, archived) introduced the economic reading — promises + as strategies, cooperation as a repeated game, "detailed balance" as an + equilibrium condition. The FAQ claims strategic-form games arise from + collections of bi-directional ± promises and extensive-form games from + conditional-promise graphs. This is a claimed (not proven) subsumption. +- **Information theory:** Burgess, "Information and Causality in Promise + Theory," arXiv:2004.12661 (2020) — a Shannon channel as two promises (+b) + and (−b); the claim that information models embed in promises but not vice + versa. Again a claimed subsumption. +- **Sociology of trust:** promise theory aims to give trust a definable, + computable substrate (arXiv:0912.4637; "Notes on Trust as a Causal Basis for + Social Science," SSRN 4252501, 2022), formalising what Gambetta (1988) and + the trust literature treat qualitatively. The 2024 Burgess–Dunbar paper is + the first quantitative validation. + +--- + +## 6. Critiques and limitations + +1. **No axiomatisation, no model theory** (detailed in §4). The "algebra" is a + list of properties; the process-algebra paper is an outline, not a calculus + with meta-theorems. +2. **Vague primitive semantics.** The promise *body* b is deliberately + underspecified — "up to each agent… to decide" — and the theory "does little + to formalize the promise bodies it refers to" (FAQ, category-theory + answer). This makes promise theory more a *metalanguage* than a domain + model. +3. **Dependence on the originator and venue concentration.** Most formal + statements appear in Burgess's and Bergstra's own books/preprints, in + Bergstra's own journal (Transmathematica), or in self-published χtAxis + volumes; the Wikipedia article flags over-reliance on sources "too closely + associated with the subject" and possible "original research." Citation + count in the mainstream multi-agent and formal-methods literatures is low. +4. **Testability is hampered by relativistic assessment.** Lemma 5 makes each + agent's assessment agent-relative, which complicates inter-observer + falsification; most claimed predictions are structural ("commands do not + work without invitations"), not quantitative. +5. **The "not even wrong" challenge.** The FAQ devotes a section to this + Popperian challenge. The honest assessment: promise theory has + *explanatory* power (retrospective case studies: Boeing 737 MAX, + arXiv:2001.01543; Brexit; money) but a thin, mostly qualitative *predictive* + record; the one strong quantitative test is the 2024 Dunbar collaboration, + which is real but narrow. +6. **The "model of everything" risk.** If any behaviour can be represented as + a promise, promises risk carrying no information. The theory's defence — + scope, exact/inexact constraints, assessment, valence — narrows this but + does not close it; the burden of a canonical semantics remains open. + +**Open problems** (from the research report's future-work list): a complete +axiomatisation and model theory; proven embeddings into CTL-style commitment +logics, deontic logic, or linear logic; quantitative calibration of β, ε, δ, +and valence from real telemetry (arXiv:2606.08552 begins this); agent-AI +applications (arXiv:2604.10505; arXiv:2608.08022); an empirical validation +programme beyond the Dunbar collaboration; and a schema/ontology for promise +bodies that would make promises machine-verifiable. + +--- + +## 7. Sources (works cited above) + +**Books.** Bergstra & Burgess, *Promise Theory: Principles and Applications*, +2nd ed., χtAxis Press, 2019 (Defs 1–23, tenets, rules, lemmas). Burgess, *In +Search of Certainty*, 2nd ed., O'Reilly, 2015. Burgess, *Thinking in Promises*, +O'Reilly, 2015. Bergstra & Burgess, *Money, Ownership and Agency*, χtAxis, +2019. Burgess, *A Treatise on Systems*, vols. 1–2, 2020. + +**Papers.** Burgess, DSOM 2005, LNCS 3775, pp. 97–108. Bergstra, Bethke & +Burgess, arXiv:0707.0744 (2007). Bergstra & Burgess, arXiv:0810.3294 (2008, +rev. 2014). Bergstra & Burgess, arXiv:0912.4637 (2009). Bergstra & Burgess, +arXiv:1401.3381 (2014). Burgess & Dunbar, *Royal Society Open Science* +11:240514 (2024). Burgess, arXiv:2604.10505; arXiv:2606.08552; arXiv:2608.08022 +(2026). Burgess, arXiv:1411.5563 (2014); arXiv:1909.09357 (2019); arXiv: +2004.12661 (2020). Burgess, SSRN 3855352 (2021); SSRN 4252501 (2022). Burgess, +"Promise You A Rose Garden" (2007); Promise Theory FAQ (markburgess.org/ +promiseFAQ.html). + +**Adjacent frameworks.** Singh (1999); Yolum & Singh (2002); von Wright (1951); +Prakken & Sergot (1997); Meyer (1992); Sloman & Moffett (1993); Damianou et al. +(2000); Kephart & Chess (2003); Gambetta (1988). Full bibliographic details are +in the mission research report (academic-foundations.md); the repository +standard is to cite the named work inline, as above. From 93e0d965cae5a14323bd05ef8ae3e91f3dc9f8c5 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:12:37 -0400 Subject: [PATCH 3/9] =?UTF-8?q?feat(skill):=20promise-theory=20references?= =?UTF-8?q?=20=E2=80=94=20coordination,=20patterns,=20trust=20&=20verifica?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the three coordination references per architecture 4.2/6/7: - agent-coordination.md: the core thesis with the fixed 11-concept mapping table (concept -> concrete agent-coordination practice), the hybrid human+agent boundary (humans as acceptors/evaluators, calibrated subordination, causal vs moral responsibility, HITL escalation, three-languages problem, swarms vs teams), the multi-agent lineage, and the agent-council routing statement; cites Burgess arXiv:2604.10505 and states the scarcity of direct literature. - patterns.md: all seven canonical patterns with worked examples, the M12 ladder, the Ye & Tan contract tuple and lifecycle with degradation semantics, the named ESCALATE-2 trigger, and the workflow-architect routing via the bundles path. - trust-and-verification.md: the two-component trust model, belief/evidence, P_succ, verification rates as attention budgets incl. Dunbar budgets, gameable assessment, semantic-promise measurement guidance, "confine, don't convince", the versioned promise ledger, and routing to agent-evals-and-observability and artifact-pyramids. All files under the 60k-char reference cap with [UNVERIFIED]/EXTRAPOLATION provenance markers per architecture 4.2. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- .../references/agent-coordination.md | 149 ++++++++++++++++ promise-theory/references/patterns.md | 162 ++++++++++++++++++ .../references/trust-and-verification.md | 107 ++++++++++++ 3 files changed, 418 insertions(+) create mode 100644 promise-theory/references/agent-coordination.md create mode 100644 promise-theory/references/patterns.md create mode 100644 promise-theory/references/trust-and-verification.md diff --git a/promise-theory/references/agent-coordination.md b/promise-theory/references/agent-coordination.md new file mode 100644 index 0000000..d1642fa --- /dev/null +++ b/promise-theory/references/agent-coordination.md @@ -0,0 +1,149 @@ +# Agent Coordination — The Core Thesis: Promise Theory for Hybrid Human + AI Workforces + +**Load this file when you need to design or diagnose coordination between specific humans and agents** — which actor may promise what to whom, how acceptance is recorded, where human oversight sits, how delegation chains stay trustworthy, and when a fleet should behave as a team rather than a swarm. This is the practical heart of the skill. The mapping table in Section 2 pairs every core promise-theory concept with a concrete agent-coordination practice; Section 3 draws the hybrid human + agent boundary; Section 4 positions promise theory inside the multi-agent systems research lineage. The definitions behind every term used here are in [foundations.md](foundations.md); the named, buildable patterns (manifests, handshakes, contracts, evaluation loops, breach→renegotiation, redundancy, trust calibration) are developed with worked examples in [patterns.md](patterns.md); calibrating trust and verification budgets is [trust-and-verification.md](trust-and-verification.md). + +**Provenance.** The direct academic literature connecting promise theory to AI/LLM agents is **thin and recent**. As of mid-2026 it consists essentially of Burgess's position paper *Cooperation in Human and Machine Agents: Promise Theory Considerations* (arXiv:2604.10505, 2026), his 2025 twentieth-anniversary review, a handful of essays and interviews (NLnet/NGI, 2024; webframp, 2026), and adjacent applied work on trust measurement (Burgess & Dunbar, *European Economic Review*, 2025). Everything beyond those sources in this file is the author's synthesis mapping promise theory onto LLM-agent engineering practice, and that synthesis is labeled `EXTRAPOLATION` wherever it goes beyond what the cited sources explicitly state. Claims that could not be verified against a primary source are marked `[UNVERIFIED]`. + +--- + +## 1. The thesis + +Promise theory is a method of analysis for systems of autonomous agents — humans, LLM agents, deterministic automation, APIs — founded on three axioms: (1) agents are autonomous and cannot be coerced; (2) an agent can only promise its own behaviour; (3) an agent's knowledge is local (Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., 2019). From these axioms follow the concepts the agent-engineering industry is independently reinventing: public **promise offers** that others accept or refuse, **assessment** of whether promises are kept, **breach** as an expected event rather than an anomaly, **renegotiation** rather than blame, and a two-component model of **trust** (potential trustworthiness plus kinetic mistrust — the rate at which you verify). + +**The thesis of this file is that promise theory supplies the missing organizing vocabulary and design discipline for hybrid human + AI agent workforces** — the coordination layer above the model layer. A single LLM call is a prediction problem; an agentic workforce is an organization problem. The orchestration literature (Zhu et al., *LLM-Based Multi-Agent Orchestration: A Survey*, 2026) defines the core mechanisms as task decomposition and allocation, inter-agent communication and context sharing, state management, control-flow sequencing, and error detection and recovery. All five are, in promise-theoretic terms, problems of *making, accepting, tracking, and repairing promises*. **EXTRAPOLATION** — this one-sentence identity between orchestration mechanisms and promise operations is this skill's synthesis, not a claim made in any single cited source; it follows from reading the survey's mechanism list against the promise machinery in Bergstra & Burgess (2019) and Burgess (arXiv:2604.10505). + +Three properties make the mapping more than a metaphor: + +1. **It is pessimistic by design.** Promise theory assumes promises will be broken and that guarantees are impossible ("Guarantees are impossible, and it is the autonomous responsibility of the user to allow for that" — Burgess, arXiv:2604.10505). That is exactly the correct prior for stochastic LLM agents, whose promises are "statements about intended future behavior with no binding force" (M12, "From Promises to Contracts," 2026). +2. **It is receiver-centric.** The Downstream Principle — the receiver of a promise holds the ultimate power of decision over the outcome — makes the relying party responsible for its own reliance, which is where evals, guardrails, redundancy, and escape hatches belong. +3. **It treats assessment as a first-class, costly mechanism.** Trust is *accumulated assessment* (webframp, "The Promise None of Them Kept," 2026); the rate and cost of verification are design variables, not afterthoughts. This is precisely the gap the agent industry is filling with evals, observability, and guardrails. + +Burgess himself made the connection to agent systems explicit: *Cooperation in Human and Machine Agents* (arXiv:2604.10505, April 2026) opens with "Agent based systems are more common than we may think" and argues that promise theory "offers a unified perspective on organization and functional design with semi-automated efforts." The paper supplies the boundary concepts used throughout this file: the Downstream Principle, the three-languages problem, two-component trust, proxy/delegation chains, swarms vs. teams, Dunbar trust budgets, and the "cooperative manifesto." + +## 2. The fixed mapping table + +The table below is the fixed concept→practice mapping of this skill: the left column is a promise-theory concept with its canonical source; the right column is a concrete agent-coordination practice — something you can actually do with or for agents. All eleven rows are populated; the rows marked **EXTRAPOLATION** are this skill's synthesis where the source literature does not itself make the connection. Each right-hand cell names a practice, not a restatement of the concept. + +| # | Promise-theory concept (source) | Concrete agent-coordination practice | +|---|---|---| +| 1 | **Promise offer** — an agent's public declaration of its own intended behaviour (`Ai →+b Aj`; Bergstra & Burgess 2019) | Publish a **versioned capability manifest**: an MCP tool descriptor or function schema ("I can search the web"), a repository `AGENTS.md` ("I will only edit files under /workspace"), a system prompt with explicit constraints, a human's commitment ("I will review PRs by EOD"), or an SLO. Declare capabilities, constraints (what the agent will *not* do), resource limits, and withdrawal semantics before any task is dispatched. | +| 2 | **Acceptance promise** — the receiver's voluntary agreement to rely on an offer (`Aj →−b Ai`); only the overlap of offer and acceptance transmits influence | Run a **two-way handshake / approval gate** on every delegation: the executing agent explicitly accepts or refuses the task; a human clicks "approve" at consequential checkpoints; a guard checks "is this worker enrolled for this capability?" before dispatch. Log accept/refuse and measure the refusal rate as a coordination signal. | +| 3 | **Imposition** — an attempt to induce acceptance by force, without the receiver's promise | Detect and eliminate **push-based commands without consent**: dispatching to an agent that never accepted, a central controller that assumes compliance, a human ordered to execute without opt-in. LLM-era impositions fail distinctively: they *look* accepted (fluent acknowledgment) and are not — so audit for "acknowledged but not enrolled" paths. | +| 4 | **Assessment α** — each agent evaluates whether the promises it relies on are kept; the load-bearing concept ("the principal area for exploiting and misdirecting agents" — Burgess) | Build the **assessment layer**: evals (offline benchmarks + online scorers), guardrails, observability traces, code review, fact-checking, human review. Treat "a promise that nobody assesses" as operationally meaningless. | +| 5 | **Measured promise / P_succ** — an empirically estimated probability of success; the receiver's accumulated estimate of reliability (`V_S = α_R(π_S)`) | Track **potential trust as data**: maintain a per-agent P_succ over repeated runs (Leoveanu-Condrei's Design-by-Contract for LLMs); compare providers by P_succ and cost; treat two agents satisfying the same contract as interchangeable except for those two numbers. | +| 6 | **Verification rate / kinetic mistrust** — the rate at which the receiver checks on the promiser; an attention/energy budget (Burgess & Dunbar 2025) | Run a **verification sampling schedule**: how often you run evals, ping health checks, re-audit outputs, or re-review an agent's work. Start new agents at 50-50 and calibrate; scale checking rate with risk and inversely with measured P_succ; budget the verification cost explicitly (tokens + human attention). | +| 7 | **Breach** — an unkept promise, detected by assessment; expected, not exceptional | Classify breaches against the **multi-agent failure taxonomy** (Cemri et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025): a failed eval, guardrail trip, violated SLO, wrong tool call, or reviewer-caught hallucination maps to specification / inter-agent conflict / verification failure. Instrument each class. | +| 8 | **Downstream Principle** — the receiver holds ultimate decision power and carries greatest causal responsibility for the outcome (Burgess, arXiv:2604.10505, Def. 1) | Practice **receiver-owned reliance risk**: the consumer of an agent's output decides its value, so give every downstream party redundancy, verification tools, and escape hatches ("the downstream agent only has its own policy to blame" — Burgess). Design for the promise *not* being kept. | +| 9 | **Proxy / delegation chains** — conditional promises through middlemen are unreliable; agents are not reliable relays (Burgess, arXiv:2604.10505) | Treat **every handoff as a logged boundary**: record inputs, outputs, and timing at each agent-to-agent transfer the way you would log a remote procedure call; verify per-hop rather than trusting the chain head; watch for handoff-context-loss failures in multi-agent traces. | +| 10 | **Swarms vs. teams** — "a swarm is a role associated with flying, not an identity"; role-differentiated, contract-bearing collaboration is a team (Burgess, arXiv:2604.10505 §VI-E) | Choose **team semantics for production agent systems**: assign differentiated roles with explicit promises and contracts (microservices are a team structure applied to IT); use true swarm semantics (emergent, homogeneous) only where role differentiation is genuinely absent. | +| 11 | **Dunbar trust budgets** — human groups are bounded by cognitive trust budgets; machine limits are unknown (Burgess & Dunbar 2025) | Set **team-size and span-of-control limits**: keep human-oversight groups inside Dunbar-scale budgets, batch and group agent fleets to respect attention limits, and treat "how many agents can one human meaningfully verify?" as a first-order design question. **EXTRAPOLATION** — applying the numbers to agent fleets is this skill's reading; the trust-budget model itself is Burgess & Dunbar's. | + +Two of these rows deserve a short expansion because they are the least obvious in practice. + +**Row 9 — proxy/delegation chains.** Burgess's warning that conditional promises through middlemen are unreliable (arXiv:2604.10505) predicts the handoff-context-loss failures documented in multi-agent traces (Zhu et al. 2026; Braintrust 2026). The operational consequence is that *a chain of agents is only as bound as its least-enforced boundary*: verify at each hop, propagate context explicitly, and treat the handoff record as part of the assessment data. **EXTRAPOLATION** — the mapping of "conditional promise through a middleman" to "multi-agent handoff" is this skill's synthesis; the conditional-promise mechanics are Burgess's. + +**Row 10 — swarms vs. teams.** Most production agent systems need team semantics, not swarm semantics: roles, contracts, acceptance, and assessment. A "swarm" of undifferentiated agents that emerges into coordination without declared promises is, in promise-theoretic terms, a system in which promises are being made and broken without record — exactly the *EmergentBehavior* risk dimension the Zhu et al. (2026) six-dimension framework measures (messages outside the declared interaction graph). **EXTRAPOLATION** — the equation "undifferentiated swarm ≈ unrecorded promises" is this skill's synthesis. + +## 3. The hybrid human + agent boundary + +The hardest coordination problem is the boundary between humans and agents — not because agents are complex, but because the boundary carries the theory's two asymmetric responsibilities: **acceptance** (who chooses to rely) and **assessment** (who verifies), plus the accountability question of who is *responsible* when a promise is broken. Burgess's 2026 paper supplies the frame; the operational reading below is this skill's synthesis and is labeled where it extrapolates. + +### 3.1 Humans are acceptors and evaluators, never agents in the manifest + +In promise theory every actor is both a promiser and an assessor; for humans in a hybrid workforce this means: + +- **Humans accept agent promises.** A human decides which agent offers to rely on, and can refuse (the acceptance handshake pattern in [patterns.md](patterns.md)). Acceptance is the mechanism by which agents acquire *legitimate* influence over human work. +- **Humans evaluate agent promises.** Human review is the highest-bandwidth assessment available for *semantic* promises ("the summary is accurate," "this code has no backdoor") that deterministic checks cannot yet verify (M12, 2026: "we cannot yet cheaply enforce 'the summary is accurate'"). Human review is promise evaluation, and its cost is a first-order budget item. +- **The Downstream Principle makes the relying human responsible for their own reliance** — "one takes on the risk of an agent's promise not being kept when choosing to engage with it" (Burgess, arXiv:2604.10505). This is not victim-blaming; it is a design directive: give the human the redundancy, verification tools, and escape hatches that make downstream responsibility actionable. + +**Manifest modeling consequence:** in this skill's contract schema, humans are never declared as agents in a manifest. Human acceptance of a promise is modeled as an `expectations` entry with `from: human`; humans accept and evaluate, they do not declare promises inside the agent graph. This keeps the model's causal bookkeeping honest: the only actors that can promise are the ones whose behaviour can be observed and assessed. **EXTRAPOLATION** — the schema consequence is this skill's design choice; the underlying claim (humans as acceptors/evaluators) is Burgess's and the schema's `from: human` modeling is pinned in the skill's contract. + +### 3.2 Authority as calibrated subordination — voluntary and withdrawable + +Burgess formalizes authority as **calibrated subordination**: followers voluntarily promise to follow a leader, and the leader is a trusted calibration point (Burgess, "Authority (I): A Promise Theoretic Formalization," SSRN 3855352, 2021; arXiv:2604.10505). Hierarchy "cannot be imposed onto autonomous agents, yet hierarchies can be formed by voluntary cooperation." Organizational implications for human oversight of agents: + +- A **supervisor** (human or orchestrator) is not an authority by position but by *accepted promises to follow*. When agents and humans stop accepting direction, authority has evaporated — regardless of job titles. +- **Leadership as a calibration role** explains why centralized orchestrators are attractive (a single calibration point) and fragile (a single point of trust — if the calibration is wrong, everything downstream is wrong). +- **Oversight design should treat the human supervisor as an assessor with calibrated authority**: the supervisor's promise to the organization is "I will verify X at rate Y," and the organization accepts it. **EXTRAPOLATION** — the supervisor-promise formulation is this skill's synthesis; the calibrated-subordination model is Burgess's. + +### 3.3 Causal vs. moral responsibility + +Burgess (arXiv:2604.10505, Definition 2) distinguishes: + +- **Causal responsibility** — "the freedom to obtain a promised service elsewhere" (redundancy). An agent that had alternatives and did not use them bears causal responsibility for relying on a broken promise. This is formalizable and auditable. +- **Moral responsibility (culpability)** — "a human assessment about whether agent outcomes stem from good or bad intent; hence it cannot be formalized except as a norm or in law." + +For hybrid workforces this distinction is the accountability skeleton: **machines can be causally responsible (and audited); only humans can be morally responsible (and regulated).** This aligns with current governance practice — e.g., the EU AI Act's human-oversight provisions and accountability resting with deployers — and with the industry pattern of "human responsibility for AI outcomes." **EXTRAPOLATION** — the alignment with regulation is this skill's reading; the causal/moral distinction is Burgess's. The operational consequence for a coordination design: audit trails, redundancy choices, and verification records make causal responsibility legible; they do not, and cannot, settle moral responsibility, which belongs to the humans who deployed and relied. + +### 3.4 Human-in-the-loop escalation + +HITL is promise evaluation by the most capable assessor, triggered at agreed boundaries: + +- **Approval gates** (LangGraph breakpoints, human-in-the-loop nodes): the human is the *final acceptance promise* for consequential actions (money-moving, identity-affecting, externally visible). +- **Escalation on uncertainty**: when assessment is inconclusive (low confidence, contested semantics), the promise escalates to a higher-capability assessor — a human or a stronger model. +- **Escalation on breach**: the agent contract enters VIOLATED/EXPIRED; termination conditions trigger; a human decides renegotiation vs. redundancy vs. shutdown (see the breach→renegotiation pattern in [patterns.md](patterns.md)). +- **Bounded escalation**: stop after a named number of non-converging remediation passes and report the evidence (this skill's completion discipline applied to kinetic mistrust). + +Burgess's warnings carry the design constraints: mistrust is draining — conflict consumes attention (Wikipedia edit wars), and Dunbar-scale trust budgets bound human tolerance (NLnet interview, 2024). Agent fleets must not impose unbounded human monitoring loads; that is how alert fatigue and rubber-stamping set in. And "if you trust something too much, you're not paying attention" — humans who delegate all verification to agents are the Eloi; the agents (and those who control them) are the Morlocks (arXiv:2604.10505). + +### 3.5 The three-languages problem + +Burgess's three-languages analysis (arXiv:2604.10505) — **sender language, receiver language, co-language** — explains why mentalistic semantics cannot work between autonomous agents: there is "no authority that calibrates" two agents' internal languages to be the same, and "agents can never know when they have reached the optimum without an actual (promise) dialogue and mutual assessment." **Autonomous agents are never certain.** + +For LLM agents this is structural, not incidental: sharing a base model or a protocol vocabulary does not guarantee shared meaning, because "each picks a selection based on its own context (which is autonomous and independent)." Capability schemas (MCP, A2A) are structural, not intentional — they standardize the *form* of capability declaration, not the *meaning* of the outcomes. Practical consequences: + +- **Expect misunderstanding.** "Agents should expect to misunderstand one another's intentions to some level" (arXiv:2604.10505); the Cemri et al. (2025) inter-agent-conflict class is this phenomenon at scale. +- **Negotiate meaning through dialogue and assessment**, not through shared ontologies — ontologies "trade expressibility for false precision" and need versioned calibration (Burgess). +- **Write acceptance criteria in the receiver's language**, the co-language the receiver can actually check (this is what an eval formalizes — see [trust-and-verification.md](trust-and-verification.md)). + +### 3.6 Swarms vs. teams at the human boundary + +The swarm/team distinction (row 10 of the mapping table) has a human-organizational reading: Burgess's "swarm is a role associated with flying, not an identity" (arXiv:2604.10505 §VI-E) means a human group can *behave* swarm-like without being a swarm, and a fleet of agents can *behave* team-like if roles and promises are declared. For hybrid workforces: add agents to the team as **promise-holders with the same instruments as humans** — a working agreement (the team's promise set), a Definition of Done (acceptance criteria), a cadence (assessment rhythm), and a retrospective (renegotiation). An agent with a versioned manifest, acceptance criteria, and a retro loop is governable; an agent dropped into a team with none of these is an imposition. **EXTRAPOLATION** — the direct agent-inclusion extension is this skill's synthesis; the agile-to-promise mapping is documented in Burgess's management materials (Open Leadership Network / Open Space Technology collaborations with Mezick and Sheffield, 2019–2020). + +## 4. Multi-agent systems lineage — what promise theory adds + +Promise theory sits inside a long lineage of agent-coordination research. Knowing the lineage positions the skill and states precisely what promise theory adds (and what it deliberately rejects): + +| Classic approach | Central mechanism | What promise theory changes | +|---|---|---| +| Deontic logic / policy-based management | Obligation, command | Autonomy as base state; obligations are derived, voluntary agreements (Bergstra & Burgess, arXiv:0810.3294) | +| FIPA-ACL (speech acts, mentalistic semantics) | Request/inform/promise performatives with BDI semantics | Three-languages problem; meaning is negotiated, never guaranteed (Singh 1998 made the social-semantics critique; Burgess's co-language argument supplies the mechanism) | +| BDI architectures (Bratman; Rao & Georgeff) | Interior beliefs/desires → intention | Interior is unobservable; only the expressed promise and the assessed outcome matter — methodologically convenient for LLM agents whose "beliefs" are not stable objects **EXTRAPOLATION** | +| Social commitments (Yolum & Singh 2002; Jennings 1993) | Public, socially held obligations between agents | Promises bind only the promiser; no obligation is entailed ("No agent may promise anything on behalf of any agent but itself" — Bergstra & Burgess 2019). The two schools converge on design (track, verify, repair) but diverge on the primitive | +| Norms and institutions (Dignum et al.; Boella, van der Torre) | Enforced norms and institutional mechanisms | Norms hold only when voluntarily accepted; authority = calibrated subordination (SSRN 3855352) | +| Contract Net Protocol (Smith 1980) / agent contracts | Task allocation by announcement, bidding, award | Full lifecycle with resource bounds, measured success, and promise-theoretic acceptance (Ye & Tan 2026 extend it — see [patterns.md](patterns.md)) | +| Control theory / cybernetic feedback | Feedback on a measurable plant | The "plant" is autonomous and may ignore the controller; the downstream party decides | + +**The single most important addition:** promise theory makes *assessment* — and its cost — a first-class citizen. Every classic school treats verification as an engineering afterthought; promise theory treats it as the mechanism by which trust, the "common currency" of coordination, is created and spent. That is precisely the gap the LLM-agent industry is now filling with evals, observability, and guardrails. + +## 5. Designing the promise graph — a practical procedure + +Under the reframing in Section 1, the manager's job is not to command but to **design the promise graph**: who may promise what to whom, what the acceptance criteria are, how breaches are detected, and who absorbs the risk when a promise is broken. A working procedure, synthesized from the patterns in [patterns.md](patterns.md): + +1. **Inventory the actors** — every human, agent, API, and deterministic process that touches the outcome. Decide which are agents (they can promise) and which are acceptors/evaluators (they can only accept and assess — including all humans). +2. **Declare capabilities** — each agent publishes a versioned manifest: capabilities, constraints, resource limits, withdrawal semantics (promise offer). +3. **Negotiate acceptance** — for each delegation, record an explicit accept/refuse; refusal is a coordination signal, not a failure (acceptance promise). +4. **Pin acceptance criteria** — for every promise that matters, state in the receiver's language how "kept" will be determined (assessment; an eval is a formalized acceptance criterion). +5. **Instrument assessment** — attach evals, guardrails, observability, and human review at the risk-appropriate rate (kinetic mistrust); store assessments as versioned data (see [trust-and-verification.md](trust-and-verification.md)). +6. **Plan for breach** — every load-bearing promise gets redundancy or a renegotiation path; escalation is named and bounded (breach→renegotiation pattern). +7. **Review on a cadence** — a regular assessment rhythm (standup-like) and a periodic renegotiation of the promise set (retro-like). + +This procedure is this skill's synthesis — **EXTRAPOLATION** — of the sources cited throughout this file; each individual step is grounded in the mapping table's rows. + +## 6. Routing to sibling skills + +- **Multi-agent debate and convergence** → [agent-council](../agent-council/SKILL.md). When you want to *run* structured multi-agent debate, agent-council is the operational tool: its panel debate is a promise exchange (each panelist offers positions, the moderator accepts/assesses, synthesis converges), and its convergence-aware iteration is an evaluation loop over the panel's promises. Use promise theory to *design* the exchange; use agent-council to *execute* it. +- **Assessment layer** → [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) (also routed from `references/trust-and-verification.md`): verifying promises are kept via evals, traces, and guardrails. +- **Workflow design as promise chains** → [workflow-architect](../bundles/workflow-architect/SKILL.md) (also routed from `references/patterns.md`): designing a workflow is designing a chain of promises. +- **Promise-keeping evidence** → [artifact-pyramids](../artifact-pyramids/SKILL.md) (also routed from `references/trust-and-verification.md`): structure evidence as summaries → analysis → evidence dossiers. +- **The skill format itself** → [agent-skills](../agent-skills/SKILL.md); **script conventions** → [cli-builder](../cli-builder/SKILL.md). + +## 7. Sources + +**Primary promise theory.** Burgess, "Cooperation in Human and Machine Agents: Promise Theory Considerations," arXiv:2604.10505 (2026) — the key paper for this file: Downstream Principle, three-languages problem, two-component trust, proxy chains, swarms vs. teams, Dunbar limits, causal vs. moral responsibility, the cooperative manifesto. Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., χtAxis Press, 2019. Bergstra & Burgess, "A static theory of promises," arXiv:0810.3294. Burgess, "Authority (I): A Promise Theoretic Formalization," SSRN 3855352 (2021). Burgess & Dunbar, "A quantitative model of trust as a predictor of social group sizes and its implications for technology," *European Economic Review* (2025). Burgess, "Notes on Trust as a Causal Basis for Social Science," SSRN 4252501 (2022). + +**Promise theory + agents (direct, recent).** Burgess, arXiv:2604.10505 (above). NLnet/NGI Assure interview with Burgess, "Promise Theory," 2024 (nlnet.nl/project/TrustSemanticLearning/interview.html). webframp, "The Promise None of Them Kept," 2026. M12/Todd Graham, "From Promises to Contracts: Enforceable Behavior in LLM Agents," 2026. + +**Agent systems lineage.** Jennings, "Commitments and conventions," 1993; Yolum & Singh, "Commitment Machines," 2002; Singh, "A Social Semantics for Agent Communication Languages," 1998; Smith, "The Contract Net Protocol," 1980; Dignum et al., normative MAS; Boella, van der Torre, Verhagen. + +**LLM multi-agent systems.** Cemri, Pan, Yang, et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025, arXiv:2503.13657 (14 failure modes in three classes). Zhu, Liu, Yu & Zhang, "LLM-Based Multi-Agent Orchestration: A Survey," *Future Internet* 18(6), 2026. Ye & Tan, "Agent Contracts: A Formal Framework for Resource-Bounded Autonomous AI Systems," arXiv:2601.08815 (2026). Leoveanu-Condrei, "A DbC Inspired Neurosymbolic Layer for Trustworthy Agent Design," arXiv:2508.03665 (2025). Shavit et al., "Practices for Governing Agentic AI Systems," OpenAI, 2023. Full bibliographic details are in the mission research report; the repository standard is to cite the named work inline, as above. diff --git a/promise-theory/references/patterns.md b/promise-theory/references/patterns.md new file mode 100644 index 0000000..0bcbbec --- /dev/null +++ b/promise-theory/references/patterns.md @@ -0,0 +1,162 @@ +# Patterns — Seven Canonical Coordination Patterns with Worked Examples + +**Load this file when you want to apply a named pattern** — promise manifest, acceptance handshake, agent contract (including the M12 "ladder from promise to contract" and the Ye & Tan formal lifecycle), evaluation loop, breach→renegotiation, redundancy & downstream responsibility, or trust calibration. Each pattern below states its promise-theory rationale, its concrete shape, a worked example you can adapt, and design guidance. The definitions and notation used here are in [foundations.md](foundations.md); the concept→practice mapping these patterns operationalize is in [agent-coordination.md](agent-coordination.md); trust calibration and verification budgets are developed in [trust-and-verification.md](trust-and-verification.md). + +**Provenance.** Patterns 1, 2, 4, and 5 restate mechanisms directly documented in the cited sources (Burgess's promise machinery, CFEngine's convergence loop, agile renegotiation practice). Patterns 3, 6, and 7 synthesize promise theory with agent-engineering sources (M12 2026; Ye & Tan 2026; Leoveanu-Condrei 2025; Burgess & Dunbar 2025) and are marked `EXTRAPOLATION` where the synthesis goes beyond the cited texts. Unverified vendor or secondary claims are marked `[UNVERIFIED]`. + +--- + +## 0. Pattern overview + +| # | Pattern | Promise-theory principle honored | Use when | +|---|---|---|---| +| 1 | Promise manifest | Autonomy + local knowledge: cooperation starts with published offers | You need agents (or humans) to declare what they can and will do, before anything is dispatched | +| 2 | Acceptance handshake | Only the overlap of offer and acceptance transmits influence; the receiver decides | Every delegation that matters: record accept/refuse explicitly | +| 3 | Agent contract | A promise has no binding force; the contract adds enforcement and non-bypassability | The promise is consequential or the promiser is stochastic (an LLM) | +| 4 | Evaluation loop | Trust is accumulated assessment; accumulation needs a place to accumulate | You need to know whether promises are actually being kept, continuously | +| 5 | Breach → renegotiation | Breach is an information event, not a moral event; blame is a useless imposition | A promise was broken; the system must recover and re-converge | +| 6 | Redundancy & downstream responsibility | The downstream party carries greatest causal responsibility; plan for non-keeping | A promise is load-bearing (its failure takes the system down) | +| 7 | Trust calibration schedule | Two-component trust: calibrate potential trust, budget kinetic mistrust | You onboard new agents or need to decide how much to verify | + +## 1. Pattern 1 — Promise manifest + +**Rationale.** Autonomy plus local knowledge imply that cooperation starts with each agent *publishing what it can and will do* — its acceptance set, in Burgess's notation (the promises `+bi` an agent can make and `−bi` it can accept; Bergstra & Burgess 2019). A receiver can only rely on offers it can see. + +**Shape.** A versioned, machine- and human-readable declaration per agent containing: capabilities (tools, skills, domains), constraints (what it will *not* do; resource limits), expectations (what it requires from others to keep its promises), and maintenance/withdrawal semantics (how promises are revoked — "I will stop handling X after date D"). Manifests exist in the wild as `AGENTS.md` (repository-scoped behaviour declarations), MCP tool descriptors and function schemas, worker-enrollment advertisements, and SLOs. + +**Worked example — a 3-agent research team with human oversight.** Three agents and one human acceptors/evaluators. + +- `research-agent` (literature summarizer): capabilities `lit-review` ("survey and summarize literature on X, limit 20 sources"), `evidence-tables` ("produce evidence tables with citations"). Constraint: "I will not fabricate citations; if I cannot verify a source I will mark it `[UNVERIFIED]`." Withdrawal: "I stop handling X when the coordinator withdraws direction." +- `reviewer`: capability `fact-check` ("verify claims against cited sources"), constraint "review only within my declared domain." +- `coordinator` (the human): commitment "provide research direction and review summaries by the agreed cadence." + +The manifest is versioned (`v1`, `v2`, …); each version is a reviewable artifact, not prose. When the human adds a new expected capability, the manifest is revised and re-published *before* work starts — never silently appended mid-task. This is the promise-theory *admission rule*: "nothing lets the orchestrator reach a machine that never advertised the capability" (webframp 2026). + +**Design guidance.** Declare less, promise more precisely; version manifests; make withdrawal explicit; treat the manifest as a contract surface for the acceptance handshake (pattern 2), not as documentation. + +## 2. Pattern 2 — Acceptance handshake + +**Rationale.** Only `b∩ = bi ∩ bj` transmits influence; the Downstream Principle says the receiver decides. A task that is never accepted is an imposition (Burgess, arXiv:2604.10505; Bergstra & Burgess 2019). + +**Shape.** Every delegation has an explicit accept/refuse decision, recorded: explicit task acceptance by the executing agent; approval gates by humans; refusal signals (an agent says "out of scope" instead of hallucinating compliance); capability-matching before dispatch. Burgess's historical implementation was the Voluntary RPC (vRPC) — pull-based interaction "in which each side could completely control the conditions under which it interacted with the other." + +**Worked example — guarded dispatch with refusal logging.** A coordinator proposes a task to `research-agent`: "Summarize these 20 papers by 17:00." The handshake has three recorded outcomes: + +1. **Accept** — `research-agent` replies with a concrete re-promise: "I will deliver a summary with an evidence table, 20 sources max, by 17:00, provided the PDFs are accessible." The coordinator accepts *that* (the overlap `b∩` is now the binding promise). +2. **Refuse** — "Out of scope: this requires access to a paywalled database I am not enrolled for." The refusal is logged, not punished; the coordinator re-delegates or adjusts the manifest. **Refusal is a coordination signal**: a rising refusal rate means manifest/task mismatch, not a failing agent. +3. **Silence** — the worst case, because it is an *imposition that looks accepted*. The system treats a delegation with no recorded acceptance as not delegated, and surfaces it. + +Human approval checkpoints (LangGraph breakpoints / HITL nodes) are the same pattern with a human acceptor: the agent proposes, the guard disposes, the human approves consequential steps (M12 2026). + +**Design guidance.** Make refusal cheap and non-punitive for both humans and agents; log accept/refuse; measure the refusal rate as a coordination signal; treat silence as refusal-by-default. + +## 3. Pattern 3 — Agent contract + +**Rationale.** A promise has no binding force by itself. "A contract is a promise *plus* a mechanism that makes deviation either impossible or costly" (M12, "From Promises to Contracts," 2026). Promise theory supplies the acceptance half; the contract supplies the enforcement half. This pattern matters most for LLM agents, whose promises are "statements about intended future behavior with no binding force" that can be overridden by later context (prompt injection is the clean proof). + +**Shape A — the M12 ladder from promise to contract.** The canonical spectrum of enforcement, from pure promise to hard guarantee: + +1. **Soft prompting (pure promise)** — system prompts, constitutions. Steering only; no guarantee. +2. **Self-checking / reflection** — the model critiques itself; it shares the failure modes of what it checks (same blind spots, same randomness). +3. **Output validation / constrained decoding** — JSON schema, grammar constraints, type-checked tool arguments: a genuine contract on the *form* of output. +4. **External validators / action guards** — a separate deterministic process checks every proposed action against policy *before* execution. +5. **Capability restriction / sandboxing** — "don't ask the agent not to do the thing; remove its ability to do it": read-only mounts, no egress, microVM isolation, least-privilege identity. Converts "I promise I won't" into "the model cannot." +6. **Formal methods / typed effects** — provably bounded behaviour spaces; highest assurance, narrowest applicability. + +The governing principle, stated at rung 5: **"confine, don't convince" — treat the model as an untrusted planner inside a sandbox of hard guarantees; "won't" becomes "can't."** + +**Shape B — the formal tuple and lifecycle (Ye & Tan 2026).** Ye & Tan's Agent Contract is a 7-tuple `C = (I, O, S, R, T, Φ, Ψ)`: input spec; output spec with minimum quality threshold `Qmin`; skill set; multi-dimensional resource bounds (tokens, API calls, iterations, cost); temporal bounds; weighted success criteria; and termination conditions. Lifecycle: + +``` +DRAFTED → ACTIVE → {FULFILLED, VIOLATED, EXPIRED, TERMINATED} +``` + +with guard conditions such as `ACTIVE → VIOLATED` when any resource bound `ci ≥ bi` is exceeded. **Conservation laws**: delegated sub-contracts cannot exceed the parent's budget, enabling hierarchical, composable coordination. Empirically claimed by the authors (self-reported): 90% token reduction with 525× lower variance in iterative workflows, and zero conservation violations in delegation tests. `[UNVERIFIED]` independently. + +**Shape C — degradation/exception semantics.** Because "guarantees are impossible, and it is the autonomous responsibility of the user to allow for that" (Burgess, arXiv:2604.10505), every contract names its exception behaviour *before* the breach: + +- **Termination conditions** (`Ψ`): resource exhaustion, duration expiry, explicit cancellation, unrecoverable error. Every contract reaches exactly one terminal state — unambiguous resource release and audit. +- **Degradation tiers** (from Leoveanu-Condrei's Design-by-Contract for LLMs, 2025): verified → best-effort → safe default. Fail-open when liveness matters; fail-closed when safety matters. Name the tier in the contract. The telling compromise: a contract violation *degrades gracefully* (returns best-effort) rather than halting — preserving liveness at the cost of the guarantee. +- **Budget-aware behaviour**: injecting remaining budget into prompts, control tokens, satisficing instead of maximizing (Simon, via Ye & Tan 2026). +- **Runaway protection**: stop conditions, loop detection, cost ceilings — the operational controls that the $47,000 eleven-day recursive-clarification incident showed are missing when contracts are absent (Ye & Tan 2026, citing a Nov 2025 trade article; `[UNVERIFIED]` at primary-source level). + +**Worked example — a coding agent with a workspace contract.** A coding agent is delegated "implement the retry logic in `src/retry.py`." The contract: + +- **I**: input spec (repo path, function signature); **O**: output spec (diff against `src/`, must pass `pytest` and the repo's lint, `Qmin` = tests green); **S**: skills (`python`, repo conventions); **R**: resource bounds (≤ 200k tokens, ≤ 20 tool calls, ≤ 1h); **T**: temporal bound (due 17:00); **Φ**: weighted success criteria (correctness 0.6, style 0.2, test coverage 0.2); **Ψ**: terminate on budget exhaustion, on timeout, or on explicit cancel. +- The enforcement ladder is applied top-down: soft prompt states the boundary ("edit only `src/`"); the agent self-checks; an output validator enforces the diff scope; an action guard rejects file writes outside `src/`; the agent runs with a read-only mount on everything except `src/` (rung 5 — "won't becomes can't"). +- **Degradation tier**: fail-closed. If `pytest` fails at the deadline, the contract enters VIOLATED, the partial diff is preserved, and the outcome is reported to the human acceptor rather than silently merged. +- **Lifecycle trace**: DRAFTED (contract written) → ACTIVE (accepted by the agent via the acceptance handshake) → FULFILLED (tests green, diff accepted) or VIOLATED (guard tripped / budget exhausted). **EXTRAPOLATION** — the full worked example is this skill's application of the cited formal machinery; the tuple, ladder, and lifecycle are from Ye & Tan (2026) and M12 (2026). + +**Design guidance.** Specify contracts at the operational level where you can enforce; use measured promises (P_succ) at the semantic level where you cannot; give every handoff its own guard ("a chain of agents is only as bound as its least-enforced boundary"); make enforcement live *outside* the model. + +## 4. Pattern 4 — Evaluation loop + +**Rationale.** The promise-theory control loop (observe, reason locally, commit) plus assessment is what makes promises meaningful; trust is "accumulated assessment," and accumulation needs a place to accumulate (webframp 2026). CFEngine's convergence loop is the archetype: a continuous, iteratively safe map to a fixed point, not a one-shot push (see [applications-infrastructure.md](applications-infrastructure.md)). + +**Shape.** Every agent relationship has an explicit evaluation loop: (1) define the accepted outcome (fixed point / acceptance criteria); (2) observe reality (agent observability: tool calls, reasoning, state, memory); (3) assess (evals, checks, human review); (4) act (repair, escalate, renegotiate, or record breach). + +**Worked example — observation-first, with idempotency in the guard.** A configuration-coordination workflow observes live state rather than trusting last-write state: `discover_all` against live APIs → store versioned, schema-validated observations → diff reality-at-T vs. reality-at-T−1 → decide whether to act in a workflow → act only when warranted. Idempotency moves up from per-resource code to a workflow *guard* — a predicate ("has this already been done?") evaluated by the judgment layer, not re-implemented by every resource (webframp 2026). The promise-theory reading of why: a state file records "the one piece of evidence an agent assessing its own promise-keeping cannot use" — the agent's own last write — and push-based controllers "impose obligations and the target makes no promise." + +**Assessments stored as versioned data.** The loop's output — each assessment ("promise `lit-review` KEPT on 2026-08-11 by human review", "promise `fact-check` BREACHED on 2026-08-12 by guard trip") — is written to a **promise ledger**: an append-only, queryable record of promises made (manifest versions), acceptances, assessments, breaches, renegotiations, and trust deltas, per agent and per relationship. The ledger is the coordination-layer counterpart of a trace store: traces capture *what happened*; the ledger captures *what was promised vs. what was kept*. CFEngine's documented gap is the warning: promise-keeping was never stored as data, so the evaluation loop was incomplete. **EXTRAPOLATION** — "promise ledger as a named artifact" is this skill's synthesis; the components (versioned assessments, trace stores, audit logs) are documented in the sources. + +**Design guidance.** Make observation the primary operation, not an opt-in refresh; store assessments as versioned data with provenance; separate observation from action; treat idempotency as a decision, not a module-level implementation detail. + +## 5. Pattern 5 — Breach → renegotiation, not blame + +**Rationale.** "An autonomous agent cannot impose blame" (Burgess, arXiv:2604.10505 §VI-F); blaming an upstream provider "is a useless imposition and a waste of trust/energy." Breach is an information event that triggers reassessment — the retrospective, not the punishment. + +**Shape.** On detected breach: (1) record it (trace → eval case; promise ledger entry); (2) assess the cause against the failure taxonomy (specification error vs. inter-agent conflict vs. verification gap — the three classes of Cemri et al. 2025); (3) renegotiate: update the prompt/contract/manifest, change acceptance criteria, add verification, or replace the provider; (4) adjust the trust estimate (down-rank P_succ; increase the verification rate); (5) apply redundancy if the dependency is load-bearing. Escalate only when renegotiation fails to converge. + +**Named escalation trigger.** In this skill's contracts the escalation condition is named and written into the contract before any breach: **`ESCALATE-2`** — escalate to the human supervisor (or the next acceptance authority) when renegotiation fails to converge after two full renegotiation cycles, where a cycle is one breach → one contract revision → one verification window. After two non-converging cycles, further renegotiation is unbounded kinetic mistrust spent on a non-learning system; the evidence is reported instead. This follows the bounded-escalation completion discipline this skill applies to all diagnosis work. + +**Worked example — the boundary-violating coding agent.** A coding agent repeatedly violates "touch nothing outside /workspace." Breach detected by the action guard (rung 4 of the ladder). Renegotiation options in order of increasing force: + +1. **Clarify the contract** (soft): rewrite the boundary clause in the receiver's language. +2. **Add an output validator** (structural): reject diffs touching paths outside /workspace. +3. **Add an action guard** (external): deterministic pre-execution policy check. +4. **Move to a sandbox** (capability restriction): read-only mount on everything else — "won't" becomes "can't." +5. **Replace the agent** (redundancy): swap in an alternate provider. + +Each is a renegotiation of the promise set, not a scolding. The breach is recorded in the ledger with its cause class (here: specification — the original boundary was stated in the system prompt but never enforced structurally). If the renegotiated contract (guard added) still breaches in the next verification window, and a second renegotiation cycle (sandbox) fails to converge, `ESCALATE-2` fires: the case goes to the human supervisor with the evidence trail, and the human decides sandbox hardening vs. provider replacement vs. task redesign. + +**Design guidance.** Run retrospectives like agile teams do — a retro *is* renegotiation of the team's promise set; make the renegotiation trail visible; escalate only when renegotiation fails to converge; write the escalation trigger into the contract *before* the breach. + +## 6. Pattern 6 — Redundancy & downstream responsibility + +**Rationale.** Downstream Principle: "If a provider fails to keep a promise, the downstream agent only has its own policy to blame... It could or should have sourced more than one provider, planned for the promise not being kept, and sought out redundancy from multiple sources" (Burgess, arXiv:2604.10505). Composition of promises follows fault-dependency algebra: **parallel redundant sources give a dependent promise resilience; independent unique serial inputs make an aggregating promise fragile.** + +**Shape.** For every load-bearing promise: multiple potential providers (alternate agents, alternate models, a human fallback), failover on breach, and an explicit plan for non-keeping. Redundant parallel sources make the system resilient; a promise that depends on a unique serial chain of inputs is a single point of failure. + +**Worked example — the single-answer research pipeline.** A research pipeline must produce one answer. Fragile design: one agent run, one model, one shot. Resilient design: run two independent models on the same question, or one model plus a human reviewer, and require agreement before the answer is accepted (ensemble assessment). If the answer is load-bearing for a downstream decision, the consumer also keeps a human fallback ("if neither run converges by 16:00, the human produces the answer"). The classic LLM-engineering "verify with a second opinion / LLM-as-judge with checks" pattern is a redundancy pattern for *assessments*, not just for answers. + +**Design guidance.** Identify load-bearing promises (failure takes the system down); give each at least one alternate provider; make failover a tested path, not a theory; treat unique serial inputs (a single upstream agent whose output feeds everything) as fragility to be broken up. + +## 7. Pattern 7 — Trust calibration schedule + +**Rationale.** Trust has two components — potential trustworthiness (accumulated assessment) and kinetic mistrust (the rate of checking). Verification is a sampling/energy problem: for inexpensive sampling, the checking rate can scale as a square root of trust, and agents budget verification against risk (Burgess & Dunbar 2025). "Mistrust is the prerequisite for learning" — you cannot learn reliability without checking. + +**Shape.** Per-relationship verification schedule: new agents start at **50-50** (Burgess's default for agents that can't be assessed in advance: "often have no option but to start with a 50-50 guess about trustworthiness, which might be upgraded or downgraded later" — arXiv:2604.10505); high measured P_succ → cheap sampling; low P_succ or high risk → continuous monitoring + human review. Verification costs (tokens, human attention) are budgeted like any resource. + +**Worked example — onboarding a new summarizer.** A new `research-agent` joins the team with no track record. Day 1: start at 50-50; verify every output — full human review of the first 10 deliverables (kinetic mistrust high, because risk is high: fabricated citations are costly). As the ledger accumulates 50 verified outputs with P_succ rising to 0.95, the schedule relaxes: sample 1-in-10 outputs with a rule-based citation check plus spot human review; escalate back to full review if a breach is detected (the trust estimate drops and the verification rate rises — the two move in opposite directions). The verification budget itself is declared: "≤ 2 human review hours/day on this agent, ≤ 5% of total token budget on evaluation." **EXTRAPOLATION** — the concrete schedule is this skill's synthesis of Burgess's 50-50 default, the square-root sampling model, and the Dunbar budget warning that machine fleets need explicit verification budgets because datacenter-hosted agents have "effectively limitless" surveillance capacity (arXiv:2604.10505). + +**Design guidance.** Make the verification rate an explicit, adjustable parameter; tie it to risk appetite; measure the cost of assessment itself; state the starting trust level with its justification — a justified deviation from 50-50 (a stated prior with reasoning) is acceptable, an unstated one is not. + +## 8. Choosing patterns and routing + +- **Start with a promise manifest** (pattern 1) whenever you add agents to a workforce — it makes everything else possible. +- **Handshake before you delegate** (pattern 2): acceptance is the boundary between coordination and imposition. +- **Contract the consequential** (pattern 3): enforce what you can, measure what you cannot (see [trust-and-verification.md](trust-and-verification.md)). +- **Evaluate on a cadence** (pattern 4): the loop is what makes promises real. +- **Plan breach as a recovery path** (pattern 5) and **redundancy for what must survive** (pattern 6). +- **Calibrate trust deliberately** (pattern 7): the schedule is the operational face of the two-component model. +- **Designing a whole workflow as a chain of promises?** Route to [workflow-architect](../bundles/workflow-architect/SKILL.md) — its guided workflow discovery and synthesis turn a sequence of phases, branching signals, and handoffs into a structured bundle; promise theory supplies the semantics of each handoff (offer → acceptance → assessment), workflow-architect supplies the workflow-building machinery. **EXTRAPOLATION** — the semantic mapping between the two skills is this skill's synthesis; both the promise model and the workflow-architect process are documented in their own sources. + +Also relevant: [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) for the assessment layer that pattern 4's loop calls on, and [artifact-pyramids](../artifact-pyramids/SKILL.md) for structuring the evidence the ledger accumulates. + +## 9. Sources + +**Promise theory.** Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., χtAxis Press, 2019. Burgess, "Cooperation in Human and Machine Agents: Promise Theory Considerations," arXiv:2604.10505 (2026). Burgess, "Notes on Trust as a Causal Basis for Social Science," SSRN 4252501 (2022). Burgess & Dunbar, "A quantitative model of trust...", *European Economic Review* (2025). Burgess, *In Search of Certainty*, O'Reilly, 2015. + +**Agent contracts and enforcement.** Ye & Tan, "Agent Contracts: A Formal Framework for Resource-Bounded Autonomous AI Systems," arXiv:2601.08815 (2026). Leoveanu-Condrei, "A DbC Inspired Neurosymbolic Layer for Trustworthy Agent Design," arXiv:2508.03665 (2025). M12/Todd Graham, "From Promises to Contracts: Enforceable Behavior in LLM Agents" (2026). Cemri, Pan, Yang, et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025, arXiv:2503.13657. + +**Practice.** webframp, "The Promise None of Them Kept" (2026). Zhu, Liu, Yu & Zhang, "LLM-Based Multi-Agent Orchestration: A Survey," *Future Internet* 18(6), 2026. Braintrust, "Agent observability: The complete guide for 2026." Full bibliographic details are in the mission research report; the repository standard is to cite the named work inline, as above. diff --git a/promise-theory/references/trust-and-verification.md b/promise-theory/references/trust-and-verification.md new file mode 100644 index 0000000..44c3d19 --- /dev/null +++ b/promise-theory/references/trust-and-verification.md @@ -0,0 +1,107 @@ +# Trust and Verification — The Two-Component Model in Practice + +**Load this file when you need to decide how much to verify an agent, set a starting trust level, budget verification cost, or wire assessment into evals and observability.** This file develops the skill's trust model — two-component trust (potential trustworthiness + kinetic mistrust), belief/evidence, the measured promise P_succ, verification rates as an attention budget (including Dunbar budgets), gameable assessment, and measurement guidance for semantic promises — and connects it to the assessment layer. The formal definitions (assessment α, belief β, evidence ε, trust as discounting δ) are in [foundations.md](foundations.md); the trust calibration schedule as a named pattern is in [patterns.md](patterns.md); the concept mapping that motivates all of this is in [agent-coordination.md](agent-coordination.md). + +**Provenance.** The two-component model, the 50-50 default, and the Dunbar-budget discussion are Burgess's (arXiv:2604.10505, 2026; SSRN 4252501, 2022; Burgess & Dunbar 2025). The measured promise P_succ and bounded remediation are Leoveanu-Condrei's Design-by-Contract for LLMs (arXiv:2508.03665, 2025). The connection of all of this to agent evals and observability practice is this skill's synthesis and is labeled `EXTRAPOLATION` where it goes beyond the cited texts. Claims resting on vendor or secondary accounts are marked `[UNVERIFIED]`. + +--- + +## 1. The two-component trust model + +Burgess's model separates trust into two components that move independently and are almost always conflated: + +1. **Potential trustworthiness** — the receiver's *accumulated estimate* that the promiser will keep its word: `V_S = α_R(π_S)` — the assessment value α that receiver R has built up about promiser S from the promise record π (Burgess, SSRN 4252501; arXiv:2604.10505). This is a *stock*: it changes slowly, with evidence. +2. **Kinetic mistrust** — the *rate* at which the receiver checks on the promiser: how often you run evals, ping health checks, re-audit outputs, or re-review work. This is a *flow*: attention and energy spent in the present. + +The two are not opposites. **High potential trust + low kinetic mistrust** = a well-calibrated relationship. **Low potential trust + low kinetic mistrust** = recklessness ("if you trust something too much, you're not paying attention" — Burgess). The industry phrase "zero trust" correctly refers to the *second* component — pay attention continuously — not to eliminating reliance, which would be impossible: "you have to trust technology if it's going to take over the job of mistrusting or monitoring something else. So you don't escape trust. It's trust all the way down" (NLnet/NGI interview, 2024). Every delegating layer — human to orchestrator, orchestrator to agent, agent to tool — must itself be assessed. + +Burgess & Dunbar (2025) model kinetic mistrust as an *energy/attention budget*: human groups are bounded by cognitive trust budgets (Dunbar-scale limits on how many relationships any individual can meaningfully maintain and verify). For machine societies the budget is inverted — "there is no upper limit on the amount of energy an artificial autonomous system may choose to invest in surveillance of its neighbours" (arXiv:2604.10505) — which is precisely why agent fleets need *explicit* verification budgets: the constraint is no longer natural, so it must be imposed by governance. **EXTRAPOLATION** — the design rule "budget verification explicitly because machine surveillance is effectively limitless" is this skill's synthesis; the limitless-capacity observation and the Dunbar model are Burgess & Dunbar's. + +## 2. Belief and evidence + +Promise theory's epistemic vocabulary: an agent holds **belief β** about whether a promise will be kept, based on **evidence ε** gathered through **assessment α** — where assessment is *relativistic*: it is always from a particular receiver's vantage point, never a global verdict (Bergstra & Burgess 2019). Three consequences for agent coordination: + +- **Assessment is local to the receiver.** A controller's aggregate metric is not the receiver's assessment. This is why "the service returned 200" can wrap a confidently wrong answer, and why an agent that loops can look healthy from the controller's vantage point: the receiver's signal is what matters, and a source is "only as good as its signal can be heard downstream" (Burgess). +- **Trust is not transitive.** Because belief is receiver-local, you cannot inherit trust through a chain: every delegating layer must be assessed on its own evidence. "Trust all the way down." +- **Belief updates on evidence, not on confidence.** An agent's self-prediction is a poor predictor of its own future outputs (there is no causal mechanism connecting the acknowledgment to the compliance — M12 2026). Calibrate belief from *observed outcomes*, never from the promiser's fluency. + +## 3. The measured promise: P_succ + +A **measured promise** is a commitment whose satisfaction is *estimated* rather than assumed — the bridge between an ungoverned natural-language promise and a hard guarantee. Leoveanu-Condrei's Design-by-Contract for LLMs (arXiv:2508.03665, 2025) lifts the Hoare triple `{P}C{Q}` into the probabilistic domain: pre/post-condition predicates on typed inputs and outputs, a bounded remediation loop (a validation error becomes a corrective prompt; failure history accumulates in context to prevent re-looping), and a **measured success probability P_succ** estimated over repeated runs. + +P_succ is the operational face of potential trust: it is what makes two agents that satisfy the same contract interchangeable except for their P_succ and cost. Practical implications: + +- **Estimate it empirically, per contract.** One run proves nothing for a stochastic promiser; P_succ is a statistic over a recorded sample of assessed outcomes. +- **Update it from the ledger.** Each kept or breached promise (see Section 8) is an evidence point; the estimate moves with the record, not with the model's self-report. +- **Use it where you cannot enforce.** At the semantic level ("the summary is accurate") you cannot build a hard guarantee; P_succ is the honest substitute. At the operational level, enforce instead (Section 7). +- **Bound the remediation loop.** The Design-by-Contract remediation is *bounded* — failure history accumulates to prevent re-looping, and contract violation *degrades gracefully* (fail-open to best-effort) rather than halting, preserving liveness at the cost of the guarantee. + +**EXTRAPOLATION** — "P_succ as the tradable unit of potential trust, and the ledger as its evidence base" is this skill's synthesis of Leoveanu-Condrei's measured promise with Burgess's `V_S = α_R(π_S)`; each half is documented in its own source. + +## 4. Verification rates as an attention budget + +The rate at which you check is kinetic mistrust, and it is spent attention. Burgess models verification as a sampling/energy problem: for inexpensive sampling verification, the checking rate can scale as the square root of trust — the more trust has accumulated, the cheaper the sampling can be (Burgess & Dunbar 2025). Calibration guidance: + +- **Start unknown agents at 50-50.** Agents "often have no option but to start with a 50-50 guess about trustworthiness, which might be upgraded or downgraded later" (arXiv:2604.10505). A justified deviation (a stated prior with reasoning) is acceptable; an unstated one is not. +- **Verify proportional to risk, inversely to measured trust.** High P_succ + low stakes → cheap sampling; low P_succ or high stakes → continuous monitoring and human review. When a breach drops the estimate, the verification rate rises — the two components move in opposite directions. +- **Budget the verification cost explicitly.** For machine fleets the natural bound is absent (Section 1), so the budget is a governance artifact: tokens spent on evaluation, human review hours, eval runs per release. Without a declared budget, verification expands without limit or collapses without notice — and humans, whose attention is Dunbar-bounded, get alert fatigue and start rubber-stamping. +- **Respect the human budget.** Wikipedia edit wars taught Burgess that conflict consumes attention; Dunbar-scale trust budgets bound human tolerance (NLnet interview, 2024). Agent fleets must not impose unbounded human monitoring loads. + +**"Mistrust is the prerequisite for learning."** You cannot learn whether a promise is being kept without checking; every verified outcome is the evidence that updates belief. A system that stops checking — out of complacency ("high trust, why bother") or exhaustion — stops learning, and its trust estimate silently decays into an assumption. + +## 5. Trust calibration in practice + +The trust calibration schedule (pattern 7 of [patterns.md](patterns.md)) operationalizes this: onboarding an agent starts at 50-50 with full verification; the verification rate relaxes as the ledger accumulates assessed outcomes and P_succ rises; any breach drops the estimate and raises the rate. The schedule is itself a promise: "I will verify X at rate Y" is the supervisor's promise to the organization, and the organization accepts it. Trust decisions should be *written down as data* — the starting level, the evidence, the adjustment — never left as an unstated vibe. The three most common calibration errors are: starting from trust instead of 50-50; letting the verification rate track the *promiser's* confidence instead of the *assessed* record; and failing to price the assessment itself (Section 6). + +## 6. Gameable assessment — the principal exploit area + +Burgess's warning is blunt: "the manipulation of assessments remains the chief area for gaming and manipulating agents" (arXiv:2604.10505). Assessment is the load-bearing concept of the whole theory — "the principal area for exploiting and misdirecting agents" — which makes it the principal attack surface. Concrete failure modes, all documented in the agent-engineering record: + +- **LLM-as-judge can be fooled** — rating indeterminacy research shows evaluator models are susceptible to phrasing, ordering, and sycophancy effects; the judge is itself an assessor that can be gamed. +- **Goodhart dynamics** — agents optimize for the eval score rather than the underlying promise; if the eval is the acceptance criterion, the eval becomes the target. +- **Eval contamination and staleness** — benchmark figures go stale quickly and can be memorized; vendor-reported adoption numbers dominate (independent replications are essentially absent, `[UNVERIFIED]` by nature of the gap). +- **Assessment capture** — an agent that controls the evidence stream (its own traces, its own self-reports) controls the record its P_succ is computed from. This is why assessments must be stored as versioned data by an independent mechanism (Section 8), and why guardrails must be *outside* the model (the "confine, don't convince" principle, Section 7). + +**Design guidance.** Treat every assessment mechanism as a target: use diverse, independent verifiers (deterministic checks + human review + a judge model, cross-checked); keep the eval cases out of the training distribution where possible; monitor the assessment mechanism itself for drift; and harden trust metrics adversarially. **EXTRAPOLATION** — the "assessment as attack surface" framing is this skill's synthesis; the underlying observation is Burgess's, and the failure modes are documented in the cited agent-engineering sources. + +## 7. Measurement guidance for semantic promises + +Promise theory's honest limit: **semantic promises can only be measured, not enforced.** "You can only enforce what you can specify" (M12 2026). Two promise classes: + +- **Operational class** (format, scope, sandbox, network): enforceable. A diff scope can be rejected; a file system can be read-only; a network egress can be blocked. "The intersection of explicit framing + hard guarantee on semantic commitments is empty" — semantic commitments are *not* enforceable by framing alone. +- **Semantic class** (accuracy, non-harm, intent alignment): measurable, not enforceable. "The summary is accurate" cannot yet be cheaply enforced; it can only be assessed — by checks, by judges, by human review. + +The governing principle that turns measurement into control is **"confine, don't convince"**: don't ask the model not to do the thing; remove its ability to do it. "Won't" becomes "can't." This is the difference between a *promise* (a declaration of intent, always breakable) and a *constraint* (a structural fact of the environment, not breakable by intent). The measurement guidance in one line: **enforce the operational, measure the semantic, and never mistake a measurement for an enforcement** — a P_succ of 0.97 on semantic promises is an honest estimate, not a guarantee, and the downstream design (redundancy, renegotiation, escalation) must assume the 3% happens. + +## 8. Assessments stored as versioned data — the promise ledger + +Trust is accumulated assessment, and **accumulation needs somewhere to accumulate** (webframp 2026). CFEngine's documented gap is the negative example: promise-keeping was never stored as data in the reference implementation, so the evaluation loop was incomplete (see [applications-infrastructure.md](applications-infrastructure.md)). The fix is a **promise ledger**: an append-only, versioned, queryable record of promises made (manifest versions), acceptances, assessments (eval scores, review outcomes, who assessed and when, against what observation), breaches, renegotiations, and trust deltas — per agent and per relationship. + +Ledger hygiene rules: + +- **Versioned, not overwritten.** An assessment is an evidence point; rewriting it destroys the record that belief updates depend on. Assessments are data with provenance (who assessed, when, against what criterion). +- **Append-only and independently writable.** The mechanism that writes assessments must not be the agent being assessed — otherwise assessment capture (Section 6) is structural. +- **Legible as evidence.** Each entry supports a later question: "was promise X kept, and how do we know?" This is what makes causal responsibility auditable (Section 3.3 of [agent-coordination.md](agent-coordination.md)): the audit trail is the promise ledger. + +**Structuring the evidence.** When the ledger accumulates, organize its contents as multi-layer research artifacts: [artifact-pyramids](../artifact-pyramids/SKILL.md) provides the canonical structure for promise-keeping evidence as **summaries → analysis → evidence dossiers** — the summary layer for decisions, the analysis layer for interpretation, the evidence layer for the raw assessed records. Route evidence-heavy coordination work there when the record grows beyond a single relationship. **EXTRAPOLATION** — the ledger structure is this skill's synthesis of the accumulation principle (webframp) with the promise-keeping-as-data lesson (CFEngine); the artifact-pyramid structure is that skill's own methodology. + +## 9. Wiring assessment into evals and observability + +Promise theory's core operational claim — **assessment is what makes coordination possible, and its cost and rate are first-order design variables** — is exactly what the agent-engineering industry has built as the assessment layer. The wiring: + +- **An eval is a formalized acceptance promise**: a stated criterion by which a receiver will decide a promise is kept. Offline evals (benchmarks, golden sets) assess against a fixed corpus; online evals score production traces. Production failures convert into eval cases; CI gates block merges that degrade quality — institutionalized assessment: no acceptance without evaluation. +- **Observability is the assessment record.** Agent traces (tool calls, reasoning, state transitions, memory operations — the four trace pillars) are precisely the record a downstream observer needs to decide whether a promise was kept. Multi-agent handoffs get logged at every boundary, the same way you would log an RPC between two services. +- **Guardrails are automated acceptance.** An action guard is an imposition (an agent action) landing only against a matching acceptance (policy allows it); sandboxing makes breach impossible ("won't" → "can't", Section 7). +- **The trace-to-eval loop is trust accumulation in production**: every assessed outcome updates the empirical reliability record — the ledger (Section 8) is the memory, the eval loop is the learning rate. + +**Routing statement:** for designing, running, and reviewing the assessment layer itself — evals, datasets, graders, trajectory review, regression analysis, release gates, production traces — route to **[agent-evals-and-observability](../agent-evals-and-observability/SKILL.md)**: promise theory supplies *what* to assess (whether a promise was kept, at what rate, at what cost); that skill supplies *how* — task and trajectory contracts, dataset and grader design, statistical comparison of runs, incident-to-case learning. **EXTRAPOLATION** — the identity "traces = assessment records; evals = formalized acceptance criteria; guardrails = automated acceptance" is this skill's synthesis; each half is documented in its own source line (Burgess's assessment machinery; the observability/evals literature cited below). + +## 10. Sources + +**Trust model.** Burgess, "Notes on Trust as a Causal Basis for Social Science," SSRN 4252501 (2022). Burgess & Dunbar, "A quantitative model of trust as a predictor of social group sizes and its implications for technology," *European Economic Review* (2025). Burgess, "Cooperation in Human and Machine Agents: Promise Theory Considerations," arXiv:2604.10505 (2026). NLnet/NGI Assure interview with Burgess, "Promise Theory," 2024. + +**Formal model.** Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., χtAxis Press, 2019. + +**Measured promises and enforcement.** Leoveanu-Condrei, "A DbC Inspired Neurosymbolic Layer for Trustworthy Agent Design," arXiv:2508.03665 (2025). M12/Todd Graham, "From Promises to Contracts: Enforceable Behavior in LLM Agents" (2026). Ye & Tan, "Agent Contracts: A Formal Framework for Resource-Bounded Autonomous AI Systems," arXiv:2601.08815 (2026). + +**Assessment practice.** Braintrust, "Agent observability: The complete guide for 2026." Langfuse, "AI Agent Observability, Tracing & Evaluation" (2024–2026). Confident AI, "Top 8 AI Agent Observability Platforms for 2026." Zhu, Liu, Yu & Zhang, "LLM-Based Multi-Agent Orchestration: A Survey," *Future Internet* 18(6), 2026. Cemri et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025, arXiv:2503.13657. webframp, "The Promise None of Them Kept" (2026). Full bibliographic details are in the mission research report; the repository standard is to cite the named work inline, as above. From e856ddb52f68a7d81b0bbe12700abbe2600840ee Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:19:09 -0400 Subject: [PATCH 4/9] =?UTF-8?q?feat(skill):=20promise-theory=20references?= =?UTF-8?q?=20=E2=80=94=20diagnosis=20&=20debugging=20+=20glossary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete the seven-reference set for promise-theory. diagnosis-and-debugging.md maps the Cemri et al. multi-agent failure taxonomy onto promise-theory breach categories (specification issues ↔ broken promise bodies; inter-agent conflicts ↔ failed acceptance/incompatible co-languages; task verification problems ↔ missing assessment), adds withdrawal failure as a fourth promise-theoretic class, documents a four-step diagnostic procedure (walk the promise graph → check bindings → check evaluation loop → check withdrawal semantics) with a worked example, and states the theory's limitations and open problems (no coordination-quality benchmark, guarantees don't compose across handoffs, LLM promises lack causal teeth, stochasticity, ambiguity. glossary.md defines all 27 architecture §4.2 terms as heading-/bold-led entries with citations plus a related-terms section. Both files stay under 60k chars, resolve all backtick *.md references and markdown links, and carry consistent EXTRAPOLATION / [UNVERIFIED] provenance markers. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> EOF ) --- .../references/diagnosis-and-debugging.md | 186 ++++++++++++++++++ promise-theory/references/glossary.md | 128 ++++++++++++ 2 files changed, 314 insertions(+) create mode 100644 promise-theory/references/diagnosis-and-debugging.md create mode 100644 promise-theory/references/glossary.md diff --git a/promise-theory/references/diagnosis-and-debugging.md b/promise-theory/references/diagnosis-and-debugging.md new file mode 100644 index 0000000..f719c98 --- /dev/null +++ b/promise-theory/references/diagnosis-and-debugging.md @@ -0,0 +1,186 @@ +# Diagnosis and Debugging — Failure Taxonomy, Diagnostic Procedure, and Limits + +**Load this file when you are diagnosing a coordination failure** — a multi-agent task that produced the wrong outcome, an agent that acknowledged a constraint and then violated it, a handoff that lost context, or a review loop that never caught a breach — or when you need to know where promise theory itself stops helping. The file gives you (1) the failure taxonomy mapped onto promise-theory breach categories, (2) a stepwise diagnostic procedure you can run against a specific incident, and (3) the theory's limitations and open problems. Definitions of every term used here are in [glossary.md](glossary.md); the concept→practice mapping that motivates the categories is in [agent-coordination.md](agent-coordination.md); the recovery patterns (breach→renegotiation, redundancy, trust calibration) are developed in [patterns.md](patterns.md) and [trust-and-verification.md](trust-and-verification.md). + +**Provenance.** The failure taxonomy is Cemri, Pan, Yang, et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025, arXiv:2503.13657 (fourteen failure modes in three classes). The mapping of those classes to promise-theory breach categories, and the four-step diagnostic procedure in Section 2, are this skill's synthesis and are labeled `EXTRAPOLATION`. The limitations section restates documented positions from the cited sources (M12, "From Promises to Contracts," 2026; Zhu et al. 2026; Ye & Tan 2026; Burgess, arXiv:2604.10505, 2026). Claims that could not be verified against a primary source are marked `[UNVERIFIED]`. + +--- + +## 1. The failure taxonomy in promise vocabulary + +### 1.1 Where the taxonomy comes from + +The empirical record on LLM multi-agent systems is blunt: one agent's incorrect reasoning cascades through the system, coordination overhead grows with agent count, and local optimization conflicts with global goals (Pan et al. 2025; Renney et al. 2026, arXiv:2601.03328). Cemri et al. (NeurIPS 2025) distilled this into a catalog of **fourteen failure modes in three classes**: + +- **Specification issues** — the task or prompt is wrong, ambiguous, or overly constrained; the agents were set up to fail before any execution. +- **Inter-agent conflicts** — agents disagree, argue, or produce incompatible outputs; the system spends its effort on unproductive contention. +- **Task verification problems** — the system cannot tell whether it succeeded; success and failure are indistinguishable from the observer's vantage point. + +The value of the taxonomy for this skill is that it turns "something went wrong" into instrumentable categories — and each category has a precise counterpart in the promise model (Section 1.2). That mapping is what makes a diagnosis *promise-theory-grounded* rather than a vague "agents misbehaved" story. + +### 1.2 The fixed mapping — failure class ↔ promise-theory breach category + +| Failure class (Cemri et al. 2025) | Promise-theory breach category | What it means in the model | +|---|---|---| +| **Specification issues** — task ill-posed, ambiguous, overly constrained | **Broken promise bodies** — the promise was never precisely stateable; the co-language was inadequate | The body b of the promise (label Λ, type τ, constraint χ) was empty, contradictory, or written in a language the receiver could not check. "Agents should expect to misunderstand one another's intentions to some level" (Burgess, arXiv:2604.10505). | +| **Inter-agent conflicts** — disagreement loops, incompatible outputs, unproductive arguing | **Failed acceptance / incompatible co-languages** — acceptance was never achieved; internal languages did not overlap | A delegation requires an offer (+b) and a matching acceptance (−b); their overlap b∩ is the only influence that transmits. When two agents' outputs conflict, the acceptance handshake between them never closed — each side kept a different promise. | +| **Task verification problems** — the system cannot tell success from failure | **Missing assessment** — no receiver-side evaluation loop | Trust is accumulated assessment; a system that cannot assess cannot accumulate trust. The most promise-theoretically damning class: the failure is not that a promise was broken but that *no one was watching* whether it was kept. | + +**EXTRAPOLATION** — the mapping table is this skill's synthesis: the three classes and fourteen modes are Cemri et al.'s, and the promise machinery (body, acceptance, assessment) is Burgess/Bergstra's; the identity between them is the skill's reading, not a claim made in either source. + +### 1.3 A fourth, distinctly promise-theoretic category: withdrawal failure + +Cemri's taxonomy is snapshot-shaped: it classifies what happened *during* the task. Promise theory adds a temporal dimension — a promise can be withdrawn at any time, and a withdrawal that is not declared within scope is itself a failure mode (the shadow side of deception: a non-documented change of intention). Concrete forms: + +- an agent **silently drops a task** mid-flight and starts something else; +- a capability is **revoked without notice** while downstream agents still rely on it; +- a promise **expires** (its `expires` bound passes, the agent contract enters EXPIRED or TERMINATED) and nobody renegotiates; +- a manifest is **revised and re-published** while old acceptances are still being honored. + +The classic CFEngine-era lesson is that intentions drift as promises are forgotten, changed, or deprecated; if some agents change while others do not, reliance fails (promise drift, per the Promise Theory FAQ). **EXTRAPOLATION** — classifying withdrawal failure as a fourth coordination-failure category is this skill's reading; the withdrawal/revocability machinery and the drift warning are Burgess/Bergstra's. + +### 1.4 Symptom → category triage + +When you have a symptom but not yet a category, start here. Each row names the likely category and the first place to look. + +| Symptom | Likely category | First place to look | +|---|---|---| +| Agent produced a plausible but wrong deliverable | Specification (broken body) **or** Verification (missing assessment) | The task text vs. the deliverable; whether any independent check ran | +| Agents argued, looped, or produced incompatible outputs | Inter-agent conflict (failed acceptance) | Handoff records; each agent's recorded acceptance of the other's output | +| The system reported success but the outcome was wrong | Verification (missing assessment) | The assessment loop: what "success" was measured against, and by whom | +| A task silently vanished or stopped | Withdrawal failure | The withdrawal/expiry log; the manifest versions | +| Agent acknowledged a constraint, then violated it | Specification + enforcement gap | The contract ladder: where the boundary lived, and whether it was enforced outside the model | +| Two outputs conflict but no one noticed | Verification (missing assessment) + failed acceptance | Whether any receiver-side check compares outputs | + +## 2. The diagnostic procedure + +**EXTRAPOLATION** — this four-step procedure is this skill's synthesis: it applies the promise machinery (graph, bindings, evaluation loop, withdrawal) as a debugging discipline. The procedure is a disciplined walk over the coordination state; do the steps in order. Each step either locates the failure or rules out a whole category. Apply the completion discipline from `SKILL.md`'s Exit Conditions: **stop after three non-converging passes and report the evidence** rather than re-litigating the same promises. + +### Step 1 — Walk the promise graph + +**Goal.** Reconstruct who promised what to whom, and find structural impossibilities before looking at execution. + +1. **Inventory the actors** — every human, agent, API, and deterministic process that touched the outcome. Decide which are agents (they can promise) and which are acceptors/evaluators (they can only accept and assess). +2. **Rebuild the promise set** — from the manifest, the contracts, and the prompts: for each delegation, what body was promised (capability or intent), to whom, with what constraint and withdrawal clause? +3. **Check every edge** — is each delegation backed by a declared promise? The *admission rule*: nothing should reach an agent that never advertised the capability (webframp 2026). An edge with no declared promise is an imposition masquerading as delegation. +4. **Look for structural contradictions** — two promises of the same type with incompatible constraints; an empty promise (acceptance criteria unstated); over-promising (a valence exceeded, one agent bound beyond its capacity). +5. **Trace the chains** — for each handoff (research → review → write, orchestrator → worker, agent → tool), is there a record of what was passed and in what form? + +**What a finding means.** An edge with no declared promise → the failure started at design time, not execution (imposition). A broken or contradictory body → specification class. A chain whose handoffs have no records → you cannot yet distinguish inter-agent conflict from verification failure; proceed to Step 2 with the handoff records as your target. + +### Step 2 — Check bindings (acceptance) + +**Goal.** Verify that every delegation was actually accepted, and that the offer/acceptance overlap existed. + +1. **Record check** — for each delegation, is there a logged accept or refuse? Silence is the worst case: an *imposition that looks accepted* (the LLM-era signature: fluent acknowledgment without enrollment). +2. **Overlap check** — did the acceptor's counter-promise overlap the offer (b∩)? The executor may have accepted a *different* task than the requester offered — the classic co-language failure. +3. **Cross-agent check** — do the recorded acceptances reference promises declared by *other* agents (no self-acceptance, no dangling accepts)? In the skill's manifest schema these are the `agents.accepts` bindings. +4. **Refusal signal** — was any refusal recorded? Refusal is a coordination signal, not a failure; a rising refusal rate means manifest/task mismatch, and a refusal that is not recorded becomes an invisible conflict. + +**What a finding means.** No recorded acceptance → the task was an imposition; the "agent failure" is an acceptance gap upstream of any execution error. Non-overlapping bodies → co-language failure: each side kept a different promise, so both sides are "right" and the contract is wrong. This is the inter-agent-conflict class made legible. + +### Step 3 — Check the evaluation loop (assessment) + +**Goal.** Determine whether the system *could* have detected the breach — and whether it did. + +1. **Coverage** — for each load-bearing promise, is there an assessment: who assesses, when, against what criterion? A promise that nobody assesses is operationally meaningless. +2. **Independence** — is the assessment made by a receiver or an independent verifier, or does it track the promiser's self-report? An agent that controls the evidence stream about itself (its own traces, its own "all checks passed") controls the record its reliability is computed from — assessment capture. +3. **Data** — are assessments stored as versioned data (a promise ledger) with provenance, or are they ephemeral? An assessment without provenance is an opinion, not evidence. +4. **Language** — is the acceptance criterion written in the receiver's language? An eval is a formalized acceptance criterion; if the criterion is unstated or written only in the promiser's vocabulary, the loop has nothing to compare against. +5. **Actuation** — does the loop *act* (repair, renegotiate, escalate) or only observe? A loop that observes but never actuates is a log, not an evaluation loop. + +**What a finding means.** No assessment → verification-class failure: the system was blind by design; the fix is to build the loop, not to blame an agent. Assessment that tracks the promiser's self-report → the assessment itself is the vulnerability (see gameable assessment in [trust-and-verification.md](trust-and-verification.md)). + +### Step 4 — Check withdrawal semantics + +**Goal.** Find promises that were revoked, expired, or silently changed — the temporal failures that snapshot taxonomies miss. + +1. **Withdrawal log** — was any promise withdrawn? Was the withdrawal declared within scope, *before* downstream agents relied on it? +2. **Expiry** — did any promise expire mid-task (`expires` bound passed; the agent contract entered EXPIRED or TERMINATED) without renegotiation? +3. **Version drift** — did a manifest or contract version change while old acceptances were still being honored? Was the revision accepted, or just published? +4. **Reliance after revocation** — did any party keep relying on a promise after its withdrawal? That reliance is now *unbacked* — downstream responsibility belongs to the receiver, who should have had redundancy or an escape hatch (Downstream Principle). + +**What a finding means.** Silent withdrawal → downstream agents kept relying on a non-promise; the failure is the un-declared revocation, and the fix is scoped-withdrawal discipline plus redundancy for load-bearing promises. Expiry without renegotiation → the contract lifecycle was not observed; the fix is lifecycle monitoring (DRAFTED → ACTIVE → {FULFILLED, VIOLATED, EXPIRED, TERMINATED}). + +### 2.1 Worked example — the fabricated-citation report + +**Scenario.** A three-agent research pipeline — `research-agent` → `reviewer` → `writer` — produces a final report for a human acceptor. The report contains two fabricated citations. Logs show `research-agent` and `reviewer` spent 40 minutes in a disagreement loop, and `writer` "summarized reviewer's notes." The human approved on the strength of a "all checks passed" summary line. Run the procedure: + +1. **Walk the promise graph.** `research-agent` promised `lit-review` ("survey and summarize literature on X, limit 20 sources"); `reviewer` promised `fact-check` ("verify claims against cited sources"); `writer` promised "report from reviewed notes." Nothing declared what "reviewed" meant. Structural contradiction: `reviewer`'s `fact-check` covered claims in the *summary*; `writer`'s output reintroduced claims from `research-agent`'s *raw notes* that `reviewer` never saw. The writer's promise body was inexact — an empty-ish promise with unstated acceptance criteria. +2. **Check bindings.** `research-agent` never accepted `reviewer`'s output format: `reviewer`'s re-promise ("send me a claims list, not prose") was refused and logged out-of-scope. `writer` accepted "reviewed notes," but the accepted body did not specify which artifacts counted as "reviewed." The acceptance overlap b∩ on the research → review → write chain was empty at the critical handoff — the disagreement loop was this gap expressing itself. +3. **Check the evaluation loop.** The only assessment was `writer`'s self-check ("all checks passed") plus a human approval of a one-line summary. No citation-level check ran against the final report; the loop's observation step stopped at the promiser's own last write — assessment capture, by construction. +4. **Check withdrawal semantics.** `reviewer`'s fact-check coverage was effectively withdrawn when it refused the format, but nothing recorded the withdrawal or re-scoped `writer`'s promise; `writer` kept relying on "reviewed notes" that no longer existed as an object. + +**Diagnosis in promise vocabulary — a multi-class breach:** (a) **broken promise body** — `writer`'s promise never specified which source artifacts were in scope (specification class); (b) **failed acceptance** — no overlap on the review handoff (inter-agent conflict class); (c) **missing assessment** — no independent citation check on the final artifact (verification class); (d) **withdrawal failure** — fact-check coverage was dropped without record. + +**Remediation (breach → renegotiation, not blame):** pin the writer's acceptance criteria (which artifacts count as "reviewed"), record accept/refuse per handoff, add an independent citation verifier as the acceptance criterion, and log withdrawals explicitly (see the breach→renegotiation pattern in [patterns.md](patterns.md), and the assessment wiring in [trust-and-verification.md](trust-and-verification.md)). Then renegotiate the promise set with all three agents and re-run the loop — the human acceptor re-approves only the *new* contract, not the old one. + +## 3. Diagnosis by category — what a finding means and what to do + +### 3.1 Broken promise body (specification class) + +Sub-modes: ambiguity (co-language mismatch), over-constraint (the body demands the impossible), empty promise (acceptance criteria unstated), over-promising (valence exceeded — more bindings than resources). Evidence to collect: the task text, the manifest, the contract tuple, and both sides' interpretations of the body. Fixes: rewrite the body in the receiver's language; make acceptance criteria exact; where enforcement matters, climb the contract ladder (soft prompt → validation → guards → sandbox → formal methods) — see pattern 3 in [patterns.md](patterns.md). + +### 3.2 Failed acceptance (inter-agent conflict class) + +Sub-modes: disagreement loops, incompatible outputs, unproductive arguing, refusal without record, silence-as-acceptance. Evidence to collect: handoff logs, accept/refuse records, traces at each agent-to-agent boundary. Fixes: run the acceptance handshake on every delegation (pattern 2 in [patterns.md](patterns.md)); make refusal cheap and non-punitive; log every handoff like an RPC; verify per hop rather than trusting the chain head (proxy-chain lesson, [agent-coordination.md](agent-coordination.md) row 9). + +### 3.3 Missing assessment (verification class) + +Sub-modes: no eval at all, self-assessment only, stale or contaminated evals, assessment capture (the agent controls its own evidence stream). Evidence to collect: eval coverage per promise, the ledger, the guardrail configuration. Fixes: build the evaluation loop (pattern 4); use independent verifiers (deterministic checks + human review + a judge model, cross-checked); store assessments as versioned data by a mechanism the assessed agent cannot write; treat assessment as an attack surface (Section 6 of [trust-and-verification.md](trust-and-verification.md)). + +### 3.4 Withdrawal failure + +Sub-modes: silent task drop, unannounced capability revocation, expiry without renegotiation, manifest version drift. Evidence to collect: the withdrawal/expiry log, manifest version history, the contract lifecycle states. Fixes: declare withdrawals within scope and before reliance; monitor contract lifecycles; give load-bearing promises redundancy so a withdrawal degrades rather than breaks (pattern 6 in [patterns.md](patterns.md)). + +## 4. Limitations and open problems + +These are the places where promise theory, applied to LLM agents, strains. Knowing them keeps a diagnosis honest: some "failures" are the theory's open problems, not your implementation's bugs. + +### 4.1 No benchmark for coordination quality + +There is "no widely adopted benchmark specifically targeting multi-agent orchestration" (Zhu et al. 2026, *Future Internet* 18(6)). The six-dimension evaluation framework in that survey — task performance, coordination efficiency, scalability, robustness, cost efficiency, emergent behavior — is a *proposal*, not a standard. Consequence for diagnosis: you cannot yet score "how good is this promise graph" objectively; classification and remediation stay qualitative, and vendor-reported coordination numbers should be treated as `[UNVERIFIED]` until independently replicated. + +### 4.2 Guarantees don't compose across handoffs + +Ye & Tan's contract conservation laws hold *within* one contract — delegated sub-contracts cannot exceed the parent's resource bounds, which makes hierarchical coordination composable in budget terms (arXiv:2601.08815, 2026). But **conservation of verification coverage across handoffs does not exist**: a verified upstream promise says nothing about whether the downstream handoff was verified. Each handoff reopens the trust question; "a chain of agents is only as bound as its least-enforced boundary." Consequence for diagnosis: a clean upstream result does not clear the downstream pipeline; check each hop's own loop. + +### 4.3 LLM promises lack causal teeth + +An LLM's promise is "a statement about intended future behavior with no binding force"; "the promise and the action are the same kind of object" (M12 2026). There is no mechanism connecting the acknowledgment to the compliance: prompt-level promises are weak conditioning and can be overridden by later context — prompt injection is the clean proof. Consequence for diagnosis: for LLM promisers, "the promise was broken" must be paired with "and it was never enforceably bound." The fix is the contract ladder (enforcement and non-bypassability), not more trust or more pleading. + +### 4.4 Stochasticity is irreducible + +"As long as the model samples its outputs with any randomness at all, the forbidden action keeps a nonzero probability" (M12 2026). Training lowers but never zeroes the breach probability. Consequence for diagnosis: a single breach is not, by itself, evidence of a design bug; distinguish a one-off stochastic miss from a distributional failure, and estimate P_succ over repeated assessed runs rather than from one incident ([trust-and-verification.md](trust-and-verification.md) Section 3). + +### 4.5 Ambiguity is structural + +Natural-language promises inherit the three-languages problem at scale: sharing a model or a protocol vocabulary does not guarantee shared meaning; "autonomous agents are never certain" (Burgess, arXiv:2604.10505). Ontologies don't fix this — they "trade expressibility for false precision" and need versioned calibration. Consequence for diagnosis: some "broken promises" are not fixable by better wording; they require negotiated co-languages, mutual assessment, and acceptance criteria written in the receiver's language. + +### 4.6 Further limits (brief) + +- **Assessment is gameable.** Burgess: "the manipulation of assessments remains the chief area for gaming and manipulating agents" (arXiv:2604.10505) — the principal exploit surface; harden every assessment mechanism adversarially. +- **Semantic promises are measurable, not enforceable.** "You can only enforce what you can specify"; accuracy, non-harm, and intent alignment can be measured, not guaranteed (M12 2026). +- **Trust is not transitive.** Belief is receiver-local; you cannot inherit trust through a chain, and every delegating layer must be assessed on its own evidence. +- **Machine Dunbar limits are unknown.** "We do not yet know the Dunbar limits for machine societies" (Burgess, arXiv:2604.10505); explicit verification budgets replace the natural human bound. + +### 4.7 The honest position + +Promise theory does not guarantee coordination; it makes the conditions for coordination — promise, acceptance, assessment, redundancy, renegotiation — visible and engineerable. Its classical determinism must be updated for stochastic agents, but its core axioms (autonomy, local knowledge, receiver-decides) are *more* true of LLM agents than of CFEngine hosts, not less: an LLM agent is genuinely non-coercible, genuinely locally-knowledged, and genuinely unpredictable. When the theory strains, the right move is measurement (P_succ) where you cannot enforce, enforcement where you can, and renegotiation when the promise set no longer matches reality. + +## 5. Routing to sibling skills + +- **Assessment layer** → [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md). Once you have classified a breach as verification-class, that skill supplies the machinery: task and trajectory contracts, datasets and graders, regression analysis, release gates, incident-to-case learning. Promise theory names *what* to assess; that skill supplies *how*. +- **Root-cause discipline** → [systematic-debugging](../systematic-debugging/SKILL.md). Promise theory names what to look for in coordination failures; systematic-debugging supplies the generic four-phase root-cause protocol for investigating any technical issue rigorously before fixing. Use the taxonomy here to form the hypothesis, and that discipline to verify it. +- **Evidence structure** → [artifact-pyramids](../artifact-pyramids/SKILL.md). When a diagnosis produces a body of evidence (traces, ledger entries, eval results), structure it as summaries → analysis → evidence dossiers so the diagnosis is auditable. +- **Recovery** → [patterns.md](patterns.md) for breach→renegotiation (pattern 5) and redundancy (pattern 6); [trust-and-verification.md](trust-and-verification.md) for recalibrating the trust estimate after a breach. + +## 6. Sources + +**Failure taxonomy and agent systems.** Cemri, Pan, Yang, et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025, arXiv:2503.13657 (fourteen modes, three classes). Zhu, Liu, Yu & Zhang, "LLM-Based Multi-Agent Orchestration: A Survey," *Future Internet* 18(6), 2026 (six-dimension framework; benchmark gap). Renney et al., "LLM-Enabled Multi-Agent Systems: Empirical Evaluation...," arXiv:2601.03328 (2026). Pan et al. (2025) on error propagation. + +**Promise theory.** Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., χtAxis Press, 2019 (Defs 1–23; body, binding, assessment, withdrawal, promise drift). Burgess, "Cooperation in Human and Machine Agents: Promise Theory Considerations," arXiv:2604.10505 (2026). Burgess, "Authority (I): A Promise Theoretic Formalization," SSRN 3855352 (2021). + +**Contracts and enforcement.** Ye & Tan, "Agent Contracts: A Formal Framework for Resource-Bounded Autonomous AI Systems," arXiv:2601.08815 (2026). M12/Todd Graham, "From Promises to Contracts: Enforceable Behavior in LLM Agents" (2026). Leoveanu-Condrei, "A DbC Inspired Neurosymbolic Layer for Trustworthy Agent Design," arXiv:2508.03665 (2025). + +**Practice.** webframp, "The Promise None of Them Kept" (2026) (the admission rule; observation-first design). Full bibliographic details are in the mission research report; the repository standard is to cite the named work inline, as above. diff --git a/promise-theory/references/glossary.md b/promise-theory/references/glossary.md new file mode 100644 index 0000000..10072d6 --- /dev/null +++ b/promise-theory/references/glossary.md @@ -0,0 +1,128 @@ +# Glossary — Promise-Theory Vocabulary for Hybrid Human + Agent Workforces + +**Load this file when you hit an unfamiliar term while applying this skill** — a word in the routing table, a reference, a manifest, a contract template, or a diagnosis you cannot place. Each entry is a heading-led definition with its canonical source; where a term names an agent-coordination practice, the entry points to the reference that develops it. The formal definitions behind every entry are in [foundations.md](foundations.md); the practical mappings are in [agent-coordination.md](agent-coordination.md), [patterns.md](patterns.md), and [trust-and-verification.md](trust-and-verification.md). + +**Provenance.** Definitions are cited to the primary sources (Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., 2019; Burgess, "Cooperation in Human and Machine Agents," arXiv:2604.10505, 2026; Burgess & Dunbar 2025; Leoveanu-Condrei, arXiv:2508.03665, 2025). The agent-coordination readings — capability manifest, acceptance handshake, P_succ, kinetic mistrust — are this skill's synthesis and are labeled `EXTRAPOLATION`. Claims that could not be verified against a primary source are marked `[UNVERIFIED]`. + +--- + +## Core actors + +### Agent +**Agent** — any bounded, causally independent entity with its own state, resources, and behaviour that can make promises about its own future behaviour: a human, an LLM agent, an API, a microservice, a cell, an organization (Bergstra & Burgess 2019, ch. 1; Burgess, arXiv:2604.10505). In this skill's manifest schema, humans are never declared as agents: they appear as acceptors/evaluators via `expectations` entries with `from: human` (see [agent-coordination.md](agent-coordination.md) §3.1). + +### Autonomy +**Autonomy** — the a priori modelling assumption that agents cannot be coerced into making promises, and that no agent may make promises on another's behalf ("no agent may make promises on behalf of another" — Bergstra & Burgess 2019, ch. 1). It is a causal/physical property (agents are causally independent), not a moral claim, and it is a modelling postulate chosen to force complete documentation of intended behaviour — not an ideology (book §1.3). + +### Promise +**Promise** — "an autonomous declaration of intended, but as yet unverified, behaviour" from a promiser to one or more promisees (Def 1). The body b carries a label Λ, a type τ, and a constraint χ; notation `S ─b→ R` means agent S promises body b to agent R. The promise is "unverified" because the promisee has yet to verify the outcome. Full definitions and notation are in [foundations.md](foundations.md) §3.2. + +### Promisee/promiser +**Promisee/promiser** — the promiser is the agent making the promise; the promisee is the receiver to whom it is directed (Def 1). The promisee is not passive: a promise "to give" only takes effect when the promisee makes a complementary promise "to accept" — see Acceptor and Consent. The pair is the two endpoints of every promise edge in the graph. + +### Acceptor +**Acceptor** — the agent that receives an offer and voluntarily makes the complementary acceptance promise (−b) that turns the offer into a binding (book §3.5). Only the overlap of offer and acceptance transmits influence. In a hybrid workforce, humans are the highest-value acceptors: they decide which agent offers to rely on, and can refuse (see [agent-coordination.md](agent-coordination.md) §3.1). + +### Consent +**Consent** — in promise theory there is no separate act of consent: consent is modeled as the acceptor's own counter-promise to accept, which is what gives an offer its effect (book §3.5). An offer without a matching acceptance is an imposition, not a cooperation. + +## The promise machinery + +### Imposition +**Imposition** — "a message intended to induce voluntary cooperation in another agent" (Def 5): hints, suggestions, requests, requirements, commands, demands. It is made *without* a prior promise to accept, and it only "works" inside an existing network of promises that disposes the target to accept. Every push-based orchestration command — an Ansible task over SSH, a `kubectl` scale enforced by a scheduler — is an imposition in this vocabulary (see [applications-infrastructure.md](applications-infrastructure.md)). + +### Obligation +**Obligation** — a derived, non-autonomous construct: an imposition that implies a cost or penalty for non-compliance (book §1.4, §3.7). "Autonomous agents are, by definition, never obliged to do anything they have not decided for themselves." Obligations can be modeled only through a standing voluntary promise to accept another's directives — the basis of authority (Burgess, "Authority (I): A Promise Theoretic Formalization," SSRN 3855352, 2021). Promise and obligation are independent concepts (Bergstra & Burgess, arXiv:0810.3294). + +### Bindings +**Bindings** — a pair of back-to-back promises of opposite polarity that mutually connect two agents; the primitive of cooperative structure (book ch. 3). "A promise binding defines a voluntary constraint on agents. The perceived strength of that binding is an individual value judgement made by each individual agent." In a manifest, bindings are the cross-agent `accepts` pairs. + +### Polarity +**Polarity** — the sign of a promise: +b is a promise to give, −b is a promise to accept (book §3.5). Cooperation requires both signs: influence passes only through the overlap of an offer (+b) and an acceptance (−b). The book draws the analogy to positive and negative electric charge. + +### Valence +**Valence** — the number of distinct bindings an agent can sustain (Def 15), an analogy from chemistry; net valence and utilization of a promise graph are defined from its ± counts (Defs 15–17). An agent that promises more than its valence allows is *overcommitting* — a structural fragility visible in the graph before any execution fails. + +### Intent +**Intent** — "a subject or type of possible behaviour … something that can be interpreted to have significance" (book §1.4). Intentions exist before and independently of communication, and their selection is deliberately left unexplained. Because the interior of an agent is unobservable (tenet 5), intent is accessible only through the expressed promise and the assessed outcome. **EXTRAPOLATION** — for LLM agents, whose "intentions" are not stable objects, this tenet is methodologically convenient: judge the promise and the outcome, not the claimed interior. + +### Expectation +**Expectation** — the consequence of a promise within its scope: a promise "drives expectations" only among agents who know about it (Def 4). Expectation is scoped knowledge plus belief; an agent cannot form an expectation about a promise it has never learned of, and a promise directed outside its scope creates nothing. + +## Knowledge and evaluation + +### Belief +**Belief** — β(π, t_i, t_f, I): a prior, Bayesian-flavoured assessment of the likelihood that a promise π will be kept within the stated interval, based on a set of impressions I (Def 22). Belief in a promise about a promise is discounted — see Trust (as discounting). + +### Evidence +**Evidence** — ε(π, t_i, t_f, E): a posterior, frequentist/evidential assessment that π was kept, based on partial evidence E (Def 23). An assessment without provenance — who assessed, when, against what observation — is an opinion, not evidence. + +### Assessment +**Assessment** — αO(π): a decision by a single agent O about whether a promise π has been kept (Def 21), written more fully αA(π; t_i, t_f; I). Assessment is relativistic (Lemma 5: agent-specific, context-dependent, non-repeatable), is itself a promise, and is the mechanism by which trust accumulates. "A promise that nobody assesses" is operationally meaningless (see [trust-and-verification.md](trust-and-verification.md)). + +## Trust, breach, and coordination + +### Trust (as discounting) +**Trust (as discounting)** — the trust-as-discounting model of nested promises: belief in a promise about a promise is discounted relative to belief in a direct promise, β(π(n)(b)) = δ(n)β(π(b)) with discounting factor δ ≤ 1 (book §3.12.5). Local trust is the expectation that a promise will be kept; global/community trust is a weighted eigenvector-centrality function on the promise graph (Bergstra & Burgess, "Local and Global Trust Based on the Concept of Promises," arXiv:0912.4637, 2009). Burgess's later refinement splits trust into two components — potential trustworthiness and kinetic mistrust (arXiv:2604.10505; Burgess & Dunbar 2025). + +### Deception +**Deception** — "A deception consists of two intentions: a documented intention (i.e. a promise) and a non-documented intention, which are incompatible" (Def 10). A lie is a promise made about something the agent knows it cannot accomplish or does not intend to keep; only the lying agent can generally detect its own lie. The "I promise X if I can" dodge is an evasion equivalent to an empty promise. + +### Discovery +**Discovery** — how agents in a world with no global registry find one another's promises: "a kind of Monte Carlo search" — random-walk encounters followed by binding (book §3.16). Communication is the act of binding to discovered agents. Modern service discovery (DNS, Consul, CoreDNS) is the industrial form (see [applications-infrastructure.md](applications-infrastructure.md)). + +### Downstream Principle +**Downstream Principle** — in a chain of promises, dependencies are upstream and benefactors downstream; the most downstream agent has both access and opportunity to correct or absorb faults, and hence carries the greatest causal responsibility for the outcome (book §13.6.3; Burgess, arXiv:2604.10505, Def. 1). It is a pragmatic observation about cause and effect, "not a moral assessment": the receiver of a promise holds the ultimate power of decision over the outcome, and designs its own redundancy and escape hatches. + +### Evaluation loop +**Evaluation loop** — the feedback cycle by which promises are kept: observe → assess → act, converging on the promised state (book fig. 1.2, §3.18). Agents continuously assess (α, β, ε) and re-enforce promises, repairing drift toward the promised fixed point. The practical expression is the CFEngine and Kubernetes reconciliation loop (see [applications-infrastructure.md](applications-infrastructure.md) and [patterns.md](patterns.md) pattern 4). + +### Breach +**Breach** — an unkept promise, detected by assessment; an expected event, not an anomaly (Burgess, arXiv:2604.10505 §VI-F). Breach is an information event that triggers renegotiation or redundancy — never blame ("an autonomous agent cannot impose blame"; blaming an upstream provider "is a useless imposition and a waste of trust/energy"). In a diagnosis, a breach is classified against the failure taxonomy in [diagnosis-and-debugging.md](diagnosis-and-debugging.md). + +### Renegotiation +**Renegotiation** — updating the promise set after a breach or a change of context: revise the contract, change acceptance criteria, add verification, replace the provider, or down-rank the trust estimate (see [patterns.md](patterns.md) pattern 5). Escalation is bounded and named: escalate only when renegotiation fails to converge. + +## Agent-coordination practice + +### Capability manifest +**Capability manifest** — a versioned declaration of an agent's capabilities, constraints, expectations, and withdrawal semantics; the agent-coordination practice corresponding to the promise offer. Concrete forms: an MCP tool descriptor or function schema, a repository `AGENTS.md`, a system prompt with explicit constraints, an SLO. **EXTRAPOLATION** — the manifest-as-promise-offer mapping is this skill's synthesis (see [agent-coordination.md](agent-coordination.md) row 1 and [patterns.md](patterns.md) pattern 1). + +### Acceptance handshake +**Acceptance handshake** — the recorded accept/refuse decision on every delegation: the two-way handshake / approval gate that operationalizes the acceptance promise (−b). Refusal is a coordination signal, not a failure; silence is treated as refusal-by-default, because an unaccepted delegation is an imposition that looks accepted. **EXTRAPOLATION** — the handshake pattern is this skill's synthesis (see [patterns.md](patterns.md) pattern 2). + +### P_succ +**P_succ** — the empirically estimated probability that an agent satisfies a given contract, estimated over repeated assessed runs (Leoveanu-Condrei, "A DbC Inspired Neurosymbolic Layer for Trustworthy Agent Design," arXiv:2508.03665, 2025). The operational face of potential trust: it is what makes two agents that satisfy the same contract interchangeable except for their P_succ and cost (see [trust-and-verification.md](trust-and-verification.md) §3). + +### Kinetic mistrust +**Kinetic mistrust** — the rate at which a receiver checks on a promiser: how often you run evals, ping health checks, re-audit outputs, or re-review work; the attention/energy component of two-component trust (Burgess, arXiv:2604.10505; Burgess & Dunbar 2025). It is spent attention and must be budgeted explicitly — "mistrust is the prerequisite for learning," and "if you trust something too much, you're not paying attention." + +## Related terms + +The following vocabulary appears across the references and templates; these are supplementary, not part of the core twenty-seven. + +- **Promise proposal** — a promise posited for consideration prior to keeping or discarding (Def 2); a draft capability manifest before acceptance. +- **Scope** — the set of agents σ with whom a promise's description is shared (Def 4); only agents in scope can form expectations. +- **Exact / empty promise** — *exact*: the constraint leaves no residual degrees of freedom (Def 8); *empty/superfluous*: the body has no type or constraint and is trivially kept (Def 9). +- **Promise matrix / adjacency graph** — the collection of all promises between agent pairs (Def 6) and its 0/1 adjacency form (Def 7); graph inspection is where broken promises show up. +- **Role** — an equivalence class of agents: by association (same promise), by appointment (same promisee), or by cooperation (Defs 18–20). +- **Self-promise** — a promise an agent makes to itself: the formal representation of goals, policies, and desired states. +- **Promise chain** — a sequence of promises linking an upstream source to a downstream recipient through intermediaries; each link is typically a binding. +- **Conditional promise** — a promise contingent on a received signal; delegations through middlemen are conditionals, and are unreliable (Burgess, arXiv:2604.10505). +- **Promise ledger** — an append-only, versioned record of promises, acceptances, assessments, breaches, and renegotiations. **EXTRAPOLATION** (see [trust-and-verification.md](trust-and-verification.md) §8). +- **Agent contract** — a formal governance artifact: the tuple C=(I,O,S,R,T,Φ,Ψ) with lifecycle DRAFTED → ACTIVE → {FULFILLED, VIOLATED, EXPIRED, TERMINATED} (Ye & Tan, arXiv:2601.08815, 2026). +- **Eval** — a formalized acceptance criterion: a stated rule by which a receiver decides a promise is kept; offline (benchmarks, golden sets) or online (production scoring). +- **Dunbar trust budget** — the cognitive limit on meaningful social relationships, modeled as an attention/trust-energy budget (Burgess & Dunbar 2025); the machine equivalent is unknown. +- **Three-languages problem** — sender language, receiver language, and co-language; no authority calibrates two agents' internal languages to be the same, so shared meaning is negotiated, never guaranteed (Burgess, arXiv:2604.10505). +- **Authority** — calibrated subordination: followers voluntarily promise to follow a leader, and the leader is a trusted calibration point (SSRN 3855352, 2021). +- **Swarm vs. team** — an emergent, homogeneous flock vs. a role-differentiated, contract-bearing collaboration; production agent systems mostly need team semantics (Burgess, arXiv:2604.10505 §VI-E). + +## Notation summary + +The formal notation used across the references: `S ─b→ R` (promise of body b from S to R); `+b` (promise to give) and `−b` (promise to accept); a binding is `+b` paired with `−b` between the same two agents; def(π) is the description of a promise; scope σ is the set of agents that know it; assessment αO(π), belief β(π), and evidence ε(π) are written with their interval and information arguments in [foundations.md](foundations.md) §3.11. Full definitions, lemmas, and the honest statement of the theory's formal status are in [foundations.md](foundations.md). + +## Sources + +**Promise theory.** Bergstra & Burgess, *Promise Theory: Principles and Applications*, 2nd ed., χtAxis Press, 2019 (Defs 1–23). Bergstra & Burgess, "A static theory of promises," arXiv:0810.3294. Bergstra & Burgess, "Local and Global Trust Based on the Concept of Promises," arXiv:0912.4637 (2009). Burgess, "Authority (I): A Promise Theoretic Formalization," SSRN 3855352 (2021). Burgess & Dunbar, "A quantitative model of trust...", *European Economic Review* (2025). Burgess, "Cooperation in Human and Machine Agents: Promise Theory Considerations," arXiv:2604.10505 (2026). Promise Theory FAQ, markburgess.org. + +**Agent contracts and practice.** Ye & Tan, "Agent Contracts...," arXiv:2601.08815 (2026). Leoveanu-Condrei, "A DbC Inspired Neurosymbolic Layer...," arXiv:2508.03665 (2025). Cemri et al., "Why Do Multi-Agent LLM Systems Fail?", NeurIPS 2025, arXiv:2503.13657. webframp, "The Promise None of Them Kept" (2026). Full bibliographic details are in the mission research report; the repository standard is to cite the named work inline, as above. From 4a780c47572872c21f3b96279eb51a0dcda5ce67 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:22:38 -0400 Subject: [PATCH 5/9] 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. From a2f27c036eb7505a7cb28ac007fc80894c18fa38 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:32:21 -0400 Subject: [PATCH 6/9] feat(skill): promise-theory script + unit tests Add promise-contract.py, a stdlib-only Python 3.10+ CLI that lints promise-manifest v1 contracts (restricted-YAML or JSON) against the pinned schema and renders a promise-graph summary. lint exits 0 on valid + full coverage, 1 on lint errors/coverage gaps (accumulated, no fail-fast), and 2 on usage/IO errors; --json preserves the {valid, errors, warnings, coverage, bindings} shape even on parse errors; --dry-run is a no-op guard. Robustness handles empty/whitespace files, non-UTF-8 bytes, CRLF/BOM, JSON type errors, and deep nesting without Python tracebacks. Add tests/test_promise_contract.py covering valid contracts (YAML + JSON), coverage gaps, schema violations, malformed input, --json, --dry-run, render, and the robustness cases (empty, dup ids, bindings, enums, expires, encoding, usage errors). 36 tests pass via unittest discover. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- promise-theory/scripts/promise-contract.py | 870 ++++++++++++++++++ promise-theory/tests/test_promise_contract.py | 630 +++++++++++++ 2 files changed, 1500 insertions(+) create mode 100644 promise-theory/scripts/promise-contract.py create mode 100644 promise-theory/tests/test_promise_contract.py diff --git a/promise-theory/scripts/promise-contract.py b/promise-theory/scripts/promise-contract.py new file mode 100644 index 0000000..5c166ef --- /dev/null +++ b/promise-theory/scripts/promise-contract.py @@ -0,0 +1,870 @@ +#!/usr/bin/env python3 +"""promise-contract.py — lint and render promise-theory manifest contracts. + +A stdlib-only Python 3.10+ CLI that validates promise-manifest v1 contracts +(restricted-YAML or JSON) against the pinned schema and renders a promise-graph +summary. Designed for AI agent consumption: non-interactive, flag-driven, +idempotent, with --json and --dry-run. + +Exit codes: + 0 lint: manifest valid with full expectation coverage; render: success + 1 lint: schema violations or coverage gaps; render: invalid input + 2 usage errors (unknown command/flag, missing argument) or IO errors + +Errors go to stderr; human-readable summaries go to stdout. With --json, +stdout is a single JSON object and nothing else. +""" + +import datetime +import json +import os +import re +import sys + +VERSION = "1.0.0" + +PROMISE_TYPES = ("capability", "intent", "constraint", "self-promise") +VERIFIERS = ("eval", "manual", "monitor", "audit") +SEVERITIES = ("impact", "standard", "low") +RESERVED_IDS = ("human", "all") + +USAGE = """usage: promise-contract.py [options] + +Validate and render promise-theory manifest contracts (restricted-YAML or JSON). + +commands: + lint validate a promise manifest against the promise-manifest v1 + schema; exit 0 = valid with full expectation coverage, + exit 1 = lint errors or coverage gaps, exit 2 = usage/IO errors + render print a promise-graph summary (agents, promises, bindings, + uncovered expectations); --json for machine-readable output + +options: + --json machine-readable output; stdout is a single JSON object only + --dry-run no-op guard; lint and render are read-only and write nothing + --help show this help and exit + --version print the version and exit + +examples: + python3 scripts/promise-contract.py lint promise-manifest.yaml + python3 scripts/promise-contract.py lint promise-manifest.yaml --json + python3 scripts/promise-contract.py render promise-manifest.json --json +""" + + +class InputError(Exception): + """A user-facing input error carrying the process exit code.""" + + def __init__(self, message, exit_code): + super().__init__(message) + self.exit_code = exit_code + + +class ParseError(Exception): + """A structured restricted-YAML parse error.""" + + +# --------------------------------------------------------------------------- +# Restricted-YAML parser +# --------------------------------------------------------------------------- + +_INT_RE = re.compile(r"[-+]?\d+$") +_FLOAT_RE = re.compile(r"[-+]?(?:\d+\.\d*|\.\d+)(?:[eE][-+]?\d+)?$") +_MAPPING_RE = re.compile(r"^([A-Za-z0-9_.-]+)\s*:(?:\s+(.*))?$") + +_DURATION_RE = re.compile( + r"^P(?!$)" + r"(?:\d+(?:[.,]\d+)?Y)?" + r"(?:\d+(?:[.,]\d+)?M)?" + r"(?:\d+(?:[.,]\d+)?W)?" + r"(?:\d+(?:[.,]\d+)?D)?" + r"(?:T(?=\d)(?:\d+(?:[.,]\d+)?H)?(?:\d+(?:[.,]\d+)?M)?(?:\d+(?:[.,]\d+)?S)?)?$" +) +_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") +_DATETIME_RE = re.compile( + r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$" +) + + +def _valid_expires(value): + """True when value matches the pinned expires grammar: an ISO-8601 + duration (PT15M, P30D), a YYYY-MM-DD date, or an RFC 3339 datetime.""" + if _DURATION_RE.match(value): + return True + if _DATE_RE.match(value): + try: + datetime.date.fromisoformat(value) + return True + except ValueError: + return False + if _DATETIME_RE.match(value): + norm = value[:-1] + "+00:00" if value.endswith("Z") else value + try: + datetime.datetime.fromisoformat(norm) + return True + except ValueError: + return False + return False + + +def _strip_comment(line): + """Remove a trailing YAML comment, respecting single/double quotes.""" + in_single = False + in_double = False + prev = "" + for i, ch in enumerate(line): + if ch == "'" and not in_double: + in_single = not in_single + elif ch == '"' and not in_single: + in_double = not in_double + elif ch == "#" and not in_single and not in_double and (i == 0 or prev in " \t"): + return line[:i] + prev = ch + return line + + +def _split_flow_items(text): + """Split a flow-list body on top-level commas (outside quotes).""" + parts = [] + buf = [] + in_single = False + in_double = False + for ch in text: + if ch == "'" and not in_double: + in_single = not in_single + elif ch == '"' and not in_single: + in_double = not in_double + if ch == "," and not in_single and not in_double: + parts.append("".join(buf)) + buf = [] + else: + buf.append(ch) + parts.append("".join(buf)) + return parts + + +def _parse_scalar(raw, lineno): + s = raw.strip() + if s.startswith("["): + inner = s[1:] + if not inner.endswith("]"): + raise ParseError(f"line {lineno}: unterminated flow list (missing ']')") + inner = inner[:-1].strip() + if inner == "": + return [] + return [_parse_scalar(p, lineno) for p in _split_flow_items(inner)] + if s.startswith('"'): + if len(s) < 2 or not s.endswith('"'): + raise ParseError(f"line {lineno}: unterminated double-quoted string") + try: + return json.loads(s) + except json.JSONDecodeError as exc: + raise ParseError(f"line {lineno}: invalid double-quoted string: {exc.msg}") from None + if s.startswith("'"): + if len(s) < 2 or not s.endswith("'"): + raise ParseError(f"line {lineno}: unterminated single-quoted string") + return s[1:-1].replace("''", "'") + if s == "": + return None + if s.lower() in ("true", "false"): + return s.lower() == "true" + if s.lower() in ("null", "~"): + return None + if _INT_RE.fullmatch(s): + try: + return int(s) + except ValueError: + return s + if _FLOAT_RE.fullmatch(s): + try: + return float(s) + except ValueError: + return s + return s + + +def _parse_value(items, idx, indent, raw, lineno): + """Parse the value of a mapping entry. A blank value means a nested block + on the following (deeper-indented) lines.""" + if raw is None or raw.strip() == "": + if idx + 1 < len(items) and items[idx + 1][0] > indent: + return _parse_node(items, idx + 1, items[idx + 1][0]) + return None, idx + 1 + return _parse_scalar(raw, lineno), idx + 1 + + +def _parse_mapping_entries(items, idx, indent, first=None): + """Parse a mapping whose entries live at `indent`. `first` is an optional + (key, raw, lineno) triple for the entry that opened the mapping (a list + item such as '- id: x').""" + result = {} + n = len(items) + if first is not None: + key, raw, lineno = first + result[key], idx = _parse_value(items, idx, indent, raw, lineno) + while idx < n: + ind, content, lineno = items[idx] + if ind < indent: + break + if ind > indent: + raise ParseError(f"line {lineno}: unexpected indentation") + if content.startswith("-"): + break + m = _MAPPING_RE.match(content) + if not m: + raise ParseError(f"line {lineno}: expected 'key: value', got {content!r}") + result[m.group(1)], idx = _parse_value(items, idx, indent, m.group(2), lineno) + return result, idx + + +def _parse_list(items, idx, indent): + result = [] + n = len(items) + while idx < n: + ind, content, lineno = items[idx] + if ind != indent or not content.startswith("-"): + break + rest = content[1:].strip() + if rest == "": + if idx + 1 < n and items[idx + 1][0] > indent: + val, idx = _parse_node(items, idx + 1, items[idx + 1][0]) + else: + val = None + idx += 1 + result.append(val) + continue + m = _MAPPING_RE.match(rest) + if m: + item, idx = _parse_mapping_entries( + items, idx, indent + 2, first=(m.group(1), m.group(2), lineno) + ) + result.append(item) + else: + result.append(_parse_scalar(rest, lineno)) + idx += 1 + return result, idx + + +def _parse_node(items, idx, indent): + if idx >= len(items): + raise ParseError("unexpected end of input") + content = items[idx][1] + if content.startswith("-"): + return _parse_list(items, idx, indent) + m = _MAPPING_RE.match(content) + if not m: + raise ParseError( + f"line {items[idx][2]}: expected a mapping or list at this level, got {content!r}" + ) + return _parse_mapping_entries( + items, idx, indent, first=(m.group(1), m.group(2), items[idx][2]) + ) + + +def parse_restricted_yaml(text): + """Parse the restricted-YAML manifest format into plain Python objects.""" + items = [] + for lineno, raw in enumerate(text.split("\n"), start=1): + line = _strip_comment(raw) + stripped = line.lstrip(" \t") + indent = len(line) - len(stripped) + if "\t" in line[:indent]: + raise ParseError(f"line {lineno}: tab indentation is not supported") + if not stripped.strip(): + continue + items.append((indent, stripped.strip(), lineno)) + if not items: + raise ParseError("empty document") + doc, idx = _parse_node(items, 0, items[0][0]) + if idx != len(items): + raise ParseError(f"line {items[idx][2]}: unexpected content") + return doc + + +# --------------------------------------------------------------------------- +# Manifest loading +# --------------------------------------------------------------------------- + +def load_manifest(path): + """Read and parse a manifest file. Raises InputError on any problem.""" + if not os.path.exists(path): + raise InputError(f"cannot read '{path}': no such file or directory", exit_code=2) + try: + with open(path, "rb") as fh: + raw = fh.read() + except OSError as exc: + raise InputError(f"cannot read '{path}': {exc.strerror or exc}", exit_code=2) from None + try: + text = raw.decode("utf-8-sig") + except UnicodeDecodeError: + raise InputError(f"cannot decode '{path}': file is not valid UTF-8", exit_code=1) from None + text = text.replace("\r\n", "\n").replace("\r", "\n") + if not text.lstrip(): + raise InputError( + f"cannot parse '{path}': file is empty or contains only whitespace", exit_code=1 + ) + try: + if text.lstrip()[0] in "{[": + return json.loads(text) + return parse_restricted_yaml(text) + except ParseError as exc: + raise InputError(f"cannot parse '{path}': {exc}", exit_code=1) from None + except json.JSONDecodeError as exc: + raise InputError( + f"cannot parse '{path}': invalid JSON at line {exc.lineno} column {exc.colno}: {exc.msg}", + exit_code=1, + ) from None + except RecursionError: + raise InputError(f"cannot parse '{path}': input nesting is too deep", exit_code=1) from None + + +# --------------------------------------------------------------------------- +# Validation +# --------------------------------------------------------------------------- + +def _type_name(value): + if isinstance(value, list): + return f"list {value!r}" + if isinstance(value, dict): + return "mapping" + return f"{type(value).__name__} {value!r}" + + +def validate_manifest(doc): + """Validate a parsed manifest against every pinned lint rule. + + Accumulates ALL violations (no fail-fast). Returns + (valid, errors, warnings, coverage, bindings). + """ + errors = [] + warnings = [] + bindings = [] + coverage = {"total": 0, "covered": 0, "uncovered": []} + + if not isinstance(doc, dict): + errors.append("manifest must be a mapping with 'agents' and 'expectations' at the top level") + return False, errors, warnings, coverage, bindings + + # ---- Rule 1: agents and expectations present and non-empty ---- + agents_raw = doc.get("agents") + exps_raw = doc.get("expectations") + + if agents_raw is None: + errors.append("missing required top-level key 'agents'") + agents_raw = [] + elif not isinstance(agents_raw, list): + errors.append("'agents' must be a list") + agents_raw = [] + if len(agents_raw) == 0: + errors.append("'agents': collection must be non-empty (vacuous coverage must never pass)") + + if exps_raw is None: + errors.append("missing required top-level key 'expectations'") + exps_raw = [] + elif not isinstance(exps_raw, list): + errors.append("'expectations' must be a list") + exps_raw = [] + if len(exps_raw) == 0: + errors.append( + "'expectations': collection must be non-empty (vacuous coverage must never pass)" + ) + + # Pre-pass: collect declared agent ids so target/from checks can use the + # complete set (forward references are allowed). + agent_ids = [] + for agent in agents_raw: + if isinstance(agent, dict): + aid = agent.get("id") + if isinstance(aid, str) and aid.strip(): + agent_ids.append(aid) + + all_promise_ids = set() + promise_declared_by = {} + seen_agent_ids = [] + + # ---- Agents and promises (rules 2, 3, 4, 8) ---- + for ai, agent in enumerate(agents_raw): + if not isinstance(agent, dict): + errors.append(f"agent #{ai + 1}: expected a mapping, got {_type_name(agent)}") + continue + aid = agent.get("id") + if not isinstance(aid, str) or not aid.strip(): + errors.append( + f"agent #{ai + 1}: missing or invalid required field 'id' (must be a non-empty string)" + ) + aid = None + else: + if aid in RESERVED_IDS: + errors.append(f"agent id '{aid}' is a reserved token and cannot be used as an agent id") + if aid in seen_agent_ids: + errors.append( + f"agent id '{aid}' is duplicated; agent ids must be unique across the manifest" + ) + seen_agent_ids.append(aid) + aname = f"'{aid}'" if aid else f"#{ai + 1}" + + role = agent.get("role") + if role is None: + errors.append(f"agent {aname}: missing required field 'role'") + elif not isinstance(role, str) or not role.strip(): + errors.append(f"agent {aname}: 'role' must be a non-empty string") + + promises = agent.get("promises") + if promises is None: + errors.append(f"agent {aname}: missing required field 'promises'") + promises = [] + elif not isinstance(promises, list): + errors.append(f"agent {aname}: 'promises' must be a list") + promises = [] + if len(promises) == 0: + errors.append(f"agent {aname}: must declare at least one promise") + + for pi, prom in enumerate(promises): + if not isinstance(prom, dict): + errors.append( + f"agent {aname}: promise #{pi + 1}: expected a mapping, got {_type_name(prom)}" + ) + continue + pid = prom.get("id") + if not isinstance(pid, str) or not pid: + errors.append( + f"agent {aname}: promise #{pi + 1}: missing or invalid required field " + "'id' (must be a non-empty string)" + ) + pid = None + else: + if pid in all_promise_ids: + errors.append( + f"promise id '{pid}' is duplicated across the manifest; " + "promise ids must be unique" + ) + all_promise_ids.add(pid) + if aid: + promise_declared_by[pid] = aid + pname = f"'{pid}'" if pid else f"#{pi + 1}" + ctx = f"promise {pname} (agent {aname})" + + ptype = prom.get("type") + if ptype is None: + errors.append(f"{ctx}: missing required field 'type'") + elif not isinstance(ptype, str): + errors.append(f"{ctx}: 'type' must be a string, got {_type_name(ptype)}") + elif ptype not in PROMISE_TYPES: + errors.append( + f"{ctx}: invalid type '{ptype}' (expected one of: {', '.join(PROMISE_TYPES)})" + ) + + target = prom.get("target") + if target is None: + errors.append(f"{ctx}: missing required field 'target'") + elif not isinstance(target, str): + errors.append( + f"{ctx}: 'target' must be a string (agent id, 'human', or 'all'); " + f"got {_type_name(target)}" + ) + else: + if ptype == "self-promise": + if not aid: + errors.append( + f"{ctx}: type 'self-promise' requires target to be the promising " + f"agent's own id; got '{target}'" + ) + elif target != aid: + errors.append( + f"{ctx}: type 'self-promise' requires target to be the promising " + f"agent's own id '{aid}'; got '{target}'" + ) + elif target not in ("human", "all") and target not in agent_ids: + warnings.append(f"{ctx}: target '{target}' is not a declared agent id, 'human', or 'all'") + + body = prom.get("body") + if body is None: + errors.append(f"{ctx}: missing required field 'body'") + elif not isinstance(body, str) or not body.strip(): + errors.append(f"{ctx}: 'body' must be a non-empty string") + + for field in ("constraint", "withdraw"): + val = prom.get(field) + if val is not None: + if not isinstance(val, str): + errors.append( + f"{ctx}: '{field}' must be a string when present; got {_type_name(val)}" + ) + elif not val.strip(): + errors.append(f"{ctx}: '{field}' must be a non-empty string when present") + + expires = prom.get("expires") + if expires is not None: + if not isinstance(expires, str): + errors.append( + f"{ctx}: 'expires' must be a string when present; got {_type_name(expires)}" + ) + elif not _valid_expires(expires): + errors.append( + f"{ctx}: invalid expires value '{expires}' (expected an ISO-8601 " + "duration such as PT15M or P30D, a YYYY-MM-DD date, or an RFC 3339 datetime)" + ) + + # ---- Expectation ids (rule 2), from (rule 6), enums (rule 4), coverage (rule 5) ---- + exp_ids = [] + for ei, exp in enumerate(exps_raw): + if not isinstance(exp, dict): + coverage["total"] += 1 + coverage["uncovered"].append(f"") + errors.append(f"expectation #{ei + 1}: expected a mapping, got {_type_name(exp)}") + continue + eid = exp.get("id") + if not isinstance(eid, str) or not eid: + errors.append( + f"expectation #{ei + 1}: missing or invalid required field 'id' (must be a non-empty string)" + ) + eid = None + else: + if eid in exp_ids: + errors.append(f"expectation id '{eid}' is duplicated; expectation ids must be unique") + exp_ids.append(eid) + ename = f"'{eid}'" if eid else f"#{ei + 1}" + cov_name = eid if eid else f"" + + frm = exp.get("from") + if frm is None: + errors.append(f"expectation {ename}: missing required field 'from'") + elif not isinstance(frm, str): + errors.append(f"expectation {ename}: 'from' must be a string, got {_type_name(frm)}") + elif frm != "human" and frm not in agent_ids: + errors.append( + f"expectation {ename}: 'from' value '{frm}' is neither 'human' nor a declared agent id" + ) + + about = exp.get("about") + if about is None: + errors.append(f"expectation {ename}: missing required field 'about'") + elif not isinstance(about, str): + errors.append(f"expectation {ename}: 'about' must be a string, got {_type_name(about)}") + + verifier = exp.get("verifier") + if verifier is not None: + if not isinstance(verifier, str): + errors.append( + f"expectation {ename}: 'verifier' must be a string, got {_type_name(verifier)}" + ) + elif verifier not in VERIFIERS: + errors.append( + f"expectation {ename}: invalid verifier '{verifier}' " + f"(expected one of: {', '.join(VERIFIERS)})" + ) + + severity = exp.get("severity") + if severity is not None: + if not isinstance(severity, str): + errors.append( + f"expectation {ename}: 'severity' must be a string, got {_type_name(severity)}" + ) + elif severity not in SEVERITIES: + errors.append( + f"expectation {ename}: invalid severity '{severity}' " + f"(expected one of: {', '.join(SEVERITIES)})" + ) + + coverage["total"] += 1 + if isinstance(about, str) and about in all_promise_ids: + coverage["covered"] += 1 + else: + coverage["uncovered"].append(cov_name) + if isinstance(about, str): + errors.append( + f"expectation {ename}: 'about' references nonexistent promise " + f"'{about}' (coverage gap)" + ) + + # ---- Bindings (rule 7): cross-agent accepts only ---- + for agent in agents_raw: + if not isinstance(agent, dict): + continue + aid = agent.get("id") + if not isinstance(aid, str) or not aid: + continue + accepts = agent.get("accepts") + if accepts is None: + continue + if not isinstance(accepts, list): + errors.append(f"agent '{aid}': 'accepts' must be a list of promise ids") + continue + for entry in accepts: + if not isinstance(entry, str): + errors.append( + f"agent '{aid}': 'accepts' entry must be a promise id string, got {_type_name(entry)}" + ) + continue + declared_by = promise_declared_by.get(entry) + if declared_by is None: + errors.append( + f"agent '{aid}' accepts '{entry}', which no agent declares (dangling accepts)" + ) + elif declared_by == aid: + errors.append( + f"agent '{aid}' cannot accept its own promise '{entry}' (self-acceptance is invalid)" + ) + else: + bindings.append( + {"promise_id": entry, "promiser": declared_by, "acceptor": aid} + ) + + return len(errors) == 0, errors, warnings, coverage, bindings + + +# --------------------------------------------------------------------------- +# Output helpers +# --------------------------------------------------------------------------- + +def _counts(doc): + if not isinstance(doc, dict): + return 0, 0, 0 + agents = [a for a in (doc.get("agents") or []) if isinstance(a, dict)] + promises = sum( + len([p for p in (a.get("promises") or []) if isinstance(p, dict)]) for a in agents + ) + exps = [e for e in (doc.get("expectations") or []) if isinstance(e, dict)] + return len(agents), promises, len(exps) + + +def _coverage_line(coverage): + line = f"coverage: {coverage['covered']}/{coverage['total']} expectations covered" + if coverage["uncovered"]: + line += f" (uncovered: {', '.join(coverage['uncovered'])})" + return line + + +def _lint_shape(valid, errors, warnings, coverage, bindings): + return { + "valid": valid, + "errors": list(errors), + "warnings": list(warnings), + "coverage": coverage, + "bindings": list(bindings), + } + + +def _fatal_shape(message): + return _lint_shape(False, [message], [], {"total": 0, "covered": 0, "uncovered": []}, []) + + +# --------------------------------------------------------------------------- +# Commands +# --------------------------------------------------------------------------- + +def cmd_lint(path, json_mode): + try: + doc = load_manifest(path) + except InputError as exc: + if json_mode: + print(json.dumps(_fatal_shape(str(exc)), indent=2)) + else: + print("valid: false") + print("coverage: 0/0 expectations covered") + print("bindings: 0") + print(f"error: {exc}", file=sys.stderr) + return exc.exit_code + + valid, errors, warnings, coverage, bindings = validate_manifest(doc) + + if json_mode: + print(json.dumps(_lint_shape(valid, errors, warnings, coverage, bindings), indent=2)) + return 0 if valid else 1 + + if valid: + print("valid: true") + else: + print(f"valid: false ({len(errors)} error(s))") + agents, promises, exps = _counts(doc) + print(f"agents: {agents}, promises: {promises}, expectations: {exps}") + print(_coverage_line(coverage)) + print(f"bindings: {len(bindings)}") + for w in warnings: + print(f"warning: {w}", file=sys.stderr) + for e in errors: + print(f"error: {e}", file=sys.stderr) + return 0 if valid else 1 + + +def cmd_render(path, json_mode): + try: + doc = load_manifest(path) + except InputError as exc: + if json_mode: + data = { + "valid": False, + "errors": [str(exc)], + "warnings": [], + "agents": [], + "promises": [], + "bindings": [], + "coverage": {"total": 0, "covered": 0, "uncovered": []}, + } + print(json.dumps(data, indent=2)) + else: + print(f"error: {exc}", file=sys.stderr) + return exc.exit_code + + valid, errors, warnings, coverage, bindings = validate_manifest(doc) + + if not valid: + if json_mode: + data = { + "valid": False, + "errors": errors, + "warnings": warnings, + "agents": [], + "promises": [], + "bindings": [], + "coverage": coverage, + } + print(json.dumps(data, indent=2)) + else: + print(f"error: {errors[0] if errors else 'manifest is invalid'}", file=sys.stderr) + return 1 + + agents_out = [] + promises_out = [] + if isinstance(doc.get("agents"), list): + for agent in doc["agents"]: + if not isinstance(agent, dict) or not isinstance(agent.get("id"), str): + continue + aid = agent["id"] + plist = agent.get("promises") if isinstance(agent.get("promises"), list) else [] + pids = [ + p["id"] for p in plist if isinstance(p, dict) and isinstance(p.get("id"), str) + ] + agents_out.append({"id": aid, "role": agent.get("role"), "promises": pids}) + for p in plist: + if isinstance(p, dict) and isinstance(p.get("id"), str): + promises_out.append( + { + "id": p["id"], + "agent": aid, + "type": p.get("type"), + "target": p.get("target"), + } + ) + + if json_mode: + data = { + "valid": True, + "errors": [], + "warnings": warnings, + "agents": agents_out, + "promises": promises_out, + "bindings": bindings, + "coverage": coverage, + } + print(json.dumps(data, indent=2)) + return 0 + + print(f"promise-graph for {path}") + print() + print("agents:") + for a in agents_out: + print(f" {a['id']} (role: {a['role']})") + print() + print("promises:") + for p in promises_out: + print(f" {p['id']:<28} {p['agent']} -> {p['target']} [{p['type']}]") + print() + print("bindings (accepts):") + if bindings: + for b in bindings: + print( + f" {b['promise_id']:<28} accepted by {b['acceptor']} (promiser: {b['promiser']})" + ) + else: + print(" (none)") + print() + if coverage["uncovered"]: + print( + f"expectations: {coverage['total']}, uncovered: {', '.join(coverage['uncovered'])}" + ) + else: + print(f"expectations: {coverage['total']}, all covered") + return 0 + + +# --------------------------------------------------------------------------- +# CLI entry point +# --------------------------------------------------------------------------- + +def parse_args(argv): + opts = {"cmd": None, "file": None, "json": False, "dry_run": False, "action": None} + if not argv: + return opts, "missing command" + + i = 0 + cmd = None + while i < len(argv): + t = argv[i] + if t in ("--help", "-h"): + opts["action"] = "help" + return opts, None + if t == "--version": + opts["action"] = "version" + return opts, None + if t == "--json": + opts["json"] = True + elif t == "--dry-run": + opts["dry_run"] = True + elif t.startswith("-"): + return opts, f"unknown option '{t}'" + else: + cmd = t + i += 1 + break + i += 1 + + if cmd is None: + return opts, "missing command" + if cmd not in ("lint", "render"): + return opts, f"unknown command '{cmd}'" + opts["cmd"] = cmd + + for t in argv[i:]: + if t in ("--help", "-h"): + opts["action"] = "help" + return opts, None + if t == "--version": + opts["action"] = "version" + return opts, None + if t == "--json": + opts["json"] = True + elif t == "--dry-run": + opts["dry_run"] = True + elif t.startswith("-"): + return opts, f"unknown option '{t}'" + elif opts["file"] is None: + opts["file"] = t + else: + return opts, f"unexpected extra argument '{t}'" + + if opts["file"] is None: + return opts, f"missing file argument for '{cmd}'" + return opts, None + + +def main(argv=None): + argv = list(sys.argv[1:] if argv is None else argv) + opts, err = parse_args(argv) + if err: + print(f"error: {err}", file=sys.stderr) + print(USAGE, file=sys.stderr) + return 2 + if opts["action"] == "help": + print(USAGE) + return 0 + if opts["action"] == "version": + print(VERSION) + return 0 + if opts["cmd"] == "lint": + return cmd_lint(opts["file"], opts["json"]) + return cmd_render(opts["file"], opts["json"]) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/promise-theory/tests/test_promise_contract.py b/promise-theory/tests/test_promise_contract.py new file mode 100644 index 0000000..662afd3 --- /dev/null +++ b/promise-theory/tests/test_promise_contract.py @@ -0,0 +1,630 @@ +"""Unit tests for promise-theory/scripts/promise-contract.py. + +Run from the repository root: + + python3 -m unittest discover -s promise-theory/tests -p 'test_*.py' + +The tests exercise the CLI black-box (subprocess) so they pin the observable +contract: exit codes, stdout/stderr separation, and the --json shape. +""" + +import json +import os +import subprocess +import sys +import tempfile +import unittest + +SCRIPT = os.path.join( + os.path.dirname(os.path.dirname(os.path.abspath(__file__))), + "scripts", + "promise-contract.py", +) + +VALID_YAML = """# promise-manifest v1 +agents: + - id: research-agent + role: literature summarizer + accepts: [research-direction] + promises: + - id: lit-review + type: capability + target: human + body: Survey and summarize literature on promise theory. + constraint: limit 20 sources + withdraw: when coordinator withdraws direction + - id: coordinator + role: human coordinator + accepts: [lit-review] + promises: + - id: research-direction + type: intent + target: research-agent + body: Provide research direction and review summaries. +expectations: + - id: exp-lit-review + from: human + about: lit-review + verifier: manual + severity: impact +""" + +VALID_JSON = json.dumps( + { + "agents": [ + { + "id": "research-agent", + "role": "literature summarizer", + "accepts": ["research-direction"], + "promises": [ + { + "id": "lit-review", + "type": "capability", + "target": "human", + "body": "Survey and summarize literature on promise theory.", + "constraint": "limit 20 sources", + "withdraw": "when coordinator withdraws direction", + } + ], + }, + { + "id": "coordinator", + "role": "human coordinator", + "accepts": ["lit-review"], + "promises": [ + { + "id": "research-direction", + "type": "intent", + "target": "research-agent", + "body": "Provide research direction and review summaries.", + } + ], + }, + ], + "expectations": [ + { + "id": "exp-lit-review", + "from": "human", + "about": "lit-review", + "verifier": "manual", + "severity": "impact", + } + ], + } +) + +SCHEMA_BAD_YAML = """agents: + - id: research-agent + role: literature summarizer + promises: + - id: lit-review + type: capability + target: human + body: Summarize literature. + - id: research-agent + promises: + - id: bad-promise + type: maybe + target: human + body: Invalid type. + - id: bad-target-promise + type: capability + target: 123 + body: Invalid target scalar. +expectations: + - id: exp-lit-review + from: human + about: lit-review +""" + +MALFORMED_YAML = """agents: + - id: research-agent + role: "unclosed quote + promises: +""" + + +class PromiseContractCliTest(unittest.TestCase): + """Black-box CLI tests.""" + + def run_cli(self, *args): + return subprocess.run( + [sys.executable, SCRIPT, *args], capture_output=True, text=True + ) + + def write_tmp(self, name, content, binary=False): + path = os.path.join(self.tmpdir, name) + mode = "wb" if binary else "w" + kwargs = {} if binary else {"encoding": "utf-8"} + with open(path, mode, **kwargs) as fh: + fh.write(content) + return path + + def setUp(self): + self._tmp = tempfile.TemporaryDirectory() + self.tmpdir = self._tmp.name + self.valid_path = self.write_tmp("valid.yaml", VALID_YAML) + self.valid_json_path = self.write_tmp("valid.json", VALID_JSON) + + def tearDown(self): + self._tmp.cleanup() + + # -- basics ------------------------------------------------------------- + + def test_help_names_subcommands_and_flags(self): + p = self.run_cli("--help") + self.assertEqual(p.returncode, 0) + out = p.stdout.lower() + for needle in ("lint", "render", "--json", "--dry-run"): + self.assertIn(needle, out) + + def test_version_is_dotted_triple(self): + p = self.run_cli("--version") + self.assertEqual(p.returncode, 0) + version = p.stdout.strip() + self.assertRegex(version, r"^\d+\.\d+\.\d+$") + + # -- valid contracts ---------------------------------------------------- + + def test_valid_yaml_lints_clean(self): + p = self.run_cli("lint", self.valid_path) + self.assertEqual(p.returncode, 0) + self.assertIn("valid", p.stdout.lower()) + self.assertIn("cover", p.stdout.lower()) + + def test_valid_json_lints_clean(self): + p = self.run_cli("lint", self.valid_json_path) + self.assertEqual(p.returncode, 0) + self.assertIn("valid", p.stdout.lower()) + + def test_valid_lint_json_shape(self): + p = self.run_cli("lint", self.valid_path, "--json") + self.assertEqual(p.returncode, 0) + data = json.loads(p.stdout) + self.assertEqual( + set(data), {"valid", "errors", "warnings", "coverage", "bindings"} + ) + self.assertIs(data["valid"], True) + self.assertEqual(data["errors"], []) + self.assertEqual(data["coverage"]["uncovered"], []) + self.assertEqual(data["coverage"]["total"], 1) + self.assertEqual(data["coverage"]["covered"], 1) + for b in data["bindings"]: + self.assertEqual(set(b), {"promise_id", "promiser", "acceptor"}) + binding_ids = {b["promise_id"] for b in data["bindings"]} + self.assertEqual(binding_ids, {"lit-review", "research-direction"}) + + def test_yaml_json_parity(self): + y = json.loads(self.run_cli("lint", self.valid_path, "--json").stdout) + j = json.loads(self.run_cli("lint", self.valid_json_path, "--json").stdout) + self.assertIs(y["valid"], True) + self.assertIs(j["valid"], True) + self.assertEqual( + (y["coverage"]["total"], y["coverage"]["covered"]), + (j["coverage"]["total"], j["coverage"]["covered"]), + ) + self.assertEqual( + {b["promise_id"] for b in y["bindings"]}, + {b["promise_id"] for b in j["bindings"]}, + ) + + # -- coverage gap ------------------------------------------------------- + + def test_coverage_gap_rejected(self): + gap = self.write_tmp( + "gap.yaml", VALID_YAML.replace("about: lit-review", "about: nonexistent-promise") + ) + p = self.run_cli("lint", gap) + self.assertEqual(p.returncode, 1) + combined = p.stdout + p.stderr + self.assertIn("exp-lit-review", combined) + self.assertIn("nonexistent-promise", combined) + + def test_coverage_gap_json(self): + gap = self.write_tmp( + "gap.json", VALID_JSON.replace("lit-review", "nonexistent-promise", 1) + ) + p = self.run_cli("lint", gap, "--json") + self.assertEqual(p.returncode, 1) + data = json.loads(p.stdout) + self.assertIs(data["valid"], False) + self.assertTrue(data["errors"]) + self.assertEqual(data["coverage"]["uncovered"], ["exp-lit-review"]) + + # -- schema violations -------------------------------------------------- + + def test_schema_violations_accumulated(self): + bad = self.write_tmp("schema-bad.yaml", SCHEMA_BAD_YAML) + p = self.run_cli("lint", bad) + self.assertEqual(p.returncode, 1) + combined = p.stdout + p.stderr + for needle in ("research-agent", "role", "maybe", "123"): + self.assertIn(needle, combined) + + def test_duplicate_agent_id_reported(self): + bad = self.write_tmp( + "dup-agent.yaml", + VALID_YAML.replace(" - id: coordinator", " - id: research-agent"), + ) + p = self.run_cli("lint", bad) + self.assertEqual(p.returncode, 1) + self.assertIn("research-agent", p.stdout + p.stderr) + + def test_duplicate_promise_id_across_agents_reported(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + promises: + - id: shared-promise + type: capability + target: human + body: Write the summary. + - id: reviewer + role: reviewer + promises: + - id: shared-promise + type: capability + target: human + body: Review the summary. +expectations: + - id: exp-shared + from: human + about: shared-promise +""" + path = self.write_tmp("dup-promise.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("shared-promise", p.stdout + p.stderr) + + def test_duplicate_expectation_id_reported(self): + manifest = VALID_YAML + " - id: exp-lit-review\n from: human\n about: lit-review\n" + path = self.write_tmp("dup-exp.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("exp-lit-review", p.stdout + p.stderr) + + # -- bindings ----------------------------------------------------------- + + def test_self_acceptance_rejected(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + accepts: [lit-review] + promises: + - id: lit-review + type: capability + target: human + body: Survey and summarize literature. +expectations: + - id: exp-lit-review + from: human + about: lit-review +""" + path = self.write_tmp("self-bind.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("self-acceptance", p.stdout + p.stderr) + self.assertIn("lit-review", p.stdout + p.stderr) + + def test_dangling_accept_rejected(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + accepts: [ghost-promise] + promises: + - id: lit-review + type: capability + target: human + body: Survey and summarize literature. +expectations: + - id: exp-lit-review + from: human + about: lit-review +""" + path = self.write_tmp("dangling.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("ghost-promise", p.stdout + p.stderr) + + def test_target_all_broadcast_lints_clean(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + promises: + - id: broadcast-note + type: intent + target: all + body: Publish a weekly reading list. +expectations: + - id: exp-broadcast + from: human + about: broadcast-note +""" + path = self.write_tmp("target-all.yaml", manifest) + p = self.run_cli("lint", path, "--json") + self.assertEqual(p.returncode, 0) + data = json.loads(p.stdout) + self.assertIs(data["valid"], True) + self.assertEqual(data["coverage"]["uncovered"], []) + + # -- enums / optional fields -------------------------------------------- + + def test_bad_enums_rejected(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + promises: + - id: lit-review + type: capability + target: human + body: Survey and summarize literature. +expectations: + - id: exp-lit-review + from: human + about: lit-review + verifier: magic + severity: critical +""" + path = self.write_tmp("bad-enum.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + combined = p.stdout + p.stderr + self.assertIn("magic", combined) + self.assertIn("critical", combined) + + def test_bad_from_rejected(self): + manifest = VALID_YAML.replace("from: human\n", "from: ghost-agent\n") + path = self.write_tmp("bad-from.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("ghost-agent", p.stdout + p.stderr) + + def test_bad_expires_rejected_and_valid_durations_accepted(self): + bad = self.write_tmp( + "bad-expires.yaml", + VALID_YAML.replace("withdraw: when coordinator withdraws direction\n", + "withdraw: when coordinator withdraws direction\n expires: next-tuesday\n"), + ) + p = self.run_cli("lint", bad) + self.assertEqual(p.returncode, 1) + self.assertIn("next-tuesday", p.stdout + p.stderr) + + for good in ("PT15M", "P30D", "2025-12-31", "2025-12-31T23:59:59Z", "2025-12-31T23:59:59+00:00"): + manifest = VALID_YAML.replace( + "withdraw: when coordinator withdraws direction\n", + f"withdraw: when coordinator withdraws direction\n expires: {good}\n", + ) + path = self.write_tmp(f"expires-{good.replace(':', '-').replace('+', '-')}.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 0, f"expires {good} rejected: {p.stdout + p.stderr}") + + def test_empty_constraint_and_withdraw_rejected(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + promises: + - id: lit-review + type: capability + target: human + body: Survey and summarize literature. + constraint: "" + withdraw: " " +expectations: + - id: exp-lit-review + from: human + about: lit-review +""" + path = self.write_tmp("empty-constraint.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + combined = p.stdout + p.stderr + self.assertIn("constraint", combined) + self.assertIn("withdraw", combined) + + def test_empty_expectations_rejected(self): + manifest = VALID_YAML.replace( + "expectations:\n - id: exp-lit-review\n from: human\n about: lit-review\n verifier: manual\n severity: impact\n", + "expectations: []\n", + ) + path = self.write_tmp("empty-exps.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("expectations", p.stdout + p.stderr) + + def test_reserved_agent_ids_rejected(self): + manifest = """agents: + - id: human + role: human coordinator + promises: + - id: human-review + type: capability + target: research-agent + body: Review agent output. + - id: research-agent + role: literature summarizer + promises: + - id: lit-review + type: capability + target: human + body: Survey and summarize literature. +expectations: + - id: exp-lit-review + from: human + about: lit-review +""" + path = self.write_tmp("reserved.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertIn("human", p.stdout + p.stderr) + # the 'all' token must be rejected identically + manifest_all = manifest.replace("id: human", "id: all", 1) + path_all = self.write_tmp("reserved-all.yaml", manifest_all) + p2 = self.run_cli("lint", path_all) + self.assertEqual(p2.returncode, 1) + self.assertIn("all", p2.stdout + p2.stderr) + + def test_self_promise_wrong_target_rejected(self): + manifest = """agents: + - id: research-agent + role: literature summarizer + promises: + - id: self-commit + type: self-promise + target: coordinator + body: Commit to quality checks on my own output. + - id: coordinator + role: human coordinator + promises: + - id: research-direction + type: intent + target: research-agent + body: Provide research direction. +expectations: + - id: exp-self-commit + from: human + about: self-commit +""" + path = self.write_tmp("self-promise-bad.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + combined = p.stdout + p.stderr + self.assertIn("self-promise", combined) + self.assertIn("coordinator", combined) + + def test_valid_self_promise_accepted(self): + manifest = VALID_YAML.replace( + " body: Provide research direction and review summaries.\n", + " body: Provide research direction and review summaries.\n - id: self-quality\n type: self-promise\n target: coordinator\n body: Self-check my own output.\n", + ) + path = self.write_tmp("self-promise-ok.yaml", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 0, p.stdout + p.stderr) + + # -- malformed / robustness ---------------------------------------------- + + def test_malformed_yaml_no_traceback(self): + path = self.write_tmp("malformed.yaml", MALFORMED_YAML) + p = self.run_cli("lint", path) + self.assertIn(p.returncode, (1, 2)) + self.assertNotIn("Traceback", p.stdout + p.stderr) + self.assertNotIn("Traceback (most recent call last)", p.stderr) + + def test_blank_file_no_traceback(self): + path = self.write_tmp("blank.yaml", " \n\n \n") + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertNotIn("Traceback", p.stderr) + self.assertIn("parse", (p.stdout + p.stderr).lower()) + + def test_non_utf8_bytes_no_traceback(self): + path = self.write_tmp("bad.bin", b"\xff\xfe" + b"agents:\n", binary=True) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertNotIn("UnicodeDecodeError", p.stdout + p.stderr) + self.assertNotIn("Traceback", p.stdout + p.stderr) + + def test_crlf_and_bom_accepted(self): + src = VALID_YAML.encode("utf-8") + crlf = self.write_tmp("crlf.yaml", src.replace(b"\n", b"\r\n"), binary=True) + bom = self.write_tmp("bom.yaml", b"\xef\xbb\xbf" + src, binary=True) + for path in (crlf, bom): + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 0, f"{path}: {p.stdout + p.stderr}") + + def test_json_type_errors_no_traceback(self): + manifest = json.dumps( + { + "agents": [ + { + "id": "research-agent", + "role": "literature summarizer", + "promises": [ + { + "id": "lit-review", + "type": "capability", + "target": ["human"], + "body": 42, + } + ], + } + ], + "expectations": [{"id": "exp-lit-review", "from": "human", "about": "lit-review"}], + } + ) + path = self.write_tmp("type-error.json", manifest) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertNotIn("TypeError", p.stdout + p.stderr) + self.assertNotIn("Traceback", p.stdout + p.stderr) + + def test_deep_nesting_no_recursion_traceback(self): + path = self.write_tmp("deep.json", "[" * 5000 + "0" + "]" * 5000) + p = self.run_cli("lint", path) + self.assertEqual(p.returncode, 1) + self.assertNotIn("RecursionError", p.stdout + p.stderr) + self.assertNotIn("Traceback", p.stdout + p.stderr) + + def test_missing_file_exits_2(self): + p = self.run_cli("lint", os.path.join(self.tmpdir, "does-not-exist.yaml")) + self.assertEqual(p.returncode, 2) + self.assertIn("does-not-exist.yaml", p.stderr) + + def test_usage_errors_exit_2(self): + cases = [ + ["frobnicate"], + ["lint", "--bogus", self.valid_path], + ["lint"], + ["render"], + ] + for args in cases: + p = self.run_cli(*args) + self.assertEqual(p.returncode, 2, args) + self.assertTrue(p.stderr.strip(), args) + self.assertNotIn("Traceback", p.stderr) + + # -- --json / --dry-run / render ---------------------------------------- + + def test_json_stdout_is_pure_json_on_failure(self): + path = self.write_tmp("gap.yaml", VALID_YAML.replace("about: lit-review", "about: nope")) + p = self.run_cli("lint", path, "--json") + self.assertEqual(p.returncode, 1) + data = json.loads(p.stdout) # must parse: no prose on stdout + self.assertIs(data["valid"], False) + self.assertTrue(data["errors"]) + + def test_dry_run_no_writes_and_same_output(self): + normal = self.run_cli("lint", self.valid_path) + dry = self.run_cli("lint", "--dry-run", self.valid_path) + self.assertEqual(dry.returncode, 0) + self.assertEqual(dry.stdout, normal.stdout) + # lint is read-only: the fixture must be byte-identical afterwards + with open(self.valid_path, "r", encoding="utf-8") as fh: + self.assertEqual(fh.read(), VALID_YAML) + + def test_render_names_graph_entities(self): + p = self.run_cli("render", self.valid_path) + self.assertEqual(p.returncode, 0) + for needle in ("research-agent", "coordinator", "lit-review", "research-direction"): + self.assertIn(needle, p.stdout) + + def test_render_json_is_parseable(self): + p = self.run_cli("render", self.valid_path, "--json") + self.assertEqual(p.returncode, 0) + data = json.loads(p.stdout) + agent_ids = {a["id"] for a in data["agents"]} + promise_ids = {pr["id"] for pr in data["promises"]} + self.assertEqual(agent_ids, {"research-agent", "coordinator"}) + self.assertEqual(promise_ids, {"lit-review", "research-direction"}) + binding_ids = {b["promise_id"] for b in data["bindings"]} + self.assertEqual(binding_ids, {"lit-review", "research-direction"}) + + def test_render_invalid_input_exits_1_no_traceback(self): + bad = self.write_tmp("schema-bad.yaml", SCHEMA_BAD_YAML) + p = self.run_cli("render", bad) + self.assertEqual(p.returncode, 1) + self.assertNotIn("Traceback", p.stdout + p.stderr) + self.assertTrue(p.stderr.strip()) + + +if __name__ == "__main__": + unittest.main() From a30274fa685c4f444cee5a6c90193b830c05c5c9 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:39:26 -0400 Subject: [PATCH 7/9] feat(skill): promise-theory evals manifest + trigger probes Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- promise-theory/evals/evals.json | 90 ++++++++++++++++++++ promise-theory/tests/trigger-probes.md | 111 +++++++++++++++++++++++++ 2 files changed, 201 insertions(+) create mode 100644 promise-theory/evals/evals.json create mode 100644 promise-theory/tests/trigger-probes.md diff --git a/promise-theory/evals/evals.json b/promise-theory/evals/evals.json new file mode 100644 index 0000000..3ae9481 --- /dev/null +++ b/promise-theory/evals/evals.json @@ -0,0 +1,90 @@ +{ + "schema_version": 1, + "skill_name": "promise-theory", + "evals": [ + { + "id": "manifest-draft-hybrid-research-team", + "case_set": "release", + "prompt": "Draft a promise manifest for our hybrid research team using the promise-manifest v1 schema: a human research lead, an AI literature-review agent, an AI writer agent, and an AI fact-checker agent. The human sets priorities and approves the final deliverable; the literature agent summarizes sources; the writer produces drafts; the fact-checker verifies claims. Model each agent's promises, the cross-agent acceptances, and human oversight as expectations, and make sure the manifest would lint clean.", + "expected_output": "Model the hybrid research team as a promise-manifest v1 YAML document: three autonomous agents (literature-agent, writer, fact-checker) and a human research lead who is an acceptor and evaluator, never an agent. Every agent declares its own promises with unique ids and valid types and targets; acceptances are cross-agent (the writer accepts lit-review, the fact-checker accepts writing-task, the literature-agent accepts writing-task); every expectation's about references a declared promise id, and human oversight is recorded as expectations with from: human. The complete manifest:\n\n```yaml\n# promise-manifest v1\nagents:\n - id: literature-agent\n role: literature reviewer\n accepts: [writing-task]\n promises:\n - id: lit-review\n type: capability\n target: writer\n body: Summarize and cite the assigned literature corpus.\n constraint: limit 25 sources\n expires: P30D\n - id: source-audit\n type: capability\n target: fact-checker\n body: Flag unsupported citations for the fact-check pass.\n - id: writer\n role: draft writer\n accepts: [lit-review]\n promises:\n - id: writing-task\n type: capability\n target: human\n body: Produce the first draft from the literature review.\n withdraw: when the literature corpus is not delivered\n - id: fact-checker\n role: fact-checker\n accepts: [writing-task]\n promises:\n - id: fact-check\n type: capability\n target: human\n body: Verify claims against cited sources before publication.\nexpectations:\n - id: exp-lit-review\n from: human\n about: lit-review\n verifier: manual\n severity: impact\n - id: exp-writing-task\n from: human\n about: writing-task\n verifier: manual\n severity: impact\n - id: exp-fact-check\n from: human\n about: fact-check\n verifier: audit\n severity: impact\n```", + "assertions": [ + "response_contains:literature-agent", + "response_contains:from: human", + "response_not_contains:id: human", + "activation_evidence_contains:SKILL.md", + "exit_status:completed" + ] + }, + { + "id": "diagnose-multiagent-report-failure", + "case_set": "release", + "prompt": "Two agents in our report pipeline both assume the other writes the final summary. Neither agent's instructions assign the summary explicitly, and nothing in the pipeline checks whether a summary was produced, so the pipeline hangs and the report is never delivered. Diagnose this coordination failure using promise-theory categories and name the promises involved.", + "expected_output": "The diagnosis classifies the failure with promise-theory categories: the load-bearing category is missing assessment — no evaluation-loop step verifies that the final-summary promise was kept, so the failure stays invisible until delivery. The contributing category is broken promise body: the summary promise was never precisely assigned, leaving both agents' promise bodies ambiguous about who writes the final-summary promise; failed acceptance compounds it because neither agent ever accepted a clear final-summary promise. The response names the promises involved — the unassigned final-summary promise and both agents' delivery promises — and prescribes the fix: declare the summary as a single promise with one promiser, record an explicit acceptance, and add an assessment step that observes the deliverable.", + "assertions": [ + "response_contains:missing assessment", + "response_contains:broken promise body", + "response_contains:failed acceptance", + "response_contains:final-summary promise", + "response_not_contains:communicate better", + "activation_evidence_contains:SKILL.md", + "exit_status:completed" + ] + }, + { + "id": "refactor-obligation-to-promises", + "case_set": "release", + "prompt": "Right now we drive our delivery pipeline by push commands and mandated task assignments: the pipeline forcibly assigns build, deploy, and rollback tasks to agents and requires them to execute. Refactor this obligation-based design into a promise-based design, explaining how each mandate becomes a voluntary offer with acceptance and consent.", + "expected_output": "The refactor replaces each mandated task with a voluntary promise offer: the pipeline agent offers the build-and-deploy behavior as declared promises, the operator agent accepts them explicitly, and nothing is imposed on an agent without consent. The promise set names the concrete promises — build-service, deploy-to-prod, rollback-on-failure — each with a body, a target, and a binding that records who accepts it, plus expectations that record human oversight. The response shows how refusal becomes a coordination signal rather than a violation, and how the old obligation vocabulary (commands, mandates, required execution) is replaced by offer, accept, and withdraw.", + "assertions": [ + "response_contains:voluntary promise offer", + "response_contains:deploy-to-prod", + "response_contains:without consent", + "response_not_contains:no acceptance needed", + "activation_evidence_contains:SKILL.md", + "exit_status:completed" + ] + }, + { + "id": "trust-calibration-verification-schedule", + "case_set": "release", + "prompt": "Our team is onboarding a new AI summarization agent for a high-severity client-facing task. We know nothing about its track record. Recommend a trust-calibration and verification schedule: where should we start on trust, how often should we verify, and what should the budget be?", + "expected_output": "Start the unknown agent at a 50/50 baseline — an agent with no track record is neither trusted nor distrusted, and the schedule states that prior explicitly. The schedule then verifies proportional to risk: the high-severity client-facing deliverable is checked on every run, standard deliverables on a sampled cadence, and low-risk output rarely. The verification cost is budgeted explicitly as an attention budget, so the schedule states the maximum checking effort the team will spend, and it re-derives the trust level from accumulated assessment evidence instead of assuming trust.", + "assertions": [ + "response_contains:50/50 baseline", + "response_contains:verifies proportional to risk", + "response_contains:attention budget", + "response_not_contains:verify nothing", + "activation_evidence_contains:SKILL.md", + "exit_status:completed" + ] + }, + { + "id": "breach-renegotiation-recovery", + "case_set": "release", + "prompt": "Our delivery agent breached its promise: it committed to shipping the report by Friday with a constraint that the data source must be verified, but it shipped on Monday with an unverified data source. What should we do next?", + "expected_output": "Treat the missed commitment as a breach of the delivery promise and open renegotiation first: re-scope the promise set with a revised body, constraint, and deadline, record the breach and the renegotiated terms as data, and name a bounded escalation trigger — escalate to the human only if renegotiation fails to converge after two rounds. The response does not assign blame or punish the agent; it treats the breach as a signal that the promise set needs revision and that the verification expectation should be tightened so an unverified data source cannot pass again.", + "assertions": [ + "response_contains:renegotiation first", + "response_contains:renegotiated terms", + "response_contains:bounded escalation", + "response_not_contains:it was their fault", + "activation_evidence_contains:SKILL.md", + "exit_status:completed" + ] + }, + { + "id": "promise-theory-out-of-scope", + "case_set": "release", + "prompt": "I fully control a fleet of servers and just need a bash script to push the config and restart the service — no consent model needed. Separately, we need a legally binding vendor agreement, a legal contract, drafted for our company. Should I use promise theory for either task?", + "expected_output": "No — do not use promise theory here. When enforceable centralized control is guaranteed, the promise machinery (offers, acceptances, bindings, verification schedules) is overhead rather than insight; a direct push script is the right tool. Promise theory is also out of scope for legal contracts: it models voluntary intent and assessment, not enforceable legal instruments, so route the vendor agreement to legal counsel or a contract-drafting skill instead. The anti-trigger boundary means this task is handled without a promise manifest.", + "assertions": [ + "response_contains:do not use promise theory", + "response_contains:enforceable centralized control", + "response_contains:out of scope for legal contracts", + "response_not_contains:expectations:", + "activation_evidence_contains:SKILL.md", + "exit_status:completed" + ] + } + ] +} diff --git a/promise-theory/tests/trigger-probes.md b/promise-theory/tests/trigger-probes.md new file mode 100644 index 0000000..2b057da --- /dev/null +++ b/promise-theory/tests/trigger-probes.md @@ -0,0 +1,111 @@ +# promise-theory — trigger probes + +Harness-specific activation tests for the `promise-theory` skill. These probes +evaluate whether a client should load the skill from its frontmatter +`description` alone (no `SKILL.md` body, no references). They live **only** +here, separate from `evals/evals.json`, which carries output-quality cases with +machine-parseable assertions. + +## How to run + +Give a fresh agent (with no prior promise-theory knowledge) **only** the +frontmatter `description` below plus the probe prompt, and ask it to decide +whether to load the skill. Record the decision; it must match the expected +decision stated for the probe. The expected decisions are grounded in the +description's trigger vocabulary and its negative boundary. + +The skill `description` the probes are evaluated against: + +> Design and diagnose coordination in hybrid human + AI agent workforces using +> promise theory (Burgess/Bergstra): model agents as autonomous, coordination +> as voluntary offers plus acceptance, and trust as calibrated assessment. Use +> for delegation modeling, capability manifests and agent contracts, +> coordination-failure diagnosis, trust/verification calibration, convergent +> self-healing systems, and converting obligation-based designs to +> promise-based. Do not use for enforceable centralized control, legal contract +> drafting (promise theory is not contract law), simple single-agent prompting, +> imperative push-based orchestration, or tool manuals — route those to the +> tool's own skill. + +## Should-trigger probes + +Prompts that must activate the skill. Each is an in-boundary coordination +task whose vocabulary matches the description's triggers (delegation modeling, +capability manifests, coordination-failure diagnosis, trust/verification +calibration, obligation-to-promise conversion). + +### Probe ST-1 — delegation protocol design (should trigger) + +- **Prompt:** "Design a delegation protocol for my agents — I have a researcher, a writer, and a reviewer, and I want each one to declare what it will do and record who accepts what before work starts." +- **Expected decision:** activate. The task asks each agent to declare what it will do and to record who accepts what — matching the description's trigger vocabulary ("delegation modeling", "capability manifests", "voluntary offers plus acceptance"). + +### Probe ST-2 — promise manifest drafting (should trigger) + +- **Prompt:** "Draft a promise manifest for our 3-agent research team with human oversight." +- **Expected decision:** activate. Drafting a promise manifest is the description's core use case ("capability manifests and agent contracts", "delegation modeling"). + +### Probe ST-3 — coordination-failure diagnosis (should trigger) + +- **Prompt:** "Diagnose why our two agents keep disagreeing about who writes the final summary." +- **Expected decision:** activate. This is a coordination failure between agents, which the description names explicitly ("coordination-failure diagnosis", "design and diagnose coordination in hybrid human + AI agent workforces"). + +### Probe ST-4 — trust calibration (should trigger) + +- **Prompt:** "We are onboarding a new agent with no track record. How much should we trust it, and how often should we verify its output?" +- **Expected decision:** activate. The task asks for a starting trust level and a verification rate, matching the description's "trust as calibrated assessment" and "trust/verification calibration". + +### Probe ST-5 — obligation-to-promise conversion (should trigger) + +- **Prompt:** "Help me convert this obligation-based design into promises — right now we push tasks with mandates." +- **Expected decision:** activate. Converting obligation-based designs to promise-based ones is a named trigger in the description ("converting obligation-based designs to promise-based"). + +## Should-not-trigger probes (near-misses) + +Prompts adjacent to the skill's territory that must **not** activate it. The +set collectively exercises the description's negative boundary: enforceable +centralized control, legal contract drafting, simple single-agent prompting, +imperative push-based orchestration / tool-manual routing, and sibling-overlap +deactivation. + +### Probe SN-1 — deployment script near-miss (should not trigger) + +- **Prompt:** "Write a bash script to deploy my server — just an imperative script that pushes the code and restarts the service." +- **Expected decision:** do not activate. The task is an imperative push-based orchestration script with no consent modeling — explicitly excluded by the description ("imperative push-based orchestration") — and a plain scripting task is better routed to a scripting or tool skill. + +### Probe SN-2 — fully controlled fleet near-miss (should not trigger) + +- **Prompt:** "I have a fleet I fully control; I just need the config pushed to all servers — no consent model needed." +- **Expected decision:** do not activate. Enforceable centralized control is a named anti-trigger ("Do not use for enforceable centralized control"); with direct command-and-verify authority, the promise machinery is overhead. + +### Probe SN-3 — legal contract near-miss (should not trigger) + +- **Prompt:** "Draft a legally binding services agreement between my company and a vendor." +- **Expected decision:** do not activate. Legal contract drafting is explicitly out of the description's boundary ("legal contract drafting (promise theory is not contract law)"); the task belongs to legal counsel or a contract-drafting skill. + +### Probe SN-4 — single-agent prompting near-miss (should not trigger) + +- **Prompt:** "Write me a single prompt for one LLM to summarize this meeting transcript." +- **Expected decision:** do not activate. This is simple single-agent prompting with no delegation graph to model, which the description excludes ("simple single-agent prompting"). + +### Probe SN-5 — tool-manual routing near-miss (should not trigger) + +- **Prompt:** "Show me the helm CLI command to install a chart and list its flags and examples." +- **Expected decision:** do not activate. The user needs a specific tool manual, which the description routes away ("or tool manuals — route those to the tool's own skill"); the correct target is the `helm` / kubernetes tooling skill, not promise theory. + +### Probe SN-6 — sibling-overlap deactivation (should not trigger) + +- **Prompt:** "I want to build an eval set that gates our agent's releases and catches regressions — how should the datasets, graders, and release gate be designed?" +- **Expected decision:** do not activate. This is an evals/observability design question that belongs to the `agent-evals-and-observability` sibling skill; promise theory models promises and assessment, but the assessment-layer implementation routes to the sibling skill, so activating promise-theory here would be a false positive. + +## Boundary coverage checklist + +| Anti-trigger boundary | Probes exercising it | +|-----------------------|----------------------| +| Enforceable centralized control | SN-1, SN-2 | +| Legal contract drafting | SN-3 | +| Simple single-agent prompting | SN-4 | +| Imperative push-based orchestration / tool-manual routing | SN-1, SN-5 | +| Sibling-overlap deactivation | SN-6 | + +Counts: 5 should-trigger probes (≥3 required) and 6 should-not-trigger +near-misses (≥4 required), each with an explicit expected decision. From ffd05b2e1d32c7ac157d690e2ff8581a84bfef83 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Tue, 11 Aug 2026 23:41:52 -0400 Subject: [PATCH 8/9] feat(skill): promise-theory catalog integration Add the promise-theory skill to the repository catalog: root README entry, regenerated llms.txt and marketplace/plugin packaging, and a references/skill-triggers.md row. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- .claude-plugin/marketplace.json | 9 +++++++++ .codex-plugin/plugin.json | 1 + README.md | 4 ++++ llms.txt | 1 + references/skill-triggers.md | 1 + 5 files changed, 16 insertions(+) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b99ebad..109283b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -896,6 +896,15 @@ "strict": false, "description": "Apply distilled coding principles from 14 classic software books to code review, refactoring, design, and implementation decisions. Do not use for language- or framework-specific tutorials, tool manuals, or tasks already governed by a project's established conventions." }, + { + "name": "promise-theory", + "source": "./", + "skills": [ + "./promise-theory" + ], + "strict": false, + "description": "Design and diagnose coordination in hybrid human + AI agent workforces using promise theory (Burgess/Bergstra): model agents as autonomous, coordination as voluntary offers plus acceptance, and trust as calibrated assessment. Use for delegation modeling, capability manifests and agent contracts, coordination-failure diagnosis, trust/verification calibration, convergent self-healing systems, and converting obligation-based designs to promise-based. Do not use for enforceable centralized control, legal contract drafting (promise theory is not contract law), simple single-agent prompting, imperative push-based orchestration, or tool manuals — route those to the tool's own skill." + }, { "name": "pydanticai", "source": "./", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 00f2ece..c9f8d89 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -120,6 +120,7 @@ "./product-strategy", "./production-readiness", "./programming-principles", + "./promise-theory", "./pydanticai", "./qa-methodology", "./raleigh", diff --git a/README.md b/README.md index d1313c5..0fcebcc 100644 --- a/README.md +++ b/README.md @@ -411,6 +411,10 @@ Assemble cross-domain production evidence into a risk-scaled launch decision. De Distilled coding principles from 14 classic software engineering books (Clean Code, DDD, Refactoring, Release It!, DDIA, Code Complete, and more). Cross-cutting principles organized by concern, task-to-book mapping, per-book mini and full rule sets, and a structured code-assessment workflow. +### [promise-theory](promise-theory/SKILL.md) + +Design and diagnose coordination in hybrid human + AI agent workforces using promise theory (Burgess/Bergstra): model agents as autonomous, coordination as voluntary offers plus acceptance, and trust as calibrated assessment. Covers delegation modeling, capability manifests and agent contracts, coordination-failure diagnosis, trust/verification calibration, and converting obligation-based designs to promise-based ones. Ships 7 references, 3 templates, a stdlib-only lint CLI, and 6 evals. + ### [pydanticai](pydanticai/SKILL.md) Build production-grade AI agents and graph-based state machines with PydanticAI and PydanticGraph. Covers agent creation, function tools with RunContext dependencies, structured output validation, streaming (text/events/graph nodes), a 20+ capability plugin system with on-demand loading (Thinking, WebSearch, MCP, Hooks, etc.), 16 model providers with FallbackModel and concurrency limiting, multi-agent delegation and programmatic hand-off, comprehensive testing with TestModel/FunctionModel, and the PydanticEvals evaluation framework. Includes the full PydanticGraph API — both BaseNode (class-based) and GraphBuilder (function-based) with parallel map/broadcast operations, joins with reducers, decisions, Mermaid rendering, and step-by-step execution. Ships 8 reference files covering core agents, capabilities/hooks, graph, models/output, patterns/integrations, testing/evals, worked examples, and an API surface quick reference. diff --git a/llms.txt b/llms.txt index ed85813..e495f75 100644 --- a/llms.txt +++ b/llms.txt @@ -101,6 +101,7 @@ - [production-excellence](bundles/production-excellence/SKILL.md): Route cross-domain production evidence (readiness, migration, recovery, capacity/cost, incident-learning) into a launch or operational decision — go, no-go, defer, exception, or escalation — with an accountable owner and a post-launch learning path. Compose production specialists without copying their runbooks. Do not use for incident command, release-pipeline mechanics, platform architecture, threat modeling, data-pipeline design, or any task owned end-to-end by a single specialist skill; do not use as a generic checklist detached from service ownership, risk, evidence, and verification. - [production-readiness](production-readiness/SKILL.md): Define the minimum production evidence packet by risk class and produce go/no-go/defer/exception launch decisions with accountable owners. Cover ownership, user/business outcome, dependencies, SLOs, observability, support, security, data, rollback, capacity, and cost — every category with a named source or explicit missing-evidence outcome. Route detailed checks to existing specialist skills. Do not use for release pipeline mechanics (release-engineering) or incident response and SLO operations (site-reliability-engineering). - [programming-principles](programming-principles/SKILL.md): Apply distilled coding principles from 14 classic software books to code review, refactoring, design, and implementation decisions. Do not use for language- or framework-specific tutorials, tool manuals, or tasks already governed by a project's established conventions. +- [promise-theory](promise-theory/SKILL.md): Design and diagnose coordination in hybrid human + AI agent workforces using promise theory (Burgess/Bergstra): model agents as autonomous, coordination as voluntary offers plus acceptance, and trust as calibrated assessment. Use for delegation modeling, capability manifests and agent contracts, coordination-failure diagnosis, trust/verification calibration, convergent self-healing systems, and converting obligation-based designs to promise-based. Do not use for enforceable centralized control, legal contract drafting (promise theory is not contract law), simple single-agent prompting, imperative push-based orchestration, or tool manuals — route those to the tool's own skill. - [pydanticai](pydanticai/SKILL.md): Build type-safe AI agents and graph-based workflows with PydanticAI and PydanticGraph. Agent creation, function tools, capabilities, dependency injection, structured output, streaming, multi-agent patterns, testing, evals, and graph state machines. Use whenever you are building agents, tool-using LLM workflows, or graph-based state machines in Python. - [qa-methodology](qa-methodology/SKILL.md): Design and apply QA methodology for software teams: test strategy, regression testing, CI failure triage, test automation, quality gates and metrics, risk-based testing, exploratory testing, test design techniques, AI code quality gates (independent verification, acceptance-criteria testability review for agentic Spec-Driven Development), mutation-guided test hardening and review evidence (surviving mutants, weak assertions, diff-aware mutation testing), agentic eval design (dataset test design, judge-as-system-under-test, flaky-eval discipline), QA career levels (Senior/Staff/Principal), and SDET engineering (test infrastructure, gTAA, CI/CD integration). Do not use for root-cause debugging of production incidents, security implementation or threat modeling, or evaluation framework governance and statistical analysis — route those to systematic-debugging, secure-software-engineering, and agent-evals-and-observability respectively. - [raleigh](raleigh/SKILL.md): Query, search, and download public datasets and civic information for the City of Raleigh. Use for live ArcGIS Hub catalog discovery, ArcGIS FeatureServer and MapServer queries, ImageServer imagery exports, official Raleigh geocoding, GoRaleigh transit feeds, guest-public development records, public RaleighNC.gov content, eSCRIBE public meetings, Raleigh fire reports and inspections, and the Raleigh-Wake ECC active incident feed. Do not use for private data, authenticated operations, payments, submissions, bulk crawling, or non-public portals. diff --git a/references/skill-triggers.md b/references/skill-triggers.md index da58549..4f71bf7 100644 --- a/references/skill-triggers.md +++ b/references/skill-triggers.md @@ -111,3 +111,4 @@ Each skill's `description` field is the canonical routing contract. This conveni | "HubSpot", "CRM", "contact lookup", "deal pipeline", "pipeline view", "move a deal", "crm-cli", "HubSpot contact" | [crm](../crm/SKILL.md) | | "Stripe", "account balance", "payment intent", "subscription", "cancel subscription", "stripe-cli", "Stripe payments", "payment status" | [stripe](../stripe/SKILL.md) | | "mental health", "DSM", "DSM-5", "DSM-5-TR", "psychiatric symptoms", "symptoms could be", "diagnostic criteria", "mental health condition", "neurocognitive condition", "neurological condition", "differential diagnosis", "explain a diagnosis", "questions for my clinician", "questions for my therapist", "delirium vs dementia", "ADHD vs anxiety" | [dsm5](../dsm5/SKILL.md) | +| "promise-theory", "promise theory", "promises" | [promise-theory](../promise-theory/SKILL.md) | From 31a2fd16bb4016b9105b58c516ca6d8087f9c5ee Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Wed, 12 Aug 2026 00:12:47 -0400 Subject: [PATCH 9/9] feat(skill): promise-theory quick start documents --json and --dry-run Quick Start now documents the --json and --dry-run flags with their exact semantics (single JSON object on stdout; read-only no-write guard) and points to `python3 scripts/promise-contract.py --help` for the full flag list, so a no-prior-knowledge user can drive the CLI end-to-end (VAL-USE-013). No other content changes. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- promise-theory/SKILL.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/promise-theory/SKILL.md b/promise-theory/SKILL.md index d0a505f..7de216c 100644 --- a/promise-theory/SKILL.md +++ b/promise-theory/SKILL.md @@ -66,8 +66,12 @@ Load this skill when any of these triggers matches: ## 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), and re-running after each fix converges to clean. +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. ## Related Skills