Migration v3 — OMNISKILL Documentation

🔄 What Changed

OMNISKILL v3.0.0 adds Layer 6: Runtime Contracts — a new layer that wraps the entire runtime with enforced session lifecycle, policy-gated tool execution, versioned telemetry, replay determinism, and MCP trust routing.

✓

Fully Backward Compatible

All existing v2 skills, agents, bundles, pipelines, schemas, hooks, and synapses continue to work without modification. v3 is purely additive.

⚠️ Breaking Changes

None. All existing content is forward-compatible:

Existing SKILL.md + manifest.yaml files work unchanged
Existing AGENT.md + agent-manifest.yaml files work unchanged
Pipeline YAML definitions consumed by the engine as-is
All 9 v2 schemas preserved alongside 6 new v3 schemas
v2 core modules untouched
All 282 v2 tests continue to pass

🚀 New Capabilities

Feature	Module	Description
Session Lifecycle	`session_manager.py`	8-state machine with strict transitions, correlation IDs, persistence
Central Policy Engine	`policy_engine.py`	Default-deny tool gating with trust tiers, schema validation, audit log
Telemetry & Replay	`telemetry.py`	Versioned envelopes (3.0.0), replay snapshots, structure-only checksums
MCP Trust Routing	`agent_mcp.py`	Capability-based routing with health policies and trust tier precedence
Schema Validation	`schema_validator.py`	Schema lint, contradiction detection, v2/v3 compatibility checking
Migration Runner	`migration.py`	Dry-run analysis, release gate scorecard, 6 hard gates

📋 New Schemas (6)

Schema	Purpose
`session.schema.yaml`	Session lifecycle states and transitions
`tool-invocation.schema.yaml`	Tool call with required policy decision
`permission.schema.yaml`	Permission rules with trust tiers
`hook-event.schema.yaml`	Normalized hook bus events
`telemetry-envelope.schema.yaml`	Versioned telemetry format
`context-handoff.schema.yaml`	Phase handoff with pinned constraints and evidence

🔁 Session Lifecycle

The SessionManager enforces an 8-state lifecycle with strict transition rules:

created → active → waiting_tool → active
                 → waiting_permission → active
                 → idle → active
                 → error → recovering → active
                 → archived (terminal)

Invalid transitions raise InvalidTransitionError. Every event is logged with a correlation ID that links sessions to pipeline traces.

🛡️ Policy Engine

The PolicyEngine gates every tool invocation through 4 checks:

Schema Validation

Tool arguments checked against registered schemas.
Permission Rules

Evaluated in order; first match wins.
Trust Tier Precedence

builtin > verified > community > untrusted
Decision Artifact

Machine-readable PolicyDecision with rationale.

Default action is deny — tools must have an explicit allow rule.

💻 Using v3 SDK

Python

from src.omniskill.core.session_manager import Session
from src.omniskill.core.policy_engine import PolicyEngine, PermissionRule
from src.omniskill.core.telemetry import TelemetryCollector, ReplayHarness

# Session lifecycle
session = Session.create("my-pipeline", {"input": "Build auth"})
session.activate()
session.wait_for_tool("file_write")
session.resume()

# Policy engine
engine = PolicyEngine()
engine.add_rule(PermissionRule(
    id="r1", scope="file_*",
    trust_tier="verified", action="allow"
))
decision = engine.evaluate(
    "file_write", {"path": "/src/main.py"},
    trust_tier="verified"
)

# Telemetry
collector = TelemetryCollector()
collector.emit_from_session_event(session, "session_start")
collector.emit_from_policy_decision(decision)

# Replay determinism
harness = ReplayHarness(collector)
baseline = harness.capture(session)
current = harness.capture(session)
result = harness.compare(baseline, current)
assert result["deterministic"] is True

✅ Release Gates

The ReleaseGateValidator validates 6 hard gates:

Gate	What It Checks
SchemaAndContracts	All v3 schemas present and version 3.x
PolicyAndSecurity	Policy engine and permission schema present
ReplayDeterminism	Telemetry module and replay tests present
ContextIntegrity	Handoff schema enforces pinned_constraints and evidence_links
PromptQuality	Prompt files present, schema validator functional
MigrationReadiness	Migration dry-run passes with zero blockers

All 6 must pass and the weighted score must reach 90+ for a GO recommendation.

⚡ Upgrade Steps

Pull the latest version

git pull or update your copy to v3.0.0
No migration required

Existing v2 content works as-is — zero breaking changes.
Run tests
```
$ python -m pytest tests/
```
All 500 tests should pass (282 v2 + 218 v3).
Optional: Use v3 features

Adopt SessionManager, PolicyEngine, and TelemetryCollector for runtime contracts.

✓

That's it!

All 282 v2 tests + 218 v3 tests = 500/500 PASS. Your existing OMNISKILL content is fully compatible with v3.0.0.

Migration Guide: v2 → v3