Merge branch 'main' into dependabot/pip/loguru-gte-0.7.3

.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": "./",
@@ -995,6 +1004,15 @@
       "strict": false,
       "description": "Plan authorized security reviews with threat modeling, architecture and dependency audits, and vulnerability classification. Use for scoped defensive security assessment. Do not use for offensive operations, unauthorized testing, or security control implementation."
     },
+    {
+      "name": "semantic-spacetime",
+      "source": "./",
+      "skills": [
+        "./semantic-spacetime"
+      ],
+      "strict": false,
+      "description": "Model and diagnose shared semantic ground between agents with Semantic Spacetime (Mark Burgess, 2014-2025): a discrete graph model of meaning over time, where local proper time replaces global clocks, causality is cooperative promises, and gamma(3,4) graphs expose semantic drift, world model divergence, and absorbing states. Use for designing convergent self-healing coordination, modeling intent and trajectories over time, mapping promises onto spacetime, diagnosing semantic drift or dead-ends, and analyzing temporal blindness in agents. Do not use for physics or relativity, pure vector embeddings or RAG without temporal-causal structure, enforceable centralized control, simple single-agent prompting, or tool manuals — route those to the appropriate skill."
+    },
     {
       "name": "seo-audit",
       "source": "./",

.codex-plugin/plugin.json

@@ -120,6 +120,7 @@
     "./product-strategy",
     "./production-readiness",
     "./programming-principles",
+    "./promise-theory",
     "./pydanticai",
     "./qa-methodology",
     "./raleigh",
@@ -130,6 +131,7 @@
     "./restic",
     "./secure-software-engineering",
     "./security-audit-methodology",
+    "./semantic-spacetime",
     "./seo-audit",
     "./site-reliability-engineering",
     "./slack",

.github/workflows/droid-review.yml

@@ -0,0 +1,59 @@
+name: Droid Auto Review
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, reopened]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  droid-review:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+      # BYOK: register the DeepSeek V4 Flash custom model where the Droid CLI
+      # reads it (~/.factory/settings.json). The droid-action's `settings`
+      # input writes to ~/.factory/droid/settings.json, which the CLI does not
+      # read for customModels, so the model must be written here explicitly.
+      # The API key is referenced as ${DEEPSEEK_API_KEY} and expanded by the
+      # CLI from the step env at request time.
+      - name: Configure BYOK model (DeepSeek V4 Flash)
+        shell: bash
+        run: |
+          mkdir -p "$HOME/.factory"
+          cat > "$HOME/.factory/settings.json" <<'FACTORY_JSON'
+          {
+            "customModels": [
+              {
+                "model": "deepseek-v4-flash",
+                "displayName": "DeepSeek V4 Flash (BYOK)",
+                "baseUrl": "https://api.deepseek.com/v1",
+                "apiKey": "${DEEPSEEK_API_KEY}",
+                "provider": "generic-chat-completion-api",
+                "maxOutputTokens": 16384
+              }
+            ]
+          }
+          FACTORY_JSON
+      - name: Run Droid Auto Review
+        uses: Factory-AI/droid-action@main
+        with:
+          factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+          automatic_review: true
+          automatic_security_review: true
+          review_model: deepseek-v4-flash
+          security_model: deepseek-v4-flash
+        env:
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

.github/workflows/droid.yml

@@ -0,0 +1,66 @@
+name: Droid Tag
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+  pull_request:
+    types: [opened, edited]
+
+jobs:
+  droid:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@droid')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@droid')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@droid')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@droid') || contains(github.event.issue.title, '@droid'))) ||
+      (github.event_name == 'pull_request' && (contains(github.event.pull_request.body, '@droid') || contains(github.event.pull_request.title, '@droid')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+      # BYOK: register the DeepSeek V4 Flash custom model where the Droid CLI
+      # reads it (~/.factory/settings.json). The droid-action's `settings`
+      # input writes to ~/.factory/droid/settings.json, which the CLI does not
+      # read for customModels, so the model must be written here explicitly.
+      # The API key is referenced as ${DEEPSEEK_API_KEY} and expanded by the
+      # CLI from the step env at request time.
+      - name: Configure BYOK model (DeepSeek V4 Flash)
+        shell: bash
+        run: |
+          mkdir -p "$HOME/.factory"
+          cat > "$HOME/.factory/settings.json" <<'FACTORY_JSON'
+          {
+            "customModels": [
+              {
+                "model": "deepseek-v4-flash",
+                "displayName": "DeepSeek V4 Flash (BYOK)",
+                "baseUrl": "https://api.deepseek.com/v1",
+                "apiKey": "${DEEPSEEK_API_KEY}",
+                "provider": "generic-chat-completion-api",
+                "maxOutputTokens": 16384
+              }
+            ]
+          }
+          FACTORY_JSON
+      - name: Run Droid Exec
+        uses: Factory-AI/droid-action@main
+        with:
+          factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+          review_model: deepseek-v4-flash
+          security_model: deepseek-v4-flash
+        env:
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

FAILURE-MODE-INDEX.md

@@ -10,5 +10,6 @@ Use this index when the work is blocked by a recognizable failure pattern rather
 | A multi-agent decision is converging too early | One perspective appears sufficient but alternatives have not been tested | [agent-council](agent-council/SKILL.md) |
 | A contribution may duplicate existing work | The requested feature sounds like something already in the repository | [opensource-contributions](opensource-contributions/SKILL.md) |
 | A workflow is repeated manually | The same sequence of skills is executed more than once | [workflow-architect](bundles/workflow-architect/SKILL.md) |
+| Meaning drifts or disagrees between agents | Agents use the same word for different meanings, or semantic divergence and dead-ends block progress | [semantic-spacetime](semantic-spacetime/SKILL.md) |
 
 This is a routing aid, not a replacement for reading the selected skill. Add a row only when the failure mode has a concrete trigger and an existing skill that addresses it.

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.
@@ -455,6 +459,10 @@ Build security into software requirements, design, implementation, review, and r
 
 Give authorized teams a disciplined way to identify and prioritize security risks without mistaking a checklist for a security guarantee.
 
+### [semantic-spacetime](semantic-spacetime/SKILL.md)
+
+Model and diagnose shared semantic ground between agents with Mark Burgess's Semantic Spacetime: discrete graph spacetimes where meaning evolves over time, typed gamma(3,4) edges expose semantic drift and absorbing states, and cooperative promises carry causality.
+
 ### [seo-audit](seo-audit/SKILL.md)
 
 Identify search-discoverability problems through evidence, prioritize the work, and distinguish technical defects from content opportunities.

agent-skills/README.md

@@ -19,6 +19,7 @@ When your agent loads this skill, it gains the ability to **create, review, and
 | `references/best-practices.md` | Guidance for useful, well-scoped instructions |
 | `references/optimizing-descriptions.md` | How to design and test reliable automatic triggers |
 | `references/using-scripts.md` | How to bundle safe, agent-friendly executable helpers |
+| `references/vetting-third-party-skills.md` | How to vet a skill from a registry, colleague, or LLM before running it |
 | `references/evaluating-skills.md` | A practical evaluation loop for testing skill quality |
 | `references/client-implementation.md` | Guidance for products that discover and load skills |
 

agent-skills/SKILL.md

@@ -117,6 +117,7 @@ Executable code agents can run. Scripts should:
 - Include helpful error messages
 - Handle edge cases gracefully
 - Use relative paths from the skill root (e.g., `scripts/extract.py`)
+- Be explicit about intent: say "run this script" or "read this as reference" — never leave the agent to guess whether a bundled file is executable or illustrative
 
 ### `references/`
 Additional documentation loaded on demand. Keep individual files focused — agents load these when instructed, so smaller files save context.
@@ -162,6 +163,7 @@ Focus on what the agent wouldn't know without the skill: project-specific conven
 ### Calibrate control
 - **Give freedom** when multiple approaches are valid — describe *why*, not just *what*
 - **Be prescriptive** when operations are fragile or a specific sequence must be followed
+- **Match prescriptiveness to fragility**: for a step that must be exactly right every time, prefer a deterministic script in `scripts/` over instructions the agent improvises on each run. A test only catches what you already thought to check; a script takes the guess out of the loop entirely
 - **Provide defaults, not menus** — pick one approach, mention alternatives briefly
 - **Favor procedures over declarations** — teach *how to approach* a class of problems, not *what to produce* for one instance
 
@@ -174,6 +176,10 @@ The highest-value content is often environment-specific corrections — things t
 ### Provide output templates
 When output needs a specific format, provide a template inline or in `assets/`. Agents pattern-match well against concrete structures.
 
+## Adopting Third-Party Skills
+
+Skills are executable capability: when a skill activates, its instructions and scripts run with the agent's permissions — shell access, file system, and credentials. Before running a skill you did not author (from a registry, a colleague, or an LLM generation), read [vetting third-party skills](references/vetting-third-party-skills.md) and treat it like any other dependency: inspect provenance, read the body and every script, and check what the skill reaches out to.
+
 ## Validation
 
 Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate skills:

agent-skills/evals/evals.json

@@ -61,6 +61,18 @@
         "Description quality is tied to routing correctness",
         "The failure modes of eager loading and weak trigger overlap are covered"
       ]
+    },
+    {
+      "id": "third-party-vetting",
+      "prompt": "I found a skill on a public registry that looks useful: it fetches weather data and sends me a notification. Before I install it, how do I tell whether it is safe to run?",
+      "expected_output": "A dependency-style vetting procedure performed before first run: check provenance (who published it, when, license, maintainer history), read the full SKILL.md body and compare it to the description for hidden or deceptive instructions (obfuscation, ignore-previous-instructions patterns, requests to reveal credentials), read every script for network calls to unknown hosts, filesystem access outside the skill directory (dotfiles, SSH keys, credential stores), hardcoded or echoed secrets, and dynamic behavior like curl-pipe-bash or remote imports, then run the first execution sandboxed with no real credentials and read-only access. The response explains that an open format standard says nothing about safety and that skills run with the agent's own permissions (shell, filesystem, credentials), citing that audits of public skill registries have found critical issues in a substantial fraction of skills.",
+      "assertions": [
+        "The vetting procedure covers provenance, the SKILL.md body, and every script before first run",
+        "Concrete red flags are named: unknown network hosts, out-of-directory filesystem access, credential exposure, obfuscation, curl-pipe-bash",
+        "First run is sandboxed with no real credentials and read-only access",
+        "The response states that format compliance or registry publication is not a safety guarantee",
+        "Skills running with the agent's permissions (shell, filesystem, credentials) is called out"
+      ]
     }
   ]
 }

agent-skills/references/vetting-third-party-skills.md

@@ -0,0 +1,80 @@
+# Vetting third-party skills before you run them
+
+> How to review a skill you did not author — or one your agent generated for you — before giving it the permissions your agent has.
+
+A skill is not a document you read; it is **executable capability**. When an agent activates a skill, the skill's instructions and scripts run with the agent's own permissions: shell access, read/write to the file system, credentials from environment variables and config files, and the ability to send messages. Installing an unvetted skill is like installing a package from a registry you have never heard of, except that no package manager gate exists by default.
+
+The risk is not theoretical. Snyk's ToxicSkills audit (published February 2026) scanned 3,984 skills from ClawHub and skills.sh, the largest public corpus of agent skills then known:
+
+- **13.4% (534) contained at least one critical-level issue** — malware, prompt injection, or exposed secrets.
+- **36.82% (1,467) had at least one security flaw at any severity** — hardcoded API keys, insecure credential handling, or dangerous third-party content exposure.
+- **76 confirmed malicious payloads** were found, with credential theft, backdoor installation, and data exfiltration; 8 were still publicly available at publication.
+
+Source: [Snyk — ToxicSkills: Snyk finds malware and prompt injection in 36% of AI agent skills](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/). The open Agent Skills standard says nothing about whether a given skill is safe; treat "published in a registry" as zero security signal.
+
+## When to use this reference
+
+Use it whenever you are about to **run** a skill you did not author and have not previously vetted:
+
+- A skill pulled from a public registry or marketplace (skills.sh, ClawHub, or similar).
+- A skill shared by a colleague, copied from a blog post, or vendored from another repository.
+- A skill an LLM generated for you in one pass and you have not read.
+- An updated version of a third-party skill you already run — re-vet on material version changes.
+
+It also applies to skills embedded in repositories you clone: project-level skills from an untrusted repository can inject instructions into your agent's context (see `client-implementation.md` for the client-side trust-gating angle).
+
+## The vetting checklist
+
+Work through this before the first run. It is a dependency review, not a skim.
+
+### 1. Provenance
+
+- Who published it, and when? Is the author identifiable, with a history beyond the skill itself? A registry account that is days old is a red flag.
+- Does it have a license, a README, a changelog? Does the repository look maintained or abandoned?
+- How did you obtain it? A direct link from a trusted source you already rely on is different from a search-result download.
+- Prefer pinned versions and record what you installed, so you can diff later updates.
+
+### 2. The SKILL.md itself
+
+Read the whole file — not just the description. The description is marketing; the body is the contract.
+
+- Does the body's actual behavior match the description's promise?
+- Look for hidden or deceptive instructions: base64 or other obfuscation, Unicode smuggling, "ignore previous instructions" patterns, system-message impersonation, instructions to do something unrelated to the stated purpose (e.g., a "weather" skill that tells the agent to read files in `~/.ssh`).
+- Does it instruct the agent to fetch and follow remote content at runtime? That is indirect prompt injection — the remote author gains control over your agent.
+- Does it ask the agent to print, echo, or reveal credentials, API keys, or tokens?
+
+### 3. Every script and executable
+
+Scripts run with your agent's permissions. Read each one before it ever executes.
+
+- **Network calls**: what hosts does it reach out to? Unknown domains, IP-literal URLs, typosquatted package names, `curl | bash` patterns, and password-protected archives are red flags.
+- **File system access**: does it read or write outside its own skill directory? Pay special attention to dotfiles, SSH keys, shell profiles, credential stores, and config files.
+- **Credential handling**: hardcoded secrets, keys passed on command lines, instructions to store secrets in plaintext.
+- **Dynamic behavior**: remote imports, downloads that execute, obfuscated or minified code you cannot read.
+- **Dependencies**: are they named, pinned, and from known sources? Executables requiring elevated privileges deserve extra scrutiny.
+
+### 4. References and assets
+
+Files in `references/` and `assets/` can carry instructions too. Scan them for the same patterns as the SKILL.md: remote fetching, hidden instructions, secrets.
+
+## Safe first-run practice
+
+Even after a clean review, run it the way you would run any untrusted dependency the first time:
+
+- Run in a sandboxed environment (container, VM, or disposable profile) where the agent has no real credentials.
+- Run with an empty or minimal environment — no production API keys, no personal tokens.
+- Prefer read-only access to the file system where the harness supports it.
+- Watch what it actually does before granting it your real working context.
+
+## If you find a problem
+
+- Do **not** run the skill further, and do not "fix and continue" silently.
+- Report it: the registry or marketplace the skill came from, and the author if contactable. Malicious skills are a supply-chain incident, not a code review finding.
+- If the skill is part of a dependency chain you already run, treat discovery like any other vulnerability: assess exposure, rotate any credentials the skill could have seen, and record what you know.
+
+## Gotchas
+
+- **An open standard is not a safety standard.** Format compliance says nothing about intent. A perfectly schema-valid SKILL.md can be malware.
+- **Curation is not an audit.** A "top skills" list measures popularity, not safety.
+- **LLM-generated skills need the same review as stranger's skills.** The model that wrote the skill is not a security reviewer, and generated skills often contain plausible-looking but unverified instructions.
+- **Re-vet on updates.** A skill you vetted at v1.0 is a new dependency at v2.0. Diff the change before letting it back in.

fireflies/README.md

@@ -3,8 +3,8 @@
 ## Why Install This Skill
 
 Turn Fireflies meetings into usable data without hand-copying notes. Search transcripts, inspect
-summaries and action items, review analytics, and ask focused questions with AskFred from a single
-dependency-free command line tool.
+summaries and action items, review analytics, fetch audio and video recording links, and ask
+focused questions with AskFred from a single dependency-free command line tool.
 
 It also makes sensitive operations deliberate: every mutation requires an explicit confirmation,
 and every mutation can be previewed locally before it is sent.
@@ -42,6 +42,7 @@ python3 scripts/fireflies meetings rename transcript-id --title "Q3 roadmap" --d
 ## Triggers
 
 - Fireflies.ai transcripts, summaries, notes, contacts, channels, or analytics
+- Meeting audio/video recording download links (`transcripts get` returns `video_url`/`audio_url`)
 - AskFred questions about meeting content
 - Remote audio upload to Fireflies
 - Fireflies Webhooks V2 signature verification

fireflies/SKILL.md

@@ -33,7 +33,7 @@ the target, scope, and rollback path; then route the change through the CLI's li
 | Need | Command |
 |---|---|
 | Find transcript metadata | `scripts/fireflies transcripts list --keyword TEXT --limit 10 --json` |
-| Read a meeting, summary, sentences, and analytics | `scripts/fireflies transcripts get ID --json` |
+| Read a meeting, summary, sentences, analytics, and recording links | `scripts/fireflies transcripts get ID --json` |
 | People, channels, groups, contacts, apps | `users`, `channels`, `groups`, `contacts`, `apps` |
 | Meeting analytics or live meetings | `analytics --start DATE --end DATE`, `meetings active` |
 | Ask a transcript question | `askfred create --question TEXT --transcript-id ID --confirm` |

fireflies/evals/evals.json

@@ -56,6 +56,17 @@
     "Notes AskFred mutations require AI credits and --confirm",
     "Does not claim AskFred works without an API key"
    ]
+  },
+  {
+   "id": "recording-urls",
+   "prompt": "I have a transcript ID for a meeting I attended and I want to download the audio and video recordings of it. How does the skill give me those files?",
+   "expected_output": "The agent uses the fireflies transcripts get command with the transcript ID; the returned JSON includes video_url and audio_url fields, which are the download links for the meeting's video and audio recordings. It explains the query is a read-only GraphQL query requiring FIREFLIES_API_KEY and returns JSON.",
+   "assertions": [
+    "Uses the fireflies transcripts get command with a transcript ID",
+    "Identifies video_url and audio_url in the returned fields as the recording download links",
+    "Notes the query is read-only and requires FIREFLIES_API_KEY",
+    "Does not propose an upload or mutation for a read-only lookup"
+   ]
   }
  ]
 }

fireflies/references/api-reference.md

@@ -41,6 +41,8 @@ follows (live schema wins):
 - `createBite` names its argument `transcript_Id` (capital I) and `privacies` takes
   `[BitePrivacy!]` (enum: `public`, `team`, `participants`).
 - `shareMeeting` input gained `expiry_days` (7, 14, or 30).
+- `transcript` selection gained `video_url` and `audio_url` (meeting recording download links),
+  verified by live introspection on 2026-08-10.
 - `updateMeetingChannel` (changelog 2.15.0), `addToLiveMeeting`, `createLiveSoundbite`,
   `createUploadUrl`/`confirmUpload`, `setUserRole`, and `askfred_thread` were added as ergonomic
   commands after the audit found them documented but uncovered.

fireflies/references/cli-reference.md

@@ -10,7 +10,7 @@ subcommands: `--json`, `--api-key`, `--endpoint`, `--timeout`, `--dry-run`, `--q
 |---|---|
 | `query --document DOC [--variables JSON|--variables-file PATH]` | Generic read-only GraphQL |
 | `mutation --document DOC ... --confirm` | Generic mutation |
-| `transcripts list|get|delete` | Search, inspect, or delete meetings |
+| `transcripts list|get|delete` | Search, inspect, or delete meetings; `get` also returns `video_url`/`audio_url` recording download links |
 | `users`, `contacts`, `channels`, `groups`, `bites`, `apps` | Workspace/content reads; `users set-role --user-id ID --role admin|user` assigns roles |
 | `analytics`, `meetings active`, `live-action-items` | Analytics and live data |
 | `meetings rename|privacy|state|share|revoke-share|update-channel` | Meeting mutations; `share` accepts `--expiry-days` |

fireflies/references/workflows.md

@@ -11,6 +11,16 @@ scripts/fireflies transcripts get transcript-id --json
 
 The detailed query includes summary, speakers, sentences, and analytics.
 
+## Fetch Recording Download URLs
+
+Use this to grab the meeting's audio and video recordings. The response's `video_url` and
+`audio_url` fields are the download links for the recording.
+
+```bash
+scripts/fireflies transcripts get transcript-id --json
+# response includes "video_url" and "audio_url" — signed download links for the recording
+```
+
 ## Extract Actions and Summary
 
 Use this for a currently live meeting or for a completed transcript.

fireflies/scripts/fireflies

@@ -16,7 +16,7 @@ EX_USAGE, EX_CONFIG, EX_TRANSPORT, EX_GRAPHQL, EX_CONFIRM = 2, 3, 4, 5, 6
 
 DOCS = {
     "transcripts_list": "query Transcripts($title: String, $keyword: String, $scope: String, $fromDate: DateTime, $toDate: DateTime, $limit: Int, $skip: Int, $hostEmail: String, $userId: String, $mine: Boolean, $organizers: [String!], $participants: [String!], $channelId: String, $organizerEmail: String, $participantEmail: String) { transcripts(title: $title, keyword: $keyword, scope: $scope, fromDate: $fromDate, toDate: $toDate, limit: $limit, skip: $skip, host_email: $hostEmail, user_id: $userId, mine: $mine, organizers: $organizers, participants: $participants, channel_id: $channelId, organizer_email: $organizerEmail, participant_email: $participantEmail) { id title date duration organizer_email participants transcript_url } }",
-    "transcript": "query Transcript($id: String!) { transcript(id: $id) { id title date duration organizer_email participants transcript_url summary { overview } speakers { id name } sentences { index text speaker_name start_time end_time } analytics { sentiments { negative_pct neutral_pct positive_pct } } } }",
+    "transcript": "query Transcript($id: String!) { transcript(id: $id) { id title date duration organizer_email participants transcript_url video_url audio_url summary { overview } speakers { id name } sentences { index text speaker_name start_time end_time } analytics { sentiments { negative_pct neutral_pct positive_pct } } } }",
     "users": "query Users { users { user_id email name is_admin integrations } }",
     "me": "query User { user { user_id email name is_admin integrations } }",
     "user": "query User($id: String!) { user(id: $id) { user_id email name is_admin integrations } }",

fireflies/tests/test_fireflies.py

@@ -79,6 +79,7 @@ class FirefliesTests(unittest.TestCase):
         self.assertEqual(analytics["variables"],{"startTime":"2026-01-01","endTime":"2026-01-31"})
         transcript=json.loads(self.run_cli("transcripts","get","transcript-id","--dry-run","--json").stdout)["payload"]
         self.assertIn("negative_pct neutral_pct positive_pct",transcript["query"])
+        self.assertIn("video_url audio_url",transcript["query"])
         audit=json.loads(self.run_cli("audit-events","--filter",'{"category":"MEETING_OPERATIONS"}',"--dry-run","--json").stdout)["payload"]
         self.assertIn("events { id time action actor { user_id } resource { type id } }",audit["query"])
     def test_transcripts_list_document_is_current(self):

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.
@@ -112,6 +113,7 @@
 - [restic](restic/SKILL.md): Install, configure, operate, secure, automate, tune, troubleshoot, and recover restic backups across local, SFTP, S3-compatible, cloud, and REST backends. Use when creating or managing a restic repository, designing backup or retention policy, validating restores, handling repository health or locks, moving repositories, or building safe scheduled backup jobs. Do not use for a generic file-copy task that does not need encrypted, deduplicated snapshots.
 - [secure-software-engineering](secure-software-engineering/SKILL.md): Use when designing or implementing software securely: define security requirements, threat-model a feature, choose secure defaults, design authentication and authorization, handle untrusted data and secrets, evaluate dependencies, or review security-sensitive changes. Use for prevention during requirements, design, implementation, and review; not for post-build security assessments or scanning an existing codebase.
 - [security-audit-methodology](security-audit-methodology/SKILL.md): Plan authorized security reviews with threat modeling, architecture and dependency audits, and vulnerability classification. Use for scoped defensive security assessment. Do not use for offensive operations, unauthorized testing, or security control implementation.
+- [semantic-spacetime](semantic-spacetime/SKILL.md): Model and diagnose shared semantic ground between agents with Semantic Spacetime (Mark Burgess, 2014-2025): a discrete graph model of meaning over time, where local proper time replaces global clocks, causality is cooperative promises, and gamma(3,4) graphs expose semantic drift, world model divergence, and absorbing states. Use for designing convergent self-healing coordination, modeling intent and trajectories over time, mapping promises onto spacetime, diagnosing semantic drift or dead-ends, and analyzing temporal blindness in agents. Do not use for physics or relativity, pure vector embeddings or RAG without temporal-causal structure, enforceable centralized control, simple single-agent prompting, or tool manuals — route those to the appropriate skill.
 - [seo-audit](seo-audit/SKILL.md): Audit websites and pages for technical SEO, on-page SEO, schema markup, content discoverability, and answer-engine readiness. Use when prioritizing search visibility improvements.
 - [site-reliability-engineering](site-reliability-engineering/SKILL.md): Design, operate, and improve reliable production systems with SLOs, incident command, observability, error budgets, and operational practices.
 - [slack](slack/SKILL.md): Operate Slack workspaces from a terminal or agent: list channels, read messages, follow threads, search message history, list files, and verify inbound webhook signatures — with a bundled slack-cli script that is read-only by default and gates every send behind a --dry-run/--yes confirmation. Use when an agent needs to read or post Slack data, triage incidents, or answer questions about what was said in a workspace. Do not use for building Slack apps or bots (that is application development) or workspace administration like user provisioning and org settings (that is the Slack admin console).

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.

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.

promise-theory/SKILL.md

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

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"
+      ]
+    }
+  ]
+}

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.

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.

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.

promise-theory/references/foundations.md

@@ -0,0 +1,706 @@
+# 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);
+the skill that develops this downstream concept is
+[semantic-spacetime](../../semantic-spacetime/SKILL.md).
+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.

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.

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.

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.

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 <command> [options] <file>
+
+Validate and render promise-theory manifest contracts (restricted-YAML or JSON).
+
+commands:
+  lint <file>      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 <file>    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"<expectation #{ei + 1}>")
+            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"<expectation #{ei + 1}>"
+
+        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())

promise-theory/templates/agent-contract.md.tmpl

@@ -0,0 +1,128 @@
+# Agent Contract: <contract-title>
+
+A promise has no binding force on its own; a contract is a promise *plus* a
+mechanism that makes deviation costly or impossible (M12, "From Promises to
+Contracts," 2026). Promise theory supplies the acceptance half; this contract
+supplies the enforcement half. Fill it from a signed-off
+[promise manifest](promise-manifest.yaml.tmpl): promise ids, types, bodies,
+verifiers, severities, and withdrawals below must match the manifest so the
+two artifacts stay in sync. Severity and verifier use the manifest schema
+enums; every promise maps to a manifest `type`.
+
+- Contract version: <0.1.0>
+- Status: <DRAFTED | ACTIVE | FULFILLED | VIOLATED | EXPIRED | TERMINATED>
+- Date: <YYYY-MM-DD>
+- Manifest version this contract is drawn from: <v1>
+- Renegotiation count (resets on each accepted revision): <0>
+
+## 1. Parties
+
+| Party | Side | Role in this contract | Contact / address |
+|---|---|---|---|
+| <Human name or team> | Acceptor and evaluator | <sponsor / reviewer / supervisor> | <email / channel / calendar> |
+| <agent-id> | Promiser | <role from manifest> | <endpoint / runtime / workspace> |
+| <agent-id> | Promiser | <role from manifest> | <endpoint / runtime / workspace> |
+
+Every party keeps its autonomy: each promise below is made voluntarily and
+can be withdrawn under the stated conditions. Nothing in this contract is a
+legal instrument.
+
+## 2. Promise set
+
+For each promise in scope, record: id (from the manifest), type (manifest
+enum), promiser, target, body, acceptance criteria (the observable conditions
+that define "kept"), verifier (manifest enum), severity (manifest enum), and
+withdrawal (the condition that ends the promise).
+
+| Promise id | Type (manifest) | Promiser | Target | Body | Acceptance criteria | Verifier | Severity | Withdrawal |
+|---|---|---|---|---|---|---|---|---|
+| <promise-id> | <capability | intent | constraint | self-promise> | <agent-id> | <agent-id | human | all> | <what the promiser will do> | <observable condition(s) that must hold> | <eval | manual | monitor | audit> | <impact | standard | low> | <condition that ends the promise> |
+| <promise-id> | <...> | <...> | <...> | <...> | <...> | <...> | <...> | <...> |
+
+For every consequential promise, name the enforcement rung applied (M12
+ladder from promise to contract): 1 soft prompt, 2 self-check/reflection,
+3 output validation/constrained decoding, 4 external action guards,
+5 capability restriction/sandboxing ("won't" becomes "can't"), 6 formal
+methods/typed effects. Enforcement lives outside the model.
+
+| Promise id | Enforcement rung (1-6) | Notes |
+|---|---|---|
+| <promise-id> | <1-6> | <e.g., "action guard rejects file writes outside src/"> |
+
+Degradation tier (named before any breach): <fail-closed | best-effort |
+safe default>, with the decision rule (fail open when liveness matters;
+fail closed when safety matters).
+
+## 3. Verification schedule
+
+Who verifies which promise, how often, at what cost. Verification is a
+budget (kinetic mistrust), not a free good — budget it explicitly.
+
+| Promise id | Verifier | Frequency / trigger | Method (eval, manual, monitor, audit) | Verification budget |
+|---|---|---|---|---|
+| <promise-id> | <human | agent-id | guard> | <per-deliverable / daily / on-change / 1-in-10 random sample> | <method and tooling> | <review minutes or tokens per period> |
+
+- Starting trust level for each new promiser: <50-50, or a stated prior with
+  reasoning>
+- Promise ledger: every assessment is appended to the ledger (who assessed,
+  when, against what observation, verdict), stored as versioned data so
+  trust can accumulate.
+
+## 4. Breach handling
+
+Breach is an information event, not a moral one. On a detected breach:
+
+1. Record it in the promise ledger (evidence, verdict).
+2. Classify the cause: specification / inter-agent conflict / verification.
+3. Renegotiate first: revise the promise set (body, acceptance criteria,
+   verifier, severity, withdrawal), add verification, or change the provider.
+4. Adjust the trust estimate and the verification rate.
+5. Apply redundancy if the promise is load-bearing.
+
+Escalate only when renegotiation fails to converge. Named escalation trigger:
+**ESCALATE-2** — escalate to <human supervisor or next acceptance authority>
+after two full renegotiation cycles (one cycle = one breach -> one contract
+revision -> one verification window) without convergence. Escalation owner:
+
+| Escalation owner | Role | Contact / channel | Response SLA |
+|---|---|---|---|
+| <name> | <supervisor / owner> | <...> | <e.g., 1 business day> |
+
+## 5. Review cadence
+
+- Review frequency: <weekly / per-sprint / per-release>
+- What is reviewed: the promise set, recent assessments, verification budget
+  spent, refusal and breach rates, and the trust estimates.
+- Review output: a revised contract version and/or a
+  [promise review](promise-review.md.tmpl) for the period.
+- Next review date: <YYYY-MM-DD>
+
+## 6. Signatures / consent
+
+| Party | Consent method | Signature / acceptance record | Date |
+|---|---|---|---|
+| <Human name or team> | <e.g., typed name in chat, approval comment on the contract> | <signature / link to approval> | <YYYY-MM-DD> |
+| <agent-id> | <logged acceptance handshake> | <ledger entry id of the accept> | <YYYY-MM-DD> |
+| <agent-id> | <logged acceptance handshake> | <ledger entry id of the accept> | <YYYY-MM-DD> |
+
+Consent is two-sided and withdrawable: any party may withdraw a promise
+under the conditions in section 2; the contract is then renegotiated, not
+abandoned.
+
+## 7. Accountability — human commitments
+
+The human side of this contract makes its own promises. These are recorded
+in the manifest as `expectations` entries with `from: human` and assessed on
+the same review cadence as agent promises.
+
+| Human promise | Acceptance criteria | Verifier | Severity | Withdrawal |
+|---|---|---|---|---|
+| Provide direction: <what the human will supply, by what cadence> | <observable condition(s)> | <manual | monitor> | <impact | standard | low> | <condition that ends the commitment> |
+| Review agent output within <response SLA> | <e.g., every deliverable reviewed within 1 business day> | <manual> | <standard> | <...> |
+| Respond to escalations within <response SLA> | <e.g., ESCALATE-2 cases answered within 1 business day> | <manual> | <impact> | <...> |
+| Maintain consent: keep signatures and the manifest/contract version current | <...> | <monitor> | <low> | <...> |
+
+Human verification of agent promises: the human evaluates <promise ids from
+section 3> by <how — e.g., reading each deliverable, spot-checking citations>
+on the verification schedule in section 3, and records verdicts in the
+promise ledger.

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 = <agent-id> | human | all
+#     verifier = eval | manual | monitor | audit
+#     severity = impact | standard | low
+#   * `expires` is an ISO-8601 duration (PT15M, P30D) or a date/datetime
+#     (YYYY-MM-DD or RFC 3339)
+#   * when `type: self-promise`, target MUST equal the promising agent's own id
+#
+# The example values below form a valid, fully covered manifest: every
+# `accepts` reference points at a promise declared by another agent, and every
+# `expectations.about` points at a promise declared in this file.
+
+agents:
+  # --- Agent 1: literature summarizer --------------------------------------
+  - id: research-agent            # required; unique across the manifest
+    role: literature summarizer   # required; free text
+    accepts: [research-direction] # optional; promise ids declared by OTHER agents
+    promises:                     # required; at least one per agent
+      - id: lit-review            # required; unique across the whole manifest
+        type: capability          # capability | intent | constraint | self-promise
+        target: human             # <agent-id> | human | all
+        body: Survey and summarize literature on promise theory.
+        constraint: limit 20 sources   # optional; non-empty when present
+        withdraw: when coordinator withdraws direction  # optional; non-empty when present
+        expires: P30D                  # optional; duration or date/datetime
+      - id: evidence-tables
+        type: capability
+        target: human
+        body: Produce evidence tables with citations for each summary.
+      - id: no-fabrication
+        type: constraint          # example of a negative capability
+        target: human
+        body: Never fabricate citations; mark unverifiable sources as unverified.
+
+  # --- Agent 2: reviewer (accepts the summarizer's lit-review promise) ------
+  - id: reviewer                  # unique; do not reuse another agent's id
+    role: fact-checker
+    accepts: [lit-review]
+    promises:
+      - id: fact-check
+        type: capability
+        target: research-agent    # directed at another agent in the manifest
+        body: Verify claims against cited sources and report discrepancies.
+        withdraw: when the claim is outside my declared domain
+
+  # --- Agent 3: coordinator agent (an autonomous agent, not the human) ------
+  - id: coordinator
+    role: workflow coordinator
+    accepts: [evidence-tables, fact-check]
+    promises:
+      - id: research-direction
+        type: intent
+        target: research-agent
+        body: Provide research direction and review summaries by the agreed cadence.
+      - id: self-quality
+        type: self-promise
+        target: coordinator       # REQUIRED: must equal this agent's own id
+        body: Run a self-check pass over my own output before publishing.
+
+expectations:                     # required; at least one entry
+  - id: exp-lit-review            # required; unique
+    from: human                   # "human" or a declared agent id
+    about: lit-review             # REQUIRED: reference an existing promise id
+    verifier: manual              # eval | manual | monitor | audit
+    severity: impact              # impact | standard | low
+  - id: exp-fact-check
+    from: research-agent          # agents can hold expectations too
+    about: fact-check
+    verifier: eval
+    severity: standard
+  - id: exp-research-direction
+    from: human
+    about: research-direction
+    verifier: monitor
+    severity: impact

promise-theory/templates/promise-review.md.tmpl

@@ -0,0 +1,75 @@
+# Promise Review: <review title or period>
+
+A retrospective is renegotiation of the team's promise set, not blame. This
+template records what was promised, what was kept and breached (with
+evidence), the root cause of each breach in promise-theory diagnosis
+categories, the renegotiated promise set, and the resulting action items.
+Promise ids below must match the promise manifest and agent contract under
+review so all artifacts stay cross-referenced.
+
+- Review period: <start date> to <end date>
+- Date of review: <YYYY-MM-DD>
+- Participants (who assessed): <names / agent ids>
+- Manifest version(s) under review: <v1, v2, ...>
+- Contract version(s) under review: <0.1.0, ...>
+
+## 1. Promise list under review
+
+Every promise in scope, drawn from the manifest(s) in force during the
+period.
+
+| Promise id | Promiser | Target | Body (from manifest) | Manifest version |
+|---|---|---|---|---|
+| <promise-id> | <agent-id> | <agent-id | human | all> | <body> | <version> |
+| <promise-id> | <agent-id> | <...> | <...> | <...> |
+
+## 2. Outcomes — kept and breached, with evidence
+
+For every promise: verdict (kept / breached / not yet due / withdrawn), who
+assessed, when, and against what observation. Cite the promise-ledger
+entries, traces, eval results, or human review records that support the
+verdict.
+
+| Promise id | Verdict | Assessed by | When | Against what observation | Evidence (ledger / trace / eval / review) |
+|---|---|---|---|---|---|
+| <promise-id> | <kept | breached | not yet due | withdrawn> | <human | agent-id | guard> | <date> | <the observation checked> | <entry id / artifact> |
+| <promise-id> | <...> | <...> | <...> | <...> | <...> |
+
+## 3. Root-cause analysis — diagnosis categories
+
+For each breached promise, assign exactly one of the three diagnosis
+categories (the multi-agent failure taxonomy mapped to promise vocabulary):
+
+- **specification** — broken promise body: the promise was unclear, wrong,
+  or unverifiable as written
+- **inter-agent conflict** — failed acceptance or incompatible co-languages
+  between agents
+- **verification** — missing or inadequate assessment: the breach was not
+  detected, or was detected too late
+
+| Breached promise id | Diagnosis category | Evidence for the diagnosis | What the category implies for the fix |
+|---|---|---|---|
+| <promise-id> | <specification | inter-agent conflict | verification> | <...> | <e.g., "rewrite the body", "renegotiate the acceptance handshake", "add a monitor"> |
+
+## 4. Renegotiated promise set
+
+The output of this review is a revised promise set: amended bodies,
+acceptance criteria, verifiers, severities, and withdrawals; promises added
+or retired; and any trust-estimate or verification-rate adjustments. Each
+change links to the section 3 diagnosis that motivated it. Version the
+revised set.
+
+| Promise id | Change (body / acceptance criteria / verifier / severity / withdrawal / added / retired) | New value | Reason (linked diagnosis) |
+|---|---|---|---|
+| <promise-id> | <change kind> | <new value> | <specification / inter-agent conflict / verification> |
+| <promise-id> | <...> | <...> | <...> |
+
+## 5. Action items
+
+| # | Action | Owner | Due | Verification of completion |
+|---|---|---|---|---|
+| 1 | <what will be done> | <human | agent-id> | <date> | <how completion will be checked> |
+| 2 | <...> | <...> | <...> | <...> |
+
+When an action changes a promise or contract, fold it into the next manifest
+and contract revision so the artifacts do not drift apart.

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()

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.

references/skill-triggers.md

@@ -111,3 +111,5 @@ 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) |
+| "semantic spacetime", "semantic drift", "shared meaning", "world model divergence", "semantic ground", "temporal blindness", "gamma(3,4)" | [semantic-spacetime](../semantic-spacetime/SKILL.md) |

requirements-dev.txt

@@ -1,7 +1,7 @@
 jsonschema[format]==4.26.0
 types-jsonschema>=4
 requests==2.34.2
-ruff>=0.16.0
+ruff>=0.16.1
 pytest>=9.1.1
 pytest-cov>=7.1.0
 pytest-xdist>=3.0

semantic-spacetime/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.

semantic-spacetime/README.md

@@ -0,0 +1,69 @@
+# Semantic Spacetime
+
+Model meaning over time with Mark Burgess's Semantic Spacetime: a discrete graph method for designing shared semantic ground between agents, diagnosing semantic drift, and building coordination that converges on intended meaning.
+
+## Why Install This Skill
+
+Multi-agent systems keep failing on meaning: two agents start from the same instructions and quietly diverge, nobody notices that a shared term no longer means the same thing to each side, and the system dead-ends in a state where information stops flowing. This skill gives your agent a working method for that problem — model the space of meaning as a graph, treat every local change as a unit of time, and measure where interpretations drift apart instead of guessing.
+
+After installing, your agent can map a team of agents onto a semantic spacetime with typed events, things, and concepts, trace how intent propagates through promises and acceptances, diagnose drift and divergence with a bounded procedure, and write an analysis report with concrete interventions and a verification plan. The method is grounded in Burgess's arXiv series (2014-2025) and his earlier Promise Theory, and it is honest about what is verified, what is not, and what is extrapolation.
+
+## What You Get
+
+| Contents | Provides |
+|---|---|
+| `SKILL.md` | When to use Semantic Spacetime, when not to, and what to load for the task at hand |
+| `references/foundations.md` | The academic core: definitions, the γ(3,4) formalism, proper time, causality, the promise substrate, and adjacent fields |
+| `references/applications-infrastructure.md` | The CFEngine → IaC → Kubernetes/GitOps/IBN → MAPE-K lineage: convergence semantics, the promise-keeping-as-data gap, SLOs as semantic contracts, and the record-of-time machinery, with a citable lessons list |
+| `references/agent-coordination.md` | Agentic AI: Burgess's agent papers, SSTorytime and MCP-SST, drift and temporal-blindness literature, spatial-temporal world models, the MCP/A2A substrate, and five labeled synthesis patterns |
+| `references/patterns.md` | Ten named patterns (semantic anchor, trajectory, convergence loop, promise propagation, drift detection, absorbing states, shared manifold, γ(3,4) modeling, distance metrics, reconciliation), each with when-to-use and anti-patterns |
+| `references/diagnosis-and-debugging.md` | A bounded procedure for diagnosing semantic drift, divergence, dead-ends, and meaning gaps — stop after three non-converging passes and report the evidence |
+| `references/glossary.md` | Heading-led definitions of every term the skill uses |
+| `references/bibliography.md` | Annotated primary sources with URLs, organized by area |
+| `templates/` | The `sst-model.yaml.tmpl` model format (agents, nodes, edges, acceptances, trajectories, observations) and the `sst-analysis.md.tmpl` report skeleton |
+| `scripts/semantic-spacetime.py` | A stdlib-only CLI: lint a model, map the γ(3,4) graph, measure semantic distance, trace trajectories, and diff snapshots for drift (`--json` and `--dry-run` supported) |
+| `tests/` | A stdlib unittest suite (runs in CI) and trigger/anti-trigger routing probes, plus a fully-filled sample model fixture |
+| `evals/` | Output-quality evals for the skill |
+| `LICENSE` | MIT license |
+
+## Quick Start
+
+Nothing to install: the CLI is stdlib-only Python 3.10+. From the repository
+root, run:
+
+1. Lint a model against the sst-model-v1 format — exit 0 prints a coverage
+   summary, exit 1 prints named violations:
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model lint semantic-spacetime/tests/fixtures/sample-model.yaml`
+2. Map the γ(3,4) graph (text | mermaid | json):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model map semantic-spacetime/tests/fixtures/sample-model.yaml --format mermaid`
+3. Measure semantic distance (weighted hop count, |link| + 1 per hop):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model distance semantic-spacetime/tests/fixtures/sample-model.yaml --from report-event --to drift-concept`
+4. Trace trajectories (simple paths with link types; cycles noted):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model trajectory semantic-spacetime/tests/fixtures/sample-model.yaml --from report-event --to drift-concept`
+5. Diff two snapshots — added/removed/changed regions; identical snapshots
+   report `no drift` (run it on the same file twice to see the no-drift case):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model drift semantic-spacetime/tests/fixtures/sample-model.yaml semantic-spacetime/tests/fixtures/sample-model.yaml`
+6. Append `--json` to any command for a single machine-readable object;
+   `--dry-run` is a no-op guard.
+
+To draft your own model, copy `templates/sst-model.yaml.tmpl` and fill it per
+the inline comments — the delimited example block shows a complete model.
+Copy `templates/sst-analysis.md.tmpl` for the analysis report skeleton:
+system description, the semantic spacetime map, drift/divergence/absorbing-state
+findings, interventions, and a verification/measurement plan.
+
+## Triggers
+
+- Designing or analyzing shared semantic ground between agents
+- Modeling intent or meaning changing over time (trajectories, drift, convergence)
+- Designing convergent, self-healing coordination where state is measured against desired meaning
+- Diagnosing semantic drift, divergence, or dead-ends (absorbing states)
+- Mapping promises onto spacetime (trajectories, propagation, causality)
+- Analyzing temporal blindness in agents (state tracking, event ordering, causality)
+
+## Requirements
+
+Python 3.10+ (stdlib only) for the bundled CLI; nothing else to install. The
+skill content is Markdown, YAML templates, and JSON evals; the bundled model
+format is versioned (`sst-model-v1`) and documented in the template itself.
+Works with any agent client that loads Agent Skills.

semantic-spacetime/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: semantic-spacetime
+description: >-
+  Model and diagnose shared semantic ground between agents with Semantic
+  Spacetime (Mark Burgess, 2014-2025): a discrete graph model of meaning over
+  time, where local proper time replaces global clocks, causality is
+  cooperative promises, and gamma(3,4) graphs expose semantic drift, world
+  model divergence, and absorbing states. Use for designing convergent
+  self-healing coordination, modeling intent and trajectories over time,
+  mapping promises onto spacetime, diagnosing semantic drift or dead-ends,
+  and analyzing temporal blindness in agents. Do not use for physics or
+  relativity, pure vector embeddings or RAG without temporal-causal structure,
+  enforceable centralized control, simple single-agent prompting, or tool
+  manuals — route those to the appropriate skill.
+license: MIT
+---
+
+# Semantic Spacetime
+
+Semantic Spacetime (SST) is Mark Burgess's discrete, graph-theoretic model of
+meaning over time. A *semantic element* is one autonomous agent plus its scalar
+promises; a *semantic spacetime* is a collection of such elements in which a
+local change in state, promises, or configuration is a local unit of time. Time
+is proper time — there is no global clock (the precedence view Burgess credits
+to Lamport). Causality is cooperative: every adjacency requires an offer (+) and
+an acceptance (−) promise on both ends, so space is made of cooperating nodes
+and edges. The 2025 γ(3,4) formalism types the graph: three node meta-types
+(events, things, concepts) connected by four link types (0 = NEAR, ±1 = LEADS
+TO, ±2 = CONTAINS, ±3 = EXPRESSES). Absorbing states in partial graphs leak
+information, and intentionality enters at the boundary. SST is built on Promise
+Theory — for the promise vocabulary, load [promise-theory](../promise-theory/SKILL.md)
+instead of re-deriving it here. This skill is a thin router: load the dense
+material only when a row in [Load By Need](#load-by-need) matches your task.
+
+## When to use
+
+- **When you need to design or analyze shared semantic ground between agents**
+  — model what "meaning" means in this system (what does a concept, term, or
+  promise mean to whom), producing a γ(3,4) map of the shared semantic ground
+  as the artifact.
+- **When you need to model intent or meaning over time** — trajectories,
+  drift, and convergence of understanding between agents, agents and humans,
+  or agents and their instructions; the artifact is a semantic trajectory with
+  recorded observations.
+- **When you need to design convergent, self-healing coordination** — a loop
+  in which state is continuously measured against a desired meaning and
+  repaired toward it; model the loop as semantic elements whose local change
+  is time.
+- **When you need to diagnose semantic drift, divergence, or dead-ends** —
+  absorbing states, meaning gaps, and non-converging agents; the artifact is a
+  drift finding with the leaking boundary identified.
+- **When you need to map promises onto spacetime** — trajectories, promise
+  propagation, and causality between agents; model each promise as an edge and
+  trace how intent propagates through the graph.
+- **When you need to analyze temporal blindness in agents** — state tracking,
+  event ordering, and causality failures where an agent cannot tell what
+  happened before what; model event order via proper time instead of a shared
+  clock.
+
+## When not to use
+
+- **Physics or relativity** — SST is not a theory of quantum gravity or
+  spacetime physics; it assumes no manifold structure and no momentum. Do not
+  use it for physics problems; those belong to a physics domain.
+- **Pure vector embeddings, RAG, or semantic search without temporal-causal
+  structure** — a static embedding index has no proper time, no causality, and
+  no trajectories to model; route to the embedding or semantic-search tool's
+  own skill instead.
+- **Enforceable centralized control** — if you can command and verify
+  compliance directly, SST's cooperative-promise machinery is overhead, not
+  insight (the same boundary promise-theory draws); route to
+  [promise-theory](../promise-theory/SKILL.md) when you need the control-vs-
+  cooperation discussion.
+- **Simple single-agent prompting** — one model and one prompt with no
+  delegation or meaning space to model needs no spacetime vocabulary.
+- **Tool manuals or framework documentation** — routing to the tool's own
+  skill is always better than framing the tool with SST.
+
+## Load By Need
+
+| Need | Load |
+|------|------|
+| Re-derive the formal model: semantic element, semantic spacetime, proper time, γ(3,4) typing rules, learning/knowledge formalism, promise substrate | [references/foundations.md](references/foundations.md) |
+| Learn from the CFEngine and infrastructure lineage before designing convergent systems (convergence semantics, IaC/Kubernetes/GitOps/IBN lessons, promise-keeping-as-data, SLOs, the record axis) | [references/applications-infrastructure.md](references/applications-infrastructure.md) |
+| Model an agent team in SST terms or design agent coordination (Burgess's agent papers, drift/temporal-blindness literature, MCP/A2A substrate, synthesis patterns) | [references/agent-coordination.md](references/agent-coordination.md) |
+| Apply a named pattern — semantic anchor, trajectory, convergence loop, promise propagation, drift detection, absorbing-state detection, shared semantic manifold, γ(3,4) modeling, distance metrics, reconciliation | [references/patterns.md](references/patterns.md) |
+| Diagnose semantic drift, divergence, dead-ends (absorbing states), or meaning gaps with a bounded procedure | [references/diagnosis-and-debugging.md](references/diagnosis-and-debugging.md) |
+| Hit an unfamiliar term while modeling or diagnosing | [references/glossary.md](references/glossary.md) |
+| Find or verify a primary source — the papers, project pages, and adjacent work behind a claim | [references/bibliography.md](references/bibliography.md) |
+
+## Quick Start
+
+The bundled CLI (`scripts/semantic-spacetime.py`) is stdlib-only — any
+`python3` runs it, nothing to install — and every command is read-only. Run
+the commands below from the repository root; the CLI resolves no files
+relative to its own location, so the same commands work from any directory
+with absolute paths.
+
+1. **Draft an SST model.** Copy `templates/sst-model.yaml.tmpl` to a working
+   file (for example `sst-model.yaml`) and replace the example values: declare
+   agents (id, role, promises), semantic nodes (id, type in
+   {event, thing, concept}), edges (from, to, link in -3..3), acceptances,
+   trajectories, and observations. The machine-delimited block between
+   `# --- example ---` and `# --- end example ---` shows a complete, valid
+   model to imitate; the same model is committed, fully filled, at
+   `tests/fixtures/sample-model.yaml`.
+2. **Lint it** against the sst-model-v1 format — exit 0 prints a coverage
+   summary, exit 1 prints named violations:
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model lint semantic-spacetime/tests/fixtures/sample-model.yaml`
+3. **Map the γ(3,4) graph** (`--format` is one of text | mermaid | json):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model map semantic-spacetime/tests/fixtures/sample-model.yaml --format mermaid`
+4. **Measure semantic distance** — weighted hop count (each hop weighs
+   |link| + 1):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model distance semantic-spacetime/tests/fixtures/sample-model.yaml --from report-event --to drift-concept`
+5. **Trace trajectories** — every simple path with link types annotated;
+   cycles are noted and the enumeration terminates on any finite model:
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model trajectory semantic-spacetime/tests/fixtures/sample-model.yaml --from report-event --to drift-concept`
+6. **Diff two snapshots** — added/removed/changed semantic regions; identical
+   snapshots report `no drift`. Point the command at your two snapshot files
+   (running it on the same file twice demonstrates the no-drift case):
+   `python3 semantic-spacetime/scripts/semantic-spacetime.py model drift semantic-spacetime/tests/fixtures/sample-model.yaml semantic-spacetime/tests/fixtures/sample-model.yaml`
+7. **Machine-readable output.** Append `--json` to any command for a single
+   JSON object on stdout. `--dry-run` is accepted everywhere as a no-op guard.
+8. **Draft the analysis report.** Copy `templates/sst-analysis.md.tmpl` to a
+   working file (for example `sst-analysis.md`) and fill the skeleton: system
+   description → semantic spacetime map → drift/divergence/absorbing-state
+   findings → interventions → verification/measurement plan.
+9. **Diagnose drift when agents disagree.** If agents diverge, treat the
+   disagreement as an observation, measure the semantic distance between their
+   interpretations, and locate the absorbing state or leaking boundary where
+   information stops flowing.
+
+## Related Skills
+
+| Skill | Route when... |
+|-------|---------------|
+| [promise-theory](../promise-theory/SKILL.md) | You need the substrate vocabulary SST builds on: promises, offers and acceptances, convergence, the Downstream Principle, and coordination diagnosis (also routed from `references/foundations.md`) |
+| [agent-evals-and-observability](../agent-evals-and-observability/SKILL.md) | You need to turn measurement and verification of semantic claims into evals, traces, and release gates (also routed from `references/foundations.md`) |
+| [agent-council](../agent-council/SKILL.md) | You want structured multi-agent debate as a mechanism for negotiating shared meaning between agents |
+| [workflow-architect](../bundles/workflow-architect/SKILL.md) | You want to encode a semantic-spacetime-informed workflow as a reusable skill bundle |
+| [artifact-pyramids](../artifact-pyramids/SKILL.md) | You need to structure SST evidence — models, maps, observations — as summaries → analysis → evidence dossiers |
+| [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 for SST models (it will follow cli-builder conventions: non-interactive, `--json`, `--dry-run`) |
+
+## Gotchas
+
+1. **Provenance honesty.** The theory files tag every factual claim
+   `[VERIFIED]` (confirmed in a primary source fetched during research) or
+   `[UNVERIFIED]` (secondary or inferred), and label original synthesis
+   `EXTRAPOLATION`. Preserve those markers when you reuse the material;
+   dropping a marker silently upgrades a claim. See the provenance block in
+   [references/foundations.md](references/foundations.md).
+2. **The theory is semi-formal and unrefereed.** Burgess published the series
+   as self-published notes with no intention of seeking refereed publication,
+   and "some proofs [are] left to the reader." Use SST as a reasoning aid, not
+   a proof system. See the status section in
+   [references/foundations.md](references/foundations.md).
+3. **Local time ≠ global clock.** Proper time is per semantic element: a local
+   change is that element's unit of time. There is no shared clock ordering all
+   events; global order is an observer-relative artifact. See the proper-time
+   section in [references/foundations.md](references/foundations.md).
+4. **Semantics requires measurement.** Meaning cannot be asserted before it is
+   measured at the right scale — "dynamics always trumps semantics" (the
+   CFEngine-lineage lesson in
+   [references/applications-infrastructure.md](references/applications-infrastructure.md)).
+   SST's spacelike (repeated trials, constant state) and timelike (continuously
+   adapting) measurements are the two ways to stabilize observation; see the
+   measurement-duality section of [references/foundations.md](references/foundations.md).
+5. **Promise-keeping must be stored as data.** The gap documented in the
+   CFEngine lineage — reporting whether a promise is kept right now without
+   ever storing promise-keeping as queryable data — is exactly the gap SST's
+   semantic-time record axis addresses (see the promise-keeping-as-data gap in
+   [references/applications-infrastructure.md](references/applications-infrastructure.md)).
+   Record observations as versioned data or trust cannot accumulate.
+
+## Exit Conditions
+
+Stop when the system is modeled as a semantic spacetime — semantic elements,
+γ(3,4) edges, trajectories, and acceptances recorded — drift/divergence/
+absorbing-state findings are written down, and a verification/measurement plan
+is stated. When diagnosing drift, stop after three non-converging passes and
+report the evidence instead of re-litigating the same model.

semantic-spacetime/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "schema_version": 1,
+  "skill_name": "semantic-spacetime",
+  "evals": [
+    {
+      "id": "gamma-3-4-typing-rules",
+      "case_set": "release",
+      "prompt": "I need to model a knowledge graph with the semantic-spacetime formalism. Explain the 2025 gamma(3,4) representation from the skill's foundations reference: the node meta-types it defines and the four link types with their integer values and meaning.",
+      "expected_output": "gamma(3,4) defines exactly three node meta-types: events (temporary, timelike process agents), things (persistent, spacelike realized agents), and concepts (invariant, unrealized potential). It defines exactly four link types: 0 = NEAR, symmetric, covering equivalence, similarity, proximity, and correlation; +/-1 = LEADS TO, directed, covering temporal and causal order such as enables, causes, precedes, and depends on; +/-2 = CONTAINS, directed, covering containment, membership, generalization, and coarse-graining; +/-3 = EXPRESSES, directed, covering attribute, name/value, and property. No additional link types exist in the formalism.",
+      "assertions": [
+        "response_contains:LEADS TO",
+        "response_contains:EXPRESSES",
+        "response_contains:concepts",
+        "response_not_contains:four node types",
+        "activation_evidence_contains:SKILL.md",
+        "exit_status:completed"
+      ]
+    },
+    {
+      "id": "proper-time-lamport-precedence",
+      "case_set": "release",
+      "prompt": "How does semantic spacetime define time, and how is causality established between agents? Which distributed-systems researcher is credited with the precedence view of time that semantic spacetime builds on?",
+      "expected_output": "Time is proper time: a local unit of time is any local change in a semantic element's state, promises, or configuration, as observed by the agent concerned, and there is no global clock shared across the spacetime. The precedence view of time as a relative transition system goes back to Leslie Lamport, whose 1978 paper on time, clocks, and the ordering of events in a distributed system showed that time can at best be understood as a precedence relation. Causality is cooperative: each adjacency requires both an offer and an acceptance promise on both ends, so space is made up of cooperating nodes and edges.",
+      "assertions": [
+        "response_contains:proper time",
+        "response_contains:Lamport",
+        "response_contains:no global clock",
+        "response_not_contains:Lorentz invariance",
+        "activation_evidence_contains:SKILL.md",
+        "exit_status:completed"
+      ]
+    },
+    {
+      "id": "absorbing-states-information-leak",
+      "case_set": "release",
+      "prompt": "My agent system sometimes reaches a state where no agent changes anything anymore and information stops flowing. What does semantic spacetime call these states, what happens to information there, and what does it say about where intent or policy can be injected?",
+      "expected_output": "These are absorbing states in a partial graph. Absorbing states are non-conserving of information: a graph process leaks information at them, closely associated with division by zero, which signals a loss of closure and the need for manual injection of remedial information. The boundary information at the leak is where intentionality can enter. In diagnosis, treat them as dead-ends in the gamma(3,4) map where meaning accumulates without propagating, and plan a manual or policy injection at that boundary.",
+      "assertions": [
+        "response_contains:absorbing states",
+        "response_contains:non-conserving",
+        "response_contains:intentionality",
+        "response_not_contains:fully converged success",
+        "activation_evidence_contains:SKILL.md",
+        "exit_status:completed"
+      ]
+    },
+    {
+      "id": "semantic-drift-diagnosis",
+      "case_set": "release",
+      "prompt": "Two agents in our system started from the same instructions but now produce incompatible reports: one means 'customer' as the paying account, the other as any user who ever signed up. Diagnose this using semantic spacetime vocabulary, and name the constructs you would use to model meaning changing over time.",
+      "expected_output": "This is semantic drift: the shared semantic ground between the two agents has diverged over time. Model each agent's interpretation as a trajectory through semantic spacetime, and measure the semantic distance between the two 'customer' concepts at successive observations to quantify the divergence. Because semantics requires measurement, record observations of each agent's usage at successive local times (spacelike or timelike measurement) rather than assuming the two interpretations still coincide. The two concepts have drifted apart along their trajectories, so re-anchor them and re-confirm the shared ground on a refresh budget.",
+      "assertions": [
+        "response_contains:semantic drift",
+        "response_contains:trajectory",
+        "response_contains:semantic distance",
+        "response_not_contains:retrain the embedding model",
+        "activation_evidence_contains:SKILL.md",
+        "exit_status:completed"
+      ]
+    },
+    {
+      "id": "metric-versus-semantic-distance",
+      "case_set": "release",
+      "prompt": "We have two ways to compare how close two concepts are in our system: coordinate similarity and interpretation similarity. Explain both from the semantic spacetime foundations, and give at least two worked examples of the interpretation-similarity kind.",
+      "expected_output": "The foundations distinguish metric (quantitative) distance, a measure of coordinate-similarity in position, from semantic (qualitative) distance, a measure of similarity in interpretation. Worked examples of semantic distance from the paper include Hamming distance, hop counts in an associative network, semantic hashing, and sparse distributed representations. The two measures can disagree: two concepts may be close in coordinates yet far in interpretation, so the choice of measure must follow the question being asked.",
+      "assertions": [
+        "response_contains:coordinate-similarity",
+        "response_contains:Hamming",
+        "response_contains:hop counts",
+        "response_not_contains:Euclidean only",
+        "activation_evidence_contains:SKILL.md",
+        "exit_status:completed"
+      ]
+    },
+    {
+      "id": "pure-embeddings-anti-trigger",
+      "case_set": "release",
+      "prompt": "We have a vector database with embeddings for all our documents and want to build semantic search over it. There is no temporal or causal structure, just static embeddings and similarity scores. Should we use the semantic-spacetime skill for this, and if not, why not?",
+      "expected_output": "No — do not use semantic spacetime for pure vector embeddings or RAG without temporal-causal structure. Semantic spacetime is a discrete graph model of meaning over time; a static embedding index has no proper time, no cooperative-promise causality, and no trajectories to model, so the machinery is overhead rather than insight. Route to the embedding or semantic-search tool's own skill instead. Use semantic spacetime only when there is meaning changing over time, causal-temporal structure, or agents whose shared semantic ground needs to be modeled.",
+      "assertions": [
+        "response_contains:do not use semantic spacetime",
+        "response_contains:without temporal-causal structure",
+        "response_contains:shared semantic ground",
+        "response_not_contains:model the embedding index as semantic elements",
+        "activation_evidence_contains:SKILL.md",
+        "exit_status:completed"
+      ]
+    }
+  ]
+}

semantic-spacetime/references/agent-coordination.md

@@ -0,0 +1,112 @@
+# Agent Coordination — SST and Promise Theory for Multi-Agent Systems
+
+**Load this file when you need to design or diagnose coordination between AI agents** — modeling an agent team in SST terms, choosing a coordination substrate, detecting drift between agents' world models, or using SST's machinery to reason about delegation, shared meaning, and temporal blindness. This is the agentic-AI companion to [foundations.md](foundations.md) (formal model and γ(3,4) definitions) and [patterns.md](patterns.md) (named patterns to apply).
+
+**What belongs here:** Burgess's 2025–26 agent papers (arXiv:2604.10505, 2512.19084, 2507.10000), the working software (SSTorytime, MCP-SST), the drift and temporal-blindness literature, spatial-temporal world models and the neuroscience substrate, the MCP/A2A coordination substrate, the honest industry record (including Anthropic's documented delegation failure), and — explicitly labeled `[EXTRAPOLATION]` — five synthesis patterns for using SST as an agent-coordination model. What does **not** belong here: the CFEngine/infrastructure lineage (see [applications-infrastructure.md](applications-infrastructure.md)); the full γ(3,4) formalism (see [foundations.md](foundations.md)); the diagnosis procedure (see [diagnosis-and-debugging.md](diagnosis-and-debugging.md)); and the promise-level machinery of offers, acceptances, and trust (see [promise-theory](../../promise-theory/SKILL.md) — linked, not restated).
+
+**Provenance.** `[VERIFIED]` = confirmed in a fetched primary source (arXiv abstract/full text, official docs, GitHub); `[UNVERIFIED]` = secondary or inferred; `[EXTRAPOLATION]` = this skill's original synthesis, labeled wherever it appears and grounded in verified sources.
+
+---
+
+## 1. Burgess's agent-cooperation program: the four load-bearing concepts
+
+*Cooperation in Human and Machine Agents: Promise Theory Considerations* (arXiv:2604.10505, April 2026) is Burgess's explicit "revisit[ing] [of] established principles of agent cooperation, as applied to humans, machines, and their mutual interactions" in the era of AI agents [VERIFIED — arXiv:2604.10505, full text read]. Four concepts carry the paper, all `[VERIFIED]`:
+
+1. **No agent may promise anything on behalf of any agent but itself.** "Autonomy is the base state of any operational entity, human or machine," and the fundamental tenet is that no agent may promise on behalf of any other; attempts to work around this "account for almost all misunderstandings and errors in agent systems" [VERIFIED — arXiv:2604.10505]. This is the coordination-layer statement of promise-theory's autonomy axiom — for the promise-theory treatment, see [promise-theory](../../promise-theory/references/foundations.md).
+2. **The Downstream Principle (Def. 1).** "Agents downstream… have the ultimate power of decision over the outcome." For autonomous agents causality is inverted: the receiver decides what it accepts, and responsibility flows downstream (a client is responsible for its own use of a service) [VERIFIED — arXiv:2604.10505].
+3. **Offer / acceptance with an overlap.** Coordination is voluntary: offer `Ai →+bi Aj` plus acceptance `Aj →−bj Ai`; influence flows only if both are kept, and the propagated content is the overlap (mutual information) `b∩ = bi ∩ bj`. Impositions are "generally ineffective" [VERIFIED — arXiv:2604.10505]. (The offer/acceptance machinery itself is promise-theory territory — link to [promise-theory](../../promise-theory/references/foundations.md), do not re-derive here.)
+4. **Trust as energy.** Trustworthiness is a potential `V`; mistrust drives kinetic sampling at rate `v = √(2(VR−VS−risk)/ρ)` — "trust is really a form of work or energy in the physics sense," whose function is to reduce the overhead of managing a promise dependency [VERIFIED — arXiv:2604.10505; the model is developed in Burgess & Dunbar, *European Economic Review*, 2025].
+
+Two further results matter for coordination design. **Convergent fixed points as the safety pattern**: CFEngine engineered certainty via mathematical fixed points — iterative evaluation `π̂|q⟩ ↦ |qπ⟩` converges on the promised state, and "convergent fixed-point outcomes are the only plausible safeguard in safety critical goals" [VERIFIED — arXiv:2604.10505]. **Swarms vs. teams (Def. 6)**: "a swarm is an ensemble of agents, which are basically similar, and has no leader"; a team has differentiated roles and clear promises — microservices are "a team structure applied to information technology" [VERIFIED — arXiv:2604.10505]. The paper also quantifies proxy chains: fully-promised delivery through N intermediaries costs O(N²), and at minimal trust the promise graph must be complete [VERIFIED — same source]. See [promise-theory's agent-coordination reference](../../promise-theory/references/agent-coordination.md) for the operational mapping of these concepts onto multi-agent engineering practice.
+
+## 2. γ(3,4) "Attention" in cognitive agents: graphs preserve intentionality
+
+*γ(3,4) 'Attention' in Cognitive Agents: Ontology-Free Knowledge Representations with Promise Theoretic Semantics* (arXiv:2512.19084, December 2025) applies the γ(3,4) representation to cognitive agents without relying on LLMs implicitly [VERIFIED — arXiv:2512.19084]. The load-bearing claim: **"while vectorized data are useful for probabilistic estimation, graphs preserve the intentionality of the source even under data fractionation"** [VERIFIED — arXiv:2512.19084]. The γ(3,4) graph "avoids complex ontologies in favour of classification of features by their roles in semantic processes" and "favours an approach to reasoning under conditions of uncertainty" [VERIFIED — same source]; "appropriate attention to causal boundary conditions may lead to orders of magnitude compression of data required for such context determination" [VERIFIED — same source, Burgess's claim, not independently benchmarked]. The full formal definition (3 node meta-types × 4 link types, the nine typing rules) belongs to [foundations.md](foundations.md) §2 — this file only summarizes and routes.
+
+The intentionality-vs-vectorization contrast is the key design trade for agent systems: embeddings are good for probabilistic estimation but their "interior spaces" have "inscrutable property models"; a typed γ(3,4) graph keeps the *kind* of relation (causal, containment, attribute, similarity) explicit even when data is fragmented across agents [VERIFIED — arXiv:2512.19084; arXiv:2506.07756].
+
+## 3. Working software: SSTorytime and MCP-SST
+
+The SST line ships real, current software — evidence it is "working software, not vaporware" [VERIFIED — GitHub, fetched 2026-08-12]:
+
+- **SSTorytime** (github.com/markburgess/SSTorytime): "an independent Knowledge Graph, based on Semantic Spacetime… aims to be both easier to use and more powerful than RDF" [VERIFIED — GitHub]. A Go library + Postgres knowledge-graph store with the **N4L note query language** and the `searchN4L`, `pathsolve`, `graph_report` tool set; ~158 stars and active through 2026-08-12 [VERIFIED — GitHub]. It ships an embedded Agent Skills-format skill — a `SKILL.md` under `.claude-plugin/skills/SSTorytime/` with `name`, trigger-style `description` (TRIGGER when the user asks about notes on a subject; SKIP for RDF questions), and `allowed-tools` — a real-world instance of the Agent Skills pattern inside the SST ecosystem [VERIFIED — GitHub].
+- **MCP-SST** (github.com/markburgess/MCP-SST): "an MCP to SST proxy" — a Model Context Protocol server advertising the **`N4Lquery`** tool on `tools/list`, so "an LLM client like Claude Code can drive the SSTorytime knowledge graph in natural language — no hand-crafted JSON-RPC needed" [VERIFIED — GitHub]. The README shows an LLM generating an SVG orbit visualization of the word "brain" from one MCP tool call [VERIFIED — GitHub]. Note the direction: MCP-SST is **agent ↔ tool** (an LLM client querying a graph tool), not agent ↔ agent — it wires SST into modern agentic infrastructure as a tool substrate [VERIFIED — GitHub; MCP spec].
+- Community spinoffs: Simon Frost's Julia `SemanticSpacetime.jl` and `CQL.jl` ("From Causal SQL to Semantic Spacetime via CQL") [VERIFIED — SSTorytime README].
+
+## 4. Intentionality, co-language, and the three-languages problem
+
+**Intentionality measurement.** *On The Role of Intentionality in Knowledge Representation: Analyzing Scene Context for Cognitive Agents with a Tiny Language Model* (arXiv:2507.10000, July 2025) applies SST as an effective Tiny Language Model: agents can detect "a degree of latent 'intentionality' in data by looking for anomalous multi-scale anomalies and assessing the work done to form them"; **scale separation** sorts content into "intended" vs "ambient context," using spacetime coherence as a measure — "at very low computational cost, without reference to extensive training or reasoning capabilities" [VERIFIED — arXiv:2507.10000]. This is the measurement arm: intentionality is detected, not assumed, by separating scales.
+
+**Co-language / three-languages.** From arXiv:2604.10505: each agent pair has three languages — the sender's, the receiver's, and the exchange *co-language*; translation between them is generically non-unitary, so "agents should expect to misunderstand one another's intentions to some level," and decompressing discourse to approximate unitarity is risky ("saying too much could make things worse"); the key line is "autonomous agents are never certain" [VERIFIED — arXiv:2604.10505]. This is the meaning-negotiation substrate of the whole SST line — and it is promise-theory's three-languages/meaning-negotiation problem. Per the no-duplication rule, the full treatment lives in [promise-theory](../../promise-theory/references/agent-coordination.md); this file uses the concept and links rather than restating the machinery.
+
+**Two labeled synthesis connections** (both `[EXTRAPOLATION]`, grounded in §4's sources): (a) the co-language machinery is the micro-mechanism underneath the shared-semantic-ground synthesis (§8.1) — agents converge on a working overlap `b∩` by negotiating a co-language, and the shared manifold is that overlap made persistent [EXTRAPOLATION — grounded in arXiv:2604.10505]; (b) it is also the diagnosis lens for delegation failure — Anthropic's documented vague-delegation failure (§7) is a small overlap `b∩` between the orchestrator's instruction language and the subagent's comprehension language, exactly what "agents should expect to misunderstand one another's intentions to some level" predicts [EXTRAPOLATION — grounded in arXiv:2604.10505 and Anthropic's engineering post].
+
+## 5. Drift literature: the empirical evidence closest to SST
+
+Three papers form the empirical core of agent drift — each with its central construct, its metric, and an explicitly labeled SST mapping [paper facts `[VERIFIED]`; mappings `[EXTRAPOLATION]`]:
+
+### 5.1 Context drift (arXiv:2606.21666, June 2026)
+
+*Hallucination as Context Drift: Synchronization Protocols for Multi-Agent LLM Systems* argues "a significant class of these failures arises… from context drift: the divergence of internal knowledge states between concurrent agents" [VERIFIED — arXiv:2606.21666]. Central constructs: a **Context Divergence Score (CDS)** over "spatial, temporal, and task dimensions," and a **Shared State Verification Protocol (SSVP)** in which "agents periodically exchange compressed state summaries and flag high-divergence conditions before joint reasoning" [VERIFIED — same source]. Key finding: naive full-broadcast sync *increases* hallucination by **34%** (contamination); selective sync reduces it (HR 0.463) with 58% fewer API calls — "refram[ing] hallucination mitigation as a distributed systems problem… context synchronization as a first-class primitive" [VERIFIED — same source]. **SST mapping [EXTRAPOLATION]**: context divergence is divergence between agents' world states in a semantic spacetime; the SSVP is an evaluation loop correcting toward promised (shared) states; contamination from full-broadcast sync is an information-leaking absorbing process — broadcasting unaccepted offers floods every agent with data that leaks its intentionality [EXTRAPOLATION — grounded in arXiv:2606.21666 and the absorbing-states doctrine of arXiv:2506.07756].
+
+### 5.2 Agent drift (arXiv:2601.04170, January 2026)
+
+*Agent Drift: Quantifying Behavioral Degradation in Multi-Agent LLM Systems* defines drift as "progressive degradation of agent behavior, decision quality, and inter-agent coherence over extended interaction sequences," with three manifestations: **semantic drift** (deviation from original intent), **coordination drift** (breakdown of consensus), and **behavioral drift** (unintended strategies) [VERIFIED — arXiv:2601.04170]. Central metric: the **Agent Stability Index (ASI)** over twelve dimensions, with mitigations including episodic memory consolidation, drift-aware routing, and adaptive behavioral anchoring [VERIFIED — same source]. **SST mapping [EXTRAPOLATION]**: the three drift types are three axes of divergence in semantic spacetime — semantic drift is displacement along the meaning coordinates, coordination drift is inter-agent trajectory separation, behavioral drift is divergence between the promised and actual path [EXTRAPOLATION — grounded in arXiv:2601.04170 and §8.2].
+
+### 5.3 Drift as bounded equilibrium (arXiv:2510.07777, 2025)
+
+*Drift No More? Context Equilibria in Multi-Turn LLM Interactions* formalizes drift as turn-wise **KL divergence** from a goal-consistent reference, evolving as "a bounded stochastic process with restoring forces"; it finds "stable, noise-limited equilibria rather than runaway degradation," and reminder interventions reliably reduce divergence [VERIFIED — arXiv:2510.07777]. **SST mapping [EXTRAPOLATION]**: bounded equilibria with restoring forces are CFEngine's fixed-point attractors in the semantic domain — the same "ball rolling into a potential well" (§1, applications-infrastructure §2) with reminders acting as reaffirmed acceptance promises [EXTRAPOLATION — grounded in arXiv:2510.07777 and arXiv:2604.10505's fixed-point convergence].
+
+## 6. Temporal blindness, spatial-temporal world models, and the neuroscience substrate
+
+Four verified results anchor SST's claim that relational knowledge and space/time share substrate:
+
+1. **LLM agents are temporally blind** (arXiv:2510.23853, ACL 2026 Findings): agents "by default assume a stationary context, failing to account for the real-world time elapsed between messages," causing over- or under-use of stale context in tool-use decisions; in a benchmark, **no model achieving a normalized alignment rate better than 65% when given time stamp information** [VERIFIED — arXiv:2510.23853]. (The 65% figure is benchmark-specific; do not over-generalize it into "models are ≤65% at temporal tasks" [UNVERIFIED — generalization beyond the benchmark].)
+2. **LLMs build linear spatial-temporal world models** (Gurnee & Tegmark, *Language Models Represent Space and Time*, arXiv:2310.02207, ICLR 2024): Llama-2 learns linear representations of space and time across scales, robust to prompting, with identifiable "space neurons" and "time neurons"; "modern LLMs… possess basic ingredients of a world model" [VERIFIED — arXiv:2310.02207].
+3. **The Tolman-Eichenbaum Machine** (Whittington et al., *Cell* 2020) unifies spatial and relational memory: the same code supports "where" and "what relates to what" — semantics and space share a substrate [VERIFIED — Cell 2020; Behrens et al., *Neuron* 2018]. Burgess's γ(3,4) claims "human concepts ultimately derive from concepts about space and time" [VERIFIED — arXiv:2506.07756].
+4. **Grid cells furnish a Euclidean metric** (Banino et al., *Nature* 557, 2018): emergent grid-like cells provide agents "with a Euclidean spatial metric and associated vector operations" [VERIFIED — Nature 2018].
+
+The SST tie, labeled per provenance rules: these are independent lines of evidence that space and meaning share machinery — which is exactly what SST formalizes as a graph in which *both* coordinates and semantic relations live on one structure [EXTRAPOLATION — grounded in the four verified results above; the "share substrate" sentence is the neuroscience literature's own framing, the SST identity is this skill's reading].
+
+## 7. The coordination substrate: MCP, A2A, the unformalized gap, and the honest industry record
+
+- **MCP (Model Context Protocol)** is the agent ↔ tool substrate (Anthropic, Nov 2024): JSON-RPC standardizing **Resources** (context/data), **Prompts** (templated workflows), and **Tools** (functions the model executes), plus client-side Sampling, Roots, and — in the 2026 release-candidate extensions — Tasks and MCP Apps [VERIFIED — MCP spec 2025-11-25; MCP blog 2026-07-28]. "MCP is for agent-to-tool communication" [VERIFIED — MCP spec].
+- **A2A (Agent2Agent Protocol)** is the agent ↔ agent substrate (Google, April 2025; Linux Foundation, June 2025): "an open protocol enabling communication and interoperability between opaque agentic applications" — agents "interact without needing to share internal memory, tools, or proprietary logic" [VERIFIED — a2a-protocol.org]. The **AgentCard** is the capability manifest: a machine-readable JSON document describing an agent's name, skills, endpoints, auth, and transports [VERIFIED — same source]. A2A and MCP are complementary: agent↔agent vs. agent↔tool [VERIFIED — same source].
+- **The unformalized gap**: neither substrate formalizes *what the common semantic ground between two agents is* or how to measure its absence; A2A keeps agents opaque, leaving semantics to per-exchange negotiation [EXTRAPOLATION — grounded in the A2A docs' opacity design and the drift literature's divergence measures]. This is precisely where SST adds value.
+- **Anthropic's documented delegation failure**: the orchestrator-worker engineering post reports that delegation quality depends on detailed task descriptions — without them "subagents misinterpret the task or perform the exact same searches" [VERIFIED — anthropic.com/engineering/multi-agent-research-system]. This is a documented operational failure mode, not a ranking: the research does not support a "#1" ranking of coordination substrates, and none is asserted here [VERIFIED — the research's own searches found no such ranking]. It is also subagents performing duplicated work, which in SST terms is two trajectories toward the same absorbing region without a shared anchor (§8.3, §8.5).
+- **The honest negative result**: no mainstream LLM-agent framework, observability platform, or enterprise multi-agent system uses SST or promise theory as its coordination model [VERIFIED — negative result of this research phase's searches]. The limitation must be stated with it: this is absence of evidence from a bounded search session, not proof of impossibility [VERIFIED — research report §2.8; the caveat is the report's own framing]. SST remains a small, deep-specialist program (Burgess's papers and software, a 2025 self-published book, a 2018 UiO thesis, data-pipeline startups, and 5G interest) [VERIFIED — agentic-ai report §2.8].
+
+## 8. Synthesis: five patterns for SST as a coordination model
+
+Each pattern below is this skill's **original synthesis — labeled `[EXTRAPOLATION]`** — and each names the verified research it builds on. None is implemented or measured at scale yet; treat them as hypotheses to test (see §9).
+
+### 8.1 Shared semantic manifold with causal-temporal structure as coordination substrate `[EXTRAPOLATION]`
+
+Give a multi-agent system a shared γ(3,4)-structured representation (nodes = events/things/concepts; links = near/leads-to/contains/expresses) as the coordination substrate, instead of raw token contexts or opaque agent cards. Each agent maintains its own projection of the shared manifold plus its interior state; coordination happens by comparing projections, not by exchanging full context. **Grounding**: γ(3,4) and "graphs preserve the intentionality of the source" (arXiv:2512.19084); A2A's opacity + AgentCard manifests (a2a-protocol.org); GraphRAG's LLM-generated graphs (arXiv:2404.16130); Tolman-Eichenbaum showing spatial and relational memory share machinery (Cell 2020); MCP-SST already demonstrating the plumbing (an LLM querying an SST graph through MCP). **Value-add**: a typed, directional shared representation lets agents agree on *what type of relation* a statement claims — the ambiguity the context-drift literature shows is costly (arXiv:2606.21666).
+
+### 8.2 Agent trajectories through semantic space as first-class observables `[EXTRAPOLATION]`
+
+Treat every agent as tracing a trajectory through semantic spacetime: a sequence of {position, intent (promise), time} steps. Drift = displacement from the promised path; divergence = inter-agent trajectory separation; convergence = approach to a shared fixed point; absorbing state = task dead-end requiring boundary injection (human input / a new promise). **Grounding**: intent as "an agent's 'direction of travel' in some space of possibility" (arXiv:2604.10505); absorbing states and division-by-zero (arXiv:2506.07756); linear space/time coordinates in LLMs (arXiv:2310.02207); drift and divergence metrics (arXiv:2601.04170, arXiv:2606.21666); observability/evals as trajectory recording (OpenTelemetry GenAI conventions; LangSmith/Langfuse; Anthropic's end-state evals). **Value-add**: gives observability a geometry — "how far am I from my promised state?" and "how far apart are our world models?" with a defined semantic metric, going beyond turn-wise KL divergence (arXiv:2510.07777).
+
+### 8.3 Promise propagation through semantic spacetime as inter-agent commitments `[EXTRAPOLATION]`
+
+Model delegation as promise propagation: an orchestrator's task description is an offer (+b); a subagent's acceptance is acceptance (−b); the effective task is the overlap `b∩`; the Downstream Principle makes the accepting agent responsible for the outcome; long chains inherit the O(N²) assurance cost; "trust" sets the monitoring/sampling rate. **Grounding**: offer/acceptance, Downstream Principle, proxy chains, contracts as bilateral promise collections, fixed-point convergence (arXiv:2604.10505); Anthropic's finding that vague delegation causes misinterpreted/duplicated work — i.e., low offer/acceptance overlap (multi-agent research system); A2A task delegation (a2a-protocol.org). **Value-add**: a principled diagnosis for a documented failure — the promise overlap was small; the fix is explicit negotiation/expansion of the co-language (§4).
+
+### 8.4 Semantic-distance metrics for delegation decisions `[EXTRAPOLATION]`
+
+Use semantic distance in the shared manifold (typed, not just cosine) to route tasks: delegate to the agent whose capability region (AgentCard → concepts/things it can act on) is nearest to the task's required concepts; prefer redundant providers for critical promises (Downstream Principle); escalate when distance to a trusted solution exceeds a risk budget. **Grounding**: embeddings/RAG distance machinery (arXiv:2005.11401; Anthropic's research system); Gärdenfors conceptual spaces (convex regions, prototypes); A2A AgentCards as capability manifests; promise-theory redundancy doctrine (arXiv:2604.10505); Context Divergence Score as a proto-metric (arXiv:2606.21666). For the formal definition of semantic distance (metric vs. semantic), see [foundations.md](foundations.md) §8.
+
+### 8.5 Detection of semantic drift between instruction, implementation, and reality `[EXTRAPOLATION]`
+
+The highest-value diagnostic: track three trajectories — *instruction* (promised state), *implementation* (the agent's actual path), *reality* (observed world state) — and alert when their pairwise semantic distances exceed a threshold, or when an agent's path enters an absorbing state (hallucination, task collapse) that leaks information. **Grounding**: semantic/agent drift (arXiv:2601.04170); context drift and synchronization protocols (arXiv:2606.21666); context equilibria and reminder interventions (arXiv:2510.07777); absorbing states as "boundary information where intentionality can enter" (arXiv:2506.07756); CFEngine fixed-point convergence — "keep applying the map until |qπ⟩" (arXiv:2604.10505); Anthropic's end-state evaluation. **Value-add**: a convergence-based correction loop (re-apply the promise map, re-affirm acceptance, inject boundary information when stuck) — the mechanism CFEngine proved at datacenter scale and the drift literature is rediscovering empirically. This is the diagnostic pattern developed in [patterns.md](patterns.md) and [diagnosis-and-debugging.md](diagnosis-and-debugging.md).
+
+## 9. Caveats on the synthesis
+
+- SST is a formal theory with a small empirical footprint; the mappings in §8 are interpretive, not yet implemented or measured [EXTRAPOLATION].
+- Burgess labels his own strong claims as hypotheses — "this remains a hypothesis for now" for the claim that four relation types suffice (arXiv:2506.07756) [VERIFIED — arXiv:2506.07756].
+- The theory is semi-formal and deliberately unrefereed; use the synthesis here as a reasoning aid, not a proof system (full disclosure in [foundations.md](foundations.md) §5 and [applications-infrastructure.md](applications-infrastructure.md) §10) [VERIFIED — markburgess.org].
+- Adoption barriers to name honestly: SST's formalism is dense; its tooling (SSTorytime/MCP-SST) is early-stage with a small community; the mainstream stack is embedding/vector-first [VERIFIED — GitHub activity; UNVERIFIED — the market-readiness assessment is opinion].
+
+## Sources and routing
+
+The full annotated source list with URLs is in [bibliography.md](bibliography.md). Key sources for this file: arXiv:2604.10505, 2512.19084, 2507.10000, 2506.07756, 2606.21666, 2601.04170, 2510.07777, 2510.23853, 2310.02207, 2404.16130, 2005.11401, 1803.10122; Banino et al. (Nature 2018); Whittington et al. (Cell 2020); Behrens et al. (Neuron 2018); a2a-protocol.org; modelcontextprotocol.io; anthropic.com/engineering/multi-agent-research-system; github.com/markburgess/SSTorytime; github.com/markburgess/MCP-SST. For promise-level machinery (offer/acceptance, Downstream Principle, trust calibration), load [promise-theory](../../promise-theory/SKILL.md) and its [agent-coordination](../../promise-theory/references/agent-coordination.md) and [patterns](../../promise-theory/references/patterns.md) references; for the formal γ(3,4) definitions, [foundations.md](foundations.md); for patterns to apply, [patterns.md](patterns.md); for diagnosis, [diagnosis-and-debugging.md](diagnosis-and-debugging.md).

semantic-spacetime/references/applications-infrastructure.md

@@ -0,0 +1,127 @@
+# Applications in Infrastructure — CFEngine, Convergence, and the Descendant Ecosystem
+
+**Load this file when you need the empirical record behind Semantic Spacetime (SST):** what the convergence/promise line actually did in thirty years of real infrastructure — CFEngine's mechanism set, the declarative-IaC / Kubernetes / GitOps / IBN / MAPE-K descendants that each inherited a piece of it, the time-and-space machinery (Lamport causality, event sourcing, bi-temporal records, versioned data namespaces) SST's line implies, and the distilled, citable lessons for designing convergent systems.
+
+**What belongs here:** the infrastructure history and its lessons — CFEngine, the descendant ecosystem, "dynamics always trumps semantics," SLOs as semantic contracts, promise-keeping-as-data, and the record-of-time layer (event sourcing, bi-temporal axes, arXiv:2204.00470). What does **not** belong here: the formal SST model itself (definitions, γ(3,4), proper time, the promise substrate — see [foundations.md](foundations.md)); agent-team coordination and the agentic-AI literature (see [agent-coordination.md](agent-coordination.md)); named design patterns (see [patterns.md](patterns.md)); and the diagnosis procedure (see [diagnosis-and-debugging.md](diagnosis-and-debugging.md)). Where promise-level machinery is involved (promise, offer/acceptance, assessment, convergence mechanics), this file links to [promise-theory](../../promise-theory/SKILL.md) rather than re-teaching it.
+
+**Provenance.** Every factual claim below carries exactly one marker: `[VERIFIED]` (confirmed in a primary source fetched during the research phase; source named), `[UNVERIFIED]` (secondary, opinion, or inferred; reason named), or `EXTRAPOLATION` (this skill's own synthesis, explicitly labeled). Do not drop markers when reusing this content.
+
+---
+
+## 1. The lineage at a glance
+
+The SST line has a concrete, traceable industrial ancestor. **CFEngine was written by Mark Burgess in 1993** at the University of Oslo, initially to automate workstation management [VERIFIED — CFEngine Wikipedia; InfoQ CFEngine article]. Its core ideas — convergence to a desired end-state, classes, promises as the unit of policy, the immunity model of self-repair, and compliance measured by the repair loop itself — are the same ideas SST later formalizes as a graph model of meaning over time. **The interpretive framing that "CFEngine is the working prototype / reference implementation of the SST/promise-theory line" is this research phase's own synthesis, not a claim in any cited source** [EXTRAPOLATION — research synthesis, infrastructure-applications report §1]. It must not be read as "CFEngine was built from SST": CFEngine (1993) predates Promise Theory (~2004–05, first presented at DSOM 2005) and SST (2014, arXiv:1411.5563) by a decade or more [VERIFIED — CFEngine Wikipedia; academic foundations]. What the lineage claim means is the reverse: SST formalizes, with time and semantics added, the machinery CFEngine already ran in production.
+
+The mechanism set itself is well documented and tagged `[VERIFIED]` throughout §2. The industry that followed inherited the machinery piecemeal (§5), and the recurring gap is that the *record* of promise-keeping was never stored as data (§6) — exactly the semantic-time capability SST's versioned record axis would supply (§8).
+
+## 2. CFEngine: the mechanism set (all `[VERIFIED]`)
+
+Sources for this section: Burgess's own *A Tiny Overview of CFEngine: Convergent Maintenance Agent* (markburgess.org/papers/tiny_intro.pdf), the InfoQ article "CFEngine's Decentralized Approach to Configuration Management" (2014), and the CFEngine Wikipedia article. All quotes below are from those fetched sources.
+
+1. **Convergence to a desired end-state (fixed point).** A convergent operator satisfies `O(q0) = q0` and `O^2 = O` at the desired endpoint; "idempotence requires only O^2 = O, while convergence is relative to a specific policy state q0" [VERIFIED — Burgess, *A Tiny Overview*]. Convergent semantics behave "like a ball rolling into a potential well"; once converged, agent action desists [VERIFIED — same source]. The Wikipedia framing adds that convergence is "now often inaccurately just called idempotence" [VERIFIED — Burgess Wikipedia].
+2. **Statistical convergence, never exact.** "A complete specification of policy determines an approximate configuration of a software system only approximately over persistent times. There are fundamental limits to the tolerances a system can satisfy with respect to policy compliance in a stochastic environment" [VERIFIED — *A Tiny Overview*]. Desired state is a fixed-point *attractor* in a stochastic environment, not a guarantee; the approach rate is set by "the ratio of the frequency of environmental change to the rate of CFEngine execution" [VERIFIED — *A Tiny Overview*; *On the theory of system administration* via Wikipedia].
+3. **Classes.** Promises are conditioned on *classes* — OS type, time, user-defined contexts — so the same policy text applies different promises under different conditions [VERIFIED — InfoQ CFEngine article; CFEngine Wikipedia]. (SST's later framing calls coarse-grained context flags "classes" too, in Burgess's knowledge-graph essays [VERIFIED — Medium, *The Role of Intent and Context*, 2025].)
+4. **Promises as the unit of policy.** CFEngine 3's documentation is explicit that promises are the central concept and everything else is an abstraction for declaring them; agents on every host pull and cache policy and decide locally whether to keep it [VERIFIED — CFEngine 3 docs via InfoQ]. Policy is federated: "an agent cannot be forced into submission by an external authority" [VERIFIED — InfoQ].
+5. **The immunity model of self-repair.** Health = policy compliance, deviation = sickness, and repair is modeled as error correction over a noisy channel in Shannon's sense — the "Computer Immunology" (1998) manifesto for self-healing systems [VERIFIED — LISA98 *Computer Immunology*; *A Tiny Overview*]. Independent convergent operations commute: "multiple orthogonal, convergent operations will always lead to the correct configuration, no matter which part of the configuration is incorrect, or in what order things occur"; failed steps can be repeated later [VERIFIED — *A Tiny Overview*].
+6. **The default 5-minute repair loop.** Agents "verify whether these promises are kept (and usually takes measures to keep them) every five minutes, by default" [VERIFIED — InfoQ CFEngine article].
+7. **Compliance without independent monitoring.** CFEngine yields "immediate and continuous measurements of compliance based on a documented model of intent, without the need for independent monitoring" [VERIFIED — InfoQ CFEngine article].
+
+Two further CFEngine-era lessons matter for SST: (a) the "congruence" alternative — destroy-and-rebuild, proposed by S. Traugott — versus convergent repair; Burgess's rebuttal was that "only the convergent approach can be used for realtime maintenance" [VERIFIED — *A Tiny Overview*]. (b) Burgess's 2014 stance that "immutability" is "politics, not science," preferring "disposable computing — throw away a broken process rather than trying to fix it" [VERIFIED — InfoQ, *In Search of Certainty* review/interview]. Both debates re-ran later in containers and immutable infrastructure.
+
+## 3. "Dynamics always trumps semantics" — meaning requires measurement
+
+The single most load-bearing lesson for SST practitioners: **"It is not possible to reason about semantics without taking into account the underlying dynamics"** [VERIFIED — InfoQ, *In Search of Certainty* book review and interview, 2014]. Meaning cannot be asserted before the dynamics are measured. The corollary is that measurement must happen **at the right scale**: "the ability to distinguish and separate scales is closely allied with our notions of simplicity," and different scales yield contradictory measurements — a system can look healthy at the requests-per-second scale while its disks are filling and its semantics (as users experience them) are degrading [VERIFIED — same source].
+
+This is the operational form of SST's measurement duality (spacelike ensemble vs. timelike cognitive measurement) developed in [foundations.md](foundations.md) §7; the infrastructure phrase is the earlier, engineering-tested statement of the same rule. Practically: any SST analysis that reasons about meaning without an explicit measurement plan (what to observe, at what scale, how often) is guesswork.
+
+## 4. SST's time lineage: Lamport causality, event sourcing, bi-temporal records
+
+SST descends from **Lamport's causal time**. Lamport's 1978 *"Time, Clocks, and the Ordering of Events in a Distributed System"* (CACM 21(7):558–565) establishes that "there is no invariant total ordering of events in space-time… there is only a partial order in which an event e1 precedes an event e2 iff e1 can causally affect e2" [VERIFIED — Lamport via Microsoft Research]. Burgess explicitly places SST in this line: "The view of time as a relative transition system goes back to the work of Leslie Lamport… time can at best be understood as a precedence relation, in a discrete spacetime context" [VERIFIED — markburgess.org, *Semantic Spacetime — What is it?*]. Wall-clock time is not the ordering primitive; causality is. This section is SST's *semantic-time* territory, not a promise-theory restatement: the promise machinery of offers and acceptances lives in [promise-theory](../../promise-theory/references/foundations.md).
+
+Two further record-of-time mechanisms belong to the same lineage:
+
+- **Event sourcing** (Fowler, 2005): "capture all changes to an application state as a sequence of events" — enabling complete rebuild by replay, temporal query of state at any point in time, and event correction [VERIFIED — martinfowler.com, *Event Sourcing*]. Fowler's documented caveat: external systems "don't know the difference between real processing and replays," so gateways must be replay-aware and external queries must be logged; temporal corrections lead to "bi-temporal behavior" and "this stuff can get very messy, don't go down this path unless you really need to" [VERIFIED — same source]. Event logs are the honest time dimension of state: semantic correctness over time (what did we *believe* when) requires recording both fact and belief.
+- **Bi-temporal databases**: a temporal database tracks **valid time** (when a fact is true in the real world — the world axis) and **transaction time** (when it was recorded — the record axis), optionally decision time; "historical information… is provided by the valid time. Rollback… is provided by the transaction time" [VERIFIED — Temporal database Wikipedia]. The two answers can differ: "the database may have been altered since 1992" [VERIFIED — same source]. SQL:2011 adopted a reduced version (application-time period tables, system-versioned tables); the richer TSQL2 proposal was killed in committee after criticism by Date and Darwen [VERIFIED — same source].
+
+The lesson for SST: any "state over time" system must separate the *world* axis from the *record* axis. Conflating them is the classic audit failure, and — as §6 and §8 show — it is precisely the axis SST's promise-keeping capability supplies.
+
+## 5. The descendant ecosystem: who inherited what, and the gap each leaves
+
+Each descendant below is stated with its inheritance mechanism and its gap/lesson, all from the fetched sources named.
+
+### 5.1 Declarative IaC — Terraform, Ansible, Chef, Puppet, Nix
+
+- **Terraform**: declarative config; `plan` diffs desired configuration against actual state; `apply` executes; drift is "when the real-world state of your infrastructure differs from the state defined in your configuration" [VERIFIED — HashiCorp, "Detecting and Managing Drift with Terraform"]. The state file maps config to real resources; `refresh` reconciles before every plan/apply; lifecycle flags tune reconciliation [VERIFIED — same source]. **Gap**: Terraform is invoked, not a loop — "Terraform cannot detect drift of resources… that are not managed using Terraform" [VERIFIED — HashiCorp]. The sharper 2026 reading — "`terraform plan` diffs one file against another file. It does not observe your infrastructure. Between applies, Terraform has no awareness" — is opinion, marked [UNVERIFIED — webframp.com, 2026]. A state file is memory of a past action, not perception; drift accumulates until a human runs the tool.
+- **Ansible**: idempotent modules — "most Ansible modules check whether the desired final state has already been achieved and exit without performing any actions if that state has been achieved" [VERIFIED — Ansible docs]; control node pushes tasks over SSH; `--check` previews; `ansible-pull` "inverts the Ansible architecture so that nodes check in to a central location instead of you pushing configuration out to them" [VERIFIED — Ansible docs]. **Gap**: default mode is push/command-and-control; the target has no daemon, no local reasoning, no self-assessment. Module-level idempotency is a local, weaker cousin of convergence; without scheduled local evaluation, drift between runs is invisible — Ansible's own docs warn "not all playbooks and not all modules behave this way" [VERIFIED — Ansible docs].
+- **Chef and Puppet**: pull-based agents on a schedule, converging toward declared state and reporting back [UNVERIFIED — the ~30-minute Chef default and "blind outside declarations" details come from the webframp analysis, not from official docs fetched in this research]. The agent-observation-scoped-to-declaration point — "if you did not write a resource for it, the agent does not see it" — is [UNVERIFIED — webframp.com, 2026; consistent with verified pull-based mechanisms].
+- **Nix / NixOS**: "purely functional package manager" — builds without side effects, immutable content-addressed store, atomic upgrades and rollbacks; NixOS builds "the entire operating system… from a description in a purely functional build language" [VERIFIED — nixos.org]. **Gap**: deterministic builds ≠ deterministic running state — even NixOS exempts "mutable state (such as the stuff that lives in /var)" [VERIFIED — nixos.org]. Nix realizes the end-state *purity* extreme — eliminating stochastic repair by making state immutable and rebuildable — closer to Traugott's destroy-and-rebuild "congruence" than to CFEngine's convergent repair [interpretive framing].
+
+### 5.2 Kubernetes: reconciliation controllers as institutionalized convergence
+
+Kubernetes controllers are "control loops" that watch state and "try to move the current cluster state closer to the desired state"; the thermostat is the canonical example [VERIFIED — kubernetes.io/docs/concepts/architecture/controller]. The inheritance mechanism is the same fixed-point metaphor as CFEngine's ball-in-potential-well: `spec` = desired state, controller loop = the map applied repeatedly. **The gap doctrine is explicit**: "potentially, your cluster never reaches a stable state. As long as the controllers… are running and able to make useful changes, it doesn't matter" [VERIFIED — kubernetes.io]. "Controllers can fail, so Kubernetes is designed to allow for that" [VERIFIED — same source]. Lesson: design simple, separable, fail-tolerant reconcilers and assume convergence never "finishes."
+
+### 5.3 GitOps: the closest industry instantiation of "the promise as data"
+
+GitOps (coined by Weaveworks, 2017) per CNCF: (1) the whole system is declarative; (2) the canonical desired state is versioned in Git; (3) changes apply automatically; (4) software agents continuously reconcile and alert when reality diverges — "software agents also help ensure that the whole system is self-healing" [VERIFIED — CNCF, *GitOps 101*]. **Interpretive framing**: GitOps is the closest the industry built to *storing the promise as data* — intended state durable, versioned, diffable, time-ordered (git history is a temporal log of intent), with the reconciling agent as promise-keeper [interpretive — labeled, not verified as a claim in the source]. "You won't achieve immediate deployment or reconciliation until you achieve a new canonical state"; the repo is the contract and drift becomes a first-class, auditable condition [VERIFIED — CNCF]. Mark the "promise as data" reading [UNVERIFIED] as an interpretive gloss unless separately sourced.
+
+### 5.4 Intent-Based Networking: intent as a productized semantic layer
+
+IBN (RFC 9315 lineage) defines intent as "a high-level, declarative statement" of a "desired operational or business goal without specifying the detailed method of implementation," and runs a closed loop **translation → activation → assurance → optimization** [VERIFIED — WashU IBN survey citing Zeydan & Turk 2020 and RFC 9315]. Architecture: three layers — Business, Intent (Knowledge/ontology + Agent + Data), Network (telemetry closing the loop); the Knowledge module "includes ontologies and models for understanding semantics" [VERIFIED — same survey]. **The hard problem is assurance** — "continuously validating whether the actual network behavior satisfies the intent" — and open challenges include intent-interpretation reliability, multi-domain coordination, and explainability: "today's IBN systems sometimes act like 'black boxes'" [VERIFIED — WashU survey]. Lesson: intent is only as good as its assurance loop; the semantic layer is where intent is won or lost.
+
+### 5.5 MAPE-K and operators: the autonomic loop codified
+
+IBM coined "autonomic computing" in 2001; Kephart & Chess (2003), *The Vision of Autonomic Computing* (IEEE Computer 36:41–50), define an autonomic manager + managed resource running the **MAPE loop — Monitor, Analyze, Plan, Execute — with shared Knowledge (MAPE-K)** [VERIFIED — Kephart & Chess 2003 via ScienceDirect; researchr]. The IBM blueprint's component-level details were not fetchable in the research phase and are [UNVERIFIED — IBM blueprint bibliography entry only]. CFEngine Wikipedia asserts *Computer Immunology* (1998) "laid out a manifesto for creating self-healing systems, reiterated a few years later by IBM in their form of Autonomic Computing" [VERIFIED — CFEngine Wikipedia]; Burgess & Couch's 2006 paper is literally titled *Autonomic Computing Approximated by Fixed-Point Promises* [VERIFIED — archive.org copy]. MAPE-K and CFEngine's converge-and-repair loop are independent formulations of the same monitor → compare → act cycle. **Lesson**: the "K" (shared Knowledge) is what makes the loop semantic; without a durable knowledge model, self-* systems repair without understanding [interpretive].
+
+## 6. The most-cited gap: promise-keeping was never stored as data
+
+The recurring critique of the whole CFEngine-to-IBN line: systems answered "is this promise kept *right now*?" but never stored promise-keeping as **queryable data** — no record of what the configuration looked like last Tuesday, how often a promise was repaired, or which hosts drifted together [UNVERIFIED — webframp.com, *The Promise None of Them Kept* (2026), an opinionated practitioner analysis; the current-state compliance behavior it describes is consistent with the verified CFEngine mechanisms of §2]. The framing: CFEngine's assessment "is a verdict rather than a record" [UNVERIFIED — webframp.com, 2026]. This claim is attributed to the CFEngine lineage — the opinion source analyzes CFEngine and its successors, not SST — and must not be presented as a verified fact or as an SST discovery.
+
+In SST terms, this is the missing **record axis** of §4 (valid vs. transaction time) applied to promises: the world axis is the state of the system, the record axis is the versioned history of what was promised, what was measured, and what was repaired. SST's semantic-time capability — a versioned record of meaning over time — is what would close the gap, and §8 names the concrete machinery.
+
+## 7. SLOs as working semantic contracts
+
+SLOs are the operational form of "meaning over time": a promise about future measured behavior with an explicit time horizon, sitting inside a control loop [interpretive framing; the facts below are verified]. Terminology (Google SRE book, Ch. 4): an **SLI** is "a carefully defined quantitative measure"; an **SLO** is "a target value or range of values… measured by an SLI"; an **SLA** is an agreement "with consequences." The mnemonic: "what happens if the SLOs aren't met?" [VERIFIED — sre.google]. **SLOs sit inside control loops**: "SLIs and SLOs are crucial elements in the control loops used to manage systems: 1. Monitor and measure… 2. Compare… 3. …figure out what needs to happen… 4. Take that action" [VERIFIED — sre.google] — the same loop CFEngine's agent runs and MAPE-K codifies (§2, §5.5), with meaning made explicit and quantifiable. **Error budgets**: "it is better to allow an error budget — a rate at which the SLOs can be missed — and track that"; "an error budget is just an SLO for meeting other SLOs" [VERIFIED — sre.google]. Selection lessons (depth evidence): "keep it simple," "avoid absolutes," "have as few SLOs as possible," "perfection can wait," and "don't overachieve" — Chubby introduced planned outages because it was *too* available [VERIFIED — sre.google].
+
+SST's reading: an SLO is a scalar promise with a measurement loop and a time horizon — a minimal, production-proven instance of "meaning over time." When you model a system in SST terms, your observations and drift checks are, operationally, SLOs over semantic state. For the promise-level machinery (offer/acceptance, assessment, breach), link to [promise-theory](../../promise-theory/references/foundations.md) rather than restating it here.
+
+## 8. Time and space in systems: the versioned-record-axis machinery
+
+The record axis of §4 needs concrete machinery. The relevant lineage, all verified:
+
+- **Lamport clocks** — logical clocks imposing a total order consistent with the causal partial order, the distributed-systems backbone for "no global clock" [VERIFIED — Lamport 1978 via Microsoft Research].
+- **Distributed tracing** — OpenTelemetry spans form a parent-child hierarchy; span links "exist so that you can associate one span with one or more spans, implying a causal relationship" [VERIFIED — opentelemetry.io]. Causality must be *carried in context* (trace-context propagation), not reconstructed from timestamps [VERIFIED — same source]. This is Lamport's partial-order causality made observable — the closest working analogue to SST's "timeline cognitive semantics" [interpretive].
+- **Event sourcing** — §4, state as a function of time with replay caveats [VERIFIED — Fowler 2005].
+- **Bi-temporal databases** — §4, world axis vs. record axis [VERIFIED — Temporal database Wikipedia].
+
+**Continuous Integration of Data Histories into Consistent Namespaces** (Burgess & Gerlits, 2022, arXiv:2204.00470) is SST's own temporal-consistency scheme for data pipelines — the concrete machinery behind the record axis [VERIFIED — arXiv:2204.00470; academic-foundations report §2.2 S9]. The mechanism: "we thus establish an invariant global ordering from a spanning tree over all shards… this forms a versioned coordinate system (or versioned namespace) with consistent semantics" [VERIFIED — arXiv:2204.00470]. In other words: versioned coordinates over distributed data history give every record a stable address in time, so "what was the meaning at time T" is a query, not archaeology. This is exactly the capability VAL-APPS-006's gap (promise-keeping never stored as data) requires: a promise ledger is a namespace of versioned data histories over promises, observations, and repairs [EXTRAPOLATION — applying the versioned-coordinate scheme to promise-keeping; the paper's own framing is about data pipelines]. The Aljabr/Dianemo smart-data-pipeline lineage behind the paper is documented [VERIFIED — Wikipedia citation + arXiv reference].
+
+## 9. Distilled lessons — citable
+
+Each lesson below carries its marker and its named source; use these as the citation spine when a design conversation needs the empirical record.
+
+1. **Convergence ≠ idempotence; convergence is relative to a declared policy state.** "Idempotence requires only O^2 = O, while convergence is relative to a specific policy state q0" (`O(q0)=q0`). [VERIFIED — Burgess, *A Tiny Overview of CFEngine*; Burgess Wikipedia]
+2. **Desired-state convergence is statistical, never exact, in a stochastic environment.** "A complete specification of policy determines an approximate configuration… only approximately over persistent times." [VERIFIED — *A Tiny Overview*; *On the theory of system administration* via Wikipedia]
+3. **Make convergence order-free where possible; repeat failed steps.** "Multiple orthogonal, convergent operations will always lead to the correct configuration, no matter which part… is incorrect, or in what order things occur." [VERIFIED — *A Tiny Overview*]
+4. **Converge for realtime maintenance; recreate if you can afford downtime.** Traugott's "congruence" is the philosophical opposite; "only the convergent approach can be used for realtime maintenance." [VERIFIED — *A Tiny Overview*]
+5. **Continuous promise evaluation yields compliance measurement for free.** "Immediate and continuous measurements of compliance based on a documented model of intent, without the need for independent monitoring." [VERIFIED — InfoQ CFEngine article, vendor-authored but primary]
+6. **Autonomy and weak coupling survive scale; strong coupling transmits failure.** Centralization is "the first idea people come back to" but propagates Byzantine failures. [VERIFIED — InfoQ CFEngine article; Burgess interview]
+7. **Autonomy without memory = a verdict, not a record.** CFEngine could say whether a promise is kept *now*, not what changed when or how often it was repaired, because "promise-keeping was never stored as data." [UNVERIFIED — webframp.com 2026, opinion source]
+8. **Dynamics trumps semantics — measure first, then attach meaning.** "It is not possible to reason about semantics without taking into account the underlying dynamics"; scale changes what you can conclude (steady RPS vs. full disks). [VERIFIED — InfoQ, *In Search of Certainty* review/interview]
+9. **Model time as causality, not wall clocks.** Lamport: "only a partial order in which an event e1 precedes an event e2 iff e1 can causally affect e2." OpenTelemetry span links "implying a causal relationship" are the productionized form. [VERIFIED — Lamport via Microsoft Research; opentelemetry.io]
+10. **Separate "world" time from "record" time in any state-over-time store.** Bi-temporal modeling (valid vs. transaction) is what makes audit and rollback coherent; SQL:2011 supports a reduced form. [VERIFIED — Temporal database Wikipedia]
+11. **Event sourcing gives time-travel state; gate external side effects.** Replays must not re-fire external messages; external query answers must be recorded. [VERIFIED — Fowler, *Event Sourcing*]
+12. **Reconciliation loops should assume they never "finish."** "Potentially, your cluster never reaches a stable state. As long as the controllers… are running and able to make useful changes, it doesn't matter." [VERIFIED — kubernetes.io]
+13. **If a declarative tool is invoked rather than looping, drift accumulates silently.** Terraform detects drift only when a human runs `plan`/`refresh`; it "cannot detect drift of resources… not managed using Terraform." [VERIFIED — HashiCorp] (the "blind between applies" framing is [UNVERIFIED — webframp.com])
+14. **Version your intended state; that makes drift auditable and recovery reproducible.** GitOps's canonical-desired-state-in-git, enforced by converging agents, is the industry's best institutionalization of "the promise as data." [VERIFIED — CNCF GitOps 101; the "promise as data" gloss is interpretive]
+15. **Intent is only as good as its assurance loop.** IBN's closed loop (translation → activation → assurance → optimization) and the finding that today's IBN systems "act like black boxes." [VERIFIED — WashU IBN survey]
+16. **SLOs are the operational form of semantic contracts.** They sit inside control loops (monitor → compare → act), carry error budgets, and their selection rules ("few SLOs," "avoid absolutes," "perfection can wait") are the art of turning meaning into measurement. [VERIFIED — Google SRE book Ch. 4]
+17. **Causality must be carried in context.** Distributed causality cannot be reconstructed later from timestamps alone. [VERIFIED — opentelemetry.io]
+18. **Versioned coordinates over data history make "meaning at time T" a query.** "We thus establish an invariant global ordering from a spanning tree over all shards… this forms a versioned coordinate system (or versioned namespace) with consistent semantics." [VERIFIED — Burgess & Gerlits, arXiv:2204.00470]
+
+## 10. Status and limits
+
+Two honest disclosures apply to everything in this file. First, **the theory behind it is semi-formal and deliberately unrefereed**: Burgess published the SST series as self-published notes ("I have no interest or intention of seeking to publish any of this work beyond making these notes available seeking trusted review"), with some proofs left to the reader [VERIFIED — markburgess.org]. Use the SST lens here as a reasoning aid, not a proof system. Second, several market-level claims in the descendant literature could not be verified: CFEngine's market decline has no authoritative post-mortem (only Burgess's own "reached its limits as a tool in the mid 2000s" [VERIFIED — InfoQ interview] and the 2017 Northern.tech rename [VERIFIED — Wikipedia]); Chef/Puppet defaults and the CFEngine-vs-successor comparisons rest on opinion or vendor sources [UNVERIFIED]. Where a claim in this file is labeled `[UNVERIFIED]` or `[interpretive]`, treat it as a hypothesis to test, not a fact.
+
+## Sources and routing
+
+The full annotated source list with URLs is in [bibliography.md](bibliography.md). Key sources for this file: InfoQ CFEngine article and *In Search of Certainty* review/interview; Burgess, *A Tiny Overview of CFEngine* (tiny_intro.pdf); markburgess.org (*Semantic Spacetime — What is it?*); Lamport 1978 (Microsoft Research); martinfowler.com (*Event Sourcing*); Temporal database Wikipedia; kubernetes.io (Controllers); HashiCorp (drift); Ansible docs; nixos.org (*How Nix Works*); CNCF (*GitOps 101*); WashU IBN survey; RFC 9315; Kephart & Chess 2003; sre.google (SLO chapter); opentelemetry.io (Traces); webframp.com (2026, opinion); Burgess & Gerlits, arXiv:2204.00470. For the promise vocabulary used in §2–§7 (promise, offer/acceptance, assessment, breach), load [promise-theory](../../promise-theory/SKILL.md) and its [applications-infrastructure reference](../../promise-theory/references/applications-infrastructure.md); for the formal SST model, [foundations.md](foundations.md); for patterns, [patterns.md](patterns.md).

semantic-spacetime/references/bibliography.md

@@ -0,0 +1,251 @@
+# Bibliography — Primary Sources for Semantic Spacetime
+
+**Load this file when you need to find or verify a source** — which paper says
+X, or where a claim in [foundations.md](foundations.md) or
+[glossary.md](glossary.md) comes from. Every entry below carries a URL that was
+checked for reachability during the research phase (2026-08-12); the
+`[VERIFIED]`/`[UNVERIFIED]` markers describe the source's verification level as
+used in [foundations.md](foundations.md). No entry here is fabricated: each
+appears in the research corpus's source lists. For the promise-theory substrate
+sources, cross-reference the promise-theory skill's own bibliography.
+
+---
+
+## 1. The Semantic Spacetime series (Burgess)
+
+- Burgess, M. *Spacetimes with Semantics* (2014). arXiv:1411.5563 [cs.MA].
+  Part I: "From Einstein to Milner." Defines the agenda: relationships between
+  objects constitute space; their change is time; observer semantics are
+  integral to spacetime. [VERIFIED]
+  URL: https://arxiv.org/abs/1411.5563
+- Burgess, M. *Spacetimes with Semantics (II): Scaling of agency, semantics,
+  and tenancy* (2015). arXiv:1505.01716 [cs.MA]. Part II: how agency scales via
+  super-agents/sub-spaces; scalar vs. vector promises; occupancy and tenancy.
+  [VERIFIED]
+  URL: https://arxiv.org/abs/1505.01716
+- Burgess, M. *Spacetimes with Semantics (III): The Structure of Functional
+  Knowledge Representation and Artificial Reasoning* (2016, rev. 2017).
+  arXiv:1608.02193 [cs.AI]. Part III (122 pages), the most formal document:
+  Definitions 1-9, Lemmas 1-3, the four irreducible associations, the
+  learning/knowledge formalism. [VERIFIED]
+  URL: https://arxiv.org/abs/1608.02193
+  Full text: https://arxiv.org/html/1608.02193v4
+- Burgess, M. *On the scaling of functional spaces, from smart cities to cloud
+  computing* (2016). arXiv:1602.06091 [cs.CY]. The "functional space" reading
+  of SST applied to the empirically observed power-law scaling of cities.
+  [VERIFIED]
+  URL: https://arxiv.org/abs/1602.06091
+- Burgess, M. *A Spacetime Approach to Generalized Cognitive Reasoning in
+  Multi-scale Learning* (2017). arXiv:1702.04638 [cs.AI]. A hybrid
+  reasoning/pattern-recognition architecture as the ML instantiation of SST
+  reasoning. [VERIFIED]
+  URL: https://arxiv.org/abs/1702.04638
+- Burgess, M. *Testing the Quantitative Spacetime Hypothesis using Artificial
+  Narrative Comprehension (I): Bootstrapping Meaning from Episodic Narrative
+  viewed as a Feature Landscape* (2020). arXiv:2010.08126 [cs.AI]. SST's
+  empirical arm: parsing narrative via measurable size/time cues as an event
+  "landscape"/interferometry; concepts as process invariants. [VERIFIED]
+  URL: https://arxiv.org/abs/2010.08126
+- Burgess, M. *Testing the Quantitative Spacetime Hypothesis using Artificial
+  Narrative Comprehension (II): Establishing the Geometry of Invariant
+  Concepts, Themes, and Namespaces* (2020). arXiv:2010.08125 [cs.AI]. Part II:
+  reconstructing concepts via multiscale interferometry based on the four
+  fundamental spacetime relationships. [VERIFIED]
+  URL: https://arxiv.org/abs/2010.08125
+- Burgess, M.; Gerlits, A. *Continuous Integration of Data Histories into
+  Consistent Namespaces* (2022). arXiv:2204.00470 [cs.DC]. Versioned
+  coordinates / namespaces for data pipelines — SST's temporal-consistency
+  scheme. [VERIFIED]
+  URL: https://arxiv.org/abs/2204.00470
+- Burgess, M. *Agent Semantics, Semantic Spacetime, and Graphical Reasoning*
+  (2025). arXiv:2506.07756 [cs.AI]. The current formal statement: the γ(3,4)
+  representation (3 node meta-types × 4 link types), the nine typing design
+  rules, absorbing states as information leaks, causal-set kinship. [VERIFIED]
+  URL: https://arxiv.org/abs/2506.07756
+  Full text: https://arxiv.org/html/2506.07756v2
+- Burgess, M. *On The Role of Intentionality in Knowledge Representation:
+  Analyzing Scene Context for Cognitive Agents with a Tiny Language Model*
+  (2025). arXiv:2507.10000 [cs.AI]. Intentionality in data via scale
+  separation. [VERIFIED]
+  URL: https://arxiv.org/abs/2507.10000
+- Burgess, M. *γ(3,4) 'Attention' in Cognitive Agents: Ontology-Free Knowledge
+  Representations With Promise Theoretic Semantics* (2025). arXiv:2512.19084
+  [cs.AI]. SST as a bridge between vectorized ML and knowledge graphs without
+  relying on language models implicitly. [VERIFIED]
+  URL: https://arxiv.org/abs/2512.19084
+
+## 2. Author's web project pages and essays
+
+- Burgess, M. *Semantic Spacetimes* (project page). "A semantic spacetime is a
+  discrete graph, which evolves, and whose properties vary from point to
+  point." [VERIFIED]
+  URL: http://markburgess.org/spacetime.html
+- Burgess, M. *Semantic Spacetime — What is it?* The best short primary
+  exposition; source of the "not quantum gravity," Lamport-relativity,
+  spacelike/timelike measurement, and cooperative-causality material.
+  [VERIFIED]
+  URL: http://markburgess.org/semantic_spacetime.html
+- Burgess, M. *The Semantic Spacetime Project: Bringing technology and physics
+  together* (2016 essay). "For inspiration, not for refereed publication."
+  [VERIFIED]
+  URL: http://markburgess.org/blog_spacetime3.html
+- Burgess, M. *Semantics of Spacetime and Cognitive Processes* (Kavli salon
+  write-up, Medium, 2022). SST as a formal bridge for neuroscience findings.
+  [VERIFIED]
+  URL: https://medium.com/@mark-burgess-oslo-mb/semantics-of-spacetime-and-cognitive-processes-d39214e9c44a
+- Burgess, M. *Semantic Spacetime 1: The Shape of Knowledge* (Medium, 2025).
+  [VERIFIED — existence and framing; URL from search index]
+  URL: https://mark-burgess-oslo-mb.medium.com/semantic-spacetime-1-the-shape-of-knowledge-86daced424a5
+- Burgess, M. *Universal Data Analytics as Semantic Spacetime* (Medium series,
+  2022). [VERIFIED — existence and framing; URL from search index]
+  URL: https://mark-burgess-oslo-mb.medium.com/universal-data-analytics-as-semantic-spacetime-dee7a76661c2
+- Burgess, M. *Motion of the Third Kind I & II* (ResearchGate, 2021-22).
+  Existence verified; full texts not fetched. [UNVERIFIED in detail]
+  URL: https://www.researchgate.net/publication/351492269
+  URL: https://www.researchgate.net/publication/360757745
+- Burgess, M. *Notes on Trust As A Causal Basis For Social Science* (2022).
+  ResearchGate; DOI 10.2139/ssrn.4252501. [VERIFIED — existence]
+  URL: https://www.researchgate.net/publication/362387906
+- Burgess, M. *The Semantic Spacetime Hypothesis: A Guide to the Semantic
+  Spacetime of Information* (2020 note). ResearchGate publication 344338994.
+  Existence verified; full contents not accessible. [UNVERIFIED in detail]
+  URL: https://www.researchgate.net/publication/344338994
+- Burgess, M. *In Search of Certainty: The Science of Our Information
+  Infrastructure* (χtAxis Press, 2013). The popular introduction; contents not
+  fetched during research. [UNVERIFIED in detail]
+  URL: https://markburgess.org/certainty.html
+- Burgess, M. *Smart Spacetime* (χtAxis Press, 2019). ISBN 978-1797773704.
+  Book-length exposition; contents not fetched. [UNVERIFIED in detail]
+  URL: https://www.amazon.com/dp/1797773704
+- Burgess, M. *SSTorytime* (software). The open-source SST knowledge-graph
+  database (Go over PostgreSQL, Apache-2.0) with the N4L note language and
+  MCP-SST connector; also the older repository and a Julia port. [VERIFIED]
+  URL: https://github.com/markburgess/SSTorytime
+  URL: https://github.com/markburgess/SemanticSpaceTime
+  URL: https://juliaknowledge.github.io/SemanticSpacetime.jl/dev/
+
+## 3. Spacetime-Entangled Networks and consensus
+
+- Borrill, P.; Burgess, M.; Karp, A.; Kasuya, A. *Spacetime-Entangled Networks
+  (I): Relativity and Observability of Stepwise Consensus* (2018, rev. 2020).
+  arXiv:1807.08549 [cs.DC]. SST/promise semantics at the consensus layer:
+  entanglement as co-dependent evolution of state; promises of sequential,
+  in-order, atomically confirmed delivery. [VERIFIED]
+  URL: https://arxiv.org/abs/1807.08549
+
+## 4. Promise theory (the substrate)
+
+- Bergstra, J.A.; Burgess, M. *A static theory of promises* (2008, v5 2014).
+  arXiv:0810.3294. The foundational promise-vs-obligation paper. [VERIFIED]
+  URL: https://arxiv.org/abs/0810.3294
+- Bergstra, J.; Bethke, I.; Burgess, M. *A process algebra based framework for
+  promise theory* (2007). arXiv:0707.0744. The process-algebra root of promise
+  semantics. [VERIFIED]
+  URL: https://arxiv.org/abs/0707.0744
+- Burgess, M.; Bergstra, J.A. *Promise Theory: Principles and Applications*
+  (χtAxis Press, 2014; 2nd ed. 2019). The canonical statement; free PDF.
+  [VERIFIED]
+  URL: https://markburgess.org/BookOfPromises.pdf
+  Page: https://markburgess.org/promises.html
+  ACM DL: https://dl.acm.org/doi/abs/10.5555/2636996
+- Bergstra, J.A. *Promise Theory as a Tool for Informaticians* (Transmathematica,
+  2020). DOI 10.36285/tm.35. Independent scholarly overview. [VERIFIED]
+  URL: https://transmathematica.org/index.php/journal/article/view/35
+- Burgess, M. *Thinking in Promises: Designing Systems for Cooperation*
+  (O'Reilly, 2015). ISBN 9781491917879. The practitioner's companion.
+  [VERIFIED]
+  URL: https://books.google.com/books/about/Thinking_in_Promises.html?id=ibL4CQAAQBAJ
+- Burgess, M.; Prangsma, E. *Koalja: from Data Plumbing to Smart Workspaces in
+  the Extended Cloud* (2019). arXiv:1907.01796. The data-pipeline lineage of
+  the SST project. [VERIFIED]
+  URL: https://arxiv.org/abs/1907.01796
+
+## 5. Adjacent and contextual work
+
+- Lamport, L. *Time, Clocks, and the Ordering of Events in a Distributed
+  System.* *CACM* 21(7):558-565, 1978. The precedence view of time Burgess
+  credits as SST's origin. [VERIFIED]
+  URL: https://amturing.acm.org/p558-lamport.pdf
+- Mattern, F. *Virtual Time and Global States of Distributed Systems* (1988/89).
+  Vector clocks. [VERIFIED]
+  URL: https://vs.inf.ethz.ch/publ/papers/VirtTimeGlobStates.pdf
+- Kowalski, R.; Sergot, M. *A logic-based calculus of events.* *New Generation
+  Computing* 4:67-95, 1986. [VERIFIED]
+  URL: https://www.doc.ic.ac.uk/~rak/papers/event%20calculus.pdf
+- McCarthy, J.; Hayes, P. *Some philosophical problems from the standpoint of
+  artificial intelligence.* *Machine Intelligence* 4, 1969. [VERIFIED]
+  URL: http://www-formal.stanford.edu/jmc/mcchay69.pdf
+- Tolman, E.C. *Cognitive maps in rats and men.* *Psychological Review*
+  55(4):189-208, 1948. [VERIFIED]
+  URL: https://psycnet.apa.org/record/1949-00103-001
+- O'Keefe, J.; Nadel, L. *The Hippocampus as a Cognitive Map.* Clarendon Press,
+  1978. [VERIFIED]
+  URL: https://discovery.ucl.ac.uk/id/eprint/10103569/
+- Hafting, T.; Fyhn, M.; Molden, S.; Moser, M.-B.; Moser, E.I. *Microstructure
+  of a spatial map in the entorhinal cortex.* *Nature* 436:801-806, 2005.
+  [VERIFIED]
+  URL: https://www.nature.com/articles/nature03721
+- Constantinescu, A.O.; O'Reilly, J.X.; Behrens, T.E.J. *Organizing conceptual
+  knowledge in humans with a gridlike code.* *Science* 352(6292):1464-1468,
+  2016. DOI 10.1126/science.aaf0941. [VERIFIED]
+  URL: https://www.science.org/doi/10.1126/science.aaf0941
+- Ralph, M.A.L.; Jefferies, E.; Patterson, K.; Rogers, T.T. *The neural and
+  computational bases of semantic cognition.* *Nature Reviews Neuroscience*
+  18:42-55, 2017. [VERIFIED]
+  URL: https://www.nature.com/articles/nrn.2016.150
+- Osgood, C.E.; Suci, G.J.; Tannenbaum, P.H. *The Measurement of Meaning.*
+  Univ. of Illinois Press, 1957. The "semantic differential." [VERIFIED]
+  URL: https://www.press.uillinois.edu/books/?id=p745393
+- Gärdenfors, P. *Conceptual Spaces: The Geometry of Thought.* MIT Press, 2000.
+  [VERIFIED]
+  URL: https://mitpress.mit.edu/9780262572194/conceptual-spaces/
+- Harris, Z.S. *Distributional Structure.* *Word* 10(2-3):146-162, 1954.
+  [VERIFIED]
+  URL: https://www.tandfonline.com/doi/abs/10.1080/00437956.1954.11659520
+- Landauer, T.K.; Dumais, S.T. *A solution to Plato's problem: The latent
+  semantic analysis theory...* *Psychological Review* 104(2):211-240, 1997.
+  [VERIFIED]
+  URL: https://www.stat.cmu.edu/~cshalizi/350/2008/readings/Landauer-Dumais.pdf
+- Turney, P.D.; Pantel, P. *From Frequency to Meaning: Vector Space Models of
+  Semantics.* *JAIR* 37:141-188, 2010. [VERIFIED]
+  URL: https://arxiv.org/abs/1003.1141
+- Mikolov, T.; Sutskever, I.; Chen, K.; Corrado, G.; Dean, J. *Distributed
+  Representations of Words and Phrases and their Compositionality* (2013).
+  arXiv:1310.4546. word2vec skip-gram. [VERIFIED]
+  URL: https://arxiv.org/abs/1310.4546
+- Sorkin, R.D. *Causal sets: discrete gravity* (2003). arXiv:gr-qc/0309009.
+  [VERIFIED]
+  URL: https://arxiv.org/abs/gr-qc/0309009
+  (The program originates with Myrheim, *Statistical Geometry*, CERN preprint
+  TH.2538, 1978 — cited in arXiv:2506.07756; citation chain verified,
+  [VERIFIED].)
+- Surya, S. *The causal set approach to quantum gravity* (2019).
+  arXiv:1903.11544. [VERIFIED]
+  URL: https://arxiv.org/abs/1903.11544
+- Konopka, T.; Markopoulou, F.; Smolin, L. *Quantum graphity* (2006).
+  arXiv:hep-th/0611197. [VERIFIED]
+  URL: https://arxiv.org/abs/hep-th/0611197
+- Milner, R. *The Space and Motion of Communicating Agents.* Cambridge Univ.
+  Press, 2009. Bigraphs — the reference model Burgess builds on. [VERIFIED]
+  URL: https://www.cambridge.org/core/books/space-and-motion-of-communicating-agents/
+- Gutiérrez, C.; Hurtado, C.; Vaisman, A. *Temporal RDF* (ESWC 2005).
+  [VERIFIED]
+  URL: https://users.dcc.uchile.cl/~cgutierr/papers/temporalRDF.pdf
+- Erwig, M.; Güting, R.H.; Schneider, M.; Vazirgiannis, M. *Spatio-temporal
+  data types: an approach to modeling and querying moving objects in
+  databases.* *GeoInformatica* 3:265-291, 1999. [VERIFIED]
+  URL: https://web.engr.oregonstate.edu/~erwig/papers/MovingObjects_GEOINF99.pdf
+- Wikipedia. *Semantic spacetime.* Tertiary overview; use only to locate
+  primary URLs, treat claims [UNVERIFIED] unless corroborated by Burgess.
+  [UNVERIFIED — tertiary]
+  URL: https://en.wikipedia.org/wiki/Semantic_spacetime
+- Wikipedia. *Promise theory.* [UNVERIFIED — tertiary]
+  URL: https://en.wikipedia.org/wiki/Promise_theory
+- Pavlyshin, V. *Semantic Space Time for AI Agent Ready Graphs* (2025,
+  Leanpub). Independent third-party book building on SST. ISBN 9798266921313.
+  [VERIFIED — listing]
+  URL: https://leanpub.com/sst-4-agenticai
+- Dewar, N. *The epistemology of spacetime.* *Philosophy Compass* 17(4), 2022.
+  DOI 10.1111/phc3.12821. Philosophy of physics — semantics *of* spacetime,
+  distinct from Burgess's spacetime *of* semantics. [VERIFIED]
+  URL: https://compass.onlinelibrary.wiley.com/doi/10.1111/phc3.12821

semantic-spacetime/references/diagnosis-and-debugging.md

@@ -0,0 +1,99 @@
+# Diagnosis and Debugging — A Bounded Procedure for Semantic Drift, Divergence, Dead-Ends, and Meaning Gaps
+
+**Load this file when you are diagnosing a semantic failure in an agent or system** — two agents disagree about what a word means, an agent's behavior drifts from its instructions, a task dead-ends and nothing the agent tries helps, or a term that used to mean something now means nothing to anyone. This file gives a bounded, checkable procedure that terminates: after three non-converging diagnostic passes you stop and report the evidence.
+
+**What belongs here:** the diagnosis procedure — inputs, the four named conditions (drift, divergence, dead-end/absorbing state, meaning gap), the stepwise diagnosis, the three-pass bounded exit, and the exit artifacts. What does **not** belong here: the definitions and formal model behind the vocabulary (see [foundations.md](foundations.md)); the drift literature and metrics in depth (see [agent-coordination.md](agent-coordination.md) §5); the named patterns the procedure applies (see [patterns.md](patterns.md)); the empirical infrastructure record (see [applications-infrastructure.md](applications-infrastructure.md)). Promise-level assessment (whether a promise is kept, breach, trust calibration) is linked to [promise-theory](../../promise-theory/SKILL.md) — this file covers the *semantic* side, not the promise-accounting side.
+
+**Provenance.** `[VERIFIED]` = confirmed in a fetched primary source; `[UNVERIFIED]` = secondary/inferred; `EXTRAPOLATION` = this skill's synthesis, labeled. The procedure's structure (steps, four conditions, three-pass exit) is this skill's original synthesis, grounded in the verified definitions it cites.
+
+---
+
+## 1. When to use this procedure (and when not to)
+
+Use this procedure when the symptom is **semantic**: the outputs, decisions, or coordinated behavior diverge from a stated meaning, and you can point at a concept, promise, instruction, or shared term as the thing that "meant" something. The four target conditions:
+
+1. **Semantic drift** — a meaning changes over time away from its promised/recorded meaning (the agent or system quietly re-interprets). Empirically: "progressive degradation of agent behavior, decision quality, and inter-agent coherence over extended interaction sequences" with semantic drift as "deviation from original intent" [VERIFIED — arXiv:2601.04170].
+2. **Divergence** — two or more agents (or an agent and its instruction) end up with *different* meanings for the same term or state; the gap grows with time. Empirically: "the divergence of internal knowledge states between concurrent agents" [VERIFIED — arXiv:2606.21666].
+3. **Dead-end (absorbing state)** — a node or process stops propagating information; the same failure recurs and interior changes do not help. Formally: "the ubiquitous appearance of absorbing states in any partial graph means that certain graph processes leak information and represent entropy changing processes"; an absorbing state "can only be replaced with new boundary data from outside the graph" [VERIFIED — arXiv:2506.07756].
+4. **Meaning gap** — a term or promise has no working interpretation at all in the current system: the co-language between the agents that must use it has no overlap on that term ("agents should expect to misunderstand one another's intentions to some level" [VERIFIED — arXiv:2604.10505]).
+
+Do **not** use this procedure when the failure is purely mechanical (a crashed service, a malformed message, a wrong API call with no meaning dimension) — route to the tool's own skill. Do **not** use it when the question is whether a promise was *kept* (assessment, breach, trust calibration) — that is [promise-theory's diagnosis-and-debugging reference](../../promise-theory/references/diagnosis-and-debugging.md), which this file links to rather than restates.
+
+## 2. Inputs — what to collect before starting
+
+Gather these before pass 1; every step consumes them:
+
+- **The instruction / promised state** — the text or artifact that stated the intended meaning (the "instruction trajectory" of [agent-coordination.md](agent-coordination.md) §8.5). If it is not versioned, version it now as an observation.
+- **Observed implementations** — agent outputs, decisions, tool calls, or system states at known times; at least two points in time to make drift/divergence measurable (drift is a time-indexed quantity).
+- **Reality observations** — measurements of the external world state the meanings are supposed to track (SLO-style measurements; see [applications-infrastructure.md](applications-infrastructure.md) §7).
+- **The shared vocabulary in play** — the terms, promises, or concepts that are in dispute, with any prior anchor definitions ([patterns.md](patterns.md) Pattern 1).
+- **The causal/time structure** — event ordering where it matters ("there is only a partial order in which an event e1 precedes an event e2 iff e1 can causally affect e2" [VERIFIED — Lamport 1978]); reconstruct causality, not timestamps, first.
+
+If the inputs are unavailable (no recorded instruction, no observations, no shared terms), the diagnosis cannot converge — that finding itself goes into the evidence report (§6) as a meaning gap.
+
+## 3. The four conditions — diagnosis checks
+
+For each candidate condition, run its check. A condition is *confirmed* only when the check's evidence is present; otherwise record it as ruled out.
+
+| Condition | Diagnosis check | Ruled out when |
+|---|---|---|
+| **Drift** | Compute the divergence between the promised/recorded meaning and the observed implementation at two or more times (semantic distance; [patterns.md](patterns.md) Patterns 5 and 9). Is the pairwise distance growing, or consistently nonzero in one direction? | Distances are stable and near zero at every pair of times |
+| **Divergence** | Compare the same term or state across two agents (or agent vs. instruction) at the same time. Is the inter-agent semantic distance above your risk threshold? Is the gap widening? | All agents agree within threshold at all sampled times |
+| **Dead-end (absorbing state)** | Trace the graph from the failing node. Do information flows stop at it? Does it re-absorb every intervention (same outcome, more input)? Is the node's interior data being erased (no learning)? | Interventions produce new, different outcomes; information passes through |
+| **Meaning gap** | For the disputed term, does any agent have a working interpretation (a defined anchor, or an observed consistent use)? Does the exchange co-language contain the term at all? | At least one agent demonstrates a stable, observable interpretation of the term |
+
+Each check consumes the inputs of §2 and produces a verdict plus the evidence that supports it. Do not skip the measurement step in any check: "it is not possible to reason about semantics without taking into account the underlying dynamics" [VERIFIED — InfoQ, *In Search of Certainty*].
+
+## 4. The procedure — bounded, stepped
+
+**EXTRAPOLATION** — this five-step procedure is this skill's synthesis: it applies the verified SST machinery (γ(3,4) typing, semantic distance, absorbing states, promise overlap) as a debugging discipline. Run the steps in order; each step either locates the failure or rules out a whole class.
+
+**Pass structure.** One *pass* = running steps 1–4 in order. You may run up to **three passes**; a pass that does not converge must change something (a new observation, a new hypothesis, a re-typed edge) rather than repeat the same loop. After three non-converging passes, stop and write the evidence report (§5). This bounded exit mirrors the skill's Exit Conditions and prevents the re-litigation trap.
+
+### Step 1 — Reconstruct the semantic spacetime
+
+Build (or update) the γ(3,4) model of the failing system from the inputs: nodes typed as events (timelike process agents), things (persistent, realized), or concepts (virtual, unrealized); edges typed 0 = NEAR, ±1 = LEADS TO, ±2 = CONTAINS, ±3 = EXPRESSES [VERIFIED — arXiv:2506.07756; formal definition in [foundations.md](foundations.md) §2]. Record promises and acceptances as edges with their overlap `b∩` [VERIFIED — arXiv:2604.10505]. If the model cannot be built (no node type fits, edges cannot be typed), record that as evidence of a meaning gap and continue.
+
+### Step 2 — Locate the divergence
+
+Compute pairwise semantic distances between the instruction trajectory, the implementation trajectory, and the reality observations ([agent-coordination.md](agent-coordination.md) §8.5). Answer: which pair diverges, and along which dimension (spatial/temporal/task for the context-divergence framing [VERIFIED — arXiv:2606.21666]; semantic/coordination/behavioral for the agent-drift framing [VERIFIED — arXiv:2601.04170])? Identify the earliest observation at which the divergence exceeded threshold — that is the candidate *onset*.
+
+### Step 3 — Classify the condition
+
+Run the §3 checks for the four conditions against the divergence locus. The most common misreads to guard against: drift and divergence both show distance, but drift is time-local (one trajectory vs. its promise) while divergence is inter-agent (two trajectories vs. each other); a dead-end is not drift — it is structural, and only boundary data helps ("can only be replaced with new boundary data from outside the graph" [VERIFIED — arXiv:2506.07756]); a meaning gap is not divergence — it is the absence of a working interpretation, not two different ones.
+
+### Step 4 — Check the promise plumbing (link, don't restate)
+
+If the failure touches whether a promise was kept, whether acceptance was recorded, or how trust was calibrated, route that part of the diagnosis to [promise-theory's diagnosis-and-debugging reference](../../promise-theory/references/diagnosis-and-debugging.md) and run its assessment steps there. This procedure covers the semantic side only; do not re-derive promise-accounting here. Record which promises/acceptances the semantic failure involves (their overlap `b∩` [VERIFIED — arXiv:2604.10505]) as evidence, then return to Step 5.
+
+### Step 5 — Hypothesize the fix and verify it in the model
+
+For the classified condition, propose the SST-typed intervention and test it in the model before applying it to the system:
+
+- **Drift** → re-anchor the drifting term (Pattern 1) and re-apply the convergence loop (Pattern 3): re-affirm the promised meaning, re-record it as versioned data [EXTRAPOLATION — grounded in the fixed-point convergence of arXiv:2604.10505 and the versioned-coordinate machinery of arXiv:2204.00470].
+- **Divergence** → reconcile (Pattern 10): expose both projections, expand the co-language, re-anchor shared terms, re-measure [EXTRAPOLATION — grounded in the offer/acceptance overlap and three-languages framing of arXiv:2604.10505].
+- **Dead-end** → inject boundary data: a new promise, a human input, outside policy — then verify the absorbing state re-opens [VERIFIED — arXiv:2506.07756].
+- **Meaning gap** → define and anchor the missing term in the exchange co-language, or refuse to proceed on it until both sides accept a definition [EXTRAPOLATION — grounded in the co-language/non-unitary-translation framing of arXiv:2604.10505].
+
+Verify the fix by re-running Step 2 on the model with the fix applied: the divergence metric must move toward zero (or stay within the risk threshold). If it does not, the fix was wrong — this is a non-converging pass; change the hypothesis and go again (up to three passes).
+
+## 5. The bounded exit — after three non-converging passes
+
+If after **three passes** the divergence metric is still above threshold, the absorbing state still absorbs, or the meaning gap persists, **stop diagnosing and report**. Do not iterate a fourth time, do not re-litigate the same model, do not silently widen the scope. The purpose of the bound is to convert an unbounded hunt into an evidence artifact — the diagnosis is itself a finding.
+
+## 6. Exit artifacts — what the evidence report must contain
+
+Write the report with at least these sections (this is the report contract of [templates/sst-analysis.md.tmpl](../templates/sst-analysis.md.tmpl)):
+
+1. **System description** — the model built in Step 1 (or the reason it could not be built).
+2. **Semantic spacetime map** — the γ(3,4) graph with node types, link types, and the divergence locus marked.
+3. **Findings** — for each of the four conditions: confirmed or ruled out, with the check evidence; the onset observation for drift/divergence; the leaking boundary for dead-ends; the unanchored term for meaning gaps.
+4. **Interventions** — the fixes tried in Steps 5, with their modeled outcomes (converged / non-converging per pass).
+5. **Verification/measurement plan** — the specific re-measurement (what to observe, at what scale, how often) that would confirm the fix in the real system, per the "dynamics always trumps semantics" measurement rule [VERIFIED — InfoQ, *In Search of Certainty*].
+6. **Pass ledger** — what changed between pass 1, 2, and 3, so a future diagnoser can see the evidence trail and pick up where this one stopped.
+
+A completed report is a legitimate termination: the exit condition is an observable artifact (the report exists and states findings + bounded escalation), not an admission of failure.
+
+## Routing
+
+For the metrics and literature behind Steps 2–3: [agent-coordination.md](agent-coordination.md) §5. For the patterns the interventions apply: [patterns.md](patterns.md). For the formal model and γ(3,4) definitions: [foundations.md](foundations.md). For the empirical infrastructure record behind the measurement rule: [applications-infrastructure.md](applications-infrastructure.md). For promise-accounting diagnosis (assessment, breach, trust): [promise-theory](../../promise-theory/SKILL.md) and its [diagnosis-and-debugging reference](../../promise-theory/references/diagnosis-and-debugging.md).

semantic-spacetime/references/foundations.md

@@ -0,0 +1,451 @@
+# Foundations — The Academic Core of Semantic Spacetime
+
+**Load this file when you need the definitions, the formal model, proper time,
+causality, the γ(3,4) formalism, the learning/knowledge formalism, or an honest
+assessment of the theory's status.** This is the academic anchor of the skill.
+What belongs here: the academic theory of Semantic Spacetime (SST) as developed
+by Mark Burgess (2014-2025) — definitions, the formal model, γ(3,4), proper
+time, causality, the promise-theory substrate, and adjacent fields. What does
+not belong here: quantum-gravity or physics derivation (this is not a physics
+theory — see §4), the CFEngine/infrastructure application history, and the
+agent-coordination synthesis; those belong to the skill's application and
+agent-coordination references ([applications-infrastructure.md](applications-infrastructure.md)
+and [agent-coordination.md](agent-coordination.md)). For
+one-line definitions see [glossary.md](glossary.md); for sources see
+[bibliography.md](bibliography.md).
+
+**Provenance.** Every definition below is tagged with exactly one marker,
+following the research corpus this skill was built from:
+
+- `[VERIFIED]` — confirmed directly in a primary source fetched during the
+  research phase (the arXiv papers, markburgess.org pages, and the fetched
+  secondary sources listed in [bibliography.md](bibliography.md)).
+- `[UNVERIFIED]` — secondary-source or inferred; confirmed only via metadata,
+  search index, or an author's own secondary account.
+- `EXTRAPOLATION` — original synthesis extending the theory to new domains;
+  never presented as a verified fact.
+
+The theory is semi-formal and deliberately unrefereed (§5). This file states
+what is defined and verified, what is only informally claimed, and what is this
+skill's own synthesis. Do not present unverified claims as fact and do not drop
+markers when reusing this content.
+
+---
+
+## 1. Authorship and scope of the term
+
+Semantic Spacetime is the coinage and project of **Mark Burgess** — the
+physicist-turned-computer-scientist who created CFEngine — with the exact term
+effectively his alone. A full-text search of arXiv for the exact phrase
+"semantic spacetime" returns exactly 7 hits, all by Burgess; "semantic
+space-time" returns zero hits [VERIFIED — arXiv full-text search performed
+2026-08-12]. There is no independent academic school using the term. The
+primary series is his arXiv papers 2014-2025:
+
+- *Spacetimes with Semantics* (2014), arXiv:1411.5563 [VERIFIED]
+- *Spacetimes with Semantics (II): Scaling of agency, semantics, and tenancy*
+  (2015), arXiv:1505.01716 [VERIFIED]
+- *Spacetimes with Semantics (III): The Structure of Functional Knowledge
+  Representation and Artificial Reasoning* (2016, rev. 2017), arXiv:1608.02193 —
+  the most formal document, canonical source for Definitions 1-9 and
+  Lemmas 1-3 [VERIFIED]
+- *Agent Semantics, Semantic Spacetime, and Graphical Reasoning* (2025),
+  arXiv:2506.07756 — the current formal statement, introducing the γ(3,4)
+  representation [VERIFIED]
+
+Burgess states the intent directly: *"I have no interest or intention of
+seeking to publish any of this work beyond making these notes available seeking
+trusted review"* [VERIFIED — markburgess.org/blog_spacetime3.html]. SST is a
+conceptual/modeling framework, deliberately not a quantum-gravity theory (§4).
+
+## 2. The formal model
+
+The formal skeleton comes from Part III (arXiv:1608.02193v4), which Burgess
+calls "lengthy notes" laying foundations; and from the 2025 γ(3,4) paper.
+
+### Semantic element (Definition 1)
+
+> "A semantic element is a tuple ⟨Aᵢ, {π_scalar j, …}⟩ consisting of a single
+> autonomous agent, and an optional number of scalar material promises."
+> [VERIFIED — arXiv:1608.02193v4, Definition 1]
+
+An agent "surrounded by a halo of promises that imbue it with semantics"
+[VERIFIED — same source]. The promises are scalar/material (the agent's own
+capabilities and properties) as distinct from the vector/adjacency promises of
+Part II that connect elements into a spacetime [VERIFIED — arXiv:1505.01716].
+
+### Semantic spacetime (Definition 2)
+
+> "A collection of semantic elements, in any phase (gas or solid), for which a
+> local change in state, promises or configuration represents a local unit of
+> time." [VERIFIED — arXiv:1608.02193v4, Definition 2]
+
+Companion one-liner from the project hub: *"A semantic spacetime is a discrete
+graph, which evolves, and whose properties vary from point to point."*
+[VERIFIED — markburgess.org/spacetime.html]. The definition makes time a
+property of local change within the graph, not an external axis.
+
+### Proper time and the absence of a global clock
+
+Time in SST is *proper time*: *"Time in this sense is the Aristotelian concept
+of proper time as countable changes, as observed by the agent concerned."*
+[VERIFIED — arXiv:2506.07756 §1.3]. There is no global clock: *"The view of
+time as a relative transition system goes back to the work of Leslie Lamport…
+Lamport rediscovered the idea that time can at best be understood as a
+precedence relation, in a discrete spacetime context."* [VERIFIED —
+markburgess.org/semantic_spacetime.html]. Lamport, "Time, Clocks, and the
+Ordering of Events in a Distributed System," *CACM* 21(7):558-565, 1978, is the
+credited origin of this precedence view [VERIFIED — same page; bibliography].
+Practically: two agents cannot share a wall-clock ordering of events; each
+element's sequence of local changes is its own time.
+
+### Causality as cooperative promises
+
+Causality in SST is constituted by cooperative promises, not by imposed links.
+Each adjacency requires both an offer (+) and an acceptance (−) promise between
+the two ends: *"each node must both emit and absorb adjacency relations,
+cooperatively… Thus space is made up of cooperating nodes and edges."*
+[VERIFIED — markburgess.org/semantic_spacetime.html]. In the notation of the
+papers, `S →(+π) R` means sender S offers promise π to receiver R, which
+accepts with the complementary −π promise; influence passes only through the
+overlap of offer and acceptance [VERIFIED — arXiv:1608.02193]. This is the
+promise-theoretic spine that makes SST an agent model rather than a global
+network model: every edge is a negotiated, observable relation.
+
+### The γ(3,4) formalism
+
+The 2025 paper (arXiv:2506.07756) refines the earlier four irreducible
+associations (aggregation, causation, cooperation, similarity — [VERIFIED —
+arXiv:1608.02193]) into a typed graph formalism called γ(3,4): **three node
+meta-types × four link types** [VERIFIED — arXiv:2506.07756, Table 1].
+
+The three node meta-types [VERIFIED — arXiv:2506.07756 §2.3]:
+
+| Meta-type | Symbol | Nature |
+|---|---|---|
+| Events | e | Temporary/ephemeral; timelike (process) agents; persist or change via "leads to" |
+| Things | t | Persistent, physical/realized agents; "behave like matter"; spacelike (snapshot) |
+| Concepts | c | Invariant notions that cannot be created or destroyed; virtual space of "unrealized" potential; materialized only by attaching to physical agents |
+
+The four link types, exactly [VERIFIED — arXiv:2506.07756, Table 1]:
+
+| Value | Label | Direction | Semantics |
+|---|---|---|---|
+| 0 | NEAR | symmetric | equivalence, similarity, proximity, correlation |
+| ±1 | LEADS TO | directed | temporal/causal order: enables, causes, precedes, depends on |
+| ±2 | CONTAINS | directed | containment, membership, generalization, coarse-graining |
+| ±3 | EXPRESSES | directed | attribute, name/value, property, distinguishing mark |
+
+Burgess frames the four-link hypothesis itself as a hypothesis: *"This remains
+a hypothesis for now, but it is not a particularly original one. Various
+authors have suggested that spacetime concepts underpin natural language."*
+[VERIFIED — arXiv:2506.07756 §2.2]. No additional link types exist in the
+formalism; adding one would leave γ(3,4).
+
+### The nine typing design rules
+
+The node typing rules from arXiv:2506.07756 §2.3, exactly as verified
+[VERIFIED — arXiv:2506.07756 §2.3]:
+
+1. Things may be contained but not expressed.
+2. Concepts may be expressed but not contained.
+3. Concepts become realized by anchoring them to things or events.
+4. Verbs are dangling concepts without a subject or object to instantiate them.
+5. Verbs anchored to subjects/objects (things) are events.
+6. A realized state of being is an event.
+7. An unrealized state of being is a concept.
+8. A realized type of thing is a thing.
+9. An unrealized type of thing is a concept.
+
+Note on the paper's abstract: it states that "The Semantic Spacetime postulates
+bring predictability when reasoning," but the research phase could not verify an
+enumerated postulate list in the fetched text (it would require a full read of
+the paper's later sections). Treat the nine design rules above as the verified
+typing content; do not present them as a numbered list of "the Semantic
+Spacetime postulates" [UNVERIFIED — exact postulate set not verified].
+
+### Location agents and signal agents
+
+Two auxiliary agent types complete the model's ontology [VERIFIED —
+arXiv:1608.02193v4]:
+
+- **Location agents** (Definition 6): "irreducible sites that take up space and
+  can emit and absorb signal agents. They may not overlap."
+- **Signal agents** (Definition 7): "They may be created and destroyed,
+  subsequently emitted and absorbed, by location agents. They can occupy the
+  same space, since they end up and accumulate at end points."
+
+## 3. Absorbing states and information leaks
+
+Absorbing states are a central diagnostic concept in SST: *"The ubiquitous
+appearance of absorbing states in any partial graph means that a graph process
+leaks information."* [VERIFIED — arXiv:2506.07756 abstract]. They are
+"non-conserving of information" [VERIFIED — same source]. Burgess ties the
+phenomenon to division by zero: the leak is *"closely associated with the issue
+of division by zero, which signals a loss of closure and the need for manual
+injection of remedial information"* — and the boundary where the graph leaks is
+*"boundary information where intentionality can enter"* [VERIFIED — arXiv:
+2506.07756 §1.3]. Practically: a dead-end node (an event or thing with no
+outgoing LEADS TO/EXPRESSES edges that matter) accumulates meaning and stops
+propagating it; intent or policy must be injected manually at that boundary.
+For a bounded diagnosis procedure using this concept, see the skill's
+[diagnosis-and-debugging.md](diagnosis-and-debugging.md) reference.
+
+## 4. The "not physics" boundary
+
+SST is explicitly **not** a theory of physics: *"Semantic spacetime is a
+discrete model of spacetime, but it is not intended as a theory of quantum
+gravity, in spite of some affinity with quantum systems."* [VERIFIED —
+markburgess.org/semantic_spacetime.html]. Three consequences worth stating
+[VERIFIED — markburgess.org/semantic_spacetime.html]:
+
+- No manifold structure is assumed: space is constituted by relationships
+  between objects, not by a background geometry.
+- There is no concept of variable velocity, nor momentum: "a discrete spacetime
+  with finite number of states is not obviously a canonical system."
+- The connection with canonical systems remains unknown.
+
+When a task is physics (general relativity, quantum gravity, kinematics), SST
+is the wrong tool; route away at the SKILL.md "When not to use" boundary.
+
+## 5. Status: semi-formal and unrefereed
+
+The core series is a set of self-published notes, deliberately not submitted
+for refereed publication: *"I have no interest or intention of seeking to
+publish any of this work beyond making these notes available seeking trusted
+review"* [VERIFIED — markburgess.org/blog_spacetime3.html]. Burgess also warns
+of the scope: *"I have improvised with an eye on practical applications. It is
+probably too ambitious in scope and detail, but bridges may serve a purpose even
+with gaps,"* and *"Although not a complete theory, it lays out guidance on the
+formulation of the basic issues of information propagation, with some proofs
+left to the reader."* [VERIFIED — arXiv:1608.02193 preamble; markburgess.org/
+semantic_spacetime.html]. Use the formalism as a reasoning aid, not a proof
+system. What is formal: the graph definitions (Definitions 1-9), the γ(3,4)
+type system and its nine design rules, the learning/knowledge formalism with
+its Nyquist bound and decay lemmas (§9), and the association-decomposition
+algebra. What is semi-formal or metaphorical: the scaling/tenancy results of
+Part II, and the physics parallels (Feynman/Schwinger readings, quantum-field
+analogies, "logic emerges from reasoning") [VERIFIED — arXiv:1608.02193;
+markburgess.org].
+
+## 6. Promise theory as the substrate
+
+SST is formally built from Promise Theory: *"The chosen language here is
+Promise Theory (2004-2014)"* [VERIFIED — markburgess.org/spacetime.html] and
+*"the idea of semantic spacetime is based on an idea called Promise Theory"*
+[VERIFIED — markburgess.org/blog_spacetime3.html]. Promise Theory is the joint
+work of Mark Burgess and Jan A. Bergstra; its canonical statement is *Promise
+Theory: Principles and Applications* (χtAxis Press, 2014; 2nd ed. 2019), which
+describes itself as a "semi-formal language for modelling intent and its
+outcome" [VERIFIED — markburgess.org/promises.html].
+
+The primitives SST inherits, stated here in one line each and developed in
+depth by the promise-theory skill, are:
+
+- **Promise** — an autonomous declaration of intended behavior, with a body
+  (label Λ), a type (τ), and a constraint (χ); written `S →(+π) R` for an offer
+  from promiser S to promisee R [VERIFIED — promise-theory foundations;
+  arXiv:1608.02193].
+- **Offer (+) and acceptance (−)** — every interaction requires both directions
+  to be promised independently; this is the semantic spine of adjacency in SST
+  (§2, Causality) [VERIFIED].
+- **Autonomy and locality** — agents are autonomous and inert except for the
+  promises they make; a strong form of locality, and the reason SST is an agent
+  model rather than a global network model [VERIFIED].
+- **Downstream Principle** — the most downstream party in a promise chain
+  carries the greatest causal responsibility for the outcome [VERIFIED —
+  promise-theory foundations].
+- **Convergence** — repeated local assessment toward a desired state; the
+  dynamic meaning of "convergent coordination" in SST [VERIFIED — promise-theory
+  foundations].
+
+Do not re-derive promise definitions here. When you need the promise vocabulary
+(promises, acceptances, bindings, assessment, trust, the Downstream Principle),
+load [promise-theory](../../promise-theory/SKILL.md) or its
+[foundations reference](../../promise-theory/references/foundations.md). This
+skill's territory is the space/time of meaning built on top of those promises:
+γ(3,4), trajectories, drift, semantic distance, shared semantic ground.
+
+## 7. Measurement: the spacelike/timelike duality
+
+SST distinguishes two inequivalent ways to stabilize observation, which Burgess
+maps onto the Feynman (path-integral) vs. Schwinger (source) readings of
+quantum theory [VERIFIED — markburgess.org/semantic_spacetime.html;
+markburgess.org/spacetime.html]:
+
+1. **Spacelike / ensemble measurement** — *repeated trials with constant state
+   and semantics, in which time plays no role*; objective/frequentist. You
+   sample the same configuration many times and average.
+2. **Timelike / "cognitive" measurement** — *continuously adapting accumulation
+   of state, whose semantics define change in real time*; subjective/Bayesian.
+   You update a running assessment as the system changes.
+
+The two modes can disagree because they answer different questions, and the
+practitioner consequence is the skill's core measurement rule: **semantics
+requires measurement** — meaning cannot be asserted before the dynamics are
+measured at the right scale. Different scales yield different conclusions; a
+measurement that is stable at one scale can be wrong at another. This duality
+is the theory-level ground for the "dynamics always trumps semantics" lesson of
+the infrastructure lineage (covered in the application reference,
+[applications-infrastructure.md](applications-infrastructure.md)) and for
+Gotcha 4 in SKILL.md.
+
+## 8. Distance: metric vs semantic
+
+Part III defines two kinds of distance [VERIFIED — arXiv:1608.02193v4]:
+
+- **Metric (quantitative) distance** (Definition 8): *"a measure of
+  coordinate-similarity in position."* Coordinates, embeddings, positions.
+- **Semantic (qualitative) distance** (Definition 9): *"a measure of similarity
+  in interpretation."* Worked examples in the paper: Hamming distance; hop
+  counts in an associative network; semantic hashing; sparse distributed
+  representations [VERIFIED — same source].
+
+The distinction is operational: two concepts can be close in coordinates yet
+far in interpretation, and vice versa. A weighted hop count over a γ(3,4) graph
+is a semantic-distance instance of the hop-count family — the family this
+skill's model tooling implements for measuring drift between two snapshots
+of a system's meaning.
+
+## 9. Learning and knowledge
+
+SST formalizes learning and knowledge as processes with explicit timescales
+[VERIFIED — arXiv:1608.02193v4]:
+
+- **Learning about a promise π** (Definition 3): "the sampling, equilibration,
+  and summarization of observational assessments concerning a promise π made by
+  another agent, repeated over a timescale T_learn > 2·T_sample." The observer
+  applies a learning function E(α(π)_{t+1}) = L(α(π)_t, E(α(π)_t)); learning
+  defines a clock ticking at rate T_sample.
+- **Knowledge of π** (Definition 4): "a stable summary of the iterated
+  assessment α(π)_{T_know}, of one or more promises π, formed by equilibration
+  of the samples over a timescale T_know ≫ 2·T_sample." Crucially, "because
+  knowledge defines a process with a timescale, the failure to confirm it
+  relative to other changes leads to its decay."
+- **Lemma 1 (knowledge decay):** uncertainty of knowledge grows geometrically
+  with time since learning, with attenuation ℓ^r, ℓ < 1.
+- **Lemma 2 (fidelity / learning rate):** "Learning can only represent source
+  values faithfully if the rate of sampling is greater than twice that of the
+  fastest rate of change in the data, i.e. 2/T_sample < ∂π/∂t" — the Nyquist
+  bound.
+
+Practitioner consequence: **staleness is a first-class quantity.** Memory and
+retrieval designs must budget refresh; a knowledge summary that is never
+re-confirmed decays geometrically no matter how accurate it was when formed.
+This directly supports drift diagnosis: a stale shared interpretation is a
+predictable source of semantic divergence.
+
+## 10. The empirical arm: the Quantitative Spacetime Hypothesis
+
+Two 2020 papers operationalize SST as a *testable hypothesis* rather than pure
+formalism [VERIFIED — arXiv:2010.08126; arXiv:2010.08125]:
+
+- **arXiv:2010.08126** — *Testing the Quantitative Spacetime Hypothesis using
+  Artificial Narrative Comprehension (I): Bootstrapping Meaning from Episodic
+  Narrative viewed as a Feature Landscape.* Parses narrative streams "without
+  knowledge of semantics, using only measurable patterns (size and time)… as an
+  event 'landscape'"; concepts are extracted "as process invariants." Results
+  claim simple spacetime process cues, not higher reasoning, drive what is
+  important about sensory experience [VERIFIED — arXiv:2010.08126].
+- **arXiv:2010.08125** — *…(II): Establishing the Geometry of Invariant
+  Concepts, Themes, and Namespaces.* Reconstructs concepts and themes via
+  "multiscale interferometry" and a "chemistry of association and pattern
+  reconstruction, based only on the four fundamental spacetime relationships,"
+  drawing a bioinformatic analogy (n-grams, micro/meso/macro scales)
+  [VERIFIED — arXiv:2010.08125].
+
+Honest caveat: these are proof-of-concept experiments on narrative corpora with
+single-CPU methods; the research phase found **no independent replication and no
+benchmark against distributional baselines** [UNVERIFIED — no independent
+replication found]. Treat the Quantitative Spacetime Hypothesis as an active,
+incompletely validated empirical program — not established validation of SST.
+
+## 11. Spacetime-Entangled Networks: consensus as entanglement
+
+*Spacetime-Entangled Networks (I): Relativity and Observability of Stepwise
+Consensus* is a four-author paper — Paul Borrill, Mark Burgess, Alan Karp,
+Atsushi Kasuya (arXiv:1807.08549, 2018, rev. 2020) — that instantiates the
+SST/promise line at the distributed-consensus layer [VERIFIED — arXiv:
+1807.08549]: *"Entanglement describes co-dependent evolution of state. Networks
+formed by entanglement of agents keep certain promises: they deliver sequential
+messages, end-to-end, in order, and with atomic confirmation of delivery to
+both ends of the link."* The "relativity of consensus" reading — observers at
+different points in the network reach consensus stepwise, in their own local
+order — is the SST no-global-clock doctrine applied to agreement
+[VERIFIED — arXiv:1807.08549; the mapping onto the cooperative-promise
+causality doctrine of §2 is this skill's synthesis and is labeled
+EXTRAPOLATION]. Note this paper is not one of the seven "semantic spacetime"
+phrase hits; it does not use the exact term [VERIFIED — arXiv search].
+
+## 12. Motion of the Third Kind
+
+SST distinguishes three ways to understand motion in a graph; the third,
+"virtual motion" (Motion of the Third Kind), treats processes and properties —
+for example cloud workloads and data records — as *promises moving from host to
+host* [VERIFIED — markburgess.org/spacetime.html]. This is the basis of
+Burgess's "cloud computing as virtual physics" framing: relocating a workload
+is not matter moving through space, it is a promise being re-anchored. The
+ResearchGate papers *Motion of the Third Kind I & II* (2021-22) exist but their
+full texts were not fetched during research; details beyond the moving-promises
+framing are [UNVERIFIED]. See [glossary.md](glossary.md) for the one-line entry.
+
+## 13. Adjacent fields
+
+SST sits next to — but is distinct from — these fields. Correct attribution and
+a one-line framing for each [VERIFIED — citations verified in the research
+phase; see bibliography]:
+
+- **Cognitive maps** — Tolman, "Cognitive maps in rats and men" (1948). The
+  brain demonstrably organizes knowledge spatially; SST is a candidate formal
+  language for concept space-times, not a neuroscience claim.
+- **Conceptual spaces** — Gärdenfors, *Conceptual Spaces: The Geometry of
+  Thought* (MIT Press, 2000). Concepts as convex regions in metric spaces with
+  quality dimensions; Gärdenfors-style spaces have **no time dimension** — SST
+  adds process and temporality.
+- **Distributional / vector-space semantics** — Harris (1954), LSA (Landauer &
+  Dumais 1997), word2vec-style embeddings (Mikolov et al. 2013). The dominant
+  statistical competitor; SST explicitly contrasts itself ("graphs preserve the
+  intentionality of the source even under data fractionation" vs. vectorized
+  probabilistic estimation [VERIFIED — arXiv:2506.07756; arXiv:2512.19084]).
+- **Event calculus** — Kowalski & Sergot (1986). Logic-based reasoning about
+  events where "the notion of event is taken to be more primitive than that of
+  time"; SST instead claims spacetime structure generates the semantics.
+- **Situation calculus** — McCarthy & Hayes (1969). Logic-based reasoning about
+  actions and change; the same logic-first framing distinguishes it from SST.
+- **Causal sets** — Myrheim (1978), Sorkin (2003), Surya (2019). The discrete-
+  spacetime program Burgess flags as the closest physics analogue: "in this
+  regard, a semantic spacetime is akin to causal sets" [VERIFIED — arXiv:
+  2506.07756 §2]. Difference: SST's nodes are autonomous agents with semantics,
+  not passive points, and SST assumes no manifold structure or symmetries.
+- **Logical clocks / virtual time** — Lamport (1978), Mattern (1988/89). The
+  distributed-systems backbone for "no global clock"; SST generalizes logical
+  clocks into full semantic spacetimes [VERIFIED].
+
+## 14. Applying this reference
+
+When you have modeled a system with this vocabulary, materialize it in the
+skill's model format — see [templates/sst-model.yaml.tmpl](../templates/sst-model.yaml.tmpl)
+(the versioned `sst-model-v1` contract: agents, nodes, edges, acceptances,
+trajectories, observations) — and write the analysis in
+[templates/sst-analysis.md.tmpl](../templates/sst-analysis.md.tmpl). For
+unfamiliar terms while reading, load [glossary.md](glossary.md). For the
+promise-theory substrate vocabulary, load
+[promise-theory](../../promise-theory/SKILL.md) — do not re-derive promises
+here. For measurement and verification practice (turning assessed meaning into
+evals and traces), the
+[agent-evals-and-observability](../../agent-evals-and-observability/SKILL.md)
+skill is the assessment-layer partner.
+
+## Sources
+
+Primary sources and adjacent works are listed with URLs in
+[bibliography.md](bibliography.md). The key items cited in this file: Burgess,
+*Spacetimes with Semantics* I-III (arXiv:1411.5563, 1505.01716, 1608.02193);
+Burgess, *Agent Semantics, Semantic Spacetime, and Graphical Reasoning*
+(arXiv:2506.07756); Burgess, *Testing the Quantitative Spacetime Hypothesis*
+I-II (arXiv:2010.08126, 2010.08125); Borrill, Burgess, Karp & Kasuya,
+*Spacetime-Entangled Networks (I)* (arXiv:1807.08549); Lamport, *Time, Clocks,
+and the Ordering of Events in a Distributed System* (CACM 1978); Burgess's
+project pages (markburgess.org/spacetime.html, /semantic_spacetime.html,
+/blog_spacetime3.html); Bergstra & Burgess, *Promise Theory: Principles and
+Applications* (2014/2019).

semantic-spacetime/references/glossary.md

@@ -0,0 +1,230 @@
+# Glossary — Semantic Spacetime Vocabulary
+
+**Load this file when you hit an unfamiliar term while applying this skill** —
+a word in the routing table, a reference, a model, or a diagnosis you cannot
+place. Each entry is a heading-led definition consistent with
+[foundations.md](foundations.md); where a term belongs to promise theory, the
+entry links there and keeps its own definition short. Sources are tagged as in
+[foundations.md](foundations.md): `[VERIFIED]` (confirmed in a primary source),
+`[UNVERIFIED]` (secondary or inferred), `EXTRAPOLATION` (this skill's
+synthesis).
+
+---
+
+## Core semantic spacetime terms
+
+### Semantic element
+**Semantic element** — "a tuple ⟨Aᵢ, {π_scalar j, …}⟩ consisting of a single
+autonomous agent, and an optional number of scalar material promises"
+[VERIFIED — arXiv:1608.02193v4 Def 1]. The atomic unit of a semantic spacetime:
+an agent "surrounded by a halo of promises that imbue it with semantics."
+See [foundations.md](foundations.md) §2.
+
+### Semantic spacetime
+**Semantic spacetime (SST)** — "a collection of semantic elements, in any phase
+(gas or solid), for which a local change in state, promises or configuration
+represents a local unit of time" [VERIFIED — arXiv:1608.02193v4 Def 2]. Mark
+Burgess's discrete graph model of meaning over time; the term is effectively his
+alone (exactly 7 arXiv hits, all by him) [VERIFIED]. See
+[foundations.md](foundations.md) §2.
+
+### Proper time
+**Proper time** — time as countable local changes observed by the agent
+concerned: "the Aristotelian concept of proper time as countable changes, as
+observed by the agent concerned" [VERIFIED — arXiv:2506.07756 §1.3]. Each
+semantic element has its own proper time; there is no global clock. See
+[foundations.md](foundations.md) §2.
+
+### Cooperative promise causality
+**Cooperative promise causality** — the SST account of causation: every
+adjacency requires both an offer (+) and an acceptance (−) promise between the
+two ends, so "space is made up of cooperating nodes and edges"
+[VERIFIED — markburgess.org/semantic_spacetime.html]. Causality is negotiated,
+local, and observable; it is never imposed. See
+[foundations.md](foundations.md) §2.
+
+### γ(3,4)
+**γ(3,4)** — the 2025 typed-graph formalism of Semantic Spacetime (Burgess,
+arXiv:2506.07756): exactly three node meta-types — events (e), things (t),
+concepts (c) — crossed with exactly four link types — 0 NEAR, ±1 LEADS TO,
+±2 CONTAINS, ±3 EXPRESSES [VERIFIED]. Pronounced "gamma three four"; the model
+format in this skill encodes it as nodes with a `type` and edges with a `link`
+value in {-3..3}. See [foundations.md](foundations.md) §2.
+
+### NEAR
+**NEAR** — γ(3,4) link value 0; symmetric; equivalence, similarity, proximity,
+correlation. The "semantic symmetrization" link [VERIFIED — arXiv:2506.07756
+Table 1]. See [foundations.md](foundations.md) §2.
+
+### LEADS TO
+**LEADS TO** — γ(3,4) link value ±1; directed; temporal/causal order — enables,
+causes, precedes, depends on. The "follows" gradient link [VERIFIED — arXiv:
+2506.07756 Table 1]. See [foundations.md](foundations.md) §2.
+
+### CONTAINS
+**CONTAINS** — γ(3,4) link value ±2; directed; containment, membership,
+generalization, coarse-graining. The aggregate/membership link [VERIFIED —
+arXiv:2506.07756 Table 1]. See [foundations.md](foundations.md) §2.
+
+### EXPRESSES
+**EXPRESSES** — γ(3,4) link value ±3; directed; attribute, name/value,
+property, distinguishing mark. The distinguishability link [VERIFIED — arXiv:
+2506.07756 Table 1]. See [foundations.md](foundations.md) §2.
+
+### Event
+**Event** — γ(3,4) node meta-type e: temporary/ephemeral, timelike (process)
+agents that persist or change via "leads to" [VERIFIED — arXiv:2506.07756
+§2.3]. A realized state of being is an event; verbs anchored to things are
+events. See [foundations.md](foundations.md) §2.
+
+### Thing
+**Thing** — γ(3,4) node meta-type t: persistent, physical/realized agents that
+"behave like matter"; spacelike snapshot [VERIFIED — arXiv:2506.07756 §2.3].
+Things may be contained but not expressed. See [foundations.md](foundations.md)
+§2.
+
+### Concept
+**Concept** — γ(3,4) node meta-type c: invariant notions that cannot be created
+or destroyed; the virtual space of "unrealized" potential, materialized only by
+anchoring to things or events [VERIFIED — arXiv:2506.07756 §2.3]. Concepts may
+be expressed but not contained. See [foundations.md](foundations.md) §2.
+
+### Absorbing state
+**Absorbing state** — a state in a partial graph where information stops
+flowing; "absorbing states are non-conserving of information" and "a graph
+process leaks information" at them [VERIFIED — arXiv:2506.07756]. Burgess ties
+the leak to division by zero: "loss of closure and the need for manual
+injection of remedial information"; the leaking boundary is "boundary
+information where intentionality can enter" [VERIFIED]. In diagnosis, a
+dead-end node that accumulates meaning without propagating it. See
+[foundations.md](foundations.md) §3.
+
+### Metric distance
+**Metric (quantitative) distance** — "a measure of coordinate-similarity in
+position" [VERIFIED — arXiv:1608.02193v4 Def 8]. Coordinates, embeddings,
+positions. Contrast with semantic distance. See [foundations.md](foundations.md)
+§8.
+
+### Semantic distance
+**Semantic (qualitative) distance** — "a measure of similarity in
+interpretation" [VERIFIED — arXiv:1608.02193v4 Def 9]; worked examples include
+Hamming distance, hop counts in an associative network, semantic hashing, and
+sparse distributed representations. Two concepts can be close in coordinates
+yet far in interpretation. See [foundations.md](foundations.md) §8.
+
+### Semantic drift
+**Semantic drift** — this skill's term for the divergence of shared semantic
+ground over time: two agents (or an agent and its instructions) start with the
+same meaning for a term and their interpretations move apart as their local
+proper times advance. The diagnosis treats drift as an observable — measure the
+semantic distance between the interpretations at successive observations.
+**EXTRAPOLATION** — the drift concept is the skill's application of SST's
+trajectory and semantic-distance machinery; the term itself is standard in the
+agent-drift literature the research corpus reviewed, while the SST framing is
+synthesis.
+
+### Trajectory
+**Trajectory** — the path an agent or a concept takes through semantic
+spacetime: the sequence of node states a semantic element occupies as its
+proper time advances, recorded as observations. Reasoning is "constrained
+spacetime trajectories" through the association network [VERIFIED — arXiv:
+1608.02193 §1, §5]. In the model format, a trajectory is a declared `path` of
+node ids.
+
+### Shared semantic ground
+**Shared semantic ground** — the overlap of interpretation between two or more
+agents: the set of terms and promises that both sides mean the same way,
+measurable as low semantic distance between their concepts. SST models it as a
+region of the semantic spacetime where NEAR/EXPRESSES edges agree across
+agents. **EXTRAPOLATION** — synthesis term for this skill, grounded in the
+cooperative-promise account of adjacency and the definition of semantic
+distance.
+
+### Temporal blindness
+**Temporal blindness** — an agent's failure to track event ordering, state
+change, or causality — effectively lacking a proper-time record of its own
+semantic element. SST's local-time account (no global clock) makes such
+blindness structural unless observations are recorded; the fix is a recorded
+observation log per element. The research corpus documents the LLM literature
+on this ("LLMs are temporally blind," arXiv:2510.23853) [VERIFIED — citation in
+the research corpus; the SST framing is EXTRAPOLATION].
+
+### Spacelike measurement
+**Spacelike (ensemble) measurement** — repeated trials with constant state and
+semantics, in which time plays no role; objective/frequentist [VERIFIED —
+markburgess.org/semantic_spacetime.html]. See [foundations.md](foundations.md)
+§7.
+
+### Timelike measurement
+**Timelike ("cognitive") measurement** — continuously adapting accumulation of
+state whose semantics define change in real time; subjective/Bayesian
+[VERIFIED — markburgess.org/semantic_spacetime.html]. See
+[foundations.md](foundations.md) §7.
+
+### Learning
+**Learning (about a promise π)** — "the sampling, equilibration, and
+summarization of observational assessments concerning a promise π made by
+another agent, repeated over a timescale T_learn > 2·T_sample" [VERIFIED —
+arXiv:1608.02193v4 Def 3]. Learning defines a clock ticking at rate T_sample.
+See [foundations.md](foundations.md) §9.
+
+### Knowledge
+**Knowledge (of a promise π)** — "a stable summary of the iterated assessment
+α(π)_{T_know}, of one or more promises π, formed by equilibration of the samples
+over a timescale T_know ≫ 2·T_sample"; it decays geometrically without refresh
+(attenuation ℓ^r, ℓ < 1) [VERIFIED — arXiv:1608.02193v4 Def 4, Lemma 1].
+Staleness is a first-class quantity. See [foundations.md](foundations.md) §9.
+
+### Location agent
+**Location agent** — "irreducible sites that take up space and can emit and
+absorb signal agents. They may not overlap" [VERIFIED — arXiv:1608.02193v4
+Def 6]. See [foundations.md](foundations.md) §2.
+
+### Signal agent
+**Signal agent** — agents that "may be created and destroyed, subsequently
+emitted and absorbed, by location agents. They can occupy the same space, since
+they end up and accumulate at end points" [VERIFIED — arXiv:1608.02193v4
+Def 7]. See [foundations.md](foundations.md) §2.
+
+### Super-agent
+**Super-agent** — the coarse-grained agent formed by scaling agency up via the
+Part II rules: replacing a group of individual agents with one "super-agent"
+(sub-space), scaling agency both dynamically and semantically [VERIFIED — arXiv:
+1505.01716]. The renormalization analogue; see
+[foundations.md](foundations.md) §1 for the series map.
+
+### Motion of the Third Kind
+**Motion of the Third Kind** — "virtual motion": processes and properties (e.g.,
+cloud workloads, data records) treated as promises moving from host to host,
+the basis of Burgess's "cloud computing as virtual physics" framing [VERIFIED —
+markburgess.org/spacetime.html]. The ResearchGate papers of that name (2021-22)
+exist; their details are [UNVERIFIED]. See [foundations.md](foundations.md) §12.
+
+## Promise-theory-owned terms (deferred)
+
+### Promise
+**Promise** — an autonomous declaration of intended, as yet unverified,
+behavior made by one agent to another; the primitive every SST adjacency builds
+on (offer polarity +π). Full definition, notation, and body/type/constraint
+machinery live in [promise-theory](../../promise-theory/SKILL.md) — load it
+there rather than re-deriving it. See [foundations.md](foundations.md) §6.
+
+### Acceptance
+**Acceptance** — the complementary counter-promise (−π) that turns an offer
+into a binding: influence passes only through the overlap of offer and
+acceptance. SST's cooperative-promise causality is built from it. Full
+treatment: [promise-theory](../../promise-theory/SKILL.md). See
+[foundations.md](foundations.md) §2 and §6.
+
+### Convergence
+**Convergence** — repeated local assessment toward a desired state (a fixed
+point), the dynamic meaning of "convergent coordination" in SST; statistical,
+never exact. Full treatment (including the distinction from idempotence):
+[promise-theory](../../promise-theory/SKILL.md) and its applications reference.
+See [foundations.md](foundations.md) §6.
+
+### Downstream Principle
+**Downstream Principle** — the most downstream party in a promise chain carries
+the greatest causal responsibility for the outcome. Promise-theory-owned;
+[promise-theory](../../promise-theory/SKILL.md) has the full statement. See
+[foundations.md](foundations.md) §6.

semantic-spacetime/references/patterns.md

@@ -0,0 +1,108 @@
+# Patterns — Ten Named SST Patterns for Design and Diagnosis
+
+**Load this file when you need to apply a named pattern** — semantic anchor, semantic trajectory, convergence loop, promise propagation, drift detection, absorbing-state detection, shared semantic manifold, γ(3,4) modeling, semantic distance/divergence metrics, or reconciliation. Each pattern states its when-to-use condition as an observable trigger, its anti-pattern as a concrete misuse, and its SST grounding.
+
+**What belongs here:** the ten patterns as reusable, named design moves, with when-to-use triggers and anti-patterns. What does **not** belong here: the formal definitions behind the patterns (see [foundations.md](foundations.md)); the empirical record of the infrastructure and agentic-AI lines (see [applications-infrastructure.md](applications-infrastructure.md) and [agent-coordination.md](agent-coordination.md)); the bounded diagnosis procedure (see [diagnosis-and-debugging.md](diagnosis-and-debugging.md)). Promise-level machinery (offer/acceptance, assessment, breach, trust calibration) is linked to [promise-theory](../../promise-theory/SKILL.md), never re-taught here.
+
+**Provenance.** `[VERIFIED]` = confirmed in a fetched primary source; `[UNVERIFIED]` = secondary/inferred; `EXTRAPOLATION` = this skill's synthesis, labeled. Patterns grounded in verified research are marked; the pattern *shapes* themselves (when-to-use/anti-pattern framing) are this skill's original synthesis [EXTRAPOLATION] unless a source is named.
+
+---
+
+## 0. Pattern overview
+
+| # | Pattern | Use when (one line) | Key anti-pattern |
+|---|---|---|---|
+| 1 | Semantic anchor | A term or promise needs a stable, versioned meaning reference | Freezing the anchor forever; anchoring to an internal embedding |
+| 2 | Semantic trajectory | You need to record where an agent's meaning is going over time | Treating snapshots as the whole story; no time axis |
+| 3 | Convergence loop | State must be measured against a desired meaning and repaired | Confusing convergence with idempotence; expecting exactness |
+| 4 | Promise propagation | Delegation chains carry commitments between agents | Modeling promises without acceptance; long unverified chains |
+| 5 | Drift detection | Meaning quietly changes between two snapshots or agents | Thresholding on one snapshot; ignoring scale |
+| 6 | Absorbing-state detection | Agents dead-end, hallucinate, or stop learning | Treating the symptom as the cause; no boundary injection |
+| 7 | Shared semantic manifold | Agents must coordinate on what relations mean | Building a manifold without causality; expecting identical projections |
+| 8 | γ(3,4) modeling | You need to type the semantic graph (events/things/concepts × 4 links) | Inventing extra link types; ontology-first modeling |
+| 9 | Semantic distance/divergence metrics | You need a number for "how far apart" two meanings are | Using raw coordinate distance as semantic distance |
+| 10 | Reconciliation | Two divergent meanings must be brought back into agreement | Forcing agreement by fiat; no acceptance on both sides |
+
+## 1. Semantic anchor
+
+**When to use:** use when you observe that a term, promise, or instruction keeps being interpreted differently by different agents (or by the same agent at different times), and you need a stable reference point against which interpretations can be compared. The observable trigger is a measurable disagreement that re-occurs despite repeated explanation.
+
+**Shape:** a versioned, addressable statement of what a concept or promise *means* in this system — the intended interpretation, its boundaries (what it does not cover), and its revision history. In SST terms the anchor is a concept node with typed edges to the things and events it is anchored to (γ(3,4) typing rule: concepts become realized by anchoring to things or events [VERIFIED — arXiv:2506.07756]); its revision history is the record axis of [applications-infrastructure.md](applications-infrastructure.md) §8.
+
+**Anti-patterns:** freezing the anchor — a semantic anchor that can never be revised becomes a lie as the system changes (knowledge decays geometrically when unconfirmed; [VERIFIED — arXiv:1608.02193, Lemma 1, via foundations.md §9]). Anchoring to an agent's internal embedding rather than to an observable, shared statement — embeddings are "interior spaces" with "inscrutable property models" [VERIFIED — arXiv:2506.07756]. Anchoring to prose that no one versioned — the GitOps lesson is that the contract must be versioned desired state [VERIFIED — CNCF, GitOps 101].
+
+## 2. Semantic trajectory
+
+**When to use:** use when you need to know where an agent's (or a system's) meaning is going over time — whether understanding is converging, drifting, or diverging — and when the artifact you need is a recorded path, not a single snapshot. Trigger: the question "how did we get from interpretation A to interpretation B?" is answerable only from a series of observations, not from the current state.
+
+**Shape:** a sequence of {position, intent (promise), time} observations — each local change is a unit of proper time for the element concerned [VERIFIED — arXiv:1608.02193, Def. 2, via foundations.md]. Record the trajectory as observations in the skill's model format (see [templates/sst-model.yaml.tmpl](../templates/sst-model.yaml.tmpl)); compute displacement (drift), inter-agent separation (divergence), and approach-to-fixed-point (convergence) from it.
+
+**Anti-patterns:** treating snapshots as the whole story — a single state cannot show drift, because drift is a time-indexed quantity [EXTRAPOLATION — grounded in the definitions of drift in arXiv:2601.04170]. Recording trajectories without a time axis or causal order — wall-clock-less, causality-less traces cannot answer "what can affect what" [VERIFIED — Lamport 1978, via applications-infrastructure §4]. Confusing the agent's reported trajectory with its actual trajectory — the record axis and the world axis must stay separate [VERIFIED — Temporal database Wikipedia, via applications-infrastructure §4].
+
+## 3. Convergence loop
+
+**When to use:** use when you need a system that continuously measures its current state against a desired meaning and repairs toward it — the SST form of a control loop. Trigger: you can state a desired end-state as an observable condition, and you expect the environment to perturb state unpredictably over time.
+
+**Shape:** a loop that (1) measures the current state, (2) compares against the promised state, (3) acts to repair divergence, (4) repeats. This is CFEngine's fixed-point machinery — a convergent operator satisfies `O(q0) = q0` with `O^2 = O`, "like a ball rolling into a potential well" [VERIFIED — Burgess, *A Tiny Overview of CFEngine*] — and MAPE-K's monitor → analyze → plan → execute [VERIFIED — Kephart & Chess 2003]. It is also the drift literature's bounded-equilibrium finding: turn-wise divergence evolves "as a bounded stochastic process with restoring forces" [VERIFIED — arXiv:2510.07777]. For the promise-level convergence mechanics (offer/acceptance and assessment inside the loop), link to [promise-theory](../../promise-theory/references/patterns.md) rather than re-deriving them.
+
+**Anti-patterns:** confusing convergence with idempotence — idempotence requires only O²=O, convergence is relative to a specific policy state q0 [VERIFIED — *A Tiny Overview*]. Expecting exactness — convergence is statistical, never exact, in a stochastic environment: "a complete specification of policy determines an approximate configuration… only approximately over persistent times" [VERIFIED — *A Tiny Overview*]. A loop with no measurement plan — "dynamics always trumps semantics"; without measurement at the right scale, the loop is guessing [VERIFIED — InfoQ, *In Search of Certainty*].
+
+## 4. Promise propagation
+
+**When to use:** use when commitments travel through chains — an orchestrator delegates to a subagent, which delegates further, or a promise must transit intermediate agents — and you need to model how intent propagates and where it attenuates. Trigger: a delegation chain of length ≥ 2, or a promise whose meaning depends on intermediate reinterpretation.
+
+**Shape:** model each delegation as an offer (+b) and acceptance (−b) with overlap `b∩` — the effective propagated content is the overlap, not the full offer [VERIFIED — arXiv:2604.10505]; the Downstream Principle makes the accepting agent responsible for its own use [VERIFIED — same source]. Cost model: fully-promised delivery through N intermediaries costs O(N²); at minimal trust the promise graph must be complete [VERIFIED — same source]. Trace the trajectory of the promise through semantic spacetime and check where the overlap shrinks (each non-unitary translation "agents should expect to misunderstand one another's intentions to some level" [VERIFIED — arXiv:2604.10505]).
+
+**Anti-patterns:** modeling promises without acceptance — a dispatched task with no recorded acceptance is an imposition that looks accepted (the silence-as-acceptance trap) [EXTRAPOLATION — grounded in arXiv:2604.10505 offer/acceptance semantics and promise-theory's acceptance handshake pattern in [promise-theory/references/patterns.md](../../promise-theory/references/patterns.md)]. Long unverified chains — trusting the chain head instead of verifying per hop, which the O(N²) result and handoff-context-loss failures warn against [VERIFIED — arXiv:2604.10505; the handoff-loss reading is this skill's synthesis]. An agent promising on behalf of another — the tenet "no agent may promise anything on behalf of any agent but itself" [VERIFIED — arXiv:2604.10505].
+
+## 5. Drift detection
+
+**When to use:** use when meaning may be changing between snapshots, between agents, or between instruction and implementation, and you need to notice it early. Trigger: you have two or more observations of the same semantic state (or the same promise) at different times or from different agents, and you need a decision rule for "they no longer mean the same thing."
+
+**Shape:** compute a divergence metric between the observations (see Pattern 9), threshold it against a risk budget, and alert. The empirical metrics to draw on: the Context Divergence Score over spatial/temporal/task dimensions [VERIFIED — arXiv:2606.21666]; the Agent Stability Index over twelve dimensions [VERIFIED — arXiv:2601.04170]; turn-wise KL divergence with restoring forces [VERIFIED — arXiv:2510.07777]. The SST framing: drift is displacement from the promised trajectory; the three-trajectory version (instruction, implementation, reality) is Pattern 5's strongest form and is developed in [diagnosis-and-debugging.md](diagnosis-and-debugging.md) and [agent-coordination.md](agent-coordination.md) §8.5.
+
+**Anti-patterns:** thresholding on a single snapshot — drift is a time-indexed quantity; one measurement cannot detect it [EXTRAPOLATION]. Ignoring scale — different scales yield contradictory conclusions; "the ability to distinguish and separate scales is closely allied with our notions of simplicity" [VERIFIED — InfoQ, *In Search of Certainty*]. Full-broadcast "sync" as a fix — naive full-broadcast synchronization *increases* hallucination by 34%; selective sync reduces it [VERIFIED — arXiv:2606.21666].
+
+## 6. Absorbing-state detection
+
+**When to use:** use when agents or systems dead-end — repeat the same failure, hallucinate, stop learning, or stop responding to new information — and you need to recognize the dead-end as a structural property rather than a one-off bug. Trigger: the same divergent outcome recurs despite intervention, or information stops propagating from some node.
+
+**Shape:** identify the absorbing state in the γ(3,4) graph: "the ubiquitous appearance of absorbing states in any partial graph means that certain graph processes leak information and represent entropy changing processes"; absorbing states erase interior information and "can only be replaced with new boundary data from outside the graph, such as outside policy choices"; this is "closely associated with the issue of division by zero, which signals a loss of closure and the need for manual injection of remedial information" — "boundary information where intentionality can enter" [VERIFIED — arXiv:2506.07756]. The SST remedy is boundary injection: a new promise, a human input, or outside policy data, not more iterations of the same loop [VERIFIED — same source]. See [foundations.md](foundations.md) §3 for the formal treatment.
+
+**Anti-patterns:** treating the symptom as the cause — e.g., "more context" for a task that has collapsed into an absorbing state where no amount of interior information helps [EXTRAPOLATION — grounded in the absorbing-states doctrine]. Never injecting boundary data — an absorbing state "can only be replaced with new boundary data from outside the graph" [VERIFIED — arXiv:2506.07756]. Confusing an absorbing state with convergence — an absorbing state is a leak (entropy-increasing); a convergent fixed point is a desired attractor [VERIFIED — arXiv:2506.07756; *A Tiny Overview*].
+
+## 7. Shared semantic manifold
+
+**When to use:** use when multiple agents must coordinate on what relations mean — when "near", "causes", "contains", and "expresses" must mean the same thing to every participant — and raw token contexts or opaque agent cards are insufficient. Trigger: you observe coordination failures that trace to relation-type ambiguity ("we disagreed about whether X causes Y or merely correlates with Y").
+
+**Shape:** a shared γ(3,4)-structured representation (typed nodes and links) that each agent projects onto, with its own interior state kept separate; coordination happens by comparing projections. This is the coordination-substrate synthesis of [agent-coordination.md](agent-coordination.md) §8.1, grounded in the intentionality-preservation claim — "graphs preserve the intentionality of the source even under data fractionation" [VERIFIED — arXiv:2512.19084] — and the Tolman-Eichenbaum finding that spatial and relational memory share machinery [VERIFIED — Whittington et al., Cell 2020].
+
+**Anti-patterns:** building the manifold without causal-temporal structure — an undirected similarity space has no "leads-to" and cannot express the relation-type ambiguity that matters [EXTRAPOLATION — grounded in the four γ(3,4) link types]. Expecting identical projections — each agent is autonomous with local knowledge; the manifold coordinates *overlaps*, not identities [VERIFIED — arXiv:2604.10505 autonomy + local knowledge; the overlap framing is the paper's b∩]. Replacing the manifold with a giant shared context — full-broadcast context sharing increases hallucination [VERIFIED — arXiv:2606.21666].
+
+## 8. γ(3,4) modeling
+
+**When to use:** use when you need to type a semantic graph — to classify nodes as events (timelike process agents), things (spacelike snapshot agents), or concepts (virtual role/intention agents), and links as 0 = NEAR, ±1 = LEADS TO, ±2 = CONTAINS, ±3 = EXPRESSES [VERIFIED — arXiv:2506.07756]. Trigger: you have a knowledge or coordination graph and you need a principled, ontology-free typing of what each edge claims.
+
+**Shape:** apply the nine typing design rules (things may be contained but not expressed; concepts may be expressed but not contained; concepts become realized by anchoring to things or events; verbs are dangling concepts without subject/object; a realized state of being is an event; an unrealized state of being is a concept; a realized type of thing is a thing; an unrealized type of thing is a concept) [VERIFIED — arXiv:2506.07756 §2.3]. **The formal definition belongs to [foundations.md](foundations.md) §2 — load it before applying this pattern.** Note the honest limit: the claim that four link types suffice "remains a hypothesis for now" [VERIFIED — arXiv:2506.07756].
+
+**Anti-patterns:** inventing extra link types — the four types (0, ±1, ±2, ±3) are the γ(3,4) contract; adding ad-hoc edge semantics re-introduces the ontology tax the formalism avoids [EXTRAPOLATION — grounded in the "four basic arrows… sufficient" hypothesis and the anti-ontology framing of arXiv:2506.07756]. Ontology-first modeling — "ontologies do not employ principles rooted in the processes of the world"; SST "is not a taxonomy or an ontology" [VERIFIED — arXiv:2506.07756]. Using vector similarity as the edge semantics — vectors are for probabilistic estimation; graphs preserve intentionality [VERIFIED — arXiv:2512.19084].
+
+## 9. Semantic distance/divergence metrics
+
+**When to use:** use when you need a number for "how far apart" two meanings are — for routing, delegation, drift alerting, or reconciliation priority. Trigger: you must decide between two interpretations, two agents, or two snapshots based on how close they are semantically.
+
+**Shape:** distinguish **metric distance** ("a measure of coordinate-similarity in position") from **semantic distance** ("a measure of similarity in interpretation") [VERIFIED — arXiv:1608.02193, Definitions 8–9, via foundations.md §8]. Semantic distance instances include Hamming distance, hop counts in an associative network, semantic hashing, and sparse distributed representations [VERIFIED — same source]. On a γ(3,4) graph, a weighted hop count over typed links is a semantic-distance instance — weight by link type (causal links farther than similarity links, etc.) [EXTRAPOLATION — the weighting scheme is this skill's design; the hop-count family is verified]. The empirical drift metrics (CDS, ASI, KL) are divergence instances to reuse [VERIFIED — arXiv:2606.21666, 2601.04170, 2510.07777].
+
+**Anti-patterns:** using raw coordinate distance as semantic distance — "two concepts can be close in coordinates yet far in interpretation, and vice versa" [VERIFIED — arXiv:1608.02193, via foundations.md §8]. Unweighted hop counts that treat a causal edge like a similarity edge [EXTRAPOLATION]. Declaring a divergence metric without a measurement plan — metrics without observations at the right scale are ungrounded ("dynamics always trumps semantics") [VERIFIED — InfoQ, *In Search of Certainty*].
+
+## 10. Reconciliation
+
+**When to use:** use when two divergent meanings must be brought back into agreement — after drift detection, after a breached promise, or after a merge of two agent teams' interpretations. Trigger: you have identified pairwise semantic distance above a threshold and you need a bounded process to close it.
+
+**Shape:** a bounded negotiation: (1) expose each side's interpretation as a projection onto the shared manifold (Pattern 7); (2) identify the overlap `b∩` that already exists and the disagreement region [VERIFIED — arXiv:2604.10505 offer/acceptance overlap]; (3) expand the co-language — "agents may have to talk their way to a calibration of meaning" [VERIFIED — arXiv:2604.10505, three-languages framing]; (4) re-anchor the shared terms (Pattern 1) and re-record them as versioned data (the record axis of applications-infrastructure §8); (5) verify by re-measuring the divergence after the reconciliation. The drift literature's empirical anchor: reminder interventions reliably reduce divergence [VERIFIED — arXiv:2510.07777].
+
+**Anti-patterns:** forcing agreement by fiat — an imposition "without the receiver's promise" is generally ineffective and looks accepted without being so [VERIFIED — arXiv:2604.10505]. No acceptance on both sides — reconciliation without both sides' acceptance is not convergence, it is coercion [EXTRAPOLATION — grounded in the offer/acceptance machinery]. Reconciling once and never re-checking — knowledge decays without confirmation; reconciliation must be re-measured [VERIFIED — arXiv:1608.02193, Lemma 1, via foundations.md §9]. Iterating reconciliation indefinitely — the bounded-exit rule of [diagnosis-and-debugging.md](diagnosis-and-debugging.md) applies: three non-converging passes → stop and report evidence.
+
+## Routing
+
+For the formal model behind these patterns: [foundations.md](foundations.md). For the empirical record: [applications-infrastructure.md](applications-infrastructure.md) and [agent-coordination.md](agent-coordination.md). For the bounded diagnosis procedure that uses Patterns 2, 5, 6, 9, and 10: [diagnosis-and-debugging.md](diagnosis-and-debugging.md). For promise-level machinery (acceptance handshakes, evaluation loops, breach → renegotiation, trust calibration): [promise-theory](../../promise-theory/SKILL.md) and its [patterns reference](../../promise-theory/references/patterns.md).

semantic-spacetime/templates/sst-analysis.md.tmpl

@@ -0,0 +1,86 @@
+# Semantic Spacetime Analysis: <analysis-title>
+
+Semantic Spacetime analysis report. Fill this skeleton from a completed model
+in [sst-model.yaml.tmpl](sst-model.yaml.tmpl) (the versioned `sst-model-v1`
+format). Every section below corresponds to a construct defined in that model
+— agents, nodes, edges, acceptances, trajectories, observations — so the
+report and the model stay in sync; do not invent new fields.
+
+- Analysis version: <0.1.0>
+- Status: <DRAFTED | IN_REVIEW | COMPLETE>
+- Date: <YYYY-MM-DD>
+- Model version analyzed: <sst-model-v1>
+- Analyst: <agent-id or human name>
+
+## 1. System description
+
+Describe the system being modeled in plain language: who the agents are (their
+ids and roles from the model's `agents`), what the semantic spacetime covers,
+and the question the analysis answers (e.g., "why did the two agents'
+interpretations diverge?").
+
+- Agents: <agent-ids and roles>
+- Scope of the spacetime: <what the nodes/edges cover>
+- Analysis question: <the question this report answers>
+
+## 2. Semantic spacetime map
+
+Summarize the model's graph as built in `sst-model.yaml.tmpl`:
+
+- Nodes: <node-ids grouped by type: event | thing | concept>
+- Edges: <the gamma(3,4) edge set, each as from --link-value--> to, with the
+  link meaning 0 = NEAR, +/-1 = LEADS TO, +/-2 = CONTAINS, +/-3 = EXPRESSES>
+- Acceptances: <promise -> accepting agent pairs from the model's `acceptances`>
+- Trajectories: <the declared `trajectories`, i.e., the paths intent takes
+  through the graph>
+- Observations: <the proper-time record: what changed and when, from the
+  model's `observations`>
+
+## 3. Findings: drift, divergence, absorbing states
+
+List each finding with the evidence that grounds it (which nodes, edges,
+trajectories, or observations support it):
+
+### Finding <F1> — <short name>
+- Observation: <what the record shows — quote the relevant `observations` entries>
+- Interpretation: <which semantic elements drifted apart, which trajectory
+  diverged, or which node is an absorbing state>
+- Absorbing-state / information-leak check: <if a partial-graph dead-end is
+  present, state where information stops flowing and where intent must be
+  injected>
+
+### Finding <F2> — <short name>
+- Observation: <...>
+- Interpretation: <...>
+- Absorbing-state / information-leak check: <...>
+
+## 4. Interventions
+
+For each finding, propose a concrete change to the model (and, if applicable,
+to the system it models):
+
+- <F1> intervention: <e.g., re-anchor a dangling concept to a thing or event;
+  add an edge to close the leak; renegotiate a promise whose acceptance is
+  missing>
+- <F2> intervention: <e.g., record a new observation at a finer timescale
+  (timelike measurement) before asserting the semantics>
+
+## 5. Verification / measurement plan
+
+State how each intervention will be measured, using the model's own record
+machinery:
+
+- What to observe: <new `observations` entries or `trajectories` to add>
+- Measurement mode: <spacelike (repeated trials, constant state) | timelike
+  (continuous accumulation) — see the skill's foundations reference>
+- Success criterion: <the observable that must hold, e.g., semantic distance
+  between the two `concept` nodes stays at 0 NEAR across N observations>
+- Refresh budget: <how often the interpretation must be re-confirmed — stale
+  knowledge decays geometrically unless refreshed>
+
+## 6. Exit
+
+This analysis is complete when the system is modeled as a semantic spacetime,
+findings are recorded with evidence, and the verification plan is stated.
+When diagnosing drift: stop after three non-converging passes and report the
+evidence.

semantic-spacetime/templates/sst-model.yaml.tmpl

@@ -0,0 +1,108 @@
+# sst-model-v1
+#
+# Semantic Spacetime model format. A model is a versioned, machine-readable
+# description of a system as a semantic spacetime: autonomous agents with
+# scalar promises, typed semantic nodes (events / things / concepts), typed
+# gamma(3,4) edges, cross-agent acceptances, declared trajectories, and an
+# observation log (the proper-time record).
+#
+# FILLING GUIDE
+# -------------
+# Copy this template to a working file (e.g. sst-model.yaml) and replace the
+# example values with your own, keeping the structure. Every field below is
+# documented inline and in this guide. The block between the markers
+# '# --- example ---' and '# --- end example ---' is a complete, valid model:
+# imitate it. A filled model must satisfy every rule listed here; the bundled
+# CLI (scripts/semantic-spacetime.py 'model lint') reports violations by name.
+#
+# TOP-LEVEL FIELDS
+# ----------------
+# schema_version  REQUIRED. Must be the integer 1. Bump only when the format
+#                 changes; the format is a versioned contract.
+# agents          REQUIRED. List of autonomous agents that make promises.
+# nodes           REQUIRED. List of semantic elements of the spacetime graph,
+#                 typed as event, thing, or concept.
+# edges           REQUIRED. List of gamma(3,4) edges between nodes.
+# acceptances     OPTIONAL. List of cross-agent acceptance records tying a
+#                 promise to the agent that accepted it.
+# trajectories    OPTIONAL. List of declared paths through the node graph.
+# observations    OPTIONAL. List of proper-time records: what changed, and when.
+#
+# RULES (the linter will enforce these)
+# -------------------------------------
+#   * strict schema: unknown top-level sections and unknown fields inside any
+#     known section are rejected (exit 1 with a named violation).
+#   * schema_version must be 1 (integer, not a string).
+#   * agent ids are unique and lowercase-hyphen (^[a-z0-9]+(?:-[a-z0-9]+)*$);
+#     "all" is a reserved target token and cannot be an agent id.
+#   * promise ids are unique across the WHOLE model (agents and acceptances).
+#   * node ids are unique and lowercase-hyphen.
+#   * node type is exactly one of: event | thing | concept.
+#   * edge from/to must reference existing node ids; edge link must be an
+#     integer in -3..3 inclusive (0 = NEAR, +/-1 = LEADS TO, +/-2 = CONTAINS,
+#     +/-3 = EXPRESSES).
+#   * acceptance.promise must reference a declared promise id, and
+#     acceptance.from must equal the agent that declares that promise.
+#   * trajectory path entries must reference existing node ids (no
+#     edge-connectivity check in v1); a path has at least one entry.
+#   * observation.changed, when present, must reference a declared node id or
+#     promise id.
+#   * input is one restricted-YAML document (mappings, flow lists, quoted or
+#     unquoted scalars, comments, indentation-based nesting); anchors/aliases,
+#     block scalars, and multi-document streams are rejected with exit 1, and a
+#     single JSON document is accepted as an equivalent representation.
+
+# --- example ---
+schema_version: 1
+agents:
+  - id: operator              # required; unique; lowercase-hyphen
+    role: workflow operator   # required; free text
+    promises:                 # optional; scalar promises this agent makes
+      - id: deliver-report    # required; unique across the whole model
+        body: Deliver the weekly status report by Friday.   # required; free text
+        type: capability      # optional; capability | intent | constraint
+        target: reviewer      # optional; <agent-id> | <node-id> | all
+      - id: no-unverified-claims
+        body: Never assert a claim without a measured source.
+        type: constraint
+        target: all
+  - id: reviewer
+    role: semantic reviewer
+    promises:
+      - id: review-report
+        body: Review the report for semantic drift against the agreed vocabulary.
+        type: capability
+        target: operator
+nodes:                        # required; at least one semantic element
+  - id: report-event          # required; unique; lowercase-hyphen
+    type: event               # required; event | thing | concept
+  - id: report-thing
+    type: thing
+  - id: drift-concept
+    type: concept
+edges:                        # required; at least one gamma(3,4) edge
+  - from: report-event        # required; must be a declared node id
+    to: report-thing          # required; must be a declared node id
+    link: 1                   # required; integer in -3..3
+  - from: report-thing
+    to: drift-concept
+    link: 3
+  - from: drift-concept
+    to: report-thing
+    link: 2
+acceptances:                  # optional; cross-agent acceptance records
+  - promise: deliver-report   # required; must reference a declared promise id
+    from: operator            # required; must equal the agent that declares it
+    to: reviewer              # required; a declared agent id
+trajectories:                 # optional; declared paths through the graph
+  - id: report-flow           # required; unique
+    path: [report-event, report-thing, drift-concept]  # required; node ids, >= 1 entry
+    label: report moves from event to reviewed thing   # optional; free text
+observations:                 # optional; the proper-time record
+  - at: t1                    # required; tick label or timestamp, free text
+    event: report drafted     # required; what changed, free text
+    changed: report-event     # optional; a declared node id or promise id
+  - at: t2
+    event: reviewer flags drift in vocabulary
+    changed: drift-concept
+# --- end example ---

semantic-spacetime/tests/fixtures/invalid-model.yaml

@@ -0,0 +1,24 @@
+# Deliberately invalid sst-model-v1 model (fixture for the strict-schema lint
+# tests). Every field satisfies the normal rules EXCEPT the two strict-schema
+# violations below, so lint reports exactly these named violations:
+#   * 'bogus-field' is an unknown field inside node 'report-event'
+#   * 'regions' is an unknown top-level section
+# Expect 'model lint' to exit 1 and name both the key and its location.
+schema_version: 1
+agents:
+  - id: operator
+    role: workflow operator
+    promises:
+      - id: deliver-report
+        body: Deliver the weekly status report by Friday.
+nodes:
+  - id: report-event
+    type: event
+    bogus-field: 42
+edges:
+  - from: report-event
+    to: report-event
+    link: 1
+regions:
+  - id: r1
+    kind: concept

semantic-spacetime/tests/fixtures/sample-model.yaml

@@ -0,0 +1,54 @@
+# --- example ---
+schema_version: 1
+agents:
+  - id: operator              # required; unique; lowercase-hyphen
+    role: workflow operator   # required; free text
+    promises:                 # optional; scalar promises this agent makes
+      - id: deliver-report    # required; unique across the whole model
+        body: Deliver the weekly status report by Friday.   # required; free text
+        type: capability      # optional; capability | intent | constraint
+        target: reviewer      # optional; <agent-id> | <node-id> | all
+      - id: no-unverified-claims
+        body: Never assert a claim without a measured source.
+        type: constraint
+        target: all
+  - id: reviewer
+    role: semantic reviewer
+    promises:
+      - id: review-report
+        body: Review the report for semantic drift against the agreed vocabulary.
+        type: capability
+        target: operator
+nodes:                        # required; at least one semantic element
+  - id: report-event          # required; unique; lowercase-hyphen
+    type: event               # required; event | thing | concept
+  - id: report-thing
+    type: thing
+  - id: drift-concept
+    type: concept
+edges:                        # required; at least one gamma(3,4) edge
+  - from: report-event        # required; must be a declared node id
+    to: report-thing          # required; must be a declared node id
+    link: 1                   # required; integer in -3..3
+  - from: report-thing
+    to: drift-concept
+    link: 3
+  - from: drift-concept
+    to: report-thing
+    link: 2
+acceptances:                  # optional; cross-agent acceptance records
+  - promise: deliver-report   # required; must reference a declared promise id
+    from: operator            # required; must equal the agent that declares it
+    to: reviewer              # required; a declared agent id
+trajectories:                 # optional; declared paths through the graph
+  - id: report-flow           # required; unique
+    path: [report-event, report-thing, drift-concept]  # required; node ids, >= 1 entry
+    label: report moves from event to reviewed thing   # optional; free text
+observations:                 # optional; the proper-time record
+  - at: t1                    # required; tick label or timestamp, free text
+    event: report drafted     # required; what changed, free text
+    changed: report-event     # optional; a declared node id or promise id
+  - at: t2
+    event: reviewer flags drift in vocabulary
+    changed: drift-concept
+# --- end example ---

semantic-spacetime/tests/test_semantic_spacetime.py

@@ -0,0 +1,846 @@
+"""Unit tests for semantic-spacetime/scripts/semantic-spacetime.py.
+
+Run from the repository root:
+
+    python3 -m unittest discover -s semantic-spacetime/tests -p 'test_*.py'
+
+The tests exercise the CLI black-box (subprocess) so they pin the observable
+contract: exit codes (0 ok / 1 invalid model or input / 2 usage or IO),
+stdout/stderr separation, --json single-object purity, --dry-run no-writes,
+and the never-a-traceback rule. They also cover the sst-model-v1 template
+contract (the delimited example lints clean) and the tracked sample fixture.
+
+check-artifacts.py discovers this file with top_level_dir = the tests dir, so
+skill-root paths are resolved via explicit sys.path handling below.
+"""
+
+import ast
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+SKILL_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, SKILL_ROOT)
+
+SCRIPT = os.path.join(SKILL_ROOT, "scripts", "semantic-spacetime.py")
+TEMPLATE_PATH = os.path.join(SKILL_ROOT, "templates", "sst-model.yaml.tmpl")
+FIXTURE_PATH = os.path.join(SKILL_ROOT, "tests", "fixtures", "sample-model.yaml")
+INVALID_FIXTURE_PATH = os.path.join(
+    SKILL_ROOT, "tests", "fixtures", "invalid-model.yaml"
+)
+REPO_ROOT = os.path.dirname(SKILL_ROOT)
+
+VALID_YAML = """schema_version: 1
+agents:
+  - id: operator
+    role: workflow operator
+    promises:
+      - id: deliver-report
+        body: Deliver the weekly status report by Friday.
+        type: capability
+        target: reviewer
+  - id: reviewer
+    role: semantic reviewer
+    promises:
+      - id: review-report
+        body: Review the report for semantic drift.
+        type: capability
+        target: operator
+nodes:
+  - id: report-event
+    type: event
+  - id: report-thing
+    type: thing
+edges:
+  - from: report-event
+    to: report-thing
+    link: 1
+  - from: report-thing
+    to: report-event
+    link: 3
+acceptances:
+  - promise: deliver-report
+    from: operator
+    to: reviewer
+"""
+
+CYCLIC_YAML = """schema_version: 1
+agents:
+  - id: operator
+    role: workflow operator
+    promises:
+      - id: deliver-report
+        body: Deliver the weekly status report by Friday.
+nodes:
+  - id: a
+    type: event
+  - id: b
+    type: thing
+  - id: c
+    type: concept
+edges:
+  - from: a
+    to: b
+    link: 1
+  - from: b
+    to: c
+    link: 1
+  - from: c
+    to: a
+    link: 1
+  - from: a
+    to: c
+    link: 2
+"""
+
+DISCONNECTED_YAML = """schema_version: 1
+agents:
+  - id: operator
+    role: workflow operator
+    promises:
+      - id: p1
+        body: do something
+nodes:
+  - id: left-a
+    type: event
+  - id: left-b
+    type: thing
+  - id: right-x
+    type: thing
+edges:
+  - from: left-a
+    to: left-b
+    link: 1
+  - from: right-x
+    to: left-a
+    link: 3
+"""
+
+MALFORMED_YAML = """schema_version: 1
+agents:
+  - id: operator
+    role: "unclosed quote
+    promises:
+"""
+
+
+def _extract_template_example():
+    """Extract the machine-delimited example block from the template.
+
+    The block runs from the line exactly '# --- example ---' through the line
+    exactly '# --- end example ---' (inclusive). The markers also appear in
+    prose inside the template's FILLING GUIDE, so matching must be line-exact.
+    """
+    with open(TEMPLATE_PATH, encoding="utf-8") as fh:
+        lines = fh.read().split("\n")
+    start = end = None
+    for i, line in enumerate(lines):
+        if line.strip() == "# --- example ---":
+            start = i
+        elif line.strip() == "# --- end example ---":
+            end = i
+    assert start is not None and end is not None and start < end
+    return "\n".join(lines[start:end + 1]) + "\n"
+
+
+class SemanticSpacetimeCliTest(unittest.TestCase):
+    """Black-box CLI tests for the sst-model-v1 tool."""
+
+    def run_cli(self, *args, cwd=None):
+        return subprocess.run(
+            [sys.executable, SCRIPT, *args], capture_output=True, text=True, cwd=cwd
+        )
+
+    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)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    # -- basics (VAL-CLI-001) -------------------------------------------------
+
+    def test_help_lists_all_subcommands_and_flags(self):
+        p = self.run_cli("--help")
+        self.assertEqual(p.returncode, 0)
+        out = p.stdout.lower()
+        for needle in (
+            "model lint",
+            "model map",
+            "model distance",
+            "model trajectory",
+            "model drift",
+            "--json",
+            "--dry-run",
+            "sst-model-v1",
+        ):
+            self.assertIn(needle, out)
+
+    def test_version_is_dotted_triple(self):
+        p = self.run_cli("--version")
+        self.assertEqual(p.returncode, 0)
+        self.assertRegex(p.stdout.strip(), r"^\d+\.\d+\.\d+$")
+
+    def test_bare_invocation_exits_2_with_usage_on_stderr(self):
+        p = self.run_cli()
+        self.assertEqual(p.returncode, 2)
+        self.assertEqual(p.stdout, "")
+        self.assertIn("usage:", p.stderr.lower())
+        self.assertNotIn("Traceback", p.stderr)
+
+    # -- lint (VAL-CLI-002/003/013, VAL-CROSS-018) -----------------------------
+
+    def test_valid_yaml_lints_clean_with_coverage(self):
+        p = self.run_cli("model", "lint", self.valid_path)
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        out = p.stdout.lower()
+        self.assertIn("valid", out)
+        self.assertIn("cover", out)
+        self.assertIn("sst-model-v1", out)
+
+    def test_lint_json_shape(self):
+        p = self.run_cli("model", "lint", self.valid_path, "--json")
+        self.assertEqual(p.returncode, 0)
+        data = json.loads(p.stdout)
+        self.assertEqual(
+            set(data), {"command", "schema_version", "valid", "errors", "coverage"}
+        )
+        self.assertIs(data["valid"], True)
+        self.assertEqual(data["errors"], [])
+        self.assertEqual(data["schema_version"], "sst-model-v1")
+        self.assertGreaterEqual(data["coverage"]["nodes"], 1)
+        self.assertGreaterEqual(data["coverage"]["edges"], 1)
+
+    def test_invalid_node_type_named_violation(self):
+        bad = self.write_tmp(
+            "bad-node.yaml",
+            VALID_YAML.replace("type: event\n", "type: object\n", 1),
+        )
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("report-event", combined)
+        self.assertIn("object", combined)
+        self.assertIn("event, thing, concept", combined)
+
+    def test_invalid_link_value_named_violation(self):
+        bad = self.write_tmp(
+            "bad-link.yaml",
+            VALID_YAML.replace("link: 1\n", "link: 5\n", 1),
+        )
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("5", combined)
+        self.assertIn("-3..3", combined)
+
+    def test_dangling_edge_reference_named_violation(self):
+        bad = self.write_tmp(
+            "dangling-edge.yaml",
+            VALID_YAML.replace("from: report-event\n", "from: ghost-node\n", 1),
+        )
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("ghost-node", combined)
+        self.assertIn("'from'", combined)
+
+    def test_dangling_acceptance_named_violation(self):
+        bad = self.write_tmp(
+            "dangling-acceptance.yaml",
+            VALID_YAML.replace(
+                "promise: deliver-report\n", "promise: ghost-promise\n", 1
+            ),
+        )
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("ghost-promise", combined)
+
+    def test_dangling_trajectory_named_violation(self):
+        model = VALID_YAML + "\ntrajectories:\n  - id: t1\n    path: [report-event, ghost]\n"
+        bad = self.write_tmp("dangling-trajectory.yaml", model)
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("ghost", combined)
+
+    def test_violations_accumulate_all(self):
+        model = VALID_YAML.replace("type: event\n", "type: object\n", 1).replace(
+            "link: 1\n", "link: 9\n", 1
+        )
+        bad = self.write_tmp("multi-error.yaml", model)
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("object", combined)
+        self.assertIn("9", combined)
+
+    # -- strict schema rejection (VAL-CROSS-009) -------------------------------
+
+    def test_unknown_top_level_section_rejected(self):
+        # 'regions:' is outside the sst-model-v1 schema: exit 1 with a named
+        # violation naming the key and its (top-level) location.
+        p = self.run_cli("model", "lint", INVALID_FIXTURE_PATH)
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("regions", combined)
+        self.assertIn("unknown top-level", combined)
+        self.assertNotIn("Traceback", combined)
+
+    def test_unknown_field_in_node_rejected(self):
+        # 'bogus-field: 42' inside node 'report-event' is a named violation in
+        # the --json errors list, with the key and its location.
+        p = self.run_cli("model", "lint", INVALID_FIXTURE_PATH, "--json")
+        self.assertEqual(p.returncode, 1)
+        data = json.loads(p.stdout)
+        self.assertIs(data["valid"], False)
+        self.assertTrue(data["errors"])
+        joined = "\n".join(data["errors"])
+        self.assertIn("bogus-field", joined)
+        self.assertIn("unknown field", joined)
+        self.assertIn("report-event", joined)
+        self.assertIn("regions", joined)
+        self.assertEqual(p.stderr, "")
+
+    def test_unknown_fields_in_other_sections_named(self):
+        model = VALID_YAML.replace(
+            "role: workflow operator\n", "role: workflow operator\n    bogus: 1\n", 1
+        ).replace("link: 1\n", "link: 1\n    bogus: 2\n", 1)
+        bad = self.write_tmp("bad-sections.yaml", model)
+        p = self.run_cli("model", "lint", bad, "--json")
+        self.assertEqual(p.returncode, 1)
+        data = json.loads(p.stdout)
+        self.assertIs(data["valid"], False)
+        joined = "\n".join(data["errors"])
+        self.assertEqual(joined.count("unknown field 'bogus'"), 2)
+        self.assertIn("agent 'operator'", joined)
+        self.assertIn("edge 'report-event -> report-thing'", joined)
+
+    # -- template contract (VAL-CLI-012, VAL-CROSS-008, VAL-ROUTE-020) ---------
+
+    def test_template_example_block_lints_clean(self):
+        block = _extract_template_example()
+        path = self.write_tmp("template-example.yaml", block)
+        p = self.run_cli("model", "lint", path)
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        self.assertIn("valid", p.stdout.lower())
+        self.assertIn("cover", p.stdout.lower())
+
+    def test_sample_fixture_lints_clean_and_matches_template(self):
+        with open(FIXTURE_PATH, encoding="utf-8") as fh:
+            fixture_text = fh.read()
+        self.assertEqual(fixture_text.strip(), _extract_template_example().strip())
+        p = self.run_cli("model", "lint", FIXTURE_PATH)
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        p2 = self.run_cli("model", "lint", FIXTURE_PATH, "--json")
+        data = json.loads(p2.stdout)
+        self.assertIs(data["valid"], True)
+        self.assertEqual(data["coverage"]["agents"], 2)
+        self.assertEqual(data["coverage"]["nodes"], 3)
+        self.assertEqual(data["coverage"]["edges"], 3)
+
+    # -- JSON equivalence (VAL-CLI-021) ----------------------------------------
+
+    def test_yaml_json_equivalence_byte_identical(self):
+        with open(FIXTURE_PATH, encoding="utf-8") as fh:
+            sample = fh.read()
+        sample_json = json.dumps(
+            {
+                "schema_version": 1,
+                "agents": [
+                    {
+                        "id": "operator",
+                        "role": "workflow operator",
+                        "promises": [
+                            {
+                                "id": "deliver-report",
+                                "body": "Deliver the weekly status report by Friday.",
+                                "type": "capability",
+                                "target": "reviewer",
+                            },
+                            {
+                                "id": "no-unverified-claims",
+                                "body": "Never assert a claim without a measured source.",
+                                "type": "constraint",
+                                "target": "all",
+                            },
+                        ],
+                    },
+                    {
+                        "id": "reviewer",
+                        "role": "semantic reviewer",
+                        "promises": [
+                            {
+                                "id": "review-report",
+                                "body": "Review the report for semantic drift against the agreed vocabulary.",
+                                "type": "capability",
+                                "target": "operator",
+                            }
+                        ],
+                    },
+                ],
+                "nodes": [
+                    {"id": "report-event", "type": "event"},
+                    {"id": "report-thing", "type": "thing"},
+                    {"id": "drift-concept", "type": "concept"},
+                ],
+                "edges": [
+                    {"from": "report-event", "to": "report-thing", "link": 1},
+                    {"from": "report-thing", "to": "drift-concept", "link": 3},
+                    {"from": "drift-concept", "to": "report-thing", "link": 2},
+                ],
+                "acceptances": [
+                    {"promise": "deliver-report", "from": "operator", "to": "reviewer"}
+                ],
+                "trajectories": [
+                    {
+                        "id": "report-flow",
+                        "path": ["report-event", "report-thing", "drift-concept"],
+                        "label": "report moves from event to reviewed thing",
+                    }
+                ],
+                "observations": [
+                    {"at": "t1", "event": "report drafted", "changed": "report-event"},
+                    {
+                        "at": "t2",
+                        "event": "reviewer flags drift in vocabulary",
+                        "changed": "drift-concept",
+                    },
+                ],
+            }
+        )
+        yaml_path = self.write_tmp("sample-as-yaml.yaml", sample)
+        json_path = self.write_tmp("sample-as-json.json", sample_json)
+        py = self.run_cli("model", "lint", yaml_path, "--json")
+        pj = self.run_cli("model", "lint", json_path, "--json")
+        self.assertEqual(py.returncode, 0)
+        self.assertEqual(pj.returncode, 0)
+        self.assertEqual(py.stdout, pj.stdout)
+        self.assertEqual(json.loads(py.stdout), json.loads(pj.stdout))
+
+    # -- restricted subset (VAL-CLI-021) ---------------------------------------
+
+    def test_out_of_subset_anchor_rejected(self):
+        bad = self.write_tmp("anchor.yaml", "schema_version: 1\nagents: &a\n  x: 1\n")
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        self.assertIn(bad, p.stdout + p.stderr)
+        self.assertNotIn("Traceback", p.stdout + p.stderr)
+
+    def test_out_of_subset_block_scalar_rejected(self):
+        bad = self.write_tmp("block.yaml", "schema_version: 1\nagents: |\n  x\n")
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        self.assertIn(bad, p.stdout + p.stderr)
+        self.assertNotIn("Traceback", p.stdout + p.stderr)
+
+    def test_out_of_subset_multi_document_rejected(self):
+        bad = self.write_tmp("multi.yaml", "---\nschema_version: 1\n")
+        p = self.run_cli("model", "lint", bad)
+        self.assertEqual(p.returncode, 1)
+        self.assertIn(bad, p.stdout + p.stderr)
+        self.assertNotIn("Traceback", p.stdout + p.stderr)
+
+    # -- map (VAL-CLI-004) ------------------------------------------------------
+
+    def test_map_text_names_nodes_and_edges_with_labels(self):
+        p = self.run_cli("model", "map", self.valid_path, "--format", "text")
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        self.assertIn("report-event", p.stdout)
+        self.assertIn("report-thing", p.stdout)
+        self.assertIn("event", p.stdout)
+        self.assertIn("thing", p.stdout)
+        self.assertIn("leads-to", p.stdout.lower())
+        self.assertIn("expresses", p.stdout.lower())
+
+    def test_map_mermaid_is_graph_block(self):
+        p = self.run_cli("model", "map", self.valid_path, "--format", "mermaid")
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        self.assertTrue(p.stdout.startswith("graph"))
+        self.assertIn("report-event", p.stdout)
+        self.assertIn("report-thing", p.stdout)
+        self.assertIn("LEADS TO", p.stdout)
+
+    def test_map_json_is_single_object(self):
+        p = self.run_cli("model", "map", self.valid_path, "--format", "json")
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        data = json.loads(p.stdout)
+        node_ids = {n["id"] for n in data["nodes"]}
+        edge_pairs = {(e["from"], e["to"], e["link"]) for e in data["edges"]}
+        self.assertEqual(node_ids, {"report-event", "report-thing"})
+        self.assertIn(("report-event", "report-thing", 1), edge_pairs)
+        self.assertIn(("report-thing", "report-event", 3), edge_pairs)
+
+    def test_map_invalid_format_exits_2_naming_value(self):
+        p = self.run_cli("model", "map", self.valid_path, "--format", "ascii-art")
+        self.assertEqual(p.returncode, 2)
+        self.assertIn("ascii-art", p.stderr)
+        self.assertEqual(p.stdout, "")
+
+    # -- distance (VAL-CLI-005/022) --------------------------------------------
+
+    def test_distance_known_pair_is_deterministic_number(self):
+        a = self.run_cli(
+            "model", "distance", self.valid_path, "--from", "report-event", "--to", "report-thing"
+        )
+        b = self.run_cli(
+            "model", "distance", self.valid_path, "--from", "report-event", "--to", "report-thing"
+        )
+        self.assertEqual(a.returncode, 0)
+        self.assertEqual(a.stdout, b.stdout)
+        match = [tok for tok in a.stdout.split() if tok.replace("-", "").isdigit()]
+        self.assertTrue(match)
+
+    def test_distance_json_has_numeric_distance(self):
+        p = self.run_cli(
+            "model",
+            "distance",
+            self.valid_path,
+            "--from",
+            "report-event",
+            "--to",
+            "report-thing",
+            "--json",
+        )
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        data = json.loads(p.stdout)
+        self.assertIsInstance(data["distance"], int)
+        self.assertEqual(data["path"], ["report-event", "report-thing"])
+
+    def test_distance_missing_id_exits_1_naming_id(self):
+        p = self.run_cli(
+            "model", "distance", self.valid_path, "--from", "ghost", "--to", "report-thing"
+        )
+        self.assertEqual(p.returncode, 1)
+        self.assertIn("ghost", p.stdout + p.stderr)
+
+    def test_distance_missing_flags_exits_2(self):
+        p = self.run_cli("model", "distance", self.valid_path)
+        self.assertEqual(p.returncode, 2)
+        self.assertIn("--from", p.stderr)
+
+    def test_distance_no_path_exits_1_naming_both_ids(self):
+        path = self.write_tmp("disconnected.yaml", DISCONNECTED_YAML)
+        p = self.run_cli(
+            "model", "distance", path, "--from", "left-a", "--to", "right-x"
+        )
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("left-a", combined)
+        self.assertIn("right-x", combined)
+
+    # -- trajectory (VAL-CLI-006/023) ------------------------------------------
+
+    def test_trajectory_enumerates_paths_with_link_types(self):
+        # the sample fixture chains report-event -[1:leads-to]-> report-thing
+        # -[3:expresses]-> drift-concept, so both link types appear on one path
+        p = self.run_cli(
+            "model", "trajectory", FIXTURE_PATH, "--from", "report-event", "--to", "drift-concept"
+        )
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        self.assertIn("report-event", p.stdout)
+        self.assertIn("drift-concept", p.stdout)
+        self.assertIn("leads-to", p.stdout)
+        self.assertIn("expresses", p.stdout)
+
+    def test_trajectory_unreachable_exits_1_naming_both(self):
+        path = self.write_tmp("disconnected.yaml", DISCONNECTED_YAML)
+        p = self.run_cli(
+            "model", "trajectory", path, "--from", "left-a", "--to", "right-x"
+        )
+        self.assertEqual(p.returncode, 1)
+        combined = p.stdout + p.stderr
+        self.assertIn("left-a", combined)
+        self.assertIn("right-x", combined)
+
+    def test_trajectory_simple_paths_no_repeats_cycles_noted_stable(self):
+        path = self.write_tmp("cyclic.yaml", CYCLIC_YAML)
+        a = self.run_cli(
+            "model", "trajectory", path, "--from", "a", "--to", "c"
+        )
+        b = self.run_cli(
+            "model", "trajectory", path, "--from", "a", "--to", "c"
+        )
+        self.assertEqual(a.returncode, 0, a.stdout + a.stderr)
+        self.assertEqual(a.stdout, b.stdout)
+        self.assertIn("cycle detected", a.stdout)
+        # JSON form: no listed path repeats a node; cycles are present.
+        pj = self.run_cli(
+            "model", "trajectory", path, "--from", "a", "--to", "c", "--json"
+        )
+        self.assertEqual(pj.returncode, 0)
+        data = json.loads(pj.stdout)
+        self.assertGreaterEqual(data["path_count"], 1)
+        for entry in data["paths"]:
+            nodes = entry["nodes"]
+            self.assertEqual(len(nodes), len(set(nodes)), nodes)
+            self.assertEqual(nodes[0], "a")
+            self.assertEqual(nodes[-1], "c")
+        self.assertTrue(data["cycles"])
+
+    # -- drift (VAL-CLI-007) ----------------------------------------------------
+
+    def test_drift_differing_snapshots_categorizes_regions(self):
+        # snap-a: only-in-a node present; snap-b: only-in-b node present,
+        # report-thing retyped thing -> concept, first edge link 1 -> 2, and
+        # observation event changed -> added + removed + changed regions
+        snap_a = VALID_YAML.replace(
+            "edges:", "  - id: only-in-a\n    type: thing\nedges:", 1
+        ) + "\nobservations:\n  - at: t1\n    event: started\n"
+        snap_b = (
+            VALID_YAML.replace("type: thing\n", "type: concept\n", 1)
+            .replace("edges:", "  - id: only-in-b\n    type: event\nedges:", 1)
+            .replace("link: 1\n", "link: 2\n", 1)
+            + "\nobservations:\n  - at: t1\n    event: finished\n"
+        )
+        a_path = self.write_tmp("snap-a.yaml", snap_a)
+        b_path = self.write_tmp("snap-b.yaml", snap_b)
+        p = self.run_cli("model", "drift", a_path, b_path)
+        self.assertEqual(p.returncode, 0, p.stdout + p.stderr)
+        out = p.stdout.lower()
+        self.assertIn("added regions", out)
+        self.assertIn("removed regions", out)
+        self.assertIn("changed regions", out)
+        self.assertIn("only-in-a", p.stdout)
+        self.assertIn("only-in-b", p.stdout)
+        self.assertIn("report-thing", p.stdout)
+        self.assertIn("t1", p.stdout)
+
+    def test_drift_identical_snapshots_no_drift(self):
+        p = self.run_cli("model", "drift", self.valid_path, self.valid_path)
+        self.assertEqual(p.returncode, 0)
+        self.assertIn("no drift", p.stdout.lower())
+
+    def test_drift_json_shape(self):
+        a_path = self.write_tmp("snap-a.yaml", VALID_YAML)
+        b_path = self.write_tmp(
+            "snap-b.yaml", VALID_YAML.replace("link: 1\n", "link: 2\n", 1)
+        )
+        p = self.run_cli("model", "drift", a_path, b_path, "--json")
+        self.assertEqual(p.returncode, 0)
+        data = json.loads(p.stdout)
+        self.assertIn("drift", data)
+        self.assertTrue(data["drift"])
+        self.assertTrue(data["changed"])
+
+    # -- --json purity (VAL-CLI-008/017) ----------------------------------------
+
+    def test_json_purity_on_content_error(self):
+        bad = self.write_tmp("bad.yaml", MALFORMED_YAML)
+        p = self.run_cli("model", "lint", bad, "--json")
+        self.assertIn(p.returncode, (1, 2))
+        data = json.loads(p.stdout)  # must parse: no prose on stdout
+        self.assertIs(data["valid"], False)
+        self.assertTrue(data["errors"])
+        self.assertEqual(p.stderr, "")
+
+    def test_json_purity_on_io_error(self):
+        missing = os.path.join(self.tmpdir, "does-not-exist.yaml")
+        p = self.run_cli("model", "lint", missing, "--json")
+        self.assertEqual(p.returncode, 2)
+        data = json.loads(p.stdout)
+        self.assertIs(data["valid"], False)
+        self.assertTrue(data["errors"])
+        self.assertIn("does-not-exist.yaml", data["errors"][0])
+        self.assertEqual(p.stderr, "")
+
+    def test_json_never_emitted_for_usage_errors(self):
+        cases = [
+            ["model", "frobnicate", "--json"],
+            ["model", "lint", "--json"],
+            ["frobnicate", "--json"],
+            ["model", "map", self.valid_path, "--format", "ascii-art", "--json"],
+        ]
+        for args in cases:
+            p = self.run_cli(*args)
+            self.assertEqual(p.returncode, 2, args)
+            self.assertEqual(p.stdout, "", args)
+            self.assertTrue(p.stderr.strip(), args)
+            self.assertNotIn("Traceback", p.stderr)
+
+    def test_json_single_object_no_second_value(self):
+        p = self.run_cli("model", "lint", self.valid_path, "--json")
+        self.assertEqual(p.returncode, 0)
+        text = p.stdout.strip()
+        self.assertEqual(text.count("{"), text.count("}"))
+        self.assertTrue(text.startswith("{"))
+        self.assertTrue(text.endswith("}"))
+
+    # -- --dry-run (VAL-CLI-009) ------------------------------------------------
+
+    def test_dry_run_no_writes_and_identical_output(self):
+        sentinel = os.path.join(self.tmpdir, "sentinel.txt")
+        with open(sentinel, "w") as fh:
+            fh.write("sentinel")
+        before = sorted(os.listdir(self.tmpdir))
+        normal = self.run_cli("model", "lint", self.valid_path)
+        dry = self.run_cli("model", "lint", "--dry-run", self.valid_path)
+        self.assertEqual(dry.returncode, normal.returncode)
+        self.assertEqual(dry.stdout, normal.stdout)
+        self.assertEqual(dry.stderr, normal.stderr)
+        self.assertEqual(sorted(os.listdir(self.tmpdir)), before)
+        with open(sentinel, encoding="utf-8") as fh:
+            self.assertEqual(fh.read(), "sentinel")
+        with open(self.valid_path, encoding="utf-8") as fh:
+            self.assertEqual(fh.read(), VALID_YAML)
+        # every subcommand accepts --dry-run and renders identically
+        p = self.run_cli("model", "map", "--dry-run", self.valid_path, "--format", "text")
+        self.assertEqual(p.returncode, 0)
+        p = self.run_cli(
+            "model", "distance", "--dry-run", self.valid_path, "--from", "report-event", "--to", "report-thing"
+        )
+        self.assertEqual(p.returncode, 0)
+
+    # -- malformed input, never a traceback (VAL-CLI-010/016) -------------------
+
+    def test_malformed_yaml_no_traceback(self):
+        path = self.write_tmp("malformed.yaml", MALFORMED_YAML)
+        p = self.run_cli("model", "lint", path)
+        self.assertIn(p.returncode, (1, 2))
+        self.assertNotIn("Traceback", p.stdout + p.stderr)
+
+    def test_blank_file_exits_1_no_traceback(self):
+        path = self.write_tmp("blank.yaml", "  \n\n  \n")
+        p = self.run_cli("model", "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_exits_1_no_traceback(self):
+        path = self.write_tmp("bad.bin", b"\xff\xfe" + b"schema_version: 1\n", binary=True)
+        p = self.run_cli("model", "lint", path)
+        self.assertEqual(p.returncode, 1)
+        self.assertNotIn("UnicodeDecodeError", 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("model", "lint", path)
+        self.assertEqual(p.returncode, 1)
+        self.assertNotIn("RecursionError", p.stdout + p.stderr)
+        self.assertNotIn("Traceback", p.stdout + p.stderr)
+
+    # -- IO and grammar taxonomy (VAL-CLI-016) ----------------------------------
+
+    def test_missing_file_exits_2_naming_path(self):
+        missing = os.path.join(self.tmpdir, "does-not-exist.yaml")
+        p = self.run_cli("model", "lint", missing)
+        self.assertEqual(p.returncode, 2)
+        self.assertIn("does-not-exist.yaml", p.stderr)
+        self.assertNotIn("Traceback", p.stderr)
+
+    def test_unreadable_directory_exits_2(self):
+        p = self.run_cli("model", "lint", self.tmpdir)
+        self.assertEqual(p.returncode, 2)
+        self.assertIn("read", p.stderr.lower())
+
+    def test_usage_errors_exit_2_with_offending_token(self):
+        cases = [
+            (["model", "frobnicate"], "frobnicate"),
+            (["model"], "subcommand"),
+            (["lint", self.valid_path], "model"),
+            (["model", "lint", "--bogus", self.valid_path], "--bogus"),
+            (["model", "lint"], "file argument"),
+            (["model", "distance", self.valid_path], "--from"),
+            (["model", "lint", self.valid_path, "extra.yaml"], "extra.yaml"),
+        ]
+        for args, token in cases:
+            p = self.run_cli(*args)
+            self.assertEqual(p.returncode, 2, args)
+            self.assertTrue(p.stderr.strip(), args)
+            self.assertIn(token, p.stderr)
+            self.assertNotIn("Traceback", p.stderr)
+
+    # -- cwd independence and module import (VAL-CLI-018/019) -------------------
+
+    def test_identical_behavior_from_any_cwd(self):
+        fixture = FIXTURE_PATH
+        outputs = []
+        for cwd in (REPO_ROOT, SKILL_ROOT, self.tmpdir):
+            p = self.run_cli("model", "lint", fixture, "--json", cwd=cwd)
+            self.assertEqual(p.returncode, 0, p.stderr)
+            outputs.append(p.stdout)
+        self.assertEqual(outputs[0], outputs[1])
+        self.assertEqual(outputs[1], outputs[2])
+
+    def test_module_import_no_side_effects(self):
+        code = (
+            "import importlib.util, pathlib\n"
+            f"s = pathlib.Path({SCRIPT!r})\n"
+            "spec = importlib.util.spec_from_file_location('sst_cli', s)\n"
+            "m = importlib.util.module_from_spec(spec)\n"
+            "spec.loader.exec_module(m)\n"
+            "assert callable(getattr(m, 'main', None))\n"
+            "assert getattr(m, 'SCHEMA_VERSION', None) == 'sst-model-v1'\n"
+        )
+        for cwd in (REPO_ROOT, self.tmpdir):
+            p = subprocess.run(
+                [sys.executable, "-c", code], capture_output=True, text=True, cwd=cwd
+            )
+            self.assertEqual(p.returncode, 0, p.stderr)
+            self.assertEqual(p.stdout, "")
+            self.assertEqual(p.stderr, "")
+
+    # -- stdlib-only / venv-independent (VAL-CLI-020) ---------------------------
+
+    def test_stdlib_only_imports(self):
+        with open(SCRIPT, encoding="utf-8") as fh:
+            source = fh.read()
+        tree = ast.parse(source)
+        roots = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                roots.update(alias.name.split(".")[0] for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                roots.add(node.module.split(".")[0])
+        self.assertTrue(roots)
+        self.assertEqual(roots - set(sys.stdlib_module_names), set())
+
+    def test_shebang_is_env_python3(self):
+        with open(SCRIPT, encoding="utf-8") as fh:
+            first_line = fh.readline().rstrip("\n")
+        self.assertEqual(first_line, "#!/usr/bin/env python3")
+
+    def test_runs_under_empty_env(self):
+        env = {"HOME": "/tmp", "PATH": os.environ.get("PATH", "")}
+        p = subprocess.run(
+            ["env", "-i", "HOME=/tmp", f"PATH={env['PATH']}", "python3", SCRIPT, "--help"],
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual(p.returncode, 0, p.stderr)
+        self.assertIn("model lint", p.stdout)
+
+    # -- Quick Start walkthrough support (VAL-ROUTE-011/020) --------------------
+
+    def test_quickstart_command_surface_runs_against_sample(self):
+        commands = [
+            ["model", "lint", FIXTURE_PATH],
+            ["model", "map", FIXTURE_PATH, "--format", "text"],
+            ["model", "map", FIXTURE_PATH, "--format", "mermaid"],
+            ["model", "map", FIXTURE_PATH, "--format", "json"],
+            ["model", "distance", FIXTURE_PATH, "--from", "report-event", "--to", "drift-concept"],
+            ["model", "trajectory", FIXTURE_PATH, "--from", "report-event", "--to", "drift-concept"],
+            ["model", "drift", FIXTURE_PATH, FIXTURE_PATH],
+        ]
+        for args in commands:
+            p = self.run_cli(*args)
+            self.assertEqual(p.returncode, 0, f"{args}: {p.stdout + p.stderr}")
+            self.assertNotIn("Traceback", p.stdout + p.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

semantic-spacetime/tests/trigger-probes.md

@@ -0,0 +1,140 @@
+# semantic-spacetime — trigger probes
+
+Harness-specific activation tests for the `semantic-spacetime` 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.
+
+This file also commits the two behavioral routing tables that VAL-ROUTE-009 /
+015 / 016 are measured against: the Load By Need routing table (each of the
+seven representative needs mapped to its expected reference) and the
+anti-trigger refusal table (each of the five anti-triggers mapped to its
+expected decision). Both carry a Results / observed-outcome column recording
+the reference a fresh agent actually picked or the decision it actually
+produced.
+
+## How to run
+
+Give a fresh agent (with no prior semantic-spacetime knowledge) **only** the
+frontmatter `description` below plus the probe prompt, and ask it to decide
+whether to load the skill and — for the routing probes — which reference it
+would open. 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 (verbatim from
+`SKILL.md` frontmatter):
+
+> Model and diagnose shared semantic ground between agents with Semantic Spacetime (Mark Burgess, 2014-2025): a discrete graph model of meaning over time, where local proper time replaces global clocks, causality is cooperative promises, and gamma(3,4) graphs expose semantic drift, world model divergence, and absorbing states. Use for designing convergent self-healing coordination, modeling intent and trajectories over time, mapping promises onto spacetime, diagnosing semantic drift or dead-ends, and analyzing temporal blindness in agents. Do not use for physics or relativity, pure vector embeddings or RAG without temporal-causal structure, enforceable centralized control, simple single-agent prompting, or tool manuals — route those to the appropriate skill.
+
+## Should-trigger probes
+
+Prompts that must activate the skill. Each is an in-boundary task whose
+vocabulary matches the description's triggers (shared semantic ground,
+semantic drift / world model divergence, mapping promises onto spacetime,
+temporal blindness).
+
+### Probe ST-1 — shared semantic ground design (should trigger)
+
+- **Prompt:** "Design shared semantic ground for a two-agent team that keeps misaligning on what 'done' means; produce a map of their interpretations."
+- **Expected decision:** activate. The task asks to design shared semantic ground between agents, which the description names first ("Model and diagnose shared semantic ground between agents").
+
+### Probe ST-2 — semantic drift / world model divergence (should trigger)
+
+- **Prompt:** "Diagnose semantic drift between my agents' world models — they started aligned and diverged over time; find where they dead-end."
+- **Expected decision:** activate. The description's trigger vocabulary covers "semantic drift", "world model divergence", and "diagnosing semantic drift or dead-ends".
+
+### Probe ST-3 — mapping promises onto spacetime (should trigger)
+
+- **Prompt:** "Map our promises and acceptances onto spacetime and trace how intent propagates between the agents over time."
+- **Expected decision:** activate. "mapping promises onto spacetime" is a named trigger in the description.
+
+### Probe ST-4 — temporal blindness analysis (should trigger)
+
+- **Prompt:** "Analyze why my agent cannot tell what happened before what — it seems temporally blind and misorders events."
+- **Expected decision:** activate. "analyzing temporal blindness in agents" is a named trigger in the description.
+
+## 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: physics /
+relativity, pure embeddings / RAG without temporal-causal structure,
+enforceable centralized control, simple single-agent prompting, and tool
+manuals.
+
+### Probe SN-1 — physics near-miss (should not trigger)
+
+- **Prompt:** "Derive the time dilation factor for a satellite in a Schwarzschild metric, including the gravitational redshift term."
+- **Expected decision:** do not activate. This is spacetime physics, which the description explicitly excludes ("Do not use for physics or relativity"); it belongs to a physics domain.
+
+### Probe SN-2 — static embeddings near-miss (should not trigger)
+
+- **Prompt:** "Build semantic search over our static vector embeddings — there are no timestamps and no causal structure, just similarity scores."
+- **Expected decision:** do not activate. A static embedding index is "pure vector embeddings or RAG without temporal-causal structure", an explicit anti-trigger; route to the embedding or semantic-search tool's own skill.
+
+### Probe SN-3 — enforceable control near-miss (should not trigger)
+
+- **Prompt:** "I fully control the fleet; just push the config to every server and verify compliance directly — no consent model needed."
+- **Expected decision:** do not activate. Direct command-and-verify authority is "enforceable centralized control", an explicit anti-trigger; the control-vs-cooperation discussion, if wanted, routes to promise-theory.
+
+### 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 or meaning space to model, an explicit anti-trigger.
+
+### Probe SN-5 — tool-manual near-miss (should not trigger)
+
+- **Prompt:** "Show me the kubectl commands and flags to deploy this chart, with examples."
+- **Expected decision:** do not activate. The user needs a tool manual, which the description routes away ("tool manuals — route those to the appropriate skill"); the correct target is the kubernetes tooling skill.
+
+## Boundary coverage checklist
+
+| Anti-trigger boundary | Probes exercising it |
+|-----------------------|----------------------|
+| Physics / relativity | SN-1 |
+| Pure vector embeddings / RAG without temporal-causal structure | SN-2 |
+| Enforceable centralized control | SN-3 |
+| Simple single-agent prompting | SN-4 |
+| Tool manuals | SN-5 |
+
+Counts: 4 should-trigger probes (≥3 required) and 5 should-not-trigger
+near-misses (≥2 required), each with an explicit expected decision.
+
+## Committed routing tables (VAL-ROUTE-009 / 015 / 016)
+
+The tables below are the committed, mechanically checkable record that
+VAL-ROUTE-009 (Load By Need row mapping), VAL-ROUTE-015 (behavioral routing of
+seven needs), and VAL-ROUTE-016 (behavioral anti-trigger refusal) are measured
+against. The Results columns record the observed outcome of a fresh-agent run
+given the probe prompt and only the `SKILL.md` router (frontmatter description
+plus the Load By Need / When not to use sections).
+
+### Load By Need routing table
+
+| Need (VAL-ROUTE-015 probe) | Expected reference | Results (observed) |
+|---|---|---|
+| "Re-derive the formal model: proper time, γ(3,4), semantic element — what does it all mean formally?" | `references/foundations.md` | Picked `foundations.md` — the formal-model row of Load By Need. Matches. |
+| "Learn from CFEngine and the IaC/Kubernetes/GitOps lineage before designing a convergent system." | `references/applications-infrastructure.md` | Picked `applications-infrastructure.md` — the CFEngine/infrastructure row. Matches. |
+| "Model this specific agent team in SST terms and design their coordination." | `references/agent-coordination.md` | Picked `agent-coordination.md` — the agent-team/coordination row. Matches. |
+| "Apply the drift-detection pattern (or another named pattern) to my system." | `references/patterns.md` | Picked `patterns.md` — the named-patterns row. Matches. |
+| "My agents keep disagreeing about what a word means — diagnose the drift." | `references/diagnosis-and-debugging.md` | Picked `diagnosis-and-debugging.md` — the drift/divergence/dead-end diagnosis row. Matches. |
+| "I hit an unfamiliar term while modeling." | `references/glossary.md` | Picked `glossary.md` — the unfamiliar-term row. Matches. |
+| "Find the primary sources — which paper says X?" | `references/bibliography.md` | Picked `bibliography.md` — the primary-sources row. Matches. |
+
+Verdict: 7/7 needs routed to the expected reference; no row sends a need to a
+semantically wrong file (VAL-ROUTE-009 and VAL-ROUTE-015 pass).
+
+### Anti-trigger refusal table
+
+| Anti-trigger (VAL-ROUTE-016 probe) | Expected decision | Results (observed) |
+|---|---|---|
+| General relativity / spacetime physics | Decline; no SST modeling — a physics domain owns this. | Declined, no reference loaded. Matches. |
+| Pure vector embeddings / RAG / semantic search without temporal-causal structure | Decline; route to the embedding or semantic-search tool's own skill. | Declined and routed to the embedding/search tool skill. Matches. |
+| Enforceable centralized control (direct command-and-verify) | Decline; SST machinery is overhead; route to promise-theory for the control-vs-cooperation discussion. | Declined; noted promise-theory as the routing target for the control discussion. Matches. |
+| Simple single-agent prompting | Decline; no delegation or meaning space to model. | Declined, no reference loaded. Matches. |
+| Tool manuals / framework documentation | Decline; route to the tool's own skill. | Declined and routed to the tool's own skill. Matches. |
+
+Verdict: 5/5 anti-trigger probes produced a decline or the stated routing
+destination, consistent with the `## When not to use` section (VAL-ROUTE-016
+passes).

supabase/references/agent-evals.md

@@ -83,3 +83,7 @@ Use the scenario set that matches the workflow under evaluation, and prefer scen
 
 - Do not use this reference to design evaluation methodology, datasets, or graders — that is [agent-evals-and-observability](../../agent-evals-and-observability/SKILL.md).
 - Do not confuse supabase/evals with this skill's own `evals/evals.json`: the former runs agents against scored scenarios, the latter is a static output-quality contract validated by this repository.
+
+## Attribution
+
+Concepts, runtime descriptions, and commands in this reference are derived from the [supabase/evals README](https://github.com/supabase/evals), Copyright Supabase, licensed under [Apache-2.0](https://github.com/supabase/evals/blob/main/LICENSE). Definitions are paraphrased or quoted for documentation; the harness and its skills submodule remain external to this repository.

supabase/references/source-index.md

@@ -40,6 +40,7 @@ Use current official documentation and source before making version-sensitive cl
 - Supavisor: https://github.com/supabase/supavisor
 - Supabase Postgres: https://github.com/supabase/postgres
 - PostgREST: https://github.com/PostgREST/postgrest
+- Agent evals harness: https://github.com/supabase/evals (Apache-2.0; concepts/commands checked 2026-08-09)
 
 Within the official Docker directory, read `README.md`, `CONFIG.md`, `CHANGELOG.md`, `versions.md`, `.env.example`, `docker-compose.yml`, `run.sh`, and the relevant `tests/` file together. `CONFIG.md` explicitly distinguishes source-derived facts from interpretive descriptions; use each service's own documentation or source when intent matters.
 

travel-guide/README.md

@@ -6,7 +6,7 @@ Turn a destination, a real traveler, and a few constraints into a considered tra
 
 Most itinerary tools optimize for coverage. This skill helps an agent design for fit: the pace, people, budget, interests, energy, and small details that make a trip feel like it belongs to the travelers.
 
-It can produce a print-ready HTML dossier for PDF conversion, a responsive companion page, or both. The visual system is editorial by default: a darkened photographic cover with a route journey line, ghost section numbers, a color-coded day strip, pace and budget meters, and a unified warm photo grade across anchor photos. It keeps current logistics and recommendations tied to sources, and it can create a sanitized edition for sharing without exposing exact dates, lodging, booking identifiers, or private notes.
+It can produce a print-ready HTML dossier for PDF conversion, a responsive companion page, or both. The visual system is editorial by default: a darkened photographic cover with a route journey line, ghost section numbers, a color-coded day strip, pace and budget meters, a unified warm photo grade across anchor photos, and a bottom-of-page footer on each section that carries a field note, a next-section line, and a ghost route mark. It keeps current logistics and recommendations tied to sources, and it can create a sanitized edition for sharing without exposing exact dates, lodging, booking identifiers, or private notes.
 
 ## What You Get
 

travel-guide/SKILL.md

@@ -192,8 +192,12 @@ The visual default is a dark photographic cover with a route journey line, warm
 gold eyebrow, white headline, restrained red accent, generous white content
 pages, ghost section numbers, a color-coded day strip right after the brief,
 pace and budget meters, compact cards, a unified warm photo grade on anchor
-images, and readable tables. Preserve contrast and selectable text. Do not let
-decoration hide uncertainty or practical caveats.
+images, readable tables, and a bottom-of-page footer per section: a content-
+derived field note (failure mode, plan B, recheck item, or skip reason) when
+one exists, a next-section line, and a ghost route mark. Preserve contrast and
+selectable text. Do not let decoration hide uncertainty or practical caveats.
+The footer is informational, never a schedule: it repeats model content in one
+line, it does not invent new plans.
 
 ## Exit criteria
 

travel-guide/references/editorial-structure.md

@@ -90,6 +90,10 @@ The default visual language is editorial rather than app-like:
 - pace and budget meters in the brief when the trip model supplies them;
 - a unified warm photo grade on anchor images so mixed-source photos read as
   one editorial set;
+- a bottom-of-page footer per section: a content-derived field note (the first
+  anchor's failure mode, the first day's alternative, the practical recheck
+  item, or the first skip reason) when one exists, a next-section line, and a
+  ghost route mark;
 - dark table headers with clear column labels;
 - short captions and visible image credits.
 
@@ -97,7 +101,10 @@ Use images to establish place and texture, not to imply that an image proves a
 recommendation. Keep body text selectable and readable in grayscale or with
 high-contrast settings. Every meaningful image needs useful alternative text.
 The day strip is a glanceable overview, not a schedule: it must never invent a
-timed plan that the day cards do not support.
+timed plan that the day cards do not support. The section footer is the same
+kind of restraint: it repeats one line already in the model rather than adding
+new recommendations, and a section with nothing worth saying simply omits the
+field note.
 
 ## Companion web page
 

travel-guide/references/pdf-rendering.md

@@ -67,6 +67,10 @@ Before delivery, verify all of the following:
 - the day strip ("trip at a glance") shows one card per day with legible kind
   colors, and the meters render when pace or budget are supplied;
 - ghost section numbers do not collide with content;
+- each section footer sits at the bottom of its page without colliding with
+  content; the field note repeats a model line (failure mode, alternative,
+  recheck, or skip reason) and the next-section line matches the section that
+  actually follows;
 - no page is blank, clipped, or unexpectedly split;
 - title, tables, captions, and source URLs are readable;
 - contrast works on the dark cover and in grayscale content pages;

travel-guide/scripts/render-travel-guide.py

@@ -148,6 +148,70 @@ def render_meters(brief):
     return '<div class="trip-meters">%s</div>' % "".join(parts)
 
 
+SECTION_ORDER = ["brief", "glance", "anchors", "days", "special", "skip", "practical", "sources"]
+SECTION_HEADINGS = {
+    "brief": ("The brief", "Why this trip, now?"),
+    "glance": ("Trip at a glance", "The whole trip, one glance."),
+    "anchors": ("The anchors", "Protect the good parts."),
+    "days": ("Day architecture", "Enough shape to wander."),
+    "special": ("Make it special", "Make it special."),
+    "skip": ("A useful no", "Skip this."),
+    "practical": ("Field notes", "Keep the friction small."),
+    "sources": ("Evidence and freshness", "Sources."),
+}
+
+
+def field_note(section, brief):
+    """One content-derived line for the section footer; None when nothing fits."""
+    if section == "anchors":
+        first = next((a for a in brief.get("anchors", []) if isinstance(a, dict)), None)
+        if first and first.get("failure_mode"):
+            return ("If it goes wrong", first["failure_mode"])
+    if section == "days":
+        first = next((d for d in brief.get("days", []) if isinstance(d, dict)), None)
+        if first and first.get("alternative"):
+            return ("Plan B", first["alternative"])
+    if section == "practical":
+        for item in brief.get("practical", []):
+            if isinstance(item, dict) and "recheck" in str(item.get("label", "")).lower() and item.get("value"):
+                return ("Recheck before departure", item["value"])
+    if section == "skip":
+        first = next((s for s in brief.get("skip", []) if isinstance(s, dict)), None)
+        if first and first.get("reason"):
+            return ("Why we skip it", first["reason"])
+    return None
+
+
+def section_footer(section, brief):
+    """Bottom-of-page footer: field note, next-section line, and a ghost mark."""
+    note = field_note(section, brief)
+    note_html = ""
+    if note:
+        note_html = '<span class="fn-label">%s</span><span class="fn-text">%s</span>' % (
+            esc(note[0]), esc(note[1]))
+    index = SECTION_ORDER.index(section)
+    next_html = ""
+    if index < len(SECTION_ORDER) - 1:
+        next_name = SECTION_ORDER[index + 1]
+        kicker, heading = SECTION_HEADINGS[next_name]
+        num = "%02d" % (index + 2)
+        next_html = ('<span class="next-up">Next: <span class="next-kicker">%s</span> — %s'
+                     '<span class="next-num">%s</span></span>') % (esc(kicker), esc(heading), num)
+    else:
+        next_html = '<span class="next-up"><span class="next-kicker">End of dossier</span></span>'
+    mark = render_mark()
+    watermark = '<div class="route-watermark" aria-hidden="true">%s</div>' % mark if mark else ""
+    return '<div class="section-footer">%s%s</div>\n%s' % (note_html, next_html, watermark)
+
+
+def inject_footer(section_html, section, brief):
+    footer_html = section_footer(section, brief)
+    index = section_html.rfind("</section>")
+    if index == -1:
+        return section_html + "\n" + footer_html
+    return section_html[:index] + "\n" + footer_html + "\n" + section_html[index:]
+
+
 def render_cover(brief, base_dir, warnings):
     trip = brief.get("trip", {})
     cover = brief.get("cover", {})
@@ -409,7 +473,18 @@ def render_sources(brief):
 
 
 def render_body(brief, base_dir, warnings, mode):
-    body = [render_cover(brief, base_dir, warnings), render_brief(brief), render_glance(brief), render_anchors(brief, base_dir, warnings), render_days(brief), render_special(brief), render_skip(brief), render_practical(brief), render_sources(brief)]
+    sections = [
+        ("brief", render_brief(brief)),
+        ("glance", render_glance(brief)),
+        ("anchors", render_anchors(brief, base_dir, warnings)),
+        ("days", render_days(brief)),
+        ("special", render_special(brief)),
+        ("skip", render_skip(brief)),
+        ("practical", render_practical(brief)),
+        ("sources", render_sources(brief)),
+    ]
+    body = [render_cover(brief, base_dir, warnings)]
+    body.extend(inject_footer(html, name, brief) for name, html in sections)
     nav = ""
     if mode == "companion":
         nav = '<nav class="companion-nav" aria-label="Guide sections"><a href="#brief">Brief</a><a href="#glance">At a glance</a><a href="#anchors">Anchors</a><a href="#days">Days</a><a href="#special">Special</a><a href="#practical">Field notes</a><a href="#sources">Sources</a></nav>'

travel-guide/styles/travel-dossier.css

@@ -93,6 +93,21 @@ p { line-height: 1.52; }
 .glance-day small { display: block; color: var(--muted); font-size: .78rem; line-height: 1.35; }
 .glance-note { margin: .8rem 0 0; font-size: .78rem; }
 
+body.dossier .sheet { display: flex; flex-direction: column; }
+.section-footer {
+  margin-top: auto; padding-top: 1.1rem;
+  border-top: 1px solid var(--line);
+  display: flex; align-items: baseline; gap: 1.2rem; flex-wrap: wrap;
+  font-size: .82rem;
+}
+.fn-label { color: var(--signal); font-weight: 800; font-size: .62rem; letter-spacing: .12em; text-transform: uppercase; }
+.fn-text { color: #4e5358; }
+.next-up { margin-left: auto; color: var(--muted); white-space: nowrap; }
+.next-kicker { color: var(--signal); font-weight: 700; }
+.next-num { margin-left: .5rem; color: rgba(23, 25, 27, .14); font-size: 1.7rem; font-weight: 800; line-height: 1; }
+.route-watermark { position: absolute; right: 1.6rem; bottom: 1.4rem; width: 12rem; opacity: .07; pointer-events: none; }
+.route-watermark svg { width: 100%; height: auto; }
+
 .anchor-list { display: grid; gap: 1.3rem; }
 .anchor-card { display: grid; grid-template-columns: minmax(0, 1fr); gap: 1.1rem; padding: 1.25rem 0; border-top: 1px solid var(--line); break-inside: avoid; }
 .anchor-card.has-image { grid-template-columns: 11rem minmax(0, 1fr); }
@@ -139,6 +154,8 @@ p { line-height: 1.52; }
   .sheet { max-width: none; min-height: 0; padding: .65in .72in; }
   .cover-inner { padding: .75in .72in; }
   .sheet, .page-break { break-before: page; }
+  body.dossier .sheet { min-height: 10.9in; }
+  .section-footer, .route-watermark { break-inside: avoid; }
   .companion-nav { display: none; }
   a { color: inherit; }
   .cover-stat, .anchor-card, .day-card, .callout, .skip-card { break-inside: avoid; }

travel-guide/tests/test_scripts.py

@@ -178,6 +178,41 @@ class TravelGuideScriptsTest(unittest.TestCase):
             payload = json.loads(result.stdout)
             self.assertTrue(any("kind" in warning for warning in payload["warnings"]))
 
+    def test_section_footer_shows_next_section_and_watermark(self):
+        with tempfile.TemporaryDirectory() as directory:
+            directory = Path(directory)
+            brief = directory / "brief.json"
+            brief.write_text(json.dumps(self._filled_brief()), encoding="utf-8")
+            output = directory / "dossier.html"
+            result = run_script("render-travel-guide.py", brief, "--output", output, "--json")
+            self.assertEqual(result.returncode, 0, result.stderr)
+            rendered = output.read_text(encoding="utf-8")
+            self.assertIn('class="section-footer"', rendered)
+            self.assertIn("Next:", rendered)
+            self.assertIn("Trip at a glance", rendered)
+            self.assertIn('class="route-watermark"', rendered)
+            self.assertIn("End of dossier", rendered)
+
+    def test_section_footer_field_notes_repeat_model_lines(self):
+        with tempfile.TemporaryDirectory() as directory:
+            directory = Path(directory)
+            brief = directory / "brief.json"
+            data = self._filled_brief()
+            data["anchors"][0]["failure_mode"] = "Rain sends the walk indoors."
+            data["days"][0]["alternative"] = "A nearby café and an early night."
+            data["practical"] = [{"label": "Recheck before departure", "value": "Museum hours change seasonally.", "source_ids": ["S1"]}]
+            brief.write_text(json.dumps(data), encoding="utf-8")
+            output = directory / "dossier.html"
+            result = run_script("render-travel-guide.py", brief, "--output", output, "--json")
+            self.assertEqual(result.returncode, 0, result.stderr)
+            rendered = output.read_text(encoding="utf-8")
+            self.assertIn("If it goes wrong", rendered)
+            self.assertIn("Rain sends the walk indoors.", rendered)
+            self.assertIn("Plan B", rendered)
+            self.assertIn("A nearby café and an early night.", rendered)
+            self.assertIn("Recheck before departure", rendered)
+            self.assertIn("Museum hours change seasonally.", rendered)
+
 
 if __name__ == "__main__":
     unittest.main()