magnus919_agent-skills/semantic-spacetime/README.md

# 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.