Skip to content

docs(safety): rewrite Safety section (0.2.3)#35

Merged
hwesterb merged 1 commit intomainfrom
docs/0.2.3-safety-rewrite
Apr 18, 2026
Merged

docs(safety): rewrite Safety section (0.2.3)#35
hwesterb merged 1 commit intomainfrom
docs/0.2.3-safety-rewrite

Conversation

@hwesterb
Copy link
Copy Markdown
Member

Summary

Docs-only release. No code or vocabulary changes. Ships:

  1. Safety section rewritten in README.md and docs/README.md.
  2. Stale SEMA_ALLOW_MINT=true instructions updated to the 0.2.2 opt-out model (SEMA_DISABLE_MINT=true, SEMA_DISABLE_PULL=true) across install.md, docs/guides/getting-started.md, and two SKILL files.

Why the Safety rewrite

The prior text read:

Sema is an experimental research project. It has not been tested in production environments. We recommend running it in a sandboxed environment.

Some patterns are marked with a caution field in their metadata to flag them as potentially risky. The absence of a caution flag does not imply safety — many patterns carry no identifier regarding their safety status. Agents connecting via MCP are informed that referencing a pattern is not authorization to perform the actions it describes.

Two category errors:

  • "Run sema in a sandboxed environment" — sema ships no executable code. The MCP server hands patterns to clients as data (handles, mechanisms, invariants, dependency graphs) and executes none of the behaviors described. Sandboxing sema itself is a non-sequitur.
  • "Referencing a pattern is not authorization" — technically correct, but framed as if any action on a pattern is deviant. Patterns are explicitly designed as references for reasoning; many are also recipes (procedures, protocols) an agent may legitimately be instructed to carry out. The framing should distinguish:
    • Intended use: reasoning and reference — tested, documented in the design manual.
    • Executing a pattern as a recipe — untested research territory; the mechanism text hasn't been validated end-to-end, so sandbox the agent's execution step, not sema itself. Authorization for that execution comes from the user / workflow context, not from the fact that a pattern was resolved.

The new block in README.md + docs/README.md makes that split explicit.

Test plan

  • pytest green (no code changes, but sync-release-metadata hook re-verifies)
  • sync-release-metadata --check passes (plugin.json + server.json auto-bumped to 0.2.3)
  • changelog-gate passes
  • After merge: scripts/release.sh cuts 0.2.3 → PyPI + MCP Registry

🤖 Generated with Claude Code

… (0.2.3)

The prior Safety text recommended "run sema in a sandboxed environment"
and framed referencing a pattern as risky. That was a category error on
both fronts:

- sema ships no executable code — the MCP server hands patterns to
  clients as data (handles, mechanisms, invariants, dependency graphs)
  and executes none of the behaviors described.
- Patterns are references agents use to reason and coordinate. Acting
  on a pattern as a recipe is a separate, user-authorized activity;
  the act of resolving a pattern doesn't authorize anything.

The intended warning was narrower — "if an agent chooses to execute
the procedure a pattern describes, that execution path is untested
and should be sandboxed." The new Safety block makes that split
explicit in both README.md and docs/README.md.

Also folded in:
- Updated stale SEMA_ALLOW_MINT=true mentions in install.md,
  docs/guides/getting-started.md, skills/sema-mint/SKILL.md, and
  skills/sema-seed/SKILL.md to the 0.2.2 opt-out model.
- Dropped the top-of-README "run in sandbox" banner; the Safety
  section below it now carries the accurate scoped version.

CHANGELOG has the why in case it's useful to future readers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@hwesterb hwesterb merged commit ed2a849 into main Apr 18, 2026
5 checks passed
@hwesterb hwesterb deleted the docs/0.2.3-safety-rewrite branch April 18, 2026 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant